java: documentation for Filter, FilterReference, Parser, and ResultHandler

4 files changed, 124 insertions, 15 deletions

diff --git a/java/src/main/java/org/pablotron/luigi/Filter.java b/java/src/main/java/org/pablotron/luigi/Filter.java
index 051ce78..134e406 100644
--- a/java/src/main/java/org/pablotron/luigi/Filter.java
+++ b/java/src/main/java/org/pablotron/luigi/Filter.java
@@ -6,8 +6,30 @@ import java.nio.charset.Charset;
 
 import org.pablotron.luigi.errors.FilterError;
 
+/**
+ * Default filter set and filter handler callback.
+ */
 public final class Filter {
-  public interface Handler {
+  /**
+   * Hide constructor to prevent instantiation.
+   */
+  private Filter() {}
+
+  /**
+   * Filter handler callback interface.
+   */
+  public static interface Handler {
+    /**
+     * Called during template expansion to apply the given filter.
+     *
+     * @param val String value.
+     * @param args Array of filter arguments specified in template string.
+     * @param row Complete map of arguments passed during template run.
+     *
+     * @return Filtered value as a string.
+     *
+     * @throws FilterError If an error occurs during filtering.
+     */
     public String filter(
       String val,
       String args[],
@@ -15,15 +37,48 @@ public final class Filter {
     ) throws FilterError;
   };
 
-  protected static byte[] getBytes(final String val, final String args[]) {
+  /**
+   * Convert given string value to byte array.
+   *
+   * If the length of the argument array is greater than zero, then the
+   * first argument is used as the name of a character set for the input
+   * string.
+   *
+   * @param val String value.
+   * @param args Array of filter arguments.  May be empty.
+   *
+   * @return Byte array.
+   */
+  private static byte[] getBytes(final String val, final String args[]) {
     final Charset charset = (args.length > 0) ? Charset.forName(args[0]) :  Charset.defaultCharset();
     return val.getBytes(charset);
   }
 
-  protected static int toUInt(final byte b) {
+  /**
+   * Convert signed byte to unsigned integer.
+   *
+   * @param b Signed byte value.
+   *
+   * @return Unsigned integer.
+   */
+  private static int toUInt(final byte b) {
     return (b < 0) ? (256 + b) : b;
   }
 
+  /**
+   * Default filter set.
+   *
+   * The default filters are as follows:
+   *
+   * <ul>
+   *   <li><code>uc</code>: Convert string to upper-case.</li>
+   *   <li><code>lc</code>: Convert string to lower-case.</li>
+   *   <li><code>h</code>: HTML-escape string.</li>
+   *   <li><code>u</code>: URL-escape string.</li>
+   *   <li><code>trim</code>: Strip leading and trailing whitespace from string.</li>
+   *   <!-- li><code>base64</code>: Base64-encode value.</li -->
+   * </ul>
+   */
   public static Map<String, Handler> FILTERS = new HashMap<String, Handler>() {{
     put("null", new Handler() {
       public String filter(String val, String args[], Map<String, String> row) {
diff --git a/java/src/main/java/org/pablotron/luigi/FilterReference.java b/java/src/main/java/org/pablotron/luigi/FilterReference.java
index 38c134b..9e45d33 100644
--- a/java/src/main/java/org/pablotron/luigi/FilterReference.java
+++ b/java/src/main/java/org/pablotron/luigi/FilterReference.java
@@ -1,10 +1,23 @@
 package org.pablotron.luigi;
 
+/**
+ * Internal filter reference used during template parsing.
+ */
 public final class FilterReference {
+  /**
+   * Filter name.
+   */
   public final String name;
+
+  /**
+   * Array of filter arguments.
+   */
   public final String[] args;
 
-  public FilterReference(final String name, final String args[]) {
+  /**
+   * Create a new FilterReference with the given name and argument list.
+   */
+  protected FilterReference(final String name, final String args[]) {
     this.name = name;
     this.args = args;
   }
diff --git a/java/src/main/java/org/pablotron/luigi/Parser.java b/java/src/main/java/org/pablotron/luigi/Parser.java
index 01e44f8..b035622 100644
--- a/java/src/main/java/org/pablotron/luigi/Parser.java
+++ b/java/src/main/java/org/pablotron/luigi/Parser.java
@@ -10,13 +10,19 @@ import org.pablotron.luigi.actions.TextAction;
 import org.pablotron.luigi.FilterReference;
 import org.pablotron.luigi.errors.LuigiError;
 
+/**
+ * Internal template string parser.
+ */
 public final class Parser {
+  /**
+   * Template string parsing regular expression.
+   */
   private static final Pattern RE_ACTION = Pattern.compile(
     // match opening brace
-    "%\\{" + 
-      
+    "%\\{" +
+
       // match optional whitespace
-      "\\s*" + 
+      "\\s*" +
 
       // match key
       // "(?<key>[^\\s\\|\\}]+)" +
@@ -28,10 +34,10 @@ public final class Parser {
 
       // match optional whitespace
       "\\s*" +
-    
+
     // match closing brace
     "\\}" +
-    
+
     // or match up all non-% chars or a single % char
     // "| (?<text>[^%]* | %)",
     "| ([^%]* | %)",
@@ -39,30 +45,48 @@ public final class Parser {
     Pattern.COMMENTS
   );
 
+  /**
+   * Filter string parsing regular expression.
+   */
   private static final Pattern RE_FILTER = Pattern.compile(
     // match filter name
     // "(?<name>\\S+)" +
     "(\\S+)" +
-  
+
     // match filter arguments (optional)
     // "(?<args>(\\s*\\S+)*)" +
     "((\\s*\\S+)*)" +
-  
+
     // optional trailing whitespace
     "\\s*",
 
     Pattern.COMMENTS
   );
 
+  /**
+   * Filter chain delimiter.
+   */
   private static final Pattern RE_DELIM_FILTERS = Pattern.compile(
     "\\s*\\|\\s*"
   );
 
+  /**
+   * Filter arguments delimiter.
+   */
   private static final Pattern RE_DELIM_ARGS = Pattern.compile(
     "\\s+"
   );
 
-  public static Action[] parse_template(
+  /**
+   * Parse given template string into an array of actions.
+   *
+   * @param template Template string.
+   *
+   * @return Array of actions.
+   *
+   * @throws LuigiError If parsing fails.
+   */
+  protected static Action[] parse_template(
     final String template
   ) throws LuigiError {
     final ArrayList<Action> r = new ArrayList<Action>();
@@ -73,7 +97,7 @@ public final class Parser {
     while (m.find()) {
       // String key = m.group("key");
       final String key = m.group(1);
-      
+
       if (key != null && key.length() > 0) {
         // r.add(new FilterAction(key, parse_filters(m.group("filters"))));
         r.add(new FilterAction(key, parse_filters(m.group(2))));
@@ -89,7 +113,16 @@ public final class Parser {
 
   private static final String[] NO_ARGS = {};
 
-  public static FilterReference[] parse_filters(
+  /**
+   * Parse given filter string into an array of filter references.
+   *
+   * @param filters_str Filter chain string.
+   *
+   * @return Array of FilterReferences.
+   *
+   * @throws LuigiError If parsing fails.
+   */
+  protected static FilterReference[] parse_filters(
     final String filters_str
   ) throws LuigiError {
     final ArrayList<FilterReference> r = new ArrayList<FilterReference>();
diff --git a/java/src/main/java/org/pablotron/luigi/ResultHandler.java b/java/src/main/java/org/pablotron/luigi/ResultHandler.java
index 32690a2..65654e9 100644
--- a/java/src/main/java/org/pablotron/luigi/ResultHandler.java
+++ b/java/src/main/java/org/pablotron/luigi/ResultHandler.java
@@ -1,5 +1,13 @@
 package org.pablotron.luigi;
 
+/**
+ * Result handler for streamed results from template runs.
+ */
 public interface ResultHandler {
-  public abstract void append(final String s);
+  /**
+   * Called during template run with each chunk of the result.
+   *
+   * @param chunk Chunk of result.
+   */
+  public abstract void append(final String chunk);
 };