Style

From BR Wiki
Jump to navigation Jump to search

The Style BRConfig.sys specification alters the appearance of program lines to suit varying tastes for capitalization and indentation. It can also be used with the Config style command or within a program line using the Execute statement.

Comments and Examples

Some features of STYLE's INDENT parameter will not take effect until a program is either listed to a file or saved in source and then reloaded. These actions cause lines that are subordinate to FOR, DEF and blocked IF statements to be indented an additional amount according to their level of subordination. The following program lines contain three sets of lines which are subordinate, or fall beneath the execution of other lines:

  1. lines 30 to 50 are subordinate to the FOR statement in line 20;
  2. line 40 is subordinate to the FOR statement in line 30;
  3. line 80 is subordinate to the DEF statement in line 70:
00010 !
00020 FOR Y=1 TO 5
00030     FOR X=1 TO 10
00040         PRINT X
00050     NEXT X
00060 NEXT Y
00070 DEF FNX
00080 LET X=2
00090 FNEND

Assume that the following STYLE specification was active when the above lines were typed in:

STYLE INDENT 4

If so, the previous lines would be listed as follows upon execution of the LIST command:

00010 !
00020  FOR Y=1 TO 5
00030      FOR X=1 TO 10
00040          PRINT X
00050      NEXT X
00060  NEXT Y
00070  DEF FNX
00080  LET X=2
00090  FNEND

If the following program lines were saved in source while the same INDENT parameter remained in effect, they would appear as follows upon reloading (note that the subordination described above is illustrated in this listing):

00010 !
00020 FOR Y=1 TO 5
00030   FOR X=1 TO 10
00040     PRINT X
00050   NEXT X
00060 NEXT Y
00070 DEF FNX
00080   LET X=2
00090 FNEND

The effects of STYLE's COMMENTS parameter differ according to whether it is acting on a comment which follows a statement or not. Also, STYLE COMMENTS specifications may be disabled for individual comments when the comment begins with a period. Imagine that the following CONFIG command is in effect:

CONFIG STYLE COMMENTS MIXED INDENT 3

The following two examples show how STYLE responds when comments do not follow a statement. The comment in line 10 would disable the impact of COMMENTS MIXED because the first character is a period. Line 20 utilizes the COMMENTS MIXED specification but because the comment does not follow a statement, the first letter in each word is capitalized.

00010 ! . capitalization control is disabled for this comment
00020 ! With Mixed, 1st Letter Of Each Word Is Capitalized

The next two examples show how STYLE responds when comments do follow a statement. Again, the comment in line 10 would disable the impact of COMMENTS MIXED because the first character is a period. Line 20 utilizes the COMMENTS MIXED specification but now that the comment is following a statement it capitalizes only the first letter of the first word in the comment.

00020 LET X(7)=15 ! . capitalization control is DISABLED for this comment
00030 LET X(8)=25 ! With mixed, only 1st letter of 1st word is capitalized

Preferred Use of STYLE COMMENTS

STYLE COMMENTS MIXED is NOT the preferred use of the STYLE COMMENTS setting. Preferred is:

CONFIG STYLE COMMENTS INDENT 3 45

This setting leaves capitalization entirely up to the programmer. No changes are made. The INDENT keyword has 2 numeric parameters. The first specifies the number of spaces used for each indent increment. The second sets the minimum column where comments appear that follow program statements. In the above example:

00040    IF A > B THEN                     ! This comment starts in Column 45
00050       LET C = J                      ! So does THIS ONE.
00060    END IF

Syntax


Diagram Default

Do not indent comments that follow statements or (when specified with CONFIG) retain previous setting.

Start-up Default

STYLE INDENT 0 0 KEYWORDS UPPER EXPRESSIONS UPPER LABELS UPPER COMMENTS CLEAR

Parameters

The top path of the syntax diagram allows you to specify your preferences for indentation. The "CLEAR" parameter (functional only when STYLE is specified as part of a CONFIG command) causes any previous INDENT specifications to be cleared and puts INDENT's start-up default values into effect.

integer: This parameter specifies the number of positions that each line (excluding lines that start with labels and comment lines that begin with !) is to be indented. Integer may have any value from 0 to 8.

column: This parameter may optionally follow the integer parameter. The column parameter indicates the column position to which comments should be indented. This parameter may have a value of 0 (no indent) or it may have any value from 20 to 60. Only comments which follow a statement are affected by this specification. Comments which are alone on a line or which follow a line label will not be indented.

It is important to note that some features of the INDENT parameter will not take effect until a program is either listed to a file or saved in source and then reloaded. For instance, lines that use manual indentation will not be indented by the INDENT parameter until the program has been saved in source. Also, lines that are subordinate to other statements such FOR or DEF will be indented an extra level upon saving to source (see the Comments section for an example).

BR differentiates between CONFIG STYLE INDENT 0 and CONFIG STYLE INDENT CLEAR. Both specifications previously maintained existing indentation. Now, CONFIG STYLE INDENT 0 does just the opposite: it strips all indentation out of a program when it is saved as source. CONFIG STYLE INDENT CLEAR, which remains as the default, does nothing to alter indentation. It is preserved when saved as source and reloaded.

The second through fifth paths of the syntax diagram are similar in that they all affect capitalization of the different elements in a program line. "KEYWORDS" affects the capitalization of all primary and secondary keywords; "LABELS" affects capitalization of line labels; "EXPRESSIONS" affects all non-literal expressions, including variable names and functions; and "COMMENTS" affects the text in REM comments and in the comments that follow exclamation points.

Four capitalization options are available for each of these elements
UPPER indicates that the element should be listed in uppercase;
LOWER indicates it should be listed in lowercase;
MIXED indicates it should be listed with the first letter in uppercase and the remaining letters in lowercase (see below for an exception);
CLEAR (functional only when STYLE is specified as part of the CONFIG command) indicates that any previous specification for that element should be cleared so that only the start-up default value remains in effect.

The MIXED parameter's effect on comments varies according to the type of comment. If the comment follows a Business Rules statement the first letter of the first word will be uppercase and the rest will be lowercase. If the comment does not follow a statement (if it is alone on a line, for instance), the first letter of each word is uppercase and the rest are lowercase. Capitalization specifications may be disabled for individual comments when the first character in the comment is a period (.).

The bottom path of the syntax diagram is functional only when STYLE is specified as part of the CONFIG command. The "CLEAR" keyword causes all previous STYLE specifications to be cleared from operation so that only the default values remain in effect.

Technical Considerations

  1. STYLE may be specified with the CONFIG command.
  2. The process of saving a file in source causes the current STYLE formatting to be saved with the file. This may be undesirable in certain instances, particularly with the effects of the INDENT and COMMENTS parameters (see above).
  3. Complete re-indentation occurs when a program is saved or listed with redirection.
  4. Once capitalization of comments has been saved in source with the file, there is no way to recover the style in which the comments were originally typed.
  5. The INDENT parameter never affects two types of program lines: those that begin with exclamation points, and those that begin with a line label.