Each module which contains code of the program's rules is split on several parts.

ruleConfig

ruleConfig contains configuration of the rule. Available settings are:

• ruleName - the name of the rule. Required. String value.
• ruleFoundMessage - the message shown when the rule return positive result of analyzing the code. Required. String value.
• ruleNotFoundMessage - the message shown when the rule returns negative result of analyzing the code. Required. String value.
• rulePositiveMessage - the message shown when the rule meets the code's element which follows the rule's requirements, for example, a procedure with documentation, etc. Required. String value.
• ruleNegativeMessage - the message shown when the rule meets the code's element which doesn't follow the rule's requirements, for example, a procedure without documentation, etc. Required. String value.
• ruleOptions - the list of options which the rule accepts. If not set, default value, the rule will not accept any arguments in a configuration file. It is a Nim sequence with possible values: node for AST Node, str for string values, integer for integer values, natural for integer values greater than -1, positive for integer values greater than 0, and custom for string values which can contain only the selected values, similar to enumerations. In the last case, the setting ruleOptionValues must be set too. At the moment, a rule can have only one custom option type. The setting is optional. Enumeration.
• ruleOptionValues - the list of values for the custom type of the rule's options. It is a Nim sequence of strings. The setting is required only when setting ruleOptions contains custom type of the options.
• ruleMinOptions - the minimal amount of options required by the rule. Default value is 0, which means the rule requires zero or more options. The setting is optional. Natural value.
• ruleShowForCheck - if true, show the rule summary message for check type of the rule. By default, it is disabled, default value false. The setting is optional. Boolean value.

Constants

Each rule has available the following constants to use in its code:

• showForCheck - Boolean value, set by the configuration's option ruleShowForCheck.
• foundMessage - String value, set by the configuration's option ruleFoundMessage.
• notFoundMessage - String value, set by the configuration's option ruleNotFoundMessage.
• positiveMessage - String value, set by the configuration's option rulePositiveMessage.
• negativeMessage - String value, set by the configuration's option ruleNegativeMessage.

checkRule

checkRule is the macro which is runs to check the Nim code. It is split on several parts. Each part must have at least discard statement. The checkRule is a recursive statement, it executes itself from the main AST node of the code to each its child. Additionally, the statement can raise only the ValueError exception, all other exceptions must be caught in the code. All the checking parts are:

• initCheck - the initialization of checking the Nim code with the rule. This part of code is run only once. It is a good place to initialize some global variables, etc.
• startCheck - the fragment which will be executed each time, before check any AST node of the Nim code.
• checking - the part in which the Nim code is checked. Executed for each AST node of the Nim code.
• endCheck - the part executed at the end of checking, same as initCheck, executed only once. It shows the rule's summary, etc.

checkRule has access to the following variables:

• astNode - the currently checked Nim code as AST node as pointer. While the pointer can't be changed, the node (and Nim code itself) can be modified.
• parentNode - the parent AST node of the currently checked Nim code. Same as astNode, the pointer can't be changed, but the Nim code is modifiable.
• rule - the rule data structure as an object. All its content can be modified. It contains fields:
  • options - the list of the rule options entered by the user in the configuration file. It is a sequence of strings.
  • parent - if true, the currently checked Nim code is the main AST node of the code to check. Boolean value.
  • fileName - the name of the file which contains the checked Nim code. String value.
  • negation - if true, the rule is configured as a negation (with word not in the configuration file). Boolean value.
  • ruleType - the type of the rule: check, fix, search or count. Enumeration.
  • amount - the amount of results found in the previous iterations of checking the Nim code. Integer value.
  • enabled - if true, the rule is enabled for the currently checked Nim code. Boolean value.
  • fixCommand - the command executed by fix type of the rule. Sets by the user in the configuration file. String value.
  • identsCache - the Nim idents cache needed for some internal rule code. It is recommended to not change it.
  • forceFixCommand - if true, the rule should use fixCommand for fix type of the rule instead of its own code. Sets by the user in the configuration file. Boolean value.
• isParent - if true, the rule is in the main AST node of the currently checked Nim code. Boolean, read only value.
• messagePrefix - the prefix added to each log's message. Its content depends on the level of the program's messages set in the configuration file. String, read only value.

checkRule can use the following procedures and templates:

• message(text: string; returnValue: var int; level: Level = lvlError; decrease: bool = true) - prints the selected text as the program's log's message and modify the rule results amount rule.amount via returnValue parameter. If decrease parameter is set to true, the returnValue will be decreased, otherwise increased. level is the level of the log message.
• errorMessage(text: string; e: ref Exception = nil): int - prints the selected text as the program's error message. If parameter e isn't nil, it also shows the message and stack trace, in debug builds only, for the current exception.
• setRuleState(node: PNode; ruleName: string; oldState: var bool) - checks and sets the state, enabled or disabled, of the rule, based on the program's pragmas in the code. node is the AST node of the Nim code currently checked, ruleName is usually set to the configuration variable ruleName and oldState is the modified state of the rule, usually set to rule.state, it can be modified by setRuleState call.
• setResult*(checkResult: bool; positiveMessage, negativeMessage: string; node: PNode; ruleData: string = ""; params: varargs[string]) - sets the result of checking the Nim code as the AST node. checkResult is the result of checking of the Nim code, for example, true if the code's documentation found or if procedure has the selected pragma. positiveMessage will be shown when checkResult fulfills the rule's settings, like negation, type, etc. negativeMessage will be shown when checkResilt not fulfills the rule's settings. Both are usually set to the rule's configuration options like positiveMessage and negativeMessage. ruleData is an additional data used by fix type of the rule. params contains list of additional data, used in the program's messages, positiveMessage and negativeMessage. To use any of params, use template {params[number]} in messages, where [number] is the number of the parameter on the list, starting from zero.
• getNodesToCheck(parentNode, node: PNode): PNode - get the flattened into one list, the list of AST nodes, starting from currently checked node of the Nim code.

fixRule

fixRule is the macro which will be executed for fix type of the rule. It must contain at least discard statement. If it is set to discard only statement, then the command set by the configuration fixCommand setting will be executed. Otherwise, the code inside the macro will be used, unless the program's configuration option forceFixCommand is set. The macro returns true if the Nim code was modified, so the program can save the new version of the Nim code to the file, otherwise false. If fixCommand executed, the macro always returns false. Additionally, the statement can't raise any exception, all must be caught in the code.

fixRule has access to the following variables:

• astNode - the currently checked Nim code as AST node as pointer. While the pointer can't be changed, the node (and Nim code itself) can be modified.
• parentNode - the parent AST node of the currently checked Nim code. Same as astNode, the pointer can't be changed, but the Nim code is modifiable.
• rule - the rule data structure as an object. It contains fields:
  • options - the list of the rule options entered by the user in the configuration file. It is a sequence of strings.
  • parent - if true, the currently checked Nim code is the main AST node of the code to check. Boolean value.
  • fileName - the name of the file which contains the checked Nim code. String value.
  • negation - if true, the rule is configured as a negation (with word not in the configuration file). Boolean value.
  • ruleType - the type of the rule: check, fix, search or count. Enumeration.
  • amount - the amount of results found in the previous iterations of checking the Nim code. Integer value.
  • enabled - if true, the rule is enabled for the currently checked Nim code. Boolean value.
  • fixCommand - the command executed by fix type of the rule. Sets by the user in the configuration file. String value.
  • identsCache - the Nim idents cache needed for some internal rule code. It is recommended to not change it.
  • forceFixCommand - if true, the rule should use fixCommand for fix type of the rule instead of its own code. Sets by the user in the configuration file. Boolean value.
• data - additional data sent to the fixRule macro, usually via setResult call. String value.