CCARD(3) RPN UTILITY CCARD(3)
NAME
ccard, c_ccard - gather and process program arguments.
DESCRIPTION
ccard is a module (a fortran subroutine or a C function) which
provides to a FORTRAN or C program a standard mechanism for the recuperation
and treatment of call-time arguments. With ccard, a call to a program has the
following format:
progname [pos ...] -key1 [val1 ...] -key2 [val2 ...] ... [-- pos ...]
where progname - is the name of the program to call
pos - represents a positional argument
keyi - is a symbolic name or key name
vali - is the value given to a symbolic name
-- - used to indicate that the following parameters are
to be treated as positional arguments.
USAGE
FORTRAN: CALL CCARD(LISTE,DEF,VAL,N,NPOS)
C : void c_ccard();
c_ccard(argv,argc,liste,val,def,n,&npos);
ARGUMENT DEFINITION
FORTRAN: CHARACTER*(*) LISTE(N), DEF(N), VAL(N)
INTEGER N, NPOS
C: char **argv, *liste[n], *def[n], val[n][256];
int argc, n, *npos;
LISTE (INPUT)
Array containing the name of the various keys. By default, the
value assigned to a key will be converted to capital letters. If
a key name is terminated by an underscore (_), the value assigned
to that key will be converted to lower case letters. Ending a
key name with a period (.), will force ccard to leave the value
untouched. These extra characters are used only inside the
program in the LISTE array in order to define the type of
treatment to perform on the value given to a certain key. They
must not appear in a program calling sequence.
With ccard, it is possible to simulate a positional mode of
argument recuperation by using the reserved key name '-' (minus
sign) in LISTE. An argument is said to be positional if it is not
associated to a key name on the command line. (See the example)
VAL (INPUT/OUTPUT)
On input, this array contains the initial values of the various
keys (first default value). On output, the VAL array contains the
final values of the keys. The value of a key is found by first
locating a key name in LISTE and then finding the value in the
corresponding position in the VAL array.
If the name of a key is not present in the argument list, the
initial value contained in VAL will be returned as the final value
for the key. The presence of a key name with no associated value
on the calling card causes ccard to copy the contents of the DEF
array, at the location given by the position of the key name in
LISTE, to the corresponding position in the VAL array. If a key
name is followed by a value, it is the user supplied value that
will be copied to VAL at the appropriate position.
DEF (INPUT)
Array containing the second default value to give to a key. If on
the program calling card the name of a key appears without being
followed by a value, the contents of DEF, at the position given by
the key in LISTE, will be copied to the corresponding position in
the VAL array.
N (INPUT)
Number of keys to initialize. Length of the LISTE, VAL and DEF
arrays.
NPOS (INPUT/OUTPUT)
On output, npos contains the number of positional parameters that
were present in the argument list. However, this value is only
returned when npos is greater than zero on input. If on input,
npos is less or equal to zero, its value will be left unchanged by
ccard. Furthermore, npos = -111 on input, informs ccard to
immediately stop program execution upon encountering an error.
argv (INPUT)
Array of pointers to the argument list of a C program.
argc (INPUT)
Number of arguments supplied to a C program. Length of argv.
EXAMPLE
To illustrate the use of ccard, we will write a FORTRAN program
called AFFICHE, which does nothing but print the final values given to its
keys as well as the positional parameters it received as arguments.
Comments: -note that key name CLE1 is followed by a period, thus
indicating that no character conversion is to be performed
on its value.
-both occurrences of CLE2 are not followed by a special
character so that the values they will be given will be
converted to upper case.
-the final value of CLE3 will be converted to lower case
letters since CLE3 is terminated by an underscore.
-note finally that since NPOS is set to a value greater than
zero on input, ccard will return the number of positional
parameters present in the program call argument list.
___________________________________________________________________
| |
| PROGRAM AFFICHE |
| |
| EXTERNAL CCARD |
| |
| CHARACTER*8 LISTE(6), DEF(6), VAL(6) |
| |
| INTEGER NPOS |
| |
|* NO CONVERSION FOR THE VALUE OF CLE1 |
|* CONVERT VALUES OF CLE2 TO UPPER CASE LETTERS |
|* CONVERT VALUE OF CLE3 TO LOWER CASE LETTERS |
| |
| DATA LISTE /'CLE1.','CLE2','CLE2', 'CLE3_','-','-'/ |
| |
| DATA VAL /'Val11','VAL21','VAL22','val31',' ',' '/ |
| |
| DATA DEF /'Def11','DEF21','DEF22','def31',' ',' '/ |
| |
| NPOS = 1 |
| CALL CCARD(LISTE,DEF,VAL,6,NPOS) |
| |
| WRITE(6,*)' NUMBER OF POSITIONAL PARAMETERS :',NPOS |
| WRITE(6,*)VAL(5), VAL(6) |
| WRITE(6,*)' CLE1 = ',VAL(1) |
| WRITE(6,*)' CLE2 = ',VAL(2), VAL(3) |
| WRITE(6,*)' CLE3 = ',VAL(4) |
| |
| STOP |
| END |
|___________________________________________________________________|
Here, we have a few calling sequences to the AFFICHE program.
Call: AFFICHE
Result: NUMBER OF POSITIONAL PARAMETERS : 0
CLE1 = Val11
CLE2 = VAL21 VAL22
CLE3 = val31
Call: AFFICHE -- pos1 pos2
Result: NUMBER OF POSITIONAL PARAMETERS : 2
POS1 POS2
CLE1 = Val11
CLE2 = VAL21 VAL22
CLE3 = val31
Call: AFFICHE -CLE1 -CLE2 -CLE3
Result: NUMBER OF POSITIONAL PARAMETERS : 0
CLE1 = Def11
CLE2 = DEF21 DEF22
CLE3 = def31
Call: AFFICHE -CLE1 Tape1 -CLE2 Tape2 Tape3 -cle3 Tape4
Result: NUMBER OF POSITIONAL PARAMETERS : 0
CLE1 = Tape1
CLE2 = TAPE2 TAPE3
CLE3 = tape4
Call: AFFICHE debug -CLE2 =-12:33
Result: NUMBER OF POSITIONAL PARAMETERS : 1
DEBUG
CLE1 = Val11
CLE2 = -12 33
CLE3 = val31
Call: AFFICHE pos1 -- pos2
Result: NUMBER OF POSITIONAL PARAMETERS : 2
POS1 POS2
CLE1 = Val11
CLE2 = VAL21 VAL22
CLE3 = val31
ASSIGNING A VALUE TO A KEY
A key may be given a single value or multiple values separated by
spaces or colons. If a key is to receive a negative value, the value must be
preceded by an equal sign. This allows ccard to differentiate between a key
name (which is always preceded by a minus sign) and a value. If a negative
value is part of colon separated list and is not the first element of the
list, the equal sign may be omitted.
Values may be assigned to keys in the following fashions:
-key value
-key "value"
-key 'value'
-key value1 value2 value3
-key value1:value2:value3
-key=value1:value2:value3
Examples:
-key 10 =-12 =-34 45
-key 10:-12:-34:45
-key =-12:10:-34:45
-key=-12:10:-34:45
NOTES
1: In order to be able to assign multiple values to a key, the key
must be defined as a list in the LISTE array. If for example, a
key named cle1, is to receive three values, that key name must be
present in three consecutive locations in the LISTE array:
DATA LISTE /'CLE1','CLE1','CLE1'/
thus allowing a program call of the form:
progname -cle1 value1 value2 value3
2: The rule stated in NOTE 1 also applies to positional arguments.
The LISTE array must contain n contiguous references to the key
'-' in order to pass n positional arguments to a program:
DATA LISTE /'-','-','-', ... /
3: Any repeated key name of the LISTE array may be terminated by a
conversion character (_ or .) that is different from the one
given to other keys of the same name. One could for instance
force the first value of key1 to lower case letters while leaving
the other values to upper case:
DATA LISTE /'key1_','key1','key1'... /
4: ccard converts all key names to upper case letters. Therefore,
calling a program using '-KEY1 value' is the same as using
'-key1 value'
5: Any program using ccard will print its calling sequence if it is
invoked with the -h key:
affiche -h
will yield:
affiche
-CLE1 [Val11:Def11]
-CLE2 [VAL21:DEF21]
-CLE2 [VAL22:DEF22]
-CLE3 [val31:def31]
-- [ : ]
-- [ : ]
Note that there is no need to have an element of the LISTE array
initialized to 'H' for this to work.
AUTHORS
M.Valin, M. Lepine, J. Caveen - RPN
Latest revision: January 1993