578 lines
16 KiB
Markdown
578 lines
16 KiB
Markdown
HackerBase Modules
|
|
==================
|
|
|
|
This file contains documentation of all exported symbols of all
|
|
modules used. Modules are grouped according to their specificity to
|
|
this project.
|
|
|
|
Functional Modules
|
|
------------------
|
|
|
|
These modules are specific to this project and their generic usage is
|
|
questionable.
|
|
|
|
### Configuration
|
|
|
|
(import configuration)
|
|
|
|
The exact behavior of some algorithms in other modules can be changed
|
|
via configuration parameters in this global configuration module.
|
|
|
|
This module also handles configuration file loading.
|
|
|
|
(*etc-hackerbase* path)
|
|
|
|
* ```path``` - path to file with configuration
|
|
|
|
Used by ```load-configuration!``` to load the system-specific default
|
|
configuration values.
|
|
|
|
*members-directory*
|
|
|
|
*apikeys-file*
|
|
|
|
*jendasap-checked*
|
|
|
|
*bank-dir*
|
|
|
|
*email-from*
|
|
|
|
(load-configuration!)
|
|
|
|
Loads configuration from ```(*etc-hackerbase*)``` file.
|
|
|
|
### 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?```.
|
|
|
|
### Bank Account
|
|
|
|
This module creates a thin abstraction layer for bank accounts and
|
|
transactions.
|
|
|
|
(make-bank-account number bank [transactions])
|
|
|
|
* ```number``` - account number
|
|
* ```bank``` - bank code
|
|
* ```transactions``` - optional list of initial transactions
|
|
|
|
Creates a new bank account data structure.
|
|
|
|
The data structure has the following accessors:
|
|
|
|
* ```(bank-account-transactions ba)``` - returns the transactions list
|
|
* ```(bank-account-number ba)```- retrieves the bank account number
|
|
* ```(bank-account-bank ba)``` - returns the bank account bank code
|
|
|
|
The underlying implementation is currently a plain list but is subject
|
|
to change in the future.
|
|
|
|
(bank-account-insert account transaction)
|
|
|
|
* ```account``` - bank account structure
|
|
* ```transaction``` - transaction structure to add
|
|
|
|
Adds (prepends) given ```transaction``` to the list of transactions of
|
|
given bank ```account```.
|
|
|
|
(make-bank-transaction i d a c v m t)
|
|
|
|
* ```i``` - transaction id
|
|
* ```d``` - date
|
|
* ```a``` - amount
|
|
* ```c``` - currency
|
|
* ```v``` - variable symbol
|
|
* ```m``` - message
|
|
* ```t``` - transaction type
|
|
|
|
Creates new bank transaction data structure. The underlying
|
|
implementation is currently a record.
|
|
|
|
The following accessors are provided:
|
|
|
|
* ```bank-transaction-id```
|
|
* ```bank-transaction-date```
|
|
* ```bank-transaction-amount```
|
|
* ```bank-transaction-currency```
|
|
* ```bank-transaction-varsym```
|
|
* ```bank-transaction-message```
|
|
* ```bank-transaction-type```
|
|
|
|
More fields with accessors will be added as other modules will need
|
|
them.
|
|
|
|
### Bank Fio
|
|
|
|
### Members Payments Processor
|
|
|
|
### Members Info Printer
|
|
|
|
### Cards
|
|
|
|
### Web Static
|
|
|
|
Specific Support Modules
|
|
------------------------
|
|
|
|
### Primes
|
|
|
|
A very simple module for generating and checking 4-digit prime numbers.
|
|
|
|
(is-4digit-prime? n)
|
|
|
|
* ```n``` - a number
|
|
|
|
Returns true if the given number ```n``` has four digits and it is a
|
|
prime number.
|
|
|
|
(gen-all-4digit-primes)
|
|
|
|
Returns a list of all 4-digit prime numbers.
|