appspec-bash - Command line framework generator for bash
Generate commandline parser, completion and man pages
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:
appspec
appspec-bash
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:
mytool
# 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" }
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.
APPSPEC.run
MyTool.command1
$OPT_FOO
$OPT_BAR
$ ./bin/mytool command1 --foo x --bar # or $ mytool command1 -f x -b === OPTION foo: x === OPTION bar: true
$ appspec completion share/mytool.yaml --zsh >share/completion/zsh/_mytool $ appspec completion share/mytool.yaml --bash >share/completion/bash/mytool.bash
$ appspec pod share/mytool.yaml > pod/mytool.pod $ perldoc pod/mytool.pod
$ appspec-bash generate help share/mydemo.yaml lib/help
appspec-bash new --class MyTool --name mytool
This will create your app mytool in the directory MyTool and output some usage information like this:
MyTool
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
appspec-bash supports various types of options.
# YAML options: - verbose|v -- Verbose output % mytool --verbose % mytool -v
You can also stack several flags:
% mytool -abc
# 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:
-a
-b
-c
% mytool -abc23
# YAML options: - verbose|v+ --Verbose output (incremental) % mytool -vvv # like: declare -i OPT_VERBOSE=3 % mytool --verbose --verbose # like: declare -i OPT_VERBOSE=2
# YAML options: - server|s=s@ --List of servers % mytool --server foo --server bar % mytool -s foo -s bar
# YAML parameters: - name: server required: true summary: Server name
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.
OPT_MAX+=1
There are also the types file, dir, filename and dirname. Currently they are only relevant for completion.
file
dir
filename
dirname
# 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.
mydemo
--help -h Show command help (flag)
appspec-bash generate <subcommands>
Generate parser, help
appspec-bash generate help <spec> <output>
Generate help functions
Parameters:
spec * YAML Specification file output * Output file, e.g. lib/help
appspec-bash generate parser <spec> <output>
Generate main commandline parser script
spec * YAML Specification file output * Output file, e.g. lib/appspec
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)
path Path to the distribution directory (default is the classname in current directory)
appspec-bash help <subcommands> [options]
Show command help
--all (flag)
appspec-bash _meta <subcommands>
Information and utilities for this app
appspec-bash _meta completion <subcommands>
Shell completion functions
appspec-bash _meta completion generate [options]
Generate self completion
--name name of the program (optional, override name in spec) --zsh for zsh (flag) --bash for bash (flag)
appspec-bash _meta pod <subcommands>
Pod documentation
appspec-bash _meta pod generate
Generate self pod
To install App::Spec::Bash, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::Spec::Bash
CPAN shell
perl -MCPAN -e shell install App::Spec::Bash
For more information on module installation, please visit the detailed CPAN module installation guide.