<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <HTML> <HEAD> <META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.50"> <TITLE> SLSH Library Reference (version 2.2.0): Command Line Parsing Functions</TITLE> <LINK HREF="slshfun-4.html" REL=next> <LINK HREF="slshfun-2.html" REL=previous> <LINK HREF="slshfun.html#toc3" REL=contents> </HEAD> <BODY> <A HREF="slshfun-4.html">Next</A> <A HREF="slshfun-2.html">Previous</A> <A HREF="slshfun.html#toc3">Contents</A> <HR> <H2><A NAME="s3">3.</A> <A HREF="slshfun.html#toc3">Command Line Parsing Functions</A></H2> <P>These functions are defined in the <CODE>cmdopt.sl</CODE> file.</P> <H2><A NAME="cmdopt_new"></A> <A NAME="ss3.1">3.1</A> <A HREF="slshfun.html#toc3.1"><B>cmdopt_new</B></A> </H2> <P> <DL> <DT><B> Synopsis </B><DD> <P>Create a cmdopt object for parsing command-line options</P> <DT><B> Usage </B><DD> <P><CODE>obj = cmdopt_new (Ref_Type error_routine)</CODE></P> <DT><B> Description </B><DD> <P>This function creates an returns an object that may be used by the <CODE>cmdopt_process</CODE> function to parse command line arguments. The <CODE>cmdopt_new</CODE> function takes a reference to an error handling function that will get called upon error. In most cases, this function should print out the error message, display a usage message, and the call <CODE>exit</CODE>. If the error handler is <CODE>NULL</CODE>, or it returns instead of calling exit, then an exception will be thrown.</P> <P>The error hander must be defined to take a single string argument (the error message) and must return nothing.</P> <DT><B> Example </B><DD> <P> <BLOCKQUOTE><CODE> <PRE> require ("cmdopt"); private define help_callback () { () = fputs ("Usage: pgm [options] infile\n", stderr); () = fputs ("Options:\n", stderr); () = fputs (" -h|--help Show this help\n", stderr); () = fputs (" -v|--verbose Increase verbosity level\n", stderr); () = fputs (" -o|--output Output filename [stdout]\n", stderr); exit (1); } private define error_handler (text) { () = fprintf (stderr, "%s\n", text); help_callback (); } define slsh_main () { variable verbose = 0; outfile = "-"; % stdout variable c = cmdopt_new (&error_handler); cmdopt_add (c, "v|verbose", &verbose; inc); cmdopt_add (c, "h|help", &help_callback); cmdopt_add (c, "s:o|output", &outfile; type="str"); variable iend = cmdopt_process (c, __argv, 1); if (verbose) message ("some informative message"); variable fp = stdout; if (outfile != "-") fp = fopen (outfile, "w"); . . } </PRE> </CODE></BLOCKQUOTE> </P> <DT><B> See Also </B><DD> <P><CODE>cmdopt_add, cmdopt_process</CODE></P> </DL> </P> <H2><A NAME="cmdopt_process"></A> <A NAME="ss3.2">3.2</A> <A HREF="slshfun.html#toc3.2"><B>cmdopt_process</B></A> </H2> <P> <DL> <DT><B> Synopsis </B><DD> <P>Process the command-line options</P> <DT><B> Usage </B><DD> <P><CODE>Int_Type cmdopt_process (optobj, argv, istart)</CODE> <BLOCKQUOTE><CODE> <PRE> Struct_Type optobj; Array_Type argv; Int_Type istart </PRE> </CODE></BLOCKQUOTE> </P> <DT><B> Description </B><DD> <P>This function parses the command line arguments in the string array <CODE>argv</CODE> according to the rules specified by the <CODE>optobj</CODE> object, previously allocated by <CODE>cmdopt_new</CODE>. The array of strings is processed starting at the index specified by <CODE>istart</CODE>. The function returns the index of the array element where parsing stopped. Upon error, the function will call the error handler established by the prior call to <CODE>cmdopt_new</CODE>.</P> <DT><B> Example </B><DD> <P> <BLOCKQUOTE><CODE> <PRE> define slsh_main () { . . optobj = cmdopt_new (...); cmdopt_add (optobj, ...); . . variable iend = cmdopt_process (optobj, __argv, 1); . . } </PRE> </CODE></BLOCKQUOTE> </P> <DT><B> Notes </B><DD> <P>This function may also be called in an object-oriented style using the <CODE>process</CODE> method: <BLOCKQUOTE><CODE> <PRE> optobj = cmdopt_new (...); optobj.add (...) iend = optobj.process (__argv, 1); </PRE> </CODE></BLOCKQUOTE> </P> <DT><B> See Also </B><DD> <P><CODE>cmdopt_add, cmdopt_new</CODE></P> </DL> </P> <H2><A NAME="cmdopt_add"></A> <A NAME="ss3.3">3.3</A> <A HREF="slshfun.html#toc3.3"><B>cmdopt_add</B></A> </H2> <P> <DL> <DT><B> Synopsis </B><DD> <P>Add support for a command-line option</P> <DT><B> Usage </B><DD> <P><CODE>cmdopt_add (optobj, optname, addr [,...] [;qualifiers])</CODE> <BLOCKQUOTE><CODE> <PRE> Struct_Type optobj; String_Type optname; Ref_Type addr; </PRE> </CODE></BLOCKQUOTE> </P> <DT><B> Description </B><DD> <P>This function adds support for a command-line option to <CODE>optobj</CODE> and specifies how that option should be handled. Handling an option involves setting the value of a variable associated with the option, or by calling a function upon its behalf. </P> <P>For clarity, assume a command-line option can be specified using the single character <CODE>f</CODE> or by the longer name <CODE>foo</CODE>. Then the rules for calling <CODE>cmdopt_add</CODE> for the various flavors options supported by this interface and how the option may be specified on the command line are as follows:</P> <P>Options that set a variable <CODE>v</CODE> to a value <CODE>val</CODE>: <BLOCKQUOTE><CODE> <PRE> cmdopt_add (optobj, "f|foo", &v; default=val); cmdline: pgm -f ... cmdline: pgm --foo ... </PRE> </CODE></BLOCKQUOTE> </P> <P>Options that increment an integer variable <CODE>v</CODE>: <BLOCKQUOTE><CODE> <PRE> cmdopt_add (optobj, "f|foo", &v; inc); cmdline: pgm -f -f ... % In these examples, v cmdline: pgm --foo --foo ... % gets incremented twice </PRE> </CODE></BLOCKQUOTE> </P> <P>Options that bitwise-or an integer variable <CODE>v</CODE> with <CODE>FLAG</CODE>: <BLOCKQUOTE><CODE> <PRE> cmdopt_add (optobj, "f|foo", &v; bor=FLAG); cmdline: pgm -f ... % v = v | FLAG cmdline: pgm --foo ... % v = v | FLAG </PRE> </CODE></BLOCKQUOTE> Options that bitwise-and an integer variable <CODE>v</CODE> with <CODE>MASK</CODE>: <BLOCKQUOTE><CODE> <PRE> cmdopt_add (optobj, "f|foo", &v; band=MASK); cmdline: pgm -f ... % v = v & MASK; cmdline: pgm --foo ... % v = v & MASK; </PRE> </CODE></BLOCKQUOTE> The above two options may be combined: <BLOCKQUOTE><CODE> <PRE> cmdopt_add (optobj, "f|foo", &v; bor=FLAG1, band=~FLAG2); cmdline: pgm -f ... % v &= ~FLAG2; v |= FLAG1; </PRE> </CODE></BLOCKQUOTE> </P> <P>Options that require a value and set <CODE>v</CODE> to the value VAL. <BLOCKQUOTE><CODE> <PRE> cmdopt_add (optobj, "f|foo", &v; type="int"); cmdline: pgm -f VAL ... cmdline: pgm -fVAL ... cmdline: pgm --foo VAL ... cmdline: pgm --foo=VAL ... </PRE> </CODE></BLOCKQUOTE> </P> <P>Options whose value is optional: <BLOCKQUOTE><CODE> <PRE> cmdopt_add (optobj, "f|foo", &v; type="string", optional=DLFT); cmdline: pgm -f ... % set v to DFLT cmdline: pgm -fVAL ... % set v to VAL cmdline: pgm --foo ... % set v to DFLT cmdline: pgm --foo=VAL ... % set v to VAL </PRE> </CODE></BLOCKQUOTE> </P> <P>For the latter two cases, if the <CODE>append</CODE> qualifier is used, then instead of assigning the value to the specified variable, the value will be appended to a list assigned to the variable, e.g., <BLOCKQUOTE><CODE> <PRE> cmdopt_add (optobj, "f|foo", &v; type="float", append); </PRE> </CODE></BLOCKQUOTE> Then the command line <CODE>pgm --foo=VAL1 -fVAL2 -f VAL3 ...</CODE> will result in the assignment to <CODE>v</CODE> or the 3 element list <CODE>{VAL1, VAL2, VAL3}</CODE>.</P> <P>An option can also be associated with a callback function that get called when the option is handled.</P> <P>Options that cause a function to be called with arguments <CODE>a0,...</CODE>: <BLOCKQUOTE><CODE> <PRE> cmdopt_add (optobj, "f|foo", &func, a0...); cmdline: pgm --foo cmdline: pgm -f </PRE> </CODE></BLOCKQUOTE> Here <CODE>func</CODE> should be written with the signature: <BLOCKQUOTE><CODE> <PRE> define func (a0, ...) {...} </PRE> </CODE></BLOCKQUOTE> Options that take a value and cause a function to be called with additional arguments <CODE>a0,...</CODE>: <BLOCKQUOTE><CODE> <PRE> cmdopt_add (optobj, "f|foo", &func, a0,...; type="int"); cmdline: pgm --foo=VAL cmdline: pgm -f VAL cmdline: pgm -fVAL </PRE> </CODE></BLOCKQUOTE> In this case, <CODE>func</CODE> should be written as <BLOCKQUOTE><CODE> <PRE> define func (value, a0, ...) {...} </PRE> </CODE></BLOCKQUOTE> </P> <P>As the above examples illustrate, the data-type of the value assigned to a variable must be specified using the <CODE>type</CODE> qualifier. Currently the <CODE>type</CODE> must be set to one of the following values: <BLOCKQUOTE><CODE> <PRE> "str" (String_Type) "int" (Int_Type) "float" (Double_Type) </PRE> </CODE></BLOCKQUOTE> </P> <DT><B> Notes </B><DD> <P>This function may also be called in an object-oriented style using the <CODE>add</CODE> method: <BLOCKQUOTE><CODE> <PRE> optobj = cmdopt_new (...); optobj.add ("f|foo", &func, a0,...; type="int"); </PRE> </CODE></BLOCKQUOTE> </P> <DT><B> See Also </B><DD> <P><CODE>cmdopt_new, cmdopt_process</CODE></P> </DL> </P> <HR> <A HREF="slshfun-4.html">Next</A> <A HREF="slshfun-2.html">Previous</A> <A HREF="slshfun.html#toc3">Contents</A> </BODY> </HTML>