= Redlander

Redlander is Ruby bindings to Redland library (see http://librdf.org) written in C, which is used to manipulate RDF graphs. This is an alternative implementation of Ruby bindings (as opposed to the official bindings), aiming to be more intuitive, lightweight, high-performing and as bug-free as possible.

= Installing

Installing Redlander is simple:

  $ gem install redlander

Note, that you will have to install Redland runtime library (librdf) for Redlander to work.

= Usage

This README outlines most obvious use cases. For more details please refer to YARD documentation of Redlander.

To start doing anything useful with Redlander, you need to initialize a model first:

  $ m = Redlander::Model.new

This creates a model where all RDF statements are stored in the memory. Depending on the selected storage you may need to supply extra parameters like :user or :password. Look-up the options for Model.initialize for the list of available options.
Naturally, you don't need to create a model if you just want to play around with independent statements, nodes and the like.

== RDF Statements

Now that you have created a model, you can access its RDF statements:

  $ m.statements

Most of Redlander functionality is accessable via these statements. The API is almost identical to ActiveRecord:

  $ s = URI.parse('http://example.com/concepts#subject')
  $ p = URI.parse('http://example.com/concepts#label')
  $ o = "subject!"
  $ m.statements.create(:subject => s, :predicate => p, :object => o)

  $ m.statements.empty?  # => false

  $ st = Redlander::Statement.new(:subject => s, :predicate => p, :object => "another label")
  $ m.statements.add(st)

  $ m.statements.size    # => 2

  $ m.statements.each { |st| puts st }

Finding statements:

  $ m.statements.find(:first, :object => "subject!")
  $ m.statements.all(:object => "another label")
  $ m.statements.each(:object => "subject!") { |statement|
      puts statement.subject
    }

Note that "m.statements.each" is "lazy", while "m.statements.all" (and other finders) is not.

You can access the subject, predicate or object of a statement:

  $ m.statements.first.subject  # => (Redlander::Node)

Please refer to Redlander::Node API doc for details.

You can also use different query languages supported by librdf ("SPARQL 1.0" being a default):

  $ m.query("SELECT ?s ?p ?o WHERE {}")  # => [{"s" => ..., "p" => ..., "o" => ...}, ...]

"ASK" queries return true/false, "SELECT" queries return arrays of binding hashes,
"CONSTRUCT" queries return an instance of a new memory-based model comprised from
the statements constructed by the query.
You can also supply a block to Model#query, which is ignored by ASK queries, but
yields the statements constructed by CONSTRUCT queries and yields the binding
hash for SELECT queries. Binding hash values are instances of Redlander::Node.

For query options and available query languages refer to Model#query documentation.


== Parsing Input

You can fill your model with statements by parsing some external sources like plain or streamed data.

  $ data = File.read("data.xml")
  $ m.from(data, :format => "rdfxml")

If the input is too large, you may prefer streaming it:

  $ source = URI("http://example.com/data.nt")
  $ m.from(source, :format => "ntriples")

If you want to get the data from a local file, you can use "file://" schema for your URI
or use "from_file" method with a local file name (without schema):

  $ m.from_file("../data.ttl", :format => "turtle")

Most frequently used parsing methods are aliased to save you some typing:
"from_rdfxml", "from_ntriples", "from_turtle", "from_uri/from_file".

Finally, you can filter the parsed input to prevent certain statements from getting into your model:

  $ m.from_turtle(data) do |statement|
      statement.object.value == "good"
    end

If the block returns "false", the statement will not be added to the model.
The above example will add only statements having "literal" objects with a value of "good".

== Serializing Model

Naturally, you can convert your model into a portable syntax:

  $ m.to(:format => "rdfxml") # => RDF/XML output

There are aliases as well: "to_rdfxml", "to_dot", etc.

You can also dump the output directly into a local file:

  $ m.to_file("data.nt", :format => "ntriples")

== Transactions

It is possible to wrap all changes you perform on a model in a transaction,
if transactions are supported by the backend storage. If they are not supported,
all changes will be instantaneous.

  $ m.transaction { m.statements.delete_all }

There are also dedicated methods to start, commit and rollback a transaction,
should you not be able to explicitly wrap your changes in a block:

  $ m.transaction_start
  $ m.delete_all
  $ if lucky?
      m.transaction_commit
    else
      m.transaction_rollback
    end

All the above methods have their "banged" counterparts ("transaction_start!",
"transaction_commit!" and "transaction_rollback!") that would raise RedlandError
in case of an error.


= Exceptions

If anything unexpected happens, Redlander raises RedlandError.

= Authors and Contributors

Slava Kravchenko <https://github.com/cordawyn>

= Thanks

Thanks goes to Dave Beckett, the creator of Redland!