r4d 3.0.1

Text oriented macro processor
Documentation 
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
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

### Macro extension

You can extend macros easily with processor interface which is enabled by
**template** feature.

Refer last part of this documentation if you want to extend macros as binary
target.

**Basic demo**

```toml
[dependencies]
r4d = {version="*", features = ["template"]}
```

```rust
use r4d::ExtMacroBuilder;
use r4d::ext_template::*;
use r4d::AuthType;
use r4d::Processor;
use r4d::RadResult;

// ---
// Processor creation precedes...
// ---

// DEMOS
// Extend function macro
processor.add_ext_macro(
    ExtMacroBuilder::new("mac1")
        .args(&["a_first", "a_second"])
        .desc("Description comes here")
        .function(function_template!(
                // NOTE
                // Function macro does not need to expand arguments
                // Because it is already expanded

                // NOTE
                // On split_args macro,
                // Function macro should give second argument as "false"
                // If true, then it will not strip literal quotes
                let args = split_args!(2,false)?;
                let result = format!("{} + {}", args[0], args[1]);
                Ok(Some(result))
        )),
);
// Extend deterred macro
processor.add_ext_macro(
    ExtMacroBuilder::new("mac2")
        .args(&["a_first", "a_second"])
        .desc("Description comes here")
        .deterred(deterred_template!(
                // NOTE
                // Audit authentication
                // Macro name, and required auth type
                audit_auth!("mac2",AuthType::CMD);

                // NOTE
                // On split_args macro,
                // Deterred macro should have second argument as "true"
                // because deterred should not strip before expansion
                let args = split_args!(2,true)?;

                // NOTE
                // expand_args macro should be only called on deterred macros
                // because it expands arguments and also strip
                let result = if expand_args!(&args[0])? == "doit" {

                    // NOTE
                    // You can expand normal expression with expand_args macro
                    Some(format!("I did it -> {}", expand_args!(&args[1])?))
                } else { None };
                Ok(result)
        )),
);
```

**More about codes**

These macros are actually a convenience for trivial typings. Actual code under
the hood are expanded as closure.

```rust
// Original function macro's type
pub(crate) type FunctionMacroType = fn(&str, &mut Processor) -> RadResult<Option<String>>;

// function_template!( Your code ) expands to
|args: &str, processor: &mut Processor| -> RadResult<Option<String>> {
    Your code
}

// Original deterred macro's type
pub(crate) type DFunctionMacroType = fn(&str, usize, &mut Processor) -> RadResult<Option<String>>;

// deterred_template!( Your code ) expands to
|args: &str, level: usize, processor: &mut Processor| -> RadResult<Option<String>> {
    Your code
}

// split_args is  equivalent to
processor.split_arguments("text,to,parse", args, false)

// expand_args macro is equivalent to
processor.expand(level,"text_to_parse", true)

// expand_expr macro is equivalent to
processor.expand(level,"text_to_parse", false)
```

You can also simply send your function as argument instead of using template macros.

### Extend macros as binary with help of script.rs file

You can also extend rad macros by manually editing script.rs file inside src
directory.

[Script file](../src/script.rs) doesn't do anything by default and actually
doesn't get included without template feature.

You can modify the file and make it included by compiling with ```template```
feature.

```bash
# You need to work in a local copy of a project e.g) git clone
git clone https://github.com/simhyeon/r4d

# Build within r4d procject
cargo build --release --features binary,template

# Built binary is located in "target/release" directory
```