data/TWiki/TWikiTimeDotPm.txt
changeset 0 414e01d06fd5
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/data/TWiki/TWikiTimeDotPm.txt	Sat Jan 26 15:50:53 2008 +0100
     1.3 @@ -0,0 +1,115 @@
     1.4 +---+ Package =TWiki::Time=
     1.5 +
     1.6 +Time handling functions.
     1.7 +
     1.8 +
     1.9 +%TOC%
    1.10 +
    1.11 +---++ StaticMethod *parseTime* <tt>($szDate,$defaultLocal) -> $iSecs</tt>
    1.12 +
    1.13 +Convert string date/time string to seconds since epoch (1970-01-01T00:00:00Z).
    1.14 +   * =$sDate= - date/time string
    1.15 +
    1.16 +Handles the following formats:
    1.17 +
    1.18 +Default TWiki format
    1.19 +   * 31 Dec 2001 - 23:59
    1.20 +
    1.21 +TWiki format without time (defaults to 00:00)
    1.22 +   * 31 Dec 2001
    1.23 +
    1.24 +Date seperated by '/', '.' or '-', time with '.' or ':'
    1.25 +Date and time separated by ' ', '.' and/or '-'
    1.26 +   * 2001/12/31 23:59:59
    1.27 +   * 2001.12.31.23.59.59
    1.28 +   * 2001/12/31 23:59
    1.29 +   * 2001.12.31.23.59
    1.30 +   * 2001-12-31 23:59
    1.31 +   * 2001-12-31 - 23:59
    1.32 +
    1.33 +ISO format
    1.34 +   * 2001-12-31T23:59:59
    1.35 +ISO dates may have a timezone specifier, either Z or a signed difference
    1.36 +in hh:mm format. For example:
    1.37 +   * 2001-12-31T23:59:59+01:00
    1.38 +   * 2001-12-31T23:59Z
    1.39 +The default timezone is Z, unless $defaultLocal is true in which case
    1.40 +the local timezone will be assumed.
    1.41 +
    1.42 +If the date format was not recognised, will return 0.
    1.43 +
    1.44 +
    1.45 +
    1.46 +---++ StaticMethod *formatTime* <tt>($epochSeconds,$formatString,$outputTimeZone) -> $value</tt>
    1.47 +
    1.48 +   * =$epochSeconds= epochSecs GMT
    1.49 +   * =$formatString= twiki time date format, default =$day $month $year - $hour:$min=
    1.50 +   * =$outputTimeZone= timezone to display, =gmtime= or =servertime=, default is whatever is set in $TWiki::cfg{DisplayTimeValues}
    1.51 +=$formatString= supports:
    1.52 +   | $seconds | secs |
    1.53 +   | $minutes | mins |
    1.54 +   | $hours | hours |
    1.55 +   | $day | date |
    1.56 +   | $wday | weekday name |
    1.57 +   | $dow | day number (0 = Sunday) |
    1.58 +   | $week | week number |
    1.59 +   | $month | month name |
    1.60 +   | $mo | month number |
    1.61 +   | $year | 4-digit year |
    1.62 +   | $ye | 2-digit year |
    1.63 +   | $http | ful HTTP header format date/time |
    1.64 +   | $email | full email format date/time |
    1.65 +   | $rcs | full RCS format date/time |
    1.66 +   | $epoch | seconds since 1st January 1970 |
    1.67 +
    1.68 +
    1.69 +
    1.70 +---++ StaticMethod *formatDelta* <tt>($s) -> $string</tt>
    1.71 +
    1.72 +Format a time in seconds as a string. For example,
    1.73 +"1 day, 3 hours, 2 minutes, 6 seconds"
    1.74 +
    1.75 +
    1.76 +
    1.77 +---++ StaticMethod *parseInterval* <tt>($szInterval) -> [$iSecs,$iSecs]</tt>
    1.78 +
    1.79 +Convert string representing a time interval to a pair of integers
    1.80 +representing the amount of seconds since epoch for the start and end
    1.81 +extremes of the time interval.
    1.82 +
    1.83 +   * =$szInterval= - time interval string
    1.84 +
    1.85 +in yacc syntax, grammar and actions:
    1.86 +<verbatim>
    1.87 +interval ::= date                 { $$.start = fillStart($1); $$.end = fillEnd($1); }
    1.88 +         | date '/' date          { $$.start = fillStart($1); $$.end = fillEnd($3); }
    1.89 +         | 'P' duration '/' date  { $$.start = fillEnd($4)-$2; $$.end = fillEnd($4); }
    1.90 +         | date '/' 'P' duration  { $$.start = fillStart($1); $$.end = fillStart($1)+$4; }
    1.91 +         ;
    1.92 +</verbatim>
    1.93 +an =interval= may be followed by a timezone specification string (this is not supported yet).
    1.94 +
    1.95 +=duration= has the form (regular expression):
    1.96 +<verbatim>
    1.97 +   P(<number><nameOfDuration>)+
    1.98 +</verbatim>
    1.99 +
   1.100 +nameOfDuration may be one of:
   1.101 +   * y(year), m(month), w(week), d(day), h(hour), M(minute), S(second)
   1.102 +
   1.103 +=date= follows ISO8601 and must include hypens.  (any amount of trailing
   1.104 +       elements may be omitted and will be filled in differently on the
   1.105 +       differents ends of the interval as to include the longest possible
   1.106 +       interval):
   1.107 +
   1.108 +   * 2001-01-01T00:00:00
   1.109 +   * 2001-12-31T23:59:59
   1.110 +
   1.111 +timezone is optional. Default is local time.
   1.112 +
   1.113 +If the format is not recognised, will return empty interval [0,0].
   1.114 +
   1.115 +TODO: timezone
   1.116 +      testing, especially on non valid strings
   1.117 +
   1.118 +