txlyre
/
avram


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200
							<html lang="en">
<head>
<title>Command Line Parsing - avram - a virtual machine code interpreter</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="avram - a virtual machine code interpreter">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Invocation.html#Invocation" title="Invocation">
<link rel="prev" href="Invocation.html#Invocation" title="Invocation">
<link rel="next" href="Execution-Modes.html#Execution-Modes" title="Execution Modes">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
</head>
<body>
<div class="node">
<a name="Command-Line-Parsing"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Execution-Modes.html#Execution-Modes">Execution Modes</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Invocation.html#Invocation">Invocation</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Invocation.html#Invocation">Invocation</a>
<hr>
</div>

<h4 class="subsection">3.4.1 Command Line Parsing</h4>

<p><a name="index-command-line-584"></a>A couple of functions declared in <samp><span class="file">cmdline.h</span></samp> can be used to do all
the necessary parsing of command lines and environment variables needed
by virtual code applications.

<div class="defun">
&mdash; Function: list <b>avm_default_command_line</b> (<var>int argc, char *argv</var>[]<var>, int index, char *extension, char *paths, int default_to_stdin_mode, int force_text_input_mode, int *file_ordinal</var>)<var><a name="index-avm_005fdefault_005fcommand_005fline-585"></a></var><br>
<blockquote>
        <p>The purpose of this function is to build most of the data structure used
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.

          <dl>
<dt><var>argc</var><dd>is the number elements in the array referenced by <var>argv</var>
<br><dt><var>argv</var><dd>is the address of an array of pointers to null terminated character strings
holding command line arguments
<br><dt><var>index</var><dd>is the position of the first element of <var>argv</var> to be
considered. Those preceding it are ignored. 
<br><dt><var>extension</var><dd>is the address of a string that will be appended to input file names
given in <var>argv</var> in an effort to find the associated files
<br><dt><var>paths</var><dd>is the address of a null terminated character string containing a colon
separated list of directory names that will be searched for input files
<br><dt><var>default_to_stdin_mode</var><dd>is set to a non-zero value by the caller if the contents of standard
input should be read in the absence of input files
<br><dt><var>force_text_input_mode</var><dd>is set to a non-zero value by the caller to indicate that input files
should be read as text, using <code>avm_load</code> (rather than
<code>avm_preamble_and_contents</code>, which would allow them to be either
text or data). The <var>preamble</var> field of the returned file
specifications will always be empty when this flag is set. 
<br><dt><var>file_ordinal</var><dd>is set to a pointer to an integer by the caller if only one file is to
be loaded during each call. The value of the integer indicates the which
one it will be. 
</dl>

        <p>The result returned by this function is a list whose <code>head</code> is a list
of file specifications and whose <code>tail</code> is a list of command line options
intended for input to a virtual code application.

        <p>The list of file specifications returned in the <code>head</code> of the
result follows the same conventions as the <var>data</var> parameter
to the function <code>avm_output_as_directed</code>, except that the
<code>head</code> of the <code>head</code> of each item is a list representing the
time stamp of the file as given by <code>avm_date_representation</code>. If
the file is standard input, then it holds the current system date and
time.

        <p>If the <var>file_ordinal</var> parameter is <code>NULL</code>, then all
files on the command line are loaded, but if it points to an integer
<var>n</var>, then only the <var>n</var>th file is loaded, and <var>n</var> is
incremented. If there is no <var>n</var>th file, a <code>NULL</code> value is
returned as the entire result of the function. For a series of calls,
the integer should be initialized to zero by the caller before the first
call.

        <p>If standard input is indicated as one of the files on the command line
(by a dash), then it is also loaded regardless of the
<var>file_ordinal</var>, but a cached copy of it is used on subsequent
calls after the first, so that the function does not actually attempt to
reread it. If standard input is to be loaded, it must be finite for this
function to work properly.

        <p>The search strategy for files is described in <a href="Environment.html#Environment">Environment</a>, and
makes use of the <var>extension</var> and <var>paths</var> parameters.

        <p>In the list of command line options returned in the <code>tail</code> of the
result, each item is a list with a non-empty <code>head</code> and
<code>tail</code>, and is interpreted as follows.

          <ul>
<li>The <code>head</code> of the <code>head</code> is a list representing a
natural number, as given by <code>avm_natural</code>, indicating the position
of the option on the command line relative to the initial value of the
<var>index</var> parameter. 
<li>The <code>tail</code> of the <code>head</code> is a list which is <code>NULL</code>
in the case of a &ldquo;short form&rdquo; option, written with a single
dash on the command line, but is a list whose <code>head</code> and
<code>tail</code> are <code>NULL</code> in the case of a &ldquo;long form&rdquo; option,
written with two dashes. 
<li>The <code>head</code> of the <code>tail</code> is a list representing a
character string for the keyword of an option, for example <kbd>foo</kbd> in
the case of an option written <kbd>--foo=bar,baz</kbd>. 
<li>The <code>tail</code> of the <code>tail</code> is a list of lists representing
character strings, with one item for each parameter associated with the
option, for example, <kbd>bar</kbd> and <kbd>baz</kbd>. 
</ul>

        <p>If multiple calls to the function are made with differing values of
<code>*</code><var>file_ordinal</var> but other parameters unchanged, the same list of
options will be returned each time, except insofar as the position
numbers in the <code>head</code> of the <code>head</code> of each item are adjusted
as explained in <a href="Input-for-Mapped-Applications.html#Input-for-Mapped-Applications">Input for Mapped Applications</a>.

        <p>Any of the i/o errors or fatal errors associated with other file
input operations are possible with this function as well. This non-fatal
warning message is also possible. 
<a name="index-g_t_0040code_007bsearch-paths-not-supported_007d-586"></a>
     <pre class="display">          <var>program-name</var><code>: warning: search paths not supported</code>
</pre>
        <p>This error occurs if the library has been built on a platform that
<a name="index-g_t_0040file_007bargz_002eh_007d-587"></a>doesn't have the <samp><span class="file">argz.h</span></samp> header file and the <var>paths</var>
parameter is non-<code>NULL</code>. 
</p></blockquote></div>

<div class="defun">
&mdash; Function: list <b>avm_environment</b> (<var>char *env</var>[])<var><a name="index-avm_005fenvironment-588"></a></var><br>
<blockquote><p><a name="index-environment-589"></a>This function takes the address of a null terminated array of pointers
to null terminated character strings of the form
<code>"variable=value"</code>. The result returned is a list of lists, with
one item for each element of the array. The <code>head</code> of each item is
a representation of the left side of the corresponding string, and the
<code>tail</code> is a representation of the right.

        <p>This function is therefore useful along with
<code>avm_default_command_line</code> for building the remainder of the data
structure described in <a href="Parameter-Mode-Interface.html#Parameter-Mode-Interface">Parameter Mode Interface</a>. For example, a
virtual machine emulator for non-interactive parameter mode applications
with no bells and whistles could have the following form.

     <pre class="example">          int
          main(argc,argv,env)
          ...
          {
            FILE *virtual_code_file;
          ...
            avm_initialize_lists();
            avm_initialize_apply();
            avm_initialize_rawio();
            avm_initialize_formout();
            avm_initialize_cmdline();
            virtual_code_file = fopen(argv[1],"rb");
            operator = avm_received_list(
              virtual_code_file,argv[1]);
            fclose(virtual_code_file);
            command = avm_default_command_line(argc,
              argv,2,NULL,NULL,0,0,NULL);
            environs = avm_environment(env);
            operand = avm_join(command,environs);
            result = avm_apply(operator,operand);
            avm_output_as_directed(result,0,0);
            avm_dispose(result);
          ...
          }
</pre>
        <p>The <code>avm_environment</code> function could cause the program to abort due
to a memory overflow.  For security reasons, it will also abort with an
<a name="index-security-590"></a>error message if any non-printing characters are detected in its
argument. (See <a href="Other-Diagnostics-and-Warnings.html#Other-Diagnostics-and-Warnings">Other Diagnostics and Warnings</a>.) 
</p></blockquote></div>

<div class="defun">
&mdash; Function: void <b>avm_initialize_cmdline</b> ()<var><a name="index-avm_005finitialize_005fcmdline-591"></a></var><br>
<blockquote><p>This function initializes some local variables and should be called
before any of the other functions in this section is called, or else
their results are unpredictable. 
</p></blockquote></div>

<div class="defun">
&mdash; Function: void <b>avm_count_cmdline</b> ()<var><a name="index-avm_005fcount_005fcmdline-592"></a></var><br>
<blockquote><p>This function should be called after the last call to any of the other
functions in this section, as it reclaims some locally allocated
storage. If the <code>avm_count_lists</code> function is used, it should be
called after this one. 
</p></blockquote></div>

   </body></html>