1.2 ⁑Arara

Volume 2 introduced arara, a Java application that automates the process of building a LaTeX document. Since then, arara has evolved into version 4.0 that has useful new features, including conditionals that can be used to determine whether or not an application needs to be run.

To refresh your memory, or for those who haven't read Volume 2, you need to tell arara how to build your document by placing directives as comments within your source code.

Example:

% arara: pdflatex
\documentclass{article}

\begin{document}
\section{A Sample Section}
This is a sample document.
\end{document}

The first line of the source code has a directive:

% arara: pdflatex

This indicates that arara needs to run pdflatex so if the document file is called, say, myDoc.tex, then the PDF file can be built using:

$ arara myDoc

However, it may be that you only want to run pdflatex if the source code has changed. With the new arara version 4.0, you can now add a conditional to the directive:

% arara: pdflatex if changed("tex")

Now arara will only run pdflatex if the .tex file has changed. You can combine tests using || (boolean or) && (boolean and) or ! (negation). For example:

% arara: pdflatex if changed("tex") || missing("pdf")

This will now run pdflatex if the .tex file has changed or if the PDF file is missing.

In addition to if (and the logically opposite unless) you can also have loops using while (repeat while the condition is true) or until (repeat until the condition is true).

Available tests that can be used in the conditions are listed below. The argument ⟨file ref⟩ indicates either an extension, such as "log", or a file reference, such as toFile("xampl.bib"). In the case of just a file extension, such as "log", the base is the same as the base of the source .tex file that contains the arara directives. The argument ⟨regex⟩ indicates a regular expression.²

changed(⟨file ref⟩): Returns true if the file has changed.
unchanged(⟨file ref⟩): Returns true if the file hasn't changed.
exists(⟨file ref⟩): Returns true if the file exists.
missing(⟨file ref⟩): Returns true if the file doesn't exist.
found(⟨file ref⟩, ⟨regex⟩): Returns true if the regular expression is found in the file.

Example:

With earlier versions of arara, if your document had cross-references you needed two pdflatex directives:

% arara: pdflatex
% arara: pdflatex
\documentclass{article}

\begin{document}
\section{A Sample Section}
Here is a cross-reference to
section~\ref{sec:another}.

\section{Another Section}
\label{sec:another}
\end{document}

However, if you make a change that doesn't affect the cross-references, you only need one invocation of pdflatex. The log file contains information if a rerun is needed:

LaTeX Warning: There were undefined references.

LaTeX Warning: Label(s) may have changed. Rerun to get
cross-references right.

So you could check for “undefined” like this:

% arara: pdflatex if changed("tex") || missing("pdf")
% arara: pdflatex if found("log", "undefined")

A more general purpose expression to search for is “Rerun”, which may also be used by some packages if they detect a rerun is required that is unrelated to cross-references.

These tests can be combined in a loop. This can make for a long line in your source code, but luckily another new feature of arara version 4.0 is the ability to break the line using:

% arara: -->

at the start of each continuation line. For example:

% arara: pdflatex while (changed("tex")
% arara: --> || missing("pdf")
% arara: --> || missing("log")
% arara: --> || found("log", "Rerun"))

Now arara will repeatedly run pdflatex while the .pdf or .log files are missing or while the .tex file has changed or while the log file contains “Rerun”. To prevent an infinite process occurring, arara will break the loop if the condition is still true after ten iterations. (This maximum value can be changed, if required.)

The above example provides a single pdflatex directive in the source code, which is useful if no other applications are required, but this may need to be broken up into multiple directives if another application, such as bibtex, needs to be run.

Example:

This example has a citation from the sample xampl.bib database. (This sample bibliography file should be provided with all modern TeX distributions.)

% arara: pdflatex if changed("tex") || missing("pdf")
% arara: bibtex if (missing("bbl") || found("log", "Citation"))
% arara: pdflatex while (found("log", "Rerun"))
\documentclass{article}

\begin{document}
\section{A Sample Section}
Here is a cross-reference to
section~\ref{sec:another}.
A citation~\cite{book-minimal}.

\section{Another Section}
\label{sec:another}

\bibliographystyle{plain}
\bibliography{xampl}
\end{document}

Now arara will only run bibtex if the .bbl file is missing or if the log file contains “Citation”, which will pick up the undefined citation warning:

LaTeX Warning: Citation `book-minimal' on page 1 undefined

Another possible test would be for any changes to the .bib file. In this case, the .bib file doesn't have the same root as the main .tex file, so I can't just do changed("bib"). Instead I need to indicate that I'm specifying the actual file rather than the extension. This can be done using

changed(toFile("⟨filename⟩"))

where ⟨filename⟩ is the name of the file.

In this case, I'm using the xampl.bib file, which is in my TeX Live distribution so I'd need the full path name, but if it was in the same directory as my .tex file I would just need to do:

changed(toFile("xampl.bib"))

⚠

The boolean operators || and && are short-circuited. This means that under certain circumstances, only the left-hand condition may be evaluated. For example, if you have ⟨test1⟩ || ⟨test2⟩ then if ⟨test1⟩ is true, there's no need to evaluate ⟨test2⟩ (since both the boolean operations (“true” or “false”) and (“true” or “true”) evaluate to “true”). Similarly, if you have ⟨test1⟩ && ⟨test2⟩ then if ⟨test1⟩ is false, there's no need to evaluate ⟨test2⟩ (since both (“false” and “false”) and (“false” and “true”) evaluate to “false”). You may therefore need to consider the optimal ordering of any conditionals, such as placing changed or unchanged at the start of the condition. Alternatively, you can use the non-short-circuited operators | or &.

Footnotes

... expression.²: See the Java Pattern class documentation for further details.

⇦

⇧

⇨

This book is also available as A4 PDF or 12.8cm x 9.6cm PDF or paperback (ISBN 978-1-909440-07-4).