TRANGE ====== Translate human time ranges to a machine-readable way. SYNOPSIS -------- trange [options] [WHICH] WHAT [to [WHICH] WHAT] DESCRIPTION ----------- WHICH is an expression to specify which occurence of given range we want. Default value is "auto", which means the same as "this" if we are in the range, "next" otherwise. WHAT is name of the range. It can be as granular as needed: common units (hour, week, month, year) are built-in but trange can be extended to support anything from day names (Sunday, Monday) to holiday names (Christmas, Easter), to custom ranges like moon phases, birthdays or regular team meetings. Rules for distinction between WHICH and WHAT are following: * WHICH must be a valid selector expression as described below If invalid expression is found, it is assumed as WHAT and WHICH is set to AUTO. * WHAT is either a built-in name or an extended name. Built-in names are lowercase only and extended must start with uppercase, e.g. "Christmas". If third argument is `to`, another range specifier follows. The final range is then inclusive, i.e. both ranges plus the "gap" (if any) between them. This allows for definitions like last week to next week In case left part of the range is later in time, strict mode results in error, otherwise it's silently switched. SELECTOR EXPRESSION ------------------- Selector expression syntax is keyword[offset] keyword must be one of built-in keywords: `next`, `last` or `this`. The former two are self-explanatory, "this" mostly does what you mean, but exceptions may exist, see next section for explanation. Offset can be provided to select a sooner or later occurence of the range. Valid offset consists of one or more plus or minus singns and optionally a digit. Valid forms are: +|-[n] +[+]... -[-]... Offset changes selection based on the sign: regardless of the keyword, minus always refers to an earlier ocurrence, plus refers to later. Number `n` is a positive integer and specifies how many ocurrences to offset. Providing multiple signs is equivalent to providing sign and `n`. Following expressions are equivalent: next++ next+2 last last+0 this++++++++++ next+10 ### `this` keyword ### Most ranges (like month or hour) are coherent, i.e. there is no point in time that is outside such range. For these, meaning of "this" is obvious. However, non-coherent ranges can be defined, like "Christmas" or "Sunday". For these ranges, if current date is outside, "this" is silently interpreted as "next" so that for example phrase "this Sunday" means what we want it to mean. Note that this substitution makes phrases like `next- Sunday` potentially dangerous since they change meaning depending on if it's Sunday or not. You can use strict mode to disable it and have trange report failure instead. UNITS ----- Question of granularity is addressed by use of units. Unit says what is the smallest time unit to consider when expressing or enumerating the range. Each named range has assigned default unit. For example, when we say next week, we generally refer to range of days rather than hours, but when we say "next day", we rather mean twenty-four hours. One thing this affects is how trange will express the time, whether it will only list days or seconds, etc. But most importantly, this is needed if we want trange to enumerate the range. For example, when enumetaring next week, we normally only want to output six dates: $ trange -1 -e next week 2014-05-12 2014-05-13 2014-05-14 2014-05-15 2014-05-16 2014-05-17 2014-05-18 $ but we might also want to select each hour: $ trange -u hour -1 -e next week 2014-05-12 00:00 2014-05-12 01:00 ... 2014-05-12 22:00 2014-05-12 23:00 2014-05-13 00:00 ... 2014-05-18 23:00 $ OPTIONS ------- -0,--null terminate items with null string -1,--line output one item per line --json same as --format=json -e,--enum enumerate all UNITs in range, not just first and last -f,--from display only FROM -F,--format=FORMAT use one of formats: words, lines, json or a UNIX date format, if FORMAT starts with "+" -D,--date=DATE use DATE instead of reading system clock. DATE must be in ISO 8601 format -S,--strict strict mode, e.g. do not change "this" to "next" -t,--to display only TO -u,--unit second|day|hour|minute|month|year|auto, default=auto -v,--verbose be verbose, e.g. warn about this vs. next EXAMPLES -------- $ trange last week 2013-01-01 2013-12-31 $ trange next year 2015-01-01 2015-12-31 $ trange next hour --json { "from": { "day": 30, "hour": 16, "minute": 0, "month": 0, "second": 0, "year": 2014 }, "to": { "day": 30, "hour": 17, "minute": 0, "month": 0, "second": 0, "year": 2014 } } $ trange next Christmas 2014-12-25 2014-12-26 $ trange next+ Christmas 2015-12-25 2015-12-26 $ trange next++ Christmas 2016-12-25 2016-12-26 $ trange next+2 Christmas 2016-12-25 2016-12-26 $ trange -1 -e next week 2014-05-12 2014-05-13 2014-05-14 2014-05-15 2014-05-16 2014-05-17 2014-05-18 $ trange last week to next week 2014-05-05 2014-05-25 EXIT VALUE ---------- trange returns zero on success, non-zero otherwise (syntax error, non-existent range). AUTHOR ------ Alois Mahdal