From 59cceaa10ae533210a58089a94c67a5f288443d2 Mon Sep 17 00:00:00 2001
From: Paul Duncan <pabs@pablotron.org>
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/main')
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);
};
--
cgit v1.2.3