Skip to content

First Steps

Start the command line

Once M42PL is installed (see the installation instructions), you may run it in REPL (interactive) mode:

If installed locally:

m42pl repl

If installed locally in a virtual environement:

source m42pl/bin/activate
m42pl repl

If installed using Docker:

docker run -it jpclipffel/m42pl repl

Command line usage

Multiline input

The M42PL REPL runs in multi-line input mode by default, which means than pressing Enter will literally add a new line.

  • To execute commands in multiline, press Esc then Enter
  • To disable the multi-line input, type ml off
  • To switch the multi-line input, type ml or ml on or ml off

The M42PL language is extremelly simple:

  • A program / script is a list of commands
  • A command starts with the pipe | character
  • A command may takes argument(s) (also known as fields)

This is an Hello World example:

| make | eval hello='world'

At any point, you may run a builtin:

  • help: Display a quick REPL help
  • exit: Quit the REPL

You can get a list of available commands by running the commands command:

| commands

Lets keep only the fields we're interested in, namely command.alias and command.about:

| commands
| fields command.alias, command.about

You may notice that some duplicates command.about appears; this is because many commands have aliases, i.e. multiple names.

To regroup the command which have the same description, you may use stats:

| commands
| fields command.alias, command.about
| stats values(command.alias) as aliases by command.about

Finally, to generate a nice single-line description of each command, it aliases and its description:

| commands
| fields command.alias, command.about
| stats values(command.alias) as aliases by command.about
| eval man = join(aliases, ', ') + ': ' + command.about
| fields man

Events

M42PL works with events. An event is a single unit of information, which contains one or more fields.

You can think of an event as a JSON or YAML document, as a Python's dict (which they are), as a C/C++ structure, etc.

Events are generated by Generating commands and processed by Streaming commands & Buffering commands.

Commands

M42PL support 4 types of commands:

  • Generating commands generates events
    • There is a single generating command per pipeline
    • Generating command are usually put first in the pipeline
    • A pipeline may include sub-pipelines, each of them may include a genrating command
    • Generating commands may be piped into streaming commands, buffering commands and meta commands
  • Streaming commands process events
    • Each streaming command may be piped into another streaming command, buffering command or meta command
  • Buffering commands process block of events
    • Each buffering command may be piped into another buffering command, streaming command or meta command
  • Meta commands forwards the data and manipulates the pipeline itself
    • Each metacommand may be piped into another meta command, streaming command or buffering command

Fields

Fields are both the events attributes and a way to access the given attributes.

M42PL's commands support 5 type of fields:

  • Literal: A literal value such as a number, a string or a list of values, e.g. 42, 'some text', (1, 2, 3)
  • Path: A field name or a doted field name, e.g. field, field.subfield
  • JsonPath: A JsonPath expression, e.g. {list[0].name}
  • Eval: An evaulation expression, e.g. at(list, 0)
  • Pipe: A sub-pipeline, e.g. [ | kvread 'someName' ]