home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / PM.ZIP / PM.DOC < prev    next >
Encoding:
Text File  |  1986-12-30  |  14.4 KB  |  463 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.                                    PasMat
  22.                                 Version 2.0
  23.  
  24.                    A Language Formatter for Turbo Pascal
  25.  
  26.  
  27.                                 Cyrus Patel 
  28.                              138 Le Moyne Pkwy
  29.                          Oak Park, Illinois  60302
  30.                            (312) 383-8985 (voice)
  31.  
  32.                        Copyright (c) 1986 Cyrus Patel
  33.                             All rights reserved.
  34.  
  35.  
  36.         PasMat  and  the  associated support files  (including  this 
  37.         documentation  file) are Copyright (c) 1985 by Cyrus  Patel. 
  38.         Non-commercial,  public distribution and use of this program 
  39.         is  not  permitted.   All  commercial rights  are  reserved. 
  40.         Distribution of PasMat should include this documentation.
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.                             Program Distribution
  71.  
  72.         PasMat was not written to be free software.  However,  after 
  73.         examination of the advertising costs involved with marketing 
  74.         a  successful program,  I have decided not to be forced into 
  75.         charging  $100+ for it.  Many hours have been put  into  the 
  76.         development  of  this program and any contribution would  be 
  77.         appreciated.  This will help offset the costs of development 
  78.         and encourage the me to continue to update this program  and 
  79.         write new ones.
  80.  
  81.  
  82.  
  83.                                 Disclaimer
  84.  
  85.         In  no  event will the author of this program be liable  for 
  86.         any  loss or damage arising from the use or misuse  of  this 
  87.         program,  even  if  the  author  has  been  advised  of  the 
  88.         possibility of such damages.  Please report bugs directly to 
  89.         the  author,  and  he  will release an  update  as  soon  as 
  90.         possible.
  91.  
  92.  
  93.  
  94.                            Introduction to PasMat
  95.  
  96.         PasMat (PM) generates a standard format for Pascal code.  PM 
  97.         will  accept standard Pascal and the language extensions  in 
  98.         Turbo  Pascal.   PM accepts full  programs,  procedures,  or 
  99.         groups  of  statements.  A  syntactically incorrect  program 
  100.         will  cause PM to abort and to cease formatting  the  output 
  101.         file.
  102.  
  103.         PM's default formatting requires no control from you.    The 
  104.         best  way  to find out how the formatting works is to try it 
  105.         and see.   In addition, PM's formatting directives give  you 
  106.         considerable control over the output format when you wish.
  107.  
  108.         PM's  rules allow you to achieve almost any effect needed in 
  109.         the display of comments.
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.         PasMat version 2.0   Users manual                     Page 2
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.              1.0  COMMENTS
  137.  
  138.              PM's rules allow you to achieve almost any effect needed  in 
  139.              the display of comments.
  140.  
  141.              1.  A  comment  standing   alone   on   a   line   will   be 
  142.                  left-justified to the current indentation level, so that 
  143.                  it will be aligned with the statements before and  after 
  144.                  it.   If  it  is too long to fit with this alignment, it 
  145.                  will be right-justified.
  146.  
  147.              2.  A comment that begins a line  and  continue  to  another 
  148.                  line will be passed to the output unaltered, indentation 
  149.                  unchanged.  This type of comment is assumed  to  contain 
  150.                  text formatted by the author, so it is not formatted.
  151.  
  152.              3.  If a comment covered by one of the above rules will  not 
  153.                  fit  within  the  defined output line length, the output 
  154.                  line will be extended as necessary  to  accommodate  the 
  155.                  comment.   Once formatting is complete, a message to the 
  156.                  display will give the number  of  times  the  width  was 
  157.                  exceeded  and  the  output  line  number  of  the  first 
  158.                  occurrence.
  159.  
  160.              4.  A comment embedded within a line will be formatted  with 
  161.                  the rest of the code on that line.  Breaks between words 
  162.                  within a  comment  may  be  changed  to  achieve  proper 
  163.                  formatting, so nothing that has a fixed format should be 
  164.                  used in such a comment.  If a comment cannot be properly 
  165.                  spaced  so  that  the  line  will  fit within the output 
  166.                  length, that line will be extended as necessary.  If  no 
  167.                  code  follows  a comment in the input line, then no code 
  168.                  will be placed after the comment in the output line.
  169.  
  170.  
  171.  
  172.              2.0  STATEMENT BUNCHING
  173.  
  174.              The normal formatting rule for a CASE statement  places  the 
  175.              selected statements on a separate line from the case labels. 
  176.              The B directive (see below) tells  the  formatter  to  place 
  177.              these  statements on the same line as the case labels if the 
  178.              statements will fit.
  179.  
  180.              Similarly, the rules for IF-THEN-ELSE, FOR, WHILE, and  WITH 
  181.              place  the  controlled  statements on separate lines.  The B 
  182.              directive  tells  the  formatter  to  place  the  controlled 
  183.              statement  on  the  same line as the statement header if the 
  184.              statement will fit.
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.         PasMat version 2.0   Users manual                     Page 3
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.              3.0  TABLES
  203.  
  204.              Many  Pascal  programs  contain  lists   of   initialization 
  205.              statements  or  constant  declarations  that are logically a 
  206.              single action or declaration.  You may want these to be  fit 
  207.              into  as few lines as possible.  The S directive (see below) 
  208.              allow this.  If this is used, logical tab stops are  set  up 
  209.              on   the   line,   and  successive  statements  or  constant 
  210.              declarations are aligned  to  these  tab  stops  instead  of 
  211.              beginning on new lines.
  212.  
  213.              At least one blank is always placed  between  statements  or 
  214.              constant  declarations,  so if tab stops are set up at every 
  215.              character location, statements will be packed on a line.
  216.  
  217.              Structured statements, which normally format  on  more  than 
  218.              one line, are not effected by this directive.
  219.  
  220.  
  221.  
  222.              4.0  USING PM
  223.  
  224.              You invoke PM with the following command:
  225.  
  226.                  A>PM input-file
  227.  
  228.              input-file
  229.                   The Turbo Pascal source  file  to  be  formatted.   The 
  230.                   default  file  type  is  ".PAS".  If the formatting was 
  231.                   successful, the input file is renamed to "name.PMT" and 
  232.                   the  output  file  receives  the  same file name as the 
  233.                   input file.
  234.  
  235.  
  236.  
  237.              5.0  FORMATTING DIRECTIVES
  238.  
  239.              Formatting directives are specified by a special  format  of 
  240.              the  Pascal  comment  structure and are placed within square 
  241.              brackets.
  242.  
  243.                  {[directives] text}
  244.  
  245.              Formatting directives are of two breeds:  switches that turn 
  246.              on  with  the  plus  sign  (+)  and  off with the minus sign 
  247.              (-)(e.g., R+ and U-);  or numeric  directives  of  the  form 
  248.              T=5.  Multiple directives separated by commas (e.g., R+,U-). 
  249.              Blanks are not allowed within a directive.  Case is ignored: 
  250.              R+ is the same as r+ in a directive.
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.         PasMat version 2.0   Users manual                     Page 4
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.              The PM formatting directives are:
  269.  
  270.              1.  A (Default A-) Adjusts each identifier so that the first 
  271.                  instance  of the identifier determines the appearance of 
  272.                  all  subsequence  instances  of  the  identifier.   This 
  273.                  facility   standardizes   the   use  of  upper-case  and 
  274.                  lower-case characters and the  break  character  (_)  in 
  275.                  program text.
  276.  
  277.              2.  B (Default B-) Specifies that the statements following a 
  278.                  THEN,  ELSE,  FOR, WITH or WHILE will be put on the same 
  279.                  line if they will fit.  The statement following  a  CASE 
  280.                  label  will  be  put  on  the same line if it fits.  The 
  281.                  result is a shorter output, which may be easier to  read 
  282.                  but which also may be harder to correct.
  283.  
  284.              3.  C (Default C-) Convert leading blanks to tabs on output.
  285.  
  286.              4.  F (Default  F+)  Turns  formatting  on  and  off.   This 
  287.                  directive goes into effect immediately after the comment 
  288.                  in which it is placed and save carefully  hand-formatted 
  289.                  portions of a program.
  290.  
  291.              5.  O (Numeric directive, default O=78) Specifies the  width 
  292.                  of  the  output  line.  The maximum value allowed is 127 
  293.                  character.  If a particular token will not  fit  in  the 
  294.                  width   specified,   the   line   will   be   lengthened 
  295.                  accordingly, and a message at the end of the  formatting 
  296.                  will give the number of times the width was exceeded and 
  297.                  the output line number of the first occurrence.
  298.  
  299.              6.  P (Default P-) Sets "portability mode" formatting, which 
  300.                  removes  break  characters  (_)  from  identifiers.  The 
  301.                  first letter of each identifier, and  the  first  letter 
  302.                  following  each break character will be made upper case, 
  303.                  while the remaining characters will be  in  lower  case. 
  304.                  This  directiver  overrides  the  U  directive.   The  R 
  305.                  directive sets the case of reserved words.
  306.  
  307.                  Warning:  Turbo Pascal  considers  the  break  character 
  308.                  significant:   User_DoesThis  is  a different identifier 
  309.                  than UserDoes_This.  Take care when using this directive 
  310.                  that you do not make two different identifiers the same.
  311.  
  312.              7.  R (no default) R+ specifies that all reserved words  are 
  313.                  converted to upper case;  R- specifies that they will be 
  314.                  converted to lower  case.   If  this  directive  is  not 
  315.                  specified,  the reserved words will be a literal copy of 
  316.                  the input.
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.         PasMat version 2.0   Users manual                     Page 5
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.              8.  S (Numeric directive, default S=1) Specifies the  number 
  335.                  of  statements  per  line.   The  space from the current 
  336.                  indention level to the end of the line is  divided  into 
  337.                  even  pieces,  and  successive statements are put on the 
  338.                  boundaries of successive pieces.  A statement  may  take 
  339.                  more  than  one  piece, in which case the next statement 
  340.                  again goes on the boundary of the next piece.   This  is 
  341.                  similar to the tabbing of a typewriter.
  342.  
  343.              9.  T (Numeric directive, default T=5) Specifies the  amount 
  344.                  to  "tab"  for  each indentation level.  Statements that 
  345.                  continue  on  successive  lines  will  be   additionally 
  346.                  indented by half the value of T.
  347.  
  348.             10.  U  (no  default)  U+  specifies  that  identifiers   are 
  349.                  converted to upper case;  U- specifies that they will be 
  350.                  converted to lower  case.   If  this  directive  is  not 
  351.                  specified, the identifiers will be a literal copy of the 
  352.                  input.  The P directive override this directive.
  353.  
  354.  
  355.  
  356.              6.0  LIMITATIONS AND ERRORS
  357.  
  358.              PM is limited in the following ways:
  359.  
  360.              1.  The maximum input line length is 127 characters.
  361.  
  362.              2.  The maximum output length is 127 characters.
  363.  
  364.              3.  Only syntactically correct statements are formatted.   A 
  365.                  syntax  error  in  the code will cause the formatting to 
  366.                  abort.  An error message will give the input line number 
  367.                  on  which  the error is detected.  The error checking is 
  368.                  not perfect, and successful formatting is  no  guarantee 
  369.                  that the program will compile.
  370.  
  371.              4.  The number of  indentation  levels  handled  by  PM   is 
  372.                  limited;   PM will abort if this number is exceeded -- a 
  373.                  rare circumstance.
  374.  
  375.              5.  If a comment will require more than the  maximum  output 
  376.                  length (127) to meet the rules given, processing will be 
  377.                  aborted.  This  situation  should  be  even  rarer  than 
  378.                  identation-level problems.
  379.  
  380.              6.  When PM aborts,  it deletes the output file.  The  input 
  381.                  file is not altered.
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.         PasMat version 2.0   Users manual                     Page 6
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.                     PasMat version 2.0 Quick Reference Guide
  409.  
  410.                Default                  Descritption
  411.              -----------------------------------------------------------
  412.                  A-   = [+, -]   Use first spelling as a "key".
  413.                  B-   = [+, -]   Bunch together statements on one line.
  414.                  C-   = [+, -]   Convert leading spaces to tabs.
  415.                  F+   = [+, -]   Start formatting at end of comment.
  416.                  O=78 = [number] Maximum line length of output.
  417.                  P-   = [+, -]   Delete _ (underscore) character from
  418.                                      variables, to make compatable with
  419.                                      other Pascal compilers.
  420.                  R-   = [+, -]   Make all reserved words upper case.
  421.                  S=1  = [number] Maximum number of statements per line.
  422.                  T=5  = [number] Number of spaces to indent.
  423.                  U-   = [+, -]   Make all identifies upper case.
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.         PasMat version 2.0   Users manual                     Page 7
  458.  
  459.  
  460.  
  461.  
  462.  
  463.