brmlab/hackerbase
9
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Update brmember and brmember-format documentation.

Browse source
This commit is contained in:
Dominik Pantůček 2023-04-23 16:35:31 +02:00
parent 3007ab8528
commit 9123573267
1 changed files with 85 additions and 51 deletions
Download patch file Download diff file Expand all files Collapse all files

136
doc/mbase.md
View file

@ -6,12 +6,14 @@ These modules manage the member files in members directory.
Modules
-------
### Member Record
### Base Member Record
(import brmember)
This module encapsulates the data structure representing a single
member record.
(make-member-record file-name file-path symlinks . args)
(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
@ -27,19 +29,32 @@ 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)
(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.
(member-record-input-file mr)
(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.
(member-record-set mr . args)
(brmember-set mr . args)
* ```mr``` - a member record structure
* ```args``` - optional keyword arguments
@ -48,7 +63,7 @@ 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)
(brmember-add-highlight mr line message pass type)
* ```mr``` - a member record structure
* ```line``` - line number in the source file
@ -67,7 +82,7 @@ Known types are:
The structure is perfectly suited for ```print-source-listing``` function.
(member-record-sub-ref mr sec key [default])
(brmember-sub-ref mr sec key [default])
* ```mr``` - a member record structure
* ```sec``` - section symbol
@ -78,7 +93,7 @@ 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)
(brmember-sub-set mr sec key value)
* ```mr``` - a member record structure
* ```sec``` - section symbol
@ -89,7 +104,7 @@ 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)
(brmember-sub-prepend mr sec key value)
* ```mr``` - a member record structure
* ```sec``` - section symbol
@ -100,7 +115,7 @@ 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)
(brmember-sub-has-key? mr sec key)
* ```mr``` - a member record structure
* ```sec``` - section symbol
@ -108,7 +123,7 @@ replacing the original value.
Returns ```#t``` if given section ```sec``` contains the ```key```.
(member-record-sub-ensure mr sec key value)
(brmember-sub-ensure mr sec key value)
* ```mr``` - a member record structure
* ```sec``` - section symbol
@ -119,14 +134,14 @@ 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)
(brmember-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])
(brmember-info mr key [default])
* ```mr``` - a member record structure
* ```key``` - key (symbol) to retrieve
@ -136,7 +151,7 @@ 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)
(brmember-missing-keys mr)
* ```mr``` - a member record structure
@ -144,49 +159,49 @@ 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)
(brmember-has-highlights? mr)
* ```mr``` - a member record structure
Returns ```#t``` if given ```mr``` has at least one source highlight.
(member-record-usable? mr)
(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.
(member-has-problems? mr)
(brmember-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
```mr```, or it is not ```brmember-usable?``` or the
```member-id``` is not 4-digit prime number.
(member-destroyed? mr)
(brmember-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)
(brmember-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)
(brmember-active? mr)
* ```mr``` - a member record structure
Returns ```#t``` if given member exists, is a member and is currently
not suspended.
(member-student? mr)
(brmember-student? mr)
* ```mr``` - a member record structure
@ -194,14 +209,14 @@ 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)
(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.
(member-flags mr)
(brmember-flags mr)
* ```mr``` - a member record structure
@ -216,19 +231,19 @@ Returns a list of member flags which can be any of the following:
The ```'existing``` and ```'destroyed``` are mutually exclusive. Also
```'active``` and ```'suspended``` are mutually exclusive.
(member-nick mr)
(brmember-nick mr)
* ```mr``` - a member record structure
Returns member's nick from its ```'info``` section.
(member-id mr)
(brmember-id mr)
* ```mr``` - a member record structure
Returns given member's id.
(member-suspended-months mr)
(brmember-suspended-months mr)
* ```mr``` - a member record structure
@ -236,6 +251,48 @@ Returns the number of months this member is suspended in
```(*current-month*)```. If the member is not suspended, returns
```0```.
(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-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
@ -251,29 +308,6 @@ Fills the following template substitutions in the ```fmt``` string:
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```
@ -314,7 +348,7 @@ key and start/stop tag.
* ```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
```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.