appspec - A Tool for generating pod documentation and shell completion

appspec is a tool working with specifications for command line tools. These specifications are typically written in YAML.

The specification for appspec itself can be found in share/appspec-spec.yaml.

It supports commands with and without subcommands, short (-v) and long options (--version) and nested subcommands.

For completion you can specify a static list of values, or you can call an external command. If your program is written in perl and using App::Spec itself, you can also add a callback to your program. which allows quite intelligent completion.

Usage

appspec help

# Generate completion
appspec completion program.yaml --bash >program.bash
appspec completion program.yaml --zsh >_program

# Generate pod documentation
appspec pod program.yaml program.pod
# You could then use pod2man to create a manpage from it
# pod2man program.pod ...

# Generate a new perl App::Spec commandline tool skeleton
appspec help new
appspec new --name myprogram --class My::Program My-Program

Examples

You can see a list of examples in my completion collection [https://github.com/perlpunk/shell-completions].

In the jq file you will see a simple example of a static list of values:

- name: indent
  type: integer
  enum: [1,2,3,4,5,6,7,8]
  summary: indent output using given number of spaces

In the mpath file you can find an example of how to call an external command:

parameters:
- name: module
  summary: Module names
  multiple: true
  type: string
  completion:
    command_string: |
      perl -E'use ExtUtils::Installed;say for ExtUtils::Installed->new(skip_cwd=>1)->modules'

Installation

This is a perl tool. In order to use it, you either need to install it from CPAN, or try the standalone version.

It should work for any perl version 5.10 or higher.

CPAN installation

You need to install the CPAN module App::AppSpec.

This can be done with the cpan or cpanm command:

% cpanm App::AppSpec
# or
% cpan App::AppSpec

The cpanm command might be easier since it doesn't require configuration. You need to install cpanminus for that (e.g. apt-get install cpanminus).

Standalone version

For a standalone version of the script, checkout the standalone branch. There you will find bin/appspec.

It currently requires perl 5.20 or higher, otherwise you will get an error message.

Completion

You can find the shell completion files in the share/completion directory.

Then you can complete like this:

appspec <TAB>
appspec completion -<TAB>
appspec completion --zsh file.yaml

bash

$ source share/completion/bash/appspec.bash

zsh

Add path/to/share/completion/zsh to your .zshrc before the compinit call:

fpath=('path/to/App-AppSpec-p5/share/completion/zsh' $fpath)

and exec zsh.