From 85e8bb6d8b1c3f9e7c1ea93b6390518f2c4c88fe Mon Sep 17 00:00:00 2001 From: Juan Ibiapina Date: Thu, 23 May 2024 02:11:56 +0200 Subject: [PATCH] doc: Improve readme --- README.md | 124 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 80 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 77154cd..b8ab374 100644 --- a/README.md +++ b/README.md @@ -55,96 +55,131 @@ Then add it to your packages: } ``` -## Usage +## Setup + +### As an alias + +The quickest way to get started with `sub` is to define an alias for your CLI +(let's call it `hat`) in your shell: + +```sh +alias hat='sub --name hat --absolute /path/to/cli/root --' +``` -`sub` is meant to be used as the entry point for a CLI. Given the following -directory structure: +Where `/path/to/cli/root` contains a `libexec` directory with executable +scripts, for example: + +``` +. +└── libexec + ├── user-script1 + ├── user-script2 +    └── user-script3 +``` + +### As an executable + +A more reliable way is to use an executable script as the entry point. Given +the following directory structure: ``` . ├── bin -│   └── awesomecli +│   └── hat └── libexec - ├── list - ├── new - ├── open -    └── nested -    ├── README -    └── command + ├── user-script1 + ├── user-script2 +    └── user-script3 ``` -The entry point in `bin/awesomecli` can then be: +The entry point in `bin/hat` is then: ```bash #!/usr/bin/env bash -sub --name awesomecli --executable "${BASH_SOURCE[0]}" --relative ".." -- "$@" +sub --name hat --executable "${BASH_SOURCE[0]}" --relative ".." -- "$@" ``` -The `--name` argument tells `sub` the name of the CLI. This is used when -printing help information. - The `--executable` argument tells `sub` where the CLI entry point is located. -Usually this will just be `${BASH_SOURCE[0]}`. The `--relative` argument tells -`sub` how to find the root of the CLI starting from the CLI entry point. +This will almost always be `${BASH_SOURCE[0]}`. The `--relative` argument tells +`sub` how to find the root of the CLI starting from the CLI entry point. In the +line above, just replace `hat` with the name of your CLI. -After the root directory is determined, `sub` picks up any executable files in -a `libexec` directory inside root to use as subcommands. Directories create -nested subcommands. Arguments for the subcommands themselves go after the `--`. +## Usage -With this setup, invoking `awesomecli` will display all available subcommands -with associated help information. To invoke a subcommand, use: +Once you have set up your CLI, you can get help by running: +```sh +$ hat --help +``` ``` -$ awesomecli +Usage: hat [OPTIONS] [commands_with_args]... + +Arguments: + [commands_with_args]... + +Options: + --usage Print usage + -h, --help Print help + --completions Print completions + --commands Print subcommands + --extension Filter subcommands by extension + +Available subcommands: + user-script1 + user-script2 + user-script3 ``` -Or to invoke a nested subcommand: +To invoke a subcommand, use: ``` -$ awesomecli nested command +$ hat user-script1 ``` -## Documenting commands - To get help for a command, use the built in `--help` flag: ```sh -awesomecli --help +hat --help ``` or ```sh -awesomecli --help +hat --help ``` +## Documenting commands + In order to display help information, `sub` looks for special comments in the -corresponding script. An example documented command: +corresponding script. A fully documented `hello` script could look like this: ```sh #!/usr/bin/env bash # -# Summary: One line summary of the command +# Summary: Say hello # -# Usage: {cmd} +# Usage: {cmd} [--spanish] # -# Extended description of what the command does. +# Say hello to a user by name. # -# The extended description can span multiple lines. +# With the --spanish flag, the greeting will be in Spanish. set -e -echo "Hello $1" -``` +declare -A args="($_HAT_ARGS)" -If the command is a directory, `sub` looks for documentation in a `README` file -inside that directory. +if [[ "${args[spanish]}" == "true" ]]; then + echo "¡Hola, ${args[name]}!" +else + echo "Hello, ${args[name]}!" +fi +``` ## Sharing code between scripts When invoking subcommands, `sub` sets an environment variable called -`_CLINAME_ROOT` (where `CLINAME` is the name of your CLI. This variable holds -the canonicalized path to the root of your CLI. It can be used for instance for -sourcing shared scripts from a `lib` directory next to `libexec`: +`_HAT_ROOT` (where `HAT` is the capitalized name of your CLI. This variable +holds the canonicalized path to the root of your CLI. It can be used for +instance for sourcing shared scripts from a `lib` directory next to `libexec`: ```sh source "$_CLINAME_ROOT/lib/shared.sh" @@ -153,12 +188,13 @@ source "$_CLINAME_ROOT/lib/shared.sh" ## Caching When invoking subcommands, `sub` sets an environment variable called -`_CLINAME_CACHE` (where `CLINAME` is the name of your CLI. This variable points -to an XDG compliant cache directory that can be used for storing temporary files. +`_HAT_CACHE` (where `HAT` is the capitalized name of your CLI. This variable +points to an XDG compliant cache directory that can be used for storing +temporary files. ## Migrating to Sub 2.x -### --bin was renamed to --executable +### change --bin was to --executable The `--bin` argument was renamed to `--executable` to better reflect its purpose.