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
|
This file contains documentation of all exported symbols of all
|
||||||
modules used. Modules are grouped according to their specificity to
|
modules used. Modules are grouped according to their specificity to
|
||||||
|
|
@ -558,171 +558,6 @@ them.
|
||||||
Specific Support Modules
|
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
|
### Primes
|
||||||
|
|
||||||
A very simple module for generating and checking 4-digit prime numbers.
|
A very simple module for generating and checking 4-digit prime numbers.
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue