ci (prompt,file,depth,list,helppath,cmdfpath);
char *prompt,*helppath,*cmdfpath;
FILE *file;
int depth;
CIENTRY *list;
Ci has a basic loop which consists of printing the string prompt, reading a line from its current input file, and executing the specified instructions. The format and meaning of these instructions is as follows:
Several instructions may appear on the same line, separated by semicolons. In addition, ci allows abbreviation of command names, variable names, and help topics to any unique prefix.
File is the file to be used for input. Normally, the standard input (stdin) is used; if you specify 0, ci will assume you are using the standard input.
Depth is used for indenting the prompt; this should usually be 0 when you execute ci, but, when it calls itself recursively for command files, this will be non-zero.
List is an array of the entry descriptors for commands and variables; you declare this to be of type CIENTRY (see below), and use the macros described below to describe the entries.
Helppath is a list of directories containing help files, separated by colons. If you specify a single directory, that's fine; ci will assume all help files lie in that directory. When the user asks for help on some topic, ci looks for a file in one of the help directories which has a matching name. The contents of the file will simply be typed out to the user. If you specify 0 for helppath, ci will assume that no help files exist.
Cmdfpath is a list of directories containing command files, separated by colons. This is useful for libraries of prepared command files. The current directory should be included in the list; this is best done by indicating a null directory name (i.e. a colon as the first character of the path, or two consecutive colons within the path). If you specify 0 (which you will probably do most of the time), ci will assume that all command file names are evaluated with respect to the current directory only. Absolute pathnames, of course, are always valid.
CIENTRY list[] = {
CIINT(...),
CIDOUBLE(...),
CICMD(...),
...
CIEND
};
The macros which define entries are described below.
mycommand (arglist)
char *arglist;
{
char *p; /* recommended for parsing */
int arg1,arg2;
p = arglist;
arg1 = intarg (&p,0,...); /* see intarg(3) */
arg2 = intarg (&p,0,...);
...
}
...
CIENTRY list[] =
{
...
CICMD ("munch",mycommand),
...
CIEND
};
The user can then type "munch 3 4", and myproc will be executed with arglist equal to "3 4". The parsing sequence shown above (using intarg(3)), will assign 3 to arg1 and 4 to arg2. If the user were to type "munch" with no arguments, he would be prompted for arg1 and arg2 as described in intarg(3).
Here is an example of two variables and how they might be used:
int i;
char s[100];
...
CIENTRY list[] =
{
CIINT ("number",i),
CISTRING ("string",s),
...
CIEND
};
Here is an excerpt of a dialogue with the program containing the above statements (lines typed by the user are indicated by italics):
n=3
number 3
s=Hello, mom!
string Hello, mom!
nu
number 3
num=4
number 4
*=
number 4
string Hello, mom!
To use a clustered variable involves two steps: you must declare the variable itself, together with its description; and you must insert the proper declaration into the CIENTRY list.
To declare a clustered "int" variable, use this macro:
CINT (sname, vname, min, max, "prompt");
This macro appears just like any other declaration, but must be
outside of any procedures (i.e.
global).
It will create
an int variable called
vname,
which you may refer to in other parts of your program; it also
declares a structure called
sname
which contains the description of
vname.
The description consists of three values:
min,
the minimum allowable value for
vname;
max,
the maximum allowed value; and
prompt,
the prompt string for assigning a value to
vname.
The corresponding entry of the CIENTRY list would be:
CICINT ("name", sname)
where
sname
is the same as
sname
in the CINT macro.
A clustered variable differs from a simple variable in two ways. When a user tries to assign a value to a clustered variable, the new value is checked for legality. If it is legal, it is assigned; otherwise, a message is printed and the user can type another value. Also, the user may type "name=", omitting the value, and will be prompted for the value to be assigned.
Here are the clustered types known to ci:
Here is an example using two clustered variables:
CINT (si, i, 1, 10, "What's your favorite number?");
CSTRING (sname, name, 100, "What's your name?");
...
CIENTRY list[] =
{
CICINT ("favorite",si),
CICSTRING ("name",sname),
...
CEND
}
This might be part of a dialogue with the program containing the above declarations (lines typed by the user are indicated in italics):
fav=7
favorite 7
name=Humpty Dumpty
name Humpty Dumpty
fav=32
32 out of range. What's your favorite number? (1 to 10) [7] 4
favorite 4
f=
What's your favorite number? (1 to 10) [4] 8
favorite 8
name=
What's your name? [Humpty Dumpty] Minnie Mouse
name Minnie Mouse
*=
favorite 8
name Minnie Mouse
Most users, for most programs, will find clustered variables to be preferable to simple variables.
There is, however, a catch. You have to write the procedure that manipulates the variable.
This type of variable is called a procedure variable. It consists of a procedure which you must provide, and an entry on the CIENTRY list which looks like this:
CIPROC ("name", procname)
where
procname
is the name of your procedure.
Your procedure will be called with two parameters:
proc (mode,arglist)
CIMODE mode;
char *arglist;
The first parameter,
mode,
indicates what
ci
is trying to do; the second,
arglist
is the list of parameters and values typed by the user.
The mode parameter may have one of three values:
Typically, the procedure will use a switch statement to deal with the three cases. If the value can be displayed by printing it on one line, the CISET and CIPEEK cases may be the same. This is true, for example, for an ordered pair of integers; it is not true, say, for a variable which represents a color picture (to display this may involve writing it onto a color TV monitor).
Here is an example of a procedure variable which represents an ordered pair:
int x,y;
...
xy (mode,arg)
CIMODE mode;
char *arg;
{
char *p; /* for parsing */
switch (mode) {
case CISET:
p = arg;
x = intarg (&p,0,"X coordinate?",-100,100,x);
y = intarg (&p,0,"Y coordinate?",-100,100,y);
/* now, fall through to display the value */
case CISHOW:
case CIPEEK:
printf ("point\t\tx %d\ty %d\n",x,y);
}
}
...
CIENTRY list[] =
{
CIPROC ("point",xy),
...
CIEND
}
Here is an example of dialogue with the program containing the above code (lines typed by the user are indicated by italics):
point=3 5
point x 3 y 5
p=
X coordinate? (-100 to 100) [3] 72
Y coordinate? (-100 to 100) [5] 39
point x 72 y 39
p= 287
287 out of range. X coordinate? (-100 to 100) [72] 28
Y coordinate? (-100 to 100) [39] 29
point x 28 y 29
p
point x 28 y 29
Note that some kinds of variables may require parameters just to be displayed; you will receive a (possibly null) argument list every time your procedure variable is called, and may parse arguments for all three activities specified by mode.
A class is a collection of procedure variables which share the same code. Each variable, however, is distinguished by its own data. The entries on the CIENTRY list look like this:
CICLASS ("name1",var1,classname),
CICLASS ("name2",var2,classname),
and so on, one entry for each variable.
Var1
and
var2
are the names of the data areas for the variables; they might be
declared like this:
typedef struct { int field1; ... } DATAAREA;
DATAAREA var1, var2;
Classname
is the name of the procedure which is used by these variables for
displaying and assigning a value.
The procedure will be called with four parameters. Continuing the above example, the procedure might begin like this:
classname (mode,arglist,varptr,varname)
CIMODE mode;
char *arglist, *varptr, *varname;
{
DATAAREA *p;
. . .
p = (DATAAREA *) varptr;
. . . p->field1 . . .
In this example, note that the first two parameters are just the same
as the first two parameters for a procedure variable.
They have
exactly the same meaning.
The third parameter is a pointer to the
data area for the variable being displayed or assigned to.
This value
must be of type "char *" for C's type-checking to work properly, so
you will want to coerce it by a type-cast to be a pointer to the proper
type.
Note also that
var1
and
var2
are DATAAREAs, not (DATAAREA *)s.
In general, whatever type of object
you declare in the CICLASS macro, the parameter passed to the procedure
will be a pointer to that type of object.
The fourth (last) parameter passed to the procedure will be the
name of the variable being processed, in a character string.
Here is an example of two ordered pairs represented by two class variables:
typedef struct {int x,y;} ORDPAIR;
ORDPAIR startp,endp;
...
ordproc (mode,arg,cdata,name)
CIMODE mode;
char *arg, *cdata, *name;
{
char *p;
ORDPAIR *data;
data = (ORDPAIR *) cdata;
switch (mode) {
case CISET:
p = arg;
data->x = intarg (&p,0,"X coordinate?",-100,100,data->x);
data->y = intarg (&p,0,"Y coordinate?",-100,100,data->y);
case CISHOW:
case CIPEEK:
printf ("%s\t\tx %d\ty %d\n",name,data->x,data->y);
}
}
...
CIENTRY list[] =
{
CICLASS ("start",startp,ordproc),
CICLASS ("end",endp,ordproc),
...
CIEND
}
Here is an example of dialogue with the program containing the above code (lines typed by the user are indicated by italics):
start = 3 5
start x 3 y 5
end = 6 10
end x 6 y 10
start =
X coordinate? (-100 to 100) [3] 72
Y coordinate? (-100 to 100) [5] 39
start x 72 y 39
If the interrupt occurred while ci was reading from the standard input, it will just print "Interrupt ignored".
If, however, the interrupt occurred during a command file, ci will print:
INTERRUPT: Abort or breakpoint? [abort]and wait for you to type something. If you type "a", or "abort", or just a carriage return, ci will abort the command file (i.e. pretend it just encountered the end of the file). If you type "b", or "breakpoint", or something like that, then ci will recursively call itself, with the new ci taking input from the standard input (e.g. terminal). The prompt will be "Breakpoint for prompt", where prompt is the prompt for the interrupted command file. When you exit from the new ci, the command file will be resumed as if nothing had happened.
The bits for ciquiet are also declared in the macro file. If a bit is 0, the output will be produced; if it is 1, the output is suppressed:
Certain bits in ciquiet control the processing of input rather than output. If these bits are 0, all special input symbols are processed; if 1, the corresponding special input character is treated just like ordinary data with no special meaning to ci: