Characters-and-Strings.html 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301
  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.2 Characters and Strings</title>
  14. <meta name="description" content="avram - a virtual machine code interpreter: 3.2 Characters and Strings">
  15. <meta name="keywords" content="avram - a virtual machine code interpreter: 3.2 Characters and Strings">
  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="Characters-and-Strings"></a>
  40. <table cellpadding="1" cellspacing="1" border="0">
  41. <tr><td valign="middle" align="left">[<a href="The-Universal-Function.html#The-Universal-Function" title="Previous section in reading order"> &lt; </a>]</td>
  42. <td valign="middle" align="left">[<a href="File-Manipulation.html#File-Manipulation" 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="Library-Reference.html#Library-Reference" 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="Characters-and-Strings-1"></a>
  58. <h2 class="section">3.2 Characters and Strings</h2>
  59. <a name="index-character-strings-4"></a>
  60. <p>If a C program is to interact with a virtual code application by
  61. exchanging text, it uses the representation for characters described in
  62. <a href="Character-Table.html#Character-Table">Character Table</a>. This convention would be inconvenient without a
  63. suitable API, so the functions in this section address the need. These
  64. functions are declared in the header file &lsquo;<tt>chrcodes.h</tt>&rsquo;.
  65. </p>
  66. <p>Some of these functions have two forms, with one of them having the
  67. word <code>standard</code> as part of its name. The reason is to cope with
  68. multiple character encodings. Versions of <code>avram</code> prior to 0.1.0
  69. <a name="index-character-encodings"></a>
  70. <a name="index-multiple-character-encodings"></a>
  71. used a different character encoding than the one documented in
  72. <a href="Character-Table.html#Character-Table">Character Table</a>. The functions described in <a href="Version-Management.html#Version-Management">Version Management</a> can be used to select backward compatible operation with
  73. the older character encoding. The normal forms of the functions in
  74. this section will use the older character set if a backward
  75. compatibility mode is indicated, whereas the standard forms will use
  76. the character encoding documented in <a href="Character-Table.html#Character-Table">Character Table</a> regardless.
  77. </p>
  78. <p>Standard encodings should always be assumed for library and function
  79. <a name="index-standard-character-encoding"></a>
  80. names associated with the <code>library</code> combinator (<a href="Calling-existing-library-functions.html#Calling-existing-library-functions">Calling existing library functions</a>), and for values of lists defined by
  81. <code>avm_list_of_value</code> (<a href="Primitive-types.html#Primitive-types">Primitive types</a>), but version
  82. dependent encodings should be used for all other purposes such as
  83. error messages. Alternatively, the normal version dependent forms of
  84. the functions below can be used safely in any case if backward
  85. <a name="index-backward-compatability"></a>
  86. compatibility is not an issue. This distinction is viewed as a
  87. transitional feature of the API that will be discontinued eventually
  88. when support for the old character set is withdrawn and the
  89. <code>standard</code> forms are be removed.
  90. </p>
  91. <dl>
  92. <dt><a name="index-avm_005fcharacter_005frepresentation"></a><u>Function:</u> list <b>avm_character_representation</b><i> (int <var>character</var>)</i></dt>
  93. </dl>
  94. <dl>
  95. <dt><a name="index-avm_005fstandard_005fcharacter_005frepresentation"></a><u>Function:</u> list <b>avm_standard_character_representation</b><i> (int <var>character</var>)</i></dt>
  96. <dd><p>This function takes an integer character code and returns a copy of
  97. the list representing it, as per the table in <a href="Character-Table.html#Character-Table">Character Table</a>. Because the copy is shared, no memory is allocated by this
  98. function so there is no possibility of overflow. Nevertheless, it is
  99. the responsibility of the caller dispose of the list when it is no
  100. longer needed by <code>avm_dispose</code>, just as if the copy were not
  101. shared (<a href="Simple-Operations.html#Simple-Operations">Simple Operations</a>). For performance reasons, this
  102. function is implemented as a macro. If the argument is outside the
  103. range of zero to 255, it is masked into that range.
  104. </p></dd></dl>
  105. <dl>
  106. <dt><a name="index-avm_005fcharacter_005fcode"></a><u>Function:</u> int <b>avm_character_code</b><i> (list <var>operand</var>)</i></dt>
  107. </dl>
  108. <dl>
  109. <dt><a name="index-avm_005fstandard_005fcharacter_005fcode"></a><u>Function:</u> int <b>avm_standard_character_code</b><i> (list <var>operand</var>)</i></dt>
  110. <dd><p>This function takes a list as an argument and returns the corresponding
  111. character code, as per <a href="Character-Table.html#Character-Table">Character Table</a>. If the argument does not
  112. represent any character, a value of <code>-1</code> is returned.
  113. </p></dd></dl>
  114. <dl>
  115. <dt><a name="index-avm_005fstrung"></a><u>Function:</u> list <b>avm_strung</b><i> (char *<var>string</var>)</i></dt>
  116. </dl>
  117. <dl>
  118. <dt><a name="index-avm_005fstandard_005fstrung"></a><u>Function:</u> list <b>avm_standard_strung</b><i> (char *<var>string</var>)</i></dt>
  119. <dd><p>This function takes a pointer to a null terminated character string and
  120. returns the list obtained by translating each character into its list
  121. representation and enqueuing them together. Memory needs to be allocated
  122. for the result, and if there isn&rsquo;t enough available, an error message is
  123. written to standard error and the process is terminated. This function
  124. is useful to initialize lists from hard coded strings at the beginning
  125. of a run, as in this example.
  126. </p>
  127. <table><tr><td>&nbsp;</td><td><pre class="example">hello_string = avm_strung(&quot;hello&quot;);
  128. </pre></td></tr></table>
  129. <p>This form initializes a single string, but to initialize a one line
  130. message suitable for writing to a file, it would have to be a list of
  131. strings, as in this example.
  132. </p>
  133. <table><tr><td>&nbsp;</td><td><pre class="example">hello_message = avm_join(avm_strung(&quot;hello&quot;),NULL);
  134. </pre></td></tr></table>
  135. <p>The latter form is used internally by the library for initializing
  136. most of the various error messages that can be returned by other functions.
  137. </p></dd></dl>
  138. <dl>
  139. <dt><a name="index-avm_005frecoverable_005fstrung"></a><u>Function:</u> list <b>avm_recoverable_strung</b><i> (char *<var>string</var>, int *<var>fault</var>);</i></dt>
  140. </dl>
  141. <dl>
  142. <dt><a name="index-avm_005frecoverable_005fstandard_005fstrung"></a><u>Function:</u> list <b>avm_recoverable_standard_strung</b><i> (char *<var>string</var>, int *<var>fault</var>);</i></dt>
  143. <dd><p>This function is like <code>avm_strung</code> except that if it runs out of memory
  144. it sets the integer referenced by <var>fault</var> to a non-zero value and returns
  145. instead of terminating the process.
  146. </p></dd></dl>
  147. <dl>
  148. <dt><a name="index-_002aavm_005funstrung"></a><u>Function:</u> char <b>*avm_unstrung</b><i> (list <var>string</var>, list *<var>message</var>, int *<var>fault</var>)</i></dt>
  149. </dl>
  150. <dl>
  151. <dt><a name="index-_002aavm_005fstandard_005funstrung"></a><u>Function:</u> char <b>*avm_standard_unstrung</b><i> (list <var>string</var>, list *<var>message</var>, int *<var>fault</var>)</i></dt>
  152. <dd><p>This function performs an inverse operation to
  153. <code>avm_recoverable_strung</code>, taking a list representing a character
  154. string to the character string in ASCII null terminated form as per
  155. the standard C representation. Memory is allocated for the result by
  156. this function which should be freed by the caller.
  157. </p>
  158. <p>In the event of an exception, the integer referenced by <code>fault</code>
  159. is assigned a non-zero value and an error message represented as a
  160. list is assigned to the list referenced by <code>message</code>. The error
  161. message should be reclaimed by the caller with <code>avm_dispose</code>
  162. (<a href="Simple-Operations.html#Simple-Operations">Simple Operations</a> if it is non-empty. Possible error messages
  163. are <code>&lt;'memory overflow'&gt;</code>, <code>&lt;'counter overflow'&gt;</code>, and
  164. <code>&lt;'invalid text format'&gt;</code>.
  165. </p></dd></dl>
  166. <dl>
  167. <dt><a name="index-avm_005fscanned_005flist"></a><u>Function:</u> list <b>avm_scanned_list</b><i> (char *<var>string</var>)</i></dt>
  168. <dd><p>An application that makes use of virtual code snippets or data that are
  169. known at compile time can use this function to initialize them. The
  170. argument is a string in the format described in <a href="Concrete-Syntax.html#Concrete-Syntax">Concrete Syntax</a>,
  171. and the result is the list representing it. For example, the program
  172. discussed in <a href="Example-Script.html#Example-Script">Example Script</a> could be hard coded into a C program
  173. by pasting the data from its virtual code file into an expression of
  174. this form.
  175. </p>
  176. <table><tr><td>&nbsp;</td><td><pre class="example">cat_program = avm_scanned_list(&quot;sKYQNTP\\&quot;);
  177. </pre></td></tr></table>
  178. <p>Note that the backslash character in the original data has to be
  179. preceded by an extra backslash in the C source, because backslashes
  180. usually mean something in C character constants.
  181. </p>
  182. <p>The <code>avm_scanned_list</code> function needs to allocate memory. If there
  183. isn&rsquo;t enough memory available, it writes a message to standard error and
  184. causes the process to exit.
  185. </p></dd></dl>
  186. <dl>
  187. <dt><a name="index-avm_005fmultiscanned"></a><u>Function:</u> list <b>avm_multiscanned</b><i> (char **<var>strings</var>)</i></dt>
  188. <dd><p>Sometimes it may be useful to initialize very large lists from
  189. strings, but some C compilers impose limitations on the maximum length
  190. of a string constant, and the ISO standard for C requires only 512
  191. bytes. This function serves a similar purpose to
  192. <code>avm_scanned_list</code>, but allows the argument to be a pointer to a
  193. null terminated array of strings instead of one long string, thereby
  194. circumventing this limitation in the compiler.
  195. </p>
  196. <table><tr><td>&nbsp;</td><td><pre class="example">char *code[] = {&quot;sKYQ&quot;,&quot;NTP\\&quot;,NULL};
  197. ...
  198. cat_program = avm_multiscanned(code);
  199. </pre></td></tr></table>
  200. <p>If there is insufficient memory to allocate the list this function needs
  201. to create, it causes an error message to be written to standard error,
  202. and then kills the process.
  203. </p></dd></dl>
  204. <dl>
  205. <dt><a name="index-avm_005fprompt"></a><u>Function:</u> char* <b>avm_prompt</b><i> (list <var>prompt_strings</var>)</i></dt>
  206. <dd><p>This function takes a list representing a list of character strings, and
  207. returns its translation to a character string with the sequence 13 10
  208. used as a separator. For example, given a tree of this form
  209. </p>
  210. <table><tr><td>&nbsp;</td><td><pre class="example">some_message = avm_join(
  211. avm_strung(&quot;hay&quot;),
  212. avm_join(
  213. avm_strung(&quot;you&quot;),
  214. NULL));
  215. </pre></td></tr></table>
  216. <p>the result returned by <code>prompt_strings(some_message)</code> would be a
  217. pointer to a null terminated character string equivalent to the C constant
  218. <code>&quot;hay\13\10you&quot;</code>.
  219. </p>
  220. <p>Error messages are printed and the process terminated in the event of
  221. either a memory overflow or an invalid character representation.
  222. </p>
  223. <p>This function is used by <code>avram</code> in the evaluation of interactive
  224. <a name="index-interactive-applications-2"></a>
  225. virtual code applications, whose output has to be compared to the output
  226. from a shell command in this format. The separator is chosen to be
  227. compatible with the <code>expect</code> library.
  228. </p></dd></dl>
  229. <dl>
  230. <dt><a name="index-avm_005frecoverable_005fprompt"></a><u>Function:</u> char* <b>avm_recoverable_prompt</b><i> (list <var>prompt_strings</var>, list *<var>message</var>, int *<var>fault</var>)</i></dt>
  231. <dd><p>This function performs the same operation as <code>avm_prompt</code> but
  232. allows the caller to handle exceptional conditions. If an exception
  233. such as a memory overflow occurs, the integer referenced by
  234. <code>fault</code> is assigned a non-zero value and a representation of the
  235. error message as a list of strings is assigned to the list referenced
  236. by <code>message</code>.
  237. </p>
  238. <p>This function is used to by <code>avram</code> to evaluate the
  239. <code>interact</code> combinator (<a href="Interaction-combinator.html#Interaction-combinator">Interaction combinator</a>), when
  240. terminating in the event of an error would be inappropriate.
  241. </p></dd></dl>
  242. <dl>
  243. <dt><a name="index-avm_005finitialize_005fchrcodes"></a><u>Function:</u> void <b>avm_initialize_chrcodes</b><i> ()</i></dt>
  244. <dd><p>This function has to be called before any of the other character
  245. conversion functions in this section, or else their results are
  246. undefined. It performs the initialization of various internal data
  247. structures.
  248. </p></dd></dl>
  249. <dl>
  250. <dt><a name="index-avm_005fcount_005fchrcodes"></a><u>Function:</u> void <b>avm_count_chrcodes</b><i> ()</i></dt>
  251. <dd><p>This function can be called at the end of a run, after the last call to
  252. any of the other functions in this section, but before
  253. <code>avm_count_lists</code> if that function is also being used. The purpose
  254. of this function is to detect and report memory leaks. If any memory
  255. associated with any of these functions has not been reclaimed by the
  256. client program, a message giving the number of unreclaimed lists will be
  257. written to standard error.
  258. </p></dd></dl>
  259. <hr size="1">
  260. <table cellpadding="1" cellspacing="1" border="0">
  261. <tr><td valign="middle" align="left">[<a href="The-Universal-Function.html#The-Universal-Function" title="Previous section in reading order"> &lt; </a>]</td>
  262. <td valign="middle" align="left">[<a href="File-Manipulation.html#File-Manipulation" title="Next section in reading order"> &gt; </a>]</td>
  263. <td valign="middle" align="left"> &nbsp; </td>
  264. <td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
  265. <td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Up section"> Up </a>]</td>
  266. <td valign="middle" align="left">[<a href="Character-Table.html#Character-Table" title="Next chapter"> &gt;&gt; </a>]</td>
  267. <td valign="middle" align="left"> &nbsp; </td>
  268. <td valign="middle" align="left"> &nbsp; </td>
  269. <td valign="middle" align="left"> &nbsp; </td>
  270. <td valign="middle" align="left"> &nbsp; </td>
  271. <td valign="middle" align="left">[<a href="avram.html#Top" title="Cover (top) of document">Top</a>]</td>
  272. <td valign="middle" align="left">[<a href="avram_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
  273. <td valign="middle" align="left">[<a href="Function-Index.html#Function-Index" title="Index">Index</a>]</td>
  274. <td valign="middle" align="left">[<a href="avram_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
  275. </tr></table>
  276. <p>
  277. <font size="-1">
  278. This document was generated on <i>November 8, 2012</i> using <a href="http://www.nongnu.org/texi2html/"><i>texi2html 1.82</i></a>.
  279. </font>
  280. <br>
  281. </p>
  282. </body>
  283. </html>