hmacro 2.2.2

A simple macro preprocessor
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

# hmacro

A kinda-terrible macro expander originally written in Haskell, but later
rewritten in Rust.

## Build

You can build this with Cargo, just run `cargo build`.

You can also install it with `cargo install`.

## Invoking from the command line
~~~
Usage:

hmacro [OPTIONS] <filename>

`-v', `--version' - Print a version message, then exit
`-h', `--help'    - Print a help message, then exit
`--license'       - Display information about hmacro's license
`-Dmacro=exp'     - Predefines a new macro, named `macro', that expands
                    to `exp'.

You can pass a list of filenames to hmacro.
They will each be expanded separately and the results concatenated.
~~~

## Example CLI invocations

~~~
hmacro foo.hm
~~~

Expands `foo.hm`, then prints the result to stdout.

## Source file format

`hmacro` works similarly to `m4` or the C preprocessor. 
It takes some text containing macros and definitions of those macros, and then expands those macros as desired and outputs the result.

Macros generally follow the vaguely-EBNF-style format below. Anything enclosed in `/` characters is a regular expression.

~~~
text ::= { textelem }
textelem ::= macro | scope | /[^\\]/ | "\\" | "\{" | "\}"
macro ::= '\' name { scope } | def | include
name ::= /[a-zA-Z\-_][a-zA-Z0-9\-_]*/
scope ::= '{' text '}'
~~~

Practically, `hmacro` source consists of macros and scopes. 
Any macros defined inside a scope are no longer valid once outside of that scope, however, any scopes defined inside a scope inherit macros defined in scopes above that scope. 
Scopes are delineated with curly braces, `{}`.
Curly braces can be escaped with `\{` and `\}`.

A macro looks something like `\name`, where name is a name that must start with an alphabetic character, `-`, or `_`, and must consist only of alphanumeric characters, as well as `-` or `_`. 
The `\` character can be escaped with `\\`.
If a macro is immediately followed by one or more scopes, those scopes are considered arguments to that macro and are available to it when it expands.


Some macros are predefined as follows:

- `\def{name}{expansion}`
Defines a new macro called `name` that expands to `expansion`.
`expansion` consists of text interspersed with macro arguments.
A macro argument is of form `$num`, where `num` is the number of
the argument.
`$1` is the first argument, `$2` is the second, and so on.
If a `$` character is followed by a numeric character, and you do not want
either to be treated as specifying an argument, escape the `$` with `\$123`.
- `\include{filename}`
Expands to the text of `filename`.
The file itself will be processed for hmacro scopes and macros.
Any macros that are not within a scope will be defined.
Recursive includes are not allowed.
- `\incldefs{filename}`
Expands to nothing, but any macros in the file `filename` that are outside of
a scope will be defined after this macro is called.
- `\cat{arg1}{arg2}...{argn}`
Concatenates all arguments provided without expanding any of them.