home *** CD-ROM | disk | FTP | other *** search
/ Source Code 1992 March / Source_Code_CD-ROM_Walnut_Creek_March_1992.iso / usenet / altsrcs / 1 / 1654 / manual < prev    next >
Text File  |  1990-12-28  |  5KB  |  187 lines
  1. INPUT FILE FORMAT:
  2.  
  3. The file is a series of class definitions followed by an end
  4. marker. The end marker is a line containing only "%%".
  5.  
  6. A class definition begins with a line containing '%' followed by a class
  7. name. Class names can be any length and can consist of any combination
  8. of upper and lower case letters, and numbers.
  9.  
  10. The lines following are instances of the class, one per line. When a
  11. class is invoked, one of these is picked at random. Most characters in
  12. the line are just copied to the output. The newline at the end is not
  13. copied. An instance may be continued onto the next line by ending the
  14. line with '\'. There is a limit of 1000 bytes on the total size of an
  15. instance.  An instance may begin with '%' if it is escaped: '\%'. A
  16. newline may be written as '\!'. A backslash may be written as '\\'.
  17.  
  18. The following is a simple rules-file that prints out either 'foo'
  19. or bar, followed by a carriage-return:
  20.  
  21. %MAIN
  22. foo\!
  23. bar\!
  24. %%
  25.  
  26. The program generates a random instance of the class 'MAIN', which in
  27. this case selects 'foo' or 'bar', with a 50-50 chance. A newline is
  28. appended.
  29.  
  30.     WEIGHTS
  31.  
  32. To give 'foo' a 90% chance of happening, you can assign weights:
  33.  
  34. %MAIN
  35. (9)foo\!
  36. bar\!
  37. %%
  38.  
  39. The weight of 'bar' is 1 by default. If an instance is to begin with '('
  40. it must be escaped, or given an explicit weight:
  41.  
  42. \(animal)
  43. (1)(vegetable)
  44.  
  45.     INVOCATION
  46.  
  47. Classes are normally invoked by writing their name immediately after a
  48. backslash. Below is a rules-file which is equivalent to the foo-bar
  49. example:
  50.  
  51. %MAIN
  52. \word\!
  53. %word
  54. (9)foo
  55. bar
  56. %%
  57.  
  58. In this case, the class 'word' outputs either 'foo' or 'bar', and
  59. the newline is appended after the invocation in 'MAIN'.
  60.  
  61. If you wish to immediately follow a class invokation by a letter or a number,
  62. you must write it followed by a slash and a space:
  63.  
  64. %MAIN
  65. \word/ bar\!
  66. %word
  67. foo
  68. bar
  69. %%
  70.  
  71. The above outputs either 'foobar' or 'barbar'. This method must also
  72. be used if the invokation is to be immediately followed by a slash.
  73.  
  74.     VARIANTS
  75.  
  76. A class may be defined with variants, and may then be invoked with
  77. variants. The 's' variant defined for the 'fruit' class below
  78. allows correct plurals to be generated:
  79.  
  80. %fruit{s}
  81. apple{|s}
  82. cherr{y|ies}
  83. pear{|s}
  84. mango{|es}
  85. %MAIN
  86. One \fruit and two \fruit/s.\!
  87. %%
  88.  
  89. The variant tag is a single letter or number. In an invocation, the
  90. class name is followed by a slash which is followed by the tag. Every
  91. class has a 'null' variant (tagged by a space) by default (thus the "/ "
  92. notation).
  93.  
  94. In the class definition line, the class name is followed by a list
  95. of variant tags in curly brackets. The order of the tags is
  96. significant.
  97.  
  98. In an instance definition, variants may be created with the following
  99. notation:
  100.     { <null-variant-text> | <1st-variant-text> | <2nd-variant-text }
  101.  
  102. When a class is invoked with a null tag, or with a blank tag, the
  103. text before the first '|' is used. If the first tag is used in the
  104. invocation (i.e. the first tag listed in {}'s in the class definition),
  105. the text between the first and second |'s is used, and so forth.  All
  106. text not in {}'s is copied regardless of the tag used.
  107.  
  108. There are normally as many |'s in these as there are tags defined.
  109. If there are too many tags, the excess ones select null strings, and
  110. if there are too many |'s, the excess strings are redundant.
  111.  
  112. The '{' character, if required literally,  must always be escaped
  113. outside the selector construction: '\{', even when no variants are
  114. defined in a class. The '|' and '}' characters must likewise be
  115. escaped inside a constructor.
  116.  
  117. Invocations may appear in a selector, but cannot span a selector.
  118. I.e. you cannot select between invoking 'catwalk' and 'catfish' by
  119.  
  120.     \cat{walk|fish}
  121.  
  122. You must use {\catwalk|\catfish}.
  123.  
  124. Finally, there is the & tag which may be used in an invocation and
  125. selects the same tag letter (or number) which the invoking
  126. class was invoked with:
  127.  
  128. %food{s}
  129. \fruit/&            <--- this is the same as
  130. {\fruit|\fruit/s}        <--- this.
  131.  
  132. MAIN is initially invoked with the null tag (although it can be invoked
  133. recursively with other tags).
  134.  
  135. Here is a class with multiple tags that generates irregular verbs:
  136.  
  137. %verb{sd}
  138. {eat|eats|ate}
  139. {be|is|was}
  140. {see|sees|saw}
  141. look{|s|ed}
  142. f{ind|inds|ound}
  143. %%
  144.  
  145. Thus \verb/d generates a past-tense verb.
  146.  
  147.      PRUNING
  148.  
  149. There is one "special" pseudo-class, PRUNE. When PRUNE is invoked, no
  150. more output is generated on that line, and control immediately reverts
  151. to the *end* of the last class invoked whose name ended with an '!'.
  152. This is useful when a certain series of choices can suddenly end
  153. the phrase or whatever (such as an abrupt, "startler" terminator to a
  154. joke). Currently prunestops (those classes ending with an '!' which
  155. stop the backtracking after a \PRUNE) can not be nested; a \PRUNE after
  156. an inner prunestop has been exited will cause an error message. This
  157. should probably be fixed sometime, as well as making the prunestop
  158. specification more elegant. Example:
  159.  
  160. %MAIN
  161. Joe got sick, \THENWHAT!/ .
  162. %THENWHAT!
  163. \MIDDLE \CONVALESCE
  164. %MIDDLE
  165. was sick for a while,
  166. ate some magic herbs,
  167. and died\PRUNE
  168. %CONVALESCE
  169. then got better.
  170. and recovered.
  171. %%
  172.  
  173.   In this case, if "and died" is chosen, text generation will resume
  174. immediately after \THENWHAT!/ , producing "Joe got sick, and died.".
  175.  
  176.     COMMENTS:
  177.  
  178. At any point, '\*' may appear on a line and the rest of the line
  179. is ignored. Blank lines are ignored completely ( as are lines
  180. beginning in \* ).
  181. Empty instances must therefore be given an explicit weight of one:
  182.  
  183. %AllOrNothing\*    50% chance, 'All', or nothing.
  184. All
  185. (1)
  186.  
  187.