AXP

About

This page is not about AXP (that is an extensible multi-purpose tool for GNU Arch), but about parsing of its commands and options.

The axp executable is a command line utility written in perl with a number of nice features:

• a multi-level pluggable set of subcommands. For example:

  axp revlib prune --size 50MB --sort ctime --verbose
  axp tree annotate --cvs --reverse -E README

• auto-generated --help, listing all options of every command, i.e.:

  axp --help
  axp triggers list --help

• auto-generated help, listing all subcommands of every composite command, i.e.:

  axp help --recursive
  axp triggers help

• auto-generated hyper-linked self-documentation with custom templates, using:

  axp self doc commands

• auto-generated hyper-linked man pages of all internal perl classes, using:

  axp self doc manpages

• auto-generated completion of all axp commands and options for unix shells (tcsh, zsh), using:

  axp self completion zsh -c -o ~/.zsh/autoload/_axp

Other interesting facts about axp:

• The "plug-in" command system works as following. On command "axp triggers add", exactly 3 classes are loaded, AXP::Command::triggers::add, AXP::Command::triggers and AXP::Command (actually in reverse). Obviously, all logic related to "adding a trigger" is implemented in the deepest class. All functionality common to trigger commands, aka "loading/saving any trigger by name or by index" is implemented in its parent class (AXP::Command::triggers). And all functionality common to all commands, like auto-help, is implemented in the super class (AXP::Command).

  Now, you know how to add a new hypothetical subcommand "axp triggers dump" without changing any existing file. See an example.

  And how does axp ensure correct parsing of "axp registry find migo"? Well, there is a subdirectory for each composite command, i.e. registry/, but not registry/find/ (just registry/find.pm), so it knows to stop here.

• To improve the user usability, all subcommands on "axp tree" level are also exposed to the top level, i.e. axp fork is the same as axp tree fork.
• axp may interactively show the man pages of its own classes (that includes AXP and Arch namespaces), using "axp man Arch::Tree". This is a bit different from invoking "man" on the globally installed man pages of perl modules, since axp may work directly from the released or development tree without installation.
• The utility consists of a short executable and accompanying perl modules, however by issuing "axp self join", it may convert itself into a self-containing single executable with no feature loss. Well, it may convert other similar utilities, like archzoom.cgi and archway too. :)