►The rdf library, wrapping the Redland RDF library
1 Storage and models
open-model
add-to-model
write-model
write-model-identify-serializer
new-storage
model-size
storage?
model?
2 Model contents
2.1 Nodes and statements
new-blank-node
node->uri
statement?
statement=?
statement-subject
statement-predicate
statement-object
new-statement
node?
blank-node?
2.2 Literals
literal?
literal-type
literal->value
literal->string
3 Iterating over, and querying, the graph
fold-nodes/ node
fold-nodes
map-nodes
map-nodes/ node
find-node/ node
find-node
fold-statements/ statements
fold-statements
fold-statements/ nodes
map-statements
map-statements/ nodes
map-statements/ statements
for-each-statement
query/ fold
query/ model
query/ ask
4 Other functions
4.1 URIs
new-uri
new-uri/ resolve
new-uri/ base
new-uri/ rebase
new-uri/ file
uri?
uri=?
uri<?
4.2 Miscellaneous
thing->string
thing->debugging-string
uri-in-namespace
version-information

The rdf library, wrapping the Redland RDF library

 (require rdf/rdf)

Norman Gray <http://nxg.me.uk>

The Redland RDF library is a well-known library for parsing, writing, constructing and querying RDF.

This Racket library wraps the librdf library, making its functionality available to Racket users. Not all of the librdf library is wrapped here, only that subset which the rdf/rdf library’s author found useful, and the interface to which could therefore be tested.

1 Storage and models

(open-model backing) → model?
  backing : (or/c model? storage? false/c)
Returns a new model. If backing is a model, then it is returned as-is, if it is storage, then this creates a new model backed by the storage, and if it is #f, then this returns a new in-memory model.
(add-to-model destination    
  source    
  [#:base-uri base-uri    
  #:mime-type mime-type    
  #:syntax syntax]) → model?
  destination : (or/c model? storage? false/c)
  source : (or/c uri? model? port? string? bytes? path? statement/c false/c)
  base-uri : (or/c string? uri?) = #f
  mime-type : string? = #f
  syntax : symbol? = #f
Adds content to a model.

Destination may be a model, storage or false: these are the same arguments as may be given to open-model.

  • If source is a URI, then read the data from that;

  • if it is a string, it should contain RDF, and we parse the contents of the string (base-uri, plus either syntax or mime-type, is required);

  • if it is a port, we parse the content of the stream (base-uri, plus either syntax or mime-type, is required);

  • if it is a model, we add all of the statements in the model to this one;

  • if it is a statement, we add the statement to the model;

  • if it is a path, we read RDF from the indicated file.

  • If source is #f, then simply return the model, without adding anything to it (this is therefore equivalent to open-model).

Keywords:

  • syntax: one of the librdf parser names (rdfxml, turtle, rdfa, grddl, ...)

  • mime-type: a MIME type, as a string

  • base-uri: used only when parsing from a string

(write-model model    
  [port    
  #:base-uri base-uri    
  #:mime-type mime-type    
  #:syntax syntax    
  #:namespaces namespaces]) → number?
  model : model?
  port : port? = #f
  base-uri : (or/c uri? false/c) = #f
  mime-type : (or/c string? bytes?) = #f
  syntax : symbol? = #f
  namespaces : (listof (cons/c string? (or/c string? uri?)))
   = '()
Write the model to the given port. If the port is omitted, then serialise the port to the (current-output-port). Returns the number of triples written to the port.

Keywords:

  • base-uri : base URI of output – #f for "don’t care"

  • mime-type and syntax : specify the output format (syntax is one of the symbols 'rdfxml, 'turtle, 'ntriples).

  • namespaces : prefix-namespace mappings (eg, '(("foaf" . "http://xmlns.com/foaf/0.1/")) )

(write-model-identify-serializer syntax 
  [#:select response]) 
 → (or/c symbol? bytes? string? false/c)
  syntax : (or/c string? symbol? bytes?)
  response : symbol? = name
Identify the serializer which can output the specified syntax. The syntax is indicated either by a syntax name (if syntax is a symbol such as ’rdfxml or ’turtle) or MIME type (if syntax is a string or bytes?).

The optional response argument indicates what is to be returned. If response argument is 'name, 'label or 'mime, then return the corresponding element, as symbol, string or bytestring respectively. Return #f if no serializer is found.

(new-storage #:option-name option ...) → storage?
  option : string?
(new-storage [storage-class    
  identifier]    
  #:option-name option ...) → storage?
  storage-class : symbol? = #f
  identifier : string? = #f
  option : string?
Returns a new storage object of the given storage class (for example 'sqlite), and with the given name (which will be a filename in the ’sqlite’ case). If these arguments are not present, then the storage is created in memory. The function may be given an arbitrary list of keyword-string pairs: these are passed to the underlying library as storage options. It will frequently be more convenient to use open-model to create storage implicitly.

(model-size model) → (or/c integer? false/c)
  model : model?
Returns the number of statements in the model, if this information is available (not all underlying stores can return the size of the graph).
(storage? v) → boolean?
  v : any/c
Returns #t if v is storage created by new-storage or add-model, and #f otherwise
(model? v) → boolean?
  v : any/c
Returns #t if v is an RDF model, and #f otherwise

2 Model contents

2.1 Nodes and statements

Models are composed of statements, each of which contains a subject, predicate and object node. The library tries reasonably hard to make this easy to use.

(new-blank-node) → blank-node?
Creates a new blank node
(node->uri node) → uri?
  node : node?
Extracts the URI from a resource node, or raises an RDF user error

(statement? v) → boolean?
  v : any/c
Returns #t if v is a statement extracted from a model, and #f otherwise.
(statement=? s1 s2) → boolean?
  s1 : statement/c
  s2 : statement/c
Returns #t if the two statements should be regarded as equal.
(statement-subject s) → (or/c uri? blank-node?)
  s : statement/c
Returns the statement’s subject.
(statement-predicate s) → uri?
  s : statement/c
Returns the statement’s predicate.
(statement-object s) → (or/c uri? blank-node? literal? list?)
  s : statement/c
Returns the statement’s object. The object is returned as a uri, blank node or literal if the object node is resource, anonymous resource or literal, respectively. If the object node is an rdf:List, then the return value is a scheme list of the corresponding objects, as uri/blank-node/literal.
(new-statement [statement    
  #:s subject    
  #:p predicate    
  #:o object    
  #:literal literal]) → statement/c
  statement : statement/c = #f
  subject : (or/c string? uri? node?) = #f
  predicate : (or/c string? uri? node? (symbols 'a)) = #f
  object : (or/c string? uri? node?) = #f
  literal : (or/c string? xml:xexpr? (listof xml:xexpr?) literal?)
   = #f
Called with no statement argument, construct a statement with subject, predicate and object as given. Called with a statement argument, create a copy of it, with any specified nodes changed. Each of #:s, #:p and #:o can be a string, a URI or a node, and each creates a URI node. That is, string arguments to #:o are converted to URIs, not literals. The argument of #:p may be 'a to create an rdf:type predicate

(node? v) → boolean?
  v : any/c
Returns #t if v is an RDF node returned from a model, and #f otherwise
(blank-node? v) → boolean?
  v : any/c
Returns #t if v is a node?, and specifically a blank node, and returns #f otherwise

2.2 Literals

Literals appear in a variety of places.

(literal? v) → boolean?
  v : any/c
Returns #t if the v is a literal, or #f otherwise.
(literal-type l) → (or/c string? uri? (symbols 'xml) false/c)
  l : literal?
Returns the type of the literal. Note that although the literal function accepts symbol types, as described, these are converted to the corresponding XSD URIs, and these literal types are reported with those URIs.
(literal->value literal) → any
  literal : literal?
Returns the literal, converted to the scheme type it corresponds to. The types in question correspond to the types in the literal creation function.
(literal->string literal) → string?
  literal : literal?
Returns the literal content formatted as a string. This is mostly useful for display.

3 Iterating over, and querying, the graph

There are a number of ways of interrogating the contents of a model, using a variety of fold, map, iteration and (SPARQL) query procedures. These differ depending on whether the mapping/folding procedure is given a statement/node as argument, or the contents of the statement/node converted to one or more Scheme values.

(fold-nodes/node proc    
  init    
  model    
  subject    
  predicate    
  object) → any
  proc : (-> node? any/c any)
  init : any/c
  model : model?
  subject : (or/c node? uri? string? false/c)
  predicate : (or/c node? uri? string? false/c (symbols 'a))
  object : (or/c node? uri? string? literal? false/c)
Basic node iterator. The proc is folded over a sequence of nodes resulting from the query.

  • subject: a string is converted to a URI

  • predicate: a string is converted to a URI, and the symbol ’a is shorthand for rdf:type

  • object: a string is converted to a plain literal

In this query, a string in either the subject or predicate position is converted to a URI; a string in the object position indicates an untyped string literal.

There are three node arguments, and any that are #f are wildcarded. Thus, for example, arguments foo bar #f would return all nodes with that subject and predicate (librdf get_targets function), and foo #f #f returns all arcs outbound from foo (librdf get_arcs_out). All possibilities are allowed, except for no-#f, all-#f and #f foo #f.
(fold-nodes proc    
  init    
  model    
  subject    
  predicate    
  object) → any
  proc : (-> (or/c uri? literal? blank-node? list?) any/c any)
  init : any/c
  model : model?
  subject : (or/c node? uri? string? false/c)
  predicate : (or/c node? uri? string? false/c (symbols 'a))
  object : (or/c node? uri? string? literal? false/c)
Basic node iterator, similar to fold-nodes/node, but with scheme objects as the arguments to the fold procedure, rather than nodes.
(map-nodes proc    
  model    
  subject    
  predicate    
  object) → list?
  proc : (-> (or/c uri? literal? blank-node?) any)
  model : model?
  subject : (or/c node? uri? string? false/c)
  predicate : (or/c node? uri? string? false/c (symbols 'a))
  object : (or/c node? uri? string? literal? false/c)
Apply the procedure to each of the nodes returned from the specification of (s, p, o). The (s, p, o) may be as documented in fold-nodes/node.
(map-nodes/node proc    
  model    
  subject    
  predicate    
  object) → list?
  proc : (-> node? any)
  model : model?
  subject : (or/c node? uri? string? false/c)
  predicate : (or/c node? uri? string? false/c (symbols 'a))
  object : (or/c node? uri? string? literal? false/c)
Apply the procedure to each of the nodes returned from the specification of (s, p, o). The (s, p, o) may be as documented in fold-nodes/node.
(find-node/node model    
  subject    
  predicate    
  object) → (or/c node? false/c)
  model : model?
  subject : (or/c node? uri? string? false/c)
  predicate : (or/c node? uri? string? false/c (symbols 'a))
  object : (or/c node? uri? string? literal? false/c)
Return the first node which matches the subject/predicate/object specification.
(find-node model subject predicate object)
 → (or/c uri? string? literal? list? false/c)
  model : model?
  subject : (or/c node? uri? string? false/c)
  predicate : (or/c node? uri? string? false/c (symbols 'a))
  object : (or/c node? uri? string? literal? false/c)
Return the first node which matches the subject/predicate/object specification.
(fold-statements/statements proc    
  init    
  model    
  [subject    
  predicate    
  object]) → any
  proc : (statement/c any/c . -> . any)
  init : any/c
  model : model?
  subject : (or/c node? uri? string? false/c) = #f
  predicate : (or/c node? uri? string? false/c (symbols 'a))
   = #f
  object : (or/c node? uri? string? literal? false/c) = #f
Acts similarly to find-nodes/fold, but acting on statements.
(fold-statements proc    
  init    
  model    
  [subject    
  predicate    
  object]) → any
  proc : ((or/c uri? blank-node?) uri? (or/c uri? blank-node? literal? list?) any/c . -> . any)
  init : any/c
  model : model?
  subject : (or/c node? uri? string? false/c) = #f
  predicate : (or/c node? uri? string? false/c (symbols 'a))
   = #f
  object : (or/c node? uri? string? literal? false/c) = #f
Acts similarly to fold-statements/statements, but acting on on the broken-down parts of statements, rather than the statement itself.
(fold-statements/nodes proc    
  init    
  model    
  [subject    
  predicate    
  object]) → any
  proc : (node? node? node? any/c . -> . any)
  init : any/c
  model : model?
  subject : (or/c node? uri? string? false/c) = #f
  predicate : (or/c node? uri? string? false/c (symbols 'a))
   = #f
  object : (or/c node? uri? string? literal? false/c) = #f
Acts similarly to fold-statements/statements, but acting on on the parts of statements, as nodes, rather than the statement itself.
(map-statements proc    
  model    
  [subject    
  predicate    
  object]) → list?
  proc : ((or/c uri? blank-node?) uri? (or/c uri? blank-node? literal? list?) . -> . any)
  model : model?
  subject : (or/c node? uri? string? false/c) = #f
  predicate : (or/c node? uri? string? false/c (symbols 'a))
   = #f
  object : (or/c node? uri? string? false/c) = #f
Apply the procedure to each of the matching statements from the model.
(map-statements/nodes proc    
  model    
  [subject    
  predicate    
  object]) → list?
  proc : (node? node? node? . -> . any)
  model : model?
  subject : (or/c node? uri? string? false/c) = #f
  predicate : (or/c node? uri? string? false/c (symbols 'a))
   = #f
  object : (or/c node? uri? string? false/c) = #f
Apply the procedure to each of the matching statements from the model.
(map-statements/statements proc    
  model    
  [subject    
  predicate    
  object]) → list?
  proc : (statement/c . -> . any)
  model : model?
  subject : (or/c node? uri? string? false/c) = #f
  predicate : (or/c node? uri? string? false/c (symbols 'a))
   = #f
  object : (or/c node? uri? string? false/c) = #f
Apply the procedure to each of the matching statements from the model.
(for-each-statement proc    
  model    
  [subject    
  predicate    
  object]) → any
  proc : (statement/c . -> . any)
  model : model?
  subject : (or/c node? uri? string? false/c) = #f
  predicate : (or/c node? uri? string? false/c (symbols 'a))
   = #f
  object : (or/c node? uri? literal? false/c) = #f
Apply the procedure to each of the matching statements from the model.
(query/fold proc init model query) → any
  proc : ((string? . -> . (or/c uri? blank-node? literal? string? list? false/c)) any/c . -> . any)
  init : any/c
  model : model?
  query : string?
Run the query over the model, and apply proc to each of the query results. proc must match (procedure? any -> any): the procedure it is passed matches (string -> various) ; in this latter procedure, the argument is one of the bindings in the query, and the value is the uri/blank-node/etc bound to that (rdf:List is available as a scheme list).

Throws an error if the query is not a SELECT query.
(query/model model query) → model?
  model : model?
  query : string?
Query a model with a CONSTRUCT query, returning the result.
(query/ask model query) → boolean?
  model : model?
  query : string?
Query a model with a ASK query, returning the result.

4 Other functions

4.1 URIs

(new-uri uri) → uri?
  uri : (or/c uri? string? node?)
Creates a new uri (as a copy, if the argument is a URI).
(new-uri/resolve uri base) → uri?
  uri : (or/c uri? string? node?)
  base : (or/c uri? string? node?)
Creates a new uri with the base URI as a base-uri.
(new-uri/base uri base) → uri?
  uri : (or/c uri? string? node?)
  base : uri?
DEPRECATED Creates a new uri with the base URI as a base-uri.
(new-uri/rebase uri new-base old-base) → uri?
  uri : (or/c uri? string? node?)
  new-base : uri?
  old-base : uri?
Creates a new uri with the given new-base, after stripping off old-base (note that librdf isn’t terribly sophisticated about normalising the resulting URLs – it’s basically just string concatenation).
(new-uri/file filename) → uri?
  filename : (or/c string? path?)
Easily constructs a file:// URI.
(uri? v) → boolean?
  v : any/c
Returns #t if v is a URI created by new-uri or friends, and #f otherwise
(uri=? uri1 uri2) → boolean?
  uri1 : uri?
  uri2 : uri?
Returns #t if the two URIs should be considered equal (this isn’t terribly sophisticated, and is basically just string equality).
(uri<? uri1 uri2) → boolean?
  uri1 : uri?
  uri2 : uri?
Returns #t if uri1 should be sorted before uri2, based on the URI’s string value.

4.2 Miscellaneous

(thing->string thing) → string?
  thing : any/c
Turns any librdf object into a string (useful for tracing/logging/chatter).
(thing->debugging-string thing) → string?
  thing : any/c
Turns any librdf object into an unambiguous string (useful for debugging/testing, mostly).
(uri-in-namespace prefix extra) → (or/c uri? false/c)
  prefix : symbol?
  extra : (or/c string? false/c)
A convenience function. Given a ’well-known’ prefix expressed as a symbol, return a new URI with the corresponding namespace as a base, and the local-part tagged on the end. The currently `well-known’ prefixes are "'rdf", "'rdfs", "'skos", "'dcterms", "'foaf", "'xsd", "'owl", "'sioc", "'sioc-access" and "'sioc-types". Return #f if the symbol isn’t as ’well-known’ as all that.
(version-information [key]) → any
  key : symbol? = #f
With no argument, return a list of possible keys. With a symbol argument, return the corresponding version information.