summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPaul Duncan <pabs@pablotron.org>2018-09-06 22:27:11 -0400
committerPaul Duncan <pabs@pablotron.org>2018-09-06 22:27:11 -0400
commit9f419891d1bdc109c3a487083b5a15ddaef2f7c7 (patch)
tree4380c4ec030096c5027285976a97638d531d97e7
parent00da8bf65784b830925718569bde36d1ad43ab4a (diff)
downloadluigi-template-9f419891d1bdc109c3a487083b5a15ddaef2f7c7.tar.bz2
luigi-template-9f419891d1bdc109c3a487083b5a15ddaef2f7c7.zip
java: add Template documentation
-rw-r--r--java/src/main/java/org/pablotron/luigi/Template.java101
1 files changed, 98 insertions, 3 deletions
diff --git a/java/src/main/java/org/pablotron/luigi/Template.java b/java/src/main/java/org/pablotron/luigi/Template.java
index 8ce8793..af3e49b 100644
--- a/java/src/main/java/org/pablotron/luigi/Template.java
+++ b/java/src/main/java/org/pablotron/luigi/Template.java
@@ -4,15 +4,28 @@ import java.util.Map;
import org.pablotron.luigi.Parser;
import org.pablotron.luigi.Filter;
import org.pablotron.luigi.errors.LuigiError;
+import org.pablotron.luigi.errors.LuigiError;
import org.pablotron.luigi.actions.Action;
+/**
+ * Template class.
+ */
public final class Template {
- private static final String VERSION = "0.4.0";
+ /**
+ * Luigi template version.
+ */
+ public static final String VERSION = "0.4.0";
private final String template;
private final Action actions[];
private final Map<String, Filter.Handler> filters;
+ /**
+ * Create a new template with the given string and filter set.
+ *
+ * @param template Template string.
+ * @param filters Map of filter names to filter handlers.
+ */
public Template(
final String template,
final Map<String, Filter.Handler> filters
@@ -22,10 +35,26 @@ public final class Template {
this.actions = Parser.parse_template(template);
}
+ /**
+ * Create a new template with the given string and the default filter
+ * set.
+ *
+ * @param template Template string.
+ */
public Template(final String template) throws LuigiError {
this(template, Filter.FILTERS);
}
+ /**
+ * Run this template with given arguments, then return the result as a
+ * String.
+ *
+ * @param args Template arguments.
+ *
+ * @throws UnknownKeyError If a key specified in the template does not exist.
+ * @throws UnknownFilterError If a filter specified in the template does not exist.
+ * @throws FilterError If a given filter fails.
+ */
public String run(final Map<String, String> args) throws LuigiError {
final StringBuilder r = new StringBuilder();
@@ -35,6 +64,17 @@ public final class Template {
return r.toString();
}
+ /**
+ * Run this template with given arguments, and pass each result chunks
+ * to the given result handler.
+ *
+ * @param args Template arguments.
+ * @param rh Result handler.
+ *
+ * @throws UnknownKeyError If a key specified in the template does not exist.
+ * @throws UnknownFilterError If a filter specified in the template does not exist.
+ * @throws FilterError If a given filter fails.
+ */
public void run(
final Map<String, String> args,
final ResultHandler r
@@ -44,10 +84,26 @@ public final class Template {
}
}
+ /**
+ * Return the original template string for this Template instance.
+ */
public String toString() {
return this.template;
}
+ /**
+ * Create and run template with given arguments, using the default
+ * filter set, then return the result as a String.
+ *
+ * @param template Template string.
+ * @param args Template arguments.
+ *
+ * @return Template expansion result.
+ *
+ * @throws UnknownKeyError If a key specified in the template does not exist.
+ * @throws UnknownFilterError If a filter specified in the template does not exist.
+ * @throws FilterError If a given filter fails.
+ */
public static String run(
final String template,
final Map<String, String> args
@@ -55,14 +111,40 @@ public final class Template {
return Template.run(template, args, Filter.FILTERS);
}
+ /**
+ * Create and run template with given arguments and result handler,
+ * using the default filter set.
+ *
+ * @param template Template string.
+ * @param args Template arguments.
+ * @param rh Result handler that result chunks are passed to.
+ *
+ * @throws UnknownKeyError If a key specified in the template does not exist.
+ * @throws UnknownFilterError If a filter specified in the template does not exist.
+ * @throws FilterError If a given filter fails.
+ */
public static void run(
final String template,
final Map<String, String> args,
- final ResultHandler r
+ final ResultHandler rh
) throws LuigiError {
- run(template, args, Filter.FILTERS, r);
+ run(template, args, Filter.FILTERS, rh);
}
+ /**
+ * Create and run template with given arguments, and filters, then
+ * return the result as a String.
+ *
+ * @param template Template string.
+ * @param args Template arguments.
+ * @param filters Template filters.
+ *
+ * @return Template expansion result.
+ *
+ * @throws UnknownKeyError If a key specified in the template does not exist.
+ * @throws UnknownFilterError If a filter specified in the template does not exist.
+ * @throws FilterError If a given filter fails.
+ */
public static String run(
final String template,
final Map<String, String> args,
@@ -72,6 +154,19 @@ public final class Template {
return t.run(args);
}
+ /**
+ * Create and run template with given arguments, filters, and result
+ * handler.
+ *
+ * @param template Template string.
+ * @param args Template arguments.
+ * @param filters Template filters.
+ * @param rh Result handler that result chunks are passed to.
+ *
+ * @throws UnknownKeyError If a key specified in the template does not exist.
+ * @throws UnknownFilterError If a filter specified in the template does not exist.
+ * @throws FilterError If a given filter fails.
+ */
public static void run(
final String template,
final Map<String, String> args,