parse-rdf v1.1.1

The "parse-rdf" package is used for parsing and dealing with RDF. This
program is in the public domain.

The main parsing function is parse or gparse, and two objects are used
being Graph and Literal.

There are also a few other properties of the module: RDF, RDFS, and XSD
are strings representing common URI prefixes.

In the data model, there are URIs, blank nodes, and literals. A URI is
represented as a string. A blank node is represented as a symbol. A
literal is represented as a Literal object.

A Literal object is constructed as "new Literal(val,typ)" where val is
the value (a string), and typ is the data type URI (also a string). The
"value" and "type" properties of that object then have these strings. It
is recommended to treat Literal instances as immutable; you should not
write to them but instead create a new one.

The Literal object itself has properties named by datatype URIs. These
properties are functions that would convert a value into a native
JavaScript value; however only some datatypes are defined. You are allowed
to add your own too.

To create a language-tagged string literal, use the langString function,
which takes a string and a language code. These are still instances of
Literal and function in the same way. If no language code is specified,
then "i-default" is used as the language code.

The Literal.prototype object has properties:

.equals(x) = Where x is another Literal object, it returns true if they
are equal or false otherwise. The value and type properties must both be
exactly equal strings; just representing the same value isn't good enough.

.getLanguage() = Returns the language code of a language tagged string. If
it is not a language tagged string, returns "i-default".

.toValue() = Converts into a native value by the use of the static
properties on Literal.

A Graph object is constructed as "new Graph()" which creates an empty RDF
graph representation object.

The object has properties named by URIs and symbols, the value of each of
which is an object. These property names correspond to the subject of a
triple. The object that is the value of these properties contains
properties named by URIs which correspond to the predicate of a triple.
The value of these properties are arrays of values which are the object of
the RDF triple.

The Graph.prototype object has properties:

.add(subj,pred,val,typ) = Adds an edge to the graph. The subj is a URI or
symbol to use as the subject of the triple, and pred is the URI of the
predicate. If typ is unspecified (or false or null or undefined), then the
val is the value of the object of the triple, which is a URI, symbol, or a
Literal object. If typ is specified it is the data type URI and val is the
string which represents the literal. Returns the Graph object called on
(so that it can be chained).

.clone() = Returns a new Graph instance consisting of the same triples.

.cloneDistinct() = The same as clone() but converts all blank nodes into
new ones so that the new graph does not share any blank nodes with the old
graph.

.delete(subj,pred,val,typ) = See add. It is similar but this method
deletes the triple instead. There is no useful return value.

.enumerate() = Returns a generator object that enumerates all of the
triples in this graph. The values yielded are objects with properties
named "subject", "predicate", and "object".

.export() = Returns the N-Triples representation of the graph.

.findObject(x) = The parameter x is the value intended to find as the
object of a triple. It returns a generator like enumerate() but only the
triples that have the specified value as the object.

.findPredicate(x) = Similar to findObject but finds the specified
predicate instead.

.findProperty(x,y) = Returns a generator that yields the subject URI (or
symbols) of triples that have predicate x and object y. This generator
does not yield JavaScript objects like the other ones do; it yields only
primitive values (strings and symbols).

.listNodes() = Return an array of all nodes in the graph (only URIs and
blank nodes; no literal nodes are listed).

.skolemize(f) = The function f should take no arguments (it is called with
no arguments) and is supposed to return a different symbol or URI string
each time. It is called for each blank node in the graph, and then the
return value is used to replace that blank node with the new node. Note
that obj.skolemize(Symbol) can be used to replace all blank nodes with new
ones; the implementation of cloneDistinct internally does this. Returns
the Graph object called on (so that it can be chained).

Parsing is done by the parse/gparse functions:

gparse(inp,out,base,obj) = The parameter inp should be either a string or a
generator function. The parameter out is null or undefined or a generator
function expected to be called as (x,subj,pred,val,typ) where x is the old
obj value and the returned value is passed the next time. The base is
optional and can be the default base URI. The obj parameter is just passed
to out to determine the new one; the final result of out is the returned
from the generator of gparse. Anything that inp/out yields will be yield
by this generator too. If out function is not specified, it will allocate
a new Graph object and add the triples to that graph.

parse(inp,out,base,obj) = Similar to gparse but is not a generator
function, and out also should not be a generator function. The inp can be
still a string or a generator function, although if inp yields anything
then parse just returns the value yielded and won't continue.

The inp generator function should return either a string, or null if the
end of the file is reached. It is called with no arguments in order to
read some more of the input data; they can read as much as they want each
time. If data is not available, it should yield and then the gparse
generator continued once the data is available.

Other functions:

equals(x,y) = Check if x and y are equal. If it is an object, then the
value of properties called "value" and "type" are checked for equal.

escape(x) = Makes the string x into the string literal format suitable for
use with N-Triples. Unprintable and non-ASCII characters are represented
as escaped characters.

escapeURI(x) = The string x is expected to be a URI. It converts into the
format suitable for including a URI in a N-Triples file, including any
escaping as necessary.

langString(text,lang) = Makes a language tagged string literal.

makeNode(val,typ) = If typ is omitted (or is undefined or null or zero or
an empty string) then returns val, otherwise makes a new Literal object.

The following extensions to standard RDF format are implemented:

* A "deanonymizing operator" consists of an exclamation mark followed by
a URI, URI abbreviation, or blank node name. It is allowed at the
beginning of a [] block or before any item in a () block, and causes that
node to be given that name instead of making a new anonymous node.

* A "cons-cell operator" consists of a comma and is placed inside of a ()
block, just after the last item. The comma can optionally be followed by
another object. This operator sets the rdf:rest for the last item,
allowing to create looping lists or unterminated lists using a more
convenient syntax.

* Integer literals can be written in hexadecimal, which starts with "0x"
and is followed by the hex digits. The "x" must be in lowercase and the
hex digits must be in uppercase. It is automatically converted to decimal
in the returned RDF data.

TODO:

* More severe testing

* New graph methods: .canonize() .equals(x) .isomorphic(x)