home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / snobol / vsnobol / gentran.doc < prev    next >
Text File  |  1991-02-14  |  10KB  |  263 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. GENERIC TRANSLATOR VERSION 0.2
  8.  
  9. For use with CATSPAW VANILLA SNOBOL4
  10.  
  11. Copyright 1987 by Kevin G. Barkes Consulting Services. Non-commercial
  12. reproduction and distribution permitted.  All other rights reserved.
  13.  
  14. Kevin G. Barkes Consulting Services
  15. 4107 Overlook Street
  16. Library, PA 15129
  17. Fido 129/38 (SYS$OUTPUT BBS - 412-854-0511)
  18.  
  19. This software is provided on an "as-is" basis; no expressed nor implied
  20. warranties are made.
  21.  
  22. ********************************************************************************
  23.  
  24. HISTORY:
  25.  
  26. This program was originally written, tested, and debugged (well, as much as it 
  27. is in its current state) in under two hours.
  28.  
  29. An associate had given me a diskette containing a manuscript which he wanted to
  30. edit and prepare for transmission to his publisher.  The file was in "print
  31. image" format... nicely formatted, with margins, extra word spaces due to
  32. justification, and other conventions which are fine if the file is going to a
  33. line printer.  This file was going to a commercial typesetter, where the
  34. composition people wanted to see a plain ASCII file with no extra spaces,
  35. "standard" typesetting generic coding, and no surprises.
  36.  
  37. I didn't feel like manually editing the file, and was tired of writing special
  38. programs for each relatively simple conversion which came along.  So I wrote
  39. GENTRAN, which is essentially a global search and replace utility, but which
  40. also contains some of the pattern matching capabilities of SNOBOL4.
  41.  
  42. The program worked, and I eventually ported it to VAX SPITBOL where it is used
  43. in a commercial printing environment.  That version contains some extra
  44. niceties, is more thoroughly debugged, and runs (as SPITBOL is wont to do)
  45. like the proverbial bat.
  46.  
  47. The original GENTRAN disappeared into the bowels of my hard disk, to resurface
  48. again when I promised Mark Emmer of Catspaw that I'd stick some useful SNOBOL4
  49. software in the files section of Catspaw's Bulletin Board.
  50.  
  51. So, here it is, in its original, pristine, unstructured, and somewhat
  52. contorted form.  In a way, this program represents both the best and the worst
  53. of SNOBOL.
  54.  
  55. I hope it provides a starting point from which you can develop your own
  56. utilities.  The program shows some of SNOBOL's fancy tricks, like user defined
  57. functions, tables, etc.  It also contains non-meaningful labels,
  58. perverted program flow, and other abominations.  In short, it's a
  59. good example of why programmers both love and hate the language.
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66. ****************************************************************************
  67.  
  68. GENTRAN is intended for use in text processing applications, specifically
  69. in preparing files for input into some type of typesetting or composition
  70. system which uses mnemonic coding (such as Datalogics' PAGER).  GENTRAN
  71. does global search and replace, line trimming, quote processing, and supports
  72. some basic pattern matching.
  73.  
  74.  
  75. 1. INSTALLATION
  76.  
  77. SNOBOL4 users should enter SNOBOL4 GENTRAN at the DOS prompt.
  78.  
  79. 2. INPUT/OUTPUT
  80.  
  81. There are three file names which must be specified after running GENTRAN. The
  82. first is the name of the translation table input (.TTI) file.
  83.  
  84. The .TTI file contains directives (special commands which affect the entire
  85. translation) as well as search and replace strings.
  86.  
  87. .TTI is the default extension name for these files.  It is not necessary
  88. to enter the .TTI extension.  If the translation table file ends in any other
  89. extension, however, the full file spec must be given.  A translation table
  90. input file named TEST.TTI could be specified merely as "TEST". One named
  91. "TEST.TRA" would have to be entered as "TEST.TRA".
  92.  
  93. You can also enter directives and search/replace strings interactively.  When
  94. prompted by the program for the .TTI filename, press ENTER.  You can now enter
  95. commands from the keyboard.  Press Control-Z, then ENTER, when you have
  96. completed entering commands. 
  97.  
  98. The input file is the name of the source, or "raw" file.  The output file is
  99. where the result of the translation will be placed.  You can use the console
  100. keyboard (CON:) for both input and output, if you wish.  This is handy for
  101. debugging purposes when setting up a new .TTI file.
  102.  
  103. 3. DIRECTIVES
  104.  
  105. Directives are GENTRAN commands which change the behavior of the software
  106. during translations.
  107.  
  108. Directives can appear anywhere in the .TTI file.  Each directive must appear on
  109. a line by itself, with no other text on the line.  With one exception, all
  110. directives begin with a percent sign (%) followed by a word.  There is no
  111. space between the percent sign and the word. GENTRAN ignores blank lines in
  112. the .TTI file.
  113.  
  114. The exception is the comment directive, the exclamation mark (!).  Lines
  115. containing an exlamation mark in the first position of the line are not
  116. processed.  This is useful for entering comments in the file.
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123. The other directives are:
  124.  
  125. IMMEDIATE DIRECTIVES:
  126.  
  127. (These directives are executed on all lines of the file, prior to search and
  128. replace and %QUOTE operations.)
  129.  
  130. %TRIM           -- Trims trailing spaces from all lines (the default).
  131.  
  132. %LTRIM          -- Trims leading spaces and tabs from all lines.
  133.  
  134. %ATRIM          -- Trims both leading and trailing spaces from all lines.
  135.                    The same as entering:
  136.                    %TRIM
  137.                    %LTRIM
  138.                    in the .TTI file.
  139.  
  140. %COMPRESS       -- Compresses multiple spaces and tabs from all lines.
  141.  
  142. %COLLAPSE       -- Trims leading and trailing spaces and compresses multiple
  143.                    spaces and tabs from all lines.
  144.                    The same as entering:
  145.                    %TRIM                                %ATRIM
  146.                    %LTRIM               or              %COMPRESS
  147.                    %COMPRESS
  148.  
  149. %TRACE          -- Displays the result of the translation to the terminal,
  150.                    in addition to writing the translation to the output
  151.                    file.
  152.  
  153.  
  154. DEFERRED DIRECTIVE
  155.  
  156. This directive is executed following the immediate directives but before
  157. the search and replace strings:
  158.  
  159. %QUOTE          -- Changes the double quote (") to open and close quotes.
  160.  
  161. Once "turned on", directives cannot be "turned off."
  162.  
  163. 4.  SEARCH AND REPLACE STRINGS.
  164.  
  165. After executing all directives, GENTRAN executes each search and replace
  166. statement in the .TTI file.
  167.  
  168. GENTRAN is case sensitive.  "THIS" will not match "This" or "this".
  169.  
  170. Strings are delimited by the backslash character (\).  Use quotes to enclose
  171. strings within the delimiters.
  172.  
  173. If the search string contains quotes, use apostrophes to define strings:
  174.  
  175. \'"HELLO"'\ \"hello"\ (changes case and strips quotes)
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182. \'"Marys' "'"\  \'"Mary' "'" 's"\  Translates "Marys'" to "Mary's"
  183. Note GENTRAN ignores spaces between quoted strings.
  184.  
  185. \\ (null string) can be used to translate the search string to null.
  186. For example:
  187.  
  188. \"green"\ \\
  189.  
  190. will effectively strip all occurrences of the string "green" in the input
  191. file.
  192.  
  193. The null string \\ cannot be used as a search string; an error will result.
  194.  
  195. GENTRAN will not permit you to translate a string to itself.  The following
  196. will generate an error:
  197.  
  198. \"string"\ \"string"\
  199.  
  200. You can still get into an endless loop, though, by inopportune replacements,
  201. such as:
  202.  
  203. \"."\ \".."\
  204.  
  205. This will replace a single period with two periods. Since GENTRAN will
  206. always find a single period, it will loop through this search and replace
  207. line until you run out of memory or reach an internal SNOBOL limit.
  208.  
  209. Be careful when entering search and replace strings.  Remember that GENTRAN
  210. goes through the strings one at a time, and that subsequent replacements
  211. can be affected by what occurred previously.  In the examples above showing
  212. how to search and replace quotes, bear in mind that if the %QUOTE directive
  213. had been specified, the replacement would have failed.
  214.  
  215. That is, if %QUOTE were NOT enabled,
  216. \'"Marys' "'"\  \'"Mary' "'" 's"\ 
  217.  
  218. would be successful.  If %QUOTE had been enabled, the strings would have
  219. to be:
  220.  
  221. \"``Marys'''"\ \"``Mary's''"\
  222.  
  223. 6. PATTERNS
  224.  
  225. GENTRAN recognizes legal SNOBOL function calls in the search & replace
  226. strings.  This vastly increases GENTRAN's power and flexibility.
  227.  
  228. For example:
  229.  
  230. \POS(0) "A"\ \DUPL(".",10)\
  231.  
  232. will replace a capital A in the first position of the line to a string of
  233. 10 periods.
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240. You can create temporary variables to rearrange data in the replacement.
  241.  
  242. \("Mr. " | "Mrs. " | "Miss ") . TITLE BREAK(" ") . NAME)\*(NAME ", " TITLE)\
  243.  
  244. will replace strings like "Mrs. Jones " with "Jones, Mrs. ".
  245.  
  246. The search string is compiled by GENTRAN when the TTI file is first read.
  247. If the replacement string is a simple string (or concatenation of strings),
  248. it too is statically compiled when the TTI file is read.  The example above
  249. shows another case:  The replacement expression uses variables assigned during
  250. the pattern match.  These variables cannot be evaluated when the TTI file
  251. is read; they must be evaluated as each record of the input file is processed
  252. (if the search string is found in that record).  The user expresses this
  253. fact by placing the replacement expression in parenthesis, and preceeding it
  254. with SNOBOL4's "defered evaluation operator", the "*".
  255.  
  256. (Hint:  If you try to use variables and functions in the replacement string,
  257. and omit the "*", you'll likely see the word "PATTERN" in your output.)
  258.  
  259. Extreme care must taken when using SNOBOL functions to avoid endless looping
  260. or conflicts with reserved function or variable names.
  261.  
  262. See the SAMPLE.TTI file in this distribution for an example of a .TTI file.
  263.