Source Code Formatter Tutorial

Introduction

Source Code formatters are use when syntax highlighting source code in the code macro ({code}). SnipSnap ships with serveral formatters, e.g. Java, XML, SQL and none. When you do not supply a formatter to the code macro (e.g. {code:sql}) then the macro will use the default formatter which currently is Java.

Example:
{code}
public void hello() {
String hello = "hello";
}
{code}

will be displayed as:

public void hello() {
   String hello = "hello";
  }

Now you have another language like python and want to use syntax highlighting with your code macro. Then you can write your own formatter and plug it into SnipSnap.

Example

Your source code formatter has to inherit from org.snipsnap.snip.filter.Filter (probably will change to an Interface). A Filter takes an input string and a snip (the context) and returns some string output. Filters are normally used to format snip content.

public abstract class Filter {
  public abstract String filter(String input, Snip snip);
}

Usually this is easier when inheriting from RegexTokenFilter, which implements search and replace using Regular Expressions. The Xml source code formatter looks like this (omitting some \ because of quoting problems):

public class XmlCodeFilter 
  extends RegexReplaceFilter implements SourceCodeFormatter {
  private static final String KEYWORDS = "b(xsl:[^&]*)b";
  private static final String TAGS = "(<.*?>)";
  private static final String QUOTE = ""(([^"]|\.)*)";
  public XmlCodeFilter() {
    super(QUOTE, "<span class="xml-quote">"$1"</class>");
    addRegex(TAGS, "<span class="xml-tag">$1</class>");
    addRegex(KEYWORDS, "<span class="xml-keyword">$1</class>");
  }
}

The constructor of XmlCodeFilter adds some regular expression to the filter, e.g. to format all tags with "xsl:" bold (KEYWORDS), to format tags with lt and gt (TAGS) and to highlight all quotes (QUOTE). The output uses CSS classes to make it easier for users to customize the look.

A small example that highlights the world hello in the code"

public class HelloCodeFilter extends RegexReplaceFilter implements SourceCodeFormatter {
  private static final String KEYWORDS = "hello";
  public HelloCodeFilter() {
    super(KEYWORDS, "<b>$1</b>");
  }
}

Deployment

To write your own formatter, the class has to implement also org.snipsnap.snip.filter.code.SourceCodeFormatter:

public interface SourceCodeFormatter {
  public String getName();
}

To make the formatter work with the code macro you have to first give your formatter a name. We take "hello" for this one. Add a getName method to the formatter:

public String getName() {
    return "hello";
  }

Then implement getPriority(). This is used to load SourceCodeFormatters with the same name. You should always use "0" as priority:

public int getPriority() {
    return 0;
  }

Create a jar file with

META-INF/services/org.radeox.macro.code.SourceCodeFormatter
example/HelloCodeFormatter.class

META-INF/services/org.radeox.macro.code.SourceCodeFormatter should contain lines with the class names of your formatters, for example

example.HelloCodeFormatter

Put this jar into applications/<AppName>/WEB-INF/lib for example if your application is named MyBlog then applications/MyBlog/WEB-INF/lib. Restart the server and the code macro should work with your formatter.