eclipse-cs Banner SourceForge.net Logo Support This Project

-- Metadata explained --

As you may know from the previous chapter you can provide metadata for your custom checks to enhance support for your checks inside the plug-in.
The structure and features of such metadata files is described below.

<?xml version="1.0" encoding="UTF-8"?>

<!-- Add the following to any metadata file that is to be validated against this DTD:

<!DOCTYPE checkstyle-metadata PUBLIC
    "-//eclipse-cs//DTD Check Metadata 1.0//EN"
    "http://eclipse-cs.sourceforge.net/dtds/checkstyle-metadata_1_0.dtd">
-->

<!-- 
Root element for every metadata definition.
-->
<!ELEMENT checkstyle-metadata (rule-group-metadata+)>


<!-- 
Used to specify a group of rules.

The 'name' attribute is used as display name and is translatable.

The 'priority' influences the order in which groups appear in the configuration editor.

The 'hidden' attribute can be used to hide an entire group.
-->
<!ELEMENT rule-group-metadata (description?,rule-metadata*)>
<!ATTLIST rule-group-metadata
	name               CDATA        #REQUIRED
	priority           CDATA        #REQUIRED
	hidden             (true|false) "false">

<!--
Used to to provide a textual description for the element.
The content might be translatable.
-->
<!ELEMENT description (#PCDATA)>


<!-- 
'rule-metadata' elements are used to define the metadata for a check (or filter) module.
The 'name' attribute is used as display name and is translatable.

The 'internal-name' attribute defines the logical name of the module.
The internal name must be unique.

The 'checkstyle-module-name' can be used if the internal-name differs from the actual name
	of the checkstyle module that needs to be written to the checkstyle configuration file.
	Most likely this will only be used by users adopting checkstyle for other languages than
	java and want to reuse existing implementations of standard checkstyle checks.
	
The 'parent' element defines if the module is a file set check (Checker as parent)
	or a regular 'TreeWalker' check.
		
The 'hasSeverity' attribute specifies if a module has a severity property that can be set.
Some modules (like filters) have no severity property.
		
The 'hidden' attribute is used to hide a module, so it cannot be seen or 
	configured in the configuration editor. This is only used for some special modules
	like FileContentsHolder. The attribut defaults to 'false'.
		
The 'deletable' attribute is used to specify if the module can be removed from the 
	configuration via the configuration editor. This only makes sense for some 
	special modules like Checker or TreeWalker, which must be present. Therefore
	this attribute default to 'false'.

The 'singleton' module is used to specify if the module should occur only once in
	a checkstyle configuration. This will be taken into account by the configuration editor.
-->
<!ELEMENT rule-metadata (alternative-name+,description?,property-metadata*)>
<!ATTLIST rule-metadata
	name                    CDATA           #REQUIRED
	internal-name           NMTOKEN         #REQUIRED
	checkstyle-module-name  NMTOKEN         #IMPLIED
	parent                  NMTOKEN         #REQUIRED
	hasSeverity             (true|false)    "true"
	hidden                  (true|false)    "false"
	deletable               (true|false)    "true"
	singleton               (true|false)    "false">


<!-- 
Every 'rule-metadata' element must have at least one 'alternative-name' child 
element, which describes under which name the module might occur in a configuration
file as well. As you may know you can specify modules in a Checkstyle configuration
file using the logical module name or the fully qualified class name.
This means that this element is used to map the fully qualified module class name 
to this module.
You are able to provide multiple alternative names, which might be useful if
your package structure for your modules changed over time. In this case specify
the old qualified class names for your module as 'alternative-name' element.
The plug-in is then able to load even Checkstyle configuration files where your old
module names are used.
-->
<!ELEMENT alternative-name EMPTY>
<!ATTLIST alternative-name
	internal-name	CDATA	#REQUIRED>


<!--
'property-metadata' elements are used to describe the properties of a checkstyle
module. Properties described this way can then be configured using the plug-ins
configuration editor.

The 'name' attributes specifies the name of the property.

The 'datatype' attribute determines which kind of data the property contains.

The 'default' attribute is used to specify the default value of the property.

Properties of data type 'MultiCheck' and 'SingleSelect' can (better must) be provided
with an 'enumeration' child element which specifies the valid enumeration values for
this property.
-->
<!ELEMENT property-metadata(description?,enumeration?)>
<!ATTLIST property-metadata
	name            NMTOKEN	#REQUIRED
	datatype        (Boolean|Integer|String|Regex|SingleSelect|MultiCheck|File|Hidden) #REQUIRED
	default-value   CDATA	#IMPLIED>


<!--
The 'enumeration' element is used to provide valid enumeration values for 'MultiCheck'
and 'SingleSelect' properties.
Either the enumeration values are defined using 'property-value-option' child elements
or by an option provider.
An option provider is a java class that implements the interface
'com.atlassw.tools.eclipse.checkstyle.config.meta.IOptionProvider' and provides the 
enumeration values via implementation. This can be useful for providing large amounts
of enumeration values (for instance all checkstyle tokens) or reoccurring sequences of
enumeration values (for instance the java visibility values).
The option provider and 'property-value-option' elements can be mixed together to build
a single enumeration.
-->
<!ELEMENT enumeration (property-value-option*)>
<!ATTLIST enumeration
	option-provider	NMTOKEN	#IMPLIED>


<!--
Specifies a single enumeration value.
-->
<!ELEMENT property-value-option EMPTY>
<!ATTLIST property-value-option
	value	CDATA	#REQUIRED>