docpars

An ultra-fast parser for declarative command-line options for your shell scripts.

It implements the Docopt syntax and is written in Rust.

Table of contents

• Usage
• Motivation
• Installation
  • Using Homebrew or Linuxbrew
  • Using cargo
  • Downloading pre-compiled binaries
  • Building from source
• Credits

Usage

If you run coffee make --dark for the following script...

#!/usr/bin/env bash

##? Coffee tool
##?
##? Usage:
##?     coffee make [--dark]
##?     coffee drink

# This function can be included in a helper bash file 
# and imported by all your scripts
args::parse() {
   eval "$(/path/to/docpars -h "$(grep "^##?" "$0" | cut -c 5-)" : "$@")"
}

args::parse "$@"

if $drink; then
   echo "Drinking coffee..."
elif $make; then
   $dark && echo "Making dark coffee..." || echo "Making coffee..."
fi

...then Making dark coffee... should be printed.

Motivation

The default implementation of docopt for shell scripts uses Python under the hood. You may want to use docpars instead in the following scenarios

You don't want to install Python

This may be the case of CI/CD instances, minimal docker containers or environments where you may want to run some scripts but aren't equipped with your whole dev arsenal, such as Termux on Android or WSL on Windows.

Instead of installing Python you can simply drop a ~1MB static binary.

You want extreme performance

Benchmarks show that docpars is up to 5.7 times faster than the Python equivalent.

This may not be noticible for most use-cases but it may make the difference if your script is called inside a for loop, for example.

Installation

Using Homebrew or Linuxbrew

brew install denisidoro/tools/docpars

Using cargo

cargo install docpars

Downloading pre-compiled binaries

You can download binaries here.

They are available for OSX, Android and Linux with ARM and x86_64 variants.

Building from source

git clone https://github.com/denisidoro/docpars ~/.docpars
cd ~/.docpars
cargo install --path .

Credits

Most work was done in docopt.rs by BurntSushi, where the actual Docopt parsing is implemented.