Initial documentation cleanup with focus on utils.

doc/members.md

@@ -0,0 +1,119 @@
+Members Base
+============
+
+This file documents the internal structure of the members information
+storage.
+
+Members Directory
+-----------------
+
+Files in this directory with file names being four decimal digits are
+member files. The file name is the member id.
+
+Symlinks to the member files serve as human-readable aliases.
+
+The implementation handles situation when the human-readable name is
+the member file and the symlink is the four-digit member id.
+
+Member File Parsing - Passes 0 and 1
+------------------------------------
+
+Member files are read line-by-line.
+
+### Pass 0
+
+Comments start with the ```#``` character and continue until the end
+of particular line.
+
+Comments are stripped from each line before parsing. The same applies
+to leading and trailing whitespace after stripping comments.
+
+### Pass 1
+
+Lines are processed as they are returned from pass 0.
+
+Empty lines are skipped.
+
+Lines without any whitespace are interned as symbols and error is
+recorded as there is only the key and no value associated with it.
+
+Each key/value pair must begin with key token composed of
+non-whitespace characters before the first whitespace. This token is
+interned as symbol upon parsing the line. The remainder of the line is
+stripped of leading whitespace and stored as a string representing the
+value for the key.
+
+The result of parsing is a list of parsed records containing key,
+value and line number for further processing.
+
+Member File Processing - Pass 2
+-------------------------------
+
+Processed source is scanned for known keys. Known keys are:
+
+* nick
+* name
+* mail
+* phone
+* born
+* joined
+* destroyed
+
+Multiple instances of single key are considered an error.
+
+Unknown keys are considered a warning.
+
+Valid multikeys are converted to single key with list of values and
+line numbers as the value for such key. Multikeys are:
+
+* card
+* desfire
+* credit
+* studentstart
+* studentstop
+* suspendstart
+* suspendstop
+
+The result is a valid dictionary of keys and multikeys.
+
+Member File Interpreter - Passes 3+
+-----------------------------------
+
+After getting a valid dictionary from the 2nd pass, the data gets interpreted.
+
+### Pass Markers
+
+All start/stop (student and suspend at the moment) markers are joined
+into lists of markers, retaining source position information.
+
+### Info
+
+The student and suspend lists of markers are converted into a lists of
+periods.
+
+The joined key is converted into a month value.
+
+Card and desfire lists are parsed to get lists of card id and optional
+comment.
+
+Credit list is parsed to get a list of amounts and optional comments.
+
+Member Record Finalization
+--------------------------
+
+If there is no ```'joined``` key, default month is substituted.
+
+If any of Mandatory keys is missing, it is filled with
+```#f```. Mandatory keys are:
+
+* nick
+* name
+* mail
+* phone
+
+
+Member File Schema
+------------------
+
+nick - single word - alphabetical characters, underscore, dash, numbers
+