Formatted-Output.html 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320
  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.4 Formatted Output</title>
  14. <meta name="description" content="avram - a virtual machine code interpreter: 3.3.4 Formatted Output">
  15. <meta name="keywords" content="avram - a virtual machine code interpreter: 3.3.4 Formatted Output">
  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-Output"></a>
  40. <table cellpadding="1" cellspacing="1" border="0">
  41. <tr><td valign="middle" align="left">[<a href="Formatted-Input.html#Formatted-Input" title="Previous section in reading order"> &lt; </a>]</td>
  42. <td valign="middle" align="left">[<a href="Invocation.html#Invocation" 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-Output-1"></a>
  58. <h3 class="subsection">3.3.4 Formatted Output</h3>
  59. <p>The following functions pertaining to the output of text files or data files with
  60. <a name="index-preamble-7"></a>
  61. preambles are declared in the header file &lsquo;<tt>formout.h</tt>&rsquo;.
  62. </p><dl>
  63. <dt><a name="index-avm_005foutput"></a><u>Function:</u> void <b>avm_output</b><i> (FILE *<var>repository</var>, char *<var>filename</var>, list <var>preamble</var>, list <var>contents</var>, int <var>trace_mode</var>)</i></dt>
  64. <dd>
  65. <p>This function writes a either a text file or a data file in the format
  66. described in <a href="File-Format.html#File-Format">File Format</a>. The parameters have these
  67. interpretations.
  68. </p>
  69. <dl compact="compact">
  70. <dt> <code><var>repository</var></code></dt>
  71. <dd><p>is the address of a file opened for writing by the caller, that will be
  72. written from its current position.
  73. </p></dd>
  74. <dt> <code><var>filename</var></code></dt>
  75. <dd><p>is the address of a null terminated character string set
  76. by the caller to be the name of the file that will
  77. be reported to the user in the event of an i/o error.
  78. </p></dd>
  79. <dt> <code><var>preamble</var></code></dt>
  80. <dd><p>is <code>NULL</code> in the case of a text file, but a list of character string
  81. representations as per <a href="Character-Table.html#Character-Table">Character Table</a>, in the case of a data
  82. file. If a data file has is to be written with an empty preamble, then
  83. this list should have a <code>NULL</code> <code>head</code> and a <code>NULL</code>
  84. <code>tail</code>.
  85. </p></dd>
  86. <dt> <code><var>contents</var></code></dt>
  87. <dd><p>is either a list of character string representations in the case of a
  88. text file, or is an unconstrained list in the case of a data file.
  89. </p></dd>
  90. <dt> <code><var>trace_mode</var></code></dt>
  91. <dd><p>may be set to a non-zero value by the caller to request that everything
  92. written to a text file should be echoed to standard output. It is
  93. ignored in the case of a data file.
  94. </p></dd>
  95. </dl>
  96. <p>The effect of calling this function is to write the preamble and
  97. contents to the file in the format indicated by the preamble. The file
  98. is left open when this function returns.
  99. </p>
  100. <p>Line breaks are always written as character code 10, not as 13 10,
  101. <a name="index-line-breaks-2"></a>
  102. regardless of the convention on the host system, so that files written
  103. by this function can be reliably read by other functions in the library.
  104. </p>
  105. <p>Leading hashes are automatically added to the beginning of the lines in
  106. the preamble, except where they are unnecessary due to a continuation
  107. character on the previous line. This action enforces consistency with the
  108. file format, ensuring that anything written as a data file can be read
  109. back as one. The hashes are stripped automatically when the file is
  110. read by <code>avm_preamble_and_contents</code>.
  111. </p>
  112. <p>Another feature of this function is that it will mark any output file as
  113. executable if it is a data format file with a prelude whose first
  114. <a name="index-executable-files-1"></a>
  115. character in the first line is an exclamation point. This feature makes
  116. it easier for a compiler implemented in virtual code to generate
  117. executable shell scripts directly.
  118. </p>
  119. <p>A fatal error is reported if any of the data required
  120. to be a character representation is not listed in the <a href="Character-Table.html#Character-Table">Character Table</a>. A fatal error can also be caused by a memory overflow. Possible
  121. error messages are the following.
  122. <a name="index-invalid-output-preamble-format-1"></a>
  123. <a name="index-invalid-text-format-1"></a>
  124. <a name="index-can_0027t-write-2"></a>
  125. </p>
  126. <ul>
  127. <li> <code><var>program-name</var>: invalid output preamble format</code>
  128. </li><li> <code><var>program-name</var>: invalid text format</code>
  129. </li><li> <code><var>program-name</var>: can't write to <var>filename</var></code>
  130. </li></ul>
  131. <a name="index-strerror-2"></a>
  132. <p>In the last case, the error message will be followed by an explanation
  133. furnished by the standard <code>strerror</code> function if available.
  134. </p></dd></dl>
  135. <dl>
  136. <dt><a name="index-avm_005foutput_005fas_005fdirected"></a><u>Function:</u> void <b>avm_output_as_directed</b><i> (list <var>data</var>, int <var>ask_to_overwrite_mode</var>, int <var>verbose_mode</var>)</i></dt>
  137. <dd><p>This function writes an ensemble of files at specified paths in either
  138. text or data format, optionally interacting with the user through
  139. standard input and output. The parameters
  140. have these interpretations.
  141. </p>
  142. <dl compact="compact">
  143. <dt> <code><var>data</var></code></dt>
  144. <dd><p>is a list in which each item specifies a file to be
  145. written.
  146. </p></dd>
  147. <dt> <code><var>ask_to_overwrite_mode</var></code></dt>
  148. <dd><p>may be set to a non-zero value by the calling program in order to
  149. have this function ask the user for permission to overwrite existing files.
  150. </p></dd>
  151. <dt> <code><var>verbose_mode</var></code></dt>
  152. <dd><p>may be set to a non-zero value by the calling program to have this
  153. function print to standard output a list of the names of the files it
  154. writes.
  155. </p></dd>
  156. </dl>
  157. <p>A high level interface between virtual code applications and the file
  158. system is provided by this function. The <code><var>data</var></code> parameter
  159. format is compatible with the the data structure returned by an
  160. application complying with the conventions in <a href="Output-From-Non_002dinteractive-Applications.html#Output-From-Non_002dinteractive-Applications">Output From Non-interactive Applications</a>.
  161. </p>
  162. <p>Each item in the <code><var>data</var></code> list should be a non-empty list whose
  163. <code>head</code> and <code>tail</code> are also non-empty. The fields in each item have
  164. the following relevance to the file it specifies.
  165. </p>
  166. <ul>
  167. <li> The <code>head</code> of the <code>head</code> is <code>NULL</code> if the file is
  168. to be opened for appending, and non-<code>NULL</code> if it is to be
  169. overwritten.
  170. </li><li> The <code>tail</code> of the <code>head</code> represents a path as a list of
  171. character string representations, in a form suitable as an argument to
  172. <code>avm_path_name</code>.
  173. </li><li> The <code>head</code> of the <code>tail</code> represents the preamble of the
  174. file, as either <code>NULL</code> for a text file or a non-empty list of
  175. character string representations for a data file.
  176. </li><li> The <code>tail</code> of the <code>tail</code> represents the contents of the
  177. file, either as a list of character string representations for a text
  178. file or as a list in an unconstrained format for a data file.
  179. </li></ul>
  180. <p>For each item in the list, the function performs the following steps.
  181. </p><ol>
  182. <li> It decides whether to open a file
  183. for overwriting or appending based on the <code>head</code> of the
  184. <code>head</code>.
  185. </li><li> It uses the <code>tail</code> of the <code>head</code> to find out the
  186. file name from <code>avm_path_name</code>, in order to open it.
  187. </li><li> If the
  188. <code><var>ask_to_overwrite_mode</var></code> flag is set and the file is found to
  189. exist already, the function will print one of the following messages to
  190. standard output, depending on whether the file is to be overwritten or
  191. appended.
  192. <ul>
  193. <li> <code><var>program-name</var>: overwrite <var>filename</var>? (y/n)</code>
  194. </li><li> <code><var>program-name</var>: append to <var>filename</var>? (y/n)</code>
  195. </li></ul>
  196. <p>It will then insist on either <kbd>y</kbd> or <kbd>n</kbd> as an answer before continuing.
  197. </p></li><li> If the <code><var>ask_to_overwrite</var></code> flag has not been set, or the file did
  198. not previously exist, or the answer of <kbd>y</kbd> was given, the preamble
  199. and contents of the file are then written with <code>avm_output</code>.
  200. </li><li> If permission to write or append was denied, one of the following
  201. messages is reported to standard output, and the data that were to be
  202. written are lost.
  203. <a name="index-not-writing-file-name"></a>
  204. <a name="index-writing-file-name"></a>
  205. <ul>
  206. <li> <code><var>program-name</var>: not writing <var>filename</var></code>
  207. </li><li> <code><var>program-name</var>: not appending <var>filename</var></code>
  208. </li></ul>
  209. </li><li> If permission was granted to write or append to the file or the <code><var>verbose_mode</var></code> flag is
  210. set, one of the messages
  211. <ul>
  212. <li> <code><var>program-name</var>: writing <var>filename</var></code>
  213. </li><li> <code><var>program-name</var>: appending <var>filename</var></code>
  214. </li></ul>
  215. <p>is sent to standard output.
  216. </p></li></ol>
  217. <a name="index-standard-output-5"></a>
  218. <p>If any files are to be written to standard output, which would be
  219. indicated by a <code>NULL</code> path, they are not written until all other
  220. files in the list are written. This feature is in the interest of
  221. <a name="index-security-1"></a>
  222. security, as it makes it more difficult for malicious or inept virtual
  223. code to alter the appearance of the console through standard output until after
  224. the interactive dialogue has taken place. Permission is not solicited
  225. for writing to standard output, and it will not be closed.
  226. </p>
  227. <p>Any of the fatal errors or i/o errors possible with <code>avm_output</code> or
  228. <code>avm_path_name</code> are also possible with this function, as well as
  229. the following additional ones.
  230. <a name="index-invalid-file-specification-1"></a>
  231. <a name="index-can_0027t-close-1"></a>
  232. <a name="index-can_0027t-write-3"></a>
  233. </p>
  234. <ul>
  235. <li> <code><var>program-name</var>: invalid file specification</code>
  236. </li><li> <code><var>program-name</var>: can't close <var>filename</var></code>
  237. </li><li> <code><var>program-name</var>: can't write <var>filename</var></code>
  238. </li></ul>
  239. <p>The last two are non-fatal i/o errors that will be accompanied by an
  240. <a name="index-strerror-3"></a>
  241. explanation from the <code>strerror</code> function if the host supports
  242. it. The other message is the result of a badly formatted
  243. <code><var>data</var></code> parameter.
  244. </p>
  245. </dd></dl>
  246. <dl>
  247. <dt><a name="index-avm_005fput_005fbytes"></a><u>Function:</u> void <b>avm_put_bytes</b><i> (list <var>bytes</var>)</i></dt>
  248. <dd>
  249. <p>This function takes a list of character representations, converts them
  250. to characters, and sends them to standard output. There is no chance of
  251. a memory overflow, but the following other errors are possible.
  252. <a name="index-invalid-text-format-2"></a>
  253. <a name="index-can_0027t-write-4"></a>
  254. </p>
  255. <ul>
  256. <li> <code><var>program-name</var>: invalid text format (code <var>nn</var>)</code>
  257. </li><li> <code><var>program-name</var>: can't write to standard output</code>
  258. </li></ul>
  259. <p>The latter is non-fatal, but the former causes the program to abort.
  260. It is caused when any member of the list <code><var>bytes</var></code> is not a
  261. character representation appearing in <a href="Character-Table.html#Character-Table">Character Table</a>.
  262. </p></dd></dl>
  263. <dl>
  264. <dt><a name="index-avm_005finitialize_005fformout"></a><u>Function:</u> void <b>avm_initialize_formout</b><i> ()</i></dt>
  265. <dd><p>This function initializes some data structures used locally by the other
  266. functions in this section, and should be called at the beginning of a
  267. run before any of them is called.
  268. </p></dd></dl>
  269. <dl>
  270. <dt><a name="index-avm_005fcount_005fformout"></a><u>Function:</u> void <b>avm_count_formout</b><i> ()</i></dt>
  271. <dd><p>This function doesn&rsquo;t do anything in the current version of the library,
  272. but should be called after the last call to any of the other functions
  273. in this section. Future versions of the library might use this function
  274. for cleaning up some internal data structures, and client programs that
  275. call it will maintain compatibility with them.
  276. </p></dd></dl>
  277. <hr size="1">
  278. <table cellpadding="1" cellspacing="1" border="0">
  279. <tr><td valign="middle" align="left">[<a href="Formatted-Input.html#Formatted-Input" title="Previous section in reading order"> &lt; </a>]</td>
  280. <td valign="middle" align="left">[<a href="Invocation.html#Invocation" title="Next section in reading order"> &gt; </a>]</td>
  281. <td valign="middle" align="left"> &nbsp; </td>
  282. <td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
  283. <td valign="middle" align="left">[<a href="File-Manipulation.html#File-Manipulation" title="Up section"> Up </a>]</td>
  284. <td valign="middle" align="left">[<a href="Character-Table.html#Character-Table" title="Next chapter"> &gt;&gt; </a>]</td>
  285. <td valign="middle" align="left"> &nbsp; </td>
  286. <td valign="middle" align="left"> &nbsp; </td>
  287. <td valign="middle" align="left"> &nbsp; </td>
  288. <td valign="middle" align="left"> &nbsp; </td>
  289. <td valign="middle" align="left">[<a href="avram.html#Top" title="Cover (top) of document">Top</a>]</td>
  290. <td valign="middle" align="left">[<a href="avram_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
  291. <td valign="middle" align="left">[<a href="Function-Index.html#Function-Index" title="Index">Index</a>]</td>
  292. <td valign="middle" align="left">[<a href="avram_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
  293. </tr></table>
  294. <p>
  295. <font size="-1">
  296. This document was generated on <i>November 8, 2012</i> using <a href="http://www.nongnu.org/texi2html/"><i>texi2html 1.82</i></a>.
  297. </font>
  298. <br>
  299. </p>
  300. </body>
  301. </html>