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. ', 'markup' => 'pod', 'name' => 'appspec-bash', 'options' => [], 'subcommands' => { 'generate' => { 'subcommands' => { 'help' => { 'op' => 'genhelp', 'parameters' => [ '+spec= +file --YAML Specification file', '+output= +filename --Output file, e.g. lib/help' ], 'summary' => 'Generate help functions' }, 'parser' => { 'op' => 'parser', 'parameters' => [ '+spec= +file --YAML Specification file', '+output= +filename --Output file, e.g. lib/appspec' ], 'summary' => 'Generate main commandline parser script' } }, 'summary' => 'Generate parser, help' }, 'new' => { 'description' => 'This command creates a skeleton for a new app. It will create a directory for your app and write a skeleton spec file.
mydemo
Example:
appspec-bash new --name mytool --class MyTool MyTool ', 'op' => 'cmd_new', 'options' => [ '+name|n=s --The (file) name of the app', '+class|c=s --The main "class" (function prefix) for your app implementation', 'overwrite|o --Overwrite existing dist directory' ], 'parameters' => [ 'path= +dirname --Path to the distribution directory (default is the classname in current directory)' ], 'summary' => 'Generate new app' } }, 'title' => 'Command line framework generator for bash' }; # END INLINE
1;
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.