hackerbase/doc/mbase.md

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.