home *** CD-ROM | disk | FTP | other *** search
/ Power Programming / powerprogramming1994.iso / progtool / turbopas / pp50.arc / PP.DOC next >
Text File  |  1989-11-28  |  7KB  |  162 lines
  1.              PP - Pascal Prettyprinting Program
  2.  
  3.                   11 October 1984
  4.  
  5.                   - Jon Hueras and
  6.                      Henry Ledgard
  7.                   - Rick L. Marcus
  8.  
  9. Toad Hall Tweak, reformat, 28 Nov 89
  10.  
  11.  
  12. What PP Does
  13. ------------
  14.  
  15.      PP takes as input a Pascal program or program fragment and reformats it
  16. according  to  a  standard  set  of prettyprinting rules.  The prettyprinted
  17. program is given as output.  PP  makes  no  attempt  to  detect  or  correct
  18. syntactic  errors  in your program.  However, syntactic errors may result in
  19. erroneous prettyprinting.
  20.  
  21.      PP  differs from some other prettyprinting programs in that it does not
  22. reformat your  program  "right  down  to  every  last  semicolon."   Such  a
  23. philosophy  requires formatting everything in a rigid fashion which is bound
  24. to be displeasing, or else it must provide you  with  a  voluminous  set  of
  25. "options."   Furthermore,  such a scheme must do full syntax analysis of the
  26. program which means that it must be completely written and  compilable.   If
  27. you  wish to prettyprint a program still under development, then you are out
  28. of luck.
  29.  
  30.      PP,  on  the  other hand, implements a strategy which states that it is
  31. not necessary to impose more than a "minimum" set of restrictions,  and  the
  32. prettyprinter  should  yield  to  your  discretion  beyond this minimum.  PP
  33. preserves blank lines and extra spaces you insert in the program  as  input,
  34. besides  adding  blank  lines  and  extra  spaces according to the rules for
  35. prettyprinting given below.
  36.  
  37. General prettyprinting rules:
  38.  
  39. 1.    All statements and declarations begin on separate lines.
  40.  
  41. 2.    No  input  line  may  be longer than 80 characters.  Any output line
  42.         longer than 80 characters is continued on a separate line.
  43.  
  44. 3.    The  keywords  "BEGIN",  "END", "REPEAT", and "RECORD" are forced to
  45.         stand on lines by themselves (or  possibly  followed  by  supporting
  46.         comments).   In  addition,  the  "UNTIL"  clause  of  "REPEAT-UNTIL"
  47.         statement is forced to start on a new line.
  48.  
  49. 4.    A  blank  line is forced before the keywords "PROGRAM", "PROCEDURE",
  50.         "FUNCTION", "LABEL", "CONST", "TYPE", and "VAR".
  51.  
  52. 5.    A  space  is  forced  before  and  after  the  symbols ":=" and "=".
  53.         Additionally, a space is forced after the  symbol  ":".   Note  that
  54.         only  "="s  in  declarations  are formatted; "="s in expressions are
  55.         ignored.
  56.  
  57. 6.    Spaces  and blank lines already in your program are preserved by PP,
  58.         which adds (but does not subtract) blank lines and spaces.  You  can
  59.         improve the readability of your programs by taking advantage of this
  60.         feature.   However,  this  feature also means that you may sometimes
  61.         have to manually de-indent (in your editor)  after  block  structure
  62.         changes.
  63.  
  64. Indentation rules:
  65.  
  66. 1.    The  body  of  a  declaration is indented from the "LABEL", "CONST",
  67.         "TYPE", or "VAR" keyword which heads it.
  68.  
  69. 2.    The  bodies  of  "BEGIN-END",  "REPEAT-UNTIL",  "WHILE", "WITH", and
  70.         "CASE" statements, as well as  "RECORD-END"  structures  and  "CASE"
  71.         variants (to one level) are indented from keywords which head them.
  72.  
  73. 3.    An "IF-THEN-ELSE" statement is indented as follows:
  74.  
  75.                IF <expression>
  76.                   THEN <statement>
  77.                   ELSE <statement>
  78.  
  79. When to Use PP
  80. --------------
  81.  
  82.      PP  is  especially  useful  to  reformat  a  Pascal  program or program
  83. fragment that you have typed without regard to formatting (such as  entering
  84. every  line  left-justified  to save time).  Because the program need not be
  85. syntactically correct, PP provides the fastest means  of  obtaining  a  more
  86. readable version of your program.
  87.  
  88.      PP  is  best  used to prettyprint a Pascal program already on a file or
  89. punched on cards.  PP changes neither the cards nor the file used as  input.
  90. Prettyprinting  a  program  line-by-line  as  it is entered at a terminal is
  91. considerably less useful.
  92.  
  93. How to Use PP
  94. -------------
  95.  
  96.      Type  "PP" at the system command level followed by the old and new file
  97. names.  If the new file already  exists,  it  will  be  overwritten  without
  98. warning.   If  the  wrong  number  of  file names are given, PP will print a
  99. message reminding the user of the correct system call.
  100.  
  101. Examples
  102. --------
  103.  
  104.      1.  Reformat the same program under MS-DOS:
  105.  
  106.             PP prog1.pas prog1.new
  107.             TYPE prog1.new
  108.             ERASE prog1.pas
  109.             RENAME prog1.new prog1.pas
  110.  
  111.      2.  Preview PP's output before writing to a file:
  112.  
  113.             PP prog.pas con
  114.  
  115.      3.  Remind oneself how to use PP:
  116.  
  117.             PP
  118.  
  119. History
  120. -------
  121.  
  122.      PP  prettyprints  a  Pascal program or program fragment given as input.
  123. It was originally named PRETTYPRINT and was written in Pascal by Jon  Hueras
  124. and  Henry Ledgard, University Computing Center and Computer and Information
  125. Science Dept., University of Massachusetts  at  Amherst,  in  August,  1976.
  126. (See  "An  Automatic Formatting Program for Pascal", by Jon Hueras and Henry
  127. Ledgard, Pascal Newsletter #6, page 70, November, 1976.)
  128.  
  129.      Small  corrections  were  made to PRETTYPRINT by Charles Fischer, Dept.
  130. of Computer Science, University of Wisconsin, Madison, in 1977.  PRETTYPRINT
  131. was modified for CDC-6000 Pascal by Rick  L.   Marcus,  University  Computer
  132. Center, University of Minnesota, in September, 1978, and was renamed PRETTY.
  133. Marcus also wrote this documentation.
  134.  
  135.      Peter  Grogono  adapted  PRETTYPRINT  to CP/M, using Pascal/Z.  He also
  136. made several modifications and  renamed  it  PP  (date  unknown).   In  1984
  137. Willett Kempton adapted the Pascal/Z version to Turbo Pascal, which required
  138. only  minor  mods.   The  Turbo  version  uses  a  portable argument library
  139. "ARGLIB.PAS" to get file names, which makes it easier to adapt PP  to  other
  140. Pascal  systems.   The  Turbo  version  has  been  tested  under CP/M-80 and
  141. CP/M-86,  and  is  believed  to  work  without  modification   (other   than
  142. recompilation)  under MS-DOS.  Kempton also adapted this documentation, from
  143. the CDC version, to apply to the microcomputer version.
  144.  
  145.      Toad Hall Tweak, 28 Nov 89:
  146.     - Rewrote to compile under Turbo Pascal v5.0
  147.     - Removed any nasty comments related to Turbo Pascal's
  148.       "nonstandard" ways.
  149.     - Replaced a bunch of array loading with typed array constants.
  150.     - Threw in some TP5 functions (Inc, Dec, etc.)
  151.     - Incorporated all the code in one file (instead of all the
  152.       silly INC files).
  153.  
  154.     Notes:
  155.     PP doesn't format Pascal code the way I like it!  (I don't like
  156.     new lines for each BEGIN, indented ENDs, etc.)
  157.     However, someone asked for a Pascal formatter, so here it is.
  158.  
  159.     David Kirschbaum
  160.     Toad Hall
  161.     kirsch@arsocomvax.socom.mil
  162.