#### Format

```
$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 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
```

**append**

Append append given string into the macro. Only
custom macro can be appended.

```
$define(test=TEST)
$append(test, CASE)
$test()
===
TEST CASE
```

**pause**

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**

Include macro include given file and paste into the position. Included file's
contents are all expanded.

```
$include(src/content.rs)
===
// Content of src/content.rs is pasted in here
```

**temp**

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)
$tempin()
$tempto(out.json)
$tempout({"name":"simon creek"})
$tempin()
===
Hello world
{"name":"simon creek"}
```

**redir**

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**

Fileout saves contents to the 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**

Print environment variable. Wrong name yields error

```
$env(HOME)
===
/home/simoncreek
```

**path**

Merge two path into one.

```
$path($env(HOME),document)
===
/home/simoncreek/document
```

**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"
```

**pipe, -, \* **

Pipe macro simply saves value to pipe. $-() returns piped value and clears
pipe. $*() returns piped value in literal form.

```
$pipe(Value)
$-()
$-() 
$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**

Loop around given value. Value is separated with commas. Thus values should be
always enclosed with double quotes.

```
$foreach(\*a,b,c*\,Value: $:
)
===
Value: a
Value: b
Value: c

```

**forloop**

Loop around given range. Value is separated with commas. 

Range is inclusive e.g. 1 and 3 means from 1 to 3.

```
$forloop(3,5,Number: $:
)
===
Number: 3
Number: 4
Number: 5

```

**forloop, foreach with nested macro usage**

Forloop and foreach's ```$:``` is a substituion rather than macro expansion.
And first of all rad doesn't create any form of AST from given source thus, $:
is expanded at the last stage, which means for loop's target are **once more evaluated** after.

```
$define(styles,a_styles=<style>
$foreach($a_styles*(),
$include($path($env(GDE_MODULE),$:.css)))
</style>
)
$styles(\*a,b,c*\)
=== 
// This fails because include tries to get path of $GDE_MODULE/$:.css
```
Thus enclose the body with literal rule which will deter evaluation for a time.

```
$define(styles,a_styles=<style>
$foreach($a_styles*(),
\*$include($path($env(GDE_MODULE),$:.css))*\)
</style>
)
$styles(\*a,b,c*\)
===
// This will execute macro of 
// $include($GDE_MODULE/a.css) 
// $include($GDE_MODULE/b.css)
// $include($GDE_MODULE/c.css)
```

**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**

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.

One important note is that, ```if``` and ```ifelse``` evalutes target statement
once more after evaluation.

```
$if(true,TRUE)
$define(wrapper,a_src=$fileout(true,a_src,Hello World))
$if(false,$wrapper*())
===
TRUE
// If always evaluate inner arguments while
// second "if" doesn't evaluate wrapper macro content thus no fileout occurs
```

**ifelse**

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**

Check if given macro is defined or not.

```
$define(some=value)
$ifdef(some)
$undef(some)
$ifdef(some)
===
true
false
```

**syscmd**

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(\*a,b,c
d,e,f*\,three)
===
1-a, 2-b, 3-c
1-d, 2-e, 3-f
```

**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*\)
===
|a|b|c|
|-|-|-|
|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>
```
