Examples of Using Substitution Variables

If a template is specified as this:

....:....1....:....2....:....3....:....4....:....5....:....6

Line prefix:%token1:25:15:L% %token2:42:7:w%%token3:50:9:r%

Notice that there is a space character between the "%" characters ending "token1" and beginning "token2", but there is no space between "token2" and "token3". This "extra" space will be forced into the output in some circumstances illustrated in the following example. In practice, it may be better to include this space to make both the template and resulting output slightly more understandable. However, it is recommended that no characters, particularly not the tab character, or at most a single space character, is inserted between the substitution variable declarations within the template file. Later examples will illustrate the associated problems.

If the data supplied is:

for token1 oneisawidestring, four, seven

for token2 two, fiveisawidestring, eight

for token3 three, six, nine

The result will be:

....:....1....:....2....:....3....:....4....:....5....:....6
Line prefix: oneisawidestrin two three
Line prefix: four fiveisa six
Line prefix: widestr
Line prefix: ing
Line prefix: seven eight nine

Notice that the first value "oneisawidestring" is truncated while "fiveisawidestring" is wrapped. In general, the columns should be specified in such a way that they do not overlap. If this rule is broken then the resulting table may not "look" as expected by the user. To illustrate this the template is changed so that the first column overlaps the "line prefix:" text within the template:

L ine prefix:%token1:9:15:L% %token2:42:7:w%%token3:50:9:r%

The resulting substituted text will be:

....:....1....:....2....:....3....:....4....:....5....:....6
Line prefix:oneisawides two three
Line prefix:four fiveisa six
Line prefix: widestr
Line prefix: ing
Line prefix:seven eight nine

On each row, the data within the first column has been "pushed" to the right by the fixed text, it should start in character column 9 and be 15 characters wide therefore the last character column in which data is displayed is 23. The first value "oneisawidestring" is truncated at this column. The other data in the first column ("four" and "seven") has also been "pushed" to the right by the fixed text, but because these strings are shorter than the remaining column width they are not truncated.

If we now allow the column specifications to overlap (not recommended):

Line prefix:%token1:9:15:L% %token2:22:18:w%%token3:35:9:r%

The result will be:

....:....1....:....2....:....3....:....4....:....5....:....6
Line prefix:oneisawides two thre
Line prefix:four fiveisawidestri six
Line prefix:seven eight nine

Remember that, with a positive column width, data within a column is padded with spaces to occupy the full column width specified.

- We know (from the previous example) that the last character column in which the first column of data should appear is 23.

- The padding characters "push" all of the second column of data to the right. The space character in the template (between token1 and token2) appears in column 24, and so all of the second column of data actually starts in character column 25. However, because it was specified to start in column 22 for 18 columns, the last character column in which the second column of data should be printed is 39.

- The first character column in which the third column of data may be printed is 40, similarly its last printing character column is 43.

Thus the strings "three" and "fiveisawidestring" are truncated to "thre" and "fiveisawidestri" respectively. One reason why the column specifications should not overlap is illustrated here, because the second column of data is specified as 18 characters wide and "w" (wrap). Data in this column will be wrapped at 18, 36, 54, etc., but the displayed column is only 15 characters wide, resulting in three characters being truncated from each wrapped line! Do not allow the column specifications to overlap.

Consider the implications of putting a tab character in the template between the "token1" and "token2" declarations (not recommended), then the file will look as follows:

....:....1....:....2....:....3....:....4....:....5....:....6

Line prefix:%token1:9:15:L% %token2:22:18:w%%token3:35:9:r%

Consider the implications of putting a tab character in the template between the "token1" and "token2" declarations (not recommended), then the file will look as follows:

The tab has printed as empty space up to the next multiple of eight, in this case 32, and so the string "token2" starts at character column 33.

The resulting output will be:

....:....1....:....2....:....3....:....4....:....5....:....6
Line prefix:oneisawides two thre
Line prefix:four fiveisawidestri six
Line prefix:seven eight nine

Thi is exactly the same as with the space character, because column 24 is also a multiple of eight. If we had put a space followed by a tab character in the template file, then when printed out the template file will appear exactly the same as above, but the printed output file would be as follows:

....:....1....:....2....:....3....:....4....:....5....:....6
Line prefix:oneisawides two thre
Line prefix:four fiveisawidestr six
Line prefix:seven eight nine

The result is very confusing because the program has put out two characters (space and tab) between the substitution variables "token1" and "token2", but this has resulted in the printed columns shifting to character column 33 instead of 26. Consequently the third column of data (three, six and nine) is also displaced by seven characters. You are advised not to use tab characters in the template file.

Going back to the original template file, containing a single space between the substitution variables "token1" and "token2", if we now change the column width specification for "token1" from "15" to "-15" then it will not force the first column of data to end in character column 23 (the minus sign requests no padding characters).

Line prefix:%token1:9:-15:L% %token2:22:18:w%%token3:35:9:r%

The result will be:

....:....1....:....2....:....3....:....4....:....5....:....6
Line prefix:oneisawides two thre
Line prefix:four fiveisawidestring six
Line prefix:seven eight nine

It can be seen that the column one data finishes in character column 23, but the second data column should start in character column 22, thus the value "two" is "pushed" to the right, but "fiveisawidestring" and "eight" start in their correct character columns. The space character between the "token1" and "token2" declarations in the template file has been forced in at character column 24 before the string "two". By luck, "fiveisawidestring" has not "pushed" the value "six" because there was space to right-justify the three characters. However, had the value "six" been "sixteen", then the result would be:

....:....1....:....2....:....3....:....4....:....5....:....6
Line prefix:oneisawides two thre
Line prefix:four fiveisawidestring sixt
Line prefix:seven eight nine

If we change the specification of "token2" width from "18" to "-18", the result will be:

....:....1....:....2....:....3....:....4....:....5....:....6
Line prefix:oneisawides two three
Line prefix:four fiveisawidestringsixte
Line prefix:seven eight nine

There is no space separating the declarations for "token2" and "token3", so the two strings have run together at the data column boundary, but "three" is no longer "pushed" to the right and so this string is all displayed. If we now change the data again so that "oneisawidestring" is shortened to "oneiswide" and "fiveisawidestring" becomes "fiveiswide", the result is:

....:....1....:....2....:....3....:....4....:....5....:....6
Line prefix:oneiswide two three
Line prefix:four fiveiswide sixteen
Line prefix:seven eight nine

NOTE Even if the columns are specified in such a way that they overlap, the data is only "pushed" to the right by non-white-space characters in the preceding column.

The next examples illustrate that the user encounters while trying to create a "boxed" table by adding characters into the template. The behavior of any character (or string of characters) between the declaration of the substitution variables in the template file is exactly the same as we have already seen for the space character (between "token1" and "token2").

If the line in the template is:

|%token1:9:-15:L%|%token2:22:-18:w%|%token3:35:9:r%|

The resulting substituted text will be:

....:....1....:....2....:....3....:....4....:....5....:....6
| oneiswide| two| three|
| four| fiveiswide| sixteen|
| seven| eight| nine|

With the wider strings, the result will be:

....:....1....:....2....:....3....:....4....:....5....:....6
| oneisawidestrin|two| three|
| four| fiveisawidestring|sixt|
| seven| eight| nine|

Either of which is probably not what was intended. The situation gets even more complex if data within the table is wrapped.

This template line:

|%token1:9:-15:L%|%token2:22:-7:w%|%token3:35:-9:r%|

generates this table:

....:....1....:....2....:....3....:....4....:....5....:....6
| oneisawidestrin|two| three|
| four| fiveisa| sixteen|
|| widestr||
|| ing||
| seven| eight| nine|

This is clearly not what was wanted, but it does serve to illustrate what the substitution program will do with characters in between the token declarations. In general, it is recommended that no characters (except perhaps a single space) should be put between the substitution variable declarations in the template file.

If we allow padding characters to be printed, then this line:

|%token1:9:15:L%|%token2:22:18:w%|%token3:35:9:r%|

results in substituted text:

....:....1....:....2....:....3....:....4....:....5....:....6
| oneisawidestrin|two| |thr|
| four |fiveisawidestri|six|
| seven |eight |nin|

This template line:

|%token1:9:12:L%|%token2:22:7:w%|%token3:35:9:r%|

generates this table:

....:....1....:....2....:....3....:....4....:....5....:....6
| oneisawidest|two | three|
| four |fiveisa| sixteen|
| |widestr| |
| |ing | |
| seven |eight | nine|

And this template line:

|%token1:2:18:L%|%token2:22:7:w%|%token3:35:9:r%|

generates this table:

....:....1....:....2....:....3....:....4....:....5....:....6
|oneisawidestring | two | three|
|four | fiveisa| sixteen|
| | widestr| |
| | ing | |
| seven | eight | nine|

For completeness, the last example has the formatting data removed from the line in the template file, but uses the same data:

%token1% %token2% %token3%

Note that there are now spaces between the substitution variable declarations, resulting in the following output text:

....:....1....:....2....:....3....:....4....:....5....:....6
oneisawidestring two three
four fiveisawidestring sixteen
seven eight nine

As expected, there is now no formatting of the data into columns. Substitutions occur one after another across the output line, and are separated by the spaces specified between the substitution variables in the template file.

Related Topics

Multi-Valued Dimensions CM Variables