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



\section{library(semweb/turtle): Turtle: Terse RDF Triple Language}

\label{sec:turtle}

\begin{tags}
    \tag{See also}
\url{http://www.w3.org/TR/turtle/} (used W3C Recommendation 25
February 2014)
\end{tags}

This module implements the Turtle language for representing the RDF
triple model as defined by Dave Beckett from the Institute for Learning
and Research Technology University of Bristol and later standardized by
the W3C RDF working group.

This module acts as a plugin to \predref{rdf_load}{2}, for processing files with
one of the extensions \verb$.ttl$ or \verb$.n3$.\vspace{0.7cm}

\begin{description}
    \predicate{rdf_read_turtle}{3}{+Input, -Triples, +Options}
Read a stream or file into a set of triples or quadruples (if
faced with TriG input) of the format

\begin{code}
rdf(Subject, Predicate, Object [, Graph])
\end{code}

The representation is consistent with the SWI-Prolog RDF/XML
and ntriples parsers. Provided options are:

\begin{description}
    \termitem{base_uri}{+BaseURI}
Initial base URI. Defaults to file://$<$file$>$ for loading
files.
    \termitem{anon_prefix}{+Prefix}
Blank nodes are generated as $<$\arg{Prefix}$>$1, $<$\arg{Prefix}$>$2, etc.
If \arg{Prefix} is not an atom blank nodes are generated as
\verb$node(1)$, \verb$node(2)$, ...
    \termitem{format}{+Format}
One of \const{auto} (default), \const{turtle} or \const{trig}. The
auto mode switches to TriG format of there is a
\verb${$ before the first triple. Finally, of the
format is explicitly stated as \const{turtle} and the
file appears to be a TriG file, a warning is printed
and the data is loaded while ignoring the graphs.
    \termitem{resources}{URIorIRI}
Officially, Turtle resources are IRIs. Quite a
few applications however send URIs. By default we
do URI\Sifthen{}IRI mapping because this rarely causes errors.
To force strictly conforming mode, pass \const{iri}.
    \termitem{prefixes}{-Pairs}
Return encountered prefix declarations as a
list of Alias-URI
    \termitem{namespaces}{-Pairs}
Same as \verb$prefixes(Pairs)$. Compatibility to \predref{rdf_load}{2}.
    \termitem{base_used}{-Base}
\arg{Base} URI used for processing the data. Unified to
\Snil{} if there is no base-uri.
    \termitem{on_error}{+ErrorMode}
In \const{warning} (default), print the error and continue
parsing the remainder of the file. If \const{error}, abort
with an exception on the first error encountered.
    \termitem{error_count}{-Count}
If \verb$on_error(warning)$ is active, this option cane be
used to retrieve the number of generated errors.
\end{description}

\begin{arguments}
\arg{Input} & is one of \verb$stream(Stream)$, \verb$atom(Atom)$, a \const{http},
\const{https} or \const{file} url or a filename specification as
accepted by \predref{absolute_file_name}{3}. \\
\end{arguments}

    \predicate{rdf_load_turtle}{3}{+Input, -Triples, +Options}

\begin{tags}
    \tag{deprecated}
Use \predref{rdf_read_turtle}{3}
\end{tags}

    \predicate[det]{rdf_process_turtle}{3}{+Input, :OnObject, +Options}
Streaming Turtle parser. The predicate \predref{rdf_process_turtle}{3}
processes Turtle data from \arg{Input}, calling \arg{OnObject} with a list
of triples for every Turtle \textit{statement} found in \arg{Input}. \arg{OnObject}
is called as below, where \arg{ListOfTriples} is a list of
\verb$rdf(S,P,O)$ terms for a normal Turtle file or \verb$rdf(S,P,O,G)$ terms
if the \verb$GRAPH$ keyword is used to associate a set of triples in
the document with a particular graph. The \arg{Graph} argument
provides the default graph for storing the triples and \textit{Line} is
the line number where the statement started.

\begin{code}
call(OnObject, ListOfTriples, Graph:Line)
\end{code}

This predicate supports the same \arg{Options} as \predref{rdf_load_turtle}{3}.

Errors encountered are sent to \predref{print_message}{2}, after which the
parser tries to recover and parse the remainder of the data.

\begin{tags}
    \tag{See also}
This predicate is normally used by \predref{load_rdf}{2} for
processing RDF data.
\end{tags}

    \predicate[semidet]{turtle_pn_local}{1}{+Atom:atom}
True if \arg{Atom} is a valid Turtle \textit{PN_LOCAL} name. The PN_LOCAL
name is what can follow the : in a resource. In the new Turtle,
this can be anything and this function becomes meaningless. In
the old turtle, PN_LOCAL is defined similar (but not equal) to
an XML name. This predicate is used by \predref{rdf_save_turtle}{2} to
write files such that can be read by old parsers.

\begin{tags}
    \tag{See also}
\predref{xml_name}{2}.
\end{tags}

    \predicate[det]{turtle_write_quoted_string}{2}{+Out, +Value}
Same as \verb$turtle_write_quoted_string(Out, Value, false)$, writing a
string with only a single \verb$"$. Embedded newlines are escapes
as \verb$\n$.

    \predicate[det]{turtle_write_uri}{2}{+Out, +Value}
Write a URI as \verb$<...>$

\qpredicate[multifile]{rdf_db}{rdf_load_stream}{3}{+Format, +Stream, :Options}(Turtle clauses)

    \predicate[det]{rdf_save_turtle}{2}{+Out, :Options}
Save an RDF graph as Turtle. \arg{Options} processed are:

\begin{description}
    \termitem{a}{+Boolean}
If \const{true} (default), use \const{a} for the predicate \verb$rdf:type$.
Otherwise use the full resource.
    \termitem{align_prefixes}{+Boolean}
Nicely align the @prefix declarations
    \termitem{base}{+Base}
Save relative to the given \arg{Base}
    \termitem{canonize_numbers}{+Boolean}
If \const{true} (default \const{false}), emit numeric datatypes using
Prolog's write to achieve canonical output.
    \termitem{comment}{+Boolean}
It \const{true} (default), write some informative comments
between the output segments
    \termitem{encoding}{+Encoding}
\arg{Encoding} used for the output stream. Default is UTF-8.
    \termitem{expand}{:Goal}
Query an alternative graph-representation. See below.
    \termitem{indent}{+Column}
Indentation for ; -lists. `0' does not indent, but
writes on the same line. Default is 8.
    \termitem{graph}{+Graph}
Save only the named graph
    \termitem{group}{+Boolean}
If \const{true} (default), using P-O and O-grouping.
    \termitem{inline_bnodes}{+Boolean}
if \const{true} (default), inline bnodes that are used once.
    \termitem{abbreviate_literals}{+Boolean}
if \const{true} (default), omit the type if allowed by turtle.
    \termitem{only_known_prefixes}{+Boolean}
Only use prefix notation for known prefixes. Without, some
documents produce \textit{huge} amounts of prefixes.
    \termitem{prefixes}{+List}
If provided, uses exactly these prefixes. \arg{List} is a list
of prefix specifications, where each specification is either
a term \textit{Prefix_-_URI} or a prefix that is known to
\predref{rdf_current_prefix}{2}.
    \termitem{silent}{+Boolean}
If \const{true} (default \const{false}), do not print the final
informational message.
    \termitem{single_line_bnodes}{+Bool}
If \const{true} (default \const{false}), write [...] and (...) on a
single line.
    \termitem{subject_white_lines}{+Count}
Extra white lines to insert between statements about a
different subject. Default is 1.
    \termitem{tab_distance}{+Tab}
Distance between tab-stops. `0' forces the library to
use only spaces for layout. Default is 8.
    \termitem{user_prefixes}{+Boolean}
If \const{true} (default), use prefixes from \predref{rdf_current_prefix}{2}.
\end{description}

The option \const{expand} allows for serializing alternative graph
representations. It is called through \predref{call}{5}, where the first
argument is the expand-option, followed by S,P,O,G. G is the
graph-option (which is by default a variable). This notably
allows for writing RDF graphs represented as \verb$rdf(S,P,O)$ using
the following code fragment:

\begin{code}
triple_in(RDF, S,P,O,_G) :-
    member(rdf(S,P,O), RDF).

    ...,
    rdf_save_turtle(Out, [ expand(triple_in(RDF)) ]),
\end{code}

\begin{arguments}
\arg{Out} & is one of \verb$stream(Stream)$, a stream handle, a file-URL
or an atom that denotes a filename. \\
\end{arguments}

    \predicate[det]{rdf_save_ntriples}{2}{+Spec, :Options}
Save RDF using ntriples format. The ntriples format is a subset
of Turtle, writing each triple fully qualified on its own line.

    \predicate[det]{rdf_save_canonical_trig}{2}{+Spec, :Options}
Save triples in a canonical format. See
\predref{rdf_save_canonical_turtle}{2} foir details.

    \predicate[det]{rdf_save_trig}{2}{+Spec, :Options}
Save multiple RDF graphs into a TriG file. \arg{Options} are the same
as for \predref{rdf_save_turtle}{2}. \predref{rdf_save_trig}{2} ignores the
\verb$graph(+Graph)$ option and instead processes one additional
option:

\begin{description}
    \termitem{graphs}{+ListOfGraphs}
List of graphs to save. When omitted, all graphs in the RDF
store are stored in the TriG file.
\end{description}

    \predicate[det]{rdf_save_canonical_turtle}{2}{+Spec, :Options}
Save triples in a canonical format. This is the same as
\predref{rdf_save_turtle}{2}, but using different defaults. In particular:

\begin{shortlist}
    \item \verb$encoding(utf8)$,
    \item \verb$indent(0)$,
    \item \verb$tab_distance(0)$,
    \item \verb$subject_white_lines(1)$,
    \item \verb$align_prefixes(false)$,
    \item \verb$user_prefixes(false)$
    \item \verb$comment(false)$,
    \item \verb$group(false)$,
    \item \verb$single_line_bnodes(true)$
\end{shortlist}

\begin{tags}
    \tag{To be done}
Work in progress. Notably blank-node handling is
incomplete.
\end{tags}
\end{description}