Contents
You can configure rules within the RuleSet file or within the "codenarc.properties" file. Both of these approaches are described in the sections below.
NOTE: Keep in mind that RuleSet files can be nested (to any depth). That, along with the "codenarc.properties" file support, allows multiple layers of rule configuration. The hierarchical layering of configuration can come in handy within organizations comprised of multiple teams or projects. For instance, you can define an organization RuleSet file. Then each team can define its own RuleSet file and/or a "codenarc.properties" file, customizing the rules from the top-level file.
Creating a RuleSet describes how to create a new RuleSet and configure the rules within it.
You can configure rules when you include a whole RuleSet using <ruleset-ref>, as in the following example:
<ruleset-ref path='rulesets/size.xml'> <rule-config name='ClassSize'> <property name='maxLines' value='500'/> </rule-config> </ruleset-ref>
Or you can configure Rules that you include individually using <rule>, as in the following example:
<rule class='org.codenarc.rule.naming.VariableNameRule'> <property name="finalRegex" value="F_[A-Z0-9]*"/> <property name='priority' value='1'/> </rule>
CodeNarc reads the properties file named "codenarc.properties", if found on the classpath, and applies the property values to any matching Rules. You can optionally override the location of the properties file by setting the "codenarc.properties.file" system property to the path or URL of the properties file. That can include a "file:" URL to load from a relative or absolute path on the filesystem (e.g., "file:relative/path/override-codenarc.properties"). If the properties file is not found, then do nothing.
For each properties entry of the form [rule-name].[property-name]=[property-value], the named property for the rule matching rule-name is set to the specified property-value. Properties entries not of this form or specifying rule names not within the current RuleSet are ignored.
The following example "codenarc.properties" file configures several rules. Note that Fields with Integer, String and Boolean values are configured.
# Sample RuleSet configuration # Entries should be of the form: [rule-name].[property-name]=[property-value] CatchThrowable.doNotApplyToClassNames=BaseController,AbstractTest CatchThrowable.priority = 1 ReturnFromFinallyBlock.priority = 1 # Turn off this rule AbstractClassName.enabled=false # Unset special naming for final fields -- use base 'regex' value for all names FieldName.finalRegex= # Make sure all field names are prefixed with '_' FieldName.regex=_[a-z][a-zA-Z0-9]*
Note that you cannot add new rules using the "codenarc.properties" file, though you can disable (turn off) rules.
The rules included with CodeNarc (as well as any subclasses of AbstractRule) provide several standard properties that can be used to configure how rules are applied to source files.
The applyToClassNames and doNotApplyToClassNames properties enable filtering the classes to which the rule is applied.
If applyToClassNames is not empty or null, then the rule is only applied to classes matching one of the specified class names. Likewise, if doNotApplyToClassNames is not empty or null, then the rule is NOT applied to classes matching any of the specified class names.
Both of these properties can specify either a single class name or a comma-separated list of names. The names may optionally contain wildcard characters ('*' or '?'). The wildcard character '*' matches a sequence of zero or more characters in the input string. The wildcard character '?' matches exactly one character in the input string.
Each class name(s) can be either a fully-qualified class name (including the package) or else a class name without a package.
For instance, in the following example "codenarc.properties" excerpt, the CatchThrowable rule is NOT applied to classes named "BaseController" or "AbstractTest", no matter what package they are in (if any). The FieldName rule, on the other hand, is only applied to the org.codenarc.CodeNarc class or any of the classes within org.codenarc.extra package.
CatchThrowable.doNotApplyToClassNames=BaseController,AbstractTest FieldName.applyToClassNames=org.codenarc.CodeNarc,org.codenarc.extra.*
Both properties default to null.
These properties are available only to subclasses of AbstractAstVisitorRule, but this includes almost all of the rules provided with CodeNarc -- i.e., all of the rules that deal with the Groovy AST (Abstract Syntax Tree) of a source file. This includes any rule that processes source code elements such as a package, class, method, field, parameter, etc..
The applyToFileNames and doNotApplyToFileNames properties enable filtering the files to which the rule is applied by specifying a comma-separated list of filenames (with optional path) of source files. If applyToFileNames is not empty or null, then the rule is only applied to source files matching one of the specified filenames. Likewise, if doNotApplyToFilesMatching is not empty or null, then the rule is NOT applied to source files matching any of the specified filenames.
Both properties may optionally specify a path (i.e., if the value contains at least one '/' path separator). In that case, the value is matched against the full pathname of each source file. If no path is specified, then only the filename of each source file is compared (i.e., its path is ignored).
Both properties may optionally contain wildcard characters ('*' or '?'). The wildcard character '*' matches a sequence of zero or more characters in the input string. The wildcard character '?' matches exactly one character in the input string. Both properties default to null.
The applyToFilesMatching and doNotApplyToFilesMatching properties enable filtering the files to which the rule is applied by matching a regular expression against the full pathname of each source file. If applyToFilesMatching is not empty or null, then the rule is only applied to source files with matching paths. Likewise, if doNotApplyToFilesMatching is not empty or null, then the rule is NOT applied to source files with matching paths. Both properties default to null.
The enabled boolean property allows a rule to be completely turned off (by setting it to false). It defaults to true.
The violationMessage property enables overriding the rule violation message. If not null, this is used as the message for all violations of this rule, overriding any message generated by the rule itself. This property defaults to null. Note that setting this to an empty string "hides" the message, if any, generated by the actual rule.
The description property enables overriding the rule description text. If not null, this value is used as the description text for this rule, overriding any description text found in the i18n resource bundles. This property defaults to null.
You can also override the default name or priority properties for each rule.
You can turn off a rule by filtering the containing ruleset to exclude the rule. See Filtering Rules Within a RuleSet.
Alternately, as mentioned above, you can turn off (disable) a rule by setting its enabled boolean property to false (assuming it is a subclass of AbstractRule), as shown in the following "codenarc.properties" excerpt.
# Turn off this rule AbstractClassName.enabled=false
The descriptions for rules used in a CodeNarc report are shown at the bottom of the resulting HTML report. Those rule descriptions are retrieved from a ResourceBundle. This ResourceBundle consists of a base (parent) bundle, provided with the CodeNarc distribution, and an optional custom (child) bundle, which may be provided by the user.
Because this is based on the standard Java ResourceBundle facility, you can customize (override) or translate these descriptions by providing your own locale-specific message properties file on the classpath. For example, a German one would be named "codenarc-messages_de.properties".
The rule description message key is of the form "<rule-name>.description". Examples include "BooleanInstantiation.description" and "CatchThrowable.description".
See the javadoc for the java.util.ResourceBundle class for more information.
The base ResourceBundle provided with the CodeNarc distribution has a basename of "codenarc-base-messages". The rules provided with CodeNarc all have associated descriptions within the "codenarc-base-messages.properties" file.
You can provide a locale-specific variant of this file on the classpath if you wish, but in most scenarios, the recommended approach for customizing rule descriptions is to provide a custom messages bundle file, as described below.
You can optionally provide descriptions for new rules or override existing rule descriptions by placing a "codenarc-messages.properties" file on the classpath. This is also a ResourceBundle file, so it can have locale-specific variants, if needed. If this bundle (file) is present, it is searched first. If the desired message key is not found, only then is the base message bundle checked.
You can provide rule description entries within this file for custom rules that you create. You can also include rule description entries for existing rules, in which case the descriptions in this file override the default descriptions.
You may wish to customize both the name and the description for an existing rule. For example, you may want to have multiple instances of a generic rule, each configured differently. Or you may just want to make the rule name more clearly denote its specific purpose.
For example, in the following excerpt from a RuleSet file, because the name property is customized for the IllegalRegexRule, the new rule name "AuthorTagNotAllowed" will show up at the bottom of the HTML report, instead of the default rule name "IllegalRegex".
<rule class='org.codenarc.rule.generic.IllegalRegexRule'> <property name="name" value="AuthorTagNotAllowed"/> <property name='regex' value='\@author'/> </rule>
The rule description must be added to the custom messages resource bundle file ("codenarc-messages.properties"). The message key will be "AuthorTagNotAllowed.description".