A date variable name dvar consists of a single, case-insensitive letter1. In a definition, this name is trailed by the assignment operator character ‘=’, and the numerical values of month mm (or a short, three characters month name, e.g. ‘Jan’, ‘Feb’...) and day dd, this variable has to store2.
For example:
--date-variable=a=1127:c=a respectively
-v a=1127:c=a
stores the 27th November into the global date variable a and into the global date variable c.
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 global text variables. These references are converted to the according textual values just before the assignment is performed by Gcal.
A global text variable is defined with an empty contents in case no text appears at the right side of one of the valid assignment operator characters.
For example:
--text-variable=$a=foo:$c=$a respectively
-r $a=foo:$c=$a
stores the ‘foo’ text into the global text variable $a and into the global text variable $c.--text-variable=$a\:foo:$c?bar respectively
-r $a\:foo:$c?bar
stores the uninterpreted output of the foo command into the global text variable $a, and the interpreted output of the bar command into the global text variable $c.
You may depreciate the special meaning of the ‘:’ separator character —in case this character itself is needed— by placing a ‘\’ (backslash) character before it, e.g. ‘\:’. If you need the ‘\:’ characters themselves, you have to protect the ‘\’ (backslash) character by another ‘\’ (backslash) character, e.g. ‘\\:’.
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. ‘\\$’.
Each time a ‘_’ (underscore) character is found in argument, this character is replaced by a real ‘ ’ (space) character.
You may depreciate the special meaning of the ‘_’ (underscore) character
—in case this character itself is needed— by placing a ‘\’
(backslash) character before it, e.g. ‘\_’. If you need the ‘\_’
themselves, you have to protect the ‘\’ (backslash) character by another
‘\’ (backslash) character, e.g. ‘\\_’.
And causes on the other hand, that the number that is given as argument is used as factor for computing the shadow length of a vertical pole by the Sun oriented special texts. The option argument must be a rational number in range 0.0...+90.0, which declares the shadow length. For example, you can detect the time when the shadow length of vertical pole is three and a half times longer than the shadow length that appears at astronomical noon if you use --adjust-value=3.5.
The following example is used to explain this. It calculates the time the astronomical twilight ends for the location Münster, Germany, during some days in May 2000, and that with and without the --limit option in each case:
| $ gcal %20000506 -f/dev/null -cxl4+ \ > -#'0*d1#999_%s9+5158+00738,120' -| -| Sun, May 7th 2000: 23:52 -| Mon, May 8th 2000: 23:57 -| Tue, May 9th 2000: 00:01 -| Wed, May 10th 2000: 00:06 $ gcal %20000506 -f/dev/null -cxl4+ --limit \ > -#'0*d1#999_%s9+5158+00738,120' -| -| Sun, May 7th 2000: 23:52 -| Mon, May 8th 2000: 23:57 -| Tue, May 9th 2000: **:** -| Wed, May 10th 2000: **:** |
As one can see well in the above example, the output for the days since 9th May differs in that the times shown without the --limit option obviously exceeded the civil midnight time and actually cannot happen during these days, whereas no times are shown for the days since 9th May if the --limit option is used because the time circle is exceeded. Astronomically seen, it is the case that the end of the astronomical twilight is at 23:57 o'clock local time on 8th May, no end of astronomical twilight happens on 9th May because the center of the Sun's disk is always above 18 degrees (the reference altitude of the astronomical twilight) below a geometric horizon, but on 10th May at 00:01 o'clock local time, this reference altitude is passed again. Thus, the time that is detected for the 9th May has properly to be moved to the 10th May, et cetera, as it is expressed by the output that is created by using the --limit option.
See Sun data,
for further information.
If values for the time interval are given to both above mentioned options that fall short of 0 o'clock, these values are automatically set to 0 o'clock. If values for the time interval are given that exceed 23:39 o'clock, these values are automatically set to 23:59 o'clock.
The timestep value between the starting and the ending time of the time interval that is respected by Gcal is one minute by default. This value can at pleasure be changed by using the --cycle-step option. See Fixed date option --cycle-step=argument, for more details.
You should always keep in mind that the use of the cycle mode is efficient only if the current time of the time interval is also part of that resource file line that has to be evaluated in this manner. Otherwise, it is difficult to find out unobjectionably lateron when displaying the data and times, which Sun or Moon oriented value resulted in what time.
The following example shows how the topocentric elevation angle of the Sun for the location Münster, Germany, is calculated during two days in April 2000, and that for the time interval 12:00 o'clock until 12:05 o'clock local time in each case:
| $ gcal %20000420 -Hno -f/dev/null -xdt -g::: \ > --here='0*d1#999_%ot+00+000_:_%oa+5158+00738,120' \ > --cycle-end=12:05 --time=12:00 -| -| Thu, Apr 20th 2000: +12h00': +045d58' -| Thu, Apr 20th 2000: +12h01': +046d03' -| Thu, Apr 20th 2000: +12h02': +046d07' -| Thu, Apr 20th 2000: +12h03': +046d12' -| Thu, Apr 20th 2000: +12h04': +046d17' -| Thu, Apr 20th 2000: +12h05': +046d22' -| ::: -| Fri, Apr 21st 2000: +12h00': +046d18' -| Fri, Apr 21st 2000: +12h01': +046d23' -| Fri, Apr 21st 2000: +12h02': +046d28' -| Fri, Apr 21st 2000: +12h03': +046d32' -| Fri, Apr 21st 2000: +12h04': +046d37' -| Fri, Apr 21st 2000: +12h05': +046d42' |
The timestep value between the starting and the ending time of the time interval that is respected by Gcal is one minute by default.
The following example shows how the topocentric elevation angle of the Sun for the location Münster, Germany, is calculated during two days in April 2000, and that for the time interval 10:00 o'clock until 17:00 o'clock local time with a timestep value of one hour and 15 minutes in each case:
| $ gcal %20000420 -Hno -f/dev/null -xdt -g::: \ > --here='0*d1#999_%ot+00+000_:_%o*a+5158+00738,120' \ > --cycle-end=10:00 --time=17:00 --cycle-step=1:15 -| -| Thu, Apr 20th 2000: +10h45': +38.038 -| Thu, Apr 20th 2000: +12h00': +45.962 -| Thu, Apr 20th 2000: +13h15': +49.665 -| Thu, Apr 20th 2000: +14h30': +47.882 -| Thu, Apr 20th 2000: +15h45': +41.267 -| Thu, Apr 20th 2000: +17h00': +31.633 -| ::: -| Fri, Apr 21st 2000: +10h45': +38.355 -| Fri, Apr 21st 2000: +12h00': +46.299 -| Fri, Apr 21st 2000: +13h15': +50.006 -| Fri, Apr 21st 2000: +14h30': +48.198 -| Fri, Apr 21st 2000: +15h45': +41.545 -| Fri, Apr 21st 2000: +17h00': +31.881 |
See Sun data,
and
Moon data,
likewise
Geographical distance and course angle,
for further information.
%![argument]
special texts are executed, and not displayed textually only.
See Shell command %![argument] special text,
for more details. And causes on the other hand, that
‘tvar?[command]’ and
‘tvar:[command]’ text variable definitions
is assigned the output of an external command, and not the text which
contains the call of the external command.
See Text variables,
for further information.
%? special texts.
The argument consists of one or more characters as used in the exclusion
without any argument %? special text; but without the leading
‘%’ character in each case.
For example, it is possible to induce Gcal to display only those fixed dates from the resource file demo.rc for the whole year which are legals holidays, and moreover, Saturdays or Sundays:
gcal -f demo.rc --year --filter-day=Rv
%?[date] special texts.
The argument consists of one or more expressions as used in the
exclusion with date argument %?[date] special
text; but without the leading ‘%’ character in each case. You can
use more than one of these %?[date] expressions
by connecting them with a ‘,’ character.
For example, it is possible to induce Gcal to display only those fixed dates from the resource file demo.rc for the whole year which appear within the period of the 17th and the 20th of any month, and which appear on the 31st of any month.
gcal -f demo.rc -y -P i00000017#00000020,i00000031#00000031
%?... special texts for text replacement.
The pattern is a regular expression,
as recognized by the Unix ed line-editor.
See Regular Expressions,
for further information.
For example, it is possible to induce Gcal to display all fixed dates from the resource file doctor.rc for the current month, which are defined for dentists or oculists:
gcal -f doctor.rc --month -I "[dD]entist|[oO]culist"
Each time a ‘_’ (underscore) character is found in the pattern argument, this character is replaced by a real ‘ ’ (space) character.
You may depreciate the special meaning of the ‘_’ (underscore) character
—in case this character itself is needed— by placing a ‘\’
(backslash) character before it, e.g. ‘\_’. If you need the ‘\_’
characters themselves, you have to protect the ‘\’ (backslash) character
by another ‘\’ (backslash) character, e.g. ‘\\_’.
You can use more than one resource file name by connecting them with a ‘+’ character, e.g.:
--resource-file=./foo+xyz+/data/bar+$HOME/.gcalrc resp.,
-f ./foo+xyz+/data/bar+$HOME/.gcalrc
respects all files given in the preceding argument by using a special file search mechanism. See File searching mechanism, for more details. Use /dev/null to avoid the use of the standard resource file, useful for creating empty fixed date lists. If a single ‘-’ character is given as file name, like --resource-file=./foo+-+xyz or -F-, but not -F -, Gcal reads and processes all input received from the standard input channel.
You may depreciate the special meaning of the ‘+’ separator character —in case this character itself is needed— by placing a ‘\’ (backslash) character before it, e.g. ‘\+’. If you need the ‘\+’ characters themselves, you have to protect the ‘\’ (backslash) character by another ‘\’ (backslash) character, e.g. ‘\\+’.
Each time a ‘_’ (underscore) character is found in name, this character is replaced by a real ‘ ’ (space) character.
You may depreciate the special meaning of the ‘_’ (underscore) character
—in case this character itself is needed— by placing a ‘\’
(backslash) character before it, e.g. ‘\_’. If you need the ‘\_’
characters themselves, you have to protect the ‘\’ (backslash) character
by another ‘\’ (backslash) character, e.g. ‘\\_’.
For example, the call:
gcal -# "0*d1su#99su.7 ^%Z" --here="#include <foo>" -y
causes the implicit processing of the standard resource file just before the further resource file line ‘0*d1su#99su.7 ^%Z’ and following ‘#include <foo>’ are processed, and that as if these lines were a physical part of the standard resource file.
Each time a ‘_’ (underscore) character is found in line, this character is replaced by a real ‘ ’ (space) character.
You may depreciate the special meaning of the ‘_’ (underscore) character —in case this character itself is needed— by placing a ‘\’ (backslash) character before it, e.g. ‘\_’. If you need the ‘\_’ characters themselves, you have to protect the ‘\’ (backslash) character by another ‘\’ (backslash) character, e.g. ‘\\_’.
Please note:
If the short-style option -c and/or its modifiers
t|[w|m|y[+|-], or the short-style option
-f is/are given in upper-case, e.g.:
-C
-F foo.bar
-CeT
-c-aW+
-CeaxY-
-c-M
Gcal displays fixed date messages for every day of the requested period.
The modifiers of a combined/complex/packed short-style fixed date option must be constructed according to following steps, because Gcal treats them as positional parameters:
- First step: Representation-of-text-modifier
- a, A, e|E, J, k, o, Q, U, x, z, Z
- Second step: Period-of-fixed-dates-modifier
- d, l, t|T, w|W|m|M|y|Y[+|-], n+|-, nd, nw, *dn[www], *wn[www], @e|t|dvar[[+|-]n], @e|t|dvar[+|-]nwww, mmdd, mmwwwn
If you want to operate with the preceding modifiers, an explicit -c|C[-] short-style option must be leading on the one hand, e.g.:
-c-t
-cw-
-CZdekloQUzJaxA12+
and only one period defining fixed date period modifier may be given6.
Or on the other hand, the modifiers must be given as single character options or composed into a single command line word, and additionally either the short-style option -c|C[-], -f|F name[+...] or -# line7 must be given like:
-c -t
-w- -c
-a -Ad -e -kloQUxz -C12+
-F foo.bar -dJZA -l*d10
--here="; Comment" -dZAa
If the modifiers are given as single character options or composed into a single command line word, and one of the t|T|[w|W|m|M|y|Y[+|-]] modifiers is used8, it is unnecessary to give a -c|C[-] respectively -f|F name[+...] short-style option9 to activate the fixed date function of Gcal, because it is triggered implicitly by means of these modifiers / alias names.
See Coding Scheme, whose tables explain the relations between the date part (yyyy...) of a resource file line and the modifiers, the short-style option -c|C[] —which is used for enabling the fixed date feature— respectively the long-style option --period-of-fixed-dates=argument may have, i.e. they point out all possible correspondences. This is necessary because Gcal does not respect all entries found in a resource file if a fixed date argument is given, it respects only those entries which have a definite relation to the fixed date argument to avoid the output of redundant information!
Fixed date text modifiers and options:
%;[date] special text— is
changed to number characters for each axis of the bar. The number
argument must be an integer value between 1...100, the default number
of characters is 20. If the number divides 100 with a remainder, it is
internally reduced to the nearest number that divides 100 without any
remainder. This means, only the numbers 1, 2, 4, 5, 10, 20, 25, 50 and
100 are factually respected, so a number argument of 19 is internally
reduced to 10.
For example:
| $ cat bio.rc -| 0*d1#999 %;19620921 $ gcal -fbio.rc %19961212 -s0 -xw --biorhythm-axis=19 -| -| Thu, Dec <12th>1996: 0- I P1 E +0 -| Fri, Dec 13th 1996: 0- I P 1 +0 -| Sat, Dec 14th 1996: 0- @ E 0 +0 -| Sun, Dec 15th 1996: 0- P IE 0 +0 -| Mon, Dec 16th 1996: 0- P E I 0 +0 -| Tue, Dec 17th 1996: 1-P E I0 +0 -| Wed, Dec 18th 1996: 0- @ 1 +0 |
See Biorhythm %?[date] special texts,
for more details.
%Z[date] special text— is
changed to number lines. The number argument must be an integer
value between 6...30, the default number of lines is 12.
For example:
| $ gcal -f/dev/null -#0*d1#999_%Z__%O %19950407 -x --moon=8 -| -| Fri, Apr < 7th>1995: ( @@@@@ -| ( @@@@@@@@ -| ( @@@@@@@@@@@ -| ( @@@@@@@@@@@@ -| ( @@@@@@@@@@@@ -| ( @@@@@@@@@@@ -| ( @@@@@@@@@@ -| ( @@@@@@@ 42%+ |
See Moon phase %[format]?[date] special texts,
for more details.
Mon, Jan 1st 1995: (`Eternal holiday list'#00003) New Year's day
Mon, Jan 1st 1995: (.gcalrc#00987) No fixed dates
...
Mon, Jan 1st 1995: New Year's day
Mon, Jan 1st 1995: No fixed dates
...
Gcal uses the alternative list format, e.g.:
Mon, Jan 1st 1995:
New Year's day
No fixed dates
...
| $ gcal -Cxw -cg -| -| Sun, Nov 6th 1994: Text 1 -| Sun, Nov 6th 1994: Text 2 -| -| Mon, Nov 7th 1994: Text 3 -| -| Tue, Nov 8th 1994: Text 4 ... $ gcal -Cxw -g'-A_user\_defined-~-grouping text-' -| -| Sun, Nov 6th 1994: Text 1 -| Sun, Nov 6th 1994: Text 2 -| -A user_defined- -| -grouping text- -| Mon, Nov 7th 1994: Text 3 -| -A user_defined- -| -grouping text- -| Tue, Nov 8th 1994: Text 4 ... |
The text may contain references to global date and text variables
(see Fixed date option --date-variable=argument,
and
Fixed date option --date-variable=argument).
Furthermore, all special texts which cause a text replacement may be used in
the text
(see %?... special texts for text replacement).
Each time a ‘~’ (tilde) or ‘^’ (caret) character is found in text, this character is replaced by a real ‘\n’ (newline) character.
You may depreciate the special meaning of the ‘~’ (tilde) character —in case this character itself is needed— by placing a ‘\’ (backslash) character before it, e.g. ‘\~’. If you need the ‘\~’ characters themselves, you have to protect the ‘\’ (backslash) character by another ‘\’ (backslash) character, e.g. ‘\\_’. All above mentioned facts are also valid for the ‘^’ (caret) character.
Each time a ‘_’ (underscore) character is found in text, this character is replaced by a real ‘ ’ (space) character.
You may depreciate the special meaning of the ‘_’ (underscore) character
—in case this character itself is needed— by placing a ‘\’
(backslash) character before it, e.g. ‘\_’. If you need the ‘\_’
characters themselves, you have to protect the ‘\’ (backslash) character
by another ‘\’ (backslash) character, e.g. ‘\\_’.
| $ gcal -cxo -| -| Sun, Nov 6th 1994: Text 1 -| Text 2 ... |
| $ gcal -f /dev/null -QUx %19800101 -#0_%j-2440588 -| 3652 |
| $ gcal -cxU -| -| Text 1 -| Text 2 ... |
| $ gcal -cxJ -| -| Sun, Nov 6th 1994: -| Sun, Nov 6th 1994: ... |
| $ gcal -cUJ --heading-text=Hello,_it_is_%K_,~%t__o'clock -| -| Hello, it is Sunday, -| 14:32 o'clock -| -| Sun, Nov 6th 1994: ... |
The text may contain references to global date and text variables
(see Fixed date option --date-variable=argument,
and
Fixed date option --date-variable=argument).
Furthermore, all special texts which cause a text replacement may be used in
the text
(see %?... special texts for text replacement).
Each time a ‘~’ (tilde) or ‘^’ (caret) character is found in text, this character is replaced by a real ‘\n’ (newline) character.
You may depreciate the special meaning of the ‘~’ (tilde) character —in case this character itself is needed— by placing a ‘\’ (backslash) character before it, e.g. ‘\~’. If you need the ‘\~’ characters themselves, you have to protect the ‘\’ (backslash) character by another ‘\’ (backslash) character, e.g. ‘\\_’. All above mentioned facts are also valid for the ‘^’ (caret) character.
Each time a ‘_’ (underscore) character is found in text, this character is replaced by a real ‘ ’ (space) character.
You may depreciate the special meaning of the ‘_’ (underscore) character
—in case this character itself is needed— by placing a ‘\’
(backslash) character before it, e.g. ‘\_’. If you need the ‘\_’
characters themselves, you have to protect the ‘\’ (backslash) character
by another ‘\’ (backslash) character, e.g. ‘\\_’.
Fixed date period modifiers and options:
Please note:
The following examples assumes the actual system date is the 17th February of any year (00000217), weeks start on Mondays and ISO week numbers are used!
[1] Except the date variable e which is internally reserved for the Easter Sunday's date, so it cannot be assigned or operated therefore. And except the date variable t which is internally reserved for today's date, so it likewise cannot be assigned or operated.
[2] Or another global date variable name which is already defined, but no date given in the ‘e|t|dvar[+|-]n[www]’, ‘mmwwwn’, or the ‘*d|wn[www]’ format.
[3] Refraction is an optical phenomenon caused by the Earth's atmosphere, which leads to an apparent raising of the location of a celestial body. The amount of refraction increases with growing air pressure and sinking temperature and vice-versa.
[4] Correct, the --time-offset option has multiple modes of operation that are depending on the context of its use!
[5] Except Gcal's line break-up characters ‘~’ and ‘^’, so you have to use ‘\~’ and ‘\\^’ in the pattern argument if you want to search texts which contain these characters.
[6] This means, exclusive the --include-today option respectively d modifier, the --list-mode option or the l modifier, and the --leap-day=february|march option.
[7] Respectively their according long-style options.
[8] Or their according alias names, like --today, --tomorrow...
[9] Or their according long-style options.
[10] RC_GROUP_SEP
“” == empty line only.
[11] Only if the --alternative-format option or the A modifier is not given.
[12] The 29th February.
[13] That is either the 51st, 52nd or 53rd Sunday.
[14] That is either the 51st, 52nd or 53rd Sunday.
[15] That is either the Sunday of the 51st, 52nd or 53rd week.
[16] That is either the Sunday of the 51st, 52nd or 53rd week.