13 releases
0.1.12 | May 28, 2024 |
---|---|
0.1.11 | May 28, 2024 |
0.1.9 | May 1, 2023 |
0.1.6 | Apr 30, 2023 |
#172 in Procedural macros
150KB
865 lines
A command-line
rpc written in Rust. It build on top of the well-known king of rust cli crates, clap
.
Most of its features are preserved but the usage of command_rpc
shortens the boilerplate code.
Official release: May 29th - There is going to be a tutorial on youtube, also linked here!
Why to use command_rpc
What crpc
is made for
- lightweightness
- efficience
- export to any language
- calls from user or other programs
Of course, that could be a disadvantage, you should not use crpc
for big and well-defaultized
transfer protocolls - and you may not use it for i/o-intense programs.
Advantages to pure clap
-
more concise and less redundant due to less boilerplate
-
inherited type hints in the help text of the cli
-
all clap features persist due to expansion
-
being easy-to write and beginner friendly
Usage of command_rpc
Installation
Run cargo add command-rpc
shell command or insert command-rpc = "*"
in your Cargo.toml.
Just now, in v0.1.12
this tools stands at the beginning of its development.
Example
use command_rpc::crpc_main;
#[crpc_main]
pub mod my_cli_backend {
use command_rpc::{cprc_mod, crpc_fn};
#[cprc_fn]
pub fn greet(
/// The name of the person you want to greet.
name: str
) {
eprintln!("Hello, {}!", name);
}
#[crpc_mod]
pub mod my_cli_backend_sub {
use command_rpc::cprc_fn;
#[crpc_fn]
pub fn friendly_greet(
/// The name of the person you want to greet.
name: str,
/// the adjective you want to use in the greeting.
adjective: str
) {
eprintln!("Hello, {}! You are {}!", name, adjective);
}
}
}
fn main() {
My_cli_mod::parse().delegate();
}
How to use crpc
-
Add
command-rpc
as dependency. -
Write a
crpc
module that has the#[crpc_main]
attribute. The functions (that need to be public!) in it you annotate with#[crpc_fn]
is going to be nested as command, and (public) modules with#[crpc_mod]
included as subcommand, its inner (public) functions will be included too. Also comments will be extracted out of the function signature - other comments are extracted like working with clap. (Better check out our examples --> https://docs.rs/command-rpc/0.1.12/command_rpc/ ) -
Import the needed proc macros with
use command_rpc::*
. -
Give the
main.rs
file access to this module. Yourmain
function looks as follows:fn main() { [name of your crpc_main module, first letter kapital]_::parse().delegate(); }
-
Now you can expand, build or compile your program. Don´t worry about error reports at first, most of them disappear after first build and expansion. Check out Advices below for more information about usage recommendations and things that might not work correctly yet.
Advice
- Use
cargo expand
to take a look on the generated code. You have to runcargo install cargo-expand
first! Unfortunately you will see all expansions even coming fromclap
. - For now,
v0.1.12
, it is not intended to have any output. You can use(e)print(ln)!
to let your cli return something. Furthermore, only native types as input types are intended. Feel free to force the user know about rust syntax for giving objects as input, instead you could use a string as (json) file path. - For the moment it is not possible to give commands with nested subcommands arguments because the function - having the same identifier in your written code - would expand to a struct with the same name which causes problems. An attribute is only allowed to manipulate the given code so this would be difficult to implement but could be possible in a newer version than
v0.1.12
. - When developing more complex command line applications, know about
clap
for more benefits regarding integration betweenclap
andcommand_rpc
!
Contribution
To do so, you may write for longer collaboration a message to me (Mail: loos-johannes@gmx.de, Instagram: lsjohannes), or open directly a pr.
Version overview/preview
v0.1.12
: first working versionv0.1.13
, new feature: commands with nested subcommands are able to have own functionality and argumentsv0.1.14
, new feature: easy version management by just adding version ranges for each commandv0.1.15
, feature extension: diffrent functions with same name but disjoint version ranges coexist
Dependencies
~235–670KB
~16K SLoC