% DO NOT EDIT THIS FILE
% (LaTeX input generated by "glatex")
\def\grind{\list{}{\listparindent 1.5em
\itemindent\listparindent
\rightmargin\leftmargin \parsep -5pt plus 1pt}\item[]}
\let\endgrind=\endlist
\documentstyle[twocolumn,times,11pt]{article}

% Make ground code smaller
\let\oldgrind=\grind
\def\grind{\oldgrind\small}

% Special words
\def\w#1{{\em #1\/}}

\def\xcal{\w{cal}}

\def\xview{\w{view}}
\def\xitem{\w{item}}
\def\xdate{\w{date}}
\def\xfile{\w{file}}
\def\xbody{\w{body}}

\def\spec#1{\item {\bf #1}\\[3pt]}

\textwidth 7in
\oddsidemargin -0.25in
\evensidemargin -0.25in
\topmargin -0.25in
\textheight 9.25in
\headheight 0in
\headsep 0in
\flushbottom

\def\incomplete{\par\noindent{\em This section is incomplete!}}

\title{The Tcl Interface to Ical}
\author{Sanjay Ghemawat}
\date{\today}

\begin{document}

\maketitle

\tableofcontents

\section{Introduction}

This document contains a brief description of the Tcl interface to
ical.  Part of this interface is implemented in C++ and the rest is
implemented by Tcl support libraries.

The C++ code exports calendar and item objects to tcl code.  A number
of operations are provided to create such objects and to manipulate
dates and times.  In addition, the calendar and item objects have
various methods that can be called from tcl code.

\section{Computation Model}

Calendars and items are stored persistently on file systems.  Copies
of these calendars and items are read into ical's address space.  The
Tcl code operates on these copies through well-defined interfaces.
These interfaces contain special operations for saving pending
modifications to persistent storage on the file system.

Each user has a main calendar.  This main calendar is represented as a
calendar object in Tcl code, and persistently as a file stored on the
file system.  The main calendar contains a list of names of included
calendar files.  The main calendar file and the included calendar
files all contain items.  Each item in the main calendar file and the
included calendar files is visible as an item object to the Tcl code.

\section{Calendars}
\label{sec:calendars}

The following calendar operations raise errors if the user does not
have sufficient permission to perform the required operation.  Errors
are also raised if specified files do not contain a calendar.  Some of
these operations also take a calendar file name as an optional
argument.  If the file name is omitted, then the main calendar file is
used.

Arguments named \w{file} in the following list are names of Unix
files.  Arguments named \w{cal} are calendar objects created by the
``calendar'' command.

\subsection{Files and Includes}

This section lists the operations for creating and deleting calendar
objects from calendar files, and also operations for handling included
calendars.

\begin{itemize}

\spec{calendar \w{cal} \w{file}}
  Create a calendar object named \w{cal} with \w{file} as the main
  calendar file.  The actual file named \w{file} contains a list of
  included calendar files.  The files mentioned in this list are also
  incorporated into \w{cal}.  Typically only one calendar object is created
  in an ical application.  Included calendars are considered part of
  this one calendar object.

\spec{\w{cal} delete}
  Discard \w{cal} and all contained items from process memory.  The
  underlying files are not destroyed and can be used to initialize a
  calendar object in another invocation.

\spec{\w{cal} main}
  Return the name of the main calendar file for \w{cal}.

\spec{\w{cal} include \w{file}}
  Include \w{file} into \w{cal}.  All items contained in \w{file} are made
  available as item objects to Tcl code.

\spec{\w{cal} exclude \w{file}}
  Exclude \w{file} from \w{cal}.  All objects for items contained
  in \w{file} are removed from the Tcl interpreter and cannot be used
  by Tcl code any more.

\spec{\w{cal} forincludes \w{var} \w{body}}
  For each include \w{file} in \w{cal}, set \w{var} to \w{file} and
  execute \w{body}.

\end{itemize}

\subsection{Adding and Removing Items}

This section describes the operations for adding and removing items
from calendars.

\begin{itemize}

\spec{\w{cal} add \w{item} [\w{file}]}
  Add \w{item} to the specified \w{file} in \w{cal}.

\spec{\w{cal} remove \w{item}}
  Remove \w{item} from \w{cal}.

\spec{\w{cal} hide \w{item}}
  Hide \w{item} from this user.  Other users will still see the item.

\end{itemize}

\subsection{Input and Output}

This section describes the operations for reading and writing
calendars to persistent storage.

\begin{itemize}

\spec{\w{cal} readonly [\w{file}]}
  Returns true iff the user does not have permission to modify the
  specified \w{file}.

\spec{\w{cal} dirty [\w{file}]}
  Has the specified \w{file} been modified locally without being saved
  to persistent storage?

\spec{\w{cal} stale [\w{file}]}
  Has the specified \w{file} been modified by another user or process?

\spec{\w{cal} save [\w{file}]}
  Save any local changes made to \w{file} to persistent storage.
  For example, the following code saves all modifications~---
\begin{verbatim}
if [cal dirty [cal main]] {
    cal save [cal main]
}

cal forincludes file {
    if [cal dirty $file] {
        cal save $file
    }
}
\end{verbatim}

\spec{\w{cal} reread [\w{file}]}
  Incorporate any changes made to \w{file} by other users or
  processes.  Any existing items objects from \w{file} may be deleted
  and replaced by new item objects even if the file has not been
  modified recently.

\end{itemize}

\subsection{User Preferences}

Each calendar file contains a general mapping from option names to
string values.  This mapping is typically used to store user preferences
for ical.  Sometimes, however this mapping contains miscellaneous
properties of the calendar file.

\begin{itemize}

\spec{\w{cal} option [-calendar \w{file}] \w{name}}
  Look up the value associated with \w{name} in the named calendar \w{file}.
  If no calendar file is specified, the value is looked up in the main
  calendar file.  An error is raised if the named option does not
  exist in the calendar.
  Example~---
\begin{verbatim}
set p "lpr"
catch {set p [cal option PrintCmd]}
\end{verbatim}

\spec{\w{cal} option [-calendar \w{file}] \w{name} \w{value}}
  Set the value of the option named \w{name} to \w{value} in the named
  calendar \w{file}.  If no calendar file is specified, the value is
  looked up in the main calendar file.
  Example~---
\begin{verbatim}
cal option PrintCmd "lpr -m"
\end{verbatim}

\spec{\w{cal} delete_option [-calendar \w{file}] \w{name}}
  Remove option named \w{name} from the named calendar \w{file}.
  If no calendar file is specified, the main calendar file is used.
  An error is raised if the named option does not
  exist in the calendar.
\end{itemize}

\subsection{Queries}

The following operations can be used to get listings of various items
in a calendar.  The range of most of these queries can be controlled
by specifying one of the following options:

\begin{itemize}
\spec{-all}
  Query ranges over all calendars and items.
\spec{-calendar \w{file}}
  Query ranges over the contents of the specified calendar file.
\spec{-list \w{item-list}}
  Query ranges over only the specified list of items.
\end{itemize}

\noindent The actual query methods are as follows:

\begin{itemize}

\spec{\w{cal} query [\w{range options}] \w{start} \w{finish}\\
                \hspace*{4em} \w{itemvar} \w{datevar} \w{body}}
  For any item occurrence in the range \w{start..finish}, set
  \w{itemvar} to the item, set \w{datevar} to the date of the item
  occurrence, and then evaluate \w{body}.  The executions of \w{body}
  are sorted by occurrence.

\spec{\w{cal} listing [\w{range options}] \w{start} \w{finish}\\
                \hspace*{4em} \w{itemvar} \w{datevar} \w{body}}
  For all items \w{i}, For each occurrence of \w{i} in
  \w{start}..(\w{finish}+[\w{i} earlywarning]), Set \w{itemvar} to
  \w{i}, \w{datevar} to the occurrence date and execute \w{body}.
  The executions of \w{body} are sorted by occurrence.
  This operation differs from ``\w{cal} query'' only in its handling of
  early warnings.
  Example~---
\begin{verbatim}
cal listing $date [expr $date+9] i d {
    print_date $d
    print_item $i
}
\end{verbatim}

\spec{\w{cal} incalendar \w{file} \w{itemvar} \w{body}}
  For all items \w{i} in \w{file}, Set \w{itemvar} to \w{i} and execute
  \w{body}.  The executions of \w{body} are sorted by date of first
  occurrence.  This operation is equivalent to the ``query'' operation
  executed with a ``-calendar'' range option.
  Example~---
\begin{verbatim}
cal incalendar [cal main] item {
    print_item $item
}
\end{verbatim}

\spec{\w{cal} loop\_forward [\w{range options}] \w{item} \w{date}\\
                \hspace*{4em} \w{itemvar} \w{datevar} \w{body}}
  For each item occurence that occurs after the specified \w{item} on the
  specified \w{date}, set \w{itemvar} and \w{datevar} to the item occurrence
  and execute \w{body}.  If \w{item} is the empty string, then start yielding
  with the first item that occurs on \w{date}.  For example, the following
  code searches for the string ``birthday''~---
\begin{verbatim}
cal loop_forward $item $date i d {
    if [string match "*birthday*" [$i text]] {
        ...
        break
    }
}
\end{verbatim}


\spec{\w{cal} loop\_backward [\w{range options}] \w{item} \w{date}\\
                \hspace*{4em} \w{itemvar} \w{datevar} \w{body}}
  For each item occurence that occurs before the specified \w{item} on the
  specified \w{date}, set \w{itemvar} and \w{datevar} to the item occurrence
  and execute \w{body}.  If \w{item} is the empty string, then start yielding
  with the last item that occurs on \w{date}.  For example, the following
  code searches for the string ``birthday''~---
\begin{verbatim}
cal loop_backward $item $date i d {
    if [string match "*birthday*" [$i text]] {
        ...
        break
    }
}
\end{verbatim}

\end{itemize}

\section{Items}
\label{sec:items}

Item objects come in two flavors -- appointments and notices.  An
appointment occurs at a specific time of the day.  A notice does not
have any associated time of day.  For example, a meeting at 3pm on
March 27th will be recorded as an appointment while somebody's
birthday on March 28th will be recorded as a notice.

Each item object also has associated text and a set of dates on which
the item occurs.

\subsection{Creation and Deletion}

The following operations can be used to create and delete items.

\begin{itemize}

\spec{notice}
  Create a notice object with empty text and an empty set of dates.

\spec{appointment}
  Create an appointment object with empty text and an empty set of dates.

\spec{\w{item} delete}
  Remove \w{item} from any calendar that contains it and delete all storage
  required for the item.

\spec{\w{item} clone}
  Create and return a copy of \w{item}.

\end{itemize}

\subsection{Item Occurrences}

The following operations can be used to manipulate and query the
set of dates on which an item occurs.

\begin{itemize}

\spec{\w{item} contains \w{date}}
  Returns true iff \w{item} occurs on \w{date}.

\spec{\w{item} empty}
  Returns true iff \w{item} has no occurrences.

\spec{\w{item} repeats}
  Returns true iff \w{item} occurs more than once.

\spec{\w{item} first}
  Returns the date of first occurrence of \w{item}.  Raises an error
  if \w{item} has no occurrences.

\spec{\w{item} next \w{date}}
  Returns the date of the first occurrence of \w{item} after \w{date}.
  Raises an error if \w{item} has no occurrences after \w{date}.

\spec{\w{item} range \w{startVar} \w{finishVar}}
  Sets \w{startVar} and \w{finishVar} to the repetition range for \w{item}
  and returns 1.  Returns 0 if item does not repeat.

\spec{\w{item} type}
  Returns a brief textual description of how the item repeats.

\spec{\w{item} describe\_repeat}
  Like ``{\bf \w{item} type}'', except that it returns a more complete
  description of how the item repeats..

\spec{\w{item} date \w{date}}
  Modifies \w{item} to occur exactly on \w{date}.

\spec{\w{item} dayrepeat \w{interval} \w{anchor}}
  Modifies \w{item} to occur on all dates that are an integral
  multiple of \w{interval} days away from \w{anchor}.  For example,
  the following code makes ``\$item'' repeat every Saturday assuming
  that the anchor date occurs on a Saturday.
\begin{verbatim}
$item dayrepeat 7 $anchor
\end{verbatim}

\spec{\w{item} monthrepeat \w{interval} \w{anchor}}
  Modifies \w{item} to occur on all dates that are an integral
  multiple of \w{interval} months away from \w{anchor}.  For example,
  the following code makes ``\$item'' repeat on the 23rd of February
  every year.
\begin{verbatim}
$item monthrepeat 12 [date make 23 12 1994]
\end{verbatim}

\spec{\w{item} weekdays [\w{weekday}...]}
  Modifies \w{item} to repeat on all specified \w{weekdays}.  For
  example, the following code makes ``\$item'' repeat on every Monday,
  Wednesday and Friday (Sunday is represented by 1, Monday is
  represented by 2, \ldots).
\begin{verbatim}
$item weekdays 2 4 6 
\end{verbatim}

\spec{\w{item} month\_day \w{n} [\w{anchor} \w{interval}]}
  Modifies \w{item} to repeat on the \w{n}th day of every month
  that is an integral number of \w{interval} months away from the
  date specified in \w{anchor}.  If \w{anchor} and \w{interval} are not
  specified, then the \w{item} repeats every month.
  For example, the following code makes
  ``\$item'' repeat on the 17th of every January because the anchor
  date is in January, and the interval is 12.
\begin{verbatim}
$item month_day 17 [date make 1 1 1994] 12
\end{verbatim}

\spec{\w{item} month\_last\_day \w{n} [\w{anchor} \w{interval}]}
  Behaves like ``{\bf \w{item} month\_day}'' except that \w{item} is made
  to repeat on the \w{n}th-{\em last\/} day of the month.
  For example, the following code makes ``\$item'' repeat on the second
  last day of every month.
\begin{verbatim}
$item month_last_day 2
\end{verbatim}

\spec{\w{item} month\_work\_day \w{n} [\w{anchor} \w{interval}]}
  Behaves like ``{\bf \w{item} month\_day}'' except that \w{item} is made to
  repeat on the \w{n}th {\em working day\/} of the month.
  For example, the following code makes ``\$item'' repeat on the first
  working day of each month.
\begin{verbatim}
$item month_work_day 1
\end{verbatim}

\spec{\w{item} month\_last\_work\_day \w{n}}
  Behaves like ``{\bf \w{item} month\_last\_day}'' except that \w{item} is made to
  repeat on the \w{n}th-last {\em working day\/} of the month.
  For example, the following code makes ``\$item'' repeat on the
  fourth-last working day of each month.
\begin{verbatim}
$item month_last_work_day 4
\end{verbatim}

\spec{\w{item} month\_week\_day \w{day} \w{n} [\w{anchor} \w{interval}]}
  Behaves like ``{\bf \w{item} month\_day}'' except that \w{item} is made
  to repeat on the \w{n}th occurrence of a particular day of the week of
  the month.
  
  The \w{day} argument should be an integer in the range $1 \ldots
  7$.  An argument of $1$ means that the item should repeat on the
  \w{n}th Sunday of the month.  An argument of $7$ means that the
  item should repeat on the \w{n}th Saturday of the month.  For example,
  the following code makes ``\$item'' repeat on the third Thursday of
  every month.  (Thursday is specified by the integer $5$).
\begin{verbatim}
$item month_week_day 5 3
\end{verbatim}

\spec{\w{item} month\_last\_week\_day \w{day} \w{n} [\w{anchor} \w{interval}]} 
  Behaves like ``{\bf \w{item} month\_week\_day}'' except that
  occurrences of \w{day} are counted from the end of the month.  For
  example, the following code makes ``\$item'' repeat on the last
  Friday of every month.  (Friday is specified by the integer $6$.)
\begin{verbatim}
$item month_last_week_day 6 1
\end{verbatim}

\spec{\w{item} start \w{date}}
  Modifies \w{item} by removing all occurrences that occur before
  \w{date}.

\spec{\w{item} finish \w{date}}
  Modifies \w{item} by removing all occurrences that occur after
  \w{date}.  For example, the following code restricts ``\$item'' to
  occur only in 1994.
\begin{verbatim}
$item start  [date make 1  1  1994]
$item finish [date make 31 12 1994]
\end{verbatim}

\spec{\w{item} deleteon \w{date}}
  If \w{item} occurs on \w{date}, removes that occurrence of \w{item}.
  Otherwise leaves \w{item} unmodified.

\end{itemize}

\subsection{Item Properties}

The following operations can be used to examine and manipulate various
properties of an item.  The first few operations apply only to
appointments.  The remaining operations apply to both appointments and
notices.

\begin{itemize}

\spec{\w{appt} length}
  Return \w{appt}'s length in minutes.

\spec{\w{appt} length \w{length}}
  Set \w{appt}'s length to \w{length} minutes.

\spec{\w{appt} starttime}
  Return the starting time for \w{appt} in minutes since midnight.

\spec{\w{appt} starttime \w{minutes}}
  Set the starting time for \w{appt} to \w{minutes} after midnight.

\spec{\w{appt} alarms}
  Return a list of alarm times.  For each entry \w{t} in this list,
  ical will generate an alarm \w{t} minutes before the appointment
  starts.  All of the elements in this list are non-negative.

\spec{\w{appt} alarms \w{list}}
  Set the list of alarm times for \w{appt}.  All of the elements of
  this list should be non-negative.  For example, the following code
  will remove all alarms from ``\$appt''.
\begin{verbatim}
$appt alarms }
\end{verbatim}
  The following code will set alarms to occur at the appointment start time,
  and also 5, 10, and 15 minutes before the appointment starts.
\begin{verbatim}
$appts alarms {0 5 10 15}
\end{verbatim}

\spec{\w{item} is appt}
  Returns true iff \w{item} is an appointment.

\spec{\w{item} is note}
  Returns true iff \w{item} is a notice.

\spec{\w{item} calendar}
  If \w{item} is contained in a calendar, return the name of that
  calendar's file.  Otherwise return the empty string.

\spec{\w{item} text}
  Return text for \w{item}.

\spec{\w{item} text \w{text}}
  Replace \w{item}'s text with \w{text}.

\spec{\w{item} earlywarning}
  Items start appearing in item listings some number of days before
  their actual occurrence.  For example, a birthday notice may start
  appearing five days early to give you enough time to go buy a
  birthday card.  This operation returns the number of days of early
  warning you get for \w{item}.

\spec{\w{item} earlywarning \w{days}}
  Set the early warning for \w{item} to \w{days}.  \w{days} must be
  non-negative.

\spec{\w{item} owner}
  Return the name of \w{item}'s owner.

\spec{\w{item} owner \w{o}}
  Make \w{o} the owner of \w{item}.

\spec{\w{item} owned}
  Returns true iff \w{item} is owned by the current user.

\spec{\w{item} own}
  Make the current user the owner of \w{item}.

\spec{\w{item} hilite}
  Return the highlight mode for \w{item}.  ``always'' means all item
  occurrences should be highlighted.  ``never'' means no item
  occurrences should be highlighted.  ``expire means only
  occurrences on or after today should be highlighted.  ``holiday''
  means that all item occurrences should be highlighted, but as holidays.

\spec{\w{item} hilite \w{mode}}
  Set the highlight mode for \w{item} to \w{mode}.
  For example, the following code will create an item for Christmas day
  and add it to the calendar.
\begin{verbatim}
set i [notice]
$i monthrepeat 12 [date make 25 12 1994]
$i text {Christmas}
$i hilite holiday
cal add $i
\end{verbatim}

\spec{\w{item} todo}
  Ical supports \w{todo} items.  If a todo item occurs in the past, that
  occurrence is automatically moved forward to today every day until
  the item is deleted, or marked as a non-todo item.  This operation
  returns true iff \w{item} is a todo item.

\spec{\w{item} todo 1}
  This operation makes \w{item} a todo item.

\spec{\w{item} todo 0}
  This operation makes \w{item} a non-todo item.

\spec{\w{item} is\_done}
  This operation returns true iff \w{item} is a todo item that
  has been marked as done.

\spec{\w{item} done 1}
  This operation makes \w{item} a todo item (if it isn't one already),
  and also marks it as done.  A done todo item stops moving forward
  every day.

\spec{\w{item} done 0}
  This operation marks the item as not done.  If the item is also a todo
  item, it will now move forward every day.

\spec{\w{item} option \w{name}}
  Look up the value associated with \w{name} in the named item \w{item}.
  An error is raised if the named option does not exist in the item.
  Example~---
\begin{verbatim}
set priority normal
catch {set priority [$item option Priority]}
\end{verbatim}

\spec{\w{item} option \w{name} \w{value}}
  Set the value of the option named \w{name} to \w{value} in the named
  item \w{item}.
  Example~---
\begin{verbatim}
$item option Priority high
\end{verbatim}

\spec{\w{item} delete_option \w{name}}
  Remove option named by \w{name}.
  An error is raised if the named option does not exist in the item.
\end{itemize}

\section{Dates}

Dates are represented in Tcl code as integers from some unspecified
date.  Therefore the ``expr'' command can be used to manipulate dates
by addition and subtraction.  Here is a list of other supported
operations on dates.

\begin{itemize}

\spec{date make \w{day} \w{month} \w{year}}
  Returns the date for the specified \w{day}, \w{month}, and \w{year}.
  \w{day}, \w{month}, and \w{year} should all be integers.  This operation
  raises an error if the date specification is invalid.  Here is an
  example of a date creation~---
\begin{verbatim}
# March 5, 1994.
set d [date make 5 3 1994]
\end{verbatim}
\spec{date today}
  Returns today's date.
\spec{date first}
  Returns the first date that can be legally represented by the ical
  implementation.
\spec{date last}
  Returns the last date that can be legally represented by the ical
  implementation.
\spec{date monthsize \w{date}}
  Return the number of days in the month containing \w{date}.
\spec{date monthday \w{date}}
  Returns the day of the month component of \w{date} as an integer in
  the range 1\ldots{}31.
\spec{date weekday \w{date}}
  Returns the day of the week component of \w{date} as an integer in the
  range 1\ldots{}7.  One corresponds to Sunday, and Seven corresponds to
  Saturday.
\spec{date month \w{date}}
  Returns the month component of \w{date} as an integer in the range
  1\ldots{}12.
\spec{date year \w{date}}
  Returns the year component of \w{date} as an integer.
\spec{date split \w{date}}
  Returns a four element list of the components of \w{date}.  The first
  element is the day of the month, the second element is the day of
  the week, the third element is the month, and the fourth element is
  the year.
\spec{date extract \w{s} \w{d} \w{pre} \w{post}}
  Returns true iff a date specification is successfully parsed from
  \w{s}.  The parsed date is stored in the variable named by \w{d}.  The
  portion of \w{s} before the parsed date specification is stored in the
  variable named by \w{pre}, and the portion of \w{s} after the parsed
  date specification is stored in the variable named by \w{post}.
  For example, the following code will store today's date in the variable
  ``date'', the string ``before'' in the variable ``pre'', and
  the string ``after'' in the variable ``post''.
\begin{verbatim}
date extract {before today after} date pre post
\end{verbatim}

\end{itemize}

\section{Times}

Times are represented in Tcl code as real numbers that give the number
of seconds since some unspecified time.  Therefore the ``expr''
command can be used to manipulate time values by addition and
subtraction.  Here is a list of other supported operations on times.

\begin{itemize}

\spec{time now}
  Returns the current time. 

\spec{time date \w{time}}
  Returns the date on which \w{time} occurs.

\spec{time hour \w{time}}
  Returns the hour of the day represented by \w{time} as an integer in
  the range 0\ldots{}23.

\spec{time minute \w{time}}
  Returns the minute of the hour represented by \w{time} as an integer in
  the range 0\ldots{}59.

\spec{time second \w{time}}
  Returns the second of the minute represented by \w{time} as an integer in
  the range 0\ldots{}59.

\spec{time millisecond \w{time}}
  Returns the millisecond of the second represented by \w{time} as an integer in
  the range 0\ldots{}999.

\spec{time split \w{time}}
  Returns a four element list of the components of \w{time}.  The first
  element is the hour, the second element is the minute, the third
  element is the second, and the fourth element is the millisecond.

\spec{time extract\_time \w{s} \w{t} \w{pre} \w{post}}
  Returns true iff a time of day specification is successfully parsed
  from \w{s}.  The parsed time is stored in the variable named by \w{d}
  as the number of seconds since midnight.  The portion of \w{s} before
  the parsed time is stored in the variable named by \w{pre}, and the
  portion of \w{s} after the parsed time is stored in the variable named
  by \w{post}.  For example, the following code will store 180 (for
  ``3am'') in the variable ``time, the string ``X'' in the
  variable ``pre'', and the string ``Y'' in the variable
  ``post''.

\begin{verbatim}
time extract_time {X 3am Y} time pre post
\end{verbatim}

\spec{time extract\_range \w{s} \w{start} \w{finish} \w{pre} \w{post}}
  Returns true iff a time range specification is successfully parsed
  from \w{s}.  The parsed time is stored in the variables named by
  \w{start} and \w{finish} as the number of seconds since midnight.  The
  portion of \w{s} before the parsed range is stored in the variable
  named by \w{pre}, and the portion of \w{s} after the parsed time is
  stored in the variable named by \w{post}.  For example, the following
  code will store 180 in the variable ``s'', 240 in the variable
  ``f'', the string ``X'' in the variable ``pre'', and the string
  ``Y'' in the variable ``post''.

\begin{verbatim}
time extract_range {X 3-4am Y} s f pre post
\end{verbatim}

\end{itemize}

\section{Customization via Hooks}

Ical provides a number of hooks.  Users can attach code to these hooks
to customize ical behavior.  Code is attached to hooks by one of
the following commands.

\begin{itemize}
\spec{append-hook \w{hook} \{\w{varnames...}\} \{\w{code}\}}
  \w{Code} will be executed when the named \w{hook} is invoked by ical.
  Ical will provide a number of arguments when it invokes \w{hook}.
  (The number of arguments will depend on the particular hook being
  invoked.)  The variables named by \w{varnames...} will be assigned the
  arguments supplied in the hook invocation before \w{code} is executed.

  For example, ical calls the ``dayview-startup'' hook when it creates
  a new calendar window.  The hook is supplied one argument, the window
  being created.  The following code changes the window to have a vertical
  layout by moving the appointment sub-window from the right side of the
  window to the bottom.

\begin{verbatim}
append-hook dayview-startup {w} {
    pack [$w window].al -side bottom
}
\end{verbatim}

\spec{prepend-hook \w{hook} \{\w{varnames...}\} \{\w{code}\}}
  This command is very similar to ``append-hook''.  The only difference is
  that the specified \w{code} will be executed before any code that is
  currently attached to \w{hook}.  (\w{Code} specified by an ``append-hook''
  command is executed after code that is already attached to the hook.)

\end{itemize}

\subsection{General Hooks}

Here is a list of some general hooks for ical.

\begin{itemize}
\spec{ical-startup}
  This hook is invoked without any arguments when ical starts up.

\spec{ical-exit}
  This hook is invoked without any arguments just before ical exits.

\spec{item-create \w{item}}
  This hook is invoked when a new item is created.  The created item is
  passed as the only argument to attached code.

\spec{item-select \w{item} \w{date}}
  This hook is invoked when an item is selected.  The selected item
  and the selected date of its occurrence are passed as arguments to
  the hook.

\spec{item-unselect \w{view} \w{date}}
  This hook is invoked when an item is unselected.  The unselected item
  and the date of its occurrence are passed as arguments to the hook.

\spec{todo-item-done \w{item}}
  This hook is invoked when a todo item is marked as done.  The done item is
  passed as the only argument to attached code.

\spec{alarm-fire \w{appt}}
  This hook is invoked whenever an alarm is generated for an appointment.
  The appointment object for which the alarm is generated is passed as
  the only argument to the attached code.
\end{itemize}

\subsection{Day Window Hooks}

The following hooks are invoked when interesting things happen to a
window that displays the items for a particular day.  These windows
are referred to as \w{dayviews} in the rest of the document.  The object
representing the dayview is passed as the first argument to these
hooks.  See Section~\ref{sec:dayview} for a description of the dayview
interface.

\begin{itemize}
\spec{dayview-startup \w{view}}
  This hook is invoked when a dayview is created.

\spec{dayview-close \w{view}}
  This hook is invoked just before a dayview is deleted.

\spec{dayview-set-date \w{view} \w{date}}
  This hook is invoked when the date displayed in a dayview is changed.
  The new date is passed as the second argument to the hook.
\end{itemize}

\section{Day Windows}
\label{sec:dayview}

\incomplete

This section describes the operations available on objects that represent
the main ical windows.  These windows display the items for a particular
day.

\section{Common Editing Actions}

\incomplete

This section describes the common editing operations that can be
invoked from user customizations.  These operations build on the
calendar and item interfaces described in earlier sections.  Use these
operations when you customize ical's user interface because these
operations provide a consistent editing interface to the user.  For
example, the operations described in this section produce friendly
messages if the user tries to edit an item in a read-only calendar.
By contrast, the low-level interfaces described in
Sections~\ref{sec:calendars} and \ref{sec:items} generate a stack
trace if they are passed invalid arguments.

\section{Miscellaneous Commands}

\noindent A few more commands are implemented in C++ to speed-up some
frequent computations.  The specifications for these commands are
given in the C++ code itself.

\end{document}
