% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\section{library(yaml): Process YAML data}

\label{sec:yaml}

This module parses YAML serialized data into a Prolog term with
structure that is compatible with the JSON library. This library is a
wrapper around the C library \const{libyaml}. This library forms the basis of
the YAML support in several languages and thus guarantees compatibility
of our YAML support with other languages.\vspace{0.7cm}

\begin{description}
    \predicate[det]{yaml_read}{2}{+Input, -DOM}
Parse \arg{Input} to a YAML \arg{DOM}. The \arg{DOM} representation uses the following
mapping:

\begin{itemize}
    \item A YAML sequence is mapped to a Prolog List.
    \item A YAML mapping is mapped to a Prolog dict.
    \item Untagged \textit{scalars} follow the implicit tag rules defined by
YAML, providing numbers (int, float and special floats),
\const{null} and the booleans \const{true} and \const{false}. Other untagged
values are returned as a Prolog string. Tagged values are
returned as \verb$tag(Tag, String)$ which is processed by
\predref{yalm_tagged}{3}. This internal predicate calls the user hook
\qpredref{yaml}{tagged}{3} with the same arguments and, if the hook fails,
provides the following defaults:

\begin{shortlist}
    \item \verb$!!binary$ converts the Base64 to a string of bytes.
    \item \verb$!!str$ explicitly keeps a string
    \item \verb$!!null$ translates "null" to \const{null}
    \item \verb$!!bool$ translates to \const{true} and \const{false}
    \item \verb$!!int$ translates to an integer
    \item \verb$!!float$ translates to a float
    \item Anything else is returned as \verb$tag(Tag, String)$
\end{shortlist}
\end{itemize}

\begin{arguments}
\arg{Input} & is one of (1) a stream, (2) a term \verb$string(Data)$ or
(3) a file name. \\
\end{arguments}

\begin{tags}
    \tag{bug}
YAML defines that floats do not require a digit after the
decimal dot. We use the Prolog parser which does require the
decimal dot to be followed by at least one digit. Because the
YAML spec intends to match JSON which does require a digit,
we ignore this incompatibility, expecting it will be addressed
in the next YAML version.
\end{tags}

    \predicate[det]{yaml_write}{2}{+Out:stream, +DOM}
\nodescription
    \predicate[det]{yaml_write}{3}{+Out:stream, +DOM, +Options}
Emit a YAML \arg{DOM} object as a serialized YAML document to the stream
\arg{Out}. \arg{Options} processed are:

\begin{description}
    \termitem{canonical}{+Boolean}
Use canonical representation. Default is \const{false}.
    \termitem{unicode}{+Boolean}
Use unicode Default is \const{true}.
    \termitem{implicit}{+Boolean}
Use implicit or explicit representation. Currently only
affects the opening and closing the document. Default is
\const{true}. Use \const{false} for embedded documents.
    \termitem{factorize}{+Boolean}
If \const{true}, minimize the term by factoring out common
structures and use \verb$&anchor$ and \verb$*anchor$. Factorization
is always used if \arg{DOM} is a cyclic term.
\end{description}

    \predicate[semidet,multifile]{tagged}{3}{+Tag, ?String, ?Value}
Hook that allows convering \verb$!!tag$ values to be decoded or
encoded.
\end{description}