NAME

appspec-bash - Command line framework generator for bash

ABSTRACT

Generate commandline parser, completion and man pages

DESCRIPTION

This script can generate a commandline parser for bash from a specification file written in YAML.

Writing a parser for commandline arguments isn't rocket science, but it's something you don't want to do manually for all of your scripts, especially in bash. Some tools exist, but they often don't support subcommands or validating of option values.

appspec/appspec-bash can generate pretty much everything for you:

Commandline parser for subcommands, options and parameters

Usage output

Shell completion files

man pages

EXAMPLES

Here is an example of a very simple script.

The following files are needed:

share/mytool.yaml
bin/mytool
lib/mytool
lib/appspec                       # generated
share/completion/zsh/_mytool      # generated
share/completion/bash/mytool.bash # generated
pod/mytool.pod                    # generated
lib/help                          # generated

The spec:

# share/mytool.yaml
---
name: mytool           # commandname
appspec: { version: 0.001 }
plugins: [-Meta]       # not supported in bash
title: My cool tool    # Will be shown in help
class: MyTool          # "Class name" (means function prefix here)

subcommands:
  command1:
    op: command1       # The function name (MyTool.command1)
    summary: cmd one   # Will be shown in help and completion
    options:
    - foo|f=s --Foo    # --foo or -f; '=s' means string
    - bar|b   --Bar    # --bar or -b; a flag

Your script mytool would look like this:

# bin/mytool
#!/bin/bash
DIR="$( dirname $BASH_SOURCE )"
source "$DIR/../lib/appspec"
source "$DIR/../lib/mytool"
APPSPEC.run $@

The actual app:

# lib/mytool
#!/bin/bash
MyTool.command1() {
    echo "=== OPTION foo: $OPT_FOO"
    echo "=== OPTION bar: $OPT_BAR"
}

Generating the parser

Then generate the parser like this:

$ appspec-bash generate parser share/mytool.yaml lib/appspec

APPSPEC.run will parse the arguments and then call the function MyTool.command1. In this function you can use the options via $OPT_FOO and $OPT_BAR.

$ ./bin/mytool command1 --foo x --bar
# or
$ mytool command1 -f x -b
=== OPTION foo: x
=== OPTION bar: true

Generate completion

$ appspec completion share/mytool.yaml --zsh >share/completion/zsh/_mytool
$ appspec completion share/mytool.yaml --bash >share/completion/bash/mytool.bash

Generate pod

$ appspec pod share/mytool.yaml > pod/mytool.pod
$ perldoc pod/mytool.pod

Generate help

$ appspec-bash generate help share/mydemo.yaml lib/help

Generate a new app skeleton

appspec-bash new --class MyTool --name mytool

This will create your app mytool in the directory MyTool and output some usage information like this:

To generate the parser and help, do:

  % cd MyTool
  % appspec-bash generate parser share/mytool.yaml lib/appspec
  % appspec-bash generate help share/mytool.yaml lib/help

Try it out:

  % bin/mytool cmd1 -ab --opt-x x -yfoo --opt-y bar
  % bin/mytool cmd2 -vvv
  % bin/mytool cmd2 -vvv foo

OPTION AND PARAMETER PARSING

appspec-bash supports various types of options.

Flags

# YAML
options:
- verbose|v -- Verbose output

% mytool --verbose
% mytool -v

You can also stack several flags:

% mytool -abc

Options with values

# YAML
options:
- color|c=s --Specify color

% mytool --color red
% mytool -c red
% mytool -cred
# Not yet supported
# mytool --color=red

You can stack flags together with options. If you have the flags -a and -b and the option -c, then you can use this syntax:

% mytool -abc23

Incremental flags

# YAML
options:
- verbose|v+ --Verbose output (incremental)

% mytool -vvv                # like: declare -i OPT_VERBOSE=3
% mytool --verbose --verbose # like: declare -i OPT_VERBOSE=2

Options with multiple values

# YAML
options:
- server|s=s@  --List of servers

% mytool --server foo --server bar
% mytool -s foo -s bar

Parameters

# YAML
parameters:
- name: server
  required: true
  summary: Server name

Option types

By default, an option is a flag. To accept a value, add a =. Then it will be a string by default:

- foo=
# or
- foo=s

You can also create integer options:

- max=i --Specify maximum value

Then you can treat it as an integer and use OPT_MAX+=1 for example.

There are also the types file, dir, filename and dirname. Currently they are only relevant for completion.

# YAML
- input= +file      --Input filename
- source-dir= +dir  --Source directory
- output= +filename --Output file
- out-dir= +dirname --Output directory

In the future, file and dir will check for an existing file or directory. And filename and dirname can be used if the file or directory doesn't exist yet, but the tab completion will still offer file or directory names.

See the mydemo app in the example directory for examples of options and parameters.

GLOBAL OPTIONS

--help -h    Show command help (flag)

SUBCOMMANDS

generate

appspec-bash  generate <subcommands>

Generate parser, help

generate help

appspec-bash generate help <spec> <output>

Generate help functions

Parameters:

spec    *  YAML Specification file   
output  *  Output file, e.g. lib/help

generate parser

appspec-bash generate parser <spec> <output>

Generate main commandline parser script

Parameters:

spec    *  YAML Specification file      
output  *  Output file, e.g. lib/appspec

new

appspec-bash  new [options] [<path>]

Generate new app

This command creates a skeleton for a new app. It will create a directory for your app and write a skeleton spec file.

Example:

appspec-bash new --name mytool --class MyTool MyTool

Options:

--name -n       *  The (file) name of the app                                    
--class -c      *  The main "class" (function prefix) for your app implementation
--overwrite -o     Overwrite existing dist directory (flag)                      

Parameters:

path    Path to the distribution directory (default is the classname in current directory)

help

appspec-bash  help <subcommands> [options]

Show command help

Options:

--all     (flag)

_meta

appspec-bash  _meta <subcommands>

Information and utilities for this app

_meta completion

appspec-bash _meta completion <subcommands>

Shell completion functions

_meta completion generate

appspec-bash _meta completion generate [options]

Generate self completion

Options:

--name    name of the program (optional, override name in spec)
--zsh     for zsh (flag)                                       
--bash    for bash (flag)                                      

_meta pod

appspec-bash _meta pod <subcommands>

Pod documentation

_meta pod generate

appspec-bash _meta pod generate

Generate self pod

cpanm App::Spec::Bash

perl -MCPAN -e shell
install App::Spec::Bash