kairos 0.4.0

A library on top of chrono to calculate times and dates ergonomically
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180

# The kairos language

Kairos features a parser frontend which can be used to parse user input into
either a `TimeType` or an `UserIterator`.

This is the documentation for the language this parser understands.


## Basics

There is only addition and subtraction

```
operator = "+" | "-"
```

Numbers are valid, too.

```
digit  = "0" | "1" "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
number = digit+
```


## Units

A unit specifies the Unit of a number

```
second_unit = "seconds" | "second" | "secs" | "sec" | "s"
minute_unit = "minutes" | "minute" | "mins" | "min"
hour_unit   = "hours" | "hour" | "hrs" | "hr"
day_unit    = "days" | "day" | "d"
week_unit   = "weeks" | "week" | "w"
month_unit  = "months" | "month"
year_unit   = "years" | "year" | "yrs"

unit =
  second_unit |
  minute_unit |
  hour_unit   |
  day_unit    |
  week_unit   |
  month_unit  |
  year_unit   |
```


## Aliases

An alias can be used for specifying "one of a <unit>". For example "1second"
can be specified as "secondly"

```
second_alias = "secondly"
minute_alias = "minutely"
hour_alias   = "hourly"
day_alias    = "daily"
week_alias   = "weekly"
month_alias  = "monthly"
year_alias   = "yearly"
```


## Amounts

An amount is a number plus a unit, or an alias

```
second_amount = number second_unit | second_alias
minute_amount = number minute_unit | minute_alias
hour_amount   = number hour_unit   | hour_alias
day_amount    = number day_unit    | day_alias
week_amount   = number week_unit   | week_alias
month_amount  = number month_unit  | month_alias
year_amount   = number year_unit   | year_alias

amount =
  second_amount |
  minute_amount |
  hour_amount   |
  day_amount    |
  week_amount   |
  month_amount  |
  year_amount
```

## Exact dates

Exact dates can be specified in ISO 8601 format. The time is optional.
Aliases for today, yesterday and tomorrow exist.

```
two_digits = digit digit

offset = "+" two_digits two_digits
time   = two_digits (":" two_digits (":" two_digits offset?)?)?

exact_date =
  two_digits two_digits ("-" two_digits ("-" two_digits ("T" time)?)?)? |
  "today"                 |
  "yesterday"             |
  "tomorrow"              |
```

As you see, specifying only a year, a year and a month, a date, a date with an
hour, an date with an hour and a minute or a complete year-to-second is
possible as well as specifying an offset ("+0200" for example).


## Expressions

Expressions are calculations of time. There are different _kinds_ of
expressions: Simple adding and subtracting of time amounts,

```
amount_expression     = amount (operator amount_expression)?
exact_date_expression = exact_date (operator amount_expression)?
```

## TimeType

A TimeType is either a date or an amount expression:

```
timetype = exact_date_expression | amount_expression
```

That means that a TimeType either represents a specific DateTime or an amount
of time (like "Two weeks" for example).


## Specifying iterators

An iterator consists of three parts which are explained in the following.


### Until

An iterator may have an "until" specification. This tells the iterator when to
stop the iteration.

```
until_spec = "until" exact_date | number "times"
```

**Warning:** The "exact_date" in this variant must be specified from year to
day. Specifying only the year does _not_ work as expected.
This is a known bug.


### Iter specification

The "iter specification" tells the iterator in what steps to iterate.
Aliases for one of a certain unit exists:

```
iter_spec =
  "secondly" |
  "minutely" |
  "hourly"   |
  "daily"    |
  "weekly"   |
  "monthly"  |
  "yearly"   |
  number unit
```

### Iterator

The iterator itself is rather simple now:

```
iterator = date iter_spec until_spec?
```

If the `until_spec` is not given, the iterator yields new TimeType objects
**until it panics**.