doc/plugins/contrib/datetime_cmp.mdwn

   1 [[!meta author="spalax"]]
   2 [[!template id=plugin name=datetime_cmp author="[[Louis|spalax]]"]]
   3 [[!tag type/pagespec]]
   4
   5 # Datetime_cmp
   6
   7 This plugin provides a family of
   8 [pagespec](http://ikiwiki.info/ikiwiki/pagespec/) matching pages according to
   9 creation or modification times.
  10
  11 It also sets the date of the next modification of the page on relevant date, so
  12 that the page will be rebuilt if the condition changes.
  13
  14 It requires the DateTime::Format::Duration perl module (on Debian : ``apt-get install libdatetime-format-duration-perl``).
  15
  16 ## List of functions
  17
  18 The list of functions is given by the following regexp:
  19
  20     [ct](date|time)_(lt|gt|leq|geq|eq|neq)_(abs|page|now|today)(|_delta)
  21
  22 where:
  23
  24   * `[ct]`: compare creation or modification time or date:
  25     * `c`reation time;
  26     * `m`odification time.
  27   * `(date|time)`: compare full date and time, or only date (useful when time is irrelevant):
  28     * `time`: compare full date and time;
  29     * `date`: compare only date.
  30   * `(lt|gt|leq|geq|eq|neq)`: operator of comparison:
  31     * `lt`: less than;
  32     * `gt`: greater than;
  33     * `leq`: less or equal than;
  34     * `geq`: greater or equal than;
  35     * `eq`: equal;
  36     * `neq`: not equal.
  37   * `(abs|page|now|today)`: element to compare to:
  38     * `abs`: absolute date or time (given in argument);
  39     * `page`: other page (given in argument);
  40     * `now`: date or time of compilation;
  41     * `today`: same meaning as `now`.
  42   * `(|_delta)`: used to add a time delta (to use comparisons such as *created at least two days after `some_page`*):
  43     * *empty*: no delta;
  44     * `_delta`: delta (given in argument).
  45
  46 ### Number of arguments
  47
  48 [[!table header=no data="""
  49          | `now` `today`  | `page`            | `abs`
  50 no delta | *no arguments* | `pagename`        | `date`
  51 delta    | `delta`        | `pagename, delta` | `date, delta`
  52 """]]
  53
  54 ### Format of arguments
  55
  56 * *date* or *time*: anything that can be recognized by perl [[str2time|http://search.cpan.org/~rse/lcwa-1.0.0/lib/lwp/lib/HTTP/Date.pm]] function, *without any comma*.
  57 * *delta*: One of the following patterns:
  58   * `Y-M-D`: positive date;
  59   * `H:M:S`: positive time;
  60   * `Y-M-D H:M:S`: positive date and time;
  61   * Add `-` at the beginning of the string to make durations negative.
  62 * several arguments: when two arguments are provided, they are passed as one string, which is then split according to the last comma.
  63
  64 ## Time zones
  65
  66 Key `timezone` in the setup file is used to define time zone. If not set, we
  67 try to guess the local time zone.
  68
  69 ## Examples
  70
  71 ### Some functions
  72
  73 * `ctime_gt_page(foo)`: match pages created after page `foo`.
  74 * `cdate_eq_today()`: match pages created the day the wiki is compiled.
  75 * `mtime_eq_now()`: match pages modified the time the wiki is compiled (likely no page, since comparison is done up to the milisecond).
  76 * `cdate_geq_page_delta(foo, 00-00-01)`: match pages created at least one day after page `foo`.
  77 * `cdate_gt_page(foo)`: same as the previous one.
  78 * `mdate_gt_today_delta(-00-01-00)`: match pages modified one month ago, or later (can be used to display recent changes).
  79
  80 ### Use case
  81
  82 It can be used to display a list of upcoming events.
  83
  84         \[[!inline pages="events/* and cdate_geq_today()" reverse=yes sorted=meta(date)]]
  85
  86 ## Code
  87
  88 Code and documentation this way: [[https://atelier.gresille.org/projects/gresille-ikiwiki/wiki/datetime_cmp]].