home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / INFO / TURBOPAS / TPF.ZIP / TPF.DOC < prev    next >
Encoding:
Text File  |  1985-12-28  |  11.0 KB  |  255 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.                                  TPF
  17.  
  18.                              Version 1.0
  19.  
  20.                 A Language Formatter for Turbo Pascal
  21.  
  22.  
  23.  
  24.  
  25.  
  26.                             Steve Wilhite
  27.                          Saunderlane Software
  28.                           Worthington, Ohio
  29.                                                                 Page 2
  30.  
  31.  
  32.           TPF generates a standard format for Pascal code.   TPF  will
  33.           accept  standard Pascal and the language extensions in Turbo
  34.           Pascal.  TPF accepts full programs, procedures, or groups of
  35.           statements.   A  syntactically  incorrect program will cause
  36.           TPF to abort and to cease formatting the output file.
  37.  
  38.           TPF's default formatting requires no control from you.   The
  39.           best  way  to find out how the formatting works is to try it
  40.           and see.  In addition, TPF's formatting directives give  you
  41.           considerable control over the output format when you wish.
  42.  
  43.           TPF's rules allow you to achieve almost any effect needed in
  44.           the display of comments.
  45.  
  46.  
  47.  
  48.           1.0  COMMENTS
  49.  
  50.           TPF's rules allow you to achieve almost any effect needed in
  51.           the display of comments.
  52.  
  53.           1.  A  comment  standing   alone   on   a   line   will   be
  54.               left-justified to the current indentation level, so that
  55.               it will be aligned with the statements before and  after
  56.               it.   If  it  is too long to fit with this alignment, it
  57.               will be right-justified.
  58.  
  59.           2.  A comment that begins a line  and  continue  to  another
  60.               line will be passed to the output unaltered, indentation
  61.               unchanged.  This type of comment is assumed  to  contain
  62.               text formatted by the author, so it is not formatted.
  63.  
  64.           3.  If a comment covered by one of the above rules will  not
  65.               fit  within  the  defined output line length, the output
  66.               line will be extended as necessary  to  accommodate  the
  67.               comment.   Once formatting is complete, a message to the
  68.               display will give the number  of  times  the  width  was
  69.               exceeded  and  the  output  line  number  of  the  first
  70.               occurrence.
  71.  
  72.           4.  A comment embedded within a line will be formatted  with
  73.               the rest of the code on that line.  Breaks between words
  74.               within a  comment  may  be  changed  to  achieve  proper
  75.               formatting, so nothing that has a fixed format should be
  76.               used in such a comment.  If a comment cannot be properly
  77.               spaced  so  that  the  line  will  fit within the output
  78.               length, that line will be extended as necessary.  If  no
  79.               code  follows  a comment in the input line, then no code
  80.               will be placed after the comment in the output line.
  81.  
  82.                                                                 Page 3
  83.  
  84.  
  85.           2.0  STATEMENT BUNCHING
  86.  
  87.           The normal formatting rule for a CASE statement  places  the
  88.           selected statements on a separate line from the case labels.
  89.           The B directive (see below) tells  the  formatter  to  place
  90.           these  statements on the same line as the case labels if the
  91.           statements will fit.
  92.  
  93.           Similarly, the rules for IF-THEN-ELSE, FOR, WHILE, and  WITH
  94.           place  the  controlled  statements on separate lines.  The B
  95.           directive  tells  the  formatter  to  place  the  controlled
  96.           statement  on  the  same line as the statement header if the
  97.           statement will fit.
  98.  
  99.  
  100.  
  101.           3.0  TABLES
  102.  
  103.           Many  Pascal  programs  contain  lists   of   initialization
  104.           statements  or  constant  declarations  that are logically a
  105.           single action or declaration.  You may want these to be  fit
  106.           into  as few lines as possible.  The S directive (see below)
  107.           allow this.  If this is used, logical tab stops are  set  up
  108.           on   the   line,   and  successive  statements  or  constant
  109.           declarations are aligned  to  these  tab  stops  instead  of
  110.           beginning on new lines.
  111.  
  112.           At least one blank is always placed  between  statements  or
  113.           constant  declarations,  so if tab stops are set up at every
  114.           character location, statements will be packed on a line.
  115.  
  116.           Structured statements, which normally format  on  more  than
  117.           one line, are not effected by this directive.
  118.  
  119.  
  120.  
  121.           4.0  USING TPF
  122.  
  123.           You invoke TPF with the following MS-DOS command:
  124.  
  125.               A>TPF input-file
  126.  
  127.           input-file
  128.                The Turbo Pascal source  file  to  be  formatted.   The
  129.                default  file  type  is  ".PAS".  If the formatting was
  130.                successful, the input file is renamed to "name.TPF" and
  131.                the  output  file  receives  the  same file name as the
  132.                input file.
  133.                                                                 Page 4
  134.  
  135.  
  136.           5.0  FORMATTING DIRECTIVES
  137.  
  138.           Formatting directives are specified by a special  format  of
  139.           the  Pascal  comment  structure and are placed within square
  140.           brackets.
  141.  
  142.               {[directives] text}
  143.  
  144.           Formatting directives are of two breeds:  switches that turn
  145.           on  with  the  plus  sign  (+)  and  off with the minus sign
  146.           (-)(e.g., R+ and U-);  or numeric  directives  of  the  form
  147.           T=5.  Multiple directives separated by commas (e.g., R+,U-).
  148.           Blanks are not allowed within a directive.  Case is ignored:
  149.           R+ is the same as r+ in a directive.
  150.  
  151.           The TPF formatting directives are:
  152.  
  153.           1.  A (Default A-) Adjusts each identifier so that the first
  154.               instance  of the identifier determines the appearance of
  155.               all  subsequence  instances  of  the  identifier.   This
  156.               facility   standardizes   the   use  of  upper-case  and
  157.               lower-case characters and the  break  character  (_)  in
  158.               program text.
  159.  
  160.           2.  B (Default B-) Specifies that the statements following a
  161.               THEN,  ELSE,  FOR, WITH or WHILE will be put on the same
  162.               line if they will fit.  The statement following  a  CASE
  163.               label  will  be  put  on  the same line if it fits.  The
  164.               result is a shorter output, which may be easier to  read
  165.               but which also may be harder to correct.
  166.  
  167.           3.  C (Default C-) Convert leading blanks to tabs on output.
  168.  
  169.           4.  F (Default  F+)  Turns  formatting  on  and  off.   This
  170.               directive goes into effect immediately after the comment
  171.               in which it is placed and save carefully  hand-formatted
  172.               portions of a program.
  173.  
  174.           5.  O (Numeric directive, default O=78) Specifies the  width
  175.               of  the  output  line.  The maximum value allowed is 127
  176.               character.  If a particular token will not  fit  in  the
  177.               width   specified,   the   line   will   be   lengthened
  178.               accordingly, and a message at the end of the  formatting
  179.               will give the number of times the width was exceeded and
  180.               the output line number of the first occurrence.
  181.  
  182.           6.  P (Default P-) Sets "portability mode" formatting, which
  183.               removes  break  characters  (_)  from  identifiers.  The
  184.               first letter of each identifier, and  the  first  letter
  185.               following  each break character will be made upper case,
  186.               while the remaining characters will be  in  lower  case.
  187.               This  directiver  overrides  the  U  directive.   The  R
  188.               directive sets the case of reserved words.
  189.                                                                 Page 5
  190.  
  191.  
  192.               Warning:  Turbo Pascal  considers  the  break  character
  193.               significant:   User_DoesThis  is  a different identifier
  194.               than UserDoes_This.  Take care when using this directive
  195.               that you do not make two different identifiers the same.
  196.  
  197.           7.  R (no default) R+ specifies that all reserved words  are
  198.               converted to upper case;  R- specifies that they will be
  199.               converted to lower  case.   If  this  directive  is  not
  200.               specified,  the reserved words will be a literal copy of
  201.               the input.
  202.  
  203.           8.  S (Numeric directive, default S=1) Specifies the  number
  204.               of  statements  per  line.   The  space from the current
  205.               indention level to the end of the line is  divided  into
  206.               even  pieces,  and  successive statements are put on the
  207.               boundaries of successive pieces.  A statement  may  take
  208.               more  than  one  piece, in which case the next statement
  209.               again goes on the boundary of the next piece.   This  is
  210.               similar to the tabbing of a typewriter.
  211.  
  212.           9.  T (Numeric directive, default T=2) Specifies the  amount
  213.               to  "tab"  for  each indentation level.  Statements that
  214.               continue  on  successive  lines  will  be   additionally
  215.               indented by half the value of T.
  216.  
  217.          10.  U  (no  default)  U+  specifies  that  identifiers   are
  218.               converted to upper case;  U- specifies that they will be
  219.               converted to lower  case.   If  this  directive  is  not
  220.               specified, the identifiers will be a literal copy of the
  221.               input.  The P directive override this directive.
  222.  
  223.  
  224.  
  225.  
  226.           6.0  LIMITATIONS AND ERRORS
  227.  
  228.           TPF is limited in the following ways:
  229.  
  230.           1.  The maximum input line length is 127 characters.
  231.  
  232.           2.  The maximum output length is 127 characters.
  233.  
  234.           3.  Only syntactically correct statements are formatted.   A
  235.               syntax  error  in  the code will cause the formatting to
  236.               abort.  An error message will give the input line number
  237.               on  which  the error is detected.  The error checking is
  238.               not perfect, and successful formatting is  no  guarantee
  239.               that the program will compile.
  240.  
  241.           4.  The number of  indentation  levels  handled  by  TPF  is
  242.               limited;  TPF will abort if this number is exceeded -- a
  243.               rare circumstance.
  244.                                                                 Page 6
  245.  
  246.  
  247.           5.  If a comment will require more than the  maximum  output
  248.               length (127) to meet the rules given, processing will be
  249.               aborted.  This  situation  should  be  even  rarer  than
  250.               identation-level problems.
  251.  
  252.           6.  When it aborts, TPF deletes the output file.  The  input
  253.               file is not altered.
  254.  
  255.