Command-Line-Parsing.html 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
  2. <html>
  3. <!-- Created on November 8, 2012 by texi2html 1.82
  4. texi2html was written by:
  5. Lionel Cons <[email protected]> (original author)
  6. Karl Berry <[email protected]>
  7. Olaf Bachmann <[email protected]>
  8. and many others.
  9. Maintained by: Many creative people.
  10. Send bugs and suggestions to <[email protected]>
  11. -->
  12. <head>
  13. <title>avram - a virtual machine code interpreter: 3.4.1 Command Line Parsing</title>
  14. <meta name="description" content="avram - a virtual machine code interpreter: 3.4.1 Command Line Parsing">
  15. <meta name="keywords" content="avram - a virtual machine code interpreter: 3.4.1 Command Line Parsing">
  16. <meta name="resource-type" content="document">
  17. <meta name="distribution" content="global">
  18. <meta name="Generator" content="texi2html 1.82">
  19. <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  20. <style type="text/css">
  21. <!--
  22. a.summary-letter {text-decoration: none}
  23. blockquote.smallquotation {font-size: smaller}
  24. pre.display {font-family: serif}
  25. pre.format {font-family: serif}
  26. pre.menu-comment {font-family: serif}
  27. pre.menu-preformatted {font-family: serif}
  28. pre.smalldisplay {font-family: serif; font-size: smaller}
  29. pre.smallexample {font-size: smaller}
  30. pre.smallformat {font-family: serif; font-size: smaller}
  31. pre.smalllisp {font-size: smaller}
  32. span.roman {font-family:serif; font-weight:normal;}
  33. span.sansserif {font-family:sans-serif; font-weight:normal;}
  34. ul.toc {list-style: none}
  35. -->
  36. </style>
  37. </head>
  38. <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
  39. <a name="Command-Line-Parsing"></a>
  40. <table cellpadding="1" cellspacing="1" border="0">
  41. <tr><td valign="middle" align="left">[<a href="Invocation.html#Invocation" title="Previous section in reading order"> &lt; </a>]</td>
  42. <td valign="middle" align="left">[<a href="Execution-Modes.html#Execution-Modes" title="Next section in reading order"> &gt; </a>]</td>
  43. <td valign="middle" align="left"> &nbsp; </td>
  44. <td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
  45. <td valign="middle" align="left">[<a href="Invocation.html#Invocation" title="Up section"> Up </a>]</td>
  46. <td valign="middle" align="left">[<a href="Character-Table.html#Character-Table" title="Next chapter"> &gt;&gt; </a>]</td>
  47. <td valign="middle" align="left"> &nbsp; </td>
  48. <td valign="middle" align="left"> &nbsp; </td>
  49. <td valign="middle" align="left"> &nbsp; </td>
  50. <td valign="middle" align="left"> &nbsp; </td>
  51. <td valign="middle" align="left">[<a href="avram.html#Top" title="Cover (top) of document">Top</a>]</td>
  52. <td valign="middle" align="left">[<a href="avram_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
  53. <td valign="middle" align="left">[<a href="Function-Index.html#Function-Index" title="Index">Index</a>]</td>
  54. <td valign="middle" align="left">[<a href="avram_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
  55. </tr></table>
  56. <hr size="1">
  57. <a name="Command-Line-Parsing-1"></a>
  58. <h3 class="subsection">3.4.1 Command Line Parsing</h3>
  59. <a name="index-command-line-6"></a>
  60. <p>A couple of functions declared in &lsquo;<tt>cmdline.h</tt>&rsquo; can be used to do all
  61. the necessary parsing of command lines and environment variables needed
  62. by virtual code applications.
  63. </p>
  64. <dl>
  65. <dt><a name="index-avm_005fdefault_005fcommand_005fline"></a><u>Function:</u> list <b>avm_default_command_line</b><i> (int <var>argc</var>, char *<var>argv</var>[], int <var>index</var>, char *<var>extension</var>, char *<var>paths</var>, int <var>default_to_stdin_mode</var>, int <var>force_text_input_mode</var>, int *<var>file_ordinal</var>)</i></dt>
  66. <dd>
  67. <p>The purpose of this function is to build most of the data structure used
  68. by parameter mode applications, as described in <a href="Input-Data-Structure.html#Input-Data-Structure">Input Data Structure</a>, by parsing the command line according to <a href="Command-Line-Syntax.html#Command-Line-Syntax">Command Line Syntax</a>. The parameters have these interpretations.
  69. </p>
  70. <dl compact="compact">
  71. <dt> <code><var>argc</var></code></dt>
  72. <dd><p>is the number elements in the array referenced by <code><var>argv</var></code>
  73. </p></dd>
  74. <dt> <code><var>argv</var></code></dt>
  75. <dd><p>is the address of an array of pointers to null terminated character strings
  76. holding command line arguments
  77. </p></dd>
  78. <dt> <code><var>index</var></code></dt>
  79. <dd><p>is the position of the first element of <code><var>argv</var></code> to be
  80. considered. Those preceding it are ignored.
  81. </p></dd>
  82. <dt> <code><var>extension</var></code></dt>
  83. <dd><p>is the address of a string that will be appended to input file names
  84. given in <code><var>argv</var></code> in an effort to find the associated files
  85. </p></dd>
  86. <dt> <code><var>paths</var></code></dt>
  87. <dd><p>is the address of a null terminated character string containing a colon
  88. separated list of directory names that will be searched for input files
  89. </p></dd>
  90. <dt> <code><var>default_to_stdin_mode</var></code></dt>
  91. <dd><p>is set to a non-zero value by the caller if the contents of standard
  92. input should be read in the absence of input files
  93. </p></dd>
  94. <dt> <code><var>force_text_input_mode</var></code></dt>
  95. <dd><p>is set to a non-zero value by the caller to indicate that input files
  96. should be read as text, using <code>avm_load</code> (rather than
  97. <code>avm_preamble_and_contents</code>, which would allow them to be either
  98. text or data). The <code><var>preamble</var></code> field of the returned file
  99. specifications will always be empty when this flag is set.
  100. </p></dd>
  101. <dt> <code><var>file_ordinal</var></code></dt>
  102. <dd><p>is set to a pointer to an integer by the caller if only one file is to
  103. be loaded during each call. The value of the integer indicates the which
  104. one it will be.
  105. </p></dd>
  106. </dl>
  107. <p>The result returned by this function is a list whose <code>head</code> is a list
  108. of file specifications and whose <code>tail</code> is a list of command line options
  109. intended for input to a virtual code application.
  110. </p>
  111. <p>The list of file specifications returned in the <code>head</code> of the
  112. result follows the same conventions as the <code><var>data</var></code> parameter
  113. to the function <code>avm_output_as_directed</code>, except that the
  114. <code>head</code> of the <code>head</code> of each item is a list representing the
  115. time stamp of the file as given by <code>avm_date_representation</code>. If
  116. the file is standard input, then it holds the current system date and
  117. time.
  118. </p>
  119. <p>If the <code><var>file_ordinal</var></code> parameter is <code>NULL</code>, then all
  120. files on the command line are loaded, but if it points to an integer
  121. <var>n</var>, then only the <var>n</var>th file is loaded, and <var>n</var> is
  122. incremented. If there is no <var>n</var>th file, a <code>NULL</code> value is
  123. returned as the entire result of the function. For a series of calls,
  124. the integer should be initialized to zero by the caller before the first
  125. call.
  126. </p>
  127. <p>If standard input is indicated as one of the files on the command line
  128. (by a dash), then it is also loaded regardless of the
  129. <code><var>file_ordinal</var></code>, but a cached copy of it is used on subsequent
  130. calls after the first, so that the function does not actually attempt to
  131. reread it. If standard input is to be loaded, it must be finite for this
  132. function to work properly.
  133. </p>
  134. <p>The search strategy for files is described in <a href="Environment.html#Environment">Environment</a>, and
  135. makes use of the <code><var>extension</var></code> and <code><var>paths</var></code> parameters.
  136. </p>
  137. <p>In the list of command line options returned in the <code>tail</code> of the
  138. result, each item is a list with a non-empty <code>head</code> and
  139. <code>tail</code>, and is interpreted as follows.
  140. </p>
  141. <ul>
  142. <li> The <code>head</code> of the <code>head</code> is a list representing a
  143. natural number, as given by <code>avm_natural</code>, indicating the position
  144. of the option on the command line relative to the initial value of the
  145. <code><var>index</var></code> parameter.
  146. </li><li> The <code>tail</code> of the <code>head</code> is a list which is <code>NULL</code>
  147. in the case of a &ldquo;short form&rdquo; option, written with a single
  148. dash on the command line, but is a list whose <code>head</code> and
  149. <code>tail</code> are <code>NULL</code> in the case of a &ldquo;long form&rdquo; option,
  150. written with two dashes.
  151. </li><li> The <code>head</code> of the <code>tail</code> is a list representing a
  152. character string for the keyword of an option, for example <kbd>foo</kbd> in
  153. the case of an option written <kbd>--foo=bar,baz</kbd>.
  154. </li><li> The <code>tail</code> of the <code>tail</code> is a list of lists representing
  155. character strings, with one item for each parameter associated with the
  156. option, for example, <kbd>bar</kbd> and <kbd>baz</kbd>.
  157. </li></ul>
  158. <p>If multiple calls to the function are made with differing values of
  159. <code>*<var>file_ordinal</var></code> but other parameters unchanged, the same list of
  160. options will be returned each time, except insofar as the position
  161. numbers in the <code>head</code> of the <code>head</code> of each item are adjusted
  162. as explained in <a href="Input-for-Mapped-Applications.html#Input-for-Mapped-Applications">Input for Mapped Applications</a>.
  163. </p>
  164. <p>Any of the i/o errors or fatal errors associated with other file
  165. input operations are possible with this function as well. This non-fatal
  166. warning message is also possible.
  167. <a name="index-search-paths-not-supported-1"></a>
  168. </p>
  169. <table><tr><td>&nbsp;</td><td><pre class="display"><code><var>program-name</var>: warning: search paths not supported</code>
  170. </pre></td></tr></table>
  171. <p>This error occurs if the library has been built on a platform that
  172. <a name="index-argz_002eh-1"></a>
  173. doesn&rsquo;t have the &lsquo;<tt>argz.h</tt>&rsquo; header file and the <code><var>paths</var></code>
  174. parameter is non-<code>NULL</code>.
  175. </p></dd></dl>
  176. <dl>
  177. <dt><a name="index-avm_005fenvironment"></a><u>Function:</u> list <b>avm_environment</b><i> (char *<var>env</var>[])</i></dt>
  178. <dd><a name="index-environment-6"></a>
  179. <p>This function takes the address of a null terminated array of pointers
  180. to null terminated character strings of the form
  181. <code>&quot;variable=value&quot;</code>. The result returned is a list of lists, with
  182. one item for each element of the array. The <code>head</code> of each item is
  183. a representation of the left side of the corresponding string, and the
  184. <code>tail</code> is a representation of the right.
  185. </p>
  186. <p>This function is therefore useful along with
  187. <code>avm_default_command_line</code> for building the remainder of the data
  188. structure described in <a href="Parameter-Mode-Interface.html#Parameter-Mode-Interface">Parameter Mode Interface</a>. For example, a
  189. virtual machine emulator for non-interactive parameter mode applications
  190. with no bells and whistles could have the following form.
  191. </p>
  192. <table><tr><td>&nbsp;</td><td><pre class="example">int
  193. main(argc,argv,env)
  194. &hellip;
  195. {
  196. FILE *virtual_code_file;
  197. &hellip;
  198. avm_initialize_lists();
  199. avm_initialize_apply();
  200. avm_initialize_rawio();
  201. avm_initialize_formout();
  202. avm_initialize_cmdline();
  203. virtual_code_file = fopen(argv[1],&quot;rb&quot;);
  204. operator = avm_received_list(
  205. virtual_code_file,argv[1]);
  206. fclose(virtual_code_file);
  207. command = avm_default_command_line(argc,
  208. argv,2,NULL,NULL,0,0,NULL);
  209. environs = avm_environment(env);
  210. operand = avm_join(command,environs);
  211. result = avm_apply(operator,operand);
  212. avm_output_as_directed(result,0,0);
  213. avm_dispose(result);
  214. &hellip;
  215. }
  216. </pre></td></tr></table>
  217. <p>The <code>avm_environment</code> function could cause the program to abort due
  218. to a memory overflow. For security reasons, it will also abort with an
  219. <a name="index-security-2"></a>
  220. error message if any non-printing characters are detected in its
  221. argument. (See <a href="Other-Diagnostics-and-Warnings.html#Other-Diagnostics-and-Warnings">Other Diagnostics and Warnings</a>.)
  222. </p></dd></dl>
  223. <dl>
  224. <dt><a name="index-avm_005finitialize_005fcmdline"></a><u>Function:</u> void <b>avm_initialize_cmdline</b><i> ()</i></dt>
  225. <dd><p>This function initializes some local variables and should be called
  226. before any of the other functions in this section is called, or else
  227. their results are unpredictable.
  228. </p></dd></dl>
  229. <dl>
  230. <dt><a name="index-avm_005fcount_005fcmdline"></a><u>Function:</u> void <b>avm_count_cmdline</b><i> ()</i></dt>
  231. <dd><p>This function should be called after the last call to any of the other
  232. functions in this section, as it reclaims some locally allocated
  233. storage. If the <code>avm_count_lists</code> function is used, it should be
  234. called after this one.
  235. </p></dd></dl>
  236. <hr size="1">
  237. <table cellpadding="1" cellspacing="1" border="0">
  238. <tr><td valign="middle" align="left">[<a href="Invocation.html#Invocation" title="Previous section in reading order"> &lt; </a>]</td>
  239. <td valign="middle" align="left">[<a href="Execution-Modes.html#Execution-Modes" title="Next section in reading order"> &gt; </a>]</td>
  240. <td valign="middle" align="left"> &nbsp; </td>
  241. <td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
  242. <td valign="middle" align="left">[<a href="Invocation.html#Invocation" title="Up section"> Up </a>]</td>
  243. <td valign="middle" align="left">[<a href="Character-Table.html#Character-Table" title="Next chapter"> &gt;&gt; </a>]</td>
  244. <td valign="middle" align="left"> &nbsp; </td>
  245. <td valign="middle" align="left"> &nbsp; </td>
  246. <td valign="middle" align="left"> &nbsp; </td>
  247. <td valign="middle" align="left"> &nbsp; </td>
  248. <td valign="middle" align="left">[<a href="avram.html#Top" title="Cover (top) of document">Top</a>]</td>
  249. <td valign="middle" align="left">[<a href="avram_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
  250. <td valign="middle" align="left">[<a href="Function-Index.html#Function-Index" title="Index">Index</a>]</td>
  251. <td valign="middle" align="left">[<a href="avram_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
  252. </tr></table>
  253. <p>
  254. <font size="-1">
  255. This document was generated on <i>November 8, 2012</i> using <a href="http://www.nongnu.org/texi2html/"><i>texi2html 1.82</i></a>.
  256. </font>
  257. <br>
  258. </p>
  259. </body>
  260. </html>