From 31b749388078d58ba283b841aff40498f6e5f088 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dominik=20Pant=C5=AF=C4=8Dek?= Date: Fri, 26 May 2023 18:25:42 +0200 Subject: [PATCH] Basic member file documentation. --- doc/formats.md | 16 ++++-- doc/hackerbase.1 | 134 +++++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 135 insertions(+), 15 deletions(-) diff --git a/doc/formats.md b/doc/formats.md index 892c5c0..5064072 100644 --- a/doc/formats.md +++ b/doc/formats.md @@ -58,8 +58,6 @@ Processed source is scanned for known keys. Known keys are: * mail * phone * born -* joined -* destroyed Multiple instances of single key are considered an error. @@ -68,6 +66,8 @@ 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: +* joined +* destroyed * card * desfire * credit @@ -75,6 +75,14 @@ line numbers as the value for such key. Multikeys are: * studentstop * suspendstart * suspendstop +* chairstart +* chairstop +* councilstart +* councilstop +* revisionstart +* revisionstop +* grantstart +* grantstop The result is a valid dictionary of keys and multikeys. @@ -85,8 +93,8 @@ 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. +All start/stop markers are joined into lists of markers, retaining +source position information. ### Info diff --git a/doc/hackerbase.1 b/doc/hackerbase.1 index c967eb3..b6fae77 100644 --- a/doc/hackerbase.1 +++ b/doc/hackerbase.1 @@ -260,6 +260,124 @@ transaction file. .SS Member Files +Before parsing the configuration file all comments are removed. The +comments start with the \fB#\fR character and continue until the end +of the line. + +All empty lines and lines containing only whitespace charecters are +removed. + +Remaining lines are parsed as follows - leading whitespace is stripped +and first token comprised of non-whitespace characters is taken as +configuration key. The remainder of the line without leading +whitespace is then taken as given configuration option value. + +This pre-processed source is scanned for mandatory known single-keys: + +.RS +.IP \[bu] 2 +nick - member username (nickname) +.IP \[bu] +name - first name and surname +.IP \[bu] +mail - valid email which is used for contacting this member +.IP \[bu] +phone - either a valid phone number or information that member does +not have a registered phone +.RE + +.P +The following single-keys are optional: + +.RS +.IP \[bu] 2 +born - year, month or exact birth date +.RE + +.P +The following generic keys can be present multiple times: + +.RS +.IP \[bu] 2 +card - RFID card id (non-desfire) for physical access to the space +.IP \[bu] +desfire - RFID desfire card id for physical access to the space +.IP \[bu] +credit - amount added to this member balance with month or exact date +of credit and optional reason for this credit record +.RE + +.P +These multi-keys are converted to keys where value is a list of all +values collected for given key. + +.P +The following period start/stop keys can be present multiple times as +well: + +.RS +.IP \[bu] 2 +joined - month or exact date of membership start +.IP \[bu] +destroyed - month or exact date right after membership end +.IP \[bu] +studentstart - month or exact date of student status start +.IP \[bu] +studentstop - month or exact date right after student status end +.IP \[bu] +suspendstart - month or exact date when member is already considered suspended +.IP \[bu] +suspendstop - month or exact date when the member is no longer considered suspended +.RE + +.P +The following organizational bodies membership start/stop keys can +also be present multiple times: + +.RS +.IP \[bu] 2 +chairstart - exact date when this chair was elected +.IP \[bu] +chairstop - exact date of the first day when this member is no longer a chair +.IP \[bu] +councilstart - exact date when this council member was elected +.IP \[bu] +councilstop - exact date of the first day when this member is no longer a council member +.IP \[bu] +revisionstart - exact date when this revision committee member was elected +.IP \[bu] +revisionstop - exact date of the first day when this member is no longer a revision committee member +.IP \[bu] +grantstart - exact date when this grant committee member was elected +.IP \[bu] +grantstop - exact date of the first day when this member is no longer a grant committee member +.RE + +.P +All the start/stop keys are coalesced into lists of periods. If for +given period the stop key is missing an open interval is assumed. The +resulting keys are as follows: + +.RS +.IP \[bu] 2 +member +.IP \[bu] +student +.IP \[bu] +suspend +.IP \[bu] +chair +.IP \[bu] +council +.IP \[bu] +revision +.IP \[bu] +grant +.RE + +These keys with lists of periods are then used for determining member +status at given date (which defaults to current date). + .SS Bank Account Statements The CSV files with bank account statements are stored in the directory @@ -287,23 +405,17 @@ When checking for \fB\-unpaired\fR transactions, only transactions with ID greater than the numeric value stored in this file are considered. +No comments, whitespace, or any other content is allowed in this file. + .SH "CONFIGURATION" The default path with the initial hackerbase configuration is stored in "/etc/hackerbase" but this can be overriden by \fB\-config\fR command-line option. -Before parsing the configuration file all comments are removed. The -comments start with the \fB#\fR character and continue until the end -of the line. - -All empty lines and lines containing only whitespace charecters are -removed. - -Remaining lines are parsed as follows - leading whitespace is stripped -and first token comprised of non-whitespace characters is taken as -configuration key. The remainder of the line without leading -whitespace is then taken as given configuration option value. +The basic parsing is the same as with \fBMember Files\fR. But after +getting a list of pairs of keys with values, no further processing is +performed. A sample configuration for Brmlab installation in "/etc/hackerbase" is: