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>