diff options
Diffstat (limited to 'support/texplate')
7 files changed, 81 insertions, 10 deletions
diff --git a/support/texplate/README.md b/support/texplate/README.md index 7428b21519..ac3db486c5 100644 --- a/support/texplate/README.md +++ b/support/texplate/README.md @@ -22,7 +22,7 @@ $ texplate \ \_\ \/_/ -TeXplate 1.0.2, a document structure creation tool +TeXplate 1.0.3, a document structure creation tool Copyright (c) 2020, Island of TeX All rights reserved. @@ -85,7 +85,7 @@ $ texplate -t article -o doc1.tex \ \_\ \/_/ -TeXplate 1.0.2, a document structure creation tool +TeXplate 1.0.3, a document structure creation tool Copyright (c) 2020, Island of TeX All rights reserved. diff --git a/support/texplate/doc/texplate-manual.pdf b/support/texplate/doc/texplate-manual.pdf Binary files differindex 19afbe5c8f..98862816c4 100644 --- a/support/texplate/doc/texplate-manual.pdf +++ b/support/texplate/doc/texplate-manual.pdf diff --git a/support/texplate/doc/texplate-manual.tex b/support/texplate/doc/texplate-manual.tex index 56dbe5e5f3..6f89d36158 100644 --- a/support/texplate/doc/texplate-manual.tex +++ b/support/texplate/doc/texplate-manual.tex @@ -17,7 +17,7 @@ \newcommand{\shortopt}[1]{{\ttfamily-#1}} \newcommand{\longopt}[1]{{\ttfamily{-}{-}#1}} \newcommand{\macro}[1]{{\ttfamily\textbackslash#1}} -\newcommand{\texplateversion}{1.0.2} +\newcommand{\texplateversion}{1.0.3} \title{A gentle introduction to \texplate:\\ a document structure creation tool} \author{Island of \TeX} @@ -171,7 +171,7 @@ Referred as either \shortopt{t} (short representation) or \longopt{template} (lo --template=article \end{code} -The provided string should match the template identifier, otherwise \texplate\ will raise an error complaining about the missing reference. The template identifier will be discussed later on, in Section~\ref{sec:namingscheme}. +The provided string should match the template identifier (or file name), otherwise \texplate\ will raise an error complaining about the missing reference. The template identifier will be discussed later on, in Section~\ref{sec:namingscheme}. For a discussion on file name lookup, see Section~\ref{sec:directorylookup}. \section{Map} \label{sec:mapcli} @@ -263,6 +263,26 @@ $ texplate -t article -o mydoc.tex \texplate\ will look for a template file named \inline{article.toml} in the path structure from the user home directory, as seen in \#1. If the file is found, the search ends and the tool proceeds to the template generation. Otherwise, \texplate\ will attempt to look in its own template folder for a match. If found, the tool will use this file reference. If the template file is not found in any of the two locations, the tool reports the issue and prematurely ends. +if the argument provided to \inline{--template} holds no \inline{.toml} extension, \texplate\ will handle it as a string and fallback to the default template lookup, previously described. Otherwise, the tool will handle it as a path reference and read the template from it. Consider, for instance, these scenarios: + +\begin{code} +--template article +\end{code} + +In this scenario, \texplate\ searches for \inline{article.toml} in the default directories (home and application, in that order). + +\begin{code} +--template article.toml +\end{code} + +In this scenario, \texplate\ searches for \inline{article.toml} in the working (current) directory. + +\begin{code} +--template dir/article.toml +\end{code} + +In this scenario, \texplate\ searches for \inline{article.toml} in the \inline{dir/} subdirectory. Note that absolute and relative paths are supported. + \section{Handlers} \label{sec:handlers} @@ -271,6 +291,7 @@ A map entry, when obtained from the command line through the \longopt{map} optio \begin{itemize} \item\inline{to-csv-list}: this handler, as the name implies, converts a string to a list of comma-separated values. The implementation attempts to respect quoted elements, when available. \item\inline{to-boolean}: this handler converts a string to a boolean value, based on the following patterns: \inline{true} and \inline{false}, \inline{1} and \inline{0}, and \inline{yes} or \inline{no}. +\item\inline{to-string-list-from-file}: this handler, as the name implies, converts a string into a file reference and attempts to read its contents into a list of lines. If the file reference does not exist or is somehow invalid, an empty list is assigned instead. \end{itemize} When type conversion is needed in the template logic, handlers are assigned to map keys in the corresponding specification, detailed later on, in Section~\ref{sec:templatestructure}. @@ -396,7 +417,7 @@ The output (i.e., the template merged with the provided data) will be written to \item When running \texplate, this is the expected output to be displayed in the command line (note that the layout is slightly modified due to space constraints in this user manual): \begin{code} -TeXplate 1.0.2, a document structure creation tool +TeXplate 1.0.3, a document structure creation tool Copyright (c) 2020, Island of TeX All rights reserved. @@ -603,7 +624,22 @@ Happy \TeX ing with \texplate! \chapter*{Changelog} -\section*{1.0.2 (current)} +\section*{1.0.3 (current)} + +\subsection*{Added} + +\begin{itemize} +\item New \inline{to-string-list-from-file} handler added. This handler converts the map entry value into a \inline{File} reference and attempts to read its contents into a list of lines. If the file reference does not exist or is invalid (e.g, not a file or with insufficient permissions), an empty list is assigned instead. +\end{itemize} + +\subsection*{Changed} + +\begin{itemize} +\item\texplate\ template path resolution has changed. Use \inline{-t article} to get the default article template. If you want to specify a file instead, use \inline{-t article.toml} or \inline{-t /my/path/to/file.toml}. Relative paths will be resolved against the working directory. +\item Updated dependencies. +\end{itemize} + +\section*{1.0.2 (2020-02-02)} \subsection*{Fixed} diff --git a/support/texplate/source/main/kotlin/org/islandoftex/texplate/TemplateProcessing.kt b/support/texplate/source/main/kotlin/org/islandoftex/texplate/TemplateProcessing.kt index 659a0df631..213971612a 100644 --- a/support/texplate/source/main/kotlin/org/islandoftex/texplate/TemplateProcessing.kt +++ b/support/texplate/source/main/kotlin/org/islandoftex/texplate/TemplateProcessing.kt @@ -207,11 +207,11 @@ class TemplateProcessing : Callable<Int> { /** * Ensures the first parameter is not null, or sets it to the second one. * - * @param <T> The type. + * @param T The type. * @param first First parameter. * @param second Second parameter. * @return Either the first or the second one. - </T> */ + */ private fun <T> ensure(first: T, second: T): T { return if (!has(first)) second else first } diff --git a/support/texplate/source/main/kotlin/org/islandoftex/texplate/model/handlers/FileReaderHandler.kt b/support/texplate/source/main/kotlin/org/islandoftex/texplate/model/handlers/FileReaderHandler.kt new file mode 100644 index 0000000000..4153dc48c0 --- /dev/null +++ b/support/texplate/source/main/kotlin/org/islandoftex/texplate/model/handlers/FileReaderHandler.kt @@ -0,0 +1,28 @@ +// SPDX-License-Identifier: BSD-3-Clause +package org.islandoftex.texplate.model.handlers + +import java.io.File + +/** + * Implements a file reader handler. + * + * @version 1.0.3 + * @since 1.0.3 + */ +class FileReaderHandler : Handler { + + /** + * Applies the conversion to the string. + * + * @param string The string denoting a file. + * @return A list of strings from the file. + */ + override fun apply(string: String?): Any? { + return string?.let { + val file = File(string) + if (file.exists() && file.isFile) + file.readLines() + else null + } ?: emptyList<String>() + } +} diff --git a/support/texplate/source/main/kotlin/org/islandoftex/texplate/util/HandlerUtils.kt b/support/texplate/source/main/kotlin/org/islandoftex/texplate/util/HandlerUtils.kt index 44eebb2b69..9f6c65d8e6 100644 --- a/support/texplate/source/main/kotlin/org/islandoftex/texplate/util/HandlerUtils.kt +++ b/support/texplate/source/main/kotlin/org/islandoftex/texplate/util/HandlerUtils.kt @@ -3,6 +3,7 @@ package org.islandoftex.texplate.util import org.islandoftex.texplate.model.handlers.BooleanHandler import org.islandoftex.texplate.model.handlers.CSVListHandler +import org.islandoftex.texplate.model.handlers.FileReaderHandler import org.islandoftex.texplate.model.handlers.Handler /** @@ -20,6 +21,7 @@ object HandlerUtils { @JvmStatic val handlers: Map<String, Handler> = mapOf( "to-csv-list" to CSVListHandler(), - "to-boolean" to BooleanHandler() + "to-boolean" to BooleanHandler(), + "to-string-list-from-file" to FileReaderHandler() ) } diff --git a/support/texplate/source/main/kotlin/org/islandoftex/texplate/util/PathUtils.kt b/support/texplate/source/main/kotlin/org/islandoftex/texplate/util/PathUtils.kt index 3a74603557..d0212769ec 100644 --- a/support/texplate/source/main/kotlin/org/islandoftex/texplate/util/PathUtils.kt +++ b/support/texplate/source/main/kotlin/org/islandoftex/texplate/util/PathUtils.kt @@ -39,7 +39,12 @@ object PathUtils { @JvmStatic @Throws(FileNotFoundException::class) fun getTemplatePath(name: String): Path { - // the file has to be a TOML format, so we add the extension + // if the name represents an existing TOML file, we assume the user wants this + // file + if (name.endsWith(".toml") && Files.exists(Paths.get(name))) + return Paths.get(name) + // if not, then we test for the file in texplate's search path + // it has to be in TOML format and without extension val fullName = "$name.toml" // the first reference is based on the user template path resolved with the // file name |