NAME
    Term::TUI - simple tool for building text-based user interfaces

SYNOPSIS
    If TUI_Run is the only routine being used:

      use Term::TUI;
      $flag=TUI_Run($command,\%desc);

      $version=Term::TUI::TUI_Version;

    If other TUI subroutines are used:

      use Term::TUI qw(:all);
      $flag=TUI_Run($command,\%desc);

      TUI_Out($message);

      $flag=TUI_Script(\%desc,$script,$sep);

DESCRIPTION
    Many times, I've wanted to quickly write a nice text-based user
    interface around a set of perl routines only to end up writing the full
    (though simple) parser and interface to make it nice enough, and
    friendly enough, to be usable.

    This module creates a simple but powerful text based user interface
    around perl routines, adding such features as command line history,
    command line editing, online help, and command completion, while hiding
    all details of the interface from the programmer.

    The interface is described in a simple hash which is passed to the
    TUI_Run command. This routine exits only when the user has exited the
    program (returning a flag signalling any special exit conditions).

ROUTINES
    TUI_Run
          use Term::TUI;
          $flag=TUI_Run($command,\%desc);

        The TUI_Run command is used to run the interface. It prompts the
        user for commands and executes them (based on description of passed
        in as %desc) until the user exits. The return flag is 0 unless the
        user exited with the Abort command when it is 1.

    TUI_Script
          use Term::TUI qw(:all);
          $flag=TUI_Script(\%desc,$script [,$sep]);

        This allows you to pass in commands in a "script" instead of an
        interactive session. The script is a series of commands separated by
        a semicolon (or the string included in $sep).

    TUI_Version
          use Term::TUI qw(:all);
          $vers=TUI_Version;

        Returns the version of the module.

    TUI_Out
          use Term::TUI qw(:all);
          TUI_Out($mess);

        This is used in the routines given in the description hash to send a
        message to STDOUT.

INTERFACE DESCRIPTION
    The interface allows you to describe multiple "modes" organized in a
    simple tree-like hierarchy (or modes, submodes, subsubmodes, etc.), each
    of which has it's own set of commands specific to that mode. I've
    modeled it after a unix filesystem with directories being "modes" and
    executables being equivalent to commands. So, you might want to model
    the following tree:

          /
          +--------------------+
          math                 string
          |                    |
          +-----+-----+        +------+
          hex   add*  mult*    len*   subs*
          |
          +-----+
          add*  mult*

    Here the "executables" are marked with asterixes(*). So in math mode,
    you could type "add" or "mult" to add a list of numbers together or
    multiply them together. It also has a submode "hex" where you can do
    that in hexidecimal.

    I find this type of interface very conveniant in many cases, but a
    nuisance to write. This module handles this trivially. The above
    interface can be written with the following 2 perl commands:

       %modes =
        (".HELP"  => "This is the main help.\nNot a lot of info here.",
         "math"   => {".HELP" => "A simple calculator.  Currently it can\n" .
                                 "only add and multiply in hex or decimal.",
                      "add"   => [ "Add numbers together."  ,    Add,0 ],
                      "mult"  => [ "Multiply numbers together.", Mult,0 ],
                      "hex"   => {".HELP"  => "Math in hex.",
                                  "add"   => [ "Add hex numbers together.",
                                               Add,1 ],
                                  "mult"  => [ "Multiply hex numbers together.",
                                               Mult,1 ]
                                 }
                     },
         "string" => {".HELP" => "String operations",
                      "subs"  => [ "Take STRING,POS,LEN and returns substring.",
                                   Substring ],
                      "len"   => [ "Returns the length of a string.",
                                   Length ]
                     }
       );

       $flag=TUI_Run("sample",\%modes);
       print "*** ABORT ***\n"  if ($flag);

    You also have to write an Add, Mult, Substring, and Length subroutine of
    course, but once that's done, you end up with a rather nice text based
    user interface. The following are excerpts from a session using the
    sample interface defined above:

    Changing modes is trivial. Just type in the new mode using a syntax
    similar to the unix filesystem:

       sample> string
       sample:string> /math/hex
       sample:math/hex> ..
       sample:math> hex
       sample:math/hex> /
       sample>

    When in a given mode, you can just type commands relevant to that mode:

       sample:string> subs barnyard 1 3
         Substring = arn
       sample:string> len barnyard
         Length = 8

    You can also explicitely type in the mode for a command. In this
    situation, commands can be typed as MODE/CMD ARGS or MODE CMD ARGS
    equivalently:

       sample:string> /math/hex/add 4 6 1
         Total = b
       sample:string> /math mult 4 6 2
         Total = 48

    There are several built-in commands including "..", "/", "help",
    "abort", "exit", and "quit". The last two ("exit" and "quit") are
    equivalent and mean to exit and return 0. "abort" exits with a value of
    1.

    There is also online help:

       sample> help

       This is the main help.
       Not a lot of info here.

       Additional help:

          Modes: math string
          Cmds : .. / abort exit help quit

       sample> help /string

       String operations

       Additional help:

          Cmds : .. / abort exit help quit
                 len subs

       sample> math
       sample:math> help

       A simple calculator.  Currently it can only
       add and multiply in hex or decimal.

       Additional help:

          Modes: hex
          Cmds : .. / abort exit help quit
                 add mult

       sample:math> help add

       Add numbers together.

       sample:math> help /string len

       Returns the length of a string.

       sample:math> help /string/subs

       Take STRING,POS,LEN and returns a substring.

    Currently, Term::TUI does not have much in the way of bells and
    whistles, and I doubt it ever will. It's not designed for a full-blown,
    feature-rich user interface. It's mainly intended for simple control or
    config tools (similar to lpc for example) used primarily by the sysadmin
    type people (who else is interested in a text-based interface after all
    :-).

    There is also a non-interactive form which allows the same interface to
    be called in scripts.

       TUI_Script(\%modes,"/math add 3 5; string; subs barnyard 1 3");

    returns

       Total = 8
       Substring = arn

    TUI DOES use one of the Term::ReadLine modules for the interactive
    session, so if you have Term::ReadLine::GNU or Term::ReadLine::Perl
    installed, you can use things like command history and command line
    editing.

KNOWN PROBLEMS
    None known at this point.

LICENSE
    This script is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

AUTHOR
    Sullivan Beck (sbeck@cpan.org)

