"Preprocessor.class" Documentation

Purpose

This application provides a simple source code preprocessor for Java and HTML files, which is missing in the standard Java Development Kit. Specifically, this preprocessor provides support for conditional compilation, multiple source files and predefined constants for the compilation time, date, source file and source line number.

Files In This Distribution

Preprocessor.class is the actual class file. Preprocessor.html is the associated documentation, which you are currently reading.

Command Line

Assuming that the Preprocessor.class file is on your CLASSPATH, type

java Preprocessor [ options ][ filename ]

Where the [ options ] are as follows -

• -c loads the Java compiler ( javac ) after preprocessing the source file.
• -k keeps the output file. This is the default when -c is not used and always true for *.html files. Output files are only deleted in the case of *.java source code where the compiler is loaded and -k is not specified on the command line.
• -v enables verbose output from the Preprocessor to the stdout stream.
• -s enables debug output to the stdout stream. This is really meant for internal use by FORT Telecommunications.
• -o sets options for the compiler. At present, only two compiler options are supported - -o g enables debug tables in the class file and -o O enables optimisations in the bytecodes. If you need to pass other options, invoke the compiler manually on the output file.
• -d defines a token in the symbol table, in the same manner as #define.

[filename] must be *.jpp for Java source code, or *.hpp for HTML. Note that while these are required for command line specified files, #included files are not limited to such naming restrictions.

At present, only one source file may be specified on the command - this will be fixed in a later release.

Preprocessor Directives

#ifdef / #ifndef token ... [ #else ] ... #endif

These are the conditional directives. #endif is mandatory and must be present. Note that #ifdef and #ifndef can enable and disable other preprocessor directives.

#include <file>

Reads from the source file file and allows one output file to be constructed from many component source files.

#define token

Unlike the preprocessor directive of the same name in C and C++, #define does not assign a value to a symbol or allow for macro expansion. This #define is very simple - it merely adds the symbol token to the internal symbol table.

#undef token

Removes the definition of the symbol token from the internal symbol namespace.

#error <text>

Produces the user defined error message text to stdout and halts the preprocessor.

#warning <text>

Produces the user defined warning message text to stdout.

#line linenumber

Sets the value of the __LINE__ predefined constant to linenumber.

Pre-defined Constants

__LINE__

Resolves to an integer expression - the line number in the current source file. May be altered using the #line directive.

__FILE__

Resolves to a quoted string expression - the file name of the current source file.

__DATE__

Resolves to a quoted string expression - the current system date.

__TIME__

Resolves to a quoted string expression - the current system time.

Pre-defined Symbols

__JAVA__

Defined if the source file extension is *.jpp for the file name passed on the command line.

__HTML__

Defined if the source file extension is *.hpp for the file name passed on the command line.

Planned Enhancements

• Allow for assignment and macro expansion with #define.
• Get #include to use CLASSPATH or another environment variable.
• Multiple input source files and wildcards on the command line.
• Allow selection of Sun javac compiler or Microsoft jvc compiler from the command line.

License Agreement

Definitions

Within the context of this License Agreement, "FORT Telecommunications" and "Author" refer to FORT Telecommunications Limited and its employees. "Software" refers to the Java Preprocessor class developed by FORT Telecommunications and its associated distributed files.

Scope

FORT Telecommunications grants you a non-exclusive license to use the Software free of charge. As you are using the Software free of charge, you are not entitled to hard-copy documentation, support or telephone assistance other than at the discretion of FORT Telecommunications.

Disclaimer Of Warranty

Free of charge Software is provided on an "AS IS" basis, without warranty of any kind, including without limitation the warranties of merchantability, fitness for a particular purpose and non-infringement. The entire risk as to the quality and performance of the Software is borne by you. Should the Software prove defective, you and not FORT Telecommunications assume the entire cost of any service and repair. This disclaimer of warranty constitutes an essential part of the agreement.

SOME JURISDICTIONS DO NOT ALLOW EXCLUSIONS OF AN IMPLIED WARRANTY, SO THIS DISCLAIMER MAY NOT APPLY TO YOU AND YOU MAY HAVE OTHER LEGAL RIGHTS THAT VARY BY JURISDICTION.

Granted Rights

You may :

• Use the Software for the purposes originally intended by the Author,
• Copy the Software for archival purposes, provided any copy must contain all of the original Software's proprietary notices,
• Redistribute the Software to others provided no charge is made for such redistribution and that the Softwate is provided to others as it provided to yourself, without modifications, additions or deletions and in the same archive format.

You may not :

• Modify, translate, reverse engineer, decompile, disassemble (except to the extent applicable laws specifically prohibit such restriction), or create derivative works based on the Software
• Copy the Software other than as specified above
• Rent, lease, grant a security interest in, or otherwise transfer rights to the Software
• Remove any proprietary notices or labels on the Software.

Title

Title, ownership rights, and intellectual property rights in the Software shall remain in FORT Telecommunications and/or its suppliers. The Software is protected by the copyright laws and treaties. Title and related rights in the content accessed through the Software is the property of the applicable content owner and may be protected by applicable law. This License gives you no rights to such content.

Termination

The license will terminate automatically if you fail to comply with the limitations described herein. On termination, you must destroy all copies of the Software and Documentation.

LIMITATION OF LIABILITY

UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, TORT, CONTRACT, OR OTHERWISE, SHALL FORT TELECOMMUNICATIONS OR ITS SUPPLIERS OR RESELLERS BE LIABLE TO YOU OR ANY OTHER PERSON FOR ANY INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER COMMERCIAL DAMAGES OR LOSSES. IN NO EVENT WILL FORT TELECOMMUNICATIONS BE LIABLE FOR ANY DAMAGES IN EXCESS OF THE AMOUNT FORT TELECOMMUNICATIONS RECEIVED FROM YOU FOR A LICENSE TO THE SOFTWARE, EVEN IF FORT TELECOMMUNICATIONS SHALL HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY. THIS LIMITATION OF LIABILITY SHALL NOT APPLY TO LIABILITY FOR DEATH OR PERSONAL INJURY TO THE EXTENT APPLICABLE LAW PROHIBITS SUCH LIMITATION. FURTHERMORE, SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THIS LIMITATION AND EXCLUSION MAY NOT APPLY TO YOU.

High Risk Activities

The Software is not fault-tolerant and is not designed, manufactured or intended for use or resale as on-line control equipment in hazardous environments requiring fail-safe performance, such as in the operation of nuclear facilities, aircraft navigation or communication systems, air traffic control, direct life support machines, or weapons systems, in which the failure of the Software could lead directly to death, personal injury, or severe physical or environmental damage ("High Risk Activities"). FORT Telecommunications and its suppliers specifically disclaim any express or implied warranty of fitness for High Risk Activities.

Miscellaneous

This Agreement represents the complete agreement concerning this license and may amended only by a writing executed by both parties. THE ACCEPTANCE OF ANY PURCHASE ORDER PLACED BY YOU IS EXPRESSLY MADE CONDITIONAL ON YOUR ASSENT TO THE TERMS SET FORTH HEREIN, AND NOT THOSE IN YOUR PURCHASE ORDER. If any provision of this Agreement is held to be unenforceable, such provision shall be reformed only to the extent necessary to make it enforceable. This Agreement shall be governed by English law. The application the United Nations Convention of Contracts for the International Sale of Goods is expressly excluded.

Contacting FORT Telecommunications Limited

If you wish to subscribe to the announcement mailing list for this product and other forthcoming products, or if you wish to report a bug with the software or make a suggestion for an improvement or even a new product, please contact FORT Telecommunications Limited via e-mail to abrick@fort.co.uk

Obtaining source code

FORT Telecommunications Limited currently have no plans to release the source code to this product. However, should you be interested in receiving the source code, please get in touch with Andy Brick at the above e-mail address.

Updates

Updated versions of this product will be made available on various public ftp sites, Compuserve forums and so on as and when they become available.