SimpleProgram v1.0 

 The Simple Development Library program declaration 

Project: the Simple Development Library.

Table of contents

1. Package description

Synopsis: the Simple Development Library program declaration.

Keywords: program, declaration and command line.

1.1 Overview

This package provides a way to declare programs in an homogeneous, easily parseable, fully introspectable way. It allows to substitute the comment block which is usually placed at the beginning of each program file by Tcl-handled text.

Programs are declared with a single command (declare-program). Every single component needed to either make the program work (such as the program options) or to document it (metadata, such as the program synopsis) is provided as arguments to that command. Components can be fully introspected, but metadata is only available if The Simple Development Library -storemetadata option is set when the program is declared.

Procedures are provided to declare a program, get information about the program, parse the program command line and exit the program execution.

1.2 Usage

Use declare-program to declare a program. The declared program metadata given to declare-program (or composed from other data, if not given, as for --help) can be obtained via the ::Simple::Program::information metadata procedure. Other subcommands of this procedure provide information about a declared program: name, version, requisites, synopsis, help, examples, options, errors, variables, types and commands.

Use ::Simple::Program::parse-command-line to parse the program command line arguments and ::Simple::Program::die to display an error and exit.

There is a backdoor implemented which allows to display the error stack trace held in errorInfo upon an uncatched error in the program execution: give the --errorinfo option as a command line argument.

1.3 Examples

# Install the package
package require SimpleDevLibProgram 1.0

# For this example we substitute the ||exit|| command by ||return|| so that
# we can provide some hard-coded command lines below
interp alias {} exit {} return

# Declare the program
declare-program {
   foo
} -version {
   3.1
} -synopsis {

   Example program

} -option {
   {-p --processing} -type choice -choices {A B C} -description {processing option}
} -option {
   {-v --verbosity} -name verbosity -type integer -range -1:4 -description {set the verbosity level}
} -option {
   {-w --width} -name width -type integer -default 80 -description {set the width of the output}
} -option {
   {-a --all} -type boolflag -description {process all files}
} -option {
   -- -name files -type string -values 3: -description {files to process}
} -optionsusage {
   -p {O -v} {O -w} {X -a --}
} -examples {

   * To process all files in mode A:
      foo -p A --all

   * To process files "bar" and "gee" in mode B in a 132 columns display:
      foo -p B -w 132 bar gee

   * To process files "bar" and "gee" in verbose mode C:
      foo -p C -v 4 bar

} -requisites {
   {Tcl 8}
} -command {
   {
      program-command

   } -synopsis {

      Example of program command

   } -body {
      puts {Program command}
   }

} -body {

   # Parse the command line here using the following line:
   # ::Simple::Program::parse-command-line $argv

   # Here use ||::Simple::Option::information available||,
   # ||::Simple::Option::information given|| and
   # ||::Simple::Option::information value|| to access the command line
   # arguments
}

# This displays the following:
#   |Usage: foo -p choice [-v verbosity] [-w width] (-a | files(3:)) 
#   |       foo --help 
#   |       foo --version
#   |       foo --examples
#   |
#   |Example program
#   |
#   |   -p, --processing           processing option (A, B or C)
#   |   -v, --verbosity VERBOSITY  set the verbosity level
#   |   -w, --width WIDTH          set the width of the output (default 80)
#   |   -a, --all                  process all files
#   |   files                      files to process
#   |       --help                 display this help and exit
#   |       --version              output version information and exit
#   |       --examples             display some usage examples and exit
::Simple::Program::parse-command-line --help

# This displays the following:
#   |foo 3.1
::Simple::Program::parse-command-line --version

# This displays the following:
#   |Example program
#   |
#   |      * To process all files in mode A:
#   |         foo -p A --all
#   |
#   |      * To process files "bar" and "gee" in mode B in a 132 columns display:
#   |         foo -p B -w 132 bar gee
#   |
#   |      * To process files "bar" and "gee" in verbose mode C:
#   |         foo -p C -v 4 bar
::Simple::Program::parse-command-line --examples

# This displays the following:
#   |foo: "-p" (or "--processing") required
#   |Try "foo --help" for more information.
::Simple::Program::parse-command-line {-w 132 -a}

# This displays the following:
#   |foo: invalid value "D" for option "-p" of type "choice": must be
#   |   A, B or C
#   |Try "foo --help" for more information.
::Simple::Program::parse-command-line {-p D -a}

# This displays the following:
#   |foo: invalid value "foo" for option "-w" of type "integer"
#   |Try "foo --help" for more information.
::Simple::Program::parse-command-line {-p A -w foo -a}

# This displays the following:
#   |foo: one of "-a" (or "--all") or "files" required
#   |Try "foo --help" for more information.
::Simple::Program::parse-command-line {-p A}

# This displays the following:
#   |foo: too few values, 3: files required, got 2
#   |Try "foo --help" for more information.
::Simple::Program::parse-command-line {-p A file1 file2}

# This displays the following:
#   |foo: too few values, 3: files required, got 2
#   |Try "foo --help" for more information.
::Simple::Program::parse-command-line {-p A file1 file2}

# This displays the following:
#   |foo: invalid value "7" for option "-v": value out of range "-1:4"
#   |Try "foo --help" for more information.
::Simple::Program::parse-command-line {-p A -v 7 -a}

# A valid command line
::Simple::Program::parse-command-line {-p A -v 3 -a}

1.4 History

1.5 Copyright

Copyright (C) 1999-2005, Juan C. Gil (jgil@gmv.es).

2. Package public API

Paradigm: procedural.

Requisites: SimpleOption 1.0.

2.1 Types

None.

2.2 Options

None.

2.3 Namespaces

1. ::Simple::Program

2. ::Simple::Program::Priv

2.4 Commands

2.4.1 ::Simple::Program::cget

Synopsis: gets the package options.

Details: see section 4.1.

2.4.2 ::Simple::Program::configure

Synopsis: configures the package options.

Details: see section 4.2.

2.4.3 declare-program program ?-version version? ?-project string? ?-synopsis string? ?-overview string? ?-usage string? ?-exitstatus string? ?-help string? ?-keywords list? ?-examples string? ?-error declaration? ?-type declaration? ?-variable declaration? ?-command declaration? ?-option declaration? ?-optionsusage list? ?-requisites packagerequisite-list? ?-assumptions string? ?-resources string? ?-limitations string? ?-details string? ?-references string? ?-remarks string? ?-todo string? ?-cmid string? ?-sprs string? ?-smrs string? ?-history string? ?-copyright string? ?-body script?

Synopsis: declares a program.

Details: see section 4.3.

2.4.4 ::Simple::Program::die ?-trymessage? message ?status?

Synopsis: displays an error message and exits unssuccessfully.

Details: see section 4.4.

2.4.5 ::Simple::Program::information commands

Synopsis: returns the program commands.

Details: see section 4.5.

2.4.6 ::Simple::Program::information errors

Synopsis: returns the program errors.

Details: see section 4.6.

2.4.7 ::Simple::Program::information examples

Synopsis: returns the program examples.

Details: see section 4.7.

2.4.8 ::Simple::Program::information help

Synopsis: returns the program help message.

Details: see section 4.8.

2.4.9 ::Simple::Program::information metadata

Synopsis: returns the program metadata.

Details: see section 4.9.

2.4.10 ::Simple::Program::information name

Synopsis: returns the program name.

Details: see section 4.10.

2.4.11 ::Simple::Program::information options

Synopsis: returns the program options.

Details: see section 4.11.

2.4.12 ::Simple::Program::information requisites

Synopsis: returns the program requisites.

Details: see section 4.12.

2.4.13 ::Simple::Program::information synopsis

Synopsis: returns the program synopsis.

Details: see section 4.13.

2.4.14 ::Simple::Program::information types

Synopsis: returns the program types.

Details: see section 4.14.

2.4.15 ::Simple::Program::information variables

Synopsis: returns the program variables.

Details: see section 4.15.

2.4.16 ::Simple::Program::information version

Synopsis: returns the program version.

Details: see section 4.16.

2.4.17 ::Simple::Program::parse-command-line commandLine

Synopsis: parses a program command line.

Details: see section 4.17.

2.5 Errors

None.

3. Package further information

None.

4. Package command details

4.1 ::Simple::Program::cget

4.1.1 Command description

Synopsis: gets the package options.

Access mode: public.

4.1.2 Command public API

Arguments: none.

Returns: the requested option value or the whole list of options if none specified.

4.2 ::Simple::Program::configure

4.2.1 Command description

Synopsis: configures the package options.

Access mode: public.

4.2.2 Command public API

Arguments: none.

Returns: the "package with no options" error is thrown.

4.3 declare-program program ?-version version? ?-project string? ?-synopsis string? ?-overview string? ?-usage string? ?-exitstatus string? ?-help string? ?-keywords list? ?-examples string? ?-error declaration? ?-type declaration? ?-variable declaration? ?-command declaration? ?-option declaration? ?-optionsusage list? ?-requisites packagerequisite-list? ?-assumptions string? ?-resources string? ?-limitations string? ?-details string? ?-references string? ?-remarks string? ?-todo string? ?-cmid string? ?-sprs string? ?-smrs string? ?-history string? ?-copyright string? ?-body script?

(Alias for ::Simple::Program::declare).

4.3.1 Command description

Synopsis: declares a program.

Access mode: public.

4.3.1.1 Overview

This procedure provides a way to declare a program. This procedure can be invoked just once.

The -synopsis flag is mandatory.

The -option flag allows to declare the program command line options. Its argument is an option declaration intended to be the arguments of a call to the ::Simple::Option::declare procedure. This flag can be given multiple times. The command line options actually accepted by the program include those plus --help, --version and --examples (as well as the backdoor option --errorinfo); see the ::Simple::Program::parse-command-line procedure.

If -optionsusage is given, the options usage is declared via the ::Simple::Option::declare-usage procedure.

If -requisites is given, the program requisites are required and installed via the ::Simple::Package::require-and-install procedure.

If -help is given, its argument is the help message displayed when invoking the program with the --help option, after substituting the %USAGE%, %SYNOPSIS% and %OPTIONS% strings by the program usage, the program synopsis or the detailed options explanation, respectively. Otherwise the help message is composed from the synopsis and options information.

The -command flag allows to declare program commands. Its argument is a command declaration intended to be the arguments of a call to ::Simple::Declare::declare-proc. This flag can be given multiple times. Program commands are intended as helper procedures for the program. In principle, program commands should live in the global namespace, but this is currently not enforced.

The -error flag allows to declare program errors. Its argument is an error declaration intended to be the arguments of a call to ::Simple::Error::declare. This flag can be given multiple times.

The -type flag allows to declare program types. Its argument is a type declaration intended to be the arguments of a call to ::Simple::Type::declare. This flag can be given multiple times.

The -variable flag allows to create program variables. Its argument is a variable declaration intended to be the arguments of a call to ::Simple::Variable::declare. This flag can be given multiple times.

It is not allowed to declare program classes. Place the classes in a package and require that package instead.

The mandatory -body flag specifies the program body script. This script is evaluated in the global scope. If there is an error in the evaluation, ::Simple::Program::die is invoked with the error message as argument. Otherwise, the program exits with exit status equal to zero. If other exit status and/or other behaviour is needed, use either exit or ::Simple::Program::die in the program body script. Notice that -exitstatus is just a documentation flag.

All other arguments are metadata, and are stored or ignored depending on whether The Simple Development Library -storemetadata option is set when the program is declared, but for the -body flag which is never stored.

4.3.2 Command public API

Arguments: (flag parsing disabled)

Returns: the empty string.

Effects:

• Requires the required packages.

• Those of the program body.

4.3.3 Command further information

4.3.3.1 Remarks

• The order of the flags is irrelevant but their parameters can not start by an hyphen.

4.4 ::Simple::Program::die ?-trymessage? message ?status?

4.4.1 Command description

Synopsis: displays an error message and exits unssuccessfully.

Access mode: public.

4.4.1.1 Overview

This procedure displays an error message in the standard error channel and exists the program. If the -trymessage flag is given, the try message ("Try <program name --help> for more information") is also displayed.

4.4.2 Command public API

Arguments:

Returns: none; the program is finished.

Effects:

• Finishes the program execution.

4.5 ::Simple::Program::information commands

4.5.1 Command description

Synopsis: returns the program commands.

Access mode: public.

4.5.2 Command public API

Arguments: none.

Returns: the program commands.

4.6 ::Simple::Program::information errors

4.6.1 Command description

Synopsis: returns the program errors.

Access mode: public.

4.6.2 Command public API

Arguments: none.

Returns: the program errors.

4.7 ::Simple::Program::information examples

4.7.1 Command description

Synopsis: returns the program examples.

Access mode: public.

4.7.2 Command public API

Arguments: none.

Returns: the program examples.

4.8 ::Simple::Program::information help

4.8.1 Command description

Synopsis: returns the program help message.

Access mode: public.

4.8.2 Command public API

Arguments: none.

Returns: the program help message .

4.9 ::Simple::Program::information metadata

4.9.1 Command description

Synopsis: returns the program metadata.

Access mode: public.

4.9.1.1 Overview

This procedure returns a list of pairs suitable to be given as argument to the array set command. Each element is one of the flags given to declare-program upon program declaration (with no hypen), but for -body (which is not stored), the item declarations (-error, -type, -variable, -command and -option; these are obtained using the corresponding ::Simple::Program::information subcommand), the -optionsusage flag (use ::Simple::Option::information usage to get this one) and -version, -synopsis, -help, -examples, -requisites and -name for which specific ::Simple::Program::information subcommands exists.

Thus, the actual list of flags is: -project, -overview, -usage, -exitstatus, -keywords, -assumptions, -resources, -limitations, -details, -references, -remarks, -todo, -cmid, -sprs, -smrs, -history and -copyright.

Notice that no data is returned unless The Simple Development Library -storemetadata option is set when the program was declared.

If a particular flag was not given in the program declaration, the empty string is returned as that flag contents.

4.9.2 Command public API

Arguments: none.

Returns: the program metadata as an item/contents pairs list.

4.10 ::Simple::Program::information name

4.10.1 Command description

Synopsis: returns the program name.

Access mode: public.

4.10.2 Command public API

Arguments: none.

Returns: the program name.

4.11 ::Simple::Program::information options

4.11.1 Command description

Synopsis: returns the program options.

Access mode: public.

4.11.2 Command public API

Arguments: none.

Returns: the program options.

4.12 ::Simple::Program::information requisites

4.12.1 Command description

Synopsis: returns the program requisites.

Access mode: public.

4.12.2 Command public API

Arguments: none.

Returns: the program requisites.

4.13 ::Simple::Program::information synopsis

4.13.1 Command description

Synopsis: returns the program synopsis.

Access mode: public.

4.13.2 Command public API

Arguments: none.

Returns: the program synopsis.

4.14 ::Simple::Program::information types

4.14.1 Command description

Synopsis: returns the program types.

Access mode: public.

4.14.2 Command public API

Arguments: none.

Returns: the program types.

4.15 ::Simple::Program::information variables

4.15.1 Command description

Synopsis: returns the program variables.

Access mode: public.

4.15.2 Command public API

Arguments: none.

Returns: the program variables.

4.16 ::Simple::Program::information version

4.16.1 Command description

Synopsis: returns the program version.

Access mode: public.

4.16.2 Command public API

Arguments: none.

Returns: the program version.

4.17 ::Simple::Program::parse-command-line commandLine

4.17.1 Command description

Synopsis: parses a program command line.

Access mode: public.

4.17.1.1 Overview

This procedure is similar to the ::Simple::Option::parse procedure in that it parses the program command line and assesses its compliance against the program options and their usage. If an error is found when parsing the command line, a suitable diagnostics is displayed in the standard error channel together with a message sugesting the use of the --help option, and the program exits.

On top of the program options given as parameter to the -option flag in the call to declare-program, this procedure also accepts the --help, --version, --examples and --errorinfo command line options:

--help

Displays the help message and exits.

--version

Displays the program version and exits.

--examples

Displays the program examples and exits.

--errorinfo

Displays the error stack trace held in errorInfo upon an uncatched error and exists.

4.17.2 Command public API

Arguments:

Returns: the empty string.

Effects:

• May finish the program execution.

4.17.3 Command further information

4.17.3.1 References

• The ::Simple::Option::parse procedure.