command-engine 1.0.0

Transform string instructions into code execution.
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

# Command Engine

Transform string instructions into code execution. <br>

## Engine

This crate provides a default engine, that is present if default features are enabled.
It is simply a container for your Commands that can also execute them based on the input.

There are 2 versions of the default Engine:
- `sync` - Default.
- `async` - Enabled with `async` feature.

## Instruction

The given input is deserialized into a specific format defined in `Instruction` structure.

It allows for one Command `caller`, multiple positional `args`, additional `o_args` which act like flags 
that can contain `sub_args`.

Format:
```pseudo
<caller> <arg> <arg> --<o_arg> <sub_arg> <sub_arg> --<o_arg>
```

Example:
```pseudo
example argument1 argument2 --flag2 child1 child2 --flag3 --flag1
```

Deserializes to:
```rust
Instruction {
    caller: "example",
    args: vec!["argument1", "argument2"],
    o_args: {
        let mut map = HashMap::new();
        map.insert("--flag2", Some(vec!["child1", "child2"]));
        map.insert("--flag3", None);
        map.insert("--flag1", None);
        map
    },
    input: "example argument1 argument2 --flag2 child1 child2 --flag3 --flag1",
};
```

To add spaces in arguments use double quotes `"`:
```pseudo
example "argument 1" "--flag 2" "child 1"
```
If there are double quotes in the argument it's suggested to use collector `#`:
```pseudo
example #"argument "quotes" 1"#
```

There are no escape characters to avoid any heap allocations. Each argument is a string slice taken from the input.

## Example

Sync version:
```rust
use command_engine::*;

pub struct Example;

impl CommandInfo for Example {
    fn caller(&self) -> &'static str {
        "ex"
    }
}

impl Command for Example {
    type Output = String;

    fn on_execute(&self, ins: Instruction) -> Self::Output {
        format!("{:?}", ins)
    }
}

fn main() {
    let input = "ex arg --o_arg sub_arg";
    
    let mut engine = Engine::new();
    engine.insert(Example);
    
    // Will return formatted string of the Instruction.
    let output = engine.execute(input).unwrap();
    println!("{}", output);
}
```

## Disclaimer


#### ToDo _(in future)_:

- [ ] Custom Instructions (just like the Outputs)
- [ ] Integrated help command

#### Versioning:

- `*.*.*` - Released.
- `*.*.*-rc.*` - Release Candidate.
- `*.*.*-dev` - Unreleased in production.
- `0.*.*` - Deprecated.