reminder

(E-mail reminders of possibly periodic events)

SYNOPSIS

reminder [-hv]

reminder ( create | new )

reminder ( active | mail | next | tags )

reminder [-t tag] list

reminder show number

reminder ( canonicalize | delete | did | edit ) number

REQUIREMENTS

Perl 5.6 or later and the Date::Manip module are required. The latter can be obtained from CPAN.

reminder is a variation on the old Unix calendar(1) program, allowing a user to maintain a list of reminders for specific dates and displaying currently applicable reminders in a few different ways. It allows periodic reminders, continues to remind about something daily until the user indicates that reminder is "done," and supports an extremely flexible date specification syntax.

The action to take is specified by the first word on the command line, which must be one of the following:

active

Lists all active reminders (reminders whose date has passed and which have not been acknowledged with did). Displays the reminder number, the title, the date of the current reminder, and the date when it will next recur (if any). Reminders are sorted by their date.

canonicalize number

Perform the same operations on reminder number as would be done after the reminder was created (mainly rewriting the Start time into ISO format). This is normally not needed, and is primiarly useful only after editing the reminder files by hand.

create

new

Create a new reminder. The new reminder will start with an empty body and empty Title, Start, and Repeat fields that the user can fill in. See FORMAT for the complete specification of the format of a reminder. After the user finishes editing the reminder, reminder will attempt to parse the dates. If that fails, the user will be prompted as to whether they want to edit the reminder again. Otherwise, they will be shown the dates as reminder understood them and be asked if that's correct.

If there are any errors, the user is asked if they want to abort (delete the new reminder as if they never tried to create it), edit it again, or quit (leave the reminder there, even if it is invalid).

delete number

Delete the reminder number completely, even if it is recurring.

did number

Mark the reminder number as acknowledged. If the reminder is not repeating, this will do the same thing as delete. If the reminder is repeating, the last acknowledged date will be updated in the Last field, thus "resetting" the repeating reminder so that it won't recur until the Repeat interval has again passed.

edit number

Edit the reminder number. After editing it, the same checks will be applied as after create.

list

Lists all reminders. Displays the reminder number, the title, the next time the reminder will trigger, and the date after that when it will recur (if any). Reminders that don't have a title or date (such as reminders that someone is in the process of creating) will be skipped. Reminders are sorted by their date.

If a tag is specified with -t, the listed reminders are restricted to those with that tag.

mail

Mails all active reminders to the user specified in the (normally hidden) User field of the reminder. Normally one would run reminder with this option each morning from cron. This mail message comes from the user the reminder program is running as, and will have the User-Agent field set to reminder/version, where version is the version of reminder (for easy e-mail sorting).

next

Like active but lists all active reminders and all reminders that will become active in the next day. Displays the reminder number, the title, the date of the current reminder, and the date when it will next recur (if any). Reminders are sorted by their date.

show number

Display the reminder number. Only the Title, Start, Last, and Repeat header fields, if present, will be shown.

tags

List all of the tags used by any reminder.

OPTIONS

-h, --help: Print out this documentation (which is done simply by feeding the script to perldoc -t.
-t tag, --tag=tag: Restricts application of the command to reminders with a particular tag. Currently, this only works in conjunction with the list command.
-v, --version: Print out the version of reminder and exit.

FORMAT

A reminder is stored on disk in a format very similar to an e-mail message, with a series of headers starting with a keyword, a colon, a space, and a value, followed by a blank line and then the body of the reminder. Unlike with an e-mail message, header lines may not be continued and are always a single line. The body is completely free-form and may be omitted.

The following header fields are allowed:

Title

The title of the reminder, displayed in the list and active views and used as the heading for the reminder in the message sent by mail. This field is required.

Start

The starting date of the reminder. If this is a one-time reminder (there is no Repeat field), this will be the date that the reminder becomes active, and the reminder will be deleted when acknowledged. If this is a repeating reminder, this is the first date that it will become active, and the reminder will then become active again every Repeat interval after Start.

This date can be in just about any format that one wishes. For a complete list of formats, see Date::Manip.

Repeat

How often the reminder repeats. This must specify an interval like 4 days or 1 year or 7 months. For a complete list of valid formats, see Date::Manip. If this field is present, the reminder will become active again every multiple of Repeat after Start. When a reminder becomes active again does not depend on when it was last acknowledged.

Last

Added by the did command and not generally specified by the user, this gives the date of the last time this reminder became active and was acknowledged. It is some multiple of Repeat after Start, not the date that the did command was issued. It is used as the basis for determining when the reminder will become active again.

Tags

A space-separated list of tags applicable to that reminder. This can be used to restrict the reminders shown by the list command.

User

Added automatically by create, this specifies the user to which the reminder applies and is used to determine where to send mail with the mail command. It is not really used at the moment beyond that, but is present for future work on multi-user reminder setups.

ENVIRONMENT

EDITOR: The editor invoked by the create and edit functions. If EDITOR is not set in the environemnt, reminder defaults to vi.

FILES

$HOME/data/reminders: Where the reminders are stored. Each reminder will be a separate file in this directory whose file name is the number of that reminder. The reminder files can be edited by hand if desired, although it's better to use the edit function so that the reminder will be sanity-checked and canonicalized after being edited.

AUTHOR

Russ Allbery <rra@stanford.edu>

COPYRIGHT AND LICENSE

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.