============================================================================ EPP V1.0. E Preprocessor. Copyright ©1993 Barry Wills. All rights reserved. ============================================================================ DISTRIBUTION. ~~~~~~~~~~~~ This product may be freely distributed under the following restrictions: 1. The complete contents of the original archive must remain intact. 2. The original material may in no way be modified. (See P.S at the end of this document for extenuation of this term.) 3. This product may not be distributed for profit. A nominal copying fee is authorized (for cost of materials and shipping and handling comparable to that charged by Fred Fish.) 4. Commercial distribution of this product without written permission from the author is forbidden. USE OF THIS PRODUCT. ~~~~~~~~~~~~~~~~~~~ This product may be used under the following restrictions: 1. Non-commercial use of this product is free of charge. 2. Commercial use of this product without written permission from the author is forbidden. This includes shareware. 3. Honorable mention of the author and product must be included in the client documentation (non-commercial and licensed-commercial.) 4. This product may not be used for malicious intent. DISCLAIMER. ~~~~~~~~~~ This product is provided without any warranty, express or implied. The user of this product assumes full responsibility for any damage resulting from the use and/or misuse of this product. CONTENTS. ~~~~~~~~ This archive should contain the following files: EPP - Executable V0.11b. EPP.doc - Copyright notice and product information (this file). EPP.e - V0.13b source. EPP.history - Revision history. Example1 - Directory containing an example EPP project. Example2 - Directory containing an example EPP project. Fishcon.txt - Short program description. Readme_First - Getting started. Pmodules/* - example real-world modules. ============================================================================ WHAT'S NEW? ~~~~~~~~~~ - From V0.14b, which was never distributed: Removed the constraints on line length -vs- buffer size. After close examination and much trying to break it, I decided the safeguard wasn't necessary. There is now a mimimum of 20-byte file buffers and source lines, and NO MAXIMUM LIMIT. So if you got the RAM, use it! :-) This warning still stands: line length must be large enough to accommodate the longest line of source. If a line is split, a keyword or a comment delimiter could be missed, and your source output may be chewed. :-( Updated this manual (about time! |-) * * * New email address. * * * Corrected token parser to recognize PROC main(). Previously it would only recognize PROC main (). Didn't investigate, but this probably bled over into other areas. Thanks to Son Le for finding this one! - From V1.0: New Turbo switch (-t) to improve speed (!!!) ***** SEE SECTION ON "Usage" FOR A DESCRIPTION. REQUIREMENTS. ~~~~~~~~~~~~ An Amiga with at least 1Meg of RAM. I have tested EPP inside of about 750K, and EPP processed itself with room to spare. Of course, you will also need Wouter van Oortmerssen's Amiga E V2.1b. (NOTE: the Amiga E compiler requires at least 1Meg of RAM to be able to do anything meaningful.) EPP should not be KickStart sensitive. DESCRIPTION. ~~~~~~~~~~~ EPP is an E project development tool which allows an E application to be developed in a modular fashion. Use of this tool contributes towards some important software engineering concepts, such as reusability and modularity. Anyone who has tried to write a respectable application in a language which doesn't support modules can attest to the unwieldiness of a huge main program file. And anyone who has written multiple applications in a language which supports modules can attest to the luxury of being able to reuse source components without having to block- copy source code from several locations. Wouter van Oortmerssen, the author of E, has promised to support user modules in a future release. The release of EPP does not presume that he will not make good on his promise. On the contrary, I am eagerly awaiting it! But in the meantime, EPP can do the basics, and hopefully the appearance of EPP will allow Wouter to concentrate on the more important (I think) features of the language: floating point support and OOP. Much care has been taken to ensure that EPP remain simple enough that only minimal changes should be required to E source code in order to become compatible with future releases of E which incorporate modules. At that time, EPP may respectfully retire. »»»»»  ENOUGH!!! HOW DO I USE THIS THING??? ««««« USAGE. ~~~~~ Invocation: EPP -l### -b### -s -t infile[.e] outfile[.e] · infile = filename of the main program, '.e' extension is optional. · outfile = filename of the processed program, which will (hopefully) be suitable for compilation with ec, the E compiler. · -l### = maximum expected source line length; increase for longer lines. Valid range is 20 to MAX_LONG_INTEGER, default is 128. · -b### = input buffer size in bytes; use size of largest source file for maximum speed, decrease if memory is low. Valid range is 20 to MAX_LONG_INTEGER, default is 128. · -s = silence progress messages (except for error messages). · -t = Turbo mode; read the "NOTE ON TURBO MODE" in the section "OTHER CONSIDERATIONS" before using this switch! EPP allows primitive inclusion of user pseudo-modules. EPP pseudo- modules are E source code. EPP is similar to a very primitive C preprocessor in that it merges source code as specified by module inclusion directives entered into the source code. Module inclusion directives use the following notation: PMODULE 'dev:path/filename' The keyword PMODULE is required. The optional 'dev:' is any valid logical DOS device. 'Path' is the optional subdirectory in which the module can be found. 'Filename' is the name of the module file without the '.e' extension. The '.e' extension is added automatically by EPP. (NOTE: EPP does not use a default logical device or directory to locate modules. The device and path must always be specified if the modules are not in the current directory.) EPP will merge all global declarations in the order of dependency as determined by the PMODULE statements: first come, first serve. EPP will then merge all procedures and functions in the same order. The final output file contains all modules' comments and some additional module information inserted at strategic locations by EPP. Runtime progress messages are sent to stdout. PROGRAM STRUCTURE. ~~~~~~~~~~~~~~~~~ PMODULE statements can be put anywhere. The only thing you have to mind is that the modules containing types, constants, and variables needed by subsequent modules must be included first, otherwise E will inform you of the error. The general format of a main program is: PMODULE 'mod1'[; ...] /* Containing types and/or procs. */ RAISE constant condition[, ...] OPT [directives] ENUM identifier[, ...] CONST identifier[, ...] OBJECT indentifier ... ENDOBJECT PMODULE 'anothermod'[; ...] /* Containing types and/or procs. */ PROC identifier () ENDPROC PMODULE 'moremods'[; ...] /* Containing types and/or procs. */ PROC main () ENDPROC /* END OF MAIN MODULE. */ As you can see, you have a lot of flexibility in placement of modules. EPP locates the declarations at the front of the final output file, and the procedures are inserted at the place of module declaration. Pseudo- modules MAY BE NESTED AS DEEPLY AS RESOURCES WILL PERMIT, i.e., as long as you have enough stack and memory you can have PMODULEs within PMODULEs within PMODULEs... * * * * * NOTE ON TURBO MODE: Turbo mode does *not* recognize PMODULE statements that occur after the first PROC statement in a module. Turbo mode does *not* check for duplicate PROC main ()s in modules. The reason for this is speed. Turbo mode does *NO PARSING* of the procs section of modules. * * * * * See the two example projects supplied with this package. These attempt to simulate the structure of real projects. OTHER CONSIDERATIONS. ~~~~~~~~~~~~~~~~~~~~ EPP is *NOT* like the COBOL COPY statement. Any global definitions and declarations in a module are moved to the global section of the main program. EPP tries to be smart about what it is reading. It is not, however, a full-blown syntax checker. EPP relies on good syntax in your modules, so you should test modules for syntax before using them with EPP. This will reduce the risk of brain damage. EPP allows you to keep a PROC main () in all modules to facilitate ease of testing. Any PROC main () encountered in modules other than the main module are omitted, and an E comment is inserted in the final output file to indicate this. This can be quite handy while testing a module since E requires a PROC main () in order to compile the module. EPP saves you the hassle of commenting and uncommenting code in your source module during development. HINT: place all test PROCs after PROC main () and EPP will ignore them. Likewise, if you want PROCs recognized by EPP, don't put them after a PROC main () in your pseudo-module. Since EPP is simply a sophisticated text file merger, it is up to you to ensure that all your modules' identifiers are unique. If they are not, the E compiler will inform you of the duplicate identifiers. CAUTION: In the instructions for compiling the examples the output file main.e is used. You are not restricted to using this name as the final output name. You are encouraged, however, to come up with a personal convention for naming the final output file. That way you will not risk accidentally overwriting your original source. One suggestion is to set up a separate directory to receive the final output file and compile it there: a directory in RAM: or RAD: would suffice for this, and you could easily set up a script to make the process less unwieldy. CAUTION: The default line length should be adequate for most programs. However, line length must be large enough to accommodate the longest line of source. If a line is split, a keyword or a comment delimiter could be missed, and your source output may be chewed. If EPP is producing strange output, check the length of your lines before reporting a possible bug. ============================================================================ LIMITATIONS. ~~~~~~~~~~~ · If you like to put comments outside of PROCs you will notice that some of them don't end up where you'd like, especially those that follow the global declarative section. See Example1 project, module 'mod2.e' for a demonstration of this phenomenon. EPP thinks that everything before the first PROC belongs to the global declaratives. HINT: keep your modules small and put your comments *inside* the PROC, immediately following the headers. TO DO (MAYBE). ~~~~~~~~~~~~~ · Macro expansion of identifiers. · Macro selection of source code (as in #ifdef ... #endif) · Optional exclusion of comments in final source output. · EPP directives in modules to automate command-line switches. Something like: POPT FILE='RAM:FinalOut' /* Set output file to RAM:FinalOut.e */ POPT LINE=150 /* Set the line length to 150 */ POPT BUFFER=30000 /* Set input file buffer to 30,000 bytes */ POPT PROGRESS=SILENT /* Silence progress messages. */ POPT PROGRESS=VERBOSE /* Turn 'em back on. */ ============================================================================ MISCELLANEOUS. ~~~~~~~~~~~~~ This product was developed in Amiga E language and tested on a Commodore Amiga 500 with the following configuration: KickStart V1.3, WorkBench V1.3, ©Commodore-Amiga, Inc. Amiga E V2.1, ©Wouter van Oortmerssen AZ V1.50, ©Jean-Michel Forgeas DataFlyer 500 SCSI controller Quantum 52M HD Dual 880K floppy drive 1M 16-bit Chip RAM CSA Derringer 030 accellerator: 68030 CPU @25MHz 68881 FPU @27MHz 4M 32-bit Fast RAM ============================================================================ CREDITS. ~~~~~~~ Special thanks go to: · Wouter van Oortmerssen for Amiga E! · Jean-Michel Forgeas and The Software Winery for their AZ text editor! ============================================================================ CONTACTING THE AUTHOR. ~~~~~~~~~~~~~~~~~~~~~ I can be reached by the following means: Internet: bwills@kirk.safb.af.mil USnail: Barry Wills 5528D Pryor Dr. Scott AFB, IL 62225 (USA) (618)-744-1096 I wrote this for my own use, but I hope you get as much use out of it as I do. Send mail, money, software, warm weather to the address(es) above. I am very interested in feedback; I will answer all mail. Good luck and enjoy! -- Barry P.S - Distributers and users of this program are hereby granted the right to replace the letters of the singly occurring expletive "shitloads" (now doubly occurring) with asterisks (*), character for character, if it so offends them. This is the only permitted change to the package contents. A package so changed MAY BE DISTRIBUTED IN THAT MODIFIED FORM (although there are some out there who would feel cheated if they couldn't figure out just what that darn word was before somone axed it!) This amendment is intended for the convenience of G-rated BBSs. (Those receiving this package in its censored form may contact me and I will reveal to them the original word so they can change it back.) ============================================================================