Split out calendar documentation.

doc/calendar.md

@@ -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```.
+