home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload / ShartewareOverload.cdr / wp / lancelot.zip / LANCEANA.DOC < prev    next >
Text File  |  1984-11-04  |  16KB  |  440 lines
  1.         Lancelot documentation for programming the analyzer
  2.         ---------------------------------------------------
  3.  
  4.      Lancelot analyzes languge by interpreting commands given in an
  5. analysis file.  The commands are called actions which have a particular form.
  6. Each action starts with a word, called a dot-dot command e.g.,  ..WORD,
  7. followed by a print message and then followed by one or more elements as
  8. defined below.
  9.  
  10.      Several sample (and useful) analysis files are included with Lancelot,
  11. and typical usage should be inferred from reading them.  They do not all use
  12. all of the options of Lancelot, and so are not a substitute for reading this
  13. documentation.
  14.  
  15.      The commands are given below in alphabetical order.  Occasionally
  16. there are common points between the commands, and they are discussed in a note
  17. to the reader.  The syntactic form of a command is followed by the semantics
  18. of the command.
  19.  
  20.  
  21.  
  22.                              Definitions
  23.  
  24. Print messages
  25.  
  26.      Print messages contain an arbitrary number of text lines which may or
  27. may not be printed depending upon where it appears in an action.  A print
  28. message begins on a line that starts with a colon, and continues to the next
  29. line that starts with a dot or colon.  Print messages may contain variables
  30. whose value will be substituted when the message is printed.
  31.  
  32.      Occasionally you may wish to print nothing in a print message.  You
  33. may accomplish that using the following print message which is called the
  34. empty print message:
  35.  
  36. :.
  37.  
  38.      Blank lines before a print message are ignored, while blank lines
  39. after a print message are included in the print message.  This happens
  40. because print messages do not stop until the next dot or dot-dot command.
  41.  
  42.  
  43. Variables
  44.  
  45.      Variables are words that start with a sharp sign (#).  Lancelot
  46. defines a number of variables that are set by various dot-dot commands.  The
  47. value that the variable takes on is described below with the dot-dot command
  48. that sets the variable.  You may define your own variables using the ..CALC
  49. command.  These variables may be used in the same manner as Lancelot's
  50. variables.  Lancelot's variables are all uppercase to make them stand out from
  51. the rest of the print message.  We suggest that your variables be given in
  52. uppercase also.  Case is significant in variable names.
  53.  
  54.  
  55. Numbers
  56.  
  57.      Some of the dot-dot commands have numbers as arguments.  When the syntax
  58. of the dot-dot command is given, the numbers are given names and enclosed in
  59. angle brackets (<>).  For example, <lower_bound> means a number whose value
  60. is used as a lower bound.
  61.  
  62.  
  63. Literal words and search words.
  64.  
  65.      Lancelot has two concepts of a word, the literal word and the search
  66. word.  The literal word is a word that must occur literally in the text, and
  67. is used by the ..MOST, ..SIZE, ..SHOW, and ..WORD commands.  Literal words are
  68. not sensitive to case.  Search words are used by phrase matching and
  69. conditional matching dot-dot commands, and are more powerful (and slower) than
  70. literal words.
  71.  
  72.      If a letter in a search word is capitalized, that letter matches
  73. either upper or lower case text letters.  A text word is terminated by one of
  74. the following characters: .?!,;)<space><tab><return><linefeed>.  If a search
  75. word contains a star (*), the star matches as many text characters as
  76. possible.  If a search word contains a percent (%), then that percent matches
  77. one or more of the following characters: <space><tab><cr><lf>.  Percent
  78. characters are useful only in conditional matching.  Examples:
  79.  
  80.   Analysis     Matching Text
  81.   --------     -------------
  82.   *ing            ing
  83.                   ring
  84.                   cling
  85.                   string
  86.  
  87.   Crawl*          crawl
  88.                   Crawl      {note that C matches both upper and lower case}
  89.                   crawled
  90.                   crawling
  91.  
  92.   a*c             ac
  93.                   abc
  94.                   abbc
  95.                   abbbc
  96.                   abbbbc
  97.  
  98.   in%to           "in to"
  99.                   "in       to"
  100.                   "in
  101.                   to"
  102.                   "in
  103.                     to"
  104.  
  105.  
  106.  
  107.  
  108.  
  109.                     Syntax of a Lancelot Action
  110.                     ----------------------------
  111.  
  112. 1. All actions start with a dot-dot command which determines the action to
  113.    occur.  For example: ..WORD means that single words are to be searched
  114.    in the text.  ..ALLCOND means that all sentences of the text are to be
  115.    searched to determine if they contain a specified word or sequence of
  116.    words.
  117.  
  118. 2. The second element of an action is an unconditional print message which is
  119.    always printed (don't forget that :. prints nothing.)
  120.  
  121. 3. The third element of an action is one or more literal words or search
  122.    words which are to be acted upon.  The particular action taken depends
  123.    upon the dot-dot command.
  124.  
  125. 4. The fourth element is a conditional print message that is printed only if
  126.    the literal or search word(s) were found.
  127.  
  128. 5. Optionally, most dot-dot commands allow any number of pairs of element 3
  129.    and element 4 to be repeated any number of times.
  130.  
  131. 6. An action is terminated by another dot-dot command.
  132.  
  133. For example:
  134.  
  135. ..allcond                                                        {Element 1}
  136. :Your text is now being searched for three word constructions.   {Element 2}
  137. .Ha* .preference                                                 {Element 3}
  138. :The text says "has(have)...a preference."  Say "prefer."        {Element 4}
  139. .Spell* .out                                                     {Element 3}
  140. :The text says "spell(s)...out."  Say "explain(s)."              {Element 4}
  141. .Take* .consideration
  142. :The text says "take(s)....Consideration."  Say "consider(s)."
  143. ..end                                                            {Element 6}
  144.  
  145.  
  146. Lancelot Dot-dot Commands
  147.  
  148. -------------------------------------------------------------
  149.  
  150. ..allcond
  151. :print message (unconditional)
  152. .word1 .word2 .word3 ...
  153. :print message (conditional upon finding a phrase containing the above words)
  154. .optional next element 3
  155. :optional next element 4
  156.  
  157.      The text is searched for all sentences that contain search word .WORD1
  158. followed by zero or more words followed by any one of .WORD2, .WORD3, or ....
  159. If the element consists of just .WORD1, then those sentences that contain
  160. .WORD1 will be accepted and the conditional print statement will be printed.
  161. If the element contains .WORD1 and .WORD2 then a sentence is accepted only if
  162. it contains both .WORD1 and .WORD2 in the respective order.  Note that .WORD1
  163. may be an entire text phrase by using the percent character.
  164.  
  165.      When a sentence is found that is accepted and the conditional print
  166. message is not empty, not only is the element 4 print message printed but
  167. also a window of three text lines is displayed to the user.  This window
  168. surrounds the place in the text where the phrase was found.  
  169.  
  170.      This action is repeated until all the occurrences in all sentences have
  171. been found.  The next element 3 is then used for the search.  Multiple
  172. elements in a single ..ALLCOND are equivalent to the same elements in multiple
  173. ..ALLCOND's.
  174.  
  175.      The variable #COUNT is set to the number of times the phrase is found,
  176. and #LINE is set to the last line in which the phrase is found.  Note that
  177. #LINE is set before the print message is printed, so the print message can
  178. print the line in which the phrase was found.
  179.  
  180. -------------------------------------------------------------
  181.  
  182. ..allphrase 
  183. :print message (unconditional) 
  184. .word1 word2 word3 ...   (NOTE: no dots - this is a phrase) 
  185. :print message (conditional upon finding the phrase.) 
  186. .optional next element 3 
  187. :optional next element 4
  188.  
  189.      The text is searched for all sentences that contain the phrase WORD1
  190. followed by WORD2, followed by WORD3 ...  If a sentence contains the
  191. phrase of element 3 then the sentence is accepted.
  192.  
  193.      When a sentence is found that is accepted and the conditional print
  194. message is not empty, not only is the element 4 print message printed but
  195. also a window of three text lines is displayed to the user.  This window
  196. surrounds the place in the text where the phrase was found.  
  197.  
  198.      This action is repeated until all phrase occurrences in all sentences
  199. have been found.  The next element 3 is then used for the search.  Multiple
  200. elements in a single ..ALLPHRASE are equivalent to the same elements in
  201. multiple ..ALLPHRASE's.
  202.  
  203.      The variable #COUNT is set to the number of times the phrase is found,
  204. and #LINE is set to the last line in which the phrase is found.  Note that
  205. #LINE is set before the print message is printed, so the print message can
  206. print the line in which the phrase was found.
  207.  
  208. -------------------------------------------------------------
  209.  
  210. ..calc
  211. .#VARNAME1 = expression
  212. .next element
  213.  
  214.      The given variable is set to the value of the expression.  The
  215. operators are plus (+), minus (-), times(*), and divide (/).  There is no
  216. unary minus, so 0-#VAR must be used.  Times and divide have higher precedence
  217. than plus or minus.  This is one of the few commands that has no print
  218. message.
  219.  
  220. Example:
  221. ..count           {this will count the words - discussed below}
  222. :.
  223. .0 1000           {we want all words counted regardless of length}
  224. ..calc            {now we estimate the number of characters in the text}
  225. .#CHARACTERS = #COUNT * 6
  226. ..type
  227. :Your text contained about #CHARACTERS characters.
  228.  
  229. -------------------------------------------------------------
  230.  
  231. ..case
  232. :print message (unconditional)
  233. .#VARIABLE
  234. .<lower_bound> <upper_bound>
  235. :print message (conditional upon the value of #VARIABLE falling between
  236.                 lower_bound and upper_bound.)
  237. .optional next element 3
  238. :optional next element 4
  239.  
  240. Example:
  241. ..sent            {this will count the sentences - discussed below}
  242. :We are now testing for sentence length
  243. .Dr .Mr .Ms .Mrs
  244. ..case
  245. :.
  246. #SLENGTH
  247. .50 100
  248. :Your longest sentence is too long.  It was found in line #LINE.
  249. .100 1000
  250. :Your longest sentence is ridiculously long.  It was found in line #LINE.
  251.  
  252. -------------------------------------------------------------
  253.  
  254. ..clear
  255.  
  256.      ..CLEAR clears the screen.  This usually follows a ..PAUSE command
  257. to give the reader time to read the screen before it is cleared.
  258.  
  259. -------------------------------------------------------------
  260.  
  261. ..comment
  262. :Print message (never printed)
  263.  
  264.      This command is used to include a comment in your analysis file.
  265.  
  266.  
  267.  
  268. -------------------------------------------------------------
  269.  
  270.  
  271. ..cond
  272. :Print message (unconditional)
  273. .word1 .word2 .word3 ...
  274. :print message (conditional upon finding a phrase containing the above words)
  275. .optional next element 3
  276. :optional next element 4
  277.  
  278.      This is identical to ..ALLCOND except that only the first sentence found
  279. that contains the matching phrase is displayed to the user.
  280.  
  281. -------------------------------------------------------------
  282.  
  283. ..count
  284. :print message (unconditional)
  285. .<lower> <upper>
  286. :Print message
  287.  
  288.      Lancelot's #COUNT variable is set to the number of words in the
  289. entire text whose lengths fall between lower and upper.
  290.  
  291. Example:
  292.   ..count
  293.   :Testing for word lengths
  294.   .2 3
  295.   :Your text contains #COUNT words whose length is either 2 or 3
  296.   .10 20
  297.   :Your text has #COUNT long words
  298.  
  299. -------------------------------------------------------------
  300.  
  301. ..double
  302. :print message (unconditional)
  303. .word1 .word2 ...
  304. :print message (conditional)
  305.  
  306.      The text is searched for double words, i.e., two sequential words
  307. which are the same.  If a double word is found and is not in the list of
  308. words (element 3), then the print message is printed.  The word "had" should
  309. probably be included in the list of excluded words because "had had" is proper
  310. English.
  311.  
  312.      The variable #COUNT is set to the number of double words found,
  313. and #LINE is set to the last line in which double words are found.  Note that
  314. #LINE is set before the print message is printed, so the print message can
  315. print the line in which the double word was found.
  316.  
  317. -------------------------------------------------------------
  318.  
  319. ..end
  320.  
  321.      The analysis file must end with ..end.
  322.  
  323. -------------------------------------------------------------
  324.  
  325. ..histo
  326. :print message (unconditional)
  327. .word1 .word2 ...
  328.  
  329.      A histogram of your sentence lengths is printed.  Each line gives the
  330. number of the sentence in the text, the line number of the text in which the
  331. sentence appears, and the sentence length.  The sentence length is shown by a
  332. bar of asterisks, one asterisk per word in the sentence.  If the sentence
  333. length is longer than 64 words, then a plus sign is shown at the right end of
  334. the asterisks, indicating that the histogram overflows the right margin.
  335.  
  336.      The list of dot words have the same meaning as in the ..SENT command.
  337.  
  338. -------------------------------------------------------------
  339.  
  340. ..most
  341. :print message (unconditional)
  342. .word1 .word2 .word3 ... <number>
  343.  
  344.      The most frequently used words of the text are display along with the
  345. number of occurances of each.  <number> determines how many words are
  346. displayed.  The words .WORD1 ... are words which are to be excluded from the
  347. display.  Typically these are "a" "the", etc. and the word processing symbols
  348. "p" "b" etc.  There is no conditional print message (element 4.)  Also, at
  349. least one .word must be present.
  350.  
  351. -------------------------------------------------------------
  352.  
  353. ..none
  354. :print message (conditional)
  355.  
  356.      If the preceeding ..ALLCOND, ..COND, ..DOUBLE, or ..WORD dot-dot command
  357. didn't find whatever it was looking for, then the print message is printed.
  358.  
  359. -------------------------------------------------------------
  360.  
  361. ..pause
  362.  
  363.      The display screen is frozen until the user presses a key.
  364.  
  365. -------------------------------------------------------------
  366. ..phrase
  367. :Print message (unconditional)
  368. .word1 word2 word3 ...
  369. :print message (conditional upon finding the phrase)
  370. .optional next element 3
  371. :optional next element 4
  372.  
  373.      This is identical to ..ALLPHRASE except that only the first sentence
  374. found that contains the matching phrase is displayed to the user.
  375.  
  376.  
  377.  
  378. -------------------------------------------------------------
  379.  
  380.  
  381. ..sent
  382. :print message (unconditional)
  383. .word1 .word2 ...
  384.  
  385.      ..SENT counts sentences and finds the longest sentence.  A sentence
  386. is a group of words ended by a word whose last charcater is one of . ! ?.
  387. The last word in a sentence is not a one letter word or any one of the
  388. words given in the list of words (element 3).  This list of words will
  389. frequently include etc, .Dr, .Mr, .Mrs, etc.
  390.  
  391.      #COUNT is set to the number of sentences.  #SLENGTH is set to the
  392. length of the longest sentence.  #LINE is set to the line number of the
  393. longest sentence.
  394.  
  395. -------------------------------------------------------------
  396.  
  397. ..show
  398. :print message (unconditional)
  399. .word1 .word2 .word3 ...
  400.  
  401.      The number of occurance in the text of the literal words of element
  402. 3 are displayed to the user.  There is no conditional print message (element
  403. 4.)
  404.  
  405. -------------------------------------------------------------
  406.  
  407. ..type
  408. :print message (unconditional)
  409.  
  410.      ..TYPE is used to unconditionally print a message.
  411.  
  412. -------------------------------------------------------------
  413.  
  414. ..word
  415. :print message (unconditional)
  416. .word1 .word2 .word3 ... <number> or <number>%
  417. :print message (conditional)
  418. .optionally next element 3
  419. :optionally next element 4
  420.  
  421.      The entire text is searched for the occurance of the literal words of
  422. element 3.  If the number of occurances of .WORD1 added to the number of
  423. occurance of .WORD2, ... equal or exceed <number> then the conditional message
  424. is printed.  If <number> is followed by % the sum of the element 3 words must
  425. equal or exceed that percentage of words in the text before the element 4
  426. print message is displayed.
  427.  
  428.      The variable #COUNT is set to the number of times the word(s) was
  429. used.
  430.  
  431.  
  432.  
  433.  
  434. Example: 
  435.   ..word 
  436.   :.  
  437.   .very large 10 
  438.   .:Your paper has used the words VERY or LARGE #COUNT times.  This is
  439.   a very large number of occurrences.
  440.