# TOC
* [Macro definition](#macro-definition)
* [Caveats](#caveats)
* [Macro invocation](#macro-invocation)
* [Literal rules](#literal-rules)
* [Comments](#comments)
* [Macro attributes](#macro-attributes)
* [Errors](#errors)
* [Break point](#break-point)
## Macro definition
Definition syntax is similar to macro invocation but requires a specific form
to sucessfully register the macro.
```
$define(name,arg1 arg2=$arg1() $arg2())
| | |
Arg: 1st 2nd 3rd
```
**First argument** (Before first comma)
First argument is a macro name. Macro should start with an alphabet character
and following characters should be either alphanumeric or underscore.
**Second argument** (Before equal sign)
Second argument is macro's arguments. Macro argument also follows same rule
of naming. Multiple arguments can be declared and should be **separated by
whitespaces.**
**Third argument** (After equal sign)
Third argument is a macro body. Any text can be included in the macro body
while an unbalanced parenthesis will prematurely. Currently there is no way to
include unbalanced parenthesis inside definition body.
You can also simply bind the value without giving arguments. Which is mostly
similar to static macro. But defined body is always evaluated.
```
$define(v_name=Simon creek)
% Which is same with
$static(v_name,Simon creek)
```
### Caveats
**Define is not evaluated on declaration**
Definition's body can include any macro invocation in itself, but wrong macro
use inside definition cannot be detected at the time of definition. By other
terms, defined macro is evaluated lazily.
```
$define(panik,kalm=$calm())
$panik()
$define(calm=KALM)
$panik()
===
error: Failed to invoke a macro : "calm"
--> stdin:2:2
$calm()
KALM
% After calm is defined, it prints out without error
```
You can check some easy mistakes with ```dryrun``` flag. Dryrun flag audits
simple errors on macro declaration.
```
% Ran with rad --dryrun
$define(panik,kalm=$calm())
$define(bonk=$fout(path.txt))
===
warning: Invalid macro name
= No such macro name : "calm"
--> [INPUT = test]:1:2 >> (MACRO = panik):1:2
warning: Invalid macro name
= No such macro name : "fout"
--> [INPUT = test]:1:2 >> (MACRO = bonk):1:2
warning: found 2 warnings
```
**Define is evaluated on every call**
Because defined macro is evaluated on every invocation. This may not be a
desired behaviour. Use static macro if you want statically bound value. Static
macro eagerly evaluates arguments and assigns the processed value to a macro.
```
$define(counter=0)
$define(print_counter=$counter())
$static(print_counter_as_static,$counter())
$append(counter,0000)
$print_counter()
$print_counter_as_static()
===
00000
0
```
Also, static macro is not evaluated on invocation thus a "static". Most of time
it doesn't matter. But theoretically static macro is faster than defined
macro.
## Macro invocation
Prefix is a dollar sign($)
```
$define(macro_name,a1 a2=$a1() $a2())
$macro_name(arg1, arg2)
```
Macro can be invoked anywhere after the definition.
```
My name is $macro_name(Simon, Creek).
```
converts to
```
My name is Simon Creek.
```
Special macro ```$:()``` is used for iterated value.
```
$foreach^(Name : $:()$nl(),John,Simon,Jane)
$forloop^($:()th$nl(),5,10)
```
converts to
```
Name : John
Name : Simon
Name : Jane
5th
6th
7th
8th
9th
10th
```
**NOTE**
An unbalanced parenthesis changes the behaviour of macro invocation and a
non-escaped comma will change the number or content of arguments. If desirable
content includes unbalanced parentheses or commas, enclose the body with string
literal with the syntax of ```\* TEXT GOES HERE *\```.
## Literal quotes
### Abstract
Texts within literal quote ```\* *\``` will not be expanded or treated as a
macro syntax. Literal quote makes code fuzzy, sadly, but it is frequently used
to give an array as a single chunk of argument. Literal quote was made to evade
confusions as much as possible so the syntax has exotic expression on intent. (
Unlike regular expressions like simple quotes or double quotes )
**Simple usage of literal quote**
```
% Although in this case, prefer arguments order of "value" and then "array" so
% that parser can greedily aggregates surplus commas as second arguments
$define(get_array_n_value,a_arr a_src=$foreach($:() $a_src()$nl(),$a_arr()))
$get_array_n_value^(\*1,2,3*\,-)
===
1 -
2 -
3 -
```
What would happen if array was given without literal quote?
```
$define(get_array_n_value,a_arr a_src=
$logm(a_arr)
$logm(a_src)
$foreach($:() $a_src()$nl(),$a_arr()))
$get_array_n_value^(1,2,3,-)
===
% Console output
% log: 1
% --> test:6:2
% log: 2,3,-
% --> test:8:2
1 2,3,-
```
The result text is not what one would expect. Because parser thought first
argument "1" was for ```a_arr``` and remainder for ```a_src```.
### Literal expansion rules
Literal rules in r4d is unfortunately not straightforward at a first glance.
General rules are followings
- Literal text inside definition body is not stripped on execution
- Literal text as an argument is expanded and then stripped
- Arguments with only constants is treated as if it were not quoted
- Arguments with macro will not expand macro and return it as if it were
normal text
In short, rad processes macros in given subprocesses.
- Expand expression from arguments
- Strip expanded arguments
- Split arguments according to macro's arguments
- Bind arguments to local macros
- Expand a macro body
See an examples to better understand literal rules
### Macro body
```r4d
$define(test=\*$path(a,b)*\)
$test()
===
% Macro body is not stripped
\*$path(a,b)*\
```
### Literl inside arguments
**Literal arguments without macros**
```r4d
$static(p1,$path(\*a*\,b,c))
$static(p2,$path(a,b,c))
$assert($p1(),$p2())
===
% This holds true because \*a*\ is stripped to be a value of "a"
% Thus path macro can process argument as if it was originally a "a,b,c"
```
**Literal arguments with macros**
```
$static(p,a/b)
$static(p1,$path(\*$p()*\,b,c))
$static(p2,$path($p(),b,c))
$logm(p1)
$logm(p2)
$assert($p1(),$p2())
===
% p1's argument was stripped but not expanded
% log: $p()/b/c
% --> test:4:2
%
% log: a/b/b/c
% --> test:5:2
% This holds anyway because assert has expanded each values
% Thus final result of p1 and p2 is same to end user
```
**Literal passed as nested arguments**
```
$define(demo,a_first=$if($a_first(),TRUE))
$demo($not(false))
$demo(\*$not(false)*\)
===
TRUE
error: Invalid argument
= If requires either true/false or zero/nonzero integer but given "$not(false)"
--> test:3:2~~
```
If an argument is passed as literal, local argument will be linked to stripped
but non-expanded value. which is ```$not(false)``` in this case. Since **local
argument is not expanded**, if receives strange value and execution fails.
To prevent this error, minimize literal usage if possible. When passing array,
use literal quote only when the values are constants. If you need to create a
dynamically created array, wrap it inside a macro and use literal attribute.
```r4d
$define=(
arr_pass,
a_arr a_it
=
$foreach=(
$:() + $a_it()$nl(),
$a_arr()
)
)
$static(array,a,b,c,d,e,f,g)
$arr_pass^($array*(),@)
% This is same with
% $arr_pass^(\*a,b,c,d,e,f,g*\,@)
===
a + @
b + @
c + @
d + @
e + @
f + @
g + @
```
Simple process how this works
- **arr_pass**
- Expand $array() -> ```a,b,c,d,e,f,g```
- Try stripping, but nothing to do anyway
- Wrap it inside literal (attirbute) -> ```\* a,b,c,d,e,f,g *\```
- Bind the wrapped value to an argument ```a_arr```
- **foreach**
- Expand $a_arr() -> ```\* a,b,c,d,e,f,g *\```
- Strip a value -> ```a,b,c,d,e,f,g```
- Bind the value to an argument ```a_body``` ( Refer --man foreach )
## Comments
Comment is disabled by default because a comment character can intefere with
macro expansion and user expectance. You can enable comment mode with
```--comment``` flag.
There are three types of comment mode. Those are none,start and any. None is
the default and ```--comment``` is same with ```--comment start```.
And finally ```--comment any``` enables comments for any positions.
Default comment character is ```%```. If you have used LaTex before, it would
be familar. This can be configured with builder method.
```
% This is a valid comment on both start and any mode
% Nested comment is better for reading in some cases
Prior content goes here % This is only valid comment on "any" mode.
```
### Macro attributes
**Trim output**
Trim output attribute ```^``` trims preceding and following newlines,
whitespaces from output.
```
$define(
test
=
Hello
World
)
$test()
$test^()
===
Hello
World
Hello
World
```
One important feature of trim output attribute is that it **converts empty
string into None**. You can refer why such feature is special in a
[doc](./newline_rules.md)
Therefore following example works
```
$define(none_if_empty=$ifdefel(test,DEFINED,$empty()))
$none_if_empty^() % => "None"
$define(test=)
$none_if_empty() % => DEFINED
===
DEFINED
```
**Trim input**
Trim input attribute ```=``` trims macro arguments by lines and also trim by
chunk. This is useful when you want to use a multiline complex text as
arguments but surplus blank spaces are unnecessary. Trim inputs power is mostly
centered on single argument macros but other situations are also plausible.
Trim input can be applied to define macro and trimming will be applied to macro
body.
```
% Needs trim output to remove newline that comes before "hello world"
$ifenv^=(HOME,
hello world
How are you?
I'm fine, thanks. How's it going?
yatti yatta
)
===
hello world
How are you?
I'm fine, thanks. How's it going?
yatti yatta
```
Since "trim input" trims input not arguments, trimmed input can be different
from expectation.
e.g)
```
$macro_name=(
first,
second
)
===
% Arguments are passed as
% first
%
% second
```
**Pipe output**
Pipe output attribute ```|``` saves macro output into a temporary container.
This is useful when you use hygiene mode and needs a persistent container that
is not volatile. Or simply you are just tired of defining container everytime
you want to use. ( Though I recommend using named macro container for code
readability )
```
$define(test,a=$a())
))
$test|(\*I'll be requoted with literal*\)
$-*()
===
I'm going to be used by a pipe macro
I'm going to be used by a pipe macro
\*I'll be requoted with literal*\
```
CAVEAT
Getting value from pipe truncates an original value.
```
$result()
% This time result will print nothing
$result()
===
true
```
**Pipe input**
Pipe input attribute sets argument as piped value. This also truncates pipe
value. Piped input is not expanded.
```
$define(mac,a_src=+$a_src())
$mac|-()
$mac-()
===
+++1
```
**Yield literal**
Yield literal attribute ```*``` makes output printed as literal form. This is
useful when you have to give an argument literal value but you need to pre
process the data which means it cannot be marked as literal. In other words you
can send dynamic content as quoted with help of yield literal attribute. Use
yield literal when you manipulate complex texts that can possibly include
unbalanced parenthesis or commas.
Refer about [literal quotes](#literal-rules) to grasp possible usages.
**Negate result**
You can negate a result with ```!``` attribute. On strict mode, if the result
is not a boolean-able, processor panicks.
```
$is_empty($empty())
$is_empty!($empty())
===
true
false
```
### Errors
Every error is panicking by default(strict mode), to make programs more stable
and expectable or because I'm too rusty person. You can disable strict mode
with lenient option ```-l or --lenient``` or puge option ```-p or --purge```.
Refer [modes](./modes.md) document for detailed error behaviours
### Break point
```BR``` is reserved for debugging usage. You cannot override breakpoint.
```
$BR()
```
### Escape blanks
```EB``` is reserved for blank escape opeartion. After ```EB``` is invoked
every blank spaces are escaped.
```r4d
BEFORE$EB()
AFTER
===
BEFOREAFTER
```