Split out calendar documentation.
This commit is contained in:
parent
2cb84d1847
commit
d32c20bb1a
2 changed files with 185 additions and 167 deletions
183
doc/calendar.md
Normal file
183
doc/calendar.md
Normal file
|
|
@ -0,0 +1,183 @@
|
|||
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.
|
||||
|
||||
Modules Documentation
|
||||
---------------------
|
||||
|
||||
All the functions documented below should be used for all manipulation
|
||||
with calendar dates - mostly with month granularity.
|
||||
|
||||
### Month
|
||||
|
||||
Module for handling months algebra to be used in period construction
|
||||
and matching.
|
||||
|
||||
(make-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.
|
||||
|
||||
(month-valid? m)
|
||||
|
||||
* ```m``` - constructed month value
|
||||
|
||||
Checks whether given value is structurally valid month value, the year
|
||||
is between 1000 and 9999 inclusive and the month is between 1 and 12
|
||||
inclusive. Returns boolean value.
|
||||
|
||||
(string->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.
|
||||
|
||||
(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.
|
||||
|
||||
(month=? m n)
|
||||
|
||||
* ```m``` - first valid month value
|
||||
* ```n``` - second valid month value
|
||||
|
||||
Returns ```#t``` if both month values are valid and ```equal?```.
|
||||
|
||||
(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.
|
||||
|
||||
(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?```.
|
||||
|
||||
(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?```.
|
||||
|
||||
(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.
|
||||
|
||||
(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.
|
||||
|
||||
(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
|
||||
|
||||
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.
|
||||
|
||||
(period-since p)
|
||||
|
||||
* ```p``` - valid period
|
||||
|
||||
Returns the ```since``` part of given period.
|
||||
|
||||
(period-before p)
|
||||
|
||||
Returns the ```since``` part of given period.
|
||||
|
||||
Returns the ```before``` part of given period.
|
||||
|
||||
(period-markers->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.
|
||||
|
||||
(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)```.
|
||||
|
||||
(month-in-periods p [m (*current-month*)])
|
||||
|
||||
* ```p``` - a periods
|
||||
* ```m``` - a valid month - defaults to ```(*current-month*)```
|
||||
|
||||
Returns ```#t``` if given month ```m``` lies within the period
|
||||
```p```.
|
||||
|
||||
(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```.
|
||||
|
||||
(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
|
||||
```"____-__"```.
|
||||
|
||||
|
||||
(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```.
|
||||
|
||||
169
doc/modules.md
169
doc/modules.md
|
|
@ -1,5 +1,5 @@
|
|||
BrmBuro Modules
|
||||
===============
|
||||
HackerBase Modules
|
||||
==================
|
||||
|
||||
This file contains documentation of all exported symbols of all
|
||||
modules used. Modules are grouped according to their specificity to
|
||||
|
|
@ -558,171 +558,6 @@ them.
|
|||
Specific Support Modules
|
||||
------------------------
|
||||
|
||||
### Month
|
||||
|
||||
Module for handling months algebra to be used in period construction
|
||||
and matching.
|
||||
|
||||
(make-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.
|
||||
|
||||
(month-valid? m)
|
||||
|
||||
* ```m``` - constructed month value
|
||||
|
||||
Checks whether given value is structurally valid month value, the year
|
||||
is between 1000 and 9999 inclusive and the month is between 1 and 12
|
||||
inclusive. Returns boolean value.
|
||||
|
||||
(string->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.
|
||||
|
||||
(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.
|
||||
|
||||
(month=? m n)
|
||||
|
||||
* ```m``` - first valid month value
|
||||
* ```n``` - second valid month value
|
||||
|
||||
Returns ```#t``` if both month values are valid and ```equal?```.
|
||||
|
||||
(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.
|
||||
|
||||
(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?```.
|
||||
|
||||
(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?```.
|
||||
|
||||
(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.
|
||||
|
||||
(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.
|
||||
|
||||
(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
|
||||
|
||||
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.
|
||||
|
||||
(period-since p)
|
||||
|
||||
* ```p``` - valid period
|
||||
|
||||
Returns the ```since``` part of given period.
|
||||
|
||||
(period-before p)
|
||||
|
||||
Returns the ```since``` part of given period.
|
||||
|
||||
Returns the ```before``` part of given period.
|
||||
|
||||
(period-markers->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.
|
||||
|
||||
(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)```.
|
||||
|
||||
(month-in-periods p [m (*current-month*)])
|
||||
|
||||
* ```p``` - a periods
|
||||
* ```m``` - a valid month - defaults to ```(*current-month*)```
|
||||
|
||||
Returns ```#t``` if given month ```m``` lies within the period
|
||||
```p```.
|
||||
|
||||
(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```.
|
||||
|
||||
(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
|
||||
```"____-__"```.
|
||||
|
||||
|
||||
(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```.
|
||||
|
||||
### Primes
|
||||
|
||||
A very simple module for generating and checking 4-digit prime numbers.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue