home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1994 January / usenetsourcesnewsgroupsinfomagicjanuary1994.iso / sources / misc / volume10 / spew / manual.spew < prev    next >
Encoding:
Text File  |  1990-02-13  |  4.4 KB  |  158 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.     COMMENTS:
  148.  
  149. At any point, '\*' may appear on a line and the rest of the line
  150. is ignored. Blank lines are ignored completely ( as are lines
  151. beginning in \* ).
  152. Empty instances must therefore be given an explicit weight of one:
  153.  
  154. %AllOrNothing\*    50% chance, 'All', or nothing.
  155. All
  156. (1)
  157.  
  158.