430 lines
11 KiB
Markdown
430 lines
11 KiB
Markdown
Calendar Support Modules
|
|
========================
|
|
|
|
This file contains the documentation of calendar handling routines.
|
|
|
|
Rationale
|
|
---------
|
|
|
|
As all the processes within the organization have monthly granularity,
|
|
it is an intentional design decision to have unified approach for
|
|
working with months, month periods and relations between them.
|
|
|
|
For certain operations, daily granularity is required, however
|
|
deterministic conversion from exact date (day) to month is implemented
|
|
with respect to different requirements of period starts and ends.
|
|
|
|
Modules Documentation
|
|
---------------------
|
|
|
|
All the functions documented below should be used for all manipulation
|
|
with calendar dates - mostly with month granularity.
|
|
|
|
### Month
|
|
|
|
(import cal-month)
|
|
|
|
Module for handling months algebra to be used in period construction
|
|
and matching.
|
|
|
|
(make-cal-month y m)
|
|
|
|
* ```y``` - a number representing valid year
|
|
* ```m``` - a number between 1 and 12 inclusive
|
|
|
|
Constructs a new month value with ```y``` number as the year component
|
|
and ```m``` number as the month component.
|
|
|
|
(cal-month? m)
|
|
|
|
* ```m``` - constructed month value
|
|
|
|
Checks whether given value is valid cal-month, the year is between
|
|
1000 and 9999 inclusive and the month is between 1 and 12
|
|
inclusive. Returns boolean value.
|
|
|
|
(cal-month-year m)
|
|
|
|
* ```m``` - a valid cal-month? value
|
|
|
|
Returns the year component from given month value.
|
|
|
|
(cal-month-month m)
|
|
|
|
* ```m``` - a valid cal-month? value
|
|
|
|
Returns the month component from given month value.
|
|
|
|
(string->cal-month s)
|
|
|
|
* ```s``` - a string in "YYYY-MM" format
|
|
|
|
Parses given string ```s``` as month and constructs a month value from
|
|
the YYYY and MM components parsed. The resulting month value is
|
|
returned only if it is valid. Otherwise ```#f``` is returned.
|
|
|
|
(cal-month->string m)
|
|
|
|
* ```m``` - valid month value or ```#f```
|
|
|
|
Converts given month value to a string in ```"YYYY-MM"``` format.
|
|
|
|
If ```#f```, returns a special empty month result ```"____-__"```.
|
|
|
|
Raises an error if ```m``` is not a valid month.
|
|
|
|
(iso-date->cal-month s)
|
|
|
|
* ```s``` - a string in "YYYY-MM-DD" format
|
|
|
|
Parses given ISO date and returns a cal-monh from the year and month
|
|
given.
|
|
|
|
(cal-month=? m n)
|
|
|
|
* ```m``` - first valid month value
|
|
* ```n``` - second valid month value
|
|
|
|
Returns ```#t``` if both month values are valid and ```equal?```.
|
|
|
|
(cal-month<? m n)
|
|
|
|
* ```m``` - first valid month value
|
|
* ```n``` - second valid month value
|
|
|
|
Returns ```#t``` if both month values are valud and ```m``` comes
|
|
before ```n``` in the calendar.
|
|
|
|
(cal-month<=? m n)
|
|
|
|
* ```m``` - first valid month value
|
|
* ```n``` - second valid month value
|
|
|
|
Returns ```#t``` if both month values are valud and ```m``` comes
|
|
before ```n``` in the calendar or they are ```equal?```.
|
|
|
|
(cal-month>=? m n)
|
|
|
|
* ```m``` - first valid month value
|
|
* ```n``` - second valid month value
|
|
|
|
Returns ```#t``` if both month values are valud and ```m``` comes
|
|
after ```n``` in the calendar or they are ```equal?```.
|
|
|
|
(cal-month>? m n)
|
|
|
|
* ```m``` - first valid month value
|
|
* ```n``` - second valid month value
|
|
|
|
Returns ```#t``` if both month values are valud and ```m``` comes
|
|
after ```n``` in the calendar.
|
|
|
|
(cal-month-diff f t)
|
|
|
|
* ```f``` - valid month (from)
|
|
* ```t``` - valid month (to)
|
|
|
|
Returns the difference in months from month ```f``` to month
|
|
```t```. If both months are the same, the result is zero. If ```t```
|
|
is before ```f```, the result is negative.
|
|
|
|
(cal-month-add m [n])
|
|
|
|
* ```m``` - valid month
|
|
* ```n``` - an integer, defaults to 1
|
|
|
|
Returns a new valid month that comes ```n``` months after ```m```. If
|
|
```n``` is negative, it correctly subtracts the months.
|
|
|
|
### Period
|
|
|
|
(import cal-period)
|
|
|
|
This module implements simple calendar period handling with month
|
|
granularity. The period contains fields ```since``` which is the first
|
|
month of the period and ```before``` which is the first month just
|
|
after the period.
|
|
|
|
(*current-month* [month])
|
|
|
|
* ```month``` - valid month structure as specified in the ```cal-month``` module
|
|
|
|
Configuration parameter specifying the current month. Defaults to the
|
|
current month derived from the current system time.
|
|
|
|
(*current-day* [day])
|
|
|
|
* ```day``` - a valid cal-day structure
|
|
|
|
Configuration parameter specifying the current day. Defaults to
|
|
current date.
|
|
|
|
(make-cal-period since before [scomment [bcomment]])
|
|
|
|
* ```since``` - a valid cal-month of the first month of the period
|
|
* ```before``` - a valid cal-month - first after the end of the period
|
|
* ```scomment``` - optional "since" comment
|
|
* ```bcomment``` - optional "before" comment
|
|
|
|
Creates new cal-period structure with mandatory ```since``` and
|
|
```before``` fields and optional ```scomment``` and ```bcomment```
|
|
fields (these default to ```#f```).
|
|
|
|
(cal-period-since p)
|
|
|
|
* ```p``` - valid period
|
|
|
|
Returns the ```since``` part of given period.
|
|
|
|
(cal-period-before p)
|
|
|
|
* ```p``` - valid period
|
|
|
|
Returns the ```before``` part of given period.
|
|
|
|
(cal-period-scomment p)
|
|
|
|
* ```p``` - valid period
|
|
|
|
Returns the comment for the since field.
|
|
|
|
(cal-period-bcomment p)
|
|
|
|
* ```p``` - valid period
|
|
|
|
Returns the comment for the before field.
|
|
|
|
(period-markers->cal-periods l)
|
|
|
|
* ```l``` - list of sorted (list tag month)
|
|
|
|
Converts a list of period markers ```l``` into actual periods where
|
|
each period is represented by ```(list start-month end-month)```.
|
|
|
|
The ```end-month``` may be ```#f``` in which case it is an open-ended
|
|
period which has not ended yet.
|
|
|
|
(cal-periods-duration l)
|
|
|
|
* ```l``` - list of periods
|
|
|
|
Returns the total duration in months of the periods given in the list
|
|
```l```. Each period is represented as ```(list start-month
|
|
end-month)```.
|
|
|
|
(cal-month-in-period? p [m (*current-month*)])
|
|
|
|
* ```p``` - a period structure
|
|
* ```m``` - a valid month or day - defaults to ```(*current-month*)```
|
|
|
|
Returns ```#t``` if given month ```m``` lies within the period
|
|
```p```. The period can be cal-day or cal-month period and is
|
|
converted to appropriate cal-month period before checking. If ```m```
|
|
is a cal-day, it is converted to cal-month before testing.
|
|
|
|
(cal-month-in-periods? ps [m (*current-month*)])
|
|
|
|
* ```ps``` - a list of periods
|
|
* ```m``` - a valid month - defaults to ```(*current-month*)```
|
|
|
|
Returns ```#t``` if given month ```m``` lies within any of the periods
|
|
given in the list of periods ```ps```.
|
|
|
|
(cal-day-in-period? p [d])
|
|
|
|
* ```p``` - a valid cal-period structure
|
|
* ```d``` - a valid cal-day or cal-month
|
|
|
|
Checks whether given day ```d``` (or month, after conversion to the
|
|
first day of given month) belongs to period specified by ```p```. The
|
|
period is converted to cal-day period if it is a cal-month period. The
|
|
tested day ```d``` defaults to ```(*current-day*)```.
|
|
|
|
(cal-day-in-periods? ps [d])
|
|
|
|
* ```ps``` - a list of valid cal-period structures
|
|
* ```d``` - a valid cal-day or cal-month
|
|
|
|
Returns ```#t``` if ```cal-day-in-period?``` returns ```#t``` for at
|
|
least one period in the ```ps``` list.
|
|
|
|
(cal-periods->string ps)
|
|
|
|
* ```ps``` - a list of periods
|
|
|
|
Returns a string representing all the periods given in the list of
|
|
periods ```ps```. The periods are represented as
|
|
````"YYYY-MM..YYYY-MM"``` and an open end is substituded with
|
|
```"____-__"```.
|
|
|
|
|
|
(cal-periods-match ps [m (*current-month*)])
|
|
|
|
* ```ps``` - a list of periods
|
|
|
|
Returns the period from the list of periods ```ps``` the given month
|
|
```m``` falls into. If no period matches, returns ```#f```.
|
|
|
|
(make-cal-period-lookup-table source)
|
|
|
|
* ```source``` a list of specifications
|
|
|
|
Creates a lookup table containing periods where each specification
|
|
starts with a month and the rest of the list is value to be stored in
|
|
the lookup table. The resulting lookup table contains periods with the
|
|
last period being open-ended without ending month.
|
|
|
|
(lookup-by-cal-period table)
|
|
|
|
* ```table``` - period lookup table
|
|
|
|
Looks up the value(s) as specified by the table created by
|
|
```make-period-lookup-table``` for current month from parameter
|
|
```(*current-month*)```.
|
|
|
|
(cal-ensure-month v [stop?])
|
|
|
|
* ```v``` - valid month or day
|
|
* ```stop?``` - if ```#t```, treat as ending month, default ```#f```
|
|
|
|
If ```v``` is a valid month, returns it unchanged. If it is a day,
|
|
uses ```cal-day->month``` for conversion with given ```stop?``` as
|
|
second argument.
|
|
|
|
(cal-ensure-day v)
|
|
|
|
* ```v``` - a valid cal-day or cal-month or ```#f```
|
|
|
|
Returns a valid cal-day structure based on ```v```. If it is a cal-day
|
|
or ```#f```, returns it unchanged. If it is a cal-month, returns a
|
|
valid cal-day of the first day of given month.
|
|
|
|
### Day
|
|
|
|
(import cal-day)
|
|
|
|
This module encapsulates date storage with daily granularity.
|
|
|
|
(make-cal-day y m d)
|
|
|
|
* ```y``` - valid year (1000-9999)
|
|
* ```m``` - valid month number (1-12)
|
|
* ```d``` - valid day number (1-31)
|
|
|
|
Construct a new cal-day structure representing a single calendar day.
|
|
|
|
(cal-day? v)
|
|
|
|
* ```v``` - any value
|
|
|
|
Return ```#t``` if given value is a cal-day structure and it
|
|
represents a valid day, ```#f``` otherwise.
|
|
|
|
(cal-day-year d)
|
|
|
|
* ```d``` - valid cal-day structure
|
|
|
|
Returns the year field of the structure.
|
|
|
|
(cal-day-month d)
|
|
|
|
* ```d``` - valid cal-day structure
|
|
|
|
Returns the month field of the structure.
|
|
|
|
(cal-day-day d)
|
|
|
|
* ```d``` - valid cal-day structure
|
|
|
|
Returns the day field of the structure.
|
|
|
|
(cal-day->month d [stop?])
|
|
|
|
* ```d``` - a valid cal-day structure
|
|
* ```stop?``` - if ```#t```, conversion for period end
|
|
|
|
Converts given cal-day to cal-month. If ```stop?``` is ```#f```, it
|
|
just strips the day number. Otherwise it converts the day to the same
|
|
month only if it is the first day of the month. It converts to the
|
|
next calendar month otherwise.
|
|
|
|
(cal-day->string d)
|
|
|
|
* ```d``` - a valid cal-day structure
|
|
|
|
Converts given day into "YYYY-MM-DD" ISO string representation.
|
|
|
|
(string->cal-day s)
|
|
|
|
* ```s``` - a string containing "YYYY-MM-DD" ISO date
|
|
|
|
Parses the string and returns a valid cal-day structure.
|
|
|
|
(parse-cal-day/month s)
|
|
|
|
* ```s``` - a string with ISO date with optional day part
|
|
|
|
Tries parsing the string as cal-day and returns the result upon
|
|
success. Upon failure, parses the string as cal-month.
|
|
|
|
(cal-day=? a b)
|
|
|
|
* ```a``` - a cal-day value
|
|
* ```b``` - a cal-day value
|
|
|
|
Returns ```#t``` if ```a``` respresents the same date as ```b``` in
|
|
calendar.
|
|
|
|
(cal-day<? a b)
|
|
|
|
* ```a``` - a cal-day value
|
|
* ```b``` - a cal-day value
|
|
|
|
Returns ```#t``` if ```a``` comes before ```b``` in calendar.
|
|
|
|
(cal-day<=? a b)
|
|
|
|
* ```a``` - a cal-day value
|
|
* ```b``` - a cal-day value
|
|
|
|
Returns ```#t``` if ```a``` comes before or is the same date as
|
|
```b``` in calendar.
|
|
|
|
(cal-day>=? a b)
|
|
|
|
* ```a``` - a cal-day value
|
|
* ```b``` - a cal-day value
|
|
|
|
Returns ```#t``` if ```a``` comes after or is the same date as ```b```
|
|
in calendar.
|
|
|
|
(cal-day>? a b)
|
|
|
|
Returns ```#t``` if ```a``` comes after ```b``` in calendar.
|
|
|
|
(cal-day/month<? a b)
|
|
|
|
* ```a``` - a cal-day or cal-month value
|
|
* ```b``` - a cal-day or cal-month value
|
|
|
|
Returns ```#t``` if ```a``` and ```b``` are of the same type and
|
|
```a``` comes before ```b``` in calendar. Raises error if the values
|
|
are not of the same type.
|
|
|
|
(cal-day/month->string v)
|
|
|
|
* ```v``` - a cal-day or cal-month value
|
|
|
|
Returns appropriate string representation of given value.
|
|
|
|
### Format
|
|
|
|
(import cal-format)
|
|
|
|
A module for formatting various calendar structures.
|
|
|
|
(cal-format v)
|
|
|
|
* ```v``` - a valid cal-day or cal-month
|
|
|
|
Returns the textual ISO representation of given day or month.
|