calrule - translate a calendar rule and iterate dates

`calrule` - translate a calendar rule and iterate dates

SYNOPSIS

<calrule [options] [RULE=]$rule[ /]> [</calrule>]

DESCRIPTION
The calrule function takes a vCalendar/English calendar rule (see the SCHEDULE directive, here), and returns the Texis date(s) corresponding to the rule. This function can be used to find the actual fixed date(s) a rule occurs on, e.g. for lookup in a fixed-date events table. The dates are returned in $ret.

If an optional end tag is given, the function becomes a looping statement, and statements inside the <calrule> ... </calrule> block are executed for each return value. The special variables $loop and $next are then set as in other looping statements. In version 8.00.1645136290 20220217 and later, the self-closing syntax also sets $loop and $next.

Options that can be specified include:

RULE=$rule The vCalendar or English calendar rule to iterate over.
START=$date The Texis-parseable starting date for the rule, if required. (Note that some rules are absolute-dated and may ignore this.) The rule starts on the first applicable date on or after this date. For example, if the rule were "every Sunday at 6pm", then a START date of "2001-01-01" would make the rule return dates only on or after Jan. 1, 2001. Defaults to "now". Ignored if TOVCAL or TOENGLISH set. Note: this is different from the FIRST date, which is the starting date for iteration and has nothing to do with the calendar rule.
END=$date The Texis-parseable ending date for the rule, if required. Default is infinite. Ignored if TOVCAL or TOENGLISH set. Note: this is different from the LAST date, which is the ending date for iteration and has nothing to do with the calendar rule.
SKIP=$n Number of initially returned result dates to skip. Default is 0.
MAX=$n Max number of results to return. The default is 100, since some rules can produce many result dates (e.g. "every 10 minutes").
FIRST=$date The Texis-parseable date to start returning results after. In other words, skip any dates that would be returned before this date. Defaults to negative infinity (e.g. Jan. 1 1970). Note that this is different from the START date, which is associated with the calendar rule itself.
LAST=$date The Texis-parseable date to stop returning results before. In other words, this is the maximum date to return results on or before. Defaults to infinite. Note that this is different from the END date, which is associated with the calendar rule itself.
ROW As with other looping statements, do not accumulate results in $ret: each new value overwrites the previous, and $ret is not a loop variable.
TOVCAL Instead of returning dates, translate the English $rule to vCalendar syntax and return it. Mutually exclusive with the TOENGLISH flag.
TOENGLISH Instead of returning dates, translate the vCalendar $rule to pseudo-English syntax and return it. Mutually exclusive with the TOVCAL flag. Note that the returned syntax may not be entirely reverse-compatible.

EXAMPLE

<$rule = "every Sunday at 6pm">
  The next 10 dates the event "$rule" occurs are:
  <calrule ROW MAX=10 RULE=$rule>
    Occurs on: $ret
  </calrule>

CAVEATS
The calrule function was added in version 4.0.997700000 20010813.