3.1.7. Guidelines¶

The tool is located in tools/waf-tools.

3.1.7.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

GuidelineViolations

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

GuidelineViolations

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: GuidelineViolations

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: GuidelineViolations

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

GuidelineViolations

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: GuidelineViolations

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: GuidelineViolations

3.1.7.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