## Format
If any permission is necessary, it is displayed as
Macro expansion demonstration is displayed as
```
$macro_invocation(...)
===
Expanded text from macro
// As some comments
```
## Basic(default) macros
All macros are case sensitive and should come with dollar sign prefix.
* [define](#define)
* [undef](#undef)
* [rename](#rename)
* [repl](#repl)
* [append](#append)
* [pause (keyword macro)](#pause--keyword-macro-)
* [include](#include)
* [read](#read)
* [tempin, tempout, tempto](#tempin--tempout--tempto)
* [redir](#redir)
* [fileout](#fileout)
* [env](#env)
* [ifenv (keyword macro)](#ifenv--keyword-macro-)
* [path](#path)
* [paths](#paths)
* [name](#name)
* [parent](#parent)
* [bind](#bind)
* [Global](#global)
* [pipe, -, \*](#pipe-------)
* [Repeat](#repeat)
* [foreach (keyword macro)](#foreach--keyword-macro-)
* [forloop (keyword macro)](#forloop--keyword-macro-)
* [eval](#eval)
* [if (keyword macro)](#if--keyword-macro-)
* [ifelse (keyword macro)](#ifelse--keyword-macro-)
* [ifdef (keyword macro)](#ifdef--keyword-macro-)
* [not](#not)
* [syscmd](#syscmd)
* [sub](#sub)
* [tr](#tr)
* [len](#len)
* [regex](#regex)
* [trim, chomp, comp](#trim--chomp--comp)
* [nl](#nl)
* [lipsum](#lipsum)
* [time, date](#time--date)
* [from](#from)
* [table](#table)
### define
Define creates an custom macro. This macro is actually not a macro but special
function. Define cannot be renamed or undefined. Define macro cannot be
overriden too.
```
$define(name,a1 a2="$a1(),$a2()")
===
// Define doesn't print new line if it is a single input in the line
```
### undef
Undef can undefine every macros including basic(default) macros. However
```define``` cannot be undefined.
```
$undef(name)
===
// Undef doesn't print new line if it is a single input in the line
```
### rename
Rename can change the name of the macro. This applies both to basic and custom
macro. You cannot rename define.
```
$rename(len,length)
$length(I'm long)
===
8
```
### repl
Replace contents of the custom macro.
```
$define(before=BEFORE)
$repl(before,AFTER)
$before()
```
### append
Append append given string into the macro. Only
custom macro can be appended.
```
$define(test=TEST)
$append(test, CASE)
$test()
===
TEST CASE
```
### pause (keyword macro)
Pause literally pauses every macro execution except pause macro. Even define is
not evaluated
```
$pause(true)
$define(some,a=$a())
$eval(1 + 2)
$pause(false)
$define(some,a=$a())
$eval(1 + 2)
===
$define(some,a=$a())
$eval(1 + 2)
3
```
### include
AUTH : FIN
Include macro reads given file and paste into the position. Included file's
contents are all expanded.
Include macro read a whole file's contents into a single string. This is an
intended behaviour so that nested include macro inside definition can respect
order of expressions. If you are using big chunk of data and you don't use
macros inside other declared macro, try use read macro which read files and
write on the way.
```
$include(src/content.rs)
===
// Content of src/content.rs is pasted in here
```
### read
"Read" include file's content but in a streamlined way. It include files
without saving to any memory. Use this macro when you read from huge file which
might affect memory usage but make sure macro is directly invoked or use some
detour.
```
$define(read_from,a_src=This go before
$read($a_src())
This go after)
$read_from(source.txt)
===
{{Read contents comes here}}
This go before
This go after
```
### tempin, tempout, tempto
AUTH : FIN or FOUT
Tempin gets content from temp file named ```rad.txt```. Macros within temp file
is also expanded. Tempout pushes content into current temp file. You can also
change the temp file with tempto.
Temp file is saved in ```%TEMP%``` in Windows and ```/tmp``` in *nix systmes.
```
$tempout(Hello world) # needs FOUT
$tempin() # needs FIN
$tempto(out.json) # needs FOUT
$tempout({"name":"simon creek"})
$tempin()
===
Hello world
{"name":"simon creek"}
```
### redir
AUTH : FOUT
Redirect all input into a temp file.
```
$redir(true)
$foreach(\*1,2,3*\,Value: $:
)
1,2,3,4,5
$redir(false)
===
// Yield nothing regardless of -o option
// Content is saved to current temp file.
```
### fileout
AUTH : FOUT
Fileout saves contents to a file. If truncate is false, non existent file
argument is panic behaviour.
```
$fileout(true,file_name.txt,Hello World)
$fileout(false,file_name.txt,This is appended)
===
```
### env
AUTH : ENV
Print environment variable. Non existent env varaible will yield warning on
strict mode.
```
$env(HOME)
===
/home/simoncreek
```
### ifenv (keyword macro)
AUTH: ENV
If environment variable is defined, execute expression
```
$ifenv(HOME,$env(HOME))
```
### path
Join a path into the first path.
```
$path($env(HOME),document)
===
/home/simoncreek/document
```
### paths
Join multiple paths
```
$paths(a,b,c)
===
a/b/c
```
### name
Get file name(last part) from input
```
$name(/home/test/Documents/info.txt)
===
info.txt
```
### parent
Get parent path from input
```
$parent(/home/test/Documents/info.txt)
===
/home/test/Documents
```
### bind
Bind macro makes new local macro inside definition. This macro is automatically
clared after evalution of the macro.
```
$define(test,a\_src a\_content=
$bind+(source,$path(cache,$a\_src()))
$fileout(false,$source(),$a\_content())
)
$test+(temp,Hello World)
===
// Now ./cache/temp file contains string "Hello World"
// cannot reference "source" macro after macro execution
```
### Global
Global binds a macro that persists for the whole processing. Global bind is
useful when you don't need dynamic evaluation but static binding. Because
definition is evaluated on every call which might not be necessarily efficient
or not be an intended behaviour.
```
$define(test=$time())
$test()
$global(test=$time())
$test()
===
17:08:39 // This will yield different result according to time.
17:08:39 // This will always yield same result
```
Though, time will most likely print same thing for a single document
processing. Other operations might need consistent bound values.
### pipe, -, \*
Pipe macro simply saves value to pipe. $-() returns piped value
$-*() returns piped value in literal form.
```
$pipe(Value)
$-()
$*()
===
Value
\*Value*\
```
### Repeat
Repeat given content for given times
```
$repeat(3,Content to be repeated
)
===
Content to be repeated
Content to be repeated
Content to be repeated
```
### foreach (keyword macro)
Loop around given value. Value is separated with commas. Thus values should be
always enclosed with double quotes. Iterated values are references with
```$:```.
```
$foreach(\*a,b,c*\,Value: $:
)
===
Value: a
Value: b
Value: c
```
### forloop (keyword macro)
Loop around given range. Value is separated with commas. Iterated values are
references with ```$:```.
Range is inclusive e.g. 1 and 3 means from 1 to 3.
```
$forloop(3,5,Number: $:
)
===
Number: 3
Number: 4
Number: 5
```
### eval
Eval evaluates expression. This macro(function) uses rust's evalexpr crate
[crate link](https://crates.io/crates/evalexpr). Therefore argument formula
follows evalexpr's syntax.
```
$eval(1+2)
$eval(0.1+0.2)
===
3
0.30000000000000004
```
### if (keyword macro)
If gets a condition and prints if given value is true
Text "true" and "false", non "0" integer and "0" are valid inputs. "true" and
"false" is case sensitive. 0 is false and any number other than 0 is true even
negative integer is valid input. Floating point number is not allowed.
```
$if(true,TRUE)
$if(false,False)
===
TRUE
```
### ifelse (keyword macro)
Ifelse gets two branches and print out one according to given condition.
```
$ifelse( true ,I'm true,I'm false)
$ifelse( false ,I'm true,I'm false)
$ifelse( 1 ,I'm true,I'm false)
$ifelse( 0 ,I'm true,I'm false)
===
I'm true
I'm false
I'm true
I'm false
```
### ifdef (keyword macro)
If macro is defined then execute given expression.
```
$define(some=value)
$ifdef(some,Defined)
$undef(some)
$ifdef(some,Not defined)
===
Defined
```
### not
Not negates given boolean value.
```
$not(true)
$not(false)
$not(1)
$not(0)
===
false
true
false
true
```
### syscmd
AUTH : CMD
Call system command, on unix system macro calls given command directly. While
windows call are mediated through ```cmd /C``` call.
```
$syscmd(uname -a)
$syscmd(ver)
===
Linux
Microsoft Windows [Version 10......]
```
### sub
Sub gets substring from given input range. You can give empty value. This is technically same with rust's syntax ```[min..max]```. Also supports utf8 characters.
```
$sub(1,5,123456789)
$sub(2,,123456789)
$sub(,6,123456789)
===
2345
3456789
123456
```
### tr
Tr translate characters to other characters. Utf8 characters work.
```
$tr(Given String,iSg,aOs)
===
Gaven Otrans
```
### len
Return the length of given string. This operation takes O(n) not like
traditional O(1) from rust' string data. This is because len returns length of
utf characters not ASCII characters.
```
$len(Lorem ipsum dolor)
$len(ሰማይ አይታረስ ንጉሥ አይከሰስ።)
$len(Зарегистрируйтесь)
$len(สิบสองกษัตริย์ก่อนหน้าแลถัดไป)
$len(⡍⠔⠙⠖ ⡊ ⠙⠕⠝⠰⠞ ⠍⠑⠁⠝)
$len(나는 안녕하지 못하다)
$len(我们刚才从图书馆来了)
===
17
20
17
29
17
11
10
```
### regex
Regex substitution and regex deletion gets source and additional arguments to
process regex operation. Second argument is regex expression. This use [regex
crate](https://crates.io/crates/regex).
```
$regex(Hello world,w.*?d,rust)
$regex(Hello World// TODO,//.*$,)
===
Hello rust
Hello World
```
### trim, chomp, comp
```Trim``` removes preceding and trailing new lines, tabs and whitespaces from
given input. ```Chomp``` removed duplicate newlines from given input.
```Comp``` both trim and chomp given input
There are variatins with suffix "l" which yield literal output. ```triml,
chompl, compl```
```
$define(value="
UP
DOWN
")
--
$trim($value())
--
$chomp($value())
--
$comp($value())
--
===
--
UP
DOWN
--
UP
DOWN
--
UP
DOWN
--
```
### nl
Simply print out "newline" characters. This newline respects formatter's
newline. Which is ```\r\n``` for windows and a ```\n``` in *nix systems by
default.
```
$nl()
===
// This is useful when you want to construct an output in one-liner
```
### lipsum
Lipsum creates a placehoder with given word counts. This requires features
"lipsum".
```
$lipsum(5)
===
Lorem ipsum dolor sit amet.
```
### time, date
Time and date prints current local time and date. This requires features
"chrono".
```
$time()
$date()
===
03:17:11
2021-08-20
```
### from
From creates formatted macro invocations with given csv values. The given macro
name doesn't need dollar sign prefix. This requires features **"csv"**.
```
$define(three,a1 a2 a3=1-$a1(), 2-$a2(), 3-$a3())
$from+(three,
a,b,c
d,e,f
)
===
1-a, 2-b, 3-c
1-d, 2-e, 3-f
```
NOTE
Former syntax required data as first parameter, however it was such an pain to
always quote values, thus I found second value as csv was much more ergonomic.
### table
Table creates a formatted table from given csv values. Currently supported
formats are ```github```, ```wikitext``` and ```html```. This macro doesn't
pretty print but just make it readable from other programs. This requires
features **"csv"**.
```
$table(github,\*a,b,c
1,2,3
4,5,6*\)
$table(wikitext,\*a,b,c
1,2,3
4,5,6*\)
$table(html,\*a,b,c
1,2,3
4,5,6*\)
===
|1|2|3|
|4|5|6|
{| class="wikitable"
!a
!b
!c
|-
|1
|2
|3
|-
|4
|5
|6
|-
|}
<table><thead><tr><td>a</td><td>b</td><td>c</td></tr></thead><tbody><tr><td>1</td><td>2</td><td>3</td></tr><tr><td>4</td><td>5</td><td>6</td></tr></tbody></table>
```