TOC PREV NEXT INDEX

Put your logo here!


7 Command Line Arguments (args.hhf)


The HLA args module provides access to, and support for, Windows Command Line Interpreter or Linux shell command line parameters. This library module provides the following routines:

arg.cmdLn; @returns( "eax" );

arg.a_cmdLn;  @returns( "eax" );
 

Returns a string containing the entire command line (including the program name). Returns a pointer to the string in EAX. arg.cmdLn returns a pointer to a string internal to the args package, arg.a_cmdLn allocates storage for a new copy of the string on the heap.

arg.c; @returns( "eax" );
 

Returns the number of command line parameters in EAX. Note that the program name is part of this count.

arg.v( index:uns32 ); @returns( "eax" );

arg.a_v( index:uns32 ); @returns( "eax" );
 

Returns a string corresponding to the specified (by index) command line parameter. If index is greater than or equal the number of command line parameters, this procedure raises an ex.BoundsError exception. Note that arg.v(0) returns the program's invocation name. The arg.v(1) call returns a string to what most people would consider to be the first command line parameter. arg.v returns a pointer to a string internal to the args package. arg.a_v allocates a new copy of the string on the heap.

arg.args;
 

This is an iterator (used in an HLA foreach loop) that returns successive command line parameters on each iteration of the foreach loop. This iterator returns a pointer to a newly allocated string in the EAX register.

arg.delete( index:uns32 )
 

Deletes the specified command line parameter from the arg.v array and decrements arg.c by one. Note that this procedure does not affect the string returned by arg.CmdLn. This procedure raises an ex.BoundsError exception if index is greater than or equal to the arg.c value.

arg.destroy( index:uns32 )
 

Deletes all of the command line parameters from internal storage and reset the command line processor. The next function that requests a command line parameter value will force the run-time system to regenerate the command line argument list.

arg.globalOptions( options:cset)
 

This is an iterator (i.e., you use it in a FOREACH loop) that yields a sequence of command line parameter options. A command line parameter option is a command line parameter that begins with a '-' or '/' character. arg.globalOptions only returns those command line parameters whose first character is a member of the "options" character set.

A typical command line might be something like the following:

c:> pgmName  -o2 -warn filename1 -c filename2 -d filename3 -x
 

 

The command line options in this example are "-o2", "-warn", "-c", "-d", and "-x". The arg.globalOptions iterator only considers those command line parameters that begin with "-" or "/" and whose first character is a member of the options parameter. Assuming options contains at least {'c', 'd', 'o', 'w', 'x'} then the arg.globalOptions iterator will return the strings "o2", "warn", "c", "d", and "x", in that order (that is, in the order they appear on the command line). If the first character of a command line option is not in the options character set, then arg.globalOptions does not return that particular command line parameter.

Note that arg.globalOptions does not remove the command line parameters from the command line string or from the arg.v array. If you want to remove them, you must explicitly do so using the arg.delete function. Note, however, that you must not delete command line arguments while scanning through the arguments in a FOREACH loop using the arg.globalOptions iterator.

[comment attached *** Here I am]

arg.localOptions( index:uns32; options:cset );
 

This is an iterator that yields the sequence of command line options begining at parameter "index". This iterator only yields strings as long as successive parameters begin with a "-" or "/". It fails upon encountering a command line parameter that is not an option (that is, begins with "-" or "/"). Note that this iterator only yields those command line options whose first character beyond the "-" or "/" character is a member of the options character set.

Typically, you would use the arg.localOptions iterator inside a FOREACH loop to obtain the command line parameters for a specific filename on the command line. That is, some programs process multiple files and let you associate command line parameters with a single filename. Consider the following simple example:

c:> pgm  -o2 -c file1  -o5 file2  -c file3
 

 

In this example, the "pgm" program (presumably) associates "-o2" and "-c" with file1, "-o5" with file2, and "-c" with file3.

Were you to call arg.localOptions as follows:

		foreach arg.localOption( 1, {'o', 'c'} ) do ... endfor;
 

 

then the arg.localOption iterator would return two strings: the first would be "o2" and the second would be "c". Within that iterator your code should save these options and count the number of command line parameters processed so it will know the index of the associated filename command line parameter once it is done processing the options. Typically, you would bury this FOREACH loop (with some minor modifications) inside some other loop that processes each filename (or other command line parameter preceded by command line options).

See the CmdLnDemo.hla file in the Examples directory of the HLA distribution for an example of each of these routines.



TOC PREV NEXT INDEX