This is an automated email from the ASF dual-hosted git repository. sgoeschl pushed a commit to branch FREEMARKER-161 in repository https://gitbox.apache.org/repos/asf/freemarker-generator.git
commit 42b74841b24060934ce75e149cb3ec360d46d12c Author: Siegfried Goeschl <[email protected]> AuthorDate: Sat Jan 9 13:16:07 2021 +0100 FREEMARKER-161 [freemarker-generator] Update documentation --- .../generator/base/file/RecursiveFileSupplier.java | 2 +- .../markdown/cli/advanced/cli-configuration.md | 9 +++--- .../site/markdown/cli/concepts/template-loading.md | 20 +++++++++---- .../src/site/markdown/cli/concepts/tools.md | 33 +++++++++++----------- .../site/markdown/cli/concepts/transformation.md | 28 ++++++++---------- .../markdown/cli/introduction/getting-started.md | 33 ++++++++++++++-------- .../src/site/markdown/index.md | 4 +-- .../freemarker/generator/cli/ExamplesTest.java | 1 - 8 files changed, 72 insertions(+), 58 deletions(-) diff --git a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/file/RecursiveFileSupplier.java b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/file/RecursiveFileSupplier.java index b2498d8..bc89df3 100644 --- a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/file/RecursiveFileSupplier.java +++ b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/file/RecursiveFileSupplier.java @@ -85,7 +85,7 @@ public class RecursiveFileSupplier implements Supplier<List<File>> { } else if (file.isDirectory()) { return resolveDirectory(file); } else { - throw new IllegalArgumentException("Unable to find source: " + source); + throw new IllegalArgumentException("Unable to find file: " + source); } } diff --git a/freemarker-generator-cli/src/site/markdown/cli/advanced/cli-configuration.md b/freemarker-generator-cli/src/site/markdown/cli/advanced/cli-configuration.md index bb8b8ca..092a5cb 100644 --- a/freemarker-generator-cli/src/site/markdown/cli/advanced/cli-configuration.md +++ b/freemarker-generator-cli/src/site/markdown/cli/advanced/cli-configuration.md @@ -16,7 +16,6 @@ The `Apache FreeMarker Generator` configuration can be tweaked to # See https://freemarker.apache.org/docs/api/freemarker/template/Configuration.html#setSetting-java.lang.String-java.lang.String- ############################################################################# # freemarker.configuration.setting.locale=JVM default - ############################################################################# # Configure FreeMarker Tools (name -> implementation class) ############################################################################# @@ -27,7 +26,8 @@ freemarker.tools.exec=org.apache.freemarker.generator.tools.commonsexec.CommonsE freemarker.tools.freemarker=org.apache.freemarker.generator.tools.freemarker.FreeMarkerTool freemarker.tools.grok=org.apache.freemarker.generator.tools.grok.GrokTool freemarker.tools.gson=org.apache.freemarker.generator.tools.gson.GsonTool -freemarker.tools.jsonpath=org.apache.freemarker.generator.tools.json.JsonPathTool +freemarker.tools.javafaker=org.apache.freemarker.generator.tools.javafaker.JavaFakerTool +freemarker.tools.jsonpath=org.apache.freemarker.generator.tools.jsonpath.JsonPathTool freemarker.tools.jsoup=org.apache.freemarker.generator.tools.jsoup.JsoupTool freemarker.tools.properties=org.apache.freemarker.generator.tools.properties.PropertiesTool freemarker.tools.system=org.apache.freemarker.generator.tools.system.SystemTool @@ -71,7 +71,6 @@ You can easily check this, e.g. FreeMarker Generator Template Loader Directories ------------------------------------------------------------------------------ -[#1] /Users/sgoeschl -[#2] /Users/sgoeschl/.freemarker-generator -[#3] /Applications/Java/freemarker-generator-2.0.0 +[#1] /Users/sgoeschl/.freemarker-generator/templates +[#2] /Applications/Java/freemarker-generator/templates ``` diff --git a/freemarker-generator-cli/src/site/markdown/cli/concepts/template-loading.md b/freemarker-generator-cli/src/site/markdown/cli/concepts/template-loading.md index 14f945a..5b1ce99 100644 --- a/freemarker-generator-cli/src/site/markdown/cli/concepts/template-loading.md +++ b/freemarker-generator-cli/src/site/markdown/cli/concepts/template-loading.md @@ -10,7 +10,6 @@ In order the render a template it needs to be loaded first - there are multiple `Apache FreeMarker Generator CLI` uses a `MultiTemplateLoader` searching for templates in the following directories -* Current working directory * Optional `~/.freemarker-generator` directory * `Apache FreeMarker Generator` installation directory @@ -21,9 +20,8 @@ freemarker-generator -t freemarker-generator/info.ftl FreeMarker Generator Template Loader Directories ------------------------------------------------------------------------------ -[#1] /Users/sgoeschl/work/github/apache/freemarker-generator -[#2] /Users/sgoeschl/.freemarker-generator -[#3] /Applications/Java/freemarker-generator-2.0.0 +[#1] /Users/sgoeschl/.freemarker-generator/templates +[#2] /Applications/Java/freemarker-generator/templates ``` The main benefit of `MultiTemplateLoader` is the use of abstract template paths finding a template in the template loader directories @@ -38,9 +36,21 @@ and [Template Includes](https://freemarker.apache.org/docs/ref_directive_include <#import "/lib/commons-csv.ftl" as csv /> ``` +You can add a template directory, e.g. the current working directory + +``` +freemarker-generator -t freemarker-generator/info.ftl --template-dir=./ + +FreeMarker Generator Template Loader Directories +------------------------------------------------------------------------------ +[#1] /Users/sgoeschl +[#2] /Users/sgoeschl/.freemarker-generator/templates +[#3] /Applications/Java/freemarker-generator/templates +``` + ### Free-Style Template Loading -The previously described `Template Loaders` do not support absolute template files or arbitrary URLS - this behaviour +The previously described `Template Loaders` do not support absolute template files or arbitrary URLs - this behaviour stems from security aspects when running `Apache FreeMarker` on the server side. For a command-line tool this is mostly irrelevant therefore any template file outside of the template loader directories can be loaded diff --git a/freemarker-generator-cli/src/site/markdown/cli/concepts/tools.md b/freemarker-generator-cli/src/site/markdown/cli/concepts/tools.md index c5bb4da..e4a34c1 100644 --- a/freemarker-generator-cli/src/site/markdown/cli/concepts/tools.md +++ b/freemarker-generator-cli/src/site/markdown/cli/concepts/tools.md @@ -4,19 +4,20 @@ A `Apache FreeMarker Generator Tool` is just a POJO (plain old Java object) that The following tools are currently implemented -| Tool | Description | -|-----------------------|-----------------------------------------------------------------------------------------------------------| -| CSVTool | Process CSV files using [Apache Commons CSV](https://commons.apache.org/proper/commons-csv/) | -| DataFrameTool | Bridge to [nRo/DataFrame](https://github.com/nRo/DataFrame) | -| ExecTool | Execute command line tools using [Apache Commons Exec](https://commons.apache.org/proper/commons-exec/) | -| ExcelTool | Process Excels files (XLS, XLSX) using [Apache POI](https://poi.apache.org) | -| FreeMarkerTool | Expose useful FreeMarker classes | -| GrokTool | Process text files using [Grok](https://github.com/thekrakken/java-grok) instead of regular expressions | -| GsonTool | Process JSON files using [GSON](https://github.com/google/gson) | -| JsonPathTool | Process JSON file using [Java JSON Path](https://github.com/json-path/JsonPath) | -| JsoupTool | Processing HTML files using [Jsoup](https://jsoup.org) | -| PropertiesTool | Process JDK properties files | -| SystemTool | System-related utility methods | -| UUIDTool | Create UUIDs | -| XmlTool | Process XML files using [Apache FreeMarker](https://freemarker.apache.org/docs/xgui.html) | -| YamlTool | Process YAML files using [SnakeYAML](https://bitbucket.org/asomov/snakeyaml/wiki/Home) | +| Implementation Class | Name | Description | +|-----------------------|---------------|-----------------------------------------------------------------------------------------------------------| +| CSVTool | csv | Process CSV files using [Apache Commons CSV](https://commons.apache.org/proper/commons-csv/) | +| DataFrameTool | dataframe | Bridge to [nRo/DataFrame](https://github.com/nRo/DataFrame) | +| ExcelTool | excel | Process Excels files (XLS, XLSX) using [Apache POI](https://poi.apache.org) | +| ExecTool | exec | Execute command line tools using [Apache Commons Exec](https://commons.apache.org/proper/commons-exec/) | +| FreeMarkerTool | freemarker | Expose useful FreeMarker classes | +| GrokTool | grok | Process text files using [Grok](https://github.com/thekrakken/java-grok) instead of regular expressions | +| GsonTool | gson | Process JSON files using [GSON](https://github.com/google/gson) | +| JavaFakerTool | javafaker | Generate test data using Java Faker [JavaFaker](https://github.com/DiUS/java-faker) +| JsonPathTool | jsonpath | Process JSON file using [Java JSON Path](https://github.com/json-path/JsonPath) | +| JsoupTool | jsoup | Processing HTML files using [Jsoup](https://jsoup.org) | +| PropertiesTool | properties | Process JDK properties files | +| SystemTool | system | System-related utility methods | +| UUIDTool | uuid | Create UUIDs | +| XmlTool | xaml | Process XML files using [Apache FreeMarker](https://freemarker.apache.org/docs/xgui.html) | +| YamlTool | yaml | Process YAML files using [SnakeYAML](https://bitbucket.org/asomov/snakeyaml/wiki/Home) | diff --git a/freemarker-generator-cli/src/site/markdown/cli/concepts/transformation.md b/freemarker-generator-cli/src/site/markdown/cli/concepts/transformation.md index 306d66e..11b1323 100644 --- a/freemarker-generator-cli/src/site/markdown/cli/concepts/transformation.md +++ b/freemarker-generator-cli/src/site/markdown/cli/concepts/transformation.md @@ -3,30 +3,29 @@ The `freemarker-generator` generates text output based on processing FreeMarker templates and data * A command line invocation requires 1..n `templates` and 0..n `data sources` / `data models` -* A command line invocation is mapped to a series of `template transformations` -* The `transformation` consists of exactly one `template`, 0..n `data sources` / `data models` written to an `output` -* The `output` is either written to +* A command line invocation is internally mapped to a list of `output generators` +* The `output generator` consists of exactly one `template`, 0..n `data sources` / `data models` written to an `output` destination +* The `output` of an `output generator` is either written to * `stdout` - * one or more output files - * one or output directories + * an output file + * an output directory * When the output is written to a directory * the structure of the input directory is preserved - * a `ftl` file extension is removed + * any `ftl` file extension is removed +* Positional command line arguments are interpreted as `data sources` (or directories) and accessible by a `output generators` ### Examples -Transforming a single template to a single output file +Transform a single template to a single output file ``` -freemarker-generator \ --t freemarker-generator/csv/md/transform.ftl examples/data/csv/contract.csv \ --o target/contract.md +freemarker-generator -t freemarker-generator/csv/md/transform.ftl -o target/contract.md examples/data/csv/contract.csv ``` -Transforming multiple templates to multiple output files (1:1 mapping between templates and outputs) +Transform multiple templates to multiple output files (1:1 mapping between templates and outputs) ``` -> freemarker-generator \ +freemarker-generator \ -t freemarker-generator/csv/md/transform.ftl -o target/contract.md \ -t freemarker-generator/csv/html/transform.ftl -o target/contract.html \ examples/data/csv/contract.csv @@ -37,7 +36,7 @@ target `-- contract.md ``` -Transforming single template directory to single output directory +Transform a single template directory to single output directory ``` > freemarker-generator \ @@ -49,8 +48,6 @@ target |-- application.properties `-- nginx `-- nginx.conf - - ``` Transforming multiple template directories to multiple output directories @@ -70,7 +67,6 @@ target |-- application.properties `-- nginx `-- nginx.conf - ``` Transforming multiple templates and data sources to multiple output files diff --git a/freemarker-generator-cli/src/site/markdown/cli/introduction/getting-started.md b/freemarker-generator-cli/src/site/markdown/cli/introduction/getting-started.md index cf264ec..5a61008 100644 --- a/freemarker-generator-cli/src/site/markdown/cli/introduction/getting-started.md +++ b/freemarker-generator-cli/src/site/markdown/cli/introduction/getting-started.md @@ -12,7 +12,7 @@ On my local box (Mac OS 10.15.5) I use the following setup ``` -export FREEMARKER_CLI_HOME=/Applications/Java/freemarker-generator-2.0.0 +export FREEMARKER_CLI_HOME=/Applications/Java/freemarker-generator export PATH=$PATH:$FREEMARKER_CLI_HOME/bin ``` @@ -20,14 +20,14 @@ Afterwards `Apache FreeMarker Generator` can be executed from the command line ``` > which freemarker-generator -/Applications/Java/freemarker-generator-2.0.0/bin/freemarker-generator +/Applications/Java/freemarker-generator/bin/freemarker-generator ``` and check the version of `Apache FreeMarker Generator` ``` > freemarker-generator -V -version=0.1.0-SNAPSHOT, time=2020-06-25T21:48:02+0200, commit=b320d00094be8789086ad6153d9d3fcaf4b8c75f +version=0.1.0-SNAPSHOT, time=2021-01-09T10:41:01+0100, commit=d308ede197f1c2972e3b328b9a37fa233cae101a ``` ### Command Line Options @@ -36,17 +36,22 @@ version=0.1.0-SNAPSHOT, time=2020-06-25T21:48:02+0200, commit=b320d00094be878908 ``` > freemarker-generator -h -Usage: freemarker-generator (-t=<templates> [-t=<templates>]... | - -i=<interactiveTemplate>) [-hV] [--stdin] - [--config=<configFile>] +Usage: freemarker-generator ((-t=<template> | -i=<interactiveTemplate>) + [[--template-include=<templateIncludePatterns>] + [--template-include=<templateIncludePatterns>]... + [--template-exclude=<templateExcludePatterns>] + [--template-exclude=<templateExcludePatterns>]...] + [[-o=<outputs>] [-o=<outputs>]...] + [[-s=<dataSources>] [-s=<dataSources>]...] + [[-m=<dataModels>] [-m=<dataModels>]...])... [-hV] + [--stdin] [--config=<configFile>] [--data-source-exclude=<dataSourceExcludePattern>] [--data-source-include=<dataSourceIncludePattern>] [-e=<inputEncoding>] [-l=<locale>] [--output-encoding=<outputEncoding>] [--template-dir=<templateDir>] [--times=<times>] - [-D=<String=String>]... [-m=<dataModels>]... - [-o=<outputs>]... [-P=<String=String>]... - [-s=<dataSources>]... [<sources>...] + [-D=<String=String>]... [-P=<String=String>]... + [<sources>...] Apache FreeMarker Generator [<sources>...] data source files and/or directories --config=<configFile> @@ -54,9 +59,9 @@ Apache FreeMarker Generator -D, --system-property=<String=String> set system property --data-source-exclude=<dataSourceExcludePattern> - file exclude pattern for data sources + data source exclude pattern --data-source-include=<dataSourceIncludePattern> - file include pattern for data sources + data source include pattern -e, --input-encoding=<inputEncoding> encoding of data source -h, --help Show this help message and exit. @@ -73,10 +78,14 @@ Apache FreeMarker Generator -s, --data-source=<dataSources> data source used for rendering --stdin read data source from stdin - -t, --template=<templates> + -t, --template=<template> templates to process --template-dir=<templateDir> additional template directory + --template-exclude=<templateExcludePatterns> + template exclude pattern + --template-include=<templateIncludePatterns> + template include pattern --times=<times> re-run X times for profiling -V, --version Print version information and exit. ``` diff --git a/freemarker-generator-cli/src/site/markdown/index.md b/freemarker-generator-cli/src/site/markdown/index.md index 9a6ecc4..e6cde71 100644 --- a/freemarker-generator-cli/src/site/markdown/index.md +++ b/freemarker-generator-cli/src/site/markdown/index.md @@ -9,9 +9,9 @@ * Transform a directory with a single command-line invocation * Made for the heavy lifting of data by using lazy-loading and streaming -### Getting Started +### First Seps -* [Installation](cli/introduction/getting-started.html) +* [Getting Started](cli/introduction/getting-started.html) * [Running Examples](cli/usage/running-examples.html) ### Concepts diff --git a/freemarker-generator-cli/src/test/java/org/apache/freemarker/generator/cli/ExamplesTest.java b/freemarker-generator-cli/src/test/java/org/apache/freemarker/generator/cli/ExamplesTest.java index fce124b..5c5ebd5 100644 --- a/freemarker-generator-cli/src/test/java/org/apache/freemarker/generator/cli/ExamplesTest.java +++ b/freemarker-generator-cli/src/test/java/org/apache/freemarker/generator/cli/ExamplesTest.java @@ -147,7 +147,6 @@ public class ExamplesTest extends AbstractMainTest { assertValid(execute("-t freemarker-generator/csv/md/transform.ftl -o target/contract.md -t freemarker-generator/csv/html/transform.ftl -o target/contract.html src/app/examples/data/csv/contract.csv")); } - @Test public void shouldTransformMultipleTemplatesAndDataSources() throws IOException { final String output = execute(
