Arguments

How to define arguments

In Mau, arguments are used to provide parameter values to a node. Just like labels, arguments are a document node that is not rendered on its own, but attached to next rendered node.

Arguments are specified using the syntax [ARGUMENTS], where ARGUMENTS is a comma-separated list of values or key/value pairs.

[arg1, arg2]

The arguments above will be attached to this paragraph.

How to use arguments

As it happens for labels, arguments are stored inside a node an are available for the visitor to be inserted in the rendered text. The way they are used, however, depends entirely on the template. While the template engine is a topic for a later chapter, it is worth showing here that labels can be rendered. The following example uses a custom template for a paragraph that attaches all arguments as a list under it.

[arg1, arg2]
This paragraph shows the arguments attached to it thanks to a custom template.

Argument rules

The definition of arguments follow the same syntax used for macro arguments. In particular, the following rules are in place:

• Arguments are separated by commas.
• Spaces are irrelevant.
• Arguments can be quoted and must be if they contain ambiguous characters like commas and brackets.

The following declarations are all equally valid.

[arg1,arg2]
[arg1, arg2]
["arg1", arg2]
["arg1",  "arg2"]

Named and unnamed arguments

Arguments can be either named or unnamed. Named arguments come in the form KEY=VALUE while unnamed ones are just a VALUE.

All unnamed arguments must be specified before named arguments.

Mau allows you to pass any number of values and to define keys on the fly. Specific node types (introduced in later chapters) will support or require certain unnamed or named arguments to be added to them, but you are still free to add custom ones.

[unnamed1, unnamed2, name1=value1, name2=value2]
This paragraph shows the arguments attached to it thanks to a custom template.

Tags

Unnamed arguments that start with a # are stored as tags and kept separate from the normal unnamed arguments.

[arg1, arg2, #tag1]
This paragraph shows the arguments attached to it thanks to a custom template.

Tags and other arguments

Tags are unnamed arguments, so they must appear before named ones, but can be freely mixed with other unnamed arguments.

[arg1, #tag1, arg2, #tag2, key1=value1]
This paragraph shows the arguments attached to it thanks to a custom template.

Subtypes

Unnamed arguments that start with a * are considered subtypes. Subtypes, just like tags, are extremely useful to customise the rendering of a node, and will be used in a later chapter.

For each set of arguments, there can be only one subtype.

[arg1, arg2, *some-subtype]
This paragraph shows the arguments attached to it thanks to a custom template.

Subtypes and other arguments

Subtypes are unnamed arguments, so they must appear before named ones, but can be freely mixed with other unnamed arguments.

[arg1, *some-subtype, arg2, key1=value1]
This paragraph shows the arguments attached to it thanks to a custom template.

Aliases

Unnamed arguments that start with a @ are considered aliases. Aliases are different from tags and subtypes. They are not stored inside the node, but expanded into a set of named arguments and subtype that are added to the arguments being processed.

For each set of arguments, there can be only one alias.

In the next examples, the alias @demo has been defined as *demosubtype, demokey=demovalue.

[arg1, arg2, @demo]
This paragraph shows the arguments attached to it thanks to a custom template.

Aliases and other arguments

Aliases are unnamed arguments, so they must appear before named ones, but can be freely mixed with other unnamed arguments.

[arg1, @demo, arg2, key1=value1]
This paragraph shows the arguments attached to it thanks to a custom template.

Multiple argument definitions

Just like labels, arguments are collected in a buffer and assigned to the next rendered node. Multiple adjacent argument definitions will result in the last one overwriting all the others.

[arg1, arg2]
[arg3, #tag1, arg4]
This paragraph shows the arguments attached to it thanks to a custom template.