1 08/04/86 Pascal compile-time options
2
3 This segment describes the $include compiler directive, used to insert
4 text from a segment into a Pascal program at compilation time, and the
5 $options compiler directive, used to control various aspects of
6 compilation and listing output.
7
8
9 Include files:
10 Stored portions of text can be inserted in a program at compilation
11 time by use of the $include compiler directive. Include files are
12 particularly useful when the same set of declarations are to be used in
13 several programs, and ensure that they appear identically in all
14 programs.
15
16
17 The syntax of $include is--
18 $include 'file_name' begin_string end_string $
19 where begin_string and end_string are either quoted character strings
20 to specify starting and ending positions within the included file, or *
21 to indicate the beginning and end of the file.
22
23 If begin_string is 'foo', for example, the included portion of
24 file_name begins with the character immediately following the first
25 occurrence of the literal string "foo". If end_string is 'bar', for
26 example, the included portion of file_name ends with the character
27 immediately preceding the first occurrence of "bar". These strings
28 are NOT interpreted as qedx regular expressions but using Pascal
29 character strings. same use of '' for ' char.
30
31 The included file is named file_name.incl.pascal and is found via the
32 "translator" search list.
33
34 Occurrences of $include in the include file itself are expanded
35 recursively.
36
37
38 Examples of $include:
39 The source line -- $include 'record_dcls' $
40 is replaced by the entire contents of the segment
41 record_dcls.incl.pascal found via the "translator" search list. This
42 example is equivalent to:
43
44 $include 'record_dcls',*,* $
45
46
47 The source line-- $include 'record_dcls','V1-START','V1-END'$
48 is replaced by the portion of record_dcls.incl.pascal that starts
49 with the character immediately following the first occurrence of
50 "V1-START" and ends with the character immediately preceding the first
51 occurrence of "V1-END" after "V1-START".
52
53
54 The source line-- $include 'record_dcls',*,'END-HEADER'$
55 is replaced by the portion of record_dcls.incl.pascal that starts at
56 the beginning of the segment and ends with the character immediately
57 preceding the first occurrence of "END-HEADER".
58
59
60 Compiler options:
61 The $options compiler directive accepts a variety of keywords that
62 control the format of the output compilation listing, the portion of
63 the source that is compiled, and the generation of debugging checks in
64 the code as produced by "pascal -debug".
65
66 The $options directive with most keywords can test the values of
67 compiler switches, which take true/false values. Compiler switches
68 must be declared within the source program by lines of the form:
69
70 $options switch switch_name1 := value1
71 switch_name2 := value2 $
72
73 where the switch names have the same syntax as Pascal identifiers. The
74 optional values can be either "true" or "false"; the default is
75 "false". Switches must be declared before they are referenced in other
76 $options directives, but their values can be changed at any time by
77 additional "$options switch" directives. Switch values can also be set
78 using the -cond control argument to the pascal command, which overrides
79 any values set within the source program.
80
81
82 Listing page breaks:
83 The directive:
84
85 $options page $
86
87 causes the compilation listing to skip to a new page.
88
89
90 Listing source text:
91 The directive:
92
93 $options listing = true/false $
94 or:
95 $options listing = not switch_name $
96
97 controls whether source subsequent source lines are written into the
98 compilation listing. The default is "true".
99
100
101 Debugging checks:
102 The directive-- $options debug = true/false $
103 or-- $options debug = not switch_name $
104 controls whether special code is to be generated to cause harmless
105 faults for uninitialized pointers and to provide other safeguards
106 against program errors. These checks are the same ones that are
107 generated by the -debug control argument to the pascal command. The
108 default value is "true". All values for debug are overridden by -debug
109 or -no_debug on the command line.
110
111
112 Conditional compilation:
113 The directive-- $options compile = true/false $
114 or-- $options compile = not switch_name $
115 controls whether succeeding text is to be included in the compilation.
116 This feature allows a source segment to contain multiple versions of
117 program text, which are selected based on the values of switches as
118 assigned by the -cond control argument to the pascal command. The
119 default value is "true".
120
121
122 Examples of conditional compilation:
123 The following sample program prints a terse message if the compiler is
124 invoked with "-cond brief true", otherwise it prints a longer message:
125
126 procedure print_not_found
127 name : packed array a..b : integer of char;
128 begin
129 $options switch brief := false $ default is not-brief
130 $options compile = brief $
131 writeln 'Not found: ' name;
132 $options compile = not brief $
133 writeln 'Unable to find program check library for: ' name;
134 $options compile = true $
135 end;