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
thenEnter
- To disable the multi-line input, type
ml off
- To switch the multi-line input, type
ml
orml on
orml 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 helpexit
: 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' ]