## Customizing CodeScanner Rules

The CodeScanner command line tool currently accepts an XML configuration file, which controls scanning behavior, like the file types to ignore and which rules to apply. Using the elements contained here makes it possible to customize the scanning rules to include new rules unique to your development environment.

This page describes the format of CodeScanner config file (codescannerconfig.xml), which is used for the following purposes:

- Controls scanning behavior of the CodeScanner command line tool
- Importing/exporting rules and file types from CodeScanner preference pages in Carbide.c++ IDE

## CODESCANNERCONFIG.XML File

The CodeScanner config file is an XML formatted file created by CodeScanner when a scan is performed or when the CodeScaner preference settings are exported. The file contains the following elements:

- Arguments element – specifies the arguments to be passed to CodeScanner
- Sources element – specifies the file types to be ignored by CodeScanner
- Scripts element – specifies the rules to be applied by CodeScanner
- Severities element – specifies the severity levels of rules to be applied by CodeScanner
- Categories element – specifies the categories of rules to be applied by CodeScanner
- CustomRules element – specifies user defined rules to be applied by CodeScanner

#### Arguments Element

Each Arguments element contains one or more of the following arguments:

- Input element (<input>, </input>) – Specify an additional directory or file to scan.
- Outputformat element (<outputformat>, </outputformat>) – Specify the output format(s) of the results generated by CodeScanner. Currently the following output formats are supported:
  - html – generate HTML report
  - xml – generate an XML report
  - std – generate messages in standard console output
- LXR element (<lxr>, </lxr>) – Specify the URL to an LXR site. When this argument is present, CodeScanner generates links to the specified LXR site instead of the local file system.
- LXR version element (<lxrversion>, </lxrversion>) – Specify the LXR version when generating links to an LXR site.
- Timestampedoutput element (<timestampedoutput>, </timestampedoutput>) – Specify whether to generate results in a time-stamped output directory. Supported values are on and off.

An example of an Arguments element:

<arguments>
<input>C:\Symbian\9.2\Epoc32\include</input>
<input>C:\CodeScanner_Tests\includes</input>
<lxr>http://s60lxr/source/</lxr>
<lxrversion>S60_3_2_200736</lxrversion>
<outputformat>html|std</outputformat>
<timestampedoutput>on</timestampedoutput>
</arguments>

#### Sources Element

Each Sources element can contain one or more Excludes elements.

- Excludes element (<excludes>, </excludes>) – Each Excludes element contains a string, which is a regular expression that specifies a file type to be ignored by CodeScanner.

An example of a Sources element:

<sources>
<exclude>.*\.avi</exclude>
<exclude>.*\.bmp</exclude>
<exclude>.*\.jpg</exclude>
<exclude>.*\\test\\.*</exclude>
</sources>

#### Scripts Element

Each Scripts element can contain one or more Script elements, each of which corresponds to a CodeScanner script (each script applies a CodeScanner rule):

- Script element The name of each Script element matches the name of the corresponding rule, e.g. baseconstruct, forbiddenwords, magicnumbers. Each Script element has the following attributes:
  - enable (boolean) – specifies whether a script is enabled by CodeScanner
  - severity (string) – specifies the severity level of a script
  - category (string) – specifies the category of a script
  In addition, certain script elements also have special child element or attribute:

- wordsRE element (<wordsRE>, </wordsRE>) – Specify the child element of the forbiddenwords script element. The wordsRE element contains a string, which is a regular expression that specifies the forbidden words detected by the forbiddenwords script.
- length attribute – Attribute of the longlines script element. The length attribute is a string that specifies the maximum length of a line of code, beyond which the longlines script flags as a problem.
- LFunctionIgnoreRE element (<LFunctionIgnoreRE>, </LFunctionIgnoreRE>) – Specify the child element of the LFunctionCantLeave script element. The LFunctionIgnoreRE element contains a string, which is a regular expression that specifies the L-functions to be ignored by the LFunctionCantLeave script when checking for L-functions inside cannot leave.
- cclassIgnoreRE element (<cclassIgnoreRE>, </cclassIgnoreRE>) – Specify the child element of the missingcclass script element. The cclassIgnoreRE element contains a string, which is a regular expression that specifies the classes to be ignored by the missingcclass script when checking for C classes not inheriting from other C classes.
- openIgnoreRE element (<openIgnoreRE>, </openIgnoreRE>) – Specify the child element of this open script element. The openIgnoreRE element contains a string, which is a regular expression that specifies the classes or objects to be ignored by the open script when checking for ignored return type from Open().
- worryRE element (<worryRE>, </ worryRE>) – Child element of the worryingcomments script element. The worryRE element contains a string, which is a regular expression that specifies the worrying comments detected by the worryingcomments script.

Complete list of currently supported Script elements with default attributes:

<scripts>
<accessArrayElementWithoutCheck category="codereview" enable="true" severity="low"/>
<accessArrayElementWithoutCheck2 category="codereview" enable="true" severity="low"/>
<activestart category="codereview" enable="true" severity="low"/>
<activestop category="codereview" enable="true" severity="low"/>
<arraypassing category="performance" enable="true" severity="medium"/>
<arrayptrcleanup category="codereview" enable="true" severity="low"/>
<assertdebuginvariant category="codingstandards" enable="true" severity="low"/>
<baddefines category="codingstandards" enable="true" severity="low"/>
<baseconstruct category="codereview" enable="true" severity="low"/>
<callActiveObjectWithoutCheckingOrStopping category="codereview" enable="true" severity="low"/> <changenotification category="codereview" enable="true" severity="low"/>
<cleanup category="codingstandards" enable="true" severity="low"/>
<commentcode category="codereview" enable="true" severity="low"/>
<connect category="canpanic" enable="true" severity="high"/>
<ConnectAndDontCloseMemberVariable category="functionality" enable="true" severity="medium"/> <constnames category="codingstandards" enable="true" severity="low"/>
<consttdescptr category="codingstandards" enable="true" severity="low"/>
<controlornull category="canpanic" enable="true" severity="high"/>
<ctltargettype category="functionality" enable="true" severity="medium"/>
<debugrom category="performance" enable="true" severity="medium"/>
<declarename category="codingstandards" enable="true" severity="low"/>
<deleteMemberVariable category="canpanic" enable="true" severity="high"/>
<destructor category="canpanic" enable="true" severity="high"/>
<doubleSemiColon category="codereview" enable="true" severity="low"/>
<driveletters category="codingstandards" enable="true" severity="low"/>
<eikbuttons category="localisation" enable="true" severity="medium"/>
<eikonenvstatic category="performance" enable="true" severity="medium"/>
<enummembers category="codingstandards" enable="true" severity="low"/>
<enumnames category="codingstandards" enable="true" severity="low"/>
<exportinline category="functionality" enable="true" severity="medium"/>
<exportpurevirtual category="functionality" enable="true" severity="medium"/>
<foff category="codereview" enable="true" severity="low"/>
<forbiddenwords category="codingstandards" enable="true" severity="low">
<wordsRE>Epoc|Nokia Mobile Phones|NMP|(^|\s)S60</wordsRE>
</forbiddenwords>
<forgottoputptroncleanupstack category="codereview" enable="true" severity="low"/>
<friend category="codereview" enable="true" severity="low"/>
<goto category="codingstandards" enable="true" severity="low"/>
<ifassignments category="codingstandards" enable="true" severity="low"/>
<ifpreprocessor category="codingstandards" enable="true" severity="low"/>
<inheritanceorder category="canpanic" enable="true" severity="high"/>
<intleaves category="codereview" enable="true" severity="low"/>
<jmp category="codingstandards" enable="true" severity="low"/>
<leave category="canpanic" enable="true" severity="high"/>
<LeaveNoError category="functionality" enable="true" severity="medium"/>
<leavingoperators category="codereview" enable="true" severity="low"/>
<LFunctionCantLeave category="codereview" enable="true" severity="low"> <LFunctionIgnoreRE>RunL</LFunctionIgnoreRE> </LFunctionCantLeave>
<longlines category="codingstandards" enable="true" length="160" severity="low"/>
<magicnumbers category="codingstandards" enable="true" severity="low"/>
<mclassdestructor category="codingstandards" enable="true" severity="low"/>
<memberlc category="canpanic" enable="true" severity="high"/>
<membervariablecallld category="codingstandards" enable="true" severity="low"/>
<missingcancel category="codingstandards" enable="true" severity="low"/>
<missingcclass category="canpanic" enable="true" severity="high"> <cclassIgnoreRE>CBase</cclassIgnoreRE>
</missingcclass>
<mmpsourcepath category="codingstandards" enable="true" severity="low"/>
<multilangrsc category="codereview" enable="true" severity="low"/>
<multipledeclarations category="codingstandards" enable="true" severity="low"/>
<multipleinheritance category="functionality" enable="true" severity="medium"/>
<mydocs category="functionality" enable="true" severity="medium"/>
<namespace category="codingstandards" enable="true" severity="low"/>
<newlreferences category="codingstandards" enable="true" severity="low"/>
<noleavetrap category="codereview" enable="true" severity="low"/>
<nonconsthbufc category="codingstandards" enable="true" severity="low"/>
<nonconsttdesc category="codingstandards" enable="true" severity="low"/>
<nonleavenew category="codereview" enable="true" severity="low"/>
<nonunicodeskins category="codereview" enable="true" severity="low"/>
<null category="codingstandards" enable="true" severity="low"/>
<open category="canpanic" enable="true" severity="high"> <openIgnoreRE>RDesReadStream|RDesWriteStream</openIgnoreRE>
</open>
<pointertoarrays category="performance" enable="true" severity="medium"/>
<pragmadisable category="codingstandards" enable="true" severity="low"/>
<pragmamessage category="codingstandards" enable="true" severity="low"/>
<pragmaother category="codereview" enable="true" severity="low"/>
<privateinheritance category="codingstandards" enable="true" severity="low"/>
<pushaddrvar category="canpanic" enable="true" severity="high"/>
<pushmember category="canpanic" enable="true" severity="high"/>
<readresource category="canpanic" enable="true" severity="high"/>
<resourcenotoncleanupstack category="codereview" enable="true" severity="low"/>
<resourcesonheap category="codingstandards" enable="true" severity="low"/> <returndescriptoroutofscope category="canpanic" enable="true" severity="high"/>
<rfs category="codereview" enable="true" severity="low"/>
<rssnames category="codereview" enable="true" severity="low"/>
<stringliterals category="codingstandards" enable="true" severity="low"/>
<stringsinresourcefiles category="codereview" enable="true" severity="low"/>
<struct category="codingstandards" enable="true" severity="low"/>
<tcclasses category="functionality" enable="true" severity="medium"/>
<tclassdestructor category="codingstandards" enable="true" severity="low"/>
<todocomments category="codereview" enable="true" severity="low"/>
<trapcleanup category="panic" enable="true" severity="high"/>
<trapeleave category="performance" enable="true" severity="medium"/>
<traprunl category="codingstandards" enable="true" severity="low"/>
<trspassing category="functionality" enable="true" severity="medium"/>
<uids category="codereview" enable="true" severity="low"/>
<uncompressedaif category="performance" enable="true" severity="medium"/>
<uncompressedbmp category="performance" enable="true" severity="medium"/>
<unicodesource category="codereview" enable="true" severity="low"/>
<userafter category="performance" enable="true" severity="medium"/>
<userfree category="codereview" enable="true" severity="low"/>
<userWaitForRequest category="codereview" enable="true" severity="low"/>
<variablenames category="codingstandards" enable="true" severity="low"/>
<voidparameter category="codingstandards" enable="true" severity="low"/>
<worryingcomments category="codereview" enable="true" severity="low"> <worryRE>\!|\?|[Zz]{3}|kludge|workaround|\scrap|hack</worryRE>
</worryingcomments>
</scripts>

#### Severities Element

Each Severities element can contain one or more Severity elements, each of which corresponds to a severity level:

- Severity element The name of each Severity element matches the name of the corresponding severity level. Each Severity element has the following attribute:
  - enable (boolean) – Specifies whether scripts of a particular severity level are enabled by CodeScanner.

Complete list of currently supported Severity elements:

<severities>
<high enable=”true”/>
<medium enable=”true”/>
<low enable=”false”/>
</severities>

#### Categories Element

Each Categories element can contain one or more Category elements, each of which corresponds to a category of CodeScanner scripts:

- Category element The name of each Category element matches the name of the corresponding script category. Each Category element has the following attribute:
  - enable (boolean) – Specifies whether scripts of a particular category are enabled by CodeScanner.

Complete list of currently supported Category elements:

<categories>
<legal enable="true"/>
<panic enable=”true”>
<canpanic enable="true"/>
<functionality enable=”true”/>
<localisation enable="true"/>
<performance enable=”true”>
<codingstandards enable="true"/>
<documentation enable=”false”/>
<codereview enable=”false”/>
<other enable="true"/>
</categories>

#### Customrules Element

Each custom rules element can contain one or more custom rule elements, each of which defines a custom rule to be applied by CodeScanner during scanning operation:

- Custom rule element (<customrule>, </customrule>)

Each custom rule element contains the following elements:

- Name element (<name>, </name>) – The name element specifies the name used by CodeScanner internally to identify a custom rule. A custom rule element can only have one name element.
- Keyword element (<keyword>, </keyword>) – A keyword element specifies a keyword to use when applying a custom rule. A custom rule element can have multiple keyword elements.
  A keyword element also has the following attribute:
  - type(string) – specifies the type of a keyword. Here is a list of currently supported keyword types:
    - baseclass (name of the base class from the declaration of a sub-class)
    - call (name of a called method)
    - class (name used in the declaration/definition of a class)
    - comment (keyword from a comment)
    - generic (keyword used in generic search, i.e. look for anything that matches the keyword)
    - local (name used in the definition of a local variable)
    - macro (name used in the definition of a macro)
    - member (name used in the definition of a data member)
    - method (name used in the declaration/definition of a method)
    - parameter (name of a resource statement parameter)
- File type element (<filetype>, </filetype>) – A file type element specifies a file extension type to scan when applying a custom rule. A custom rule element can have multiple file type elements. This element is required.
- Severity element (<severity>, </severity>) – A severity element specifies the severity level of a custom rule: high, medium or low. A custom rule element can have only one severity element.
- Title element (<title>, </title>) – A title element specifies a title message associated with a custom rule. This is used as the title of HTML report or stdout warning/error message generated when applying a custom rule. A custom rule element can have only one title element.
- Description element (<description>, </description>) – A description element specifies a detailed description of a custom rule. This is used when generating HTML reports or warning/error messages for stdout when applying a custom rule. A custom rule element can have zero or one description element.
- Link element (<link>, </link>) – A link element specifies any external link associated with a custom rule. This is used when generating HTML reports or warning/error messages for stdout when applying a custom rule. A custom rule element can have zero or one link element.

An example of CustomRules element:

<customrules>
<customrule>
<name>myOwnRule</name>
<keyword type=”class”>CMyOwnClass</keyword>
<filetype>h</filetype>
<severity>low</severity>
<title>My own little CodeScanner rule</title>
<description>Locate the definition of CMyOwnClass::MyFunction()</description>
<link>http://www.myownsite.nokia.com</link>
</customrule>
</customrules>