NAME

events; da.events.muf - calendar of events

SYNOPSIS

Command Line:
Properties:
_events/personal
String, set on trigger; equal to "yes" if this event list does not need write access control.
_events/readaccess
String, set on trigger; a space-separated list of player names who have read access to this list.
_events/calendar
String, set on trigger; Equal to "yes" if this event list is in "calendar" mode, that is, events are shown in the author's time zone rather than the player running the program.
_events/quiet/list
String, set on player; equal to "yes" if this event list should not announce its events to this player.
_events/format/list
String, set on player; a strftime format to use to display event times in the -all and -next n listings.
events/EVENT/by
Dbref, set on trigger; the author of the event and the object which all times are relative to.
events/registry
String, set on trigger; space-separated list of events in chronological order.
events/EVENT/title
String, set on trigger; the title of the event.
events/EVENT/next
Integer, set on trigger; systime (local to author) of next occurrence of this event.
events/EVENT/nextutc
Integer, set on trigger; systime (in UTC) of next occurrence of this event.
events/EVENT/repeat
Integer, set on trigger; zero if event repeats, -1 if parsetime rule should be used, or a positive integer to indicate period in days.
events/EVENT/rule
String, set on trigger; parsetime rule to use for repeat.
events/EVENT/desc/
multi-line editor data, set on trigger; the long description of the event.
events/EVENT/access
String, set on trigger; space-separated list of names which can alter this event's details.
events/EVENT/notify
integer, set on trigger; 1 if event should announce itself when event is created and when event elapses, 0 otherwise.

DESCRIPTION

da.events.muf is a calendar program which keeps track of events, notifies you when they elapse and reschedules them if they are repeating events. A global action, events is linked to this program, and this documentation will assume that you are using the events global, though you may of course use the same commands for any event list.

Event definition

An event is an instant in time on a particular day. Events may occur once or they may recur regularly. An event has the following properties:

Listing events

To get a complete listing of all events on the list, type:
events -all
This listing shows, from left to right, the event name, the time it occurs, the event's repeat status, its title, and (if the list is not personal) the event author, i.e., the player to contact about this event.

The single-character repeat status is blank if the event does not repeat, a single integer specifying days between repetitions for regularly repeating events, or an asterisk for repeats given in terms of a parsetime rule.

If the contact player ends with "...", you will need to display an event in its entirety to see the full list of contacts.

Since this list may be very long and you may not care about events far into the future, you can limit the listing to the events within the next n days with the command:

events -next n
To display detailed information about an event, including its repeat status, complete list of contacts and description, type
events EVENT
where EVENT is the event name you want details on.

Adding an event

To add a new event to an event list, simply type:
events -new
and answer the long list of questions. Each of the groups of questions is given its own section below. To abort at any time, type a single dot (".").
Name
All events have a name, which is made from one to six capital letters or numbers. If you try to add an event which already exists you will be made to type in a different name.
Title
The title can be any text. If you try to type in a string over 35 characters long you will be asked to type in a new string. This prevents half the title from not being visible on an event listing.
Scheduling the event
To schedule an event you will need to pick an exact time for it to occur. This time must be given to events in a format acceptable to parsetime. You can type "?" to get a long description of the format of a parsetime string. Note that parsetime will not allow you to give a date without an accompanying time of day. Just pick some arbitrary time during the day.

If the event does not repeat, answer "n" to the next question, otherwise type "y". If you answered yes, you will be asked to say when the event repeats. If the event repeats at the same time every day, or the same time every n days, simply type that number (e.g., "7" for a weekly event).

If your event does not repeat with precisely the same period (for instance, it is a monthly or annual event, or it repeats every 29 days, 6 hours and 12 minutes), you can enter a parsetime string, which will be interpreted just after the event elapses, and whatever time parsetime evaluates the string to be will be the next time the event occurs. Thus for an event that happens on the first of every month, the repeat rule could be "midnight 1st"; for an annual event every May Day, "midnight 1st May"; for an event that happens every lunar synodic period, "now +29d +6h +12m".

Description
To edit the description of an event, you are placed in the multi-line editor. Type as many lines as you wish. To end the editor, type ".s" on a line by itelf.
Miscellany
Finally, you are asked some miscellaneous questions about this event. If the event list is not personal, you are prompted to list players apart from yourself who are allowed to edit or delete this event. You are always included, and if you don't want to give anyone else access, type a single space. Otherwise, type each player's name, separated by spaces. On personal event lists, write access is made the same as the list's global read access list, so that anyone who can see the event may modify it.

Then you are asked if the event should announce itself. If you answer "y" then the event will notify all connected players on the read access list about itself when it is added, and will also notify all connected players on the read access list when the event elapses.

Removing an event

To delete an event EVENT, type
events -del EVENT
You are not asked to confirm the deletion and you cannot undelete an event, although it may be possible to recall some of the data from the event. Contact the author of events if this happens.

All players with write access to an event may delete it.

Modifying an event

To modify an event, you use one of the following commands:
events -rename EVENT
To change an event's title.
events -resched EVENT
To change an event's next occurrence time as well as its repeat status.
events -redesc EVENT
To change an event's multi-line description
events -remisc EVENT
To change an event's write access and notification status.
Each of these options coincides with the sections in Adding an event above.

Some notes about modifying an event you don't own
When you reschedule an event owned by someone else with -resched, you are first asked if you want to claim ownership of the event. If you answer yes, you are now the owner of the event and all times you subsequently type will be in your time zone using your language locale. If the event repeats using a parsetime rule, it will almost certainly be wrong unless you are absolutely sure that the original author has the same time zone and language locale that you have. You will be warned if this is not the case. If you answer no, the event remains owned by the original author and you will need to type the time of the next occurrence using that player's time zone (but your language locale). However, because you are not relevant when the event elapses, if the event repeats according to a parsetime rule, it must be typed in terms of the author's time zone, using the author's language locale. This probably won't matter unless the author has changed its language locale information (see timelib for much more). It is probably best to claim ownership of an event in this case, or have the original author do all rescheduling.

When you enter a new write access list for an event with -remisc, it is your name, not the author's name, which you leave off.

Event notification

Events are checked for elapsing every time an event command for that list is run. There is a do-nothing command, events -update which simply checks for elapsed events and announces them if necessary. You can use this command to force an event to be announced if it has elapsed but not yet been announced because no one has run events since then.

events can, in conjunction with the -trigger #dbrefoption, list or notify you of elapsed events upon connection by placing an appropriate string in your _connect property. Commands to automate this will be included in a future version of events.

To prevent spamming players with unwelcome event notifications from badly set-up event lists, if the read access of an event list is unset (i.e., anyone may access the event list), events will only be announced if the trigger action is a global, that is, it is located in room #0.

Any player may choose not to see elapsing event notifications with the -quiet option.

Event list global settings

All events and global settings for an event list are stored on the trigger action. The owner of the event is the owner of the trigger action. Only the owner of an event list can change a list's global settings.
Read access
Since event lists can be created to work as private calendars, you may want to keep others from accessing your event list. To this end, each event list has a single read access list, of names of players who are allowed to use the list. Players with read access may list all events on the event list, add new events, and modify other players' events (if they have been given write access to them). Players without read access may not use the list in any way. By default all players have read access to a list. To change this, type:
events -access
and follow the instructions. Note that you, as the event list owner, are always included in this list. To forbid everyone else from using your event list, type a single space. Otherwise, type the names of other users who are allowed to use the list, separated by spaces.
Personal lists
If your event list is to be used solely by you or a small group of people with mutual trust, you can make the list "personal", that is, so that players do not need to specify write access each time an event is added. To make a list personal, type:
events -personal
From now on, events are displayed without the "Contact" field, and the write access list for all new events will be made equal to the global read access list. Note that existing events' write access lists are unchanged. Making a list personal is purely for convenience and does not provide any extra functionality.
Calendar mode
For some event lists it is better to know what time the author of the event means the event to be at rather than the time it is for you. An event list for which this may be true is a birthday list. To set a list so that dates are printed in the author's time zone, type:
events -calendar
You can still see the local time an event occurs by viewing the detailed event information with
events EVENT
Note that with this option set times may appear out of order on listings. If your time format contains the string "%Z" then you will see the author's time zone on each line.

Event list personal settings

Every player with read access to an event list can do a few things to change the list's behaviour. These settings are stored on the player and are bound to the event list's primary name (i.e., if you change the name of the event list the settings will not be retained).
Event notification
If you do not wish to be notified of any events as they are scheduled or elapse, type:
events -quiet
This will silence messages about elapsing events without affecting anyone else.
Time format
You can change the format that times are displayed in the events -all or events -next n listings. You may want to do this if you prefer 24-hour time, or if you don't want the time to be displayed at all (on a celandar that is purely for listing day-long events like birthdays), or whatever reason. da.events.muf uses timelib for its time display functions, so your format should be as per the strftime format. Because of strict width restrictions, you are limited to a format which produces strings 19 or fewer characters long. This should be long enough for most formats. It is also because of these restrictions that events cannot use your locale date and time formats, as set by date -format. To set your format, type
events -format
and follow the instructions.

DIAGNOTSICS

events PANIC: Illegal parsetime format on event EVENT
A repeating event could not reschedule itself because its parsetime rule was not valid. The only real way this can happen is that a player altered its language locale after scheduling a repeating event. The event was not deleted but it has been removed from the schedule. To reschedule it, type events -reschedule EVENT. to delete it, type events -del EVENT.
events PANIC: EVENT reschedules in the past.
A repeating event elapsed and attempted to reschedule itself at the same or an earlier time. The event was not deleted but it has been removed from the schedule. To reschedule it, type events -reschedule EVENT. to delete it, type events -del EVENT.

BUGS

If you schedule an event, then change your daylight savings rule (with date -zone, for instance), the event will not be scheduled properly until it elapses and reschedules itself (for a repeating event) or you use events -resched EVENT and press "." to retain all current values. This is because events stores times internally in UTC for efficiency, which will no longer be correct if you change your DST rule. Yet another reason not to use the "on" and "off" DST rules. I'm beginning to think maybe I should remove them . . .

It's entirely possible for an author to grant write access for an event to a player and for that player to revoke write access to the author. This may be considered a feature.

AUTHOR

Deborah Pickett (<Ariel> on FDCMuck).