@@ 1,3 1,157 @@
# bearimy
-[ ] add information about the bearimy
+## Purpose
+
+Bearimy is the library for handling dates and times with Janet programming
+language.
+
+## Architecture
+
+The internal storage is the so-called UNIX epoch or the number of seconds
+from 1970-01-01 in the GMT timezone. Another data structure used internally
+is the Janet struct akin to the return structure from the `os/date` core
+function call.
+
+## Types
+
+Functionality added by the library leans heavily on Janet's table prototypes.
+
+### Date
+
+The first core type provides means for representing a date. It has an
+eponymous prototype. For creating this data, the utility function `make-date`
+can convert its argument from `table` or `struct`, which has the structure
+similar to the core Janet's date, `number` with epoch seconds, and from
+`string` representation of ISO 8601 format (YYYY-MM-DD).
+
+The prototype contains five methods for representing Date:
+
+- `format` returns Date representation as a string in ISO 8601 format.
+- `epoch` returns the UNIX epoch seconds.
+- `str-week-day` returns a string with the name of the day in the week. An
+ optional format argument can have two values:
+ - `:short` makes method return default short representation of the weekday
+ name (Sun, Mon, etc.)
+ - `:long` makes the method return a long representation of the weekday name
+ (Sunday, Monday, etc.)
+- `str-month` returns a string with the name of the month. An optional format
+ argument can have two values:
+ - `:short` makes method return default short representation of the month
+ name (Jan, Feb, etc.)
+ - `:long` makes the method return a long representation of the month name
+ (Sunday, Monday, etc.)
+- `local` returns the Date corrected for the current timezone.
+
+### DateTime
+
+The second core type provides means for representing date and time. It
+has an eponymous prototype. For creating this type, the utility function
+`make-date-time` can convert its argument from `table`, `struct`, `number`
+with epoch seconds and from `string` representation based on ISO 8601 format
+(YYYY-MM-DD hh:mm:ss). This prototype inherits from the Date prototype. It
+contains the same methods with the one notable change to `format`, which
+returns a string with the time information and adds one more method,
+`http-format`, which returns the representation suitable for HTTP headers.
+
+### Interval
+
+The third core type provides means for representing and working with the
+time intervals. The eponymous prototype contains only the `:duration` key in
+seconds. For creating this type, the utility function `make-interval` can
+convert its argument from `number` of seconds, set as `:duration` and from
+`table` with the `:duration` key. It also converts the `struct` with the
+`:duration` key or `:start` and `:end` keys or with one or more of `:years`,
+`:months`, `:days`, `:hours`, `:minutes` or `:seconds` keys. These the
+function recomputes to seconds. The last type of argument for the function
+is a string representation in the format "1h 20m", etc.
+
+There are eight methods for this prototype:
+- `format` returns the Interval formatted for the human consumption in the
+ `hh:mm:ss` format.
+- `compare` compares the Interval with another one and returns the integer
+ similarly to Janet's `compare` core function.
+- `add` adds another Interval to this Interval.
+- `sub` substracts another Interval from this Interval.
+- `in-years` returns the Interval as a float number of years.
+- `in-days` returns the Interval as a float number of days.
+- `in-hours` returns the Interval as a float number of hours.
+- `in-minutes` returns the Interval as a float number of minutes.
+
+### Calendar
+
+The fourth core type provides means for working with the DateTime in
+the Calendar manner. Its eponymous prototype inherits from the DateTime
+prototype. The utility function `make-calendar` uses the `make-date-time`
+function internally for creating this type.
+
+The prototype has five more functions on top of all the DateTime provides:
+
+- `sooner` returns the new Calendar with DateTime set to earlier one by the
+ Interval argument.
+- `later` returns the new Calendar with DateTime set to later one by the
+ Interval argument.
+- `compare` compares the Calendar with another one and returns the integer
+ similarly to Janet's `compare` core function.
+- `before?` returns true if the argument Calendar is before this one in time.
+- `after?` returns true if the argument Calendar is after this one in time.
+
+### Period
+
+The last core type provides means for working with a period starting
+with DateTime and lasting for Interval duration. The utility function
+`make-period` takes Calendar and Period arguments and uses `make-calendar`
+and `make-interval` functions internally for converting them.
+
+The prototype has five methods:
+- `later` is similar to Calendar's `later` method but takes the Interval
+ into account.
+- `contains?` returns true if the DateTime argument is within the boundaries
+ of the Period.
+- `after?` is similar to Calendar's `after?` method but takes the Interval
+ into account.
+- `start` returns the epoch seconds of the DateTime part of the Period.
+- `end` returns the epoch seconds of the DateTime plus the Interval duration
+ part of the Period.
+
+## Utility
+
+On top of the core types and their methods are convenience functions for
+working with them. First are formatting functions:
+
+- `format-date`, `format-date-time`, `http-format-date-time`, `format-interval`
+ are simple wrapper around the respective `make-*` functions and call to
+ `format` method of the result.
+- `format-time` formates DateTime time part and returns it in `hh:mm:ss` format.
+- `format-now` takes the current DateTime and returns it formated.
+- `format-today` takes the current Date and returns it formated.
+
+The second group of functions provides convenience for creating the Calendar
+from the number of respective time units in history or future:
+
+- `days-ago` returns a new Calendar based on current DateTime or an optional
+ provided one, moved by argument days to the history.
+- `days-after` returns a new Calendar based on current DateTime or an optional
+ provided one, moved by argument days into the future.
+ - `yesterday` returns a new Calendar of yesterday's DateTime.
+- `weeks-ago` returns a new Calendar based on current DateTime or an optional
+ provided one, moved by argument weeks to the history.
+- `months-ago` returns a new Calendar based on current DateTime or an optional
+ provided one, moved by argument months; to the history.
+- `start-of-week` returns a new Calendar based on current DateTime or an
+ optional provided one, set to the first day of the week.
+- `current-week-start` returns a new Calendar set to the start of the
+ current week.
+ - `last-week-start` returns a new Calendar set to the start of the last week.
+- `start-of-month` returns a new Calendar based on current DateTime or an
+ optional provided one, set number of months in the history.
+- `current-month-start` returns a new Calendar set to the start of the
+ current month.
+ - `last-month-start` returns a new Calendar set to the start of the last month.
+- `start-of-year` returns a new Calendar based on current DateTime or an
+ optional provided one, set number of years in the history.
+- `current-year-start` returns a new Calendar set to the start of the
+ current year.
+
+The last function, `human`, represents the DateTime argument in the
+human-readable format concerning the current DateTime (now, last month,
+and so on).