|REMIND(1)||General Commands Manual||REMIND(1)|
- The -n option causes Remind to print the next occurrence of each reminder in a simple calendar format. You can sort this by date by piping the output through sort(1).
- Runs Remind in "purge" mode to get rid of expired reminders. See the section PURGE MODE for details.
- The -r option disables RUN directives and the shell() function. As of Remind 3.00.17, using -u implies -r.
- The -c option causes Remind to produce a calendar that is sent to standard output. If you supply a number n, then a calendar will be generated for n months, starting with the current month. By default, a calendar for only the current month is produced.
- causes a calendar for n weeks to be produced.
- causes Remind to display reminders on the calendar on the day they actually occur as well as on any preceding days specified by the reminder's delta.
- causes Remind to use VT100 line-drawing characters to draw the calendar. The characters are hard-coded and will only work on terminals that emulate the VT00 line-drawing character set.
- is similar to 'l', but causes Remind to use UNICODE line-drawing characters to draw the calendar. The characters are hard-coded and will only work on terminals that are set to UTF-8 character encoding.
- causes Remind to use VT100 escape sequences to
approximate SPECIAL COLOR reminders. The approximation is (of necessity)
very coarse, because the VT100 only has eight different color sequences,
each with one of two brightnesses. A color component greater than 64 is
considered "on", and if any of the three color components is
greater than 128, the color is considered "bright".
- The -w option specifies the output width, padding and spacing of the formatted calendar output. Col specifies the number of columns in the output device, and defaults to 80. Pad specifies how many lines to use to "pad" empty calendar boxes. This defaults to 5. If you have many reminders on certain days that make your calendar too large to fit on a page, you can try reducing pad to make the empty boxes smaller. Spc specifies how many blank lines to leave between the day number and the first reminder entry. It defaults to 1.
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.
- The -s option is very similar to the -c
option, except that the output calendar is not formatted. It is listed in
a "simple format" that can be used as input for more
sophisticated calendar-drawing programs. If n starts with
"+", then it is interpreted as a number of weeks.
- The -p option is very similar to the -s
option, except that the output contains additional information for use by
the Rem2PS program, which creates a PostScript calendar. For this
option, n cannot start with "+"; it must specify a number
of months. The format of the -p output is described in the
rem2ps(1) man page. If you immediately follow the p with the
letter a, then Remind displays reminders on the calendar on
the day they actually occur as well as on any preceding days
specified by the reminder's delta.
- If you use the -l option in conjunction with the -p option, then Remind outputs additional information for back-end programs such as rem2ps. This additional information lets the back-end programs correlate a reminder with the source file and line number that produced it.
- The -m option causes the -c or -p options to produce a calendar whose first column is Monday rather than Sunday. (This conforms to the international standard.)
- The -v option makes the output of Remind slightly more verbose. Currently, this causes Remind to echo a bad line in case of an error, and to print a security message if a script tests the $RunOff system variable.
- The -o option causes Remind to ignore all ONCE directives.
- The -t option causes Remind to trigger all non-expired reminders, regardless of the delta supplied for each reminder.
- If you supply a number n after the -t option, then Remind pretends that each non-expired reminder has a delta of n days and triggers reminders accordingly.
- The -h option ("hush...") suppresses certain warning and information messages. In particular, if no reminders are triggered, this mode produces no output.
- The -a option causes Remind not to
immediately trigger timed reminders that trigger on the current day. It
also causes Remind not to place timed reminders in a calendar. If
you supply two or more -a options, then Remind will
trigger timed reminders that are in the future, but will not trigger timed
reminders whose time has passed. (Regardless of how many -a options
you supply, Remind will not include timed reminders in the calendar
if at least one -a option is used.)
- The -q option causes Remind not to queue timed reminders for later execution.
- The -f option causes Remind to remain in the foreground when processing queued reminders, rather than forking off a background process to handle them.
- The -e option diverts error messages (normally sent to the standard error stream) to the standard output stream.
- The -d option enables certain debugging modes. The chars specify which modes to enable:
- Echo all input lines
- Trace all expression evaluation
- Display all trigger date computation
- Dump the variable table after execution of the reminder script
- Echo lines when displaying error messages
- Trace the reading of reminder files
- Normally, reminders are issued in the order in which they
are encountered in the reminder script. The -g option cause
Remind to sort reminders by date and time prior to issuing them.
The optional a and d characters specify the sort order
(ascending or descending) for the date, time and priority fields. See the
section "Sorting Reminders" for more information.
- Set the time format for the calendar and simple-calendar outputs. N can range from 0 to 2, with the default 0. A value of 0 causes times to be inserted in 12-hour (am/pm) format. 1 causes times to be inserted in 24-hour format, and 2 inhibits the automatic insertion of times in the calendar output.
- Sets the iteration limit for the SATISFY clause of a REM command. Defaults to 150.
- Instead of simply printing MSG-type reminders, this causes them to be passed to the specific cmd. You must use '%s' where you want the body to appear, and may need to enclose this option in quotes. Note that all shell characters in the body of the reminder are escaped with a backslash, and the entire body of the reminder is passed as a single argument. Note that this option overrides the -r option and the RUN OFF command.
As an example, suppose you have an X Window program called xmessage that pops up a window and displays its invocation arguments. You could use:
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. Because all shell and whitespace characters are escaped, the program you execute with the -k option must be prepared to handle the entire message as a single argument.
- -z[n] Runs Remind in the daemon mode. If n
- is supplied, it specifies how often (in minutes) Remind should wake up to check if the reminder script has been changed. N defaults to 1, and can range from 1 to 60. Note that the use of the -z option also enables the -f option.
If you supply the option -z0, Remind runs in a special mode called server mode. This is documented in the tkremind man page; see tkremind(1).
- Runs Remind with the uid and gid of the user specified by name. The option changes the uid and gid as described, and sets the environment variables HOME, SHELL and USER to the home directory, shell, and user name, respectively, of the specified user. LOGNAME is also set to the specified user name. This option is meant for use in shell scripts that mail reminders to all users. Note that as of Remind 3.00.17, using -u implies -r -- the RUN directive and shell() functions are disabled.
Non-root users can also use the -u option. However, in this case, it only changes the environment variables as described above. It does not change the effective uid or gid.
- Causes Remind to synthesize a tag for any reminder that lacks a TAG clause.
- Sets the value of the specified var to expr, and preserves var. Expr can be any valid Remind expression. See the section "Initializing Variables on the Command Line" for more details.
- Allows you to define a function on the command line.
REM 6 Jan MSG Dianne's birthdayto the baroque and obscure:
REM [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. Note that Remind processes line continuations before anything else. For example:
# This is a comment \ This line is part of the comment because of line continuation \ and so on. REM MSG This line is not ignored (no \ above)Remind is not case sensitive; you can generally use any mixture of upper- or lower-case for commands, parameters, invocation options, etc.
REM [ONCE] [date_spec] [ back] [ delta] [ repeat] [ PRIORITY prio] [ SKIP | BEFORE | AFTER] [ OMIT omit_list] [ OMITFUNC omit_function] [ AT time [tdelta] [ trepeat]] [ SCHED sched_function] [ WARN warn_function] [ UNTIL expiry_date | THROUGH last_date] [ SCANFROM scan_date | FROM start_date] [ DURATION duration] [ TAG tag] < MSG | MSF | RUN | CAL | SATISFY | SPECIAL special | PS | PSFILE> bodyThe 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, SPECIAL, 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. Note that you can omit the reminder type, in which case it defaults to MSG. So you can write:
6 January Dianne's Birthdayalthough this is not recommended. 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. A SPECIAL-type reminder is used to pass "out-of-band" information from Remind to a calendar-producing back-end. It should be followed by a word indicating the type of special data being passed. The type of a special reminder depends on the back-end. For the Rem2PS back-end, SPECIAL PostScript is equivalent to a PS-type reminder, and SPECIAL PSFile is equivalent to a PSFILE-type reminder. The body of a SPECIAL reminder is obviously dependent upon the back-end. 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:
- 1, 22, 31, 14, 3
- JANUARY, feb, March, ApR, may, Aug
- 1990, 1993, 2030, 95 (interpreted as 1995). The year can range from 1990 to 2075.
- Monday, tue, Wed, THU, Friday, saturday, sundAy
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 February4. day and month present. Examples:
REM 6 Jan MSG Every 6th of January REM Feb 29 MSG Every 29th of February5. Only year present. Example:
REM 1991 MSG Every day in 19916. year and day present. Examples:
REM 1 1990 MSG 1st of every month in 1990 REM 1992 23 MSG 23rd of every month in 19927. year and month present. Examples:
REM Feb 1991 MSG Every day in Feb 1991 REM 1992 September MSG Every day in Sept 19928. 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 Wednesday10. 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 month11. 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 February12. 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 July13. weekday and year present. Example:
REM Sat Sun 1991 MSG Every Saturday and Sunday in 199114. 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 199015. 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 that also satisfies the weekday constraint. It does this by picking the first date on or after the specified day that is listed in the list of weekdays. Thus, a reminder like:
REM Mon Tue 28 Oct 1990 MSG Hiwould 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. SHORT-HAND DATE SPECIFICATIONS In addition to spelling out the day, month and year separately, you can specify YYYY-MM-DD or YYYY/MM/DD. For example, the following statements are equivalent:
REM 5 June 2010 MSG Cool! REM 2010-06-05 MSG Cool!You can also specify a date and time as YYYY-MM-DD@HH:MM. These statements are equivalent:
REM 19 Dec 2010 AT 16:45 MSG Hi REM 2010-12-19@16:45 MSG HiThere's one subtlety with short-hand date specifications: The following statements are not equivalent:
REM 19 Dec 2010 AT 16:45 +60 MSG Hi REM 2010-12-19@16:45 +60 MSG HiIn the second statement, the "+60" is a delta that applies to the date rather than a tdelta that applies to the time. We recommend explicitly using the AT keyword with timed reminders. THE REMIND ALGORITHM Remind uses the following algorithm to compute a trigger date: Starting from the current date, it examines each day, one at a time, until it finds a date that satisfies the date specification, or proves to itself that no such date exists. (Actually, Remind merely behaves as if it used this algorithm; it would be much too slow in practice. Internally, Remind uses much faster techniques to calculate a trigger date.) See DETAILS ABOUT TRIGGER COMPUTATION for more information. 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 that 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 PaydayThis 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 and FROM The SCANFROM and FROM keywords are 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. FROM is available only from 03.01.00 and later. 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. (This default can be changed by adjusting the system variable $DefaultPrio. See the section "System Variables" for more information.) 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 1992-11-30 *1 +2 UNTIL 1992-12-04 MSG Jury dutyNote that the repeat of *1 is necessary; without it, the reminder would be issued only on 30 November (and the two days preceding.) As a special case, you can use the THROUGH keyword instead of *1 and UNTIL. The following two REM commands are equivalent:
REM 1992-11-30 *1 +2 UNTIL 1992-12-04 MSG Jury duty REM 1992-11-30 +2 THROUGH 1992-12-04 MSG Jury dutyTHE 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 that 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 that 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 EventThis 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 monthAgain, 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. COMPUTED LOCAL OMITS The OMITFUNC phrase of the REM command allows you to supply a function that determines whether or not a date is omitted. The function is passed a single parameter of type DATE, and must return a non-zero integer if the date is considered "omitted" and 0 otherwise. Here's an example:
FSET _third(x) (day(x) % 3) || \ (wkdaynum(x) == 0) || \ (wkdaynum(x) == 6) REM OMITFUNC _third AFTER MSG Working day divisible by 3In the example above, the reminder is triggered every Monday to Friday whose day-of-month number is divisible by three. Here's how it works:
- The OMITFUNC _third portion causes all days for which _third(x) returns non-zero to be considered "omitted". This causes all days whose day-of-month number is not a multiple of three to be omitted. Note that _third also returns non-zero if the weekday is Sunday or Saturday.
- The AFTER keyword causes the reminder to be moved after a block of omitted days.
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 ExampleThe 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 Example2The "+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 that were in effect at the end of the reminder script. These definitions may not necessarily be those that were in effect at the time the reminder was queued. THE SCHED AND WARN KEYWORDS The SCHED keyword allows more precise control over the triggering of timed reminders, and the WARN keyword allows precise control over the advance triggering of all types of reminders. However, discussion must be deferred until after expressions and user-defined functions are explained. See the subsection "Precise Scheduling" further on. TAG AND DURATION The TAG keyword lets you "tag" certain reminders. This facility is used by certain back-ends or systems built around Remind, such as TkRemind. These back-ends have specific rules about tags; see their documentation for details. The TAG keyword is followed by a tag consisting of up to 48 characters. You can have as many TAG clauses as you like in a given REM statement. If you supply the -y option to Remind, then any reminder that lacks a TAG will have one synthesized. The synthesized tag consists of the characters "__syn__" followed by the hexadecimal representation of the MD5 sum of the REM command line. This lets you give a more-or-less unique identifier to each distinct REM command. The DURATION keyword makes sense only for timed reminders; it specifies the duration of an event. Currently, this is not used, but it may be used in future by back-ends or scheduling systems built around Remind. For example, if you have a 90-minute meeting starting at 1:00pm, you could use:
REM 5 March 1999 AT 13:00 DURATION 1:30 MSG MeetingNote that duration is specified in hours and minutes.
- is replaced with "on weekday, day month, year"
For example, consider 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."
- is replaced with "in diff day's time" where diff is the actual number of days between the current date and the trigger date. ( OMITs have no effect.)
For example, consider: 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."
- is replaced with "on weekday"
Example: REM 18 Oct 1990 +4 MSG Meeting with Bob %c. 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."
- is replaced with "day", the day of the month.
- is replaced with "on dd-mm-yyyy"
- is replaced with "on mm-dd-yyyy"
- is replaced with "on weekday, day month"
- is replaced with "on dd-mm"
- is replaced with "on mm-dd"
- is replaced with "on weekday, month day-th, year" This form appends the characters "st", "nd", "rd" or "th" to the day of the month, as appropriate.
- is replaced with "on weekday, month day-th"
- is replaced with "on yyyy-mm-dd"
- is replaced with "month", the name of the month.
- is replaced with the number (1 to 12) of the month.
- is replaced with " (today)" if and only if the current system date is the same as the date being used by Remind as the current date. Recall that you can specify a date for Remind to use on the command line. This substitution is not generally useful in a REM command, but is useful in a BANNER command. (See "The BANNER Command.")
- is replaced with "s" if the diff between the current date and the trigger date is not 1. You can use this to construct reminders like:
REM 1 Jan +4 MSG %x day%p to go before New Year!
- is replaced with "'s" if the diff between the trigger date and the current date is 1. Otherwise, it is replaced with "s'" This can be used as follows:
REM 1 Jan +4 MSG New Year in %x day%q time!
- is replaced with the day of the month (01 to 31) padded with a leading zero if needed to pad to two digits.
- is replaced with "st", "nd", "rd" or "th" depending on the day of the month.
- is replaced with the number of the month (01 to 12) padded to two digits with a leading zero.
- is replaced with "on weekday, day-th month, year" This is similar to %a except that "st", "nd", "rd" or "th" is added to the day as appropriate.
- is replaced with "on weekday, day-th month"
- is replaced with "weekday", the name of the day of the week.
- is replaced with the diff between the current date and the trigger date. The diff is defined as the actual number of days between these two dates; OMITs are not counted. (Strict date subtraction is performed.)
- is replaced with "year", the year of the trigger date.
- is replaced with "yy", the last two digits of the year.
- (percent-underscore) is replaced with a newline. You can use this to achieve multi-line reminders.
- is replaced with "now", "m minutes from now", " m minutes ago", " h hours from now", " h hours ago", "h hours and m minutes from now" or " h hours and m minutes ago", as appropriate for a timed reminder. Note that unless you specify the -a option, timed reminders will be triggered like normal reminders, and thus a timed reminder that occurred earlier in the day may be triggered. This causes the need for the "...ago" forms.
- is replaced with "at hh:mmam" or "..pm" depending on the AT time of the reminder.
- is replaced with "at hh:mm" in 24-hour format.
- is replaced with "mm" where mm is the number of minutes between "now" and the time specified by AT. If the AT time is earlier than the current time, then the result is negative.
- is replaced with "ma" where ma is the absolute value of the number produced by %4.
- is replaced with "ago" or "from now", depending on the relationship between the AT time and the current time.
- is replaced with the number of hours between the AT time and the current time. It is always non-negative.
- is replaced with the number of minutes between the AT time and the current time, after the hours ( %7) have been subtracted out. This is a number ranging from 0 to 59.
- is replaced with "s" if the value produced by %8 is not 1.
- is replaced with "s" if the value produced by %7 is not 1.
- is replaced with "is" if the current time is before the AT time, or "was" if it is after.
- is similar to %2 but displays the current time.
- is similar to %3 but displays the current time.
- (percent-doublequote - ") is removed. This sequence is not used by the substitution filter, but is used to tell Remind which text to include in a calendar entry when the -c, -s or -p option is chosen. See "Calendar Mode"
- Remind normally prints a blank line after each reminder; if the last character of the body is "%", the blank line will not be printed.
- Substitutions a, b, c, e, f, g, h, i, j, k, l, u and v all are replaced with "today" if the current date equals the trigger date, or "tomorrow" if the trigger date is one day after the current date. Thus, they are not the same as substitutions built up from the simpler %w, %y, etc. sequences.
- Any of the substitutions dealing with time (0 through 9 and '!') produce undefined results if used in a reminder that does not have an AT keyword. Also, if a reminder has a delta and may be triggered on several days, the time substitutions ignore the date. Thus, the %1 substitution may report that a meeting is in 15 minutes, for example, even though it may only be in 2 days time, because a delta has triggered the reminder. It is recommended that you use the time substitutions only in timed reminders with no delta that are designed to be queued for timed activation.
- Capital letters can be used in the substitution sequence, in which case the first character of the substituted string is capitalized (if it is normally a lower-case letter.)
- All other characters following a "%" sign are simply copied. In particular, to get a "%" sign out, use "%%" in the body. To start the body of a reminder with a space, use "% ", since Remind normally scans for the first non-space character after a MSG, CAL or RUN token.
OMIT day month [year] or: OMIT day1 month1 year1 THROUGH day2 month2 year2The OMIT command is used to "globally" omit certain days (usually holidays). These globally-omitted days are skipped by the "-" and "+" forms of back and delta. Some examples:
OMIT 1 Jan OMIT 7 Sep 1992The first example specifies a holiday that occurs on the same date each year - New Year's Day. The second example specifies a holiday that 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.) As with the REM command, you can use shorthand specifiers for dates; the following are equivalent:
OMIT 7 Sep 1992 OMIT 1992-09-07For convenience, you can use a delta and MSG or RUN keyword in the OMIT command. The following sequences are 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 THROUGH keyword lets you conveniently OMIT a range of days. The starting and ending points must be fully-specified (ie, they must include day, month and year.). For example, the following sequences are equivalent:
OMIT 3 Jan 2011 OMIT 4 Jan 2011 OMIT 5 Jan 2011 and OMIT 3 Jan 2011 THROUGH 5 Jan 2011You can make a THROUGH OMIT do double-duty as a REM command:
OMIT 6 Sep 2010 THROUGH 10 Sep 2010 MSG Vacation
OMIT DUMPThe OMIT DUMP command prints the current global omits to standard output. THE BEFORE, AFTER AND SKIP KEYWORDS Normally, days that are omitted, whether by a global OMIT command or the local OMIT or OMITFUNC keywords 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:
- This keyword moves the reminder to before any omitted days. Thus, in the above example, use of BEFORE would cause the meeting reminder to be triggered on Tuesday, 10 November 1992.
- This keyword moves the reminder to after any omitted days. In the above example, the meeting reminder would be triggered on Thursday, 12 November 1992.
- This keyword causes the reminder to be skipped completely on any omitted days. Thus, in the above example, the reminder would not be triggered on 11 November 1992. However, it would be triggered as usual on the following Wednesday, 18 November 1992.
REM 1 OMIT Sat Sun AFTER RUN do_backupLet'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.
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 specify a directory as the argument to INCLUDE, then Remind will process all files in that directory that match the shell patterm "*.rem". The files are processed in sorted order; the sort order matches that used by the shell when it expands "*.rem".
RUN OFF # Disable RUN INCLUDE .reminders.in RUN ON # Re-enable RUNIn addition, Remind contains a few other security features. It will not read a file that is group- or world-writable. It will not run set-uid. If it reads a file you don't own, it will disable RUN and the shell() function. And if it is run as root, it will only read files owned by root.
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:
BANNER formatThe 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:
- This command saves the current global OMITs on an internal stack.
- This command clears all of the global OMITs, starting you off with a "clean slate."
- This command restores the global OMITs that were saved by the most recent PUSH-OMIT-CONTEXT.
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
- The INT data type consists of the integers representable in one machine word. The INT data type corresponds to the C "int" type.
- The STRING data type consists of strings of characters. It is somewhat comparable to a C character array, but more closely resembles the string type in BASIC.
- The TIME data type consists of times of the day. The TIME data type is internally stored as an integer representing the number of minutes since midnight.
- The DATE data type consists of dates (later than 1 January 1990.) Internally, DATE objects are stored as the number of days since 1 January 1990.
- The DATETIME data type consists of a date and time together. Internally, DATETIME objects are stored as the number of minutes since midnight, 1 January 1990. You can think of a DATETIME object as being the combination of DATE and TIME parts.
- INT constants
- 12, 36, -10, 0, 1209
- STRING constants
- "Hello there", "This is a test", "\n\gosd\w", ""
Note that the empty string is represented by "", and that backslashes in a string are not interpreted specially, as in they are in C.
- TIME constants
- 12:33, 0:01, 14:15, 16:42, 12.16, 13.00, 1.11
Note that TIME constants are written in 24-hour format. Either the period or colon can be used to separate the minutes from the hours. However, Remind will consistently output times using only one separator character. (The output separator character is chosen at compile-time.)
- DATE constants
- DATE constants are expressed as 'yyyy/mm/dd' or 'yyyy-mm-dd', and the single quotes must be supplied. This distinguishes date constants from division or subtraction of integers. Examples:
´1993/02/22', '1992-12-25', '1999/01/01' Note that DATE values 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.
- DATETIME constants
- DATETIME constants are expressed similarly to DATE constants with the addition of an "@HH:MM" part. For example:
´2008-04-05@23:11', '1999/02/03@14:06', '2001-04-07@08:30' DATETIME values are printed without the quotes. Notes about date and time separator characters for DATE and TIME constants apply also to DATETIME constants.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
- Logical negation. Can be applied to an INT type. If the operand is non-zero, returns zero. Otherwise, returns 1.
- Unary minus. Can be applied to an INT. Returns the negative of the operand.
- Multiplication. Returns the product of two INTs.
- Integer division. Returns the quotient of two INTs, discarding the remainder.
- Modulus. Returns the remainder upon dividing one INT by another.
- Has several uses. These are:
INT + INT - returns the sum of two INTs. 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. INT + DATETIME or DATETIME + INT - returns a DATETIME obtained by adding INT minutes to the original DATETIME. STRING + STRING - returns a STRING that 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.
- Has several uses. These are:
INT - INT - returns the difference of two INTs. 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. DATETIME - DATETIME - returns (as an INT) the difference in minutes between two DATETIMEs. DATE - INT - returns a DATE that is INT days earlier than the original DATE. TIME - INT - returns a TIME that is INT minutes earlier than the original TIME. DATETIME - INT - returns a DATETIME that is INT minutes earlier than the original DATETIME.
- <, <=, >, and >=
- These are the comparison operators. They can take operands of any type, but both operands must be of the same type. The comparison operators return 1 if the comparison is true, or 0 if it is false. Note that string comparison is done following the lexical ordering of characters on your system, and that upper and lower case are distinct for these operators.
- ==, !=
- == tests for equality, returning 1 if its operands are equal, and 0 if they are not. != tests for inequality.
If the operands are not of the same type, == returns 0 and != returns 1. Again, string comparisons are case-sensitive.
- This is the logical AND operator. Both of its operands must be of type INT. It returns 1 if both operands are non-zero, and 0 otherwise.
- This is the logical OR operator. Both of its operands must be of type INT. It returns 1 if either operand is non-zero, and 0 otherwise.
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 dateSYSTEM VARIABLES In addition to the regular user variables, Remind has several "system variables" that 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.
- If 1 (the default), then Remind uses C library functions to calculate the number of minutes between local and Universal Time Coordinated. This affects astronomical calculations ( sunrise() for example.) If 0, then you must supply the number of minutes between local and Universal Time Coordinated in the $MinsFromUTC system variable.
- $CalMode (read-only)
- If non-zero, then the -c option was supplied on the command line.
- $Daemon (read-only)
- If the daemon mode -z was invoked, contains the number of minutes between wakeups. If not running in daemon mode, contains 0.
- This variable can be set only to "/" or "-". It holds the character used to separate portions of a date when Remind prints a DATE or DATETIME value.
- The default priority assigned to reminders without a PRIORITY clause. You can set this as required to adjust the priorities of blocks of reminders without having to type priorities for individual reminders. At startup, $DefaultPrio is set to 5000; it can range from 0 to 9999.
- $DontFork (read-only)
- If non-zero, then the -c option was supplied on the command line.
- $DontTrigAts (read-only)
- The number of times that the -a option was supplied on the command line.
- $DontQueue (read-only)
- If non-zero, then the -q option was supplied on the command line.
- $EndSent (STRING type)
- Contains a list of characters that end a sentence. The MSF keyword inserts two spaces after these characters. Initially, $EndSent is set to ".!?" (period, exclamation mark, and question mark.)
- $EndSentIg (STRING type)
- Contains a list of characters that should be ignored when MSF decides whether or not to place two spaces after a sentence. Initially, is set to "'>)]}"+CHAR(34) (single-quote, greater-than, right parenthesis, right bracket, right brace, and double-quote.)
For example, the default values work as follows:
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 number of spaces by which to indent the first line of a MSF-type reminder. The default is 0.
- The standard Unix library functions may have difficulty dealing with dates later than 2037. If this variable is set to 1, then the UTC calculations "fold back" years later than 2037 before using the Unix library functions. For example, to find out whether or not daylight saving time is in effect in June, 2077, the year is "folded back" to 2010, because both years begin on a Monday, and both are non-leapyears. The rules for daylight saving time are thus presumed to be identical for both years, and the Unix library functions can handle 2010. By default, this variable is 0. Set it to 1 if the sun or UTC functions misbehave for years greater than 2037.
- The maximum width of each line of text for formatting MSF-type reminders. The default is 72. If an MSF-type reminder contains a word too long to fit in this width, it will not be truncated - the width limit will be ignored.
- $HushMode (read-only)
- If non-zero, then the -h option was supplied on the command line.
- $IgnoreOnce (read-only)
- If non-zero, then the -o option was supplied on the command line, or a date different from today's true date was supplied. If non-zero, then ONCE directives will be ignored.
- $InfDelta (read-only)
- If non-zero, then the -t option was supplied on the command line.
- $LatDeg, $LatMin, $LatSec
- These specify the latitude of your location. $LatDeg can range from -90 to 90, and the others from -59 to 59. Northern latitudes are positive; southern ones are negative. For southern latitudes, all three components should be negative.
- $Location (STRING type)
- This is a string specifying the name of your location. It is usually the name of your town or city. It can be set to whatever you like, but good style indicates that it should be kept consistent with the latitude and longitude system variables.
- $LongDeg, $LongMin, $LongSec
- These specify the longitude of your location. $LongDeg can range from -180 to 180. Western longitudes are positive; eastern ones are negative. Note that all three components should have the same sign: All positive for Western longitudes and all negative for Eastern longitudes.
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.
- The maximum number of iterations for the SATISFY clause (described later.) Must be at least 10.
- The number of minutes between Universal Time Coordinated and local time. If $CalcUTC is non-zero, this is calculated upon startup of Remind. Otherwise, you must set it explicitly. If $CalcUTC is zero, then $MinsFromUTC is used in the astronomical calculations. You must adjust it for daylight saving time yourself. Also, if you want to initialize $MinsFromUTC using the -i command-line option, you must also set $CalcUTC to 0 with the -i option.
- $NextMode (read-only)
- If non-zero, then the -n option was supplied on the command line.
- $NumQueued (read-only)
- Contains the number of reminders queued so far for background timed triggering.
- $NumTrig (read-only)
- Contains the number of reminders triggered for the current date. One use for this variable is as follows: Suppose you wish to shade in the box of a PostScript calendar whenever a holiday is triggered. You could save the value of $NumTrig in a regular variable prior to executing a block of holiday reminders. If the value of $NumTrig after the holiday block is greater than the saved value, then at least one holiday was triggered, and you can execute the command to shade in the calendar box. (See the section "Calendar Mode".)
Note that $NumTrig is affected only by REM commands; triggers in IFTRIG commands do not affect it.
- $PrefixLineNo (read-only)
- If non-zero, then the -l option was supplied on the command line.
- $PSCal (read-only)
- If non-zero, then the -p option was supplied on the command line.
- $RunOff (read-only)
- If non-zero, the RUN directives are disabled.
- $SimpleCal (read-only)
- Set to a non-zero value if either of the -p or -s command-line options was supplied.
- $SortByDate (read-only)
- Set to 0 if no -g option is used, 1 if sorting by date in ascending order, or 2 if sorting by date in descending order.
- $SortByPrio (read-only)
- Set to 0 if no -g option is used, 1 if sorting by priority in ascending order, or 2 if sorting by priority in descending order.
- $SortByTime (read-only)
- Set to 0 if no -g option is used, 1 if sorting by time in ascending order, or 2 if sorting by time in descending order.
- The number of spaces by which all lines (except the first) of an MSF-type reminder should be indented. The default is 0.
- $T (read-only, DATE type)
- Exactly equivalent to trigdate(). (See BUILT-IN FUNCTIONS.)
- $Td (read-only)
- Equivalent to day(trigdate()).
- $Tm (read-only)
- Equivalent to monnum(trigdate()).
- $Tw (read-only)
- Equivalent to wkdaynum(trigdate()).
- $Ty (read-only)
- Equivalent to year(trigdate()).
- This variable can be set only to ":" or ".". It holds the character used to separate portions of a time when Remind prints a TIME or DATETIME value.
- $UntimedFirst (read-only)
- Set to 1 if the -g option is used with a fourth sort character of "d"; set to 0 otherwise.
- $U (read-only, DATE type)
- Exactly equivalent to today(). (See BUILT-IN FUNCTIONS.)
- $Ud (read-only)
- Equivalent to day(today()).
- $Um (read-only)
- Equivalent to monnum(today()).
- $Uw (read-only)
- Equivalent to wkdaynum(today()).
- $Uy (read-only)
- Equivalent to year(today()).
- Returns the absolute value of num.
- access(s_file, si_mode)
- Tests the access permissions for the file file. Mode can be a string, containing a mix of the characters "rwx" for read, write and execute permission testing. Alternatively, mode can be a number as described in the UNIX access(2) system call. The function returns 0 if the file can be accessed with the specified mode, and -1 otherwise.
- Returns the number of arguments expected by the user-defined function fname, or -1 if no such user-defined function exists. Note that this function examines only user-defined functions, not built-in functions. Its main use is to determine whether or not a particular user-defined function has been defined previously. The args() function is available only in versions of Remind from 03.00.04 and up.
- Returns an INT that is the ASCII code of the first character in string. As a special case, asc("") returns 0.
- Returns the "base year" that was compiled into Remind (normally 1990.) All dates are stored internally as the number of days since 1 January of baseyr().
- char(i_i1 [,i_i2...])
- This function can take any number of INT arguments. It returns a STRING consisting of the characters specified by the arguments. Note that none of the arguments can be 0, unless there is only one argument. As a special case, char(0) returns "".
Note that because Remind does not support escaping of characters in strings, the only way to get a double-quote in a string is to use char(34).
- choose(i_index, x_arg1 [,x_arg2...])
- Choose must take at least two arguments, the first of which is an INT. If index is n, then the nth subsequent argument is returned. If index is less than 1, then arg1 is returned. If index is greater than the number of subsequent arguments, then the last argument is returned. Examples:
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
Note that all arguments to choose() are always evaluated.
- coerce(s_type, x_arg)
- This function converts arg to the specified type, if such conversion is possible. Type must be one of "INT", "STRING", "DATE", "TIME" or "DATETIME" (case-insensitive). The conversion rules are as follows:
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 DATETIME is converted to a date by dropping the time component. 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 DATETIME is converted to a time by dropping the date component. A DATE arg cannot be converted to a time. If type is "DATETIME", then an INT arg is converted by interpreting it as the number of minutes since midnight, 1 January baseyr(). A STRING is converted by attempting to read it as if it were a printed datetime. Other types cannot be converted to a datetime. If type is "INT", then DATE, TIME and DATETIME arguments are converted using the reverse of procedures described above. A STRING arg is converted by parsing it as an integer.
- Returns the current date and time as a DATETIME object. This may be the actual date and time, or may be the date and time supplied on the command line.
- date(i_y, i_m, i_d)
- The date() function returns a DATE object with the year, month and day components specified by y, m and d.
- Returns a DATE object representing the date portion of datetime.
- The datetime() function can take anywhere from two to five arguments. It always returns a DATETIME generated from its arguments.
If you supply two arguments, the first must be a DATE and the second a TIME. If you supply three arguments, the first must be a DATE and the second and third must be INTs. The second and third arguments are interpreted as hours and minutes and converted to a TIME. If you supply four arguments, the first three must be INTs, interpreted as the year, month and day. The fourth argument must be a TIME. Finally, if you supply five arguments, they must all be INTs and are interpreted as year, month, day, hour and minute.
- Returns the time of "civil dawn" on the specified date. If date is omitted, defaults to today(). If a datetime object is supplied, only the date component is used.
- This function takes a DATE or DATETIME as an argument, and returns an INT that is the day-of-month component of date.
- daysinmon(i_m, i_y)
- Returns the number of days in month m (1-12) of the year y.
- Returns 1 if the variable named by var is defined, or 0 if it is not.
Note that defined() takes a STRING argument; thus, to check if variable X is defined, use:
defined(X)The second example will attempt to evaluate X, and will return an error if it is undefined or not of type STRING.
- dosubst(s_str [,d_date [,t_time]]) or dosubst(s_str [,q_datetime])
- Returns a STRING that is the result of passing str through the substitution filter described earlier. The parameters date and time (or datetime) establish the effective trigger date and time used by the substitution filter. If date and time are omitted, they default to today() and now().
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 that 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.
- Returns the time of "civil twilight" on the specified date. If date is omitted, defaults to today().
- If arg is an INT, then returns the date of Easter Sunday for the specified year. If arg is a DATE or DATETIME, then returns the date of the next Easter Sunday on or after arg. (The time component of a datetime is ignored.)
- evaltrig(s_trigger [,dq_start])
- Evaluates trigger as if it were a REM or IFTRIG trigger specification and returns the trigger date as a DATE (or as a DATETIME if there is an AT clause.) Returns a negative INT if no trigger could be computed.
Normally, evaltrig finds a trigger date on or after today. If you supply the start argument, then it scans starting from there. For example, the expression:
evaltrig("Mon 1", '2008-10-07')returns '2008-11-03', since that is the first date on or after 7 October 2008 that satisfies "Mon 1". If you want to see how many days it is from the first Monday in October, 2008 to the first Monday in November, 2008, use:
evaltrig("Mon 1", '2008-11-01') - evaltrig("Mon 1", '2008-10-01')and the answer is 28. The trigger argument to evaltrig can have all the usual trigger clauses ( OMIT, AT, SKIP, etc.) but cannot have a SATISFY, MSG, etc. reminder-type clause.
- Returns the modification date of filename. If filename does not exist, or its modification date is before the year baseyr(), then 1 January of baseyr() is returned.
- Returns the modification date and time of filename. If filename does not exist, or its modification date is before the year baseyr(), then midnight, 1 January of baseyr() is returned.
- Returns the directory that contains the current file being processed. It may be a relative or absolute pathname, but is guaranteed to be correct for use in an INCLUDE command as follows:
This includes the file "stuff" in the same directory as the current file being processed.
- Returns (as a STRING) the name of the current file being processed by Remind. Inside included files, returns the name of the included file.
- Similar to the getenv(2) system call. Returns a string representing the value of the specified environment variable. Returns "" if the environment variable is not defined. Note that the names of environment variables are generally case-sensitive; thus, getenv("HOME") is not the same as getenv("home").
- hebdate(i_day, s_hebmon [,idq_yrstart [,i_jahr [,i_aflag]]])
- Support for Hebrew dates - see the section "The Hebrew Calendar"
- Support for Hebrew dates - see the section "The Hebrew Calendar"
- Support for Hebrew dates - see the section "The Hebrew Calendar"
- Support for Hebrew dates - see the section "The Hebrew Calendar"
- Returns the hour component of time.
- iif(si_test1, x_arg1, [si_test2, x_arg2,...], x_default)
- If test1 is not zero or the null string, returns arg1. Otherwise, if test2 is not zero or the null string, returns arg2, and so on. If all of the test arguments are false, returns default. Note that all arguments are always evaluated. This function accepts an odd number of arguments - note that prior to version 03.00.05 of Remind, it accepted 3 arguments only. The 3-argument version of iif() is compatible with previous versions of Remind.
- index(s_search, s_target [,i_start)
- Returns an INT that is the location of target in the string search. The first character of a string is numbered 1. If target does not exist in search, then 0 is returned.
The optional parameter start specifies the position in search at which to start looking for target.
- isdst([d_date [,t_time]]) or isdst(q_datetime)
- Returns a positive number if daylight saving time is in effect on the specified date and time. Date defaults to today() and time defaults to midnight.
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.
- Returns 1 if arg is a leap year, and 0 otherwise. Arg can be an INT, DATE or DATETIME object. If a DATE or DATETIME is supplied, then the year component is used in the test.
- Returns 1 if date is omitted, given the current global OMIT context. Returns 0 otherwise. (If a datetime is supplied, only the date part is used.) Note that any local OMIT or OMITFUNC clauses are not taken into account by this function.
- Returns a STRING naming the language supported by Remind. (See "Foreign Language Support.") By default, Remind is compiled to support English messages, so this function returns "English". For other languages, this function will return the English name of the language (e.g. "German") Note that language() is not available in versions of Remind prior to 03.00.02.
- Returns a STRING with all upper-case characters in string converted to lower-case.
- max(x_arg1 [,x_arg2...)
- Can take any number of arguments, and returns the maximum. The arguments can be of any type, but must all be of the same type. They are compared as with the > operator.
- min(x_arg1 [,x_arg2...)
- Can take any number of arguments, and returns the minimum. The arguments can be of any type, but must all be of the same type. They are compared as with the < operator.
- minsfromutc([d_date [,t_time]]) or minsfromutc(q_datetime)
- Returns the number of minutes from Universal Time Coordinated (formerly GMT) to local time on the specified date and time. Date defaults to today() and time defaults to midnight. If local time is before UTC, the result is negative. Otherwise, the result is positive.
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.
- Returns the minute component of time.
- If arg is of DATE or DATETIME type, returns a string that names the month component of the date. If arg is an INT from 1 to 12, returns a string that names the month.
- Returns an INT from 1 to 12, representing the month component of date.
- moondate(i_phase [,d_date [,t_time]]) or moondate(i_phase, q_datetime)
- This function returns the date of the first occurrence of the phase phase of the moon on or after date and time. Phase can range from 0 to 3, with 0 signifying new moon, 1 first quarter, 2 full moon, and 3 third quarter. If date is omitted, it defaults to today(). If time is omitted, it defaults to midnight.
For example, the following returns the date of the next full moon:
SET fullmoon moondate(2)
- moontime(i_phase [,d_date [,t_time]]) or moontime(i_phase, q_datetime)
- This function returns the time of the first occurrence of the phase phase of the moon on or after date and time. Phase can range from 0 to 3, with 0 signifying new moon, 1 first quarter, 2 full moon, and 3 third quarter. If date is omitted, it defaults to today(). If time is omitted, it defaults to midnight. Moontime() is intended to be used in conjunction with moondate(). The moondate() and moontime() functions are accurate to within a couple of minutes of the times in "Old Farmer's Almanac" for Ottawa, Ontario.
For example, the following returns the date and time of the next full moon:
MSG Next full moon at [moontime(2)] on [moondate(2)]
- moondatetime(i_phase [,d_date [,t_time]]) or moondatetime(i_phase, q_datetime)
- This function is similar to moondate and moontime, but returns a DATETIME result.
- moonphase([d_date [,t_time]]) or moonphase(q_datetime)
- This function returns the phase of the moon on date and time, which default to today() and midnight, respectively. The returned value is an integer from 0 to 359, representing the phase of the moon in degrees. 0 is a new moon, 180 is a full moon, 90 is first-quarter, etc.
- nonomitted(dq_start, dq_end [,s_wkday...])
- This function returns the number of non-omitted days between start and end. If start is non-omitted, then it is counted. end is never counted.
Note that end must be greater than or equal to start or an error is reported. In addition to using the global OMIT context, you can supply additional arguments that are names of weekdays to be omitted. However, in a REM command, any local OMITFUNC clause is not taken into account by this function. For example, the following line sets a to 11 (assuming no global OMITs):
set a nonomitted('2007-08-01', '2007-08-16', "Sat", "Sun")because Thursday, 16 August 2007 is the 11th working day (not counting Saturday and Sunday) after Wednesday, 1 August 2007. nonomitted has various uses. For example, many schools run on a six-day cycle and the day number is not incremented on holidays. Suppose the school year starts with Day 1 on 4 September 2007. The following reminder will label day numbers in a calendar:
IF today() >= '2007-09-04' set daynum nonomitted('2007-09-04', today(), "Sat", "Sun") REM OMIT SAT SUN SKIP CAL Day [(daynum % 6) + 1] ENDIFObviously, the answer you get from nonomitted depends on the global OMIT context. If you use moveable OMITs, you may get inconsistent results. Here is a more complex use for nonomitted. My garbage collection follows two interleaved 14-day cycles: One Friday, garbage and paper recycling ("Black Box") are collected. The next Friday, garbage and plastic recycling ("Blue Box") are collected. If any of Monday-Friday is a holiday, collection is delayed until the Saturday. Here's a way to encode these rules:
fset _garbhol(x) wkdaynum(x) == 5 && nonomitted(x-4, x+1) < 5 REM 12 November 1999 *14 AFTER OMITFUNC _garbhol MSG Black Box REM 19 November 1999 *14 AFTER OMITFUNC _garbhol MSG Blue BoxHere's how it works: The _garbhol(x) user-defined function returns 1 if and only if (1) x is a Friday and (2) there is at least one OMITted day from the previous Monday up to and including the Friday. The first REM statement sets up the 14-day black-box cycle. The AFTER keyword makes it move collection to the Saturday if _garbhol returns 1. The second REM statement sets up the 14-day blue-box cycle with a similar adjustment made by AFTER in conjunction with _garbhol.
- Returns the current system time, as a TIME type. This may be the actual time, or a time supplied on the command line.
- Returns a string that is the ordinal number num. For example, ord(2) returns "2nd", and ord(213) returns "213th".
- Returns "UNIX". Remind used to run on OS/2 and MS-DOS, but does not any longer.
- plural(i_num [,s_str1 [,s_str2]])
- Can take from one to three arguments. If one argument is supplied, returns "s" if num is not 1, and "" if num is 1.
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.
- psmoon(i_phase [,i_size [,s_note [,i_notesize]]])
- [DEPRECATED] Returns a STRING consisting of PostScript code to draw a moon in the upper-left hand corner of the calendar box. Phase specifies the phase of the moon, and is 0 (new moon), 1 (first quarter), 2 (full moon) or 3 (third quarter). If size is specified, it controls the radius of the moon in PostScript units (1/72 inch.) If it is not specified or is negative, the size of the day-number font is used.
For example, the following four lines place moon symbols on the PostScript calendar:
REM [moondate(0)] PS [psmoon(0)] REM [moondate(1)] PS [psmoon(1)] REM [moondate(2)] PS [psmoon(2)] REM [moondate(3)] PS [psmoon(3)]If note is specified, the text is used to annotate the moon display. The font is the same font used for calendar entries. If notesize is given, it specifies the font size to use for the annotation, in PostScript units (1/72 inch.) If notesize is not given, it defaults to the size used for calendar entries. (If you annotate the display, be careful not to overwrite the day number -- Remind does not check for this.) For example, if you want the time of each new moon displayed, you could use this in your reminder script:
REM [moondate(0)] PS [psmoon(0, -1, moontime(0)+"")]Note how the time is coerced to a string by concatenating the null string.
- psshade(i_gray) or psshade(i_red, i_green, i_blue)
- [DEPRECATED] Returns a STRING that consists of PostScript commands to shade a calendar box. Num can range from 0 (completely black) to 100 (completely white.) If three arguments are given, they specify red, green and blue intensity from 0 to 100. Here's an example of how to use this:
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. Note that psmoon and psshade are deprecated; instead you should use the SPECIAL SHADE and SPECIAL MOON reminders as described in "Out-of-Band Reminders."
- Returns (as a DATETIME) the true date and time of day as provided by the operating system. This is in contrast to current(), which may return a time supplied on the command line.
- Returns the true time of day as provided by the operating system. This is in contrast to now(), which may return a time supplied on the command line.
- Returns the date as provided by the operating system. This is in contrast to Remind's concept of "today", which may be changed if it is running in calendar mode, or if a date has been supplied on the command line.
- Returns -1 if num is negative, 1 if num is positive, and 0 if num is zero.
- shell(s_cmd [,i_maxlen])
- Executes cmd as a system command, and returns the first 511 characters of output resulting from cmd. Any whitespace character in the output is converted to a space. Note that if RUN OFF has been executed, or the -r command-line option has been used, shell() will result in an error, and cmd will not be executed.
If maxlen is specified, then shell() returns the first maxlen characters of output (rather than the first 511). If maxlen is specified as a negative number, then all the output from cmd is returned.
- slide(d_start, i_amt [,s_wkday...])
- This function is the inverse of nonomitted. It adds amt days (which can be negative) to start, not counting omitted days. The optional wkday arguments are additional weekday names to omit.
Consider this example:
OMIT 14 May 2009 SET a slide('2009-05-13', 5, "Sat", "Sun")In this case, a is set to 2009-05-21. That's because we slide forward by 5 days, not including Thursday, May 14 or Saturday and Sunday, May 16 and 17. You can go backwards, too, so:
OMIT 14 May 2009 SET a slide('2009-05-21', -5, "Sat", "Sun")takes a back to 2009-05-13.
- Returns the length of str.
- substr(s_str, i_start [,i_end])
- Returns a STRING consisting of all characters in str from start up to and including end. Characters are numbered from 1. If end is not supplied, then it defaults to the length of str.
- Returns a TIME indicating the time of sunrise on the specified date (default today().) In high latitudes, there may be no sunrise on a particular day, in which case sunrise() returns the INT 0 if the sun never sets, or 1440 if it never rises.
- Returns a TIME indicating the time of sunset on the specified date (default today().) In high latitudes, there may be no sunset on a particular day, in which case sunset() returns the INT 0 if the sun never rises, or 1440 if it never sets.
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 4 minutes for latitudes lower than 60 degrees. The functions are available starting from version 03.00.07 of Remind.
- time(i_hr, i_min)
- Creates a TIME with the hour and minute components specified by hr and min.
- Returns a TIME object representing the time portion of datetime.
- Returns Remind's notion of "today." This may be the actual system date, or a date supplied on the command line, or the date of the calendar entry currently being computed.
- Returns the calculated trigger date of the last REM or IFTRIG command. If used in the body of a REM command, returns that command's trigger date. If the most recent REM command did not yield a computable trigger date, returns the integer 0.
- Similar to trigdate(), but returns a DATETIME if the most recent triggerable REM command had an AT clause. If there was no AT clause, returns a DATE. If no trigger could be computed, returns the integer 0.
- trigger(d_date [,t_time [,i_utcflag]]) or trigger(q_datetime [,i_utcflag])
- Returns a string suitable for use in a REM command or a SCANFROM or UNTIL clause, allowing you to calculate trigger dates in advance. Note that in earlier versions of Remind, trigger was required to convert a date into something the REM command could consume. However, in this version of Remind, you can omit it. Note that trigger() always returns its result in English, even for foreign-language versions of Remind. This is to avoid problems with certain C libraries that do not handle accented characters properly. Normally, the date and time are the local date and time; however, if utcflag is non-zero, the date and time are interpreted as UTC times, and are converted to local time. Examples:
trigger('1993/04/01') returns "1 April 1993",
trigger('1994/08/09', 12:33) returns "9 August 1994 AT 12:33", as does:
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.
- Returns the time of the last REM command with an AT clause. If the last REM did not have an AT clause, returns the integer 0.
- Returns 1 if the value returned by trigdate() is valid for the most recent REM command, or 0 otherwise. Sometimes REM commands cannot calculate a trigger date. For example, the following REM command can never be triggered:
REM Mon OMIT Mon SKIP MSG Impossible!
- Returns "STRING", "INT", "DATE", "TIME" or "DATETIME", depending on the type of arg.
- tzconvert(q_datetime, s_srczone [,s_dstzone])
- Converts datetime from the time zone named by srczone to the time zone named by dstzone. If dstzone is omitted, the default system time zone is used. The return value is a DATETIME. Time zone names are system-dependent; consult your operating system for legal values. Here is an example:
tzconvert('2007-07-08@01:14', "Canada/Eastern", "Canada/Pacific") returns 2007-07-07@22:14
- Returns a STRING with all lower-case characters in string converted to upper-case.
- value(s_varname [,x_default])
- Returns the value of the specified variable. For example, value("X"+"Y") returns the value of variable XY, if it is defined. If XY is not defined, an error results.
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.
- Returns a string specifying the version of Remind. For version 03.00.04, returns "03.00.04". It is guaranteed that as new versions of Remind are released, the value returned by version() will strictly increase, according to the rules for string ordering.
- weekno([dq_date, [i_wkstart, [i_daystart]]])
- Returns the week number of the year. If no arguments are supplied, returns the ISO 8601 week number for today(). If one argument date is supplied, then returns the ISO 8601 week number for that date. If two arguments are supplied, then wkstart must range from 0 to 6, and represents the first day of the week (with 0 being Sunday and 6 being Saturday.). If wkstart is not supplied, then it defaults to 1. If the third argument daystart is supplied, then it specifies when Week 1 starts. If daystart is less than or equal to 7, then Week 1 starts on the first wkstart on or after January daystart. Otherwise, Week 1 starts on the first wkstart on or after December daystart. If omitted, daystart defaults to 29 (following the ISO 8601 definition.)
- If arg is a DATE or DATETIME, returns a string representing the day of the week of the date. If arg is an INT from 0 to 6, returns the corresponding weekday ("Sunday" to "Saturday").
- Returns a number from 0 to 6 representing the day-of-week of the specified date. (0 represents Sunday, and 6 represents Saturday.)
- Returns a INT that is the year component of date.
REM [mydate] MSG fooThis evaluates the expression "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:
- If Remind is expecting an expression, as in the SET command, or the IF command, you should not include square brackets. For example, use:
SET a 4+5and not:
SET a [4+5]
- You cannot use expression pasting for the first token on a line. For example, the following will not work:
["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!  ["Nov " + 1993] AT [12:05+60] MSG BOO!
- You cannot use expression-pasting to determine the type (MSG, CAL, etc.) of a REM command. You can paste expressions before and after the MSG, etc keywords, but cannot do something like this:
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 foowill fail if mydelta happens to be negative.
IF expr t-command t-command... ELSE f-command f-command... ENDIFNote 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..." ENDIFTHE 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 ENDIFNote 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.
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:
- If you access a variable in expr that is not in the list of arguments, the "global" value (if any) is used.
- Function and parameter names are significant only to 12 characters.
- The value() function always accesses the "global" value of a variable, even if it has the same name as an argument. For example:
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.
- User-defined functions may call other functions, including other user-defined functions. However, recursive calls are not allowed.
- User-defined functions are not syntax-checked when they are defined; parsing occurs only when they are called.
- If a user-defined function has the same name as a built-in function, it is ignored and the built-in function is used. To prevent conflicts with future versions of Remind (which may define more built-in functions), you may wish to name all user-defined functions beginning with an underscore.
- If n is positive, then the reminder is triggered exactly n days before its trigger date.
- If n is negative, then it is triggered n days before its trigger date, not counting OMITted days.
FSET _wfun(x) choose(x, 5, 3, 1, 0) REM 4 July WARN _wfun MSG American Independence Day is %b.NOTES
- If an error occurs during the evaluation of warn_function, then Remind stops calling it and simply issues the reminder on its trigger date.
- If the absolute-values of the return values of warn_function are not monotonically decreasing, Remind stops calling it and issues the reminder on its trigger date.
- Warn_function should (as a matter of good style) return 0 as the final value in its sequence of return values. However, a reminder will always be triggered on its trigger date, regardless of what warn_function does.
FSET _sfun(x) choose(x, -60, 30, 15, 10, 3, 1, 1, 1, 1, 0) REM AT 13:00 SCHED _sfun MSG fooThe 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
- If an error occurs during the evaluation of sched_func, then Remind reverts to using the AT time and the delta and repeat values, and never calls sched_func again.
- If processing sched_func yields a time earlier than the current system time, it is repeatedly called with increasing argument until it yields a value greater than or equal to the current time. However, if the sequence of values calculated during the repetition is not strictly increasing, then Remind reverts to the default behaviour and never calls sched_func again.
- It is quite possible using sched_func to keep triggering a reminder even after the AT-time. However, it is not possible to reschedule a reminder past midnight - no crossing of date boundaries is allowed. Also, it is quite possible to not trigger a reminder on the AT time when you use a scheduling function. However, if your scheduling function is terminated (for reasons 1 and 2) before the AT time of the reminder, it will be triggered at the AT time, because normal processing takes over.
- Your scheduling functions should (as a matter of good style) return 0 when no more scheduling is required. See the example.
- All scheduling functions are evaluated after the entire Remind script has been read in. So whatever function definitions are in effect at the end of the script are used.
# 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 [trigdate()] +2 MSG \ Friday the 13th is %b. ENDIFLet'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 to set up the next reminder. We could also have written:
REM Fri SATISFY day(trigdate()) == 13but 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 [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 hellothe 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 bodyNote 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!!!Note that SATISFY and OMITFUNC can often be used to solve the same problem, though in different ways. Sometimes a SATISFY is cleaner and sometimes an OMITFUNC; experiment and use whichever seems clearer.
DEBUG +x set a very_complex_expression(many_args) DEBUG -xTHE 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 ENDIFTHE 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.
remind -p .reminders | rem2psYou 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 1993then 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 %"Dianne's birthday%" is %bIn the normal mode, Remind would print "Dianne's birthday is today" on 6 January. However, in the calendar mode, only the text "Dianne'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 ENDIFThe 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 that 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 width of the black grid lines making up the calendar.
- The border between the center of the grid lines and the space used to print calendar entries. This border is normally blank space.
- BoxWidth and BoxHeight
- The width and height of the calendar box, from center-to-center of the black gridlines.
- The height from the center of the bottom black gridline to the top of the regular calendar entry area. The space from here to the top of the box is used only to draw the day number.
- /DayFont, /EntryFont, /SmallFont, /TitleFont and /HeadFont
- The fonts used to draw the day numbers, the calendar entries, the small calendars, the calendar title (month, year) and the day-of-the-week headings, respectively.
- DaySize, EntrySize, TitleSize and HeadSize
- The sizes of the above fonts. (The size of the small calendar font is not defined here.) For example, if you wanted to print the Hebrew date next to the regular day number in the calendar, use:
REM PS Border BoxHeight Border sub DaySize sub moveto \ /DayFont findfont DaySize scalefont setfont \ ([hebday(today())] [hebmon(today())]) show
Note how /DayFont and DaySize are used.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.
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.
#!P: Cannot purge SATISFY-type reminders #!P: The next IF evaluated false... #!P: REM statements in IF block not checked for purging. #!P: The previous IF evaluated true. #!P: REM statements in ELSE block not checked for purging #!P: The next IFTRIG did not trigger. #!P: REM statements in IFTRIG block not checked for purging. #!P: Next line has expired, but contains expression... please verify #!P: Next line may have expired, but contains non-constant expression #!P! Could not parse next line: Some-Error-Message-HereRemind always annotates .purged files with lines beginning with "#!P". If such lines are encountered in the original file, they are not copied to the .purged file.
# 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 futureYou 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
- If msgprefix() is defined, it is evaluated with the priority of the reminder as its argument. The result is printed. It is not passed through the substitution filter.
- The body of the reminder is printed.
- If msgsuffix() is defined, it is evaluated with the priority of the reminder as its argument. The result is printed. It is not passed through the substitution filter.
fset msgprefix(x) iif(x==0, "URGENT: ", \ x==6000, "(not important) ", "")In Calendar Mode (with the -c, -s or -p options), an analogous pair of functions named calprefix() and calsuffix() can be defined. They work with all reminders that 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
- Returns the day of the Hebrew month corresponding to the date parameter. For example, 12 April 1993 corresponds to 21 Nisan 5753. Thus, hebday('1993/04/12') returns 21.
- Returns the name of the Hebrew month corresponding to date. For example, hebmon('1993/04/12') returns "Nisan".
- Returns the Hebrew year corresponding to date. For example, hebyear('1993/04/12') returns 5753.
- hebdate(i_day, s_hebmon [,id_yrstart [,i_jahr [,i_aflag]]])
- The hebdate() function is the most complex of the Hebrew support functions. It can take from 2 to 5 arguments. It returns a DATE corresponding to the Hebrew date.
The day parameter can range from 1 to 30, and specifies the day of the Hebrew month. The hebmon parameter is a string that must name one of the Hebrew months specified above. Note that the month must be spelled out in full, and use the English transliteration shown previously. You can also specify "Adar A" and "Adar B." Month names are not case-sensitive. 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: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 for more information. In addition, because some months change length, it is not obvious which day the anniversary of a death is. The following rules are used:
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 that 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:
- 30 Heshvan is converted to 1 Kislev in years when Heshvan is chaser
- 30 Kislev is converted to 1 Tevet in years when Kislev is chaser
- 30 Adar A is converted to 1 Nisan in non-leapyears
- Other dates in Adar A are moved to the corresponding day in Adar in non-leapyears
- 30 Kislev and 30 Heshvan are converted to 29 Kislev and 29 Heshvan, respectively, if the month is chaser
- 30 Adar A is converted to 30 Shvat in non-leapyears
- Other dates in Adar A are moved to the corresponding day in Adar in non-leapyears
- If aflag is 0, then the date is triggered in Adar B. This is the default.
- If aflag is 1, then the date is triggered in Adar A. This may be appropriate for jahrzeits in the Ashkenazi tradition; consult a rabbi.
- If aflag is 2, then the date is triggered in both Adar A and Adar B of a leap year. Some Ashkenazim perform jahrzeit in both Adar A and Adar B.
- If the death occurred on 30 Heshvan, and Heshvan in the year after the death is chaser, then the jahrzeit is observed on 29 Heshvan in years when Heshvan is chaser. Otherwise, the yahrzeit is observed on 1 Kislev when Heshvan is chaser.
- If the death occurred on 30 Kislev, and Kislev in the year after the death is chaser, then the jahrzeit is observed on 29 Kislev in years when Kislev is chaser. Otherwise, the yahrzeit is observed on 1 Tevet when Kislev is chaser.
- If the death occurred on 1-29 Adar A, it is observed on 1-29 Adar in non-leapyears.
- If the death occurred on 30 Adar A, it is observed on 30 Shvat in a non-leapyear.
REM Sat Sun SPECIAL SHADE 128 REM Mon SPECIAL SHADE 255 0 0The SHADE keyword is followed by either one or three numbers, from 0 to 255. If one number is supplied, it is interpreted as a grey-scale value from black (0) to white (255). If three numbers are supplied, they are interpreted as RGB components from minimum (0) to maximum (255). The example above shades weekends a fairly dark grey and makes Mondays a fully-saturated red. (These shadings appear in calendars produced by Rem2PS, tkremind and rem2html.) The MOON special replaces the psmoon() function. Use it like this:
REM [moondate(0)] SPECIAL MOON 0 REM [moondate(1)] SPECIAL MOON 1 REM [moondate(2)] SPECIAL MOON 2 REM [moondate(3)] SPECIAL MOON 3These draw little moons on the various calendars. The complete syntax of the MOON special is as follows:
... SPECIAL MOON phase moonsize fontsize msgPhase is a number from 0 to 3, with 0 representing a new moon, 1 the first quarter, 2 a full moon and 3 the last quarter. moonsize is the diameter in PostScript units of the moon to draw. If omitted or supplied as -1, the backend chooses an appropriate size. fontsize is the font size in PostScript units of the msg Msg is additional text that is placed near the moon glyph. Note that only the Rem2PS backend supports moonsize and fontsize; the other backends use fixed sizes. The COLOR special lets you place colored reminders in the calendar. Use it like this:
REM ... SPECIAL COLOR 255 0 0 This is a bright red reminder REM ... SPECIAL COLOR 0 128 0 This is a dark green reminder
REM Monday SPECIAL WEEK (W[weekno()])
- REM can be omitted - it is implied if no other valid command is present.
- CLEAR-OMIT-CONTEXT --> CLEAR
- PUSH-OMIT-CONTEXT --> PUSH
- POP-OMIT-CONTEXT --> POP
- DUMPVARS --> DUMP
- BANNER --> BAN
- INCLUDE --> INC
- SCANFROM --> SCAN
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 1993This 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 [trigdate()] ++5 MSG \ U.S. Presidential Election!! ENDIFThis 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 that 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 FooThe 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 that 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 [today()-7] SATISFY 1 OMIT [trigdate()] REM Mon AFTER MSG HelloThe 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 that may occur, and on the range of the movable holiday. Generally, a value of 7 is safe. The FROM clause operates almost like the counterpoint to UNTIL. It prevents the reminder from triggering before the FROM date. For example, the following reminder:
REM Mon Thu FROM 23 Jul 2007 UNTIL 2 Aug 2007 MSG Testwill trigger on Mondays and Thursdays between 23 July 2007 and 2 August 2007 inclusive. FROM is really just syntactic sugar; you could implement the reminder above as follows:
REM Mon Thu SCANFROM [max(today(), '2007-07-23')] \ UNTIL 2 Aug 2007 MSG Testbut that's a lot harder to read. Internally, Remind treats FROM exactly as illustrated using SCANFROM. For that reason, you cannot use both FROM and SCANFROM. 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 that compute trigger dates that can be used unmodified in subsequent REM commands. The file "defs.rem" that 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 that 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.
|31 August 2008||4th Berkeley Distribution|