Examples of using substitution variables

This topic provides some examples of how substitution variables can be used.

If a template is specified as the following:

....:....1....:....2....:....3....:....4....:....5....:....6 
Line prefix:%token1:25:15:L% %token2:42:7:w%%token3:50:9:r%

There is a space character between the percent sign (%) characters ending token1 and beginning token2. But there is no space between token2 and token3. This extra space is 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 more understandable. We recommend that you insert no characters, particularly not the tab character, or at most a single space character, between the substitution variable declarations within the template file. Later examples illustrate the associated issues.

If the supplied data is the following:

for token1      oneisawidestring, four, seven

for token2      two, fiveisawidestring, eight

for token3      three, six, nine

The result is the following:

....:....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, you need to specify the columns in such a way that they do not overlap. Otherwise, the resulting table may not look as expected.

To illustrate this, the template is changed so that the first column overlaps the "Line prefix:" text within the template:

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

The result is the following:

....:....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 you allow the column specifications to overlap (not recommended):

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

The result is the following:

....:....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.

  • 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) is displayed in column 24, so all the second column of data actually starts in character column 25. But 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.

As a result, 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 is wrapped at 18, 36, 54, 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 looks as follows:

....:....1....:....2....:....3....:....4....:....5....:....6 
Line prefix:%token1:9:15:L% %token2:22:18:w%%token3:35:9:r%

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 result is the following:

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

This is exactly the same as with the space character, because column 24 is also a multiple of eight.

If you put a space followed by a tab character in the template file, then when printed out, the template file is displayed exactly as above, but the printed output file is 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 confusing because the program has put out the space and tab characters between the substitution variables token1 and token2, but this has resulted in the printed columns shifting to character column 33 instead of 26. The third column of data (three, six and nine) is also displaced by seven characters. We recommend that you do not 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, change the column width specification for token1 from 15 to -15. Then it does 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 is the following:

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

You can see that the column one data finishes in character column 23, but the second data column should start in character column 22. 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. But if the value six is replaced with"sixteen, then the result is the following:

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

If you change the specification of token2 width from 18 to -18, the result is the following:

....:....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. The two strings have run together at the data column boundary. But three is no longer pushed to the right and is displayed in full.

If you change the data, so that oneisawidestring is shortened to oneiswide, and fiveisawidestring becomes "fiveiswide, the result is the following:

....:....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-whitespace characters in the preceding column.

The next examples illustrate what you encounter 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 described earlier for the space character (between token1 and token2).

If the line in the template is the following:

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

The resulting substituted text is the following:

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

With the wider strings, the result is the following:

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

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

The following template line:

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

generates the following table:

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

This is not what was wanted, but it does serve to illustrate what the substitution program does with characters in-between the token declarations. In general, we recommend that you put no characters, except perhaps a single space, between the substitution variable declarations in the template file.

If you allow to print padding characters, then the following line:

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

results in the following substituted text:

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

The following template line:

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

generates the following table:

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

The following template line:

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

generates the following table:

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

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

%token1% %token2% %token3%

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

The data is no longer formatted into columns. Substitutions occur one after another across the output line. They are separated by the spaces specified between the substitution variables in the template file.

Back to top

See also: