Category : Pascal Source Code
Archive   : EPB233.ZIP
Filename : EPB233.DOC

ED'S PASCAL BEAUTIFIER (EPB)
Copyright 1992 By Edward Lee
25 July 1992



EPB v2.32 formats Pascal source code in a consistent form, with fully
automatic indentation. The resulting source code can be well compressed.
EPB generally preserves existing line breaks but conditionally inserts line
breaks after semicolons and the keywords BEGIN, DO, ELSE, OF, RECORD,
REPEAT, and THEN. EPB does not check for syntax errors, so you must rely
on yourself or on the compiler for syntax checking. EPB can, however, help
you to see programming or typing errors that you may have made. For
example, if you forget to close a comment, EPB will not format any source
code that comes after the beginning of the comment until the comment is
closed. This means that if your code is formatted in the default upper-
case mode, then you can toggle the case of the Pascal keywords with the
-(m)ixed case switch to see if any code is being commented out. EPB can
also help you to see unintended semantics in nested Pascal code, especially
in nested IF THEN ELSE constructs. All user-declared identifiers for
constants, data types, variables, labels, procedures, and functions are
capitalized to the way they first appear in the Pascal source code. EPB is
a tool with many features that will help make it easier for you to
comprehend and to maintain Pascal source code, whether you are an
experienced or a beginning Pascal programmer.

Examples of EPB invocations are provided at the end of this file.

EPB requires over 256 KB of free conventional memory in order to run. The
maximum length of a user-declared identifier can be 255 characters, which
exceeds the Turbo Pascal v4.0 standard. The Turbo Pascal v4.0 compiler
still only recognizes the first 63 characters of an identifier as
significant, however. The maximum indentation depth is arbitrarily set at
255 indentation levels. Statements nested that deeply would probably
exceed Turbo Pascal v4.0's maximum line length. If one of your programs
ever exceeds the maximum line length with deeply nested IF THEN ELSE
constructs, then you may want to change the ElseIndent constant to 0 (zero)
in the EPB.PAS source code that is provided and recompile EPB.

If your machine crashes or locks up while using NCACHE v6.0 or some other
resident program during the execution of EPB, your source file will most
likely be saved as a "*.BAK" backup file or as the original file. If such
an unfortunate event occurs, regain control over your computer and check
the file size of your Pascal source code to make sure that the size is not
0 (zero). If the file size is zero, then look for the program's filename
with the ".BAK" file name extension. If that file is also gone, you may
have to resort to using a file recovery utility such as the ones found in
Norton Utilities. I recommend that you do NOT use NCACHE v6.0 with any of
your important or high input/output performance programs. If you have
NCACHE v6.0, you might want to consider getting a more recent version or
another disk caching program.

EPB is continually being improved. If you have any specific suggestions
for improving EPB, you can contact the author via email as
[email protected] on Usenet.



INVOCATION EXAMPLES

1. The following three invocations of EPB are equivalent to each other:

epb file

epb file.pas

epb file.pas file.pas

In the above examples, the original file is renamed to *.BAK before
being used as the input file. Any one of the invocations is equivalent
to the following two commands in sequence at the MSDOS prompt:

rename file.pas file.bak
epb file.bak file.pas

I generally recommend the first invocation, "epb file", since it is the
simplest and since it resembles a compilation such as, "tpc file".


2. Display a help screen:

epb


3. Format file.pas with (-m)ixed case Pascal identifiers:

epb -m file

The "-m" switch shuts off the default capitalization of (Turbo) Pascal
keywords.


4. (-S)ubstitute all of the identifiers in file.pas that match "xx" with
"MoreDescriptiveIdentifier":

epb file -s xx MoreDescriptiveIdentifier

or

epb -s xx MoreDescriptiveIdentifier file

I often use short identifiers when developing code to save time and
later want to use more descriptive names for the sake of readability.
During identifier substitution, comments and literal strings are left
alone by EPB, as well as substrings in larger identifiers. Starting
with EPB v2.33, the letter E in real constants such as 1.0e-10 is also
ignored as well as the letters in hexadecimal constants such as $fe00.
This substitution option is superior to many editors' search and
replace features, since EPB takes some of the Pascal syntax into
account. If you also want to change some identifiers that are within
comments, you will have to change those identifiers without EPB,
because EPB never alters the content of comments.


5. Accept input data from some other program via the standard (-i)nput
stream, format it, and output the formatted data to outfile.pas:

producer | epb -i outfile

A PRODUCER is any program that outputs data to the standard output
stream. Any program that displays data on the screen is a producer
unless it is directly writing to the screen, bypassing the BIOS. One
program's output stream can be another program's input stream. Any
program that accepts data from the standard input stream is known as a
consumer. EPB acts as a CONSUMER in the above invocation.


6. Accept input data from another program via the standard (-i)nput
stream, process it, and send the output data to some other program via
the standard (-o)utput stream:

producer | epb -io | consumer

Programs like MORE or Buerg's LIST /S are possible consumers.


7. Get input data from the file "infile.pas", process it, and put the
output data in a file named "outfile.pas", not changing the contents of
"infile.pas":

epb infile outfile


8. Get input data from file.pas, process it, and send the output data to
the standard (o)utput stream which, in this case, leads to the screen:

epb file -o

When data is sent to the standard output stream with no output pipe
("|"), it is conventional in both MSDOS and Unix for the output to
appear on the display device.


9. Get the input data from the standard (-i)nput stream (the keyboard in
this case), format the data, and output the data to the standard
(-o)utput stream (the screen in this case):

epb -io

This invocation is useful for determining how EPB will format a small
code segment that is entered from the keyboard. It is conventional in
both MSDOS and Unix for standard input data to come from the keyboard
when no input pipe ("|") is specified. You can terminate your input on
a separate line by pressing [Ctrl]-Z or the [F6] function key, followed
by pressing the [Enter] or [Return] key.


10. Shut off the output of parentheses comments:

epb -p file

This is a preprocessor-like feature of EPB that I am considering for
removal. Let me know if you think that this option is worth keeping.


11. Shut off the output of bracket comments:

epb -b file

This is exactly like example 10, except that bracket comments, {...},
are deleted instead of parentheses comments, (* ... *).


12. Examples 10 and 11 can be combined:

epb -bp file

To shut off the output of all comments.



ACKNOWLEDGMENTS


EPB is influenced by the work of AT&T Unix authors in its naming (e.g.
John's Own Version of Emacs, JOVE) and in the structure of its interface
(e.g. '-' as the switch character.).

In the EPB versions past v1.5, some users have suggested improvements to
the program. My thanks go out to them for helping to make EPB more
interesting.

EPB is intended to be a free program, a gift to the other programmers out
there, so if you paid money for this, you may have unnecessarily parted
with some of your money. All rights to EPB are reserved by the author, and
EPB is provided without warranty, though it is unlikely that you will ever
encounter any serious problems with this program.


-Ed L
[email protected]

Unofficial member of a nonexistent group, S.T.A.T.S. (Some Take Acronyms
Too Seriously).