hoglet - Code Handler

Code Handler

The code handler will highlight a chunk of source code. The handler will process/highlight the source code and replace it in a template.

Sections

Features
Handler Options
XML Initialization
Shortcuts
Example Usage
Notes

Features

Will highlight keywords, the keywords are configurable depending upon the language.
Will highlight single and multi-line comments. The delimiters for the comments are configurable.
Will highlight strings. The delimiters for the string are configurable.
Line numbering is supported, the starting line is configurable.
Will format/highlight the content of the tag or a source file can be specified (and optionally specific lines from the file selected).

The handler is implemented by the CodeHandler class and initialized via the XML Configured Processor.

Example:

[java]
public static void main (String argv[])
{
   System.out.println ("Hello World");
}
[java]

Becomes:

public static void main (String argv[])
{
   System.out.println ("Hello World");
}

And:

[java hoglet,org.hoglet.Processor,linenums=y,lines=129:140/]

Becomes:

129:      public String getTagContent (Tag    t)
130:                                   throws HogletException
131:      {
132:  
133:          if (t.getName () == null)
134:          {
135:  
136:              return this.getDefaultTagContent (t);
137:  
138:          }
139:  
140:          TagHandler th = (TagHandler) this.handlers.get (t.getName ());

Handler Options

The handler supports the following options:

Name	Optional	Type	Description
linenums	Yes	Any value	If provided (can be given any value) then line numbers will be prefixed to the start of each source line.
linestart	Yes	Integer	If provided, can be any integer, then the line numbering will start from that number. If not provided then line numbering will start at 1. If this option is NOT specified AND a lines option is specified then line numbering start at the start line value.
linepref	Yes	Any value	If provided then this is appended after the line number. If not specified and line numbering is switched on then it defaults to: : followed by two non-blanking spaces.
lines	Yes	Integer:Integer	Only used if a source file is specified. Should be in the form: [start line]:[end line]. Alternatively just a start line value can be provided. The start line should be a minimum of 1. If both the start and end lines are specified then those lines are retrieved from the file and used as the content. If :[end line] is specified (i.e. no start line is specified) then everything from line 1 to the end line is used as content. If [start line]: or just [start line] is specified then everything from that line to the end of the file is used as content. If end line is less than start line then the end line value is taken to be the number of lines to retrieve from the start line.
sc or anonymous option 1	Yes	Any value	If sc is provided then it is taken to be a shortcut value. If anonymous option 2 is specified then option 1 is taken to be a shortcut value. If anonymous option 2 is NOT specified then option 1 is taken to be a class name or a path to a file (the init attribute fileExtension is used as the file extension).
class or anonymous option 2	Yes	Any value	If class is provided then it is taken to be either a fully-qualified class name or a path to a file (the init attribute fileExtension is used as the file extension). It is the combination of the shortcut (if provided) and the class that determine the file to use to get the content from.

Note: If a class is specified (either via anonymous option 1 or the class option) then the content of the tag is ignored.

XML Initialization

The init element expects to find a keywords element that contains a comma separated list of keywords for the language.

The init element should also contain a templates element that should then contain a wrapper element. The wrapper template will be used to wrap the formatted source and the value: [[VALUE]] will be replaced with the formatted source.

The init element can optionally contain the following templates:

keywordWrapper element - the content of this element is taken as the "wrapper" that should be placed around a keyword. Since a regular expression is used to find the keyword the wrapper should contain $0 to have the matched keyword output. If this is not specified then keyword replacement/highlighting does not occur.
commentWrapper element - the content of this element is taken as the "wrapper" that should be placed around a comment. Since a regular expression is used to find the comment the wrapper should contain $0 to have the matched comment output. If this is not specified then comment replacement/highlighting does not occur.
stringWrapper element - the content of this element is taken as the "wrapper" that should be placed around a string. Since a regular expression is used to find the string the wrapper should contain $0 to have the matched string output. If this is not specified then string replacement/highlighting does not occur.
prefixWrapper element - the content of this element is taken as the "wrapper" that should be placed around any prefix for the line. The prefix will be the combination of the linepref value (or the default) and the line number. If this is not specified then line prefix highlighting does not occur.

The following attributes (set on the init element) can also be specified:

singleLineCommentDelimiter - should be a string indicating the delimiter used to prefix a single line comment, for example: //. If this attribute is not specified then single line comment highlighting does not occur.
multiLineCommentDelimiters - should be in the form: [start delimiter],[end delimiter] indicating the start and end delimiters for a multi-line comment, for example: /*,*/. If this attribute is not specified then multi-line comment highlighting does not occur.
stringDelimiters - should be a comma separated list of single characters that are used to delimit strings, for example: ".
stringEscape - should be a single character that is the escape character for the string delimiter. If stringDelimiters is provided then this attribute must be specified, for example: \.
fileExtension - this is used when the class or option 2 is specified to convert the value into a file. Note: this attribute is mainly aimed at Java formatting.
tabSize - specifies (as an integer) the number of characters that comprise a tab (\t) in the source code. Any tab characters are replaced with this number of blank spaces.

The init element can optionally contain one or more src elements (see shortcuts).

Example:

<init singleLineCommentDelimiter="//"
      multiLineCommentDelimiters="/*,*/"
      stringEscape="\"
      stringDelimiters='"'
      fileExtension=".java"
      tabSize="8">
      <src id="hoglet"
       url="d:/development/hoglet/src" />

      <keywords>public,private,protected,static,final,int,char,try,catch,finally,boolean,abstract,continue,for,new,switch,assert,default,goto,package,synchronized,do,if,this,break,double,implements,throw,byte,else,import,throws,case,enum,instanceof,return,transient,catch,extends,short,interface,void,class,long,strictfp,volatile,const,float,native,super,while,null</keywords>
      <templates>
        <keywordWrapper><[CDATA[<span Class="java-keyword">$0</span>]]></keywordWrapper>
        <wrapper><[CDATA[<div class="source-div"><pre class="source">[[VALUE]]</pre></div>]]></wrapper>
        <commentWrapper><[CDATA[<span Class="comment">$0</span>]]></commentWrapper>
        <stringWrapper><[CDATA[<span Class="string">$0</span>]]></stringWrapper>
        <prefixWrapper><[CDATA[<span Class="prefix">[[VALUE]]</span>]]></prefixWrapper>
      </templates>
    </init>

Shortcuts

To make referencing urls easier the handler supports shortcuts. This is basically a short name that maps to a url prefix (or a full url).

The shortcuts are defined in the init element. The shortcut is defined by using a src element, two attributes id and url are required, the id attribute defines the short name for the shortcut and the url defines the url that it maps to.

Example:

[java hoglet,org.hoglet.Processor/]

There is no limit to the number of shortcuts that can be defined. Shortcut names are case-sensitive.

Example Usage

Format the content of the tag:

[java linenums=y,linestart=10,linepref=*]
public String getValue ()
{

    return this.value;

}
[java]

Would produce:

10*public String getValue ()
11*{
12*
13*    return this.value;
14*
15*}

Format some lines of a source file, specifying a shortcut and a class name:

[java hoglet,org.hoglet.tools.DirectoryProcessor,lines=44:99/]

Would produce:

    public static void main (String argv[])
    {

        if (argv.length < 5)
        {

            System.err.println ("Usage: " + 
                                DirectoryProcessor.class.getName () + 
                                " [xml config file] [input directory] [input file extension] [output directory] [output file extension] <overwrite file> <recurse directories>");

            return;

        }

        boolean overwrite = false;

        if (argv.length > 5)
        {

            overwrite = Boolean.valueOf (argv[5]).booleanValue ();

        }

        boolean recurse = false;

        if (argv.length > 6)
        {

            recurse = Boolean.valueOf (argv[6]).booleanValue ();

        }

        try
        {

            DirectoryProcessor dp = new DirectoryProcessor (new java.io.File (argv[0]));

            dp.processDirectory (new java.io.File (argv[1]),
                                 argv[2],
                                 new java.io.File (argv[3]),
                                 argv[4],
                                 overwrite,
                                 recurse);

            System.out.println ("Processed directory: " +
                                argv[1] +
                                ", written out to: " +
                                argv[3]);

        } catch (Exception e) {

            e.printStackTrace ();

        }

    }

Format a try/catch expression from a source file, specifying the full url and renumber lines:

[java class=d:/development/hoglet/src/org/hoglet/tools/DirectoryProcessor.java,lines=76:97,linenums=y,linestart=1/]

Would produce:

  1:          try
  2:          {
  3:  
  4:              DirectoryProcessor dp = new DirectoryProcessor (new java.io.File (argv[0]));
  5:  
  6:              dp.processDirectory (new java.io.File (argv[1]),
  7:                                   argv[2],
  8:                                   new java.io.File (argv[3]),
  9:                                   argv[4],
 10:                                   overwrite,
 11:                                   recurse);
 12:  
 13:              System.out.println ("Processed directory: " +
 14:                                  argv[1] +
 15:                                  ", written out to: " +
 16:                                  argv[3]);
 17:  
 18:          } catch (Exception e) {
 19:  
 20:              e.printStackTrace ();
 21:  
 22:          }

Notes

The code handler uses a regular expression to make the replacements for the keywords. As such if the tag contains child tags that are converted to HTML then this can produce strange results. For example, since java has class as a keyword and this word also has special meaning in HTML then it can cause formatting problems if you use a javadoc tag for example. In that case you should configure your templates to use something like: Class="myclass" to prevent the regular expression finding that keyword.