Gcal respects global and/or local text variables which may be used anywhere in a line of a Gcal resource file.
See section Fixed date options, for more information how global text variables can be used.
This means, up to 26 user defined text variables can be set and referenced during program execution. A text variable name tvar consists of the `$' prefix and a single, case-insensitive letter, and is trailed in a definition by the assignment operator character `=', and the text, this variable has to store. Only local text variables are set to an undefined value in case no text is specified on the right side of the assignment operator character. You should always remember that text variables can only be referenced in a line if they are already defined, because Gcal processes a resource file line by line. Gcal always expands text variable references recursively until all sub-references to other text variables are resolved.
You may depreciate the special meaning of the `$' prefix character --- in case this character itself is needed in the text -- by placing a `\' (backslash) character before it, e.g. `\$'. If you need the `\$' characters themselves in the text, you have to protect the `\' (backslash) character by itself, e.g. `\\$'.
Here are some examples showing how Gcal processes text variables. Let's assume a resource file by the name of `demo.rc' exists with the following contents:
$a=foo 0 \$a:1=$a $c=$a 0 \$c=$c $b=$c bar $a 0 \$b=$b $a=bar $b baz $a booz 0 \$a:2=$a $a= $b=0 $b $c frozz $a frozz $b ->That's \$b 0 \$x='$x' and \$d is undefined: $d... $a= 0 ~ 1~2~\$3~%n~$c~now it's enough! 0 \$a=---$a--- $a=0 \ \ \\ And this... $a works too!
So Gcal creates the following output:
$ gcal %19960101 -H no -x -r '$A=FROBOZZ:$x=' -f ./demo.rc -| -| Mon, Jan 1st 1996: $a:1=foo -| Mon, Jan 1st 1996: $a:2=bar foo bar foo baz foo booz -| Mon, Jan 1st 1996: $a=--- 0 -| 1 -| 2 -| $3 -| 01-Jan-1996 -| foo -| now it's enough!--- -| Mon, Jan 1st 1996: $b=foo bar foo -| Mon, Jan 1st 1996: $c=foo -| Mon, Jan 1st 1996: \ \\ And this... works too! -| Mon, Jan 1st 1996: $x=" and $d is undefined: $d... -| Mon, Jan 1st 1996: foo bar foo foo frozz FROBOZZ frozz ->That's $b
Or a resource file by the name of `demo2.rc' exists with the following contents:
$a=$b foo $b=0@e $a bar $b \$b 0 \$a:$a 0 \$b:$b
So Gcal creates the following output:
$ gcal %19960101 -H no -x -f ./demo2.rc -| -| Mon, Jan 1st 1996: $a:0@e foo -| Mon, Jan 1st 1996: $b:0@e $ gcal %19960101 -H no -x -f ./demo2.rc -y -| -| Sun, Apr 7th 1996: $b -| Sun, Apr 7th 1996: foo bar
As seen before, it's allowed to store complete (or partial) date parts
(see section Date part of a line),
likewise special texts
(see section %?... special texts)
into text variables or references to other text variables,
which are processed by Gcal after their expansion.
Text variables which are defined in a resource file are always local and only respected in this specific file, and that file which is included by it. This means for the included file, that all local variables of the caller are visible. The included file itself may define its own local variables in its own name-space, which are not exported to caller on return. All other definitions of text variables (59) are always global. If a resource file line contains a reference to a text variable which is not locally defined in that file, Gcal will try to use the global values held by this variable. If this fails because no global definition of this text variable is given, Gcal keeps the name of this text variable untouched in this line.
Only advanced users should apply the `--export-text-variables' option which effects that the actual incarnation of a local text variable --- which was previously defined in a resource file and not in an included file --- is being exported to further resource files instead of using its global value, in case that text variable isn't locally defined in that further resource file. See section Include directives, for more details.
But be aware, the use of this option could create unwanted results, because the order of processing the resource files is an important entity in managing the `--export-text-variables' option, so it's not recommended using it. You, the user, must exactly know what you're doing when applying this option; you are expressively warned now!
The scope of the definitions which are done on a local text variable, is that resource or include file, where the local text variable is defined.
If a global text variable is redefined in a resource file or that file which is included by it, these redefinitions are only valid in that specific file (60), not in further resource files processed. This means, the initial values of global text variables are always restored if the resource file changes.
Please finally note, that each text variable assignment must be given separately on a single line in the resource file.
Go to the first, previous, next, last section, table of contents.