home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / INFO / TURBOPAS / P4MAT202.ZIP / PFORMAT.DOC < prev    next >
Encoding:
Text File  |  1985-08-30  |  15.4 KB  |  336 lines
  1. 29-AUG-85              pFORMAT.PAS (v 2.02) 26-Aug-1985                 page 1
  2.  
  3.  
  4.       Author : Andy J. S. Decepida
  5.  
  6.       N.B.   : This utility is declared public domain.  Therefore it should
  7.   not be used for commercial purposes.  Users may freely distribute
  8.   pFORMAT.PAS and p4mSetUp.PAS in source or executable form (unaltered or
  9.   otherwise).  Users who alter the source of pFORMAT.PAS and/or p4mSetUp.PAS
  10.   are amiably requested to notify the author of any significant changes that
  11.   would affect/optimize execution.  The author also welcomes bug reports or
  12.   suggestions.
  13.  
  14.       Messages may be sent to :
  15.            Andy Decepida
  16.            416 Perth Avenue
  17.            Toronto, Ontario
  18.            CANADA   M6P 3Y6
  19.            (416) 762-0802 (voice/data --- no collect calls please)
  20.  
  21.            PC1171 on PCanada
  22.            (416) 751-6337
  23.            E-Mail
  24.  
  25. Layout of this Document:
  26. ~~~~~~~~~~~~~~~~~~~~~~~
  27. General Functional Description
  28.   Primary Features
  29.     Case Alteration of Words
  30.       RESERVED WORDS
  31.       USER-DEFINED WORDS
  32.     Handling of String Literals
  33.     Handling of Comments
  34.     Handling of Hexadecimal Literals
  35.   Error Handling
  36.     NonExistent Input File
  37.     Extant Output File
  38.     Input File designated as Output File as well
  39.   Miscellaneous Features
  40.     FileSpec Specifications Parsing
  41.     Command Line Parameters
  42.     Will Display File Date/Time & Size to assist in FileSpec confirmation
  43.     Abortable by KeyPress during translation
  44.     ReConfigurable at Compile Time
  45.       ReConfigure the RESERVED WORD TABLE
  46.       ReConfigure the MIXED-CASE handling
  47.     A Sort of undocumented Turbo Pascal (v 30) feature?
  48.   Limitations
  49.     Inherently Slow
  50.     Will NOT indent for you
  51. Usage
  52.   Command Line Conventions
  53.   Responding to the Option Prompts
  54. Terminologies / Jargon
  55.  
  56.  
  57. 1: General Functional Description
  58.    ------------------------------
  59.     pFormat will read an ASCII-text file, assumed to contain Pascal source,
  60.     and generate a copy with changes in the case of both reserved and user-
  61.     defined words according to options selected by the user.
  62.  
  63. 1.1: Primary Features
  64.      ----------------
  65.           Input : Pascal source (in pFORMAT standard configuration, Turbo
  66.       Pascal dialect)
  67.           Output: a copy of the input with altered cases of reserved words and
  68.       user-defined words.
  69.  
  70. 1.1.1: Case Alteration of Words
  71.        ------------------------
  72.  
  73. 1.1.1.1: RESERVED WORDS
  74.          --------------
  75.               - User-Defined Translation
  76.               - Primary Options are to translate RESERVED WORDS to:
  77.                    Upper-Case or Lower-Case or As-Is
  78.               - Default is to translate RESERVED WORDS to Upper-Case.
  79.               - When the default is overridden, the user is given the option
  80.           to alter the translation as defined in the Primary Options above.
  81.                 Additionally, the user is prompted whether Extensions are to
  82.           be translated to MIXED CASE (cf PROCEDURE makemixedcase in
  83.           pFORMAT.PAS).
  84.  
  85. 1.1.1.2: USER-DEFINED WORDS
  86.          ------------------
  87.               - User-Defined Translation
  88.               - Primary Options are to translate USER-DEFINED WORDS to:
  89.                    Upper-Case or Lower-Case or As-Is
  90.               - Default is to leave USER-DEFINED WORDS as-is.
  91.  
  92. 1.1.2: Handling of String Literals
  93.        ---------------------------
  94.             String Literals are NOT translated at all (with the exception of
  95.         HexaDecimal characters --- see below).  They are, as with comments,
  96.         left as-is, REGARDLESS of user selection/s for the treatment of
  97.         RESERVED & USER-DEFINED WORDS.
  98.  
  99. 1.1.3: Handling of Comments
  100.        --------------------
  101.             Comments are NOT translated at all (with the exception of
  102.         HexaDecimal Literals --- see below).  They are, as with string
  103.         literals, left as-is, REGARDLESS of user selection/s for the
  104.         treatment of RESERVED & USER-DEFINED WORDS.
  105.  
  106. 1.1.4: Handling of Hexadecimal Literals
  107.        --------------------------------
  108.             - HexaDecimal Literals (specifically digits 'A'..'F') are
  109.         unconditionally translated to Upper-Case ANYWHERE in the file.  A
  110.         HexaDecimal literal is recognized only by the <$> prefix.
  111.  
  112. 1.2: Error Handling
  113.      --------------
  114.           pFORMAT has the standard error-handling features you would expect of
  115.       text-based processors.  These features, stated as the scenarios they are
  116.       guarding against, are enumerated below.
  117.  
  118. 1.2.1: NonExistent Input File
  119.        ----------------------
  120.             Severity : FATAL;
  121.             Handling : The user is re-prompted for an extant file as input.
  122.  
  123. 1.2.2: Extant Output File
  124.        ------------------
  125.             Severity : Depends on how dear the existing output file is to the
  126.         user;
  127.             Handling : The user is told of the situation and is asked whether
  128.         he/she wants to proceed to write over the file or backout (NOT to
  129.         write over the extant file).  When this backout option is exercised,
  130.         pFormat will prompt the user for a different FileSpec.
  131.  
  132. 1.2.3: Input File designated as Output File as well
  133.        --------------------------------------------
  134.             Severity : VERY VERY FATAL;
  135.             Handling : The user is told of the near-disaster and is reprompted
  136.         for both an input and output file (ie., full recycling).
  137.  
  138. 1.3: Miscellaneous Features
  139.      ----------------------
  140. 1.3.1: FileSpec Specifications Parsing
  141.        -------------------------------
  142.             When supplying FileSpecs, the default Ext(ension) is <.PAS>.  This
  143.         means you don't have to key-in the Ext if the file has (or should
  144.         have) the <.PAS> Ext.
  145.             When specifying a filename without Ext, I have taken the cue from
  146.         the Turbo Editor and made pFormat to expect a FileName suffixed by a
  147.         lone period <.>.  (e.g., to specify "FILE1" as the FileName, key in
  148.         "FILE1."
  149.  
  150. 1.3.2: Command Line Parameters
  151.        -----------------------
  152.             When Present =-> 1st Parm is the Input FileSpec
  153.                          =-> 2nd Parm is the Output FileSpec
  154.  
  155. 1.3.3: Will Display File Date/Time & Size to assist in FileSpec confirmation
  156.        ---------------------------------------------------------------------
  157.  
  158. 1.3.4: Abortable by KeyPress during translation
  159.        ----------------------------------------
  160.             Before pFORMAT goes off to translate a file, it will prompt the
  161.         user for a last option, that of being able to abort with a keypress
  162.         during execution. If you elect this option, you can interrupt the
  163.         translation in progress by pressing any key.  At that point, pFORMAT
  164.         will ask if you want to abort the translation or not ... much like
  165.         the Turbo Compile command.
  166.  
  167. 1.3.5: ReConfigurable at Compile Time
  168.        ------------------------------
  169.             pFORMAT.PAS is distributed in source form and is readily
  170.         compilable with Turbo Pascal v 3.0.  If you don't have release 3.xx,
  171.         you may use the distributed executable image pFORMAT.COM or alter the
  172.         v 3.0 specific code to compile under your version of Turbo Pascal.
  173.         The ReConfiguration being hinted here concerns that of the array
  174.         "Token" (which contains all the Turbo Pascal 3.0 RESERVED WORDS and,
  175.         consequently, all token-patterns that will be translated as per user-
  176.         choice for the RESERVED set of WORDS).
  177.             I am supplying p4mSetUp.PAS as a companion utility to semi-
  178.         automate this ReConfiguration.  The readily ReConfigurable items
  179.         (without altering the source of pFORMAT.PAS) are described below
  180.         (such alterations would precede a re-compile of pFORMAT.PAS of
  181.         course):
  182.  
  183. 1.3.5.1: ReConfigure the RESERVED WORD TABLE
  184.          -----------------------------------
  185.               pFORMAT.PAS has 3 include files.  The first is the declaration
  186.           of the size of the array <token>.  Then there is the initialization
  187.           statements for the same array, and finally, the CASE (Pascal sense)
  188.           body of the PROCEDURE doreserved.
  189.               The array <token> is the driver array or RESERVED WORD TABLE.
  190.           If you wish to expand, contract, or simply alter the actual WORDS
  191.           that pFORMAT will recognize as RESERVED WORDS, you have to alter the
  192.           second include file (distributed as TOKEN.INC).  p4mSetUp.PAS will
  193.           do this automatically for you after you alter the p4mSetUp.PAS input
  194.           files called BASE.RES and EXTNS.RES (which contain the ISO-Pascal &
  195.           Extensions respectively).  These two files are plain ASCII-text
  196.           files and can be altered by any text-editor or word-processor
  197.           capable of handling plain text files.  The advantages of using
  198.           p4mSetUp are that you reduce keying errors and ensure synchronized
  199.           include files.
  200.  
  201. 1.3.5.2: ReConfigure the MIXED-CASE handling
  202.          -----------------------------------
  203.               As mentioned above (in the discussion of ReConfiguring the
  204.           RESERVED WORD TABLE), the third include file (EXTNS.INC) contains
  205.           the logic for translating extensions to MIXED-CASE.
  206.               If you don't like the way the CASES are mixed in the standardly
  207.           configured EXTNS.INC you can just edit that file.  If you are
  208.           dissatisfied with the scope/coverage this means you have to
  209.           expand/contract the EXTNS.INC.  You can then add the appropriate
  210.           lines anywhere in EXTNS.INC or run p4mSetUp.PAS.
  211.               If you the reconfiguration manually, you must keep the 3 include
  212.           files in synch. p4mSetUp will do this for you automatically.
  213.  
  214. 1.3.6: A Sort of undocumented Turbo Pascal (v 3.0) feature?
  215.        ---------------------------------------------------
  216.             This observation concerns Turbo Pascal v 3.0 only.
  217.  
  218.          Well it seems that pFORMAT, as compiled with Turbo Pascal 3.xx, will
  219.         accept a filename <PRN> as an output file (since it is a logical
  220.         device).  The program (pFORMAT) will actually tell you it exists and
  221.         even give you the strange file attributes of your printer (date, time,
  222.         & size!).  When you specify and confirm the PRN (that is, the printer)
  223.         as a destination file, pFORMAT will actually route output to the
  224.         printer.  I have not provided for pagination if this happens since it
  225.         will markedly slow the process down too significantly.  There are
  226.         several Pascal listers in the public domain anyway.
  227.           If you use SideKick regularly, you know that the sequence ^K^P would
  228.         cause either the marked block (or if none are marked, the entire file)
  229.         in a NotePad file would print to LPT1:.  Well, the above-mentioned
  230.         piece-of-trivia also applies to SideKick AND the Turbo Editor.
  231.  
  232. 1.4: Limitations
  233.      -----------
  234.  
  235. 1.4.1: Inherently Slow ...
  236.        -------------------
  237.             Since the I/O of pFORMAT is READLN/WRITELN and not
  238.         BLOCKREAD/BLOCKWRITE, it is slow ... however, I can vouch that
  239.         READ/WRITE (char by char) would be even more tedious.  A more elegant
  240.         version, which I will not release, uses READLN/WRITELN but has a
  241.         different parser, tacks on 30% more time at execution.
  242.  
  243. 1.4.2: Will NOT indent for you ...
  244.        ---------------------------
  245.             pFORMAT may be a misleading program ID, since it seems to claim
  246.         that it will actually format Pascal source files (which usually
  247.         includes what pFORMAT does plus indentation).  Incorporating logic to
  248.         indent source files is possible but NOT practical.  It would slow down
  249.         execution dramatically. I am working on an indenter but it will impose
  250.         its own indentation style (which is another big question, who
  251.         dictates?).  There are several public domain indenters (and they are
  252.         char-by-char oriented, ergo slow) available.
  253.  
  254.  
  255. 2: Usage
  256.    -----
  257.  
  258. 2.1: Command Line Conventions
  259.      ------------------------
  260.           The following assume normal scenarios, for exception handling/flow
  261.       see Exception Handling above.
  262.  
  263.           Where you see FileName specify the 8-char DOS file-name
  264.           Where you see extension you specify the 3 char extension (optional
  265.       if these extensions are <.PAS> anyway.
  266.  
  267.        1. Calling pFORMAT and specifying input and output at command line
  268.                A> pformat <FileName><Ext> <FileName><Ext>
  269.           The first FileName is the input file and the 2nd, the output file
  270.  
  271.        2.  Calling pFORMAT and specifying input only
  272.                A> pformat <FileName><Ext>
  273.           The FileName is the input file name and pformat will ask for the
  274.       output file name.
  275.  
  276.        3.  Calling pFORMAT without specifying any parameters
  277.                A> pformat
  278.           pFORMAT will prompt you for the input file name & then the output
  279.       filename.
  280.  
  281. 2.2: Responding to the Option Prompts
  282.      --------------------------------
  283.           The Option Prompts are already bulletproof, a beep will sound if you
  284.       have miskeyed a character input.
  285.  
  286. 3: Terminologies / Jargon
  287.    ----------------------
  288.  
  289.         RESERVED WORDS - includes the ISO-Pascal set and (in the standard
  290.     pFormat configuration) Turbo Pascal-Extension set of "standard"
  291.     identifiers, verbs, functions, procedures, etc.
  292.  
  293.         USER-DEFINED WORDS - the set of alpha-numeric identifiers, functions,
  294.     procedures excluding RESERVED WORDS.
  295.  
  296.         CASE - concerns the visual configuration of a WORD (specifically,
  297.     whether in upper-case or capital-letters, or lower-case).
  298.  
  299.         AS-IS - in pFORMAT context, this means no translation of a WORD found
  300.     in the input file will be made in writing the WORD to the output file.
  301.  
  302.         MIXED-CASE - in pFORMAT context, means a special translation (via
  303.     PROCEDURE makemixedcase) of a WORD is to be done.  This (in the standard
  304.     pFormat configuration) effectively highlights the Pascal-Extensions from
  305.     those of the ISO-Pascal reserved words.  An example is to translate the
  306.     reserved word "lowvideo" to "LowVideo".
  307.  
  308.         STANDARD pFORMAT CONFIGURATION - pFORMAT as originally configured by
  309.     the author and as distributed originally (for configuration information
  310.     refer to p4mSetUp.PAS.
  311.     
  312.         WORD - the superset that consists of RESERVED WORDS and USER-DEFINED
  313.     WORDS.  A word is a string/sequence of alpha-numeric characters including
  314.     the underscore-character <_>.
  315.     
  316.         HEXADECIMAL LITERALS - a string of characters prefixed by a dollar-
  317.     sign <$> and restricted to the set of characters '0'..'9' and 'A'..'F'. In
  318.     BNF,
  319.     <hexadecimal literal> ::= <$> 0|1|2|3|4|5|6|7|8|9|a|A|b|B|c|C|d|D|e|E|f|F
  320.     
  321.         STRING LITERALS - a string of characters spanning the entire ASCII
  322.     spectrum and delimited by a pair of apostrophe signs (e.g., '<string>')
  323.     
  324.         COMMENTS - a string of characters spanning the entire ASCII spectrum
  325.     and delimited by a pair of either curly braces  {}  or  the parenthesis-
  326.     asterisk markers  (* *)
  327.     
  328.         FileSpec - <FileName>.<Ext> this is an abbrev. of File Specification.
  329.     
  330.         FileName - 8 character maximum-length name of a file
  331.  
  332.         Ext - abbrev for Extension or the 3 character maximum-length
  333.     qualification of a file's ID
  334.  
  335.         File - in pFormat context is strictly an ASCII-text file
  336.