![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to puman5.n CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / share / doc / ps1 / 04.pascal|
Return to puman5.n CVS log | Up to [CSRG BSD Unix] / 43BSDReno / share / doc / ps1 / 04.pascal |
1.1 root 1: .\" Copyright (c) 1980 Regents of the University of California.
2: .\" All rights reserved. The Berkeley software License Agreement
3: .\" specifies the terms and conditions for redistribution.
4: .\"
5: .\" @(#)puman5.n 6.2 (Berkeley) 5/7/86
6: .\"
7: .if !\n(xx \{\
8: .so tmac.p \}
9: .ND
10: .nr H1 4
11: .NH
12: Details on the components of the system
13: .NH 2
14: Options
15: .PP
16: The programs
17: .PI ,
18: .PC ,
19: and
20: .XP
21: take a number of options.\*(dg
22: .FS
23: \*(dgAs
24: .IX
25: uses
26: .PI
27: to translate Pascal programs,
28: it takes the options of
29: .PI
30: also.
31: We refer to them here, however, as
32: .PI
33: options.
34: .FE
35: There is a standard
36: .UX
37: convention for passing options to programs on the command line,
38: and this convention is followed by the
39: .UP
40: system programs.
41: As we saw in the examples above,
42: option related arguments consisted of the character `\-' followed
43: by a single character option name.
44: .PP
45: Except for the
46: .B b
47: option
48: which takes a single digit value,
49: each option may be set on (enabled)
50: or off (disabled.)
51: When an on/off valued option appears on the command line of
52: .PI
53: or
54: .PX
55: it inverts the default setting of that option.
56: Thus
57: .LS
58: % \*bpi -l foo.p\fR
59: .LE
60: enables the listing option
61: .B l ,
62: since it defaults off, while
63: .LS
64: % \*bpi -t foo.p\fR
65: .LE
66: disables the run time tests option
67: .B t ,
68: since it defaults on.
69: .PP
70: In additon to inverting the default settings of
71: .PI
72: options on the command line, it is also possible to control the
73: .PI
74: options
75: within the body of the program by using comments of a special
76: form illustrated by
77: .LS
78: {$l-}
79: .LE
80: .PP
81: Here we see that the opening comment delimiter (which could also be a `(*')
82: is immediately followed by the character `$'.
83: After this `$', which signals the start of the option list,
84: we can place a sequence of letters and option controls, separated by `,'
85: characters\*(dd.
86: .FS
87: \*(ddThis format was chosen because it is used by Pascal 6000-3.4.
88: In general the options common to both implementations are controlled
89: in the same way so that comment control in options is mostly
90: portable.
91: It is recommended, however, that only one control be put per comment for
92: maximum portability, as the Pascal 6000-3.4
93: implementation will ignore controls
94: after the first one which it does not recognize.
95: .FE
96: The most basic actions for options are to set them, thus
97: .LS
98: {$l+ Enable listing}
99: .LE
100: or to clear them
101: .LS
102: {$t-,p- No run-time tests, no post mortem analysis}
103: .LE
104: Notice that `+' always enables an option and `\-' always disables it,
105: no matter what the default is.
106: Thus `\-' has a different meaning in an option comment than it has on the
107: command line.
108: As shown in the examples,
109: normal comment text may follow the option list.
110: .NH 2
111: Options common to Pi, Pc, and Pix
112: .PP
113: The following options are common to both the compiler
114: and the interpreter.
115: With each option we give its default setting,
116: the setting it would have if it appeared on the command line,
117: and a sample command using the option.
118: Most options are on/off valued,
119: with the
120: .B b
121: option
122: taking a single digit value.
123: .SH
124: Buffering of the file output \- b
125: .PP
126: The
127: .B b
128: option controls the buffering of the file
129: .I output .
130: The default is line buffering, with flushing at
131: each reference to the file
132: .I input
133: and under certain other circumstances detailed in section 5
134: below.
135: Mentioning
136: .B b
137: on the command line, e.g.
138: .LS
139: % \*bpi -b assembler.p\fR
140: .LE
141: causes standard output to be block buffered,
142: where a block is some system\-defined number of characters.
143: The
144: .B b
145: option may also be controlled in comments.
146: It, unique among the
147: .UP
148: options,
149: takes a single digit value rather than an on or off setting.
150: A value of 0, e.g.
151: .LS
152: {$b0}
153: .LE
154: causes the file
155: .I output
156: to be unbuffered.
157: Any value 2 or greater causes block buffering and is equivalent
158: to the flag on the command line.
159: The option control comment setting
160: .B b
161: must precede the
162: .B program
163: statement.
164: .SH
165: Include file listing \- i
166: .PP
167: The
168: .B i
169: option takes the name of an
170: .B include
171: file,
172: .B procedure
173: or
174: .B function
175: name and causes it
176: to be listed while translating\*(dg.
177: .FS
178: \*(dg\*bInclude\fR files are discussed in section 5.9.
179: .FE
180: Typical uses would be
181: .LS
182: % \*bpix -i scanner.i compiler.p\fR
183: .LE
184: to make a listing of the routines in the file scanner.i, and
185: .LS
186: % \*bpix -i scanner compiler.p\fR
187: .LE
188: to make a listing of only the routine
189: .I scanner .
190: This option is especially useful for conservation-minded programmers making
191: partial program listings.
192: .SH
193: Make a listing \- l
194: .PP
195: The
196: .B l
197: option enables a listing of the program.
198: The
199: .B l
200: option defaults off.
201: When specified on the command line, it causes
202: a header line identifying the version of the translator in use
203: and a line giving the modification time of the file being translated
204: to appear before the actual program listing.
205: The
206: .B l
207: option is pushed and popped by the
208: .B i
209: option at appropriate points in the program.
210: .SH
211: Standard Pascal only \- s
212: .PP
213: The
214: .B s
215: option causes many of the features of the
216: .SM UNIX
217: implementation which are not found in standard Pascal
218: to be diagnosed as `s' warning errors.
219: This option defaults off and is enabled when mentioned on the command line.
220: Some of the features which are diagnosed are:
221: non-standard
222: .B procedure s
223: and
224: .B function s,
225: extensions to the
226: .B procedure
227: .I write ,
228: and the padding of constant strings with blanks.
229: In addition, all letters are mapped to lower case except in
230: strings and characters so that the case of keywords and identifiers
231: is effectively ignored.
232: The
233: .B s
234: option is most useful when a program is to be transported, thus
235: .LS
236: % \*bpi -s isitstd.p\fR
237: .LE
238: will produce warnings unless the program meets the standard.
239: .SH
240: Runtime tests \- t and C
241: .PP
242: These
243: options control the generation of tests that subrange variable
244: values are within bounds at run time.
245: .PI
246: defaults to generating tests and uses the option
247: .B t
248: to disable them.
249: .PC
250: defaults to not generating tests,
251: and uses the option
252: .B C
253: to enable them.
254: Disabling runtime tests also causes
255: .B assert
256: statements to be treated as comments.\*(dd
257: .FS
258: \*(ddSee section A.1 for a description of
259: .B assert
260: statements.
261: .FE
262: .SH
263: Suppress warning diagnostics \- w
264: .PP
265: The
266: .B w
267: option, which defaults on,
268: allows the translator to print a number of warnings about inconsistencies
269: it finds in the input program.
270: Turning this option off with a comment of the form
271: .LS
272: {$w-}
273: .LE
274: or on the command line
275: .LS
276: % \*bpi -w tryme.p\fR
277: .LE
278: suppresses these usually useful diagnostics.
279: .SH
280: Generate counters for a pxp execution profile \- z
281: .PP
282: The
283: .B z
284: option, which defaults off,
285: enables the production of execution profiles.
286: By specifying
287: .B z
288: on the command line, i.e.
289: .LS
290: % \*bpi -z foo.p\fR
291: .LE
292: or by enabling it in a comment before the
293: .B program
294: statement causes
295: .PI
296: and
297: .PC
298: to insert operations in the interpreter code to
299: count the number of times each statement was executed.
300: An example of using
301: .XP
302: was given in section 2.6;
303: its options are described in section 5.6.
304: Note that the
305: .B z
306: option cannot be used on separately compiled programs.
307: .NH 2
308: Options available in Pi
309: .SH
310: Post-mortem dump \- p
311: .PP
312: The
313: .B p
314: option defaults on,
315: and causes the runtime system to initiate a post-mortem
316: backtrace when an error occurs.
317: It also cause
318: .X
319: to count statements in the executing program,
320: enforcing a statement limit to prevent infinite loops.
321: Specifying
322: .B p
323: on the command line disables these checks and the ability
324: to give this post-mortem analysis.
325: It does make smaller and faster programs, however.
326: It is also possible to control the
327: .B p
328: option in comments.
329: To prevent the post-mortem backtrace on error,
330: .B p
331: must be off at the end of the
332: .B program
333: statement.
334: Thus, the Pascal cross-reference program was translated with
335: .LS
336: % \*bpi -pbt pxref.p\fR
337: .LE
338: .NH 2
339: Options available in Px
340: .PP
341: The first argument to
342: .X
343: is the name of the file containing the program to be interpreted.
344: If no arguments are given, then the file
345: .I obj
346: is executed.
347: If more arguments are given, they are available to the Pascal
348: program by using the built-ins
349: .I argc
350: and
351: .I argv
352: as described in section 4.6.
353: .ne 7
354: .PP
355: .I Px
356: may also be invoked automatically.
357: In this case, whenever a Pascal object file name is given as a command,
358: the command will be executed with
359: .X
360: prepended to it; that is
361: .LS
362: % \*bobj primes\fR
363: .LE
364: will be converted to read
365: .LS
366: % \*bpx obj primes\fR
367: .LE
368: .NH 2
369: Options available in Pc
370: .SH
371: Generate assembly language \- S
372: .PP
373: The program is compiled and the assembly language
374: output is left in file appended .s.
375: Thus
376: .LS
377: % \*bpc -S foo.p\fR
378: .LE
379: creates a file
380: .I foo.s .
381: No executable file is created.
382: .SH
383: Symbolic Debugger Information \- g
384: .PP
385: The
386: .B g
387: option causes the compiler to generate information
388: needed by
389: .I sdb (1)
390: the symbolic debugger.
391: For a complete description of
392: .I sdb
393: see Volume 2c of the
394: .UX
395: Reference Manual.
396: .SH
397: Redirect the output file \- o
398: .PP
399: The
400: .I name
401: argument after the
402: .B -o
403: is used as the name of the output file instead of
404: .I a.out .
405: Its typical use is to name the compiled program using
406: the root of the file name.
407: Thus:
408: .LS
409: % \*bpc -o myprog myprog.p\fR
410: .LE
411: causes the compiled program to be called
412: .I myprog .
413: .SH
414: Generate counters for a \*iprof\fP execution profile \- p
415: .PP
416: The compiler produces code which counts the number of times each
417: routine is called.
418: The profiling is based on a periodic sample taken by the
419: system rather than by inline counters used by
420: .XP .
421: This results in less degradation in execution,
422: at somewhat of a loss in accuracy.
423: See
424: .I prof (1)
425: for a more complete description.
426: .SH
427: Run the object code optimizer \- O
428: .PP
429: The output of the compiler is run through
430: the object code optimizer.
431: This provides an increase in compile time in
432: exchange for a decrease in compiled code size
433: and execution time.
434: .NH 2
435: Options available in Pxp
436: .PP
437: .I Pxp
438: takes, on its command line, a list of options followed by the program file
439: name, which must end in `.p' as it must for
440: .PI ,
441: .PC ,
442: and
443: .IX .
444: .I Pxp
445: will produce an execution profile if any of the
446: .B z ,
447: .B t
448: or
449: .B c
450: options is specified on the command line.
451: If none of these options is specified, then
452: .XP
453: functions as a program reformatter.
454: .PP
455: It is important to note that only the
456: .B z
457: and
458: .B w
459: options of
460: .XP ,
461: which are common to
462: .PI ,
463: .PC ,
464: and
465: .XP
466: can be controlled in comments.
467: All other options must be specified on the command line to have any effect.
468: .PP
469: The following options are relevant to profiling with
470: .XP :
471: .SH
472: Include the bodies of all routines in the profile \- a
473: .PP
474: .I Pxp
475: normally suppresses printing the bodies of routines
476: which were never executed, to make the profile more compact.
477: This option forces all routine bodies to be printed.
478: .SH
479: Suppress declaration parts from a profile \- d
480: .PP
481: Normally a profile includes declaration parts.
482: Specifying
483: .B d
484: on the command line suppresses declaration parts.
485: .SH
486: Eliminate include directives \- e
487: .PP
488: Normally,
489: .XP
490: preserves
491: .B include
492: directives to the output when reformatting a program,
493: as though they were comments.
494: Specifying
495: .B \-e
496: causes the contents of the specified files to be reformatted
497: into the output stream instead.
498: This is an easy way to eliminate
499: .B include
500: directives, e.g. before transporting a program.
501: .SH
502: Fully parenthesize expressions \- f
503: .PP
504: Normally
505: .XP
506: prints expressions with the minimal parenthesization necessary to
507: preserve the structure of the input.
508: This option causes
509: .I pxp
510: to fully parenthesize expressions.
511: Thus the statement which prints as
512: .LS
513: d := a + b mod c / e
514: .LE
515: with minimal parenthesization, the default, will print as
516: .LS
517: d := a + ((b mod c) / e)
518: .LE
519: with the
520: .B f
521: option specified on the command line.
522: .SH
523: Left justify all procedures and functions \- j
524: .PP
525: Normally, each
526: .B procedure
527: and
528: .B function
529: body is indented to reflect its static nesting depth.
530: This option prevents this nesting and can be used if the indented
531: output would be too wide.
532: .SH
533: Print a table summarizing procedure and function calls \- t
534: .PP
535: The
536: .B t
537: option causes
538: .XP
539: to print a table summarizing the number of calls to each
540: .B procedure
541: and
542: .B function
543: in the program.
544: It may be specified in combination with the
545: .B z
546: option, or separately.
547: .SH
548: Enable and control the profile \- z
549: .PP
550: The
551: .B z
552: profile option is very similar to the
553: .B i
554: listing control option of
555: .PI .
556: If
557: .B z
558: is specified on the command line, then all arguments up to the
559: source file argument which ends in `.p' are taken to be the names of
560: .B procedure s
561: and
562: .B function s
563: or
564: .B include
565: files which are to be profiled.
566: If this list is null, then the whole file is to be profiled.
567: A typical command for extracting a profile of part of a large program
568: would be
569: .LS
570: % \*bpxp -z test parser.i compiler.p\fR
571: .LE
572: This specifies that profiles of the routines in the file
573: .I parser.i
574: and the routine
575: .I test
576: are to be made.
577: .NH 2
578: Formatting programs using pxp
579: .PP
580: The program
581: .XP
582: can be used to reformat programs, by using a command of the form
583: .LS
584: % \*bpxp dirty.p > clean.p\fR
585: .LE
586: Note that since the shell creates the output file `clean.p' before
587: .XP
588: executes, so `clean.p' and `dirty.p' must not be the same file.
589: .PP
590: .I Pxp
591: automatically paragraphs the program, performing housekeeping
592: chores such as comment alignment, and
593: treating blank lines, lines containing exactly one blank
594: and lines containing only a form-feed character as though they
595: were comments, preserving their vertical spacing effect in the output.
596: .I Pxp
597: distinguishes between four kinds of comments:
598: .HP
599: .RS
600: .IP 1)
601: Left marginal comments, which begin in the first column of the
602: input line and are placed in the first column of an output line.
603: .IP 2)
604: Aligned comments, which are preceded by no input tokens on the
605: input line.
606: These are aligned in the output with the running program text.
607: .IP 3)
608: Trailing comments, which are preceded in the input line by a token with
609: no more than two spaces separating the token from the comment.
610: .IP 4)
611: Right marginal comments, which are preceded in the input line
612: by a token from which they are separated by at least three spaces or a tab.
613: These are aligned down the right margin of the output,
614: currently to the first tab stop after the 40th column from the current
615: ``left margin''.
616: .RE
617: .LP
618: Consider the following program.
619: .LS
620: % \*bcat comments.p\fR
621: .so comments1.p
622: .LE
623: When formatted by
624: .XP
625: the following output is produced.
626: .LS
627: % \*bpxp comments.p\fR
628: .so commentsout
629: %
630: .LE
631: The following formatting related options are currently available in
632: .XP .
633: The options
634: .B f
635: and
636: .B j
637: described in the previous section may also be of interest.
638: .SH
639: Strip comments \-s
640: .PP
641: The
642: .B s
643: option causes
644: .XP
645: to remove all comments from the input text.
646: .SH
647: Underline keywords \- \_
648: .PP
649: A command line argument of the form
650: .B \-\_
651: as in
652: .LS
653: % \*bpxp -_ dirty.p\fR
654: .LE
655: can be used to cause
656: .XP
657: to underline all keywords in the output for enhanced readability.
658: .SH
659: Specify indenting unit \- [23456789]
660: .PP
661: The normal unit which
662: .XP
663: uses to indent a structure statement level is 4 spaces.
664: By giving an argument of the form
665: \fB\-\fId\fR
666: with
667: .I d
668: a digit,
669: 2 \(<=
670: .I d
671: \(<= 9
672: you can specify that
673: .I d
674: spaces are to be used per level instead.
675: .NH 2
676: Pxref
677: .PP
678: The cross-reference program
679: .I pxref
680: may be used to make cross-referenced listings of Pascal
681: programs.
682: To produce a cross-reference of the program in the file
683: `foo.p'
684: one can execute the command:
685: .LS
686: % \*bpxref foo.p\fR
687: .LE
688: The cross-reference is, unfortunately, not block structured.
689: Full details on
690: .I pxref
691: are given in its manual section
692: .I pxref
693: (1).
694: .NH 2
695: Multi-file programs
696: .PP
697: A text inclusion facility is available with
698: .UP .
699: This facility allows the interpolation of source text from other
700: files into the source stream of the translator.
701: It can be used to divide large programs into more manageable pieces
702: for ease in editing, listing, and maintenance.
703: .PP
704: The
705: .B include
706: facility is based on that of the
707: .SM
708: UNIX
709: .NL
710: C compiler.
711: To trigger it you can place the character `#' in the first portion of
712: a line and then, after an arbitrary number of blanks or tabs,
713: the word
714: `include'
715: followed by a filename enclosed in single `\(aa' or double `"' quotation
716: marks.
717: The file name may be followed by a semicolon `;' if you wish to treat
718: this as a pseudo-Pascal statement.
719: The filenames of included files must end in `.i'.
720: An example of the use of included files in a main program would be:
721: .LS
722: \*bprogram\fR compiler(input, output, obj);
723:
724: #\*binclude\fR "globals.i"
725: #\*binclude\fR "scanner.i"
726: #\*binclude\fR "parser.i"
727: #\*binclude\fR "semantics.i"
728:
729: \*bbegin\fR
730: { main program }
731: \*bend\fR.
732: .LE
733: .PP
734: At the point the
735: .B include
736: pseudo-statement is encountered in the input, the lines from
737: the included file are interpolated into the input stream.
738: For the purposes of translation and runtime diagnostics and
739: statement numbers in the listings and post-mortem backtraces,
740: the lines in the included file are numbered from 1.
741: Nested includes are possible up to 10 deep.
742: .PP
743: See the descriptions of the
744: .B i
745: option of
746: .PI
747: in section 5.2
748: above;
749: this can be used to control listing when
750: .B include
751: files are present.
752: .PP
753: When a non-trivial line is encountered in the source text after an
754: .B include
755: finishes, the
756: `popped' filename is printed, in the same manner as above.
757: .PP
758: For the purposes of error diagnostics when not making a listing, the filename
759: will be printed before each diagnostic if the current
760: filename has changed since the last
761: filename was printed.
762: .NH 2
763: Separate Compilation with Pc
764: .PP
765: A separate compilation facility is provided with the Berkeley Pascal compiler,
766: .PC .
767: This facility allows programs to be divided into a number of files and
768: the pieces to be compiled individually,
769: to be linked together at some later time.
770: This is especially useful for large programs,
771: where small changes would otherwise require
772: time-consuming re-compilation of the entire program.
773: .PP
774: Normally,
775: .PC
776: expects to be given entire Pascal programs.
777: However, if given the
778: .B \-c
779: option on the command line, it will accept a sequence of definitions and
780: declarations, and compile them into a
781: .B .o
782: file, to be linked with a Pascal program at a later time.
783: In order that procedures and functions be available across
784: separately compiled files, they must be declared with the directive
785: .B external .
786: This directive is similar to the directive
787: .B forward
788: in that it must precede the resolution of the function or procedure,
789: and formal parameters and function result types must be specified
790: at the
791: .B external
792: declaration and may not be specified at the resolution.
793: .PP
794: Type checking is performed across separately compiled files.
795: Since Pascal type defintions define unique types,
796: any types which are shared between separately compiled files
797: must be the same definition.
798: This seemingly impossible problem is solved using a facility similar
799: to the
800: .B include
801: facility discussed above.
802: Definitions may be placed in files with the extension
803: .B .h
804: and the files included by separately compiled files.
805: Each definition from a
806: .B .h
807: file defines a unique type, and all uses of a definition from the same
808: .B .h
809: file define the same type.
810: Similarly, the facility is extended to allow the definition of
811: .B const s
812: and the declaration of
813: .B label s,
814: .B var s,
815: and
816: .B external
817: .B function s
818: and
819: .B procedure s.
820: Thus
821: .B procedure s
822: and
823: .B function s
824: which are used between separately compiled files must be declared
825: .B external ,
826: and must be so declared in a
827: .B .h
828: file included by any file which calls or resolves the
829: .B function
830: or
831: .B procedure .
832: Conversely,
833: .B function s
834: and
835: .B procedure s
836: declared
837: .B external
838: may only be so declared in
839: .B .h
840: files.
841: These files may be included only at the outermost level,
842: and thus define or declare global objects.
843: Note that since only
844: .B external
845: .B function
846: and
847: .B procedure
848: declarations (and not resolutions) are allowed in
849: .B .h
850: files, statically nested
851: .B function s
852: and
853: .B procedure s
854: can not be declared
855: .B external .
856: .PP
857: An example of the use of included
858: .B .h
859: files in a program would be:
860: .LS
861: \*bprogram\fR compiler(input, output, obj);
862:
863: #\*binclude\fR "globals.h"
864: #\*binclude\fR "scanner.h"
865: #\*binclude\fR "parser.h"
866: #\*binclude\fR "semantics.h"
867:
868: \*bbegin\fR
869: { main program }
870: \*bend\fR.
871: .LE
872: .PP
873: This might include in the main program
874: the definitions and declarations of all the global
875: .B label s,
876: .B const s,
877: .B type s and
878: .B var s
879: from the file globals.h,
880: and the
881: .B external
882: .B function
883: and
884: .B procedure
885: declarations for each of the
886: separately compiled files for the scanner, parser and semantics.
887: The header file
888: .I scanner.h
889: would contain declarations of the form:
890: .LS
891: \*btype\fR
892: token = \*brecord\fR
893: { token fields }
894: \*bend\fR;
895:
896: \*bfunction\fR scan(\*bvar\fR inputfile: text): token;
897: \*bexternal\fR;
898: .LE
899: .ne 15
900: Then the scanner might be in a separately compiled file containing:
901: .LS
902: #\*binclude\fR "globals.h"
903: #\*binclude\fR "scanner.h"
904:
905: \*bfunction\fR scan;
906: \*bbegin\fR
907: { scanner code }
908: \*bend\fR;
909: .LE
910: which includes the same global definitions and declarations
911: and resolves the scanner functions and procedures declared
912: .B external
913: in the file scanner.h.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.