diysh is a library which allows developers to create their own shell-like interface for their Rust programs.
A shell is the text interface from where you can read the commands and log the info you need. In order to create a shell you must follow those steps:
```rust let mut shell = Shell::new(); // Mandatory
shell.setsparse(dosparse: bool);
shell.set_prompt(prompt: &str);
shell.register_command(command: CommandDefinition);
shell.register_help();
shell.register_history();
shell.register_exit();
shell.setlogdirectory(path: &str); ```
Once your shell is created, you have access to methods such as:
```rust shell.readandrun();
shell.log(level: LogLevel, text: &str);
shell.help();
shell.history(len: usize);
shell.exit(); ```
If set to true, will print an empty line after a command output in order to give some visual separation between commands.
``` help exit - Exists the program history len - Shows the len-th last commands help - Shows this page print text:str - Prints the specified text to the terminal
print "Hello World" Hello World ```
Sets the text to be displayed before the user input. For example, setting it to ">> ", will give the result:
```
print "Hello World" Hello World help exit - Exists the program history len:int - Shows the list of the last len-th commands ran help - Shows this page print text:str - Prints the specified text to the terminal ```
Probably the most important method. It's used to register new commands to your shell using a CommandDefinition. A CommandDefinition has: a name, a description, arguments and a callback function. Here's an example of a CommandDefinition of a print command:
```rust
let printcommand = CommandDefinition::new("print") // Creates a empty command with given name
.setdescription("text:str - Prints the specified text to the terminal")
.addarg(ArgType::Str) // You can add positional arguments of Str, Int, Float and Bool, as many as you wish
// Here you can both pass the pointer to a function or use a closure that will be called when this command is called
// Your function must be fn(&Shell, &Vec
println!("{}", text);
Box::new(Passed())
})
.build() // Builds the command
```
A description isn't mandatory, but it's recommended to help users to use your shell.
The add_arg method can be called as many times as you wish to add any of the avaliable ArgTypes.
Setting a callback is the most important thing about a command, you can create a command with no callback, but it's useless. The callback receives a reference to the running Shell and the EvaluatedArg vector with the values read from the input.
When specifying command arguments, you need to specify the type of the argument both on the command definition and when you use the argument inside the callback function
ArgType is used to specify the type in the CommandDefinition. Once defined, when the command is read and evaluated, you will receive a vector of EvaluatedArg is the same order that you defined in the definition.
So if you create the following command:
rust
CommandDefinition::new("print")
.add_arg(ArgType::Str)
.add_arg(ArgType::Int)
.add_arg(ArgType::Bool)
.set_callback(|shell, args| { ... })
.build()
args will be a vector where args[0] has a EvaluatedArg::Str, args[1] has a EvaluatedArg::Int and args[2] has a EvaluatedArg::Bool. And inside the function, to get the proper value stored, just call args[0].get_str().unwrap() or args[1].get_int().unwrap() or args[2].get_bool().unwrap().
The methods get_str(),get_int(), get_float() and get_bool() returns a Option and don't try casting, if you call get_int() on a EvaluatedArg::Float you'll receive a None instead of Some.
Registers a help, a history len:int and an exit command.
Here are the respective CommandDefinitions:
```rust CommandDefinition::new("help") .setdescription("- Shows this page") .setcallback(|shell, _args| { shell.help(); }) .build();
CommandDefinition::new("history") .addarg(ArgType::Int) .setdescription("len:int - Shows the list of the last len-th commands ran") .setcallback(|shell, args| { let len = args[0].getint().unwrap();
shell.history(len);
})
.build();
CommandDefinition::new("exit") .setdescription("- Exists the program") .setcallback(|shell, _args| { shell.exit(); }) .build() ```
It's good to know that help, history and exit are public methods, so you can create your own definitions of those commands and still use our provided methods.
Sets a directory where to write the logs
This method is the one who asks for the user to insert a command. It's default behaviour is to print the defined prompt, wait for the user to type the input, try to parse the user input to a command and then run the respective callback passing the arguments passed by the user. Also this function will log every errors, warnings and infos.
The usual is to use readandrun inside a loop.
diysh log system is kinda simple. You just need to call the method log for the current shell and pass it the LogLevel which can be: INFO, WARN or ERROR and then pass a &str containg the desired message. Warnings and Errors get logged to the log file and to the screen, but infos only get logged to the log file.
Here it's a full example of a shell that implements the default commands and a print and a sum command
```rust fn main() { let mut shell = Shell::new();
shell
.set_sparse(true)
.set_prompt(">> ")
.set_log_directory("/tmp/diysh/")
.register_help()
.register_history()
.register_exit()
.register_command( CommandDefinition::new("print")
.set_description("text:str - Prints the specified text to the terminal")
.add_arg(ArgType::Str)
.set_callback(|shell, args| {
let text = args[0].get_str().unwrap();
println!("{}", &text);
shell.log(LogLevel::INFO, &text);
})
.build()
)
.register_command( CommandDefinition::new("sum")
.set_description("a:int b:int - Prints the result of the sum of a + b")
.add_arg(ArgType::Int)
.add_arg(ArgType::Int)
.set_callback(|shell, args| {
let a = args[0].get_int().unwrap();
let b = args[1].get_int().unwrap();
println!("{}", a + b);
shell.log(LogLevel::INFO, &format!("The sum is {}", a + b));
})
.build()
);
loop {
shell.read_and_run();
}
} ```