Critical Mass Modula-3: m3tk-misc/src/M3Args.i3

m3tk-misc/src/M3Args.i3

************************************************************************* Copyright (C) Olivetti 1989 All Rights reserved Use and copy of this software and preparation of derivative works based upon this software are permitted to any person, provided this same copyright notice and the following Olivetti warranty disclaimer are included in any copy of the software or any modification thereof or derivative work therefrom made by any person. This software is made available AS IS and Olivetti disclaims all warranties with respect to this software, whether expressed or implied under any law, including all implied warranties of merchantibility and fitness for any purpose. In no event shall Olivetti be liable for any damages whatsoever resulting from loss of use, data or profits or otherwise arising out of or in connection with the use or performance of this software. ************************************************************************* Copyright (C) 1992, Digital Equipment Corporation All rights reserved. See the file COPYRIGHT for a full description.

INTERFACE M3Args;

This package provides argument decoding and help support for tools that operate in either a Unix style command line environment, or in a window based environment. In particular, several tools can coexist in a single program.

TYPE
  T <: REFANY;  (* tool handle *)

  Opt = {Optional, Required, Positional};

PROCEDURE New(
    toolName, toolDescription, version: TEXT;
    master := FALSE;
    ): T RAISES {};

Register a new tool, returning a handle for later use

toolName is a short name for the tool, for example, m3c. It will used to prefix any messages generated by other calls. toolDescription is a longer explanation that is output when help is requested, e.g. Modula-3 Compiler Front End. version is the version of the tool. All of these arguments are required to be non-empty TEXTs. master indicates whether this is the master (or controlling) tool. The master tool information will always be displayed first in the help output. It is a checked run-time error if a tool named toolName has already been created.

PROCEDURE SetMaster(t: T): T RAISES {};

Set t to be the master tool, returning the previous master, if any, else NIL.

The following three procedures register keyword arguments with a tool. The values associated with a keyword take one of three types: a flag (boolean), a single string or a a sequence of strings. usage is displayed in response to a request for help. If opt = Required, it is an error for the argument to be unset, and this will cause Find to return FALSE. Flag keywords are always optional; their omission is equivalent to a value of FALSE. The Positional setting, which also imples Optional, is only relevant to a command line implementation, in which case, this and only this argument can be supplies without the keyword. Keywords are assigned {\it short forms} by concatenating all the upper-case letters in argName from left to right. So the short form of PrintUnit would be pu. Numerics are not included in short-forms, so the the short-form of LM3Check would be lmc. For any tool, all it's keyword names and their short forms must be unique. In addition, an implementation, for example based on a commmand line, may require that the keywords be unique across all the registered tools. A keyword may be denoted as {\it shared} by setting shared = TRUE, in which case the same value will be propagated to all tools. If duplicates are not allowed and shared = FALSE, a duplicate will cause a checked runtime error will occur. Prefix keywords are somewhat like flags; any keyword that begins with argName will match but, since there may be several such matches, the Get/Set procedures return/takes text arrays like RegisterStringList. Prefix arguments support the -Idir idiom beloved by some tools.

Clients of this interface can update the keyword argument values directly by the calls SetFlag, SetString, SetStringList and SetPrefix. In addition from time to time values may be transferred from the outside, for example a dialog box, by a daemon. The Find call is guaranteed to force the transfer, so it is required that each tool call this procedure before accessing values. All calls are atomic with respect to the daemon.

PROCEDURE RegisterFlag(
    t: T;
    argName: TEXT;
    usage: TEXT;
    shared := FALSE);

Register a Flag keyword called argName


PROCEDURE RegisterString(
    t:T;
    argName: TEXT;
    usage: TEXT;
    opt: Opt := Opt.Optional;
    shared := FALSE);

Register a String keyword called argName


PROCEDURE RegisterStringList(
    t:T;
    argName: TEXT;
    usage: TEXT;
    opt: Opt := Opt.Optional;
    shared := FALSE);

Register a StringList keyword called argName


PROCEDURE RegisterPrefix(
    t:T;
    argName: TEXT;
    usage: TEXT;
    opt: Opt := Opt.Optional;
    shared := FALSE);

Register a Prefix keyword called argName

\subsection{Help information}

The way in which help information is requested and displayed is implementation dependent. For example, in a command line implementation, the keyword Help might be reserved for this purpose. The CheckHelp procedure is provided to discover if help has been requested. If so, and display=TRUE, then CheckHelp calls Help(t), for all registered tools, It returns TRUE if help was requested. If display=FALSE the calls on Help(t) are suppressed, which enables a master tool to subvert the normal behaviour.

PROCEDURE Help(t: T; preamble := TRUE) RAISES {};

Give help on tool t, showing the usage text passed to registration procs. If preamble = TRUE, general information on keyword types and short forms is output first.


PROCEDURE CheckHelp(display := TRUE): BOOLEAN RAISES {};

Check for help requested and if display=TRUE, call Help(t) for all t in the set of registered tools.


PROCEDURE HelpPreamble(t: T) RAISES {};

Display the general information on keyword types and short forms.

\subsection{Getting and Setting Argument Values}

Unbound arguments return NIL for String and StringList keywords. The empty string list is denoted by a result r where NUMBER(r) = 0. It is a checked runtime error to provide an argument name that has not been registered.

PROCEDURE Find(t: T): BOOLEAN RAISES {};

Gather the arguments for tool t. This ensures that arguments from the outside are transferred into the tool's maps. The result will be TRUE unless the arguments are incorrect, for example, a missing Required argument.


PROCEDURE GetFlag(t: T; argName: TEXT): BOOLEAN;

Return the value of Flag keyword argName in tool t.


PROCEDURE GetString(t: T; argName: TEXT): TEXT;

Return the value of String keyword argName in tool t.


PROCEDURE GetStringList(t: T; argName: TEXT): REF ARRAY OF TEXT;

Return the value of StringList keyword argName in tool t.


PROCEDURE GetPrefix(t: T; s: TEXT): REF ARRAY OF TEXT;

Return the value of Prefix keyword argName in tool t.


PROCEDURE SetFlag(t: T; argName: TEXT; f: BOOLEAN);

Set the value of Flag keyword argName in tool t to f.


PROCEDURE SetString(t: T; argName: TEXT; val: TEXT);

Set the value of String keyword argName in tool t to val.


PROCEDURE SetStringList(t: T; argName: TEXT; sl: REF ARRAY OF TEXT);

Set the value of StringList keyword argName in tool t to val.


PROCEDURE SetPrefix(t: T; s: TEXT; sl: REF ARRAY OF TEXT);

Set the value of Prefix keyword argName in tool t to val.


PROCEDURE SetStringAsList(t: T; argName: TEXT; val: TEXT);

Takes a comma or space separated string val, breaks it into sub-strings at the boundaries defined by the comma or space characters and sets the value of StringList keyword argName in tool t to rge resulting list of sub-strings.

\subsection{Example}

In the initialisation code for the tool, place a call to New, and record the tool handle. For example:

      MODULE MyTool;
      ..
      BEGIN
        tool_g := M3Args.New("mytool", "My Wonderful Tool", "1.1");
        (* now register argument keywords, e.g. 

|   M3Args.RegisterFlag(tool_g, "PrintUnits",
|        "print name of units as they are compiled");
| END MyTool.

In the action routines of the tool, call "Find" to gather arguments
and then "GetFlag, GetString, GetStringList" as appropriate.

In a main program which includes "MyTool", always start with a call
to "CheckHelp" to ensure that a simple call by the user for help works,
and then go about your business as usual. *)

END M3Args.