This is an automated email from the ASF dual-hosted git repository. sgoeschl pushed a commit to branch FREEMARKER-141 in repository https://gitbox.apache.org/repos/asf/freemarker-generator.git
commit 79c669eaf345e115207a6df5eb6bf9f66b76b93c Author: Siegfried Goeschl <[email protected]> AuthorDate: Thu Apr 16 00:25:05 2020 +0200 FREEMARKER-141 freemarker-cli: Expose user-supplied parameters in the data model --- .../base/activation/CachingUrlDataSource.java | 16 ++++++++++ .../generator/base/activation/Mimetypes.java | 16 ++++++++++ .../generator/base/datasource/DataSource.java | 5 ++- .../base/parameter/ParameterModelSupplier.java | 7 ++-- .../org/apache/freemarker/generator/cli/Main.java | 5 ++- .../freemarker/generator/cli/config/Settings.java | 12 +++---- .../freemarker/generator/cli/config/Suppliers.java | 6 ++-- .../generator/cli/task/FreeMarkerTask.java | 5 +-- .../src/site/markdown/cli/concepts/named-uris.md | 14 ++++---- .../site/markdown/cli/concepts/user-parameters.md | 37 ++++++++++++++++++++++ .../src/site/markdown/index.md | 1 + .../freemarker/generator/cli/ManualTest.java | 4 +-- .../generator/cli/config/SettingsTest.java | 2 +- freemarker-generator-cli/templates/info.ftl | 12 ++++--- 14 files changed, 106 insertions(+), 36 deletions(-) diff --git a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/activation/CachingUrlDataSource.java b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/activation/CachingUrlDataSource.java index 24e02ac..6616598 100644 --- a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/activation/CachingUrlDataSource.java +++ b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/activation/CachingUrlDataSource.java @@ -1,3 +1,19 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ package org.apache.freemarker.generator.base.activation; import javax.activation.URLDataSource; diff --git a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/activation/Mimetypes.java b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/activation/Mimetypes.java index 5bb4ebe..3a18a86 100644 --- a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/activation/Mimetypes.java +++ b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/activation/Mimetypes.java @@ -1,3 +1,19 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ package org.apache.freemarker.generator.base.activation; public class Mimetypes { diff --git a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/datasource/DataSource.java b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/datasource/DataSource.java index 4864dc6..94acf92 100644 --- a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/datasource/DataSource.java +++ b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/datasource/DataSource.java @@ -34,7 +34,6 @@ import java.util.List; import java.util.regex.Matcher; import java.util.regex.Pattern; -import static java.nio.charset.Charset.forName; import static java.nio.charset.StandardCharsets.UTF_8; import static java.util.Objects.requireNonNull; import static org.apache.commons.io.IOUtils.lineIterator; @@ -172,7 +171,7 @@ public class DataSource implements Closeable { public String getText(String charsetName) { final StringWriter writer = new StringWriter(); try (InputStream is = getUnsafeInputStream()) { - IOUtils.copy(is, writer, forName(charsetName)); + IOUtils.copy(is, writer, Charset.forName(charsetName)); return writer.toString(); } catch (IOException e) { throw new RuntimeException("Failed to get text: " + toString(), e); @@ -224,7 +223,7 @@ public class DataSource implements Closeable { */ public LineIterator getLineIterator(String charsetName) { try { - return closables.add(lineIterator(getUnsafeInputStream(), forName(charsetName))); + return closables.add(lineIterator(getUnsafeInputStream(), Charset.forName(charsetName))); } catch (IOException e) { throw new RuntimeException("Failed to create line iterator: " + toString(), e); } diff --git a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/parameter/ParameterModelSupplier.java b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/parameter/ParameterModelSupplier.java index da5a757..ac74090 100644 --- a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/parameter/ParameterModelSupplier.java +++ b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/parameter/ParameterModelSupplier.java @@ -16,22 +16,21 @@ */ package org.apache.freemarker.generator.base.parameter; +import java.util.Collections; import java.util.HashMap; import java.util.Map; import java.util.function.Supplier; -import static java.util.Objects.requireNonNull; - /** * Converts a map of parameters to a map. The resulting map contains - * either (key -> String) or (key -> Map<String, Object>). + * either (key=String) or (key=Map<String, Object>). */ public class ParameterModelSupplier implements Supplier<Map<String, Object>> { private final Map<String, String> parameters; public ParameterModelSupplier(Map<String, String> parameters) { - this.parameters = requireNonNull(parameters); + this.parameters = parameters != null ? parameters : Collections.emptyMap(); } @Override diff --git a/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/Main.java b/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/Main.java index 99d1876..60b0ccc 100644 --- a/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/Main.java +++ b/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/Main.java @@ -17,6 +17,7 @@ package org.apache.freemarker.generator.cli; import org.apache.freemarker.generator.base.FreeMarkerConstants.GeneratorMode; +import org.apache.freemarker.generator.base.parameter.ParameterModelSupplier; import org.apache.freemarker.generator.base.util.ClosableUtils; import org.apache.freemarker.generator.base.util.StringUtils; import org.apache.freemarker.generator.cli.config.Settings; @@ -205,6 +206,8 @@ public class Main implements Callable<Integer> { } private Settings settings(Properties configuration, List<File> templateDirectories) { + final ParameterModelSupplier parameterModelSupplier = new ParameterModelSupplier(parameters); + return Settings.builder() .isReadFromStdin(readFromStdin) .setArgs(args) @@ -216,7 +219,7 @@ public class Main implements Callable<Integer> { .setLocale(locale) .setOutputEncoding(outputEncoding) .setOutputFile(outputFile) - .setParameters(parameters != null ? parameters : new HashMap<>()) + .setParameters(parameterModelSupplier.get()) .setDataSources(getCombindedDataSources()) .setDataModels(dataModels) .setSystemProperties(systemProperties != null ? systemProperties : new Properties()) diff --git a/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/config/Settings.java b/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/config/Settings.java index e3151bf..5163aed 100644 --- a/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/config/Settings.java +++ b/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/config/Settings.java @@ -86,10 +86,10 @@ public class Settings { private final List<String> dataSources; /** User-supplied list of data sources directly exposed in the data model */ - private List<String> dataModels; + private final List<String> dataModels; /** User-supplied parameters */ - private final Map<String, String> parameters; + private final Map<String, Object> parameters; /** User-supplied system properties */ private final Properties sytemProperties; @@ -113,7 +113,7 @@ public class Settings { boolean isReadFromStdin, List<String> dataSources, List<String> dataModels, - Map<String, String> parameters, + Map<String, Object> parameters, Properties sytemProperties, Writer writer) { if (isEmpty(template) && isEmpty(interactiveTemplate)) { @@ -208,7 +208,7 @@ public class Settings { return dataModels; } - public Map<String, String> getParameters() { + public Map<String, Object> getParameters() { return parameters; } @@ -282,7 +282,7 @@ public class Settings { private boolean isReadFromStdin; private List<String> dataSources; private List<String> dataModels; - private Map<String, String> parameters; + private Map<String, Object> parameters; private Properties systemProperties; private Properties configuration; private Writer writer; @@ -383,7 +383,7 @@ public class Settings { return this; } - public SettingsBuilder setParameters(Map<String, String> parameters) { + public SettingsBuilder setParameters(Map<String, Object> parameters) { if (parameters != null) { this.parameters = parameters; } diff --git a/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/config/Suppliers.java b/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/config/Suppliers.java index 9937610..6a57e59 100644 --- a/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/config/Suppliers.java +++ b/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/config/Suppliers.java @@ -21,8 +21,8 @@ import org.apache.freemarker.generator.base.datasource.DataSourcesSupplier; import org.apache.freemarker.generator.base.file.PropertiesClassPathSupplier; import org.apache.freemarker.generator.base.file.PropertiesFileSystemSupplier; import org.apache.freemarker.generator.base.file.PropertiesSupplier; -import org.apache.freemarker.generator.base.parameter.ParameterModelSupplier; +import java.util.Map; import java.util.function.Supplier; /** @@ -61,8 +61,8 @@ public class Suppliers { return new DataModelSupplier(settings.getDataModels()); } - public static ParameterModelSupplier parameterSupplier(Settings settings) { - return new ParameterModelSupplier(settings.getParameters()); + public static Supplier<Map<String, Object>> parameterSupplier(Settings settings) { + return settings::getParameters; } public static PropertiesSupplier propertiesSupplier(String fileName) { diff --git a/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/task/FreeMarkerTask.java b/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/task/FreeMarkerTask.java index 549078c..803b9c2 100644 --- a/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/task/FreeMarkerTask.java +++ b/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/task/FreeMarkerTask.java @@ -89,7 +89,7 @@ public class FreeMarkerTask implements Callable<Integer> { public Integer call() { final Template template = template(settings, configurationSupplier); try (Writer writer = settings.getWriter(); DataSources dataSources = dataSources(settings, dataSourcesSupplier)) { - final Map<String, Object> dataModel = dataModel(settings, dataSources, parameterModelSupplier, dataModelsSupplier, toolsSupplier); + final Map<String, Object> dataModel = dataModel(dataSources, parameterModelSupplier, dataModelsSupplier, toolsSupplier); template.process(dataModel, writer); return SUCCESS; } catch (RuntimeException e) { @@ -140,18 +140,15 @@ public class FreeMarkerTask implements Callable<Integer> { } private static Map<String, Object> dataModel( - Settings settings, DataSources dataSources, Supplier<Map<String, Object>> parameterModelSupplier, Supplier<Map<String, Object>> dataModelsSupplier, Supplier<Map<String, Object>> tools) { final Map<String, Object> result = new HashMap<>(); - result.putAll(dataModelsSupplier.get()); result.put(DATASOURCES, dataSources); result.putAll(parameterModelSupplier.get()); result.putAll(tools.get()); - return result; } diff --git a/freemarker-generator-cli/src/site/markdown/cli/concepts/named-uris.md b/freemarker-generator-cli/src/site/markdown/cli/concepts/named-uris.md index 2a2469e..7ab78e8 100644 --- a/freemarker-generator-cli/src/site/markdown/cli/concepts/named-uris.md +++ b/freemarker-generator-cli/src/site/markdown/cli/concepts/named-uris.md @@ -18,13 +18,13 @@ scheme authority path query fragment For our purposes, the scheme and the path components are especially important, though the other components are used by certain datasources for particular purposes. -| Component | Purpose | -|-----------|---------| -| scheme | All datasources require a scheme (except for file when using relative paths) | -| authority | Used only by remote datasources, and can be omitted in some of those cases. Consists of userinfo (user:pass), host, and port. | -| path | Can be omitted, but usually used as the basis of the locator for the datasource. | -| query | Used mainly for HTTP and HTTPS URLs | -| fragment | Used rarely for providing additional attributes, e.g. `mimetype` of `charset` | +| Component | Purpose | +|-----------|-----------------------------------------------------------------------------------------------------------| +| scheme | All datasources require a scheme (except for file when using relative paths) | +| authority | Used only by remote datasources, and can be omitted in some of those cases. | +| path | Can be omitted, but usually used as the basis of the locator for the datasource. | +| query | Used mainly for HTTP and HTTPS URLs | +| fragment | Used rarely for providing additional attributes, e.g. `mimetype` of `charset` | The following Named URI loads a "user.csv" and the data source is available as `my_users` diff --git a/freemarker-generator-cli/src/site/markdown/cli/concepts/user-parameters.md b/freemarker-generator-cli/src/site/markdown/cli/concepts/user-parameters.md new file mode 100644 index 0000000..46f2d2e --- /dev/null +++ b/freemarker-generator-cli/src/site/markdown/cli/concepts/user-parameters.md @@ -0,0 +1,37 @@ +# User-Supplied Parameters + +User-supplied parameters allow to pass additional information to an Apache FreeMarker template + +* `-Pname=value` to define a key/value pair +* `-Pname:group=value` to define a map containing key/value pairs, i.e nested map + +Pass a simple name/value pair on the command line + +``` +> bin/freemarker-cli -t templates/info.ftl -P key=value + +User Supplied Parameters +------------------------------------------------------------------------------ +- key ==> value +``` + +By providing a `group` you can create nested maps + +``` +> bin/freemarker-cli -t templates/info.ftl -P foo1:group=bar1 -P foo2:group=bar2 + +User Supplied Parameters +------------------------------------------------------------------------------ +- group ==> { foo1=bar1 foo2=bar2 } +``` + +It is also possible to mix and match the two approaches + +``` +> bin/freemarker-cli -t templates/info.ftl -P foo1:group=bar1 -P foo2:group=bar2 -P key=value + +User Supplied Parameters +------------------------------------------------------------------------------ +- key ==> value +- group ==> { foo1=bar1 foo2=bar2 } +``` \ No newline at end of file diff --git a/freemarker-generator-cli/src/site/markdown/index.md b/freemarker-generator-cli/src/site/markdown/index.md index c5807bc..791ab12 100644 --- a/freemarker-generator-cli/src/site/markdown/index.md +++ b/freemarker-generator-cli/src/site/markdown/index.md @@ -2,5 +2,6 @@ ### Concepts +* [User-Supplied Parameters](cli/concepts/user-parameters.html) * [Named URIs](cli/concepts/named-uris.html) * [Data Models](cli/concepts/data-models.html) \ No newline at end of file diff --git a/freemarker-generator-cli/src/test/java/org/apache/freemarker/generator/cli/ManualTest.java b/freemarker-generator-cli/src/test/java/org/apache/freemarker/generator/cli/ManualTest.java index c6eb230..210f32f 100644 --- a/freemarker-generator-cli/src/test/java/org/apache/freemarker/generator/cli/ManualTest.java +++ b/freemarker-generator-cli/src/test/java/org/apache/freemarker/generator/cli/ManualTest.java @@ -28,7 +28,7 @@ public class ManualTest { // private static final String CMD = "-b ./src/test -l de_AT -DFOO=foo -DBAR=bar -t templates/info.ftl site/sample/csv/transactions.csv"; // private static final String CMD = "-b ./src/test -DFOO=foo -PBAR=bar -l de -t templates/demo.ftl site/sample/csv/transactions.csv"; // private static final String CMD = "-b ./src/test -DFOO=foo -PBAR=bar -t templates/demo.ftl site/sample/csv/transactions.csv"; - private static final String CMD = "-b ./src/test -PCSV_OUT_FORMAT=TDF -t templates/csv/transform.ftl site/sample/csv/contract.csv"; + // private static final String CMD = "-b ./src/test -PCSV_OUT_FORMAT=TDF -t templates/csv/transform.ftl site/sample/csv/contract.csv"; // private static final String CMD = "-t templates/excel/csv/transform.ftl -l de_AT site/sample/excel/test.xlsx"; // private static final String CMD = "-i ${JsonPathTool.parse(DataSources.first).read('$.info.title')} site/sample/json/swagger-spec.json"; // private static final String CMD = "-i ${XmlTool.parse(DataSources.first)['recipients/person[1]/name']} site/sample/xml/recipients.xml"; @@ -48,7 +48,7 @@ public class ManualTest { // private static final String CMD = "-b ./src/test -t templates/demo.ftl -m env=./site/sample/properties/user_0001/user.properties"; // private static final String CMD = "-b ./src/test -t templates/demo.ftl -m ./site/sample/properties/user_0001/user.properties"; // private static final String CMD = "-b ./src/test --data-model post=https://jsonplaceholder.typicode.com/posts/2 -t templates/info.ftl"; - // private static final String CMD = "-b ./src/test -t templates/info.ftl -P key:group=value"; + private static final String CMD = "-b ./src/test -t templates/info.ftl -P name=value"; public static void main(String[] args) { diff --git a/freemarker-generator-cli/src/test/java/org/apache/freemarker/generator/cli/config/SettingsTest.java b/freemarker-generator-cli/src/test/java/org/apache/freemarker/generator/cli/config/SettingsTest.java index 0ccd737..16032e4 100644 --- a/freemarker-generator-cli/src/test/java/org/apache/freemarker/generator/cli/config/SettingsTest.java +++ b/freemarker-generator-cli/src/test/java/org/apache/freemarker/generator/cli/config/SettingsTest.java @@ -42,7 +42,7 @@ public class SettingsTest { private static final String ANY_OUTPUT_FILE = "outputFile"; private static final List<String> ANY_SOURCES = singletonList("sources"); private static final String ANY_TEMPLATE_NAME = "templateName"; - private static final Map<String, String> ANY_USER_PARAMETERS = new HashMap<>(); + private static final Map<String, Object> ANY_USER_PARAMETERS = new HashMap<>(); private static final Properties ANY_SYSTEM_PROPERTIES = new Properties(); @Test diff --git a/freemarker-generator-cli/templates/info.ftl b/freemarker-generator-cli/templates/info.ftl index 01384c3..3d46398 100644 --- a/freemarker-generator-cli/templates/info.ftl +++ b/freemarker-generator-cli/templates/info.ftl @@ -48,8 +48,12 @@ URI : ${dataSource.uri} User Supplied Parameters ------------------------------------------------------------------------------ -<#list SystemTool.parameters as name,value> -- ${name} ==> ${value} +<#list SystemTool.parameters as key,value> +<#if value?is_hash> +- ${key} ==> { <#list value as name,value>${name}=${value} </#list>} +<#else> +- ${key} ==> ${value} +</#if> </#list> User Supplied System Properties @@ -62,7 +66,5 @@ SystemTool ------------------------------------------------------------------------------ Command line : ${SystemTool.getCommandLineArgs()?join(", ")} Host Name : ${SystemTool.getHostName()} -Java Home : ${SystemTool.getEnv("JAVA_HOME", "N.A.")} +Current Dir : ${SystemTool.getEnv("PWD", "N.A.")} User Name : ${SystemTool.getSystemProperty("user.name", "N.A.")} -Timestamp : ${SystemTool.currentTimeMillis} -Writer : ${SystemTool.writer.class.name}
