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 Remind reads its files starting from the beginning to the end, or until
28 it encounters a line whose sole content is "__EOF__" (without the
29 quotes.) Anything after the __EOF__ marker is completely ignored.
30
33 Remind has a slew of options. If you're new to the program, ignore
34 them for now and skip to the section "Reminder Files".
35 -n The -n option causes Remind to print the next occurrence of each
37 reminder in a simple calendar format. You can sort this by date
38 by piping the output through sort(1).
39 -j[n] Runs Remind in "purge" mode to get rid of expired reminders.
41 See the section PURGE MODE for details.
42 -r The -r option disables RUN directives and the shell() function.
44 As of Remind 3.00.17, using -u implies -r.
45 -c[flags]n
47 The -c option causes Remind to produce a calendar that is sent
48 to standard output. If you supply a number n, then a calendar
49 will be generated for n months, starting with the current month.
50 By default, a calendar for only the current month is produced.
51 You can precede n (if any) with a set of flags. The flags are as fol‐
53 lows:
54 '+' causes a calendar for n weeks to be produced.
56 'a' causes Remind to display reminders on the calendar on the day
58 they actually occur as well as on any preceding days specified
59 by the reminder's delta.
60 'l' causes Remind to use VT100 line-drawing characters to draw the
62 calendar. The characters are hard-coded and will only work on
63 terminals that emulate the VT00 line-drawing character set.
64 'u' is similar to 'l', but causes Remind to use UNICODE line-drawing
66 characters to draw the calendar. The characters are hard-coded
67 and will only work on terminals that are set to UTF-8 character
68 encoding.
69 'c' causes Remind to use VT100 escape sequences to approximate SPE‐
71 CIAL COLOR reminders. The approximation is (of necessity) very
72 coarse, because the VT100 only has eight different color
73 sequences, each with one of two brightnesses. A color component
74 greater than 64 is considered "on", and if any of the three
75 color components is greater than 128, the color is considered
76 "bright".
77 -wcol[,pad[,spc]]]
80 The -w option specifies the output width, padding and spacing of
81 the formatted calendar output. Col specifies the number of col‐
82 umns in the output device, and defaults to 80. Pad specifies
83 how many lines to use to "pad" empty calendar boxes. This
84 defaults to 5. If you have many reminders on certain days that
85 make your calendar too large to fit on a page, you can try
86 reducing pad to make the empty boxes smaller. Spc specifies how
87 many blank lines to leave between the day number and the first
88 reminder entry. It defaults to 1.
89 Any of col, pad or spc can be omitted, providing you provide the
91 correct number of commas. Don't use any spaces in the option.
92 -s[a]n The -s option is very similar to the -c option, except that the
94 output calendar is not formatted. It is listed in a "simple
95 format" that can be used as input for more sophisticated calen‐
96 dar-drawing programs. If n starts with "+", then it is inter‐
97 preted as a number of weeks.
98 If you immediately follow the s with the letter a, then Remind
100 displays reminders on the calendar on the day they actually
101 occur as well as on any preceding days specified by the
102 reminder's delta.
103 -p[a]n The -p option is very similar to the -s option, except that the
105 output contains additional information for use by the Rem2PS
106 program, which creates a PostScript calendar. For this option,
107 n cannot start with "+"; it must specify a number of months.
108 The format of the -p output is described in the rem2ps(1) man
109 page. If you immediately follow the p with the letter a, then
110 Remind displays reminders on the calendar on the day they actu‐
111 ally occur as well as on any preceding days specified by the
112 reminder's delta.
113 -l If you use the -l option in conjunction with the -p option, then
116 Remind outputs additional information for back-end programs such
117 as rem2ps. This additional information lets the back-end pro‐
118 grams correlate a reminder with the source file and line number
119 that produced it.
120 -m The -m option causes the -c or -p options to produce a calendar
122 whose first column is Monday rather than Sunday. (This conforms
123 to the international standard.)
124 -v The -v option makes the output of Remind slightly more verbose.
126 Currently, this causes Remind to echo a bad line in case of an
127 error, and to print a security message if a script tests the
128 $RunOff system variable.
129 -o The -o option causes Remind to ignore all ONCE directives.
131 -t The -t option causes Remind to trigger all non-expired
133 reminders, regardless of the delta supplied for each reminder.
134 -tn If you supply a number n after the -t option, then Remind pre‐
136 tends that each non-expired reminder has a delta of n days and
137 triggers reminders accordingly.
138 -h The -h option ("hush...") suppresses certain warning and infor‐
140 mation messages. In particular, if no reminders are triggered,
141 this mode produces no output.
142 -a The -a option causes Remind not to immediately trigger timed
144 reminders that trigger on the current day. It also causes
145 Remind not to place timed reminders in a calendar. If you sup‐
146 ply two or more -a options, then Remind will trigger timed
147 reminders that are in the future, but will not trigger timed
148 reminders whose time has passed. (Regardless of how many -a
149 options you supply, Remind will not include timed reminders in
150 the calendar if at least one -a option is used.)
151 -q The -q option causes Remind not to queue timed reminders for
154 later execution.
155 -f The -f option causes Remind to remain in the foreground when
157 processing queued reminders, rather than forking off a back‐
158 ground process to handle them.
159 -e The -e option diverts error messages (normally sent to the stan‐
161 dard error stream) to the standard output stream.
162 -dchars
164 The -d option enables certain debugging modes. The chars spec‐
165 ify which modes to enable:
166 e Echo all input lines
168 x Trace all expression evaluation
170 t Display all trigger date computation
172 v Dump the variable table after execution of the reminder script
174 l Echo lines when displaying error messages
176 f Trace the reading of reminder files
178 -g[a|d[a|d[a|d[a|d]]]]
180 Normally, reminders are issued in the order in which they are
181 encountered in the reminder script. The -g option cause Remind
182 to sort reminders by date and time prior to issuing them. The
183 optional a and d characters specify the sort order (ascending or
184 descending) for the date, time and priority fields. See the
185 section "Sorting Reminders" for more information.
186 -b[n] Set the time format for the calendar and simple-calendar out‐
189 puts. N can range from 0 to 2, with the default 0. A value of
190 0 causes times to be inserted in 12-hour (am/pm) format. 1
191 causes times to be inserted in 24-hour format, and 2 inhibits
192 the automatic insertion of times in the calendar output.
193 -x[n] Sets the iteration limit for the SATISFY clause of a REM com‐
195 mand. Defaults to 150.
196 -kcmd Instead of simply printing MSG-type reminders, this causes them
198 to be passed to the specific cmd. You must use '%s' where you
199 want the body to appear, and may need to enclose this option in
200 quotes. Note that all shell characters in the body of the
201 reminder are escaped with a backslash, and the entire body of
202 the reminder is passed as a single argument. Note that this
203 option overrides the -r option and the RUN OFF command.
204 As an example, suppose you have an X Window program called xmes‐
206 sage that pops up a window and displays its invocation argu‐
207 ments. You could use:
208 remind '-kxmessage %s &' ...
210 to have all of your MSG-type reminders processed using xmessage.
212 A word of warning: It is very easy to spawn dozens of xmessage
214 processes with the above technique. So be very careful.
215 Because all shell and whitespace characters are escaped, the
216 program you execute with the -k option must be prepared to han‐
217 dle the entire message as a single argument.
218 -z[n] Runs Remind in the daemon mode. If n
220 is supplied, it specifies how often (in minutes) Remind should
221 wake up to check if the reminder script has been changed. N
222 defaults to 1, and can range from 1 to 60. Note that the use of
223 the -z option also enables the -f option.
224 If you supply the option -z0, Remind runs in a special mode
226 called server mode. This is documented in the tkremind man
227 page; see tkremind(1).
228 -uname Runs Remind with the uid and gid of the user specified by name.
230 The option changes the uid and gid as described, and sets the
231 environment variables HOME, SHELL and USER to the home direc‐
232 tory, shell, and user name, respectively, of the specified user.
233 LOGNAME is also set to the specified user name. This option is
234 meant for use in shell scripts that mail reminders to all users.
235 Note that as of Remind 3.00.17, using -u implies -r -- the RUN
236 directive and shell() functions are disabled.
237 Non-root users can also use the -u option. However, in this
239 case, it only changes the environment variables as described
240 above. It does not change the effective uid or gid.
241 -y Causes Remind to synthesize a tag for any reminder that lacks a
243 TAG clause.
244 -ivar=expr
246 Sets the value of the specified var to expr, and preserves var.
247 Expr can be any valid Remind expression. See the section "Ini‐
248 tializing Variables on the Command Line" for more details.
249 -ifunc(args)=definition
251 Allows you to define a function on the command line.
252 If you supply a date on the command line, it must consist of day month
254 year, where day is the day of the month, month is at least the first
255 three letters of the English name of the month, and year is a year (all
256 4 digits) from 1990 to about 2075. You can leave out the day, which
257 then defaults to 1.
258 If you do supply a date on the command line, then Remind uses it,
260 rather than the actual system date, as its notion of "today." This
261 lets you create calendars for future months, or test to see how your
262 reminders will be triggered in the future. Similarly, you can supply a
263 time (in 24-hour format -- for example, 17:15) to set Remind's notion
264 of "now" to a particular time. Supplying a time on the command line
265 also implicitly enables the -q option and disables the -z option.
266 If you would rather specify the date more succinctly, you can supply it
268 as YYYY-MM-DD or YYYY/MM/DD. You can even supply a date and time on
269 the command line as one argument: YYYY-MM-DD@HH:MM.
270 In addition, you can supply a repeat parameter, which has the form
272 *num. This causes Remind to be run num times, with the date increment‐
273 ing on each iteration. You may have to enclose the parameter in quotes
274 to avoid shell expansion. See the subsection "Repeated Execution" in
275 the section "Calendar Mode" for more information.
276
278 Remind uses scripts to control its operation. You can use any text
279 editor capable of creating plain ASCII files to create a Remind script.
280 The commands inside a script can range from the very simple and almost
281 immediately understandable:
282 REM 6 Jan MSG Dianne's birthday
284 to the baroque and obscure:
286 REM [date(thisyear, 1, 1) + 180] ++5 OMIT \
288 sat sun BEFORE MSG [ord(thisyear-1980)] payment due %b!
289 A reminder file consists of commands, with one command per line. Sev‐
291 eral lines can be continued using the backslash character, as in the
292 above example. In this case, all of the concatenated lines are treated
293 as a single line by Remind. Note that if an error occurs, Remind
294 reports the line number of the last line of a continued line.
295 Remind ignores blank lines, and lines beginning with the '#' or ';'
297 characters. You can use the semicolon as a comment character if you
298 wish to pass a Remind script through the C pre-processor, which inter‐
299 prets the '#' character as the start of a pre-processing directive.
300 Note that Remind processes line continuations before anything else.
302 For example:
303 # This is a comment \
305 This line is part of the comment because of line continuation \
306 and so on.
307 REM MSG This line is not ignored (no \ above)
308 Remind is not case sensitive; you can generally use any mixture of
310 upper- or lower-case for commands, parameters, invocation options, etc.
311
313 The most powerful command in a Remind script is the REM command. This
314 command is responsible for issuing reminders. Its syntax is:
315 REM [ONCE] [date_spec] [back] [delta] [repeat] [PRIORITY prio]
317 [SKIP | BEFORE | AFTER] [OMIT omit_list] [OMITFUNC omit_func‐
318 tion] [AT time [tdelta] [trepeat]] [SCHED sched_function] [WARN
319 warn_function] [UNTIL expiry_date | THROUGH last_date] [SCANFROM
320 scan_date | FROM start_date] [DURATION duration] [TAG tag] <MSG
321 | MSF | RUN | CAL | SATISFY | SPECIAL special | PS | PSFILE>
322 body
323 The parts of the REM command can be specified in any order, except that
325 the body must come immediately after the MSG, RUN, CAL, PS, PSFILE or
326 SATISFY keyword.
327 The REM token is optional, providing that the remainder of the command
329 cannot be mistaken for another Remind command such as OMIT or RUN. The
330 portion of the REM command before the MSG, MSF RUN, CAL or SATISFY
331 clause is called a trigger.
332 MSG, MSF, RUN, CAL, SPECIAL, PS and PSFILE
334 These keywords denote the type of the reminder. (SATISFY is more com‐
336 plicated and will be explained later.) A MSG-type reminder normally
337 prints a message to the standard output, after passing the body through
338 a special substitution filter, described in the section "The Substitu‐
339 tion Filter." However, if you have used the -k command-line option,
340 then MSG-type reminders are passed to the appropriate program. Note
341 that the options -c, -s, -p and -n disable the -k option.
342 Note that you can omit the reminder type, in which case it defaults to
344 MSG. So you can write:
345 6 January Dianne's Birthday
347 although this is not recommended.
349 The MSF keyword is almost the same as the MSG keyword, except that the
351 reminder is formatted to fit into a paragraph-like format. Three sys‐
352 tem variables control the formatting of MSF-type reminders - they are
353 $FirstIndent, $SubsIndent and $FormWidth. They are discussed in the
354 section "System Variables." The MSF keyword causes the spacing of your
355 reminder to be altered - extra spaces are discarded, and two spaces are
356 placed after periods and other characters, as specified by the system
357 variables $EndSent and $EndSentIg. Note that if the body of the
358 reminder includes newline characters (placed there with the %_
359 sequence), then the newlines are treated as the beginnings of new para‐
360 graphs, and the $FirstIndent indentation is used for the next line.
361 You can use two consecutive newlines to have spaced paragraphs emitted
362 from a single reminder body.
363 A RUN-type reminder also passes the body through the substitution fil‐
365 ter, but then executes the result as a system command. A CAL-type
366 reminder is used only to place entries in the calendar produced when
367 Remind is run with the -c, -s or -p options.
368 A PS or PSFILE-type reminder is used to pass PostScript code directly
370 to the printer when producing PostScript calendars. This can be used
371 to shade certain calendar entries (see the psshade() function), include
372 graphics in the calendar, or almost any other purpose you can think of.
373 You should not use these types of reminders unless you are an expert
374 PostScript programmer. The PS and PSFILE reminders are ignored unless
375 Remind is run with the -p option. See the section "More about Post‐
376 Script" for more details.
377 A SPECIAL-type reminder is used to pass "out-of-band" information from
379 Remind to a calendar-producing back-end. It should be followed by a
380 word indicating the type of special data being passed. The type of a
381 special reminder depends on the back-end. For the Rem2PS back-end,
382 SPECIAL PostScript is equivalent to a PS-type reminder, and SPECIAL
383 PSFile is equivalent to a PSFILE-type reminder. The body of a SPECIAL
384 reminder is obviously dependent upon the back-end.
385 DATE SPECIFICATIONS
387 A date_spec consists of zero to four parts. These parts are day (day
389 of month), month (month name), year and weekday. Month and weekday are
390 the English names of months and weekdays. At least the first three
391 characters must be used. The following are examples of the various
392 parts of a date_spec:
393 day: 1, 22, 31, 14, 3
395 month: JANUARY, feb, March, ApR, may, Aug
397 year: 1990, 1993, 2030, 95 (interpreted as 1995). The year can range
399 from 1990 to 2075.
400 weekday:
402 Monday, tue, Wed, THU, Friday, saturday, sundAy
403 Note that there can be several weekday components separated by spaces
405 in a date_spec.
406 INTERPRETATION OF DATE SPECIFICATIONS
408 The following examples show how date specifications are interpreted.
410 1. Null date specification - the reminder is triggered every day. The
412 trigger date for a specific run is simply the current system date.
413 2. Only day present. The reminder is triggered on the specified day of
415 each month. The trigger date for a particular run is the closest such
416 day to the current system date. For example:
417 REM 1 MSG First of every month.
418 REM 31 MSG 31st of every month that has 31 days.
419 3. Only month present. The reminder is triggered every day of the
421 specified month. Example:
422 REM Feb MSG Every day in February
423 4. day and month present. Examples:
425 REM 6 Jan MSG Every 6th of January
426 REM Feb 29 MSG Every 29th of February
427 5. Only year present. Example:
429 REM 1991 MSG Every day in 1991
430 6. year and day present. Examples:
432 REM 1 1990 MSG 1st of every month in 1990
433 REM 1992 23 MSG 23rd of every month in 1992
434 7. year and month present. Examples:
436 REM Feb 1991 MSG Every day in Feb 1991
437 REM 1992 September MSG Every day in Sept 1992
438 8. year, month and day present. Examples:
440 REM 8 Jan 1991 MSG 8th January 1991.
441 REM 1992 March 9 MSG 9th March 1992.
442 9. weekday only. Examples:
444 REM Sat MSG Every Saturday
445 REM Mon Tue Wed Thu Fri MSG Every working day
446 REM Monday Wednesday MSG Every Monday and Wednesday
447 10. weekday and day present. Examples:
449 REM Sat 1 MSG First Saturday of every month
450 REM Mon Tue Wed Thu Fri 15 \
451 MSG 1st working day after 15th of every month
452 11. weekday and month present. Examples:
454 REM Mon March MSG Every Monday in March
455 REM Mon Tue Wed Thu Fri Feb MSG Every working day in February
456 12. weekday, month and day present. Examples:
458 REM Mon 1 March MSG First Monday in March
459 REM Sat Sun 15 July MSG First Sat or Sun on or after 15 July
460 13. weekday and year present. Example:
462 REM Sat Sun 1991 MSG Every Saturday and Sunday in 1991
463 14. weekday, day and year present. Examples:
465 REM Mon 15 1990 MSG 1st Mon after 15th of every month in 1990
466 REM Mon Tue Wed Thu Fri 1 1990 \
467 MSG 1st working day of every month in 1990
468 15. weekday, month and year present. Example:
470 REM Mon Wed 1991 Feb MSG Every Mon and Wed in Feb 1991.
471 16. weekday, day, month and year present. Example:
473 REM Mon Tue Wed Thu Fri 28 Oct 1990 \
474 MSG 1st working day on or after 28 October 1990.
475 Note that when both weekday and day are specified, Remind chooses the
477 first date on or after the specified day that also satisfies the week‐
478 day constraint. It does this by picking the first date on or after the
479 specified day that is listed in the list of weekdays. Thus, a reminder
480 like:
481 REM Mon Tue 28 Oct 1990 MSG Hi
483 would be issued only on Monday, 29 October, 1990. It would not be
485 issued on Tuesday, 30 October, 1990, since the 29th is the first date
486 to satisfy the weekday constraints.
487 SHORT-HAND DATE SPECIFICATIONS
489 In addition to spelling out the day, month and year separately, you can
491 specify YYYY-MM-DD or YYYY/MM/DD. For example, the following state‐
492 ments are equivalent:
493 REM 5 June 2010 MSG Cool!
495 REM 2010-06-05 MSG Cool!
496 You can also specify a date and time as YYYY-MM-DD@HH:MM. These state‐
498 ments are equivalent:
499 REM 19 Dec 2010 AT 16:45 MSG Hi
501 REM 2010-12-19@16:45 MSG Hi
502 There's one subtlety with short-hand date specifications: The follow‐
504 ing statements are not equivalent:
505 REM 19 Dec 2010 AT 16:45 +60 MSG Hi
507 REM 2010-12-19@16:45 +60 MSG Hi
508 In the second statement, the "+60" is a delta that applies to the date
510 rather than a tdelta that applies to the time. We recommend explicitly
511 using the AT keyword with timed reminders.
512 THE REMIND ALGORITHM
514 Remind uses the following algorithm to compute a trigger date: Starting
516 from the current date, it examines each day, one at a time, until it
517 finds a date that satisfies the date specification, or proves to itself
518 that no such date exists. (Actually, Remind merely behaves as if it
519 used this algorithm; it would be much too slow in practice. Inter‐
520 nally, Remind uses much faster techniques to calculate a trigger date.)
521 See DETAILS ABOUT TRIGGER COMPUTATION for more information.
522 BACKWARD SCANNING
524 Sometimes, it is necessary to specify a date as being a set amount of
526 time before another date. For example, the last Monday in a given
527 month is computed as the first Monday in the next month, minus 7 days.
528 The back specification in the reminder is used in this case:
529 REM Mon 1 -7 MSG Last Monday of every month.
531 A back is specified with one or two dashes followed by an integer.
533 This causes Remind to move "backwards" from what would normally be the
534 trigger date. The difference between --7 and -7 will be explained when
535 the OMIT keyword is described.
536 ADVANCE WARNING
538 For some reminders, it is appropriate to receive advance warning of the
540 event. For example, you may wish to be reminded of someone's birthday
541 several days in advance. The delta portion of the REM command achieves
542 this. It is specified as one or two "+" signs followed by a number n.
543 Again, the difference between the "+" and "++" forms will be explained
544 under the OMIT keyword. Remind will trigger the reminder on computed
545 trigger date, as well as on each of the n days before the event. Here
546 are some examples:
547 REM 6 Jan +5 MSG Remind me of birthday 5 days in advance.
549 The above example would be triggered every 6th of January, as well as
551 the 1st through 5th of January.
552 PERIODIC REMINDERS
554 We have already seen some built-in mechanisms for certain types of
556 periodic reminders. For example, an event occurring every Wednesday
557 could be specified as:
558 REM Wed MSG Event!
560 However, events that do not repeat daily, weekly, monthly or yearly
562 require another approach. The repeat component of the REM command
563 fills this need. To use it, you must completely specify a date (year,
564 month and day, and optionally weekday.) The repeat component is an
565 asterisk followed by a number specifying the repetition period in days.
566 For example, suppose you get paid every second Wednesday, and your last
568 payday was Wednesday, 28 October, 1992. You can use:
569 REM 28 Oct 1992 *14 MSG Payday
571 This issues the reminder every 14 days, starting from the calculated
573 trigger date. You can use delta and back with repeat. Note, however,
574 that the back is used only to compute the initial trigger date; there‐
575 after, the reminder repeats with the specified period. Similarly, if
576 you specify a weekday, it is used only to calculate the initial date,
577 and does not affect the repetition period.
578 SCANFROM and FROM
580 The SCANFROM and FROM keywords are for advanced Remind programmers
582 only, and will be explained in the section "Details about Trigger Com‐
583 putation" near the end of this manual. Note that SCANFROM is available
584 only in versions of Remind from 03.00.04 up. FROM is available only
585 from 03.01.00 and later.
586 PRIORITY
588 The PRIORITY keyword must be followed by a number from 0 to 9999. It
590 is used in calendar mode and when sorting reminders. If two reminders
591 have the same trigger date and time, then they are sorted by priority.
592 If the PRIORITY keyword is not supplied, a default priority of 5000 is
593 used. (This default can be changed by adjusting the system variable
594 $DefaultPrio. See the section "System Variables" for more informa‐
595 tion.)
596 EXPIRY DATES
598 Some reminders should be issued periodically for a certain time, but
600 then expire. For example, suppose you have a class every Friday, and
601 that your last class is on 11 December 1992. You can use:
602 REM Fri UNTIL 11 Dec 1992 MSG Class today.
604 Another example: Suppose you have jury duty from 30 November 1992
606 until 4 December 1992. The following reminder will issue the message
607 every day of your jury duty, as well as 2 days ahead of time:
608 REM 1992-11-30 *1 +2 UNTIL 1992-12-04 MSG Jury duty
610 Note that the repeat of *1 is necessary; without it, the reminder would
612 be issued only on 30 November (and the two days preceding.)
613 As a special case, you can use the THROUGH keyword instead of *1 and
615 UNTIL. The following two REM commands are equivalent:
616 REM 1992-11-30 *1 +2 UNTIL 1992-12-04 MSG Jury duty
618 REM 1992-11-30 +2 THROUGH 1992-12-04 MSG Jury duty
620 THE ONCE KEYWORD
622 Sometimes, it is necessary to ensure that reminders are run only once
624 on a given day. For example, if you have a reminder that makes a
625 backup of your files every Friday:
626 REM Fri RUN do_backup
628 (Here, do_backup is assumed to be a program or shell script that does
630 the work.) If you run Remind from your .login script, for example, and
631 log in several times per day, the do_backup program will be run each
632 time you log in. If, however, you use the ONCE keyword in the
633 reminder, the Remind checks the last access date of the reminder
634 script. If it is the same as the current date, Remind assumes that it
635 has already been run, and will not issue reminders containing the ONCE
636 keyword.
637 Note that if you view or edit your reminder script, the last access
639 date will be updated, and the ONCE keyword will not operate properly.
640 If you start Remind with the -o option, then the ONCE keyword will be
641 ignored.
642 LOCALLY OMITTING WEEKDAYS
644 The OMIT portion of the REM command is used to "omit" certain days when
646 counting the delta or back. It is specified using the keyword OMIT
647 followed by a list of weekdays. Its action is best illustrated with
648 examples:
649 REM 1 +1 OMIT Sat Sun MSG Important Event
651 This reminder is normally triggered on the first of every month, as
653 well as the day preceding it. However, if the first of the month falls
654 on a Sunday or Monday, then the reminder is triggered starting from the
655 previous Friday. This is because the delta of +1 does not count Satur‐
656 day or Sunday when it counts backwards from the trigger date to deter‐
657 mine how much advance warning to give.
658 Contrast this with the use of "++1" in the above command. In this
660 case, the reminder is triggered on the first of each month, as well as
661 the day preceding it. The omitted days are counted.
662 REM 1 -1 OMIT Sat Sun MSG Last working day of month
664 Again, in the above example, the back of -1 normally causes the trigger
666 date to be the last day of the month. However, because of the OMIT
667 clause, if the first of the month falls on a Sunday or Monday, the
668 trigger date is moved backwards past the weekend to Friday. (If you
669 have globally omitted holidays, the reminder will be moved back past
670 them, also. See "The OMIT command" for more details.)
671 By comparison, if we had used "--1", the reminder would be triggered on
673 the last day of the month, regardless of the OMIT.
674 COMPUTED LOCAL OMITS
676 The OMITFUNC phrase of the REM command allows you to supply a function
678 that determines whether or not a date is omitted. The function is
679 passed a single parameter of type DATE, and must return a non-zero
680 integer if the date is considered "omitted" and 0 otherwise. Here's an
681 example:
682 FSET _third(x) (day(x) % 3) || \
684 (wkdaynum(x) == 0) || \
685 (wkdaynum(x) == 6)
686 REM OMITFUNC _third AFTER MSG Working day divisible by 3
687 In the example above, the reminder is triggered every Monday to Friday
689 whose day-of-month number is divisible by three. Here's how it works:
690 o The OMITFUNC _third portion causes all days for which _third(x)
692 returns non-zero to be considered "omitted". This causes all
693 days whose day-of-month number is not a multiple of three to be
694 omitted. Note that _third also returns non-zero if the weekday
695 is Sunday or Saturday.
696 o The AFTER keyword causes the reminder to be moved after a block
698 of omitted days.
699 The combination of OMITFUNC and AFTER keyword causes the reminder to be
701 issued on all days whose day-of-month number is divisible by three, but
702 not on Saturday or Sunday.
703 Note that if you use OMITFUNC, then a local OMIT is ignored as are all
705 global OMITs. If you want to omit specific weekdays, your omit func‐
706 tion will need to test for them specifically. If you want to take into
707 account the global OMIT context, then your omit function will need to
708 test for that explicitly (using the isomitted() function.)
709 Note that an incorrect OMITFUNC might cause all days to be considered
711 omitted. For that reason, when Remind searches through omitted days,
712 it terminates the search after the SATISFY iteration limit (command-
713 line option -x.)
714 TIMED REMINDERS
716 Timed reminders are those that have an AT keyword followed by a time
718 and optional tdelta and trepeat. The time must be specified in 24-hour
719 format, with 0:00 representing midnight, 12:00 representing noon, and
720 23:59 representing one minute to midnight. You can use either a colon
721 or a period to separate the hours from the minutes. That is, 13:39 and
722 13.39 are equivalent.
723 Remind treats timed reminders specially. If the trigger date for a
725 timed reminder is the same as the current system date, the reminder is
726 queued for later activation. When Remind has finished processing the
727 reminder file, it puts itself in the background, and activates timed
728 reminders when the system time reached the specified time.
729 If the trigger date is not the same as the system date, the reminder is
732 not queued.
733 For example, the following reminder, triggered every working day, will
735 emit a message telling you to leave at 5:00pm:
736 REM Mon Tue Wed Thu Fri AT 17:00 MSG Time to leave!
738 The following reminder will be triggered on Thursdays and Fridays, but
740 will only be queued on Fridays:
741 REM Fri ++1 AT 13:00 MSG Lunch at 1pm Friday.
743 The tdelta and trepeat have the same form as a repeat and delta, but
745 are specified in minutes. For example, this reminder will be triggered
746 at 12:00pm as well as 45 minutes before:
747 REM AT 12:00 +45 MSG Example
749 The following will be issued starting at 10:45, every half hour until
751 11:45, and again at noon.
752 REM AT 12:00 +75 *30 MSG Example2
754 The "+75" means that the reminder is issued starting 75 minutes before
756 noon; in other words, at 10:45. The *30 specifies that the reminder is
757 subsequently to be issued every 30 minutes. Note that the reminder is
758 always issued at the specified time, even if the tdelta is not a multi‐
759 ple of the trepeat. So the above example is issued at 10:45am,
760 11:15am, 11:45am, and 12:00pm. Note that in the time specification,
761 there is no distinction between the "+" and "++" forms of tdelta.
762 Normally, Remind will issue timed reminders as it processes the
764 reminder script, as well as queuing them for later. If you do not want
765 Remind to issue the reminders when processing the script, but only to
766 queue them for later, use the -a command-line option. If you do not
767 want reminders to be queued for later, use the -q command-line option.
768 Normally, Remind forks a background process to handle queued reminders.
770 If you want Remind to remain in the foreground, use the -f command-line
771 option. This is useful, for example, in .xinitrc scripts, where you
772 can use the command:
773 remind -fa myreminders &
775 This ensures that when you exit X-Windows, the Remind process is
777 killed.
778 WARNING ABOUT TIMED REMINDERS
780 Note: If you use user-defined functions or variables (described later)
782 in the bodies of timed reminders, then when the timed reminders are
783 activated, the variables and functions have the definitions that were
784 in effect at the end of the reminder script. These definitions may not
785 necessarily be those that were in effect at the time the reminder was
786 queued.
787 THE SCHED AND WARN KEYWORDS
789 The SCHED keyword allows more precise control over the triggering of
791 timed reminders, and the WARN keyword allows precise control over the
792 advance triggering of all types of reminders. However, discussion must
793 be deferred until after expressions and user-defined functions are
794 explained. See the subsection "Precise Scheduling" further on.
795 TAG AND DURATION
797 The TAG keyword lets you "tag" certain reminders. This facility is
799 used by certain back-ends or systems built around Remind, such as TkRe‐
800 mind. These back-ends have specific rules about tags; see their docu‐
801 mentation for details.
802 The TAG keyword is followed by a tag consisting of up to 48 characters.
804 You can have as many TAG clauses as you like in a given REM statement.
805 If you supply the -y option to Remind, then any reminder that lacks a
807 TAG will have one synthesized. The synthesized tag consists of the
808 characters "__syn__" followed by the hexadecimal representation of the
809 MD5 sum of the REM command line. This lets you give a more-or-less
810 unique identifier to each distinct REM command.
811 The DURATION keyword makes sense only for timed reminders; it specifies
813 the duration of an event. Currently, this is not used, but it may be
814 used in future by back-ends or scheduling systems built around Remind.
815 For example, if you have a 90-minute meeting starting at 1:00pm, you
816 could use:
817 REM 5 March 1999 AT 13:00 DURATION 1:30 MSG Meeting
819 Note that duration is specified in hours and minutes.
821
823 Before being processed, the body of a REM command is passed through a
824 substitution filter. The filter scans for sequences "%x" (where "x" is
825 any letter and certain other characters) and performs substitutions as
826 shown below. (All dates refer to the trigger date of the reminder.)
827 %a is replaced with "on weekday, day month, year"
829 For example, consider the reminder:
830 REM 18 Oct 1990 +4 MSG Meeting with Bob %a.
832 On 16 October 1990, it would print "Meeting with Bob on Thurs‐
834 day, 18 October, 1990."
835 On 17 October 1990, it would print "Meeting with Bob tomorrow."
837 On 18 October 1990, it would print "Meeting with Bob today."
839 %b is replaced with "in diff day's time" where diff is the actual
841 number of days between the current date and the trigger date.
842 (OMITs have no effect.)
843 For example, consider:
844 REM 18 Oct 1990 +4 MSG Meeting with Bob %b.
846 On 16 October 1990, it would print "Meeting with Bob in 2 days'
848 time."
849 On 17 October 1990, it would print "Meeting with Bob tomorrow."
851 On 18 October 1990, it would print "Meeting with Bob today."
853 %c is replaced with "on weekday"
855 Example: REM 18 Oct 1990 +4 MSG Meeting with Bob %c.
856 On 16 October 1990, it would print "Meeting with Bob on Thurs‐
858 day."
859 On 17 October 1990, it would print "Meeting with Bob tomorrow."
861 On 18 October 1990, it would print "Meeting with Bob today."
863 %d is replaced with "day", the day of the month.
865 %e is replaced with "on dd-mm-yyyy"
867 %f is replaced with "on mm-dd-yyyy"
869 %g is replaced with "on weekday, day month"
871 %h is replaced with "on dd-mm"
873 %i is replaced with "on mm-dd"
875 %j is replaced with "on weekday, month day-th, year" This form
877 appends the characters "st", "nd", "rd" or "th" to the day of
878 the month, as appropriate.
879 %k is replaced with "on weekday, month day-th"
881 %l is replaced with "on yyyy-mm-dd"
883 %m is replaced with "month", the name of the month.
885 %n is replaced with the number (1 to 12) of the month.
887 %o is replaced with " (today)" if and only if the current system
889 date is the same as the date being used by Remind as the current
890 date. Recall that you can specify a date for Remind to use on
891 the command line. This substitution is not generally useful in
892 a REM command, but is useful in a BANNER command. (See "The
893 BANNER Command.")
894 %p is replaced with "s" if the diff between the current date and
896 the trigger date is not 1. You can use this to construct
897 reminders like:
898 REM 1 Jan +4 MSG %x day%p to go before New Year!
899 %q is replaced with "'s" if the diff between the trigger date and
901 the current date is 1. Otherwise, it is replaced with "s'"
902 This can be used as follows:
903 REM 1 Jan +4 MSG New Year in %x day%q time!
904 %r is replaced with the day of the month (01 to 31) padded with a
906 leading zero if needed to pad to two digits.
907 %s is replaced with "st", "nd", "rd" or "th" depending on the day
909 of the month.
910 %t is replaced with the number of the month (01 to 12) padded to
912 two digits with a leading zero.
913 %u is replaced with "on weekday, day-th month, year" This is simi‐
915 lar to %a except that "st", "nd", "rd" or "th" is added to the
916 day as appropriate.
917 %v is replaced with "on weekday, day-th month"
919 %w is replaced with "weekday", the name of the day of the week.
921 %x is replaced with the diff between the current date and the trig‐
923 ger date. The diff is defined as the actual number of days
924 between these two dates; OMITs are not counted. (Strict date
925 subtraction is performed.)
926 %y is replaced with "year", the year of the trigger date.
928 %z is replaced with "yy", the last two digits of the year.
930 %_ (percent-underscore) is replaced with a newline. You can use
932 this to achieve multi-line reminders.
933 %1 is replaced with "now", "m minutes from now", "m minutes ago",
935 "h hours from now", "h hours ago", "h hours and m minutes from
936 now" or "h hours and m minutes ago", as appropriate for a timed
937 reminder. Note that unless you specify the -a option, timed
938 reminders will be triggered like normal reminders, and thus a
939 timed reminder that occurred earlier in the day may be trig‐
940 gered. This causes the need for the "...ago" forms.
941 %2 is replaced with "at hh:mmam" or "..pm" depending on the AT time
943 of the reminder.
944 %3 is replaced with "at hh:mm" in 24-hour format.
946 %4 is replaced with "mm" where mm is the number of minutes between
948 "now" and the time specified by AT. If the AT time is earlier
949 than the current time, then the result is negative.
950 %5 is replaced with "ma" where ma is the absolute value of the num‐
952 ber produced by %4.
953 %6 is replaced with "ago" or "from now", depending on the relation‐
955 ship between the AT time and the current time.
956 %7 is replaced with the number of hours between the AT time and the
958 current time. It is always non-negative.
959 %8 is replaced with the number of minutes between the AT time and
961 the current time, after the hours (%7) have been subtracted out.
962 This is a number ranging from 0 to 59.
963 %9 is replaced with "s" if the value produced by %8 is not 1.
965 %0 is replaced with "s" if the value produced by %7 is not 1.
967 %! is replaced with "is" if the current time is before the AT time,
969 or "was" if it is after.
970 %@ is similar to %2 but displays the current time.
972 %# is similar to %3 but displays the current time.
974 %" (percent-doublequote - ") is removed. This sequence is not used
976 by the substitution filter, but is used to tell Remind which
977 text to include in a calendar entry when the -c, -s or -p option
978 is chosen. See "Calendar Mode"
979 Notes:
981 o Remind normally prints a blank line after each reminder; if the
983 last character of the body is "%", the blank line will not be
984 printed.
985 o Substitutions a, b, c, e, f, g, h, i, j, k, l, u and v all are
987 replaced with "today" if the current date equals the trigger
988 date, or "tomorrow" if the trigger date is one day after the
989 current date. Thus, they are not the same as substitutions
990 built up from the simpler %w, %y, etc. sequences.
991 o Any of the substitutions dealing with time (0 through 9 and '!')
993 produce undefined results if used in a reminder that does not
994 have an AT keyword. Also, if a reminder has a delta and may be
995 triggered on several days, the time substitutions ignore the
996 date. Thus, the %1 substitution may report that a meeting is in
997 15 minutes, for example, even though it may only be in 2 days
998 time, because a delta has triggered the reminder. It is recom‐
999 mended that you use the time substitutions only in timed
1000 reminders with no delta that are designed to be queued for timed
1001 activation.
1002 o Capital letters can be used in the substitution sequence, in
1004 which case the first character of the substituted string is cap‐
1005 italized (if it is normally a lower-case letter.)
1006 o All other characters following a "%" sign are simply copied. In
1008 particular, to get a "%" sign out, use "%%" in the body. To
1009 start the body of a reminder with a space, use "% ", since
1010 Remind normally scans for the first non-space character after a
1011 MSG, CAL or RUN token.
1012
1014 In addition to being a keyword in the REM command, OMIT is a command in
1015 its own right. Its syntax is:
1016 OMIT day month [year]
1018 or:
1020 OMIT day1 month1 year1 THROUGH day2 month2 year2
1022 The OMIT command is used to "globally" omit certain days (usually holi‐
1024 days). These globally-omitted days are skipped by the "-" and "+"
1025 forms of back and delta. Some examples:
1026 OMIT 1 Jan
1028 OMIT 7 Sep 1992
1029 The first example specifies a holiday that occurs on the same date each
1031 year - New Year's Day. The second example specifies a holiday that
1032 changes each year - Labour Day. For these types of holidays, you must
1033 create an OMIT command for each year. (Later, in the description of
1034 expressions and some of the more advanced features of Remind, you will
1035 see how to automate this for some cases.)
1036 As with the REM command, you can use shorthand specifiers for dates;
1038 the following are equivalent:
1039 OMIT 7 Sep 1992
1041 OMIT 1992-09-07
1042 For convenience, you can use a delta and MSG or RUN keyword in the OMIT
1044 command. The following sequences are equivalent:
1045 OMIT 1 Jan
1047 REM 1 Jan +4 MSG New year's day is %b!
1048 and
1050 OMIT 1 Jan +4 MSG New year's day is %b!
1052 The THROUGH keyword lets you conveniently OMIT a range of days. The
1054 starting and ending points must be fully-specified (ie, they must
1055 include day, month and year.). For example, the following sequences
1056 are equivalent:
1057 OMIT 3 Jan 2011
1059 OMIT 4 Jan 2011
1060 OMIT 5 Jan 2011
1061 and
1063 OMIT 3 Jan 2011 THROUGH 5 Jan 2011
1065 You can make a THROUGH OMIT do double-duty as a REM command:
1067 OMIT 6 Sep 2010 THROUGH 10 Sep 2010 MSG Vacation
1069 You can debug your global OMITs with the following command:
1072 OMIT DUMP
1074 The OMIT DUMP command prints the current global omits to standard out‐
1076 put.
1077 THE BEFORE, AFTER AND SKIP KEYWORDS
1079 Normally, days that are omitted, whether by a global OMIT command or
1081 the local OMIT or OMITFUNC keywords in a REM statement, only affect the
1082 counting of the -back or the +delta. For example, suppose you have a
1083 meeting every Wednesday. Suppose, too, that you have indicated 11 Nov
1084 as a holiday:
1085 OMIT 11 Nov +4 MSG Remembrance Day
1087 REM Wed +1 MSG Code meeting %b.
1088 The above sequence will issue a reminder about a meeting for 11 Novem‐
1090 ber 1992, which is a Wednesday. This is probably incorrect. There are
1091 three options:
1092 BEFORE This keyword moves the reminder to before any omitted days.
1094 Thus, in the above example, use of BEFORE would cause the meet‐
1095 ing reminder to be triggered on Tuesday, 10 November 1992.
1096 AFTER This keyword moves the reminder to after any omitted days. In
1098 the above example, the meeting reminder would be triggered on
1099 Thursday, 12 November 1992.
1100 SKIP This keyword causes the reminder to be skipped completely on any
1102 omitted days. Thus, in the above example, the reminder would
1103 not be triggered on 11 November 1992. However, it would be
1104 triggered as usual on the following Wednesday, 18 November 1992.
1105 The BEFORE and AFTER keywords move the trigger date of a reminder to
1107 before or after a block of omitted days, respectively. Suppose you
1108 normally run a backup on the first day of the month. However, if the
1109 first day of the month is a weekend or holiday, you run the backup on
1110 the first working day following the weekend or holiday. You could use:
1111 REM 1 OMIT Sat Sun AFTER RUN do_backup
1113 Let's examine how the trigger date is computed. The 1 specifies the
1115 first day of the month. The local OMIT keyword causes the AFTER key‐
1116 word to move the reminder forward past weekends. Finally, the AFTER
1117 keyword will keep moving the reminder forward until it has passed any
1118 holidays specified with global OMIT commands.
1119
1121 Remind allows you to include other files in your reminder script, simi‐
1122 lar to the C preprocessor #include directive. For example, your system
1123 administrator may maintain a file of holidays or system-wide reminders.
1124 You can include these in your reminder script as follows:
1125 INCLUDE /usr/share/remind/holidays
1127 INCLUDE /usr/share/remind/reminders
1128 (The actual pathnames vary from system to system - ask your system
1130 administrator.)
1131 INCLUDE files can be nested up to a depth of 8.
1133 If you specify a filename of "-" in the INCLUDE command, Remind will
1135 begin reading from standard input.
1136 If you specify a directory as the argument to INCLUDE, then Remind will
1138 process all files in that directory that match the shell patterm
1139 "*.rem". The files are processed in sorted order; the sort order
1140 matches that used by the shell when it expands "*.rem".
1141
1144 If you include other files in your reminder script, you may not always
1145 entirely trust the contents of the other files. For example, they may
1146 contain RUN-type reminders that could be used to access your files or
1147 perform undesired actions. The RUN command can restrict this: If you
1148 include the command RUN OFF in your top-level reminder script, any
1149 reminder or expression that would normally execute a system command is
1150 disabled. RUN ON will re-enable the execution of system commands.
1151 Note that the RUN ON command can only be used in your top-level
1152 reminder script; it will not work in any files accessed by the INCLUDE
1153 command. This is to protect you from someone placing a RUN ON command
1154 in an included file. However, the RUN OFF command can be used at top
1155 level or in an included file.
1156 If you run Remind with the -r command-line option, RUN-type reminders
1158 and the shell() function will be disabled, regardless of any RUN com‐
1159 mands in the reminder script. However, any command supplied with the
1160 -k option will still be executed.
1161 One use of the RUN command is to provide a secure interface between
1163 Remind and the Elm mail system. The Elm system can automatically scan
1164 incoming mail for reminder or calendar entries, and place them in your
1165 calendar file. To use this feature, you should set the calendar file‐
1166 name option under Elm to be something like "~/.reminders.in", not your
1167 main reminder file! This is so that any RUN ON commands mailed to you
1168 can never be activated.
1169 Then, you can use the Elm scan message for calendar entries command to
1171 place reminders prefaced by "->" into .reminders.in. In your main
1172 .reminders file, include the following lines:
1173 RUN OFF # Disable RUN
1175 INCLUDE .reminders.in
1176 RUN ON # Re-enable RUN
1177 In addition, Remind contains a few other security features. It will
1179 not read a file that is group- or world-writable. It will not run set-
1180 uid. If it reads a file you don't own, it will disable RUN and the
1181 shell() function. And if it is run as root, it will only read files
1182 owned by root.
1183
1185 When Remind first issues a reminder, it prints a message like this:
1186 Reminders for Friday, 30th October, 1992 (today):
1188 (The banner is not printed if any of the calendar-producing options is
1190 used, or if the -k option is used.)
1191 The BANNER command lets you change the format. It should appear before
1193 any REM commands. The format is:
1194 BANNER format
1196 The format is similar to the body of a REM command. It is passed
1198 through the substitution filter, with an implicit trigger of the cur‐
1199 rent system date. Thus, the default banner is equivalent to:
1200 BANNER Reminders for %w, %d%s %m, %y%o:
1202 You can disable the banner completely with BANNER %. Or you can create
1204 a custom banner:
1205 BANNER Hi - here are your reminders for %y-%t-%r:
1207
1209 Sometimes, it is necessary to temporarily change the global OMITs that
1210 are in force for a few reminders. Three commands allow you to do this:
1211 PUSH-OMIT-CONTEXT
1213 This command saves the current global OMITs on an internal
1214 stack.
1215 CLEAR-OMIT-CONTEXT
1217 This command clears all of the global OMITs, starting you off
1218 with a "clean slate."
1219 POP-OMIT-CONTEXT
1221 This command restores the global OMITs that were saved by the
1222 most recent PUSH-OMIT-CONTEXT.
1223 For example, suppose you have a block of reminders that require a clear
1225 OMIT context, and that they also introduce unwanted global OMITs that
1226 could interfere with later reminders. You could use the following
1227 fragment:
1228 PUSH-OMIT-CONTEXT # Save the current context
1230 CLEAR-OMIT-CONTEXT # Clean the slate
1231 # Block of reminders goes here
1232 POP-OMIT-CONTEXT # Restore the saved omit context
1233
1235 In certain contexts, to be described later, Remind will accept expres‐
1236 sions for evaluation. Remind expressions resemble C expressions, but
1237 operate on different types of objects.
1238 DATA TYPES
1240 Remind expressions operate on five types of objects:
1242 INT The INT data type consists of the integers representable in one
1244 machine word. The INT data type corresponds to the C "int"
1245 type.
1246 STRING The STRING data type consists of strings of characters. It is
1248 somewhat comparable to a C character array, but more closely
1249 resembles the string type in BASIC.
1250 TIME The TIME data type consists of times of the day. The TIME data
1252 type is internally stored as an integer representing the number
1253 of minutes since midnight.
1254 DATE The DATE data type consists of dates (later than 1 January
1256 1990.) Internally, DATE objects are stored as the number of
1257 days since 1 January 1990.
1258 DATETIME
1260 The DATETIME data type consists of a date and time together.
1261 Internally, DATETIME objects are stored as the number of minutes
1262 since midnight, 1 January 1990. You can think of a DATETIME
1263 object as being the combination of DATE and TIME parts.
1264 CONSTANTS
1266 The following examples illustrate constants in Remind expressions:
1268 INT constants
1270 12, 36, -10, 0, 1209
1271 STRING constants
1273 "Hello there", "This is a test", "\n\gosd\w", ""
1274 Note that the empty string is represented by "", and that back‐
1276 slashes in a string are not interpreted specially, as in they
1277 are in C.
1278 TIME constants
1280 12:33, 0:01, 14:15, 16:42, 12.16, 13.00, 1.11
1281 Note that TIME constants are written in 24-hour format. Either
1283 the period or colon can be used to separate the minutes from the
1284 hours. However, Remind will consistently output times using
1285 only one separator character. (The output separator character
1286 is chosen at compile-time.)
1287 DATE constants
1289 DATE constants are expressed as 'yyyy/mm/dd' or 'yyyy-mm-dd',
1290 and the single quotes must be supplied. This distinguishes date
1291 constants from division or subtraction of integers. Examples:
1292 ´1993/02/22', '1992-12-25', '1999/01/01'
1294 Note that DATE values are printed without the quotes. Although
1296 either '-' or '/' is accepted as a date separator on input, when
1297 dates are printed, only one will be used. The choice of whether
1298 to use '-' or '/' is made at compile-time. Note also that ver‐
1299 sions of Remind prior to 03.00.01 did not support date con‐
1300 stants. In those versions, you must create dates using the
1301 date() function. Also, versions prior to 03.00.02 did not sup‐
1302 port the '-' date separator.
1303 DATETIME constants
1305 DATETIME constants are expressed similarly to DATE constants
1306 with the addition of an "@HH:MM" part. For example:
1307 ´2008-04-05@23:11', '1999/02/03@14:06', '2001-04-07@08:30'
1309 DATETIME values are printed without the quotes. Notes about
1311 date and time separator characters for DATE and TIME constants
1312 apply also to DATETIME constants.
1313 OPERATORS
1315 Remind has the following operators. Operators on the same line have
1317 equal precedence, while operators on lower lines have lower precedence
1318 than those on higher lines. The operators approximately correspond to
1319 C operators.
1320 ! - (unary logical negation and arithmetic negation)
1322 * / %
1323 + -
1324 < <= > >=
1325 == !=
1326 &&
1327 ||
1328 DESCRIPTION OF OPERATORS
1330 ! Logical negation. Can be applied to an INT type. If the oper‐
1332 and is non-zero, returns zero. Otherwise, returns 1.
1333 - Unary minus. Can be applied to an INT. Returns the negative of
1335 the operand.
1336 * Multiplication. Returns the product of two INTs.
1338 / Integer division. Returns the quotient of two INTs, discarding
1340 the remainder.
1341 % Modulus. Returns the remainder upon dividing one INT by
1343 another.
1344 + Has several uses. These are:
1346 INT + INT - returns the sum of two INTs.
1348 INT + TIME or TIME + INT - returns a TIME obtained by adding INT
1350 minutes to the original TIME.
1351 INT + DATE or DATE + INT - returns a DATE obtained by adding INT
1353 days to the original DATE.
1354 INT + DATETIME or DATETIME + INT - returns a DATETIME obtained
1356 by adding INT minutes to the original DATETIME.
1357 STRING + STRING - returns a STRING that is the concatenation of
1359 the two original STRINGs.
1360 STRING + anything or anything + STRING - converts the non-STRING
1362 argument to a STRING, and then performs concatenation. See the
1363 coerce() function.
1364 - Has several uses. These are:
1366 INT - INT - returns the difference of two INTs.
1368 DATE - DATE - returns (as an INT) the difference in days between
1370 two DATEs.
1371 TIME - TIME - returns (as an INT) the difference in minutes
1373 between two TIMEs.
1374 DATETIME - DATETIME - returns (as an INT) the difference in min‐
1376 utes between two DATETIMEs.
1377 DATE - INT - returns a DATE that is INT days earlier than the
1379 original DATE.
1380 TIME - INT - returns a TIME that is INT minutes earlier than the
1382 original TIME.
1383 DATETIME - INT - returns a DATETIME that is INT minutes earlier
1385 than the original DATETIME.
1386 <, <=, >, and >=
1388 These are the comparison operators. They can take operands of
1389 any type, but both operands must be of the same type. The com‐
1390 parison operators return 1 if the comparison is true, or 0 if it
1391 is false. Note that string comparison is done following the
1392 lexical ordering of characters on your system, and that upper
1393 and lower case are distinct for these operators.
1394 ==, != == tests for equality, returning 1 if its operands are equal,
1396 and 0 if they are not. != tests for inequality.
1397 If the operands are not of the same type, == returns 0 and !=
1399 returns 1. Again, string comparisons are case-sensitive.
1400 && This is the logical AND operator. Both of its operands must be
1402 of type INT. It returns 1 if both operands are non-zero, and 0
1403 otherwise.
1404 || This is the logical OR operator. Both of its operands must be
1406 of type INT. It returns 1 if either operand is non-zero, and 0
1407 otherwise.
1408 NOTES
1410 Operators of equal precedence are always evaluated from left to right,
1412 except where parentheses dictate otherwise. This is important, because
1413 the enhanced "+" operator is not necessarily associative. For example:
1414 1 + 2 + "string" + 3 + 4 yields "3string34"
1416 1 + (2 + "string") + (3 + 4) yields "12string7"
1417 12:59 + 1 + "test" yields "13:00test"
1418 12:59 + (1 + "test") yields "12:591test"
1419 The logical operators are not so-called short-circuit operators, as
1421 they are in C. Both operands are always evaluated. Thus, an expres‐
1422 sion such as:
1423 (f!=0) && (100/f <= 3)
1425 will cause an error if f is zero.
1427 VARIABLES
1429 Remind allows you to assign values to variables. The SET command is
1431 used as follows:
1432 SET var expr
1434 Var is the name of a variable. It must start with a letter or under‐
1436 score, and consist only of letters, digits and underscores. Only the
1437 first 12 characters of a variable name are significant. Variable names
1438 are not case sensitive; thus, "Afoo" and "afOo" are the same variable.
1439 Examples:
1440 SET a 10 + (9*8)
1442 SET b "This is a test"
1443 SET mydir getenv("HOME")
1444 SET time 12:15
1445 SET date today()
1446 Note that variables themselves have no type. They take on the type of
1448 whatever you store in them.
1449 To delete a variable, use the UNSET command:
1451 UNSET var [var...]
1453 For example, to delete all the variables declared above, use:
1455 UNSET a b mydir time date
1457 SYSTEM VARIABLES
1459 In addition to the regular user variables, Remind has several "system
1461 variables" that are used to query or control the operating state of
1462 Remind. System variables are available starting from version 03.00.07
1463 of Remind.
1464 All system variables begin with a dollar sign '$'. They can be used in
1466 SET commands and expressions just as regular variables can. All system
1467 variables always hold values of a specified type. In addition, some
1468 system variables cannot be modified, and you cannot create new system
1469 variables. System variables can be initialized on the command line
1470 with the -i option, but you may need to quote them to avoid having the
1471 shell interpret the dollar sign. System variable names are not case-
1472 sensitive.
1473 The following system variables are defined. Those marked "read-only"
1475 cannot be changed with the SET command. All system variables hold val‐
1476 ues of type INT, unless otherwise specified.
1477 $CalcUTC
1479 If 1 (the default), then Remind uses C library functions to cal‐
1480 culate the number of minutes between local and Universal Time
1481 Coordinated. This affects astronomical calculations (sunrise()
1482 for example.) If 0, then you must supply the number of minutes
1483 between local and Universal Time Coordinated in the $MinsFromUTC
1484 system variable.
1485 $CalMode (read-only)
1487 If non-zero, then the -c option was supplied on the command
1488 line.
1489 $Daemon (read-only)
1491 If the daemon mode -z was invoked, contains the number of min‐
1492 utes between wakeups. If not running in daemon mode, contains
1493 0.
1494 $DateSep
1496 This variable can be set only to "/" or "-". It holds the char‐
1497 acter used to separate portions of a date when Remind prints a
1498 DATE or DATETIME value.
1499 $DefaultPrio
1501 The default priority assigned to reminders without a PRIORITY
1502 clause. You can set this as required to adjust the priorities
1503 of blocks of reminders without having to type priorities for
1504 individual reminders. At startup, $DefaultPrio is set to 5000;
1505 it can range from 0 to 9999.
1506 $DontFork (read-only)
1508 If non-zero, then the -c option was supplied on the command
1509 line.
1510 $DontTrigAts (read-only)
1512 The number of times that the -a option was supplied on the com‐
1513 mand line.
1514 $DontQueue (read-only)
1516 If non-zero, then the -q option was supplied on the command
1517 line.
1518 $EndSent (STRING type)
1520 Contains a list of characters that end a sentence. The MSF key‐
1521 word inserts two spaces after these characters. Initially,
1522 $EndSent is set to ".!?" (period, exclamation mark, and question
1523 mark.)
1524 $EndSentIg (STRING type)
1526 Contains a list of characters that should be ignored when MSF
1527 decides whether or not to place two spaces after a sentence.
1528 Initially, is set to "'>)]}"+CHAR(34) (single-quote, greater-
1529 than, right parenthesis, right bracket, right brace, and double-
1530 quote.)
1531 For example, the default values work as follows:
1533 MSF He said, "Huh! (Two spaces will follow this.)" Yup.
1535 because the final parenthesis and quote are ignored (for the
1537 purposes of spacing) when they follow a period.
1538 $FirstIndent
1540 The number of spaces by which to indent the first line of a MSF-
1541 type reminder. The default is 0.
1542 $FoldYear
1544 The standard Unix library functions may have difficulty dealing
1545 with dates later than 2037. If this variable is set to 1, then
1546 the UTC calculations "fold back" years later than 2037 before
1547 using the Unix library functions. For example, to find out
1548 whether or not daylight saving time is in effect in June, 2077,
1549 the year is "folded back" to 2010, because both years begin on a
1550 Monday, and both are non-leapyears. The rules for daylight sav‐
1551 ing time are thus presumed to be identical for both years, and
1552 the Unix library functions can handle 2010. By default, this
1553 variable is 0. Set it to 1 if the sun or UTC functions misbe‐
1554 have for years greater than 2037.
1555 $FormWidth
1557 The maximum width of each line of text for formatting MSF-type
1558 reminders. The default is 72. If an MSF-type reminder contains
1559 a word too long to fit in this width, it will not be truncated -
1560 the width limit will be ignored.
1561 $HushMode (read-only)
1563 If non-zero, then the -h option was supplied on the command
1564 line.
1565 $IgnoreOnce (read-only)
1567 If non-zero, then the -o option was supplied on the command
1568 line, or a date different from today's true date was supplied.
1569 If non-zero, then ONCE directives will be ignored.
1570 $InfDelta (read-only)
1572 If non-zero, then the -t option was supplied on the command
1573 line.
1574 $LatDeg, $LatMin, $LatSec
1576 These specify the latitude of your location. $LatDeg can range
1577 from -90 to 90, and the others from -59 to 59. Northern lati‐
1578 tudes are positive; southern ones are negative. For southern
1579 latitudes, all three components should be negative.
1580 $Location (STRING type)
1582 This is a string specifying the name of your location. It is
1583 usually the name of your town or city. It can be set to what‐
1584 ever you like, but good style indicates that it should be kept
1585 consistent with the latitude and longitude system variables.
1586 $LongDeg, $LongMin, $LongSec
1588 These specify the longitude of your location. $LongDeg can
1589 range from -180 to 180. Western longitudes are positive; east‐
1590 ern ones are negative. Note that all three components should
1591 have the same sign: All positive for Western longitudes and all
1592 negative for Eastern longitudes.
1593 The latitude and longitude information is required for the func‐
1595 tions sunrise() and sunset(). Default values can be compiled
1596 into Remind, or you can SET the correct values at the start of
1597 your reminder scripts.
1598 $MaxSatIter
1600 The maximum number of iterations for the SATISFY clause
1601 (described later.) Must be at least 10.
1602 $MinsFromUTC
1604 The number of minutes between Universal Time Coordinated and
1605 local time. If $CalcUTC is non-zero, this is calculated upon
1606 startup of Remind. Otherwise, you must set it explicitly. If
1607 $CalcUTC is zero, then $MinsFromUTC is used in the astronomical
1608 calculations. You must adjust it for daylight saving time your‐
1609 self. Also, if you want to initialize $MinsFromUTC using the -i
1610 command-line option, you must also set $CalcUTC to 0 with the -i
1611 option.
1612 $NextMode (read-only)
1614 If non-zero, then the -n option was supplied on the command
1615 line.
1616 $NumQueued (read-only)
1618 Contains the number of reminders queued so far for background
1619 timed triggering.
1620 $NumTrig (read-only)
1622 Contains the number of reminders triggered for the current date.
1623 One use for this variable is as follows: Suppose you wish to
1624 shade in the box of a PostScript calendar whenever a holiday is
1625 triggered. You could save the value of $NumTrig in a regular
1626 variable prior to executing a block of holiday reminders. If
1627 the value of $NumTrig after the holiday block is greater than
1628 the saved value, then at least one holiday was triggered, and
1629 you can execute the command to shade in the calendar box. (See
1630 the section "Calendar Mode".)
1631 Note that $NumTrig is affected only by REM commands; triggers in
1633 IFTRIG commands do not affect it.
1634 $PrefixLineNo (read-only)
1636 If non-zero, then the -l option was supplied on the command
1637 line.
1638 $PSCal (read-only)
1640 If non-zero, then the -p option was supplied on the command
1641 line.
1642 $RunOff (read-only)
1644 If non-zero, the RUN directives are disabled.
1645 $SimpleCal (read-only)
1647 Set to a non-zero value if either of the -p or -s command-line
1648 options was supplied.
1649 $SortByDate (read-only)
1651 Set to 0 if no -g option is used, 1 if sorting by date in
1652 ascending order, or 2 if sorting by date in descending order.
1653 $SortByPrio (read-only)
1655 Set to 0 if no -g option is used, 1 if sorting by priority in
1656 ascending order, or 2 if sorting by priority in descending
1657 order.
1658 $SortByTime (read-only)
1660 Set to 0 if no -g option is used, 1 if sorting by time in
1661 ascending order, or 2 if sorting by time in descending order.
1662 $SubsIndent
1664 The number of spaces by which all lines (except the first) of an
1665 MSF-type reminder should be indented. The default is 0.
1666 $T (read-only, DATE type)
1668 Exactly equivalent to trigdate(). (See BUILT-IN FUNCTIONS.)
1669 $Td (read-only)
1671 Equivalent to day(trigdate()).
1672 $Tm (read-only)
1674 Equivalent to monnum(trigdate()).
1675 $Tw (read-only)
1677 Equivalent to wkdaynum(trigdate()).
1678 $Ty (read-only)
1680 Equivalent to year(trigdate()).
1681 $TimeSep
1683 This variable can be set only to ":" or ".". It holds the char‐
1684 acter used to separate portions of a time when Remind prints a
1685 TIME or DATETIME value.
1686 $UntimedFirst (read-only)
1688 Set to 1 if the -g option is used with a fourth sort character
1689 of "d"; set to 0 otherwise.
1690 $U (read-only, DATE type)
1692 Exactly equivalent to today(). (See BUILT-IN FUNCTIONS.)
1693 $Ud (read-only)
1695 Equivalent to day(today()).
1696 $Um (read-only)
1698 Equivalent to monnum(today()).
1699 $Uw (read-only)
1701 Equivalent to wkdaynum(today()).
1702 $Uy (read-only)
1704 Equivalent to year(today()).
1705 Note: If any of the calendar modes are in effect, then the values of
1707 $Daemon, $DontFork, $DontTrigAts, $DontQueue, $HushMode, $IgnoreOnce,
1708 $InfDelta, and $NextMode are not meaningful.
1709 BUILT-IN FUNCTIONS
1711 Remind has a plethora of built-in functions. The syntax for a function
1713 call is the same as in C - the function name, followed a comma-sepa‐
1714 rated list of arguments in parentheses. Function names are not case-
1715 sensitive. If a function takes no arguments, it must be followed by
1716 "()" in the function call. Otherwise, Remind will interpret it as a
1717 variable name, and probably not work correctly.
1718 In the descriptions below, short forms are used to denote acceptable
1720 types for the arguments. The characters "i", "s", "d", "t" and "q"
1721 denote INT, STRING, DATE, TIME and DATETIME arguments, respectively.
1722 If an argument can be one of several types, the characters are concate‐
1723 nated. For example, "di_arg" denotes an argument that can be a DATE or
1724 an INT. "x_arg" denotes an argument that can be of any type. The type
1725 of the argument is followed by an underscore and an identifier naming
1726 the argument.
1727 The built-in functions are:
1729 abs(i_num)
1731 Returns the absolute value of num.
1732 access(s_file, si_mode)
1734 Tests the access permissions for the file file. Mode can be a
1735 string, containing a mix of the characters "rwx" for read, write
1736 and execute permission testing. Alternatively, mode can be a
1737 number as described in the UNIX access(2) system call. The
1738 function returns 0 if the file can be accessed with the speci‐
1739 fied mode, and -1 otherwise.
1740 args(s_fname)
1742 Returns the number of arguments expected by the user-defined
1743 function fname, or -1 if no such user-defined function exists.
1744 Note that this function examines only user-defined functions,
1745 not built-in functions. Its main use is to determine whether or
1746 not a particular user-defined function has been defined previ‐
1747 ously. The args() function is available only in versions of
1748 Remind from 03.00.04 and up.
1749 asc(s_string)
1751 Returns an INT that is the ASCII code of the first character in
1752 string. As a special case, asc("") returns 0.
1753 baseyr()
1755 Returns the "base year" that was compiled into Remind (normally
1756 1990.) All dates are stored internally as the number of days
1757 since 1 January of baseyr().
1758 char(i_i1 [,i_i2...])
1760 This function can take any number of INT arguments. It returns
1761 a STRING consisting of the characters specified by the argu‐
1762 ments. Note that none of the arguments can be 0, unless there
1763 is only one argument. As a special case, char(0) returns "".
1764 Note that because Remind does not support escaping of characters
1766 in strings, the only way to get a double-quote in a string is to
1767 use char(34).
1768 choose(i_index, x_arg1 [,x_arg2...])
1770 Choose must take at least two arguments, the first of which is
1771 an INT. If index is n, then the nth subsequent argument is
1772 returned. If index is less than 1, then arg1 is returned. If
1773 index is greater than the number of subsequent arguments, then
1774 the last argument is returned. Examples:
1775 choose(0, "foo", 1:13, 1000) returns "foo"
1777 choose(1, "foo", 1:13, 1000) returns "foo"
1778 choose(2, "foo", 1:13, 1000) returns 1:13
1779 choose(3, "foo", 1:13, 1000) returns 1000
1780 choose(4, "foo", 1:13, 1000) returns 1000
1781 Note that all arguments to choose() are always evaluated.
1782 coerce(s_type, x_arg)
1784 This function converts arg to the specified type, if such con‐
1785 version is possible. Type must be one of "INT", "STRING",
1786 "DATE", "TIME" or "DATETIME" (case-insensitive). The conversion
1787 rules are as follows:
1788 If arg is already of the type specified, it is returned
1790 unchanged.
1791 If type is "STRING", then arg is converted to a string consist‐
1793 ing of its printed representation.
1794 If type is "DATE", then an INT arg is converted by interpreting
1796 it as the number of days since 1 January baseyr(). A STRING arg
1797 is converted by attempting to read it as if it were a printed
1798 date. A DATETIME is converted to a date by dropping the time
1799 component. A TIME arg cannot be converted to a date.
1800 If type is "TIME", then an INT arg is converted by interpreting
1802 it as the number of minutes since midnight. A STRING arg is
1803 converted by attempting to read it as if it were a printed time.
1804 A DATETIME is converted to a time by dropping the date compo‐
1805 nent. A DATE arg cannot be converted to a time.
1806 If type is "DATETIME", then an INT arg is converted by inter‐
1808 preting it as the number of minutes since midnight, 1 January
1809 baseyr(). A STRING is converted by attempting to read it as if
1810 it were a printed datetime. Other types cannot be converted to
1811 a datetime.
1812 If type is "INT", then DATE, TIME and DATETIME arguments are
1814 converted using the reverse of procedures described above. A
1815 STRING arg is converted by parsing it as an integer.
1816 current()
1818 Returns the current date and time as a DATETIME object. This
1819 may be the actual date and time, or may be the date and time
1820 supplied on the command line.
1821 date(i_y, i_m, i_d)
1823 The date() function returns a DATE object with the year, month
1824 and day components specified by y, m and d.
1825 datepart(dq_datetime)
1827 Returns a DATE object representing the date portion of datetime.
1828 datetime(args)
1830 The datetime() function can take anywhere from two to five argu‐
1831 ments. It always returns a DATETIME generated from its argu‐
1832 ments.
1833 If you supply two arguments, the first must be a DATE and the
1835 second a TIME.
1836 If you supply three arguments, the first must be a DATE and the
1838 second and third must be INTs. The second and third arguments
1839 are interpreted as hours and minutes and converted to a TIME.
1840 If you supply four arguments, the first three must be INTs,
1842 interpreted as the year, month and day. The fourth argument
1843 must be a TIME.
1844 Finally, if you supply five arguments, they must all be INTs and
1846 are interpreted as year, month, day, hour and minute.
1847 dawn([dq_date])
1849 Returns the time of "civil dawn" on the specified date. If date
1850 is omitted, defaults to today(). If a datetime object is sup‐
1851 plied, only the date component is used.
1852 day(dq_date)
1854 This function takes a DATE or DATETIME as an argument, and
1855 returns an INT that is the day-of-month component of date.
1856 daysinmon(i_m, i_y)
1858 Returns the number of days in month m (1-12) of the year y.
1859 defined(s_var)
1861 Returns 1 if the variable named by var is defined, or 0 if it is
1862 not.
1863 Note that defined() takes a STRING argument; thus, to check if
1864 variable X is defined, use:
1865 defined("X")
1867 and not:
1869 defined(X)
1871 The second example will attempt to evaluate X, and will return
1873 an error if it is undefined or not of type STRING.
1874 dosubst(s_str [,d_date [,t_time]]) or dosubst(s_str [,q_datetime])
1876 Returns a STRING that is the result of passing str through the
1877 substitution filter described earlier. The parameters date and
1878 time (or datetime) establish the effective trigger date and time
1879 used by the substitution filter. If date and time are omitted,
1880 they default to today() and now().
1881 Note that if str does not end with "%", a newline character will
1883 be added to the end of the result. Also, calling dosubst() with
1884 a date that is in the past (i.e., if date < today()) will pro‐
1885 duce undefined results.
1886 Dosubst() is only available starting from version 03.00.04 of
1888 Remind.
1889 dusk([dq_date])
1891 Returns the time of "civil twilight" on the specified date. If
1892 date is omitted, defaults to today().
1893 easterdate(dqi_arg)
1895 If arg is an INT, then returns the date of Easter Sunday for the
1896 specified year. If arg is a DATE or DATETIME, then returns the
1897 date of the next Easter Sunday on or after arg. (The time com‐
1898 ponent of a datetime is ignored.)
1899 evaltrig(s_trigger [,dq_start])
1901 Evaluates trigger as if it were a REM or IFTRIG trigger specifi‐
1902 cation and returns the trigger date as a DATE (or as a DATETIME
1903 if there is an AT clause.) Returns a negative INT if no trigger
1904 could be computed.
1905 Normally, evaltrig finds a trigger date on or after today. If
1907 you supply the start argument, then it scans starting from
1908 there.
1909 For example, the expression:
1911 evaltrig("Mon 1", '2008-10-07')
1913 returns '2008-11-03', since that is the first date on or after 7
1915 October 2008 that satisfies "Mon 1".
1916 If you want to see how many days it is from the first Monday in
1918 October, 2008 to the first Monday in November, 2008, use:
1919 evaltrig("Mon 1", '2008-11-01') - evaltrig("Mon 1", '2008-10-01')
1921 and the answer is 28. The trigger argument to evaltrig can have
1923 all the usual trigger clauses (OMIT, AT, SKIP, etc.) but cannot
1924 have a SATISFY, MSG, etc. reminder-type clause.
1925 filedate(s_filename)
1927 Returns the modification date of filename. If filename does not
1928 exist, or its modification date is before the year baseyr(),
1929 then 1 January of baseyr() is returned.
1930 filedatetime(s_filename)
1932 Returns the modification date and time of filename. If filename
1933 does not exist, or its modification date is before the year
1934 baseyr(), then midnight, 1 January of baseyr() is returned.
1935 filedir()
1937 Returns the directory that contains the current file being pro‐
1938 cessed. It may be a relative or absolute pathname, but is guar‐
1939 anteed to be correct for use in an INCLUDE command as follows:
1940 INCLUDE [filedir()]/stuff
1942 This includes the file "stuff" in the same directory as the cur‐
1944 rent file being processed.
1945 filename()
1947 Returns (as a STRING) the name of the current file being pro‐
1948 cessed by Remind. Inside included files, returns the name of
1949 the included file.
1950 getenv(s_envvar)
1952 Similar to the getenv(2) system call. Returns a string repre‐
1953 senting the value of the specified environment variable.
1954 Returns "" if the environment variable is not defined. Note
1955 that the names of environment variables are generally case-sen‐
1956 sitive; thus, getenv("HOME") is not the same as getenv("home").
1957 hebdate(i_day, s_hebmon [,idq_yrstart [,i_jahr [,i_aflag]]])
1959 Support for Hebrew dates - see the section "The Hebrew Calendar"
1960 hebday(dq_date)
1962 Support for Hebrew dates - see the section "The Hebrew Calendar"
1963 hebmon(dq_date)
1965 Support for Hebrew dates - see the section "The Hebrew Calendar"
1966 hebyear(dq_date)
1968 Support for Hebrew dates - see the section "The Hebrew Calendar"
1969 hour(tq_time)
1971 Returns the hour component of time.
1972 iif(si_test1, x_arg1, [si_test2, x_arg2,...], x_default)
1974 If test1 is not zero or the null string, returns arg1. Other‐
1975 wise, if test2 is not zero or the null string, returns arg2, and
1976 so on. If all of the test arguments are false, returns default.
1977 Note that all arguments are always evaluated. This function
1978 accepts an odd number of arguments - note that prior to version
1979 03.00.05 of Remind, it accepted 3 arguments only. The 3-argu‐
1980 ment version of iif() is compatible with previous versions of
1981 Remind.
1982 index(s_search, s_target [,i_start)
1984 Returns an INT that is the location of target in the string
1985 search. The first character of a string is numbered 1. If tar‐
1986 get does not exist in search, then 0 is returned.
1987 The optional parameter start specifies the position in search at
1989 which to start looking for target.
1990 isdst([d_date [,t_time]]) or isdst(q_datetime)
1992 Returns a positive number if daylight saving time is in effect
1993 on the specified date and time. Date defaults to today() and
1994 time defaults to midnight.
1995 Note that this function is only as reliable as the C run-time
1997 library functions. It is available starting with version
1998 03.00.07 of Remind.
1999 isleap(idq_arg)
2001 Returns 1 if arg is a leap year, and 0 otherwise. Arg can be an
2002 INT, DATE or DATETIME object. If a DATE or DATETIME is sup‐
2003 plied, then the year component is used in the test.
2004 isomitted(dq_date)
2006 Returns 1 if date is omitted, given the current global OMIT con‐
2007 text. Returns 0 otherwise. (If a datetime is supplied, only
2008 the date part is used.) Note that any local OMIT or OMITFUNC
2009 clauses are not taken into account by this function.
2010 language()
2012 Returns a STRING naming the language supported by Remind. (See
2013 "Foreign Language Support.") By default, Remind is compiled to
2014 support English messages, so this function returns "English".
2015 For other languages, this function will return the English name
2016 of the language (e.g. "German") Note that language() is not
2017 available in versions of Remind prior to 03.00.02.
2018 lower(s_string)
2020 Returns a STRING with all upper-case characters in string con‐
2021 verted to lower-case.
2022 max(x_arg1 [,x_arg2...)
2024 Can take any number of arguments, and returns the maximum. The
2025 arguments can be of any type, but must all be of the same type.
2026 They are compared as with the > operator.
2027 min(x_arg1 [,x_arg2...)
2029 Can take any number of arguments, and returns the minimum. The
2030 arguments can be of any type, but must all be of the same type.
2031 They are compared as with the < operator.
2032 minsfromutc([d_date [,t_time]]) or minsfromutc(q_datetime)
2034 Returns the number of minutes from Universal Time Coordinated
2035 (formerly GMT) to local time on the specified date and time.
2036 Date defaults to today() and time defaults to midnight. If
2037 local time is before UTC, the result is negative. Otherwise,
2038 the result is positive.
2039 Note that this function is only as reliable as the C run-time
2041 library functions. It is available starting with version
2042 03.00.07 of Remind.
2043 minute(tq_time)
2045 Returns the minute component of time.
2046 mon(dqi_arg)
2048 If arg is of DATE or DATETIME type, returns a string that names
2049 the month component of the date. If arg is an INT from 1 to 12,
2050 returns a string that names the month.
2051 monnum(dq_date)
2053 Returns an INT from 1 to 12, representing the month component of
2054 date.
2055 moondate(i_phase [,d_date [,t_time]]) or moondate(i_phase, q_datetime)
2057 This function returns the date of the first occurrence of the
2058 phase phase of the moon on or after date and time. Phase can
2059 range from 0 to 3, with 0 signifying new moon, 1 first quarter,
2060 2 full moon, and 3 third quarter. If date is omitted, it
2061 defaults to today(). If time is omitted, it defaults to mid‐
2062 night.
2063 For example, the following returns the date of the next full
2065 moon:
2066 SET fullmoon moondate(2)
2068 moontime(i_phase [,d_date [,t_time]]) or moontime(i_phase, q_datetime)
2070 This function returns the time of the first occurrence of the
2071 phase phase of the moon on or after date and time. Phase can
2072 range from 0 to 3, with 0 signifying new moon, 1 first quarter,
2073 2 full moon, and 3 third quarter. If date is omitted, it
2074 defaults to today(). If time is omitted, it defaults to mid‐
2075 night. Moontime() is intended to be used in conjunction with
2076 moondate(). The moondate() and moontime() functions are accu‐
2077 rate to within a couple of minutes of the times in "Old Farmer's
2078 Almanac" for Ottawa, Ontario.
2079 For example, the following returns the date and time of the next
2081 full moon:
2082 MSG Next full moon at [moontime(2)] on [moondate(2)]
2084 moondatetime(i_phase [,d_date [,t_time]]) or moondatetime(i_phase,
2086 q_datetime)
2087 This function is similar to moondate and moontime, but returns a
2088 DATETIME result.
2089 moonphase([d_date [,t_time]]) or moonphase(q_datetime)
2091 This function returns the phase of the moon on date and time,
2092 which default to today() and midnight, respectively. The
2093 returned value is an integer from 0 to 359, representing the
2094 phase of the moon in degrees. 0 is a new moon, 180 is a full
2095 moon, 90 is first-quarter, etc.
2096 nonomitted(dq_start, dq_end [,s_wkday...])
2098 This function returns the number of non-omitted days between
2099 start and end. If start is non-omitted, then it is counted.
2100 end is never counted.
2101 Note that end must be greater than or equal to start or an error
2103 is reported. In addition to using the global OMIT context, you
2104 can supply additional arguments that are names of weekdays to be
2105 omitted. However, in a REM command, any local OMITFUNC clause
2106 is not taken into account by this function.
2107 For example, the following line sets a to 11 (assuming no global
2109 OMITs):
2110 set a nonomitted('2007-08-01', '2007-08-16', "Sat", "Sun")
2112 because Thursday, 16 August 2007 is the 11th working day (not
2114 counting Saturday and Sunday) after Wednesday, 1 August 2007.
2115 nonomitted has various uses. For example, many schools run on a
2117 six-day cycle and the day number is not incremented on holidays.
2118 Suppose the school year starts with Day 1 on 4 September 2007.
2119 The following reminder will label day numbers in a calendar:
2120 IF today() >= '2007-09-04'
2122 set daynum nonomitted('2007-09-04', today(), "Sat", "Sun")
2123 REM OMIT SAT SUN SKIP CAL Day [(daynum % 6) + 1]
2124 ENDIF
2125 Obviously, the answer you get from nonomitted depends on the
2127 global OMIT context. If you use moveable OMITs, you may get
2128 inconsistent results.
2129 Here is a more complex use for nonomitted. My garbage collec‐
2131 tion follows two interleaved 14-day cycles: One Friday, garbage
2132 and paper recycling ("Black Box") are collected. The next Fri‐
2133 day, garbage and plastic recycling ("Blue Box") are collected.
2134 If any of Monday-Friday is a holiday, collection is delayed
2135 until the Saturday. Here's a way to encode these rules:
2136 fset _garbhol(x) wkdaynum(x) == 5 && nonomitted(x-4, x+1) < 5
2138 REM 12 November 1999 *14 AFTER OMITFUNC _garbhol MSG Black Box
2139 REM 19 November 1999 *14 AFTER OMITFUNC _garbhol MSG Blue Box
2140 Here's how it works: The _garbhol(x) user-defined function
2142 returns 1 if and only if (1) x is a Friday and (2) there is at
2143 least one OMITted day from the previous Monday up to and includ‐
2144 ing the Friday.
2145 The first REM statement sets up the 14-day black-box cycle. The
2147 AFTER keyword makes it move collection to the Saturday if _garb‐
2148 hol returns 1. The second REM statement sets up the 14-day
2149 blue-box cycle with a similar adjustment made by AFTER in con‐
2150 junction with _garbhol.
2151 now() Returns the current system time, as a TIME type. This may be
2153 the actual time, or a time supplied on the command line.
2154 ord(i_num)
2156 Returns a string that is the ordinal number num. For example,
2157 ord(2) returns "2nd", and ord(213) returns "213th".
2158 ostype()
2160 Returns "UNIX". Remind used to run on OS/2 and MS-DOS, but does
2161 not any longer.
2162 plural(i_num [,s_str1 [,s_str2]])
2164 Can take from one to three arguments. If one argument is sup‐
2165 plied, returns "s" if num is not 1, and "" if num is 1.
2166 If two arguments are supplied, returns str1 + "s" if num is not
2168 1. Otherwise, returns str1.
2169 If three arguments are supplied, returns str1 if num is 1, and
2171 str2 otherwise.
2172 psmoon(i_phase [,i_size [,s_note [,i_notesize]]])
2174 [DEPRECATED] Returns a STRING consisting of PostScript code to
2175 draw a moon in the upper-left hand corner of the calendar box.
2176 Phase specifies the phase of the moon, and is 0 (new moon), 1
2177 (first quarter), 2 (full moon) or 3 (third quarter). If size is
2178 specified, it controls the radius of the moon in PostScript
2179 units (1/72 inch.) If it is not specified or is negative, the
2180 size of the day-number font is used.
2181 For example, the following four lines place moon symbols on the
2183 PostScript calendar:
2184 REM [moondate(0)] PS [psmoon(0)]
2186 REM [moondate(1)] PS [psmoon(1)]
2187 REM [moondate(2)] PS [psmoon(2)]
2188 REM [moondate(3)] PS [psmoon(3)]
2189 If note is specified, the text is used to annotate the moon dis‐
2191 play. The font is the same font used for calendar entries. If
2192 notesize is given, it specifies the font size to use for the
2193 annotation, in PostScript units (1/72 inch.) If notesize is not
2194 given, it defaults to the size used for calendar entries. (If
2195 you annotate the display, be careful not to overwrite the day
2196 number -- Remind does not check for this.) For example, if you
2197 want the time of each new moon displayed, you could use this in
2198 your reminder script:
2199 REM [moondate(0)] PS [psmoon(0, -1, moontime(0)+"")]
2201 Note how the time is coerced to a string by concatenating the
2203 null string.
2204 psshade(i_gray) or psshade(i_red, i_green, i_blue)
2206 [DEPRECATED] Returns a STRING that consists of PostScript com‐
2207 mands to shade a calendar box. Num can range from 0 (completely
2208 black) to 100 (completely white.) If three arguments are given,
2209 they specify red, green and blue intensity from 0 to 100.
2210 Here's an example of how to use this:
2211 REM Sat Sun PS [psshade(95)]
2213 The above command emits PostScript code to lightly shade the
2215 boxes for Saturday and Sunday in a PostScript calendar.
2216 Note that psmoon and psshade are deprecated; instead you should
2218 use the SPECIAL SHADE and SPECIAL MOON reminders as described in
2219 "Out-of-Band Reminders."
2220 realcurrent()
2222 Returns (as a DATETIME) the true date and time of day as pro‐
2223 vided by the operating system. This is in contrast to cur‐
2224 rent(), which may return a time supplied on the command line.
2225 realnow()
2227 Returns the true time of day as provided by the operating sys‐
2228 tem. This is in contrast to now(), which may return a time sup‐
2229 plied on the command line.
2230 realtoday()
2232 Returns the date as provided by the operating system. This is
2233 in contrast to Remind's concept of "today", which may be changed
2234 if it is running in calendar mode, or if a date has been sup‐
2235 plied on the command line.
2236 sgn(i_num)
2238 Returns -1 if num is negative, 1 if num is positive, and 0 if
2239 num is zero.
2240 shell(s_cmd [,i_maxlen])
2242 Executes cmd as a system command, and returns the first 511
2243 characters of output resulting from cmd. Any whitespace charac‐
2244 ter in the output is converted to a space. Note that if RUN OFF
2245 has been executed, or the -r command-line option has been used,
2246 shell() will result in an error, and cmd will not be executed.
2247 If maxlen is specified, then shell() returns the first maxlen
2249 characters of output (rather than the first 511). If maxlen is
2250 specified as a negative number, then all the output from cmd is
2251 returned.
2252 slide(d_start, i_amt [,s_wkday...])
2254 This function is the inverse of nonomitted. It adds amt days
2255 (which can be negative) to start, not counting omitted days.
2256 The optional wkday arguments are additional weekday names to
2257 omit.
2258 Consider this example:
2260 OMIT 14 May 2009
2262 SET a slide('2009-05-13', 5, "Sat", "Sun")
2263 In this case, a is set to 2009-05-21. That's because we slide
2265 forward by 5 days, not including Thursday, May 14 or Saturday
2266 and Sunday, May 16 and 17. You can go backwards, too, so:
2267 OMIT 14 May 2009
2269 SET a slide('2009-05-21', -5, "Sat", "Sun")
2270 takes a back to 2009-05-13.
2272 strlen(s_str)
2274 Returns the length of str.
2275 substr(s_str, i_start [,i_end])
2277 Returns a STRING consisting of all characters in str from start
2278 up to and including end. Characters are numbered from 1. If
2279 end is not supplied, then it defaults to the length of str.
2280 sunrise([dq_date])
2282 Returns a TIME indicating the time of sunrise on the specified
2283 date (default today().) In high latitudes, there may be no sun‐
2284 rise on a particular day, in which case sunrise() returns the
2285 INT 0 if the sun never sets, or 1440 if it never rises.
2286 sunset([dq_date])
2288 Returns a TIME indicating the time of sunset on the specified
2289 date (default today().) In high latitudes, there may be no sun‐
2290 set on a particular day, in which case sunset() returns the INT
2291 0 if the sun never rises, or 1440 if it never sets.
2292 The functions sunrise() and sunset() are based on an algorithm
2294 in "Almanac for Computers for the year 1978" by L. E. Doggett,
2295 Nautical Almanac Office, USNO. They require the latitude and
2296 longitude to be specified by setting the appropriate system
2297 variables. (See "System Variables".) The sun functions should
2298 be accurate to within about 4 minutes for latitudes lower than
2299 60 degrees. The functions are available starting from version
2300 03.00.07 of Remind.
2301 time(i_hr, i_min)
2303 Creates a TIME with the hour and minute components specified by
2304 hr and min.
2305 timepart(tq_datetime)
2307 Returns a TIME object representing the time portion of datetime.
2308 today()
2310 Returns Remind's notion of "today." This may be the actual sys‐
2311 tem date, or a date supplied on the command line, or the date of
2312 the calendar entry currently being computed.
2313 trigdate()
2315 Returns the calculated trigger date of the last REM or IFTRIG
2316 command. If used in the body of a REM command, returns that
2317 command's trigger date. If the most recent REM command did not
2318 yield a computable trigger date, returns the integer 0.
2319 trigdatetime()
2321 Similar to trigdate(), but returns a DATETIME if the most recent
2322 triggerable REM command had an AT clause. If there was no AT
2323 clause, returns a DATE. If no trigger could be computed,
2324 returns the integer 0.
2325 trigger(d_date [,t_time [,i_utcflag]]) or trigger(q_datetime
2327 [,i_utcflag])
2328 Returns a string suitable for use in a REM command or a SCANFROM
2329 or UNTIL clause, allowing you to calculate trigger dates in
2330 advance. Note that in earlier versions of Remind, trigger was
2331 required to convert a date into something the REM command could
2332 consume. However, in this version of Remind, you can omit it.
2333 Note that trigger() always returns its result in English, even
2334 for foreign-language versions of Remind. This is to avoid prob‐
2335 lems with certain C libraries that do not handle accented char‐
2336 acters properly. Normally, the date and time are the local date
2337 and time; however, if utcflag is non-zero, the date and time are
2338 interpreted as UTC times, and are converted to local time.
2339 Examples:
2340 trigger('1993/04/01')
2342 returns "1 April 1993",
2344 trigger('1994/08/09', 12:33)
2346 returns "9 August 1994 AT 12:33", as does:
2348 trigger('1994/08/09@12:33').
2350 Finally:
2352 trigger('1994/12/01', 03:00, 1)
2354 returns "30 November 1994 AT 22:00" for EST, which is 5 hours
2356 behind UTC. The value for your time zone may differ.
2357 trigtime()
2359 Returns the time of the last REM command with an AT clause. If
2360 the last REM did not have an AT clause, returns the integer 0.
2361 trigvalid()
2363 Returns 1 if the value returned by trigdate() is valid for the
2364 most recent REM command, or 0 otherwise. Sometimes REM commands
2365 cannot calculate a trigger date. For example, the following REM
2366 command can never be triggered:
2367 REM Mon OMIT Mon SKIP MSG Impossible!
2369 typeof(x_arg)
2371 Returns "STRING", "INT", "DATE", "TIME" or "DATETIME", depending
2372 on the type of arg.
2373 tzconvert(q_datetime, s_srczone [,s_dstzone])
2375 Converts datetime from the time zone named by srczone to the
2376 time zone named by dstzone. If dstzone is omitted, the default
2377 system time zone is used. The return value is a DATETIME. Time
2378 zone names are system-dependent; consult your operating system
2379 for legal values. Here is an example:
2380 tzconvert('2007-07-08@01:14', "Canada/Eastern", "Canada/Pacific")
2382 returns
2384 2007-07-07@22:14
2386 upper(s_string)
2388 Returns a STRING with all lower-case characters in string con‐
2389 verted to upper-case.
2390 value(s_varname [,x_default])
2392 Returns the value of the specified variable. For example,
2393 value("X"+"Y") returns the value of variable XY, if it is
2394 defined. If XY is not defined, an error results.
2395 However, if you supply a second argument, it is returned if the
2397 varname is not defined. The expression value("XY", 0) will
2398 return 0 if XY is not defined, and the value of XY if it is
2399 defined.
2400 version()
2402 Returns a string specifying the version of Remind. For version
2403 03.00.04, returns "03.00.04". It is guaranteed that as new ver‐
2404 sions of Remind are released, the value returned by version()
2405 will strictly increase, according to the rules for string order‐
2406 ing.
2407 weekno([dq_date, [i_wkstart, [i_daystart]]])
2409 Returns the week number of the year. If no arguments are sup‐
2410 plied, returns the ISO 8601 week number for today(). If one
2411 argument date is supplied, then returns the ISO 8601 week number
2412 for that date. If two arguments are supplied, then wkstart must
2413 range from 0 to 6, and represents the first day of the week
2414 (with 0 being Sunday and 6 being Saturday.). If wkstart is not
2415 supplied, then it defaults to 1. If the third argument daystart
2416 is supplied, then it specifies when Week 1 starts. If daystart
2417 is less than or equal to 7, then Week 1 starts on the first
2418 wkstart on or after January daystart. Otherwise, Week 1 starts
2419 on the first wkstart on or after December daystart. If omitted,
2420 daystart defaults to 29 (following the ISO 8601 definition.)
2421 wkday(dqi_arg)
2423 If arg is a DATE or DATETIME, returns a string representing the
2424 day of the week of the date. If arg is an INT from 0 to 6,
2425 returns the corresponding weekday ("Sunday" to "Saturday").
2426 wkdaynum(dq_date)
2428 Returns a number from 0 to 6 representing the day-of-week of the
2429 specified date. (0 represents Sunday, and 6 represents Satur‐
2430 day.)
2431 year(dq_date)
2433 Returns a INT that is the year component of date.
2434
2436 An extremely powerful feature of Remind is its macro capability, or
2437 "expression pasting."
2438 In almost any situation where Remind is not expecting an expression,
2440 you can "paste" an expression in. To do this, surround the expression
2441 with square brackets. For example:
2442 REM [mydate] MSG foo
2444 This evaluates the expression "mydate", where "mydate" is presumably
2446 some pre-computed variable, and then "pastes" the result into the com‐
2447 mand-line for the parser to process.
2448 A formal description of this is: When Remind encounters a "pasted-in"
2450 expression, it evaluates the expression, and coerces the result to a
2451 STRING. It then substitutes the string for the pasted-in expression,
2452 and continues parsing. Note, however, that expressions are evaluated
2453 only once, not recursively. Thus, writing:
2454 ["[a+b]"]
2456 causes Remind to read the token "[a+b]". It does not interpret this as
2458 a pasted-in expression. In fact, the only way to get a literal left-
2459 bracket into a reminder is to use ["["].
2460 You can use expression pasting almost anywhere. However, there are a
2462 few exceptions:
2463 o If Remind is expecting an expression, as in the SET command, or
2465 the IF command, you should not include square brackets. For
2466 example, use:
2467 SET a 4+5
2469 and not:
2470 SET a [4+5]
2471 o You cannot use expression pasting for the first token on a line.
2473 For example, the following will not work:
2474 ["SET"] a 1
2476 This restriction is because Remind must be able to unambiguously
2478 determine the first token of a line for the flow-control com‐
2479 mands (to be discussed later.)
2480 In fact, if Remind cannot determine the first token on a line,
2482 it assumes that it is a REM command. If expression-pasting is
2483 used, Remind assumes it is a REM command. Thus, the following
2484 three commands are equivalent:
2485 REM 12 Nov 1993 AT 13:05 MSG BOO!
2487 12 Nov 1993 AT 13:05 MSG BOO!
2488 [12] ["Nov " + 1993] AT [12:05+60] MSG BOO!
2489 o You cannot use expression-pasting to determine the type (MSG,
2491 CAL, etc.) of a REM command. You can paste expressions before
2492 and after the MSG, etc keywords, but cannot do something like
2493 this:
2494 REM ["12 Nov 1993 AT 13:05 " + "MSG" + " BOO!"]
2496 COMMON PITFALLS IN EXPRESSION PASTING
2498 Remember, when pasting in expressions, that extra spaces are not
2500 inserted. Thus, something like:
2501 REM[expr]MSG[expr]
2503 will probably fail.
2505 If you use an expression to calculate a delta or back, ensure that the
2507 result is a positive number. Something like:
2508 REM +[mydelta] Nov 12 1993 MSG foo
2510 will fail if mydelta happens to be negative.
2512
2514 Remind has commands that control the flow of a reminder script. Nor‐
2515 mally, reminder scripts are processed sequentially. However, IF and
2516 related commands allow you to process files conditionally, and skip
2517 sections that you don't want interpreted.
2518 THE IF COMMAND
2520 The IF command has the following form:
2522 IF expr
2524 t-command
2525 t-command...
2526 ELSE
2527 f-command
2528 f-command...
2529 ENDIF
2530 Note that the commands are shown indented for clarity. Also, the ELSE
2532 portion can be omitted. IF commands can be nested up to a small limit,
2533 probably around 8 or 16 levels of nesting, depending on your system.
2534 If the expr evaluates to a non-zero INT, or a non-null STRING, then the
2536 IF portion is considered true, and the t-commands are executed. If
2537 expr evaluates to zero or null, then the f-commands (if the ELSE por‐
2538 tion is present) are executed. If expr is not of type INT or STRING,
2539 then it is an error.
2540 Examples:
2542 IF defined("want_hols")
2544 INCLUDE /usr/share/remind/holidays
2545 ENDIF
2546 IF today() > '1992/2/10'
2548 set missed_ap "You missed it!"
2549 ELSE
2550 set missed_ap "Still have time..."
2551 ENDIF
2552 THE IFTRIG COMMAND
2554 The IFTRIG command is similar to an IF command, except that it computes
2556 a trigger (as in the REM command), and evaluates to true if a corre‐
2557 sponding REM command would trigger. Examples:
2558 IFTRIG 1 Nov
2560 ; Executed on 1 Nov
2561 ELSE
2562 ; Executed except on 1 Nov
2563 ENDIF
2564 IFTRIG 1 -1 OMIT Sat Sun +4
2566 ; Executed on last working day of month,
2567 ; and the 4 working days preceding it
2568 ELSE
2569 ; Executed except on above days
2570 ENDIF
2571 Note that the IFTRIG command computes a trigger date, which can be
2573 retrieved with the trigdate() function. You can use all of the normal
2574 trigger components, such as UNTIL, delta, etc in the IFTRIG command.
2575
2577 In addition to the built-in functions, Remind allows you to define your
2578 own functions. The FSET command does this for you:
2579 FSET fname(args) expr
2581 Fname is the name of the function, and follows the convention for nam‐
2583 ing variables. Args is a comma-separated list of arguments, and expr
2584 is an expression. Args can be empty, in which case you define a func‐
2585 tion taking no parameters. Here are some examples:
2586 FSET double(x) 2*x
2588 FSET yeardiff(date1, date2) year(date1) - year(date2)
2589 FSET since(x) ord(year(trigdate())-x)
2590 The last function is useful in birthday reminders. For example:
2592 REM 1 Nov +12 MSG Dean's [since(1984)] birthday is %b.
2594 Dean was born in 1984. The above example, on 1 November 1992, would
2596 print:
2597 Dean's 8th birthday is today.
2599 Notes:
2601 o If you access a variable in expr that is not in the list of
2603 arguments, the "global" value (if any) is used.
2604 o Function and parameter names are significant only to 12 charac‐
2606 ters.
2607 o The value() function always accesses the "global" value of a
2609 variable, even if it has the same name as an argument. For
2610 example:
2611 fset func(x) value("x")
2613 set x 1
2614 set y func(5)
2615 The above sequence sets y to 1, which is the global value of x.
2617 o User-defined functions may call other functions, including other
2619 user-defined functions. However, recursive calls are not
2620 allowed.
2621 o User-defined functions are not syntax-checked when they are
2623 defined; parsing occurs only when they are called.
2624 o If a user-defined function has the same name as a built-in func‐
2626 tion, it is ignored and the built-in function is used. To pre‐
2627 vent conflicts with future versions of Remind (which may define
2628 more built-in functions), you may wish to name all user-defined
2629 functions beginning with an underscore.
2630
2632 The WARN keyword allows precise control over advance warning in a more
2633 flexible manner than the delta mechanism. It should be followed by the
2634 name of a user-defined function, warn_function.
2635 If a warn_function is supplied, then it must take one argument of type
2637 INT. Remind ignores any delta, and instead calls warn_function succes‐
2638 sively with the arguments 1, 2, 3, ...
2639 Warn_function's return value n is interpreted as follows:
2641 o If n is positive, then the reminder is triggered exactly n days
2643 before its trigger date.
2644 o If n is negative, then it is triggered n days before its trigger
2646 date, not counting OMITted days.
2647 As an example, suppose you wish to be warned of American Independence
2649 Day 5, 3, and 1 days in advance. You could use this:
2650 FSET _wfun(x) choose(x, 5, 3, 1, 0)
2652 REM 4 July WARN _wfun MSG American Independence Day is %b.
2653 NOTES
2655 1 If an error occurs during the evaluation of warn_function, then
2657 Remind stops calling it and simply issues the reminder on its
2658 trigger date.
2659 2 If the absolute-values of the return values of warn_function are
2661 not monotonically decreasing, Remind stops calling it and issues
2662 the reminder on its trigger date.
2663 3 Warn_function should (as a matter of good style) return 0 as the
2665 final value in its sequence of return values. However, a
2666 reminder will always be triggered on its trigger date, regard‐
2667 less of what warn_function does.
2668 Similarly to WARN, the SCHED keyword allows precise control over the
2670 scheduling of timed reminders. It should be followed by the name of a
2671 user-defined function, sched_function.
2672 If a scheduling function is supplied, then it must take one argument of
2674 type INT. Rather than using the AT time, time delta, and time repeat,
2675 Remind calls the scheduling function to determine when to trigger the
2676 reminder. The first time the reminder is queued, the scheduling func‐
2677 tion is called with an argument of 1. Each time the reminder is trig‐
2678 gered, it is re-scheduled by calling the scheduling function again. On
2679 each call, the argument is incremented by one.
2680 The return value of the scheduling function must be an INT or a TIME.
2682 If the return value is a TIME, then the reminder is re-queued to trig‐
2683 ger at that time. If it is a positive integer n, then the reminder is
2684 re-queued to trigger at the previous trigger time plus n minutes.
2685 Finally, if it is a negative integer or zero, then the reminder is re-
2686 queued to trigger n minutes before the AT time. Note that there must
2687 be an AT clause for the SCHED clause to do anything.
2688 Here's an example:
2690 FSET _sfun(x) choose(x, -60, 30, 15, 10, 3, 1, 1, 1, 1, 0)
2692 REM AT 13:00 SCHED _sfun MSG foo
2693 The reminder would first be triggered at 13:00-60 minutes, or at 12:00.
2695 It would next be triggered 30 minutes later, at 12:30. Then, it would
2696 be triggered at 12:45, 12:55, 12:58, 12:59, 13:00, 13:01 and 13:02.
2697 NOTES
2699 1 If an error occurs during the evaluation of sched_func, then
2701 Remind reverts to using the AT time and the delta and repeat
2702 values, and never calls sched_func again.
2703 2 If processing sched_func yields a time earlier than the current
2705 system time, it is repeatedly called with increasing argument
2706 until it yields a value greater than or equal to the current
2707 time. However, if the sequence of values calculated during the
2708 repetition is not strictly increasing, then Remind reverts to
2709 the default behaviour and never calls sched_func again.
2710 3 It is quite possible using sched_func to keep triggering a
2712 reminder even after the AT-time. However, it is not possible to
2713 reschedule a reminder past midnight - no crossing of date bound‐
2714 aries is allowed. Also, it is quite possible to not trigger a
2715 reminder on the AT time when you use a scheduling function.
2716 However, if your scheduling function is terminated (for reasons
2717 1 and 2) before the AT time of the reminder, it will be trig‐
2718 gered at the AT time, because normal processing takes over.
2719 4 Your scheduling functions should (as a matter of good style)
2721 return 0 when no more scheduling is required. See the example.
2722 5 All scheduling functions are evaluated after the entire Remind
2724 script has been read in. So whatever function definitions are
2725 in effect at the end of the script are used.
2726
2728 The form of REM that uses SATISFY is as follows:
2729 REM trigger SATISFY expr
2731 The way this works is as follows: Remind first calculates a trigger
2733 date, in the normal fashion. Next, it sets trigdate() to the calcu‐
2734 lated trigger date. It then evaluates expr. If the result is not the
2735 null string or zero, processing ends. Otherwise, Remind computes the
2736 next trigger date, and re-tests expr. This iteration continues until
2737 expr evaluates to non-zero or non-null, or until the iteration limit
2738 specified with the -x command-line option is reached.
2739 If expr is not satisfied, then trigvalid() is set to 0. Otherwise,
2741 trigvalid() is set to 1. In any event, no error message is issued.
2742 This is really useful only if expr involves a call to the trigdate()
2744 function; otherwise, expr will not change as Remind iterates.
2745 An example of the usefulness of SATISFY: Suppose you wish to be warned
2747 of every Friday the 13th. Your first attempt may be:
2748 # WRONG!
2750 REM Fri 13 +2 MSG Friday the 13th is %b.
2751 But this won't work. This reminder triggers on the first Friday on or
2753 after the 13th of each month. The way to do it is with a more compli‐
2754 cated sequence:
2755 REM 13 SATISFY wkdaynum(trigdate()) == 5
2757 IF trigvalid()
2758 REM [trigdate()] +2 MSG \
2759 Friday the 13th is %b.
2760 ENDIF
2761 Let's see how this works. The SATISFY clause iterates through all the
2763 13ths of successive months, until a trigger date is found whose day-of-
2764 week is Friday (== 5). If a valid date was found, we use the calcu‐
2765 lated trigger date to set up the next reminder.
2766 We could also have written:
2768 REM Fri SATISFY day(trigdate()) == 13
2770 but this would result in more iterations, since "Fridays" occur more
2772 often than "13ths of the month."
2773 This technique of using one REM command to calculate a trigger date to
2775 be used by another command is quite powerful. For example, suppose you
2776 wanted to OMIT Labour day, which is the first Monday in September. You
2777 could use:
2778 # Note: SATISFY 1 is an idiom for "do nothing"
2780 REM Mon 1 Sept SATISFY 1
2781 OMIT [trigdate()]
2782 CAVEAT: This only omits the next Labour Day, not all Labour Days in the
2784 future. This could cause strange results, as the OMIT context can
2785 change depending on the current date. For example, if you use the fol‐
2786 lowing command after the above commands:
2787 REM Mon AFTER msg hello
2789 the result will not be as you expect. Consider producing a calendar
2791 for September, 1992. Labour Day was on Monday, 7 September, 1992.
2792 However, when Remind gets around to calculating the trigger for Tues‐
2793 day, 8 September, 1992, the OMIT command will now be omitting Labour
2794 Day for 1993, and the "Mon AFTER" command will not be triggered. (But
2795 see the description of SCANFROM in the section "Details about Trigger
2796 Computation.")
2797 It is probably best to stay away from computing OMIT trigger dates
2799 unless you keep these pitfalls in mind.
2800 For versions of Remind starting from 03.00.07, you can include a MSG,
2802 RUN, etc. clause in a SATISFY clause as follows:
2803 REM trigger_stuff SATISFY [expr] MSG body
2805 Note that for this case only, the expr after SATISFY must be enclosed
2807 in braces. It must come after all the other components of the trigger,
2808 and immediately before the MSG, RUN, etc. keyword. If expr cannot be
2809 satisfied, then the reminder is not triggered.
2810 Thus, the "Friday the 13th" example can be expressed more compactly as:
2812 REM 13 +2 SATISFY [wkdaynum(trigdate()) == 5] \
2814 MSG Friday the 13th is %b.
2815 And you can trigger a reminder on Mondays, Wednesdays and Thursdays
2817 occurring on odd-numbered days of the month with the following:
2818 REM Mon Wed Thu SATISFY [day(trigdate())%2] \
2820 MSG Here it is!!!
2821 Note that SATISFY and OMITFUNC can often be used to solve the same
2823 problem, though in different ways. Sometimes a SATISFY is cleaner and
2824 sometimes an OMITFUNC; experiment and use whichever seems clearer.
2825
2827 Although the command-line -d option is useful for debugging, it is
2828 often overkill. For example, if you turn on the -dx option for a
2829 reminder file with many complex expressions, you'll get a huge amount
2830 of output. The DEBUG command allows you to control the debugging flags
2831 under program control. The format is:
2832 DEBUG [+flagson] [-flagsoff]
2834 Flagson and flagsoff consist of strings of the characters "extvlf" that
2836 correspond to the debugging options discussed in the command-line
2837 options section. If preceded with a "+", the corresponding group of
2838 debugging options is switched on. Otherwise, they are switched off.
2839 For example, you could use this sequence to debug a complicated expres‐
2840 sion:
2841 DEBUG +x
2843 set a very_complex_expression(many_args)
2844 DEBUG -x
2845 THE DUMPVARS COMMAND
2847 The command DUMPVARS displays the values of variables in memory. Its
2849 format is:
2850 DUMPVARS [var...]
2852 If you supply a space-separated list of variable names, the correspond‐
2854 ing variables are displayed. If you do not supply a list of variables,
2855 then all variables in memory are displayed. To dump a system variable,
2856 put its name in the list of variables to dump. If you put a lone dol‐
2857 lar sign in the list of variables to dump, then all system variables
2858 will be dumped.
2859 THE ERRMSG COMMAND
2861 The ERRMSG command has the following format:
2863 ERRMSG body
2865 The body is passed through the substitution filter (with an implicit
2867 trigger date of today()) and printed to the error output stream. Exam‐
2868 ple:
2869 IF !defined("critical_var")
2871 ERRMSG You must supply a value for "critical_var"
2872 EXIT
2873 ENDIF
2874 THE EXIT COMMAND
2876 The above example also shows the use of the EXIT command. This causes
2878 an unconditional exit from script processing. Any queued timed
2879 reminders are discarded. If you are in calendar mode (described next),
2880 then the calendar processing is aborted.
2881 If you supply an INT-type expression after the EXIT command, it is
2883 returned to the calling program as the exit status. Otherwise, an exit
2884 status of 99 is returned.
2885 THE FLUSH COMMAND
2887 This command simply consists of the word FLUSH on a line by itself.
2889 The command flushes the standard output and standard error streams used
2890 by Remind. This is not terribly useful to most people, but may be use‐
2891 ful if you run Remind as a subprocess of another program, and want to
2892 use pipes for communication.
2893
2895 If you supply the -c, -s or -p command-line option, then Remind runs in
2896 "calendar mode." In this mode, Remind interprets the script repeat‐
2897 edly, performing one iteration through the whole file for each day in
2898 the calendar. Reminders that trigger are saved in internal buffers,
2899 and then inserted into the calendar in the appropriate places.
2900 If you also supply the -a option, then Remind will not include timed
2902 reminders in the calendar.
2903 The -p option is used in conjunction with the Rem2PS program to produce
2905 a calendar in PostScript format. For example, the following command
2906 will send PostScript code to standard output:
2907 remind -p .reminders | rem2ps
2909 You can print a PostScript calendar by piping this to the lpr command.
2911 If you have a reminder script called ".reminders", and you execute this
2913 command:
2914 remind -c .reminders jan 1993
2916 then Remind executes the script 31 times, once for each day in January.
2918 Each time it executes the script, it increments the value of today().
2919 Any reminders whose trigger date matches today() are entered into the
2920 calendar.
2921 MSG and CAL-type reminders, by default, have their entire body inserted
2923 into the calendar. RUN-type reminders are not normally inserted into
2924 the calendar. However, if you enclose a portion of the body in the
2925 %"...%" sequence, only that portion is inserted. For example, consider
2926 the following:
2927 REM 6 Jan MSG %"Dianne's birthday%" is %b
2929 In the normal mode, Remind would print "Dianne's birthday is today" on
2931 6 January. However, in the calendar mode, only the text "Dianne's
2932 birthday" is inserted into the box for 6 January.
2933 If you explicitly use the %"...%" sequence in a RUN-type reminder, then
2935 the text between the delimiters is inserted into the calendar. If you
2936 use the sequence %"%" in a MSG or CAL-type reminder, then no calendar
2937 entry is produced for that reminder.
2938 PRESERVING VARIABLES
2940 Because Remind iterates through the script for each day in the calen‐
2942 dar, slow operations may severely reduce the speed of producing a cal‐
2943 endar.
2944 For example, suppose you set the variables "me" and "hostname" as fol‐
2946 lows:
2947 SET me shell("whoami")
2949 SET hostname shell("hostname")
2950 Normally, Remind clears all variables between iterations in calendar
2952 mode. However, if certain variables are slow to compute, and will not
2953 change between iterations, you can "preserve" their values with the
2954 PRESERVE command. Also, since function definitions are preserved
2955 between calendar iterations, there is no need to redefine them on each
2956 iteration. Thus, you could use the following sequence:
2957 IF ! defined("initialized")
2959 set initialized 1
2960 set me shell("whoami")
2961 set hostname shell("hostname")
2962 fset func(x) complex_expr
2963 preserve initialized me hostname
2964 ENDIF
2965 The operation is as follows: On the first iteration through the
2967 script, "initialized" is not defined. Thus, the commands between IF
2968 and ENDIF are executed. The PRESERVE command ensures that the values
2969 of initialized, me and hostname are preserved for subsequent itera‐
2970 tions. On the next iteration, the commands are skipped, since initial‐
2971 ized has remained defined. Thus, time-consuming operations that do not
2972 depend on the value of today() are done only once.
2973 System variables (those whose names start with '$') are automatically
2975 preserved between calendar iterations.
2976 Note that for efficiency, Remind caches the reminder script (and any
2978 INCLUDEd files) in memory when producing a calendar.
2979 Timed reminders are sorted and placed into the calendar in time order.
2981 These are followed by non-timed reminders. Remind automatically places
2982 the time of timed reminders in the calendar according to the -b com‐
2983 mand-line option. Reminders in calendar mode are sorted as if the -g
2984 option had been used; you can change the sort order in calendar mode by
2985 explicitly using the -g option to specify a different order from the
2986 default.
2987 REPEATED EXECUTION
2989 If you supply a repeat parameter on the command line, and do not use
2991 the -c, -p, or -s options, Remind operates in a similar manner to cal‐
2992 endar mode. It repeatedly executes the reminder script, incrementing
2993 today() with each iteration. The same rules about preserving variables
2994 and function definitions apply. Note that using repeat on the command
2995 line also enables the -q option and disables any -z option. As an
2996 example, if you want to see how Remind will behave for the next week,
2997 you can type:
2998 remind .reminders '*7'
3000 If you want to print the dates of the next 1000 days, use:
3002 (echo 'banner %'; echo 'msg [today()]%') | remind - '*1000'
3004
3006 The -i option is used to initialize variables on the Remind command
3007 line. The format is -ivar=expr, where expr is any valid expression.
3008 Note that you may have to use quotes or escapes to prevent the shell
3009 from interpreting special characters in expr. You can have as many -i
3010 options as you want on the command line, and they are processed in
3011 order. Thus, if a variable is defined in one -i option, it can be
3012 referred to by subsequent -i options.
3013 Note that if you supply a date on the command line, it is not parsed
3015 until all options have been processed. Thus, if you use today() in any
3016 of the -i expressions, it will return the same value as realtoday() and
3017 not the date supplied on the command line.
3018 Any variables defined on the command line are preserved as with the
3020 PRESERVE command.
3021 You should not have any spaces between the -i option and the equal
3023 sign; otherwise, strange variable names are created that can only be
3024 accessed with the value() or defined() functions.
3025 You can also define a function on the command line by using:
3027 -ifunc(args)=definition
3029 Be sure to protect special characters from shell interpretation.
3031
3033 The PS and PSFILE reminders pass PostScript code directly to the
3034 printer. They differ in that the PS-type reminder passes its body
3035 directly to the PostScript output (after processing by the substitution
3036 filter) while the PSFILE-type's body should simply consist of a file‐
3037 name. The Rem2PS program will open the file named in the PSFILE-type
3038 reminder, and include its contents in the PostScript output.
3039 The PostScript-type reminders for a particular day are included in the
3041 PostScript output in sorted order of priority. Note that the order of
3042 PostScript commands has a major impact on the appearance of the calen‐
3043 dars. For example, PostScript code to shade a calendar box will oblit‐
3044 erate code to draw a moon symbol if the moon symbol code is placed in
3045 the calendar first. For this reason, you should not provide PS or
3046 PSFILE-type reminders with priorities; instead, you should ensure that
3047 they appear in the reminder script in the correct order. PostScript
3048 code should draw objects working from the background to the foreground,
3049 so that foreground objects properly overlay background ones. If you
3050 prioritize these reminders and run the script using descending sort
3051 order for priorities, the PostScript output will not work.
3052 All of the PostScript code for a particular date is enclosed in a save-
3054 restore pair. However, if several PostScript-type reminders are trig‐
3055 gered for a single day, each section of PostScript is not enclosed in a
3056 save-restore pair - instead, the entire body of included PostScript is
3057 enclosed.
3058 PostScript-type reminders are executed by the PostScript printer before
3060 any regular calendar entries. Thus, regular calendar entries will
3061 overlay the PostScript-type reminders, allowing you to create shaded or
3062 graphical backgrounds for particular days.
3063 Before executing your PostScript code, the origin of the PostScript
3065 coordinate system is positioned to the bottom left-hand corner of the
3066 "box" in the calendar representing today(). This location is exactly
3067 in the middle of the intersection of the bottom and left black lines
3068 delineating the box - you may have to account for the thickness of
3069 these lines when calculating positions.
3070 Several PostScript variables are available to the PostScript code you
3072 supply. All distance and size variables are in PostScript units (1/72
3073 inch.) The variables are:
3074 LineWidth
3076 The width of the black grid lines making up the calendar.
3077 Border The border between the center of the grid lines and the space
3079 used to print calendar entries. This border is normally blank
3080 space.
3081 BoxWidth and BoxHeight
3083 The width and height of the calendar box, from center-to-center
3084 of the black gridlines.
3085 InBoxHeight
3087 The height from the center of the bottom black gridline to the
3088 top of the regular calendar entry area. The space from here to
3089 the top of the box is used only to draw the day number.
3090 /DayFont, /EntryFont, /SmallFont, /TitleFont and /HeadFont
3092 The fonts used to draw the day numbers, the calendar entries,
3093 the small calendars, the calendar title (month, year) and the
3094 day-of-the-week headings, respectively.
3095 DaySize, EntrySize, TitleSize and HeadSize
3097 The sizes of the above fonts. (The size of the small calendar
3098 font is not defined here.) For example, if you wanted to print
3099 the Hebrew date next to the regular day number in the calendar,
3100 use:
3101 REM PS Border BoxHeight Border sub DaySize sub moveto \
3103 /DayFont findfont DaySize scalefont setfont \
3104 ([hebday(today())] [hebmon(today())]) show
3105 Note how /DayFont and DaySize are used.
3107 Note that if you supply PostScript code, it is possible to produce
3109 invalid PostScript files. Always test your PostScript thoroughly with
3110 a PostScript viewer before sending it to the printer. You should not
3111 use any document structuring comments in your PostScript code.
3112
3114 If you use the -z command-line option, Remind runs in the "daemon"
3115 mode. In this mode, no "normal" reminders are issued. Instead, only
3116 timed reminders are collected and queued, and are then issued whenever
3117 they reach their trigger time.
3118 In addition, Remind wakes up every few minutes to check the modifica‐
3120 tion date on the reminder script (the filename supplied on the command
3121 line.) If Remind detects that the script has changed, it re-executes
3122 itself in daemon mode, and interprets the changed script.
3123 In daemon mode, Remind also re-reads the remind script when it detects
3125 that the system date has changed.
3126 In daemon mode, Remind acts as if the -f option had been used, so to
3128 run in the daemon mode in the background, use:
3129 remind -z .reminders &
3131 If you use sh or bash, you may have to use the "nohup" command to
3133 ensure that the daemon is not killed when you log out.
3134
3137 If you supply the -j command-line option, Remind runs in purge mode.
3138 In this mode, it tries to purge expired reminders from your reminder
3139 files.
3140 In purge mode, Remind reads your reminder file and creates a new file
3142 by appending ".purged" to the original file name. Note that Remind
3143 never edits your original file; it always creates a new .purged file.
3144 If you invoke Remind against a directory instead of a file, then a
3146 .purged file is created for each *.rem file in the directory.
3147 Normally, Remind does not create .purged files for INCLUDed files.
3149 However, if you supply a numeric argument after -j, then Remind will
3150 create .purged files for the specified level of INCLUDE. For example,
3151 if you invoke Remind with the argument -j2, then .purged files will be
3152 created for the file (or directory) specified on the command line, any
3153 files included by them, and any files included by those files. How‐
3154 ever, .purged files will not be created for third-or-higher level
3155 INCLUDE files.
3156 Determining which reminders have expired is extremely tricky. Remind
3158 does its best, but you should always compare the .purged file to the
3159 original file and hand-merge the changes back in.
3160 Remind annotates the .purged file as follows:
3162 An expired reminder is prefixed with: #!P: Expired:
3164 In situations where Remind cannot reliably determine that something was
3166 expired, you may see the following comments inserted before the prob‐
3167 lematic line:
3168 #!P: Cannot purge SATISFY-type reminders
3170 #!P: The next IF evaluated false...
3172 #!P: REM statements in IF block not checked for purging.
3173 #!P: The previous IF evaluated true.
3175 #!P: REM statements in ELSE block not checked for purging
3176 #!P: The next IFTRIG did not trigger.
3178 #!P: REM statements in IFTRIG block not checked for purging.
3179 #!P: Next line has expired, but contains expression... please verify
3181 #!P: Next line may have expired, but contains non-constant expression
3183 #!P! Could not parse next line: Some-Error-Message-Here
3185 Remind always annotates .purged files with lines beginning with "#!P".
3187 If such lines are encountered in the original file, they are not copied
3188 to the .purged file.
3189
3191 The -g option causes Remind to sort reminders by trigger date, time and
3192 priority before issuing them. Note that reminders are still calculated
3193 in the order encountered in the script. However, rather than being
3194 issued immediately, they are saved in an internal buffer. When Remind
3195 has finished processing the script, it issues the saved reminders in
3196 sorted order. The -g option can be followed by up to four characters
3197 that must all be "a" or "d". The first character specifies the sort
3198 order by trigger date (ascending or descending), the second specifies
3199 the sort order by trigger time and the third specifies the sort order
3200 by priority. If the fourth character is "d", the untimed reminders are
3201 sorted before timed reminders. The default is to sort all fields in
3202 ascending order and to sort untimed reminders after timed reminders.
3203 In ascending order, reminders are issued with the most imminent first.
3205 Descending order is the reverse. Reminders are always sorted by trig‐
3206 ger date, and reminders with the same trigger date are then sorted by
3207 trigger time. If two reminders have the same date and time, then the
3208 priority is used to break ties. Reminders with the same date, time and
3209 priority are issued in the order they were encountered.
3210 You can define a user-defined function called SORTBANNER that takes one
3212 DATE-type argument. In sort mode, the following sequence happens:
3213 If Remind notices that the next reminder to issue has a different trig‐
3215 ger date from the previous one (or if it is the first one to be
3216 issued), then SORTBANNER is called with the trigger date as its argu‐
3217 ment. The result is coerced to a string, and passed through the sub‐
3218 stitution filter with the appropriate trigger date. The result is then
3219 displayed.
3220 Here's an example - consider the following fragment:
3222 # Switch off the normal banner
3224 BANNER %
3225 REM 11 March 1993 ++1 MSG Not so important
3226 REM 17 March 1993 ++7 MSG Way in the future
3227 REM 10 March 1993 MSG Important Reminder
3228 REM 11 March 1993 ++1 MSG Not so important - B
3229 FSET sortbanner(x) iif(x == today(), \
3230 "***** THINGS TO DO TODAY *****", \
3231 "----- Things to do %b -----")
3232 Running this with the -gaa option on 10 March 1993 produces the follow‐
3234 ing output:
3235 ***** THINGS TO DO TODAY *****
3237 Important Reminder
3239 ----- Things to do tomorrow -----
3241 Not so important
3243 Not so important - B
3245 ----- Things to do in 7 days' time -----
3247 Way in the future
3249 You can use the args() built-in function to determine whether or not
3251 SORTBANNER has been defined. (This could be used, for example, to pro‐
3252 vide a default definition for SORTBANNER in a system-wide file included
3253 at the end of the user's file.) Here's an example:
3254 # Create a default sortbanner function if it hasn't already
3256 # been defined
3257 if args("sortbanner") != 1
3258 fset sortbanner(x) "--- Things to do %b ---"
3259 endif
3260
3262 You can define two functions in your script called msgprefix() and msg‐
3263 suffix(). They should each accept one argument, a number from 0 to
3264 9999.
3265 In normal mode, for MSG- and MSF-type reminders, the following sequence
3267 occurs when Remind triggers a reminder:
3268 o If msgprefix() is defined, it is evaluated with the priority of
3270 the reminder as its argument. The result is printed. It is not
3271 passed through the substitution filter.
3272 o The body of the reminder is printed.
3274 o If msgsuffix() is defined, it is evaluated with the priority of
3276 the reminder as its argument. The result is printed. It is not
3277 passed through the substitution filter.
3278 Here's an example: The following definition causes priority-0
3280 reminders to be preceded by "URGENT", and priority-6000 reminders to be
3281 preceded by "(not important)".
3282 fset msgprefix(x) iif(x==0, "URGENT: ", \
3284 x==6000, "(not important) ", "")
3285 In Calendar Mode (with the -c, -s or -p options), an analogous pair of
3287 functions named calprefix() and calsuffix() can be defined. They work
3288 with all reminders that produce an entry in the calendar (i.e., CAL-
3289 and possibly RUN-type reminders as well as MSG-type reminders.)
3290 NOTES
3292 Normally, the body of a reminder is followed by a carriage return.
3294 Thus, the results of msgsuffix() will appear on the next line. If you
3295 don't want this, end the body of the reminder with a percentage sign,
3296 "%". If you want a space between your reminders, simply include a car‐
3297 riage return (char(13)) as part of the msgsuffix() return value.
3298 If Remind has problems evaluating msgprefix(), msgsuffix() or sortban‐
3300 ner(), you will see a lot of error messages. For an example of this,
3301 define the following:
3302 fset msgprefix(x) x/0
3304
3306 Your version of Remind may have been compiled to support a language
3307 other than English. This support may or may not be complete - for
3308 example, all error and usage messages may still be in English. How‐
3309 ever, at a minimum, foreign-language versions of Remind will output
3310 names of months and weekdays in the foreign language. Also, the sub‐
3311 stitution mechanism will substitute constructs suitable for the foreign
3312 language rather than for English.
3313 A foreign-language version of Remind will accept either the English or
3315 foreign-language names of weekdays and months in a reminder script.
3316 However, for compatibility between versions of Remind, you should use
3317 only the English names in your scripts. Also, if your C compiler or
3318 run-time libraries are not "8-bit clean" or don't understand the ISO-
3319 Latin character set, month or day names with accented letters may not
3320 be recognized.
3321
3323 Remind has support for the Hebrew calendar, which is a luni-solar cal‐
3324 endar. This allows you to create reminders for Jewish holidays,
3325 jahrzeits (anniversaries of deaths) and smachot (joyous occasions.)
3326 THE HEBREW YEAR
3328 The Hebrew year has 12 months, alternately 30 and 29 days long. The
3330 months are: Tishrey, Heshvan, Kislev, Tevet, Shvat, Adar, Nisan, Iyar,
3331 Sivan, Tamuz, Av and Elul. In Biblical times, the year started in
3332 Nisan, but Rosh Hashana (Jewish New Year) is now celebrated on the 1st
3333 and 2nd of Tishrey.
3334 In a cycle of 19 years, there are 7 leap years, being years 3, 6, 8,
3336 11, 14, 17 and 19 of the cycle. In a leap year, an extra month of 30
3337 days is added before Adar. The two Adars are called Adar A and Adar B.
3338 For certain religious reasons, the year cannot start on a Sunday,
3340 Wednesday or Friday. To adjust for this, a day is taken off Kislev or
3341 added to Heshvan. Thus, a regular year can have from 353 to 355 days,
3342 and a leap year from 383 to 385.
3343 When Kislev or Heshvan is short, it is called chaser, or lacking. When
3345 it is long, it is called shalem, or full.
3346 The Jewish date changes at sunset. However, Remind will change the
3348 date at midnight, not sunset. So in the period between sunset and mid‐
3349 night, Remind will be a day earlier than the true Jewish date. This
3350 should not be much of a problem in practice.
3351 The computations for the Jewish calendar were based on the program
3353 "hdate" written by Amos Shapir of the Hebrew University of Jerusalem,
3354 Israel. He also supplied the preceding explanation of the calendar.
3355 HEBREW DATE FUNCTIONS
3357 hebday(d_date)
3359 Returns the day of the Hebrew month corresponding to the date
3360 parameter. For example, 12 April 1993 corresponds to 21 Nisan
3361 5753. Thus, hebday('1993/04/12') returns 21.
3362 hebmon(d_date)
3364 Returns the name of the Hebrew month corresponding to date. For
3365 example, hebmon('1993/04/12') returns "Nisan".
3366 hebyear(d_date)
3368 Returns the Hebrew year corresponding to date. For example,
3369 hebyear('1993/04/12') returns 5753.
3370 hebdate(i_day, s_hebmon [,id_yrstart [,i_jahr [,i_aflag]]])
3372 The hebdate() function is the most complex of the Hebrew support
3373 functions. It can take from 2 to 5 arguments. It returns a
3374 DATE corresponding to the Hebrew date.
3375 The day parameter can range from 1 to 30, and specifies the day
3377 of the Hebrew month. The hebmon parameter is a string that must
3378 name one of the Hebrew months specified above. Note that the
3379 month must be spelled out in full, and use the English translit‐
3380 eration shown previously. You can also specify "Adar A" and
3381 "Adar B." Month names are not case-sensitive.
3382 The yrstart parameter can either be a DATE or an INT. If it is
3384 a DATE, then the hebdate() scans for the first Hebrew date on or
3385 after that date. For example:
3386 hebdate(15, "Nisan", '1990/01/01')
3388 returns 1990/03/30, because that is the first occurrence of 15
3390 Nisan on or after 1 January 1990.
3391 If yrstart is an INT, it is interpreted as a Hebrew year. Thus:
3393 hebdate(22, "Kislev", 5756)
3395 returns 1995/12/15, because that date corresponds to 22 Kislev,
3397 5756. Note that none of the Hebrew date functions will work
3398 with dates outside Remind's normal range for dates.
3399 If yrstart is not supplied, it defaults to today().
3401 The jahr modifies the behaviour of hebdate() as follows:
3403 If jahr is 0 (the default), then hebdate() keeps scanning until
3405 it finds a date that exactly satisfies the other parameters.
3406 For example:
3407 hebdate(30, "Adar A", 1993/01/01)
3409 returns 1995/03/02, corresponding to 30 Adar A, 5755, because
3411 that is the next occurrence of 30 Adar A after 1 January, 1993.
3412 This behaviour is appropriate for Purim Katan, which only
3413 appears in leap years.
3414 If jahr is 1, then the date is modified as follows:
3416 o 30 Heshvan is converted to 1 Kislev in years when Heshvan
3418 is chaser
3419 o 30 Kislev is converted to 1 Tevet in years when Kislev is
3421 chaser
3422 o 30 Adar A is converted to 1 Nisan in non-leapyears
3424 o Other dates in Adar A are moved to the corresponding day
3426 in Adar in non-leapyears
3427 This behaviour is appropriate for smachot (joyous occasions) and
3429 for some jahrzeits - see "JAHRZEITS."
3430 if jahr is 2, then the date is modified as follows:
3432 o 30 Kislev and 30 Heshvan are converted to 29 Kislev and
3434 29 Heshvan, respectively, if the month is chaser
3435 o 30 Adar A is converted to 30 Shvat in non-leapyears
3437 o Other dates in Adar A are moved to the corresponding day
3439 in Adar in non-leapyears
3440 if jahr is not 0, 1, or 2, it is interpreted as a Hebrew year,
3442 and the behaviour is calculated as described in the next sec‐
3443 tion, "JAHRZEITS."
3444 The aflag parameter modifies the behaviour of the function for
3446 dates in Adar during leap years. The aflag is only used if
3447 yrstart is a DATE type.
3448 The aflag only affects date calculations if hebmon is specified
3450 as "Adar". In leap years, the following algorithm is followed:
3451 o If aflag is 0, then the date is triggered in Adar B.
3453 This is the default.
3454 o If aflag is 1, then the date is triggered in Adar A.
3456 This may be appropriate for jahrzeits in the Ashkenazi
3457 tradition; consult a rabbi.
3458 o If aflag is 2, then the date is triggered in both Adar A
3460 and Adar B of a leap year. Some Ashkenazim perform
3461 jahrzeit in both Adar A and Adar B.
3462 JAHRZEITS
3464 A jahrzeit is a yearly commemoration of someone's death. It normally
3466 takes place on the anniversary of the death, but may be delayed if
3467 burial is delayed - consult a rabbi for more information.
3468 In addition, because some months change length, it is not obvious which
3470 day the anniversary of a death is. The following rules are used:
3471 o If the death occurred on 30 Heshvan, and Heshvan in the year
3473 after the death is chaser, then the jahrzeit is observed on 29
3474 Heshvan in years when Heshvan is chaser. Otherwise, the
3475 yahrzeit is observed on 1 Kislev when Heshvan is chaser.
3476 o If the death occurred on 30 Kislev, and Kislev in the year after
3478 the death is chaser, then the jahrzeit is observed on 29 Kislev
3479 in years when Kislev is chaser. Otherwise, the yahrzeit is
3480 observed on 1 Tevet when Kislev is chaser.
3481 o If the death occurred on 1-29 Adar A, it is observed on 1-29
3483 Adar in non-leapyears.
3484 o If the death occurred on 30 Adar A, it is observed on 30 Shvat
3486 in a non-leapyear.
3487 Specifying a Hebrew year for the jahr parameter causes the correct be‐
3489 haviour to be selected for a death in that year. You may also have to
3490 specify aflag, depending on your tradition.
3491 The jahrzeit information was supplied by Frank Yellin, who quoted "The
3493 Comprehensive Hebrew Calendar" by Arthur Spier, and "Calendrical Calcu‐
3494 lations" by E. M. Reingold and Nachum Dershowitz.
3495
3497 The SPECIAL keyword is used to transmit "out-of-band" information to
3498 Remind backends, such as tkremind or Rem2PS. They are used only when
3499 piping data from a remind -p line. (Note that the COLOR special is an
3500 exception; it downgrades to the equivalent of MSG in remind's normal
3501 mode of operation.)
3502 The various SPECIALs recognized are particular for each backend; how‐
3504 ever, there are three SPECIALs that all backends should attempt to sup‐
3505 port. They are currently supported by Rem2PS, tkremind and rem2html.
3506 The SHADE special replaces the psshade() function. Use it like this:
3508 REM Sat Sun SPECIAL SHADE 128
3509 REM Mon SPECIAL SHADE 255 0 0
3510 The SHADE keyword is followed by either one or three numbers, from 0 to
3511 255. If one number is supplied, it is interpreted as a grey-scale
3512 value from black (0) to white (255). If three numbers are supplied,
3513 they are interpreted as RGB components from minimum (0) to maximum
3514 (255). The example above shades weekends a fairly dark grey and makes
3515 Mondays a fully-saturated red. (These shadings appear in calendars
3516 produced by Rem2PS, tkremind and rem2html.)
3517 The MOON special replaces the psmoon() function. Use it like this:
3519 REM [moondate(0)] SPECIAL MOON 0
3520 REM [moondate(1)] SPECIAL MOON 1
3521 REM [moondate(2)] SPECIAL MOON 2
3522 REM [moondate(3)] SPECIAL MOON 3
3523 These draw little moons on the various calendars. The complete syntax
3524 of the MOON special is as follows:
3525 ... SPECIAL MOON phase moonsize fontsize msg
3526 Phase is a number from 0 to 3, with 0 representing a new moon, 1 the
3528 first quarter, 2 a full moon and 3 the last quarter.
3529 moonsize is the diameter in PostScript units of the moon to draw. If
3531 omitted or supplied as -1, the backend chooses an appropriate size.
3532 fontsize is the font size in PostScript units of the msg
3534 Msg is additional text that is placed near the moon glyph.
3536 Note that only the Rem2PS backend supports moonsize and fontsize; the
3538 other backends use fixed sizes.
3539 The COLOR special lets you place colored reminders in the calendar.
3541 Use it like this:
3542 REM ... SPECIAL COLOR 255 0 0 This is a bright red reminder
3544 REM ... SPECIAL COLOR 0 128 0 This is a dark green reminder
3545 You can spell COLOR either the American way ("COLOR") or the British
3547 way ("COLOUR"). This manual will use the American way.
3548 Immediately following COLOR should be three decimal numbers ranging
3550 from 0 to 255 specifying red, green and blue intensities, respectively.
3551 The rest of the line is the text to put in the calendar.
3552 The COLOR special is "doubly special", because in its normal operating
3554 mode, remind treats a COLOR special just like a MSG-type reminder.
3555 Also, if you invoke Remind with -cc..., then it approximates SPECIAL
3556 COLOR reminders on your terminal.
3557 The WEEK special lets you place annotations such as the week number in
3559 the calendar. For example, this would number each Monday with the ISO
3560 8601 week number. The week number is shown like this: "(Wn)" in this
3561 example, but you can put whatever text you like after the WEEK keyword.
3562 REM Monday SPECIAL WEEK (W[weekno()])
3564
3567 COMMAND ABBREVIATIONS
3568 The following tokens can be abbreviated:
3570 o REM can be omitted - it is implied if no other valid command is
3572 present.
3573 o CLEAR-OMIT-CONTEXT --> CLEAR
3575 o PUSH-OMIT-CONTEXT --> PUSH
3577 o POP-OMIT-CONTEXT --> POP
3579 o DUMPVARS --> DUMP
3581 o BANNER --> BAN
3583 o INCLUDE --> INC
3585 o SCANFROM --> SCAN
3587 NIFTY EXAMPLES
3589 This section is a sampling of what you can do with Remind.
3591 REM 5 Feb 1991 AT 14:00 +45 *30 \
3593 RUN mail -s "Meeting at %2" $LOGNAME </dev/null &
3594 On 5 February, 1991, this reminder will mail you reminders of a 2:00pm
3596 meeting at 1:15, 1:45 and 2:00. The subject of the mail message will
3597 be "Meeting at 2:00pm" and the body of the message will be blank.
3598 REM AT 17:00 RUN echo "5:00pm - GO HOME!" | xless -g +0+0 &
3600 This reminder will pop up an xless window at 5:00pm every day. The
3602 xless window will contain the line "5:00pm - GO HOME!"
3603 REM AT 23:59 RUN (sleep 120; remind -a [filename()]) &
3605 This reminder will run at one minute to midnight. It will cause a new
3607 Remind process to start at one minute past midnight. This allows you
3608 to have a continuous reminder service so you can work through the night
3609 and still get timed reminders for early in the morning. Note that this
3610 trick is no longer necessary, providing you run Remind in daemon mode.
3611 remind -c12 /dev/null Jan 1993
3613 This invocation of Remind will cause it to print a calendar for 1993,
3615 with all entries left blank.
3616 REM CAL [trigdate()-date(year(trigdate()), 1, 1)+1]
3618 This example puts an entry in each box of a calendar showing the number
3620 (1-365 or 366) of the day of the year.
3621 REM Tue 2 Nov SATISFY (year(trigdate())%4) == 0
3623 IF trigvalid()
3624 REM [trigdate()] ++5 MSG \
3625 U.S. Presidential Election!!
3626 ENDIF
3627 This example warns you 5 days ahead of each American presidential elec‐
3629 tion. The first REM command calculates the first Tuesday after the
3630 first Monday in November. (This is equivalent to the first Tuesday on
3631 or after 2 November.) The SATISFY clause ensures that the trigger date
3632 is issued only in election years, which are multiples of 4. The second
3633 REM command actually issues the reminder.
3634 DETAILS ABOUT TRIGGER COMPUTATION
3636 Here is a conceptual description of how triggers are calculated. Note
3638 that Remind actually uses a much more efficient procedure, but the
3639 results are the same as if the conceptual procedure had been followed.
3640 Remind starts from the current date (that is, the value of today()) and
3642 scans forward, examining each day one at a time until it finds a date
3643 that satisfies the trigger, or can prove that no such dates (on or
3644 later than today()) exist.
3645 If Remind is executing a SATISFY-type reminder, it evaluates the
3647 expression with trigdate() set to the date found above. If the expres‐
3648 sion evaluates to zero or the null string, Remind continues the scan‐
3649 ning procedure described above, starting with the day after the trigger
3650 found above.
3651 The SCANFROM clause (having a syntax similar to UNTIL) can modify the
3653 search strategy used. In this case, Remind begins the scanning proce‐
3654 dure at scan_date, which is the date specified in the SCANFROM clause.
3655 For example:
3656 REM Mon 1 SCANFROM 17 Jan 1992 MSG Foo
3658 The example above will always have a trigger date of Monday, 3 February
3660 1992. That is because Remind starts scanning from 17 January 1992, and
3661 stops scanning as soon as it hits a date that satisfies "Mon 1."
3662 The main use of SCANFROM is in situations where you want to calculate
3664 the positions of floating holidays. Consider the Labour Day example
3665 shown much earlier. Labour Day is the first Monday in September. It
3666 can move over a range of 7 days. Consider the following sequence:
3667 REM Mon 1 Sept SCANFROM [today()-7] SATISFY 1
3669 OMIT [trigdate()]
3670 REM Mon AFTER MSG Hello
3672 The SCANFROM clause makes sure that Remind begins scanning from 7 days
3674 before the current date. This ensures that Labour Day for the current
3675 year will continue to be triggered until 7 days after it has occurred.
3676 This allows you to safely use the AFTER keyword as shown.
3677 In general, use SCANFROM as shown for safe movable OMITs. The amount
3679 you should scan back by (7 days in the example above) depends on the
3680 number of possible consecutive OMITted days that may occur, and on the
3681 range of the movable holiday. Generally, a value of 7 is safe.
3682 The FROM clause operates almost like the counterpoint to UNTIL. It
3684 prevents the reminder from triggering before the FROM date. For exam‐
3685 ple, the following reminder:
3686 REM Mon Thu FROM 23 Jul 2007 UNTIL 2 Aug 2007 MSG Test
3688 will trigger on Mondays and Thursdays between 23 July 2007 and 2 August
3690 2007 inclusive.
3691 FROM is really just syntactic sugar; you could implement the reminder
3693 above as follows:
3694 REM Mon Thu SCANFROM [max(today(), '2007-07-23')] \
3696 UNTIL 2 Aug 2007 MSG Test
3697 but that's a lot harder to read. Internally, Remind treats FROM
3699 exactly as illustrated using SCANFROM. For that reason, you cannot use
3700 both FROM and SCANFROM.
3701 Note that if you use one REM command to calculate a trigger date, per‐
3703 form date calculations (addition or subtraction, for example) and then
3704 use the modified date in a subsequent REM command, the results may not
3705 be what you intended. This is because you have circumvented the normal
3706 scanning mechanism. You should try to write REM commands that compute
3707 trigger dates that can be used unmodified in subsequent REM commands.
3708 The file "defs.rem" that comes with the Remind distribution contains
3709 examples.
3710 DETAILS ABOUT TRIGVALID()
3712 The trigvalid() function returns 1 if Remind could find a trigger date
3714 for the previous REM or IFTRIG command. More specifically, it returns
3715 1 if Remind finds a date not before the starting date of the scanning
3716 that satisfies the trigger. In addition, there is one special case in
3717 which trigvalid() returns 1 and trigdate() returns a meaningful result:
3718 If the REM or IFTRIG command did not contain an UNTIL clause, and con‐
3720 tained all of the day, month and year components, then Remind will cor‐
3721 rectly compute a trigger date, even if it happens to be before the
3722 start of scanning. Note that this behaviour is not true for versions
3723 of Remind prior to 03.00.01.
3724
3726 Remind is now supported by Roaring Penguin Software Inc.
3727 (http://www.roaringpenguin.com)
3728 Dianne Skoll <dfs@roaringpenguin.com> wrote Remind. The moon code was
3730 copied largely unmodified from "moontool" by John Walker. The sunrise
3731 and sunset functions use ideas from programs by Michael Schwartz and
3732 Marc T. Kaufman. The Hebrew calendar support was taken from "hdate" by
3733 Amos Shapir. OS/2 support was done by Darrel Hankerson, Russ Herman,
3734 and Norman Walsh. The supported foreign languages and their transla‐
3735 tors are listed below. Languages marked "complete" support error mes‐
3736 sages and usage instructions in that language; all others only support
3737 the substitution filter mechanism and month/day names.
3738 German -- Wolfgang Thronicke
3740 Dutch -- Willem Kasdorp and Erik-Jan Vens
3742 Finnish -- Mikko Silvonen (complete)
3744 French -- Laurent Duperval (complete)
3746 Norwegian -- Trygve Randen
3748 Danish -- Mogens Lynnerup
3750 Polish -- Jerzy Sobczyk (complete)
3752 Brazilian Portuguese -- Marco Paganini (complete)
3754 Italian -- Valerio Aimale
3756 Romanian -- Liviu Daia
3758 Spanish -- Rafa Couto
3760 Icelandic -- Björn Davíðsson
3762
3764 There's no good reason why read-only system variables are not imple‐
3765 mented as functions, or why functions like version(), etc. are not
3766 implemented as read-only system variables.
3767 Hebrew dates in Remind change at midnight instead of sunset.
3769 Language should be selectable at run-time, not compile-time. Don't
3771 expect this to happen soon!
3772 Remind has some built-in limits (for example, number of global OMITs.)
3774
3776 Nachum Dershowitz and Edward M. Reingold, "Calendrical Calculations",
3777 Software-Practice and Experience, Vol. 20(9), Sept. 1990, pp 899-928.
3778 L. E. Doggett, Almanac for computers for the year 1978, Nautical
3780 Almanac Office, USNO.
3781 Richard Siegel and Michael and Sharon Strassfeld, The First Jewish Cat‐
3783 alog, Jewish Publication Society of America.
3784
3786 rem, rem2ps, tkremind
37874th Berkeley Distribution 31 August 2008 REMIND(1)