3.1.9. Guidelines¶
The tool is located in tools/waf-tools
.
3.1.9.1. Tool Documentation¶
Implements a waf tool to check for foxBMS project guidelines
- class f_guidelines.AutoNumberGuidelineErrors(value)¶
Auto numbering Enum
Inherits from enum and provides an automatic numeration for all its members
- class f_guidelines.GuidelineViolations(value)¶
Assign numbers to our error codes
GuidelineViolations inherits from AutoNumberGuidelineErrors and numbers are automatically set for each error code. The counting starts with 0 for NO_VIOLATION.
- class f_guidelines.c_check_comment_style(*args: Any, **kwargs: Any)¶
Class to implement c comment style check
A task is only executed if a file is changed.
- keyword()¶
Displayed keyword for check
- run()¶
calls test function and prints the error message
A list (in self.input) containing the path of the to be checked file is passed as first argument in the task generation. The second argument self.rule_name contains the name of the style guide rule. run calls the test function and passes the text of the to be checked file with regular expression for the comment style. Depending on the return value of the test function an error message with the filename and the line number is printed.
- Returns
If no violation is found the value of GuidelineViolations.NO_VIOLATION is returned. If the file contains the forbidden comment style the value of GuidelineViolations.C_COMMENT_STYLE is returned
- Return type
int
- static test(txt, regex)¶
Implements check which searches for forbidden comment style
- Parameters
txt (string) – text of the to be checked file
regex (compiled pattern) –
style (contains regular expression for the forbidden comment) –
- Returns
A list with line numbers in which the forbidden comment style was found.
- Return type
list
- class f_guidelines.c_check_define_guard(*args: Any, **kwargs: Any)¶
Class to implement define guard check
A task is only executed if a file or the regular expression C_005_REGEX is changed.
- keyword()¶
Displayed keyword for check
- run()¶
calls test function to search after the include guard
A list (in self.input) containing the path and the name of the to be checked file is passed as first argument in the task generation. The second argument self.rule_name contains the name of the style guide rule. run calls the test function and passes the filename, the text of the to be checked file and regular expression from rules.json. Depending on the return value of the test function, an error message is printed.
- Returns
If no violation is found the value of GuidelineViolations.NO_VIOLATION is returned. If a line in the file contains tabs GuidelineViolations.GUARD is returned
- Return type
int
- static test(filename, txt, config)¶
Implements checks that the include guard exists
First it is searched after #ifndef, #define and #endif. Afterwards it is checked with the line number whether everything is at the correct position.
- Parameters
filename (string) – name of the actual file
txt (string) – text of the to be checked file
config (dict) – dictionary containing regular expressions
- Returns
A list of tuple with GuidelineViolations member and the error message
- Return type
list
- class f_guidelines.c_check_doxygen(*args: Any, **kwargs: Any)¶
Class to implement the doxygen comment check
A task is only executed if a file or the regular expression C_004_REGEX is changed.
- keyword()¶
Displayed keyword for check
- run()¶
calls test function and prints out the line with a wrong file level doxygen comment
A list (in self.input) containing the path of the to be checked file is passed as first argument in the task generation. The second argument self.rule_name contains the name of the style guide rule. run calls the test function and passes the filename, the text of the to be checked file and regular expression from rules.json. Depending on the return value of the test function, an error message is printed.
- Returns
If no violation is found the value of GuidelineViolations.NO_VIOLATION is returned. If a line is not conform with the FILE LEVEL Doxygen rule the GuidelineViolations.C_DOXYGEN value is returned
- Return type
int
- static test(filename, txt, regex)¶
Implements check that the file level doxygen comments are correct
This function checks whether the FILE LEVEL Doxygen comment format is existent and in the correct order in the file. The first for loop compiles the needed regular expressions for the FILE LEVEL Doxygen comment style and the second loop goes line by line over the whole file. doxygen_regex_number is the current searched regular expression and doxygen_regex_found_line is the line of the match of the last searched regular expression. In the second loop the beginning of the C comment is searched first. A second occurrence of the C comment start sets doxygen_regex_found_line to the actual line, because not all C comments are FILE LEVEL Doxygen comments. The next if clause looks for the end of the Doxygen comment. At last it is checked whether all necessary comments exists in the right order.
- Parameters
filename (string) – name of the actual file
txt (string) – text of the to be checked file
config (dict) – dictionary containing regular expressions
- Returns
A list of tuple with GuidelineViolations member and the error message
- Return type
list
- class f_guidelines.c_check_sections(*args: Any, **kwargs: Any)¶
Class to check existence of section comments
A task is only executed if a file or the regular expression C_006_SECTION_STRING is changed.
- keyword()¶
Displayed keyword for check
- run()¶
calls test function to search section comments
A list (in self.input) containing the path of the to be checked file is passed as first argument in the task generation. The second argument self.rule_name contains the name of the style guide rule. run calls the test function and passes the text of the to be checked file and regular expression from rules.json. Depending on the return value of the test function, an error message is printed.
- Returns
If no violation is found the value of GuidelineViolations.NO_VIOLATION is returned. If the sections are not correct the value of GuidelineViolations.C_SECTION is returned
- Return type
int
- static test(txt, section_strings)¶
Implements check that all section comments exists in the right order
This function checks whether the section comments are existent in the file. Furthermore it is checked whether the section comments are in the correct order which is checked by a current_section_searched.
- Parameters
txt (string) – text of the to be checked file
section_strings (list) – list containing regular expressions for the section comments
- Returns
A list with tuple out of a GuidelineViolations member and the error messages
- Return type
list
- f_guidelines.check_guidelines(ctx)¶
Calls the guidelines check
- class f_guidelines.check_header(*args: Any, **kwargs: Any)¶
Class to implement running the checks for headers in files
A task is only executed if a file or the regular expression HEADER_REGEX is changed. This task is executed for C, Python, Shell, Batch and YAML files.
- keyword()¶
Displayed keyword for check depending on the file type
- run()¶
calls test function and errors in the headers of the files
A list (in self.input) containing the path of the to be checked file is passed as first argument in the task generation. The second argument self.rule_name contains the name of the style guide rule. run calls the test function and passes the text of the to be checked file with the specific header of a file type. Depending on the return value of the test function an error message with the filename and line is printed.
- Returns
If no violation is found the value of GuidelineViolations.NO_VIOLATION is returned. If a line in the file contains whitespace at the end GuidelineViolations.HEADER is returned
- Return type
int
- static test(txt, header)¶
Implements check that header is contained in text
For each file type it is defined a specific header which has to be contained in the file. test function checks each line for this header.
- Parameters
txt (string) – text of the to be checked file
header (list) – contains all lines of the header
- Returns
A list of tuples with GuidelineViolations members and the line number containing differences in the headers.
- Return type
list
- f_guidelines.configure(conf)¶
Configures all sub-tools the guidelines tool needs
- class f_guidelines.encoding(*args: Any, **kwargs: Any)¶
Class to implement the utf-8 coding check
A task is only executed if a file is changed.
- keyword()¶
Displayed keyword for check
- run()¶
Implements check that a file can be opened in utf-8 mode and has no BOM markers
A list (in self.input) containing the path of the to be checked file is passed as first argument in the task generation. The second argument self.rule_name contains the name of the style guide rule. run calls the test function and passes file path, rule name and the encoding style (utf-8). Depending on the return value of the test function, an error message is printed.
- Returns
returns 0 for no encoding violation otherwise the value of GuidelineViolations.GENERAL_ENCODING
- Return type
int
- static test(file_path, rulename, encoding_type='utf-8')¶
checks whether a file is correct encoded
file in file_path is first opened and read with utf-8 encoding and afterwards checked for not allowed BOM
- Parameters
file_path (string) – path to file
encoding_type (string) – expected file encoding (default: “utf8”)
- Raises
UnicodeDecodeError – DecodeError is thrown if the file can not be read with the specified encoding
- Returns
If the file can be opened with the specified encoding and contains no BOM, GuidelineViolations.NO_VIOLATION is returned. Otherwise GuidelineViolations.GENERAL_ENCODING is returned along with a more detailed error message
- Return type
- class f_guidelines.filenames(*args: Any, **kwargs: Any)¶
Class to implement the filenames check
A task is only executed if the filename of a file or the regular expression for correct filenames is changed.
- keyword()¶
Displayed keyword for check
- run()¶
calls test function and prints the error message
A list (in self.input) containing the name of the to be checked file is passed as first argument in the task generation. The second argument self.rule_name contains the name of the style guide rule. Depending on the return value of the test function, an error message with incorrect filename is printed.
- Returns
returns 0 for no filename rule violation otherwise the value of GuidelineViolations.GENERAL_FORBIDDEN_FILENAME
- Return type
int
- static test(filename, reg)¶
Implements check that filename does not include forbidden characters
- Parameters
filename (string) – the name of the to be checked file
reg (regex) – a compiled regular expression for a correct filename
- Returns
GENERAL_FORBIDDEN_FILENAME or NO_VIOLATION depending on the test result
- Return type
- class f_guidelines.guidelines_context(*args: Any, **kwargs: Any)¶
Helper class to bind the guidelines check to an waf argument
- f_guidelines.options(opt)¶
Defines options that can be passed to waf
- class f_guidelines.posix_3_206(*args: Any, **kwargs: Any)¶
Class to implement the POSIX 3.206 check
A task is only executed if a file or the check itself is changed.
- keyword()¶
Displayed keyword for check
- run()¶
Implements check that the file contains one empty line at the end
A list (in self.input) containing the text of the to be checked file is passed as first argument in the task generation. The second argument self.rule_name contains the name of the style guide rule. run calls the test function and passes the text of the to be checked file. Depending on the return value of the test function, an error message is printed.
- Returns
If no violation is found the value of GuidelineViolations.NO_VIOLATION is returned. If a file contains no empty line or too many empty lines an error message the is printed and the value of GuidelineViolations.GENERAL_EOF_NO_EMPTY_NEWLINE or GuidelineViolations.GENERAL_EOF_TOO_MANY_EMPTY_NEWLINES is returned
- Return type
int
- static test(txt)¶
Implements check that text ends with a single empty line
- Parameters
txt (string) – contains text that should have only one single empty line at the end
- Returns
GuidelineViolations.NO_VIOLATION if the text ends with an empty line, GuidelineViolations.GENERAL_EOF_NO_EMPTY_NEWLINE if a newline is missing at the end of the text or GuidelineViolations.GENERAL_EOF_TOO_MANY_EMPTY_NEWLINES if there is more than one empty line at the end of the text.
- Return type
- f_guidelines.process_guidelines(self)¶
creates guideline tasks for the repository
process_guidelines is decorated with TaskGen.feature which specifies when the tasks are executed. feature guidelines is defined in wscript.
- class f_guidelines.rst_check_heading(*args: Any, **kwargs: Any)¶
Class to implement the rst heading check
A task is only executed if a file is changed.
- keyword()¶
Displayed keyword for check
- run()¶
calls test function and prints the error message
A list (in self.input) containing the path of the to be checked file is passed as first argument in the task generation. The second argument self.rule_name contains the name of the style guide rule. run calls the test function and passes the text of the to be checked file. Depending on the return value of the test function an error message with the filename is printed.
- Returns
If no violation is found the value of GuidelineViolations.NO_VIOLATION is returned. If the file does not have a heading the value of GuidelineViolations.RST_HEADING is returned
- Return type
int
- static test(txt, regex)¶
Implements the check that rst files have a heading
First it is iterated over the whole file to search for the file label, overline, file caption and underline. Afterwards there are returned error messages depending on the case.
- Parameters
txt (string) – text of the to be checked file
- Returns
if a file has a heading two lines after the file label GuidelineViolations.NO_VIOLATION is returned, otherwise GuidelineViolations.RST_HEADING
- Return type
- class f_guidelines.rst_check_include(*args: Any, **kwargs: Any)¶
Class to implement the macro include check
A task is only executed if a file or the INCLUDE_REGEX is changed.
- keyword()¶
Displayed keyword for check
- run()¶
calls test function and prints the error message
A list (in self.input) containing the path of the to be checked file is passed as first argument in the task generation. The second argument self.rule_name contains the name of the style guide rule. run iterates over all specific excludes of the included files. Afterwards run calls the test function and passes the text of the to be checked file with regular expression for to be included file. Depending on the return value of the test function an error message with the filename is printed.
- Returns
If no violation is found the value of GuidelineViolations.NO_VIOLATION is returned. If the file does not include the necessary file the value of GuidelineViolations.RST_MISSING_INCLUDE is returned
- Return type
int
- static test(txt, regex)¶
Implements check that all necessary files are included
Each .rst file has to include specific files
- Parameters
txt (string) – text of the to be checked file
regex (compiled pattern) – contains regular expression for the include
- Returns
if a file includes necessary file, GuidelineViolations.NO_VIOLATION is returned otherwise GuidelineViolations.RST_MISSING_INCLUDE
- Return type
- class f_guidelines.rst_check_orphan(*args: Any, **kwargs: Any)¶
Class to implement declaration of rst file orphans
A task is only executed if a file is changed
- keyword()¶
Displayed keyword for check
- run()¶
calls test function and prints the error message
A list (in self.input) containing the path of the to be checked file is passed as first argument in the task generation. The second argument self.rule_name contains the name of the style guide rule. run calls the test function and passes the first line of the to be checked file. Depending on the return value of the test function an error message with the filename is printed.
- Returns
If no violation is found the value of GuidelineViolations.NO_VIOLATION is returned. If the file does not have orphan in the first line the value of GuidelineViolations.RST_ORPHAN is returned
- Return type
int
- static test(txt)¶
Implements check that the file is declared as orphan
- Parameters
txt (string) – first line of the to be checked file
- Returns
if a file includes orphan in the first line, GuidelineViolations.NO_VIOLATION is returned, otherwise GuidelineViolations.ORPHAN
- Return type
- class f_guidelines.tabs(*args: Any, **kwargs: Any)¶
Class to implement running the trailing whitespace check
A task is only executed if a file is changed.
- keyword()¶
Displayed keyword for check
- run()¶
calls test function and prints out the line with tabs in it
A list (in self.input) containing the path of the to be checked file is passed as first argument in the task generation. The second argument self.rule_name contains the name of the style guide rule. run calls the test function and passes the text of the to be checked file. Depending on the return value of the test function, an error message is printed.
- Returns
If no violation is found the value of GuidelineViolations.NO_VIOLATION is returned. If a line in the file contains tabs the value of GuidelineViolations.GENERAL_TABS is returned
- Return type
int
- static test(txt)¶
Implements check that lines in text do not have tabs
- Parameters
txt (string) – text of the to be checked file
- Returns
A list of tuples with GuidelineViolations members and the line number containing tabs.
- Return type
list
- class f_guidelines.trailing_whitespace(*args: Any, **kwargs: Any)¶
Class to implement the trailing whitespace check
A task is only executed if a file is changed.
- keyword()¶
Displayed keyword for check
- run()¶
calls test function and prints the line number with trailing whitespace
A list (in self.input) containing the path of the to be checked file is passed as first argument in the task generation. The second argument self.rule_name contains the name of the style guide rule. run calls the test function and passes the text of the to be checked file. Depending on the return value of the test function, an error message is printed.
- Returns
If no violation is found the value of GuidelineViolations.NO_VIOLATION is returned. If a line in the file contains whitespace at the end GuidelineViolations.GENERAL_TRAILING_WHITESPACE is returned
- Return type
int
- static test(txt)¶
checks line by line the text whether there are trailing whitespace
- Parameters
txt (string) – text of the to be checked file
- Returns
A list of tuples with GuidelineViolations members and the line number containing trailing whitespace.
- Return type
list
- class f_guidelines.unique_filenames(*args: Any, **kwargs: Any)¶
Class to implement the filename uniqueness check
A task is only executed if a filename of a file is changed. A filename is not allowed to occur twice or more in the repository.
- keyword()¶
Displayed keyword for check
- run()¶
calls test function and prints the error message
A list (in self.input) containing the name of the to be checked file is passed as first argument in the task generation. The second argument self.rule_name contains the name of the style guide rule. run calls the test function and passes all filenames in the repository. Depending on the return value of the test function, an error message with all duplicates is printed.
- Returns
returns 0 for no unique filename rule violation otherwise the value of GuidelineViolations.GENERAL_NOT_UNIQUE_FILENAME
- Return type
int
- static test(all_filenames)¶
checks whether there are files with the same name in the repository
The collections.Counter puts all filenames with their count in a dictionary. If the count is bigger than one, the filename is inserted into the list of duplicates.
- Parameters
all_filenames (list) – list with all filenames in the repository
- Returns
If the duplicates list is not empty a GuidelineViolations GENERAL_NOT_UNIQUE_FILENAME is returned with the duplicates list
- Return type
3.1.9.2. Test Documentation¶
The unit tests of the module are implemented in
tests/scripts/waf-tools/f_hcg/test_f_guidelines.py
Implements tests for the waf tool f_guidelines
.
- class test_f_guidelines.TestGuidelineMethods(methodName='runTest')¶
Unit test class for the
f_guidelines
tool- general_tester(result, function_result)¶
function for reiterative tests
- Parameters
result (list) – list containing the defined results of one test
function_result (list) – list containing the results from the called test function
- test_c_comment_style()¶
Unit test for c comment style check in c and h files
test_c_comment_style uses python unittest to check the return value of the f_guidelines c_check_comment_style test function. There are forbidden comment styles which has to be checked
- test_c_define_guard()¶
checks the define guard
- test_c_sections()¶
Unit test for c section check in c and h files
test_c_sections uses python unittest to check the return value of the f_guidelines c_check_sections test function. There have to be section comments in the right order for c and h files.
- test_doxygen()¶
Unit test for FILE LEVEL doxygen comment style in c and h files
test_doxygen uses python unittest to check the return value of the f_guidelines c_check_doxygen test function. There has to be a doxygen comment in a specific style.
- test_encoding()¶
test guideline-check that files MUST be UTF-8
- test_filenames()¶
Unit test for valid filenames
test_filenames uses python unittest to check the return value of the f_guidelines filename test function with bad and good filenames.
- test_header()¶
Unit test to check the header
test_header uses python unittest to check the return value of the f_guidelines check_header test function. Depending of the file type the file has to start with a specific header.
- test_posix_3_206()¶
Unit test for empty line at end of text
test_posix_3_206 uses python unittest to check the return value of the f_guidelines posix_3_206 test function. Only one empty line is allowed at the end of each text.
- test_rst_heading()¶
Unit test for macro including check in rst files
test_rst_heading uses python unittest to check the return value of the f_guidelines rst_check_heading test function. Each rst files must have a heading
- test_rst_macro()¶
Unit test for macro including check in rst files
test_rst_macro uses python unittest to check the return value of the f_guidelines rst_check_include test function. Each rst files has to include macros.txt
- test_rst_orphan()¶
Unit test for macro including check in rst files
test_rst_orphan uses python unittest to check the return value of the f_guidelines rst_check_orphan test function. rst files which are not included in other rst files must have :orphan: in the first line
- test_tabs()¶
Unit test for no tabs in lines of text
test_tabs uses python unittest to check the return value of the tabs test function. Tabs are not allowed. Whitespace is used for indentation.
- test_trailing_whitespace()¶
Unit test for no trailing whitespace in lines of text
test_trailing_whitespace uses python unittest to check the return value of the f_guidelines trailing_whitespace test function. There should be no trailing whitespace at the end of a line.
- test_unique_filename()¶
Unit test for unique filenames
test_unique_filename uses python unittest to check the return value of the f_guidelines unique_filenames test function. In the repository a filename can not exit more than one time.
- test_f_guidelines.get_git_root(path: str) str ¶
helper function to find the repository root
- Parameters
path (string) – path of test_f_guidelines
- Returns
root path of the git repository
- Return type
root (string)
- test_f_guidelines.get_results(tests_folder, result_json_file)¶
returns result json
- Parameters
tests_folder (string) – folder name of the test
- test_f_guidelines.get_txt(f)¶
returns the content of file
- test_f_guidelines.main()¶
main function