sparql-client 0.0.1 → 0.0.2

data/README

@@ -8,43 +8,62 @@ This is a pure-Ruby implementation of a [SPARQL][] client for [RDF.rb][].
 Features
 --------
 
-* Queries SPARQL HTTP endpoints.
+* Executes queries against any SPARQL 1.0-compatible endpoints over HTTP.
+* Provides a query builder [DSL][] for `ASK`, `SELECT`, `DESCRIBE` and
+  `CONSTRUCT` queries.
+* Supports tuple result sets in both XML and JSON formats, with JSON being
+  the preferred default for content negotiation purposes.
+* Supports graph results in any RDF serialization format understood by RDF.rb.
+* Returns results using the [RDF.rb object model][RDF.rb model].
+* Supports accessing endpoints as read-only [`RDF::Repository`][RDF::Repository]
+  instances.
 
 Examples
 --------
 
     require 'sparql/client'
     
-    sparql = SPARQL::Client.new('http://dbpedia.org/sparql')
+    sparql = SPARQL::Client.new("http://dbpedia.org/sparql")
 
-### Executing a boolean query
+### Executing a boolean query and outputting the result
 
-    result = sparql.query('ASK WHERE { ?s ?p ?o }')
+    # ASK WHERE { ?s ?p ?o }
+    result = sparql.ask.whether([:s, :p, :o]).true?
     
     puts result.inspect   #=> true or false
 
-### Executing a tuple query
+### Executing a tuple query and iterating over the returned solutions
 
-    result = sparql.query('SELECT * WHERE { ?s ?p ?o } LIMIT 10')
+    # SELECT * WHERE { ?s ?p ?o } OFFSET 100 LIMIT 10
+    query = sparql.select.where([:s, :p, :o]).offset(100).limit(10)
     
-    result.each do |bindings|
-      puts bindings.inspect
+    query.each_solution do |solution|
+      puts solution.inspect
     end
 
-### Executing a graph query
+### Executing a graph query and iterating over the returned statements
 
-    result = sparql.query('CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o } LIMIT 10')
+    # CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o } LIMIT 10
+    query = sparql.construct([:s, :p, :o]).where([:s, :p, :o]).limit(10)
     
-    result.each_statement do |statement|
+    query.each_statement do |statement|
       puts statement.inspect
     end
 
+### Executing an arbitrary textual SPARQL query string
+
+    result = sparql.query("ASK WHERE { ?s ?p ?o }")
+    
+    puts result.inspect   #=> true or false
+
 Documentation
 -------------
 
-<http://sparql.rubyforge.org/>
+<http://sparql.rubyforge.org/client/>
 
 * {SPARQL::Client}
+  * {SPARQL::Client::Query}
+  * {SPARQL::Client::Repository}
 
 Dependencies
 ------------
@@ -75,7 +94,7 @@ as follows:
 Resources
 ---------
 
-* <http://sparql.rubyforge.org/>
+* <http://sparql.rubyforge.org/client/>
 * <http://github.com/bendiken/sparql-client>
 * <http://rubygems.org/gems/sparql-client>
 * <http://rubyforge.org/projects/sparql/>
@@ -94,6 +113,11 @@ License
 `SPARQL::Client` is free and unencumbered public domain software. For more
 information, see <http://unlicense.org/> or the accompanying UNLICENSE file.
 
-[RDF]:      http://www.w3.org/RDF/
-[SPARQL]:   http://en.wikipedia.org/wiki/SPARQL
-[RDF.rb]:   http://rdf.rubyforge.org/
+[RDF]:             http://www.w3.org/RDF/
+[SPARQL]:          http://en.wikipedia.org/wiki/SPARQL
+[SPARQL JSON]:     http://www.w3.org/TR/rdf-sparql-json-res/
+[RDF.rb]:          http://rdf.rubyforge.org/
+[RDF.rb model]:    http://blog.datagraph.org/2010/03/rdf-for-ruby
+[RDF::Repository]: http://rdf.rubyforge.org/RDF/Repository.html
+[DSL]:             http://en.wikipedia.org/wiki/Domain-specific_language
+                   "domain-specific language"

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.0.2

data/lib/sparql.rb

@@ -1 +1,3 @@
-require 'sparql/client'
+module SPARQL
+  autoload :Client, 'sparql/client'
+end

data/lib/sparql/client.rb

@@ -1,12 +1,19 @@
 require 'net/http'
 require 'rdf'
 require 'rdf/ntriples'
-require 'sparql/version'
 
 module SPARQL
   ##
   # A SPARQL client for RDF.rb.
   class Client
+    autoload :Query,      'sparql/client/query'
+    autoload :Repository, 'sparql/client/repository'
+    autoload :VERSION,    'sparql/client/version'
+
+    class ClientError < StandardError; end
+    class MalformedQuery < ClientError; end
+    class ServerError < StandardError; end
+
     RESULT_BOOL = 'text/boolean'.freeze # Sesame-specific
     RESULT_JSON = 'application/sparql-results+json'.freeze
     RESULT_XML  = 'application/sparql-results+xml'.freeze
@@ -21,7 +28,7 @@ module SPARQL
     # @param  [Hash{Symbol => Object}] options
     def initialize(url, options = {}, &block)
       @url, @options = RDF::URI.new(url.to_s), options
-      @headers = {'Accept' => "#{RESULT_XML}, #{RESULT_JSON}, text/plain"}
+      @headers = {'Accept' => "#{RESULT_JSON}, #{RESULT_XML}, text/plain"}
 
       if block_given?
         case block.arity
@@ -31,19 +38,63 @@ module SPARQL
       end
     end
 
+    ##
+    # Executes a boolean `ASK` query.
+    #
+    # @return [Query]
+    def ask(*args)
+      client = self
+      result = Query.ask(*args)
+      (class << result; self; end).send(:define_method, :execute) do
+        client.query(self)
+      end
+      result
+    end
+
+    ##
+    # Executes a tuple `SELECT` query.
+    #
+    # @param  [Array<Symbol>] variables
+    # @return [Query]
+    def select(*args)
+      client = self
+      result = Query.select(*args)
+      (class << result; self; end).send(:define_method, :execute) do
+        client.query(self)
+      end
+      result
+    end
+
+    ##
+    # Executes a graph `CONSTRUCT` query.
+    #
+    # @param  [Array<Symbol>] pattern
+    # @return [Query]
+    def construct(*args)
+      client = self
+      result = Query.construct(*args)
+      (class << result; self; end).send(:define_method, :execute) do
+        client.query(self)
+      end
+      result
+    end
+
     ##
     # Executes a SPARQL query.
     #
     # @param  [String, #to_s]          url
     # @param  [Hash{Symbol => Object}] options
+    # @return [Array<RDF::Query::Solution>]
     def query(query, options = {})
-      get(query.to_s) do |response|
+      get(query) do |response|
         case response
-          when Net::HTTPClientError
-            abort response.inspect # FIXME
-          when Net::HTTPServerError
-            abort response.inspect # FIXME
-          when Net::HTTPSuccess
+          when Net::HTTPBadRequest  # 400 Bad Request
+            raise MalformedQuery.new(response.body)
+          when Net::HTTPClientError # 4xx
+            raise ClientError.new(response.body)
+          when Net::HTTPServerError # 5xx
+            raise ServerError.new(response.body)
+          when Net::HTTPSuccess     # 2xx
             parse_response(response)
         end
       end
@@ -79,7 +130,7 @@ module SPARQL
         when json['results']
           json['results']['bindings'].map do |row|
             row = row.inject({}) do |cols, (name, value)|
-              cols.merge(name => parse_json_value(value))
+              cols.merge(name.to_sym => parse_json_value(value))
             end
             RDF::Query::Solution.new(row)
           end

data/lib/sparql/client/query.rb

@@ -0,0 +1,267 @@
+module SPARQL; class Client
+  ##
+  # A SPARQL query builder.
+  #
+  # @example Iterating over all found solutions
+  #   query.each_solution { |solution| puts solution.inspect }
+  #
+  class Query < RDF::Query
+    ##
+    # @return [Symbol]
+    # @see    http://www.w3.org/TR/rdf-sparql-query/#QueryForms
+    attr_reader :form
+
+    ##
+    # @return [Hash{Symbol => Object}]
+    attr_reader :options
+
+    ##
+    # Creates a boolean `ASK` query.
+    #
+    # @param  [Hash{Symbol => Object}] options
+    # @return [Query]
+    # @see    http://www.w3.org/TR/rdf-sparql-query/#ask
+    def self.ask(options = {})
+      self.new(:ask, options)
+    end
+
+    ##
+    # Creates a tuple `SELECT` query.
+    #
+    # @param  [Array<Symbol>]          variables
+    # @param  [Hash{Symbol => Object}] options
+    # @return [Query]
+    # @see    http://www.w3.org/TR/rdf-sparql-query/#select
+    def self.select(*variables)
+      options = variables.last.is_a?(Hash) ? variables.pop : {}
+      self.new(:select, options).select(*variables) # FIXME
+    end
+
+    ##
+    # Creates a graph `CONSTRUCT` query.
+    #
+    # @param  [Array<RDF::Query::Pattern, Array>] patterns
+    # @param  [Hash{Symbol => Object}]            options
+    # @return [Query]
+    # @see    http://www.w3.org/TR/rdf-sparql-query/#construct
+    def self.construct(*patterns)
+      options = patterns.last.is_a?(Hash) ? patterns.pop : {}
+      self.new(:construct, options).construct(*patterns) # FIXME
+    end
+
+    ##
+    # @param  [Symbol, #to_s]          form
+    # @param  [Hash{Symbol => Object}] options
+    # @yield  [query]
+    # @yieldparam [Query]
+    def initialize(form = :ask, options = {}, &block)
+      @form = form.respond_to?(:to_sym) ? form.to_sym : form.to_s.to_sym
+      super(options.dup, &block)
+    end
+
+    ##
+    # @return [Query]
+    # @see    http://www.w3.org/TR/rdf-sparql-query/#ask
+    def ask
+      @form = :ask
+      self
+    end
+
+    ##
+    # @param  [Array<Symbol>] variables
+    # @param  [Hash{Symbol => Object}] options
+    # @return [Query]
+    # @see    http://www.w3.org/TR/rdf-sparql-query/#select
+    def select(*variables)
+      @form = :select
+      options = variables.last.is_a?(Hash) ? variables.pop : {}
+      @variables = variables.inject({}) do |vars, var|
+        vars.merge(var.to_sym => RDF::Query::Variable.new(var))
+      end
+      self
+    end
+
+    ##
+    # @param  [Array<RDF::Query::Pattern, Array>] patterns
+    # @return [Query]
+    def construct(*patterns)
+      options[:template] = patterns.map do |pattern|
+        case pattern
+          when RDF::Query::Pattern then pattern
+          else RDF::Query::Pattern.new(*pattern.to_a)
+        end
+      end
+      self
+    end
+
+    ##
+    # @param  [Array<RDF::Query::Pattern, Array>] patterns
+    # @return [Query]
+    # @see    http://www.w3.org/TR/rdf-sparql-query/#GraphPattern
+    def where(*patterns)
+      @patterns += patterns.map do |pattern|
+        case pattern
+          when RDF::Query::Pattern then pattern
+          else RDF::Query::Pattern.new(*pattern.to_a)
+        end
+      end
+      self
+    end
+
+    alias_method :whether, :where
+
+    ##
+    # @param  [Array<Symbol>] variables
+    # @return [Query]
+    # @see    http://www.w3.org/TR/rdf-sparql-query/#modOrderBy
+    def order(*variables)
+      options[:order_by] = variables
+      self
+    end
+
+    alias_method :order_by, :order
+
+    ##
+    # @return [Query]
+    # @see    http://www.w3.org/TR/rdf-sparql-query/#modDistinct
+    def distinct(state = true)
+      options[:distinct] = state
+      self
+    end
+
+    ##
+    # @return [Query]
+    # @see    http://www.w3.org/TR/rdf-sparql-query/#modReduced
+    def reduced(state = true)
+      options[:reduced] = state
+      self
+    end
+
+    ##
+    # @param  [Integer, #to_i] start
+    # @return [Query]
+    # @see    http://www.w3.org/TR/rdf-sparql-query/#modOffset
+    def offset(start)
+      slice(start, nil)
+    end
+
+    ##
+    # @param  [Integer, #to_i] length
+    # @return [Query]
+    # @see    http://www.w3.org/TR/rdf-sparql-query/#modResultLimit
+    def limit(length)
+      slice(nil, length)
+    end
+
+    ##
+    # @param  [Integer, #to_i] start
+    # @param  [Integer, #to_i] length
+    # @return [Query]
+    def slice(start, length)
+      options[:offset] = start.to_i if start
+      options[:limit] = length.to_i if length
+      self
+    end
+
+    ##
+    # @private
+    def filter(string)
+      (options[:filters] ||= []) << string
+      self
+    end
+
+    ##
+    # @return [Boolean]
+    def true?
+      case result
+        when TrueClass, FalseClass then result
+        when Enumerable then !result.empty?
+        else false
+      end
+    end
+
+    ##
+    # @return [Boolean]
+    def false?
+      !true?
+    end
+
+    ##
+    # @return [Enumerable<RDF::Query::Solution>]
+    def solutions
+      result
+    end
+
+    ##
+    # @yield  [statement]
+    # @yieldparam [RDF::Statement]
+    # @return [Enumerator]
+    def each_statement(&block)
+      result.each_statement(&block)
+    end
+
+    ##
+    # @return [Object]
+    def result
+      @result ||= execute
+    end
+
+    ##
+    # @return [Object]
+    def execute
+      raise NotImplementedError
+    end
+
+    ##
+    # Returns the string representation of this query.
+    #
+    # @return [String]
+    def to_s
+      buffer = [form.to_s.upcase]
+      case form
+        when :select
+          buffer << 'DISTINCT' if options[:distinct]
+          buffer << 'REDUCED'  if options[:reduced]
+          buffer << (variables.empty? ? '*' : variables.values.map(&:to_s).join(' '))
+        when :construct
+          buffer << '{'
+          buffer += options[:template].map(&:to_s)
+          buffer << '}'
+      end
+
+      buffer << 'WHERE {'
+      buffer += patterns.map(&:to_s)
+      if options[:filters]
+        buffer += options[:filters].map { |filter| "FILTER(#{filter})" }
+      end
+      buffer << '}'
+
+      if options[:order_by]
+        buffer << 'ORDER BY'
+        buffer += options[:order_by].map { |var| "?#{var}" }
+      end
+
+      buffer << "OFFSET #{options[:offset]}" if options[:offset]
+      buffer << "LIMIT #{options[:limit]}"   if options[:limit]
+
+      buffer.join(' ')
+    end
+
+    ##
+    # Outputs a developer-friendly representation of this query to `stderr`.
+    #
+    # @return [void]
+    def inspect!
+      warn(inspect)
+      self
+    end
+
+    ##
+    # Returns a developer-friendly representation of this query.
+    #
+    # @return [String]
+    def inspect
+      sprintf("#<%s:%#0x(%s)>", self.class.name, __id__, to_s)
+    end
+  end
+end; end

data/lib/sparql/client/repository.rb

@@ -0,0 +1,170 @@
+module SPARQL; class Client
+  ##
+  # A read-only repository view of a SPARQL endpoint.
+  #
+  # @see RDF::Repository
+  class Repository < ::RDF::Repository
+    # @return [SPARQL::Client]
+    attr_reader :client
+
+    ##
+    # @param  [String, #to_s]          endpoint
+    # @param  [Hash{Symbol => Object}] options
+    def initialize(endpoint, options = {})
+      @options = options.dup
+      @client  = SPARQL::Client.new(endpoint, options)
+    end
+
+    ##
+    # Enumerates each RDF statement in this repository.
+    #
+    # @yield  [statement]
+    # @yieldparam [RDF::Statement] statement
+    # @return [Enumerator]
+    # @see    RDF::Repository#each
+    def each(&block)
+      unless block_given?
+        require 'enumerator' unless defined?(::Enumerable::Enumerator)
+        ::Enumerable::Enumerator.new(self, :each)
+      else
+        client.construct([:s, :p, :o]).where([:s, :p, :o]).each_statement(&block)
+      end
+    end
+
+    ##
+    # Returns `true` if this repository contains the given subject.
+    #
+    # @param  [RDF::Resource]
+    # @return [Boolean]
+    # @see    RDF::Repository#has_subject?
+    def has_subject?(subject)
+      client.ask.whether([subject, :p, :o]).true?
+    end
+
+    ##
+    # Returns `true` if this repository contains the given predicate.
+    #
+    # @param  [RDF::URI]
+    # @return [Boolean]
+    # @see    RDF::Repository#has_predicate?
+    def has_predicate?(predicate)
+      client.ask.whether([:s, predicate, :o]).true?
+    end
+
+    ##
+    # Returns `true` if this repository contains the given object.
+    #
+    # @param  [RDF::Value]
+    # @return [Boolean]
+    # @see    RDF::Repository#has_object?
+    def has_object?(object)
+      client.ask.whether([:s, :p, object]).true?
+    end
+
+    ##
+    # Iterates over each subject in this repository.
+    #
+    # @yield  [subject]
+    # @yieldparam [RDF::Resource] subject
+    # @return [Enumerator]
+    # @see    RDF::Repository#each_subject?
+    def each_subject(&block)
+      unless block_given?
+        require 'enumerator' unless defined?(::Enumerable::Enumerator)
+        ::Enumerable::Enumerator.new(self, :each_subject)
+      else
+        client.select(:s, :distinct => true).where([:s, :p, :o]).each { |solution| block.call(solution[:s]) }
+      end
+    end
+
+    ##
+    # Iterates over each predicate in this repository.
+    #
+    # @yield  [predicate]
+    # @yieldparam [RDF::URI] predicate
+    # @return [Enumerator]
+    # @see    RDF::Repository#each_predicate?
+    def each_predicate(&block)
+      unless block_given?
+        require 'enumerator' unless defined?(::Enumerable::Enumerator)
+        ::Enumerable::Enumerator.new(self, :each_predicate)
+      else
+        client.select(:p, :distinct => true).where([:s, :p, :o]).each { |solution| block.call(solution[:p]) }
+      end
+    end
+
+    ##
+    # Iterates over each object in this repository.
+    #
+    # @yield  [object]
+    # @yieldparam [RDF::Value] object
+    # @return [Enumerator]
+    # @see    RDF::Repository#each_object?
+    def each_object(&block)
+      unless block_given?
+        require 'enumerator' unless defined?(::Enumerable::Enumerator)
+        ::Enumerable::Enumerator.new(self, :each_object)
+      else
+        client.select(:o, :distinct => true).where([:s, :p, :o]).each { |solution| block.call(solution[:o]) }
+      end
+    end
+
+    ##
+    # Returns `true` if this repository contains the given `triple`.
+    #
+    # @param  [Array<RDF::Resource, RDF::URI, RDF::Value>] triple
+    # @return [Boolean]
+    # @see    RDF::Repository#has_triple?
+    def has_triple?(triple)
+      client.ask.whether(triple.to_a[0...3]).true?
+    end
+
+    ##
+    # Returns `true` if this repository contains the given `statement`.
+    #
+    # @param  [RDF::Statement] statement
+    # @return [Boolean]
+    # @see    RDF::Repository#has_statement?
+    def has_statement?(statement)
+      has_triple?(statement.to_triple)
+    end
+
+    ##
+    # Returns the number of statements in this repository.
+    #
+    # @return [Integer]
+    # @see    RDF::Repository#count?
+    def count
+      begin
+        binding = client.query("SELECT COUNT(*) WHERE { ?s ?p ?o }").first.to_hash
+        binding[binding.keys.first].value.to_i
+      rescue SPARQL::Client::MalformedQuery => e
+        # SPARQL 1.0 does not include support for aggregate functions:
+        count = 0
+        each_statement { count += 1 } # TODO: optimize this
+        count
+      end
+    end
+
+    alias_method :size,   :count
+    alias_method :length, :count
+
+    ##
+    # Returns `true` if this repository contains no statements.
+    #
+    # @return [Boolean]
+    # @see    RDF::Repository#empty?
+    def empty?
+      client.ask.whether([:s, :p, :o]).false?
+    end
+
+    ##
+    # Returns `false` to indicate that this is a read-only repository.
+    #
+    # @return [Boolean]
+    # @see    RDF::Mutable#mutable?
+    def writable?
+      false
+    end
+  end
+end; end

data/lib/sparql/{version.rb → client/version.rb}

@@ -2,7 +2,7 @@ module SPARQL; class Client
   module VERSION
     MAJOR = 0
     MINOR = 0
-    TINY  = 1
+    TINY  = 2
     EXTRA = nil
 
     STRING = [MAJOR, MINOR, TINY].join('.')

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - Arto Bendiken
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-04-07 00:00:00 +02:00
+date: 2010-04-12 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -28,8 +28,8 @@ dependencies:
         segments: 
         - 0
         - 1
-        - 4
-        version: 0.1.4
+        - 6
+        version: 0.1.6
   type: :development
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
@@ -70,8 +70,8 @@ dependencies:
         segments: 
         - 0
         - 1
-        - 5
-        version: 0.1.5
+        - 6
+        version: 0.1.6
   type: :runtime
   version_requirements: *id004
 - !ruby/object:Gem::Dependency 
@@ -101,8 +101,10 @@ files:
 - README
 - UNLICENSE
 - VERSION
+- lib/sparql/client/query.rb
+- lib/sparql/client/repository.rb
+- lib/sparql/client/version.rb
 - lib/sparql/client.rb
-- lib/sparql/version.rb
 - lib/sparql.rb
 has_rdoc: false
 homepage: http://sparql.rubyforge.org/