doc/plugins/contrib/datetime_cmp.mdwn

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