/usr/share/mozart/doc/system/node4.html is in mozart-doc 1.4.0-8ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD><TITLE>1.3 Option Specifications</TITLE><LINK href="ozdoc.css" rel="stylesheet" type="text/css"></HEAD><BODY><TABLE align="center" border="0" cellpadding="6" cellspacing="6" class="nav"><TR bgcolor="#DDDDDD"><TD><A href="node3.html#section.application.parsingconventions"><< Prev</A></TD><TD><A href="node1.html">- Up -</A></TD></TR></TABLE><DIV id="section.application.specifications"><H2><A name="section.application.specifications">1.3 Option Specifications</A></H2><P> There are several ways to specify the way the arguments are parsed; we present them in order of increasing processing power. </P><H3><A name="label17">1.3.1 Plain</A></H3><DIV class="apropos"><P class="margin">Syntax Specification</P><P> The <CODE>plain</CODE> way of command line processing actually involves no processing at all. In CGI parsing, not even escaped characters are translated. </P><BLOCKQUOTE><TABLE border="0" cellpadding="0" cellspacing="0"><TR valign="top"><TD><<I>spec</I>></TD><TD align="center"> ::= </TD><TD><CODE>plain</CODE></TD></TR></TABLE></BLOCKQUOTE><P> </P></DIV><DIV class="apropos"><P class="margin">Returned Result</P><P> For CGI scripts, the result consists of a list of pairs of strings (the name/value pairs), whereas for command lines, it consists of a list of strings. </P></DIV><H3><A name="label18">1.3.2 List</A></H3><DIV class="apropos"><P class="margin">Syntax Specification</P><P> The <CODE>list</CODE> way of processing command line arguments takes care of determining what is a command line option, whether it takes a value, how its value to be interpreted, etc. </P><BLOCKQUOTE><TABLE border="0" cellpadding="0" cellspacing="0"><TR valign="top"><TD><<I>spec</I>></TD><TD align="center"> += </TD><TD><CODE>list(</CODE>[<CODE>mode: </CODE><<I>mode</I>>] <<I>option</I>> ... <<I>option</I>>)</TD></TR></TABLE></BLOCKQUOTE><P> Using the <CODE>mode</CODE> specification, the command line parser can either be instructed to stop at the first non-option argument it encounters (<CODE>start</CODE>) or it can look for options on the whole command line (<CODE>anywhere</CODE>). The latter is the default if no <CODE>mode</CODE> is given. </P><BLOCKQUOTE><TABLE border="0" cellpadding="0" cellspacing="0"><TR valign="top"><TD><<I>mode</I>></TD><TD align="center"> ::= </TD><TD><CODE>start</CODE> | <CODE>anywhere</CODE></TD></TR></TABLE></BLOCKQUOTE><P> </P></DIV><P> The integer fields of the option specification describe the individual options. An option must as least have an <<I>option name</I>>. Furthermore, it may either be an alias for another option (if <CODE>alias</CODE> is given) or it may be a <SPAN class="quasi">`real'</SPAN> option actually visible to the application. Aliases are never returned to the application; they are always replaced by the option they stand for. </P><BLOCKQUOTE><TABLE border="0" cellpadding="0" cellspacing="0"><TR valign="top"><TD><<I>option</I>></TD><TD align="center"> ::= </TD><TD><<I>option name</I>><CODE>(</CODE>[<CODE>char:</CODE> <<I>char or chars</I>>] [<CODE>type: </CODE><<I>type</I>>]<CODE>)</CODE></TD></TR><TR valign="top"><TD></TD><TD align="center"> | </TD><TD><<I>option name</I>><CODE>(</CODE>[<CODE>char: </CODE><<I>char or chars</I>>] <CODE>alias: </CODE><<I>alias</I>><CODE>)</CODE></TD></TR></TABLE></BLOCKQUOTE><P> </P><BLOCKQUOTE><TABLE border="0" cellpadding="0" cellspacing="0"><TR valign="top"><TD><<I>option name</I>></TD><TD align="center"> ::= </TD><TD><<I>atom</I>></TD></TR></TABLE></BLOCKQUOTE><P> As mentioned in <A href="node3.html#section.application.cmdparsing">Section 1.2.2</A>, options may be notated using single-character short forms. With the <CODE>char</CODE> specification one or several single-character short forms may be assigned to an option. </P><BLOCKQUOTE><TABLE border="0" cellpadding="0" cellspacing="0"><TR valign="top"><TD><<I>char or chars</I>></TD><TD align="center"> ::= </TD><TD><<I>char</I>> | <CODE>[</CODE><<I>char</I>><CODE>]</CODE></TD></TR></TABLE></BLOCKQUOTE><P> </P><P> If no <CODE>type</CODE> is given, then the option does not take an argument. (Note that <CODE><SPAN class="keyword">true</SPAN></CODE> will be used as the associated value in this case.) Boolean options have a special status, as has already been described in <A href="node3.html#section.application.parsingconventions">Section 1.2</A>. The remaining type specifications, however, require an additional argument. The <CODE>list(</CODE><<I>primary type</I>><CODE>)</CODE> annotation interprets its argument as a comma-separated list of elements of a specific type. </P><BLOCKQUOTE><TABLE border="0" cellpadding="0" cellspacing="0"><TR valign="top"><TD><<I>type</I>></TD><TD align="center"> ::= </TD><TD><CODE>bool</CODE></TD></TR><TR valign="top"><TD></TD><TD align="center"> | </TD><TD><<I>primary type</I>></TD></TR><TR valign="top"><TD></TD><TD align="center"> | </TD><TD><CODE>list(</CODE><<I>primary type</I>><CODE>)</CODE></TD></TR></TABLE></BLOCKQUOTE><P> </P><P> There are four supported basic types and a <SPAN class="quasi">`generic'</SPAN> type. Integer and float arguments have to be given in Oz concrete syntax (with the exception that the unary minus sign may be notated as <CODE><SPAN class="keyword">-</SPAN></CODE>); minimum and maximum values may also be specified. For arguments to be returned as atoms, a set of allowed values may be specified. Strings are returned as-is. </P><P> The generic type simply consists of a binary procedure with the signature <CODE>{P </CODE><CODE>+<I>S</I></CODE><CODE> </CODE><CODE><I>X</I></CODE><CODE>}</CODE> which may arbitrarily transform the argument, given as a string. </P><BLOCKQUOTE><TABLE border="0" cellpadding="0" cellspacing="0"><TR valign="top"><TD><<I>primary type</I>></TD><TD align="center"> ::= </TD><TD><CODE>int(</CODE>[<CODE>min: </CODE><<I>int</I>>] [<CODE>max: </CODE><<I>int</I>>]<CODE>)</CODE></TD></TR><TR valign="top"><TD></TD><TD align="center"> | </TD><TD><CODE>float(</CODE>[<CODE>min: </CODE><<I>float</I>>] [<CODE>max: </CODE><<I>float</I>>]<CODE>)</CODE></TD></TR><TR valign="top"><TD></TD><TD align="center"> | </TD><TD><CODE>atom(</CODE>[<<I>atom</I>> ... <<I>atom</I>>]<CODE>)</CODE></TD></TR><TR valign="top"><TD></TD><TD align="center"> | </TD><TD><CODE>string</CODE></TD></TR><TR valign="top"><TD></TD><TD align="center"> | </TD><TD><<I>procedure</I>></TD></TR></TABLE></BLOCKQUOTE><P> </P><P> Two different forms of alias are supported. Option name aliases simply state that this option name is equivalent to some other option name; the other option's argument description will be used for parsing this option as well. The second kind of alias states that this option is equivalent to another option used with the supplied value (or a combination of several options). In the latter case, the value will be transferred to the output without any additional transformations. </P><BLOCKQUOTE><TABLE border="0" cellpadding="0" cellspacing="0"><TR valign="top"><TD><<I>alias</I>></TD><TD align="center"> ::= </TD><TD><<I>option name</I>></TD></TR><TR valign="top"><TD></TD><TD align="center"> | </TD><TD><<I>option name</I>><CODE><SPAN class="keyword">#</SPAN></CODE><<I>value</I>></TD></TR><TR valign="top"><TD></TD><TD align="center"> | </TD><TD><CODE>[</CODE><<I>option name</I>><CODE><SPAN class="keyword">#</SPAN></CODE><<I>value</I>><CODE>]</CODE></TD></TR></TABLE></BLOCKQUOTE><P> </P><DIV class="apropos"><P class="margin">Returned Result</P><P> The result of this processing step is a list of parsed options, interspersed with non-parsed arguments, a so-called <<I>option list</I>>. All option names in this list are the canonical (i. e., not aliased and unabbreviated) forms. The list respects the order in which the arguments were given. </P><BLOCKQUOTE><TABLE border="0" cellpadding="0" cellspacing="0"><TR valign="top"><TD><<I>option list</I>></TD><TD align="center"> ::= </TD><TD><CODE>[</CODE><<I>arg or option</I>><CODE>]</CODE></TD></TR></TABLE></BLOCKQUOTE><P> </P><BLOCKQUOTE><TABLE border="0" cellpadding="0" cellspacing="0"><TR valign="top"><TD><<I>arg or option</I>></TD><TD align="center"> ::= </TD><TD><<I>option name</I>><CODE><SPAN class="keyword">#</SPAN></CODE><<I>value</I>></TD></TR><TR valign="top"><TD></TD><TD align="center"> | </TD><TD><<I>string</I>></TD></TR></TABLE></BLOCKQUOTE><P> </P></DIV><HR><UL class="toc"><LI><A href="node5.html#section.application.list.examples">List Examples</A></LI></UL><HR><H3><A name="label19">1.3.3 Record</A></H3><DIV class="apropos"><P class="margin">Syntax Specification</P><P> The additional processing step involved in <CODE>record</CODE> kind specifications is that additional contextual conditions may be checked, and the result is returned in a different form. </P></DIV><P> Basically, the <CODE>record</CODE> specification is a strict extension of the <CODE>list</CODE> specification. </P><BLOCKQUOTE><TABLE border="0" cellpadding="0" cellspacing="0"><TR valign="top"><TD><<I>spec</I>></TD><TD align="center"> += </TD><TD><CODE>record(</CODE>[<CODE>mode: </CODE><<I>mode</I>>] <<I>option</I>> ... <<I>option</I>>)</TD></TR></TABLE></BLOCKQUOTE><P> The specifications for <SPAN class="quasi">`real'</SPAN> (i. e., non-alias) options take some more information into consideration, namely how often the option may appear and how several occurrences combine (<<I>occ</I>>), and whether it is a required option (<CODE>optional</CODE>; the default is <CODE><SPAN class="keyword">true</SPAN></CODE>) or whether it takes a default value (<CODE>default</CODE>), which it does not by default. At most one of <CODE>default</CODE> and <CODE>optional</CODE> may be given. </P><BLOCKQUOTE><TABLE border="0" cellpadding="0" cellspacing="0"><TR valign="top"><TD><<I>option</I>></TD><TD align="center"> += </TD><TD><<I>option name</I>><CODE>(</CODE></TD></TR><TR valign="top"><TD></TD><TD align="center"></TD><TD><CODE> 1: </CODE><<I>occ</I>></TD></TR><TR valign="top"><TD></TD><TD align="center"></TD><TD><CODE> </CODE>[<CODE>char: </CODE><<I>char or chars</I>>]</TD></TR><TR valign="top"><TD></TD><TD align="center"></TD><TD><CODE> </CODE>[<CODE>type: </CODE><<I>type</I>>]</TD></TR><TR valign="top"><TD></TD><TD align="center"></TD><TD><CODE> </CODE>[<CODE>default: </CODE><<I>value</I>> | <CODE>optional: </CODE><<I>bool</I>>]<CODE>)</CODE></TD></TR></TABLE></BLOCKQUOTE><P> An option may be allowed to occur at most once (<CODE>single</CODE>) or any number of times. In the latter case, the result may either respect all occurrences (<CODE>multiple</CODE>), or it may ignore all but the first (<CODE>leftmost</CODE>) or last (<CODE>rightmost</CODE>) occurrence. When all occurrences are respected, a list of them (preserving the order) is returned. </P><BLOCKQUOTE><TABLE border="0" cellpadding="0" cellspacing="0"><TR valign="top"><TD><<I>occ</I>></TD><TD align="center"> ::= </TD><TD><CODE>single</CODE> | <CODE>multiple</CODE> | <CODE>leftmost</CODE> | <CODE>rightmost</CODE> | <CODE>accumulate(P)</CODE></TD></TR></TABLE></BLOCKQUOTE><P> When <CODE>accumulate(P)</CODE> is specified, procedure <CODE>P</CODE> is called for each occurrence of the option. It takes two arguments: the option (as an atom) and the parsed value. This can be used to accumulate multiple occurrences of related options into one list. See, for example, options <CODE><SPAN class="keyword">--</SPAN>include</CODE> and <CODE><SPAN class="keyword">--</SPAN>exclude</CODE> of <A href="../tools/node7.html#chapter.linker">the Oz linker <CODE>ozl</CODE></A>. </P><DIV class="apropos"><P class="margin">Returned Result</P><P> The result consists of an option record. All options which had an explicit <<I>occ</I>> given in their specification are moved from the option list into this record, the feature being the option name, the subtree the associated value. Defaulted options that have not been overridden by the argument list appear in this record with their default value. Only optional options may be missing from this record, namely when they have not been specified in the argument list. Those options which did not have an explicit <<I>occ</I>> given in their specification are found, interspersed with non-parsed arguments, in an option list under feature <CODE>1</CODE> of the option record. </P><BLOCKQUOTE><TABLE border="0" cellpadding="0" cellspacing="0"><TR valign="top"><TD><<I>option record</I>></TD><TD align="center"> ::= </TD><TD><CODE>optRec(1: </CODE><<I>option list</I>></TD></TR><TR valign="top"><TD></TD><TD align="center"></TD><TD><CODE> </CODE><<I>option name</I>><CODE>: </CODE><<I>value</I>> ...</TD></TR><TR valign="top"><TD></TD><TD align="center"></TD><TD><CODE> </CODE><<I>option name</I>><CODE>: </CODE><<I>value</I>><CODE>)</CODE></TD></TR></TABLE></BLOCKQUOTE><P> </P></DIV><HR><UL class="toc"><LI><A href="node6.html#section.application.record.examples">Record Examples</A></LI></UL></DIV><TABLE align="center" border="0" cellpadding="6" cellspacing="6" class="nav"><TR bgcolor="#DDDDDD"><TD><A href="node3.html#section.application.parsingconventions"><< Prev</A></TD><TD><A href="node1.html">- Up -</A></TD></TR></TABLE><HR><ADDRESS><A href="http://www.ps.uni-sb.de/~duchier/">Denys Duchier</A>, <A href="http://www.ps.uni-sb.de/~kornstae/">Leif Kornstaedt</A>, <A href="http://www.ps.uni-sb.de/~homik/">Martin Homik</A>, <A href="http://www.ps.uni-sb.de/~tmueller/">Tobias Müller</A>, <A href="http://www.ps.uni-sb.de/~schulte/">Christian Schulte</A> and <A href="http://www.info.ucl.ac.be/~pvr">Peter Van Roy</A><BR><SPAN class="version">Version 1.4.0 (20110908185330)</SPAN></ADDRESS></BODY></HTML>
|