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)
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.
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 *\.
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 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
$define(test=\*$path(a,b)*\)
$test()
===
% Macro body is not stripped
\*$path(a,b)*\
Literal arguments without macros
$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.
$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
- Expand $array() ->
- 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 )
- Expand $a_arr() ->
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.
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
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'm going to be used by a pipe macro)
$trim($repeat(2,$-()
))
$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.
$eval|("test" == "test")
$define(result=$-())
$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|(1)
$mac|-()
$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 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
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 document for detailed error behaviours
BR is reserved for debugging usage. You cannot override breakpoint.
$BR()
EB is reserved for blank escape opeartion. After EB is invoked
every blank spaces are escaped.
BEFORE$EB()
AFTER
===
BEFOREAFTER