% !TeX root = ../arara-manual.tex
\chapter{YAML}
\label{chap:yaml}

According to the \href{http://yaml.org/spec/1.2/spec.html}{specification}, YAML (a recursive acronym for \emph{YAML Ain't Markup Language}) is a human-friendly, cross language, Unicode-based data serialization language designed around the common native data type of programming languages. \arara\ uses this format in three circumstances:

\begin{enumerate}
\item\emph{Parametrized directives}, as the set of attribute/value pairs (namely, argument name and corresponding value) is represented by a map. This particular type of directive is formally introduced in Section~\ref{sec:directives}, on page~\pageref{sec:directives}.

\item\emph{Rules}, as their entire structure is represented by a set of specific keys and their corresponding values (a proper YAML document). A rule follows a very strict model, detailed in Section~\ref{sec:rule}, on page~\pageref{sec:rule}.

\item\emph{Configuration files}, as the general settings are represented by a set of specific keys and their corresponding values (a proper YAML document). Configuration files are covered in Chapter~\ref{chap:configurationfile}, on page~\pageref{chap:configurationfile}.
\end{enumerate}

This chapter only covers the relevant parts of the YAML format for a consistent use with \arara. For advanced topics, I highly recommend the complete format specification, available online.

\section{Collections}
\label{sec:yamlcollections}

According to the specification, YAML's block collections use indentation for scope and begin each entry on its own line. Block sequences indicate each entry with a dash and space. Mappings use a colon and space to mark each \emph{key: value} pair. Comments begin with an octothorpe \rbox{\#}. \arara\ relies solely on mappings and a few scalars to sequences at some point. Let us see an example of a sequence:

\begin{codebox}{A sequence of scalars in YAML}{teal}{\icnote}{white}
team:
- Paulo Cereda
- Marco Daniel
- Brent Longborough
- Nicola Talbot
- Ben Frank
\end{codebox}

It is quite straightforward: \abox{team} holds a sequence of four scalars. YAML also has flow styles, using explicit indicators rather than indentation to denote scope. The flow sequence is written as a comma-separated list within square brackets:

\begin{codebox}{A sequence of scalars in YAML}{teal}{\icnote}{white}
primes: [ 2, 3, 5, 7, 11 ]
\end{codebox}

Attribute maps are easily represented by nesting entries, respecting indentation. For instance, consider a map \abox{developer} containing two keys, \abox{name} and \abox{country}. The YAML representation is presented as follows:

\begin{codebox}{An attribute map in YAML}{teal}{\icnote}{white}
developer:
 name: Paulo
 country: Brazil
\end{codebox}

Similarly, the flow mapping uses curly braces. Observe that this is the form adopted by a parametrized directive (see syntax in Section~\ref{sec:directives}, on page~\pageref{sec:directives}):

\begin{codebox}{An attribute map in YAML (flow mapping)}{teal}{\icnote}{white}
developer: { name: Paulo, country: Brazil }
\end{codebox}

An attribute map can contain sequences as well. Consider the following code where \abox{developers} holds a list of two developers containing their names and countries:

\begin{codebox}{An attribute map with sequences in YAML}{teal}{\icnote}{white}
developers:
- name: Paulo
  country: Brazil
- name: Marco
  country: Germany
\end{codebox}

The previous code can be easily represented in flow style by using square and curly brackets to represent sequences and attribute maps.

\section{Scalars}
\label{sec:yamlscalars}

Scalar content can be written in block notation, using a literal style, indicated by a vertical bar, where \emph{all line breaks are significant}. Alternatively, they can be written with the folded style, denoted by a greater-than sign, where \emph{each line break is folded to a space} unless it ends an empty or a more-indented line. It is mportant to note that \arara\ intensively uses both styles (as seen in Section~\ref{sec:rule}, on page~\pageref{sec:rule}). Let us see an example:

\begin{codebox}{Scalar content in literal and folded styles}{teal}{\icnote}{white}
logo: |
  This is the arara logo
  in its ASCII glory! 
    __ _ _ __ __ _ _ __ __ _ 
   / _` | '__/ _` | '__/ _` |
  | (_| | | | (_| | | | (_| |
   \__,_|_|  \__,_|_|  \__,_|
slogan: >
  The cool TeX
  automation tool
\end{codebox}

As seen in the previous code, \abox{logo} holds the ASCII logo of our tool, respecting line breaks. Similarly, observe that the \abox{slogan} key holds the text with line breaks replaced by spaces (in the same fashion \TeX\ does with consecutive, non-empty lines).

\begin{messagebox}{Block indentation indicator}{attentioncolour}{\icattention}{black}
\setlength{\parskip}{1em}
According to the YAML specification, the indentation level of a block scalar is typically detected from its first non-empty line. It is an error for any of the leading empty lines to contain more spaces than the first non-empty line, hence the ASCII logo could not be represented, as it starts with a space.

When detection would fail, YAML requires that the indentation level for the content be given using an explicit indentation indicator. This level is specified as the integer number of the additional indentation spaces used for the content, relative to its parent node. It would be the case if we want to represent our logo without the preceding text.
\end{messagebox}

YAML's flow scalars include the plain style and two quoted styles. The double-quoted style provides escape sequences. The single-quoted style is useful when escaping is not needed. All flow scalars can span multiple lines. Note that line breaks are always folded. Since \arara\ uses MVEL as its underlying scripting language (Chapter~\ref{chap:mvel}, on page~\pageref{chap:mvel}), it might be advisable to quote scalars when starting with forbidden symbols in YAML.

\section{Tags}
\label{sec:yamltags}

According to the specification, in YAML, untagged nodes are given a type depending on the application. The examples covered in this primer use the \rbox{seq}, \rbox{map} and \rbox{str} types from the fail safe schema. Explicit typing is denoted with a tag using the exclamation point symbol. Global tags are usually uniform resource identifiers and may be specified in a tag shorthand notation using a handle. Application-specific local tags may also be used. For \arara, there is a special schema used for both rules and configuration files, so in those cases, make sure to add \abox{!config} as global tag:

\begin{codebox}{Global tag for rules and configuration files}{teal}{\icnote}{white}
!config
\end{codebox}

In particular, rules and configuration files of \arara\ are properly covered in Section~\ref{sec:rule} and Chapter~\ref{chap:configurationfile}, on pages~\pageref{sec:rule} and~\pageref{chap:configurationfile}, respectively. For now, it suffices to say that the \abox{!config} global tag is necessary to provide the correct mapping of values inside our tool.

\section{Further reading}
\label{sec:yamlfurtherreading}

This chapter does not cover all features of the YAML format, so further reading is advisable. I highly recommend the \href{http://yaml.org/spec/1.2/spec.html}{official YAML specification}, currently covering the third version of the format.
