~pepe/bearimy

Date time calculations and transformation for Janet
5de04a90 — Josef Pospíšil 1 year, 9 months ago
Start with the docs improvement in utils
bbe7b418 — Josef Pospíšil 1 year, 9 months ago
Ensure right docs in core
2ea60c04 — Josef Pospíšil 2 years ago
Fix typo

refs

master
browse  log 

clone

read-only
https://git.sr.ht/~pepe/bearimy
read/write
git@git.sr.ht:~pepe/bearimy

You can also use your local clone with git send-email.

#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).