Formatted-Input.html 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231
  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.3.3 Formatted Input</title>
  14. <meta name="description" content="avram - a virtual machine code interpreter: 3.3.3 Formatted Input">
  15. <meta name="keywords" content="avram - a virtual machine code interpreter: 3.3.3 Formatted Input">
  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="Formatted-Input"></a>
  40. <table cellpadding="1" cellspacing="1" border="0">
  41. <tr><td valign="middle" align="left">[<a href="Raw-Files.html#Raw-Files" title="Previous section in reading order"> &lt; </a>]</td>
  42. <td valign="middle" align="left">[<a href="Formatted-Output.html#Formatted-Output" 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="File-Manipulation.html#File-Manipulation" 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="Formatted-Input-1"></a>
  58. <h3 class="subsection">3.3.3 Formatted Input</h3>
  59. <p>Some functions relating to the input of text files or data files with
  60. preambles are declared in the header file &lsquo;<tt>formin.h</tt>&rsquo;. The usage of
  61. these functions is as follows.
  62. </p>
  63. <dl>
  64. <dt><a name="index-avm_005fpreamble_005fand_005fcontents"></a><u>Function:</u> list <b>avm_preamble_and_contents</b><i> (FILE *<var>source</var>, char *<var>filename</var>)</i></dt>
  65. <dd><p>This function loads a file of either text or data format into memory.
  66. </p>
  67. <dl compact="compact">
  68. <dt> <code><var>source</var></code></dt>
  69. <dd><p>should be initialized by the caller as the address of a file
  70. already open for reading that will be read from its current position.
  71. </p></dd>
  72. <dt> <code><var>filename</var></code></dt>
  73. <dd><p>should be set by the caller to the address of a null terminated
  74. character string giving the name of the file that will be used if an i/o
  75. error message needs to be written about it. If it is a <code>NULL</code>
  76. pointer, standard input is assumed.
  77. </p></dd>
  78. </dl>
  79. <p>The result returned by the function will be a list whose <code>head</code>
  80. <a name="index-preamble-6"></a>
  81. represents the preamble of the file and whose <code>tail</code> represents the
  82. contents. As a side effect, the input file will be closed, unless the
  83. <code><var>filename</var></code> parameter is <code>NULL</code>.
  84. </p>
  85. <p>If the file conforms to the format described in <a href="File-Format.html#File-Format">File Format</a>, the
  86. preamble is a list of character strings. In the result returned by the
  87. function, the <code>head</code> field will be a list with one item for each
  88. line in the file, and each item will be a list of character
  89. representations as in <a href="Character-Table.html#Character-Table">Character Table</a>, but with the leading hashes
  90. stripped. The <code>tail</code> will be the list specified by remainder of the
  91. file according to <a href="Concrete-Syntax.html#Concrete-Syntax">Concrete Syntax</a>. If the file has an empty
  92. preamble but is nevertheless a data file, the <code>head</code> will be a list
  93. whose <code>head</code> and <code>tail</code> are both <code>NULL</code>.
  94. </p>
  95. <p>If the file does not conform to the format in <a href="File-Format.html#File-Format">File Format</a>, then
  96. the <code>head</code> of the result will be <code>NULL</code>, and the <code>tail</code>
  97. will be a list of lists of character representations, with one for each
  98. line.
  99. </p>
  100. <p>Whether or not the file conforms to the format is determined on the fly,
  101. so this function is useful for situations in which the format is not
  102. known in advance. The conventions regarding the preamble and contents
  103. maintained by this function are the same as those used by virtual code
  104. applications as described in <a href="Standard-Output-Representation.html#Standard-Output-Representation">Standard Output Representation</a> and
  105. <a href="Input-Data-Structure.html#Input-Data-Structure">Input Data Structure</a>.
  106. </p>
  107. <p>The characters used for line breaks are not explicitly represented in
  108. <a name="index-line-breaks-1"></a>
  109. the result. Depending on the host system, line breaks in text files may
  110. be represented either by the character code 10, or by the sequence 13
  111. 10. However, in order for the library to deal with binary files in a
  112. portable way, a line break always corresponds to a 10 as far as this
  113. function is concerned regardless of the host, and a 13 is treated like
  114. any other character. Hence, if this function were used on binary files
  115. that happened to have some 10s in them, the exact contents of a
  116. file could be reconstructed easily by appending a 10 to all but the last
  117. line and flattening the list.
  118. </p>
  119. <p>A considerable amount of memory may need to be allocated by this
  120. function in order to store the file as a list. If not enough memory is
  121. available, the function prints an error message to standard error and
  122. aborts rather than returning to the caller. However, i/o errors are not
  123. fatal, and will cause the function to print a warning but attempt to
  124. continue.
  125. </p></dd></dl>
  126. <dl>
  127. <dt><a name="index-avm_005fload"></a><u>Function:</u> list <b>avm_load</b><i> (FILE *<var>source</var>, char *<var>filename</var>, int <var>raw</var>)</i></dt>
  128. <dd><p>Similarly to <code>avm_preamble_and_contents</code>, this function also loads
  129. a file into memory, but the format is specified in advance.
  130. </p>
  131. <dl compact="compact">
  132. <dt> <code><var>source</var></code></dt>
  133. <dd><p>should be set by the caller to the address of an already open file for
  134. reading, which will be read from its current position.
  135. </p></dd>
  136. <dt> <code><var>filename</var></code></dt>
  137. <dd><p>should be initialized by the caller as a pointer to a null terminated
  138. string containing the name of the file that will be reported to the user
  139. in the event of an error reading from it. If it is a <code>NULL</code>
  140. pointer, standard input is assumed.
  141. </p></dd>
  142. <dt> <code><var>raw</var></code></dt>
  143. <dd><p>is set to a non-zero value by the caller to indicate that the file is
  144. expected to conform to the format in <a href="File-Format.html#File-Format">File Format</a>. If the file is
  145. an ordinary text file, then it should be set to zero.
  146. </p></dd>
  147. </dl>
  148. <p>In the case of a data file, which is when <code><var>raw</var></code> is non-zero,
  149. the result returned by this function will be a list representing the
  150. data section of the file and ignoring the preamble. In the case of a
  151. text file, the result will be a list of lists of character
  152. representations as per <a href="Character-Table.html#Character-Table">Character Table</a>, with one such list for
  153. each line in the file. Similar comments about line breaks to those
  154. mentioned under <code>avm_preamble_and_contents</code> are applicable.
  155. </p>
  156. <p>As a side effect of this function, the <code><var>source</var></code> file will be
  157. closed, unless the <code><var>filename</var></code> is a <code>NULL</code> pointer.
  158. </p>
  159. <p>This function is useful when the type of file is known in advance. If a
  160. data file is indicated by the <code><var>raw</var></code> parameter but the format
  161. is incorrect, an error message is reported and the process
  162. terminates. The error message will be of the form
  163. </p>
  164. <table><tr><td>&nbsp;</td><td><pre class="display"><code><var>program-name</var>: invalid raw file format in <var>filename</var></code>
  165. </pre></td></tr></table>
  166. <p>Alternatively, if a text file is indicated by the
  167. <a name="index-invalid-raw-file-format-2"></a>
  168. <code><var>raw</var></code> parameter, then no attempt is made to test whether it
  169. could be interpreted as data, even if it could be. This behavior differs
  170. from that of <code>avm_preamble_and_contents</code>, where a bad data
  171. file format causes the file to be treated as text, and a valid data file
  172. format, even in a &ldquo;text&rdquo; file, causes it to be treated as data.
  173. </p>
  174. <p>Memory requirements for this function are significant and will cause the
  175. process to abort with an error message in the event of insufficient free
  176. memory. Messages pertaining to i/o errors are also possible and are not
  177. fatal.
  178. </p></dd></dl>
  179. <dl>
  180. <dt><a name="index-avm_005finitialize_005fformin"></a><u>Function:</u> void <b>avm_initialize_formin</b><i> ()</i></dt>
  181. <dd><p>This function should be called before either of the other functions in
  182. this section is called, as it initializes some necessary static data
  183. structures. Results of the other functions are undefined if this one is
  184. not called first.
  185. </p></dd></dl>
  186. <dl>
  187. <dt><a name="index-avm_005fcount_005fformin"></a><u>Function:</u> void <b>avm_count_formin</b><i> ()</i></dt>
  188. <dd><p>This function should be called after the last call to any of the other
  189. functions in this section, as it is necessary for cleaning up and
  190. reclaiming some internal data. If any storage remains unreclaimed due to
  191. memory leaks in these functions or to misuse of them, a warning message
  192. is written to standard error. If the function <code>avm_count_lists</code> is
  193. also being used by the client program, it should be called after this
  194. one.
  195. </p></dd></dl>
  196. <hr size="1">
  197. <table cellpadding="1" cellspacing="1" border="0">
  198. <tr><td valign="middle" align="left">[<a href="Raw-Files.html#Raw-Files" title="Previous section in reading order"> &lt; </a>]</td>
  199. <td valign="middle" align="left">[<a href="Formatted-Output.html#Formatted-Output" title="Next section in reading order"> &gt; </a>]</td>
  200. <td valign="middle" align="left"> &nbsp; </td>
  201. <td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
  202. <td valign="middle" align="left">[<a href="File-Manipulation.html#File-Manipulation" title="Up section"> Up </a>]</td>
  203. <td valign="middle" align="left">[<a href="Character-Table.html#Character-Table" title="Next chapter"> &gt;&gt; </a>]</td>
  204. <td valign="middle" align="left"> &nbsp; </td>
  205. <td valign="middle" align="left"> &nbsp; </td>
  206. <td valign="middle" align="left"> &nbsp; </td>
  207. <td valign="middle" align="left"> &nbsp; </td>
  208. <td valign="middle" align="left">[<a href="avram.html#Top" title="Cover (top) of document">Top</a>]</td>
  209. <td valign="middle" align="left">[<a href="avram_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
  210. <td valign="middle" align="left">[<a href="Function-Index.html#Function-Index" title="Index">Index</a>]</td>
  211. <td valign="middle" align="left">[<a href="avram_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
  212. </tr></table>
  213. <p>
  214. <font size="-1">
  215. This document was generated on <i>November 8, 2012</i> using <a href="http://www.nongnu.org/texi2html/"><i>texi2html 1.82</i></a>.
  216. </font>
  217. <br>
  218. </p>
  219. </body>
  220. </html>