Previous: Date variables, Up: Resource file [Contents][Index]
Gcal respects global and/or local text variables which may be used anywhere in a line of a Gcal resource file. This means, up to 26 user-defined text variables can be set and referenced during program execution. See Fixed date option --text-variable=argument, for more information how global text variables can be used.
A text variable name tvar consists of the ‘$’ prefix and a single, case-insensitive letter.
A text variable is defined as follows:
Indeed, Gcal executes external commands only if the --execute-command option is given at program start-up. See Fixed date option --execute-command, for more details.
The text which appears at the right side of one of the valid assignment operator characters may reference names of already defined text variables. These references are converted to the according textual values just before the assignment is performed by Gcal. 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.
Local text variables are set to an empty value and thus defined in a special mode in case no text appears at the right side of one of the valid assignment operator characters.
If a text variable is referenced, an optional format instruction may be specified between the ‘$’ prefix and the single letter (here: the variable name), which makes it possible to modify the representation of the text (here: the contents) at which the text variable points to. Let us assume a resource file by the name of tvarf-1.rc exists with the following contents:
$ cat tvarf-1.rc -| ; tvarf-1.rc -| ; -| $a=123 -| $b=$:010*a -| $c=$b -| $b= -| 0 1. \$c=.$c. -| 0 2. \$c=.$:20*c. -| 0 3. \$b=.$>1w*b. -| 0 4. \$a=.$>5#a. |
So Gcal creates the following output:
$ gcal -Ux --text-variable='$b=XXX YY' --resource-file=./tvarf-1.rc -| -| 1. $c=.0000000123. -| 2. $c=. 0000000123 . -| 3. $b=.Xxx Yy. -| 4. $a=. 123. |
See Format Instruction, for the detailed description of the format instruction and its components.
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 another ‘\’ (backslash) character, e.g. ‘\\$’.
External commands are not directly executed by Gcal, they are executed by means of the command line interpreter of the operating system, the shell. As consequence to this, of course the commands have to be specified according to the syntax conventions of the used shell, concerning the grouping conventions, list processing conventions, redirection conventions et cetera! For example, it is possible that you have to write ‘$a?(cat text)’ instead of the simple ‘$a?cat text’. See the pertinent literature for more details.
If the output of external commands, which appears on the standard output channel, is assigned to text variables in an interpreted manner, this output is internally directed by Gcal into a temporary file. Thereafter, the contents of the temporary file is transfered to the text variable and the temporary file is removed.
If the output of external commands, which appears on the standard
output channel, is assigned to text variables in an uninterpreted manner,
this output is internally processed by the Txt2gcal program first
(see Invoking txt2gcal),
and then this output is directed by Gcal into a temporary file. Thereafter,
the contents of the temporary file is transfered to the text variable and the
temporary file is removed. In case a TXT2GCALPROG environment variable
(see Environment Variable TXT2GCALPROG)
is defined and set with the file name of the executable Txt2gcal program,
Gcal will use this file name for calling Txt2gcal. Otherwise, the file name
txt2gcal —which is burned-in during the compilation step of the
Gcal program— is used for calling the Txt2gcal program.
The TXT2GCALPROG environment variable must always be set if the
Txt2gcal program is installed under another name than the standard name
txt2gcal, otherwise Gcal is unable to execute the Txt2gcal
program automatically!
If the simple --debug respectively --debug=internal option is given at program start-up, informational messages about the executed command and its exit code will be shown on the standard error channel (see Global option --debug=internal).
If the --debug=abort option is given, the Gcal program will be aborted with an error code in case an exit code not equal zero occurred during the execution of the command. See Error Code 2, and Global option --debug=abort, for further information.
Here is an example which explains how the output of external commands can be assigned to text variables. Supposing there is a resource file by the name of tvarc-1.rc with the following contents:
$ cat tvarc-1.rc -| %t $a $>+06*b $>1u*c |
This file is used in the resource file tvarc-1a.rc and processed by Gcal as follows:
$ cat tvarc-1a.rc -| ; tvarc-1a.rc -| ; -| $a=bonjour -| $b=123 -| $c=bonsoir -| $x?cat $f -| 0 \$x=---$:30*x--- -| $y:cat $f -| 0 \$y=---$y--- -| 0 \$y=:::$>1u*y::: $ gcal -f tvarc-1a.rc -QUx --exe -r'$f=./tvarc-1.rc' -| $x=--- 18:54 bonjour +00123 BONSOIR --- -| $y=---%t $a $>+06*b $>1u*c--- -| $y=:::%T $A $>+06*B $>1U*C::: |
Here are some more examples showing how Gcal processes text variables. Let us assume a resource file by the name of tvar-1.rc exists with the following contents:
$ cat tvar-1.rc -| ; tvar-1.rc -| ; -| $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 ./tvar-1.rc -| -| Mon, Jan 1st 1996: \ \\ And this... works too! -| 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: $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 tvar-2.rc exists with the following contents:
$ cat tvar-2.rc -| ; tvar-2.rc -| ; -| $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 ./tvar-2.rc -| -| Mon, Jan 1st 1996: $a:0@e foo -| Mon, Jan 1st 1996: $b:0@e $ gcal %19960101 -H no -x -f ./tvar-2.rc -y -| -| Sun, Apr 7th 1996: $b -| Sun, Apr 7th 1996: foo bar |
As seen before, it is allowed to store complete (or partial) date parts
(see Date part of a line),
likewise special texts
(see %?… Special Texts)
into text variables or references to other text variables,
which are processed by Gcal after their expansion.
See Description of all %?… Special Texts,
for limitations concerning the assignment of special texts to text variables.
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 variables65 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, except this text variable held an empty value. In such a case, Gcal completely ignores this text variable while processing and displaying instead of keeping its name untouched in this line.
An example to this. Supposing a resource file by the name of tvar-3.rc exists with the following contents:
$ cat tvar-3.rc -| ; tvar-3.rc -| ; -| $c=+00+000 -| $h= -| $d=$c$h -| 0 %o$d %s$d -| 0 \$c=$c \$h=$h \$d=$d \$x=$x |
So Gcal creates the following output:
$ gcal -QUx -f ./tvar-3.rc -| $c=+00+000 $h= $d=+00+000 $x=$x -| 05:57 18:04 $ gcal -QUx -r '$h=+1000:$x=' -f ./tvar-3.rc -| $c=+00+000 $h=+1000 $d=+00+000+1000 $x= -| 05:52 18:09 |
Only advanced users should apply the --export-text-variables option which causes 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 is not locally defined in that further resource file. See 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 is not recommended to use it. You, the user, must exactly know what you are doing when applying this option; you are expressively warned now!
Some basic operations can be performed on text variables in case they contain integer values. These are:
Here is an example showing how Gcal processes text variable operations. Let us assume a resource file by the name of tvaro-1.rc exists with the following contents:
$ cat tvaro-1.rc -| ; tvaro-1.rc -| ; -| $a=130 -| $b=2 -| 0 1. \$b=$b -| $b++ -| 0 2. \$b=$b -| $b+=7 -| 0 3. \$b=$b -| $b-- -| 0 4. \$b=$b -| $b-=-5 -| 0 5. \$b=$b -| $b+=123 -| 0 6. \$b=$b -| $b-=$a -| 0 7. \$b=$b -| $b-=10000 -| 0 8. \$b=$b -| $b+=10000 -| 0 9. \$b=$b -| $b=02 -| 0 a. \$b=$b -| $b++ -| 0 b. \$b=$b |
So Gcal creates the following output:
$ gcal -QUx -f ./tvaro-1.rc -| 1. $b=2 -| 2. $b=3 -| 3. $b=10 -| 4. $b=09 -| 5. $b=14 -| 6. $b=137 -| 7. $b=007 -| 8. $b=-9993 -| 9. $b=00007 -| a. $b=02 -| b. $b=03 |
As you can see in the former example, if operations are made like these, the default behavior of Gcal is to fill with leading zeroes to preserve a former length of a text variable, in case a carry into one of the next decimal places has happened and is taken back by an operation at a later place in the resource file. But this default behavior can be disabled respectively changed by using the already above mentioned format instruction.
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 file66, 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/operation must be given separately on a single line in the resource file.
Previous: Date variables, Up: Resource file [Contents][Index]