/ 
Term-DBPrompt-0.02
/ Term::DBPrompt

NAME

Term::DBPrompt - Commandline prompt for a database application

SYNOPSIS

use strict;
use warnings;
use 5.010;

use Term::DBPrompt;

set_prompt 'dbx> ';

set_banner qq{\n}.
  qq{*******************************************\n}.
  qq{**   The Database Application Ver 0.12   **\n}.
  qq{*******************************************\n}.
  qq{*                                         *\n}.
  qq{* to get a help screen,    enter "h(elp)" *\n}.
  qq{* to exit the application, enter "e(xit)" *\n}.
  qq{*                                         *\n}.
  qq{*******************************************\n};

set_command qw(exit help list);

while (my ($rc, $open, $close, $cmd, @params) = get_cmd_line) {

    next if $rc eq 'Empty';

    page_open if $open;

    if ($rc eq 'Dup') {
        local $" = "', '";
        page_msg_say "-- Command '$cmd' can not be uniquely identified";
        page_msg_say "-- Possibilities are ('@params')";
        page_msg_say "-- type 'h' for help or 'e' to exit";
    }
    elsif ($rc eq 'Multi') {
        page_msg_say "-- Multiple commands can not be issued in interactive mode";
        page_msg_say "-- type 'h' for help or 'e' to exit";
    }
    else {
        given ($cmd) {
            when ('exit') { last; }
            when ('help') { do_help(@params); }
            when ('list') { do_list(@params); }
            default {
                local $" = "', '";
                if ($rc eq 'Not') {
                    page_msg_say "-- Invalid command '$cmd' ('@params')";
                    page_msg_say "-- type 'h' for help or 'e' to exit";
                }
                else {
                    page_msg_say "-- Function not implemented '$cmd' ('@params')";
                    page_msg_say "-- type 'h' for help or 'e' to exit";
                }
            }
        }
    }

    page_close if $close;
}

sub do_help {
    page_say 'DBX - Database Application';
    page_say '';
    page_say 'Commands:';
    page_say '';
    page_say '  h(elp)   -- shows this screen';
    page_say '  l(ist)   -- list parameters';
    page_say '  e(xit)   -- exit the application';
}

sub do_list {
    page_say '*****************';
    page_say '**  Parameters **';
    page_say '*****************';
    page_say '';

    for (1..100) {
        page_say sprintf('Parameter #%03d...: ZZZ', $_);
    }

    page_say '';
    page_say '*****************';
}

DESCRIPTION

Interactive mode

We save the example program from the synopsis in dbx.pl and we run it with a simple 'perl dbx.pl', which creates the following output:

C:\>perl dbx.pl

*******************************************
**   The Database Application Ver 0.12   **
*******************************************
*                                         *
* to get a help screen,    enter "h(elp)" *
* to exit the application, enter "e(xit)" *
*                                         *
*******************************************

dbx>

As you can see, we are greeted by a banner (as defined by the set_banner command in the dbx.pl program) and a command prompt 'dbx>'.

Now we can enter our first interactive command, the 'help' command:

dbx> help

DBX - Database Application

Commands:

  h(elp)   -- shows this screen
  l(ist)   -- list parameters
  e(xit)   -- exit the application


dbx>

Now we can issue another command, the 'list' command. We don't need to spell out the whole command, the first characters that make that command unique is enough, in this case a simple 'l' suffices. (The list of available commands is defined by the 'set_command(...)' instruction).

dbx> l
*****************
**  Parameters **
*****************

Parameter #001...: ZZZ
Parameter #002...: ZZZ
...
Parameter #049...: ZZZ
Parameter #050...: ZZZ
-- Next  --
...
Parameter #099...: ZZZ
Parameter #100...: ZZZ

*****************

dbx>

You will notice that the output waits for a keypress (see the '-- Next --' line) after a page is complete (i.e. it is piped through 'more').

To exit the application, you can either hit the EOF character (that is Ctrl-Z on Windows or Ctrl-D on Linux) or you can enter the exit command.

Batch mode

There are 3 different ways to feed commands in batch mode: as a parameter on the commandline, as a file specified via option '-f' or as a file redirected into STDIN, all of these 3 possibilities can be combined. Multiple commands can be issued on a single line by separating them with a ';' character. You can also use the '#' character to write comments.

Commandline

Here is an example that uses a parameter on the command line to issue the help command:

C:\>perl dbx.pl help

In order to issue multiple commands, you need to enclose the parameter with double quotes (on Windows) or single quotes (on Linux). Here is a Windows example:

C:\>perl dbx.pl "help; list;"
option -f

Here is an example that uses option '-f' to feed a file into dbx.pl. Suppose we have a file 'cmd.txt' that contains many commands. We could feed this file into dbx.pl like so:

C:\>perl dbx.pl -f cmd.txt
Redirection

We can also feed a file into dbx.pl by redirecting STDIN:

C:\>perl dbx.pl < cmd.txt

Commandline interface

Here is an overview of the commandline interface:

perl dbx.pl [-q] [-p] [-s] [-f file] [-i] "cmd1; cmd2; ..."
option -q

Option '-q' stands for quiet mode. This option supresses normal output in batch mode (it does not have any effect in interactive mode).

option -p

Option '-p' stands for show prompt. This option shows a prompt and the commands in batch mode. It does not have any effect in interactive mode where the prompt is shown anyway.

option -s

Option '-s' stands for silent mode. This option supresses messages (error messages and success messages). It does not have any effect in interactive mode where messages are shown anyway.

option -f

As already described above, we can use option '-f' to feed a file into dbx.pl:

C:\>perl dbx.pl -f cmd.txt
option -i

Option '-i' forces interactive mode where the command would otherwise run in batch mode. Consider the above example "perl dbx.pl -f cmd.txt" which runs in batch mode, i.e. it terminates after the last command in cmd.txt. If, however, you wish to continue in interactive mode after the commands in cmd.txt have been processed, you can use the -i option:

C:\>perl dbx.pl -i -f cmd.txt

EXPORTED FUNCTIONS

The following functions are exported by default:

set_prompt

This functions sets the prompt. Here is an example to set the prompt to 'abc> ':

set_prompt 'abc> ';

The default is '?> '.

set_banner

The banner is one big string which is displayed at the beginning of each interactive session. You can set the banner with the set_banner function:

set_banner qq{\n}.
  qq{*******************************************\n}.
  qq{**   The Database Application Ver 0.12   **\n}.
  qq{*******************************************\n}.
  qq{*                                         *\n}.
  qq{* to get a help screen,    enter "h(elp)" *\n}.
  qq{* to exit the application, enter "e(xit)" *\n}.
  qq{*                                         *\n}.
  qq{*******************************************\n};
set_command

The function set_command is used to register all possible identifiers that can be used to trigger an action. Two common identifiers are 'help' and 'exit', but there can be many more, depending on the particular application, such as 'add', 'remove', 'list', etc. The reason why these identifiers have to be registered is that long commands can be shortened to a prefix, if that prefix is unique. With the help of the function set_command, the program can then automatically compute the smallest prefix which is still unique to identify an action.

To give a concrete example, suppose we have the following list of commands:

set_command qw(help exit init input list);

If we issued a command 'h', the system would automatically choose the identifier 'help' because there is only one identifier that begins with 'h'. However, if we issued a command 'i', the system would not be able to decide if we wanted the identifier 'init' or 'input'. In order to be valid, we would have to enter at least 3 characters (either 'ini' or 'inp').

get_cmd_line

This is the main function to obtain one line from the input (either from STDIN, from a file or from the commandline). The function takes no parameter, but returns 5 elements:

my ($rc, $open, $close, $cmd, @params) = get_cmd_line;

The first parameter is a return code. It can have 4 values: 'Found', 'Not', 'Empty' or 'Dup'.

$rc == 'Found'

indicates that the prefix that has been entered corresponds exactly to one identifier. $cmd contains that identifier in full and @param contains all parameters.

$rc == 'Not'

indicates that the prefix that has been entered does not correspond to any identifier. $cmd contains the prefix and @param contains all parameters.

$rc == 'Empty'

indicates that an empty line has been entered.

$rc == 'Dup'

indicates that the prefix which has been entered corresponds to more than one identifier. In that case $cmd contains the prefix and @param contains all the possible identifiers that match the prefix.

The value $open can be either 0 or 1. It indicates whether or not the page_open() function should be called before the command is executed.

The value $close can be either 0 or 1. It indicates whether or not the page_close() function should be called after the command is executed.

get_candidates

This functions returns all possible candidates for a given word where the prefix of the commands registered in the set_command function matches that word. The returned list can have 0, 1 or more than 1 element.

page_open

This functions open a pipe to 'more' for interactive sessions (in batch mode, this is a no-op)

page_say

This function is used for printing normal output with a trailing newline character.

For interactive sessions, this function prints the output (followed by a newline character) to the 'more' pipe. In batch mode, this function prints the output (followed by a newline character) to STDOUT.

page_print

This function is used for printing normal output without a trailing newline character.

For interactive sessions, this function prints the output (without a newline character) to the 'more' pipe. In batch mode, this function prints the output (without a newline character) to STDOUT.

page_msg_say

This function is used for printing messages with a trailing newline character.

For interactive sessions, this function prints the message (followed by a newline character) to the 'more' pipe. In batch mode, this function prints the message (followed by a newline character) to STDOUT.

page_msg_print

This function is used for printing messages without a trailing newline character.

For interactive sessions, this function prints the message (without a newline character) to the 'more' pipe. In batch mode, this function prints the message (without a newline character) to STDOUT.

page_close

This functions closes the pipe to 'more' for interactive sessions (in batch mode, this is a no-op)

AUTHOR

Klaus Eichner <klaus03@gmail.com>

COPYRIGHT

Copyright (c) 2009 Klaus Eichner. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.