% !TeX root = ../arara-manual.tex
\chapter{Command line}
\label{chap:commandline}

\arara\ is a command line tool. It can be used in a plethora of command interpreter implementations, from bash to a Windows prompt, provided that the Java runtime environment is accessible within the current session. This chapter covers the user interface design, as well as options (also known as flags or switches) that modify the underlying application behaviour.

\section{User interface design}
\label{sec:userinterfacedesign}

The goal of a user interface design is to make the interaction as simple and efficient as possible. Good user interface design facilitates finishing the task at hand without drawing unnecessary attention to itself. We redesigned the interface in order to look more pleasant to the eye, after all, we work with \TeX\ and friends:

\begin{codebox}{Terminal}{teal}{\icnote}{white}
  __ _ _ __ __ _ _ __ __ _
 / _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
 \__,_|_|  \__,_|_|  \__,_|

Processing 'doc5.tex' (size: 285 B, last modified: 03/01/2020
19:25:40), please wait.

(PDFLaTeX) PDFLaTeX engine .............................. SUCCESS
(BibTeX) The BibTeX reference management software ....... SUCCESS
(PDFLaTeX) PDFLaTeX engine .............................. SUCCESS
(PDFLaTeX) PDFLaTeX engine .............................. SUCCESS

Total: 1.14 seconds
\end{codebox}

First of all, we have the nice application logo, displayed using ASCII art. The entire layout is based on monospaced font spacing, usually used in terminal prompts. Hopefully you follow the conventional use of a monospaced font in your terminal, otherwise the visual effect will not be so pleasant. First and foremost, \arara\ displays details about the file being processed, including size and modification status:

\begin{codebox}{Terminal}{teal}{\icnote}{white}
Processing 'doc5.tex' (size: 285 B, last modified: 03/01/2020
19:25:40), please wait.
\end{codebox}

The list of tasks was also redesigned to be fully justified, and each entry displays both task and subtask names (the former being displayed enclosed in parentheses), besides of course the usual execution result:

\begin{codebox}{Terminal}{teal}{\icnote}{white}
(PDFLaTeX) PDFLaTeX engine .............................. SUCCESS
(BibTeX) The BibTeX reference management software ....... SUCCESS
(PDFLaTeX) PDFLaTeX engine .............................. SUCCESS
(PDFLaTeX) PDFLaTeX engine .............................. SUCCESS
\end{codebox}

As previously mentioned in Section~\ref{sec:rule}, on page~\pageref{sec:rule}, if a task fails, \arara\ will halt the entire execution at once and immediately report back to the user. This is an example of how a failed task looks like:

\begin{codebox}{Terminal}{teal}{\icnote}{white}
(PDFLaTeX) PDFLaTeX engine .............................. FAILURE
\end{codebox}

Also, observe that our tool displays the execution time before terminating, in seconds. The execution time has a very simple precision, as it is meant to be easily readable, and should not be considered for command profiling.

\begin{codebox}{Terminal}{teal}{\icnote}{white}
Total: 1.14 seconds
\end{codebox}

The tool has two execution modes: \emph{silent}, which is the default, and \emph{verbose}, which prints as much information about tasks as possible. When in silent mode, \arara\ will simply display the task and subtask names, as well as the execution result. Nothing more is added to the output. For instance:

\begin{codebox}{Terminal}{teal}{\icnote}{white}
(BibTeX) The BibTeX reference management software ....... SUCCESS
\end{codebox}

When executed in verbose mode, \arara\ will display the underlying system command output as well, when applied. In version 4.0 of our tool, this mode was also entirely redesigned in order to avoid unnecessary clutter, so it would be easier to spot each task. For instance:

\begin{codebox}{Terminal}{teal}{\icnote}{white}
-----------------------------------------------------------------
(BibTeX) The BibTeX reference management software
-----------------------------------------------------------------
This is BibTeX, Version 0.99d (TeX Live 2019)
The top-level auxiliary file: doc5.aux
The style file: plain.bst
Database file #1: mybib.bib

--------------------------------------------------------- SUCCESS
\end{codebox}

It is important to observe that, when in verbose mode, \arara\ can offer proper interaction if the system command requires user intervention. However, when in silent mode, the tool will simply discard this requirement and the command will almost surely fail.

\section{Options}
\label{sec:options}

In order to run \arara\ on your \TeX\ file, the simplest possible way is to provide the file name to the tool in your favourite command interpreter session, provided that the file has at least one directive:

\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ arara doc6.tex
\end{codebox}

From version 5.0 on, \arara\ may receive more than one file as parameter. It will compile them sequentially (starting with the leftmost). The process fails on the first failure of these executions. For the files to be flawlessly compiled by \TeX, they should be in the same working directory. If you process your files with other tools, this requirement could be lifted.

\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ arara doc20.tex doc21.tex
  __ _ _ __ __ _ _ __ __ _
 / _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
 \__,_|_|  \__,_|_|  \__,_|

Processing 'doc20.tex' (size: 28 B, last modified: 02/28/2020
07:15:02), please wait.

(PDFTeX) PDFTeX engine .................................. SUCCESS

Processing 'doc21.tex' (size: 28 B, last modified: 02/28/2020
07:15:10), please wait.

(PDFTeX) PDFTeX engine .................................. SUCCESS

Total: 1.20 seconds
\end{codebox}

The tool has a set of command line options (also known as flags or switches) that modify the underlying execution behaviour or enhance the execution workflow. If you do not provide any parameters, \arara\ will display the tool usage and the available options:

\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ arara
  __ _ _ __ __ _ _ __ __ _
 / _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
 \__,_|_|  \__,_|_|  \__,_|

Usage: arara [OPTIONS] [file]...

Options:
  -l, --log                        Generate a log output
  -v, --verbose / -s, --silent     Print the command output
  -n, --dry-run                    Go through all the motions of running a
                                   command, but with no actual calls
  -H, --header                     Extract directives only in the file header
  -t, --timeout INT                Set the execution timeout (in milliseconds)
  -L, --language TEXT              Set the application language
  -m, --max-loops INT              Set the maximum number of loops (> 0)
  -p, --preamble TEXT              Set the file preamble based on the
                                   configuration file
  -d, --working-directory DIRECTORY
                                   Set the working directory for all tools
  -V, --version                    Show the version and exit
  -h, --help                       Show this message and exit

Arguments:
  file  The file(s) to evaluate and process
\end{codebox}

The available options for our tool are detailed as follows. Each option contains short and long variations, which are denoted by \opbox{o} and \opbox{{-}option} in the command line, respectively. Additionally, when a parameter is required by the current option, it will be denoted by \prbox{parameter} in the description.

\begin{description}
\item[\describeop{h}{help}] As the name indicates, this option prints the help message containing the tool usage and the list of all available options. The tool exits afterwards. When running \arara\ without any options or a file to be processed, this is the default behaviour. This option has the highest priority over the others.

\item[\describeop{H}{header}] This option changes the mechanics of how \arara\ extracts the directives from the code. The tool always reads the entire file and extracts every single directive found throughout the code. However, by activating this switch, \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 (hence the option name). Consider the following example:

\begin{ncodebox}{Source file}{teal}{\icnote}{white}{doc7.tex}
% arara: pdftex
Hello world.
\bye

% arara: pdftex
\end{ncodebox}

When running \arara\ without this option, two directives will be extracted (the ones found in lines 1 and 5). However, if executed with \opbox{{-}header}, the tool will only extract one directive (from line 1), as it will stop the extraction process as soon as it reaches line 2. This option can also be activated by default in the configuration file (see Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}).

\item[\describeop{l}{log}] This option enables the logging feature of our tool. All streams from all system commands will be logged and, at the end of the execution, a consolidated log file named \rbox{arara.log} will be generated. This option can also be activated by default in the configuration file (see Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}). Refer to Chapter~\ref{chap:logging}, on page~\pageref{chap:logging}, for more details on the logging feature.

\item[\describeopp{L}{language}{code}] This option sets the language of the current execution of \arara\ according to the language code identified by the \prbox{code} value provided as the parameter. The language code tries to follow the ISO 639 norm, standardized nomenclature used to classify languages. For example, this is our tool speaking Dutch:

\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ arara -L nl doc5.tex
  __ _ _ __ __ _ _ __ __ _
 / _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
 \__,_|_|  \__,_|_|  \__,_|

Verwerken van 'doc5.tex' (grootte: 285 B, laatst gewijzigd:
03/01/2020 19:25:40), een ogenblik geduld.

(PDFLaTeX) PDFLaTeX engine .............................. SUCCESVOL
(BibTeX) The BibTeX reference management software ....... SUCCESVOL
(PDFLaTeX) PDFLaTeX engine .............................. SUCCESVOL
(PDFLaTeX) PDFLaTeX engine .............................. SUCCESVOL

Totaal: 1,07 seconden
\end{codebox}

\begin{messagebox}{Navis volitans mihi anguillis plena est}{araracolour}{\icok}{white}
At time of writing, \arara\ is able to speak English, German, Dutch, Italian and Brazilian Portuguese out of the box. There is also a special dialect named Broad Norfolk, spoken by those living in the county of Norfolk in England.

\vspace{1em}

{\centering
\def\arraystretch{1.5}
\setlength\tabcolsep{1em}
\begin{tabular}{lll}
\rbox[araracolour]{\hphantom{x}en\hphantom{x}} English &
\rbox[araracolour]{\hphantom{x}de\hphantom{x}} German &
\rbox[araracolour]{\hphantom{x}qn\hphantom{x}} Broad Norfolk \\
\rbox[araracolour]{\hphantom{x}it\hphantom{x}} Italian &
\rbox[araracolour]{\hphantom{x}nl\hphantom{x}} Dutch &
\rbox[araracolour]{ptbr} Portuguese (BR)
\end{tabular}\par}

\vspace{1.4em}

Would you like to make \arara\ speak your own language? Splendid! We would love to have you in the team! Just send us an electronic mail, join our \href{https://gitter.im/cereda/arara}{dedicated chatroom} or \href{https://gitlab.com/islandoftex/arara/issues}{open an issue} about it. The localization process is quite straightforward, we can help you. Any language is welcome!
\end{messagebox}

This option can also be specified in the configuration file (see Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}). However, one can always override this setting by running the tool with an explicit \opbox{L} option.

\item[\describeopp{m}{max-loops}{number}] As a means to avoid infinite iterations, \arara\ has a predefined maximum number of loops, with the default set to 10, as a technical solution (seen in Section~\ref{sec:directives}, on page~\pageref{sec:directives}). For instance, consider the following directive:

\begin{codebox}{A naughty directive}{teal}{\icnote}{white}
% arara: pdftex while true
\end{codebox}

The \opbox{{-}max-loops} option is used to redefine the maximum number of loops our tool will allow for potentially infinite iterations. Any positive integer can be used as the \prbox{number} value for this option. An execution of the previous directive with a lower maximum number of loops is shown as follows:

\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ arara -m 2 doc8.tex 
  __ _ _ __ __ _ _ __ __ _ 
 / _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
 \__,_|_|  \__,_|_|  \__,_|

Processing 'doc8.tex' (size: 45 B, last modified: 05/29/2018
12:32:14), please wait.

(PDFTeX) PDFTeX engine .................................. SUCCESS
(PDFTeX) PDFTeX engine .................................. SUCCESS

Total: 0.58 seconds
\end{codebox}

This option can also be specified in the configuration file (see Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}). However, one can always override this setting by running the tool with an explicit \opbox{m} option.

\item[\describeop{n}{dry-run}] This option makes \arara\ go through all the motions of running tasks and subtasks, but with no actual calls. It is a very useful feature for testing the sequence of underlying system commands to be performed on a file. For instance, consider the following execution:

\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ arara -n doc5.tex 
  __ _ _ __ __ _ _ __ __ _
 / _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
 \__,_|_|  \__,_|_|  \__,_|

Processing 'doc5.tex' (size: 285 B, last modified: 03/01/2020
19:25:40), please wait.

[DR] (PDFLaTeX) PDFLaTeX engine
-----------------------------------------------------------------
Author: Island of TeX
About to run: [ pdflatex, /home/paulo/Downloads/doc5.tex ] @ 

[DR] (BibTeX) The BibTeX reference management software
-----------------------------------------------------------------
Author: Island of TeX
About to run: [ bibtex, doc5 ] @ 

[DR] (PDFLaTeX) PDFLaTeX engine
-----------------------------------------------------------------
Author: Island of TeX
About to run: [ pdflatex, /home/paulo/Downloads/doc5.tex ] @ 

[DR] (PDFLaTeX) PDFLaTeX engine
-----------------------------------------------------------------
Author: Island of TeX
About to run: [ pdflatex, /home/paulo/Downloads/doc5.tex ] @ 

Total: 0.23 seconds
\end{codebox}

Note that the rule authors are displayed (so they can be blamed in case anything goes wrong), as well as the system command to be executed. It is an interesting approach to see everything that will happen to your document and in which order.

\begin{messagebox}{Conditionals and boolean values}{attentioncolour}{\icattention}{black}
It is very important to observe that conditionals are not evaluated when our tool is executed in the \opbox{{-}dry-run} mode, although they are properly listed. Also, when a rule returns a boolean value, the code is executed regardless of this mode.
\end{messagebox}

\item[\describeopp{p}{preamble}{name}] Some \TeX\ documents require the same automation steps, e.g, a set of articles. To this end, so as to avoid repeating the same preamble over and over in this specific scenario, \arara\ has the possibility of setting predefined preambles in a special section of the configuration file identified by a unique key for later use. This command line option prepends the predefined preamble referenced by the \prbox{name} key to the current document and then proceeds to extract directives, as usual. For instance:

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

\begin{ncodebox}{Source file}{teal}{\icnote}{white}{doc9.tex}
Hello world.
\bye
\end{ncodebox}

In this example, we have a preamble named \abox{twopdftex} and a \TeX\ file named \rbox{doc9.tex} with no directives. Of course, our tool will complain about missing directives, unless we deliberately inject the two directives from the predefined preamble into the current execution:

\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ arara -p twopdftex doc9.tex
  __ _ _ __ __ _ _ __ __ _ 
 / _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
 \__,_|_|  \__,_|_|  \__,_|

Processing 'doc9.tex' (size: 18 B, last modified: 05/29/2018
14:39:21), please wait.

(PDFTeX) PDFTeX engine .................................. SUCCESS
(PDFTeX) PDFTeX engine .................................. SUCCESS

Total: 0.96 seconds
\end{codebox}

It is important to note that this is just a directive-based preamble and nothing else, so a line other than a directive is discarded. Line breaks and conditionals are supported. Trying to exploit this area for other purposes will not work. The preamble specification in the configuration file is detailed in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}. 

\item[\describeopp{t}{timeout}{number}] This option sets an execution timeout for every task, in milliseconds. If the timeout is reached before the task ends, \arara\ will kill it and halt the execution. Any positive integer can be used as the \prbox{number} value for this option. Of course, use a sensible value to allow proper time for a task to be executed. For instance, consider the following recursive call:

\begin{ncodebox}{Source file}{teal}{\icnote}{white}{doc10.tex}
% arara: pdftex
\def\foo{\foo}
This will go \foo forever.
\bye
\end{ncodebox}

\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ arara --timeout 3000 doc9.tex
  __ _ _ __ __ _ _ __ __ _ 
 / _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
 \__,_|_|  \__,_|_|  \__,_|

Processing 'doc10.tex' (size: 63 B, last modified: 05/29/2018
15:24:06), please wait.

(PDFTeX) PDFTeX engine .................................   ERROR

The system command execution reached the provided timeout value
and was aborted. If the time was way too short, make sure to
provide a longer value. There are more details available on this
exception:

DETAILS ---------------------------------------------------------
Timed out waiting for java.lang.UNIXProcess@6b53e23f to finish,
timeout: 3000 milliseconds, executed command [pdftex, doc10.tex]

Total: 3.37 seconds
\end{codebox}

If left unattended, this particular execution would never finish (and probably crash the engine at a certain point), as expected by the recursive calls without a proper fixed point. The \opbox{{-}timeout} option was set at 3000 milliseconds and the task was aborted when the time limit was reached. Note that the tool raised an error about it.

\item[\describeop{d}{working-directory}] This option allows you to change the working directory. That is, the commands will run from a different directory than the directory you launched \arara\ in. This is especially useful when calling a \TeX\ engine as they resolve files against the working direcotry. For that reason, \arara\ will also resolve each file you pass to it that has no absolute path against the working directory. The working directory is fixed for the whole call; passing multiple files to \arara\ will resolve all of them against and execute all actions within that one working directory.

\item[\describeop{V}{version}] This option, as the name indicates, prints the current version. It also prints the current revision and a list of libraries with their corresponding licenses. Finally, it simply exits the application. Note that this option has the second highest priority over the others.

\item[\describeop{v}{verbose}] This option enables the verbose mode of \arara, as seen in Section~\ref{sec:userinterfacedesign}, on page~\pageref{sec:userinterfacedesign}. It also enables all streams to be flushed directly to the terminal, including potential user input interactions (the exact opposite of silent mode). This option can also be activated by default in the configuration file (see Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}).

\item[\describeop{s}{silent}] This option disables the verbose mode of \arara\ (thus activating the default silent mode), if previously enabled by a proper configuration file (see Chapter~\ref{chap:configurationfile}, on page~\pageref{chap:configurationfile}). It is important to note that this command line option has higher priority over the \opbox{{-}verbose} counterpart.
% It might be worth clarifying here that --silent doesn't completely stop all messages from being written to STDOUT, just the messages normally produced by the system commands called by the subtasks. The normal arara messages are still displayed.
\end{description}

You can combine options, use long or short variations interchangeably and write them in any order, provided that a file name is given at some point in the command line, otherwise the usage will be printed. Use the provided features in order to enhance and optimize your automation workflow.

\section{File name lookup}
\label{sec:filenamelookup}

\arara, as a command line application, provides support for a restricted range of file types. In particular, the tool recognizes five file types based on their extensions. These types are presented as follows, as well as the lookup order.

\vspace{1em}

{\centering
\setlength\tabcolsep{1em}
\begin{tabular}{ccccc}
{\footnotesize\textit{attempt 1}} &
{\footnotesize\textit{attempt 2}} &
{\footnotesize\textit{attempt 3}} &
{\footnotesize\textit{attempt 4}} &
{\footnotesize\textit{attempt 5}} \\
\rbox{\hphantom{xx}tex\hphantom{xx}} &
\rbox{\hphantom{xx}dtx\hphantom{xx}} &
\rbox{\hphantom{xx}ltx\hphantom{xx}} &
\rbox{\hphantom{xx}drv\hphantom{xx}} &
\rbox{\hphantom{xx}ins\hphantom{xx}}
\end{tabular}\par}

\vspace{1.4em}

Note that other extensions can be added through a proper mapping in the configuration file, as well as modifying the lookup order. This feature is detailed later on, in Section~\ref{sec:basicstructure}, on page~\pageref{sec:basicstructure}. \arara\ employs the following scheme for file name lookup:

\begin{itemize}[label={--}]
\item First and foremost, if the provided file name already contains a valid extension, the tool attempts an exact match. If the file exists, it will be selected. This is the best approach if your working directory contains other files sharing the same base name.

\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ arara doc11.tex
  __ _ _ __ __ _ _ __ __ _ 
 / _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
 \__,_|_|  \__,_|_|  \__,_|

Processing 'doc11.tex' (size: 34 B, last modified: 05/29/2018
19:40:35), please wait.

(PDFTeX) PDFTeX engine .................................. SUCCESS

Total: 0.69 seconds
\end{codebox}

\item If the provided file name has an unsupported extension or no extension at all, the tool iterates through the list of default extensions, appending the current element to the file name and attempting an exact match. If the file exists, it will be selected.

\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ arara doc11
  __ _ _ __ __ _ _ __ __ _ 
 / _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
 \__,_|_|  \__,_|_|  \__,_|

Processing 'doc11.tex' (size: 34 B, last modified: 05/29/2018
19:40:35), please wait.

(PDFTeX) PDFTeX engine .................................. SUCCESS

Total: 0.69 seconds
\end{codebox}

\item Many shells complete file names that have multiple extensions in the same directory, so that they end with a period. We try to
resolve against them as well!

\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ arara doc11.
  __ _ _ __ __ _ _ __ __ _ 
 / _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
 \__,_|_|  \__,_|_|  \__,_|

Processing 'doc11.tex' (size: 34 B, last modified: 05/29/2018
19:40:35), please wait.

(PDFTeX) PDFTeX engine .................................. SUCCESS

Total: 0.69 seconds
\end{codebox}
\end{itemize}

It is highly recommended to use complete file names with our tool, in order to ensure the correct file is being processed. If your command line interpreter features tab completion, you can use it to automatically fill partially typed file names from your working directory.

\begin{messagebox}{Exit status support}{araracolour}{\icok}{white}
\arara\ follows the good practices of software development and provides three values for exit status, so our tool can be programmatically used in scripts and other complex workflows.

\vspace{1em}

{\centering
\def\arraystretch{1.5}
\begin{tabular}{ll}
\rbox[araracolour]{\hphantom{x}0\hphantom{x}} & Successful execution \\
\rbox[araracolour]{\hphantom{x}1\hphantom{x}} & One of the rules failed \\
\rbox[araracolour]{\hphantom{x}2\hphantom{x}} & An exception was raised
\end{tabular}\par}

\vspace{1.4em}

Please refer to the documentation of your favourite command line interpreter to learn more about exit status captures. Programming languages also offer methods for retrieving such information.
\end{messagebox}
