1 06/05/87 format_pl1, fp
2
3 Syntax as a command: fp in_path -control_args
4
5
6 Function: formats a PL/I, create_data_segment, reductions, or
7 pl1_macro source segment to make it more readable.
8
9
10 Arguments:
11 in_path
12 is the pathname of the source segment. Suffixes for PL/I,
13 create_data_segment, reductions, and pl1_macro are recognized. If
14 in_path does not have a recognized suffix, format_pl1 attempts to
15 use in_path.pl1 or in_path.cds, in that order.
16
17
18 Control arguments:
19 -brief, -bf
20 does not print a warning if the prevailing style differs from the
21 command line modes.
22 -check_comments, -ckcom
23 prints a warning if a comment contains "/*". It is useful if you
24 have omitted a "*/" from a comment.
25 -check_strings, -ckstr
26 prints a warning if a character string constant contains "/*", "*/",
27 or vertical white space. It is useful after receiving an error
28 message indicating that you have omitted a quote from a character
29 string constant.
30
31
32 -force, -fc
33 forms the prevailing style by concatenating the default style, the
34 prevailing style control comment modes, and the command line modes.
35 If the program already has a prevailing style control comment and
36 the prevailing style differs from the prevailing style control
37 comment modes, the prevailing style control comment is deleted. If
38 you provide -record_style, a new prevailing style control comment is
39 inserted.
40 -long, -lg
41 prints a warning indicating the modes that differ if the prevailing
42 style differs from the command line modes. Default
43 -modes STR, -mode STR, -md STR
44 specifies a modes string STR used in forming the prevailing style
45 see "Notes on prevailing style" below.
46
47
48 -no_check_comments, -nckcom
49 does not print a warning if a comment contains "/*". Default
50 -no_check_strings, -nckstr
51 does not print a warning if a character string constant contains
52 "/*", "*/", or vertical white space. Default
53 -no_force, -nfc
54 forms the prevailing style by concatenating the default style, the
55 command line modes, and the prevailing style control comment modes.
56 Default
57 -no_record_style, -nrcst
58 does not put a control comment in the source specifying the
59 prevailing style. Default
60 -no_require_style_comment, -nrqst
61 formats the source even if it does not already contain a prevailing
62 style control comment. Default
63
64
65 -no_version, -nver
66 does not print the version of format_pl1. Default
67 -output_file path, -of path
68 specifies the pathname of the formatted source segment. The equal
69 convention is allowed. The suffix of in_path is assumed if not
70 specified. If omitted and there were no errors, in_path is
71 overwritten; if omitted and there were errors, a formatted copy is
72 left in the process directory.
73 -record_style, -rcst
74 puts a control comment in the source specifying the prevailing style
75 if the source does not already have a prevailing style control
76 comment. The comment is placed immediately before the first token
77 of the program so it does not interfere with copyright notices.
78
79
80 -require_style_comment, -rqst
81 prints an error message if the source does not already contain a
82 prevailing style control comment. This is useful if you are
83 concerned with accidentally destroying the style of a hand-formatted
84 program.
85 -version, -ver
86 prints the version of format_pl1.
87
88
89 Notes: Alternate methods of formatting particular language constructs
90 are selected by means of modes. Several popular styles, consisting of
91 groups of modes, are defined. Modes and styles are specified on the
92 command line and in comments in the source segment.
93
94
95 An exec_com tool called compare_pl1 compares PL/I source segments of
96 dissimilar formats via format_pl1.
97
98
99 If you give two opposing control arguments, the rightmost one is
100 chosen. The term "token" excludes comments. See the Multics PL/I
101 Language Specification, Order No. AG94, for definitions of words
102 describing syntactic constructs in a PL/I program, e.g., independent
103 statement, declaration list, etc. Condition and label prefixes are not
104 considered part of a statement.
105
106
107 Notes on modes string: A modes string changes the style format_pl1
108 uses to format a program. It consists of mode names separated by
109 commas. Many modes can be preceded by ^ to turn the specified mode
110 off. The modes string is processed from left to right; thus, if two or
111 more contradictory modes appear within the same modes string, the
112 rightmost mode prevails. Modes not specified by the modes string are
113 left unchanged.
114
115
116 Notes on control comments: A control comment has the form
117 /* format: STR */
118 where STR is a modes string. The control comment can start with one of
119 the other comment indicators listed in "List of comment indicators"
120 below. Control comments can occur only before the first token of the
121 program, between a semicolon and the first token of the next statement,
122 or after the last semicolon in the program. Control comments cannot
123 occur in the middle of a statement. Optional horizontal white space
124 can precede "format" or surround STR. Some modes changed by a control
125 comment may not take effect immediately; for example, end statements
126 are formatted according to the modes in effect when the matching do,
127 begin, or procedure statement was formatted.
128
129
130 There are two special control comments that are used in if statements.
131 If a comment containing "/* case */" or "/* tree */" immediately
132 follows the word "if" in an if statement, then the current style is
133 changed for the duration of that if statement; exactly one space must
134 precede and follow "case" and "tree". See case and tree modes in the
135 "List of if statement modes" below.
136
137
138 Notes on prevailing style: The style in which format_pl1 formats a
139 PL/I program is formed from a combination of three sources:
140 format_pl1's default style, modes specified on the command line, and
141 control comments in the program. The first control comment of the
142 program preceding the first token of the program is called the
143 prevailing style control comment. A program might not have a
144 prevailing style control comment. The style specified by the
145 concatenation of the default style, the command line modes, and the
146 prevailing style control comment modes is called the prevailing style.
147 This is the style in which most of the program is formatted.
148
149
150 Since a styleN mode specifies the setting of every mode, if the
151 prevailing style control comment contains a styleN mode, the default
152 format_pl1 style and the command line modes are ignored. If the
153 program doesn't already have a prevailing style control comment, the
154 command line
155 format_pl1 in_path -modes MY_STYLE -record_style
156 formats a program in MY_STYLE and records the style in a prevailing
157 style control comment. If the program has a prevailing style control
158 comment, the program is formatted in the style specified by its
159 prevailing style control comment and -record_style has no effect. The
160 prevailing style control comment created as a result of -record_style
161 always begins with a styleN mode.
162
163
164 Notes on examples: The examples show how various program fragments are
165 formatted. If you give no control comment, then style1, is assumed; if
166 you give a control comment, the default is used for all unspecified
167 modes. Unless you use delnl,insnl mode, each line of the input source
168 segment contains the same tokens as the corresponding line of the
169 example. If you use delnl,insnl mode, then newline characters are
170 inserted and deleted as required by the style. See "Notes on styles"
171 below.
172
173
174 List of modes: Modes for various language constructs are listed
175 separately.
176 styleN
177 specifies formatting style N.
178 revert
179 changes the formatting style to the prevailing style. You can't
180 supply this mode in -modes or in the prevailing style control
181 comment. Note that the on mode is changed to the phase specified in
182 the prevailing style.
183 off, ^on
184 leaves the source exactly as it is until a control comment changes
185 the style to on. In this mode, block and group entries and exits
186 are noticed so the program following the on mode control comment is
187 formatted correctly.
188
189
190 on, ^off
191 starts formatting the source again. Default
192 indN
193 N is the number of columns to indent for each block or group
194 indentation level. An independent statement in a then or else
195 clause that does not have a condition or label prefix is indented a
196 minimum of five columns when not in ifthen mode even if indN is less
197 than five. This avoids placing the then or else clause on the line
198 after the "then" or "else". The five columns are measured from the
199 column the "else" would start in if the else clause was an
200 independent statement. Default: 5
201
202
203
204 Example /* format: ind3 */
205 if v = 2
206 then
207 do;
208 x = 12;
209 y = 128;
210 end;
211 else z = 12;
212
213 llN
214 N is the output line length. Default: 122
215 lineconindN
216 N is the number of columns to indent the continuation of lines that
217 exceed the output line length. Default: 5
218 equalindN
219 if N is greater than zero, places the equal sign of assignment
220 statements in a column indented N columns from the left margin. If
221 in insnl mode, a new line is inserted if necessary to insure that
222 the equal sign is indented the specified column positions. If N is
223 zero, then assignment statements are formatted just as ordinary
224 statements. Default: 0
225
226 Example: /* format: style2,equalind8 */
227 a = 12;
228 index = 1;
229 second_index
230 = 43;
231 initcolN
232 N is the initial column that statements occurring before the first
233 procedure statement should start at. This is useful for include
234 files. Default: 6
235
236
237 Notes on declare statements: Depending upon delnl and insnl modes,
238 each level one identifier that is declared is placed on a line by
239 itself. In indattr mode, all attributes are indented to the same
240 column. If a declaration list parenthesized list has all the
241 attributes factored i.e. each declaration component in the
242 declaration list consists only of an identifier and doesn't contain
243 any comments and none of the identifiers contain a $, then the
244 declaration list is placed on as few lines as possible instead of
245 placing each identifier on a separate line.
246 Example: dcl hbound index null builtin;
247
248
249 List of declare statement modes:
250 indattr
251 always indents the attributes so they start in the same column.
252 Default
253 ^indattr
254 doesn't indent the attributes from the identifier being declared.
255 inddcls
256 indents declare statements so they start in the same column any
257 other statement would start in. Default
258 ^inddcls
259 always starts declare statements in column 1.
260 declareindN
261 indents N columns after the start of dcl. Default: 8
262 dclindN
263 indents N columns after the start of dcl. Default: 8
264
265
266 idindN
267 indents N columns after the start of an identifier before starting
268 the attributes. Ignored if in ^indattr mode. Default: 23
269 struclvlindN
270 indents N columns for each level in a structure. Default: 2
271
272
273 List of if statement modes:
274 ifthenstmt
275 puts the then clause on the same line as the "if", if it fits.
276 These criteria must be met: 1 the then clause must be an
277 independent statement and cannot be another if statement; 2 the
278 then clause must not have a condition or label prefix; 3 if in
279 tree mode, the if statement must not have an else clause; 4 if in
280 case mode, the if statement must fall into one of the following
281 categories: a there is no else clause, b the else clause
282 consists of an if statement, or c the if statement under
283 consideration is an else clause of another if statement.
284 Example: /* format: ifthenstmt */
285 if x > 3 then return;
286
287
288 ^ifthenstmt
289 doesn't put the then clause on the same line as the "if". Default
290 Example: if x > 3
291 then return;
292 ifthendo
293 puts the "then do" on the same line as the "if", if it fits even if
294 indN is less than five, if the then clause of an if statement is a
295 noniterative do group without a condition or label prefix; puts the
296 "then do" on the same line if it fits and in ^thendo mode; lines the
297 "then" up with the "if" if in thendo mode; puts the "else do" on the
298 same line, if it fits even if indN is less than five, if the else
299 clause of an if statement is a noniterative do group without a
300 condition or label prefix. In ^delnl mode, the "then" or the "else"
301 must already be on the same line as the "do".
302
303
304 Example /* format: ifthendo,^indnoniterdo */
305 if v = 2 then do;
306 x = 8;
307 y = 9;
308 end;
309 else do;
310 x = 9;
311 y = 92;
312 end;
313
314
315
316 /* format: ind3,ifthendo,^indnoniterdo */
317 if v = 2 then do;
318 x = 8;
319 y = 9;
320 end;
321 else do;
322 x = 9;
323 y = 92;
324 end;
325
326
327
328 ^ifthendo
329 doesn't put the "then do" on the same line as the "if". Default
330 Example: /* format: ^indnoniterdo */
331 if v = 2
332 then do;
333 x = 8;
334 y = 9;
335 end;
336 else do;
337 x = 9;
338 y = 92;
339 end;
340
341
342
343 thendo
344 if in ifthendo mode, lines the "then" up with the "if".
345 Example: /* format: ind3,ifthendo,thendo,^indnoniterdo */
346 if v = 2
347 then do;
348 x = 8;
349 y = 9;
350 end;
351 else do;
352 x = 9;
353 y = 92;
354 end;
355
356
357
358 ^thendo
359 if in ifthendo mode, puts the "then do" on the same line as the "if"
360 if it fits. Default
361 Example: /* format: ind3,ifthendo,^indnoniterdo */
362 if v = 2 then do;
363 x = 8;
364 y = 9;
365 end;
366 else do;
367 x = 9;
368 y = 92;
369 end;
370
371
372
373 ifthen
374 puts the "then" on the same line as the "if".
375 Example: /* format: ind3,ifthen */
376 if v = 2 then
377 do;
378 x = 12;
379 y = 128;
380 end;
381 else
382 do;
383 x = 128;
384 y = 12;
385 end;
386
387
388
389 ^ifthen
390 lines the "then" up with the "if". Default
391 Example: if v = 2
392 then x = 8;
393 else x = 9;
394 elsestmt
395 places independent statements on the same line as the else clause;
396 places nonindependent statements on the same line as the else clause
397 if indN is set to five or more. Default
398
399
400 ^elsestmt
401 does not place any statements on the same line the else clause
402 appears on unless the else clause is part of an if statement in
403 "case" mode and the statement following the else clause is another
404 if statement.
405 Example: /* format: style2,ifthen,^elsestmt */
406 if a = b then
407 x = y;
408 else
409 x = z;
410
411
412
413 indnoniterdo
414 indents the statements of the do group two indentation levels from
415 the column in which the "if" starts if a then or else clause
416 contains a noniterative do group without a condition or label
417 prefix; indents three levels if in indthenelse mode. Default
418 Example: if v = 2
419 then do;
420 x = 3;
421 y = 4;
422 end;
423 else do;
424 x = 35;
425 y = 27;
426 end;
427
428
429
430 ^indnoniterdo
431 indents the statements of the do group one indentation level from
432 the column in which the "if" starts if a then or else clause
433 contains a noniterative do group without a condition or label
434 prefix; indents two levels if in indthenelse mode.
435 Example: /* format: ^indnoniterdo */
436 if v = 2
437 then do;
438 x = 3;
439 y = 4;
440 end;
441 else do;
442 x = 35;
443 y = 27;
444 end;
445
446
447
448 inditerdo
449 indents the statements of the do group two indentation levels from
450 the column in which the "if" starts if a then or else clause
451 contains an iterative do group and it does not have a condition or
452 label prefix; indents three levels if in indthenelse mode.
453 Default
454 Example: if v = 2
455 then do i = 1 to 4;
456 a i = i;
457 end;
458
459
460
461 ^inditerdo
462 indents the statements of the do group one indentation level from
463 the column in which the "if" starts if a then or else clause
464 contains an iterative do group and it does not have a condition or
465 label prefix; indents two levels if in indthenelse mode.
466 Example: /* format: ^insnl,^inditerdo */
467 if v = 2 then do i = 1 to 4;
468 a i = i;
469 end;
470
471
472
473 indnoniterend
474 starts the end statement of the noniterative do group in the same
475 column as the statements of the noniterative do group if a then or
476 else clause contains a noniterative do group without a condition or
477 label prefix.
478 Example: /* format: ^indnoniterdo,indnoniterend */
479 if v = 2
480 then do;
481 x = 8;
482 y = 9;
483 end;
484 else do;
485 x = 9;
486 y = 92;
487 end;
488
489
490
491 ^indnoniterend
492 starts the end statement of the noniterative do group in the column
493 that is one indentation level before the column the statements of
494 the noniterative do group start in if a then or else clause contains
495 a noniterative do group without a condition or label prefix.
496 Default
497
498
499
500 Example /* format: ^indnoniterdo */
501 if v = 2
502 then do;
503 x = 8;
504 y = 9;
505 end;
506 else do;
507 x = 9;
508 y = 92;
509 end;
510
511
512
513 indthenelse
514 indents the then and else clauses two indentation levels from the
515 column in which the "if" is placed. Places the "else" one
516 indentation level from the column in which the "if" is started. If
517 in ^ifthen mode and the ifthenstmt and ifthendo modes do not apply
518 to the if statement, places the "then" in the same column as the
519 "else". If in case mode and the if statement under consideration is
520 the else clause of another if statement, then indents from the
521 column in which the preceding "else" is placed instead of the column
522 in which the "if" is placed. In case mode this mode is ignored for
523 the else clause if the else clause consists of an if statement or
524 the if statement under consideration is an else clause of another if
525 statement.
526
527
528
529 Example /* format: indthenelse */
530 if v = 2
531 then x = 8;
532 else do;
533 x = 9;
534 call default;
535 end;
536 /* format: indthenelse */
537 if v = 2
538 then x = 8;
539 else if v = 3
540 then x = 25;
541 else call error;
542
543
544
545 ^indthenelse
546 indents the then and else clauses one indentation level from the
547 column in which the "if" is placed. Places the "else" in the same
548 column as the "if" is placed. If in ^ifthen mode and the ifthenstmt
549 and ifthendo modes do not apply to the if statement, places the
550 "then" in the same column as the "else". If in case mode and the if
551 statement under consideration is the else clause of another if
552 statement, then indent from the column in which the preceding "else"
553 is placed instead of the column in which the "if" is placed.
554 Default
555
556
557
558 Example if v = 2
559 then x = 8;
560 else do;
561 x = 9;
562 call default;
563 end;
564 if v = 2
565 then x = 8;
566 else if v = 3
567 then x = 25;
568 else call error;
569
570
571
572 case, ^tree
573 indents "else if" clauses like a case statement. Default
574 Example: if char = "a"
575 then call char_a;
576 else if char = "b"
577 then call char_b;
578 else if char = "c"
579 then call char_c;
580 else call error;
581
582
583
584 /* format: ifthenstmt */
585 if char = "a" then call char_a;
586 else if char = "b" then call char_b;
587 else if char = "c" then call char_c;
588 else call error;
589 /* Decision tree formatted like a case statement. */
590 if condition_1
591 then if condition_2
592 then call condition 0;
593 else call condition 1;
594 else if condition_2
595 then call condition 2;
596 else call condition 3;
597
598
599
600 tree, ^case
601 indents "else if" clauses like a decision tree.
602 Example: if /* tree */ condition_1
603 then if condition_2
604 then call condition 0;
605 else call condition 1;
606 else if condition_2
607 then call condition 2;
608 else call condition 3;
609
610
611
612 /* Case statement formatted like a decision tree. */
613 /* format: tree */
614 if char = "a"
615 then call char_a;
616 else if char = "b"
617 then call char_b;
618 else if char = "c"
619 then call char_c;
620 else call error;
621
622
623
624 indbegin
625 indents the body of those begin blocks that do not follow then
626 clauses, else clauses, or on statements. Default
627 Example: a = 15;
628 begin;
629 x = 21;
630 end;
631 y = 2;
632
633
634
635 ^indbegin
636 does not indent the body of those begin blocks that do not follow
637 then clauses, else clauses, or on statements.
638 Example: /* format: ^indbegin */
639 a = 15;
640 begin;
641 x = 21;
642 end;
643 y = 2;
644
645
646
647 indbeginend
648 indents the end statement of those begin blocks that do not follow
649 then clauses, else clauses, or on statements to the level of the
650 begin block body. If in ^indbegin mode, this option does not effect
651 the placement of the end statement. The end statement always lines
652 up under the begin block body and in the same column as the begin
653 statement since they are the same column.
654 Example: /* format: indbeginend */
655 a = 15;
656 begin;
657 x = 21;
658 end;
659 y = 2;
660
661
662
663 Example /* format: ^indbegin,indbeginend */
664 a = 15;
665 begin;
666 x = 21;
667 end;
668 y = 2;
669 ^indbeginend
670 places the end statement of those begin blocks that do not follow
671 then clauses, else clauses, or on statements in the same column as
672 the begin statement. Default
673
674
675 indthenbegin
676 indents the body of begin blocks that follow then clauses, else
677 clauses, or on statements. Default
678 Example: if a = 2
679 then begin;
680 x = 12;
681 end;
682 y = 15;
683
684
685
686 ^indthenbegin
687 does not indent the body of begin blocks that follow then clauses,
688 else clauses, or on statements. By default the corresponding end
689 statement is indented one less level than the begin block body see
690 indthenbeginend.
691 Example: /* format: ^indthenbegin */
692 if a = 2
693 then begin;
694 x = 12;
695 end;
696 y = 15;
697
698
699
700 indthenbeginend
701 indents the end statement of those begin blocks that follow then
702 clauses, else clauses, or on statements to the same level as the
703 begin block body.
704 Example: /* format: indthenbeginend */
705 if a = 2
706 then begin;
707 x = 47;
708 end;
709 y = 100;
710
711
712
713 Example /* format: ^indthenbegin,indthenbeginend */
714 if a = 89
715 then begin;
716 x = y;
717 end;
718 y = 100;
719 ^indthenbeginend
720 indents the end statement of those begin blocks that follow then
721 clauses, else clauses, or on statements one less level than the
722 indentation of the begin block body. Default
723 Example: if a = b
724 then begin;
725 x = 15;
726 end;
727 y = 9;
728
729
730
731 Example /* format: ^indthenbegin */
732 if a = b
733 then begin;
734 x = 15;
735 end;
736 y = 9;
737 indproc
738 starts the procedure statement in the same column as other
739 statements of the containing procedure if a procedure is contained
740 within at least two other procedures, i.e., the procedure is an
741 internal procedure of an internal procedure; starts the procedure
742 statement in column indN+1, otherwise.
743
744
745
746 Example /* format: indproc */
747 extp:
748 procedure;
749 a = 1;
750 intp1:
751 procedure;
752 b = 2;
753 intp2:
754 procedure;
755 c = 3;
756 end intp2;
757 end intp1;
758 end extp;
759
760
761
762 ^indproc
763 start procedure statements in column indN+1. Default
764 Example: extp:
765 procedure;
766 a = 1;
767 intp1:
768 procedure;
769 b = 2;
770 intp2:
771 procedure;
772 c = 3;
773 end intp2;
774 end intp1;
775 end extp;
776
777
778
779 indprocbody
780 indents the body of the procedure, the statements following the
781 procedure statement, one level farther than the indentation of the
782 procedure statement. Default
783 ^indprocbody
784 begins the statements following a procedure statement in the same
785 column as the procedure statement.
786 Example: /* format: ^indprocbody */
787 test:
788 procedure;
789 a = 12;
790 end test;
791
792
793
794 indend
795 starts the end statement of a do group, except those affected by
796 indnoniterend mode, in the same column as the statements of the
797 group.
798 Example: /* format: indend */
799 do i = 1 to 5;
800 a i = i;
801 end;
802 ^indend
803 starts the end statement of a do group, except those affected by
804 indnoniterend mode, in the column that is one indentation level
805 before the column the statements of the group start in. Default
806 Example: do i = 1 to 5;
807 a i = i;
808 end;
809
810
811 Notes on horizontal white space: All horizontal white space, except
812 within character string constants and comments, is removed from the
813 program. Spaces are inserted before left parentheses, after commas,
814 around operators, and in other places to improve readability. Where
815 possible, horizontal tabs are used to conserve space in the output
816 segment.
817
818
819 Statements continued onto another line are indented lineconindN from
820 the current left margin. The left margin at which a statement is
821 indented is increased by indN for every nested begin block, group, and
822 then or else clause except as required by the indnoniterdo, inditerdo,
823 indthenelse, case, indproc, and indprocbody modes. Entry statements
824 are placed in the same column as the corresponding procedure statement.
825 The left margin before a procedure statement is saved; it is restored
826 after the procedure's end statement. After a procedure statement the
827 left margin is increased by indN if the indprocbody option is set. End
828 statements are started in the same column as the statement that began
829 the block or group except as required by the indnoniterend, indend,
830 indbeginend, and indthenbeginend modes. Condition and label prefixes
831 are placed on lines by themselves except possibly in ^insnl mode.
832
833
834 Notes on vertical white space: Vertical white space within character
835 string constants and comments is never changed. Other vertical white
836 space can be intrastatement and interstatement. In on mode, vertical
837 tabs and newlines before newpages are removed, newlines before vertical
838 tabs are removed, and multiple newpages are reduced to one. Then a
839 newline is inserted before and after a sequence of vertical tabs and
840 newpages if there is not already one there. Interstatement vertical
841 white space is never changed except for the above canonicalizations;
842 intrastatement vertical white space is also canonicalized as above and
843 processed depending upon delnl and insnl modes.
844
845
846 List of vertical white space modes:
847 delnl
848 deletes all existing intrastatement vertical white space.
849 ^delnl
850 leaves existing intrastatement vertical white space in the program.
851 Default
852
853
854 insnl
855 inserts newlines in the program if necessary. Newlines are inserted
856 when statements are too long to fit on a line. To determine where
857 newlines are inserted, various heuristics exist that use the
858 statement type and the precedence of the tokens in the statement to
859 determine where to insert newlines. The driving force of format_pl1
860 is what column statements or other language constructs should start
861 in. Newlines are inserted to start a statement, subset of a
862 statement, or a comment in a particular column.
863 ^insnl
864 doesn't insert newlines into the program. Default
865
866
867 Notes on comments: Comments are classified by where they occur within
868 a PL/I program and where they are placed in the output segment. They
869 are divided into three categories: intrastatement comments, indented
870 comments, and block comments. Intrastatement comments occur between
871 the first token of a statement and the semicolon ending the statement.
872 They are normally separated from surrounding tokens by a space except
873 as required for linecom mode. Comments that follow a semicolon and are
874 separated by at most one newline character are considered indented
875 comments. They are placed in column comcolN. All other comments are
876 block comments. Block comments are placed in column one or indented to
877 the current left margin according to the indcom and indblkcom modes.
878 All comments following a blank line, following a block comment, and
879 before the first token of the program are block comments. Placing a
880 comment in column N means that the "/*" starts in column N.
881
882
883 In these special cases intrastatement comments are treated as indented
884 comments and placed in column comcolN: comments following a comma;
885 preceding the right parenthesis of a declaration component; following
886 the colon in a condition or label prefix; and, in if statements that
887 the ifthenstmt or ifthendo modes do not apply to, following the "then"
888 in ifthen mode and preceding the "then" in ^ifthen mode.
889
890
891 A comment indicator is placed at the beginning of a comment to specify
892 where the comment is placed or to inhibit indcomtxt mode on the
893 comment. If necessary, even in ^insnl mode, a newline is inserted to
894 place the comment in the specified column. Comment indicators consist
895 of the "/*", which starts the comment followed by other characters as
896 listed below. A comment indicator does not affect the classification
897 of succeeding comments.
898
899
900 List of comment indicators:
901 /*
902 places the comment according to its default classification.
903 /**
904 places the comment in column comcolN.
905 /***
906 indents the comment relative to the current left margin according to
907 indblkcom mode.
908
909
910
911 /****
912 places the comment in column one.
913 Example: /* format: ind3,comcol21 */
914 /**** column one comment */
915 /*** comment indented to left margin */
916 /** indented comment */
917 a = 3; /* indented comment */
918
919 /* column one comment by default */
920 b = 4;
921 /*^
922 places the comment according to its default classification; formats
923 the comment according to ^indcomtxt mode.
924
925
926
927 /**^
928 places the comment in column comcolN; formats the comment according
929 to ^indcomtxt mode.
930 /***^
931 indents the comment relative to the current left margin according to
932 indblkcom mode; formats the comment according to ^indcomtxt mode.
933 /****^
934 places the comment in column one; formats the comment according to
935 ^indcomtxt mode.
936
937
938 List of comment modes:
939 comcolN
940 N is the column indented comments are placed at. Default: 61
941 indcom
942 indents block comments relative to the current left margin according
943 to indblkcom mode. This mode doesn't apply before the first token
944 of the program so it doesn't interfere with copyright notices.
945 Example: /**** format: ind3 */
946 /* comment indented to left margin */
947 a = 3;
948 ^indcom
949 places block comment in column one. Default
950 Example: /* format: ind3 */
951 /* column one comment */
952 a = 3;
953
954
955
956 indblkcom
957 starts comments that begin with the "/***" or "/***^" comment
958 indicators and in indcom mode, block comments, at the current left
959 margin. Default
960 Example: /* format: ind3,indcom */
961 /**** column one comment */
962 /*** block comment */
963 a = 5;
964
965
966
967 ^indblkcom
968 starts comments that begin with the "/***" or "/***^" comment
969 indicators and in indcom mode, block comments, one indentation level
970 before the current left margin.
971 Example: /* format: ind3,indcom,^indblkcom */
972 /**** column one comment */
973 /*** block comment */
974 a = 5;
975
976
977
978 linecom
979 intrastatement comments at the end of a line in the original source
980 segment apply to an entire line. These comments are treated as
981 indented comments and are placed in column comcolN.
982 Example: /* format: linecom */
983 if line_status < 3 /* Is line active? */
984 | char_count > 0
985 then return;
986 ^linecom
987 intrastatement comments apply to the preceding token. Default
988 Example: /* format: ^delnl */
989 if char = "040"b3 /* space */
990 | char_count > 0
991 then return;
992
993
994
995 indcomtxt
996 inserts a space if there is no horizontal or vertical white space
997 between the comment indicator and the comment text or between the
998 end of the comment text and the "*/" or the reverse of any comment
999 indicator. Indents the text of continuation lines of a multiline
1000 comment so they line up; indenting the text of continuation lines
1001 does not apply to intrastatement comments. The horizontal white
1002 space between the comment indicator and the comment text on the
1003 first line of a comment is not reduced; however, leading horizontal
1004 white space on subsequent lines is replaced by sufficient horizontal
1005 white space to indent the line. If the comment is placed in column
1006 N, the length of the comment indicator is L, then the text of each
1007 line of the comment begins in column N+L+1. This mode does not
1008 apply to comments whose comment indicator ends with "^". Example:
1009
1010
1011
1012 Input /* format: indcomtxt */
1013 a = 3; /* Here we have a very
1014 complicated assignment
1015 statement. */
1016 Output: /* format: indcomtxt */
1017 a = 3; /* Here we have a very
1018 complicated assignment
1019 statement. */
1020 ^indcomtxt
1021 leaves the white space at the beginning of each line of a comment
1022 alone. The character string between the "/*" and the "*/" of a
1023 comment is never changed in this mode. Default
1024
1025
1026 Notes on irreversible changes: Several modes can cause irreversible
1027 changes to be made to the source program. Suppose that program p.pl1
1028 was formatted with style S and does not contain a prevailing style
1029 control comment, then style T causes an irreversible change if the
1030 following command lines produce a program q.pl1 that differs
1031 substantially from p.pl1:
1032 format_pl1 p -modes T -output_file q.pl1
1033 format_pl1 q -modes S
1034
1035 The following modes can cause irreversible changes--delnl, insnl,
1036 ^linecom, and indcomtxt. If a program is not formatted with
1037 format_pl1, the on mode may also cause irreversible changes.
1038
1039
1040 Notes on styles:
1041 style1: on,ind5,ll122,initcol6,indattr,inddcls,declareind8,
1042 dclind8,idind23,struclvlind2,^ifthenstmt,^ifthendo,
1043 ^thendo,^ifthen,indnoniterdo,inditerdo,
1044 ^indnoniterend,^indthenelse,case,^indproc,^indend,
1045 ^delnl,^insnl,comcol61,^indcom,indblkcom,^linecom,
1046 ^indcomtxt Default
1047 style2: style1,delnl,insnl
1048 style3: style2,^inddcls,declareind10,dclind10,idind20
1049 style4: style1,^indattr,^inddcls,declareind9,dclind5,
1050 ifthendo,^indnoniterdo,^inditerdo,indproc,linecom,
1051 indcomtxt
1052 style5: style2,linecom,ifthen,^indnoniterdo,indnoniterend,
1053 indcomtxt,^indthenbegin,indthenbeginend,^indprocbody,
1054 ^elsestmt,ind8,ll80,initcol0,idind24,comcol57,lineconind4,
1055
1056
1057
1058 Style1 indents declare statements, the attributes of declare
1059 statements, and the statements of the do group and lines up the end
1060 statement of a noniterative do group in a then or else clause under the
1061 "do". No irreversible changes, such as with the delnl, insnl, or
1062 indcomtxt modes, are made. Example:
1063 /* format: style1 */
1064 declare entryname char 32;
1065 if x = 2
1066 then do;
1067 a = 43;
1068 b = 21;
1069 end;
1070
1071
1072
1073 Style2 is the same as style1 except it uses the delnl,insnl modes. It
1074 may cause irreversible changes.
1075
1076 Style3 is the same as style2 except that declare statements start in
1077 column one and the identifiers and attributes start in columns aligned
1078 on tab stops. It may can cause irreversible changes. Example:
1079 /* format: style3 */
1080 declare entryname char 32;
1081 if x = 2
1082 then do;
1083 a = 43;
1084 b = 21;
1085 end;
1086
1087
1088
1089 Style4 starts declare statements in column one, doesn't indent the
1090 attributes in declare statements, formats noniterative do groups in
1091 then or else clauses by indenting the statements of the noniterative do
1092 group one indentation level from the "if" or the "else", and starts the
1093 end statement in the same column as the "if" or the "else". This style
1094 uses the ^delnl,^insnl modes, but still may cause irreversible changes
1095 from indcomtxt mode; it resembles that of the indent command. Example:
1096 /* format: style4 */
1097 declare entryname char 32;
1098 if x = 2 then do;
1099 a = 43;
1100 b = 21;
1101 end;
1102
1103
1104
1105 Style5 starts declare statements in column one, sets the line length to
1106 80 columns, sets the indentation amount to eight columns, sets the line
1107 continuation indentation to four columns, places the then clause of the
1108 "if/then" statement on the same line with the if, doesn't place any
1109 statement on a line with an if statement or else clause except for
1110 placing an if statement on the line after an else when in case mode,
1111 doesn't indent the procedure body, and doesn't indent the body of
1112 "begin/end" blocks or noniterative do groups under if statements.
1113
1114
1115
1116 Example /* format: style5 */
1117 test:
1118 procedure;
1119 a = 12;
1120 if a = b then
1121 a = 15;
1122 else
1123 a = -15;
1124 b = 78;
1125
1126
1127
1128 if b = c then
1129 do;
1130 x = 1;
1131 y = 99;
1132 end;
1133 a = 0;
1134 end test;
1135
1136
1137 Notes on error checking: Parenthesis balance checking is done for
1138 statements that are not partially contained in include files. A
1139 warning is printed if an end statement with a closure label terminates
1140 more than one block or group. If you provide no -output_file and there
1141 were errors, the source segment is not overwritten and a formatted copy
1142 is left in the process directory. An error message is printed if a
1143 control comment is incorrect.
1144
1145
1146 Notes on error severities: The following severity values are returned
1147 by the severity active function when the "format_pl1" keyword is used:
1148 VALUE MEANING
1149 0 No error
1150 1 Warning
1151 2 Correctable error
1152 3 Fatal error
1153 4 Unrecoverable error
1154 5 Bad control arguments, could not find source,
1155 or other severe errors.
1156
1157
1158
1159 Notes on macros: This command makes certain assumptions about macros.
1160 Include files must contain complete statements and balanced blocks or
1161 groups. Macro constructs can only occur between statements; they must
1162 not occur within a statement. All macro constructs are placed in
1163 column one. All %then and %else clauses of a %if macro must have the
1164 same effect on the current left margin and on block and group nesting;
1165 in addition, the effect on block and group nesting can only be to leave
1166 it unchanged or to start new blocks or groups. Blocks or groups that
1167 were started before the %if macro cannot be closed in the %then or
1168 %else clauses. A %then or %else clause cannot start with an else
1169 clause.