/ 
Term-DBPrompt-0.01
/ Term::DBPrompt

NAME

Term::DBPrompt - Commandline prompt for a database application

SYNOPSIS

use strict;
use warnings;
use 5.010;

use Term::DBPrompt;

set_prompt { main => 'dbx> ',
             sec  => '  -> ' };

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, $cmd, @params) = get_cmd_line) {

    next if $rc eq 'Empty';

    page_open;

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

    page_close;
}

sub do_help {
    page_say '';
    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';
    page_say '';
}

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
-- Suite  --
...
Parameter #099...: ZZZ
Parameter #100...: ZZZ

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

dbx>

You will notice that the output waits for a keypress 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 in any of the 3 batch modes on a single line by separating them with a ';' character (this is not the case in interactive mode, where multiple commands would interfere with controlling the output pages using the 'more' feature).

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|-a] [-i] [-f file] "cmd1; cmd2; ..."
option -q

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

option -a

Option '-a' stands for show all. This option shows a prompt and the commands in batch mode (it does not have any effect in interactive mode where the prompt and commands 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 set the 2 prompts, the main prompt and the secondary prompt (which is used for multiple commands). The parameter is a hash reference with two keys: 'main' and 'sec'. Here is an example to set the main prompt to 'abc> ' and the secondary prompt to ' --> ':

set_prompt {main => 'abc> ', sec => ' --> '};

The default is '?> ' for the main prompt and '!> ' for the secondary prompt.

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 three elements:

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

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

$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.

$rc == 'Multi'

indicates that multiple commands (separated by ';') have been entered in interactive mode.

page_open

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

page_say

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

page_print

For interactive sessions, this function prints its parameters (without a newline character) to the 'more' pipe. In batch mode, this function prints its parameters (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.