From 098588dd4ad950008d05fafa597778b05d0c3ce2 Mon Sep 17 00:00:00 2001
From: Matthias Beyer <mail@beyermatthias.de>
Date: Thu, 22 Mar 2018 15:33:56 +0100
Subject: Add language documentation

---
 README.md       |   3 +-
 doc/language.md | 180 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 182 insertions(+), 1 deletion(-)
 create mode 100644 doc/language.md

diff --git a/README.md b/README.md
index b8ea209..e4d4bc7 100644
--- a/README.md
+++ b/README.md
@@ -51,7 +51,8 @@ let _ = (TT::today() - TT::years(1))       // exactly one year ago
 kairos ships a user input parser, so you can include kairos in your
 commandline applications.
 
-Have a look at [the example CLI utility](./examples/main.rs).
+Have a look at [the example CLI utility](./examples/main.rs)
+or the [language documentation](./doc/language.md).
 
 # License
 
diff --git a/doc/language.md b/doc/language.md
new file mode 100644
index 0000000..b2b2716
--- /dev/null
+++ b/doc/language.md
@@ -0,0 +1,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**.
+
+
-- 
cgit v1.2.3