CommentOut FilterReader User Manual

Overview

This FilterReader inserts comment tags from the data supplied to it, depending of a token value and a condition name. A section or a line from a Java, XML, HTML or JSP source code can be commented out such as a directive of compilation. The purpose is for instance, to not compile a specific code such as logging functions, to do an application for evaluation, to have a HTML page for a local or remote environment or to not compile test coding when designing by contract.

Three tokens define the type of comments:


A condition name, that follows the token, enables the comments if this name is provided in the condition list. If the condition name of a token does not exist in the condition list, the comments are disabled, even if they were enabled before the parsing.
The comment characters depends how the token is itself commented out (Java line, Java block, HTML/XML/XSLT, JSP).

Parameters

Parameter Name Parameter Value Required
condition A condition name No

Examples

This enable all blocks and lines with 'debug' as condition name. The other blocks and lines with a different condition name are disabled. 

<loadfile srcfile="${src.file}" property="${src.file.contents}">
  <filterchain>
    <filterreader classname="net.sourceforge.serialver.CommentOut">
      <param name="condition" value="debug"/>
    </filterreader>
  </filterchain>
</loadfile>

This disable all commented blocks and lines. This is like a reset. 

<loadfile srcfile="${src.file}" property="${src.file.contents}">
  <filterchain>
    <filterreader classname="net.sourceforge.serialver.CommentOut"/>
  </filterchain>
</loadfile>

Parsing examples:

This example shows the parsing on a Java file with one condition set to 'debug'. 

/*
license
*/
package tests;
/**
 * Test
 */ 
public class Test {
    // Constructor
    public Test() {
        /* Do nothing */
    }
    
    public void method() {
        log("-->method()"); // @IF_LINE@ debug
        
        enableSaveNenu(); // @IF_LINE@ evaluation
        
        /* @IF_LINE@ debug */ log("<--method()");
    }
    
    /* @IF_BLOCK@ debug */
    private void log(String message) {
        
    }
    // @IF_END@ debug
    
    private void enableSaveNenu() {
        String label = "Save";
//        label = getResources("SaveMenu"); // @IF_LINE@ localization
      
    }
}
The result is: 
/*
license
*/
package tests;
/**
 * Test
 */ 
public class Test {
    // Constructor
    public Test() {
        /* Do nothing */
    }
    
    public void method() {
//        log("-->method()"); // @IF_LINE@ debug
        
        enableSaveNenu(); // @IF_LINE@ evaluation
        
/*        /* @IF_LINE@ debug log("<--method()");*/
    }
    
    /* @IF_BLOCK@ debug
    private void log(String message) {
        
    }
    // @IF_END@ debug */
    
    private void enableSaveNenu() {
        String label = "Save";
        label = getResources("SaveMenu"); // @IF_LINE@ localization
      
    }
}

Conversions list

The 'aa' string represents the beginning of the line, and the 'bb' string the end of the line. Their values can be an empty string. The number of spaces before and after the comment characters or between the tokens and the condition names do not matter. The other comments (without token) are preserved. If the syntax is wrong, the line is untouched.

Line declaration
(source code)		 Condition name is defined
(enable comments)		 Condition name is not defined
(disable comments)
@IF_LINE@
aa // @IF_LINE@ conditionName bb //aa // @IF_LINE@ conditionName bb aa // @IF_LINE@ conditionName bb
//aa // @IF_LINE@ conditionName bb //aa // @IF_LINE@ conditionName bb aa // @IF_LINE@ conditionName bb
aa /* @IF_LINE@ conditionName */ bb /*aa /* @IF_LINE@ conditionName bb*/ aa /* @IF_LINE@ conditionName */ bb
/*aa /* @IF_LINE@ conditionName bb*/ /*aa /* @IF_LINE@ conditionName bb*/ aa /* @IF_LINE@ conditionName */ bb
aa <!-- @IF_LINE@ conditionName --> bb <!--aa <!-- @IF_LINE@ conditionName bb--> aa <!-- @IF_LINE@ conditionName --> bb
<!--aa <!-- @IF_LINE@ conditionName bb--> <!--aa <!-- @IF_LINE@ conditionName bb--> aa <!-- @IF_LINE@ conditionName --> bb
aa <%-- @IF_LINE@ conditionName --%> bb <%--aa <%-- @IF_LINE@ conditionName bb--%> aa <%-- @IF_LINE@ conditionName --%> bb
<%--aa <%-- @IF_LINE@ conditionName bb--%> <%--aa <%-- @IF_LINE@ conditionName bb--%> aa <%-- @IF_LINE@ conditionName --%> bb
@IF_BLOCK@
aa // @IF_BLOCK@ conditionName bb aa /* // @IF_BLOCK@ conditionName bb aa // @IF_BLOCK@ conditionName bb
aa /* // @IF_BLOCK@ conditionName bb aa /* // @IF_BLOCK@ conditionName bb aa // @IF_BLOCK@ conditionName bb
aa /* @IF_BLOCK@ conditionName */ bb aa /* @IF_BLOCK@ conditionName bb aa /* @IF_BLOCK@ conditionName */ bb
aa /* @IF_BLOCK@ conditionName bb aa /* @IF_BLOCK@ conditionName bb aa /* @IF_BLOCK@ conditionName */ bb
aa <!-- @IF_BLOCK@ conditionName --> bb aa <!-- @IF_BLOCK@ conditionName bb aa <!-- @IF_BLOCK@ conditionName --> bb
aa <!-- @IF_BLOCK@ conditionName bb aa <!-- @IF_BLOCK@ conditionName bb aa <!-- @IF_BLOCK@ conditionName --> bb
aa <%-- @IF_BLOCK@ conditionName --%> bb aa <%-- @IF_BLOCK@ conditionName bb aa <%-- @IF_BLOCK@ conditionName --%> bb
aa <%-- @IF_BLOCK@ conditionName bb aa <%-- @IF_BLOCK@ conditionName bb aa <%-- @IF_BLOCK@ conditionName --%> bb
@IF_END@
aa // @IF_END@ conditionName bb aa // @IF_END@ conditionName */ bb aa // @IF_END@ conditionName bb
aa // @IF_END@ conditionName */ bb aa // @IF_END@ conditionName */ bb aa // @IF_END@ conditionName bb
aa /* @IF_END@ conditionName */ bb aa @IF_END@ conditionName */ bb aa /* @IF_END@ conditionName */ bb
aa @IF_END@ conditionName */ bb aa @IF_END@ conditionName */ bb aa /* @IF_END@ conditionName */ bb
aa <!-- @IF_END@ conditionName --> bb aa @IF_END@ conditionName --> bb aa <!-- @IF_END@ conditionName --> bb
aa @IF_END@ conditionName --> bb aa @IF_END@ conditionName --> bb aa <!-- @IF_END@ conditionName --> bb
aa <%-- @IF_END@ conditionName --%> bb aa @IF_END@ conditionName --%> bb aa <%-- @IF_END@ conditionName --%> bb
aa @IF_END@ conditionName --%> bb aa @IF_END@ conditionName --%> bb aa <%-- @IF_END@ conditionName --%> bb

By Stéphane Chauvin (stchauvin@users.sourceforge.net)

Copyright © 2002 Apache Software Foundation. All rights Reserved.