diff --git a/doc/calendar.md b/doc/calendar.md new file mode 100644 index 0000000..beec2b5 --- /dev/null +++ b/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 +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```. + diff --git a/doc/modules.md b/doc/modules.md index 7f2f172..78a4dab 100644 --- a/doc/modules.md +++ b/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 -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.