summaryrefslogtreecommitdiff
path: root/support/arara/doc/chapters/concepts.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/arara/doc/chapters/concepts.tex')
-rw-r--r--support/arara/doc/chapters/concepts.tex305
1 files changed, 89 insertions, 216 deletions
diff --git a/support/arara/doc/chapters/concepts.tex b/support/arara/doc/chapters/concepts.tex
index 0a8d168fe7..acd96f0fe1 100644
--- a/support/arara/doc/chapters/concepts.tex
+++ b/support/arara/doc/chapters/concepts.tex
@@ -15,7 +15,7 @@ A \emph{rule} is a formal description of how \arara\ handles a certain task. For
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
-Processing 'doc1.tex' (size: 83 bytes, last modified: 05/03/2018
+Processing 'doc1.tex' (size: 83 B, last modified: 05/03/2018
12:10:33), please wait.
I could not find a rule named 'foo' in the provided rule paths.
@@ -28,7 +28,11 @@ Total: 0.09 seconds
Once a rule is defined, \arara\ automatically provides an access layer to that rule through directives in the source code, a concept to be formally introduced later on, in Section~\ref{sec:directives}. Observe that a directive reflects a particular instance of a rule of the same name (i.e, a \rbox{foo} directive in a certain source code is an instance of the \rbox{foo} rule).
-In short, a rule is a plain text file written in the \gls{YAML} format, described in Chapter~\ref{chap:yaml}, on page~\pageref{chap:yaml}. I opted for this format because back then it was cleaner and more intuitive to use than other markup languages such as \gls{XML}, besides of course being a data serialization standard for programming languages.
+\begin{messagebox}{A note about rules}{attentioncolour}{\icattention}{black}
+For version 5.0, we kept the current YAML rule scheme. However, the names of the rules being public are marked as deprecated, as they might change in future versions.
+\end{messagebox}
+
+In short, a rule is a plain text file written in the YAML format, described in Chapter~\ref{chap:yaml}, on page~\pageref{chap:yaml}. I opted for this format because back then it was cleaner and more intuitive to use than other markup languages such as XML, besides of course being a data serialization standard for programming languages.
\begin{messagebox}{Animal jokes}{araracolour}{\icok}{white}
As a bonus, the acronym \emph{YAML} rhymes with the word \emph{camel}, so \arara\ is heavily environmentally friendly. Speaking of camels, there is the programming reference as well, since this amusing animal is usually associated with Perl and friends.
@@ -36,12 +40,12 @@ As a bonus, the acronym \emph{YAML} rhymes with the word \emph{camel}, so \arara
The default rules, i.e, the rules shipped with \arara, are placed inside a special subdirectory named \abox[araracolour]{rules/} inside another special directory named \abox[araracolour]{ARARA\_HOME} (the place where our tool is installed). We will learn later on, in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}, that we can add an arbitrary number of paths for storing our own rules, in order of priority, so do not worry too much about the location of the default rules, although it is important to understand and acknowledge their existence.
-The following list describes the basic structure of an \arara\ rule by presenting the proper elements (or keys, if we consider the proper \gls{YAML} nomenclature). Observe that elements marked as \rbox[araracolour]{M} are mandatory (i.e, the rule \emph{has} to have them in order to work). Similarly, elements marked as \rbox[araracolour]{O} are optional, so you can safely ignore them when writing a rule for our tool. A key preceded by \rbox{context$\rightarrow$} indicates a context and should be properly defined inside it.
+The following list describes the basic structure of an \arara\ rule by presenting the proper elements (or keys, if we consider the proper YAML nomenclature). Observe that elements marked as \rbox[araracolour]{M} are mandatory (i.e, the rule \emph{has} to have them in order to work). Similarly, elements marked as \rbox[araracolour]{O} are optional, so you can safely ignore them when writing a rule for our tool. A key preceded by \rbox{context$\rightarrow$} indicates a context and should be properly defined inside it.
\begin{description}
\item[\describe{M}{!config}] This keyword is mandatory and must be the first line of any \arara\ rule. It denotes the object mapping metadata to be internally used by the tool. Actually, the tool is not too demanding on using it (in fact, you could suppress it entirely and \arara\ will not complain), but it is considered good practice to start all rules with a \abox{!config} keyword regardless.
-\item[\describe{M}{identifier}] This key acts as a unique identifier for the rule (as expected). It is highly recommended to use lowercase letters without spaces, accents or punctuation symbols, as good practice (again). As a convention, if you have an identifier named \rbox{pdflatex}, the rule filename must be \rbox{pdflatex.yaml} (like our own instance). Please note that, although \rbox{yml} is known to be a valid \gls{YAML} extension as well, \arara\ only considers files ending with the \rbox{yaml} extension. This is a deliberate decision.
+\item[\describe{M}{identifier}] This key acts as a unique identifier for the rule (as expected). It is highly recommended to use lowercase letters without spaces, accents or punctuation symbols, as good practice (again). As a convention, if you have an identifier named \rbox{pdflatex}, the rule filename must be \rbox{pdflatex.yaml} (like our own instance). Please note that, although \rbox{yml} is known to be a valid YAML extension as well, \arara\ only considers files ending with the \rbox{yaml} extension. This is a deliberate decision.
\begin{codebox}{Example}{teal}{\icnote}{white}
identifier: pdflatex
@@ -61,29 +65,17 @@ authors:
- Paulo Cereda
\end{codebox}
-\item[\describe{M}{commands}] This key is introduced in version 4.0 of \arara\ and denotes a potential list of commands. From the user perspective, each command is called a \emph{subtask} within a task (rule and directive) context. A task may represent only a single command (a single subtask), as well as a sequence of commands (subtasks). For instance, the \rbox{frontespizio} rule requires at least two commands. So, as a means of normalizing the representation, a task composed of a single command (single subtask) is defined as the only element of the list, as opposed to previous versions of \arara, which had a specific key to hold just one command.
-
-\begin{messagebox}{Incompatibility with older versions}{attentioncolour}{\icerror}{black}
-Dear reader, note that rules from version 4.0 are incompatible with older versions of \arara. If you are migrating from old versions to version 4.0, we need to replace \abox{command} by \abox{commands} and specify a contextual element, as seen in the following descriptions. Please refer to Section~\ref{sec:migrationguide}, on page~\pageref{sec:migrationguide}, for a comprehensible migration guide.
-\end{messagebox}
+\item[\describe{M}{commands}] This key denotes a potential list of commands. From the user perspective, each command is called a \emph{subtask} within a task (rule and directive) context. A task may represent only a single command (a single subtask), as well as a sequence of commands (subtasks). For instance, the \rbox{frontespizio} rule requires at least two commands. So, as a means of normalizing the representation, a task composed of a single command (single subtask) is defined as the only element of the list, as opposed to previous versions of \arara, which had a specific key to hold just one command.
In order to properly set a subtask, the keys used in this specification are defined inside the \rbox{commands$\rightarrow$} context and presented as follows.
\begin{description}
\item[\describecontext{O}{commands}{name}] This key holds the name of the subtask as a plain string. When running \arara, this value will be displayed in the output. Subtask names are displayed after the main task name. By the way, did you notice that this key is entirely optional? That means that a subtask can simply be unnamed, if you decide so. However, such practice is not recommended, as it's always good to have a visual description of what \arara\ is running at the moment, so name your subtasks properly.
-\item[\describecontext{M}{commands}{command}] This key holds the action to be performed, typically a system command. In previous versions, \arara\ would rely solely on a string. For this version on, as a means to enhance the user experience (and also fix serious blockers when handling spaces in file names, as seen in \href{https://github.com/cereda/arara/issues}{previous issues} reported in the repository), the tool offers four types of returned values:
+\item[\describecontext{M}{commands}{command}] This key holds the action to be performed, typically a system command. The tool offers two types of returned values:
\begin{itemize}[label={--}]
-\item A plain string: this is the default (and only) behaviour in older versions of \arara. The plain string is processed as it is by the underlying execution engine. However, automatic argument parsing is problematic, so this approach, although supported, is not recommended any more.
-
-\begin{codebox}{Example}{teal}{\icnote}{white}
-command: 'ls'
-\end{codebox}
-
-It is important to observe that you can use either a plain string directly or use an \gls{orb-tag} with an explicit \rbox{return} command (as seen in Section~\ref{sec:mvelbasicusage}, on page~\pageref{sec:mvelbasicusage}). Personally, I favour the explicit indication for a quick understanding.
-
-\item A \rbox{Command} object: \arara\ 4.0 features a new approach for handling system commands based on a high level structure with explicit argument parsing named \rbox{Command} (for our curious users, it is a plain Java object). In order to use this approach, we need to rely on \glspl{orb-tag} and use a helper method named \mtbox{getCommand} to obtain the desired result. We will detail this method later on, in Section~\ref{sec:commandsandtriggers}, on page~\pageref{sec:commandsandtriggers}. We highly recommend the adoption of this approach for rule writing instead of using plain strings.
+\item A \rbox{Command} object: \arara\ features an approach for handling system commands based on a high level structure with explicit argument parsing named \rbox{Command} (for our curious users, it is a plain Java object). In order to use this approach, we need to rely on orb tags and use a helper method named \mtbox{getCommand} to obtain the desired result. We will detail this method later on, in Section~\ref{sec:commands}, on page~\pageref{sec:commands}. We highly recommend the adoption of this approach for rule writing instead of using plain strings.
\begin{codebox}{Example}{teal}{\icnote}{white}
command: "@{ return getCommand('ls') }"
@@ -94,33 +86,27 @@ command: "@{ return getCommand('ls') }"
\begin{codebox}{Example}{teal}{\icnote}{white}
command: "@{ return 1 == 1 }"
\end{codebox}
-
-\item A \rbox{Trigger} object: this is surely the least common type of returned value and it is mentioned here just for documentation purposes. In simple terms, a \rbox{Trigger} object constitutes a special command that changes the internal workings of \arara\ at runtime. We have not worked much on this concept, so there is only one trigger available, seen in action in the official \rbox{halt} rule. In order to use this approach, we need to rely on \glspl{orb-tag} and use a helper method named \mtbox{getTrigger} to obtain the desired result.
\end{itemize}
-It is also worth mentioning that \arara\ also supports lists of commands represented as plain strings, \rbox{Command} or \rbox{Trigger} objects, boolean values or a mix of them. This is useful if your rule has to decide whether more actions are required in order to accomplish a task. In this case, our tool will take care of the list and execute each element in the specified order.
+It is also worth mentioning that \arara\ also supports lists of commands represented as \rbox{Command} objects, boolean values or a mix of them. This is useful if your rule has to decide whether more actions are required in order to accomplish a task. In this case, our tool will take care of the list and execute each element in the specified order.
\begin{codebox}{Example}{teal}{\icnote}{white}
-command: "@{ return [ 'ls', 'ls', 'ls' ] }"
+command: "@{ return [ getCommand('ls'), getCommand('ls') ] }"
\end{codebox}
As an example, please refer to the official \rbox{clean} rule for a real scenario where a list of commands is successfully employed: for each provided extension, the rule creates a new cleaning command and adds it to a list of removals to be processed later.
-\begin{messagebox}{Plain string is deprecated}{attentioncolour}{\icattention}{black}
-It took me a lot of effort to find out that handling plain strings and employing guesswork to parse arguments are the root of several issues reported by users. Therefore, this approach is being marked as \emph{deprecated} and will be removed in future versions.
-\end{messagebox}
-
-There are at least two variables available in the \abox{command} context and are described as follows (note that \gls{MVEL} variables and \glspl{orb-tag} are discussed in Chapter~\ref{chap:mvel}). A variable will be denoted by \varbox{variable} in this list. For each rule argument (defined later on), there will be a corresponding variable in the \abox{command} context, directly accessed through its unique identifier.
+There are at least two variables available in the \abox{command} context and are described as follows (note that MVEL variables and orb tags are discussed in Chapter~\ref{chap:mvel}). A variable will be denoted by \varbox{variable} in this list. For each rule argument (defined later on), there will be a corresponding variable in the \abox{command} context, directly accessed through its unique identifier.
\begin{description}
\item[\varbox{file}] This variable holds the file name, without any path reference, as a plain string. It is usually composed from the base name and the extension. This variable is available since the first release of \arara.
-\item[\varbox{reference}] This variable is introduced in version 4.0 of \arara\ and holds the canonical, absolute path representation of the \varbox{file} variable as a \rbox{File} object. This is useful if it's necessary to know the hierarchical structure of a project. Since the reference is a Java object, we can use all methods available in the \rbox{File} class.
+\item[\varbox{reference}] This variable holds the canonical, absolute path representation of the \varbox{file} variable as a \rbox{File} object. This is useful if it's necessary to know the hierarchical structure of a project. Since the reference is a Java object, we can use all methods available in the \rbox{File} class.
\end{description}
\begin{messagebox}{Quote handling}{araracolour}{\icinfo}{white}
\setlength{\parskip}{1em}
-The \gls{YAML} format disallows key values starting with \rbox{@} without proper quoting. This is the reason we had to use double quotes for the value and internally using single quotes for the command string. Also, we could use the other way around, or even using only one type and then escaping them when needed. This is excessively verbose but needed due to the format requirement. Thankfully, \arara\ offers two solutions for removing the quoting verbosity when writing commands.
+The YAML format disallows key values starting with \rbox{@} without proper quoting. This is the reason we had to use double quotes for the value and internally using single quotes for the command string. Also, we could use the other way around, or even using only one type and then escaping them when needed. This is excessively verbose but needed due to the format requirement. Thankfully, \arara\ offers two solutions for removing the quoting verbosity when writing commands.
The first solution is used in previous versions and it still works like a charm in modern days. We need to precede our command with a special keyword \rbox{<arara>} which will be removed afterwards. This solution works on virtually every key in the rule context, so it is a bonus. The new code will look like this:
@@ -128,7 +114,7 @@ The first solution is used in previous versions and it still works like a charm
command: <arara> @{ return getCommand('ls') }
\end{codebox}
-The second approach is more of a \gls{YAML} feature rather than a tool exclusive, although we have to do a couple of checks under the hood in order to ensure the correct execution. The idea here is to use the scalar content in folded style, as seen in Section~\ref{sec:yamlscalars}, on page~\pageref{sec:yamlscalars}. The new code will look like this:
+The second approach is more of a YAML feature rather than a tool exclusive, although we have to do a couple of checks under the hood in order to ensure the correct execution. The idea here is to use the scalar content in folded style, as seen in Section~\ref{sec:yamlscalars}, on page~\pageref{sec:yamlscalars}. The new code will look like this:
\begin{codebox}{Example}{teal}{\icnote}{white}
command: >
@@ -137,10 +123,10 @@ command: >
}
\end{codebox}
-Mind the indentation, as \gls{YAML} requires it to properly identify blocks. I personally recommend this approach for longer code, as it provides a better visual representation. You will see the second solution all around the default rules, but feel free to use the one you feel more comfortable with.
+Mind the indentation, as YAML requires it to properly identify blocks. Please keep in mind that the \rbox{<arara>} keyword is marked as deprecated in version 5.0 and will be removed in future versions of \arara, so it is highly recommended to favour this approach.
\end{messagebox}
-\item[\describecontext{O}{commands}{exit}] This key holds a special purpose in \arara\ 4.0, as it represents a custom exit status evaluation for the corresponding command. In general, a successful execution has zero as an exit status, but sometimes we end up with tools or situations where we need to override this check for whatever reason. For this purpose, simply write a \gls{MVEL} expression \emph{without \glspl{orb-tag}} as plain string and use the special variable \varbox{value} if you need the actual exit status returned by the command, available at runtime. For example, if the command returns a non-zero value indicating a successful execution, we can write this key as:
+\item[\describecontext{O}{commands}{exit}] This key holds a special purpose, as it represents a custom exit status evaluation for the corresponding command. In general, a successful execution has zero as an exit status, but sometimes we end up with tools or situations where we need to override this check for whatever reason. For this purpose, simply write a MVEL expression \emph{without orb tags} as plain string and use the special variable \varbox{value} if you need the actual exit status returned by the command, available at runtime. For example, if the command returns a non-zero value indicating a successful execution, we can write this key as:
\begin{codebox}{Example}{teal}{\icnote}{white}
exit: value > 0
@@ -199,10 +185,10 @@ There are three variables available in the \abox{flag} context, described as fol
\item[\varbox{file}] This variable holds the file name, without any path reference, as a plain string. It is usually composed from the base name and the extension. This variable is available since the first release of \arara.
-\item[\varbox{reference}] This variable is introduced in version 4.0 of \arara\ and holds the canonical, absolute path representation of the \varbox{file} variable as a \rbox{File} object. This is useful if it's necessary to know the hierarchical structure of a project. Since the reference is a Java object, we can use all methods available in the \rbox{File} class.
+\item[\varbox{reference}] This variable holds the canonical, absolute path representation of the \varbox{file} variable as a \rbox{File} object. This is useful if it's necessary to know the hierarchical structure of a project. Since the reference is a Java object, we can use all methods available in the \rbox{File} class.
\end{description}
-In the previous example, observe that the \gls{MVEL} expression defined in the \abox{flag} key checks if the user provided an affirmative value regarding shell escape, through comparing \varbox{parameters.shell} with a set of predefined affirmative values. In any case, the corresponding command flag is defined as result of such evaluation.
+In the previous example, observe that the MVEL expression defined in the \abox{flag} key checks if the user provided an affirmative value regarding shell escape, through comparing \varbox{parameters.shell} with a set of predefined affirmative values. In any case, the corresponding command flag is defined as result of such evaluation.
\item[\describecontext{O}{arguments}{default}] As default behaviour, if a parameter is not set in the directive context, the reference will be mapped to an empty string. This key exists for the exact purpose of overriding such behaviour.
@@ -217,7 +203,7 @@ There are three variables available in the \abox{default} context, described as
\item[\varbox{file}] This variable holds the file name, without any path reference, as a plain string. It is usually composed from the base name and the extension. This variable is available since the first release of \arara.
-\item[\varbox{reference}] This variable is introduced in version 4.0 of \arara\ and holds the canonical, absolute path representation of the \varbox{file} variable as a \rbox{File} object. This is useful if it's necessary to know the hierarchical structure of a project. Since the reference is a Java object, we can use all methods available in the \rbox{File} class.
+\item[\varbox{reference}] This variable holds the canonical, absolute path representation of the \varbox{file} variable as a \rbox{File} object. This is useful if it's necessary to know the hierarchical structure of a project. Since the reference is a Java object, we can use all methods available in the \rbox{File} class.
\end{description}
\item[\describecontext{O}{arguments}{required}] There might be certain scenarios in which a rule could make use of required arguments (for instance, a copy operation in which source and target must be provided). The \abox{required} key acts as a boolean switch to indicate whether the corresponding argument should be mandatory. In this case, set the key value to \rbox{true} and the argument becomes required. Later on at runtime, \arara\ will throw an error if a required parameter is missing in the directive.
@@ -249,21 +235,13 @@ arguments:
\end{codebox}
\end{description}
-This is the rule structure in the \gls{YAML} format used by \arara. Keep in mind that all subtasks in a rule are checked against their corresponding exit status. If an abnormal execution is detected, the tool will instantly halt and the rule will fail. Even \arara\ itself will return an exit code different than zero when this situation happens (detailed in Chapter~\ref{chap:commandline}, on page~\pageref{chap:commandline}).
+This is the rule structure in the YAML format used by \arara. Keep in mind that all subtasks in a rule are checked against their corresponding exit status. If an abnormal execution is detected, the tool will instantly halt and the rule will fail. Even \arara\ itself will return an exit code different than zero when this situation happens (detailed in Chapter~\ref{chap:commandline}, on page~\pageref{chap:commandline}).
\section{Directives}
\label{sec:directives}
A \emph{directive} is a special comment inserted in the source file in which you indicate how \arara\ should behave. You can insert as many directives as you want and in any position of the file. The tool will read the whole file and extract the directives.
-\begin{messagebox}{New features in version 4.0}{araracolour}{\icinfo}{white}
-\setlength{\parskip}{1em}
-\textbf{Partial directive extraction} -- From version 4.0 of \arara\ on, it is now possible to extract directives only available in the file preamble, i.e, all lines from the beginning that are comments until reaching the first line that is not a comment (excluding blank lines). To this end, a new command line flag is introduced in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}.
-
-\textbf{Predefined preambles} -- Common preambles can be predefined and used with files that require the same automation steps, then \arara\ can be invoked based on such specifications. This feature is covered in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}.
-\end{messagebox}
-
-
There are two types of directives in \arara\ which determine the way the corresponding rules will be instantiated. They are listed as follows. Note that directives are always preceded by the \rbox{arara:} pattern.
\begin{description}
@@ -273,7 +251,7 @@ There are two types of directives in \arara\ which determine the way the corresp
% arara: pdflatex
\end{codebox}
-\item[parametrized directive] This type of directive also has the rule name (which refers to the \abox{identifier} key from the rule of the same name), and also contains a map of parameters in order to provide additional information to the corresponding rule. This map is defined in the \gls{YAML} format, based on the inline style.
+\item[parametrized directive] This type of directive also has the rule name (which refers to the \abox{identifier} key from the rule of the same name), and also contains a map of parameters in order to provide additional information to the corresponding rule. This map is defined in the YAML format, based on the inline style.
\begin{codebox}{Parametrized directive}{teal}{\icnote}{white}
% arara: pdflatex: { shell: yes }
@@ -296,7 +274,7 @@ When handling parametrized directives, \arara\ always checks if directive parame
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
-Processing 'hello.tex' (size: 103 bytes, last modified:
+Processing 'hello.tex' (size: 103 B, last modified:
05/03/2018 15:40:16), please wait.
I have spotted an error in rule 'pdflatex' located at
@@ -309,11 +287,7 @@ Total: 0.21 seconds
As the message suggests, we need to remove the unknown parameter key from our directive or rewrite the rule in order to include it as an argument. The first option is, of course, easier.
-\begin{messagebox}{New feature in version 4.0}{araracolour}{\icinfo}{white}
-\textbf{Helpful messages} -- It is a staple of \arara\ to have friendly and helpful messages. From version 4.0 on, we decided to make messages even friendlier and include suggestions for correcting errors or improving usage. So, whenever possible, make sure to read all messages our tool provides, they will help you!
-\end{messagebox}
-
-Sometimes, directives can span several columns of a line, particularly the ones with several parameters. From \arara\ 4.0 on, we can split a directive into multiple lines by using the \rbox{arara: {-}{-}>} mark (also known as \emph{arrow notation} during development) to each line which should compose the directive. We call it a \emph{multiline directive}. Let us see an example:
+Sometimes, directives can span several columns of a line, particularly the ones with several parameters. We can split a directive into multiple lines by using the \rbox{arara: {-}{-}>} mark (also known as \emph{arrow notation} during development) to each line which should compose the directive. We call it a \emph{multiline directive}. Let us see an example:
\begin{codebox}{Multiline directive}{teal}{\icnote}{white}
% arara: pdflatex: {
@@ -328,28 +302,28 @@ It is important to observe that there is no need of them to be in contiguous lin
Although it is possible to spread lines of a multiline directive all over the code, it is considered good practice to keep them together for easier reading and editing. In any case, you can always see which lines compose a directive by inspecting the log file.
\end{messagebox}
-\arara\ 4.0 provides logical expressions, written in the \gls{MVEL} language, and special operators processed at runtime in order to determine whether and how a directive should be processed. This feature is named \emph{directive conditional}, or simply \emph{conditional} as an abbreviation. The following list describes all conditional operators available in the directive context.
+\arara\ provides logical expressions, written in the MVEL language, and special operators processed at runtime in order to determine whether and how a directive should be processed. This feature is named \emph{directive conditional}, or simply \emph{conditional} as an abbreviation. The following list describes all conditional operators available in the directive context.
\begin{description}
-\item[\describeconditional{a priori}{if}] The associated \gls{MVEL} expression is evaluated beforehand, and the directive is interpreted if, and only if, the result of such evaluation is true. This directive, when the conditional holds true, is executed at most once.
+\item[\describeconditional{a priori}{if}] The associated MVEL expression is evaluated beforehand, and the directive is interpreted if, and only if, the result of such evaluation is true. This directive, when the conditional holds true, is executed at most once.
\begin{codebox}{Conditional}{teal}{\icnote}{white}
% arara: pdflatex if missing('pdf') || changed('tex')
\end{codebox}
-\item[\describeconditional{a posteriori}{until}] The directive is interpreted the first time, then the associated \gls{MVEL} expression evaluation is done. While the result holds false, the directive is interpreted again and again. There are no guarantees of proper halting.
+\item[\describeconditional{a posteriori}{until}] The directive is interpreted the first time, then the associated MVEL expression evaluation is done. While the result holds false, the directive is interpreted again and again. There are no guarantees of proper halting.
\begin{codebox}{Conditional}{teal}{\icnote}{white}
% arara: pdflatex until !found('log', 'undefined references')
\end{codebox}
-\item[\describeconditional{a priori}{unless}] Technically an inverted \cdbox{if} conditional, the associated \gls{MVEL} expression is evaluated beforehand, and the directive is interpreted if, and only if, the result is false. This directive, when the conditional holds false, is executed at most once.
+\item[\describeconditional{a priori}{unless}] Technically an inverted \cdbox{if} conditional, the associated MVEL expression is evaluated beforehand, and the directive is interpreted if, and only if, the result is false. This directive, when the conditional holds false, is executed at most once.
\begin{codebox}{Conditional}{teal}{\icnote}{white}
% arara: pdflatex unless unchanged('tex') && exists('pdf')
\end{codebox}
-\item[\describeconditional{a priori}{while}] The associated \gls{MVEL} expression is evaluated beforehand, the directive is interpreted if, and only if, the result is true, and the process is repeated while the result still holds true. There are no guarantees of proper halting.
+\item[\describeconditional{a priori}{while}] The associated MVEL expression is evaluated beforehand, the directive is interpreted if, and only if, the result is true, and the process is repeated while the result still holds true. There are no guarantees of proper halting.
\begin{codebox}{Conditional}{teal}{\icnote}{white}
% arara: pdflatex while missing('pdf') ||
@@ -407,199 +381,98 @@ It is important to observe that, in this case, \rbox{doc3.tex} is a plain \TeX\
Even when a directive is interpreted with a file other than the one being processed by \arara\ (through the magic of the \abox{files} parameter), it is possible to use helper methods in the rule context to get access to the original file and reference. Such methods are detailed later on, in Section~\ref{sec:files}, on page~\pageref{sec:files}.
-\section{Migration guide}
+\section{Important changes in version 5.0}
\label{sec:migrationguide}
\begin{messagebox}{A note to users}{araracolour}{\icattention}{white}
If this is your first time using \arara\ or you do not have custom rules in the old format, you can safely ignore this section. All rules shipped with our tool are already written in the new format.
\end{messagebox}
-As previously discussed in Section~\ref{sec:rule}, on page~\pageref{sec:rule}, version 4.0 of \arara\ introduces a new rule format. As a result, user-defined rules in the old format are incompatible with the new version of our tool and thus have to be updated. In short, we need to replace \abox{command} by \abox{commands} and specify a contextual element. As an example, consider the following hypothetical rule \rbox{ls} written in the old format:
+\begin{messagebox}{Removal of triggers}{araracolour}{\icattention}{white}
+\arara\ previously had the concept of triggers which allowed to easily trigger events like halting \arara. As of version 5.0, support for triggers has been dropped due to the lack of use cases.
-\begin{codebox}{A rule in the old format}{teal}{\icnote}{white}
-!config
-identifier: ls
-name: LS
-command: ls @{details}
-arguments:
-- identifier: details
- flag: '@{ isTrue(parameters.details, "-l", "") }'
-\end{codebox}
+As the only pre-defined trigger has been \rbox{halt} we did not deprecate the ability to halt the application. However, the new mechanism uses the concept of session values (see \autoref{sec:others}).
+\end{messagebox}
-This rule does nothing too important, it simply runs the system command \rbox{ls} which lists the contents of the current directory. However, when we try to run \arara\ on a file which contains a directive referencing this rule, we get the following error in the terminal:
+\begin{messagebox}{Removal of Velocity support}{araracolour}{\icinfo}{white}
+\arara\ featured support for the Velocity Template Language. In version 5.0, this support has been removed. We decided in favour of this breaking change to achieve more independence from third-party modules and to avoid being stuck at version~1.7 for compatibility reasons.
-\begin{codebox}{Terminal}{teal}{\icnote}{white}
- __ _ _ __ __ _ _ __ __ _
- / _` | '__/ _` | '__/ _` |
-| (_| | | | (_| | | | (_| |
- \__,_|_| \__,_|_| \__,_|
+Due to this change, \arara\ does not ship support for any templating language at the moment. If you are interested in getting a templating language on board, you are welcome to support our efforts to make the inclusion of JVM code on the user-side more pleasant.
+\end{messagebox}
-Processing 'doc4.tex' (size: 31 bytes, last modified: 05/27/2018
-21:05:57), please wait.
+\begin{messagebox}{Removal of string-based commands}{araracolour}{\icinfo}{white}
+Up to version 5.0 you could simply use
-I have spotted an error in rule 'ls' located at '/home/paulo'. I
-could not parse the rule, something bad happened. Apparently, the
-provided YAML file is invalid. I will do my best to help you in
-any way I can. There are more details available on this
-exception:
+\begin{codebox}{Return statement}{teal}{\icnote}{white}
+return "command";
+\end{codebox}
-DETAILS ---------------------------------------------------------
-Cannot create property=command for
-JavaBean=com.github.cereda.arara.model.Rule@29774679
- in
-'reader', line 1, column 1:
- !config
- ^
-Unable to find
-property 'command' on class: com.github.cereda.arara.model.Rule
+\noindent in your rules. This resulted in \arara\ implicitly constructing a command object. As this does not make clear that this command is actually run, we now enforce the usage of
-in 'reader', line 4, column 10:
- command: ls @{details}
-
- ^
+\vspace{1em}
+\mdbox{R}{getCommand(List<String> commands)}{Command}
-Total: 0.03 seconds
-\end{codebox}
+\vspace{1em}
-The above terminal output shows the usual error \arara\ raises when a rule in the old format is used, and thus the corresponding \gls{YAML} file is considered invalid. In order to fix the rule, we need to move the \abox{command} key inside a \rbox{commands$\rightarrow$} context as a list element, as seen as follows.
+\noindent in the \rbox{return} statement. Hence, the new way of doing the same is (with either single or double quote pairs):
-\begin{codebox}{A rule converted into the new format}{teal}{\icnote}{white}
-!config
-identifier: ls
-name: LS
-commands:
-- command: ls @{details}
-arguments:
-- identifier: details
- flag: '@{ isTrue(parameters.details, "-l", "") }'
+\begin{codebox}{Return statement}{teal}{\icnote}{white}
+return getCommand("command");
\end{codebox}
+\end{messagebox}
-Note that this fix is sufficient to make the rule valid in the new format. Also, it is interesting to observe that the subtask will be unnamed during the execution, as there is no corresponding \abox{name} key in the list element.
+\begin{messagebox}{Methods: removal and change of name}{araracolour}{\icinfo}{white}
+The following previously available methods (and repective overloaded variants) have been removed:
+
+\begin{itemize}
+\item[\textcolor{warningcolour}{\faClose}] \mdbox{R}{addQuotes(String string)}{String}
+\item[\textcolor{warningcolour}{\faClose}] \mdbox{R}{isAIX()}{boolean}
+\item[\textcolor{warningcolour}{\faClose}] \mdbox{R}{isIrix()}{boolean}
+\item[\textcolor{warningcolour}{\faClose}] \mdbox{R}{isOS2()}{boolean}
+\item[\textcolor{warningcolour}{\faClose}] \mdbox{R}{isSolaris()}{boolean}
+\item[\textcolor{warningcolour}{\faClose}] \mdbox{R}{getFullBasename(File file)}{String}
+\item[\textcolor{warningcolour}{\faClose}] \mdbox{R}{\parbox{0.62\textwidth}{mergeVelocityTemplate(File input,\\\hspace*{1em} File output, Map<String, Object> map)}}{void}
+\end{itemize}
-\begin{codebox}{Terminal}{teal}{\icnote}{white}
-(LS) Unnamed task ....................................... SUCCESS
-\end{codebox}
+The following methods have been renamed:
+\begin{itemize}
+\item[\textcolor{warningcolour}{\faClose}] \mdbox{R}{(Session.)insert(String key, Object value)}{void}
-Now, let us consider an example containing a list of commands, also based on the old format. The \rbox{ls} rule was updated to include two runs of the system command of the same name in the current directory:
+\vspace{.5em}
-\begin{codebox}{A rule in the old format}{teal}{\icnote}{white}
-!config
-identifier: ls
-name: LS
-commands:
-- ls @{details}
-- ls @{details}
-arguments:
-- identifier: details
- flag: '@{ isTrue(parameters.details, "-l", "") }'
-\end{codebox}
+\hspace{2cm}\textcolor{teal}{\faArrowDown}
-Observe that the old format directly represents commands as a list of plain strings. When trying to run \arara\ on a file which contains a directive referencing the updated \rbox{ls} rule, we get the following error in the terminal:
+\item[\textcolor{okcolour}{\faCheck}]\mdbox{R}{(Session.)put(String key, Object value)}{void}
-\begin{codebox}{Terminal}{teal}{\icnote}{white}
- __ _ _ __ __ _ _ __ __ _
- / _` | '__/ _` | '__/ _` |
-| (_| | | | (_| | | | (_| |
- \__,_|_| \__,_|_| \__,_|
+\vspace{1em}
-Processing 'doc4.tex' (size: 31 bytes, last modified: 05/27/2018
-21:05:57), please wait.
-
-I have spotted an error in rule 'ls' located at '/home/paulo'. I
-could not parse the rule, something bad happened. Apparently, the
-provided YAML file is invalid. I will do my best to help you in
-any way I can. There are more details available on this
-exception:
-
-DETAILS ---------------------------------------------------------
-Cannot create property=commands for
-JavaBean=com.github.cereda.arara.model.Rule@91161c7
- in 'reader',
-line 1, column 1:
- !config
- ^
-No single argument
-constructor found for class
-com.github.cereda.arara.model.RuleCommand
- in 'reader', line 5,
-column 1:
- - ls @{details}
- ^
-
-
-Total: 0.02 seconds
-\end{codebox}
+\item[\textcolor{warningcolour}{\faClose}] \mdbox{R}{(Session.)exists(String key)}{boolean}
-The above terminal output shows a slightly different message, but the error is practically the same to the one \arara\ raised before when a rule in the old format was used. The difference relies on the missing rule property being set at the moment, but the idea remains the same. In order to fix the rule, we need to precede every list element in the \rbox{commands$\rightarrow$} context with the \abox{command} key, as seen as follows.
+\vspace{.5em}
-\begin{codebox}{A rule converted into the new format}{teal}{\icnote}{white}
-!config
-identifier: ls
-name: LS
-commands:
-- command: ls @{details}
-- command: ls @{details}
-arguments:
-- identifier: details
- flag: '@{ isTrue(parameters.details, "-l", "") }'
-\end{codebox}
+\hspace{2cm}\textcolor{teal}{\faArrowDown}
-This fix is sufficient to make the rule valid in the new format. Also, as mentioned before, it is interesting to observe that the subtasks will be unnamed during the execution, as there are no corresponding \abox{name} keys in the list elements.
+\item[\textcolor{okcolour}{\faCheck}] \mdbox{R}{(Session.)contains(String key)}{boolean}
-\begin{codebox}{Terminal}{teal}{\icnote}{white}
-(LS) Unnamed task ....................................... SUCCESS
-(LS) Unnamed task ....................................... SUCCESS
-\end{codebox}
+\vspace{1em}
-There is a helper tool available in the \href{https://github.com/cereda/arara/releases/tag/4.0}{release section} of our project repository that attempts to automatically convert rules in the old format to the new one. If you want to try it, download the \rbox{rc.jar} file from the repository and put it in the same directory where the old rules are located. You can also provide a full path instead. It is important to note that, although the tool might indicate a successful conversion, there are no guarantees that the resulting rule is fully compliant with the new format, due to potential changes in the internal workings of \arara, so your mileage may vary. In general, it should work. The rule converter is written in Java and requires a virtual machine to run. The tool has a straightforward workflow and takes just one parameter referring to the rule to be converted. The entire process should happen without intervention. When invoked without the file name, this is the expected output:
+\item[\textcolor{warningcolour}{\faClose}] \mdbox{R}{(Session.)obtain(String key)}{Object}
-\begin{codebox}{Terminal}{teal}{\icnote}{white}
-$ java -jar rc.jar
- _ _
- ___ _ _| |___ ___ ___ ___ _ _ ___ ___| |_ ___ ___
-| _| | | | -_| | _| . | | | | -_| _| _| -_| _|
-|_| |___|_|___| |___|___|_|_|\_/|___|_| |_| |___|_|
-
-version 1.0 (rules < 4.0)
-
-OH NO! -----------------------------------------------------
-This tool expects the YAML rule from previous versions of
-arara. Please, provide a proper YAML file containing the old
-rule as a parameter and try again. I will do my best to
-convert the rule to the new version 4.0 format.
-\end{codebox}
+\vspace{.5em}
-Let us invoke the tool with the first version of our hypothetical \rbox{ls} rule, still in the old format. The tool removes all comments from the original file, if any, and constructs a new file with a \rbox{\_v4} suffix attached to the name. The original file is preserved. Just keep in mind that the new rule must be renamed afterwards, as the base name and the corresponding \abox{identifier} key must match. The output is presented as follows.
+\hspace{2cm}\textcolor{teal}{\faArrowDown}
-\begin{codebox}{Terminal}{teal}{\icnote}{white}
-$ java -jar rc.jar ls.yaml
- _ _
- ___ _ _| |___ ___ ___ ___ _ _ ___ ___| |_ ___ ___
-| _| | | | -_| | _| . | | | | -_| _| _| -_| _|
-|_| |___|_|___| |___|___|_|_|\_/|___|_| |_| |___|_|
-
-version 1.0 (rules < 4.0)
-
-The provided YAML rule looks OK. I will try my best to
-convert it to the new version 4.0 format adopted by arara.
-The new rule name will be written in the same directory of
-the original one and will have a '_v4' suffix to it. Keep in
-mind that the base name must match the identifier!
-
-YAY! -------------------------------------------------------
-Good news, everybody! The provided YAML rule was updated
-successfully to the new version 4.0 format of arara! Of
-course, there are no guarantees this new rule will work out
-of the box, so fingers crossed! Take a closer look at the
-manual and update your rule to use the new enhancements of
-arara. Have a great time!
-\end{codebox}
+\item[\textcolor{okcolour}{\faCheck}]\mdbox{R}{(Session.)get(String key)}{Object}
+\end{itemize}
+\end{messagebox}
-The resulting rule is identical to the one manually converted in this section. Just note that, when creating the file, the resulting \gls{YAML} file might write the keys in alphabetical order. That means that, although both files semantically represent the same rule, the positions of the keys differ. However, that poses no issue at all, as long as the keys are correctly defined. Also, it is important to note that, due to a conversion policy of the underlying \gls{YAML} library, folded scalars in the old format are transcribed as literal scalars in the new format. We could force a folded style as default, but the resulting rule would be unnecessarily verbose, so we opted for the simpler, cleaner solution. As a direct consequence, we strongly recommend a subsequent verification and potential fix of existing literal scalars into folded ones, if any. Please refer to Section~\ref{sec:yamlscalars}, on page~\pageref{sec:yamlscalars}, for more details on scalars.
+\begin{messagebox}{Support for multiple files}{araracolour}{\icinfo}{white}
+From version 5.0 on, \arara\ is able to compile multiple files at once by providing multiple files as arguments. Please note that they should reside in the same working directory. Every other kind of compilation of multiple files is restricted by the mechanisms of the running programs. See \autoref{chap:commandline} for details.
+\end{messagebox}
-\begin{messagebox}{Replace plain strings in commands}{araracolour}{\icattention}{white}
-As plain strings are known to be problematic when defining commands, they are marked as deprecated in version 4.0 of \arara\ and will likely be removed in future releases. Since you are migrating from an old format to a new one, please consider replacing plain strings in command by proper \rbox{Command} objects. The helper methods available in the rule context, including the indispensable \mtbox{getCommand} method, for obvious reasons, are detailed in Section~\ref{sec:commandsandtriggers}, on page~\pageref{sec:commandsandtriggers}. It is highly advisable to update your rules on this regard, if applicable.
+\begin{messagebox}{Support for changing the working directory}{araracolour}{\icinfo}{white}
+A common problem when compiling \TeX\ files are specialties of \TeX\ engines looking for files. Usually, you should call an engine from the directory where the target file is located. \arara\ had the same restriction in that case. Now you can instruct \arara\ to operate from another directory lifting that constraint. See \autoref{chap:commandline} for details.
\end{messagebox}
-This section pretty much covered the basics for correctly migrating rules in the old format to the new one. Of course, it is highly advisable to make use of the new features available in \arara\ 4.0 for achieving better results. If you need any help, please do not hesitating in contacting us. See Section~\ref{sec:support}, on page~\pageref{sec:support}, for more details on how to get help.
+This section pretty much covered the basics of the changes to this version. Of course, it is highly advisable to make use of the new features available in \arara\ 5.0 for achieving better results. If you need any help, please do not hesitate to contact us. See Section~\ref{sec:support}, on page~\pageref{sec:support}, for more details on how to get help.