From 84b701e0868643982dc7b4f9ffc929f63e12dff3 Mon Sep 17 00:00:00 2001 From: ciorceri Date: Wed, 18 Jul 2018 23:47:27 +0300 Subject: [PATCH] Updated documentation --- README.md | 156 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 114 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index a3cb3ac..1aa6c83 100644 --- a/README.md +++ b/README.md @@ -12,21 +12,21 @@ - Validate logs based on predefined rules - Output can have following formats: human-friendly, json, xml - Cross checker to generate a VHF contest results -Future features: +#####Future features: - Support for ADIF & Cabrillo logs with generic and rules based validator -Current VHF rules format (this format may be subject to change): +#####Current VHF rules format (this format may be subject to change): ``` [contest] -name=Cupa Nasaud -begindate=20160805 -enddate=20160806 +name=Contest name +begindate=20180701 +enddate=20180702 beginhour=1200 -endhour=1200 +endhour=1800 bands=2 periods=2 -categories=4 +categories=3 modes=1,2,6 [log] @@ -39,39 +39,34 @@ multiplier=1 [band2] band=432 -regexp=430|432|70cm -multiplier=1 +regexp=430|432|435|70cm +multiplier=2 [period1] -begindate=20160805 -enddate=20160805 +begindate=20180701 +enddate=20180701 beginhour=1200 -endhour=2359 +endhour=1800 bands=band1,band2 [period2] -begindate=20160806 -enddate=201608086 -beginhour=0000 -endhour=1200 +begindate=20180702 +enddate=20180702 +beginhour=1200 +endhour=1800 bands=band1,band2 [category1] -name=Single Operator 144 +name=Single Operator regexp=so|single bands=band1 [category2] -name=Single Operator 432 -regexp=so|single -bands=band2 - -[category3] name=Multi Operator regexp=mo|multi bands=band1,band2 -[category4] +[category3] name=Checklog regexp=check|checklog bands=band1,band2 @@ -81,38 +76,115 @@ email=yes address=no name=yes ``` -The rules format is based on [INI file format](http://en.wikipedia.org/wiki/INI_file). -There are the following sections: +#####The rules format is based on [INI file format](http://en.wikipedia.org/wiki/INI_file) and there are the following sections: [contest] - contains generic details about contest (name, contest date, contest hours, bands, periods and categories + contains generic details about contest: + - name + - contest date : begindate, enddate + - contest hours : beginhour, endhour + - bands : number of bands used in contest + - periods : number of periods + - categories : number of categories (sosb, momb, checklog, ...) + - modes : list with valid contest modes (1=ssb, 2=cw, 6=fm) [log] - specifies the log format (edi, adif, cabrillo) + specifies the log format (only edi is supported at this moment) [band1], [band2], ... [bandN] rules about contest bands (frequency) + - band : band name to be used in report + - regexp : customisable regular expresion field to detect band in logs + - multiplier : the points multiplier for this band (use 1 as default value) [period1], [period2], ... [periodN] - rules about contest periods (begin/end date, begin/end hour, bands) + rules about contest periods + - period date : begindate, enddate + - period hours : beginhour, endhour + - bands : list with contest bands that will be used in that period [category1], [category2], ... [categoryN] rules about contest categories (single/multi operator[s], category bands) + - name : category name to be used in report + - regexp : customisable regular experesion field to detect ham category in logs + - bands : list with allowed bands by that category (usually all bands) [extra] - rules presence and validation of other header fields (email, address, name) + rules presence and validation of other header fields from log (email, address, name) -The following errors can be displayed if validation fails: +#####Run examples using the provided 'test_logs' folder: - - Line None : PCall field is not present - - Line None : PWWLo field is not present - - Line None : PBand field is not present - - Line None : PSect field is not present - - Line None : TDate field is not present - - Line 4 : PCall field content is not valid - - Line 5 : PWWLo field value is not valid - - Line 3 : TDate field value is not valid (201605070;20160508) +* Single log validation (generic, no rules) and human friendly output +``` +$ python3 ./logXchecker.py -slc ./test_logs/logs/yo2lza_20160514_091251.edi -f edi +logXchecker - v1.0 +Checking log : ./test_logs/logs/yo2lza_20160514_091251.edi +No error found +``` +* Single log validation (generic, no rules) and json output +``` +$ python3 ./logXchecker.py -slc ./test_logs/logs/yo2lza_20160514_091251.edi -f edi -o json +logXchecker - v1.0 +{"log": "./test_logs/logs/yo2lza_20160514_091251.edi", "io": [], "header": [], "qso": []} +``` +* Single log validation (with rules) and human friendly output +``` +$ python3 ./logXchecker.py -slc ./test_logs/logs/yo2lza_20160514_091251.edi -r ./test_logs/rules.config +logXchecker - v1.0 +Checking log : ./test_logs/logs/yo2lza_20160514_091251.edi +QSO errors : +Line 226 : 160508;1201;OM3RLA;1;59;186;59;185;;JN98LB;349;;;; <- Qso date/hour is invalid: not inside contest periods +Line 227 : 160508;1213;IQ8BI;1;59;187;59;076;;JN71HU;679;;;; <- Qso date/hour is invalid: not inside contest periods +``` +* Single log validation (with rules) and json output +``` +$ python3 ./logXchecker.py -slc ./test_logs/logs/yo2lza_20160514_091251.edi -r ./test_logs/rules.config -o json +logXchecker - v1.0 +{"log": "./test_logs/logs/yo2lza_20160514_091251.edi", "io": [], "header": [], "qso": [[226, "160508;1201;OM3RLA;1;59;186;59;185;;JN98LB;349;;;;", "Qso date/hour is invalid: not inside contest periods"], [227, "160508;1213;IQ8BI;1;59;187;59;076;;JN71HU;679;;;;", "Qso date/hour is invalid: not inside contest periods"]]} +``` +* Multiple logs validation (with rules) and human friendly output +``` +$ python3 ./logXchecker.py -mlc ./test_logs/logs/ -r ./test_logs/rules.config +... +``` +* Logs cross-check (rules are mandatory) and human friendly output +``` +$ python3 ./logXchecker.py -cc ./test_logs/logs -r ./test_logs/rules.config +... +``` +* Logs + checklogs cross-check (rules are mandatory) and human friendly output +``` +$ python3 ./logXchecker.py -cc ./test_logs/logs -cl ./test_logs/checklogs/ -r ./test_logs/rules.config +... +``` +* Logs + checklogs cross-check (rules are mandatory) and verbose human friendly output +``` +$ python3 ./logXchecker.py -cc ./test_logs/logs -cl ./test_logs/checklogs/ -r ./test_logs/rules.config -v +... +``` -If a rules file was provided the following errors can be displayed if validation fails: - TO ADD +#####Example of possible errors at log header validation: +``` +Line None : PCall field is not present +Line None : PWWLo field is not present +Line None : PBand field is not present +Line None : PSect field is not present +Line None : TDate field is not present +Line 3 : TDate field value is not valid (20180701;2018) +Line 4 : PCall field content is not valid +Line 5 : PWWLo field value is not valid +``` -Notes: +#####Example of possible errors at log header validation when rules are provided: +``` +Line 3 : TDate field value has an invalid value (20160507;20160508). Not as defined in contest rule +Line 9 : PSect field value has an invalid value (SINGLE). Not as defined in contest rules +``` + +#####Example of Qso errors: +``` +160507;1450;LZ7J;1;59;006;59;019;;KN22HB;362;;N;; : No log from LZ7J +160507;1529;LZ2SQ;1;59;008;59;020 KN33GY;;;234;;N;; : Qso field has an invalid value (020 KN33GY) +160507;1549;LZ2JA;1;59;010;59;009;;KN22UA;357;;;; : Qth locator mismatch +``` + +#####Notes: - - This is a work in progress and there are still more things to add. - Suggestions are appreciated. - Only Python 3.6+ will be supported. + - I will provide MacOS and Windows builds to make Python install optional.