trange

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