Unix/Linux Go Back    


CentOS 7.0 - man page for zshcalsys (centos section 1)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


ZSHCALSYS(1)									     ZSHCALSYS(1)

NAME
       zshcalsys - zsh calendar system

DESCRIPTION
       The  shell  is  supplied with a series of functions to replace and enhance the traditional
       Unix calendar programme, which warns the user of imminent or  future  events,  details  of
       which  are  stored  in a text file (typically calendar in the user's home directory).  The
       version provided here includes a mechanism for alerting the user when an event is due.

       In addition a function age is provided that can be used in a  glob  qualifier;  it  allows
       files to be selected based on their modification times.

       The  format  of	the calendar file and the dates used there in and in the age function are
       described first, then the functions that can be called to examine and modify the  calendar
       file.

       The  functions here depend on the availability of the zsh/datetime module which is usually
       installed with the shell.  The library  function  strptime()  must  be  available;  it  is
       present on most recent operating systems.

FILE AND DATE FORMATS
   Calendar File Format
       The  calendar  file is by default ~/calendar.  This can be configured by the calendar-file
       style, see the section STYLES below.  The basic format consists of a  series  of  separate
       lines,  with  no  indentation,  each including a date and time specification followed by a
       description of the event.

       Various enhancements to this format are supported, based on the syntax of  Emacs  calendar
       mode.   An  indented  line indicates a continuation line that continues the description of
       the event from the preceding line (note the date may not be continued in  this  way).   An
       initial ampersand (&) is ignored for compatibility.

       An  indented  line  on which the first non-whitespace character is # is not displayed with
       the calendar entry, but is still scanned for information.  This can be used to hide infor-
       mation  useful  to  the calendar system but not to the user, such as the unique identifier
       used by calendar_add.

       The Emacs extension that a date with no description may refer to a  number  of  succeeding
       events at different times is not supported.

       Unless  the  done-file  style  has  been altered, any events which have been processed are
       appended to the file with the same name as the calendar file with the suffix .done,  hence
       ~/calendar.done by default.

       An example is shown below.

   Date Format
       The format of the date and time is designed to allow flexibility without admitting ambigu-
       ity.  (The words `date' and `time' are both used in the documentation below; except  where
       specifically  noted this implies a string that may include both a date and a time specifi-
       cation.)  Note that there is no localization support; month and day names must be in  Eng-
       lish and separator characters are fixed.  Matching is case insensitive, and only the first
       three letters of the names are significant, although as a special case  a  form	beginning
       "month"	does  not match "Monday".  Furthermore, time zones are not handled; all times are
       assumed to be local.

       It is recommended that, rather than exploring the intricacies of the system, users find	a
       date  format that is natural to them and stick to it.  This will avoid unexpected effects.
       Various key facts should be noted.

       o      In particular, note the confusion between month/day/year	and  day/month/year  when
	      the  month  is  numeric;	these formats should be avoided if at all possible.  Many
	      alternatives are available.

       o      The year must be given in full to avoid confusion, and only years from 1900 to 2099
	      inclusive are matched.

       The  following  give  some obvious examples; users finding here a format they like and not
       subject to vagaries of style may skip the  full	description.   As  dates  and  times  are
       matched separately (even though the time may be embedded in the date), any date format may
       be mixed with any format for the time of day provide the separators are clear (whitespace,
       colons, commas).

	      2007/04/03 13:13
	      2007/04/03:13:13
	      2007/04/03 1:13 pm
	      3rd April 2007, 13:13
	      April 3rd 2007 1:13 p.m.
	      Apr 3, 2007 13:13
	      Tue Apr 03 13:13:00 2007
	      13:13 2007/apr/3

       More detailed rules follow.

       Times  are  parsed and extracted before dates.  They must use colons to separate hours and
       minutes, though a dot is allowed before seconds if they are  present.   This  limits  time
       formats to the following:

       o      HH:MM[:SS[.FFFFF]] [am|pm|a.m.|p.m.]

       o      HH:MM.SS[.FFFFF] [am|pm|a.m.|p.m.]

       Here,  square  brackets indicate optional elements, possibly with alternatives.	Fractions
       of a second are recognised but ignored.	For absolute times (the normal format require  by
       the  calendar file and the age function) a date is mandatory but a time of day is not; the
       time returned is at the start of the date.  One variation is allowed: if a.m. or  p.m.  or
       one of their variants is present, an hour without a minute is allowed, e.g. 3 p.m..

       Time  zones  are  not  handled, though if one is matched following a time specification it
       will be removed to allow a surrounding date to be parsed.  This only happens if the format
       of  the	timezone is not too unusual.  The following are examples of forms that are under-
       stood:

	      +0100
	      GMT
	      GMT-7
	      CET+1CDT

       Any part of the timezone that is not numeric must have exactly three  capital  letters  in
       the name.

       Dates suffer from the ambiguity between DD/MM/YYYY and MM/DD/YYYY.  It is recommended this
       form is avoided with purely numeric dates, but use  of  ordinals,  eg.  3rd/04/2007,  will
       resolve the ambiguity as the ordinal is always parsed as the day of the month.  Years must
       be four digits (and the first two must be 19 or 20); 03/04/08 is  not  recognised.   Other
       numbers may have leading zeroes, but they are not required.  The following are handled:

       o      YYYY/MM/DD

       o      YYYY-MM-DD

       o      YYYY/MNM/DD

       o      YYYY-MNM-DD

       o      DD[th|st|rd] MNM[,] [ YYYY ]

       o      MNM DD[th|st|rd][,] [ YYYY ]

       o      DD[th|st|rd]/MM[,] YYYY

       o      DD[th|st|rd]/MM/YYYY

       o      MM/DD[th|st|rd][,] YYYY

       o      MM/DD[th|st|rd]/YYYY

       Here, MNM is at least the first three letters of a month name, matched case-insensitively.
       The remainder of the month name may appear but its contents are irrelevant, so  janissary,
       febrile, martial, apricot, maybe, junta, etc. are happily handled.

       Where the year is shown as optional, the current year is assumed.  There are only two such
       cases, the form Jun 20 or 14 September (the only two commonly occurring forms, apart  from
       a  "the"  in  some forms of English, which isn't currently supported).  Such dates will of
       course become ambiguous in the future, so should ideally be avoided.

       Times may follow dates with a colon, e.g. 1965/07/12:09:45; this is in order to provide	a
       format  with  no  whitespace.  A comma and whitespace are allowed, e.g. 1965/07/12, 09:45.
       Currently the order of these separators is not  checked,  so  illogical	formats  such  as
       1965/07/12,  :  ,09:45 will also be matched.  For simplicity such variations are not shown
       in the list above.  Otherwise, a time is only recognised as being associated with  a  date
       if there is only whitespace in between, or if the time was embedded in the date.

       Days  of the week are not normally scanned, but will be ignored if they occur at the start
       of the date pattern only.  However, in contexts where it is useful to specify dates  rela-
       tive to today, days of the week with no other date specification may be given.  The day is
       assumed to be either today or within the past week.  Likewise, the words yesterday,  today
       and  tomorrow  are  handled.  All matches are case-insensitive.	Hence if today is Monday,
       then Sunday is equivalent to yesterday, Monday is equivalent to today, but Tuesday gives a
       date  six days ago.  This is not generally useful within the calendar file.  Dates in this
       format may be combined with a time specification; for example Tomorrow, 8 p.m..

       For example, the standard date format:

	      Fri Aug 18 17:00:48 BST 2006

       is handled by matching HH:MM:SS and removing it together with  the  matched  (but  unused)
       time zone.  This leaves the following:

	      Fri Aug 18 2006

       Fri is ignored and the rest is matched according to the standard rules.

   Relative Time Format
       In certain places relative times are handled.  Here, a date is not allowed; instead a com-
       bination of various supported periods are allowed, together with an  optional  time.   The
       periods must be in order from most to least significant.

       In some cases, a more accurate calculation is possible when there is an anchor date:  off-
       sets of months or years pick the correct day, rather than being rounded, and it is  possi-
       ble  to	pick  a  particular  day in a month as `(1st Friday)', etc., as described in more
       detail below.

       Anchors are available in the following cases.  If one or two times are passed to the func-
       tion  calendar,	the start time acts an anchor for the end time when the end time is rela-
       tive (even if the start time is implicit).  When examining calendar files,  the	scheduled
       event  being examined anchors the warning time when it is given explicitly by means of the
       WARN keyword; likewise, the scheduled event anchors a repetition period when given by  the
       RPT  keyword,  so that specifications such as RPT 2 months, 3rd Thursday are handled prop-
       erly.  Finally, the -R argument to calendar_scandate directly provides an anchor for rela-
       tive calculations.

       The periods handled, with possible abbreviations are:

       Years  years,  yrs,  ys,  year,	yr,  y, yearly.  A year is 365.25 days unless there is an
	      anchor.

       Months months, mons, mnths, mths, month, mon, mnth, mth, monthly.  Note that  m,  ms,  mn,
	      mns  are ambiguous and are not handled.  A month is a period of 30 days rather than
	      a calendar month unless there is an anchor.

       Weeks  weeks, wks, ws, week, wk, w, weekly

       Days   days, dys, ds, day, dy, d, daily

       Hours  hours, hrs, hs, hour, hr, h, hourly

       Minutes
	      minutes, mins, minute, min, but not m, ms, mn or mns

       Seconds
	      seconds, secs, ss, second, sec, s

       Spaces between the numbers are optional, but are required between items, although a  comma
       may be used (with or without spaces).

       The  forms  yearly  to  hourly allow the number to be omitted; it is assumed to be 1.  For
       example, 1 d and daily are equivalent.  Note that using those forms with plurals  is  con-
       fusing;	2 yearly is the same as 2 years, not twice yearly, so it is recommended they only
       be used without numbers.

       When an anchor time is present, there is an extension to handle regular events in the form
       of  the	nth  someday of the month.  Such a specification must occur immediately after any
       year and month specification, but before any  time  of  day,  and  must	be  in	the  form
       n(th|st|rd)  day,  for  example	1st  Tuesday or 3rd Monday.  As in other places, days are
       matched case insensitively, must be in English, and only the first three letters are  sig-
       nificant except that a form beginning `month' does not match `Monday'.  No attempt is made
       to sanitize the resulting date; attempts to squeeze too many occurrences into a month will
       push the day into the next month (but in the obvious fashion, retaining the correct day of
       the week).

       Here are some examples:

	      30 years 3 months 4 days 3:42:41
	      14 days 5 hours
	      Monthly, 3rd Thursday
	      4d,10hr

   Example
       Here is an example calendar file.  It uses a consistent date format, as recommended above.

	      Feb 1, 2006 14:30 Pointless bureaucratic meeting
	      Mar 27, 2006 11:00 Mutual recrimination and finger pointing
		Bring water pistol and waterproofs
	      Mar 31, 2006 14:00 Very serious managerial pontification
		# UID 12C7878A9A50
	      Apr 10, 2006 13:30 Even more pointless blame assignment exercise WARN 30 mins
	      May 18, 2006 16:00 Regular moaning session RPT monthly, 3rd Thursday

       The second entry has a continuation line.  The third entry has a  continuation  line  that
       will  not  be shown when the entry is displayed, but the unique identifier will be used by
       the calendar_add function when updating the event.  The fourth entry will produce a  warn-
       ing 30 minutes before the event (to allow you to equip yourself appropriately).	The fifth
       entry repeats after a month on the 3rd Thursday, i.e. June 15, 2006, at the same time.

USER FUNCTIONS
       This section describes functions that are designed to be called directly by the user.  The
       first  part describes those functions associated with the user's calendar; the second part
       describes the use in glob qualifiers.

   Calendar system functions
       calendar [ -abdDsv ] [ -C calfile ] [ -n num ] [ -S showprog ] [ [ start ] end ](
       calendar -r [ -abdDrsv ] [ -C calfile ] [ -n num ] [ -S showprog ] [ start ]
	      Show events in the calendar.

	      With no arguments, show events from the start of today until the end  of	the  next
	      working  day after today.  In other words, if today is Friday, Saturday, or Sunday,
	      show up to the end of the following Monday, otherwise show today and tomorrow.

	      If end is given, show events from the start of today up to the time and date given,
	      which  is  in the format described in the previous section.  Note that if this is a
	      date the time is assumed to be midnight at the start of the date,  so  that  effec-
	      tively this shows all events before the given date.

	      end may start with a +, in which case the remainder of the specification is a rela-
	      tive time format as described in the previous section indicating the range of  time
	      from the start time that is to be included.

	      If start is also given, show events starting from that time and date.  The word now
	      can be used to indicate the current time.

	      To implement an alert when events are due, include calendar  -s  in  your  ~/.zshrc
	      file.

	      Options:

	      -a     Show all items in the calendar, regardless of the start and end.

	      -b     Brief:   don't display continuation lines (i.e. indented lines following the
		     line with the date/time), just the first line.

	      -B lines
		     Brief: display at most the first lines lines of the calendar entry.  `-B  1'
		     is equivalent to `-b'.

	      -C calfile
		     Explicitly specify a calendar file instead of the value of the calendar-file
		     style or the default ~/calendar.

	      -d     Move any events that have passed from the calendar file to the "done"  file,
		     as  given	by  the done-file style or the default which is the calendar file
		     with .done appended.  This option is implied by the -s option.

	      -D     Turns off the option -d, even if the -s option is also present.

	      -n num, -num
		     Show at least num events, if present in the calendar file, regardless of the
		     start and end.

	      -r     Show all the remaining options in the calendar, ignoring the given end time.
		     The start time is respected; any argument given is treated as a start time.

	      -s     Use the shell's sched command to schedule a timed event that will	warn  the
		     user  when  an  event  is due.  Note that the sched command only runs if the
		     shell is at an interactive prompt; a foreground task  blocks  the	scheduled
		     task from running until it is finished.

		     The  timed event usually runs the programme calendar_show to show the event,
		     as described in the section UTILITY FUNCTIONS below.

		     By default, a warning of the event is shown five minutes before it  is  due.
		     The  warning period can be configured by the style warn-time or for a single
		     calendar entry by including WARN reltime in the first  line  of  the  entry,
		     where reltime is one of the usual relative time formats.

		     A repeated event may be indicated by including RPT reldate in the first line
		     of the entry.  After the scheduled event  has  been  displayed  it  will  be
		     re-entered  into  the  calendar  file  at	a time reldate after the existing
		     event.  Note that this is currently the only use made of the  repeat  count,
		     so  that  it  is  not  possible to query the schedule for a recurrence of an
		     event in the calendar until the previous event has passed.

		     If RPT is used, it is also possible to specify that certain  recurrences  of
		     an  event	are  rescheduled  or cancelled.  This is done with the OCCURRENCE
		     keyword, followed by whitespace and the date and time of the  occurrence  in
		     the regular sequence, followed by whitespace and either the date and time of
		     the rescheduled event or the exact string CANCELLED.  In this case the  date
		     and  time	must  be in exactly the "date with local time" format used by the
		     text/calendar MIME type (RFC 2445),  <YYYY><MM><DD>T<hh><mm><ss>  (note  the
		     presence  of  the	literal character T).  The first word (the regular recur-
		     rence) may be something other than a proper date/time to indicate	that  the
		     event  is	additional  to the normal sequence; a convention that retains the
		     formatting appearance is XXXXXXXXTXXXXXX.

		     Furthermore, it is useful to record the next regular recurrence (as then the
		     displayed	date  may be for a rescheduled event so cannot be used for calcu-
		     lating the regular sequence).  This is specified by RECURRENCE and a time or
		     date  in  the  same  format.   calendar_add  adds such an indication when it
		     encounters a recurring event that does not include one, based on  the  head-
		     line date/time.

		     If  calendar_add  is  used  to  update occurrences the UID keyword described
		     there should be present in both the existing entry and the added  occurrence
		     in order to identify recurring event sequences.

		     For example,

			    Thu May 6, 2010 11:00 Informal chat RPT 1 week
			      # RECURRENCE 20100506T110000
			      # OCCURRENCE 20100513T110000 20100513T120000
			      # OCCURRENCE 20100520T110000 CANCELLED

		     The  event  that  occurs  at  11:00  on 13th May 2010 is rescheduled an hour
		     later.  The event that occurs a week later is  cancelled.	 The  occurrences
		     are  given  on  a	continuation line starting with a # character so will not
		     usually be displayed as part of the event.  As elsewhere, no account of time
		     zones  is	taken  with  the  times. After the next event occurs the headline
		     date/time will be `Thu May 13, 2010 12:00' while  the  RECURRENCE	date/time
		     will  be  `20100513T110000'  (note  that  cancelled and moved events are not
		     taken account of in the RECURRENCE, which	records  what  the  next  regular
		     recurrence is, but they are accounted for in the headline date/time).

		     It is safe to run calendar -s to reschedule an existing event (if the calen-
		     dar file has changed, for example), and also to have it running in multiples
		     instances of the shell since the calendar file is locked when in use.

		     By  default, expired events are moved to the "done" file; see the -d option.
		     Use -D to prevent this.

	      -S showprog
		     Explicitly specify a programme to be used for showing events instead of  the
		     value of the show-prog style or the default calendar_show.

	      -v     Verbose:	show more information about stages of processing.  This is useful
		     for confirming that the function has successfully parsed the  dates  in  the
		     calendar file.

       calendar_add [ -BL ] event ...
	      Adds  a  single  event  to the calendar in the appropriate location.  The event can
	      contain multiple lines, as described in the section  Calendar  File  Format  above.
	      Using  this  function  ensures  that  the  calendar file is sorted in date and time
	      order.  It also makes special  arrangements  for	locking  the  file  while  it  is
	      altered.	The old calendar is left in a file with the suffix .old.

	      The  option  -B  indicates that backing up the calendar file will be handled by the
	      caller and should not be performed by calendar_add.  The option -L  indicates  that
	      calendar_add  does  not  need  to  lock  the calendar file as it is already locked.
	      These options will not usually be needed by users.

	      If the style reformat-date is true, the date and time of	the  new  entry  will  be
	      rewritten  into  the  standard date format:  see the descriptions of this style and
	      the style date-format.

	      The function can use a unique identifier stored with  each  event  to  ensure  that
	      updates  to  existing  events  are treated correctly.  The entry should contain the
	      word UID, followed by whitespace, followed by a word consisting entirely	of  hexa-
	      decimal  digits  of arbitrary length (all digits are significant, including leading
	      zeroes).	As the UID is not directly useful to the user, it is convenient  to  hide
	      it on an indented continuation line starting with a #, for example:

		     Aug 31, 2007 09:30  Celebrate the end of the holidays
		       # UID 045B78A0

	      The second line will not be shown by the calendar function.

	      It  is possible to specify the RPT keyword followed by CANCELLED instead of a rela-
	      tive time.  This causes any matched event or series of events to be cancelled  (the
	      original	event does not have to be marked as recurring in order to be cancelled by
	      this method).  A UID is required in order to match an existing event in the  calen-
	      dar.

	      calendar_add will attempt to manage recurrences and occurrences of repeating events
	      as described for event scheduling by calendar -s above.  To reschedule or cancel	a
	      single  event calendar_add should be called with an entry that includes the correct
	      UID but does not include the RPT keyword as this is taken to mean the entry applies
	      to  a series of repeating events and hence replaces all existing information.  Each
	      rescheduled or cancelled occurrence must have an OCCURRENCE keyword  in  the  entry
	      passed  to  calendar_add which will be merged into the calendar file.  Any existing
	      reference to the occurrence is replaced.	An occurrence that does not  refer  to	a
	      valid existing event is added as a one-off occurrence to the same calendar entry.

       calendar_edit
	      This  calls  the	user's editor to edit the calendar file.  If there are arguments,
	      they are taken as the editor to use (the file name is appended  to  the  commands);
	      otherwise,  the  editor  is given by the variable VISUAL, if set, else the variable
	      EDITOR.

	      If the calendar scheduler was running, then after editing the file calendar  -s  is
	      called to update it.

	      This  function  locks  out the calendar system during the edit.  Hence it should be
	      used to edit the calendar file if there is any  possibility  of  a  calendar  event
	      occurring  meanwhile.   Note this can lead to another shell with calendar functions
	      enabled hanging waiting for a lock, so it is necessary to quit the editor  as  soon
	      as possible.

       calendar_parse calendar-entry
	      This is the internal function that analyses the parts of a calendar entry, which is
	      passed as the only argument.  The function returns status 1 if the  argument  could
	      not  be  parsed  as  a calendar entry and status 2 if the wrong number of arguments
	      were passed; it also sets the parameter reply to an empty associative array.   Oth-
	      erwise,  it  returns  status  0 and sets elements of the associative array reply as
	      follows:
       time   The time as a string of digits in the same units as $EPOCHSECONDS
       schedtime
	      The regularly scheduled time.  This may differ from the actual event time  time  if
	      this  is a recurring event and the next occurrence has been rescheduled.	Then time
	      gives the actual time and schedtime the time of the regular recurrence before modi-
	      fication.
       text1  The  text from the line not including the date and time of the event, but including
	      any WARN or RPT keywords and values.
       warntime
	      Any warning time given by the WARN keyword as a string  of  digits  containing  the
	      time  at	which to warn in the same units as $EPOCHSECONDS.  (Note this is an abso-
	      lute time, not the relative time passed down.)  Not set no WARN keyword  and  value
	      were matched.
       warnstr
	      The raw string matched after the WARN keyword, else unset.
       rpttime
	      Any  recurrence  time given by the RPT keyword as a string of digits containing the
	      time of the recurrence in the same units as $EPOCHSECONDS.  (Note this is an  abso-
	      lute time.)  Not set if no RPT keyword and value were matched.
       schedrpttime
	      The  next  regularly scheduled occurrence of a recurring event before modification.
	      This may differ from rpttime, which is the actual time of the event that	may  have
	      been rescheduled from the regular time.
       rptstr The raw string matched after the RPT keyword, else unset.
       text2  The text from the line after removal of the date and any keywords and values.  )

       calendar_showdate [ -r ] [ -f fmt ] date-spec ...
	      The given date-spec is interpreted and the corresponding date and time printed.  If
	      the initial date-spec begins with a + or - it is treated as relative to the current
	      time;  date-specs after the first are treated as relative to the date calculated so
	      far and a leading + is optional in that case.  This allows one to use the system as
	      a date calculator.  For example, calendar_showdate '+1 month, 1st Friday' shows the
	      date of the first Friday of next month.

	      With the option -r nothing is printed but the value of the date and time in seconds
	      since the epoch is stored in the parameter REPLY.

	      With the option -f fmt the given date/time conversion format is passed to strftime;
	      see notes on the date-format style below.

	      In order to avoid ambiguity with negative  relative  date  specifications,  options
	      must  occur  in separate words; in other words, -r and -f should not be combined in
	      the same word.

       calendar_sort
	      Sorts the calendar file into date and time order.    The old calendar is left in	a
	      file with the suffix .old.

   Glob qualifiers
       The  function  age can be autoloaded and use separately from the calendar system, although
       it uses the function calendar_scandate for date	formatting.   It  requires  the  zsh/stat
       builtin, but uses only the builtin zstat.

       age  selects files having a given modification time for use as a glob qualifier.  The for-
       mat of the date is the same as that understood by the calendar system,  described  in  the
       section FILE AND DATE FORMATS above.

       The  function can take one or two arguments, which can be supplied either directly as com-
       mand or arguments, or separately as shell parameters.

	      print *(e:age 2006/10/04 2006/10/09:)

       The example above matches all files modified between the start of those dates.  The second
       argument may alternatively be a relative time introduced by a +:

	      print *(e:age 2006/10/04 +5d:)

       The example above is equivalent to the previous example.

       In  addition  to  the  special use of days of the week, today and yesterday, times with no
       date may be specified; these apply to  today.   Obviously  such	uses  become  problematic
       around midnight.

	      print *(e-age 12:00 13:30-)

       The example above shows files modified between 12:00 and 13:00 today.

	      print *(e:age 2006/10/04:)

       The  example  above  matches  all  files modified on that date.	If the second argument is
       omitted it is taken to be exactly 24 hours after the first argument  (even  if  the  first
       argument contains a time).

	      print *(e-age 2006/10/04:10:15 2006/10/04:10:45-)

       The  example above supplies times.  Note that whitespace within the time and date specifi-
       cation must be quoted to ensure age receives the correct arguments, hence the use  of  the
       additional colon to separate the date and time.

	      AGEREF1=2006/10/04:10:15
	      AGEREF2=2006/10/04:10:45
	      print *(+age)

       This  shows the same example before using another form of argument passing.  The dates and
       times in the parameters AGEREF1 and AGEREF2 stay in effect until unset, but will be  over-
       ridden  if  any	argument is passed as an explicit argument to age.  Any explicit argument
       causes both parameters to be ignored.

STYLES
       The zsh style mechanism using the zstyle command is describe in	zshmodules(1).	 This  is
       the same mechanism used in the completion system.

       The  styles  below are all examined in the context :datetime:function:, for example :date-
       time:calendar:.

       calendar-file
	      The location of the main calendar.  The default is ~/calendar.

       date-format
	      A strftime format string (see strftime(3)) with the zsh extensions providing  vari-
	      ous  numbers  with  no  leading  zero  or  space if the number is a single digit as
	      described for the %D{string} prompt format  in  the  section  EXPANSION  OF  PROMPT
	      SEQUENCES in zshmisc(1).

	      This  is	used  for outputting dates in calendar, both to support the -v option and
	      when adding recurring events back to the calendar file, and in calendar_showdate as
	      the final output format.

	      If  the style is not set, the default used is similar the standard system format as
	      output by the date command (also known as `ctime format'): `%a %b  %d  %H:%M:%S  %Z
	      %Y'.

       done-file
	      The  location  of  the  file  to	which events which have passed are appended.  The
	      default is the calendar file location with the suffix .done.  The style may be  set
	      to an empty string in which case a "done" file will not be maintained.

       reformat-date
	      Boolean,	used  by  calendar_add.   If it is true, the date and time of new entries
	      added to the calendar will  be  reformatted  to  the  format  given  by  the  style
	      date-format  or  its default.  Only the date and time of the event itself is refor-
	      matted; any subsidiary dates and times such as those  associated	with  repeat  and
	      warning times are left alone.

       show-prog
	      The programme run by calendar for showing events.  It will be passed the start time
	      and stop time of the events requested in seconds since the epoch	followed  by  the
	      event  text.   Note  that  calendar -s uses a start time and stop time equal to one
	      another to indicate alerts for specific events.

	      The default is the function calendar_show.

       warn-time
	      The time before an event at which a warning will be displayed, if the first line of
	      the event does not include the text EVENT reltime.  The default is 5 minutes.

UTILITY FUNCTIONS
       calendar_lockfiles
	      Attempt  to lock the files given in the argument.  To prevent problems with network
	      file locking this is done in an ad hoc fashion by attempting to create  a  symbolic
	      link  to the file with the name file.lockfile.  No other system level functions are
	      used for locking, i.e. the file can be accessed and modified by  any  utility  that
	      does not use this mechanism.  In particular, the user is not prevented from editing
	      the calendar file at the same time unless calendar_edit is used.

	      Three attempts are made to lock the file before giving up.  If the module  zsh/zse-
	      lect  is	available,  the  times	of  the  attempts  are	jittered so that multiple
	      instances of the calling function are unlikely to retry at the same time.

	      The files locked are appended to the array lockfiles, which should be local to  the
	      caller.

	      If all files were successfully locked, status zero is returned, else status one.

	      This  function  may  be used as a general file locking function, although this will
	      only work if only this mechanism is used to lock files.

       calendar_read
	      This is a backend used by various other functions to parse the calendar file, which
	      is  passed  as the only argument.  The array calendar_entries is set to the list of
	      events in the file; no pruning is done except that ampersands are removed from  the
	      start of the line.  Each entry may contain multiple lines.

       calendar_scandate
	      This  is	a  generic  function to parse dates and times that may be used separately
	      from the calendar system.   The  argument  is  a	date  or  time	specification  as
	      described  in  the section FILE AND DATE FORMATS above.  The parameter REPLY is set
	      to the number of seconds since the epoch corresponding to that date  or  time.   By
	      default, the date and time may occur anywhere within the given argument.

	      Returns status zero if the date and time were successfully parsed, else one.

	      Options:
	      -a     The  date	and time are anchored to the start of the argument; they will not
		     be matched if there is preceding text.

	      -A     The date and time are anchored to both the start and end  of  the	argument;
		     they will not be matched if the is any other text in the argument.

	      -d     Enable additional debugging output.

	      -m     Minus.   When  -R	anchor_time is also given the relative time is calculated
		     backwards from anchor_time.

	      -r     The argument passed is to be parsed as a relative time.

	      -R anchor_time
		     The argument passed is to be parsed as a relative time.  The time	is  rela-
		     tive  to  anchor_time,  a	time in seconds since the epoch, and the returned
		     value is the absolute time corresponding to  advancing  anchor_time  by  the
		     relative  time  given.   This allows lengths of months to be correctly taken
		     into account.  If the final day does not exist in the given month, the  last
		     day  of the final month is given.	For example, if the anchor time is during
		     31st January 2007 and the relative time is 1 month, the final  time  is  the
		     same time of day during 28th February 2007.

	      -s     In  addition  to  setting REPLY, set REPLY2 to the remainder of the argument
		     after the date and time have been stripped.  This is empty if the option  -A
		     was given.

	      -t     Allow  a  time with no date specification.  The date is assumed to be today.
		     The behaviour is unspecified if the  iron	tongue	of  midnight  is  tolling
		     twelve.

       calendar_show
	      The  function  used  by default to display events.  It accepts a start time and end
	      time for events, both in epoch seconds, and an event description.

	      The event is always printed to standard output.  If  the	command  line  editor  is
	      active  (which will usually be the case) the command line will be redisplayed after
	      the output.

	      If the parameter DISPLAY is set and the start and end times are the same	(indicat-
	      ing  a scheduled event), the function uses the command xmessage to display a window
	      with the event details.

BUGS
       As the system is based entirely on  shell  functions  (with  a  little  support	from  the
       zsh/datetime  module)  the  mechanisms used are not as robust as those provided by a dedi-
       cated calendar utility.	Consequently the user should not rely  on  the	shell  for  vital
       alerts.

       There is no calendar_delete function.

       There  is no localization support for dates and times, nor any support for the use of time
       zones.

       Relative periods of months and years do not take into account the variable number of days.

       The calendar_show function is currently hardwired to use xmessage for displaying alerts on
       X  Window  System displays.  This should be configurable and ideally integrate better with
       the desktop.

       calendar_lockfiles hangs the shell while waiting for a lock on a file.  If called  from	a
       scheduled task, it should instead reschedule the event that caused it.

zsh 5.0.2				December 21, 2012			     ZSHCALSYS(1)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 03:03 AM.