% !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 2020) 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 -s, --safe-run Run in safe mode and disable potentially harmful features. Make sure your projects uses only allowed features. -H, --header Extract directives only in the file header -p, --preamble TEXT Set the file preamble based on the configuration file -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) -d, --working-directory PATH Set the working directory for all tools -P, --call-property VALUE Pass parameters to the application to be used within the session. -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 IETF BCP 47 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]{en-QN} Broad Norfolk \\ \rbox[araracolour]{\hphantom{x}it\hphantom{x}} Italian & \rbox[araracolour]{\hphantom{x}nl\hphantom{x}} Dutch & \rbox[araracolour]{pt-BR} 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. \begin{messagebox}{Invalid language codes}{araracolour}{\icinfo}{white} From version 6.0 on, if you pass an invalid language code, \arara\ will now run in English and issue a log warning but not fail anymore. Failing due to the wrong language in the output was considered inappropriate. \end{messagebox} \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: 360 B, last modified: 12/28/2020 13:03:32), please wait. [DR] (PDFLaTeX) PDFLaTeX engine ----------------------------------------------------------------- Author: Island of TeX About to run: [pdflatex, doc5.tex] @ /home/paulo/Downloads [DR] (BibTeX) The BibTeX reference management software ----------------------------------------------------------------- Author: Island of TeX About to run: [bibtex, doc5] @ /home/paulo/Downloads [DR] (PDFLaTeX) PDFLaTeX engine ----------------------------------------------------------------- Author: Island of TeX About to run: [pdflatex, doc5.tex] @ /home/paulo/Downloads [DR] (PDFLaTeX) PDFLaTeX engine ----------------------------------------------------------------- Author: Island of TeX About to run: [pdflatex, doc5.tex] @ /home/paulo/Downloads Total: 0.18 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. \item[\describeop{S}{safe-run}] This option enables the safe mode of \arara, protecting the system by disallowing certain user actions. Currently, the following features are restricted: \begin{itemize}[label={--}] \item File lookup will only perform explicit file resolution. Wildcard filters are disabled. \item \mtbox{unsafelyExecuteSystemCommand} will raise an exception and abort the run. Keep in mind that rules are still allowed to construct arbitrary commands using \rbox{Command} objects, so this restriction only disallows arbitrary system commands that would not get logged and are thus invisible to the user. \item The \rbox{options} parameter does not expand orb tags in any directive. \end{itemize} \item[\describeopp{P}{call-property}{entry}] This option forwards the provided \prbox{entry}, in the \rbox{key=value} format, to the session map. For instance, consider the following call: \begin{codebox}{Example}{teal}{\icnote}{white} $ arara -P foo=bar hello.tex \end{codebox} In a rule, you may now retrieve the value associated to the \rbox{foo} key, which is \rbox{bar}, set at runtime, by calling the following method in your code: \begin{codebox}{Example}{teal}{\icnote}{white} getSession().get('arg:foo') \end{codebox} This option may be called multiple times, as a means to provide as many data pairs as needed. Please refer to \mtbox{getSession} in Chapter~\ref{chap:methods}, on page~\pageref{chap:methods}, for more details. \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}