Unix validation tools: description of SysVTools.pm

JT::CLI::SysVTools - An object oriented interface to SysV input validation tools methods.

  use JT::CLI::SysVTools;

  my $ck = JT::CLI::SysVTools->new($progType, $poPath, \%options);
  die unless defined $ck && ref $ck;
  my $rc = $ck->run($toolType, \@args);

This documentation describes version 0.33 of JT::CLI::SysVTools.

This module was designed as an object oriented interface for a perl implementation of the input validation tools like ckitem or ckyorn, which are available on SystemV unix systems. It is used in the sysvtools.pl program, but the methods can be used within every other perl program.

The module provides an easy way to prompt the user for a defined type of input and to validate his response. It defines error, help and prompt messages and a set of common and utility specific options to format output and to check the user input against.

There are no terminal specific properties in use, the module should do his work on every terminal, even if you are connected via ssh or Telnet. The only one control key used is CTRL-d (page control in ckitem), all other input is done by an ordinary keyboard with alphanumeric keys.

new($progType, $poPath, \%opts)

Creates a new instance of the class. The progType parameter defines the utility to create. The following types are supported:

ckcont

This utility is an extension to the tools available in SysV unix systems. It simply prints the prompt message and waits for a RETURN. I missed it and added it to my collection. One can use it to let the user read messages printed out by programs and continue with work when ready.

ckdate

The user response must match the given format (or the default format) for a date.

ckgid

The user response should be an existing group name.

ckint

The user response should be an integer, optionally appropriate to a defined base. The output is always the value to base 10.

ckitem

This utility builds a menu and then verifies the response. By default the menu is formatted so that each item is prepended by a number and is printed in columns across the terminal with 10 items per screen. The items are sorted alphabetically. This behaviour can be overwritten by options.

If the choices list is greater than a 10 lines height, the user can page down using the RETURN key or stop the display of choices using CTRL-d. The utility will then show the prompt message. The ?? response reprints the menu starting at the first page.

ckkeywd

The user response must be one of the list of the defined keywords.

ckpath

The user response must be a pathname which obeys the criteria specified by options. If no criteria is defined, the pathname must be a regular file that does not yet exist.

ckrange

The user response should be an integer, optionally appropriate to a defined base. The input is validated against the defined lower and upper bounds. If only one limit is defined, then the range is bounded on only one end. The output is always the value to base 10.

ckstr

The user response must match the defined regular expression and be no longer than the length specified. If no regular expression is given, valid input must be a string with a length less than or equal to the length defined with no internal, leading or trailing white space. If no length is defined, the length is not checked.

cktime

The user response must match the given format (or the default format) for a time.

ckuid

The user response should be an existing user login name.

ckyorn

The user response must be a yes or no answer.

The poPath parameter is the path to the location of the .po message catalogues. I actually did not find a description, where these files should be stored to avoid a separate setting using the bindtextdomain method. If you have installed this module via the make install target, you can left this parameter empty; the install path will be used instead.

The opts parameter is a hash reference with the common and tool specific options, which control both the program behaviour and the validation of the user input.

The following options are accepted by all tools:

  noQuit    => 0         # quit is not allowed as a valid response (0|1)
  width     => 70        # line size for all messages (0..n)
  default   => ''        # the default value when the input is empty
  help      => ''        # help message
  error     => ''        # error message
  prompt    => ''        # prompt message
  killPID   => -1        # the pid to sent a signal to on user quit
  sigPID    => SIGTERM   # the signal sent to the process

The error, help and prompt default messages are read from the message catalogue files. You can overwrite them or append / prepend your own text. This is done by placing a tilde sign at the beginning or the end of your own message.

There are additional options depending on the utility type:

  # ckcont
    message    => ''         # the message to show before the prompt
  # ckdate
    dFormat    => '%m/%d/%y' # the format to check the input against
  # ckgid
    listGroups => 0          # print a list of groups on help and error (0|1)
  # ckint
    base       => 10         # input base (2..36)
  # ckitem
    invisible  => []         # list of choices, which are not printed
    label      => ''         # the menu label
    choices    => 1          # max number of items the user can choose (1..n)
    noSort     => 0          # do or do not sort the items (0|1)
    onlyOne    => 0          # return only one token (0|1)
    noNumbers  => 0          # do not prepend the list with numbers (0|1)
    itemList   => []         # the list of choices to display
  # ckkeywd
    keyWords   => []         # the list of words the user can choose from
  # ckpath
    rel_abs    => ''         # 'relative' or 'absolute'
    fileType   => ''         # requested file type ('b', 'c', 'f' or 'y')
    fIsOld     => 0          # file must exist (0|1)
    fIsNew     => 0          # file must not exist (0|1)
    fCanCreate => 0          # file must be creatable (0|1)
    fNoEmpty   => 0          # file must have a size > 0 (0|1)
    filePerms  => ''         # requested permissions ('rwx')
  # ckrange
    base       => 10         # requested base of input (2..36)
    lower      => LONG_MIN   # lower limit for input
    upper      => LONG_MAX   # upper limit of input
  # ckstr
    sLength    => 0          # maximum length of input
    regex      => []         # list of regex to check the input against
  # cktime
    tFormat    => '%H:%M'    # the format to check the input against
  # ckuid
    listUsers  => 0          # print a list of users on help and error (0|1)

For more details see sysvtools.pl.

run($toolType, \@args[, $silent)

Processes a complete run of the requested tool type. Returns an exit value depending on the result of the process. The following exit values are possible:

0

Successful execution; the value of the user response is printed on STDOUT unless the silent parameter is set to 1.

2

Invalid user input for the val tool type

3

User termination (quit); the response is printed on STDOUT unless the silent parameter is set to 1.

The toolType parameter specifies the type of processing, that should be performed. The following tool types are supported:

ck

Print the prompt message and wait for user response. The response is validated against the defined options. If the user makes an error, the error message is printed and then the prompt message to wait fo a new input. The user can type '?' to display the help message and then return to the input prompt.

For the item program type at first the label (if defined) and the list of choices is printed. If the list exceeds the size of 10, the user can page forward with the RETURN key or stop the listing and show the prompt with the CTRL-d key.

val

Validate the user input and quit. No output is printed

err

Print the error message and quit.

help

Print the help message and quit.

The optional parameter silent specifies, if the user input is printed on STDOUT when exiting the input process

showMessage($msgType)

Prints a message of the requested type. The accepted types are 'error', 'help' and 'prompt'. For the ckitem program type there are 3 additional message types defined: 'error_num' for an invalid numeric input, 'error_str' for an alphanumeric input, which does not match to any choice and 'error_uniq' for an input, which does not identify a choice uniqually.

showList()

This method is valid only for the ckitem program type. It prints the list of choices and controls the paging of the list.

value()

Returns the user response in case of valid input or termination. The value is empty in all other cases.

validateInput($input)

Validates the input parameter against the defined check options. Depending on the program type and the validation result several return values are:

0

The input is valid; the value is available via the value() method.

1

validation error.

2

Empty input, but default available; the default value is available via the value() method.

3

Empty input, no default available.

4

User termination (quit); The input is available via the value() method. If the noQuit option is set to '1', this return value is not possible, instead '1' is returned.

5

Help is requested (the user input was '?')

6

Reprint is requested (the user input was '??'); only available for ckitem.

7

Specific value for ckitem: A numeric input did not match a choices number.

8

Specific value for ckitem: An alphanumeric input did not match a choice.

9

Specific value for ckitem: An alphanumeric input did not uniqually identify a choice.

BUGS

There are some differences to the unix originals, please see TODO for a detailed discussion. If you find a bug, please contact me and send me a detailed bug report.