NAME

"Commandable" - utilities for commandline-based programs

DESCRIPTION

This distribution contains a collection of utilities extracted from various commandline-based programs I have written, in the hope of trying to find a standard base to build these from in future.

Note that "commandline" does not necessarily mean "plain-text running in a terminal"; simply that the mode of operation is that the user types a textual representation of some action, and the program parses this text in order to perform it. This could equally apply to a command input text area in a GUI program.

PROGRAM STRUCTURE

A typical program using this distribution would have a single instance of a "finder", whose job is to work out the set of commands offered by the program. Various subclasses of finder are provided that use different techniques to locate the individual commands, depending on the structure provided by the program.

• Commandable::Finder::SubAttributes - expects to find each command implemented as a subroutine within a single package. These subroutines should all have attributes that provide description text, and specifications of argument and option parsing. The code body of the subroutine is then used to implement the actual command.
• Commandable::Finder::MethodAttributes - a variant of the above which expects that commands are implemented as methods on an object instance.
• Commandable::Finder::Packages - expects to find each command implemented as an entire package, with (constant) subroutines to give the description text and argument and option parsing specifications. Another subroutine within the package actually implements the command.

As the user requests that commands be executed, the text of each request is then wrapped in an instance of Commandable::Invocation. This is then passed to the finder instance to actually invoke a command by parsing its name, options and arguments, and run the actual code body.

   my $finder = Commandable::Finder::...->new( ... );
   my $cinv = Commandable::Invocation->new( $text );
   $finder->find_and_invoke( $cinv );

The finder instance is not modified by individual invocations, and can be reused if the program wishes to provide some sort of multiple invocation ability; perhaps in the form of a REPL-like shell:

   my $finder = ...
   while( my $text = <STDIN> ) {
      $finder->find_and_invoke( Commandable::Invocation->new( $text ) );
   }

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>