shitbox/CONTRIBUTING.md

Contents
========
* [Licensing](#licensing)
* [The **Cmd** trait](#the-cmd-trait)
* [A simple example applet](#a-simple-example-applet)
* [Incorporating a new 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
```Rust
// 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.