~pepe/bearimy

e199d223b16783ca339bade271875a6805e33db5 — Josef Pospíšil 3 months ago 9698960
Add proper readme documentation
1 files changed, 155 insertions(+), 1 deletions(-)

M README.md
M README.md => README.md +155 -1
@@ 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).