contrib/trytime/README

   1 "trytime" is a small program that allows you to play with at-style
   2 time specifications without actually bothering any of the rrd databases.
   3 It takes either single at-style specification or two of those
   4 (for start and end time, just like rrdtool fetch or graph do) and
   5 reports what it thinks of it. The diagnostic is as close as possible
   6 to that of rrdtool compiled for at-style time specification support.
   7
   8 To learn what's possible with at-style time specifications, see
   9 the AT-STYLE TIME SPECIFICATION section in the rrdfetch documentation.
  10
  11 The formal syntax parsed is (this is taken right from the parsetime.c):
  12
  13 /*
  14  * The BNF-like specification of the time syntax parsed is below:
  15  *
  16  * As usual, [ X ] means that X is optional, { X } means that X may
  17  * be either omitted or specified as many times as needed,
  18  * alternatives are separated by |, brackets are used for grouping.
  19  * (# marks the beginning of comment that extends to the end of line)
  20  *
  21  * TIME-SPECIFICATION ::= TIME-REFERENCE [ OFFSET-SPEC ] |
  22  *                                         OFFSET-SPEC   |
  23  *                         ( START | END ) OFFSET-SPEC
  24  *
  25  * TIME-REFERENCE ::= NOW | TIME-OF-DAY-SPEC [ DAY-SPEC-1 ] |
  26  *                        [ TIME-OF-DAY-SPEC ] DAY-SPEC-2
  27  *
  28  * TIME-OF-DAY-SPEC ::= NUMBER [(':'|'.') NUMBER] [am|pm] | # HH:MM HH.MM HH[MM]
  29  *                     'noon' | 'midnight' | 'teatime'
  30  *
  31  * DAY-SPEC-1 ::= NUMBER '/' NUMBER '/' NUMBER |  # MM/DD/[YY]YY
  32  *                NUMBER '.' NUMBER '.' NUMBER |  # DD.MM.[YY]YY
  33  *                NUMBER                          # DDMM[YY]YY
  34  *
  35  * DAY-SPEC-2 ::= MONTH-NAME NUMBER [NUMBER] |    # Month DD [YY]YY
  36  *                'yesterday' | 'today' | 'tomorrow' |
  37  *                DAY-OF-WEEK
  38  *
  39  *
  40  * OFFSET-SPEC ::= '+'|'-' NUMBER TIME-UNIT { ['+'|'-'] NUMBER TIME-UNIT }
  41  *
  42  * TIME-UNIT ::= SECONDS | MINUTES | HOURS |
  43  *               DAYS | WEEKS | MONTHS | YEARS
  44  *
  45  * NOW ::= 'now' | 'n'
  46  *
  47  * START ::= 'start' | 's'
  48  * END   ::= 'end' | 'e'
  49  *
  50  * SECONDS ::= 'seconds' | 'second' | 'sec' | 's'
  51  * MINUTES ::= 'minutes' | 'minute' | 'min' | 'm'
  52  * HOURS   ::= 'hours' | 'hour' | 'hr' | 'h'
  53  * DAYS    ::= 'days' | 'day' | 'd'
  54  * WEEKS   ::= 'weeks' | 'week' | 'wk' | 'w'
  55  * MONTHS  ::= 'months' | 'month' | 'mon' | 'm'
  56  * YEARS   ::= 'years' | 'year' | 'yr' | 'y'
  57  *
  58  * MONTH-NAME ::= 'jan' | 'january' | 'feb' | 'february' | 'mar' | 'march' |
  59  *                'apr' | 'april' | 'may' | 'jun' | 'june' | 'jul' | 'july' |
  60  *                'aug' | 'august' | 'sep' | 'september' | 'oct' | 'october' |
  61  *                'nov' | 'november' | 'dec' | 'december'
  62  *
  63  * DAY-OF-WEEK ::= 'sunday' | 'sun' | 'monday' | 'mon' | 'tuesday' | 'tue' |
  64  *                 'wednesday' | 'wed' | 'thursday' | 'thu' | 'friday' | 'fri' |
  65  *                 'saturday' | 'sat'
  66  *
  67  *
  68  * As you may note, there is an ambiguity with respect to
  69  * the 'm' time unit (which can mean either minutes or months).
  70  * To cope with this, code tries to read users mind :) by applying
  71  * certain heuristics. There are two of them:
  72  *
  73  * 1. If 'm' is used in context of (i.e. right after the) years,
  74  *    months, weeks, or days it is assumed to mean months, while
  75  *    in the context of hours, minutes, and seconds it means minutes.
  76  *    (e.g., in -1y6m or +3w1m 'm' means 'months', while in
  77  *    -3h20m or +5s2m 'm' means 'minutes')
  78  *
  79  * 2. Out of context (i.e. right after the '+' or '-' sign) the
  80  *    meaning of 'm' is guessed from the number it directly follows.
  81  *    Currently, if the number absolute value is below 25 it is assumed
  82  *    that 'm' means months, otherwise it is treated as minutes.
  83  *    (e.g., -25m == -25 minutes, while +24m == +24 months)
  84  *
  85  */