M3PP(1) M3PP(1)
NAME
m3pp - pretty-print (i.e., format) a Modula-3 program
SYNTAX
m3pp [options] [file]
DESCRIPTION
m3pp is a pretty-printer for Modula-3 programs. It will take the
source code and make decisions on where to place line breaks, how far
to indent lines, etc. to produce a supposedly more readable version of
the program. This version of m3pp supports the Modula-3 language
including the so-called "twelve changes."
The pretty-printer reads its input from the specified file. If no file
is given, then the pretty-printer reads standard input. The formatted
version is always sent to standard output.
The pretty-printer can produce text output suitable for replacing your
code (the default) or PostScript output suitable for printing. Some
additional options are availble when producing PostScript output.
OPTIONS
The pretty-printer reads options from $HOME/.m3pp.pro.1, then
.m3pp.pro.1 in the current directory, then from the command line. Sin-
gle-letter abbreviations can be used, but no others are recognized.
-caps Recognize keywords in either lower or upper case and map them to
upper case in the output. If this option is not specified, key-
words must appear in upper case.
-margin n
Set the margin to n. The margin is the maximum width of an out-
put line. The pretty-printer occasionally exceeds this maximum,
so it's usually wise to set it a little lower than you want. If
this option is not specified, a margin of 75 is used.
-offset n
Set the offset to n. The offset is the number of spaces by which
a construct inside another one is indented. The default is 2 for
text ouput, and 4 for PostScript output.
-xcolumn n
Set the comment column to n. This is the column in which com-
ments that are on the same line as code but are not followed on
that line by code will start. To disable comment alignment,
specify -xcolumn 1. The default is 33 for text output, 80 for
PostScript output.
-src Use the SRC style of formatting (default).
-eric Use Eric's style. "END"s are emitted at the end of lines rather
than on a line by themselves. This option cannot be abbreviated.
-callspace
This inserts blank space around function calls and array sub-
scripts. "f(x,y)" becomes "f (x, y)" and "a[i]" becomes "a [i]".
This option cannot be abbreviated.
-noalign
The pretty-printer attempts to align const, variable, and type
declarations into columns. This option turns off the alignment.
It does not disable the alignment of formal parameter lists when
they don't fit on one line.
-whenbreak {always | early | late}
When the pretty-printer has to break a line that's too long, you
have two stylistic choices:
1: ALongFunctionCall(
withLongParameters, likeThisOne, andThisOne);
2: ALongFunctionCall(withLongParameters, likeThisOne,
andThisOne);
-whenbreak always tells the pretty-printer to use style 1,
always. Otherwise, it will consider BOTH styles, which takes
somewhat more time. If style 1 produces fewer lines, it will use
it. If they produce the same number of lines, then: -whenbreak
early says to use style 1, and -whenbreak late says to use style
2. The arguments can be abbreviated as a, e, or l. The default
is -whenbreak early.
-break
This is equivalent to -whenbreak always.
-follow
Normally, the formatter assumes that comments precede declara-
tions or code, and formats them at the same indentation level as
whatever follows. This style can also work fine with comments
that follow a declaration. This option changes the comment
indentation to more closely match the older version of the
pretty-printer, assuming that comments follow declarations. With
-follow, you get
CONST
maxElements = 3;
(* limit for number of elements *)
PROCEDURE AddOne(e: INTEGER);
instead of
CONST
maxElements = 3;
(* Add an element. *)
PROCEDURE AddOne(e: INTEGER);
In either case, a blank line will cause subsequent comments to be
aligned with the statements or declarations that follow. You get
CONST
maxElements = 3;
(* Add an element. *)
PROCEDURE AddOne(e: INTEGER);
in either mode. The chief disadvantage of this mode is that com-
ments in blocks of code are attached to the preceding statement
and indented one level unless they are preceded by a blank line.
-ZZ Use emacs filter mode. The formatter loops, accepting and for-
matting declarations, BEGIN-END groups, or modules. Each chunk
of code to be formatted should begin with a control-B (^B) and
end with a control-A (^A).
-ZZG Use emacs filter mode on a single chunk (for a different Emacs
package).
-text Produce text output. This is the default.
The following options are used when producing PostScript output.
Except for -portrait, they cannot be abbreviated. For the font
options, valid font names are PostScript names followed by an integer
point size (e.g. "Helvetica9"). The font metrics are located by
searching the colon-separated list of directories defined by the envi-
ronment variable AFMPATH. If AFMPATH is not defined, a hard-wired path
("/usr/local/lib/ps") is used.
-ps Produce PostScript output suitable for printing.
-portrait
Produce one-column portrait mode output. The default is two-col-
umn landscape mode output.
-bf font
Set the font used for formatting the body text of the program.
The default is Times-Roman10.
-kf font
Set the font used for formatting keywords. The default is Hel-
vetica7.
-bif font
Set the font used for formatting built-in identifiers. The
default is Times-Roman8.
-pf font
Set the font used for formatting procedure names. The default is
Times-Bold10.
-cf font
Set the font used for formatting comments. The default is Times-
Italic10.
-fcf font
Set the font used for formatting comments that aren't refilled
(see below). The default is Courier-Oblique9.
-ff font
Set the font used for formatting text and char literals. The
default is Courier9.
FEATURES
The pretty-printer fills long comments; that is, it chooses line breaks
inside long comments so as to fill up each line with words. This is
usually convenient, but occasionally disastrous: a carefully formated
table, equation, or program in the input will be reduced to a dense
paragraph in the output. To spare your formatted comments from this
fate, begin the comment with "(*|" or "(**", or begin the comment with
"(*" on a line by itself. The old style of marking each line individu-
ally is also supported. In filled comments, lines that begin with a
vertical bar ("|") in column 1 will not be filled.
Conversely, if you want a comment to be filled, begin the comment with
"(*" and place some text on the same line as the comment start. Prag-
mas are never reformatted. Pragmas and comments that are not reformat-
ted may still be moved left or right to an appropriate indentation
level.
The pretty-printer tries hard not to add or remove blank lines from the
program. It will add and remove line breaks, however.
The formatting rule used for CASE statements is geared toward programs
in which there is no vertical bar after the last case, and no vertical
bar before the ELSE clause. The same goes for TYPECASE and TRY state-
ments.
In selecting elements of multi-dimensional arrays, the syntax a[i][j]
means the same thing as a[i, j]. The second version will be handled
better by the pretty-printer.
The compiler currently ignores the portion of the input file that fol-
lows the module-terminating dot. However, the pretty-printer requires
that only properly-delimited comments appear in this portion of the
file. Therefore, if your file has any comments there, be sure that
they are enclosed within comment brackets.
If the input contains a syntactically valid compilation unit (that is,
a definition module, implementation module, or program module) then the
output becomes the corresponding pretty-printed version. If the input
contains a syntax error, then the output is pretty-printed up to the
lexical token that caused the syntax error, then a line is printed con-
sisting of the string "(* SYNTAX ERROR *)" followed by the offending
token, an error message is printed to standard error output, and the
remainder of the input is copied unchanged into the output. Regardless
of whether a syntax error is found, m3pp exits with status code 0. (If
the syntax error was caused by an unexpected end of file, then the
string "(* SYNTAX ERROR *)" will appear at the end of the output file.)
EXCEPTIONS
String constants of more than 500 characters, or input or output lines
of more than 500 characters, will overflow internal buffers. In case
these or any other run-time errors cause the program to abort, the out-
put file (if specified) will not be modified.
BUGS
The pretty-printer sometimes exceeds the margin limits due to details
of the formatting algorithm. The text that exceeds the limit usually
consists of closing delimiters, such as right parens and right brack-
ets. Setting the margin a little lower than you want usually does the
trick.
The -noalign option still uses the alignment machinery of the format-
ter, but tells it to reset its idea of the column boundaries after each
declaration. The bad side effect of this is that a declaration with a
large initializier can be formatted with the initializer snaking down
the right side of the page.
If you have alignment on and a record has some fields with initializ-
ers, but the last field has no initializer and no trailing semicolon
and is followed by a comment on the same line, then the other fields
may be aligned improperly. Fix this by adding a semicolon to the last
field declaration.
Systems Programming with Modula-3 edited by Greg Nelson. Prentice
Hall, 1991.
m3(1)
Bill Kalsow and Eric Muller (using the framework provided by ppmp).
David Nichols (Xerox PARC) and Jim Meehan (SRC) made a large number of
improvements and bug fixes. David Nichols added PostScript support,
which Bill Schilit (Xerox PARC and Columbia Univ.) ported into the cur-
rent version.
Bill Kalsow and Eric Muller
M3PP(1)