DEFINITION MODULE Arguments;

(*
    Title: 	Decodes arguments from a command line
    LastEdit:	"Fri Apr 26 11:07:27 1985"
    Author: 	jd
		Cambridge University Computer Laboratory
*)

(*  This module can be used to decode arguments from a stream according
    a given pattern. It can be used on any stream which can Seek and Tell
    between consecutive NewLineCh's, and in particular can be used by the
    PROCs which are dispatched by the module "dispatch".
    
    Arguments sets up a parameter pattern (described below) which must match
    the given arguments. If it does, then the procedures CardArg, IntArg,
    RealArg and StringArg can be used to find the argument value if it 
    was given.
 *)

FROM Streams IMPORT Stream;

EXPORT QUALIFIED
    Arguments, Present,
    CardArg, IntArg, RealArg, StringArg;


PROCEDURE Arguments (in, out: Stream; format: ARRAY OF CHAR): BOOLEAN;
        (* sets up a format string to be used in command decoding. A return
           of FALSE indicates that the arguments cannot be mapped onto the
           format, and the command should probably be abandoned. 
           
           If the first item in the stream is '?', then
           Arguments displays the requested format and returns FALSE.
           
           The format string is a sequence of keywords, optionally qualified,PROCEDURE 
           and separated by commas. Each keyword matches a single argument,
           delimited either by spaces or double quotes ("). The case of
           keywords is significant. The argument is separated from the
           keyword by spaces or an equals sign. A sequence of keyword
           qualifiers may immediately follow the keyword, and have the
           following meanings independent of  case:
           
           /s   switch, taking no argument
           /m   the argument is mandatory
           /k   if the argument is present, the keyword must also be given
           
       *)

(* In the following procedures, arguments are specified by an index into
   the format string which was presented to Arguments, and are numbered
   from 1. Thus in "from,to/k,with/k/s", 'to'  would correspond to arg 2
*)

PROCEDURE Present (arg: CARDINAL): BOOLEAN;
        (* returns TRUE if the argument was given a value *)

(* If the following procedures are called on an argument which is a switch,
   or if the argument is not Present, then no change is made to their
   VAR argument, so a default value may be set before the call. Interpretation
   of the argument stops at the first unexpected character, as in the 
   BFormatIO procedures ReadCard, ReadInt, ReadReal.
*)

PROCEDURE CardArg (arg: CARDINAL; VAR c: CARDINAL);

PROCEDURE IntArg (arg: CARDINAL; VAR i: INTEGER);

PROCEDURE RealArg (arg: CARDINAL; VAR r: REAL);

PROCEDURE StringArg (arg: CARDINAL; VAR s: ARRAY OF CHAR): CARDINAL;
        (* strips the optional double quotes surrounding the argument, and
           returns the length of the string.
        *)


END Arguments.
