home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1994 #1 / monster.zip / monster / PROG_GEN / EDSV4064.ZIP / EPP-V1_1.ZIP / EPP.DOC < prev    next >
Text File  |  1993-06-26  |  16KB  |  402 lines
  1. ============================================================================
  2.  
  3.                          EPP V1.1.  E Preprocessor.
  4.              Copyright ⌐1993 Barry Wills.  All rights reserved.
  5.  
  6.  
  7. ============================================================================
  8.  
  9.  
  10. DISTRIBUTION.
  11. ~~~~~~~~~~~~
  12.    This product may be freely distributed under the following restrictions:
  13.  
  14.    1.  The complete contents of the original archive must remain intact.
  15.    2.  The original material may in no way be modified. (See P.S at the end
  16.        of this document for extenuation of this term.)
  17.    3.  This product may not be distributed for profit.  A nominal copying
  18.        fee is authorized (for cost of materials and shipping and handling
  19.        comparable to that charged by Fred Fish.)
  20.    4.  Commercial distribution of this product without written permission
  21.        from the author is forbidden.
  22.  
  23.  
  24.  
  25. USE OF THIS PRODUCT.
  26. ~~~~~~~~~~~~~~~~~~~
  27.    This product may be used under the following restrictions:
  28.  
  29.    1.  Non-commercial use of this product is free of charge.
  30.    2.  Commercial use of this product without written permission from the
  31.        author is forbidden.  This includes shareware.
  32.    3.  Honorable mention of the author and product must be included in the
  33.        client documentation (non-commercial and licensed-commercial.)
  34.    4.  This product may not be used for malicious intent.
  35.  
  36.  
  37.  
  38. DISCLAIMER.
  39. ~~~~~~~~~~
  40.    This product is provided without any warranty, express or implied.  The
  41.    user of this product assumes full responsibility for any damage resulting
  42.    from the use and/or misuse of this product.
  43.  
  44.  
  45.  
  46. CONTENTS.
  47. ~~~~~~~~
  48.    This archive should contain the following files:
  49.  
  50.      EPP          - Executable V1.1.
  51.      EPP.doc      - Copyright notice and product information (this file).
  52.      EPP.e        - V0.13b source.
  53.      EPP.history  - Revision history.
  54.      EPP_Example1 - Directory containing an example EPP project.
  55.      EPP_Example2 - Directory containing an example EPP projects, and module
  56.                     tests and demos.
  57.      Fishcon.txt  - Short program description.
  58.      Readme_First - Getting started.
  59.      Pmodules/*   - example real-world modules.
  60.  
  61.  
  62. ============================================================================
  63.  
  64.  
  65. WHAT'S NEW?
  66. ~~~~~~~~~~
  67.    ╖  More speed!  Thanks to Son Huu Le, who rearranged EPP's parsing
  68.       algorithm!
  69.  
  70.    ╖  Fixed bug in the Turbo routine.  Turbo was eating modules if the
  71.       default buffer size was not used.
  72.  
  73.    ╖  Added an OPT TURBO directive to turn on Turbo mode for the duration of
  74.       the invoking module.  This is good if you want fast processing, but
  75.       still want to see the progress messages for part of the project.
  76.  
  77.    ╖  New PModules!  Modules names cSkip* are optimized for speed and may be
  78.       used instead of the original skip* modules.  (This will require changes
  79.       to your main programs!  Read the comments in the modules to find out
  80.       how to use them properly.)  The old versions are still provided for
  81.       die-hards.  I will not distribute the old versions in future releases
  82.       (unless I forget to remove them :)
  83.  
  84.    ╖  Fixed bug in read() that dropped last line of a module if the line
  85.       did not end with a linefeed (ascii 10).  No more program crashes due
  86.       to this error. :)
  87.  
  88.    ╖  Replaced calls to write() with Write() for speed.
  89.  
  90.    ╖  Modified program to process CtrlC().
  91.  
  92.    ╖  Son Huu Le modified appendProcsToDefs() for speed and cosmetics.
  93.  
  94.  
  95. REQUIREMENTS.
  96. ~~~~~~~~~~~~
  97.    An Amiga with at least 1Meg of RAM.  I have tested EPP inside of about
  98.    500K, and EPP processed itself with room to spare.
  99.  
  100.    Of course, you will also need Wouter van Oortmerssen's Amiga E V2.1b or
  101.    better.  At the time of this release, Amiga E V2.1b is the most recent.
  102.    (NOTE: the Amiga E compiler requires at least 1Meg of RAM to be able to
  103.    do anything meaningful.)
  104.  
  105.    EPP should not be KickStart sensitive.
  106.  
  107.  
  108.  
  109. DESCRIPTION.
  110. ~~~~~~~~~~~
  111.    EPP is an E project development tool which allows an E application to be
  112.    developed in a modular fashion.  Use of this tool contributes towards
  113.    some important software engineering concepts, such as reusability and
  114.    modularity.  Anyone who has tried to write a respectable application in a
  115.    language which doesn't support modules can attest to the unwieldiness of
  116.    a huge main program file.  And anyone who has written multiple
  117.    applications in a language which supports modules can attest to the
  118.    luxury of being able to reuse source components without having to block-
  119.    copy source code from several locations.
  120.  
  121.    Wouter van Oortmerssen, the author of E, has promised to support user
  122.    modules in a future release.  The release of EPP does not presume that he
  123.    will not make good on his promise.  On the contrary, I am eagerly awaiting
  124.    it!  But in the meantime, EPP can do the basics, and hopefully the
  125.    appearance of EPP will allow Wouter to concentrate on the more important
  126.    (I think) features of the language:  floating point support and OOP.  Much
  127.    care has been taken to ensure that EPP remain simple enough that only
  128.    minimal changes should be required to E source code in order to become
  129.    compatible with future releases of E which incorporate modules.  At that
  130.    time, EPP may respectfully retire.
  131.  
  132.  
  133.            ╗╗╗╗╗ááENOUGH!!!  HOW DO I USE THIS THING???  ½½½½½
  134.  
  135.  
  136.  
  137. USAGE.
  138. ~~~~~
  139.    Invocation:  EPP -l### -b### -s -t infile[.e] outfile[.e]
  140.  
  141.    ╖ infile = filename of the main program, '.e' extension is optional.
  142.    ╖ outfile = filename of the processed program, which will
  143.      (hopefully) be suitable for compilation with ec, the E compiler.
  144.    ╖ -l### = maximum expected source line length; increase for longer lines.
  145.      Valid range is 20 to MAX_LONG_INTEGER, default is 128.
  146.    ╖ -b### = input buffer size in bytes; use size of largest source file for
  147.      maximum speed, decrease if memory is low.  Valid range is 20 to
  148.      MAX_LONG_INTEGER, default is 128.
  149.    ╖ -s = silence progress messages (except for error messages).
  150.    ╖ -t = Turbo mode; read the "NOTE ON TURBO MODE" in the section "PROGRAM
  151.      STRUCTURE" before using this switch!
  152.  
  153.  
  154.    EPP allows primitive inclusion of user pseudo-modules.  EPP pseudo-
  155.    modules are E source code.  EPP is similar to a very primitive C
  156.    preprocessor in that it merges source code as specified by module
  157.    inclusion directives entered into the source code.  Module inclusion
  158.    directives use the following notation:
  159.  
  160.  
  161.      PMODULE 'dev:path/filename'
  162.  
  163.  
  164.    The keyword PMODULE is required.  The optional 'dev:' is any valid
  165.    logical DOS device.  'Path' is the optional subdirectory in which the
  166.    module can be found.  'Filename' is the name of the module file without
  167.    the '.e' extension.  The '.e' extension is added automatically by EPP.
  168.    (NOTE:  EPP does not use a default logical device or directory to locate
  169.    modules.  The device and path must always be specified if the modules are
  170.    not in the current directory.)
  171.  
  172.    EPP will merge all global declarations in the order of dependency as
  173.    determined by the PMODULE statements:  first come, first serve.  EPP will
  174.    then merge all procedures and functions in the same order.
  175.  
  176.    The final output file contains all modules' comments.  Additional module
  177.    information is inserted at strategic locations by EPP if the -c switch is
  178.    specified on the command line.  Runtime progress messages are sent to
  179.    stdout, unless the -s switch is specified on the command line.
  180.  
  181.  
  182.  
  183. PROGRAM STRUCTURE.
  184. ~~~~~~~~~~~~~~~~~
  185.    PMODULE statements can be put anywhere (see the "NOTE ON TURBO MODE"
  186.    below for a caveat.)  The only thing you have to mind is that the modules
  187.    containing types, constants, and variables needed by subsequent modules
  188.    must be included first, otherwise EC will inform you of the error.  The
  189.    general format of a main program is:
  190.  
  191.  
  192.      PMODULE 'mod1'[; ...]  /* Containing types and/or procs. */
  193.  
  194.      [Global defs and decls...]
  195.  
  196.      PMODULE 'anothermod'[; ...]  /* Containing types and/or procs. */
  197.  
  198.      PROC identifier ()
  199.        ...
  200.      ENDPROC
  201.  
  202.      PMODULE 'moremods'[; ...]  /* Containing types and/or procs. */
  203.  
  204.      PROC main ()
  205.        ...
  206.      ENDPROC
  207.        /* END OF MODULE. */
  208.  
  209.  
  210.    As you can see, you have a lot of flexibility in placement of modules.
  211.    EPP locates any module declarations at the front of the final output file,
  212.    and the procedures are inserted at the place of module declaration.
  213.    Pseudo-modules MAY BE NESTED AS DEEPLY AS RESOURCES WILL PERMIT, i.e., as
  214.    long as you have enough stack and memory you can have PMODULEs within
  215.    PMODULEs within PMODULEs...
  216.  
  217.                           *    *    *    *    *
  218.  
  219.    NOTE ON TURBO MODE:  Turbo mode does *not* recognize PMODULE statements
  220.    that occur after the first PROC statement in a module.  Turbo mode does
  221.    *not* check for duplicate PROC main()s in modules.  The reason for this
  222.    is speed.  Turbo mode does *NO PARSING* of the procs section of modules.
  223.  
  224.    The OPT TURBO directive starts TURBO mode within a single module for the
  225.    duration of that module.  It can be placed anywhere in a module outside
  226.    of a PROC..ENDPROC.  The Turbo routine will be invoked upon the next
  227.    occurrence of the PROC keyword.  OPT TURBO must, of course, be uncommented.
  228.    It may be placed as far down in the module as desired.  Only one OPT TURBO
  229.    directive should be used within a module file since subsequent occurrences
  230.    will not be parsed once the Turbo routine is invoked, and EC will not
  231.    recognize "OPT TURBO".
  232.  
  233.  
  234.                           *    *    *    *    *
  235.  
  236.    See the two examples directories supplied with this package.  EPP_Example1
  237.    attempts to simulate the structure of a real project.  EPP_Example2
  238.    contains examples of how to use some of the modules provided in the
  239.    PModules directory.
  240.  
  241.  
  242.  
  243. OTHER CONSIDERATIONS.
  244. ~~~~~~~~~~~~~~~~~~~~
  245.    EPP is *NOT* like the COBOL COPY statement.  Any global definitions and
  246.    declarations in a module are moved to the global section of the main
  247.    program.
  248.  
  249.    EPP tries to be smart about what it is reading.  It is not, however, a
  250.    full-blown syntax checker.  EPP relies on good syntax in your modules, so
  251.    you should test modules for syntax before using them with EPP.  This will
  252.    reduce the risk of brain damage. :)
  253.  
  254.    EPP allows you to keep a PROC main() in all modules to facilitate ease
  255.    of testing.  Any PROC main() encountered in modules other than the main
  256.    module are omitted, and, if EPP comments are turned on, an E comment is
  257.    inserted in the final output file to indicate this.  This can be quite
  258.    handy while testing a module since E requires a PROC main() in order to
  259.    compile the module.  EPP saves you the hassle of commenting and
  260.    uncommenting code in your source module during development.  (HINT:  place
  261.    all test PROCs after PROC main() and EPP will ignore them.  Likewise, if
  262.    you want PROCs recognized by EPP, don't put them after a PROC main() in
  263.    your modules.)  THIS FEATURE IS NOT AVAILABLE IF YOU CHOOSE TO USE THE
  264.    TURBO OPTION IN A MODULE.  (HINT:  use the OPT TURBO directive in modules
  265.    that don't need this feature to speed up processing.  Duplicate PROC
  266.    main()s will still be omitted in modules not using OPT TURBO.)
  267.  
  268.    Since EPP is simply a sophisticated text file merger, it is up to you to
  269.    ensure that all your modules' identifiers are unique.  If they are not,
  270.    the E compiler will inform you of the duplicate identifiers.
  271.  
  272.    CAUTION:  In the instructions for compiling the examples (the file
  273.    Readme_First.doc) the output file main.e is used.  You are not restricted
  274.    to using this name as the final output name.  You are encouraged, however,
  275.    to come up with a personal convention for naming the final output file.
  276.    That way you will not risk accidentally overwriting your original source.
  277.    One suggestion is to set up a separate directory to receive the final
  278.    output file and compile it there:  a directory in RAM: or RAD: is ideal
  279.    for this, and you could easily set up a script to make the process less
  280.    unwieldy.
  281.  
  282.    CAUTION:  The default line length should be adequate for most programs.
  283.    However, line length must be large enough to accommodate the longest line
  284.    of source.  If a line is split, a keyword or a comment delimiter could be
  285.    missed, and your source output may be chewed.  If EPP is producing strange
  286.    output, check the length of your lines before reporting a possible bug.
  287.  
  288.  
  289. ============================================================================
  290.  
  291.  
  292. LIMITATIONS.
  293. ~~~~~~~~~~~
  294.     ╖ If you like to put comments outside of PROCs you will notice that some
  295.       of them don't end up where you'd like, especially those that follow
  296.       the global declarative section.  See Example1 project, module 'mod2.e'
  297.       for a demonstration of this phenomenon.  EPP thinks that everything
  298.       before the first PROC belongs to the global declaratives.  (HINT:  keep
  299.       your modules small and put your comments *inside* the PROC, immediately
  300.       following the headers.)
  301.  
  302.  
  303.  
  304.  
  305. TO DO (MAYBE).
  306. ~~~~~~~~~~~~~
  307.     ╖ Macro expansion of identifiers.
  308.     ╖ Macro selection of source code (as in #ifdef ... #endif)
  309.     ╖ Optional exclusion of comments in final source output.
  310.  
  311.  
  312. ============================================================================
  313.  
  314.  
  315. MISCELLANEOUS.
  316. ~~~~~~~~~~~~~
  317. This product was developed in Amiga E language and tested on a Commodore
  318. Amiga 500 with the following configuration:
  319.  
  320.    KickStart V1.3, WorkBench V1.3, ⌐Commodore-Amiga, Inc.
  321.    Amiga E V2.1, ⌐Wouter van Oortmerssen
  322.    AZ V1.50, ⌐Jean-Michel Forgeas
  323.  
  324.    DataFlyer 500 SCSI controller
  325.    Quantum 52M HD
  326.    Dual 880K floppy drive
  327.    1M 16-bit Chip RAM
  328.    CSA Derringer 030 accellerator:
  329.       68030 CPU @25MHz
  330.       68881 FPU @27MHz
  331.       4M 32-bit Fast RAM
  332.  
  333.  
  334. ============================================================================
  335.  
  336.  
  337. CREDITS.
  338. ~~~~~~~
  339. Special thanks go to:
  340.  
  341.   ╖ Wouter van Oortmerssen for Amiga E!  (And for revealing to me the
  342.     insidious, ubiquitous, sideways smiley face :)
  343.  
  344.   ╖ Jean-Michel Forgeas and The Software Winery for their AZ text editor!
  345.  
  346.   ╖ Son Huu Le for his testing, analysis, and modifications.  If it weren't
  347.     for his initiative, EPP would probably still be taking its own good time
  348.     (and yours, too! :)
  349.  
  350.  
  351. ============================================================================
  352.  
  353.  
  354. CONTACTING THE AUTHOR.
  355. ~~~~~~~~~~~~~~~~~~~~~
  356. I can be reached by the following means:
  357.  
  358.   Internet:  bwills@kirk.safb.af.mil
  359.  
  360.   USnail:    Barry Wills
  361.              5528D Pryor Dr.
  362.              Scott AFB, IL 62225 (USA)
  363.              (618)-744-1096
  364.  
  365. I wrote this for my own use, but I hope you get as much use out of it as I
  366. do.  Send mail, money, software, warm weather to the address(es) above.  I
  367. am very interested in feedback; I will answer all mail.  Good luck and
  368. enjoy!
  369.  
  370.   -- Barry
  371.  
  372.  
  373.  
  374. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  375.                 ╗╗╗╗╗  Join the Amiga E mailing list!  ½½½½½
  376.  
  377.                              Email the words
  378.                           "Please subscribe me!"
  379.                     to amigae-request@bkhouse.cts.com.
  380.  
  381.                Get in tune with Life, the Universe...and E!
  382.  
  383.                ("Those are in the wrong order," says Wouter.
  384.                   But I didn't want to obscure the pun! :-)
  385.  
  386. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  387.  
  388.  
  389. P.S - Distributers and users of this program are hereby granted the right to
  390. replace the letters of the singly occurring expletive "shitloads" (now doubly
  391. occurring) with asterisks (*), character for character, if it so offends
  392. them.  This is the only permitted change to the package contents.  A package
  393. so changed MAY BE DISTRIBUTED IN THAT MODIFIED FORM (although there are some
  394. out there who would feel cheated if they couldn't figure out just what that
  395. darn word was before somone axed it!)  This amendment is intended for the
  396. convenience of G-rated BBSs.  (Those receiving this package in its censored
  397. form may contact me and I will reveal to them the original word so they can
  398. change it back :)
  399.  
  400.  
  401. ============================================================================
  402.