1REMIND(1) General Commands Manual REMIND(1)
2
6 remind - a sophisticated reminder service
7
9 remind [options] filename [date] [*rep] [time]
10
12 Remind reads the supplied filename and executes the commands found in
13 it. The commands are used to issue reminders and alarms. Each
14 reminder or alarm can consist of a message sent to standard output, or
15 a program to be executed.
16 If filename is specified as a single dash '-', then Remind takes its
18 input from standard input. This also implicitly enables the -o option,
19 described below.
20 If filename happens to be a directory rather than a plain file, then
22 Remind reads all of the files in that directory that match the pattern
23 "*.rem". The files are read in sorted order; the sort order may depend
24 on your locale, but should match the sort order used by the shell to
25 expand "*.rem".
26
29 Remind has a slew of options. If you're new to the program, ignore
30 them for now and skip to the section "Reminder Files".
31 -n The -n option causes Remind to print the next occurrence of each
33 reminder in a simple calendar format. You can sort this by date
34 by piping the output through sort(1).
35 -r The -r option disables RUN directives and the shell() function.
37 As of Remind 3.00.17, using -u implies -r.
38 -c[flags]n
40 The -c option causes Remind to produce a calendar that is sent
41 to standard output. If you supply a number n, then a calendar
42 will be generated for n months, starting with the current month.
43 By default, a calendar for only the current month is produced.
44 You can precede n (if any) with a set of flags. The flags are as fol‐
46 lows:
47 '+' causes a calendar for n weeks to be produced.
49 'a' causes Remind to display reminders on the calendar on the day
51 they actually occur as well as on any preceding days specified
52 by the reminder's delta.
53 'l' causes Remind to use VT100 line-drawing characters to draw the
55 calendar. The characters are hard-coded and will only work on
56 terminals that emulate the VT00 line-drawing character set.
57 'c' causes Remind to use VT100 escape sequences to approximate SPE‐
59 CIAL COLOR reminders. The approximation is (of necessity) very
60 coarse, because the VT100 only has eight different color
61 sequences, each with one of two brightnesses. A color component
62 greater than 64 is considered "on", and if any of the three
63 color components is greater than 128, the color is considered
64 "bright".
65 -wcol[,pad[,spc]]]
68 The -w option specifies the output width, padding and spacing of
69 the formatted calendar output. Col specifies the number of col‐
70 umns in the output device, and defaults to 80. Pad specifies
71 how many lines to use to "pad" empty calendar boxes. This
72 defaults to 5. If you have many reminders on certain days that
73 make your calendar too large to fit on a page, you can try
74 reducing pad to make the empty boxes smaller. Spc specifies how
75 many blank lines to leave between the day number and the first
76 reminder entry. It defaults to 1.
77 Any of col, pad or spc can be omitted, providing you provide the
79 correct number of commas. Don't use any spaces in the option.
80 -s[a]n The -s option is very similar to the -c option, except that the
82 output calendar is not formatted. It is listed in a "simple
83 format" that can be used as input for more sophisticated calen‐
84 dar-drawing programs. If n starts with "+", then it is inter‐
85 preted as a number of weeks.
86 If you immediately follow the s with the letter a, then Remind
88 displays reminders on the calendar on the day they actually
89 occur as well as on any preceding days specified by the
90 reminder's delta.
91 -p[a]n The -p option is very similar to the -s option, except that the
93 output contains additional information for use by the Rem2PS
94 program, which creates a PostScript calendar. For this option,
95 n cannot start with "+"; it must specify a number of months.
96 The format of the -p output is described in the rem2ps(1) man
97 page. If you immediately follow the p with the letter a, then
98 Remind displays reminders on the calendar on the day they actu‐
99 ally occur as well as on any preceding days specified by the
100 reminder's delta.
101 -l If you use the -l option in conjunction with the -p option, then
104 Remind outputs additional information for back-end programs such
105 as rem2ps. This additional information lets the back-end pro‐
106 grams correlate a reminder with the source file and line number
107 that produced it.
108 -m The -m option causes the -c or -p options to produce a calendar
110 whose first column is Monday rather than Sunday. (This conforms
111 to the international standard.)
112 -v The -v option makes the output of Remind slightly more verbose.
114 Currently, this causes Remind to echo a bad line in case of an
115 error, and to print a security message if a script tests the
116 $RunOff system variable.
117 -o The -o option causes Remind to ignore all ONCE directives.
119 -t The -t option causes Remind to trigger all non-expired
121 reminders, regardless of the delta supplied for each reminder.
122 -tn If you supply a number n after the -t option, then Remind pre‐
124 tends that each non-expired reminder has a delta of n days and
125 triggers reminders accordingly.
126 -h The -h option ("hush...") suppresses certain warning and infor‐
128 mation messages. In particular, if no reminders are triggered,
129 this mode produces no output.
130 -a The -a option causes Remind not to immediately trigger timed
132 reminders that would also be queued. It also causes Remind not
133 to place timed reminders in a calendar.
134 -q The -q option causes Remind not to queue timed reminders for
136 later execution.
137 -f The -f option causes Remind to remain in the foreground when
139 processing queued reminders, rather than forking off a back‐
140 ground process to handle them.
141 -e The -e option diverts error messages (normally sent to the stan‐
143 dard error stream) to the standard output stream.
144 -dchars
146 The -d option enables certain debugging modes. The chars spec‐
147 ify which modes to enable:
148 e Echo all input lines
150 x Trace all expression evaluation
152 t Display all trigger date computation
154 v Dump the variable table after execution of the reminder script
156 l Echo lines when displaying error messages
158 f Trace the reading of reminder files
160 -g[a|d[a|d[a|d[a|d]]]]
162 Normally, reminders are issued in the order in which they are
163 encountered in the reminder script. The -g option cause Remind
164 to sort reminders by date and time prior to issuing them. The
165 optional a and d characters specify the sort order (ascending or
166 descending) for the date, time and priority fields. See the
167 section "Sorting Reminders" for more information.
168 -b[n] Set the time format for the calendar and simple-calendar out‐
171 puts. N can range from 0 to 2, with the default 0. A value of
172 0 causes times to be inserted in 12-hour (am/pm) format. 1
173 causes times to be inserted in 24-hour format, and 2 inhibits
174 the automatic insertion of times in the calendar output.
175 -x[n] Sets the iteration limit for the SATISFY clause of a REM com‐
177 mand. Defaults to 150.
178 -kcmd Instead of simply printing MSG-type reminders, this causes them
180 to be passed to the specific cmd. You must use '%s' where you
181 want the body to appear, and may need to enclose this option in
182 quotes. Note that all shell characters in the body of the
183 reminder are escaped with a backslash, and the entire body of
184 the reminder is passed as a single argument. Note that this
185 option overrides the -r option and the RUN OFF command.
186 As an example, suppose you have an X Window program called xmes‐
188 sage that pops up a window and displays its invocation argu‐
189 ments. You could use:
190 remind '-kxmessage %s &' ...
192 to have all of your MSG-type reminders processed using xmessage.
194 A word of warning: It is very easy to spawn dozens of xmessage
196 processes with the above technique. So be very careful. Also,
197 the cmd is passed as an argument to sprintf(). If you use for‐
198 matting directives other than %s, or use more than one %s direc‐
199 tive, there's a good chance that you'll crash Remind. Finally,
200 because all shell and whitespace characters are escaped, the
201 program you execute with the -k option must be prepared to han‐
202 dle the entire message as a single argument.
203 -z[n] Runs Remind in the daemon mode. If n is supplied, it specifies
205 how often (in minutes) Remind should wake up to check if the
206 reminder script has been changed. N defaults to 5, and can
207 range from 5 to 60. Note that the use of the -z option also
208 enables the -f option.
209 If you supply the option -z0, Remind runs in a special mode
211 called server mode. This is documented in the tkremind man
212 page; see tkremind(1).
213 -uname Runs Remind with the uid and gid of the user specified by name.
215 The option changes the uid and gid as described, and sets the
216 environment variables HOME, SHELL and USER to the home direc‐
217 tory, shell, and user name, respectively, of the specified user.
218 LOGNAME is also set to the specified user name. This option is
219 meant for use in shell scripts that mail reminders to all users.
220 Note that as of Remind 3.00.17, using -u implies -r -- the RUN
221 directive and shell() functions are disabled.
222 Non-root users can also use the -u option. However, in this
224 case, it only changes the environment variables as described
225 above. It does not change the effective uid or gid.
226 -y Causes Remind to synthesize a tag for any reminder that lacks a
228 TAG clause.
229 -ivar=expr
231 Sets the value of the specified var to expr, and preserves var.
232 Expr can be any valid Remind expression. See the section "Ini‐
233 tializing Variables on the Command Line" for more details.
234 -ifunc(args)=definition
236 Allows you to define a function on the command line.
237 If you supply a date on the command line, it must consist of day month
239 year, where day is the day of the month, month is at least the first
240 three letters of the English name of the month, and year is a year (all
241 4 digits) from 1990 to about 2075. You can leave out the day, which
242 then defaults to 1.
243 If you do supply a date on the command line, then Remind uses it,
245 rather than the actual system date, as its notion of "today." This
246 lets you create calendars for future months, or test to see how your
247 reminders will be triggered in the future. Similarly, you can supply a
248 time (in 24-hour format -- for example, 17:15) to set Remind's notion
249 of "now" to a particular time. Supplying a time on the command line
250 also implicitly enables the -q option and disables the -z option.
251 If you would rather specify the date more succinctly, you can supply it
253 as YYYY-MM-DD or YYYY/MM/DD. You can even supply a date and time on
254 the command line as one argument: YYYY-MM-DD@HH:MM.
255 In addition, you can supply a repeat parameter, which has the form
257 *num. This causes Remind to be run num times, with the date increment‐
258 ing on each iteration. You may have to enclose the parameter in quotes
259 to avoid shell expansion. See the subsection "Repeated Execution" in
260 the section "Calendar Mode" for more information.
261
263 Remind uses scripts to control its operation. You can use any text
264 editor capable of creating plain ASCII files to create a Remind script.
265 The commands inside a script can range from the very simple and almost
266 immediately understandable:
267 REM 6 Jan MSG David's birthday
269 to the baroque and obscure:
271 REM [date(thisyear, 1, 1) + 180] ++5 OMIT \
273 sat sun BEFORE MSG [ord(thisyear-1980)] payment due %b!
274 A reminder file consists of commands, with one command per line. Sev‐
276 eral lines can be continued using the backslash character, as in the
277 above example. In this case, all of the concatenated lines are treated
278 as a single line by Remind. Note that if an error occurs, Remind
279 reports the line number of the last line of a continued line.
280 Remind ignores blank lines, and lines beginning with the '#' or ';'
282 characters. You can use the semicolon as a comment character if you
283 wish to pass a Remind script through the C pre-processor, which inter‐
284 prets the '#' character as the start of a pre-processing directive.
285 Remind is not case sensitive; you can generally use any mixture of
287 upper- or lower-case for commands, parameters, invocation options, etc.
288
290 The most powerful command in a Remind script is the REM command. This
291 command is responsible for issuing reminders. Its syntax is:
292 REM [ONCE] [date_spec] [back] [delta] [repeat] [PRIORITY prio]
294 [SKIP | BEFORE | AFTER] [OMIT omit_list] [OMITFUNC omit_func‐
295 tion] [AT time [tdelta] [trepeat]] [SCHED sched_function] [WARN
296 warn_function] [UNTIL expiry_date] [SCANFROM scan_date | FROM
297 start_date] [DURATION duration] [TAG tag] <MSG | MSF | RUN | CAL
298 | SATISFY | SPECIAL special | PS | PSFILE> body
299 The parts of the REM command can be specified in any order, except that
301 the body must come immediately after the MSG, RUN, CAL, PS, PSFILE or
302 SATISFY keyword.
303 The REM token is optional, providing that the remainder of the command
305 cannot be mistaken for another Remind command such as OMIT or RUN. The
306 portion of the REM command before the MSG, MSF RUN, CAL or SATISFY
307 clause is called a trigger.
308 MSG, MSF, RUN, CAL, SPECIAL, PS and PSFILE
310 These keywords denote the type of the reminder. (SATISFY is more com‐
312 plicated and will be explained later.) A MSG-type reminder normally
313 prints a message to the standard output, after passing the body through
314 a special substitution filter, described in the section "The Substitu‐
315 tion Filter." However, if you have used the -k command-line option,
316 then MSG-type reminders are passed to the appropriate program. Note
317 that the options -c, -s, -p and -n disable the -k option.
318 Note that you can omit the reminder type, in which case it defaults to
320 MSG. So you can write:
321 6 January David's Birthday
323 although this is not recommended.
325 The MSF keyword is almost the same as the MSG keyword, except that the
327 reminder is formatted to fit into a paragraph-like format. Three sys‐
328 tem variables control the formatting of MSF-type reminders - they are
329 $FirstIndent, $SubsIndent and $FormWidth. They are discussed in the
330 section "System Variables." The MSF keyword causes the spacing of your
331 reminder to be altered - extra spaces are discarded, and two spaces are
332 placed after periods and other characters, as specified by the system
333 variables $EndSent and $EndSentIg. Note that if the body of the
334 reminder includes newline characters (placed there with the %_
335 sequence), then the newlines are treated as the beginnings of new para‐
336 graphs, and the $FirstIndent indentation is used for the next line.
337 You can use two consecutive newlines to have spaced paragraphs emitted
338 from a single reminder body.
339 A RUN-type reminder also passes the body through the substitution fil‐
341 ter, but then executes the result as a system command. A CAL-type
342 reminder is used only to place entries in the calendar produced when
343 Remind is run with the -c, -s or -p options.
344 A PS or PSFILE-type reminder is used to pass PostScript code directly
346 to the printer when producing PostScript calendars. This can be used
347 to shade certain calendar entries (see the psshade() function), include
348 graphics in the calendar, or almost any other purpose you can think of.
349 You should not use these types of reminders unless you are an expert
350 PostScript programmer. The PS and PSFILE reminders are ignored unless
351 Remind is run with the -p option. See the section "More about Post‐
352 Script" for more details.
353 A SPECIAL-type reminder is used to pass "out-of-band" information from
355 Remind to a calendar-producing back-end. It should be followed by a
356 word indicating the type of special data being passed. The type of a
357 special reminder depends on the back-end. For the Rem2PS back-end,
358 SPECIAL PostScript is equivalent to a PS-type reminder, and SPECIAL
359 PSFile is equivalent to a PSFILE-type reminder. The body of a SPECIAL
360 reminder is obviously dependent upon the back-end.
361 DATE SPECIFICATIONS
363 A date_spec consists of zero to four parts. These parts are day (day
365 of month), month (month name), year and weekday. Month and weekday are
366 the English names of months and weekdays. At least the first three
367 characters must be used. The following are examples of the various
368 parts of a date_spec:
369 day: 1, 22, 31, 14, 3
371 month: JANUARY, feb, March, ApR, may, Aug
373 year: 1990, 1993, 2030, 95 (interpreted as 1995). The year can range
375 from 1990 to 2075.
376 weekday:
378 Monday, tue, Wed, THU, Friday, saturday, sundAy
379 Note that there can be several weekday components separated by spaces
381 in a date_spec.
382 INTERPRETATION OF DATE SPECIFICATIONS
384 The following examples show how date specifications are interpreted.
386 1. Null date specification - the reminder is triggered every day. The
388 trigger date for a specific run is simply the current system date.
389 2. Only day present. The reminder is triggered on the specified day of
391 each month. The trigger date for a particular run is the closest such
392 day to the current system date. For example:
393 REM 1 MSG First of every month.
394 REM 31 MSG 31st of every month that has 31 days.
395 3. Only month present. The reminder is triggered every day of the
397 specified month. Example:
398 REM Feb MSG Every day in February
399 4. day and month present. Examples:
401 REM 6 Jan MSG Every 6th of January
402 REM Feb 29 MSG Every 29th of February
403 5. Only year present. Example:
405 REM 1991 MSG Every day in 1991
406 6. year and day present. Examples:
408 REM 1 1990 MSG 1st of every month in 1990
409 REM 1992 23 MSG 23rd of every month in 1992
410 7. year and month present. Examples:
412 REM Feb 1991 MSG Every day in Feb 1991
413 REM 1992 September MSG Every day in Sept 1992
414 8. year, month and day present. Examples:
416 REM 8 Jan 1991 MSG 8th January 1991.
417 REM 1992 March 9 MSG 9th March 1992.
418 9. weekday only. Examples:
420 REM Sat MSG Every Saturday
421 REM Mon Tue Wed Thu Fri MSG Every working day
422 REM Monday Wednesday MSG Every Monday and Wednesday
423 10. weekday and day present. Examples:
425 REM Sat 1 MSG First Saturday of every month
426 REM Mon Tue Wed Thu Fri 15 \
427 MSG 1st working day after 15th of every month
428 11. weekday and month present. Examples:
430 REM Mon March MSG Every Monday in March
431 REM Mon Tue Wed Thu Fri Feb MSG Every working day in February
432 12. weekday, month and day present. Examples:
434 REM Mon 1 March MSG First Monday in March
435 REM Sat Sun 15 July MSG First Sat or Sun on or after 15 July
436 13. weekday and year present. Example:
438 REM Sat Sun 1991 MSG Every Saturday and Sunday in 1991
439 14. weekday, day and year present. Examples:
441 REM Mon 15 1990 MSG 1st Mon after 15th of every month in 1990
442 REM Mon Tue Wed Thu Fri 1 1990 \
443 MSG 1st working day of every month in 1990
444 15. weekday, month and year present. Example:
446 REM Mon Wed 1991 Feb MSG Every Mon and Wed in Feb 1991.
447 16. weekday, day, month and year present. Example:
449 REM Mon Tue Wed Thu Fri 28 Oct 1990 \
450 MSG 1st working day on or after 28 October 1990.
451 Note that when both weekday and day are specified, Remind chooses the
453 first date on or after the specified day that also satisfies the week‐
454 day constraint. It does this by picking the first date on or after the
455 specified day that is listed in the list of weekdays. Thus, a reminder
456 like:
457 REM Mon Tue 28 Oct 1990 MSG Hi
459 would be issued only on Monday, 29 October, 1990. It would not be
461 issued on Tuesday, 30 October, 1990, since the 29th is the first date
462 to satisfy the weekday constraints.
463 SHORT-HAND DATE SPECIFICATIONS
465 In addition to spelling out the day, month and year separately, you can
467 specify YYYY-MM-DD or YYYY/MM/DD. For example, the following state‐
468 ments are equivalent:
469 REM 5 June 2010 MSG Cool!
471 REM 2010-06-05 MSG Cool!
472 You can also specify a date and time as YYYY-MM-DD@HH:MM. These state‐
474 ments are equivalent:
475 REM 19 Dec 2010 AT 16:45 MSG Hi
477 REM 2010-12-19@16:45 MSG Hi
478 There's one subtlety with short-hand date specifications: The follow‐
480 ing statements are not equivalent:
481 REM 19 Dec 2010 AT 16:45 +60 MSG Hi
483 REM 2010-12-19@16:45 +60 MSG Hi
484 In the second statement, the "+60" is a delta that applies to the date
486 rather than a tdelta that applies to the time. We recommend explicitly
487 using the AT keyword with timed reminders.
488 BACKWARD SCANNING
490 Sometimes, it is necessary to specify a date as being a set amount of
492 time before another date. For example, the last Monday in a given
493 month is computed as the first Monday in the next month, minus 7 days.
494 The back specification in the reminder is used in this case:
495 REM Mon 1 -7 MSG Last Monday of every month.
497 A back is specified with one or two dashes followed by an integer.
499 This causes Remind to move "backwards" from what would normally be the
500 trigger date. The difference between --7 and -7 will be explained when
501 the OMIT keyword is described.
502 ADVANCE WARNING
504 For some reminders, it is appropriate to receive advance warning of the
506 event. For example, you may wish to be reminded of someone's birthday
507 several days in advance. The delta portion of the REM command achieves
508 this. It is specified as one or two "+" signs followed by a number n.
509 Again, the difference between the "+" and "++" forms will be explained
510 under the OMIT keyword. Remind will trigger the reminder on computed
511 trigger date, as well as on each of the n days before the event. Here
512 are some examples:
513 REM 6 Jan +5 MSG Remind me of birthday 5 days in advance.
515 The above example would be triggered every 6th of January, as well as
517 the 1st through 5th of January.
518 PERIODIC REMINDERS
520 We have already seen some built-in mechanisms for certain types of
522 periodic reminders. For example, an event occurring every Wednesday
523 could be specified as:
524 REM Wed MSG Event!
526 However, events that do not repeat daily, weekly, monthly or yearly
528 require another approach. The repeat component of the REM command
529 fills this need. To use it, you must completely specify a date (year,
530 month and day, and optionally weekday.) The repeat component is an
531 asterisk followed by a number specifying the repetition period in days.
532 For example, suppose you get paid every second Wednesday, and your last
534 payday was Wednesday, 28 October, 1992. You can use:
535 REM 28 Oct 1992 *14 MSG Payday
537 This issues the reminder every 14 days, starting from the calculated
539 trigger date. You can use delta and back with repeat. Note, however,
540 that the back is used only to compute the initial trigger date; there‐
541 after, the reminder repeats with the specified period. Similarly, if
542 you specify a weekday, it is used only to calculate the initial date,
543 and does not affect the repetition period.
544 SCANFROM and FROM
546 The SCANFROM and FROM keywords are for advanced Remind programmers
548 only, and will be explained in the section "Details about Trigger Com‐
549 putation" near the end of this manual. Note that SCANFROM is available
550 only in versions of Remind from 03.00.04 up. FROM is available only
551 from 03.01.00 and later.
552 PRIORITY
554 The PRIORITY keyword must be followed by a number from 0 to 9999. It
556 is used in calendar mode and when sorting reminders. If two reminders
557 have the same trigger date and time, then they are sorted by priority.
558 If the PRIORITY keyword is not supplied, a default priority of 5000 is
559 used. (This default can be changed by adjusting the system variable
560 $DefaultPrio. See the section "System Variables" for more informa‐
561 tion.)
562 EXPIRY DATES
564 Some reminders should be issued periodically for a certain time, but
566 then expire. For example, suppose you have a class every Friday, and
567 that your last class is on 11 December 1992. You can use:
568 REM Fri UNTIL 11 Dec 1992 MSG Class today.
570 Another example: Suppose you have jury duty from 30 November 1992
572 until 4 December 1992. The following reminder will issue the message
573 every day of your jury duty, as well as 2 days ahead of time:
574 REM 1992-11-30 *1 +2 UNTIL 1992-12-04 MSG Jury duty
576 Note that the repeat of *1 is necessary; without it, the reminder would
578 be issued only on 30 November (and the two days preceding.)
579 THE ONCE KEYWORD
581 Sometimes, it is necessary to ensure that reminders are run only once
583 on a given day. For example, if you have a reminder that makes a
584 backup of your files every Friday:
585 REM Fri RUN do_backup
587 (Here, do_backup is assumed to be a program or shell script that does
589 the work.) If you run Remind from your .login script, for example, and
590 log in several times per day, the do_backup program will be run each
591 time you log in. If, however, you use the ONCE keyword in the
592 reminder, the Remind checks the last access date of the reminder
593 script. If it is the same as the current date, Remind assumes that it
594 has already been run, and will not issue reminders containing the ONCE
595 keyword.
596 Note that if you view or edit your reminder script, the last access
598 date will be updated, and the ONCE keyword will not operate properly.
599 If you start Remind with the -o option, then the ONCE keyword will be
600 ignored.
601 LOCALLY OMITTING WEEKDAYS
603 The OMIT portion of the REM command is used to "omit" certain days when
605 counting the delta or back. It is specified using the keyword OMIT
606 followed by a list of weekdays. Its action is best illustrated with
607 examples:
608 REM 1 +1 OMIT Sat Sun MSG Important Event
610 This reminder is normally triggered on the first of every month, as
612 well as the day preceding it. However, if the first of the month falls
613 on a Sunday or Monday, then the reminder is triggered starting from the
614 previous Friday. This is because the delta of +1 does not count Satur‐
615 day or Sunday when it counts backwards from the trigger date to deter‐
616 mine how much advance warning to give.
617 Contrast this with the use of "++1" in the above command. In this
619 case, the reminder is triggered on the first of each month, as well as
620 the day preceding it. The omitted days are counted.
621 REM 1 -1 OMIT Sat Sun MSG Last working day of month
623 Again, in the above example, the back of -1 normally causes the trigger
625 date to be the last day of the month. However, because of the OMIT
626 clause, if the first of the month falls on a Sunday or Monday, the
627 trigger date is moved backwards past the weekend to Friday. (If you
628 have globally omitted holidays, the reminder will be moved back past
629 them, also. See "The OMIT command" for more details.)
630 By comparison, if we had used "--1", the reminder would be triggered on
632 the last day of the month, regardless of the OMIT.
633 COMPUTED LOCAL OMITS
635 The OMITFUNC phrase of the REM command allows you to supply a function
637 that determines whether or not a date is omitted. The function is
638 passed a single parameter of type DATE, and must return a non-zero
639 integer if the date is considered "omitted" and 0 otherwise. Here's an
640 example:
641 FSET _third(x) (day(x) % 3) || \
643 (wkdaynum(x) == 0) || \
644 (wkdaynum(x) == 6)
645 REM OMITFUNC _third AFTER MSG Working day divisible by 3
646 In the example above, the reminder is triggered every Monday to Friday
648 whose day-of-month number is divisible by three. Here's how it works:
649 o The OMITFUNC _third portion causes all days for which _third(x)
651 returns non-zero to be considered "omitted". This causes all
652 days whose day-of-month number is not a multiple of three to be
653 omitted. Note that _third also returns non-zero if the weekday
654 is Sunday or Saturday.
655 o The AFTER keyword causes the reminder to be moved after a block
657 of omitted days.
658 The combination of OMITFUNC and AFTER keyword causes the reminder to be
660 issued on all days whose day-of-month number is divisible by three, but
661 not on Saturday or Sunday.
662 Note that if you use OMITFUNC, then a local OMIT is ignored as are all
664 global OMITs. If you want to omit specific weekdays, your omit func‐
665 tion will need to test for them specifically. If you want to take into
666 account the global OMIT context, then your omit function will need to
667 test for that explicitly (using the isomitted() function.)
668 Note that an incorrect OMITFUNC might cause all days to be considered
670 omitted. For that reason, when Remind searches through omitted days,
671 it terminates the search after the SATISFY iteration limit (command-
672 line option -x.)
673 TIMED REMINDERS
675 Timed reminders are those that have an AT keyword followed by a time
677 and optional tdelta and trepeat. The time must be specified in 24-hour
678 format, with 0:00 representing midnight, 12:00 representing noon, and
679 23:59 representing one minute to midnight. You can use either a colon
680 or a period to separate the hours from the minutes. That is, 13:39 and
681 13.39 are equivalent.
682 Remind treats timed reminders specially. If the trigger date for a
684 timed reminder is the same as the current system date, the reminder is
685 queued for later activation. When Remind has finished processing the
686 reminder file, it puts itself in the background, and activates timed
687 reminders when the system time reached the specified time.
688 If the trigger date is not the same as the system date, the reminder is
691 not queued.
692 For example, the following reminder, triggered every working day, will
694 emit a message telling you to leave at 5:00pm:
695 REM Mon Tue Wed Thu Fri AT 17:00 MSG Time to leave!
697 The following reminder will be triggered on Thursdays and Fridays, but
699 will only be queued on Fridays:
700 REM Fri ++1 AT 13:00 MSG Lunch at 1pm Friday.
702 The tdelta and trepeat have the same form as a repeat and delta, but
704 are specified in minutes. For example, this reminder will be triggered
705 at 12:00pm as well as 45 minutes before:
706 REM AT 12:00 +45 MSG Example
708 The following will be issued starting at 10:45, every half hour until
710 11:45, and again at noon.
711 REM AT 12:00 +75 *30 MSG Example2
713 The "+75" means that the reminder is issued starting 75 minutes before
715 noon; in other words, at 10:45. The *30 specifies that the reminder is
716 subsequently to be issued every 30 minutes. Note that the reminder is
717 always issued at the specified time, even if the tdelta is not a multi‐
718 ple of the trepeat. So the above example is issued at 10:45am,
719 11:15am, 11:45am, and 12:00pm. Note that in the time specification,
720 there is no distinction between the "+" and "++" forms of tdelta.
721 Normally, Remind will issue timed reminders as it processes the
723 reminder script, as well as queuing them for later. If you do not want
724 Remind to issue the reminders when processing the script, but only to
725 queue them for later, use the -a command-line option. If you do not
726 want reminders to be queued for later, use the -q command-line option.
727 Normally, Remind forks a background process to handle queued reminders.
729 If you want Remind to remain in the foreground, use the -f command-line
730 option. This is useful, for example, in .xinitrc scripts, where you
731 can use the command:
732 remind -fa myreminders &
734 This ensures that when you exit X-Windows, the Remind process is
736 killed.
737 WARNING ABOUT TIMED REMINDERS
739 Note: If you use user-defined functions or variables (described later)
741 in the bodies of timed reminders, then when the timed reminders are
742 activated, the variables and functions have the definitions that were
743 in effect at the end of the reminder script. These definitions may not
744 necessarily be those that were in effect at the time the reminder was
745 queued.
746 THE SCHED AND WARN KEYWORDS
748 The SCHED keyword allows more precise control over the triggering of
750 timed reminders, and the WARN keyword allows precise control over the
751 advance triggering of all types of reminders. However, discussion must
752 be deferred until after expressions and user-defined functions are
753 explained. See the subsection "Precise Scheduling" further on.
754 TAG AND DURATION
756 The TAG keyword lets you "tag" certain reminders. This facility is
758 used by certain back-ends or systems built around Remind, such as TkRe‐
759 mind. These back-ends have specific rules about tags; you should not
760 use the TAG keyword yourself, or your script will interact badly with
761 back-ends.
762 The TAG keyword is followed by a tag consisting of up to 48 characters.
764 If you supply the -y option to Remind, then any reminder that lacks a
766 TAG will have one synthesized. The synthesized tag consists of the
767 characters "__syn__" followed by the hexadecimal representation of the
768 MD5 sum of the REM command line. This lets you give a more-or-less
769 unique identifier to each distinct REM command.
770 The DURATION keyword makes sense only for timed reminders; it specifies
772 the duration of an event. Currently, this is not used, but it may be
773 used in future by back-ends or scheduling systems built around Remind.
774 For example, if you have a 90-minute meeting starting at 1:00pm, you
775 could use:
776 REM 5 March 1999 AT 13:00 DURATION 1:30 MSG Meeting
778 Note that duration is specified in hours and minutes.
780
782 Before being processed, the body of a REM command is passed through a
783 substitution filter. The filter scans for sequences "%x" (where "x" is
784 any letter and certain other characters) and performs substitutions as
785 shown below. (All dates refer to the trigger date of the reminder.)
786 %a is replaced with "on weekday, day month, year"
788 For example, consider the reminder:
789 REM 18 Oct 1990 +4 MSG Meeting with Bob %a.
791 On 16 October 1990, it would print "Meeting with Bob on Thurs‐
793 day, 18 October, 1990."
794 On 17 October 1990, it would print "Meeting with Bob tomorrow."
796 On 18 October 1990, it would print "Meeting with Bob today."
798 %b is replaced with "in diff day's time" where diff is the actual
800 number of days between the current date and the trigger date.
801 (OMITs have no effect.)
802 For example, consider:
803 REM 18 Oct 1990 +4 MSG Meeting with Bob %b.
805 On 16 October 1990, it would print "Meeting with Bob in 2 days'
807 time."
808 On 17 October 1990, it would print "Meeting with Bob tomorrow."
810 On 18 October 1990, it would print "Meeting with Bob today."
812 %c is replaced with "on weekday"
814 Example: REM 18 Oct 1990 +4 MSG Meeting with Bob %c.
815 On 16 October 1990, it would print "Meeting with Bob on Thurs‐
817 day."
818 On 17 October 1990, it would print "Meeting with Bob tomorrow."
820 On 18 October 1990, it would print "Meeting with Bob today."
822 %d is replaced with "day", the day of the month.
824 %e is replaced with "on dd-mm-yyyy"
826 %f is replaced with "on mm-dd-yyyy"
828 %g is replaced with "on weekday, day month"
830 %h is replaced with "on dd-mm"
832 %i is replaced with "on mm-dd"
834 %j is replaced with "on weekday, month day-th, year" This form
836 appends the characters "st", "nd", "rd" or "th" to the day of
837 the month, as appropriate.
838 %k is replaced with "on weekday, month day-th"
840 %l is replaced with "on yyyy-mm-dd"
842 %m is replaced with "month", the name of the month.
844 %n is replaced with the number (1 to 12) of the month.
846 %o is replaced with " (today)" if and only if the current system
848 date is the same as the date being used by Remind as the current
849 date. Recall that you can specify a date for Remind to use on
850 the command line. This substitution is not generally useful in
851 a REM command, but is useful in a BANNER command. (See "The
852 BANNER Command.")
853 %p is replaced with "s" if the diff between the current date and
855 the trigger date is not 1. You can use this to construct
856 reminders like:
857 REM 1 Jan +4 MSG %x day%p to go before New Year!
858 %q is replaced with "'s" if the diff between the trigger date and
860 the current date is 1. Otherwise, it is replaced with "s'"
861 This can be used as follows:
862 REM 1 Jan +4 MSG New Year in %x day%q time!
863 %r is replaced with the day of the month (01 to 31) padded with a
865 leading zero if needed to pad to two digits.
866 %s is replaced with "st", "nd", "rd" or "th" depending on the day
868 of the month.
869 %t is replaced with the number of the month (01 to 12) padded to
871 two digits with a leading zero.
872 %u is replaced with "on weekday, day-th month, year" This is simi‐
874 lar to %a except that "st", "nd", "rd" or "th" is added to the
875 day as appropriate.
876 %v is replaced with "on weekday, day-th month"
878 %w is replaced with "weekday", the name of the day of the week.
880 %x is replaced with the diff between the current date and the trig‐
882 ger date. The diff is defined as the actual number of days
883 between these two dates; OMITs are not counted. (Strict date
884 subtraction is performed.)
885 %y is replaced with "year", the year of the trigger date.
887 %z is replaced with "yy", the last two digits of the year.
889 %_ (percent-underscore) is replaced with a newline. You can use
891 this to achieve multi-line reminders.
892 %1 is replaced with "now", "m minutes from now", "m minutes ago",
894 "h hours from now", "h hours ago", "h hours and m minutes from
895 now" or "h hours and m minutes ago", as appropriate for a timed
896 reminder. Note that unless you specify the -a option, timed
897 reminders will be triggered like normal reminders, and thus a
898 timed reminder that occurred earlier in the day may be trig‐
899 gered. This causes the need for the "...ago" forms.
900 %2 is replaced with "at hh:mmam" or "..pm" depending on the AT time
902 of the reminder.
903 %3 is replaced with "at hh:mm" in 24-hour format.
905 %4 is replaced with "mm" where mm is the number of minutes between
907 "now" and the time specified by AT. If the AT time is earlier
908 than the current time, then the result is negative.
909 %5 is replaced with "ma" where ma is the absolute value of the num‐
911 ber produced by %4.
912 %6 is replaced with "ago" or "from now", depending on the relation‐
914 ship between the AT time and the current time.
915 %7 is replaced with the number of hours between the AT time and the
917 current time. It is always non-negative.
918 %8 is replaced with the number of minutes between the AT time and
920 the current time, after the hours (%7) have been subtracted out.
921 This is a number ranging from 0 to 59.
922 %9 is replaced with "s" if the value produced by %8 is not 1.
924 %0 is replaced with "s" if the value produced by %7 is not 1.
926 %! is replaced with "is" if the current time is before the AT time,
928 or "was" if it is after.
929 %@ is similar to %2 but displays the current time.
931 %# is similar to %3 but displays the current time.
933 %" (percent-doublequote - ") is removed. This sequence is not used
935 by the substitution filter, but is used to tell Remind which
936 text to include in a calendar entry when the -c, -s or -p option
937 is chosen. See "Calendar Mode"
938 Notes:
940 o Remind normally prints a blank line after each reminder; if the
942 last character of the body is "%", the blank line will not be
943 printed.
944 o Substitutions a, b, c, e, f, g, h, i, j, k, l, u and v all are
946 replaced with "today" if the current date equals the trigger
947 date, or "tomorrow" if the trigger date is one day after the
948 current date. Thus, they are not the same as substitutions
949 built up from the simpler %w, %y, etc. sequences.
950 o Any of the substitutions dealing with time (0 through 9 and '!')
952 produce undefined results if used in a reminder that does not
953 have an AT keyword. Also, if a reminder has a delta and may be
954 triggered on several days, the time substitutions ignore the
955 date. Thus, the %1 substitution may report that a meeting is in
956 15 minutes, for example, even though it may only be in 2 days
957 time, because a delta has triggered the reminder. It is recom‐
958 mended that you use the time substitutions only in timed
959 reminders with no delta that are designed to be queued for timed
960 activation.
961 o Capital letters can be used in the substitution sequence, in
963 which case the first character of the substituted string is cap‐
964 italized (if it is normally a lower-case letter.)
965 o All other characters following a "%" sign are simply copied. In
967 particular, to get a "%" sign out, use "%%" in the body. To
968 start the body of a reminder with a space, use "% ", since
969 Remind normally scans for the first non-space character after a
970 MSG, CAL or RUN token.
971
973 In addition to being a keyword in the REM command, OMIT is a command in
974 its own right. Its syntax is:
975 OMIT day month [year]
977 The OMIT command is used to "globally" omit certain days (usually holi‐
979 days). These globally-omitted days are skipped by the "-" and "+"
980 forms of back and delta. Some examples:
981 OMIT 1 Jan
983 OMIT 7 Sep 1992
984 The first example specifies a holiday that occurs on the same date each
986 year - New Year's Day. The second example specifies a holiday that
987 changes each year - Labour Day. For these types of holidays, you must
988 create an OMIT command for each year. (Later, in the description of
989 expressions and some of the more advanced features of Remind, you will
990 see how to automate this for some cases.)
991 As with the REM command, you can use shorthand specifiers for dates;
993 the following are equivalent:
994 OMIT 7 Sep 1992
996 OMIT 1992-09-07
997 For convenience, you can use a delta and MSG or RUN keyword in the OMIT
999 command. The following sequences are exactly equivalent:
1000 OMIT 1 Jan
1002 REM 1 Jan +4 MSG New year's day is %b!
1003 and
1005 OMIT 1 Jan +4 MSG New year's day is %b!
1007 THE BEFORE, AFTER AND SKIP KEYWORDS
1009 Normally, days that are omitted, whether by a global OMIT command or
1011 the local OMIT or OMITFUNC keywords in a REM statement, only affect the
1012 counting of the -back or the +delta. For example, suppose you have a
1013 meeting every Wednesday. Suppose, too, that you have indicated 11 Nov
1014 as a holiday:
1015 OMIT 11 Nov +4 MSG Remembrance Day
1017 REM Wed +1 MSG Code meeting %b.
1018 The above sequence will issue a reminder about a meeting for 11 Novem‐
1020 ber 1992, which is a Wednesday. This is probably incorrect. There are
1021 three options:
1022 BEFORE This keyword moves the reminder to before any omitted days.
1024 Thus, in the above example, use of BEFORE would cause the meet‐
1025 ing reminder to be triggered on Tuesday, 10 November 1992.
1026 AFTER This keyword moves the reminder to after any omitted days. In
1028 the above example, the meeting reminder would be triggered on
1029 Thursday, 12 November 1992.
1030 SKIP This keyword causes the reminder to be skipped completely on any
1032 omitted days. Thus, in the above example, the reminder would
1033 not be triggered on 11 November 1992. However, it would be
1034 triggered as usual on the following Wednesday, 18 November 1992.
1035 The BEFORE and AFTER keywords move the trigger date of a reminder to
1037 before or after a block of omitted days, respectively. Suppose you
1038 normally run a backup on the first day of the month. However, if the
1039 first day of the month is a weekend or holiday, you run the backup on
1040 the first working day following the weekend or holiday. You could use:
1041 REM 1 OMIT Sat Sun AFTER RUN do_backup
1043 Let's examine how the trigger date is computed. The 1 specifies the
1045 first day of the month. The local OMIT keyword causes the AFTER key‐
1046 word to move the reminder forward past weekends. Finally, the AFTER
1047 keyword will keep moving the reminder forward until it has passed any
1048 holidays specified with global OMIT commands.
1049
1051 Remind allows you to include other files in your reminder script, simi‐
1052 lar to the C preprocessor #include directive. For example, your system
1053 administrator may maintain a file of holidays or system-wide reminders.
1054 You can include these in your reminder script as follows:
1055 INCLUDE /usr/share/remind/holidays
1057 INCLUDE /usr/share/remind/reminders
1058 (The actual pathnames vary from system to system - ask your system
1060 administrator.)
1061 INCLUDE files can be nested up to a depth of 8.
1063 If you specify a filename of "-" in the INCLUDE command, Remind will
1065 begin reading from standard input.
1066 If you specify a directory as the argument to INCLDUE, then Remind will
1068 process all files in that directory that match the shell patterm
1069 "*.rem". The files are processed in sorted order; the sort order
1070 matches that used by the shell when it expands "*.rem".
1071
1074 If you include other files in your reminder script, you may not always
1075 entirely trust the contents of the other files. For example, they may
1076 contain RUN-type reminders that could be used to access your files or
1077 perform undesired actions. The RUN command can restrict this: If you
1078 include the command RUN OFF in your top-level reminder script, any
1079 reminder or expression that would normally execute a system command is
1080 disabled. RUN ON will re-enable the execution of system commands.
1081 Note that the RUN ON command can only be used in your top-level
1082 reminder script; it will not work in any files accessed by the INCLUDE
1083 command. This is to protect you from someone placing a RUN ON command
1084 in an included file. However, the RUN OFF command can be used at top
1085 level or in an included file.
1086 If you run Remind with the -r command-line option, RUN-type reminders
1088 and the shell() function will be disabled, regardless of any RUN com‐
1089 mands in the reminder script. However, any command supplied with the
1090 -k option will still be executed.
1091 One use of the RUN command is to provide a secure interface between
1093 Remind and the Elm mail system. The Elm system can automatically scan
1094 incoming mail for reminder or calendar entries, and place them in your
1095 calendar file. To use this feature, you should set the calendar file‐
1096 name option under Elm to be something like "~/.reminders.in", not your
1097 main reminder file! This is so that any RUN ON commands mailed to you
1098 can never be activated.
1099 Then, you can use the Elm scan message for calendar entries command to
1101 place reminders prefaced by "->" into .reminders.in. In your main
1102 .reminders file, include the following lines:
1103 RUN OFF # Disable RUN
1105 INCLUDE .reminders.in
1106 RUN ON # Re-enable RUN
1107 In addition, Remind contains a few other security features. It will
1109 not read a file that is group- or world-writable. It will not run set-
1110 uid. If it reads a file you don't own, it will disable RUN and the
1111 shell() function. And if it is run as root, it will only read files
1112 owned by root.
1113
1115 When Remind first issues a reminder, it prints a message like this:
1116 Reminders for Friday, 30th October, 1992 (today):
1118 (The banner is not printed if any of the calendar-producing options is
1120 used, or if the -k option is used.)
1121 The BANNER command lets you change the format. It should appear before
1123 any REM commands. The format is:
1124 BANNER format
1126 The format is similar to the body of a REM command. It is passed
1128 through the substitution filter, with an implicit trigger of the cur‐
1129 rent system date. Thus, the default banner is equivalent to:
1130 BANNER Reminders for %w, %d%s %m, %y%o:
1132 You can disable the banner completely with BANNER %. Or you can create
1134 a custom banner:
1135 BANNER Hi - here are your reminders for %y-%t-%r:
1137
1139 Sometimes, it is necessary to temporarily change the global OMITs that
1140 are in force for a few reminders. Three commands allow you to do this:
1141 PUSH-OMIT-CONTEXT
1143 This command saves the current global OMITs on an internal
1144 stack.
1145 CLEAR-OMIT-CONTEXT
1147 This command clears all of the global OMITs, starting you off
1148 with a "clean slate."
1149 POP-OMIT-CONTEXT
1151 This command restores the global OMITs that were saved by the
1152 most recent PUSH-OMIT-CONTEXT.
1153 For example, suppose you have a block of reminders that require a clear
1155 OMIT context, and that they also introduce unwanted global OMITs that
1156 could interfere with later reminders. You could use the following
1157 fragment:
1158 PUSH-OMIT-CONTEXT # Save the current context
1160 CLEAR-OMIT-CONTEXT # Clean the slate
1161 # Block of reminders goes here
1162 POP-OMIT-CONTEXT # Restore the saved omit context
1163
1165 In certain contexts, to be described later, Remind will accept expres‐
1166 sions for evaluation. Remind expressions resemble C expressions, but
1167 operate on different types of objects.
1168 DATA TYPES
1170 Remind expressions operate on five types of objects:
1172 INT The INT data type consists of the integers representable in one
1174 machine word. The INT data type corresponds to the C "int"
1175 type.
1176 STRING The STRING data type consists of strings of characters. It is
1178 somewhat comparable to a C character array, but more closely
1179 resembles the string type in BASIC.
1180 TIME The TIME data type consists of times of the day. The TIME data
1182 type is internally stored as an integer representing the number
1183 of minutes since midnight.
1184 DATE The DATE data type consists of dates (later than 1 January
1186 1990.) Internally, DATE objects are stored as the number of
1187 days since 1 January 1990.
1188 DATETIME
1190 The DATETIME data type consists of a date and time together.
1191 Internally, DATETIME objects are stored as the number of minutes
1192 since midnight, 1 January 1990. You can think of a DATETIME
1193 object as being the combination of DATE and TIME parts.
1194 CONSTANTS
1196 The following examples illustrate constants in Remind expressions:
1198 INT constants
1200 12, 36, -10, 0, 1209
1201 STRING constants
1203 "Hello there", "This is a test", "\n\gosd\w", ""
1204 Note that the empty string is represented by "", and that back‐
1206 slashes in a string are not interpreted specially, as in they
1207 are in C.
1208 TIME constants
1210 12:33, 0:01, 14:15, 16:42, 12.16, 13.00, 1.11
1211 Note that TIME constants are written in 24-hour format. Either
1213 the period or colon can be used to separate the minutes from the
1214 hours. However, Remind will consistently output times using
1215 only one separator character. (The output separator character
1216 is chosen at compile-time.)
1217 DATE constants
1219 DATE constants are expressed as 'yyyy/mm/dd' or 'yyyy-mm-dd',
1220 and the single quotes must be supplied. This distinguishes date
1221 constants from division or subtraction of integers. Examples:
1222 ´1993/02/22', '1992-12-25', '1999/01/01'
1224 Note that DATE values are printed without the quotes. Although
1226 either '-' or '/' is accepted as a date separator on input, when
1227 dates are printed, only one will be used. The choice of whether
1228 to use '-' or '/' is made at compile-time. Note also that ver‐
1229 sions of Remind prior to 03.00.01 did not support date con‐
1230 stants. In those versions, you must create dates using the
1231 date() function. Also, versions prior to 03.00.02 did not sup‐
1232 port the '-' date separator.
1233 DATETIME constants
1235 DATETIME constants are expressed similarly to DATE constants
1236 with the addition of an "@HH:MM" part. For example:
1237 ´2008-04-05@23:11', '1999/02/03@14:06', '2001-04-07@08:30'
1239 DATETIME values are printed without the quotes. Notes about
1241 date and time separator characters for DATE and TIME constants
1242 apply also to DATETIME constants.
1243 OPERATORS
1245 Remind has the following operators. Operators on the same line have
1247 equal precedence, while operators on lower lines have lower precedence
1248 than those on higher lines. The operators approximately correspond to
1249 C operators.
1250 ! - (unary logical negation and arithmetic negation)
1252 * / %
1253 + -
1254 < <= > >=
1255 == !=
1256 &&
1257 ||
1258 DESCRIPTION OF OPERATORS
1260 ! Logical negation. Can be applied to an INT type. If the oper‐
1262 and is non-zero, returns zero. Otherwise, returns 1.
1263 - Unary minus. Can be applied to an INT. Returns the negative of
1265 the operand.
1266 * Multiplication. Returns the product of two INTs.
1268 / Integer division. Returns the quotient of two INTs, discarding
1270 the remainder.
1271 % Modulus. Returns the remainder upon dividing one INT by
1273 another.
1274 + Has several uses. These are:
1276 INT + INT - returns the sum of two INTs.
1278 INT + TIME or TIME + INT - returns a TIME obtained by adding INT
1280 minutes to the original TIME.
1281 INT + DATE or DATE + INT - returns a DATE obtained by adding INT
1283 days to the original DATE.
1284 INT + DATETIME or DATETIME + INT - returns a DATETIME obtained
1286 by adding INT minutes to the original DATETIME.
1287 STRING + STRING - returns a STRING that is the concatenation of
1289 the two original STRINGs.
1290 STRING + anything or anything + STRING - converts the non-STRING
1292 argument to a STRING, and then performs concatenation. See the
1293 coerce() function.
1294 - Has several uses. These are:
1296 INT - INT - returns the difference of two INTs.
1298 DATE - DATE - returns (as an INT) the difference in days between
1300 two DATEs.
1301 TIME - TIME - returns (as an INT) the difference in minutes
1303 between two TIMEs.
1304 DATETIME - DATETIME - returns (as an INT) the difference in min‐
1306 utes between two DATETIMEs.
1307 DATE - INT - returns a DATE that is INT days earlier than the
1309 original DATE.
1310 TIME - INT - returns a TIME that is INT minutes earlier than the
1312 original TIME.
1313 DATETIME - INT - returns a DATETIME that is INT minutes earlier
1315 than the original DATETIME.
1316 <, <=, >, and >=
1318 These are the comparison operators. They can take operands of
1319 any type, but both operands must be of the same type. The com‐
1320 parison operators return 1 if the comparison is true, or 0 if it
1321 is false. Note that string comparison is done following the
1322 lexical ordering of characters on your system, and that upper
1323 and lower case are distinct for these operators.
1324 ==, != == tests for equality, returning 1 if its operands are equal,
1326 and 0 if they are not. != tests for inequality.
1327 If the operands are not of the same type, == returns 0 and !=
1329 returns 1. Again, string comparisons are case-sensitive.
1330 && This is the logical AND operator. Both of its operands must be
1332 of type INT. It returns 1 if both operands are non-zero, and 0
1333 otherwise.
1334 || This is the logical OR operator. Both of its operands must be
1336 of type INT. It returns 1 if either operand is non-zero, and 0
1337 otherwise.
1338 NOTES
1340 Operators of equal precedence are always evaluated from left to right,
1342 except where parentheses dictate otherwise. This is important, because
1343 the enhanced "+" operator is not necessarily associative. For example:
1344 1 + 2 + "string" + 3 + 4 yields "3string34"
1346 1 + (2 + "string") + (3 + 4) yields "12string7"
1347 12:59 + 1 + "test" yields "13:00test"
1348 12:59 + (1 + "test") yields "12:591test"
1349 The logical operators are not so-called short-circuit operators, as
1351 they are in C. Both operands are always evaluated. Thus, an expres‐
1352 sion such as:
1353 (f!=0) && (100/f <= 3)
1355 will cause an error if f is zero.
1357 VARIABLES
1359 Remind allows you to assign values to variables. The SET command is
1361 used as follows:
1362 SET var expr
1364 Var is the name of a variable. It must start with a letter or under‐
1366 score, and consist only of letters, digits and underscores. Only the
1367 first 12 characters of a variable name are significant. Variable names
1368 are not case sensitive; thus, "Afoo" and "afOo" are the same variable.
1369 Examples:
1370 SET a 10 + (9*8)
1372 SET b "This is a test"
1373 SET mydir getenv("HOME")
1374 SET time 12:15
1375 SET date today()
1376 Note that variables themselves have no type. They take on the type of
1378 whatever you store in them.
1379 To delete a variable, use the UNSET command:
1381 UNSET var [var...]
1383 For example, to delete all the variables declared above, use:
1385 UNSET a b mydir time date
1387 SYSTEM VARIABLES
1389 In addition to the regular user variables, Remind has several "system
1391 variables" that are used to query or control the operating state of
1392 Remind. System variables are available starting from version 03.00.07
1393 of Remind.
1394 All system variables begin with a dollar sign '$'. They can be used in
1396 SET commands and expressions just as regular variables can. All system
1397 variables always hold values of a specified type. In addition, some
1398 system variables cannot be modified, and you cannot create new system
1399 variables. System variables can be initialized on the command line
1400 with the -i option, but you may need to quote them to avoid having the
1401 shell interpret the dollar sign. System variable names are not case-
1402 sensitive.
1403 The following system variables are defined. Those marked "read-only"
1405 cannot be changed with the SET command. All system variables hold val‐
1406 ues of type INT, unless otherwise specified.
1407 $CalcUTC
1409 If 1 (the default), then Remind uses C library functions to cal‐
1410 culate the number of minutes between local and Universal Time
1411 Coordinated. This affects astronomical calculations (sunrise()
1412 for example.) If 0, then you must supply the number of minutes
1413 between local and Universal Time Coordinated in the $MinsFromUTC
1414 system variable.
1415 $CalMode (read-only)
1417 If non-zero, then the -c option was supplied on the command
1418 line.
1419 $Daemon (read-only)
1421 If the daemon mode -z was invoked, contains the number of min‐
1422 utes between wakeups. If not running in daemon mode, contains
1423 0. For the MS-DOS version, always contains 0.
1424 $DateSep
1426 This variable can be set only to "/" or "-". It holds the char‐
1427 acter used to separate portions of a date when Remind prints a
1428 DATE or DATETIME value.
1429 $DefaultPrio
1431 The default priority assigned to reminders without a PRIORITY
1432 clause. You can set this as required to adjust the priorities
1433 of blocks of reminders without having to type priorities for
1434 individual reminders. At startup, $DefaultPrio is set to 5000;
1435 it can range from 0 to 9999.
1436 $DontFork (read-only)
1438 If non-zero, then the -c option was supplied on the command
1439 line. For the MS-DOS version, always contains 1.
1440 $DontTrigAts (read-only)
1442 If non-zero, then the -a option was supplied on the command
1443 line. For the MS-DOS version, always contains 0.
1444 $DontQueue (read-only)
1446 If non-zero, then the -q option was supplied on the command
1447 line. For the MS-DOS version, always contains 1.
1448 $EndSent (STRING type)
1450 Contains a list of characters that end a sentence. The MSF key‐
1451 word inserts two spaces after these characters. Initially,
1452 $EndSent is set to ".!?" (period, exclamation mark, and question
1453 mark.)
1454 $EndSentIg (STRING type)
1456 Contains a list of characters that should be ignored when MSF
1457 decides whether or not to place two spaces after a sentence.
1458 Initially, is set to "'>)]}"+CHAR(34) (single-quote, greater-
1459 than, right parenthesis, right bracket, right brace, and double-
1460 quote.)
1461 For example, the default values work as follows:
1463 MSF He said, "Huh! (Two spaces will follow this.)" Yup.
1465 because the final parenthesis and quote are ignored (for the
1467 purposes of spacing) when they follow a period.
1468 $FirstIndent
1470 The number of spaces by which to indent the first line of a MSF-
1471 type reminder. The default is 0.
1472 $FoldYear
1474 The standard Unix library functions may have difficulty dealing
1475 with dates later than 2037. If this variable is set to 1, then
1476 the UTC calculations "fold back" years later than 2037 before
1477 using the Unix library functions. For example, to find out
1478 whether or not daylight savings time is in effect in June, 2077,
1479 the year is "folded back" to 2010, because both years begin on a
1480 Monday, and both are non-leapyears. The rules for daylight sav‐
1481 ings time are thus presumed to be identical for both years, and
1482 the Unix library functions can handle 2010. By default, this
1483 variable is 0. Set it to 1 if the sun or UTC functions misbe‐
1484 have for years greater than 2037.
1485 $FormWidth
1487 The maximum width of each line of text for formatting MSF-type
1488 reminders. The default is 72. If an MSF-type reminder contains
1489 a word too long to fit in this width, it will not be truncated -
1490 the width limit will be ignored.
1491 $HushMode (read-only)
1493 If non-zero, then the -h option was supplied on the command
1494 line.
1495 $IgnoreOnce (read-only)
1497 If non-zero, then the -o option was supplied on the command
1498 line, or a date different from today's true date was supplied.
1499 If non-zero, then ONCE directives will be ignored.
1500 $InfDelta (read-only)
1502 If non-zero, then the -t option was supplied on the command
1503 line.
1504 $LatDeg, $LatMin, $LatSec
1506 These specify the latitude of your location. $LatDeg can range
1507 from -90 to 90, and the others from -59 to 59. Northern lati‐
1508 tudes are positive; southern ones are negative. For southern
1509 latitudes, all three components should be negative.
1510 $Location (STRING type)
1512 This is a string specifying the name of your location. It is
1513 usually the name of your town or city. It can be set to what‐
1514 ever you like, but good style indicates that it should be kept
1515 consistent with the latitude and longitude system variables.
1516 $LongDeg, $LongMin, $LongSec
1518 These specify the longitude of your location. $LongDeg can
1519 range from -180 to 180. Western longitudes are positive; east‐
1520 ern ones are negative.
1521 The latitude and longitude information is required for the func‐
1523 tions sunrise() and sunset(). Default values can be compiled
1524 into Remind, or you can SET the correct values at the start of
1525 your reminder scripts.
1526 $MaxSatIter
1528 The maximum number of iterations for the SATISFY clause
1529 (described later.) Must be at least 10.
1530 $MinsFromUTC
1532 The number of minutes between Universal Time Coordinated and
1533 local time. If $CalcUTC is non-zero, this is calculated upon
1534 startup of Remind. Otherwise, you must set it explicitly. If
1535 $CalcUTC is zero, then $MinsFromUTC is used in the astronomical
1536 calculations. You must adjust it for daylight savings time
1537 yourself. Also, if you want to initialize $MinsFromUTC using
1538 the -i command-line option, you must also set $CalcUTC to 0 with
1539 the -i option.
1540 $NextMode (read-only)
1542 If non-zero, then the -n option was supplied on the command
1543 line.
1544 $NumQueued (read-only)
1546 Contains the number of reminders queued so far for background
1547 timed triggering. For MS-DOS, always returns 0.
1548 $NumTrig (read-only)
1550 Contains the number of reminders triggered for the current date.
1551 One use for this variable is as follows: Suppose you wish to
1552 shade in the box of a PostScript calendar whenever a holiday is
1553 triggered. You could save the value of $NumTrig in a regular
1554 variable prior to executing a block of holiday reminders. If
1555 the value of $NumTrig after the holiday block is greater than
1556 the saved value, then at least one holiday was triggered, and
1557 you can execute the command to shade in the calendar box. (See
1558 the section "Calendar Mode".)
1559 Note that $NumTrig is affected only by REM commands; triggers in
1561 IFTRIG commands do not affect it.
1562 $PrefixLineNo (read-only)
1564 If non-zero, then the -l option was supplied on the command
1565 line.
1566 $PSCal (read-only)
1568 If non-zero, then the -p option was supplied on the command
1569 line.
1570 $RunOff (read-only)
1572 If non-zero, the RUN directives are disabled.
1573 $SimpleCal (read-only)
1575 Set to a non-zero value if either of the -p or -s command-line
1576 options was supplied.
1577 $SortByDate (read-only)
1579 Set to 0 if no -g option is used, 1 if sorting by date in
1580 ascending order, or 2 if sorting by date in descending order.
1581 $SortByPrio (read-only)
1583 Set to 0 if no -g option is used, 1 if sorting by priority in
1584 ascending order, or 2 if sorting by priority in descending
1585 order.
1586 $SortByTime (read-only)
1588 Set to 0 if no -g option is used, 1 if sorting by time in
1589 ascending order, or 2 if sorting by time in descending order.
1590 $SubsIndent
1592 The number of spaces by which all lines (except the first) of an
1593 MSF-type reminder should be indented. The default is 0.
1594 Note: If any of the calendar modes are in effect, then the values of
1596 $Daemon, $DontFork, $DontTrigAts, $DontQueue, $HushMode, $IgnoreOnce,
1597 $InfDelta, and $NextMode are not meaningful.
1598 $TimeSep
1600 This variable can be set only to ":" or ".". It holds the char‐
1601 acter used to separate portions of a time when Remind prints a
1602 TIME or DATETIME value.
1603 $UntimedFirst (read-only)
1605 Set to 1 if the -g option is used with a fourth sort character
1606 of "d"; set to 0 otherwise.
1607 BUILT-IN FUNCTIONS
1609 Remind has a plethora of built-in functions. The syntax for a function
1611 call is the same as in C - the function name, followed a comma-sepa‐
1612 rated list of arguments in parentheses. Function names are not case-
1613 sensitive. If a function takes no arguments, it must be followed by
1614 "()" in the function call. Otherwise, Remind will interpret it as a
1615 variable name, and probably not work correctly.
1616 In the descriptions below, short forms are used to denote acceptable
1618 types for the arguments. The characters "i", "s", "d", "t" and "q"
1619 denote INT, STRING, DATE, TIME and DATETIME arguments, respectively.
1620 If an argument can be one of several types, the characters are concate‐
1621 nated. For example, "di_arg" denotes an argument that can be a DATE or
1622 an INT. "x_arg" denotes an argument that can be of any type. The type
1623 of the argument is followed by an underscore and an identifier naming
1624 the argument.
1625 The built-in functions are:
1627 abs(i_num)
1629 Returns the absolute value of num.
1630 access(s_file, si_mode)
1632 Tests the access permissions for the file file. Mode can be a
1633 string, containing a mix of the characters "rwx" for read, write
1634 and execute permission testing. Alternatively, mode can be a
1635 number as described in the UNIX access(2) system call. The
1636 function returns 0 if the file can be accessed with the speci‐
1637 fied mode, and -1 otherwise.
1638 args(s_fname)
1640 Returns the number of arguments expected by the user-defined
1641 function fname, or -1 if no such user-defined function exists.
1642 Note that this function examines only user-defined functions,
1643 not built-in functions. Its main use is to determine whether or
1644 not a particular user-defined function has been defined previ‐
1645 ously. The args() function is available only in versions of
1646 Remind from 03.00.04 and up.
1647 asc(s_string)
1649 Returns an INT that is the ASCII code of the first character in
1650 string. As a special case, asc("") returns 0.
1651 baseyr()
1653 Returns the "base year" that was compiled into Remind (normally
1654 1990.) All dates are stored internally as the number of days
1655 since 1 January of baseyr().
1656 char(i_i1 [,i_i2...])
1658 This function can take any number of INT arguments. It returns
1659 a STRING consisting of the characters specified by the argu‐
1660 ments. Note that none of the arguments can be 0, unless there
1661 is only one argument. As a special case, char(0) returns "".
1662 Note that because Remind does not support escaping of characters
1664 in strings, the only way to get a double-quote in a string is to
1665 use char(34).
1666 choose(i_index, x_arg1 [,x_arg2...])
1668 Choose must take at least two arguments, the first of which is
1669 an INT. If index is n, then the nth subsequent argument is
1670 returned. If index is less than 1, then arg1 is returned. If
1671 index is greater than the number of subsequent arguments, then
1672 the last argument is returned. Examples:
1673 choose(0, "foo", 1:13, 1000) returns "foo"
1675 choose(1, "foo", 1:13, 1000) returns "foo"
1676 choose(2, "foo", 1:13, 1000) returns 1:13
1677 choose(3, "foo", 1:13, 1000) returns 1000
1678 choose(4, "foo", 1:13, 1000) returns 1000
1679 Note that all arguments to choose() are always evaluated.
1680 coerce(s_type, x_arg)
1682 This function converts arg to the specified type, if such con‐
1683 version is possible. Type must be one of "INT", "STRING",
1684 "DATE", "TIME" or "DATETIME" (case-insensitive). The conversion
1685 rules are as follows:
1686 If arg is already of the type specified, it is returned
1688 unchanged.
1689 If type is "STRING", then arg is converted to a string consist‐
1691 ing of its printed representation.
1692 If type is "DATE", then an INT arg is converted by interpreting
1694 it as the number of days since 1 January baseyr(). A STRING arg
1695 is converted by attempting to read it as if it were a printed
1696 date. A DATETIME is converted to a date by dropping the time
1697 component. A TIME arg cannot be converted to a date.
1698 If type is "TIME", then an INT arg is converted by interpreting
1700 it as the number of minutes since midnight. A STRING arg is
1701 converted by attempting to read it as if it were a printed time.
1702 A DATETIME is converted to a time by dropping the date compo‐
1703 nent. A DATE arg cannot be converted to a time.
1704 If type is "DATETIME", then an INT arg is converted by inter‐
1706 preting it as the number of minutes since midnight, 1 January
1707 baseyr(). A STRING is converted by attempting to read it as if
1708 it were a printed datetime. Other types cannot be converted to
1709 a datetime.
1710 If type is "INT", then DATE, TIME and DATETIME arguments are
1712 converted using the reverse of procedures described above. A
1713 STRING arg is converted by parsing it as an integer.
1714 current()
1716 Returns the current date and time as a DATETIME object. This
1717 may be the actual date and time, or may be the date and time
1718 supplied on the command line.
1719 date(i_y, i_m, i_d)
1721 The date() function returns a DATE object with the year, month
1722 and day components specified by y, m and d.
1723 datetime(args)
1725 The datetime() function can take anywhere from two to five argu‐
1726 ments. It always returns a DATETIME generated from its argu‐
1727 ments.
1728 If you supply two arguments, the first must be a DATE and the
1730 second a TIME.
1731 If you supply three arguments, the first must be a DATE and the
1733 second and third must be INTs. The second and third arguments
1734 are interpreted as hours and minutes and converted to a TIME.
1735 If you supply four arguments, the first three must be INTs,
1737 interpreted as the year, month and day. The fourth argument
1738 must be a TIME.
1739 Finally, if you supply five arguments, they must all be INTs and
1741 are interpreted as year, month, day, hour and minute.
1742 dawn([dq_date])
1744 Returns the time of "civil dawn" on the specified date. If date
1745 is omitted, defaults to today(). If a datetime object is sup‐
1746 plied, only the date component is used.
1747 day(dq_date)
1749 This function takes a DATE or DATETIME as an argument, and
1750 returns an INT that is the day-of-month component of date.
1751 daysinmon(i_m, i_y)
1753 Returns the number of days in month m (1-12) of the year y.
1754 defined(s_var)
1756 Returns 1 if the variable named by var is defined, or 0 if it is
1757 not.
1758 Note that defined() takes a STRING argument; thus, to check if
1759 variable X is defined, use:
1760 defined("X")
1762 and not:
1764 defined(X)
1766 The second example will attempt to evaluate X, and will return
1768 an error if it is undefined or not of type STRING.
1769 dosubst(s_str [,d_date [,t_time]]) or dosubst(s_str [,q_datetime])
1771 Returns a STRING that is the result of passing str through the
1772 substitution filter described earlier. The parameters date and
1773 time (or datetime) establish the effective trigger date and time
1774 used by the substitution filter. If date and time are omitted,
1775 they default to today() and now().
1776 Note that if str does not end with "%", a newline character will
1778 be added to the end of the result. Also, calling dosubst() with
1779 a date that is in the past (i.e., if date < today()) will pro‐
1780 duce undefined results.
1781 Dosubst() is only available starting from version 03.00.04 of
1783 Remind.
1784 dusk([dq_date])
1786 Returns the time of "civil twilight" on the specified date. If
1787 date is omitted, defaults to today().
1788 easterdate(dqi_arg)
1790 If arg is an INT, then returns the date of Easter Sunday for the
1791 specified year. If arg is a DATE or DATETIME, then returns the
1792 date of the next Easter Sunday on or after arg. (The time com‐
1793 ponent of a datetime is ignored.)
1794 evaltrig(s_trigger [,dq_start])
1796 Evaluates trigger as if it were a REM or IFTRIG trigger specifi‐
1797 cation and returns the trigger date as a DATE (or as a DATETIME
1798 if there is an AT clause.) Returns a negative INT if no trigger
1799 could be computed.
1800 Normally, evaltrig finds a trigger date on or after today. If
1802 you supply the start argument, then it scans starting from
1803 there.
1804 For example, the expression:
1806 evaltrig("Mon 1", '2008-10-07')
1808 returns '2008-11-03', since that is the first date on or after 7
1810 October 2008 that satisfies "Mon 1".
1811 If you want to see how many days it is from the first Monday in
1813 October, 2008 to the first Monday in November, 2008, use:
1814 evaltrig("Mon 1", '2008-11-01') - evaltrig("Mon 1", '2008-10-01')
1816 and the answer is 28. The trigger argument to evaltrig can have
1818 all the usual trigger clauses (OMIT, AT, SKIP, etc.) but cannot
1819 have a SATISFY, MSG, etc. reminder-type clause.
1820 filedate(s_filename)
1822 Returns the modification date of filename. If filename does not
1823 exist, or its modification date is before the year baseyr(),
1824 then 1 January of baseyr() is returned.
1825 filedatetime(s_filename)
1827 Returns the modification date and time of filename. If filename
1828 does not exist, or its modification date is before the year
1829 baseyr(), then midnight, 1 January of baseyr() is returned.
1830 filedir()
1832 Returns the directory that contains the current file being pro‐
1833 cessed. It may be a relative or absolute pathname, but is guar‐
1834 anteed to be correct for use in an INCLUDE command as follows:
1835 INCLUDE [filedir()]/stuff
1837 This includes the file "stuff" in the same directory as the cur‐
1839 rent file being processed.
1840 filename()
1842 Returns (as a STRING) the name of the current file being pro‐
1843 cessed by Remind. Inside included files, returns the name of
1844 the included file.
1845 getenv(s_envvar)
1847 Similar to the getenv(2) system call. Returns a string repre‐
1848 senting the value of the specified environment variable.
1849 Returns "" if the environment variable is not defined. Note
1850 that the names of environment variables are generally case-sen‐
1851 sitive; thus, getenv("HOME") is not the same as getenv("home").
1852 hour(tq_time)
1854 Returns the hour component of time.
1855 iif(si_test1, x_arg1, [si_test2, x_arg2,...], x_default)
1857 If test1 is not zero or the null string, returns arg1. Other‐
1858 wise, if test2 is not zero or the null string, returns arg2, and
1859 so on. If all of the test arguments are false, returns default.
1860 Note that all arguments are always evaluated. This function
1861 accepts an odd number of arguments - note that prior to version
1862 03.00.05 of Remind, it accepted 3 arguments only. The 3-argu‐
1863 ment version of iif() is compatible with previous versions of
1864 Remind.
1865 index(s_search, s_target [,i_start)
1867 Returns an INT that is the location of target in the string
1868 search. The first character of a string is numbered 1. If tar‐
1869 get does not exist in search, then 0 is returned.
1870 The optional parameter start specifies the position in search at
1872 which to start looking for target.
1873 isdst([d_date [,t_time]]) or isdst(q_datetime)
1875 Returns a positive number if daylight savings time is in effect
1876 on the specified date and time. Date defaults to today() and
1877 time defaults to midnight.
1878 Note that this function is only as reliable as the C run-time
1880 library functions. It is available starting with version
1881 03.00.07 of Remind.
1882 isleap(idq_arg)
1884 Returns 1 if arg is a leap year, and 0 otherwise. Arg can be an
1885 INT, DATE or DATETIME object. If a DATE or DATETIME is sup‐
1886 plied, then the year component is used in the test.
1887 isomitted(dq_date)
1889 Returns 1 if date is omitted, given the current global OMIT con‐
1890 text. Returns 0 otherwise. (If a datetime is supplied, only
1891 the date part is used.) Note that any local OMIT or OMITFUNC
1892 clauses are not taken into account by this function.
1893 hebdate(i_day, s_hebmon [,idq_yrstart [,i_jahr [,i_aflag]]])
1895 Support for Hebrew dates - see the section "The Hebrew Calendar"
1896 hebday(dq_date)
1898 Support for Hebrew dates - see the section "The Hebrew Calendar"
1899 hebmon(dq_date)
1901 Support for Hebrew dates - see the section "The Hebrew Calendar"
1902 hebyear(dq_date)
1904 Support for Hebrew dates - see the section "The Hebrew Calendar"
1905 language()
1907 Returns a STRING naming the language supported by Remind. (See
1908 "Foreign Language Support.") By default, Remind is compiled to
1909 support English messages, so this function returns "English".
1910 For other languages, this function will return the English name
1911 of the language (e.g. "German") Note that language() is not
1912 available in versions of Remind prior to 03.00.02.
1913 lower(s_string)
1915 Returns a STRING with all upper-case characters in string con‐
1916 verted to lower-case.
1917 max(x_arg1 [,x_arg2...)
1919 Can take any number of arguments, and returns the maximum. The
1920 arguments can be of any type, but must all be of the same type.
1921 They are compared as with the > operator.
1922 min(x_arg1 [,x_arg2...)
1924 Can take any number of arguments, and returns the minimum. The
1925 arguments can be of any type, but must all be of the same type.
1926 They are compared as with the < operator.
1927 minsfromutc([d_date [,t_time]]) or minsfromutc(q_datetime)
1929 Returns the number of minutes from Universal Time Coordinated
1930 (formerly GMT) to local time on the specified date and time.
1931 Date defaults to today() and time defaults to midnight. If
1932 local time is before UTC, the result is negative. Otherwise,
1933 the result is positive.
1934 Note that this function is only as reliable as the C run-time
1936 library functions. It is available starting with version
1937 03.00.07 of Remind.
1938 minute(tq_time)
1940 Returns the minute component of time.
1941 mon(dqi_arg)
1943 If arg is of DATE or DATETIME type, returns a string that names
1944 the month component of the date. If arg is an INT from 1 to 12,
1945 returns a string that names the month.
1946 monnum(dq_date)
1948 Returns an INT from 1 to 12, representing the month component of
1949 date.
1950 moondate(i_phase [,d_date [,t_time]]) or moondate(i_phase, q_datetime)
1952 This function returns the date of the first occurrence of the
1953 phase phase of the moon on or after date and time. Phase can
1954 range from 0 to 3, with 0 signifying new moon, 1 first quarter,
1955 2 full moon, and 3 third quarter. If date is omitted, it
1956 defaults to today(). If time is omitted, it defaults to mid‐
1957 night.
1958 For example, the following returns the date of the next full
1960 moon:
1961 SET fullmoon moondate(2)
1963 moontime(i_phase [,d_date [,t_time]]) or moontime(i_phase, q_datetime)
1965 This function returns the time of the first occurrence of the
1966 phase phase of the moon on or after date and time. Phase can
1967 range from 0 to 3, with 0 signifying new moon, 1 first quarter,
1968 2 full moon, and 3 third quarter. If date is omitted, it
1969 defaults to today(). If time is omitted, it defaults to mid‐
1970 night. Moontime() is intended to be used in conjunction with
1971 moondate(). The moondate() and moontime() functions are accu‐
1972 rate to within a couple of minutes of the times in "Old Farmer's
1973 Almanac" for Ottawa, Ontario.
1974 For example, the following returns the date and time of the next
1976 full moon:
1977 MSG Next full moon at [moontime(2)] on [moondate(2)]
1979 moondatetime(i_phase [,d_date [,t_time]]) or moondatetime(i_phase,
1981 q_datetime)
1982 This function is similar to moondate and moontime, but returns a
1983 DATETIME result.
1984 moonphase([d_date [,t_time]]) or moonphase(q_datetime)
1986 This function returns the phase of the moon on date and time,
1987 which default to today() and midnight, respectively. The
1988 returned value is an integer from 0 to 359, representing the
1989 phase of the moon in degrees. 0 is a new moon, 180 is a full
1990 moon, 90 is first-quarter, etc.
1991 nonomitted(dq_start, dq_end [,s_wkday...])
1993 This function returns the number of non-omitted days between
1994 start and end. If start is non-omitted, then it is counted.
1995 end is never counted.
1996 Note that end must be greater than or equal to start or an error
1998 is reported. In addition to using the global OMIT context, you
1999 can supply additional arguments that are names of weekdays to be
2000 omitted. However, in a REM command, any local OMITFUNC clause
2001 is not taken into account by this function.
2002 For example, the following line sets a to 11 (assuming no global
2004 OMITs):
2005 set a nonomitted('2007-08-01', '2007-08-16', "Sat", "Sun")
2007 because Thursday, 16 August 2007 is the 11th working day (not
2009 counting Saturday and Sunday) after Wednesday, 1 August 2007.
2010 nonomitted has various uses. For example, many schools run on a
2012 six-day cycle and the day number is not incremented on holidays.
2013 Suppose the school year starts with Day 1 on 4 September 2007.
2014 The following reminder will label day numbers in a calendar:
2015 IF today() >= '2007-09-04'
2017 set daynum nonomitted('2007-09-04', today(), "Sat", "Sun")
2018 REM OMIT SAT SUN SKIP CAL Day [(daynum % 6) + 1]
2019 ENDIF
2020 Obviously, the answer you get from nonomitted depends on the
2022 global OMIT context. If you use moveable OMITs, you may get
2023 inconsistent results.
2024 Here is a more complex use for nonomitted. My garbage collec‐
2026 tion follows two interleaved 14-day cycles: One Friday, garbage
2027 and paper recycling ("Black Box") are collected. The next Fri‐
2028 day, garbage and plastic recycling ("Blue Box") are collected.
2029 If any of Monday-Friday is a holiday, collection is delayed
2030 until the Saturday. Here's a way to encode these rules:
2031 fset _garbhol(x) wkdaynum(x) == 5 && nonomitted(x-4, x+1) < 5
2033 REM 12 November 1999 *14 AFTER OMITFUNC _garbhol MSG Black Box
2034 REM 19 November 1999 *14 AFTER OMITFUNC _garbhol MSG Blue Box
2035 Here's how it works: The _garbhol(x) user-defined function
2037 returns 1 if and only if (1) x is a Friday and (2) there is at
2038 least one OMITted day from the previous Monday up to and includ‐
2039 ing the Friday.
2040 The first REM statement sets up the 14-day black-box cycle. The
2042 AFTER keyword makes it move collection to the Saturday if _garb‐
2043 hol returns 1. The second REM statement sets up the 14-day
2044 blue-box cycle with a similar adjustment made by AFTER in con‐
2045 junction with _garbhol.
2046 now() Returns the current system time, as a TIME type. This may be
2048 the actual time, or a time supplied on the command line.
2049 ord(i_num)
2051 Returns a string that is the ordinal number num. For example,
2052 ord(2) returns "2nd", and ord(213) returns "213th".
2053 ostype()
2055 Returns "UNIX". Remind used to run on OS/2 and MS-DOS, but does
2056 not any longer.
2057 plural(i_num [,s_str1 [,s_str2]])
2059 Can take from one to three arguments. If one argument is sup‐
2060 plied, returns "s" if num is not 1, and "" if num is 1.
2061 If two arguments are supplied, returns str1 + "s" if num is not
2063 1. Otherwise, returns str1.
2064 If three arguments are supplied, returns str1 if num is 1, and
2066 str2 otherwise.
2067 psmoon(i_phase [,i_size [,s_note [,i_notesize]]])
2069 [DEPRECATED] Returns a STRING consisting of PostScript code to
2070 draw a moon in the upper-left hand corner of the calendar box.
2071 Phase specifies the phase of the moon, and is 0 (new moon), 1
2072 (first quarter), 2 (full moon) or 3 (third quarter). If size is
2073 specified, it controls the radius of the moon in PostScript
2074 units (1/72 inch.) If it is not specified or is negative, the
2075 size of the day-number font is used.
2076 For example, the following four lines place moon symbols on the
2078 PostScript calendar:
2079 REM [moondate(0)] PS [psmoon(0)]
2081 REM [moondate(1)] PS [psmoon(1)]
2082 REM [moondate(2)] PS [psmoon(2)]
2083 REM [moondate(3)] PS [psmoon(3)]
2084 If note is specified, the text is used to annotate the moon dis‐
2086 play. The font is the same font used for calendar entries. If
2087 notesize is given, it specifies the font size to use for the
2088 annotation, in PostScript units (1/72 inch.) If notesize is not
2089 given, it defaults to the size used for calendar entries. (If
2090 you annotate the display, be careful not to overwrite the day
2091 number -- Remind does not check for this.) For example, if you
2092 want the time of each new moon displayed, you could use this in
2093 your reminder script:
2094 REM [moondate(0)] PS [psmoon(0, -1, moontime(0)+"")]
2096 Note how the time is coerced to a string by concatenating the
2098 null string.
2099 psshade(i_gray) or psshade(i_red, i_green, i_blue)
2101 [DEPRECATED] Returns a STRING that consists of PostScript com‐
2102 mands to shade a calendar box. Num can range from 0 (completely
2103 black) to 100 (completely white.) If three arguments are given,
2104 they specify red, green and blue intensity from 0 to 100.
2105 Here's an example of how to use this:
2106 REM Sat Sun PS [psshade(95)]
2108 The above command emits PostScript code to lightly shade the
2110 boxes for Saturday and Sunday in a PostScript calendar.
2111 Note that psmoon and psshade are deprecated; instead you should
2113 use the SPECIAL SHADE and SPECIAL MOON reminders as described in
2114 "Out-of-Band Reminders."
2115 realcurrent()
2117 Returns (as a DATETIME) the true date and time of day as pro‐
2118 vided by the operating system. This is in contrast to cur‐
2119 rent(), which may return a time supplied on the command line.
2120 realnow()
2122 Returns the true time of day as provided by the operating sys‐
2123 tem. This is in contrast to now(), which may return a time sup‐
2124 plied on the command line.
2125 realtoday()
2127 Returns the date as provided by the operating system. This is
2128 in contrast to Remind's concept of "today", which may be changed
2129 if it is running in calendar mode, or if a date has been sup‐
2130 plied on the command line.
2131 sgn(i_num)
2133 Returns -1 if num is negative, 1 if num is positive, and 0 if
2134 num is zero.
2135 shell(s_cmd [,i_maxlen])
2137 Executes cmd as a system command, and returns the first 511
2138 characters of output resulting from cmd. Any whitespace charac‐
2139 ter in the output is converted to a space. Note that if RUN OFF
2140 has been executed, or the -r command-line option has been used,
2141 shell() will result in an error, and cmd will not be executed.
2142 If maxlen is specified, then shell() returns the first maxlen
2144 characters of output (rather than the first 511). If maxlen is
2145 specified as a negative number, then all the output from cmd is
2146 returned.
2147 slide(d_start, i_amt [,s_wkday...])
2149 This function is the inverse of nonomitted. It adds amt days
2150 (which can be negative) to start, not counting omitted days.
2151 The optional wkday arguments are additional weekday names to
2152 omit.
2153 Consider this example:
2155 OMIT 14 May 2009
2157 SET a slide('2009-05-13', 5, "Sat", "Sun")
2158 In this case, a is set to 2009-05-21. That's because we slide
2160 forward by 5 days, not including Thursday, May 14 or Saturday
2161 and Sunday, May 16 and 17. You can go backwards, too, so:
2162 OMIT 14 May 2009
2164 SET a slide('2009-05-21', -5, "Sat", "Sun")
2165 takes a back to 2009-05-13.
2167 strlen(s_str)
2169 Returns the length of str.
2170 substr(s_str, i_start [,i_end])
2172 Returns a STRING consisting of all characters in str from start
2173 up to and including end. Characters are numbered from 1. If
2174 end is not supplied, then it defaults to the length of str.
2175 sunrise([dq_date])
2177 Returns a TIME indicating the time of sunrise on the specified
2178 date (default today().) In high latitudes, there may be no sun‐
2179 rise on a particular day, in which case sunrise() returns the
2180 INT 0 if the sun never sets, or 1440 if it never rises.
2181 sunset([dq_date])
2183 Returns a TIME indicating the time of sunset on the specified
2184 date (default today().) In high latitudes, there may be no sun‐
2185 set on a particular day, in which case sunset() returns the INT
2186 0 if the sun never rises, or 1440 if it never sets.
2187 The functions sunrise() and sunset() are based on an algorithm
2189 in "Almanac for Computers for the year 1978" by L. E. Doggett,
2190 Nautical Almanac Office, USNO. They require the latitude and
2191 longitude to be specified by setting the appropriate system
2192 variables. (See "System Variables".) The sun functions should
2193 be accurate to within about 2 minutes for latitudes lower than
2194 60 degrees. The functions are available starting from version
2195 03.00.07 of Remind.
2196 time(i_hr, i_min)
2198 Creates a TIME with the hour and minute components specified by
2199 hr and min.
2200 today()
2202 Returns Remind's notion of "today." This may be the actual sys‐
2203 tem date, or a date supplied on the command line, or the date of
2204 the calendar entry currently being computed.
2205 trigdate()
2207 Returns the calculated trigger date of the last REM or IFTRIG
2208 command. If used in the body of a REM command, returns that
2209 command's trigger date. If the most recent REM command did not
2210 yield a computable trigger date, returns the integer 0.
2211 trigdatetime()
2213 Similar to trigdate(), but returns a DATETIME if the most recent
2214 triggerable REM command had an AT clause. If there was no AT
2215 clause, returns a DATE. If no trigger could be computed,
2216 returns the integer 0.
2217 trigger(d_date [,t_time [,i_utcflag]]) or trigger(q_datetime
2219 [,i_utcflag])
2220 Returns a string suitable for use in a REM command or a SCANFROM
2221 or UNTIL clause, allowing you to calculate trigger dates in
2222 advance. Note that in earlier versions of Remind, trigger was
2223 required to convert a date into something the REM command could
2224 consume. However, in this version of Remind, you can omit it.
2225 Note that trigger() always returns its result in English, even
2226 for foreign-language versions of Remind. This is to avoid prob‐
2227 lems with certain C libraries that do not handle accented char‐
2228 acters properly. Normally, the date and time are the local date
2229 and time; however, if utcflag is non-zero, the date and time are
2230 interpreted as UTC times, and are converted to local time.
2231 Examples:
2232 trigger('1993/04/01')
2234 returns "1 April 1993",
2236 trigger('1994/08/09', 12:33)
2238 returns "9 August 1994 AT 12:33", as does:
2240 trigger('1994/08/09@12:33').
2242 Finally:
2244 trigger('1994/12/01', 03:00, 1)
2246 returns "30 November 1994 AT 22:00" for EST, which is 5 hours
2248 behind UTC. The value for your time zone may differ.
2249 trigtime()
2251 Returns the time of the last REM command with an AT clause. If
2252 the last REM did not have an AT clause, returns the integer 0.
2253 trigvalid()
2255 Returns 1 if the value returned by trigdate() is valid for the
2256 most recent REM command, or 0 otherwise. Sometimes REM commands
2257 cannot calculate a trigger date. For example, the following REM
2258 command can never be triggered:
2259 REM Mon OMIT Mon SKIP MSG Impossible!
2261 typeof(x_arg)
2263 Returns "STRING", "INT", "DATE", "TIME" or "DATETIME", depending
2264 on the type of arg.
2265 tzconvert(q_datetime, s_srczone [,s_dstzone])
2267 Converts datetime from the time zone named by srczone to the
2268 time zone named by dstzone. If dstzone is omitted, the default
2269 system time zone is used. The return value is a DATETIME. Time
2270 zone names are system-dependent; consult your operating system
2271 for legal values. Here is an example:
2272 tzconvert('2007-07-08@01:14', "Canada/Eastern", "Canada/Pacific")
2274 returns
2276 2007-07-07@22:14
2278 upper(s_string)
2280 Returns a STRING with all lower-case characters in string con‐
2281 verted to upper-case.
2282 value(s_varname [,x_default])
2284 Returns the value of the specified variable. For example,
2285 value("X"+"Y") returns the value of variable XY, if it is
2286 defined. If XY is not defined, an error results.
2287 However, if you supply a second argument, it is returned if the
2289 varname is not defined. The expression value("XY", 0) will
2290 return 0 if XY is not defined, and the value of XY if it is
2291 defined.
2292 version()
2294 Returns a string specifying the version of Remind. For version
2295 03.00.04, returns "03.00.04". It is guaranteed that as new ver‐
2296 sions of Remind are released, the value returned by version()
2297 will strictly increase, according to the rules for string order‐
2298 ing.
2299 weekno([dq_date, [i_wkstart, [i_daystart]]])
2301 Returns the week number of the year. If no arguments are sup‐
2302 plied, returns the ISO 8601 week number for today(). If one
2303 argument date is supplied, then returns the ISO 8601 week number
2304 for that date. If two arguments are supplied, then wkstart must
2305 range from 0 to 6, and represents the first day of the week
2306 (with 0 being Sunday and 6 being Saturday.). If wkstart is not
2307 supplied, then it defaults to 1. If the third argument daystart
2308 is supplied, then it specifies when Week 1 starts. If daystart
2309 is less than or equal to 7, then Week 1 starts on the first
2310 wkstart on or after January daystart. Otherwise, Week 1 starts
2311 on the first wkstart on or after December daystart. If omitted,
2312 daystart defaults to 29 (following the ISO 8601 definition.)
2313 wkday(dqi_arg)
2315 If arg is a DATE or DATETIME, returns a string representing the
2316 day of the week of the date. If arg is an INT from 0 to 6,
2317 returns the corresponding weekday ("Sunday" to "Saturday").
2318 wkdaynum(dq_date)
2320 Returns a number from 0 to 6 representing the day-of-week of the
2321 specified date. (0 represents Sunday, and 6 represents Satur‐
2322 day.)
2323 year(dq_date)
2325 Returns a INT that is the year component of date.
2326
2328 An extremely powerful feature of Remind is its macro capability, or
2329 "expression pasting."
2330 In almost any situation where Remind is not expecting an expression,
2332 you can "paste" an expression in. To do this, surround the expression
2333 with square brackets. For example:
2334 REM [mydate] MSG foo
2336 This evaluates the expression "mydate", where "mydate" is presumably
2338 some pre-computed variable, and then "pastes" the result into the com‐
2339 mand-line for the parser to process.
2340 A formal description of this is: When Remind encounters a "pasted-in"
2342 expression, it evaluates the expression, and coerces the result to a
2343 STRING. It then substitutes the string for the pasted-in expression,
2344 and continues parsing. Note, however, that expressions are evaluated
2345 only once, not recursively. Thus, writing:
2346 ["[a+b]"]
2348 causes Remind to read the token "[a+b]". It does not interpret this as
2350 a pasted-in expression. In fact, the only way to get a literal left-
2351 bracket into a reminder is to use ["["].
2352 You can use expression pasting almost anywhere. However, there are a
2354 few exceptions:
2355 o If Remind is expecting an expression, as in the SET command, or
2357 the IF command, you should not include square brackets. FOr
2358 example, use:
2359 SET a 4+5
2361 and not:
2362 SET a [4+5]
2363 o You cannot use expression pasting for the first token on a line.
2365 For example, the following will not work:
2366 ["SET"] a 1
2368 This restriction is because Remind must be able to unambiguously
2370 determine the first token of a line for the flow-control com‐
2371 mands (to be discussed later.)
2372 In fact, if Remind cannot determine the first token on a line,
2374 it assumes that it is a REM command. If expression-pasting is
2375 used, Remind assumes it is a REM command. Thus, the following
2376 three commands are equivalent:
2377 REM 12 Nov 1993 AT 13:05 MSG BOO!
2379 12 Nov 1993 AT 13:05 MSG BOO!
2380 [12] ["Nov " + 1993] AT [12:05+60] MSG BOO!
2381 o You cannot use expression-pasting to determine the type (MSG,
2383 CAL, etc.) of a REM command. You can paste expressions before
2384 and after the MSG, etc keywords, but cannot do something like
2385 this:
2386 REM ["12 Nov 1993 AT 13:05 " + "MSG" + " BOO!"]
2388 COMMON PITFALLS IN EXPRESSION PASTING
2390 Remember, when pasting in expressions, that extra spaces are not
2392 inserted. Thus, something like:
2393 REM[expr]MSG[expr]
2395 will probably fail.
2397 If you use an expression to calculate a delta or back, ensure that the
2399 result is a positive number. Something like:
2400 REM +[mydelta] Nov 12 1993 MSG foo
2402 will fail if mydelta happens to be negative.
2404
2406 Remind has commands that control the flow of a reminder script. Nor‐
2407 mally, reminder scripts are processed sequentially. However, IF and
2408 related commands allow you to process files conditionally, and skip
2409 sections that you don't want interpreted.
2410 THE IF COMMAND
2412 The IF command has the following form:
2414 IF expr
2416 t-command
2417 t-command...
2418 ELSE
2419 f-command
2420 f-command...
2421 ENDIF
2422 Note that the commands are shown indented for clarity. Also, the ELSE
2424 portion can be omitted. IF commands can be nested up to a small limit,
2425 probably around 8 or 16 levels of nesting, depending on your system.
2426 If the expr evaluates to a non-zero INT, or a non-null STRING, then the
2428 IF portion is considered true, and the t-commands are executed. If
2429 expr evaluates to zero or null, then the f-commands (if the ELSE por‐
2430 tion is present) are executed. If expr is not of type INT or STRING,
2431 then it is an error.
2432 Examples:
2434 IF defined("want_hols")
2436 INCLUDE /usr/share/remind/holidays
2437 ENDIF
2438 IF today() > '1992/2/10'
2440 set missed_ap "You missed it!"
2441 ELSE
2442 set missed_ap "Still have time..."
2443 ENDIF
2444 THE IFTRIG COMMAND
2446 The IFTRIG command is similar to an IF command, except that it computes
2448 a trigger (as in the REM command), and evaluates to true if a corre‐
2449 sponding REM command would trigger. Examples:
2450 IFTRIG 1 Nov
2452 ; Executed on 1 Nov
2453 ELSE
2454 ; Executed except on 1 Nov
2455 ENDIF
2456 IFTRIG 1 -1 OMIT Sat Sun +4
2458 ; Executed on last working day of month,
2459 ; and the 4 working days preceding it
2460 ELSE
2461 ; Executed except on above days
2462 ENDIF
2463 Note that the IFTRIG command computes a trigger date, which can be
2465 retrieved with the trigdate() function. You can use all of the normal
2466 trigger components, such as UNTIL, delta, etc in the IFTRIG command.
2467
2469 In addition to the built-in functions, Remind allows you to define your
2470 own functions. The FSET command does this for you:
2471 FSET fname(args) expr
2473 Fname is the name of the function, and follows the convention for nam‐
2475 ing variables. Args is a comma-separated list of arguments, and expr
2476 is an expression. Args can be empty, in which case you define a func‐
2477 tion taking no parameters. Here are some examples:
2478 FSET double(x) 2*x
2480 FSET yeardiff(date1, date2) year(date1) - year(date2)
2481 FSET since(x) ord(year(trigdate())-x)
2482 The last function is useful in birthday reminders. For example:
2484 REM 1 Nov +12 MSG Dean's [since(1984)] birthday is %b.
2486 Dean was born in 1984. The above example, on 1 November 1992, would
2488 print:
2489 Dean's 8th birthday is today.
2491 Notes:
2493 o If you access a variable in expr that is not in the list of
2495 arguments, the "global" value (if any) is used.
2496 o Function and parameter names are significant only to 12 charac‐
2498 ters.
2499 o The value() function always accesses the "global" value of a
2501 variable, even if it has the same name as an argument. For
2502 example:
2503 fset func(x) value("x")
2505 set x 1
2506 set y func(5)
2507 The above sequence sets y to 1, which is the global value of x.
2509 o User-defined functions may call other functions, including other
2511 user-defined functions. However, recursive calls are not
2512 allowed.
2513 o User-defined functions are not syntax-checked when they are
2515 defined; parsing occurs only when they are called.
2516 o If a user-defined function has the same name as a built-in func‐
2518 tion, it is ignored and the built-in function is used. To pre‐
2519 vent conflicts with future versions of Remind (which may define
2520 more built-in functions), you may wish to name all user-defined
2521 functions beginning with an underscore.
2522
2524 The WARN keyword allows precise control over advance warning in a more
2525 flexible manner than the delta mechanism. It should be followed by the
2526 name of a user-defined function, warn_function.
2527 If a warn_function is supplied, then it must take one argument of type
2529 INT. Remind ignores any delta, and instead calls warn_function succes‐
2530 sively with the arguments 1, 2, 3, ...
2531 Warn_function's return value n is interpreted as follows:
2533 o If n is positive, then the reminder is triggered exactly n days
2535 before its trigger date.
2536 o If n is negative, then it is triggered n days before its trigger
2538 date, not counting OMITted days.
2539 As an example, suppose you wish to be warned of American Independence
2541 Day 5, 3, and 1 days in advance. You could use this:
2542 FSET _wfun(x) choose(x, 5, 3, 1, 0)
2544 REM 4 July WARN _wfun MSG American Independence Day is %b.
2545 NOTES
2547 1 If an error occurs during the evaluation of warn_function, then
2549 Remind stops calling it and simply issues the reminder on its
2550 trigger date.
2551 2 If the absolute-values of the return values of warn_function are
2553 not monotonically decreasing, Remind stops calling it and issues
2554 the reminder on its trigger date.
2555 3 Warn_function should (as a matter of good style) return 0 as the
2557 final value in its sequence of return values. However, a
2558 reminder will always be triggered on its trigger date, regard‐
2559 less of what warn_function does.
2560 Similarly to WARN, the SCHED keyword allows precise control over the
2562 scheduling of timed reminders. It should be followed by the name of a
2563 user-defined function, sched_function.
2564 If a scheduling function is supplied, then it must take one argument of
2566 type INT. Rather than using the AT time, time delta, and time repeat,
2567 Remind calls the scheduling function to determine when to trigger the
2568 reminder. The first time the reminder is queued, the scheduling func‐
2569 tion is called with an argument of 1. Each time the reminder is trig‐
2570 gered, it is re-scheduled by calling the scheduling function again. On
2571 each call, the argument is incremented by one.
2572 The return value of the scheduling function must be an INT or a TIME.
2574 If the return value is a TIME, then the reminder is re-queued to trig‐
2575 ger at that time. If it is a positive integer n, then the reminder is
2576 re-queued to trigger at the previous trigger time plus n minutes.
2577 Finally, if it is a negative integer or zero, then the reminder is re-
2578 queued to trigger n minutes before the AT time. Note that there must
2579 be an AT clause for the SCHED clause to do anything.
2580 Here's an example:
2582 FSET _sfun(x) choose(x, -60, 30, 15, 10, 3, 1, 1, 1, 1, 0)
2584 REM AT 13:00 SCHED _sfun MSG foo
2585 The reminder would first be triggered at 13:00-60 minutes, or at 12:00.
2587 It would next be triggered 30 minutes later, at 12:30. Then, it would
2588 be triggered at 12:45, 12:55, 12:58, 12:59, 13:00, 13:01 and 13:02.
2589 NOTES
2591 1 If an error occurs during the evaluation of sched_func, then
2593 Remind reverts to using the AT time and the delta and repeat
2594 values, and never calls sched_func again.
2595 2 If processing sched_func yields a time earlier than the current
2597 system time, it is repeatedly called with increasing argument
2598 until it yields a value greater than or equal to the current
2599 time. However, if the sequence of values calculated during the
2600 repetition is not strictly increasing, then Remind reverts to
2601 the default behaviour and never calls sched_func again.
2602 3 It is quite possible using sched_func to keep triggering a
2604 reminder even after the AT-time. However, it is not possible to
2605 reschedule a reminder past midnight - no crossing of date bound‐
2606 aries is allowed. Also, it is quite possible to not trigger a
2607 reminder on the AT time when you use a scheduling function.
2608 However, if your scheduling function is terminated (for reasons
2609 1 and 2) before the AT time of the reminder, it will be trig‐
2610 gered at the AT time, because normal processing takes over.
2611 4 Your scheduling functions should (as a matter of good style)
2613 return 0 when no more scheduling is required. See the example.
2614 5 All scheduling functions are evaluated after the entire Remind
2616 script has been read in. So whatever function definitions are
2617 in effect at the end of the script are used.
2618
2620 The form of REM that uses SATISFY is as follows:
2621 REM trigger SATISFY expr
2623 The way this works is as follows: Remind first calculates a trigger
2625 date, in the normal fashion. Next, it sets trigdate() to the calcu‐
2626 lated trigger date. It then evaluates expr. If the result is not the
2627 null string or zero, processing ends. Otherwise, Remind computes the
2628 next trigger date, and re-tests expr. This iteration continues until
2629 expr evaluates to non-zero or non-null, or until the iteration limit
2630 specified with the -x command-line option is reached.
2631 If expr is not satisfied, then trigvalid() is set to 0. Otherwise,
2633 trigvalid() is set to 1. In any event, no error message is issued.
2634 This is really useful only if expr involves a call to the trigdate()
2636 function; otherwise, expr will not change as Remind iterates.
2637 An example of the usefulness of SATISFY: Suppose you wish to be warned
2639 of every Friday the 13th. Your first attempt may be:
2640 # WRONG!
2642 REM Fri 13 +2 MSG Friday the 13th is %b.
2643 But this won't work. This reminder triggers on the first Friday on or
2645 after the 13th of each month. The way to do it is with a more compli‐
2646 cated sequence:
2647 REM 13 SATISFY wkdaynum(trigdate()) == 5
2649 IF trigvalid()
2650 REM [trigdate()] +2 MSG \
2651 Friday the 13th is %b.
2652 ENDIF
2653 Let's see how this works. The SATISFY clause iterates through all the
2655 13ths of successive months, until a trigger date is found whose day-of-
2656 week is Friday (== 5). If a valid date was found, we use the calcu‐
2657 lated trigger date to set up the next reminder.
2658 We could also have written:
2660 REM Fri SATISFY day(trigdate()) == 13
2662 but this would result in more iterations, since "Fridays" occur more
2664 often than "13ths of the month."
2665 This technique of using one REM command to calculate a trigger date to
2667 be used by another command is quite powerful. For example, suppose you
2668 wanted to OMIT Labour day, which is the first Monday in September. You
2669 could use:
2670 # Note: SATISFY 1 is an idiom for "do nothing"
2672 REM Mon 1 Sept SATISFY 1
2673 OMIT [trigdate()]
2674 CAVEAT: This only omits the next Labour Day, not all Labour Days in the
2676 future. This could cause strange results, as the OMIT context can
2677 change depending on the current date. For example, if you use the fol‐
2678 lowing command after the above commands:
2679 REM Mon AFTER msg hello
2681 the result will not be as you expect. Consider producing a calendar
2683 for September, 1992. Labour Day was on Monday, 7 September, 1992.
2684 However, when Remind gets around to calculating the trigger for Tues‐
2685 day, 8 September, 1992, the OMIT command will now be omitting Labour
2686 Day for 1993, and the "Mon AFTER" command will not be triggered. (But
2687 see the description of SCANFROM in the section "Details about Trigger
2688 Computation.")
2689 It is probably best to stay away from computing OMIT trigger dates
2691 unless you keep these pitfalls in mind.
2692 For versions of Remind starting from 03.00.07, you can include a MSG,
2694 RUN, etc. clause in a SATISFY clause as follows:
2695 REM trigger_stuff SATISFY [expr] MSG body
2697 Note that for this case only, the expr after SATISFY must be enclosed
2699 in braces. It must come after all the other components of the trigger,
2700 and immediately before the MSG, RUN, etc. keyword. If expr cannot be
2701 satisfied, then the reminder is not triggered.
2702 Thus, the "Friday the 13th" example can be expressed more compactly as:
2704 REM 13 +2 SATISFY [wkdaynum(trigdate()) == 5] \
2706 MSG Friday the 13th is %b.
2707 And you can trigger a reminder on Mondays, Wednesdays and Thursdays
2709 occurring on odd-numbered days of the month with the following:
2710 REM Mon Wed Thu SATISFY [day(trigdate())%2] \
2712 MSG Here it is!!!
2713 Note that SATISFY and OMITFUNC can often be used to solve the same
2715 problem, though in different ways. Sometimes a SATISFY is cleaner and
2716 sometimes an OMITFUNC; experiment and use whichever seems clearer.
2717
2719 Although the command-line -d option is useful for debugging, it is
2720 often overkill. For example, if you turn on the -dx option for a
2721 reminder file with many complex expressions, you'll get a huge amount
2722 of output. The DEBUG command allows you to control the debugging flags
2723 under program control. The format is:
2724 DEBUG [+flagson] [-flagsoff]
2726 Flagson and flagsoff consist of strings of the characters "extvlf" that
2728 correspond to the debugging options discussed in the command-line
2729 options section. If preceded with a "+", the corresponding group of
2730 debugging options is switched on. Otherwise, they are switched off.
2731 For example, you could use this sequence to debug a complicated expres‐
2732 sion:
2733 DEBUG +x
2735 set a very_complex_expression(many_args)
2736 DEBUG -x
2737 THE DUMPVARS COMMAND
2739 The command DUMPVARS displays the values of variables in memory. Its
2741 format is:
2742 DUMPVARS [var...]
2744 If you supply a space-separated list of variable names, the correspond‐
2746 ing variables are displayed. If you do not supply a list of variables,
2747 then all variables in memory are displayed. To dump a system variable,
2748 put its name in the list of variables to dump. If you put a lone dol‐
2749 lar sign in the list of variables to dump, then all system variables
2750 will be dumped.
2751 THE ERRMSG COMMAND
2753 The ERRMSG command has the following format:
2755 ERRMSG body
2757 The body is passed through the substitution filter (with an implicit
2759 trigger date of today()) and printed to the error output stream. Exam‐
2760 ple:
2761 IF !defined("critical_var")
2763 ERRMSG You must supply a value for "critical_var"
2764 EXIT
2765 ENDIF
2766 THE EXIT COMMAND
2768 The above example also shows the use of the EXIT command. This causes
2770 an unconditional exit from script processing. Any queued timed
2771 reminders are discarded. If you are in calendar mode (described next),
2772 then the calendar processing is aborted.
2773 If you supply an INT-type expression after the EXIT command, it is
2775 returned to the calling program as the exit status. Otherwise, an exit
2776 status of 99 is returned.
2777 THE FLUSH COMMAND
2779 This command simply consists of the word FLUSH on a line by itself.
2781 The command flushes the standard output and standard error streams used
2782 by Remind. This is not terribly useful to most people, but may be use‐
2783 ful if you run Remind as a subprocess of another program, and want to
2784 use pipes for communication.
2785
2787 If you supply the -c, -s or -p command-line option, then Remind runs in
2788 "calendar mode." In this mode, Remind interprets the script repeat‐
2789 edly, performing one iteration through the whole file for each day in
2790 the calendar. Reminders that trigger are saved in internal buffers,
2791 and then inserted into the calendar in the appropriate places.
2792 If you also supply the -a option, then Remind will not include timed
2794 reminders in the calendar.
2795 The -p option is used in conjunction with the Rem2PS program to produce
2797 a calendar in PostScript format. For example, the following command
2798 will send PostScript code to standard output:
2799 remind -p .reminders | rem2ps
2801 You can print a PostScript calendar by piping this to the lpr command.
2803 If you have a reminder script called ".reminders", and you execute this
2805 command:
2806 remind -c .reminders jan 1993
2808 then Remind executes the script 31 times, once for each day in January.
2810 Each time it executes the script, it increments the value of today().
2811 Any reminders whose trigger date matches today() are entered into the
2812 calendar.
2813 MSG and CAL-type reminders, by default, have their entire body inserted
2815 into the calendar. RUN-type reminders are not normally inserted into
2816 the calendar. However, if you enclose a portion of the body in the
2817 %"...%" sequence, only that portion is inserted. For example, consider
2818 the following:
2819 REM 6 Jan MSG %"David's birthday%" is %b
2821 In the normal mode, Remind would print "David's birthday is today" on 6
2823 January. However, in the calendar mode, only the text "David's birth‐
2824 day" is inserted into the box for 6 January.
2825 If you explicitly use the %"...%" sequence in a RUN-type reminder, then
2827 the text between the delimiters is inserted into the calendar. If you
2828 use the sequence %"%" in a MSG or CAL-type reminder, then no calendar
2829 entry is produced for that reminder.
2830 PRESERVING VARIABLES
2832 Because Remind iterates through the script for each day in the calen‐
2834 dar, slow operations may severely reduce the speed of producing a cal‐
2835 endar.
2836 For example, suppose you set the variables "me" and "hostname" as fol‐
2838 lows:
2839 SET me shell("whoami")
2841 SET hostname shell("hostname")
2842 Normally, Remind clears all variables between iterations in calendar
2844 mode. However, if certain variables are slow to compute, and will not
2845 change between iterations, you can "preserve" their values with the
2846 PRESERVE command. Also, since function definitions are preserved
2847 between calendar iterations, there is no need to redefine them on each
2848 iteration. Thus, you could use the following sequence:
2849 IF ! defined("initialized")
2851 set initialized 1
2852 set me shell("whoami")
2853 set hostname shell("hostname")
2854 fset func(x) complex_expr
2855 preserve initialized me hostname
2856 ENDIF
2857 The operation is as follows: On the first iteration through the
2859 script, "initialized" is not defined. Thus, the commands between IF
2860 and ENDIF are executed. The PRESERVE command ensures that the values
2861 of initialized, me and hostname are preserved for subsequent itera‐
2862 tions. On the next iteration, the commands are skipped, since initial‐
2863 ized has remained defined. Thus, time-consuming operations that do not
2864 depend on the value of today() are done only once.
2865 System variables (those whose names start with '$') are automatically
2867 preserved between calendar iterations.
2868 Note that for efficiency, Remind caches the reminder script (and any
2870 INCLUDEd files) in memory when producing a calendar.
2871 Timed reminders are sorted and placed into the calendar in time order.
2873 These are followed by non-timed reminders. Remind automatically places
2874 the time of timed reminders in the calendar according to the -b com‐
2875 mand-line option. Reminders in calendar mode are sorted as if the -g
2876 option had been used; you can change the sort order in calendar mode by
2877 explicitly using the -g option to specify a different order from the
2878 default.
2879 REPEATED EXECUTION
2881 If you supply a repeat parameter on the command line, and do not use
2883 the -c, -p, or -s options, Remind operates in a similar manner to cal‐
2884 endar mode. It repeatedly executes the reminder script, incrementing
2885 today() with each iteration. The same rules about preserving variables
2886 and function definitions apply. Note that using repeat on the command
2887 line also enables the -q option and disables any -z option. As an
2888 example, if you want to see how Remind will behave for the next week,
2889 you can type:
2890 remind .reminders '*7'
2892 If you want to print the dates of the next 1000 days, use:
2894 (echo 'banner %'; echo 'msg [today()]%') | remind - '*1000'
2896
2898 The -i option is used to initialize variables on the Remind command
2899 line. The format is -ivar=expr, where expr is any valid expression.
2900 Note that you may have to use quotes or escapes to prevent the shell
2901 from interpreting special characters in expr. You can have as many -i
2902 options as you want on the command line, and they are processed in
2903 order. Thus, if a variable is defined in one -i option, it can be
2904 referred to by subsequent -i options.
2905 Note that if you supply a date on the command line, it is not parsed
2907 until all options have been processed. Thus, if you use today() in any
2908 of the -i expressions, it will return the same value as realtoday() and
2909 not the date supplied on the command line.
2910 Any variables defined on the command line are preserved as with the
2912 PRESERVE command.
2913 You should not have any spaces between the -i option and the equal
2915 sign; otherwise, strange variable names are created that can only be
2916 accessed with the value() or defined() functions.
2917 You can also define a function on the command line by using:
2919 -ifunc(args)=definition
2921 Be sure to protect special characters from shell interpretation.
2923
2925 The PS and PSFILE reminders pass PostScript code directly to the
2926 printer. They differ in that the PS-type reminder passes its body
2927 directly to the PostScript output (after processing by the substitution
2928 filter) while the PSFILE-type's body should simply consist of a file‐
2929 name. The Rem2PS program will open the file named in the PSFILE-type
2930 reminder, and include its contents in the PostScript output.
2931 The PostScript-type reminders for a particular day are included in the
2933 PostScript output in sorted order of priority. Note that the order of
2934 PostScript commands has a major impact on the appearance of the calen‐
2935 dars. For example, PostScript code to shade a calendar box will oblit‐
2936 erate code to draw a moon symbol if the moon symbol code is placed in
2937 the calendar first. For this reason, you should not provide PS or
2938 PSFILE-type reminders with priorities; instead, you should ensure that
2939 they appear in the reminder script in the correct order. PostScript
2940 code should draw objects working from the background to the foreground,
2941 so that foreground objects properly overlay background ones. If you
2942 prioritize these reminders and run the script using descending sort
2943 order for priorities, the PostScript output will not work.
2944 All of the PostScript code for a particular date is enclosed in a save-
2946 restore pair. However, if several PostScript-type reminders are trig‐
2947 gered for a single day, each section of PostScript is not enclosed in a
2948 save-restore pair - instead, the entire body of included PostScript is
2949 enclosed.
2950 PostScript-type reminders are executed by the PostScript printer before
2952 any regular calendar entries. Thus, regular calendar entries will
2953 overlay the PostScript-type reminders, allowing you to create shaded or
2954 graphical backgrounds for particular days.
2955 Before executing your PostScript code, the origin of the PostScript
2957 coordinate system is positioned to the bottom left-hand corner of the
2958 "box" in the calendar representing today(). This location is exactly
2959 in the middle of the intersection of the bottom and left black lines
2960 delineating the box - you may have to account for the thickness of
2961 these lines when calculating positions.
2962 Several PostScript variables are available to the PostScript code you
2964 supply. All distance and size variables are in PostScript units (1/72
2965 inch.) The variables are:
2966 LineWidth
2968 The width of the black grid lines making up the calendar.
2969 Border The border between the center of the grid lines and the space
2971 used to print calendar entries. This border is normally blank
2972 space.
2973 BoxWidth and BoxHeight
2975 The width and height of the calendar box, from center-to-center
2976 of the black gridlines.
2977 InBoxHeight
2979 The height from the center of the bottom black gridline to the
2980 top of the regular calendar entry area. The space from here to
2981 the top of the box is used only to draw the day number.
2982 /DayFont, /EntryFont, /SmallFont, /TitleFont and /HeadFont
2984 The fonts used to draw the day numbers, the calendar entries,
2985 the small calendars, the calendar title (month, year) and the
2986 day-of-the-week headings, respectively.
2987 DaySize, EntrySize, TitleSize and HeadSize
2989 The sizes of the above fonts. (The size of the small calendar
2990 font is not defined here.) For example, if you wanted to print
2991 the Hebrew date next to the regular day number in the calendar,
2992 use:
2993 REM PS Border BoxHeight Border sub DaySize sub moveto \
2995 /DayFont findfont DaySize scalefont setfont \
2996 ([hebday(today())] [hebmon(today())]) show
2997 Note how /DayFont and DaySize are used.
2999 Note that if you supply PostScript code, it is possible to produce
3001 invalid PostScript files. Always test your PostScript thoroughly with
3002 a PostScript viewer before sending it to the printer. You should not
3003 use any document structuring comments in your PostScript code.
3004
3006 If you use the -z command-line option, Remind runs in the "daemon"
3007 mode. In this mode, no "normal" reminders are issued. Instead, only
3008 timed reminders are collected and queued, and are then issued whenever
3009 they reach their trigger time.
3010 In addition, Remind wakes up every few minutes to check the modifica‐
3012 tion date on the reminder script (the filename supplied on the command
3013 line.) If Remind detects that the script has changed, it re-executes
3014 itself in daemon mode, and interprets the changed script.
3015 In daemon mode, Remind also re-reads the remind script when it detects
3017 that the system date has changed.
3018 In daemon mode, Remind acts as if the -f option had been used, so to
3020 run in the daemon mode in the background, use:
3021 remind -z .reminders &
3023 If you use sh or bash, you may have to use the "nohup" command to
3025 ensure that the daemon is not killed when you log out.
3026
3028 The -g option causes Remind to sort reminders by trigger date, time and
3029 priority before issuing them. Note that reminders are still calculated
3030 in the order encountered in the script. However, rather than being
3031 issued immediately, they are saved in an internal buffer. When Remind
3032 has finished processing the script, it issues the saved reminders in
3033 sorted order. The -g option can be followed by up to four characters
3034 that must all be "a" or "d". The first character specifies the sort
3035 order by trigger date (ascending or descending), the second specifies
3036 the sort order by trigger time and the third specifies the sort order
3037 by priority. If the fourth character is "d", the untimed reminders are
3038 sorted before timed reminders. The default is to sort all fields in
3039 ascending order and to sort untimed reminders after timed reminders.
3040 In ascending order, reminders are issued with the most imminent first.
3042 Descending order is the reverse. Reminders are always sorted by trig‐
3043 ger date, and reminders with the same trigger date are then sorted by
3044 trigger time. If two reminders have the same date and time, then the
3045 priority is used to break ties. Reminders with the same date, time and
3046 priority are issued in the order they were encountered.
3047 You can define a user-defined function called SORTBANNER that takes one
3049 DATE-type argument. In sort mode, the following sequence happens:
3050 If Remind notices that the next reminder to issue has a different trig‐
3052 ger date from the previous one (or if it is the first one to be
3053 issued), then SORTBANNER is called with the trigger date as its argu‐
3054 ment. The result is coerced to a string, and passed through the sub‐
3055 stitution filter with the appropriate trigger date. The result is then
3056 displayed.
3057 Here's an example - consider the following fragment:
3059 # Switch off the normal banner
3061 BANNER %
3062 REM 11 March 1993 ++1 MSG Not so important
3063 REM 17 March 1993 ++7 MSG Way in the future
3064 REM 10 March 1993 MSG Important Reminder
3065 REM 11 March 1993 ++1 MSG Not so important - B
3066 FSET sortbanner(x) iif(x == today(), \
3067 "***** THINGS TO DO TODAY *****", \
3068 "----- Things to do %b -----")
3069 Running this with the -gaa option on 10 March 1993 produces the follow‐
3071 ing output:
3072 ***** THINGS TO DO TODAY *****
3074 Important Reminder
3076 ----- Things to do tomorrow -----
3078 Not so important
3080 Not so important - B
3082 ----- Things to do in 7 days' time -----
3084 Way in the future
3086 You can use the args() built-in function to determine whether or not
3088 SORTBANNER has been defined. (This could be used, for example, to pro‐
3089 vide a default definition for SORTBANNER in a system-wide file included
3090 at the end of the user's file.) Here's an example:
3091 # Create a default sortbanner function if it hasn't already
3093 # been defined
3094 if args("sortbanner") != 1
3095 fset sortbanner(x) "--- Things to do %b ---"
3096 endif
3097
3099 You can define two functions in your script called msgprefix() and msg‐
3100 suffix(). They should each accept one argument, a number from 0 to
3101 9999.
3102 In normal mode, for MSG- and MSF-type reminders, the following sequence
3104 occurs when Remind triggers a reminder:
3105 o If msgprefix() is defined, it is evaluated with the priority of
3107 the reminder as its argument. The result is printed. It is not
3108 passed through the substitution filter.
3109 o The body of the reminder is printed.
3111 o If msgsuffix() is defined, it is evaluated with the priority of
3113 the reminder as its argument. The result is printed. It is not
3114 passed through the substitution filter.
3115 Here's an example: The following definition causes priority-0
3117 reminders to be preceded by "URGENT", and priority-6000 reminders to be
3118 preceded by "(not important)".
3119 fset msgprefix(x) iif(x==0, "URGENT: ", \
3121 x==6000, "(not important) ", "")
3122 In Calendar Mode (with the -c, -s or -p options), an analogous pair of
3124 functions named calprefix() and calsuffix() can be defined. They work
3125 with all reminders that produce an entry in the calendar (i.e., CAL-
3126 and possibly RUN-type reminders as well as MSG-type reminders.)
3127 NOTES
3129 Normally, the body of a reminder is followed by a carriage return.
3131 Thus, the results of msgsuffix() will appear on the next line. If you
3132 don't want this, end the body of the reminder with a percentage sign,
3133 "%". If you want a space between your reminders, simply include a car‐
3134 riage return (char(13)) as part of the msgsuffix() return value.
3135 If Remind has problems evaluating msgprefix(), msgsuffix() or sortban‐
3137 ner(), you will see a lot of error messages. For an example of this,
3138 define the following:
3139 fset msgprefix(x) x/0
3141
3143 Your version of Remind may have been compiled to support a language
3144 other than English. This support may or may not be complete - for
3145 example, all error and usage messages may still be in English. How‐
3146 ever, at a minimum, foreign-language versions of Remind will output
3147 names of months and weekdays in the foreign language. Also, the sub‐
3148 stitution mechanism will substitute constructs suitable for the foreign
3149 language rather than for English.
3150 A foreign-language version of Remind will accept either the English or
3152 foreign-language names of weekdays and months in a reminder script.
3153 However, for compatibility between versions of Remind, you should use
3154 only the English names in your scripts. Also, if your C compiler or
3155 run-time libraries are not "8-bit clean" or don't understand the ISO-
3156 Latin character set, month or day names with accented letters may not
3157 be recognized.
3158
3160 Remind has support for the Hebrew calendar, which is a luni-solar cal‐
3161 endar. This allows you to create reminders for Jewish holidays,
3162 jahrzeits (anniversaries of deaths) and smachot (joyous occasions.)
3163 THE HEBREW YEAR
3165 The Hebrew year has 12 months, alternately 30 and 29 days long. The
3167 months are: Tishrey, Heshvan, Kislev, Tevet, Shvat, Adar, Nisan, Iyar,
3168 Sivan, Tamuz, Av and Elul. In Biblical times, the year started in
3169 Nisan, but Rosh Hashana (Jewish New Year) is now celebrated on the 1st
3170 and 2nd of Tishrey.
3171 In a cycle of 19 years, there are 7 leap years, being years 3, 6, 8,
3173 11, 14, 17 and 19 of the cycle. In a leap year, an extra month of 30
3174 days is added before Adar. The two Adars are called Adar A and Adar B.
3175 For certain religious reasons, the year cannot start on a Sunday,
3177 Wednesday or Friday. To adjust for this, a day is taken off Kislev or
3178 added to Heshvan. Thus, a regular year can have from 353 to 355 days,
3179 and a leap year from 383 to 385.
3180 When Kislev or Heshvan is short, it is called chaser, or lacking. When
3182 it is long, it is called shalem, or full.
3183 The Jewish date changes at sunset. However, Remind will change the
3185 date at midnight, not sunset. So in the period between sunset and mid‐
3186 night, Remind will be a day earlier than the true Jewish date. This
3187 should not be much of a problem in practice.
3188 The computations for the Jewish calendar were based on the program
3190 "hdate" written by Amos Shapir of the Hebrew University of Jerusalem,
3191 Israel. He also supplied the preceding explanation of the calendar.
3192 HEBREW DATE FUNCTIONS
3194 hebday(d_date)
3196 Returns the day of the Hebrew month corresponding to the date
3197 parameter. For example, 12 April 1993 corresponds to 21 Nisan
3198 5753. Thus, hebday('1993/04/12') returns 21.
3199 hebmon(d_date)
3201 Returns the name of the Hebrew month corresponding to date. For
3202 example, hebmon('1993/04/12') returns "Nisan".
3203 hebyear(d_date)
3205 Returns the Hebrew year corresponding to date. For example,
3206 hebyear('1993/04/12') returns 5753.
3207 hebdate(i_day, s_hebmon [,id_yrstart [,i_jahr [,i_aflag]]])
3209 The hebdate() function is the most complex of the Hebrew support
3210 functions. It can take from 2 to 5 arguments. It returns a
3211 DATE corresponding to the Hebrew date.
3212 The day parameter can range from 1 to 30, and specifies the day
3214 of the Hebrew month. The hebmon parameter is a string that must
3215 name one of the Hebrew months specified above. Note that the
3216 month must be spelled out in full, and use the English translit‐
3217 eration shown previously. You can also specify "Adar A" and
3218 "Adar B." Month names are not case-sensitive.
3219 The yrstart parameter can either be a DATE or an INT. If it is
3221 a DATE, then the hebdate() scans for the first Hebrew date on or
3222 after that date. For example:
3223 hebdate(15, "Nisan", '1990/01/01')
3225 returns 1990/03/30, because that is the first occurrence of 15
3227 Nisan on or after 1 January 1990.
3228 If yrstart is an INT, it is interpreted as a Hebrew year. Thus:
3230 hebdate(22, "Kislev", 5756)
3232 returns 1995/12/15, because that date corresponds to 22 Kislev,
3234 5756. Note that none of the Hebrew date functions will work
3235 with dates outside Remind's normal range for dates.
3236 If yrstart is not supplied, it defaults to today().
3238 The jahr modifies the behaviour of hebdate() as follows:
3240 If jahr is 0 (the default), then hebdate() keeps scanning until
3242 it finds a date that exactly satisfies the other parameters.
3243 For example:
3244 hebdate(30, "Adar A", 1993/01/01)
3246 returns 1995/03/02, corresponding to 30 Adar A, 5755, because
3248 that is the next occurrence of 30 Adar A after 1 January, 1993.
3249 This behaviour is appropriate for Purim Katan, which only
3250 appears in leap years.
3251 If jahr is 1, then the date is modified as follows:
3253 o 30 Heshvan is converted to 1 Kislev in years when Heshvan
3255 is chaser
3256 o 30 Kislev is converted to 1 Tevet in years when Kislev is
3258 chaser
3259 o 30 Adar A is converted to 1 Nisan in non-leapyears
3261 o Other dates in Adar A are moved to the corresponding day
3263 in Adar in non-leapyears
3264 This behaviour is appropriate for smachot (joyous occasions) and
3266 for some jahrzeits - see "JAHRZEITS."
3267 if jahr is 2, then the date is modified as follows:
3269 o 30 Kislev and 30 Heshvan are converted to 29 Kislev and
3271 29 Heshvan, respectively, if the month is chaser
3272 o 30 Adar A is converted to 30 Shvat in non-leapyears
3274 o Other dates in Adar A are moved to the corresponding day
3276 in Adar in non-leapyears
3277 if jahr is not 0, 1, or 2, it is interpreted as a Hebrew year,
3279 and the behaviour is calculated as described in the next sec‐
3280 tion, "JAHRZEITS."
3281 The aflag parameter modifies the behaviour of the function for
3283 dates in Adar during leap years. The aflag is only used if
3284 yrstart is a DATE type.
3285 The aflag only affects date calculations if hebmon is specified
3287 as "Adar". In leap years, the following algorithm is followed:
3288 o If aflag is 0, then the date is triggered in Adar B.
3290 This is the default.
3291 o If aflag is 1, then the date is triggered in Adar A.
3293 This may be appropriate for jahrzeits in the Ashkenazi
3294 tradition; consult a rabbi.
3295 o If aflag is 2, then the date is triggered in both Adar A
3297 and Adar B of a leap year. Some Ashkenazim perform
3298 jahrzeit in both Adar A and Adar B.
3299 JAHRZEITS
3301 A jahrzeit is a yearly commemoration of someone's death. It normally
3303 takes place on the anniversary of the death, but may be delayed if
3304 burial is delayed - consult a rabbi for more information.
3305 In addition, because some months change length, it is not obvious which
3307 day the anniversary of a death is. The following rules are used:
3308 o If the death occurred on 30 Heshvan, and Heshvan in the year
3310 after the death is chaser, then the jahrzeit is observed on 29
3311 Heshvan in years when Heshvan is chaser. Otherwise, the
3312 yahrzeit is observed on 1 Kislev when Heshvan is chaser.
3313 o If the death occurred on 30 Kislev, and Kislev in the year after
3315 the death is chaser, then the jahrzeit is observed on 29 Kislev
3316 in years when Kislev is chaser. Otherwise, the yahrzeit is
3317 observed on 1 Tevet when Kislev is chaser.
3318 o If the death occurred on 1-29 Adar A, it is observed on 1-29
3320 Adar in non-leapyears.
3321 o If the death occurred on 30 Adar A, it is observed on 30 Shvat
3323 in a non-leapyear.
3324 Specifying a Hebrew year for the jahr parameter causes the correct be‐
3326 haviour to be selected for a death in that year. You may also have to
3327 specify aflag, depending on your tradition.
3328 The jahrzeit information was supplied by Frank Yellin, who quoted "The
3330 Comprehensive Hebrew Calendar" by Arthur Spier, and "Calendrical Calcu‐
3331 lations" by E. M. Reingold and Nachum Dershowitz.
3332
3334 The SPECIAL keyword is used to transmit "out-of-band" information to
3335 Remind backends, such as tkremind or Rem2PS. They are used only when
3336 piping data from a remind -p line. (Note that the COLOR special is an
3337 exception; it downgrades to the equivalent of MSG in remind's normal
3338 mode of operation.)
3339 The various SPECIALs recognized are particular for each backend; how‐
3341 ever, there are three SPECIALs that all backends should attempt to sup‐
3342 port. They are currently supported by Rem2PS, tkremind and rem2html.
3343 The SHADE special replaces the psshade() function. Use it like this:
3345 REM Sat Sun SPECIAL SHADE 128
3346 REM Mon SPECIAL SHADE 255 0 0
3347 The SHADE keyword is followed by either one or three numbers, from 0 to
3348 255. If one number is supplied, it is interpreted as a grey-scale
3349 value from black (0) to white (255). If three numbers are supplied,
3350 they are interpreted as RGB components from minimum (0) to maximum
3351 (255). The example above shades weekends a fairly dark grey and makes
3352 Mondays a fully-saturated red. (These shadings appear in calendars
3353 produced by Rem2PS, tkremind and rem2html.)
3354 The MOON special replaces the psmoon() function. Use it like this:
3356 REM [moondate(0)] SPECIAL MOON 0
3357 REM [moondate(1)] SPECIAL MOON 1
3358 REM [moondate(2)] SPECIAL MOON 2
3359 REM [moondate(3)] SPECIAL MOON 3
3360 These draw little moons on the various calendars. The complete syntax
3361 of the MOON special is as follows:
3362 ... SPECIAL MOON phase moonsize fontsize msg
3363 Phase is a number from 0 to 3, with 0 representing a new moon, 1 the
3365 first quarter, 2 a full moon and 3 the last quarter.
3366 moonsize is the diameter in PostScript units of the moon to draw. If
3368 omitted or supplied as -1, the backend chooses an appropriate size.
3369 fontsize is the font size in PostScript units of the msg
3371 Msg is additional text that is placed near the moon glyph.
3373 Note that only the Rem2PS backend supports moonsize and fontsize; the
3375 other backends use fixed sizes.
3376 The COLOR special lets you place colored reminders in the calendar.
3378 Use it like this:
3379 REM ... SPECIAL COLOR 255 0 0 This is a bright red reminder
3381 REM ... SPECIAL COLOR 0 128 0 This is a dark green reminder
3382 Immediately following COLOR should be three decimal numbers ranging
3384 from 0 to 255 specifying red, green and blue intensities, respectively.
3385 The rest of the line is the text to put in the calendar.
3386 The COLOR special is "doubly special", because in its normal operating
3388 mode, remind treats a COLOR special just like a MSG-type reminder.
3389 Also, if you invoke Remind with -cc..., then it approximates SPECIAL
3390 COLOR reminders on your terminal.
3391 The WEEK special lets you place annotations such as the week number in
3393 the calendar. For example, this would number each Monday with the ISO
3394 8601 week number. The week number is shown like this: "(Wn)" in this
3395 example, but you can put whatever text you like after the WEEK keyword.
3396 REM Monday SPECIAL WEEK (W[weekno()])
3398
3401 COMMAND ABBREVIATIONS
3402 The following tokens can be abbreviated:
3404 o REM can be omitted - it is implied if no other valid command is
3406 present.
3407 o CLEAR-OMIT-CONTEXT --> CLEAR
3409 o PUSH-OMIT-CONTEXT --> PUSH
3411 o POP-OMIT-CONTEXT --> POP
3413 o DUMPVARS --> DUMP
3415 o BANNER --> BAN
3417 o INCLUDE --> INC
3419 o SCANFROM --> SCAN
3421 NIFTY EXAMPLES
3423 This section is a sampling of what you can do with Remind.
3425 REM 5 Feb 1991 AT 14:00 +45 *30 \
3427 RUN mail -s "Meeting at %2" $LOGNAME </dev/null &
3428 On 5 February, 1991, this reminder will mail you reminders of a 2:00pm
3430 meeting at 1:15, 1:45 and 2:00. The subject of the mail message will
3431 be "Meeting at 2:00pm" and the body of the message will be blank.
3432 REM AT 17:00 RUN echo "5:00pm - GO HOME!" | xless -g +0+0 &
3434 This reminder will pop up an xless window at 5:00pm every day. The
3436 xless window will contain the line "5:00pm - GO HOME!"
3437 REM AT 23:59 RUN (sleep 120; remind -a [filename()]) &
3439 This reminder will run at one minute to midnight. It will cause a new
3441 Remind process to start at one minute past midnight. This allows you
3442 to have a continuous reminder service so you can work through the night
3443 and still get timed reminders for early in the morning. Note that this
3444 trick is no longer necessary, providing you run Remind in daemon mode.
3445 remind -c12 /dev/null Jan 1993
3447 This invocation of Remind will cause it to print a calendar for 1993,
3449 with all entries left blank.
3450 REM CAL [trigdate()-date(year(trigdate()), 1, 1)+1]
3452 This example puts an entry in each box of a calendar showing the number
3454 (1-365 or 366) of the day of the year.
3455 REM Tue 2 Nov SATISFY (year(trigdate())%4) == 0
3457 IF trigvalid()
3458 REM [trigdate()] ++5 MSG \
3459 U.S. Presidential Election!!
3460 ENDIF
3461 This example warns you 5 days ahead of each American presidential elec‐
3463 tion. The first REM command calculates the first Tuesday after the
3464 first Monday in November. (This is equivalent to the first Tuesday on
3465 or after 2 November.) The SATISFY clause ensures that the trigger date
3466 is issued only in election years, which are multiples of 4. The second
3467 REM command actually issues the reminder.
3468 DETAILS ABOUT TRIGGER COMPUTATION
3470 Here is a conceptual description of how triggers are calculated. Note
3472 that Remind actually uses a much more efficient procedure, but the
3473 results are the same as if the conceptual procedure had been followed.
3474 Remind starts from the current date (that is, the value of today()) and
3476 scans forward, examining each day one at a time until it finds a date
3477 that satisfies the trigger, or can prove that no such dates (on or
3478 later than today()) exist.
3479 If Remind is executing a SATISFY-type reminder, it evaluates the
3481 expression with trigdate() set to the date found above. If the expres‐
3482 sion evaluates to zero or the null string, Remind continues the scan‐
3483 ning procedure described above, starting with the day after the trigger
3484 found above.
3485 The SCANFROM clause (having a syntax similar to UNTIL) can modify the
3487 search strategy used. In this case, Remind begins the scanning proce‐
3488 dure at scan_date, which is the date specified in the SCANFROM clause.
3489 For example:
3490 REM Mon 1 SCANFROM 17 Jan 1992 MSG Foo
3492 The example above will always have a trigger date of Monday, 3 February
3494 1992. That is because Remind starts scanning from 17 January 1992, and
3495 stops scanning as soon as it hits a date that satisfies "Mon 1."
3496 The main use of SCANFROM is in situations where you want to calculate
3498 the positions of floating holidays. Consider the Labour Day example
3499 shown much earlier. Labour Day is the first Monday in September. It
3500 can move over a range of 7 days. Consider the following sequence:
3501 REM Mon 1 Sept SCANFROM [today()-7] SATISFY 1
3503 OMIT [trigdate()]
3504 REM Mon AFTER MSG Hello
3506 The SCANFROM clause makes sure that Remind begins scanning from 7 days
3508 before the current date. This ensures that Labour Day for the current
3509 year will continue to be triggered until 7 days after it has occurred.
3510 This allows you to safely use the AFTER keyword as shown.
3511 In general, use SCANFROM as shown for safe movable OMITs. The amount
3513 you should scan back by (7 days in the example above) depends on the
3514 number of possible consecutive OMITted days that may occur, and on the
3515 range of the movable holiday. Generally, a value of 7 is safe.
3516 The FROM clause operates almost like the counterpoint to UNTIL. It
3518 prevents the reminder from triggering before the FROM date. For exam‐
3519 ple, the following reminder:
3520 REM Mon Thu FROM 23 Jul 2007 UNTIL 2 Aug 2007 MSG Test
3522 will trigger on Mondays and Thursdays between 23 July 2007 and 2 August
3524 2007 inclusive.
3525 FROM is really just syntactic sugar; you could implement the reminder
3527 above as follows:
3528 REM Mon Thu SCANFROM [max(today(), '2007-07-23')] \
3530 UNTIL 2 Aug 2007 MSG Test
3531 but that's a lot harder to read. Internally, Remind treats FROM
3533 exactly as illustrated using SCANFROM. For that reason, you cannot use
3534 both FROM and SCANFROM.
3535 Note that if you use one REM command to calculate a trigger date, per‐
3537 form date calculations (addition or subtraction, for example) and then
3538 use the modified date in a subsequent REM command, the results may not
3539 be what you intended. This is because you have circumvented the normal
3540 scanning mechanism. You should try to write REM commands that compute
3541 trigger dates that can be used unmodified in subsequent REM commands.
3542 The file "defs.rem" that comes with the Remind distribution contains
3543 examples.
3544 DETAILS ABOUT TRIGVALID()
3546 The trigvalid() function returns 1 if Remind could find a trigger date
3548 for the previous REM or IFTRIG command. More specifically, it returns
3549 1 if Remind finds a date not before the starting date of the scanning
3550 that satisfies the trigger. In addition, there is one special case in
3551 which trigvalid() returns 1 and trigdate() returns a meaningful result:
3552 If the REM or IFTRIG command did not contain an UNTIL clause, and con‐
3554 tained all of the day, month and year components, then Remind will cor‐
3555 rectly compute a trigger date, even if it happens to be before the
3556 start of scanning. Note that this behaviour is not true for versions
3557 of Remind prior to 03.00.01.
3558
3560 Remind is now supported by Roaring Penguin Software Inc.
3561 (http://www.roaringpenguin.com)
3562 David F. Skoll <dfs@roaringpenguin.com> wrote Remind. The moon code
3564 was copied largely unmodified from "moontool" by John Walker. The sun‐
3565 rise and sunset functions use ideas from programs by Michael Schwartz
3566 and Marc T. Kaufman. The Hebrew calendar support was taken from
3567 "hdate" by Amos Shapir. OS/2 support was done by Darrel Hankerson,
3568 Russ Herman, and Norman Walsh. The supported foreign languages and
3569 their translators are listed below. Languages marked "complete" sup‐
3570 port error messages and usage instructions in that language; all others
3571 only support the substitution filter mechanism and month/day names.
3572 German -- Wolfgang Thronicke
3574 Dutch -- Willem Kasdorp and Erik-Jan Vens
3576 Finnish -- Mikko Silvonen (complete)
3578 French -- Laurent Duperval (complete)
3580 Norwegian -- Trygve Randen
3582 Danish -- Mogens Lynnerup
3584 Polish -- Jerzy Sobczyk (complete)
3586 Brazilian Portuguese -- Marco Paganini (complete)
3588 Italian -- Valerio Aimale
3590 Romanian -- Liviu Daia
3592 Spanish -- Rafa Couto
3594 Icelandic -- Björn Davíðsson
3596
3598 There's no good reason why read-only system variables are not imple‐
3599 mented as functions, or why functions like version(), etc. are not
3600 implemented as read-only system variables.
3601 Hebrew dates in Remind change at midnight instead of sunset.
3603 Language should be selectable at run-time, not compile-time. Don't
3605 expect this to happen soon!
3606 Remind has some built-in limits (for example, number of global OMITs.)
3608
3610 Nachum Dershowitz and Edward M. Reingold, "Calendrical Calculations",
3611 Software-Practice and Experience, Vol. 20(9), Sept. 1990, pp 899-928.
3612 L. E. Doggett, Almanac for computers for the year 1978, Nautical
3614 Almanac Office, USNO.
3615 Richard Siegel and Michael and Sharon Strassfeld, The First Jewish Cat‐
3617 alog, Jewish Publication Society of America.
3618
3620 rem, rem2ps, tkremind
36214th Berkeley Distribution 31 August 2008 REMIND(1)