Share this page
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.
See also:
