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 in the document:
The Turtle format is designed as an RDF serialization that is easy to
read and write by both machines and humans. Due to the latter property,
this library goes a long way in trying to produce human-readable output.
In addition to the human-readable format, this library can write a
canonical representation of RDF graphs. The canonical representation
has the following properties:
- Equivalent graphs result in the same document. Graphs are
considered equivalent iff they contain the same set of
triples, regardless of the labeling of blank nodes in the
graph.
- Changes to the graph are diff-friendly. This means
- Prefixes are combined in the header and thus changes
to the namespaces only result in changes in the header.
- Blank nodes that are used only once (including collections)
are written in-line with the object they belong to.
- For other blank nodes we to realise stable labeling that
is based on property-values.
- To be done
- - Low-level string output takes 28% of the time. Move to C?
- rdf_save_turtle(+Out, :Options) is det
- Save an RDF graph as Turtle. Options processed are:
- a(+Boolean)
- If
true
(default), use a
for the predicate rdf:type
.
Otherwise use the full resource.
- align_prefixes(+Boolean)
- Nicely align the @prefix declarations
- base(+Base)
- Save relative to the given Base
- canonize_numbers(+Boolean)
- If
true
(default false
), emit numeric datatypes using
Prolog's write to achieve canonical output.
- comment(+Boolean)
- It
true
(default), write some informative comments
between the output segments
- encoding(+Encoding)
- Encoding used for the output stream. Default is UTF-8.
- expand(:Goal)
- Query an alternative graph-representation. See below.
- indent(+Column)
- Indentation for ; -lists. `0' does not indent, but
writes on the same line. Default is 8.
- graph(+Graph)
- Save only the named graph
- group(+Boolean)
- If
true
(default), using P-O and O-grouping.
- inline_bnodes(+Boolean)
- if
true
(default), inline bnodes that are used once.
- abbreviate_literals(+Boolean)
- if
true
(default), omit the type if allowed by turtle.
- only_known_prefixes(+Boolean)
- Only use prefix notation for known prefixes. Without, some
documents produce huge amounts of prefixes.
- prefixes(+List)
- If provided, uses exactly these prefixes. List is a list
of prefix specifications, where each specification is either
a term Prefix_-_URI or a prefix that is known to
rdf_current_prefix/2.
- silent(+Boolean)
- If
true
(default false
), do not print the final
informational message.
- single_line_bnodes(+Bool)
- If
true
(default false
), write [...] and (...) on a
single line.
- subject_white_lines(+Count)
- Extra white lines to insert between statements about a
different subject. Default is 1.
- tab_distance(+Tab)
- Distance between tab-stops. `0' forces the library to
use only spaces for layout. Default is 8.
- user_prefixes(+Boolean)
- If
true
(default), use prefixes from rdf_current_prefix/2.
The option expand
allows for serializing alternative graph
representations. It is called through 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 rdf(S,P,O)
using
the following code fragment:
triple_in(RDF, S,P,O,_G) :-
member(rdf(S,P,O), RDF).
...,
rdf_save_turtle(Out, [ expand(triple_in(RDF)) ]),
- Arguments:
-
Out | - is one of stream(Stream) , a stream handle, a file-URL
or an atom that denotes a filename. |
- rdf_save_canonical_turtle(+Spec, :Options) is det
- Save triples in a canonical format. This is the same as
rdf_save_turtle/2, but using different defaults. In particular:
encoding(utf8)
,
indent(0)
,
tab_distance(0)
,
subject_white_lines(1)
,
align_prefixes(false)
,
user_prefixes(false)
comment(false)
,
group(false)
,
single_line_bnodes(true)
- To be done
- - Work in progress. Notably blank-node handling is
incomplete.
- rdf_save_ntriples(+Spec, :Options) is det
- Save RDF using ntriples format. The ntriples format is a subset
of Turtle, writing each triple fully qualified on its own line.
- rdf_save_trig(+Spec, :Options) is det
- Save multiple RDF graphs into a TriG file. Options are the same
as for rdf_save_turtle/2. rdf_save_trig/2 ignores the
graph(+Graph)
option and instead processes one additional
option:
- graphs(+ListOfGraphs)
- List of graphs to save. When omitted, all graphs in the RDF
store are stored in the TriG file.
- rdf_save_canonical_trig(+Spec, :Options) is det
- Save triples in a canonical format. See
rdf_save_canonical_turtle/2 foir details.
- trig_graphs(+State, -Graphs) is det[private]
- True when Graphs is the (sorted) list of graphs we must save. If
the expand argument is used and no graphs are specified, it
enumerates all triples and extracts the graphs.
- open_output(+Spec, +Encoding, -Stream, -Cleanup) is det[private]
- Open output Spec, returning a stream using Encoding.
- Arguments:
-
Cleanup | - is a goal that must be used to revert the side
effects of open_output/4. |
- init_prefix_map(+State, -State) is det[private]
- Set the prefix_map of State. The prefix map is list of
Prefix-URI of prefixes to use for emitting the graph requested
in State. If multiple prefixes are present where the one is a
prefix of the other, the longer one appears first in the list.
- user_prefix_map(+Prefixes, -PrefixMap) is det[private]
- Convert a list of prefix specifications to a list Prefix-URI,
longest URI first.
- turtle_prefix(+OnlyKnown, +Where, +Prefix, +URI) is semidet
- Test whether we want to include the proposed prefix in the
@prefix declaration.
- propose_abbrev(+State, +Len, +URI, -Abbrev) is multi[private]
- Propose an abbreviation for URI. Backtracking yields longer
ones.
- namespace_parts(+URL, -Parts)[private]
- init_base(+State0, -State) is det[private]
- Initialise dealing with the base URI. It sets two attributes of
the state: base_root and base_path.
- tw_graph(+State, +Out) is det[private]
- Write an RDF graph as Turtle data.
- To be done
- - Write unconnected and multi-connected blank-nodes.
- tw_prefix_map(+PrefixMap, +State, +Out) is det[private]
- Write the @base and @prefix declarations
- tw_proper_subjects(+Subjects, +State, +Out) is det[private]
- Write the subjects that are not Bnodes.
- tw_subject(+URI, +State, +Out) is det[private]
- Write a toplevel non-bnode subject.
- tw_bnodes(+Pairs, +State, +Out) is det[private]
- Write the Bnodes. Pairs is a list URI-Ref, where Ref is one of
written
if the Bnode is already written; an integer if it is
used multiple times or a variable if it has not been written.
The order in which we deal with bnodes is defined as follows:
- First, write the bnodes that are not referenced at all
as toplevel bnodes using [ ... ] notation.
- Next, write the bnodes that need written as toplevel
nodes using the _:XX notation because they are referenced
multiple times in the graph. Continue this process until it
is exhausted.
- tw_top_bnodes(+Pairs, +State, +Out, -Rest)[private]
- Write the top bnodes: those that do not appear as an object
anywhere.
- tw_cyclic_bnodes(+Pairs, +BNode, +State, +Out, +Cycle)[private]
- The rest. These are groups of bnodes that are reachable, but we
cannot find a starting point, neither from a named resource, nor
from an unlinked bnode. As long as we are not considering stable
canonical output, we can break the cycle at any point.
- tw_subject_triples(+Grouped, +Subject, +State, +Out)[private]
- Save triples on Subject. Combine groups of triples with the
same subject (;) and same subject+predicate (,).
- Arguments:
-
Subject | - is either a URI or an integer. The latter is
used for writing a named bnode. |
- tw_ungrouped_triples(+Grouped, +URI, +State, +Out)[private]
- Write triples for subject URI as one line per triple. Used
for canonical output.
- tw_triples(+Groups, +Indent, +State, +Out) is det[private]
- Triple writer that uses ; and ,- grouping
- tw_object(+Value, +State, +Out) is det[private]
- Write the object of a triple.
- tw_bnode_object(+Value, +State, +Out) is det[private]
- Write a Bnode value. There are a number of cases:
- The BNode was already written. Write the same ref.
- The BNode is not shared. Inline and set
written
- The BNode is shared. Generate a NodeID and store it
- The BNode is once as object: Generate a NodeID
- The BNode is more than once object: Generate a NodeID
and put in table.
- tw_unshared_bnode(+BNode, +State, +Out) is semidet[private]
- Write a bnode if this is the only place it is used.
- unshared_collection(+URI, +State, -Members) is semidet[private]
- True if URI denodes an RDF list that is made up from bnodes, is
linked exactly once to its context and contains no extra
triples.
- object_link_count(+BNode, +STate, -Count) is det[private]
- Number of times BNode is used as an object in the graph
- nl_indent(+Out, +State, +Indent) is det[private]
- Write a newline and indent to column Indent.
- subject_triples(+URI, +State, -Pairs) is det[private]
- Pairs is a sorted list of P-O pairs representing all triples on
the subject URI.
- subjects(+State, -Subjects:ord_set) is det[private]
- Subjects is a list of all subjects in the graph requested in
State.
- sort_bnodes(+BNodes, -Sorted, +State) is det[private]
- Sort a list of blank nodes.
- sort_bnode_pairs(+Pairs, -Sorted, +State) is det[private]
- Sort a list of Pairs BNode-Ref
- bnode_to_term(+BNode, -Term, +State)[private]
- Term is a canonical representation of the graph formed by BNode.
The transformation of a bnode is
bnode(p-[o1,o2,..], ..)
The arguments are alphabetically sorted on predicate (can't we
leave the preds out them?) and the objects are alphabetically
sorted. Sorting multiple bnode values?
- next_bnode_id(+State, +BNode, -Ref) is det[private]
- Generate a node-id for BNode. When writing non-canonically, we
simply number the bnodes. Otherwise we want a more stable
numbering. Our numbering is a hash of the content of the bnode.
It is not unlikely that we find muliple copies, and therefore we
number the full id is bn_<hash>_<n>, <n> counting 0...
- bnode_hash(+BNode, -Hash) is det[private]
- Hash is the hash-value for a bnode.
- To be done
- - : Hash on content.
- tw_resource(+Resource, +State, +Out) is det[private]
- Write a resource
- tw_literal(+Literal, +State, +Out) is det[private]
- Write a literal value to the stream Out.
- tw_abbreviated_literal(+Type, +Value, +State, +Out) is semidet[private]
- Turtle abbreviated typed literals.
- To be done
- - : Deal with canonical forms (or is this a task of the
RDF parser?
- - : What if the value is not in the lexical space of the type?
- tw_quoted_string(+Atom, +State, +Out) is det[private]
- Write Atom to Out as a quoted string. We only use the
single-"..." representation.