puman5.n

早期freebsd实现

will produce an execution profile if any of the
.B z ,
.B t
or
.B c
options is specified on the command line.
If none of these options is specified, then
.XP
functions as a program reformatter.
.PP
It is important to note that only the
.B z
and
.B w
options of
.XP ,
which are common to
.PI ,
.PC ,
and
.XP
can be controlled in comments.
All other options must be specified on the command line to have any effect.
.PP
The following options are relevant to profiling with
.XP :
.SH
Include the bodies of all routines in the profile \- a
.PP
.I Pxp
normally suppresses printing the bodies of routines
which were never executed, to make the profile more compact.
This option forces all routine bodies to be printed.
.SH
Suppress declaration parts from a profile \- d
.PP
Normally a profile includes declaration parts.
Specifying
.B d
on the command line suppresses declaration parts.
.SH
Eliminate include directives \- e
.PP
Normally,
.XP
preserves
.B include
directives to the output when reformatting a program,
as though they were comments.
Specifying
.B \-e
causes the contents of the specified files to be reformatted
into the output stream instead.
This is an easy way to eliminate
.B include
directives, e.g. before transporting a program.
.SH
Fully parenthesize expressions \- f
.PP
Normally
.XP
prints expressions with the minimal parenthesization necessary to
preserve the structure of the input.
This option causes
.I pxp
to fully parenthesize expressions.
Thus the statement which prints as
.LS
d := a + b mod c / e
.LE
with minimal parenthesization, the default, will print as
.LS
d := a + ((b mod c) / e)
.LE
with the
.B f
option specified on the command line.
.SH
Left justify all procedures and functions \- j
.PP
Normally, each
.B procedure
and
.B function
body is indented to reflect its static nesting depth.
This option prevents this nesting and can be used if the indented
output would be too wide.
.SH
Print a table summarizing procedure and function calls \- t
.PP
The
.B t
option causes
.XP
to print a table summarizing the number of calls to each
.B procedure
and
.B function
in the program.
It may be specified in combination with the
.B z
option, or separately.
.SH
Enable and control the profile \- z
.PP
The
.B z
profile option is very similar to the
.B i
listing control option of
.PI .
If
.B z
is specified on the command line, then all arguments up to the
source file argument which ends in `.p' are taken to be the names of
.B procedure s
and
.B function s
or
.B include
files which are to be profiled.
If this list is null, then the whole file is to be profiled.
A typical command for extracting a profile of part of a large program
would be
.LS
% \*bpxp -z test parser.i compiler.p\fR
.LE
This specifies that profiles of the routines in the file
.I parser.i
and the routine
.I test
are to be made.
.NH 2
Formatting programs using pxp
.PP
The program
.XP
can be used to reformat programs, by using a command of the form
.LS
% \*bpxp dirty.p > clean.p\fR
.LE
Note that since the shell creates the output file `clean.p' before
.XP
executes, so `clean.p' and `dirty.p' must not be the same file.
.PP
.I Pxp
automatically paragraphs the program, performing housekeeping
chores such as comment alignment, and
treating blank lines, lines containing exactly one blank
and lines containing only a form-feed character as though they
were comments, preserving their vertical spacing effect in the output.
.I Pxp
distinguishes between four kinds of comments:
.HP
.RS
.IP 1)
Left marginal comments, which begin in the first column of the
input line and are placed in the first column of an output line.
.IP 2)
Aligned comments, which are preceded by no input tokens on the
input line.
These are aligned in the output with the running program text.
.IP 3)
Trailing comments, which are preceded in the input line by a token with
no more than two spaces separating the token from the comment.
.IP 4)
Right marginal comments, which are preceded in the input line
by a token from which they are separated by at least three spaces or a tab.
These are aligned down the right margin of the output,
currently to the first tab stop after the 40th column from the current
``left margin''.
.RE
.LP
Consider the following program.
.LS
% \*bcat comments.p\fR
.so comments1.p
.LE
When formatted by
.XP
the following output is produced.
.LS
% \*bpxp comments.p\fR
.so commentsout
%
.LE
The following formatting related options are currently available in
.XP .
The options
.B f
and
.B j
described in the previous section may also be of interest.
.SH
Strip comments \-s
.PP
The
.B s
option causes
.XP
to remove all comments from the input text.
.SH
Underline keywords \- \_
.PP
A command line argument of the form
.B \-\_
as in
.LS
% \*bpxp -_ dirty.p\fR
.LE
can be used to cause
.XP
to underline all keywords in the output for enhanced readability.
.SH
Specify indenting unit \- [23456789]
.PP
The normal unit which
.XP
uses to indent a structure statement level is 4 spaces.
By giving an argument of the form
\fB\-\fId\fR
with
.I d
a digit,
2 \(<=
.I d
\(<= 9
you can specify that
.I d
spaces are to be used per level instead.
.NH 2
Pxref
.PP
The cross-reference program
.I pxref
may be used to make cross-referenced listings of Pascal
programs.
To produce a cross-reference of the program in the file
`foo.p'
one can execute the command:
.LS
% \*bpxref foo.p\fR
.LE
The cross-reference is, unfortunately, not block structured.
Full details on
.I pxref
are given in its manual section
.I pxref
(1).
.NH 2
Multi-file programs
.PP
A text inclusion facility is available with
.UP .
This facility allows the interpolation of source text from other
files into the source stream of the translator.
It can be used to divide large programs into more manageable pieces
for ease in editing, listing, and maintenance.
.PP
The
.B include
facility is based on that of the
.SM
UNIX
.NL
C compiler.
To trigger it you can place the character `#' in the first portion of
a line and then, after an arbitrary number of blanks or tabs,
the word
`include'
followed by a filename enclosed in single `\(aa' or double `"' quotation
marks.
The file name may be followed by a semicolon `;' if you wish to treat
this as a pseudo-Pascal statement.
The filenames of included files must end in `.i'.
An example of the use of included files in a main program would be:
.LS
\*bprogram\fR compiler(input, output, obj);

#\*binclude\fR "globals.i"
#\*binclude\fR "scanner.i"
#\*binclude\fR "parser.i"
#\*binclude\fR "semantics.i"

\*bbegin\fR
    { main program }
\*bend\fR.
.LE
.PP
At the point the
.B include
pseudo-statement is encountered in the input, the lines from
the included file are interpolated into the input stream.
For the purposes of translation and runtime diagnostics and
statement numbers in the listings and post-mortem backtraces,
the lines in the included file are numbered from 1.
Nested includes are possible up to 10 deep.
.PP
See the descriptions of the
.B i
option of
.PI
in section 5.2
above;
this can be used to control listing when
.B include
files are present.
.PP
When a non-trivial line is encountered in the source text after an
.B include
finishes, the
`popped' filename is printed, in the same manner as above.
.PP
For the purposes of error diagnostics when not making a listing, the filename
will be printed before each diagnostic if the current
filename has changed since the last
filename was printed.
.NH 2
Separate Compilation with Pc
.PP
A separate compilation facility is provided with the Berkeley Pascal compiler,
.PC .
This facility allows programs to be divided into a number of files and 
the pieces to be compiled individually,
to be linked together at some later time.
This is especially useful for large programs,
where small changes would otherwise require
time-consuming re-compilation of the entire program.
.PP
Normally,
.PC
expects to be given entire Pascal programs.
However, if given the
.B \-c
option on the command line, it will accept a sequence of definitions and
declarations, and compile them into a
.B .o
file, to be linked with a Pascal program at a later time.
In order that procedures and functions be available across
separately compiled files, they must be declared with the directive
.B external .
This directive is similar to the directive
.B forward
in that it must precede the resolution of the function or procedure,
and formal parameters and function result types must be specified
at the
.B external
declaration and may not be specified at the resolution.
.PP
Type checking is performed across separately compiled files.
Since Pascal type defintions define unique types,
any types which are shared between separately compiled files
must be the same definition.
This seemingly impossible problem is solved using a facility similar
to the
.B include
facility discussed above.
Definitions may be placed in files with the extension
.B .h
and the files included by separately compiled files.
Each definition from a 
.B .h
file defines a unique type, and all uses of a definition from the same 
.B .h
file define the same type.
Similarly, the facility is extended to allow the definition of 
.B const s
and the declaration of
.B label s,
.B var s,
and
.B external
.B function s
and
.B procedure s.
Thus
.B procedure s
and
.B function s
which are used between separately compiled files must be declared
.B external ,
and must be so declared in a
.B .h
file included by any file which calls or resolves the 
.B function
or 
.B procedure .
Conversely,
.B function s
and
.B procedure s
declared
.B external
may only be so declared in 
.B .h
files.
These files may be included only at the outermost level,
and thus define or declare global objects.
Note that since only
.B external
.B function
and
.B procedure
declarations (and not resolutions) are allowed in
.B .h
files, statically nested
.B function s
and
.B procedure s
can not be declared
.B external .
.PP
An example of the use of included
.B .h
files in a program would be:
.LS
\*bprogram\fR compiler(input, output, obj);

#\*binclude\fR "globals.h"
#\*binclude\fR "scanner.h"
#\*binclude\fR "parser.h"
#\*binclude\fR "semantics.h"

\*bbegin\fR
    { main program }
\*bend\fR.
.LE
.PP
This might include in the main program
the definitions and declarations of all the global 
.B label s,
.B const s,
.B type s and
.B var s
from the file globals.h,
and the
.B external
.B function
and
.B procedure
declarations for each of the
separately compiled files for the scanner, parser and semantics.
The header file
.I scanner.h
would contain declarations of the form:
.LS
\*btype\fR
    token = \*brecord\fR
	{ token fields }
    \*bend\fR;

\*bfunction\fR scan(\*bvar\fR inputfile: text): token;
    \*bexternal\fR;
.LE
.ne 15
Then the scanner might be in a separately compiled file containing:
.LS
#\*binclude\fR "globals.h"
#\*binclude\fR "scanner.h"

\*bfunction\fR scan;
\*bbegin\fR
    { scanner code }
\*bend\fR;
.LE
which includes the same global definitions and declarations
and resolves the scanner functions and procedures declared
.B external
in the file scanner.h.