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>