llms.txt

# options.bash

> A Bash library for building CLI utilities with rich terminal output and option parsing. Pure Bash 4.0+, zero external dependencies beyond coreutils and getopt.

## Quick start

```bash
#!/usr/bin/env bash
set -euo pipefail

LIB_DIR="/path/to/options.bash"

source "${LIB_DIR}/args.sh"
source "${LIB_DIR}/args-help.sh"
source "${LIB_DIR}/args-version.sh"

args::program "my-tool" "1.0.0" "Does useful things"
args::option "-v, --version" "Show version"
args::option "-h, --help" "Show help"
args::option "--output, -o" "Output file" "file"
args::option "build" "Build the project"

args::parse "$@"

# Check parsed results
if [[ -v args_options["--output"] ]]; then
  echo "Output: ${args_options["--output"]}"
fi
echo "Command: ${args_command}"
```

## Modules

### string.sh

String utilities. No dependencies.

- `string::clean STRING` — strip ANSI codes (delegates to `ansi::strip` if loaded, otherwise passthrough).
- `string::length STRING` — visible length (delegates to `ansi::length` if loaded).
- `string::make_pad LENGTH [CHAR]` — create a padding string of given length.
- `string::pad STRING LENGTH [ALIGN] [CHAR]` — pad string to length. ALIGN: `left`/`l`, `right`/`r`, `center`/`c`.
- `string::out ARGS...` — terminal-aware echo (strips ANSI when piped).
- `string::warn ARGS...` — terminal-aware echo to stderr (returns 0, safe under `set -e`).
- `string::err ARGS...` — terminal-aware echo to stderr (returns 1).

### ansi-utils.sh

Shared ANSI utilities loaded by both `ansi.sh` and `ansi-tput.sh`.

- `ansi::color::rgb R G B` — compute 3-bit color code from RGB flags (0 or non-0).
- `ansi::color::make_bright CODE` — add 8 to get bright variant.
- `ansi::color::true R G B` — compute 256-color code from RGB (0–255).
- `ansi::color::grey INTENSITY` — compute 256-color greyscale (0–255).
- `ansi::fg::rgb R G B` — set fg to 3-bit RGB color.
- `ansi::fg::bright_rgb R G B` — set fg to bright 3-bit RGB color.
- `ansi::fg::true R G B` — set fg to 256-color.
- `ansi::fg::grey INTENSITY` — set fg to greyscale.
- `ansi::bg::rgb`, `ansi::bg::bright_rgb`, `ansi::bg::true`, `ansi::bg::grey` — bg equivalents.
- `ansi::extract_sgr_commands CODE` — extract numeric SGR parameters from an escape sequence.
- `ansi::make STYLE...` — compose multiple named/numeric styles into one sequence.
- `ansi::strip STRING` — remove all ANSI escape codes.
- `ansi::length STRING` — visible string length (after stripping ANSI).
- `ansi::out ARGS...` — terminal-aware echo (strips ANSI when piped).
- `ansi::warn ARGS...` — terminal-aware echo to stderr (returns 0, safe under `set -e`).
- `ansi::err ARGS...` — terminal-aware echo to stderr (returns 1).
- `ansi::prompt ARGS...` — like `ansi::out` but no trailing newline.

### ansi.sh

ANSI terminal control via raw escape sequences. Bash 4.0+. Loads `ansi-utils.sh`.

Global data:
- `ansi_style_colors` — associative array mapping color names to numbers (black=0 .. white=7).
- `ansi_style_sgr_commands` — associative array of all named SGR/cursor/screen escape sequences.

Functions:
- `ansi::fg N` — foreground color (0–7 standard, 8–15 bright, 16–255 extended).
- `ansi::bg N` — background color.
- `ansi::fg_true R G B` — 24-bit true color foreground.
- `ansi::bg_true R G B` — 24-bit true color background.
- `ansi::decoration N` — decoration color (256-color).
- `ansi::decoration_true R G B` — 24-bit decoration color.
- `ansi::get NAME` — look up escape sequence by name (tries `NAME`, `text_NAME`, `fg_NAME`).
- `ansi::sgr::make STYLE...` — compose styles into a single SGR sequence.
- `ansi::cursor::pos ROW COL`, `ansi::cursor::up N`, `ansi::cursor::down N`, etc. — cursor movement.
- `ansi::screen::scroll_up N`, `ansi::screen::scroll_down N` — scrolling.
- `ansi::hyperlink URL [TEXT]` — OSC 8 hyperlink.

On source, defines uppercase globals: `RED`, `GREEN`, `BOLD`, `RESET_ALL`, `FG_RED`, `BG_GREEN`, `TEXT_BOLD`, etc.
Suppress with `ANSI_NO_SIMPLE_COMMAND_NAMES=1` before sourcing.

### ansi-tput.sh

Alternative ANSI implementation via `tput`. Bash 4.3+. Loads `ansi-utils.sh`.
Same core API as `ansi.sh` (`ansi::fg`, `ansi::bg`, `ansi::get`, `ansi::make`).
**Mutually exclusive with `ansi.sh`** — source only one.

Additional functions:
- `ansi::tput::sgr BOOL...` — raw tput sgr (standout, underline, reverse, blink, dim, bold, invis, protect, altcharset).
- `ansi::cursor::insert N` — insert N characters.
- `ansi::cursor::insert_lines N` — insert N lines.
- `ansi::screen::lines`, `ansi::screen::cols`, `ansi::screen::colors` — terminal dimensions/capabilities.
- `ansi::terminal::name` — terminal long name.

### ansi-semantic.sh

Semantic color globals for CLI feedback. Bash 4.0+. Loads `ansi.sh`.

Globals (always defined):
- `SEMANTIC_ERROR` — bold bright-white on red background (error messages).
- `SEMANTIC_WARN` — bold bright-white on blue background (warnings).
- `SEMANTIC_INFO` — bold cyan (informational).
- `SEMANTIC_OK` — bold green (success).

Simple names (`ERROR`, `WARN`, `INFO`, `OK`) are defined by default as aliases. Suppress with `ANSI_NO_SEMANTIC_NAMES=1` before sourcing.

Override defaults before sourcing: `ANSI_SEMANTIC_ERROR`, `ANSI_SEMANTIC_WARN`, `ANSI_SEMANTIC_INFO`, `ANSI_SEMANTIC_OK`.

Functions:
- `ansi::semantic::define [PREFIX]` — output eval-able code defining semantic name variables. With prefix: `PREFIX_ERROR`, etc.

### args.sh

CLI option and command parsing via `getopt`. Bash 4.0+. No library dependencies.

Setup functions:
- `args::program NAME VERSION [DESCRIPTION] [URL]` — set program metadata.
- `args::option "NAMES" "DESCRIPTION" [ARG_NAME] [OPTIONAL]` — register an option or command.
  - NAMES: comma/space-separated (e.g., `"-v, --version"`, `"build"`).
  - Options start with `-`; bare words are commands.
  - ARG_NAME non-empty: option takes an argument. OPTIONAL non-empty: argument is optional.
- `args::immediate OPTIONS...` — add to immediate-option list (default: `-h --help -v --version --bash-completion`).
- `args::on_options FUNCTION` — register a hook called after option extraction, before immediate dispatch. Fires even when immediate options exit.
- `args::on_parse FUNCTION` — register a hook called after every successful `args::parse`. Does not fire when immediate options exit early.
- `args::parse "$@"` — parse arguments.

Result globals:
- `args_options` — associative array of parsed options keyed by primary name.
- `args_command` — matched command name (empty if none).
- `args_cleaned` — array of remaining positional arguments.

Configuration globals:
- `args_program_default_command` — default command when none given. Makes command optional. Help screen annotates with *(default)*.
- `args_program_help_style` — `"grid"` (default) or `"list"`.
- `args_program_usage` — custom usage text (overrides auto-generated).
- `args_program_header` — text shown after program description.
- `args_program_footer` — text shown at the end of help.

Error hooks (define to customize error messages):
- `args::error::getopt` — getopt parse failure.
- `args::error::unknown_option OPTION` — unknown option.
- `args::error::no_command` — missing required command.
- `args::error::unknown_command COMMAND` — unknown command.
- `args::error::invalid_short_option NAME` — malformed short option.
- `args::error::invalid_long_option NAME` — malformed long option.

### args-help.sh

Auto-generated colored help screen. Loads `ansi.sh`, `string.sh`, `box.sh`.

- `args::option::help` — print help and exit. Triggered by `-h`/`--help`.
- `args::option::h` — alias for `args::option::help`.

Style globals (override before sourcing or after):
- `args_help_section`, `args_help_program`, `args_help_version`, `args_help_command`, `args_help_option`, etc.

### args-version.sh

Version display handler. No dependencies (uses `args_program_*` globals).

- `args::option::version` — print "name version" and exit. Triggered by `-v`/`--version`.
- `args::option::v` — alias for `args::option::version`.

### args-completion.sh

Bash completion script generation from `args.sh` registration data. Loads `args.sh`.

- `args::completion::generate` — generate a bash completion script and print to stdout. Includes a format version signature, standard `complete -F` function, option argument awareness, and command detection.
- `args::completion::register` — write completion script to `~/.local/share/bash-completion/completions/<name>`. Skips if file has current format version and is newer than tool script. Regenerates on version mismatch. Fails silently if directory is not writable.
- `args::option::completion` — immediate option handler for `--bash-completion`. Calls `generate` and exits.

On source, registers an `args::on_options` hook that calls `args::completion::register` before immediate dispatch (only for tools that declared `--bash-completion`). This ensures registration happens even when `-h` or `--bash-completion` exit early.

Generated files start with `# options.bash-completion v<N>`. Format version changes trigger regeneration regardless of timestamps.

Tools opt in by declaring the option explicitly (like `--help` and `--version`):
```bash
args::option "--bash-completion" "Output bash completion script"
```

### deps.sh

External-tool dependency check. No dependencies. Uses the `args_program_name` global if set, falls back to `${0##*/}`.

- `deps::need TOOL...` — verify each tool is on `$PATH` via `command -v`. If any are missing, print `<program>: required tool(s) not installed: <missing list>` to stderr (all missing tools on one line, order preserved) and `exit 1`. Zero-arg call is a silent no-op. Uses plain `echo`, so it is safe to call before `ansi.sh` is sourced.

### box.sh

Text box layout engine for multi-line strings. Loads `string.sh`.

- `box::make_lines LINE...` — join arguments into a multi-line string.
- `box::make LINE...` — make + normalize (left-aligned).
- `box::get_width STRING` — width of first line (visible characters).
- `box::get_height STRING` — number of lines.
- `box::exec STRING CMD...` — process string through a command pipeline.
  Commands: `normalize ALIGN`, `pad_lr LEFT RIGHT`, `pad_tb TOP BOTTOM`, `align_lr ALIGN WIDTH`, `align_tb ALIGN HEIGHT`, `set_pad CHAR`, `clean`, `extract FROM COUNT`.
  Aliases: `n`, `ph`, `pv`, `ah`, `av`, `sp`, `c`, `e`.
- `box::stack_lr STRING1 STRING2` — stack side-by-side (must have equal height).
- `box::stack_tb STRING1 STRING2` — stack vertically (must have equal width).
- `box::out STRING` — terminal-aware multi-line output.
- `box::warn STRING` — terminal-aware multi-line output to stderr (returns 0, safe under `set -e`).
- `box::err STRING` — terminal-aware multi-line output to stderr (returns 1).

## Bootstrap pattern

A common pattern is a bootstrap file (e.g., `~/.local/libs/bootstrap.sh`) that auto-updates and sources the core modules:

```bash
# include options.bash
command -v git &> /dev/null && git -C ~/.local/share/libs/scripts pull --no-recurse-submodules > /dev/null || true

. ~/.local/share/libs/scripts/ansi.sh
. ~/.local/share/libs/scripts/args.sh
. ~/.local/share/libs/scripts/args-version.sh
. ~/.local/share/libs/scripts/args-help.sh
. ~/.local/share/libs/scripts/args-completion.sh

# echo the first argument and run
echoRun() {
  ansi::out "${CYAN}$@${RESET_ALL}"
  eval "$@"
}

echoRunBold() {
  ansi::out "${BOLD}${CYAN}$@${RESET_ALL}"
  eval "$@"
}
```

Scripts then source it with `. ~/.local/libs/bootstrap.sh` and immediately have access to all library functions, color globals, and helper utilities.

## Testing

### test.sh

Built-in test harness. Loads `ansi.sh` for colored output.

- `test_lib_dir` — absolute path to the library root directory.
- `test_pass`, `test_fail`, `test_total` — counters.
- `test::name LABEL` — set a label for subsequent tests.
- `test::equal ACTUAL EXPECTED [MSG]` — assert string equality.
- `test::not_equal ACTUAL EXPECTED [MSG]` — assert string inequality.
- `test::match ACTUAL PATTERN [MSG]` — assert regex match.
- `test::contains HAYSTACK NEEDLE [MSG]` — assert substring present.
- `test::ok [MSG]` — unconditional pass.
- `test::fail_ [MSG]` — unconditional fail.
- `test::done` — print summary and exit (0 if all pass, 1 if any fail).

Run all automated tests: `bash tests/run.sh`

## Common patterns

### Full CLI with help and version

```bash
#!/usr/bin/env bash
set -euo pipefail

LIB_DIR="$(dirname "$(realpath "$0")")/../lib/options.bash"
source "${LIB_DIR}/args.sh"
source "${LIB_DIR}/args-help.sh"
source "${LIB_DIR}/args-version.sh"

args::program "deploy" "2.0.0" "Deploy application to servers" "https://example.com/deploy"
args::option "-v, --version" "Show version"
args::option "-h, --help" "Show help"
args::option "-n, --dry-run" "Preview without executing"
args::option "--env, -e" "Target environment" "name"
args::option "start" "Start the deployment"
args::option "status" "Check deployment status"

args::parse "$@"

case "$args_command" in
  start)
    echo "Deploying..."
    if [[ -v args_options["--dry-run"] ]]; then
      echo "(dry run)"
    fi
    ;;
  status)
    echo "Checking status..."
    ;;
esac
```

### Colored output

```bash
source "/path/to/options.bash/ansi.sh"

ansi::out "${BOLD}${GREEN}Success:${RESET_ALL} Operation completed"
ansi::err "${BOLD}${RED}Error:${RESET_ALL} Something went wrong"

# Compose styles
header="$(ansi::make bold underline cyan)"
ansi::out "${header}My Header${RESET_ALL}"
```

### Dependency checking

```bash
source "/path/to/options.bash/deps.sh"

# Hard dependency — fail early, before args::program if you want, or after.
# Deliberately makes --help/--version fail on hosts without the tool.
deps::need jq curl

# Optional / lazy dependency — check only on the code path that uses it.
# Good for multi-subcommand utilities that dispatch to different tools.
case "$args_command" in
  encrypt) deps::need age ;;
  compress) deps::need zstd ;;
esac

# Inline fallback for a utility that deliberately doesn't source the library
# (e.g. a slim wrapper that wants to stay dependency-free):
command -v jq >/dev/null 2>&1 || {
  echo "${0##*/}: required tool(s) not installed: jq" >&2
  exit 1
}
```

### Box layout

```bash
source "/path/to/options.bash/box.sh"

lines=$(box::make "Hello" "World" "!")
box=$(box::exec "$lines" set_pad '.' pad_lr 2 2 pad_tb 1 1)
box::out "$box"
# Output:
# ..........
# ..Hello...
# ..World...
# ..!.......
# ..........
```

## Examples

The `examples/` directory contains runnable code samples:

- `bootstrap.sh` — include pattern for `~/.local/libs/bootstrap.sh` (auto-update + source core modules).
- `simple-tool` — minimal CLI tool showing the full args pattern (program, options, commands, parse, use).
- `clean-completions` — utility to find and remove completion files generated by this project.
- `rich-output` — ANSI styling, composed styles, and box layout demo.

## Links

- GitHub: https://github.com/uhop/options.bash
- Wiki: https://github.com/uhop/options.bash/wiki
- License: BSD 3-Clause