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-chair? mr)

* ```mr``` - a member record structure

Returns ```#t``` if given ```mr``` is chair as of
```(*current-day*)```.

    (brmember-council? mr)

* ```mr``` - a member record structure

Returns ```#t``` if given ```mr``` is a member of council as of
```(*current-day*)```.

    (brmember-revision? mr)

* ```mr``` - a member record structure

Returns ```#t``` if given ```mr``` is a member of revision committee
as of ```(*current-day*)```.

    (brmember-grant? mr)

* ```mr``` - a member record structure

Returns ```#t``` if given ```mr``` is a member of grant committee as
of ```(*current-day*)```.

    (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```
* ```'chair```
* ```'council```
* ```'revision```
* ```'grant```

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