From 59cceaa10ae533210a58089a94c67a5f288443d2 Mon Sep 17 00:00:00 2001 From: Paul Duncan Date: Thu, 6 Sep 2018 22:54:51 -0400 Subject: java: documentation for Filter, FilterReference, Parser, and ResultHandler --- java/src/main/java/org/pablotron/luigi/Filter.java | 61 ++++++++++++++++++++-- .../java/org/pablotron/luigi/FilterReference.java | 15 +++++- java/src/main/java/org/pablotron/luigi/Parser.java | 53 +++++++++++++++---- .../java/org/pablotron/luigi/ResultHandler.java | 10 +++- 4 files changed, 124 insertions(+), 15 deletions(-) (limited to 'java/src') 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: + * + * + */ public static Map FILTERS = new HashMap() {{ put("null", new Handler() { public String filter(String val, String args[], Map 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 // "(?[^\\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 // "| (?[^%]* | %)", "| ([^%]* | %)", @@ -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 // "(?\\S+)" + "(\\S+)" + - + // match filter arguments (optional) // "(?(\\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 r = new ArrayList(); @@ -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 r = new ArrayList(); 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); }; -- cgit v1.2.3