docopts docopt.sh comatible examples

Alternative implementation of using docopt CLI option parser language

Following #35, could we provide a set of examples compatibles with both docopts and docopt.sh?

Do not confuse, docopt.sh command line generator for docopt CLI language with our script docopts.sh (with a final S) which is an helper for simplify reuse of docopts binary.

Example format

In order to be compatble with both docopts AND docopt.sh an example should have this format:

• user DOCOPT_PREFIX=ARGS_ ==> docopts -G ${DOCOPT_PREFIX%_} --docopt_sh
• docopts must be found in PATH (See: helpers section bellow)
• Usage $DOC assignment (as docopts read it from -h "$VARIABLE")
• docopt parser switcher (at main script code to allow global scope variable)
• main script code call (normal expected code based on parsed OPTIONS)

pseudo code

#!/usr/bin/env bash

DOC="Usage: code [-v] ARGUMENT"

main_code()
{
  # main function for this script
  return 0
}

# docopt parser switcher code
[...]
main_code

prototype

Here is a tested code, that implements the format for compatibles examples:

Code available here

It requires docopts v0.6.4-alpha1 which support --docopt_sh formater switch, available here.

#!/usr/bin/env bash

DOC="Argument parser
Usage: arguments_example.sh [-vqrh] [FILE] ...
       arguments_example.sh (--left | --right) CORRECTION FILE

Process FILE and optionally apply correction to either left-hand side or
right-hand side.

Arguments:
  FILE        optional input file
  CORRECTION  correction angle, needs FILE, --left or --right to be present

Options:
  -h --help
  -v       verbose mode
  -q       quiet mode
  -r       make report
  --left   use left-hand side
  --right  use right-hand side"

main_arguments()
{
  # main function for this script

  # only display parsed arguments
  set | grep "^$DOCOPT_PREFIX"

  return 0
}

DOCOPT_PREFIX=ARGS_
case $DOCOPT_PARSER in
  docopts)
    if [[ -z $(type -p docopts) ]] ; then
      echo "docopts not found in PATH, use: source example_env.sh"
      exit 1
    fi
    # docopts append _ to prefix
    eval "$(docopts -G ${DOCOPT_PREFIX%_} --docopt_sh -h "$DOC" : "$@")"
    ;;
  docopt.sh)
    eval "$(docopt "$@")"
    ;;
  "")
    echo "DOCOPT_PARSER is undefined"
    exit 1
    ;;
  *)
    echo "DOCOPT_PARSER unsuported value: $DOCOPT_PARSER"
    exit 1
    ;;
esac

# passing $@ is probably wrong without shifting...
main_arguments "$@"

helper and usage

We provided an helper to setup environment

example_env.sh

Usage for docopts

cd path/to/docopts/examples/compatible_docopt.sh
source example_env.sh

Usage for docopt.sh

cd path/to/docopts/examples/compatible_docopt.sh
export DOCOPT_PARSER=docopt.sh
## will update the example code inline
docopt.h arguments_example.sh

compare behavior

diff -u <(DOCOPT_PARSER=docopts ./arguments_example.sh --left corr pipo) <(DOCOPT_PARSER=docopt.sh ./arguments_example.sh --left corr pipo)