path: root/support/arara/doc/chapters/configuration.tex

% !TeX root = ../arara-manual.tex
\chapter{Configuration file}
\label{chap:configurationfile}

\arara\ provides a persistent model of modifying the underlying execution behaviour or enhancing the execution workflow through the concept of a configuration file. This chapter provides the basic structure of that file, as well as details on the file lookup in the operating system.

\section{File lookup}
\label{sec:filelookup}

Our tool looks for the presence of at least one of four very specific files before execution. These files are presented as follows. Observe that the directories must have the correct permissions for proper lookup and access. The lookup order is also presented.

\vspace{1em}

{\centering
\begin{tabular}{cccc}
{\footnotesize\textit{attempt 1}} &
{\footnotesize\textit{attempt 2}} &
{\footnotesize\textit{attempt 3}} &
{\footnotesize\textit{attempt 4}} \\
\rbox{.araraconfig.yaml} &
\rbox{araraconfig.yaml} &
\rbox{.arararc.yaml} &
\rbox{arararc.yaml}
\end{tabular}
\par}

\vspace{1.4em}

\arara\ provides two approaches regarding the location of a configuration file. They dictate how the execution should behave and happen from a user perspective, and are described as follows.

\begin{description}
\item[global configuration file] For this approach, the configuration file should be located at \abox[araracolour]{USER\_HOME} which is the home directory of the current user. All subsequent executions of \arara\ will read this configuration file and apply the specified settings accordingly. However, it is important to note that this approach has the lowest lookup priority, which means that a local configuration, presented as follows, will always supersede a global counterpart.

\item[local configuration file] For this approach, the configuration file should be located at \abox[araracolour]{USER\_DIR} which is the working directory associated with the current execution. This directory can also be interpreted as the one relative to the processed file. This approach offers a project-based solution for complex workflows, e.g, a thesis or a book. However, \arara\ must be executed within the working directory, or the local configuration file lookup will fail. Observe that this approach has the highest lookup priority, which means that it will always supersede a global configuration.
\end{description}

\begin{messagebox}{Beware of empty configuration files}{attentioncolour}{\icattention}{black}
A configuration file should never be empty, otherwise \arara\ will complain about it. Make sure to populate it with at least one key, or do not write a configuration file at all. The available keys are described in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}.
\end{messagebox}

If the logging feature is properly enabled, \arara\ will indicate in the corresponding \rbox{arara.log} file whether a configuration file was used during the execution and, if so, the corresponding canonical, absolute path. Logging is detailed later on, in Chapter~\ref{chap:logging}, on page~\pageref{chap:logging}.

\section{Basic structure}
\label{sec:basicstructure}

The following list describes the basic structure of an \arara\ configuration file 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 configuration file \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 configuration file for our tool.

\begin{description}
\item[\describe{M}{!config}] This keyword is mandatory and must be the first line of a configuration file. 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 a configuration file with a \abox{!config} keyword regardless.

\item[\describecfn{O}{string list}{paths}] When looking for rules, \arara\ always searches the default rule path, which consists of a special subdirectory named \abox[araracolour]{rules/} inside another special directory named \abox[araracolour]{ARARA\_HOME} (the place where our tool is installed). If no rule is found, the execution halts with an error. The \abox{paths} key specifies a list of directories, represented as plain strings, in which our tool should search for rules. The default path is appended to the list. Then the search happens from the first to the last element, in order.

\begin{codebox}{Example}{teal}{\icnote}{white}
paths:
- '/home/paulo/rules'
- '/opt/paulo/rules'
\end{codebox}

There are three variables available in the \abox{paths} context and are described as follows (note that MVEL variables and orb tags are discussed in Chapter~\ref{sec:mvelbasicusage}). A variable will be denoted by \varbox{variable} in this list.

\begin{description}
\item[\varbox{user.home}] This variable, as the name implies, holds the value of the absolute, canonical path of \abox[araracolour]{USER\_HOME} which is the home directory of the current user, as plain string. Note that the specifics of the home directory (such as name and location) are defined by the operating system involved.

\begin{codebox}{Example}{teal}{\icnote}{white}
paths:
- '@{user.home}/rules'
\end{codebox}

\item[\varbox{user.name}] This variable, as the name implies, holds the value of the current user account name, as plain string. On certain operating systems, this value is used to build the home directory structure.

\begin{codebox}{Example}{teal}{\icnote}{white}
paths:
- '/home/@{user.name}/rules'
\end{codebox}

\item[\varbox{application.workingDirectory}] This variable, as the name implies, holds the value of the absolute, canonical path of the working directory associated with the current execution, as plain string.

\begin{codebox}{Example}{teal}{\icnote}{white}
paths:
- '@{application.workingDirectory}/rules'
\end{codebox}
\end{description}

Observe that the \varbox{user} variable actually holds a map containing two keys (resulting in a map within a map). However, for didactic purposes, it is easier to use the property navigation feature of MVEL, detailed in Section~\ref{sec:propertynavigation}, on page~\pageref{sec:propertynavigation}, and consider the map references as three independent variables. You can use property navigation styles interchangeably. Note that you can also precede the path with the special keyword \rbox{<arara>} and save some quotes (see Section~\ref{sec:rule}, on page~\pageref{sec:rule}, but keep in mind that this special keyword is marked as deprecated and will be removed in future versions). In this specific scenario, the special keyword will be automatically removed afterwards.

\begin{messagebox}{Avoid folded and literal styles for scalars in a path}{attentioncolour}{\icattention}{black}
Do not use folded or literal styles for scalars in a path! The orb tag resolution for a path in plain string should be kept as simple as possible, so \emph{always} use the inline style.
\end{messagebox}

\item[\describecf{O}{string}{language}{en}] This key sets the language of all subsequent executions of \arara\ according to the provided language code value, as plain string. The default language is set to English. Also, it is very important to observe that the \opbox{{-}language} command line option can override this setting.

\begin{codebox}{Example}{teal}{\icnote}{white}
language: nl
\end{codebox}

\item[\describecf{O}{integer}{loops}{10}] This key redefines the maximum number of loops \arara\ will allow for potentially infinite iterations. Any positive integer can be used as the value for this variable. Also, it is very important to observe that the \opbox{{-}max-loops} command line option can override this setting.

\begin{codebox}{Example}{teal}{\icnote}{white}
loops: 30
\end{codebox}

\item[\describecf{O}{boolean}{verbose}{false}] This key activates or deactivates the verbose mode of \arara\ as default mode, according to the associated boolean value. Also, it is very important to observe that the \opbox{{-}verbose} command line option can override this setting if, and only if, this variable holds \rbox{false} as the value. Similarly, the \opbox{{-}silent} command line option can override this setting if, and only if, this variable holds \rbox{true} as the value.

\begin{codebox}{Example}{teal}{\icnote}{white}
verbose: true
\end{codebox}

\item[\describecf{O}{boolean}{logging}{false}] This key activates or deactivates the logging feature of \arara\ as the default behaviour, according to the associated boolean value. Also, it is very important to observe that the \opbox{{-}log} command line option can override this setting if, and only if, this variable holds \rbox{false} as the value.

\begin{codebox}{Example}{teal}{\icnote}{white}
logging: true
\end{codebox}

\item[\describecf{O}{boolean}{header}{false}] This key modifies the directive extraction, according to the associated boolean value. If enabled, \arara\ will extract all directives from the beginning of the file until it reaches a line that is not empty and it is not a comment. Otherwise, the tool will resort to the default behaviour and extract all directives from the entire file. It is very important to observe that the \opbox{{-}header} command line option can override this setting if, and only if, this variable holds \rbox{false} as the value.

\begin{codebox}{Example}{teal}{\icnote}{white}
header: false
\end{codebox}

\item[\describecf{O}{string}{logname}{arara}] This key modifies the default log file name, according to the associated plain string value, plus the \rbox{log} extension. The value cannot be empty or contain invalid characters. There is no orb tag evaluation in this specific context, only a plain string value. The log file will be written by our tool if, and only if, the \opbox{{-}log} command line option is used.

\begin{codebox}{Example}{teal}{\icnote}{white}
logname: mylog
\end{codebox}

\item[\describecf{O}{string}{dbname}{arara}] This key modifies the default YAML database file name, according to the associated plain string value, plus the \rbox{yaml} extension. The value cannot be empty or contain invalid characters. There is no orb tag evaluation in this specific context, only a plain string value. This database is used by file hashing operations, detailed in Section~\ref{sec:files}, on page~\pageref{sec:files}.

\begin{codebox}{Example}{teal}{\icnote}{white}
dbname: mydb
\end{codebox}

\item[\describecf{O}{string}{laf}{none}] This key modifies the default look and feel class reference, i.e,  the appearance of GUI widgets provided by our tool, according to the associated plain string value. The value cannot be empty or contain invalid characters. There is no orb tag evaluation in this specific context, only a plain string value. This look and feel setting is used by UI methods, detailed in Section~\ref{sec:dialogboxes}, on page~\pageref{sec:dialogboxes}. Note that this value is used by the underlying Java runtime environment, so a full qualified class name is expected.

\begin{codebox}{Example}{teal}{\icnote}{white}
laf: 'javax.swing.plaf.nimbus.NimbusLookAndFeel'
\end{codebox}

\begin{messagebox}{Special keywords for the look and feel setting}{araracolour}{\icok}{white}
Look and feel values other than the default provided by Java offer a more pleasant visual experience to the user, so if your rules or directives employ UI methods (detailed in Section~\ref{sec:dialogboxes}, on page~\pageref{sec:dialogboxes}), it might be interesting to provide a value to the \rbox{laf} key. At the time of writing, \arara\ provides two special keywords that are translated to the corresponding fully qualified Java class names:

\vspace{1em}

{\centering
\def\arraystretch{1.5}
\begin{tabular}{ll}
\rbox[araracolour]{\hphantom{xx}none\hphantom{xx}} & Default look and feel\\
\rbox[araracolour]{\hphantom{x}system\hphantom{x}} & System look and feel\\
\end{tabular}\par}

\vspace{1.4em}

The system look and feel, of course, offers the best option of all since it mimics the native appearance of graphical applications in the underlying system. However, some systems might encounter slow rendering times when this option is used, so your mileage might vary.
\end{messagebox}

\item[\describecfn{O}{string map}{preambles}] This key holds a string map containing predefined preambles for later use with the \opbox{{-}preamble} option (see Section~\ref{sec:options}, on page~\pageref{sec:options}). Note that each map key must be unique. Additionally, it it is highly recommended to use lowercase letters without spaces, accents or punctuation symbols, as key values. Only directives, line breaks and conditionals are recognized.

\begin{codebox}{Example}{teal}{\icnote}{white}
preambles:
  twopdftex: |
    % arara: pdftex
    % arara: pdftex
\end{codebox}

\begin{messagebox}{Literal style when defining a preamble}{attentioncolour}{\icattention}{black}
When defining preambles in the configuration file, \emph{always} use the literal style for scalar blocks. The reason for this requirement is the proper retention of line breaks, which are significant when parsing the strings into proper directive lines. Using the folded style in this particular scenario will almost surely be problematic.
\end{messagebox}

\item[\describecfn{O}{file type list}{filetypes}] This key holds a list of file types supported by \arara\ when searching for a file name, as well as their corresponding directive lookup patterns. In order to properly set a file type, the keys used in this specification are defined inside the \rbox{filetypes$\rightarrow$} context and presented as follows.

\begin{description}
\item[\describecontext{M}{filetypes}{extension}] This key, as the name implies, holds the file extension, represented as a plain string and without the leading dot (unless it is part of the extension). An extension is an identifier specified as a suffix to the file name and indicates a characteristic of the corresponding content or intended use. Observe that this key is mandatory when specifying a file type, as our tool does not support files without a proper extension.

\begin{codebox}{Example}{teal}{\icnote}{white}
extension: c
\end{codebox}

\item[\describecontextt{M}{O}{filetypes}{pattern}] This key holds the directive lookup pattern as a regular expression (which is, of course, represented as a plain string). When introducing a new file type, \arara\ must know how to interpret each line and how to properly find and extract directives, hence this key. Observe that this key is marked as optional and mandatory. The reason for such an unusual indication highly depends on the current scenario and is illustrated as follows.

\begin{itemize}[label={--}]
\item The \abox{pattern} key is entirely \emph{optional} for known file types (presented in Section~\ref{sec:filenamelookup}, on page~\pageref{sec:filenamelookup}, and henceforth named \emph{default} file types), in case you just want to modify the file name lookup order. It is important to observe that default file types already have their directive lookup patterns set, which incidentally are the same, presented as follows.

\begin{codebox}{Default regular expression pattern for known file types}{teal}{\icnote}{white}
^\s*%\s+
\end{codebox}

\item The \abox{pattern} key is \emph{mandatory} for new file types and for overriding existing patterns for default file types. Make sure to provide a valid regular expression as key value. It is very important to note that, regardless of the underlying pattern (default or provided through this key), the special \rbox{arara:} keyword is immutable and thus included by our tool in every directive lookup pattern.

\begin{codebox}{Example}{teal}{\icnote}{white}
pattern: ^\s*//\s*
\end{codebox}
\end{itemize}
\end{description}

For instance, let us reverse the default file name lookup order presented in Section~\ref{sec:filenamelookup}, on page~\pageref{sec:filenamelookup}. Since the default lookup patterns will be preserved, the corresponding \abox{pattern} keys can be safely omitted. Now it is just a matter of rearranging the entries in the desired order, presented as follows.

\begin{codebox}{Example}{teal}{\icnote}{white}
filetypes:
- extension: ins
- extension: drv
- extension: ltx
- extension: dtx
- extension: tex
\end{codebox}

If a default file type is included in the \abox{filetypes} list but others from the same tier are left out, these file types not on the list will implicitly have the lowest priority over the explicit list element during the file name lookup, although still respecting their original lookup order modulo the specified file type. For instance, consider the following list:

\begin{codebox}{Example}{teal}{\icnote}{white}
filetypes:
- extension: ins
- extension: drv
\end{codebox}

According to the previous example, three out of five default file types were deliberately left out of the \abox{filetypes} list. As expected, the two default file types provided to this list will have the highest priority during the file name lookup. It is important to note that \arara\ will always honour the original lookup order for omitted default file types, yet favouring the explicit elements. The following list is semantically equivalent to the previous example.

\begin{codebox}{Example}{teal}{\icnote}{white}
filetypes:
- extension: ins
- extension: drv
- extension: tex
- extension: dtx
- extension: ltx
\end{codebox}

The following example introduces the definition of a new file type to support \rbox{c} files. Observe that, for this specific scenario, the \abox{pattern} key is mandatory, as previously discussed. The resulting list is presented as follows, including the corresponding regular expression pattern.

\begin{codebox}{Example}{teal}{\icnote}{white}
filetypes:
- extension: c
  pattern: ^\s*//\s*
\end{codebox}

It is important to note that, if no default file type is explicitly specified, as seen in previous example, the original list of default file types will have the highest priority over the \abox{filetypes} values during the file name lookup. The following list is semantically equivalent to the previous example.

\begin{codebox}{Example}{teal}{\icnote}{white}
filetypes:
- extension: tex
- extension: dtx
- extension: ltx
- extension: drv
- extension: ins
- extension: c
  pattern: ^\s*//\s*
\end{codebox}

\begin{messagebox}{Do not escape backslashes}{attentioncolour}{\icattention}{black}
\setlength{\parskip}{1em}
When writing a file type pattern, there is no need for escaping backslashes as one does for strings in a typical programming language (including MVEL expressions). In this specific scenario, key values are represented as plain, literal strings.

However, please note that character escaping might be required by the underlying regular expression in some scenarios (i.e, a literal dot in the pattern). It is highly recommended to consult a proper regular expression documentation for a comprehensive overview.
\end{messagebox}
\end{description}

Since \arara\ allows four different names for configuration files, as well as global and local approaches, it is highly advisable to run our tool with the \opbox{{-}log} command line option enabled, in order to easily identify which file was considered for that specific execution. The logging feature is discussed later on, in Chapter~\ref{chap:logging}, on page~\pageref{chap:logging}.