Split mbase documentation.
This commit is contained in:
parent
a170918fbf
commit
3007ab8528
2 changed files with 459 additions and 451 deletions
459
doc/mbase.md
Normal file
459
doc/mbase.md
Normal file
|
|
@ -0,0 +1,459 @@
|
|||
Members Base
|
||||
============
|
||||
|
||||
These modules manage the member files in members directory.
|
||||
|
||||
Modules
|
||||
-------
|
||||
|
||||
### Member Record
|
||||
|
||||
This module encapsulates the data structure representing a single
|
||||
member record.
|
||||
|
||||
(make-member-record file-name file-path symlinks . args)
|
||||
|
||||
* ```file-name``` - a symbol representing the primary filename
|
||||
* ```file-path``` - a string representing the path to the file
|
||||
* ```symlinks``` - a list of symbols representing symlinks
|
||||
* ```args``` - optional keyword arguments
|
||||
|
||||
Creates a new member record dictionary. The three mandatory arguments
|
||||
are stored under respective keys and any keyword arguments are stored
|
||||
as keys obtained by converting the keyword to symbol with values
|
||||
following the keyword.
|
||||
|
||||
The ```'id``` key is filled with any four-digit file-name or symlink
|
||||
converted to a number. Preferably the four-digit symbol should be the
|
||||
file-name but it is not required.
|
||||
|
||||
(member-file-path mr)
|
||||
* ```mr``` - a member record structure
|
||||
|
||||
Returns the path used for accessing this member's file.
|
||||
|
||||
(member-record-input-file mr)
|
||||
|
||||
* ```mr``` - a member record structure
|
||||
|
||||
Returns an open file port to given member record underlying file. This
|
||||
function should be used by the parser to get the member file contents.
|
||||
|
||||
(member-record-set mr . args)
|
||||
|
||||
* ```mr``` - a member record structure
|
||||
* ```args``` - optional keyword arguments
|
||||
|
||||
Any keyword arguments are stored in the member record dictionary as
|
||||
keys obtained by converting the keyword to symbol with values
|
||||
following the keyword.
|
||||
|
||||
(member-record-add-highlight mr line message pass type)
|
||||
|
||||
* ```mr``` - a member record structure
|
||||
* ```line``` - line number in the source file
|
||||
* ```message``` - a string with message for highlight
|
||||
* ```pass``` - parsing stage
|
||||
* ```type``` - symbol representing the highlight type
|
||||
|
||||
Adds a new highlight to member record to be used when displaying the
|
||||
source file listing.
|
||||
|
||||
Known types are:
|
||||
|
||||
* ```'error``` - to denote fatal problem in the source
|
||||
* ```'warning``` - to signal known problem which does not make the record invalid
|
||||
* ```'info``` - supplemental information
|
||||
|
||||
The structure is perfectly suited for ```print-source-listing``` function.
|
||||
|
||||
(member-record-sub-ref mr sec key [default])
|
||||
|
||||
* ```mr``` - a member record structure
|
||||
* ```sec``` - section symbol
|
||||
* ```key``` - key symbol
|
||||
* ```default``` - optional default value
|
||||
|
||||
Retrieves given ```key``` from dictionary stored as section ```sec```
|
||||
in given ```mr``` structure. If no ```default``` is provided and the
|
||||
```key``` does not exist it raises an exception.
|
||||
|
||||
(member-record-sub-set mr sec key value)
|
||||
|
||||
* ```mr``` - a member record structure
|
||||
* ```sec``` - section symbol
|
||||
* ```key``` - key symbol
|
||||
* ```value``` - value to set
|
||||
|
||||
Sets the value of given ```key``` in dictionary stored as section
|
||||
```sec``` in given ```mr``` structure to the new ```value``` possibly
|
||||
overwriting previous one.
|
||||
|
||||
(member-record-sub-prepend mr sec key value)
|
||||
|
||||
* ```mr``` - a member record structure
|
||||
* ```sec``` - section symbol
|
||||
* ```key``` - key symbol
|
||||
* ```value``` - value to prepend (cons) to the key current value
|
||||
|
||||
Prepends (cons) new the ```value``` to current value of given ```key``` in
|
||||
dictionary stored as section ```sec``` in given ```mr``` structure
|
||||
replacing the original value.
|
||||
|
||||
(member-record-sub-has-key? mr sec key)
|
||||
|
||||
* ```mr``` - a member record structure
|
||||
* ```sec``` - section symbol
|
||||
* ```key``` - key symbol
|
||||
|
||||
Returns ```#t``` if given section ```sec``` contains the ```key```.
|
||||
|
||||
(member-record-sub-ensure mr sec key value)
|
||||
|
||||
* ```mr``` - a member record structure
|
||||
* ```sec``` - section symbol
|
||||
* ```key``` - key symbol
|
||||
* ```value``` - value to set
|
||||
|
||||
Sets the value of given ```key``` in dictionary stored as section
|
||||
```sec``` in given ```mr``` structure to the new ```value``` if and
|
||||
only if it is not already present.
|
||||
|
||||
(member-source mr)
|
||||
|
||||
* ```mr``` - a member record structure
|
||||
|
||||
Returns a list of strings representing the source file of this member
|
||||
record.
|
||||
|
||||
(member-record-info mr key [default])
|
||||
|
||||
* ```mr``` - a member record structure
|
||||
* ```key``` - key (symbol) to retrieve
|
||||
* ```default``` - optional default value
|
||||
|
||||
Like ```dict-ref``` returns the value associated with ```key``` in
|
||||
section ```'info```. If ```default``` is provided, it is passed on to
|
||||
the underlying ```dict-ref```.
|
||||
|
||||
(member-missing-keys mr)
|
||||
|
||||
* ```mr``` - a member record structure
|
||||
|
||||
Returns a list of keys (symbols) from within the ```'info``` section
|
||||
of given ```mr``` that have ```#f``` values (indicating they are
|
||||
missing mandatory fields in the source).
|
||||
|
||||
(member-has-highlights? mr)
|
||||
|
||||
* ```mr``` - a member record structure
|
||||
|
||||
Returns ```#t``` if given ```mr``` has at least one source highlight.
|
||||
|
||||
(member-record-usable? mr)
|
||||
|
||||
* ```mr``` - a member record structure
|
||||
|
||||
Returns ```#t``` if it is possible to work with this member - mainly
|
||||
that the ```'info``` section contains the ```'member``` key.
|
||||
|
||||
(member-has-problems? mr)
|
||||
|
||||
* ```mr``` - a member record structure
|
||||
|
||||
Returns ```#t``` if there are any ```'error``` type highlights in
|
||||
```mr```, or it is not ```member-record-usable?``` or the
|
||||
```member-id``` is not 4-digit prime number.
|
||||
|
||||
(member-destroyed? mr)
|
||||
|
||||
* ```mr``` - a member record structure
|
||||
|
||||
Returns ```#t``` if the member is not existing and already has existed
|
||||
in the past.
|
||||
|
||||
(member-suspended? mr)
|
||||
|
||||
* ```mr``` - a member record structure
|
||||
|
||||
Returns ```#t``` if the current month falls within any of given member's
|
||||
suspended periods.
|
||||
|
||||
(member-active? mr)
|
||||
|
||||
* ```mr``` - a member record structure
|
||||
|
||||
Returns ```#t``` if given member exists, is a member and is currently
|
||||
not suspended.
|
||||
|
||||
(member-student? mr)
|
||||
|
||||
* ```mr``` - a member record structure
|
||||
|
||||
Returns ```#t``` if given member exists, is a member, is currently not
|
||||
suspended and current month falls within any member's suspended
|
||||
periods.
|
||||
|
||||
(member-existing? mr)
|
||||
|
||||
* ```mr``` - a member record structure
|
||||
|
||||
Returns ```#t``` if given member exists - that is the current month is
|
||||
within any of the member (membership) periods.
|
||||
|
||||
(member-flags mr)
|
||||
|
||||
* ```mr``` - a member record structure
|
||||
|
||||
Returns a list of member flags which can be any of the following:
|
||||
|
||||
* ```'student```
|
||||
* ```'suspended```
|
||||
* ```'active```
|
||||
* ```'destroyed```
|
||||
* ```'existing```
|
||||
|
||||
The ```'existing``` and ```'destroyed``` are mutually exclusive. Also
|
||||
```'active``` and ```'suspended``` are mutually exclusive.
|
||||
|
||||
(member-nick mr)
|
||||
|
||||
* ```mr``` - a member record structure
|
||||
|
||||
Returns member's nick from its ```'info``` section.
|
||||
|
||||
(member-id mr)
|
||||
|
||||
* ```mr``` - a member record structure
|
||||
|
||||
Returns given member's id.
|
||||
|
||||
(member-suspended-months mr)
|
||||
|
||||
* ```mr``` - a member record structure
|
||||
|
||||
Returns the number of months this member is suspended in
|
||||
```(*current-month*)```. If the member is not suspended, returns
|
||||
```0```.
|
||||
|
||||
(member-format fmt mr)
|
||||
|
||||
* ```fmt``` - format string
|
||||
* ```mr``` - a member record structure
|
||||
|
||||
Fills the following template substitutions in the ```fmt``` string:
|
||||
|
||||
* ```~N``` - member's nick
|
||||
* ```~I``` - member's id
|
||||
* ```~S``` - number of months this member has been suspended
|
||||
* ```~E``` - number of highlights in square brackets if there is at least one
|
||||
* ```~~``` - literal ```~```
|
||||
|
||||
Other parts of the string are retained.
|
||||
|
||||
(member<? a b)
|
||||
|
||||
* ```a``` - a member record structure
|
||||
* ```b``` - a member record structure
|
||||
|
||||
Returns true if member ```a```'s nick comes before ```b```'s nick in
|
||||
the lexicographical order.
|
||||
|
||||
(member-record-add-payment mr pt)
|
||||
|
||||
* ```mr``` - a member record structure
|
||||
* ```pt``` - bank transaction of the payment
|
||||
|
||||
Adds (prepends) given transaction ```pt``` to given member record
|
||||
```mr```'s ```'payments'``` key list.
|
||||
|
||||
(member-payments mr)
|
||||
|
||||
* ```mr``` - a member record structure
|
||||
|
||||
Returns the payments (bank transactions) list of given member record
|
||||
```mr``` defaulting to an empty list.
|
||||
|
||||
### Member Parser
|
||||
|
||||
This module exports only one function - the ```load-member-file```
|
||||
which loads and parses given file as member file. The specification of
|
||||
this file format is in a separate document ```MEMBERS.md```.
|
||||
|
||||
The module implements this specification as multi-pass parser with
|
||||
important definitions being at the top of the module.
|
||||
|
||||
mandatory-keys
|
||||
|
||||
A list of symbols containing keys which must be present in the
|
||||
file. If any of them is missing, it is added to the resulting
|
||||
structure with the ```#f``` value.
|
||||
|
||||
optional-keys
|
||||
|
||||
A list of symbols of keys which the parser recognizes and adds them to
|
||||
the resulting data structure.
|
||||
|
||||
ignored-keys
|
||||
|
||||
A list of symbols with keys that are parsed, and albeit not added to
|
||||
the result they do not generate warnings.
|
||||
|
||||
known-multikeys
|
||||
|
||||
A list of keys that can appear multiple times and in the 2nd pass they
|
||||
are collected as lists of values.
|
||||
|
||||
start-stop-markers-lookup
|
||||
|
||||
A list of start/stop specifications - each key is paired with given
|
||||
key and start/stop tag.
|
||||
|
||||
(load-member-file mr)
|
||||
|
||||
* ```mr``` - (almost) empty member record structure
|
||||
|
||||
It must be possible to get the member file using
|
||||
```member-record-input-file``` function. Loads the file as a list of
|
||||
lines, processes these lines with 1st and 2nd pass parsers, interprets
|
||||
the result using 3rd passes and finalizes the result in the 4th pass.
|
||||
|
||||
### Members Directory
|
||||
|
||||
This module encapsulates the members base directory format as
|
||||
documented in ```MEMBERS.md``` document.
|
||||
|
||||
Each member file should have a 4-digit name identical to member id and
|
||||
optional symlinks with human-known names of the members. The module
|
||||
can correctly handle a situation where the 4-digit id is a symlink to
|
||||
arbitrarily named file.
|
||||
|
||||
In first pass it extracts all files and symlinks to them, binds them
|
||||
together and makes sure the 4-digit name is used as id and the regular
|
||||
file is read when loading its contents.
|
||||
|
||||
(load-members-dir dn)
|
||||
|
||||
* ```dn``` - directory name (path)
|
||||
|
||||
Scans given directory and returns a dictionary of canonical names as
|
||||
keys and lists of alias symlinks as values.
|
||||
|
||||
(members-dir-load-member mdir fname symlinks)
|
||||
|
||||
* ```mdir``` - members directory name (path)
|
||||
* ```fname``` - file name inside ```mdir``` (without path)
|
||||
* ```symlinks``` - a list of symlinks to ```fname```
|
||||
|
||||
Creates an initial member record and uses ```load-member-file``` to
|
||||
load, parse and interpret its contents.
|
||||
|
||||
### Members Base
|
||||
|
||||
This module uses the members directory module to load and parse all
|
||||
members files and provides a simple interface for accessing the data.
|
||||
|
||||
(load-members dn [progress?])
|
||||
|
||||
* ```dn``` - directory with member files
|
||||
* ```progress?``` - if ```#t```, displays loading progress
|
||||
|
||||
Loads all member files and creates a members base data structure.
|
||||
|
||||
(members-base-members mb)
|
||||
|
||||
* ```mb``` - members base structure
|
||||
|
||||
Returns the list of all member records loaded.
|
||||
|
||||
(find-member-by-id mb id)
|
||||
|
||||
* ```mb``` - members base structure
|
||||
* ```id``` - member identifier (4-digit prime number)
|
||||
|
||||
Returns the member record associated with the provided ```id```.
|
||||
|
||||
(find-member-by-nick mb nick)
|
||||
|
||||
* ```mb``` - members base structure
|
||||
* ```nick``` - member nick
|
||||
|
||||
Returns the member record identified by its ```nick```.
|
||||
|
||||
(find-members-by-nick mb nick)
|
||||
|
||||
* ```mb``` - members base structure
|
||||
* ```nick``` - member nick
|
||||
|
||||
Returns the list of all member records with substring matching of
|
||||
```nick```. May return empty list, list with one member or multiple
|
||||
member records.
|
||||
|
||||
(list-members-ids mb)
|
||||
|
||||
* ```mb``` - members base structure
|
||||
|
||||
Returns a list of all members' ids.
|
||||
|
||||
(filter-members-by-predicate mb pred)
|
||||
|
||||
* ```mb``` - members base structure
|
||||
* ```pred``` - predicate procedure
|
||||
|
||||
Returns a list of all member records matching the given predicate.
|
||||
|
||||
(list-members-nicks mb)
|
||||
|
||||
* ```mb``` - members base structure
|
||||
|
||||
Returns a list of all member nicks.
|
||||
|
||||
(members-base-info mb)
|
||||
|
||||
* ```mb``` - members base structure
|
||||
|
||||
Returns a dictionary with basic information about given members
|
||||
base. The dictionary contains the following keys:
|
||||
|
||||
* ```'invalid``` - a list of all invalid member records
|
||||
* ```'active``` - a list of all active member records
|
||||
* ```'suspended``` - a list of all suspended member records
|
||||
* ```'students``` - a list of all student member records
|
||||
* ```'destroyed``` - a list of all destroyed member records
|
||||
* ```'month``` - the current month for this info dictionary
|
||||
* ```'total``` - a list of all member records contained
|
||||
|
||||
This procedure is used for further printing of information about given
|
||||
members base.
|
||||
|
||||
(members-base-stats mb)
|
||||
|
||||
* ```mb``` - members base structure
|
||||
|
||||
Creates a list of lists of statistical information about given members
|
||||
base through time. The first row of the resulting list contains column
|
||||
headers and the rows are sorted chronologically by month.
|
||||
|
||||
(get-free-members-ids mb)
|
||||
|
||||
* ```mb``` - members base structure
|
||||
|
||||
Returns a list of valid member ids which are not already used in given
|
||||
members base.
|
||||
|
||||
(gen-member-id mb)
|
||||
|
||||
|
||||
* ```mb``` - members base structure
|
||||
|
||||
Generates a random 4-digit prime number which is not yet used as a
|
||||
member id.
|
||||
|
||||
(members-base-update mb pred? proc)
|
||||
|
||||
* ```mb``` - members base structure
|
||||
* ```pred?``` - member record predicate
|
||||
* ```proc``` - processing procedure
|
||||
|
||||
Updates given members base by applying ```proc``` to all member
|
||||
records matching ```pred?```.
|
||||
Loading…
Add table
Add a link
Reference in a new issue