home *** CD-ROM | disk | FTP | other *** search
/ C!T ROM 2 / ctrom_ii_b.zip / ctrom_ii_b / PROGRAM / FOXPRO / PRE307 / PRE.DOC < prev    next >
Text File  |  1990-05-04  |  22KB  |  708 lines
  1. PRE - Preprocessor Version 3.07, copyright (C) 1988-90 by Gary Crouse.
  2.  
  3. A preprocessor for Clipper and other dBase style source code.
  4.  
  5. This program is similar in function to preprocessors for C and other
  6. language compilers.
  7.  
  8.  
  9. Features:
  10.  
  11.      Constant and simple function substitution (#DEFINE).
  12.      Include files (#INCLUDE).
  13.      Include blocks of source code (#LIBRARY, #<library identifier>).    
  14.      Conditional compilation or processing (#IF, #IFDEF, #IFNDEF, #IGNORE).
  15.      Comment or skip blocks (#COMMENT/#XCOMMENT, #GOTO, #LABEL).
  16.      If the program terminates with an error (usually a file not found),
  17.           DOS errorlevel is set to 1.
  18.      Run a DOS program upon successful completion.
  19.  
  20.  
  21. Syntax:
  22.  
  23.      PRE [<Input Filename[.pre]>] [<Output Filename[.prg]>] [[/|-]switches]
  24.  
  25.      If no filenames are specified on command line, a help screen is
  26.      displayed and the program will prompt for input and output filenames.
  27.      If only the input file is specified on the command line then the
  28.      output filename is assumed to be the same as the input filename but
  29.      with an extension of ".PRG".  If no extension is given for the input
  30.      file, then ".PRE" is assumed.  If no extension is given for the output
  31.      file, then ".PRG" is assumed.  Input and output filenames may include
  32.      complete drive and path specification.  The output and input files
  33.      must be different - i.e. the input file cannot be overwritten by the
  34.      output file (!).
  35.  
  36.      Pressing the escape key at a prompt or during processing will
  37.      terminate the program.
  38.  
  39.  
  40. Environment Variable:
  41.  
  42.      Command line parameters may be placed in a DOS environment variable
  43.      called "PRE".  Parameters in the environment variable are processed
  44.      before parameters on the command line.
  45.      Example:
  46.           set pre=/q+ /o+
  47.  
  48.  
  49. Special Input filenames:
  50.  
  51.      #<library identifier>
  52.           Extracts a library source code block.
  53.           See #LIBRARY.
  54.  
  55.      #LIBNAMES
  56.           Extracts a list of the module names in a source code library.
  57.           See #LIBRARY.
  58. Switches:
  59.  
  60.      Command line switches are preceded by "-" or "/" and may appear
  61.      anywhere on the command line and in any order.
  62.      Switches can be upper case or lower case and used in any of these
  63.      formats:
  64.  
  65.           /q /o
  66.           /qo
  67.           -q /o
  68.  
  69.      Switches /1 /2 /B /C /L /O /Q /S and /T are on/off type switches. An
  70.      on/off switch is turned on by following it with a plus sign (+) or
  71.      nothing, and turned off by following it with a minus sign (-).
  72.      (NOTE: this is a significant change from some previous versions, where
  73.      on/off type switches not followed by a plus or minus simply toggled
  74.      the previous state.)
  75.      
  76.      Example:
  77.  
  78.           /o+ /q- /l
  79.                ("O" is on, "Q" is off, "O" is on.)
  80.  
  81.      With the exception of /#, /D, and /I, switches should appear only once
  82.      on the command line.  The last occurrence of other switches will be
  83.      the one to take affect.
  84.  
  85.  
  86.  
  87.  
  88.      /#<directive>, /@<directive>
  89.  
  90.           Command line directive.
  91.           Directive must be in quotes (").
  92.           Limited to 255 characters or maximum DOS command line length.
  93.           Processed with implicit #XLIST and #XBLANK directives to maintain
  94.           line number alignment between input and output files.
  95.           Multiple command line directives may be used.
  96.  
  97.           Example:
  98.  
  99.                pre test /#"define esc 27"
  100.  
  101.  
  102.      /', /"
  103.  
  104.           Select single or double quotes for use with the "stringizing"
  105.           operator (#).
  106.           Default is double quote (").
  107.  
  108.  
  109.      /1 , /2
  110.  
  111.           Ignore single/double quotes in function defines.
  112.           Allows processing of directives within quotes.
  113.           ON is the same as #SQUOTE/#DQUOTE, OFF the same as
  114.           #XSQUOTE/#XDQUOTE.
  115.           Default is OFF.
  116.  
  117.  
  118.     /B
  119.  
  120.           Blank lines and comments are copied.
  121.           ON is the same as #BLANK, OFF the same as #XBLANK.
  122.           Default is ON.
  123.           See #BLANK.
  124.  
  125.  
  126.      /C
  127.           Case sensitivity for #DEFINE identifiers.
  128.           Turning case sensitivity off will cause slower processing.
  129.           Default is ON.
  130.  
  131.  
  132.      /D<identifier> [<constant or expression>]
  133.  
  134.           Command line #DEFINE.
  135.           Optional constant or expression must be in quotes (").
  136.           Limited to 255 characters or maximum DOS command line length.
  137.           Processed with implicit #XLIST and #XBLANK directives to maintain
  138.           line number alignment between input and output files.
  139.           Multiple command line defines may be used.
  140.           See #DEFINE.
  141.  
  142.           Examples:
  143.  
  144.                pre test /ddebug
  145.                pre test /d"esc 27"
  146.                pre test /dv1 /dv3
  147.  
  148.  
  149.      /H, /?
  150.  
  151.           Help.
  152.           Displays the following help screen and then ends the program.
  153.  
  154.  
  155.  
  156.  
  157.  
  158.      /I<filename>
  159.  
  160.           Command line #INCLUDE.
  161.           Limited to 64 characters.
  162.           Processed with implicit #XLIST and #XBLANK directives to maintain
  163.           line number alignment between input and output files.
  164.           Multiple command line includes may be used.
  165.           See #INCLUDE.
  166.  
  167.           Example:
  168.  
  169.                pre test /ikeydefs.inc
  170.  
  171.  
  172.      /L
  173.  
  174.           List.
  175.           Directives are copied as comments.
  176.           ON is the same as #LIST, OFF the same as #XLIST.
  177.           Default is ON.
  178.           See #LIST.
  179.  
  180.  
  181.      /M
  182.  
  183.           Math.
  184.           Constant expressions in #DEFINES are evaluated.  Parameter
  185.           substitutions are made before evaluation.
  186.           ON is the same as #MATH, OFF the same as #XMATH.
  187.           Default is ON.
  188.           See #MATH.
  189.  
  190.  
  191.      /N<filename>
  192.  
  193.           Library file name.
  194.           The default name is "LIBRARY.SRC".
  195.           See #LIBRARY.
  196.  
  197.  
  198.      /O
  199.  
  200.           Overwrite existing output file without warning.
  201.           If /O is off and the output file already exists, a warning prompt
  202.           appears.
  203.           Default is OFF.
  204.  
  205.  
  206.      /P<path>
  207.  
  208.           Path for includes and library.
  209.           See #PATH.
  210.  
  211.  
  212.      /Q
  213.  
  214.           Quiet.
  215.           No Display of filenames or line numbers.
  216.           Default is OFF.
  217.  
  218.  
  219.      /R<DOS command>
  220.  
  221.           Run a DOS command after completion of processing.
  222.           Runs only if processing completes without error.
  223.           The output file name will be applied as a parameter unless
  224.           <DOS command> is in quotes.  If <DOS command> contains spaces, it
  225.           must be surrounded by quotes.  If "%s" appears in <DOS command>,
  226.           the output file name will be substituted. Memory available to the
  227.           DOS command is reduced by about 100k.
  228.  
  229.           Examples:
  230.  
  231.                pre test /rclipper
  232.                     (will run: clipper test.prg)
  233.  
  234.                pre test /r"clipper %s -m"
  235.                     (will run: clipper test.prg -m)
  236.  
  237.                pre test /r"DIR"
  238.                     (will run: DIR)
  239.  
  240.           To save the memory overhead of the run command use a batch file:
  241.  
  242.                pre test
  243.                if not errorlevel 1 clipper test
  244.  
  245.  
  246.      /S
  247.           Show Defines.
  248.           After all other processing is done, displays a list of all the
  249.           #DEFINES encountered.
  250.           Useful for debugging.
  251.           Default is OFF.
  252.  
  253.  
  254.      /T
  255.  
  256.           Test Date.
  257.           Process only if the input file date and time is later than the
  258.           output file date and time.
  259.           Default is OFF.
  260.  
  261.  
  262.      /U
  263.  
  264.           Update default switches.
  265.           Used in conjunction with the other switches to change the program
  266.           defaults.
  267.           If used with versions of DOS older than 3.0, "PRE.EXE" must be in
  268.           the current directory.
  269.           Updates the program file and then exits without processing any
  270.           input files.
  271.           When used with /I, /D, or /# switches, stores the first of each
  272.           switch found.  With other switches stores the last occurrence of
  273.           the switch.
  274.           Warning - switches in the pre environment variable will affect
  275.           the result of the update switch.
  276.  Directives:
  277.  
  278.  
  279.      All directives can be upper or lower case (#define,#DEFINE), but
  280.      parameters may depend on the setting of the /C switch.
  281.      A directive must be the only thing on a line except for inline
  282.      comments (&&).  Inline comments do not become part of the directive.
  283.      Any physical line beginning with a poundsign (#) will be treated as a
  284.      directive.  Continuations (;) are not recognized in regular source
  285.      lines so do not use continuations to break up an expression that is to
  286.      be expanded by the preprocessor.  Continuations may be used with
  287.      directive declarations, but the combined length may not exceed 255.
  288.      Directives are evaluated after and therefore override any equivalent
  289.      command line switches.
  290.  
  291.  
  292.      #<library identifier>
  293.  
  294.           Include a source code block.
  295.           See #LIBRARY.
  296.  
  297.  
  298.      #* [<comment>]
  299.  
  300.           Preprocessor comment line.
  301.  
  302.  
  303.      #BLANK (#XBLANK)
  304.  
  305.           Blank lines and comments are (are not) copied to the output file.
  306.           Overrides /B.
  307.           To keep output file line numbers aligned with input file line
  308.           numbers, leave #BLANK on and #LIST on (see #LIST).
  309.           Default is #BLANK.
  310.  
  311.  
  312.  
  313.      #COMMENT (#XCOMMENT)
  314.  
  315.           Begins (ends) a comment block.
  316.           Lines following #COMMENT are commented out with an asterisk (*)
  317.           until a #XCOMMENT directive occurs.
  318.           Default is #XCOMMENT.
  319.  
  320.  
  321.      #DEFINE <identifier or function> [<constant or expression>]
  322.  
  323.           An identifier consists of letters,numbers, or underscore up to a
  324.           maximum length of 255.
  325.           A function is an identifier with a set of parentheses containing
  326.           optional replaceable parameters. Function invocations may be
  327.           nested.  Warning: be sure that complex expressions do not create
  328.           a definition loop.  In some cases, invoking a function using the
  329.           same variable names that were used in the function definition can
  330.           confuse the preprocessor (see the examples).
  331.           The <constant or expression> will be used by the preprocessor to
  332.           replace any occurrences of the <identifier or function> in the
  333.           source code.
  334.           The maximum length of a <constant or expression> is 255.
  335.           The total length of the #DEFINE may not exceed 255 characters.
  336.           Replacements will not be done within comments, quotes (single or
  337.           double), text blocks, or #IGNORE blocks.
  338.           The <constant or expression> may be a previously defined
  339.           identifier or function.  The <constant or expression> is optional
  340.           (see #IF, #IFDEF, #IFNDEF).
  341.           #DEFINE's may be stacked (#DEFINE the same identifier multiple
  342.           times) and then unstacked one at a time with #UNDEF (useful for
  343.           creating "local" #DEFINE's).
  344.  
  345.           Examples:
  346.  
  347.                #define esc 27
  348.                Any occurrence of 'esc' will be replaced with '27'.
  349.  
  350.                #define zips esc
  351.                Assuming that 'esc' was previously defined as '27', any
  352.                occurrence of 'zips' will be replaced with 27.
  353.  
  354.                #define zips Hotsy Totsy
  355.                'zips' has been stacked and will now produce 'Hotsy Totsy'.
  356.  
  357.                #undef zips
  358.                'zips' will produce '27'.
  359.  
  360.                #undef zips
  361.                'zips' will now produce 'zips'.
  362.  
  363.                #define inc(x) x = x + 1
  364.                Any occurrence of the pattern 'inc(something)' will be
  365.                replaced by 'something = something + 1'.
  366.  
  367.                #define keypress(c) keyboard(chr(c))
  368.                Assuming the previous definitions, 'keypress(esc)' will be
  369.                translated to 'keyboard(chr(27))'.
  370.  
  371.                #define max(i,j) if(i>j,i,j)
  372.                At least one bizarre example is required - 'max(max(A,B),C)'
  373.                will produce 'if(if(A>B,A,B)>C,if(A>B,A,B),C)'.
  374.  
  375.  
  376.      #DQUOTE (#XDQUOTE)
  377.  
  378.           Process inside double quotes.
  379.           See switch /2.
  380.  
  381.  
  382.  
  383.      #GOTO <label>
  384.  
  385.           Skips to the specified label, commenting out all lines in
  386.           between.  The label must occur AFTER the #GOTO directive -
  387.           backward references are not allowed.  If the label is not found
  388.           the program ends with an error.
  389.           See #LABEL.
  390.  
  391.  
  392.      #IF [<identifier>] [<constant>]. . . [#ELSE] . . . #ENDIF
  393.  
  394.           If <identifier> is equal to <constant>, process following lines
  395.           until #ELSE or #END is found.  If <identifier> and/or <constant>
  396.           is left out, the following lines are NOT processed.
  397.           May be nested up to 100 deep.
  398.           See #IFDEF.
  399.  
  400.  
  401.  
  402.      #IFDEF [<identifier>] [constant or expression] . . [#ELSE] . . #ENDIF
  403.  
  404.           If defined . . .
  405.           Blocks of code may be processed or ignored depending on whether
  406.           <identifier> has been defined.  The second parameter of the
  407.           #DEFINE statement is ignored in this context.
  408.           #IFDEF without an identifier will effectively comment out a block
  409.           of code.
  410.           May be nested up to 100 deep.
  411.  
  412.           Example:
  413.  
  414.                #define debug
  415.                #ifdef debug
  416.                  ? 'Debugging'
  417.                #endif
  418.  
  419.  
  420.      #IFNDEF <identifier> . . . [#ELSE] . . . #ENDIF
  421.  
  422.           If not defined . . .
  423.           See #IFDEF.
  424.  
  425.  
  426.      #IGNORE (#XIGNORE)
  427.  
  428.           Copy following lines to output file but do not (do) process.
  429.           (Lines beginning with '#' are not copied).
  430.           Default is #XIGNORE.
  431.  
  432.  
  433.      #INCLUDE <filename>
  434.  
  435.           The file specified by <filename> will be processed and
  436.           incorporated into the output file. The filename may include drive
  437.           and path.
  438.           #INCLUDE's may be nested (i.e. an included file may include
  439.           another file, etc.) but beware of the snake eating its tail.
  440.           See QINCLUDE.
  441.  
  442.  
  443.  
  444.      #LABEL <label>
  445.  
  446.           Identifies a label for the #GOTO directive.  A label may be any
  447.           combination of letters, numbers, and underscores up to a length
  448.           of 255 characters.
  449.  
  450.  
  451.  
  452.      #LIBRARY <filename>
  453.  
  454.           The filename (may include path) of a source code library.
  455.           Overrides /N.
  456.           The default filename is 'LIBRARY.SRC'.
  457.           A source code library is a file with blocks of code in the
  458.           following format:
  459.  
  460.                note <description of block>
  461.                *<library identifier>
  462.                .
  463.                .
  464.                source code
  465.                .
  466.                .
  467.  
  468.  
  469.           A block ends at the next line that starts with 'note' or *eof.
  470.           The library format is compatible with the SourceView library
  471.           format used in dBRIEF (trademark of Global Technologies Corp).
  472.           The <library identifier> has the same format as directive
  473.           identifiers.
  474.  
  475.  
  476.      #LIST (#XLIST)
  477.  
  478.           Directives are (are not) copied to the output file as comments
  479.           (preceded by '*').
  480.           Overrides /L.
  481.           To force the line numbers of the output file to correspond with
  482.           the line numbers of the input file, turn #LIST on in the input
  483.           file and off in any #INCLUDE files (see #QINCLUDE).
  484.           The default is #LIST.
  485.  
  486.  
  487.      #MATH (#XMATH)
  488.  
  489.           Constant expressions in #DEFINES are evaluated.  Parameters are
  490.           substituted before evaluation.
  491.  
  492.           Example:
  493.  
  494.                #define n 4
  495.                #define arrcnt n + 1
  496.                ? arrcnt
  497.                     with math on becomes: ? 5
  498.                     with math off       : ? 4 + 1
  499.  
  500.  
  501.      #PATH <path>
  502.  
  503.           If #INCLUDE or #LIBRARY filenames are given without a drivespec
  504.           or path, the preprocessor looks for the file first in the default
  505.           directory, then in the #PATH path.  #PATH will override /P.
  506.  
  507.  
  508.      #QINCLUDE <filename>
  509.  
  510.           #INCLUDE with implicit #XLIST and #XBLANK.
  511.           Useful for keeping line number alignment between input and output
  512.           files.
  513.           See #INCLUDE.
  514.  
  515.  
  516.      #SQUOTE (#XSQUOTE)
  517.  
  518.           Process inside single quotes.
  519.           See switch /1
  520.  
  521.  
  522.      #UNDEF <identifier or function>
  523.  
  524.           Undefines a previous #DEFINE.
  525.           See #DEFINE.
  526.  
  527.  
  528.      #XBLANK
  529.  
  530.           See #BLANK.
  531.  
  532.  
  533.      #XIGNORE
  534.  
  535.           See #IGNORE.
  536.  
  537.  
  538.      #XLIST
  539.  
  540.           See #LIST.
  541.  
  542.  
  543.      #XMATH
  544.  
  545.           See #MATH.
  546. Operators:
  547.  
  548.  
  549.      Concatenating operator (##).
  550.  
  551.           Used in the <constant or expression> part of a #DEFINE to join
  552.           two parameters.  Parameters are reevaluated after joining.
  553.  
  554.           Examples:
  555.  
  556.                #define jam(i) X##i
  557.                jam(4)
  558.                     (translated to: X4)
  559.  
  560.                #define stickto(x,y)  x##y
  561.                stickto(Altos,4)
  562.                     (translated to: Altos4)
  563.  
  564.                #define n 9
  565.                stickto(Knight,n)
  566.                     (translated to: Knight9
  567.  
  568.  
  569.      Stringizing operator (#).
  570.  
  571.           Used in the <constant or expression> part of a #DEFINE to place
  572.           quotes around the following parameter.  The parameter is
  573.           evaluated before the quotes are inserted.  If stringizing results
  574.           in adjacent quotes, the quotes are removed and replaced by a
  575.           single space.
  576.           Single or double quotes may be selected with the /' and /"
  577.           switches.
  578.  
  579.           Examples:
  580.  
  581.                #define stringer(x) #x
  582.                ? stringer(Spurious)
  583.                     (translated to: ? "Spurious")
  584.  
  585.                #define message(msg) ? #msg"Error"
  586.                message(Unknown)
  587.                     (translated to: ? "Unknown Error")
  588.  
  589.                #define number 4
  590.                #define count(n) #n#times.
  591.                ? count(number)
  592.                     (translated to: ? "4 times." Error Messages.
  593.  
  594.  
  595.      Where appropriate, the following error messages will include the
  596.      filename, line number, and the contents of the line being processed. 
  597.      In some cases the line will be displayed partially translated.
  598.  
  599.  
  600.      #ELSE without #IF.
  601.      #ELSEIF without #IF.
  602.      #ENDIF without #IF.
  603.      DEFINE definition <constant or expression> exceeds length limit: 255
  604.      DEFINE <identifier>  exceeds length limit: 255
  605.      Disk Full, program terminated.
  606.      Escape pressed, program ended.
  607.      Expression too complex, or definition loop.
  608.      File: <filename> not found.
  609.      Input file: <filename> not found.
  610.      Invalid directive: <identifier>
  611.      Invalid drive: <drivespec>
  612.      Invalid output file: <filename>
  613.      Invalid Parameter: <command line parameter>
  614.      Invalid switch: <switch>
  615.      Invalid drive: <drivespec>
  616.      Label not found: <label>
  617.      Library file: <filename> not found.
  618.      Maximum command line directives exceeded: 50
  619.      Maximum Include nesting level exceeded: 10
  620.      Maximum line length exceeded: 255
  621.      Maximum nesting level exceeded: 10
  622.      Maximum number of #DEFINES exceeded: 4000
  623.      Out of Memory
  624.      Output file <filename> is "read only" !
  625.      Output file <filename> is same as input file !
  626.      Too Many files open: <number>
  627.      Unmatched Parentheses in function.
  628.      Update failed: <program name> not found.
  629.  
  630. Limits:
  631.  
  632.      Number of Defines                       4000 or available memory.
  633.  
  634.      Size of directive identifier            255*
  635.  
  636.      Size of defined constant or expression  255*
  637.  
  638.           * Note: Sum of identifier size and defined constant or expression
  639.           cannot exceed maximum line length (255).
  640.  
  641.      Number of command line parameters       50 or DOS limit on command
  642.                                              length.
  643.  
  644.      Line length                             255
  645.  
  646.      File length                             Available disk space.
  647.  
  648.      #INCLUDE nesting                        10 or available memory or DOS
  649.                                              limit on number of open files.
  650.  
  651.      #IF,#IFDEF,#IFNDEF nesting              10
  652.  
  653.      Minimum available memory required       200k (for about 200 defines).
  654.  
  655.      Run Switch (/r) memory overhead         136k
  656.  
  657.  
  658.  
  659. Technical support:
  660.  
  661.      Available to registered users by mail or Compuserve.
  662.  
  663. Gary Crouse
  664. 4629 S. Xavier Street
  665. Denver, CO 80236
  666. (CompuServe: 71525,1417)
  667. Phone: (303) 795-6719
  668. REGISTRATION
  669.  
  670.  
  671.  
  672. Name ___________________________________ DATE______________
  673.  
  674.  
  675. Company ________________________________ PRE VERSION # ____
  676.  
  677.  
  678. Address ___________________________________________________
  679.  
  680.  
  681. City, State, Zip __________________________________________
  682.  
  683.  
  684. Phone ________________________ Compuserve ID ______________
  685.  
  686.  
  687. Where did you get your copy of PRE ? ______________________
  688.  
  689.  
  690.                
  691.  
  692. Registration Fee: $40.00
  693.  
  694. Registered users will receive:
  695.   The current version of the preprocessor.
  696.   Printed documentation.
  697.   Pre.ng - Pre documentation in Norton Guides format
  698.   Apply.exe - a global program execution filter.
  699.   Predoc.com - a #comment extract filter.
  700.   Technical support.
  701.  
  702. To register your copy of this software, fill out this form and send it with
  703. payment to:
  704.  
  705.      Gary Crouse
  706.      4629 S. Xavier Street
  707.      Denver, CO 80236
  708.