Sather Home Page

Section 8.10.3.1:
PROGRAM_ARGS

class PROGRAM_ARGS

Formal Types

The type definitions in this class specification fall into two groups :-

  1. The definition of PROGRAM_ARGS itself (including SAME).
  2. The auxiliary vdm type needed to define a generic Sather type used in the feature definitions which follow.
types

SAME = PROGRAM_ARGS ;
PROGRAM_ARGS = token ; -- token is used as the type is opaque

-- Auxiliary type

Option_Type = CARD | FIELD | INT | RAT | FLT | CPX | MONEY | BOOL | STR

This class provides the facility to handle arbitrary program arguments in unix-style format. Program options may be made available either as the traditional Unix-style argument 'pack' or as a single string (provided, for example under DOS) or as the contents of some named file or some combination of these.

Argument Concrete Syntax

However the arguments to a program may be passed to it, they should conform to the concrete syntax defined in this sub-section. It should be noted that since arguments come from the program run-time environment their encoding and repertoire are necessarily those of the default culture.

Argument :=
Option | Program Argument ;

Option :=
Option delimiter, Option name, [White Space, Option value] ;
Option Delimiter :=
Minus symbol | Plus symbol ;
Option name :=
Identifier ;
Option value :=
Number | Truth value | Value string ;
Number :=
Whole number | Approximate number | Complex number | Rational number | Monetary value ;
Truth value :=
True symbol | False symbol ;
Value string :=
Quoted string | No Space string ;
Quoted string :=
Quote symbol, {Encoding *}, Quote symbol ;
Program argument :=
No Space string ;
NOTE 1. All symbols are arbitrary bit-sequences determined from the default program argument mapping parameter file when the argument class is first created.
2. There may be an arbitrary number of alternative quote symbols, the only restriction being that the encoding which is detected at the beginning of a quoted string must be the same as used at the end - and must not, of course, appear anywhere within the bit-stream of the string value itself.
3. Numeric values are presumed to begin with an encoding which is not a quote symbol, white space or option delimiter and is also not permitted as the first encoding in an identifier. Otherwise there are no restrictions on the encodings.

Argument Handling

After creation of an object any number of program parameters may be specifed in terms of their name and the function which is to be associated with it which is to be called when the name is recognised during argument reading.

Argument handlers must be closures of type ROUT{$OPTION}. As defined in this specification, there are options - CARD, FIELD, BOOL, INT, RAT, CPX, MONEY and STR. The facility for using a handler which receives an unquoted string is intended to permit handlers to take enumeration names as string value.

Reader Routines

The following reader routines should be void until after arguments have been read -


create

create (
lib : LIBCHARS
) : SAME
Formal Signature
create(lib : LIBCHARS) res : SAME
Pre-condition

Since this is a creation routine, the pre-condition is vacuously true.

Post-condition

Since this is a creation routine, the post-condition also is vacuously true.

This creation routine sets up a void program name and an empty list of arguments for a new object in the given culture and returns the object created.


create

This creation routine also produces an initially empty object, but uses the default encoding and repertoire.

create : SAME
Formal Signature
create2() res : SAME
Pre-condition

Since this is a creation routine, the pre-condition is vacuously true.

Post-condition

Since this is a creation routine, the post-condition also is vacuously true.

This creation routine sets up a void program name and an empty list of arguments using the default culture encoding and repertoire.


add_option

This routine provides the facility to associate handlers with program options - which is to be done before reading the options using one or more of the read variants following.

add_option (
name : STR,
func : ROUT{$OPTION},
has_val : BOOL
)
Formal Signature
add_handler(self : SAME, name : STR, func : Option_Type ==> (), has_val : BOOL)
Pre-condition
pre len name > 0
and let loc_op(arg : Option_Type) = func in
is_bool(arg)
or has_val
Post-condition

The addition of a handler always happens successfully by definition, thus the post-condition is inevitably true.

This routine adds a new option name with an associated handler to the object. Note, however, the pre-condition.


delete_option

Should it be necessary to delete one or more options this routine provides the facility to do so.

delete_option (
name : STR
)
Formal Signature
delete_option(self : SAME, str : STR)
Pre-condition

Since the contents of the string argument is arbitrary, the pre-condition is true.

pre true
Post-condition

If the string argument was the name of an option then it has been deleted. If the string argument was not the name of an option then the resulting state is as if it had been deleted. The post-condition is therefore true.

post true

This routine deletes an option with the given name. It shall not be an error if the name did not exist.


read

This first argument reading feature looks to find arguments in a file with the given access path.

read (
filename : FILE_PATH
) : BOOL
Formal Signature
read(self : SAME, path : FILE_PATH) res : BOOL
Pre-condition
pre let dir = DIRECTORY.existent(FILE_PATH.head(path)) in
(dir <> nil)
and DIRECTORY.exists(dir, FILE_PATH.leaf(path))
Post-condition

Should false be returned then the standard error channel has had some appropriate error message sent to it.

post res
or let msg : seq of CHAR be st len msg > 0 in
ERR = ERR~ ^ msg

This routine reads the program options and arguments from the file indicated, returning true if this has been done successfully, otherwise false.


read

This routine offers the facility to read arguments from an already open text file.

read (
fyle : TEXT_FILE
) : BOOL
Formal Signature
read2(self : SAME, fyle : TEXT_FILE) res : BOOL
Pre-condition
pre TEXT_FILE.is_open(fyle)
Post-condition

Should false be returned then the standard error channel has had some appropriate error message sent to it.

post post res
or let msg : seq of CHAR be st len msg > 0 in
ERR = ERR~ ^ msg

This routine reads the file provided for options and arguments, returning true if and only if there have been no reported errors.


read

This third variant if argument reading is provided for the case where arguments have been put into an arbitrary text string.

read
string : STR
) : BOOL
Formal Signature
read3(self : SAME, str : STR) res : BOOL
Pre-condition
pre len str > 0
Post-condition

Should false be returned then the standard error channel has had some appropriate error message sent to it.

post res
or let msg : seq of CHAR be st len msg > 0 in
ERR = ERR~ ^ msg

This routine treats the given string as a list of options and arguments, reading them and returning true if and only if successful.


read

This final version handles command line arguments presented in the unix-style. It is important to note that this variant is the only one which can set the program name!

read (
argv : ARRAY{STR}
) : BOOL
Formal Signature
read4(self : SAME, argv : seq of STR) res : BOOL
Pre-condition
pre len argv > 0
and len argv(1) > 0
Post-condition

Should false be returned then the standard error channel has had some appropriate error message sent to it.

post (res
and len progname > 0)
or let msg : seq of CHAR be st len msg > 0 in
ERR = ERR~ ^ msg

This routine handles the command line option/argument string case - the first item in the array being taken as the program name. True is only returned if and only if there have been no reported errors.


Language Index Library Index Input/Output Index
Comments or enquiries should be made to Keith Hopper.
Page last modified: Tuesday, 21 November 2000.
Produced with Amaya