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 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 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/monthstring 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.