summaryrefslogtreecommitdiff
path: root/support/arara/doc/chapters/methods.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/arara/doc/chapters/methods.tex')
-rw-r--r--support/arara/doc/chapters/methods.tex171
1 files changed, 35 insertions, 136 deletions
diff --git a/support/arara/doc/chapters/methods.tex b/support/arara/doc/chapters/methods.tex
index b8cca6a5f3..dd6da67902 100644
--- a/support/arara/doc/chapters/methods.tex
+++ b/support/arara/doc/chapters/methods.tex
@@ -2,10 +2,10 @@
\chapter{Methods}
\label{chap:methods}
-\arara\ features several helper methods available in directive conditional and rule contexts which provide interesting features for enhancing the user experience, as well as improving the automation itself. This chapter provides a list of such methods. It is important to observe that virtually all classes from the Java runtime environment can be used within \gls{MVEL} expressions, so your mileage might vary.
+\arara\ features several helper methods available in directive conditional and rule contexts which provide interesting features for enhancing the user experience, as well as improving the automation itself. This chapter provides a list of such methods. It is important to observe that virtually all classes from the Java runtime environment can be used within MVEL expressions, so your mileage might vary.
\begin{messagebox}{A note on writing code}{araracolour}{\icok}{white}
-As seen in Chapter~\ref{chap:mvel}, on page~\pageref{chap:mvel}, Java and \gls{MVEL} code be used interchangeably within expressions and \glspl{orb-tag}, including instantiation of classes into objects and invocation of methods. However, be mindful of explicitly importing Java packages and classes through the classic \rbox{import} statement, as \gls{MVEL} does not automatically handle imports, or an exception will surely be raised. Alternatively, you can provide the full qualified name to classes as well.
+As seen in Chapter~\ref{chap:mvel}, on page~\pageref{chap:mvel}, Java and MVEL code be used interchangeably within expressions and orb tags, including instantiation of classes into objects and invocation of methods. However, be mindful of explicitly importing Java packages and classes through the classic \rbox{import} statement, as MVEL does not automatically handle imports, or an exception will surely be raised. Alternatively, you can provide the full qualified name to classes as well.
\end{messagebox}
Methods are listed with their complete signatures, including potential parameters and corresponding types. Also, the return type of a method is denoted by \rrbox{type} and refers to a typical Java data type (either class or primitive). Do not worry too much, as there are illustrative examples. A method available in the directive conditional context will be marked by \ctbox{C} next to the corresponding signature. Similarly, an entry marked by \ctbox{R} denotes that the corresponding method is available in the rule context.
@@ -34,7 +34,7 @@ if (reference.equals(getOriginalFile())) {
}
\end{codebox}
-\item[\mddbox{C}{R}{currentFile()}{File}] This method returns the file reference, as a \rbox{File} object, for the current directive. It is important to observe that, from version 4.0 on, \arara\ replicates the directive when the special \abox{files} parameter is detected amongst the parameters, so each instance will have a different reference.
+\item[\mddbox{C}{R}{currentFile()}{File}] This method returns the file reference, as a \rbox{File} object, for the current directive. It is important to observe that \arara\ replicates the directive when the special \abox{files} parameter is detected amongst the parameters, so each instance will have a different reference.
\begin{codebox}{Example}{teal}{\icnote}{white}
% arara: pdflatex if currentFile().getName() == 'thesis.tex'
@@ -46,30 +46,18 @@ if (reference.equals(getOriginalFile())) {
f = toFile('thesis.tex');
\end{codebox}
-\item[\mdbox{R}{getBasename(File file)}{String}] This method returns the base name (i.e, the name without the associated extension) of the provided \rbox{File} reference, as a string. Observe that this method ignores a potential path reference when extracting the base name. For a complete base name extraction with full path support, please refer to the \mtbox{getFullBasename} methods. Also, this method will throw an exception if the provided reference is not a proper file.
+\item[\mdbox{R}{getBasename(File file)}{String}] This method returns the base name (i.e, the name without the associated extension) of the provided \rbox{File} reference, as a string. Observe that this method ignores a potential path reference when extracting the base name. Also, this method will throw an exception if the provided reference is not a proper file.
\begin{codebox}{Example}{teal}{\icnote}{white}
basename = getBasename(toFile('thesis.tex'));
\end{codebox}
-\item[\mdbox{R}{getBasename(String reference)}{String}] This method returns the base name (i.e, the name without the associated extension) of the provided \rbox{String} reference, as a string. Observe that this method ignores a potential path reference when extracting the base name. For a complete base name extraction with full path support, please refer to the \mtbox{getFullBasename} methods.
+\item[\mdbox{R}{getBasename(String reference)}{String}] This method returns the base name (i.e, the name without the associated extension) of the provided \rbox{String} reference, as a string. Observe that this method ignores a potential path reference when extracting the base name.
\begin{codebox}{Example}{teal}{\icnote}{white}
basename = getBasename('thesis.tex');
\end{codebox}
-\item[\mdbox{R}{getFullBasename(File file)}{String}] This method returns the full base name (i.e, the name without the associated extension, as well as the potential path reference) of the provided \rbox{File} reference, as a string. This method will throw an exception if the provided reference is not a proper file.
-
-\begin{codebox}{Example}{teal}{\icnote}{white}
-basename = getFullBasename(toFile('/home/paulo/thesis.tex'));
-\end{codebox}
-
-\item[\mdbox{R}{getFullBasename(String reference)}{String}] This method returns the full base name (i.e, the name without the associated extension, as well as the potential path reference) of the provided \rbox{String} reference, as a string. As the path discovery requires an underlying file conversion, this method will throw an exception if the provided reference is not a proper file.
-
-\begin{codebox}{Example}{teal}{\icnote}{white}
-basename = getFullBasename('/home/paulo/thesis.tex');
-\end{codebox}
-
\item[\mdbox{R}{getFiletype(File file)}{String}] This method returns the file type (i.e, the associated extension specified as a suffix to the name, typically delimited with a full stop) of the provided \rbox{File} reference, as a string. This method will throw an exception if the provided reference is not a proper file. An empty string is returned if, and only if, the provided file name has no associated extension.
\begin{codebox}{Example}{teal}{\icnote}{white}
@@ -106,7 +94,7 @@ extension = getFiletype('thesis.pdf');
% arara: pdftex if missing('pdf')
\end{codebox}
-\item[\mddbox{C}{R}{changed(File file)}{boolean}] This method returns a boolean value according to whether the provided \rbox{File} reference has changed since last verification, based on a traditional cyclic redundancy check. The file reference, as well as the associated hash, is stored in a \gls{XML} database file named \rbox{arara.xml} located in the same directory as the current file (the database name can be overridden in the configuration file, as discussed in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}). The method semantics (including the return values) is presented as follows.
+\item[\mddbox{C}{R}{changed(File file)}{boolean}] This method returns a boolean value according to whether the provided \rbox{File} reference has changed since last verification, based on a traditional cyclic redundancy check. The file reference, as well as the associated hash, is stored in a YAML database file named \rbox{arara.yaml} located in the same directory as the current file (the database name can be overridden in the configuration file, as discussed in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}). The method semantics (including the return values) is presented as follows.
\vspace{1em}
@@ -135,14 +123,14 @@ It is important to observe that this method \emph{always} performs a database op
\end{codebox}
\begin{messagebox}{Short-circuit evaluation}{araracolour}{\icok}{white}
-According to the \href{https://en.wikipedia.org/wiki/Short-circuit_evaluation}{Wikipedia entry}, a \emph{short-circuit evaluation} is the semantics of some boolean operators in some programming languages in which the second argument is executed or evaluated only if the first argument does not suffice to determine the value of the expression. In Java (and consequently \gls{MVEL}), both short-circuit and standard boolean operators are available.
+According to the \href{https://en.wikipedia.org/wiki/Short-circuit_evaluation}{Wikipedia entry}, a \emph{short-circuit evaluation} is the semantics of some boolean operators in some programming languages in which the second argument is executed or evaluated only if the first argument does not suffice to determine the value of the expression. In Java (and consequently MVEL), both short-circuit and standard boolean operators are available.
\end{messagebox}
\begin{messagebox}{CRC as a hashing algorithm}{attentioncolour}{\icattention}{black}
\arara\ internally relies on a CRC32 implementation for file hashing. This particular choice, although not designed for hashing, offers an interesting trade-off between speed and quality. Besides, since it is not computationally expensive as strong algorithms such as MD5 and SHA1, CRC32 can be used for hashing typical \TeX\ documents and plain text files with little to no collisions.
\end{messagebox}
-\item[\mddbox{C}{R}{changed(String extension)}{boolean}] This method returns a boolean value according to whether the base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the provided \rbox{String} extension has changed since last verification, based on a traditional cyclic redundancy check. The file reference, as well as the associated hash, is stored in a \gls{XML} database file named \rbox{arara.xml} located in the same directory as the current file (the database name can be overridden in the configuration file, as discussed in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}). The method semantics (including the return values) is presented as follows.
+\item[\mddbox{C}{R}{changed(String extension)}{boolean}] This method returns a boolean value according to whether the base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the provided \rbox{String} extension has changed since last verification, based on a traditional cyclic redundancy check. The file reference, as well as the associated hash, is stored in a YAML database file named \rbox{arara.yaml} located in the same directory as the current file (the database name can be overridden in the configuration file, as discussed in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}). The method semantics (including the return values) is presented as follows.
\vspace{1em}
@@ -170,7 +158,7 @@ It is important to observe that this method \emph{always} performs a database op
% arara: pdflatex if changed('tex')
\end{codebox}
-\item[\mddbox{C}{R}{unchanged(File file)}{boolean}] This method returns a boolean value according to whether the provided \rbox{File} reference has not changed since last verification, based on a traditional cyclic redundancy check. The file reference, as well as the associated hash, is stored in a \gls{XML} database file named \rbox{arara.xml} located in the same directory as the current file (the database name can be overridden in the configuration file, as discussed in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}). The method semantics (including the return values) is presented as follows.
+\item[\mddbox{C}{R}{unchanged(File file)}{boolean}] This method returns a boolean value according to whether the provided \rbox{File} reference has not changed since last verification, based on a traditional cyclic redundancy check. The file reference, as well as the associated hash, is stored in a YAML database file named \rbox{arara.yaml} located in the same directory as the current file (the database name can be overridden in the configuration file, as discussed in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}). The method semantics (including the return values) is presented as follows.
\vspace{1em}
@@ -198,7 +186,7 @@ It is important to observe that this method \emph{always} performs a database op
% arara: pdflatex if !unchanged(toFile('thesis.tex'))
\end{codebox}
-\item[\mddbox{C}{R}{unchanged(String extension)}{boolean}] This method returns a boolean value according to whether the base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the provided \rbox{String} extension has not changed since last verification, based on a traditional cyclic redundancy check. The file reference, as well as the associated hash, is stored in a \gls{XML} database file named \rbox{arara.xml} located in the same directory as the current file (the database name can be overridden in the configuration file, as discussed in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}). The method semantics (including the return values) is presented as follows.
+\item[\mddbox{C}{R}{unchanged(String extension)}{boolean}] This method returns a boolean value according to whether the base name of the \mtbox{currentFile} reference (i.e, the name without the associated extension) as a string concatenated with the provided \rbox{String} extension has not changed since last verification, based on a traditional cyclic redundancy check. The file reference, as well as the associated hash, is stored in a YAML database file named \rbox{arara.yaml} located in the same directory as the current file (the database name can be overridden in the configuration file, as discussed in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}). The method semantics (including the return values) is presented as follows.
\vspace{1em}
@@ -333,7 +321,7 @@ This section introduces methods related to conditional flow based on \emph{natur
\vspace{1.4em}
-All elements from the provided set of natural boolean values can be used interchangeably in directive parameters. It is important to observe that, from version 4.0 on, \arara\ throws an exception if a value absent from the set is provided to the methods described in this section.
+All elements from the provided set of natural boolean values can be used interchangeably in directive parameters. It is important to observe that \arara\ throws an exception if a value absent from the set is provided to the methods described in this section.
\begin{description}
\item[\mdbox{R}{isTrue(String string)}{boolean}] This method returns a boolean value according to whether the provided \rbox{String} value is contained in the sub-set of natural true boolean values. It is worth mentioning that the verification is case insensitive, i.e, upper case and lower case symbols are treated as equivalent. If the provided value is an empty string, the method returns false.
@@ -465,12 +453,6 @@ result = buildString('a', 'b', 'c', 'd');
result = trimSpaces(' hello world ');
\end{codebox}
-\item[\mdbox{R}{addQuotes(String string)}{String}] This method returns the provided parameter enclosed in double quotes, as a plain string. It is important to observe that there is no automatic quote handling.
-
-\begin{codebox}{Example}{teal}{\icnote}{white}
-result = addQuotes('to be or not to be');
-\end{codebox}
-
\item[\mdbox{R}{replicatePattern(String pattern, List<Object> values)}{List<Object>}] This method replicates the provided pattern to each element of the second parameter and returns the resulting list. The pattern must contain exactly one placeholder. For instance, \rbox{\%s} denotes a string representation of the provided argument. Please refer to the \rbox{Formatter} class reference in the \href{https://docs.oracle.com/javase/7/docs/api/java/util/Formatter.html}{Java documentation} for more information on placeholders. This method raises an exception if an invalid pattern is applied.
\begin{codebox}{Example}{teal}{\icnote}{white}
@@ -523,30 +505,6 @@ if (isMac()) { System.out.println('Running Mac OS.'); }
if (isUnix()) { System.out.println('Running Unix.'); }
\end{codebox}
-\item[\mdbox{R}{isAIX()}{boolean}] This method returns a boolean value according to whether the underlying operating system vendor is IBM AIX.
-
-\begin{codebox}{Example}{teal}{\icnote}{white}
-if (isAIX()) { System.out.println('Running AIX.'); }
-\end{codebox}
-
-\item[\mdbox{R}{isIrix()}{boolean}] This method returns a boolean value according to whether the underlying operating system vendor is Silicon Graphics Irix.
-
-\begin{codebox}{Example}{teal}{\icnote}{white}
-if (isIrix()) { System.out.println('Running Irix.'); }
-\end{codebox}
-
-\item[\mdbox{R}{isOS2()}{boolean}] This method returns a boolean value according to whether the underlying operating system vendor is IBM OS/2 Warp.
-
-\begin{codebox}{Example}{teal}{\icnote}{white}
-if (isOS2()) { System.out.println('Running OS/2 Warp.'); }
-\end{codebox}
-
-\item[\mdbox{R}{isSolaris()}{boolean}] This method returns a boolean value according to whether the underlying operating system vendor is Oracle Solaris.
-
-\begin{codebox}{Example}{teal}{\icnote}{white}
-if (isSolaris()) { System.out.println('Running Solaris.'); }
-\end{codebox}
-
\item[\mdbox{R}{isCygwin()}{boolean}] This method returns a boolean value according to whether the underlying operating system vendor is Microsoft Windows and \arara\ is being executed inside a Cygwin environment.
\begin{codebox}{Example}{teal}{\icnote}{white}
@@ -577,30 +535,6 @@ command = isMac('ls', 'dir');
command = isUnix('tree', 'dir');
\end{codebox}
-\item[\mdbox{R}{isAIX(Object yes, Object no)}{Object}] This method checks if the underlying operating system vendor is IBM AIX. If the result holds true, the first parameter is returned. Otherwise, the second parameter is returned.
-
-\begin{codebox}{Example}{teal}{\icnote}{white}
-command = isAIX('pwd', 'ls');
-\end{codebox}
-
-\item[\mdbox{R}{isIrix(Object yes, Object no)}{Object}] This method checks if the underlying operating system vendor is Silicon Graphics Irix. If the result holds true, the first parameter is returned. Otherwise, the second parameter is returned.
-
-\begin{codebox}{Example}{teal}{\icnote}{white}
-command = isIrix('ls', 'pwd');
-\end{codebox}
-
-\item[\mdbox{R}{isOS2(Object yes, Object no)}{Object}] This method checks if the underlying operating system vendor is IBM OS/2 Warp. If the result holds true, the first parameter is returned. Otherwise, the second parameter is returned.
-
-\begin{codebox}{Example}{teal}{\icnote}{white}
-command = isOS2('ls', 'cd');
-\end{codebox}
-
-\item[\mdbox{R}{isSolaris(Object yes, Object no)}{Object}] This method checks if the underlying operating system vendor is Oracle Solaris. If the result holds true, the first parameter is returned. Otherwise, the second parameter is returned.
-
-\begin{codebox}{Example}{teal}{\icnote}{white}
-command = isSolaris('ls', 'cat');
-\end{codebox}
-
\item[\mdbox{R}{isCygwin(Object yes, Object no)}{Object}] This method checks if the underlying operating system vendor is Microsoft Windows and if \arara\ is being executed inside a Cygwin environment. If the result holds true, the first parameter is returned. Otherwise, the second parameter is returned.
\begin{codebox}{Example}{teal}{\icnote}{white}
@@ -652,15 +586,15 @@ The methods presented in this section cover the most common types used in direct
\section{Classes and objects}
\label{sec:classesandobjects}
-From version 4.0 on, \arara\ can be extended at runtime with code from \gls{JVM} languages, such as Groovy, Scala, Clojure and Kotlin. The tool can load classes from \rbox{class} and \rbox{jar} files and even instantiate them. This section introduces methods related to class loading and object instantiation.
+\arara\ can be extended at runtime with code from JVM languages, such as Groovy, Scala, Clojure and Kotlin. The tool can load classes from \rbox{class} and \rbox{jar} files and even instantiate them. This section introduces methods related to class loading and object instantiation.
\begin{messagebox}{Ordered pairs}{araracolour}{\icok}{white}
According to the \href{https://en.wikipedia.org/wiki/Ordered_pair}{Wikipedia entry}, in mathematics, an \emph{ordered pair} $(a, b)$ is a pair of objects. The order in which the objects appear in the pair is significant: the ordered pair $(a, b)$ is different from the ordered pair $(b, a)$ unless $a = b$. In the ordered pair $(a, b)$, the object $a$ is called the \emph{first} entry, and the object $b$ the \emph{second} entry of the pair. \arara\ relies on this concept with the helper \rbox{Pair<A, B>} class, in which \rbox{A} and \rbox{B} denote the component classes, i.e, the types associated to the pair elements. In order to access the pair entries, the class provides two methods:
\begin{description}
-\item[\mtbox{first()}\hfill\rrbox{A}] This method, as the name implies, returns the first entry of the ordered pair, as an \rbox{A} object. It is important to observe that, from the \gls{MVEL} context, as the method constitutes a property accessor (namely, a getter), the parentheses can be safely omitted.
+\item[\mtbox{first()}\hfill\rrbox{A}] This method, as the name implies, returns the first entry of the ordered pair, as an \rbox{A} object. It is important to observe that, from the MVEL context, as the method constitutes a property accessor (namely, a getter), the parentheses can be safely omitted.
-\item[\mtbox{second()}\hfill\rrbox{B}] This method, as the name implies, returns the second entry of the ordered pair, as a \rbox{B} object. It is important to observe that, from the \gls{MVEL} context, as the method constitutes a property accessor (namely, a getter), the parentheses can be safely omitted.
+\item[\mtbox{second()}\hfill\rrbox{B}] This method, as the name implies, returns the second entry of the ordered pair, as a \rbox{B} object. It is important to observe that, from the MVEL context, as the method constitutes a property accessor (namely, a getter), the parentheses can be safely omitted.
\end{description}
Keep in mind that the entries in the \rbox{Pair} class, once defined, cannot be modified to other values. The initial values are set during instantiation and, therefore, only entry getters are available to the user during the object life cycle.
@@ -827,7 +761,7 @@ This method shows a dialog box according to the provided parameters, including o
\end{codebox}
\begin{messagebox}{Swing toolkit}{araracolour}{\icok}{white}
-According to the \href{https://en.wikipedia.org/wiki/Swing_(Java)}{Wikipedia entry}, the Swing toolkit was developed to provide a more sophisticated set of \gls{GUI} components than the earlier AWT widget system. Swing provides a look and feel that emulates the look and feel of several platforms, and also supports a pluggable look and feel that allows applications to have a look and feel unrelated to the underlying platform. It has more powerful and flexible components than AWT. In addition to familiar components such as buttons, check boxes and labels, Swing provides several advanced components, such as scroll panes, trees, tables, and lists.
+According to the \href{https://en.wikipedia.org/wiki/Swing_(Java)}{Wikipedia entry}, the Swing toolkit was developed to provide a more sophisticated set of GUI components than the earlier AWT widget system. Swing provides a look and feel that emulates the look and feel of several platforms, and also supports a pluggable look and feel that allows applications to have a look and feel unrelated to the underlying platform. It has more powerful and flexible components than AWT. In addition to familiar components such as buttons, check boxes and labels, Swing provides several advanced components, such as scroll panes, trees, tables, and lists.
\end{messagebox}
\item[\mddbox{C}{R}{showInput(int width, int icon, String title, String text)}{String}]\uimethod{inputbox1}
@@ -851,10 +785,10 @@ This method shows an input dialog box according to the provided parameters. The
The UI methods presented in this section can be used for writing \TeX\ tutorials and assisted compilation workflows based on user interactions, including visual input and feedback through dialog boxes.
-\section{Commands and triggers}
-\label{sec:commandsandtriggers}
+\section{Commands}
+\label{sec:commands}
-From version 4.0 on, \arara\ features the \rbox{Command} object, a new approach for handling system commands based on a high level structure with explicit argument parsing. Similarly, there is also the mystical \rbox{Trigger} object that constitutes a very special command that changes the inner workings of our tool at runtime. This section introduces methods for generating such objects.
+\arara\ features the \rbox{Command} object, a new approach for handling system commands based on a high level structure with explicit argument parsing.
\begin{messagebox}{The anatomy of a command}{araracolour}{\icok}{white}
\setlength{\parskip}{1em}
@@ -894,28 +828,6 @@ Note that the above list of integers contains nested lists. When applying list f
List flattening and string mapping confer expressiveness and flexibility to the \rbox{Command} object construction, as users can virtually use any data type to describe the underlying rule logic and yet obtain a consistent representation.
-\begin{messagebox}{The anatomy of a trigger}{araracolour}{\icok}{white}
-\setlength{\parskip}{1em}
-A \rbox{Trigger} object constitutes a special command that changes the internal workings of \arara\ at runtime. It is a highly experimental feature. A trigger is basically a function call defined in terms of a \rbox{String} reference representing the actual function name followed by an optional list of \rbox{Object} arguments. For instance, consider this hypothetical trigger that multiplies an arbitrary number of integer terms:
-
-{\centering
-\setlength\tabcolsep{0.2em}
-\begin{tabular}{cccc}
-{\footnotesize\em name} &
-\multicolumn{3}{c}{\footnotesize\em list of arguments} \\
-\rbox[cyan]{multiply} &
-\rbox[araracolour]{\hphantom{w}12\hphantom{w}} &
-\rbox[araracolour]{\hphantom{w}34\hphantom{w}} &
-\rbox[araracolour]{\hphantom{w}65\hphantom{w}}
-\end{tabular}\par}
-
-\vspace{0.4em}
-
-This description is, in some aspects, very much like a typical \rbox{Command} construction. However, a trigger is less forgiving on data types and does not apply transformations on the provided list of arguments. Therefore, the argument types \emph{must match} the trigger signature.
-
-So far, the tool provides only one trigger, seen in action in one of the official rules, under the name \rbox{halt} and with no parameters. This particular trigger halts the current interpretation workflow, such that subsequent directives are ignored. We have not worked much on triggers yet, and the concept is mentioned here for documentation purposes only.
-\end{messagebox}
-
\begin{description}
\item[\mdbox{R}{getCommand(List<String> elements)}{Command}] This method, as the name implies, returns a \rbox{Command} object according to the provided list of \rbox{String} elements. If the list is empty, the tool will ignore the execution.
@@ -929,18 +841,6 @@ return getCommand([ 'ls', '-l' ]);
return getCommand('pdflatex', '--shell-escape', 'thesis.tex');
\end{codebox}
-\item[\mdbox{R}{getTrigger(String name)}{Trigger}] This method, as the name implies, returns a \rbox{Trigger} object according to the provided \rbox{String} reference as function name. It is important to observe that this particular trigger instance does not have parameters.
-
-\begin{codebox}{Example}{teal}{\icnote}{white}
-return getTrigger('halt');
-\end{codebox}
-
-\item[\mdbox{R}{getTrigger(String name, Object... parameters)}{Trigger}] This method, as the name implies, returns a proper \rbox{Trigger} object according to the provided \rbox{String} reference as function name and the \rbox{Object} array as associated parameters. Note that the object array is denoted by a comma-separated sequence of elements in the actual method call, resulting in a variable number of parameters.
-
-\begin{codebox}{Example}{teal}{\icnote}{white}
-return getTrigger('multiply', 12, 34, 65);
-\end{codebox}
-
\item[\mdbox{R}{\parbox{0.62\textwidth}{getCommandWithWorkingDirectory(File directory,\\\hspace*{1em} List<String> elements)}}{Command}] This method, as the name implies, sets the working directory based on the provided \rbox{File} reference and returns a proper \rbox{Command} object according to the provided list of \rbox{String} elements. If the list is empty, the tool will ignore the execution.
\begin{codebox}{Example}{teal}{\icnote}{white}
@@ -978,16 +878,16 @@ The methods presented in this section constitute the foundations of underlying s
This section introduces assorted methods provided by \arara\ as a means to improve the automation itself with expressive rules and enhance the user experience. Such methods are properly described as follows.
\begin{messagebox}{Session}{araracolour}{\icok}{white}
-Rules are designed under the \emph{encapsulation} notion, such that the direct access to internal workings of such structures is restricted. However, as a means to support framework awareness, \arara\ provides a mechanism for data sharing across rule contexts, implemented as a \rbox{Session} object. In practical terms, this particular object is a global, persistent map composed of \rbox{String} keys and \rbox{Object} values available throughout the entire execution. The public methods are described as follows:
+Rules are designed under the \emph{encapsulation} notion, such that the direct access to internal workings of such structures is restricted. However, as a means to support framework awareness, \arara\ provides a mechanism for data sharing across rule contexts, implemented as a \rbox{Session} object. In practical terms, this particular object is a global, persistent map composed of \rbox{String} keys and \rbox{Object} values available throughout the entire execution. The public methods of a session are described as follows:
\begin{description}
-\item[\mtbox{insert(String key, Object value)}\hfill\rrbox{void}] This method, as the name implies, inserts an object into the session, indexed by the provided key. Observe that, if the session previously contained a mapping for the provided key, the old value is replaced by the specified value.
+\item[\mtbox{put(String key, Object value)}\hfill\rrbox{void}] This method, as the name implies, inserts an object into the session, indexed by the provided key. Observe that, if the session previously contained a mapping for the provided key, the old value is replaced by the specified value.
\item[\mtbox{remove(String key)}\hfill\rrbox{void}] This method, as the name implies, removes the mapping for the provided key from the session. Be mindful that an attempt to remove a mapping for a nonexistent key will raise an exception.
-\item[\mtbox{exists(String key)}\hfill\rrbox{boolean}] This method, as the name implies, returns a boolean value according to whether the session contains a mapping for the provided key. It is highly advisable to use this method before attempting to remove a mapping from the session.
+\item[\mtbox{contains(String key)}\hfill\rrbox{boolean}] This method, as the name implies, returns a boolean value according to whether the session contains a mapping for the provided key. It is highly advisable to use this method before attempting to remove a mapping from the session.
-\item[\mtbox{obtain(String key)}\hfill\rrbox{Object}] This method, as the name implies, returns the object value to which the specified key is mapped. Be mindful that an attempt to return a value for a nonexistent key will raise an exception.
+\item[\mtbox{get(String key)}\hfill\rrbox{Object}] This method, as the name implies, returns the object value to which the specified key is mapped. Be mindful that an attempt to return a value for a nonexistent key will raise an exception.
\item[\mtbox{forget()}\hfill\rrbox{void}] This method, as the name implies, removes all of the existing mappings from the session. The session object will be effectively empty after this call returns.
\end{description}
@@ -999,7 +899,7 @@ It is important to observe that the \rbox{Session} object provided by our tool f
\item[\mdbox{R}{getSession()}{Session}] This method, as the name implies, returns the \rbox{Session} object for data sharing across rule contexts. Keep in mind that a session cannot contain duplicate keys. Each key can map to at most one value.
\begin{codebox}{Example}{teal}{\icnote}{white}
-name = getSession().obtain('name');
+name = getSession().get('name');
\end{codebox}
\item[\mdbox{R}{throwError(String message)}{void}] This method deliberately throws an error to be intercepted later on during execution. Consider using such method for an explicit notification about unexpected or unsought scenarios, e.g, wrong parameter types or values. The raised error has an associated message which is displayed in the terminal and added to the log file.
@@ -1033,6 +933,10 @@ According to the \href{https://en.wikipedia.org/wiki/PATH_(variable)}{Wikipedia
result = unsafelyExecuteSystemCommand(getCommand('ls'));
\end{codebox}
+\begin{messagebox}{Important change in version 5.0}{araracolour}{\icattention}{white}
+\textbf{Working directory support} -- \arara\ now executes commands obtained from \rbox{getCommandWithWorkingDirectory} correctly. Previously, the working directory got silently ignored. This makes \arara\ even more powerful but we decided to change this for the sake of consistency.
+\end{messagebox}
+
\begin{messagebox}{Hic sunt leones}{attentioncolour}{\icattention}{black}
Please \emph{do not abuse} this method! Keep in mind that this particular feature is included for very specific scenarios in which the command streams are needed ahead of time for proper decision making.
\end{messagebox}
@@ -1042,25 +946,20 @@ Please \emph{do not abuse} this method! Keep in mind that this particular featur
\begin{codebox}{Example}{teal}{\icnote}{white}
valid = isSubdirectory(toFile('chapters/'));
\end{codebox}
+\end{description}
-\item[\mdbox{R}{\parbox{0.62\textwidth}{mergeVelocityTemplate(File input, File output,\\\hspace*{1em} Map<String, Object> map)}}{void}] This method, as the name implies, merges the provided \rbox{File} template reference written in the Velocity Template Language 1.7 specification with the \rbox{Map} data object in order to produce a corresponding \rbox{File} output. It is important to observe that this method will raise an exception if the provided input file does not exist or if there is an error with the underlying template language.
-
-\begin{ncodebox}{Source file}{teal}{\icnote}{white}{input.txt}
-Hello, my name is ${name} and
-I am from ${country}!
-\end{ncodebox}
+\begin{messagebox}{Flags and reserved storage in a session}{araracolour}{\icok}{white}
+Within a session there are two ``reserved'' namespaces: \verb|arara| and \verb|environment|. The latter is quite intuitive: \arara\ will store the current state of the systems environment variables in its session. You may alter these values in the session storage but they will not be written back to the system configuration. To access an environment variable, you can use its usual name prefixed by \verb|environment:|.
\begin{codebox}{Example}{teal}{\icnote}{white}
-mergeVelocityTemplate(toFile('input.txt'), toFile('output.txt'),
- [ 'name' : 'Paulo', 'country' : 'Brazil' ])
+path = getSession().get('environment:PATH');
\end{codebox}
-\begin{messagebox}{Velocity Template Language 1.7}{attentioncolour}{\icattention}{black}
-\setlength{\parskip}{1em}
-As of 2017, the Apache Foundation has released the new 2.0 version for the Velocity Template Language. However, this particular version introduces behavioural and syntactic changes that may cause problems with older versions.
+The \verb|arara| namespace is a bit different. It provides flags that control \arara s behaviour. Flags are used in rules and may be manipulated by the user. Be aware, that every change in this namespace will result in \arara\ acting like you know what you did. Use this power with care. Currently, there is only one relevant flag: \verb|arara:FILENAME:halt|. This will stop the currently run command execution on the file with the specified file name. The value of this map entry is the exit status you want \arara\ to have.
-In order to maintain compatibility with older Java virtual machines, \arara\ works with the \href{http://velocity.apache.org/engine/1.7/vtl-reference.html}{VTL 1.7 specification}, so it is highly recommended to strictly adhere to this reference when writing templates for the corresponding method or the official \rbox{velocity} rule.
+\begin{codebox}{Example}{teal}{\icnote}{white}
+path = getSession().put('arara:myfile.tex:halt', 42);
+\end{codebox}
\end{messagebox}
-\end{description}
The methods presented in this section provide interesting features for persistent data sharing, error handling, early command execution, and templating. It is important to note that more classes, objects and methods can be incorporated into \arara\ through class loading and object instantiation, extending the features and enhancing the overall user experience.