DateManipPlugin

Date times, durations and recurrences

Description

This plugin adds the power of date-time manipulations of Date::Manip to Foswiki:

• localized formatting of date time
• time deltas, durations
• recurrences

In addition all calculations can either be performed in "standard" mode or in "business" mode. Standard arithmetics are performed based on the normal calendar relationship. In business mode off times are left out. Only working days of a week, work times per day and holidays are excluded from calcuating durations, deltas and recurences.

Related plugins and macros

There are related plugins that have a feature overlap with this one.

• TimeSincePlugin: can only render durations, is superseded by the %DURATION macro
• SpreadSheetPlugin: its %FORMATTIMEDIFF is yet another implementation of the same feature that %DURATION provides; this plugin is able to perform simple time calculations
• DateTimePlugin: this is another plugin to add more flexibility to the core date macros of Foswiki; albeit its name it does not use the DateTime and its related perl packages; localization as well as supported date formats are rather limitted
• there are a set of core macros (%GMTIME, %DATE, %SERVERTIME, etc) that all tend to cover the same feature, however are rather limited and not localized

None of the previous work covers recurrences or a "business" mode of date calculations.

Language support

Date::Manip is able to parse a wide variety of date formats, as well as understands date times and deltas specified by a limited set of natural language in various languages.

Supported languages are:

1. Catalan
2. Danish
3. Dutch
4. English
5. Finnish
6. French
7. German
8. Italian
9. Norwegian
10. Polish
11. Portugue
12. Romanian
13. Russian
14. Spanish
15. Swedish
16. Turkish

Unless specified explicitly in the macro or via the LANGUAGE preference setting, the browser's language is used to parse and render date times and deltas.

See the list of english terms that can be used in dates.

Examples

Dates

%DATETIME{"today"}%

%DATETIME{"1st Thursday in June 1992"}%

%DATETIME{"05/10/93"}%

%DATETIME{"8:00pm December tenth"}%

%DATETIME{"2017/11/21" delta="one week later"}%

%DATETIME{"now" delta="in two hours three minutes"}%

%DATETIME{"jetzt" delta="vor zwei tagen" language="de"}%

%DATETIME{"2/Mar/1999 15:30:00 +0500"}%

%DATETIME{"Jan 30 1999 13:00 EST"}%

%DATETIME{"1511259079"}%

%DATETIME{"1er decembre 1990" language="fr"}%

Durations

%DURATION{"in 12 hours"}%

%DURATION{"-1:30:0"}%

%DURATION{"4 business days later"}%

Recurrences

Every second hour today

%RECURRENCE{
   frequency="0:0:0:0:2:0:0"
   start="today"
   end="tomorrow"
}%

2nd Tuesday of every month from Jan 1 1999 to Apr 30 1999

%RECURRENCE{
   frequency="0:1*2:2:0:0:0" 
   start="Jan 1 1999" 
   end="Apr 30 1999"
   format="   * $weekday, $day $month $year"
   separator="$n"
}%

Monday after Easter in 1997-1999

%RECURRENCE{"*1997-1999:0:0:0:0:0:0*EASTER,ND1"}%

Syntax

%DATETIME

This macro is used to output a date and/or a time or any portion of it. A point in time can either be specified directly in one of the many formats understood, or using an additional delta which is either added or subtracted from the base date.

Parameter	Description	Default
"<date-spec>", date="<date-spec>"	date; see the list of valid date formats below	now
delta="<delta-spec>"	a duration added or subtracted from the given date	0:0:0:0:0:0:0
business="<boolean>"	switch to enable/disable business date arithmetics	off
subtract="<boolean>"	switch to enable subtraction of the given delta	off
format="<format-spec>"	format string to render the date time output; see below for valid format strings	$Foswiki::cfg{DateManipPlugin}{DefaultDateTimeFormat} or %d %b %Y - %H:%M
lang="...", language="..."	code of language that date is parsed as well as formatted	LANGUAGE preference setting or the browser's default language

A <format-spec> may use either the printf directives of Date::Manip or Foswiki's own tokens as per VarGMTIME with a few additions and diversions.

Foswiki tokens

Token	Unit	Example
$iso	ISO format timestamp	2024-11-25T19:11:07Z
$rcs	RCS format timestamp	2024/11/25 19:11:07
$http	E-mail & http format timestamp	Mon, 25 November 2024 19:11:07 GMT
$year	4 digit year	1999
$ye	2 digit year	99
$month	name of month	December
$mon	short name of month	Dec
$mo	2 digit month	12
$weekday	name of day of the week	Tuesday
$wday	short name of day of the week	Tue
$day	day of month	31
$dow	day of the week (Sun = 0)	2
$doy	day of the year	123
$dom	day of the month with suffix	1rst, 2nd, ...
$hours	hours 00 - 23	23
$h	hours 0 - 23	7
$hours12	hours 01 - 12	11
$h12	hours 1 - 12 pm/am	7 pm
$minutes	minutes	59
$seconds	seconds	59
$week	number of week in year (ISO 8601)	34
$tz	time zone abbreviation	EDT
$offset	time zone as GMT offset	+0100
$epoch	number of seconds since 00:00 on 1st January, 1970	1732561867

Printf tokens

Year
    %y     year                     - 00 to 99
    %Y     year                     - 0001 to 9999

Month, Week
    %m     month of year            - 01 to 12
    %f     month of year            - " 1" to "12"
    %b,%h  month abbreviation       - Jan to Dec
    %B     month name               - January to December

Day
    %j     day of the year          - 001 to 366
    %d     day of month             - 01 to 31
    %e     day of month             - " 1" to "31"
    %v     weekday abbreviation     - " S"," M"," T", ...
    %a     weekday abbreviation     - Sun to Sat
    %A     weekday name             - Sunday to Saturday
    %w     day of week              - 1 to 7 (1=Monday)
    %E     day of month with
           suffix                   - 1st, 2nd, 3rd...

Hour
    %H     hour                     - 00 to 23
    %k     hour                     - " 0" to "23"
    %i     hour                     - " 1" to "12"
    %I     hour                     - 01 to 12
    %p     AM or PM

Minute, Second, Time zone
    %M     minute                   - 00 to 59
    %S     second                   - 00 to 59
    %Z     time zone abbreviation   - EDT
    %z     time zone as GMT offset  - +0100 
    %N     time zone as GMT offset  - +01:00:00

Epoch 
    %s     seconds from
           1/1/1970 GMT             - negative if before
    %o     seconds from 1/1/1970
           in the current time
           zone

Date, Time
    %c     %a %b %e %H:%M:%S %Y     - Fri Apr 28 17:23:15 1995
    %C,%u  %a %b %e %H:%M:%S %Z %Y  - Fri Apr 28 17:25:57 EDT 1995
    %g     %a, %d %b %Y %H:%M:%S %Z - Fri, 28 Apr 1995 17:23:15 EDT
    %D     %m/%d/%y                 - 04/28/95
    %x     %m/%d/%y or %d/%m/%y     - 04/28/95 or 28/04/95
                                      (Depends on DateFormat variable)
    %l     date in ls(1) format
             %b %e %H:%M            - Apr 28 17:23 (*)
             %b %e  %Y              - Apr 28  1993 (*)
    %r     %I:%M:%S %p              - 05:39:55 PM
    %R     %H:%M                    - 17:40
    %T,%X  %H:%M:%S                 - 17:40:58
    %V     %m%d%H%M%y               - 0428174095
    %Q     %Y%m%d                   - 19961025
    %q     %Y%m%d%H%M%S             - 19961025174058
    %P     %Y%m%d%H:%M:%S           - 1996102517:40:58
    %O     %Y-%m-%dT%H:%M:%S        - 1996-10-25T17:40:58
    %F     %A, %B %e, %Y            - Sunday, January  1, 1996
    %K     %Y-%j                    - 1997-045

Special Year/Week formats 
    %G     year, Monday as first
           day of week              - 0001 to 9999
    %W     week of year, Monday
           as first day of week     - 01 to 53
    %L     year, Sunday as first
           day of week              - 0001 to 9999
    %U     week of year, Sunday
           as first day of week     - 01 to 53
    %J     %G-W%W-%w                - 1997-W02-2

Other formats
    %n     insert a newline character
    %t     insert a tab character
    %%     insert a `%' character
    %+     insert a `+' character

All other characters are currently unused, but may be used in the
future.  They currently insert the character following the %.

The following multi-character formats also exist:

Extended formats
    %<A=NUM>   These returns the NUMth value of the %A, %a, and %v formats
    %<a=NUM>   respectively.  In English, that would yield:
    %<v=NUM>      %<A=2>   => Tuesday
                  %<a=2>   => Tue
                  %<v=2>   => T
               NUM must be in the range 1-7.

    %<B=NUM>   These return the NUMth value of the %B and %b formats
    %<b=NUM>   respectively.  In English, that would yield:
                  %<B=2>   => February
                  %<b=2>   => Feb
               NUM must be in the range 1-12 (or 01-12).

    %<p=NUM>   These return the NUMth value of the %p format.  In
               English, that would yield:
                  %<p=1>   => AM
                  %<p=2>   => PM
               NUM must be in the range 1-2.

    %<E=NUM>   These return the NUMth value of the %E format.  In
               English, that would yield:
                  %<E=1>   => 1st
                  %<E=53>  => 53rd
               NUM must be in the range 1-53.

%DURATION

This macro returns the number of seconds, minuts, hours, ..., years in the specified delta. A duration can either be given by two dates from and to or directly as in "in two hours" or the like. The output is either rendered using a given duraction spec string in the format parameter or via a list of units such as in "2 days 3 hours and 1 minute"

Parameter	Description	Default
"<delta-spec>"	duration of the time span; if specified from and to are not used	0:0:0:0:0:0:0
from="<date-spec>"	time span start	now
to="<date-spec>"	time span end	now
lang="...", language="..."	code of language that from and to is parsed	LANGUAGE preference setting or the browser's default language
business="<boolean>"	switch to enable/disable business date arithmetics	off
subtract="<boolean>"	switch to subtract from from to rather than the other way around	off
format="<delta-spec>"	if specfified will render the delta based on a "delta-spec"; for example %Dt will return the raw delta value in Date::Manip's delta notation; if not will the number of hours, minutes, seconds etc be returned
years="<boolean>"	switch on/off the "years" unit	on
months="<boolean>"	switch on/off the "months" unit	on
weeks="<boolean>"	switch on/off the "weeks" unit	on
days="<boolean>"	switch on/off the "days" unit	on
hours="<boolean>"	switch on/off the "hours" unit	on
minutes="<boolean>"	switch on/off the "minutes" unit	on
seconds="<boolean>"	switch on/off the "seconds" unit	on
null="..."	string to be returned for a duration of zero seconds	null
units="..."	maximum number of units to use; the rest of the duration value is truncated

A duration is stored internally as a vector 1:2:3:4:5:6:7 which specifies the years, months, weeks, days, hours, minutes and seconds of a duration. In general each of these values can be positive as well as negative. Tokens of a %DURATION's format string start with a %. A single % is replaced by a double %%.

Token	Description	Example
%[+][pad][width]Xv	directives to print out a single field; X is one of y,M,w,d,h,m,s, pad is <, > or 0	"Month: %Mv": Month 2, "Day: %+05v": Day: +0004
%[+][pad][width][.precision] XYZ	directives to print out several fields in terms of one of them; X, Y, and Z are each one of y,M,w,d,h,m,s	%sdh day and hour fields in terms of seconds, "%.4Myw months": 14.6900 monts
%[+][pad][width]DXY	directives to print out portions of the duration; X and Y are each one of y,M,w,d,h,m,s	%+Dyd: +1:+2:+3:+4
%[+][pad][width]Dt	directive to print out all of the duration

If no format string is specified a list of units is returne and the years, months, weeks, days, hours, minutes and seconds parameters take effect, as well as limit, units and null.

For example

%DURATION{from="12:00" to="18:47:03"}%

will return

6 hours, 47 minutes and 3 seconds

in case your browser language is set to English

or

6 Stunden, 47 Minuten und 3 Sekunden

when set to German.

WARNING: right now Date::Manip does not support localized output of durations by itself. The output of the %DURATION macro is not affected by its language parameter. It only affects the way a <delta-spec> or <date-spec> is parsed in. Thus we are using Foswiki's support for internationalization, i.e. its %MAKETEXT macro ... which however does not produce any other language's output other than the browser's currently configured one.

%RECURRENCE

A recurrence is a compact specification of a set of dates. This macro will render a list of date times within the given recurrence. Please have a look at the official frequency notation] for a detailed explanation. A recurrence can either be specified in the compact notation - such as in "*1997-1999:0:0:0:0:0:0*EASTER,ND1" - or separated into the five base parameter, frequency, start, end, base and modifiers. Either a rec-spec or a frequency parameter is mandatory. The parameters frequency, start, end, base and modifiers are ignored once a rec-spec is provide. If no end date is specified the recurrence is open. Make sure that you restrict the output of returned dates using the limit parameter.

Parameter	Description	Default
"<rec-spec>"	recurrence specifier
freq="...", frequency="..."	frequency specifier
start="<date-spec>"	date when the recurence starts	now
end="<date-spec>"	date when the recurence ends
base="<date-spec>"	base date when the recurence starts; this date is used by the modifiers, i.e. to specify an offset for the recurrence
limit="..."	maximum number of dates rendered in the output	1000
lang="...", language="..."	output language of date times	LANGUAGE preference setting or the browser's default language
format="&format-spec>"	format string to render a date time in the list of returned dates	$Foswiki::cfg{DateManipPlugin}{DefaultDateTimeFormat} or %d %b %Y - %H:%M
header="..."	header string prepended to the output in case the recurrence is not empty
footer="..."	footer string appended to the output in case the recurrence is not empty
separator="..."	separator string between returned lines returned

Valid formats

Part of the power of Date::Manip is its cheer amount of formats of dates, times and durations it is able to parse. So instead of repeating the documentation available online for this perl package here are simply the links to the real source of the documentation.

• date formats
• time formats
• combined date and time formats
• timezone formats
• delta formats
• frequency notation
• recurrence modifiers

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

Name	Version	Description
Date::Manip	>=6.0	Required.

Change History

12 Nov 2019	improve compatibility with default time formatting
03 Oct 2018	performance improvement
20 Jun 2018	monkey patch core date time parser and formatter with own one
28 May 2018	support "all ints" epoch seconds without having to prefix it with "epoch" (compatibility with DateTimePlugin)
24 Nov 2017	initial release