If filename is specified as a single dash '-', then Remind takes its input from standard input. This also implicitly enables the -o option, described below.
Any of col, pad or spc can be omitted, providing you provide the correct number of commas. Don't use any spaces in the option.
remind '-kxmessage %s &' ...
to have all of your MSG-type reminders processed using xmessage.
A word of warning: It is very easy to spawn dozens of xmessage processes with the above technique. So be very careful. Also, the cmd is passed as an argument to sprintf(). If you use formatting directives other than %s, or use more than one %s directive, there's a good chance that you'll crash Remind. Finally, because cmd is executed using the system() library function, shell delimiters in MSG-type reminders could cause problems. In particular, never run untrusted reminders using the -k option. A reminder like:
REM msg foo ; rm -Rf .
would cause havoc if run with the -k option.
If you supply a date on the command line, it must consist of day month year, where day is the day of the month, month is at least the first three letters of the English name of the month, and year is a year (all 4 digits) from 1990 to about 2075. You can leave out the day, which then defaults to 1.
If you do supply a date on the command line, then Remind uses it, rather than the actual system date, as its notion of "today." This lets you create calendars for future months, or test to see how your reminders will be triggered in the future.
In addition, as part of the date component, you can supply a repeat parameter, which has the form *num. This causes Remind to be run num times, with the date incrementing on each iteration. You may have to enclose the parameter in quotes to avoid shell expansion. See the subsection "Repeated Execution" in the section "Calendar Mode" for more information.
Remind uses scripts to control its operation. The commands inside a script can range from the very simple and almost immediately understandable:
REM 6 Jan MSG David's birthday
to the baroque and obscure:
REM [trigger(date(thisyear, 1, 1) + 180)] ++5 OMIT \
sat sun BEFORE MSG [ord(thisyear-1980)] payment due %b!
A reminder file consists of commands, with one command per line. Several lines can be continued using the backslash character, as in the above example. In this case, all of the concatenated lines are treated as a single line by Remind. Note that if an error occurs, Remind reports the line number of the last line of a continued line.
Remind ignores blank lines, and lines beginning with the '#' or ';' characters. You can use the semicolon as a comment character if you wish to pass a Remind script through the C pre-processor, which interprets the '#' character as the start of a pre-processing directive.
Remind is not case sensitive; you can generally use any mixture of upper- or lower-case for commands, parameters, invocation options, etc.
The most powerful command in a Remind script is the REM command. This command is responsible for issuing reminders. Its syntax is:
The parts of the REM command can be specified in any order, except that the body must come immediately after the MSG, RUN, CAL, PS, PSFILE or SATISFY keyword.
The REM token is optional, providing that the remainder of the command cannot be mistaken for another Remind command such as OMIT or RUN. The portion of the REM command before the MSG, MSF RUN, CAL or SATISFY clause is called a trigger.
MSG, MSF, RUN, CAL, PS and PSFILE
These keywords denote the type of the reminder. (SATISFY is more complicated and will be explained later.) A MSG-type reminder normally prints a message to the standard output, after passing the body through a special substitution filter, described in the section "The Substitution Filter." However, if you have used the -k command-line option, then MSG-type reminders are passed to the appropriate program. Note that the options -c, -s, -p and -n disable the -k option.
The MSF keyword is almost the same as the MSG keyword, except that the reminder is formatted to fit into a paragraph-like format. Three system variables control the formatting of MSF-type reminders - they are $FirstIndent, $SubsIndent and $FormWidth. They are discussed in the section "System Variables." The MSF keyword causes the spacing of your reminder to be altered - extra spaces are discarded, and two spaces are placed after periods and other characters, as specified by the system variables $EndSent and $EndSentIg. Note that if the body of the reminder includes newline characters (placed there with the %_ sequence), then the newlines are treated as the beginnings of new paragraphs, and the $FirstIndent indentation is used for the next line. You can use two consecutive newlines to have spaced paragraphs emitted from a single reminder body.
A RUN-type reminder also passes the body through the substitution filter, but then executes the result as a system command. A CAL-type reminder is used only to place entries in the calendar produced when Remind is run with the -c, -s or -p options.
A PS or PSFILE-type reminder is used to pass PostScript code directly to the printer when producing PostScript calendars. This can be used to shade certain calendar entries (see the psshade() function), include graphics in the calendar, or almost any other purpose you can think of. You should not use these types of reminders unless you are an expert PostScript programmer. The PS and PSFILE reminders are ignored unless Remind is run with the -p option. See the section "More about PostScript" for more details.
DATE SPECIFICATIONS
A date_spec consists of zero to four parts. These parts are day (day of month), month (month name), year and weekday. Month and weekday are the English names of months and weekdays. At least the first three characters must be used. The following are examples of the various parts of a date_spec:
Note that there can be several weekday components separated by spaces in a date_spec.
INTERPRETATION OF DATE SPECIFICATIONS
The following examples show how date specifications are interpreted.
1. Null date specification - the reminder is triggered every day. The trigger date for a specific run is simply the current system date.
2. Only day present. The reminder is triggered on the specified day of each month. The trigger date for a particular run is the closest such day to the current system date. For example:
REM 1 MSG First of every month.
REM 31 MSG 31st of every month that has 31 days.
3. Only month present. The reminder is triggered every day of the specified month. Example:
REM Feb MSG Every day in February
4. day and month present. Examples:
REM 6 Jan MSG Every 6th of January
REM Feb 29 MSG Every 29th of February
5. Only year present. Example:
REM 1991 MSG Every day in 1991
6. year and day present. Examples:
REM 1 1990 MSG 1st of every month in 1990
REM 1992 23 MSG 23rd of every month in 1992
7. year and month present. Examples:
REM Feb 1991 MSG Every day in Feb 1991
REM 1992 September MSG Every day in Sept 1992
8. year, month and day present. Examples:
REM 8 Jan 1991 MSG 8th January 1991.
REM 1992 March 9 MSG 9th March 1992.
9. weekday only. Examples:
REM Sat MSG Every Saturday
REM Mon Tue Wed Thu Fri MSG Every working day
REM Monday Wednesday MSG Every Monday and Wednesday
10. weekday and day present. Examples:
REM Sat 1 MSG First Saturday of every month
REM Mon Tue Wed Thu Fri 15 \
MSG 1st working day after 15th of every month
11. weekday and month present. Examples:
REM Mon March MSG Every Monday in March
REM Mon Tue Wed Thu Fri Feb MSG Every working day in February
12. weekday, month and day present. Examples:
REM Mon 1 March MSG First Monday in March
REM Sat Sun 15 July MSG First Sat or Sun on or after 15 July
13. weekday and year present. Example:
REM Sat Sun 1991 MSG Every Saturday and Sunday in 1991
14. weekday, day and year present. Examples:
REM Mon 15 1990 MSG 1st Mon after 15th of every month in 1990
REM Mon Tue Wed Thu Fri 1 1990 \
MSG 1st working day of every month in 1990
15. weekday, month and year present. Example:
REM Mon Wed 1991 Feb MSG Every Mon and Wed in Feb 1991.
16. weekday, day, month and year present. Example:
REM Mon Tue Wed Thu Fri 28 Oct 1990 \
MSG 1st working day on or after 28 October 1990.
Note that when both weekday and day are specified, Remind chooses the first date on or after the specified day which also satisfies the weekday constraint. It does this by picking the first date on or after the specified day which is listed in the list of weekdays. Thus, a reminder like:
REM Mon Tue 28 Oct 1990 MSG Hi
would be issued only on Monday, 29 October, 1990. It would not be issued on Tuesday, 30 October, 1990, since the 29th is the first date to satisfy the weekday constraints.
BACKWARD SCANNING
Sometimes, it is necessary to specify a date as being a set amount of time before another date. For example, the last Monday in a given month is computed as the first Monday in the next month, minus 7 days. The back specification in the reminder is used in this case:
REM Mon 1 -7 MSG Last Monday of every month.
A back is specified with one or two dashes followed by an integer. This causes Remind to move "backwards" from what would normally be the trigger date. The difference between --7 and -7 will be explained when the OMIT keyword is described.
ADVANCE WARNING
For some reminders, it is appropriate to receive advance warning of the event. For example, you may wish to be reminded of someone's birthday several days in advance. The delta portion of the REM command achieves this. It is specified as one or two "+" signs followed by a number n. Again, the difference between the "+" and "++" forms will be explained under the OMIT keyword. Remind will trigger the reminder on computed trigger date, as well as on each of the n days before the event. Here are some examples:
REM 6 Jan +5 MSG Remind me of birthday 5 days in advance.
The above example would be triggered every 6th of January, as well as the 1st through 5th of January.
PERIODIC REMINDERS
We have already seen some built-in mechanisms for certain types of periodic reminders. For example, an event occurring every Wednesday could be specified as:
REM Wed MSG Event!
However, events which do not repeat daily, weekly, monthly or yearly require another approach. The repeat component of the REM command fills this need. To use it, you must completely specify a date (year, month and day, and optionally weekday.) The repeat component is an asterisk followed by a number specifying the repetition period in days.
For example, suppose you get paid every second Wednesday, and your last payday was Wednesday, 28 October, 1992. You can use:
REM 28 Oct 1992 *14 MSG Payday
This issues the reminder every 14 days, starting from the calculated trigger date. You can use delta and back with repeat. Note, however, that the back is used only to compute the initial trigger date; thereafter, the reminder repeats with the specified period. Similarly, if you specify a weekday, it is used only to calculate the initial date, and does not affect the repetition period.
SCANFROM
The SCANFROM keyword is for advanced Remind programmers only, and will be explained in the section "Details about Trigger Computation" near the end of this manual. Note that SCANFROM is available only in versions of Remind from 03.00.04 up.
PRIORITY
The PRIORITY keyword must be followed by a number from 0 to 9999. It is used in calendar mode and when sorting reminders. If two reminders have the same trigger date and time, then they are sorted by priority. If the PRIORITY keyword is not supplied, a default priority of 5000 is used.
EXPIRY DATES
Some reminders should be issued periodically for a certain time, but then expire. For example, suppose you have a class every Friday, and that your last class is on 11 December 1992. You can use:
REM Fri UNTIL 11 Dec 1992 MSG Class today.
Another example: Suppose you have jury duty from 30 November 1992 until 4 December 1992. The following reminder will issue the message every day of your jury duty, as well as 2 days ahead of time:
REM 30 Nov 1992 *1 +2 UNTIL 4 Dec 1992 MSG Jury duty
Note that the repeat of *1 is necessary; without it, the reminder would be issued only on 30 November (and the two days preceding.)
THE ONCE KEYWORD
Sometimes, it is necessary to ensure that reminders are run only once on a given day. For example, if you have a reminder which makes a backup of your files every Friday:
REM Fri RUN do_backup
(Here, do_backup is assumed to be a program or shell script which does the work.) If you run Remind from your .login script, for example, and log in several times per day, the do_backup program will be run each time you log in. If, however, you use the ONCE keyword in the reminder, the Remind checks the last access date of the reminder script. If it is the same as the current date, Remind assumes that it has already been run, and will not issue reminders containing the ONCE keyword.
Note that if you view or edit your reminder script, the last access date will be updated, and the ONCE keyword will not operate properly. If you start Remind with the -o option, then the ONCE keyword will be ignored.
LOCALLY OMITTING WEEKDAYS
The OMIT portion of the REM command is used to "omit" certain days when counting the delta or back. It is specified using the keyword OMIT followed by a list of weekdays. Its action is best illustrated with examples:
REM 1 +1 OMIT Sat Sun MSG Important Event
This reminder is normally triggered on the first of every month, as well as the day preceding it. However, if the first of the month falls on a Sunday or Monday, then the reminder is triggered starting from the previous Friday. This is because the delta of +1 does not count Saturday or Sunday when it counts backwards from the trigger date to determine how much advance warning to give.
Contrast this with the use of "++1" in the above command. In this case, the reminder is triggered on the first of each month, as well as the day preceding it. The omitted days are counted.
REM 1 -1 OMIT Sat Sun MSG Last working day of month
Again, in the above example, the back of -1 normally causes the trigger date to be the last day of the month. However, because of the OMIT clause, if the first of the month falls on a Sunday or Monday, the trigger date is moved backwards past the weekend to Friday. (If you have globally omitted holidays, the reminder will be moved back past them, also. See "The OMIT command" for more details.)
By comparison, if we had used "--1", the reminder would be triggered on the last day of the month, regardless of the OMIT.
TIMED REMINDERS
Timed reminders are those which have an AT keyword followed by a time and optional tdelta and trepeat. The time must be specified in 24-hour format, with 0:00 representing midnight, 12:00 representing noon, and 23:59 representing one minute to midnight. You can use either a colon or a period to separate the hours from the minutes. That is, 13:39 and 13.39 are equivalent.
Remind treats timed reminders specially. If the trigger date for a timed reminder is the same as the current system date, the reminder is queued for later activation. When Remind has finished processing the reminder file, it puts itself in the background, and activates timed reminders when the system time reached the specified time.
If the trigger date is not the same as the system date, the reminder is not queued.
For example, the following reminder, triggered every working day, will emit a message telling you to leave at 5:00pm:
REM Mon Tue Wed Thu Fri AT 17:00 MSG Time to leave!
The following reminder will be triggered on Thursdays and Fridays, but will only be queued on Fridays:
REM Fri ++1 AT 13:00 MSG Lunch at 1pm Friday.
The tdelta and trepeat have the same form as a repeat and delta, but are specified in minutes. For example, this reminder will be triggered at 12:00pm as well as 45 minutes before:
REM AT 12:00 +45 MSG Example
The following will be issued starting at 10:45, every half hour until 11:45, and again at noon.
REM AT 12:00 +75 *30 MSG Example2
The "+75" means that the reminder is issued starting 75 minutes before noon; in other words, at 10:45. The *30 specifies that the reminder is subsequently to be issued every 30 minutes. Note that the reminder is always issued at the specified time, even if the tdelta is not a multiple of the trepeat. So the above example is issued at 10:45am, 11:15am, 11:45am, and 12:00pm. Note that in the time specification, there is no distinction between the "+" and "++" forms of tdelta.
Normally, Remind will issue timed reminders as it processes the reminder script, as well as queuing them for later. If you do not want Remind to issue the reminders when processing the script, but only to queue them for later, use the -a command-line option. If you do not want reminders to be queued for later, use the -q command-line option.
Normally, Remind forks a background process to handle queued reminders. If you want Remind to remain in the foreground, use the -f command-line option. This is useful, for example, in .xinitrc scripts, where you can use the command:
remind -fa myreminders &
This ensures that when you exit X-Windows, the Remind process is killed.
WARNING ABOUT TIMED REMINDERS
Note: If you use user-defined functions or variables (described later) in the bodies of timed reminders, then when the timed reminders are activated, the variables and functions have the definitions which were in effect at the end of the reminder script. These definitions may not necessarily be those which were in effect at the time the reminder was queued.
THE SCHED KEYWORD
The SCHED keyword allows more precise control over the triggering of timed reminders. However, discussion must be deferred until after expressions and user-defined functions are explained. See the subsection "Precise Scheduling" further on.
Before being processed, the body of a REM command is passed through a substitution filter. The filter scans for sequences "%x" (where "x" is any letter and certain other characters) and performs substitutions as shown below. (All dates refer to the trigger date of the reminder.)
REM 18 Oct 1990 +4 MSG Meeting with Bob %a.
On 16 October 1990, it would print "Meeting with Bob on Thursday, 18 October, 1990."
On 17 October 1990, it would print "Meeting with Bob tomorrow."
On 18 October 1990, it would print "Meeting with Bob today."
REM 18 Oct 1990 +4 MSG Meeting with Bob %b.
On 16 October 1990, it would print "Meeting with Bob in 2 days' time."
On 17 October 1990, it would print "Meeting with Bob tomorrow."
On 18 October 1990, it would print "Meeting with Bob today."
On 16 October 1990, it would print "Meeting with Bob on Thursday."
On 17 October 1990, it would print "Meeting with Bob tomorrow."
On 18 October 1990, it would print "Meeting with Bob today."
Notes:
In addition to being a keyword in the REM command, OMIT is a command in its own right. Its syntax is:
The OMIT command is used to "globally" omit certain days, which are usually holidays. These globally-omitted days are skipped by the "-" and "+" forms of back and delta. Some examples:
OMIT 1 Jan
OMIT 7 Sep 1992
The first example specifies a holiday which occurs on the same date each year - New Year's Day. The second example specifies a holiday which changes each year - Labour Day. For these types of holidays, you must create an OMIT command for each year. (Later, in the description of expressions and some of the more advanced features of Remind, you will see how to automate this for some cases.)
For convenience, you can use a delta and MSG or RUN keyword in the OMIT command. The following sequences are exactly equivalent:
OMIT 1 Jan
REM 1 Jan +4 MSG New year's day is %b!
and
OMIT 1 Jan +4 MSG New year's day is %b!
THE BEFORE, AFTER AND SKIP KEYWORDS
Normally, days which are omitted, whether by a global OMIT command or the local OMIT keyword in a REM statement, only affect the counting of the -back or the +delta. For example, suppose you have a meeting every Wednesday. Suppose, too, that you have indicated 11 Nov as a holiday:
OMIT 11 Nov +4 MSG Remembrance Day
REM Wed +1 MSG Code meeting %b.
The above sequence will issue a reminder about a meeting for 11 November 1992, which is a Wednesday. This is probably incorrect. There are three options:
The BEFORE and AFTER keywords move the trigger date of a reminder to before or after a block of omitted days, respectively. Suppose you normally run a backup on the first day of the month. However, if the first day of the month is a weekend or holiday, you run the backup on the first working day following the weekend or holiday. You could use:
REM 1 OMIT Sat Sun AFTER RUN do_backup
Let's examine how the trigger date is computed. The 1 specifies the first day of the month. The local OMIT keyword causes the AFTER keyword to move the reminder forward past weekends. Finally, the AFTER keyword will keep moving the reminder forward until it has passed any holidays specified with global OMIT commands.
Remind allows you to include other files in your reminder script, similar to the C preprocessor #include directive. For example, your system administrator may maintain a file of holidays or system-wide reminders. You can include these in your reminder script as follows:
INCLUDE /usr/share/remind/holidays
INCLUDE /usr/share/remind/reminders
(The actual pathnames vary from system to system - ask your system administrator.)
INCLUDE files can be nested up to a depth of 8.
If you specify a filename of "-" in the INCLUDE command, Remind will begin reading from standard input.
If you include other files in your reminder script, you may not always entirely "trust" the contents of the other files. For example, they may contain RUN-type reminders which could be used to access your files or perform undesired actions. The RUN command can restrict this: If you include the command RUN OFF in your top-level reminder script, any reminder or expression which would normally execute a system command is disabled. RUN ON will re-enable the execution of system commands. Note that the RUN ON command can only be used in your top-level reminder script; it will not work in any files accessed by the INCLUDE command. This is to protect you from someone placing a RUN ON command in an included file. However, the RUN OFF command can be used at top level or in an included file.
If you run Remind with the -r command-line option, RUN-type reminders and the shell() function will be disabled, regardless of any RUN commands in the reminder script. However, any command supplied with the -k option will still be executed.
One use of the RUN command is to provide a secure interface between Remind and the Elm mail system. The Elm system can automatically scan incoming mail for reminder or calendar entries, and place them in your calendar file. To use this feature, you should set the calendar filename option under Elm to be something like "~/.reminders.in", not your main reminder file! This is so that any RUN ON commands mailed to you can never be activated.
Then, you can use the Elm scan message for calendar entries command to place reminders prefaced by "->" into .reminders.in. In your main .reminders file, include the following lines:
RUN OFF # Disable RUN
INCLUDE .reminders.in
RUN ON # Re-enable RUN
When Remind first issues a reminder, it prints a message like this:
Reminders for Friday, 30th October, 1992 (today):
(The banner is not printed if any of the calendar-producing options is used, or if the -k option is used.)
The BANNER command lets you change the format. It should appear before any REM commands. The format is:
The format is similar to the body of a REM command. It is passed through the substitution filter, with an implicit trigger of the current system date. Thus, the default banner is equivalent to:
BANNER Reminders for %w, %d%s %m, %y%o:
You can disable the banner completely with BANNER %. Or you can create a custom banner:
BANNER Hi - here are your reminders for %y/%t/%r:
Sometimes, it is necessary to temporarily change the global OMITs which are in force for a few reminders. Three commands allow you to do this:
For example, suppose you have a block of reminders which require a clear OMIT context, and that they also introduce unwanted global OMITs which could interfere with later reminders. You could use the following fragment:
PUSH-OMIT-CONTEXT # Save the current context
CLEAR-OMIT-CONTEXT # Clean the slate
# Block of reminders goes here
POP-OMIT-CONTEXT # Restore the saved omit context
In certain contexts, to be described later, Remind will accept expressions for evaluation. Remind expressions resemble C expressions, but operate on different types of objects.
DATA TYPES
Remind expressions understand four types of objects:
CONSTANTS
The following examples illustrate constants in Remind expressions:
Note that DATE constants are printed without the quotes. Although either '-' or '/' is accepted as a date separator on input, when dates are printed, only one will be used. The choice of whether to use '-' or '/' is made at compile-time. Note also that versions of Remind prior to 03.00.01 did not support date constants. In those versions, you must create dates using the date() function. Also, versions prior to 03.00.02 did not support the '-' date separator.
OPERATORS
Remind has the following operators. Operators on the same line have equal precedence, while operators on lower lines have lower precedence than those on higher lines. The operators approximately correspond to C operators.
! - (unary logical negation and arithmetic negation)
* / %
+ -
< <= > >=
== !=
&&
||
DESCRIPTION OF OPERATORS
INT + TIME or TIME + INT - returns a TIME obtained by adding INT minutes to the original TIME.
INT + DATE or DATE + INT - returns a DATE obtained by adding INT days to the original DATE.
STRING + STRING - returns a STRING which is the concatenation of the two original STRINGs.
STRING + anything or anything + STRING - converts the non-STRING argument to a STRING, and then performs concatenation. See the coerce() function.
DATE - DATE - returns (as an INT) the difference in days between two DATEs.
TIME - TIME - returns (as an INT) the difference in minutes between two TIMEs.
DATE - INT - returns a DATE which is INT days earlier than the original DATE.
TIME - INT - returns a TIME which is INT minutes earlier than the original TIME.
NOTES
Operators of equal precedence are always evaluated from left to right, except where parentheses dictate otherwise. This is important, because the enhanced "+" and "-" operators are not necessarily associative. For example:
1 + 2 + "string" + 3 + 4 yields "3string34"
1 + (2 + "string") + (3 + 4) yields "12string7"
12:59 + 1 + "test" yields "13:00test"
12:59 + (1 + "test") yields "12:591test"
The logical operators are not so-called short-circuit operators, as they are in C. Both operands are always evaluated. Thus, an expression such as:
(f!=0) && (100/f <= 3)
will cause an error if f is zero.
VARIABLES
Remind allows you to assign values to variables. The SET command is used as follows:
SET var expr
Var is the name of a variable. It must start with a letter or underscore, and consist only of letters, digits and underscores. Only the first 12 characters of a variable name are significant. Variable names are not case sensitive; thus, "Afoo" and "afOo" are the same variable. Examples:
SET a 10 + (9*8)
SET b "This is a test"
SET mydir getenv("HOME")
SET time 12:15
SET date today()
Note that variables themselves have no type. They take on the type of whatever you store in them.
To delete a variable, use the UNSET command:
UNSET var [var...]
For example, to delete all the variables declared above, use:
UNSET a b mydir time date
SYSTEM VARIABLES
In addition to the regular user variables, Remind has several "system variables" which are used to query or control the operating state of Remind. System variables are available starting from version 03.00.07 of Remind.
All system variables begin with a dollar sign '$'. They can be used in SET commands and expressions just as regular variables can. All system variables always hold values of a specified type. In addition, some system variables cannot be modified, and you cannot create new system variables. System variables can be initialized on the command line with the -i option, but you may need to quote them to avoid having the shell interpret the dollar sign. System variable names are not case-sensitive.
The following system variables are defined. Those marked "read-only" cannot be changed with the SET command. All system variables hold values of type INT, unless otherwise specified.
MSF He said, "Huh! (Two spaces will follow this.)" Yup.
because the final parenthesis and quote are ignored (for the purposes of spacing) when they follow a period.
The latitude and longitude information is required for the functions sunrise() and sunset(). Default values can be compiled into Remind, or you can SET the correct values at the start of your reminder scripts.
Note: If any of the calendar modes are in effect, then the values of $Daemon, $DontFork, $DontTrigAts, $DontQueue, $HushMode, $IgnoreOnce, $InfDelta, and $NextMode are not meaningful.
BUILT-IN FUNCTIONS
Remind has a plethora of built-in functions. The syntax for a function call is the same as in C - the function name, followed a comma-separated list of arguments in parentheses. Function names are not case-sensitive. If a function takes no arguments, it must be followed by "()" in the function call. Otherwise, Remind will interpret it as a variable name, and probably not work correctly.
In the descriptions below, short forms are used to denote acceptable types for the arguments. The characters "i", "s", "d" and "t" denote INT, STRING, DATE and TIME arguments, respectively. If an argument can be one of several types, the characters are concatenated. For example, "di_arg" denotes an argument which can be a DATE or an INT. "x_arg" denotes an argument which can be of any type. The type of the argument is followed by an underscore and an identifier naming the argument, for convenience.
The built-in functions are:
choose(0, "foo", 1:13, 1000) returns "foo"
choose(1, "foo", 1:13, 1000) returns "foo"
choose(2, "foo", 1:13, 1000) returns 1:13
choose(3, "foo", 1:13, 1000) returns 1000
choose(4, "foo", 1:13, 1000) returns 1000
If arg is already of the type specified, it is returned unchanged.
If type is "STRING", then arg is converted to a string consisting of its printed representation.
If type is "DATE", then an INT arg is converted by interpreting it as the number of days since 1 January baseyr(). A STRING arg is converted by attempting to read it as if it were a printed date. A TIME arg cannot be converted to a date.
If type is "TIME", then an INT arg is converted by interpreting it as the number of minutes since midnight. A STRING arg is converted by attempting to read it as if it were a printed time. A DATE arg cannot be converted to a time.
If type is "INT", then DATE and TIME arguments are converted using the reverse of procedures described above. A STRING arg is converted by parsing it as an integer.
defined("X")
and not:
defined(X)
The second example will attempt to evaluate X, and will return an error if it is undefined or not of type STRING.
Note that if str does not end with "%", a newline character will be added to the end of the result. Also, calling dosubst() with a date which is in the past (i.e., if date < today()) will produce undefined results.
Dosubst() is only available starting from version 03.00.04 of Remind.
INCLUDE [filedir()]/stuff
The optional parameter start specifies the position in search at which to start looking for target.
Note that this function is only as reliable as the C run-time library functions. It is available starting with version 03.00.07 of Remind.
Note that this function is only as reliable as the C run-time library functions. It is available starting with version 03.00.07 of Remind.
For example, the following returns the date of the next full moon:
SET fullmoon moondate(2)
For example, the following returns the date and time of the next full moon:
MSG Next full moon at [moontime(2)] on [moondate(2)]
If two arguments are supplied, returns str1 + "s" if num is not 1. Otherwise, returns str1.
If three arguments are supplied, returns str1 if num is 1, and str2 otherwise.
REM [trigger(moondate(0))] PS [psmoon(0)]
REM [trigger(moondate(1))] PS [psmoon(1)]
REM [trigger(moondate(2))] PS [psmoon(2)]
REM [trigger(moondate(3))] PS [psmoon(3)]
REM Sat Sun PS [psshade(95)]
The above command emits PostScript code to lightly shade the boxes for Saturday and Sunday in a PostScript calendar.
The functions sunrise() and sunset() are based on an algorithm in "Almanac for Computers for the year 1978" by L. E. Doggett, Nautical Almanac Office, USNO. They require the latitude and longitude to be specified by setting the appropriate system variables. (See "System Variables".) The sun functions should be accurate to within about 2 minutes for latitudes lower than 60 degrees. The functions are available starting from version 03.00.07 of Remind.
trigger('1993/04/01')
returns "1 April 1993",
trigger('1994/08/09', 12:33)
returns "9 August 1994 AT 12:33", and
trigger('1994/12/01', 03:00, 1)
returns "30 November 1994 AT 22:00" for EST, which is 5 hours behind UTC. The value for your time zone may differ.
REM Mon OMIT Mon SKIP MSG Impossible!
However, if you supply a second argument, it is returned if the varname is not defined. The expression value("XY", 0) will return 0 if XY is not defined, and the value of XY if it is defined.
An extremely powerful feature of Remind is its macro capability, or "expression pasting."
In almost any situation where Remind is not expecting an expression, you can "paste" an expression in. To do this, surround the expression with square brackets. For example:
REM [trigger(mydate)] MSG foo
This evaluates the expression "trigger(mydate)", where "mydate" is presumably some pre-computed variable, and then "pastes" the result into the command-line for the parser to process.
A formal description of this is: When Remind encounters a "pasted-in" expression, it evaluates the expression, and coerces the result to a STRING. It then substitutes the string for the pasted-in expression, and continues parsing. Note, however, that expressions are evaluated only once, not recursively. Thus, writing:
["[a+b]"]
causes Remind to read the token "[a+b]". It does not interpret this as a pasted-in expression. In fact, the only way to get a literal left-bracket into a reminder is to use ["["].
You can use expression pasting almost anywhere. However, there are a few exceptions:
["SET"] a 1
This restriction is because Remind must be able to unambiguously determine the first token of a line for the flow-control commands (to be discussed later.)
In fact, if Remind cannot determine the first token on a line, it assumes that it is a REM command. If expression-pasting is used, Remind assumes it is a REM command. Thus, the following three commands are equivalent:
REM 12 Nov 1993 AT 13:05 MSG BOO!
12 Nov 1993 AT 13:05 MSG BOO!
[12] ["Nov " + 1993] AT [12:05+60] MSG BOO!
REM ["12 Nov 1993 AT 13:05 " + "MSG" + " BOO!"]
COMMON PITFALLS IN EXPRESSION PASTING
Remember, when pasting in expressions, that extra spaces are not inserted. Thus, something like:
REM[expr]MSG[expr]
will probably fail.
If you use an expression to calculate a delta or back, ensure that the result is a positive number. Something like:
REM +[mydelta] Nov 12 1993 MSG foo
will fail if mydelta happens to be negative.
Remind has commands which control the flow of a reminder script. Normally, reminder scripts are processed sequentially. However, IF and related commands allow you to process files conditionally, and skip sections which you don't want interpreted.
THE IF COMMAND
The IF command has the following form:
IF expr
t-command
t-command...
ELSE
f-command
f-command...
ENDIF
Note that the commands are shown indented for clarity. Also, the ELSE portion can be omitted. IF commands can be nested up to a small limit, probably around 8 or 16 levels of nesting, depending on your system.
If the expr evaluates to a non-zero INT, or a non-null STRING, then the IF portion is considered true, and the t-commands are executed. If expr evaluates to zero or null, then the f-commands (if the ELSE portion is present) are executed. If expr is not of type INT or STRING, then it is an error.
Examples:
IF defined("want_hols")
INCLUDE /usr/share/remind/holidays
ENDIF
IF today() > '1992/2/10'
set missed_ap "You missed it!"
ELSE
set missed_ap "Still have time..."
ENDIF
THE IFTRIG COMMAND
The IFTRIG command is similar to an IF command, except that it computes a trigger (as in the REM command), and evaluates to true if a corresponding REM command would trigger. Examples:
IFTRIG 1 Nov
; Executed on 1 Nov
ELSE
; Executed except on 1 Nov
ENDIF
IFTRIG 1 -1 OMIT Sat Sun +4
; Executed on last working day of month,
; and the 4 working days preceding it
ELSE
; Executed except on above days
ENDIF
Note that the IFTRIG command computes a trigger date, which can be retrieved with the trigdate() function. You can use all of the normal trigger components, such as UNTIL, delta, etc in the IFTRIG command.
In addition to the built-in functions, Remind allows you to define your own functions. The FSET command does this for you:
FSET fname(args) expr
Fname is the name of the function, and follows the convention for naming variables. Args is a comma-separated list of arguments, and expr is an expression. Args can be empty, in which case you define a function taking no parameters. Here are some examples:
FSET double(x) 2*x
FSET yeardiff(date1, date2) year(date1) - year(date2)
FSET since(x) ord(year(trigdate())-x)
The last function is useful in birthday reminders. For example:
REM 1 Nov +12 MSG Dean's [since(1984)] birthday is %b.
Dean was born in 1984. The above example, on 1 November 1992, would print:
Dean's 8th birthday is today.
Notes:
fset func(x) value("x")
set x 1
set y func(5)
The above sequence sets y to 1, which is the global value of x.
The SCHED keyword allows precise control over the scheduling of timed reminders. It should be followed by the name of a user-defined function, sched_function.
If a scheduling function is supplied, then it must take one argument of type INT. Rather than using the AT time, time delta, and time repeat, Remind calls the scheduling function to determine when to trigger the reminder. The first time the reminder is queued, the scheduling function is called with an argument of 1. Each time the reminder is triggered, it is re-scheduled by calling the scheduling function again. On each call, the argument is incremented by one.
The return value of the scheduling function must be an INT or a TIME. If the return value is a TIME, then the reminder is re-queued to trigger at that time. If it is a positive integer n, then the reminder is re-queued to trigger at the previous trigger time plus n minutes. Finally, if it is a negative integer or zero, then the reminder is re-queued to trigger n minutes before the AT time. Note that there must be an AT clause for the SCHED clause to do anything.
Here's an example:
FSET _sfun(x) choose(x, -60, 30, 15, 10, 3, 1, 1, 1, 1, 0)
REM AT 13:00 SCHED _sfun MSG foo
The reminder would first be triggered at 13:00-60 minutes, or at 12:00. It would next be triggered 30 minutes later, at 12:30. Then, it would be triggered at 12:45, 12:55, 12:58, 12:59, 13:00, 13:01 and 13:02.
NOTES
The form of REM which uses SATISFY is as follows:
REM trigger SATISFY expr
The way this works is as follows: Remind first calculates a trigger date, in the normal fashion. Next, it sets trigdate() to the calculated trigger date. It then evaluates expr. If the result is not the null string or zero, processing ends. Otherwise, Remind computes the next trigger date, and re-tests expr. This iteration continues until expr evaluates to non-zero or non-null, or until the iteration limit specified with the -x command-line option is reached.
If expr is not satisfied, then trigvalid() is set to 0. Otherwise, trigvalid() is set to 1. In any event, no error message is issued.
This is really useful only if expr involves a call to the trigdate() function; otherwise, expr will not change as Remind iterates.
An example of the usefulness of SATISFY: Suppose you wish to be warned of every Friday the 13th. Your first attempt may be:
# WRONG!
REM Fri 13 +2 MSG Friday the 13th is %b.
But this won't work. This reminder triggers on the first Friday on or after the 13th of each month. The way to do it is with a more complicated sequence:
REM 13 SATISFY wkdaynum(trigdate()) == 5
IF trigvalid()
REM [trigger(trigdate())] +2 MSG \
Friday the 13th is %b.
ENDIF
Let's see how this works. The SATISFY clause iterates through all the 13ths of successive months, until a trigger date is found whose day-of-week is Friday (== 5). If a valid date was found, we use the calculated trigger date (converted into a trigger format with the trigger() function) to set up the next reminder.
We could also have written:
REM Fri SATISFY day(trigdate()) == 13
but this would result in more iterations, since "Fridays" occur more often than "13ths of the month."
This technique of using one REM command to calculate a trigger date to be used by another command is quite powerful. For example, suppose you wanted to OMIT Labour day, which is the first Monday in September. You could use:
# Note: SATISFY 1 is an idiom for "do nothing"
REM Mon 1 Sept SATISFY 1
OMIT [trigger(trigdate())]
CAVEAT: This only omits the next Labour Day, not all Labour Days in the future. This could cause strange results, as the OMIT context can change depending on the current date. For example, if you use the following command after the above commands:
REM Mon AFTER msg hello
the result will not be as you expect. Consider producing a calendar for September, 1992. Labour Day was on Monday, 7 September, 1992. However, when Remind gets around to calculating the trigger for Tuesday, 8 September, 1992, the OMIT command will now be omitting Labour Day for 1993, and the "Mon AFTER" command will not be triggered. (But see the description of SCANFROM in the section "Details about Trigger Computation.")
It is probably best to stay away from computing OMIT trigger dates unless you keep these pitfalls in mind.
For versions of Remind starting from 03.00.07, you can include a MSG, RUN, etc. clause in a SATISFY clause as follows:
REM trigger_stuff SATISFY [expr] MSG body
Note that for this case only, the expr after SATISFY must be enclosed in braces. It must come after all the other components of the trigger, and immediately before the MSG, RUN, etc. keyword. If expr cannot be satisfied, then the reminder is not triggered.
Thus, the "Friday the 13th" example can be expressed more compactly as:
REM 13 +2 SATISFY [wkdaynum(trigdate()) == 5] \
MSG Friday the 13th is %b.
And you can trigger a reminder on Mondays, Wednesdays and Thursdays occurring on odd-numbered days of the month with the following:
REM Mon Wed Thu SATISFY [day(trigdate())%2] \
MSG Here it is!!!
Although the command-line -d option is useful for debugging, it is often overkill. For example, if you turn on the -dx option for a reminder file with many complex expressions, you'll get a huge amount of output. The DEBUG command allows you to control the debugging flags under program control. The format is:
DEBUG [+flagson] [-flagsoff]
Flagson and flagsoff consist of strings of the characters "extvl" which correspond to the debugging options discussed in the command-line options section. If preceded with a "+", the corresponding group of debugging options is switched on. Otherwise, they are switched off. For example, you could use this sequence to debug a complicated expression:
DEBUG +x
set a very_complex_expression(many_args)
DEBUG -x
THE DUMPVARS COMMAND
The command DUMPVARS displays the values of variables in memory. Its format is:
DUMPVARS [var...]
If you supply a space-separated list of variable names, the corresponding variables are displayed. If you do not supply a list of variables, then all variables in memory are displayed. To dump a system variable, put its name in the list of variables to dump. If you put a lone dollar sign in the list of variables to dump, then all system variables will be dumped.
THE ERRMSG COMMAND
The ERRMSG command has the following format:
ERRMSG body
The body is passed through the substitution filter (with an implicit trigger date of today()) and printed to the error output stream. Example:
IF !defined("critical_var")
ERRMSG You must supply a value for "critical_var"
EXIT
ENDIF
THE EXIT COMMAND
The above example also shows the use of the EXIT command. This causes an unconditional exit from script processing. Any queued timed reminders are discarded. If you are in calendar mode (described next), then the calendar processing is aborted.
If you supply an INT-type expression after the EXIT command, it is returned to the calling program as the exit status. Otherwise, an exit status of 99 is returned.
THE FLUSH COMMAND
This command simply consists of the word FLUSH on a line by itself. The command flushes the standard output and standard error streams used by Remind. This is not terribly useful to most people, but may be useful if you run Remind as a subprocess of another program, and want to use pipes for communication.
If you supply the -c, -s or -p command-line option, then Remind runs in "calendar mode." In this mode, Remind interprets the script repeatedly, performing one iteration through the whole file for each day in the calendar. Reminders which trigger are saved in internal buffers, and then inserted into the calendar in the appropriate places.
If you also supply the -a option, then Remind will not include timed reminders in the calendar.
The -p option is used in conjunction with the rem2ps program to produce a calendar in PostScript format. For example, the following command will send PostScript code to standard output:
remind -p .reminders | rem2ps
You can print a PostScript calendar by piping this to the lpr command.
If you have a reminder script called ".reminders", and you execute this command:
remind -c .reminders jan 1993
then Remind executes the script 31 times, once for each day in January. Each time it executes the script, it increments the value of today(). Any reminders whose trigger date matches today() are entered into the calendar.
MSG and CAL-type reminders, by default, have their entire body inserted into the calendar. RUN-type reminders are not normally inserted into the calendar. However, if you enclose a portion of the body in the %"...%" sequence, only that portion is inserted. For example, consider the following:
REM 6 Jan MSG %"David's birthday%" is %b
In the normal mode, Remind would print "David's birthday is today" on 6 January. However, in the calendar mode, only the text "David's birthday" is inserted into the box for 6 January.
If you explicitly use the %"...%" sequence in a RUN-type reminder, then the text between the delimiters is inserted into the calendar. If you use the sequence %"%" in a MSG or CAL-type reminder, then no calendar entry is produced for that reminder.
PRESERVING VARIABLES
Because Remind iterates through the script for each day in the calendar, slow operations may severely reduce the speed of producing a calendar.
For example, suppose you set the variables "me" and "hostname" as follows:
SET me shell("whoami")
SET hostname shell("hostname")
Normally, Remind clears all variables between iterations in calendar mode. However, if certain variables are slow to compute, and will not change between iterations, you can "preserve" their values with the PRESERVE command. Also, since function definitions are preserved between calendar iterations, there is no need to redefine them on each iteration. Thus, you could use the following sequence:
IF ! defined("initialized")
set initialized 1
set me shell("whoami")
set hostname shell("hostname")
fset func(x) complex_expr
preserve initialized me hostname
ENDIF
The operation is as follows: On the first iteration through the script, "initialized" is not defined. Thus, the commands between IF and ENDIF are executed. The PRESERVE command ensures that the values of initialized, me and hostname are preserved for subsequent iterations. On the next iteration, the commands are skipped, since initialized has remained defined. Thus, time-consuming operations which do not depend on the value of today() are done only once.
System variables (those whose names start with '$') are automatically preserved between calendar iterations.
Note that for efficiency, Remind caches the reminder script (and any INCLUDEd files) in memory when producing a calendar.
Timed reminders are sorted and placed into the calendar in time order. These are followed by non-timed reminders. Remind automatically places the time of timed reminders in the calendar according to the -b command-line option. Reminders in calendar mode are sorted as if the -g option had been used; you can change the sort order in calendar mode by explicitly using the -g option to specify a different order from the default.
REPEATED EXECUTION
If you supply a repeat parameter on the command line, and do not use the -c, -p, or -s options, Remind operates in a similar manner to calendar mode. It repeatedly executes the reminder script, incrementing today() with each iteration. The same rules about preserving variables and function definitions apply. Note that using repeat on the command line also enables the -q option and disables any -z option. As an example, if you want to see how Remind will behave for the next week, you can type:
remind .reminders '*7'
If you want to print the dates of the next 1000 days, use:
(echo 'banner %'; echo 'msg [today()]%') | remind - '*1000'
The -i option is used to initialize variables on the Remind command line. The format is -ivar=expr, where expr is any valid expression. Note that you may have to use quotes or escapes to prevent the shell from interpreting special characters in expr. You can have as many -i options as you want on the command line, and they are processed in order. Thus, if a variable is defined in one -i option, it can be referred to by subsequent -i options.
Note that if you supply a date on the command line, it is not parsed until all options have been processed. Thus, if you use today() in any of the -i expressions, it will return the same value as realtoday() and not the date supplied on the command line.
Any variables defined on the command line are preserved as with the PRESERVE command.
You should not have any spaces between the -i option and the equal sign; otherwise, strange variable names are created which can only be accessed with the value() or defined() functions.
If your site uses the Remind-all shell script to mail reminders to users, the script will initialize the variable remind_all to 1 using the -i option. Thus, you can detect when your reminder script is being processed by Remind-all and can use this information to control which reminders you want mailed to you.
The PS and PSFILE reminders pass PostScript code directly to the printer. They differ in that the PS-type reminder passes its body directly to the PostScript output (after processing by the substitution filter) while the PSFILE-type's body should simply consist of a filename. The Rem2ps program will open the file named in the PSFILE-type reminder, and include its contents in the PostScript output.
The PostScript-type reminders for a particular day are included in the PostScript output in sorted order of priority. Note that the order of PostScript commands has a major impact on the appearance of the calendars. For example, PostScript code to shade a calendar box will obliterate code to draw a moon symbol if the moon symbol code is placed in the calendar first. For this reason, you should not provide PS or PSFILE-type reminders with priorities; instead, you should ensure that they appear in the reminder script in the correct order. PostScript code should draw objects working from the background to the foreground, so that foreground objects properly overlay background ones. If you prioritize these reminders and run the script using descending sort order for priorities, the PostScript output will not work.
All of the PostScript code for a particular date is enclosed in a save-restore pair. However, if several PostScript-type reminders are triggered for a single day, each section of PostScript is not enclosed in a save-restore pair - instead, the entire body of included PostScript is enclosed.
PostScript-type reminders are executed by the PostScript printer before any regular calendar entries. Thus, regular calendar entries will overlay the PostScript-type reminders, allowing you to create shaded or graphical backgrounds for particular days.
Before executing your PostScript code, the origin of the PostScript coordinate system is positioned to the bottom left-hand corner of the "box" in the calendar representing today(). This location is exactly in the middle of the intersection of the bottom and left black lines delineating the box - you may have to account for the thickness of these lines when calculating positions.
Several PostScript variables are available to the PostScript code you supply. All distance and size variables are in PostScript units (1/72 inch.) The variables are:
REM PS Border BoxHeight Border sub DaySize sub moveto \
/DayFont findfont DaySize scalefont setfont \
([hebday(today())] [hebmon(today())]) show
Note that if you supply PostScript code, it is possible to produce invalid PostScript files. Always test your PostScript thoroughly with a PostScript viewer before sending it to the printer. You should not use any document structuring comments in your PostScript code.
If you use the -z command-line option, Remind runs in the "daemon" mode. In this mode, no "normal" reminders are issued. Instead, only timed reminders are collected and queued, and are then issued whenever they reach their trigger time.
In addition, Remind wakes up every few minutes to check the modification date on the reminder script (the filename supplied on the command line.) If Remind detects that the script has changed, it re-executes itself in daemon mode, and interprets the changed script.
In daemon mode, Remind also re-reads the remind script when it detects that the system date has changed.
In daemon mode, Remind acts as if the -f option had been used, so to run in the daemon mode in the background, use:
remind -z .reminders &
If you use sh or bash, you may have to use the "nohup" command to ensure that the daemon is not killed when you log out.
The -g option causes Remind to sort reminders by trigger date, time and priority before issuing them. Note that reminders are still calculated in the order encountered in the script. However, rather than being issued immediately, they are saved in an internal buffer. When Remind has finished processing the script, it issues the saved reminders in sorted order. The -g option can be followed by up to three characters, which must be "a" or "d". The first character specifies the sort order by trigger date (ascending or descending), the second specifies the sort order by trigger time and the third specifies the sort order by priority. The default is to sort all fields in ascending order.
In ascending order, reminders are issued with the most imminent first. Descending order is the reverse. Reminders are always sorted by trigger date, and reminders with the same trigger date are then sorted by trigger time. Non-timed reminders are always issued after timed reminders in this mode. If two reminders have the same date and time, then the priority is used to break ties. Reminders with the same date, time and priority are issued in the order they were encountered.
You can define a user-defined function called SORTBANNER which takes one DATE-type argument. In sort mode, the following sequence happens:
If Remind notices that the next reminder to issue has a different trigger date from the previous one (or if it is the first one to be issued), then SORTBANNER is called with the trigger date as its argument. The result is coerced to a string, and passed through the substitution filter with the appropriate trigger date. The result is then displayed.
Here's an example - consider the following fragment:
# Switch off the normal banner
BANNER %
REM 11 March 1993 ++1 MSG Not so important
REM 17 March 1993 ++7 MSG Way in the future
REM 10 March 1993 MSG Important Reminder
REM 11 March 1993 ++1 MSG Not so important - B
FSET sortbanner(x) iif(x == today(), \
"***** THINGS TO DO TODAY *****", \
"----- Things to do %b -----")
Running this with the -gaa option on 10 March 1993 produces the following output:
***** THINGS TO DO TODAY *****
Important Reminder
----- Things to do tomorrow -----
Not so important
Not so important - B
----- Things to do in 7 days' time -----
Way in the future
You can use the args() built-in function to determine whether or not SORTBANNER has been defined. (This could be used, for example, to provide a default definition for SORTBANNER in a system-wide file included at the end of the user's file.) Here's an example:
# Create a default sortbanner function if it hasn't already
# been defined
if args("sortbanner") != 1
fset sortbanner(x) "--- Things to do %b ---"
endif
You can define two functions in your script called msgprefix() and msgsuffix(). They should each accept one argument, a number from 0 to 9999.
In normal mode, for MSG- and MSF-type reminders, the following sequence occurs when Remind triggers a reminder:
Here's an example: The following definition causes priority-0 reminders to be preceded by "URGENT", and priority-6000 reminders to be preceded by "(not important)".
fset msgprefix(x) iif(x==0, "URGENT: ", \
x==6000, "(not important) ", "")
In Calendar Mode (with the -c, -s or -p options), an analagous pair of functions named calprefix() and calsuffix() can be defined. They work with all reminders which produce an entry in the calendar (i.e., CAL- and possibly RUN-type reminders as well as MSG-type reminders.)
NOTES
Normally, the body of a reminder is followed by a carriage return. Thus, the results of msgsuffix() will appear on the next line. If you don't want this, end the body of the reminder with a percentage sign, "%". If you want a space between your reminders, simply include a carriage return (char(13)) as part of the msgsuffix() return value.
If Remind has problems evaluating msgprefix(), msgsuffix() or sortbanner(), you will see a lot of error messages. For an example of this, define the following:
fset msgprefix(x) x/0
Your version of Remind may have been compiled to support a language other than English. This support may or may not be complete - for example, all error and usage messages may still be in English. However, at a minimum, foreign-language versions of Remind will output names of months and weekdays in the foreign language. Also, the substitution mechanism will substitute constructs suitable for the foreign language rather than for English.
A foreign-language version of Remind will accept either the English or foreign-language names of weekdays and months in a reminder script. However, for compatibility between versions of Remind, you should use only the English names in your scripts.
Remind has support for the Hebrew calendar, which is a luni-solar calendar. This allows you to create reminders for Jewish holidays, jahrzeits (anniversaries of deaths) and smachot (joyous occasions.)
THE HEBREW YEAR
The Hebrew year has 12 months, alternately 30 and 29 days long. The months are: Tishrey, Heshvan, Kislev, Tevet, Shvat, Adar, Nisan, Iyar, Sivan, Tamuz, Av and Elul. In Biblical times, the year started in Nisan, but Rosh Hashana (Jewish New Year) is now celebrated on the 1st and 2nd of Tishrey.
In a cycle of 19 years, there are 7 leap years, being years 3, 6, 8, 11, 14, 17 and 19 of the cycle. In a leap year, an extra month of 30 days is added before Adar. The two Adars are called Adar A and Adar B.
For certain religious reasons, the year cannot start on a Sunday, Wednesday or Friday. To adjust for this, a day is taken off Kislev or added to Heshvan. Thus, a regular year can have from 353 to 355 days, and a leap year from 383 to 385.
When Kislev or Heshvan is short, it is called "chaser", or lacking. When it is long, it is called "shalem", or full.
The Jewish date changes at sunset. However, Remind will change the date at midnight, not sunset. So in the period between sunset and midnight, Remind will be a day earlier than the true Jewish date. This should not be much of a problem in practice.
The computations for the Jewish calendar were based on the program "hdate" written by Amos Shapir of the Hebrew University of Jerusalem, Israel. He also supplied the preceding explanation of the calendar.
HEBREW DATE FUNCTIONS
The yrstart parameter can either be a DATE or an INT. If it is a DATE, then the hebdate() scans for the first Hebrew date on or after that date. For example:
hebdate(15, "Nisan", '1990/01/01')
returns 1990/03/30, because that is the first occurrence of 15 Nisan on or after 1 January 1990.
If yrstart is an INT, it is interpreted as a Hebrew year. Thus:
hebdate(22, "Kislev", 5756)
returns 1995/12/15, because that date corresponds to 22 Kislev, 5756. Note that none of the Hebrew date functions will work with dates outside Remind's normal range for dates.
If yrstart is not supplied, it defaults to today().
The jahr modifies the behaviour of hebdate() as follows:
If jahr is 0 (the default), then hebdate() keeps scanning until it finds a date which exactly satisfies the other parameters. For example:
hebdate(30, "Adar A", 1993/01/01)
returns 1995/03/02, corresponding to 30 Adar A, 5755, because that is the next occurrence of 30 Adar A after 1 January, 1993. This behaviour is appropriate for Purim Katan, which only appears in leap years.
If jahr is 1, then the date is modified as follows:
This behaviour is appropriate for smachot (joyous occasions) and for some jahrzeits - see "JAHRZEITS."
if jahr is 2, then the date is modified as follows:
if jahr is not 0, 1, or 2, it is interpreted as a Hebrew year, and the behaviour is calculated as described in the next section, "JAHRZEITS."
The aflag parameter modifies the behaviour of the function for dates in Adar during leap years. The aflag is only used if yrstart is a DATE type (or is omitted, defaulting to today().)
The aflag only affects date calculations if hebmon is specified as "Adar". In leap years, the following algorithm is followed:
JAHRZEITS
A jahrzeit is a yearly commemoration of someone's death. It normally takes place on the anniversary of the death, but may be delayed if burial is delayed - consult a rabbi.
In addition, because some months change length, it is not obvious which day the anniversary of a death is. The following rules are used:
Specifying a Hebrew year for the jahr parameter causes the correct behaviour to be selected for a death in that year. You may also have to specify aflag, depending on your tradition.
The jahrzeit information was supplied by Frank Yellin, who quoted "The Comprehensive Hebrew Calendar" by Arthur Spier, and "Calendrical Calculations" by E. M. Reingold and Nachum Dershowitz.
COMMAND ABBREVIATIONS
The following tokens can be abbreviated:
NIFTY EXAMPLES
This section is a sampling of what you can do with Remind.
REM 5 Feb 1991 AT 14:00 +45 *30 \
RUN mail -s "Meeting at %2" $LOGNAME </dev/null &
On 5 February, 1991, this reminder will mail you reminders of a 2:00pm meeting at 1:15, 1:45 and 2:00. The subject of the mail message will be "Meeting at 2:00pm" and the body of the message will be blank.
REM AT 17:00 RUN echo "5:00pm - GO HOME!" | xless -g +0+0 &
This reminder will pop up an xless window at 5:00pm every day. The xless window will contain the line "5:00pm - GO HOME!"
REM AT 23:59 RUN (sleep 120; remind -a [filename()]) &
This reminder will run at one minute to midnight. It will cause a new Remind process to start at one minute past midnight. This allows you to have a continuous reminder service so you can work through the night and still get timed reminders for early in the morning. Note that this trick is no longer necessary, providing you run Remind in daemon mode.
remind -c12 /dev/null Jan 1993
This invocation of Remind will cause it to print a calendar for 1993, with all entries left blank.
REM CAL [trigdate()-date(year(trigdate()), 1, 1)+1]
This example puts an entry in each box of a calendar showing the number (1-365 or 366) of the day of the year.
REM Tue 2 Nov SATISFY (year(trigdate())%4) == 0
IF trigvalid()
REM [trigger(trigdate())] ++5 MSG \
U.S. Presidential Election!!
ENDIF
This example warns you 5 days ahead of each American presidential election. The first REM command calculates the first Tuesday after the first Monday in November. (This is equivalent to the first Tuesday on or after 2 November.) The SATISFY clause ensures that the trigger date is issued only in election years, which are multiples of 4. The second REM command actually issues the reminder.
DETAILS ABOUT TRIGGER COMPUTATION
Here is a conceptual description of how triggers are calculated. Note that Remind actually uses a much more efficient procedure, but the results are the same as if the conceptual procedure had been followed.
Remind starts from the current date (that is, the value of today()) and scans forward, examining each day one at a time until it finds a date which satisfies the trigger, or can prove that no such dates (on or later than today()) exist.
If Remind is executing a SATISFY-type reminder, it evaluates the expression with trigdate() set to the date found above. If the expression evaluates to zero or the null string, Remind continues the scanning procedure described above, starting with the day after the trigger found above.
The SCANFROM clause (having a syntax similar to UNTIL) can modify the search strategy used. In this case, Remind begins the scanning procedure at scan_date, which is the date specified in the SCANFROM clause. For example:
REM Mon 1 SCANFROM 17 Jan 1992 MSG Foo
The example above will always have a trigger date of Monday, 3 February 1992. That is because Remind starts scanning from 17 January 1992, and stops scanning as soon as it hits a date which satisfies "Mon 1."
The main use of SCANFROM is in situations where you want to calculate the positions of floating holidays. Consider the Labour Day example shown much earlier. Labour Day is the first Monday in September. It can move over a range of 7 days. Consider the following sequence:
REM Mon 1 Sept SCANFROM [trigger(today()-7)] SATISFY 1
OMIT [trigger(trigdate())]
REM Mon AFTER MSG Hello
The SCANFROM clause makes sure that Remind begins scanning from 7 days before the current date. This ensures that Labour Day for the current year will continue to be triggered until 7 days after it has occurred. This allows you to safely use the AFTER keyword as shown.
In general, use SCANFROM as shown for safe movable OMITs. The amount you should scan back by (7 days in the example above) depends on the number of possible consecutive OMITted days which may occur, and on the range of the movable holiday. Generally, a value of 7 is safe.
Note that if you use one REM command to calculate a trigger date, perform date calculations (addition or subtraction, for example) and then use the modified date in a subsequent REM command, the results may not be what you intended. This is because you have circumvented the normal scanning mechanism. You should try to write REM commands which compute trigger dates that can be used unmodified in subsequent REM commands. The file "defs.rem" which comes with the Remind distribution contains examples.
DETAILS ABOUT TRIGVALID()
The trigvalid() function returns 1 if Remind could find a trigger date for the previous REM or IFTRIG command. More specifically, it returns 1 if Remind finds a date not before the starting date of the scanning which satisfies the trigger. In addition, there is one special case in which trigvalid() returns 1 and trigdate() returns a meaningful result:
If the REM or IFTRIG command did not contain an UNTIL clause, and contained all of the day, month and year components, then Remind will correctly compute a trigger date, even if it happens to be before the start of scanning. Note that this behaviour is not true for versions of Remind prior to 03.00.01.
David F. Skoll wrote Remind. The moon code was copied largely unmodified from "moontool" by John Walker. The Hebrew calendar support was taken from "hdate" by Amos Shapir. The authors of the language files are listed in the header file "lang.h" which comes with Remind. OS/2 support was provided initially by Darrel Hankerson; more complete OS/2 support was done by Russ Herman.
There's no good reason why read-only system variables are not implemented as functions, or why functions like version(), etc. are not implemented as read-only system variables.
Hebrew dates change at midnight, not sunset.
The UTC functions are not reliable under MS-DOS.
The MS-DOS version of Remind does not support queuing or timed activation of reminders.
Remind has some built-in limits on total line length, substitution buffer length, number of global OMITs, etc.
rem, elm, kall, rem2ps