553 lines
15 KiB
Markdown
553 lines
15 KiB
Markdown
Members Base
|
|
============
|
|
|
|
These modules manage the member files in members directory.
|
|
|
|
Modules
|
|
-------
|
|
|
|
### Base Member Record
|
|
|
|
(import brmember)
|
|
|
|
This module encapsulates the data structure representing a single
|
|
member record.
|
|
|
|
(make-brmember 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.
|
|
|
|
(brmember? v)
|
|
|
|
* ```v``` - any value
|
|
|
|
Returns ```#t``` if given value ```v``` is a brmember instance.
|
|
|
|
(brmember-file-name mr)
|
|
|
|
* ```mr``` - a member record structure
|
|
|
|
Returns the file name of this member's file usually without full path.
|
|
|
|
(brmember-file-path mr)
|
|
|
|
* ```mr``` - a member record structure
|
|
|
|
Returns the path used for accessing this member's file.
|
|
|
|
(brmember-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.
|
|
|
|
(brmember-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.
|
|
|
|
(brmember-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.
|
|
|
|
(brmember-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.
|
|
|
|
(brmember-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.
|
|
|
|
(brmember-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.
|
|
|
|
(brmember-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```.
|
|
|
|
(brmember-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.
|
|
|
|
(brmember-source mr)
|
|
|
|
* ```mr``` - a member record structure
|
|
|
|
Returns a list of strings representing the source file of this member
|
|
record.
|
|
|
|
(brmember-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```.
|
|
|
|
(brmember-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).
|
|
|
|
(brmember-has-highlights? mr)
|
|
|
|
* ```mr``` - a member record structure
|
|
|
|
Returns ```#t``` if given ```mr``` has at least one source highlight.
|
|
|
|
(brmember-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.
|
|
|
|
(brmember-has-problems? mr)
|
|
|
|
* ```mr``` - a member record structure
|
|
|
|
Returns ```#t``` if there are any ```'error``` type highlights in
|
|
```mr```, or it is not ```brmember-usable?``` or the
|
|
```member-id``` is not 4-digit prime number.
|
|
|
|
(brmember-destroyed? mr)
|
|
|
|
* ```mr``` - a member record structure
|
|
|
|
Returns ```#t``` if the member is not existing and already has existed
|
|
in the past.
|
|
|
|
(brmember-suspended? mr)
|
|
|
|
* ```mr``` - a member record structure
|
|
|
|
Returns ```#t``` if the current month falls within any of given member's
|
|
suspended periods.
|
|
|
|
(brmember-active? mr)
|
|
|
|
* ```mr``` - a member record structure
|
|
|
|
Returns ```#t``` if given member exists, is a member and is currently
|
|
not suspended.
|
|
|
|
(brmember-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.
|
|
|
|
(brmember-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.
|
|
|
|
(brmember-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.
|
|
|
|
(brmember-nick mr)
|
|
|
|
* ```mr``` - a member record structure
|
|
|
|
Returns member's nick from its ```'info``` section.
|
|
|
|
(brmember-id mr)
|
|
|
|
* ```mr``` - a member record structure
|
|
|
|
Returns given member's id.
|
|
|
|
(brmember-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```.
|
|
|
|
((brmember-suspended-for at-least [less-than]) mr)
|
|
|
|
* ```at-least``` - number of months
|
|
* ```less-than``` - number of months
|
|
* ```mr``` - member record structure
|
|
|
|
Curried predicate for checking whether given member ```mr``` is at
|
|
least ```at-least``` months suspended. If ```less-than``` is provided
|
|
then only those records which have been suspended less than this value
|
|
are included.
|
|
|
|
(brmember<? 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.
|
|
|
|
(brmember-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.
|
|
|
|
(brmember-credit mr)
|
|
|
|
* ```mr``` - a member record structure
|
|
|
|
Returns the total credit manually recorded in given member
|
|
record. Takes into account ```(*current-month*)``` to allow showing
|
|
current status at given date.
|
|
|
|
(brmember-payments mr)
|
|
|
|
* ```mr``` - a member record structure
|
|
|
|
Returns the payments (bank transactions) list of given member record
|
|
```mr``` defaulting to an empty list.
|
|
|
|
(brmember-mailman mr)
|
|
|
|
* ```mr``` - a member record structure
|
|
|
|
Returns a list of mailman mailing lists this member is member of.
|
|
|
|
(brmember-add-mailman mr ml)
|
|
|
|
* ```mr``` - a member record structure
|
|
* ```ml``` - mailinglist name
|
|
|
|
Adds given mailman mailinglist into the list of given members mailinglists.
|
|
|
|
### Base Member Record Formatter
|
|
|
|
(import brmember-format)
|
|
|
|
Allows format-like formatting of brmember records.
|
|
|
|
(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 Parser
|
|
|
|
This module exports only one function - the ```load-brmember-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-brmember-file mr)
|
|
|
|
* ```mr``` - (almost) empty member record structure
|
|
|
|
It must be possible to get the member file using
|
|
```brmember-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 Base Directory
|
|
|
|
(import mbase-dir)
|
|
|
|
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-mbase-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.
|
|
|
|
(mbase-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
|
|
|
|
(import mbase)
|
|
|
|
This module uses the members directory module to load and parse all
|
|
members files and provides a simple interface for accessing the data.
|
|
|
|
(load-mbase dn [progress?])
|
|
|
|
* ```dn``` - directory with member files
|
|
* ```progress?``` - if ```#t```, displays loading progress
|
|
|
|
Loads all member files and creates a members base data structure.
|
|
|
|
(mbase-members mb)
|
|
|
|
* ```mb``` - members base structure
|
|
|
|
Returns the list of all member records loaded.
|
|
|
|
(find-member-by-predicate 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-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-predicate mb pred)
|
|
|
|
* ```mb``` - members base structure
|
|
* ```pred``` - predicate procedure
|
|
|
|
Returns a list of all member records matching the given predicate.
|
|
|
|
(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-mbase-ids mb)
|
|
|
|
* ```mb``` - members base structure
|
|
|
|
Returns a list of all members' ids.
|
|
|
|
(list-mbase-nicks mb)
|
|
|
|
* ```mb``` - members base structure
|
|
|
|
Returns a list of all member nicks.
|
|
|
|
(mbase-free-ids mb)
|
|
|
|
* ```mb``` - members base structure
|
|
|
|
Returns a list of valid member ids which are not already used in given
|
|
members base.
|
|
|
|
(mbase-gen-id mb)
|
|
|
|
* ```mb``` - members base structure
|
|
|
|
Generates a random 4-digit prime number which is not yet used as a
|
|
member id.
|
|
|
|
(mbase-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?```.
|
|
|
|
(mbase-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.
|
|
|
|
(mbase-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.
|
|
|
|
(mbase-add-unpaired mb tr)
|
|
|
|
* ```mb``` - mbase structure
|
|
* ```tr``` - bank-transaction
|
|
|
|
Adds given transaction ```tr``` into unpaired transactions list of
|
|
```mb``` mbase.
|
|
|
|
(mbase-unpaired mb)
|
|
|
|
* ```mb``` - mbase structure
|
|
|
|
Returns the list of unpaired transactions recorded.
|
|
|
|
(mbase-active-emails mb)
|
|
|
|
* ```mb``` - mbase structure
|
|
|
|
Returns the list of emails of all active members.
|
|
|
|
(mbase-merge-mailman mb ml)
|
|
|
|
* ```mb``` - mbase structure
|
|
* ```ml``` - mailman mailinglist info
|
|
|
|
Based on mailman mailinglist emails - ```(cdr ml)``` at the moment -
|
|
merges the listname - ```(car ml)``` at the moment - into respective
|
|
members of givem ```mb``` structure.
|
|
|
|
The ```ml``` should be output of ```mailman-list-members```.
|