Cs-contrib.unkrig.de: Difference between revisions

From unkrig.de
Jump to navigation Jump to search
 
(36 intermediate revisions by the same user not shown)
Line 1: Line 1:
<meta name="keywords" content="checkstyle, checks, filters, quickfixes"></meta>
<meta name="description" content="Custom checks, filters and quickfixes for checkstyle and eclipse-cs"></meta>
= Introduction =
= Introduction =
This project adds custom checks, filters and for [http://checkstyle.sourceforge.net/ CheckStyle] and [http://eclipse-cs.sourceforge.net/ Eclipse-CS].
This project adds custom checks, filters and quickfixes for [http://checkstyle.sourceforge.net/ CheckStyle] and [http://eclipse-cs.sourceforge.net/ Eclipse-CS].
 
This project uses the [[Cs-doclet|CS doclet]] (internally) to generate its CheckStyle and eclipse-cs metadata files.
 
Cs-contrib 1.2.21+ requires the CheckStyle core version 8.21+, because there was an (accidential) breaking change in that version.


= Download =
= Download =
Line 13: Line 19:
A [http://cs-contrib.unkrig.de/CHANGELOG.txt change log] is also available.
A [http://cs-contrib.unkrig.de/CHANGELOG.txt change log] is also available.


= Checks =
= Documentation =
 
== Check 'de.unkrig.Alignment' ==
Checks that Java elements are vertically aligned in immediately consecutive lines (and only there!).
 
public class Main {
    int    <font color="red">x</font> = 7;
    double <font color="red">xxx</font> = 7.0;              // Aligned field names
    int y      <font color="red">=</font> 7;
    double yyy <font color="red">=</font> 7.0;              // Aligned field initializers
    public static void meth1(
        String[] <font color="red">p1</font>,
        int      <font color="red">p2</font>                // Aligned parameter names
    ) {
        int    <font color="red">x</font> = 7;\n\
        double <font color="red">xxx</font> = 7.0;          // Aligned local variable names
        int y      <font color="red">=</font> 7;\n\
        double yyy <font color="red">=</font> 7.0;          // Aligned local variable initializers
        y  <font color="red">=</font> 8;
        yyy <font color="red">=</font> 8.0;                // Aligned assignments
        switch (x) {
        case 1:  <font color="red">break;</font>
        default: <font color="red">x++;</font> return;      // Aligned case groups statements
        }
    }
    public static void <font color="red">meth2</font>()  <font color="red">{}</font>
    public void        <font color="red">meth33</font>() <font color="red">{}</font> // Aligned method names and bodies
}
 
'''Properties:'''
;applyToFieldName                : Check alignment of field names in declarations.
;applyToFieldInitializer        : Check alignment of '=' in field declarations.
;applyToLocalVariableName        : Check alignment of local variable names in declarations.
;applyToLocalVariableInitializer : Check alignment of '=' in local variable declarations.
;applyToParameterName            : Check alignment of constructor and method parameter names.
;applyToMethodName              : Check alignment of method (and constructor) names in declarations.
;applyToMethodBody              : Check alignment of '{' in method (and constructor) declarations.
;applyToCaseGroupStatements      : Check alignment of first statement in case groups.
;applyToAssignments              : Check alignment of '=' in assignments.
 
== Check 'de.unkrig.InnerAssignment' ==
Assignments in expressions must be parenthesized.
 
'''Quickfixes:'''
;Parenthesize assignment : Parenthesize assignment to indicate that it is intentional
 
== Check 'de.unkrig.NameSpelling' ==
 
'''Description:'''
 
Checks that the names of Java elements match resp. no not match given patterns.
 
This check makes name checking more powerful, compared with CheckStyle's standard "Naming Conventions" checks:
* Arbitrary sets of required/forbidden modifiers can be specified
* Name patterns can not only be ''enforced'' but also be ''forbidden'' (useful, e.g., to forbid certains styles of hungarian notation)
* Adds the possibility to check the names of annotations, annotation fields, enums and enum constants (which are missing from the standard checks)
 
This check supersedes all of the CheckStyle standard "Naming Conventions" checks:
* Abstract Class Name
* Class Type Parameter Name
* Constant Names
* Local Final Variable Names
* Local Variable Names
* Member Names
* Method Names
* Method Type Parameter Name
* Package Names
* Parameter Names
* Static Variable Names
* Type Names
 
'''Properties:'''
;elements          : Elements to apply this check to (annotation, annotation_field, catch_parameter, class, enum, enum_constant, for_variable, foreach_variable, field, formal_parameter, interface, local_variable, method, package and/or type_parameter)
;requiredModifiers : Apply only to declarations which have these modifiers
;missingModifiers  : Apply only to declarations which do not have these modifiers
;option            : Whether to ''require'' or ''forbid'' that names match
;format            : Pattern to match the name against
 
== Check 'de.unkrig.ParenPad' ==
Enhanced version of "ParenPad": NOSPACE now allows '( // ...'.
 
<span style="color: red">'''This check is superseded by '[[#Check 'de.unkrig.Whitespace'|de.unkrig.Whitespace]]'.'''</span>
 
'''Properties:'''
;option : Whether space is required or forbidding
;tokens : Tokens to check


== Check 'de.unkrig.Whitespace' ==
The [http://cs-contrib.unkrig.de/csdoc/ documentation for the cs-contrib checks, filters and quickfixes] was generated by the [http://doclet.unkrig.de CS doclet]
Checks that tokens are (or are not) preceded with (and/or followed by) whitespace.
 
This check supersedes all of CheckStyle's whitespace-related checks:
* Generic Whitespace
* Empty For Initializer Pad
* Empty For Iterator Pad
* No Whitespace After
* No Whitespace Before
* Method Parameter Pad
* Paren Pad
* Typecast Paren Pad
* Whitespace After
* Whitespace Around
, as well as
* de.unkrig.ParenPad
* de.unkrig.WhitespaceAround
.
 
=== Properties ===
;whitespaceBefore:  The Java elements which must be preceded with whitespace (or a line break)
;noWhitespaceBefore: The Java elements which must not be preceded with whitespace (or are preceded with a line break)
;whitespaceAfter:    The Java elements which must be followed by whitespace (or a line break)
;noWhitespaceAfter:  The Java elements which must not be followed by whitespace (or are followed by a line break)
 
=== Java Elements ===
The properties described above represent the "Java elements" to which each property applies. "Java elements" correspond roughly with the Java tokens, but some Java tokens can appear in different contexts where they have different meanings. The latter case is represented by ''multiple'' Java elements which relate to the same Java token, but to different contexts (see example below).
 
The list of Java elements is long and mostly self-explanatory; for illustration, the first few Java elements are listed here:
 
;abstract:        <font color="red">abstract</font> class MyClass { ... }<br/><font color="red">abstract</font> myMethod(...) { ... }
;and__expr:      a <font color="red">&amp;</font> b
;and__type_bound: &lt;T extends MyClass <font color="red">&amp;</font> MyInterface>
;and_assign:      a <font color="red">&amp;=</font> b
;assert:          <font color="red">assert</font> x == 0;<br/><font color="red">assert</font> x == 0 : "x not zero";
;...
 
The tokens 'abstract', '&=' and 'assert' can appear in only one context each, while the token '&' has two different meanings. Thus there are two Java elements starting with 'and' and two underscores. (The double underscore separates the token name from the context name.)
 
Notice that 'and_assign' ('&amp;=') and 'and' ('&amp;') are '''different''' tokens which you can recognize by the ''single'' underscore in 'and_assign'.
 
== Check 'de.unkrig.WhitespaceAround' ==
Checks that a token is surrounded by whitespace. Empty constructor bodies, method bodies, catch blocks and type bodies of the form
 
<span style="color: red">'''This check is superseded by '[[#Check 'de.unkrig.Whitespace'|de.unkrig.Whitespace]]'.'''</span>
 
public MyClass() {}          // empty constructor body
public void func() {}        // empty method body
public void func() {
    new Object() {
        // ...
    }.hashCode();            // No space between '}' and '.' -- always allowed
    try {
        // ...
    } catch {}                // empty catch block
}
interface MyInterface {}      // emtpy type body
 
may optionally be exempted from the policy using the <code>allowEmptyMethods</code>, <code>allowEmptyConstructors</code>, <code>allowEmptyCatches</code> and <code>allowEmptyTypes</code> properties.
 
'''Properties:'''
;allowEmptyConstructors : allow empty constructor bodies
;allowEmptyMethods      : allow empty method bodies
;allowEmptyCatches      : allow empty catch blocks
;allowEmptyTypes        : allow empty class and interface bodies
;tokens                : Tokens to check
 
== Check 'de.unkrig.WrapAndIndent' ==
Statements must be uniformly wrapped and indented.
 
'''Properties:'''
;basicOffset : How many spaces to use for new indentation level
 
'''Quickfixes:'''
;Wrap line          : Wrap this line at the correct position
;Join lines          : Append this line to the previous
;Correct indentation : Correct the indentation of this line
 
== Check 'de.unkrig.ZeroParameterSuperconstructorInvocation' ==
Checks that no constructor calls the zero-parameter superconstructor.
 
'''Quickfixes:'''
;Remove : Remove redundant invocation of zero-parameter superconstructor
 
= Filters =
 
== Filter 'de.unkrig.SuppressionLine' ==
Events (i.e. CheckStyle warnings) are switched off by a 'magic line' ('offCommentFormat') or back on by another 'magic line' ('onCommentFormat').
 
After the 'off' magic line, events do not show if at least one of the following conditions is true:
* The 'checkNameFormat' (if set) is found in the check name (e.g. 'de.unkrig.cscontrib.checks.Alignment')
* The 'messageFormat' (if set) is found in the event message
* The 'moduleIdFormat' (if set) is found in the ID of the module that generated the event
This filter can only work if a 'FileContentsHolder' module exists in the configuration.
 
'''Properties:'''
;offFormat      : Line pattern to trigger filter to begin suppression
;onFormat        : Line pattern to trigger filter to end suppression
;checkNameFormat : Check name pattern to suppress
;messageFormat  : Message pattern to suppress
;moduleIdFormat  : Module ID pattern to suppress


= License =
= License =
Line 219: Line 29:
= Source Code =
= Source Code =


The source code is available through SVN:
The source code of <code>cs-contrib</code> (the CheckStyle extension) is on GITHUB:
 
    https://github.com/aunkrig/cs-contrib/
 
The source code of the Eclipse plugin (<code>.core</code>, <code>.branding</code>, <code>.feature</code>, <code>.updatesite</code>) is also on GITHUB:


     https://svn.code.sf.net/p/loggifier/code
     https://github.com/aunkrig/cs-contrib.branding
    https://github.com/aunkrig/cs-contrib.core
    https://github.com/aunkrig/cs-contrib.core_test
    https://github.com/aunkrig/cs-contrib.feature
    https://github.com/aunkrig/cs-contrib.updatesite
    https://github.com/aunkrig/cs-contrib_dist

Latest revision as of 12:25, 19 January 2022

<meta name="keywords" content="checkstyle, checks, filters, quickfixes"></meta> <meta name="description" content="Custom checks, filters and quickfixes for checkstyle and eclipse-cs"></meta>

Introduction[edit]

This project adds custom checks, filters and quickfixes for CheckStyle and Eclipse-CS.

This project uses the CS doclet (internally) to generate its CheckStyle and eclipse-cs metadata files.

Cs-contrib 1.2.21+ requires the CheckStyle core version 8.21+, because there was an (accidential) breaking change in that version.

Download[edit]

Install the ECLIPSE plug-in from this update site:

    http://cs-contrib.unkrig.de/update

If you're only interested in the checks (and not the ECLIPSE plug-in), you can download the most recent 'de.unkrig.cs-contrib.core_*.jar' file from

    http://cs-contrib.unkrig.de/update/plugins/

and put it on CheckStyle's classpath.

A change log is also available.

Documentation[edit]

The documentation for the cs-contrib checks, filters and quickfixes was generated by the CS doclet

License[edit]

CS-CONTRIB.UNKRIG.DE is published under the "New BSD License".

Source Code[edit]

The source code of cs-contrib (the CheckStyle extension) is on GITHUB:

   https://github.com/aunkrig/cs-contrib/

The source code of the Eclipse plugin (.core, .branding, .feature, .updatesite) is also on GITHUB:

   https://github.com/aunkrig/cs-contrib.branding
   https://github.com/aunkrig/cs-contrib.core
   https://github.com/aunkrig/cs-contrib.core_test
   https://github.com/aunkrig/cs-contrib.feature
   https://github.com/aunkrig/cs-contrib.updatesite
   https://github.com/aunkrig/cs-contrib_dist