This is an automated email from the ASF dual-hosted git repository.
sgoeschl pushed a commit to branch FREEMARKER-147
in repository https://gitbox.apache.org/repos/asf/freemarker-generator.git
The following commit(s) were added to refs/heads/FREEMARKER-147 by this push:
new 558f1e6 FREEMARKER-147 Complete Maven site documenation
558f1e6 is described below
commit 558f1e66bf826155b99f80318ded69ec4edf01d6
Author: Siegfried Goeschl <[email protected]>
AuthorDate: Fri Jun 26 08:45:13 2020 +0200
FREEMARKER-147 Complete Maven site documenation
---
.../generator/base/template/TemplateOutput.java | 2 +-
.../generator/base/uri/UriFragmentParser.java | 2 +-
.../freemarker/generator/base/util/ListUtils.java | 5 +-
.../freemarker/generator/base/util/Validate.java | 2 +-
freemarker-generator-cli/pom.xml | 14 +++++
.../org/apache/freemarker/generator/cli/Main.java | 4 +-
.../markdown/cli/introduction/getting-started.md | 70 ++++++++++++++++++++++
.../site/markdown/cli/usage/transforming-csv.md | 7 ++-
.../src/site/markdown/index.md | 8 ++-
.../freemarker/generator/cli/ManualTest.java | 3 +-
.../generator/tools/commonscsv/CommonsCSVTool.java | 10 ++--
.../generator/tools/dataframe/DataFrameTool.java | 10 +++-
.../tools/dataframe/impl/ConverterUtils.java | 2 +-
.../tools/dataframe/impl/ListConverter.java | 1 +
.../generator/tools/excel/ExcelTool.java | 6 +-
.../generator/tools/system/SystemTool.java | 4 +-
pom.xml | 2 +-
17 files changed, 125 insertions(+), 27 deletions(-)
diff --git
a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/template/TemplateOutput.java
b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/template/TemplateOutput.java
index 5e8e8a5..426c0f1 100644
---
a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/template/TemplateOutput.java
+++
b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/template/TemplateOutput.java
@@ -26,7 +26,7 @@ import java.io.Writer;
import static java.util.Objects.requireNonNull;
/**
- * Information about where to write the ouput of a template. Initially we
+ * Information about where to write the output of a template. Initially we
* wanted to use a <code>FileWriter</code> but it requires actually an
* existing output file (otherwise a FileNotFound exception is thrown).
* An alternative could be a "LazyFileWriter" which creates the file on
diff --git
a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/uri/UriFragmentParser.java
b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/uri/UriFragmentParser.java
index 839cba7..2242b90 100644
---
a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/uri/UriFragmentParser.java
+++
b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/uri/UriFragmentParser.java
@@ -24,7 +24,7 @@ import static java.util.stream.Collectors.toMap;
import static org.apache.freemarker.generator.base.util.StringUtils.isEmpty;
/**
- * Parses the URI fragment as list of name/value pairs seperated by an
ampersand.
+ * Parses the URI fragment as list of name/value pairs separated by an
ampersand.
*/
public class UriFragmentParser {
diff --git
a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/util/ListUtils.java
b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/util/ListUtils.java
index e04d16a..369bf90 100644
---
a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/util/ListUtils.java
+++
b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/util/ListUtils.java
@@ -58,7 +58,10 @@ public class ListUtils {
* @return copied array
*/
public static <T> T coalesce(List<T> list) {
- return list.stream().filter(Objects::nonNull).findFirst().orElseGet(()
-> null);
+ return list.stream()
+ .filter(Objects::nonNull)
+ .findFirst()
+ .orElse(null);
}
/**
diff --git
a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/util/Validate.java
b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/util/Validate.java
index af2b497..114b61d 100644
---
a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/util/Validate.java
+++
b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/util/Validate.java
@@ -19,7 +19,7 @@ package org.apache.freemarker.generator.base.util;
import java.io.File;
/**
- * Simple validation methods designed for interal use.
+ * Simple validation methods designed for internal use.
*/
public final class Validate {
diff --git a/freemarker-generator-cli/pom.xml b/freemarker-generator-cli/pom.xml
index 443b739..db85554 100644
--- a/freemarker-generator-cli/pom.xml
+++ b/freemarker-generator-cli/pom.xml
@@ -127,6 +127,20 @@
</goals>
</execution>
</executions>
+ <configuration>
+ <dotGitDirectory>${project.basedir}/.git</dotGitDirectory>
+ <prefix>git</prefix>
+ <verbose>false</verbose>
+ <generateGitPropertiesFile>true</generateGitPropertiesFile>
+
<generateGitPropertiesFilename>${project.build.outputDirectory}/git.properties
+ </generateGitPropertiesFilename>
+ <format>properties</format>
+ <gitDescribe>
+ <skip>false</skip>
+ <always>false</always>
+ <dirty>-dirty</dirty>
+ </gitDescribe>
+ </configuration>
</plugin>
</plugins>
</build>
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 6315aa0..7e86f85 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
@@ -66,7 +66,7 @@ public class Main implements Callable<Integer> {
public String interactiveTemplate;
}
- @Option(names = { "-b", "--basedir" }, description = "optional template
base directory")
+ @Option(names = { "-b", "--basedir" }, description = "additional template
base directory")
String baseDir;
@Option(names = { "-D", "--system-property" }, description = "set system
property")
@@ -87,7 +87,7 @@ public class Main implements Callable<Integer> {
@Option(names = { "-P", "--param" }, description = "set parameter")
Map<String, String> parameters;
- @Option(names = { "-s", "--data-source" }, description = "data source used
for redering")
+ @Option(names = { "-s", "--data-source" }, description = "data source used
for rendering")
List<String> dataSources;
@Option(names = { "--config" }, defaultValue =
FREEMARKER_CLI_PROPERTY_FILE, description = "FreeMarker CLI configuration file")
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
new file mode 100644
index 0000000..5883b5a
--- /dev/null
+++
b/freemarker-generator-cli/src/site/markdown/cli/introduction/getting-started.md
@@ -0,0 +1,70 @@
+## Getting Started
+
+### Installation
+
+* Requires JDK 1.8+ on Linux, Mac OSX and Windows
+* Download [freemarker-generator-cli-0.1.0-SNAPSHOT-app.tar.gz] or
[freemarker-generator-cli-0.1.0-SNAPSHOT-app.zip]
+* Unpack the archive in a directory of your choice
+* Add the `bin/freemarker-cli` or `bin/freemarker-cli.bat` to your `PATH`
variable
+
+### Verify Installation
+
+On my local box (Mac OS 10.15.5) I use the following setup
+
+```
+export FREEMARKER_CLI_HOME=/Applications/Java/freemarker-cli-2.0.0
+export PATH=$PATH:$FREEMARKER_CLI_HOME/bin
+```
+
+Afterwards `Apache FreeMarker CLI` can be executed from the command line
+
+```
+> which freemarker-cli
+/Applications/Java/freemarker-cli-2.0.0/bin/freemarker-cli
+
+> freemarker-cli -V
+version=0.1.0-SNAPSHOT, time=2020-06-25T21:48:02+0200,
commit=b320d00094be8789086ad6153d9d3fcaf4b8c75f
+
+> freemarker-cli -h
+Usage: freemarker-cli (-t=<templates> [-t=<templates>]... |
+ -i=<interactiveTemplate>) [-hV] [--stdin] [-b=<baseDir>]
+ [--config=<configFile>] [--data-source-exclude=<exclude>]
+ [--data-source-include=<include>] [-e=<inputEncoding>]
+ [-l=<locale>] [-o=<outputFile>]
+ [--output-encoding=<outputEncoding>] [--times=<times>]
+ [-D=<String=String>]... [-m=<dataModels>]...
+ [-P=<String=String>]... [-s=<dataSources>]...
+ [<sources>...]
+Apache FreeMarker CLI
+ [<sources>...] data source files and/or directories
+ -b, --basedir=<baseDir> optional template base directory
+ --config=<configFile> FreeMarker CLI configuration file
+ -D, --system-property=<String=String>
+ set system property
+ --data-source-exclude=<exclude>
+ file exclude pattern for data sources
+ --data-source-include=<include>
+ file include pattern for data sources
+ -e, --input-encoding=<inputEncoding>
+ encoding of data source
+ -h, --help Show this help message and exit.
+ -i, --interactive=<interactiveTemplate>
+ interactive template to process
+ -l, --locale=<locale> locale being used for the output, e.g. 'en_US'
+ -m, --data-model=<dataModels>
+ data model used for rendering
+ -o, --output=<outputFile> output file or directory
+ --output-encoding=<outputEncoding>
+ encoding of output, e.g. UTF-8
+ -P, --param=<String=String>
+ set parameter
+ -s, --data-source=<dataSources>
+ data source used for redering
+ --stdin read data source from stdin
+ -t, --template=<templates>
+ template to process
+ --times=<times> re-run X times for profiling
+ -V, --version Print version information and exit.
+```
+
+
diff --git
a/freemarker-generator-cli/src/site/markdown/cli/usage/transforming-csv.md
b/freemarker-generator-cli/src/site/markdown/cli/usage/transforming-csv.md
index 0b0dd67..ce54659 100644
--- a/freemarker-generator-cli/src/site/markdown/cli/usage/transforming-csv.md
+++ b/freemarker-generator-cli/src/site/markdown/cli/usage/transforming-csv.md
@@ -1,6 +1,7 @@
## Transforming CSV
-A common task is changing the output format of a CSV file
+A common task is changing the output format of a CSV file therefore `Apache
FreeMarker CLI` ships with a ready-to-use
+templates to convert CSVs
* Convert a CSV into a different format
* Convert a CSV into Markdown or HTML
@@ -8,8 +9,8 @@ A common task is changing the output format of a CSV file
### Convert CSV To A Different Output Format
Let's assume that a CSV file in [DEFAULT
format](https://commons.apache.org/proper/commons-csv/apidocs/org/apache/commons/csv/CSVFormat.html#DEFAULT)
-should be converted into a [Microsoft Excel compatible
format](https://commons.apache.org/proper/commons-csv/apidocs/org/apache/commons/csv/CSVFormat.html#EXCEL).
-This allows opening the CSV directly in Excel without going to the tedious CSV
import form.
+should be converted into a [Microsoft Excel
format](https://commons.apache.org/proper/commons-csv/apidocs/org/apache/commons/csv/CSVFormat.html#EXCEL).
+This allows opening the CSV directly in Excel without going to the tedious CSV
import dialog.
The following command line prints the converted CSV to `stdout`
diff --git a/freemarker-generator-cli/src/site/markdown/index.md
b/freemarker-generator-cli/src/site/markdown/index.md
index 9a584b4..ea29b88 100644
--- a/freemarker-generator-cli/src/site/markdown/index.md
+++ b/freemarker-generator-cli/src/site/markdown/index.md
@@ -5,10 +5,14 @@
* Requires JDK 1.8+ on Linux, Mac OSX and Windows
* Use stdin, files and URLs to load data and templates
* Reads a variety of structured data formats such as access logs, CSV, Excel,
JSON, HTML, YAML, XML
-* Provides JSONPath and DataFrames for advanced data manipulation
+* Provides JSONPath, XPath and DataFrames for advanced data manipulation
* Transform a directory with a single command-line invocation
* Made for the heavy lifting of data by using lazy-loading and streaming
+### Getting Started
+
+* [Installation](cli/introduction/getting-started.html)
+
### Concepts
* [Named URIs](cli/concepts/named-uris.html)
@@ -28,4 +32,4 @@
### Advanced Topics
-* [FreeMarker CLI Configuration](cli/usage/cli-configuration.html)
+* [FreeMarker CLI Configuration](cli/advanced/cli-configuration.html)
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 e4c172c..2b7f456 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
@@ -24,8 +24,9 @@ import java.util.Arrays;
public class ManualTest {
private static final String SPACE = " ";
+ private static final String CMD = "-V";
// private static final String CMD = "-PCSV_SOURCE_FORMAT=DATAFRAME -t
examples/templates/dataframe/example.ftl
https://raw.githubusercontent.com/nRo/DataFrame/master/src/test/resources/users.csv";;
- private static final String CMD = "-PCSV_SOURCE_WITH_HEADER=false
-PCSV_SOURCE_FORMAT=DEFAULT -PCSV_TARGET_FORMAT=EXCEL
-PCSV_TARGET_WITH_HEADER=true -t templates/csv/csv/transform.ftl
examples/data/csv/contract.csv";
+ // private static final String CMD = "-PCSV_SOURCE_WITH_HEADER=false
-PCSV_SOURCE_FORMAT=DEFAULT -PCSV_TARGET_FORMAT=EXCEL
-PCSV_TARGET_WITH_HEADER=true -t templates/csv/csv/transform.ftl
examples/data/csv/contract.csv";
// private static final String CMD = "-t
examples/templates/json/dataframe/github-users.ftl
examples/data/json/github-users.json";
diff --git
a/freemarker-generator-tools/src/main/java/org/apache/freemarker/generator/tools/commonscsv/CommonsCSVTool.java
b/freemarker-generator-tools/src/main/java/org/apache/freemarker/generator/tools/commonscsv/CommonsCSVTool.java
index 157e04a..1dcda46 100644
---
a/freemarker-generator-tools/src/main/java/org/apache/freemarker/generator/tools/commonscsv/CommonsCSVTool.java
+++
b/freemarker-generator-tools/src/main/java/org/apache/freemarker/generator/tools/commonscsv/CommonsCSVTool.java
@@ -73,7 +73,7 @@ public class CommonsCSVTool {
}
try {
- // We don't need to close the underyling ByteArrayInputStream
+ // We don't need to close the underlying ByteArrayInputStream
return parse(toInputStream(csv, UTF_8), UTF_8, format);
} catch (IOException e) {
throw new RuntimeException("Failed to parse CSV", e);
@@ -116,7 +116,7 @@ public class CommonsCSVTool {
/**
* Map the given value of the CVS record into (key to record). If
duplicates
- * are encountered return the first occurence of the CVS record. The map
+ * are encountered return the first occurrence of the CVS record. The map
* retains the insertion order of they keys.
*
* @param records records to process
@@ -129,7 +129,7 @@ public class CommonsCSVTool {
/**
* Map the given value of the CVS record into (key to record). If
duplicates
- * are encountered return the first occurence of the CVS record. The map
+ * are encountered return the first occurrence of the CVS record. The map
* retains the insertion order of they keys.
*
* @param records records to process
@@ -163,8 +163,8 @@ public class CommonsCSVTool {
}
/**
- * Maps the sybmolic name of a delimiter to a single character since it
- * is not possible to define commony used delimiters on the command line.
+ * Maps the symbolic name of a delimiter to a single character since it
+ * is not possible to define commonly used delimiters on the command line.
*
* @param name symbolic name of delimiter
* @return CSV delimiter
diff --git
a/freemarker-generator-tools/src/main/java/org/apache/freemarker/generator/tools/dataframe/DataFrameTool.java
b/freemarker-generator-tools/src/main/java/org/apache/freemarker/generator/tools/dataframe/DataFrameTool.java
index bdad38e..640d798 100644
---
a/freemarker-generator-tools/src/main/java/org/apache/freemarker/generator/tools/dataframe/DataFrameTool.java
+++
b/freemarker-generator-tools/src/main/java/org/apache/freemarker/generator/tools/dataframe/DataFrameTool.java
@@ -43,7 +43,9 @@ import static
de.unknownreality.dataframe.DataFrameWriter.DEFAULT_PRINT_FORMAT;
public class DataFrameTool {
/**
- * Create a default data frame.
+ * Create an empty data frame.
+ *
+ * @return data frame
*/
public DataFrame create() {
return new DefaultDataFrame();
@@ -81,7 +83,7 @@ public class DataFrameTool {
}
/**
- * Provide a convinience map with predefined sort orders to be used by
templates.
+ * Provide a convenience map with predefined sort orders to be used by
templates.
*
* @return available sort orders
*/
@@ -93,7 +95,7 @@ public class DataFrameTool {
}
/**
- * Provide a convinience map with predefined transformers.
+ * Provide a convenience map with predefined transformers.
*
* @return available transformers
*/
@@ -107,6 +109,7 @@ public class DataFrameTool {
* Print the <code>DataFrame</code> to the FreeMarker writer.
*
* @param dataFrame data frame
+ * @return text representation of data frame
*/
public String print(DataFrame dataFrame) {
final StringWriter writer = new StringWriter();
@@ -119,6 +122,7 @@ public class DataFrameTool {
return "Bridge to [nRo/DataFrame](https://github.com/nRo/DataFrame)";
}
+ @SuppressWarnings("rawtypes")
private static CountTransformer countTransformer(boolean ignoreNA) {
return new CountTransformer(ignoreNA);
}
diff --git
a/freemarker-generator-tools/src/main/java/org/apache/freemarker/generator/tools/dataframe/impl/ConverterUtils.java
b/freemarker-generator-tools/src/main/java/org/apache/freemarker/generator/tools/dataframe/impl/ConverterUtils.java
index a600031..9cc9853 100644
---
a/freemarker-generator-tools/src/main/java/org/apache/freemarker/generator/tools/dataframe/impl/ConverterUtils.java
+++
b/freemarker-generator-tools/src/main/java/org/apache/freemarker/generator/tools/dataframe/impl/ConverterUtils.java
@@ -66,7 +66,7 @@ public class ConverterUtils {
case "java.util.Date":
return builder.addStringColumn(columnName);
default:
- throw new RuntimeException("Unable to add colum for the
following type: " + columnType.getName());
+ throw new RuntimeException("Unable to add column for the
following type: " + columnType.getName());
}
}
diff --git
a/freemarker-generator-tools/src/main/java/org/apache/freemarker/generator/tools/dataframe/impl/ListConverter.java
b/freemarker-generator-tools/src/main/java/org/apache/freemarker/generator/tools/dataframe/impl/ListConverter.java
index 4c17fd6..4f83d04 100644
---
a/freemarker-generator-tools/src/main/java/org/apache/freemarker/generator/tools/dataframe/impl/ListConverter.java
+++
b/freemarker-generator-tools/src/main/java/org/apache/freemarker/generator/tools/dataframe/impl/ListConverter.java
@@ -28,6 +28,7 @@ public class ListConverter {
* that the rows represent tabular data.
*
* @param rows rows to build the data frame
+ * @param withFirstRowAsColumnNames column names as first row?
* @return <code>DataFrame</code>
*/
public static DataFrame toDataFrame(List<List<Object>> rows, boolean
withFirstRowAsColumnNames) {
diff --git
a/freemarker-generator-tools/src/main/java/org/apache/freemarker/generator/tools/excel/ExcelTool.java
b/freemarker-generator-tools/src/main/java/org/apache/freemarker/generator/tools/excel/ExcelTool.java
index 08133fc..d9bb473 100644
---
a/freemarker-generator-tools/src/main/java/org/apache/freemarker/generator/tools/excel/ExcelTool.java
+++
b/freemarker-generator-tools/src/main/java/org/apache/freemarker/generator/tools/excel/ExcelTool.java
@@ -94,7 +94,7 @@ public class ExcelTool {
/**
* EXPERIMENTAL FEATURE
* <p>
- * Transform the sheet to table contaning raw Java objects, e.g. Date,
Double, ...
+ * Transform the sheet to table containing raw Java objects, e.g. Date,
Double, ...
*
* @param sheet Excel sheet
* @return Table containing cells as raw Java objects
@@ -121,8 +121,8 @@ public class ExcelTool {
final List<Object> columnValues = new ArrayList<>();
for (int columnIndex = 0; columnIndex < row.getLastCellNum();
columnIndex++) {
final Cell cell = row.getCell(columnIndex, CREATE_NULL_AS_BLANK);
- final String formatedCellValue =
dataFormatter.formatCellValue(cell).trim();
- columnValues.add(formatedCellValue);
+ final String formattedCellValue =
dataFormatter.formatCellValue(cell).trim();
+ columnValues.add(formattedCellValue);
}
return columnValues;
}
diff --git
a/freemarker-generator-tools/src/main/java/org/apache/freemarker/generator/tools/system/SystemTool.java
b/freemarker-generator-tools/src/main/java/org/apache/freemarker/generator/tools/system/SystemTool.java
index 3f038f7..36a8139 100644
---
a/freemarker-generator-tools/src/main/java/org/apache/freemarker/generator/tools/system/SystemTool.java
+++
b/freemarker-generator-tools/src/main/java/org/apache/freemarker/generator/tools/system/SystemTool.java
@@ -125,7 +125,7 @@ public class SystemTool {
}
/**
- * Convinience lookup of a configuration value based on
+ * Convenience lookup of a configuration value based on
* user-supplied parameters, system properties and
* environment variables.
*
@@ -140,7 +140,7 @@ public class SystemTool {
}
/**
- * Convinience lookup of a configuration value based on
+ * Convenience lookup of a configuration value based on
* user-supplied parameters, system properties and
* environment variables.
*
diff --git a/pom.xml b/pom.xml
index 316229f..45cb794 100644
--- a/pom.xml
+++ b/pom.xml
@@ -218,7 +218,7 @@
<plugin>
<groupId>pl.project13.maven</groupId>
<artifactId>git-commit-id-plugin</artifactId>
- <version>2.2.6</version>
+ <version>4.0.0</version>
</plugin>
<plugin>
<groupId>org.apache.rat</groupId>
