shitbox/CONTRIBUTING.md

Contents

• Licensing
• The Cmd trait
• A simple example applet
• Incorporating a new applet

Licensing

This code is BeerWare. It is essentially in the public domain. If you wish to contribute, your name may be added to the credits, but by contributing you agree to basically place your contributions into the public domain.

The Cmd trait

The Cmd trait is defined in src/cmd/mod.rs. All applets should live in their own submodule under crate::cmd and include a struct with the name of the command, in snake case. This struct must implement Cmd. It is recommended that this struct have at least the fields name: &'static str and path: crate::Path. The trait methods name and path can then just return the corresponding fields.

The applet module should further contain a constant which is basically the default instance for this struct.

A Simple Example Applet

// src/cmd/myapplet/mod.rs
use clap::Command;
use super::Cmd;

pub struct MyApplet {
    name: &'static str,
    path: crate::Path,
}

pub const MYAPPLET: MyApplet = MyApplet {
    name: "myapplet",
    path: crate::Path::UsrBin,
};

impl Cmd for MyApplet {
    fn name(&self) -> &str {
        self.name
    }

    fn cli(&self) -> clap::Command {
        Command::new(self.name)
            .version(env!("CARGO_PKG_VERSION"))
            .author("Zaphod Beeblebrox")
            .about("Does sketchy things")
    }

    fn run(&self, _matches: Option<&clap::ArgMatches>) -> Result<(), Box<dyn std::error::Error>> {
        println!("If there's anything more important than my ego around, I want it caught and shot now.");
        Ok(())
    }

    fn path(&self) -> Option<crate::Path> {
        self.path
    }
}

Incorporating a new applet

Each command module should be public in src/cmd/mod.rs and both the struct which implements Cmd and the constant which is an instance of that struct should be exported as public in that file.

There are several other files which must also be edited to fully integrate a new command. Expect improvements to this process as the Api evolves.

• src/lib.rs: The function run has a match statement which checks the name with which the program was invoked. A new match arm must be added here.
• src/cmd/bootstrap/mod.rs: The run method has a Vec of trait objects representing all of the available applets. The constant which is an instance of the struct implementing Cmd should be added to this Vec. -src/cmd/shitbox/mod.rs: The cli method will need MYAPPLET.cli() added in to the clap subcommands. The run method has a match statement which checks the subcommand that has been asked to run. A new match arm must also be added here.