search

ruby-rdf / rdf-turtle

Turtle reader/writer for Ruby
http://rubygems.org/gems/rdf-turtle
The Unlicense
31 stars 9 forks source link

readme

RDF::Turtle reader/writer

Turtle reader/writer for RDF.rb .

Gem Version Build Status Coverage Status Gitter chat

Description

This is a Ruby implementation of a Turtle parser for RDF.rb.

Features

RDF::Turtle parses Turtle and N-Triples into statements or triples. It also serializes to Turtle.

Install with gem install rdf-turtle

Usage

Instantiate a reader from a local file:

graph = RDF::Graph.load("etc/doap.ttl", format:  :ttl)

Define @base and @prefix definitions, and use for serialization using :base_uri an :prefixes options.

Canonicalize and validate using :canonicalize and :validate options.

Write a graph to a file:

RDF::Turtle::Writer.open("etc/test.ttl") do |writer|
   writer << graph
end

RDF 1.2

Both reader and writer include provisional support for RDF 1.2 triple terms.

Both reader and writer include provisional support for RDF 1.2 directional language-tagged strings, which are literals of type rdf:dirLangString having both a language and direction.

Internally, an RDF::Statement is treated as another resource, along with RDF::URI and RDF::Node, which allows an RDF::Statement to have a #subject or #object which is also an RDF::Statement.

Note: This feature is subject to change or elimination as the standards process progresses.

Serializing a Graph containing reified triples

require 'rdf/turtle'
triple = RDF::Statement(RDF::URI('bob'), RDF::Vocab::FOAF.age, RDF::Literal(23))
graph = RDF::Graph.new << [RDF::URI('r'), RDF::URI("ex:certainty"), RDF::Literal(0.9)]
graph << RDF::Statement(RDF::URI('r'), RDF.reifies, triple)
graph.dump(:ttl, validate: false, standard_prefixes: true)
# => '<<<bob> foaf:age 23>> <ex:certainty> 9.0e-1 .'

Reading a Graph containing reified triples

By default, the Turtle reader will reject a document containing a subject resource.

ttl = %(
  @prefix foaf: <http://xmlns.com/foaf/0.1/> .
  @prefix ex: <http://example.com/> .
  <<<bob> foaf:age 23>> ex:certainty 9.0e-1 .
)
graph = RDF::Graph.new do |graph|
  RDF::Turtle::Reader.new(ttl) {|reader| graph << reader}
end
# => RDF::ReaderError

Readers support a boolean valued rdfstar option; only one statement is asserted, although the reified statement is contained within the graph.

graph = RDF::Graph.new do |graph|
  RDF::Turtle::Reader.new(ttl, rdfstar: true) {|reader| graph << reader}
end
graph.count #=> 2

Reading a Graph containing statement annotations

Annotations are introduced using the {| ... |} syntax, which is treated like a blankNodePropertyList, where the subject is the the triple ending with that annotation.

ttl = %(
  @prefix foaf: <http://xmlns.com/foaf/0.1/> .
  @prefix ex: <http://example.com/> .
  <bob> foaf:age 23 {| ex:certainty 9.0e-1 |} .
)
graph = RDF::Graph.new do |graph|
  RDF::Turtle::Reader.new(ttl) {|reader| graph << reader}
end
# => RDF::Graph.new do |g|
  triple = RDF::Statement.new(RDF::URI('bob'), RDF::FOAF.age, RDF::Literal(23))
  bn = RDF::Node.new('anno)
  g << triple
  g << RDF::Statement.new(bn, RDF.reifies, triple)
  g << RDF::Statement.new(bn, RDF::URI("http://example.com/certainty"), RDF::Literal.new(9.0e-1))
end

Annotations can also have a reifier identifier

ttl = %(
  @prefix foaf: <http://xmlns.com/foaf/0.1/> .
  @prefix ex: <http://example.com/> .
  <bob> foaf:age 23 ~ ex:anno {| ex:certainty 9.0e-1 |} .
)

Note that this requires the rdfstar option to be set.

Documentation

Full documentation available on Rubydoc.info

Principle Classes

Variations from the spec

In some cases, the specification is unclear on certain issues:

Freebase-specific Reader

There is a special reader useful for processing Freebase Dumps. To invoke this, add the freebase: true option to the {RDF::Turtle::Reader.new}, or use {RDF::Turtle::FreebaseReader} directly. As with {RDF::Turtle::Reader}, prefix definitions may be passed in using the :prefixes option to RDF::Turtle::FreebaseReader} using the standard mechanism defined for RDF::Reader.

The Freebase Dumps have a very normalized form, similar to N-Triples but with prefixes. They also have a large amount of garbage. This Reader is optimized for this format and will perform faster error recovery.

An example of reading Freebase dumps:

require "rdf/turtle"
fb = "../freebase/freebase-rdf-2013-03-03-00-00.ttl"
fb_prefixes = {
  ns:  "http://rdf.freebase.com/ns/",
  key:  "http://rdf.freebase.com/key/",
  owl:  "http://www.w3.org/2002/07/owl#>",
  rdfs:  "http://www.w3.org/2000/01/rdf-schema#",
  rdf:  "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
  xsd:  "http://www.w3.org/2001/XMLSchema#"
}
RDF::Turtle::Reader.open(fb,
  freebase:  true,
  prefixes:  fb_prefixes) do |r|

  r.each_statement {|stmt| puts stmt.to_ntriples}
end

Implementation Notes

This version uses a hand-written parser using the Lexer from the EBNF gem instead of a general EBNF LL(1) parser for faster performance.

Change Log

See Release Notes on GitHub

Dependencies

Installation

The recommended installation method is via RubyGems. To install the latest official release of the RDF::Turtle gem, do:

% [sudo] gem install rdf-turtle

Mailing List

Author

Contributing

This repository uses Git Flow to mange development and release activity. All submissions must be on a feature branch based on the develop branch to ease staging and integration.

License

This is free and unencumbered public domain software. For more information, see https://unlicense.org/ or the accompanying {file:UNLICENSE} file.

A copy of the Turtle EBNF and derived parser files are included in the repository, which are not covered under the UNLICENSE. These files are covered via the W3C Document License.