From 9f419891d1bdc109c3a487083b5a15ddaef2f7c7 Mon Sep 17 00:00:00 2001 From: Paul Duncan Date: Thu, 6 Sep 2018 22:27:11 -0400 Subject: java: add Template documentation --- .../main/java/org/pablotron/luigi/Template.java | 101 ++++++++++++++++++++- 1 file changed, 98 insertions(+), 3 deletions(-) (limited to 'java/src') 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 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 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 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 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 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 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 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 args, -- cgit v1.2.3