The Mau command line

The Mau command line help

At any time, you can see all command line options running mau -h or mau --help.

usage: mau -i INPUT_FILE
           [-h] [-c CONFIG_FILE] [-o OUTPUT_FILE]
           [--verbose] [--debug]
           [-e ENVIRONMENT_FILE] [--environment-files-namespace ENVIRONMENT_FILES_NAMESPACE]
           [-v ENVIRONMENT_VARIABLE] [--environment-variables-namespace ENVIRONMENT_VARIABLES_NAMESPACE]
           [-t {mau_html_visitor:HtmlVisitor,core:YamlVisitor,core:JinjaVisitor}]
           [--lexer-print-output] [--lexer-only]
           [--version]

options:
  -h, --help            show this help message and exit
  -c CONFIG_FILE, --config-file CONFIG_FILE
                        Optional YAML config file (default: None)
  -i INPUT_FILE, --input-file INPUT_FILE
                        Input file (default: None)
  -o OUTPUT_FILE, --output-file OUTPUT_FILE
                        Optional output file ('-' for standard output) (default: None)
  --verbose             set loglevel to INFO (default: None)
  --debug               set loglevel to DEBUG (default: None)
  -e ENVIRONMENT_FILE, --environment-file ENVIRONMENT_FILE
                        Optional text/YAML file in the form key=path (can be specified multiple times). The key can be dotted to add namespaces. (default: None)
  --environment-files-namespace ENVIRONMENT_FILES_NAMESPACE
                        Optional namespace for environment files (default: envfiles)
  -v ENVIRONMENT_VARIABLE, --environment-variable ENVIRONMENT_VARIABLE
                        Optional environment variable in the form key=value (can be specified multiple times). The key can be dotted to add namespaces. (default: None)
  --environment-variables-namespace ENVIRONMENT_VARIABLES_NAMESPACE
                        Optional namespace for environment variables (default: envvars)
  -t {mau_html_visitor:HtmlVisitor,core:YamlVisitor,core:JinjaVisitor}, --visitor {mau_html_visitor:HtmlVisitor,core:YamlVisitor,core:JinjaVisitor}
                        Output format (default: None)
  --lexer-print-output  print the output of the lexer (default: False)
  --lexer-only          stop after lexing (default: False)
  --version             show program's version number and exit

The only mandatory value on the command line is the input file, that you specify with -i INPUT_FILE.

Output file

If you don't specify any value for it, the output file name will be that of the input file with the extension .mau replaced by a suitable extension that depends on the current visitor. For example, the HTML visitor would parse /path/to/myinput.mau and create /path/to/myinput.html.

Configuration file

The default Mau configuration is an empty dictionary. If you want to pass configuration values you need to create a YAML file and pass it to Mau using -c CONFIG_FILE. The whole file will be loaded into the Mau environment under the default namespace mau and be available as variables. For example, the following configuration file

answer: 42
namespace:
  value: 123

would result in the variables mau.answer and mau.namespace.value to be available in Mau.

The answer is: {mau.answer}

The value is: {mau.namespace.value}

Environment vars

Mau allows you to define variables on the command line through the option -v KEY=VALUE. The variable is loaded into the environment using the base namespace mau and an additional namespace defined by the option --environment-variables-namespace, which defaults to envvars.

# This defines {mau.envvars.answer}
mau -i input.mau -v answer=42

# This defines {mau.custom.answer}
mau -i input.mau -v answer=42 --environment-variables-namespace custom

Environment files

Mau can import entire environment files, that is YAML files that are loaded as Python dictionaries and injected into the environment.

An environment file is added with the syntax -e KEY=PATH, and all the values are loaded using the base namespace mau.ENVFILESNS.KEY, where ENVFILESNS is the namespace defined by --environment-files-namespace, which defaults to envfiles.

Given the file

answer: 42
target:
  life: "true"
  universe: "true"
  everything: "true"

the command line

mau -i input.mau -e custom=/path/to/env.yaml

will load the following environment

{
    "mau": {
        ...
        "envfiles": {
            "custom": {
                "answer": 42,
                "target": {
                    "life": "true",
                    "universe": "true",
                    "everything": "true",
                },
            }
        },
    }
}

while the command line

mau -i input.mau -e custom=/path/to/env.yaml --environment-files-namespace myvars

will load the following environment

{
    "mau": {
        ...
        "myvars": {
            "custom": {
                "answer": 42,
                "target": {
                    "life": "true",
                    "universe": "true",
                    "everything": "true",
                },
            }
        },
    }
}

The environment file can also be specified without a key with -e PATH. In this case, the key will be the name of the file without extension.

For example, the command line

mau -i input.mau -e /path/to/env.yaml

will load the following environment

{
    "mau": {
        ...
        "envfiles": {
            "env": {
                "answer": 42,
                "target": {
                    "life": "true",
                    "universe": "true",
                    "everything": "true",
                },
            }
        },
    }
}

Variables and namespaces

All variables that are not defined inside the document will be stored under the namespace mau. This is true for the whole config file and for other types of variables defined on the command line.

In general, variables defined in the config file should be considered fully typed values, as YAML types like strings, integers, booleans, lists translate perfectly into Python types. Such variables are used internally to control Mau's behaviour.

Environment variables and files, however, should be considered as pure strings only, as they will be used in Mau documents.

The system will try a trivial conversion between YAML types and Python strings, which will work in simple cases like the numbers used above. YAML booleans, for example, do not translate well, as they are read as Python booleans and transformed into the strings "True" and "False" which won't pass a test like == true in Mau.

When you use YAML, you should always stick to explicit strings, unless you are sure that the conversion will be harmless.

Verbose and debug output

The options --verbose and --debug increment the output level of the logger, increasing the amount of information you can see on the command line.

The debug level will be useful when developing templates, as it will provide data about the selected document nodes.

Visitor

You can specify the visitor you want to use with the option -t VISITOR_NAME. Visitors are named MODULE:CLASS where MODULE is the plugin that defines them and CLASS is the name of the class that implements the visitor you want.

The Mau core package provides two visitors, core:YamlVisitor and core:JinjaVisitor, while a plugin like the Mau HTML visitor provides mau_html_visitor:HtmlVisitor.

The selected visitor will provide the default extension for the output, should you leave Mau decide the output file.

Lexer debug

Should you need to see the output of the lexer, you can use the option --lexer-print-output, and you can stop after the lexing step with --lexer-only.