sparql-client 0.3.2 → 0.3.3

data/AUTHORS

@@ -1,2 +1,3 @@
-* Arto Bendiken <arto.bendiken@gmail.com>
+* Arto Bendiken <arto@bendiken.net>
 * Ben Lavender <blavender@gmail.com>
+* Gregg Kellogg <gregg@greggkellogg.net>

data/CREDITS

@@ -5,5 +5,5 @@
 * Fumihiro Kato <fumi@fumi.me>
 * David Nielsen <david@graveyard.dk>
 * Thamaraiselvan Poomalai <p.thamarai@gmail.com>
-* Gregg Kellogg <gregg@greggkellogg.net>
 * Michael Sokol <mikaa123@gmail.com>
+* Yves Raimond <yves.raimond@bbc.co.uk>

data/README

@@ -7,11 +7,12 @@ This is a [Ruby][] implementation of a [SPARQL][] client for [RDF.rb][].
 
 ##Features
 
-* Executes queries against any SPARQL 1.0-compatible endpoints over HTTP.
+* Executes queries against any SPARQL 1.0-compatible endpoint over HTTP.
 * Provides a query builder [DSL][] for `ASK`, `SELECT`, `DESCRIBE` and
   `CONSTRUCT` queries.
+* Includes preliminary support for some SPARQL 1.1 Update operations.
 * Supports tuple result sets in both XML and JSON formats, with JSON being
-  the preferred default for content negotiation purposes.
+  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]
@@ -56,8 +57,6 @@ This is a [Ruby][] implementation of a [SPARQL][] client for [RDF.rb][].
 
 ##Documentation
 
-<http://sparql.rubyforge.org/client/>
-
 * {SPARQL::Client}
   * {SPARQL::Client::Query}
   * {SPARQL::Client::Repository}
@@ -65,8 +64,9 @@ This is a [Ruby][] implementation of a [SPARQL][] client for [RDF.rb][].
 ##Dependencies
 
 * [Ruby](http://ruby-lang.org/) (>= 1.8.7) or (>= 1.8.1 with [Backports][])
-* [RDF.rb](http://rubygems.org/gems/rdf) (>= 0.3.0)
-* [JSON](http://rubygems.org/gems/json_pure) (>= 1.4.2)
+* [RDF.rb](http://rubygems.org/gems/rdf) (>= 0.3.5)
+* [Net::HTTP::Persistent](http://rubygems.org/gems/net-http-persistent) (>= 1.4.1)
+* [JSON](http://rubygems.org/gems/json_pure) (>= 1.4.6)
 
 ##Installation
 
@@ -79,12 +79,12 @@ To install the latest official release of the `SPARQL::Client` gem, do:
 
 To get a local working copy of the development repository, do:
 
-    % git clone git://github.com/bendiken/sparql-client.git
+    % git clone git://github.com/ruby-rdf/sparql-client.git
 
 Alternatively, download the latest development version as a tarball as
 follows:
 
-    % wget http://github.com/bendiken/sparql-client/tarball/master
+    % wget http://github.com/ruby-rdf/sparql-client/tarball/master
 
 ##Mailing List
 
@@ -94,6 +94,7 @@ follows:
 
 * [Arto Bendiken](http://github.com/bendiken) - <http://ar.to/>
 * [Ben Lavender](http://github.com/bhuga) - <http://bhuga.net/>
+* [Gregg Kellogg](http://github.com/gkellogg) - <http://kellogg-assoc.com/>
 
 ##Contributors
 
@@ -104,7 +105,6 @@ follows:
 * [Fumihiro Kato](http://github.com/fumi) - <http://fumi.me/>
 * [David Nielsen](http://github.com/drankard) - <http://github.com/drankard>
 * [Thamaraiselvan Poomalai](http://github.com/selvan) - <http://softonaut.blogspot.com/>
-* [Gregg Kellogg](http://github.com/gkellogg) - <http://kellogg-assoc.com/>
 * [Michael Sokol](http://github.com/mikaa123) - <http://sokolmichael.com/>
 * [Yves Raimond](http://github.com/moustaki) - <http://moustaki.org/>
 
@@ -124,8 +124,8 @@ follows:
 
 ##Resources
 
-* <http://sparql.rubyforge.org/client/>
-* <http://github.com/bendiken/sparql-client>
+* <http://ruby-rdf.github.com/sparql-client/>
+* <http://github.com/ruby-rdf/sparql-client>
 * <http://rubygems.org/gems/sparql-client>
 * <http://rubyforge.org/projects/sparql/>
 * <http://raa.ruby-lang.org/project/sparql-client/>

data/VERSION

@@ -1 +1 @@
-0.3.2
+0.3.3

data/lib/sparql/client.rb

@@ -1,13 +1,13 @@
-require 'net/http/persistent'
-require 'rdf' # @see http://rubygems.org/gems/rdf
-require 'rdf/ntriples'
+require 'net/http/persistent' # @see http://rubygems.org/gems/net-http-persistent
+require 'rdf'                 # @see http://rubygems.org/gems/rdf
+require 'rdf/ntriples'        # @see http://rubygems.org/gems/rdf
 
 module SPARQL
   ##
   # A SPARQL client for RDF.rb.
   #
-  # @see http://www.w3.org/TR/rdf-sparql-protocol/
-  # @see http://www.w3.org/TR/rdf-sparql-json-res/
+  # @see http://www.w3.org/TR/sparql11-query/
+  # @see http://www.w3.org/TR/sparql11-results-json/
   class Client
     autoload :Query,      'sparql/client/query'
     autoload :Repository, 'sparql/client/repository'
@@ -17,25 +17,33 @@ module SPARQL
     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
+    RESULT_BOOL = 'text/boolean'.freeze                           # Sesame-specific
+    RESULT_BRTR = 'application/x-binary-rdf-results-table'.freeze # Sesame-specific
     ACCEPT_JSON = {'Accept' => RESULT_JSON}.freeze
     ACCEPT_XML  = {'Accept' => RESULT_XML}.freeze
+    ACCEPT_BRTR = {'Accept' => RESULT_BRTR}.freeze
 
+    # @return [RDF::URI]
     attr_reader :url
+
+    # @return [Hash{String => String}]
+    attr_reader :headers
+
+    # @return [Hash{Symbol => Object}]
     attr_reader :options
 
     ##
     # @param  [String, #to_s]          url
     # @param  [Hash{Symbol => Object}] options
+    # @option options [Symbol] :method (:post)
     # @option options [Hash] :headers
     def initialize(url, options = {}, &block)
-      @url, @options = RDF::URI.new(url.to_s), options
-      #@headers = {'Accept' => "#{RESULT_JSON}, #{RESULT_XML}, text/plain"}
+      @url, @options = RDF::URI.new(url.to_s), options.dup
       @headers = {
         'Accept' => [RESULT_JSON, RESULT_XML, RDF::Format.content_types.keys.map(&:to_s)].join(', ')
-      }.merge @options[:headers] || {}
+      }.merge(@options.delete(:headers) || {})
       @http = http_klass(@url.scheme)
 
       if block_given?
@@ -81,6 +89,128 @@ module SPARQL
       call_query_method(:construct, *args)
     end
 
+    ##
+    # Executes an `INSERT DATA` operation.
+    #
+    # This requires that the endpoint support SPARQL 1.1 Update.
+    #
+    # Note that for inserting non-trivial amounts of data, you probably
+    # ought to consider using the RDF store's native bulk-loading facilities
+    # or APIs, as `INSERT DATA` operations entail comparably higher
+    # parsing overhead.
+    #
+    # @example Inserting data constructed ad-hoc
+    #   client.insert_data(RDF::Graph.new { |graph|
+    #     graph << [:jhacker, RDF::FOAF.name, "J. Random Hacker"]
+    #   })
+    #
+    # @example Inserting data sourced from a file or URL
+    #   data = RDF::Graph.load("http://rdf.rubyforge.org/doap.nt")
+    #   client.insert_data(data)
+    #
+    # @example Inserting data into a named graph
+    #   client.insert_data(data, :graph => "http://example.org/")
+    #
+    # @param  [RDF::Graph] data
+    # @param  [Hash{Symbol => Object}] options
+    # @option options [RDF::URI, String] :graph
+    # @return [void] `self`
+    # @see    http://www.w3.org/TR/sparql11-update/#insertData
+    def insert_data(data, options = {})
+      raise ArgumentError, "no data given" if data.empty?
+      query_text = 'INSERT DATA {'
+      query_text += ' GRAPH ' + self.class.serialize_uri(options[:graph]) + ' {' if options[:graph]
+      query_text += "\n"
+      query_text += RDF::NTriples::Writer.buffer { |writer| writer << data }
+      query_text += '}' if options[:graph]
+      query_text += "}\n"
+      query(query_text)
+      self
+    end
+
+    ##
+    # Executes a `DELETE DATA` operation.
+    #
+    # This requires that the endpoint support SPARQL 1.1 Update.
+    #
+    # @example Deleting data sourced from a file or URL
+    #   data = RDF::Graph.load("http://rdf.rubyforge.org/doap.nt")
+    #   client.delete_data(data)
+    #
+    # @example Deleting data from a named graph
+    #   client.delete_data(data, :graph => "http://example.org/")
+    #
+    # @param  [RDF::Graph] data
+    # @param  [Hash{Symbol => Object}] options
+    # @option options [RDF::URI, String] :graph
+    # @return [void] `self`
+    # @see    http://www.w3.org/TR/sparql11-update/#deleteData
+    def delete_data(data, options = {})
+      raise ArgumentError, "no data given" if data.empty?
+      query_text = 'DELETE DATA {'
+      query_text += ' GRAPH ' + self.class.serialize_uri(options[:graph]) + ' {' if options[:graph]
+      query_text += "\n"
+      query_text += RDF::NTriples::Writer.buffer { |writer| writer << data }
+      query_text += '}' if options[:graph]
+      query_text += "}\n"
+      query(query_text)
+      self
+    end
+
+    ##
+    # Executes a `CLEAR GRAPH` operation.
+    #
+    # This is a convenience wrapper for the {#clear} method.
+    #
+    # @example `CLEAR GRAPH <http://example.org/>`
+    #   client.clear_graph("http://example.org/")
+    #
+    # @param  [RDF::URI, String] graph_uri
+    # @param  [Hash{Symbol => Object}] options
+    # @option options [Boolean] :silent
+    # @return [void] `self`
+    # @see    http://www.w3.org/TR/sparql11-update/#clear
+    def clear_graph(graph_uri, options = {})
+      self.clear(:graph, graph_uri, options)
+    end
+
+    ##
+    # Executes a `CLEAR` operation.
+    #
+    # This requires that the endpoint support SPARQL 1.1 Update.
+    #
+    # @example `CLEAR GRAPH <http://example.org/>`
+    #   client.clear(:graph, RDF::URI("http://example.org/"))
+    #
+    # @example `CLEAR DEFAULT`
+    #   client.clear(:default)
+    #
+    # @example `CLEAR NAMED`
+    #   client.clear(:named)
+    #
+    # @example `CLEAR ALL`
+    #   client.clear(:all)
+    #
+    # @param  [Symbol, #to_sym] what
+    # @param  [Hash{Symbol => Object}] options
+    # @option options [Boolean] :silent
+    # @return [void] `self`
+    # @see    http://www.w3.org/TR/sparql11-update/#clear
+    def clear(what, *arguments)
+      options = arguments.last.is_a?(Hash) ? arguments.pop : {}
+      query_text = 'CLEAR '
+      query_text += 'SILENT ' if options[:silent]
+      case what.to_sym
+        when :graph   then query_text += 'GRAPH ' + self.class.serialize_uri(arguments.pop)
+        when :default then query_text += 'DEFAULT'
+        when :named   then query_text += 'NAMED'
+        when :all     then query_text += 'ALL'
+        else raise ArgumentError, "invalid CLEAR operation: #{what.inspect}"
+      end
+      query(query_text)
+      self
+    end
+
     ##
     # @private
     def call_query_method(meth, *args)
@@ -93,7 +223,8 @@ module SPARQL
     end
 
     ##
-    # A mapping of blank node results for this client
+    # Returns a mapping of blank node results for this client.
+    #
     # @private
     def nodes
       @nodes ||= {}
@@ -112,7 +243,8 @@ module SPARQL
     end
 
     ##
-    # Executes a SPARQL query and returns the Net::HTTP::Response of the result.
+    # Executes a SPARQL query and returns the Net::HTTP::Response of the
+    # result.
     #
     # @param [String, #to_s]   query
     # @param  [Hash{Symbol => Object}] options
@@ -120,8 +252,9 @@ module SPARQL
     # @option options [Hash] :headers
     # @return [String]
     def response(query, options = {})
-      @headers['Accept'] = options[:content_type] if options[:content_type]
-      get(query, options[:headers] || {}) do |response|
+      headers = options[:headers] || {}
+      headers['Accept'] = options[:content_type] if options[:content_type]
+      request(query, headers) do |response|
         case response
           when Net::HTTPBadRequest  # 400 Bad Request
             raise MalformedQuery.new(response.body)
@@ -133,7 +266,6 @@ module SPARQL
             response
         end
       end
-
     end
 
     ##
@@ -160,7 +292,6 @@ module SPARQL
     def self.parse_json_bindings(json, nodes = {})
       require 'json' unless defined?(::JSON)
       json = JSON.parse(json.to_s) unless json.is_a?(Hash)
-
       case
         when json['boolean']
           json['boolean']
@@ -249,6 +380,35 @@ module SPARQL
       end
     end
 
+    ##
+    # Serializes a URI or URI string into SPARQL syntax.
+    #
+    # @param  [RDF::URI, String] uri
+    # @return [String]
+    # @private
+    def self.serialize_uri(uri)
+      case uri
+        when String then RDF::NTriples.serialize(RDF::URI(uri))
+        when RDF::URI then RDF::NTriples.serialize(uri)
+        else raise ArgumentError, "expected the graph URI to be a String or RDF::URI, but got #{uri.inspect}"
+      end
+    end
+
+    ##
+    # Serializes an `RDF::Value` into SPARQL syntax.
+    #
+    # @param  [RDF::Value] value
+    # @return [String]
+    # @private
+    def self.serialize_value(value)
+      # SPARQL queries are UTF-8, but support ASCII-style Unicode escapes, so
+      # the N-Triples serializer is fine unless it's a variable:
+      case
+        when value.variable? then value.to_s
+        else RDF::NTriples.serialize(value)
+      end
+    end
+
     ##
     # Outputs a developer-friendly representation of this object to `stderr`.
     #
@@ -268,41 +428,75 @@ module SPARQL
     protected
 
     ##
-    # Returns an HTTP class or HTTP proxy class based on environment http_proxy & https_proxy settings
+    # Returns an HTTP class or HTTP proxy class based on the `http_proxy`
+    # and `https_proxy` environment variables.
+    #
+    # @param  [String] scheme
     # @return [Net::HTTP::Proxy]
     def http_klass(scheme)
-      proxy_uri = nil
+      proxy_url = nil
       case scheme
-        when "http"
-          proxy_uri = URI.parse(ENV['http_proxy']) unless ENV['http_proxy'].nil?
-        when "https"
-          proxy_uri = URI.parse(ENV['https_proxy']) unless ENV['https_proxy'].nil?
+        when 'http'
+          value = ENV['http_proxy']
+          proxy_url = URI.parse(value) unless value.nil? || value.empty?
+        when 'https'
+          value = ENV['https_proxy']
+          proxy_url = URI.parse(value) unless value.nil? || value.empty?
       end
-      klass = Net::HTTP::Persistent.new(self.class.to_s, proxy_uri)
-      klass.keep_alive = 120	# increase to 2 minutes
+      klass = Net::HTTP::Persistent.new(self.class.to_s, proxy_url)
+      klass.keep_alive = 120 # increase to 2 minutes
       klass
     end
 
     ##
-    # Performs an HTTP GET request against the SPARQL endpoint.
+    # Performs an HTTP request against the SPARQL endpoint.
     #
     # @param  [String, #to_s]          query
     # @param  [Hash{String => String}] headers
     # @yield  [response]
     # @yieldparam [Net::HTTPResponse] response
     # @return [Net::HTTPResponse]
-    def get(query, headers = {}, &block)
-      url = self.url.dup
-      url.query_values = (url.query_values || {}).merge(:query => query.to_s)
+    # @see    http://www.w3.org/TR/sparql11-protocol/#query-operation
+    def request(query, headers = {}, &block)
+      method = (self.options[:method] || :post).to_sym
+      request = send("make_#{method}_request", query, headers)
 
-      request = Net::HTTP::Get.new(url.request_uri, @headers.merge(headers))
-      request.basic_auth url.user, url.password if url.user && !url.user.empty?
-      response = @http.request url, request
+      request.basic_auth(url.user, url.password) if url.user && !url.user.empty?
+
+      response = @http.request(url, request)
       if block_given?
-	block.call(response)
+        block.call(response)
       else
-	response
+        response
       end
     end
+
+    ##
+    # Constructs an HTTP GET request according to the SPARQL Protocol.
+    #
+    # @param  [String, #to_s]          query
+    # @param  [Hash{String => String}] headers
+    # @return [Net::HTTPRequest]
+    # @see    http://www.w3.org/TR/sparql11-protocol/#query-via-get
+    def make_get_request(query, headers = {})
+      url = self.url.dup
+      url.query_values = (url.query_values || {}).merge(:query => query.to_s)
+      request = Net::HTTP::Get.new(url.request_uri, self.headers.merge(headers))
+      request
+    end
+
+    ##
+    # Constructs an HTTP POST request according to the SPARQL Protocol.
+    #
+    # @param  [String, #to_s]          query
+    # @param  [Hash{String => String}] headers
+    # @return [Net::HTTPRequest]
+    # @see    http://www.w3.org/TR/sparql11-protocol/#query-via-post-urlencoded
+    def make_post_request(query, headers = {})
+      url = self.url
+      request = Net::HTTP::Post.new(url.request_uri, self.headers.merge(headers))
+      request.set_form_data(:query => query.to_s)
+      request
+    end
   end # Client
 end # SPARQL

data/lib/sparql/client/query.rb

@@ -8,7 +8,7 @@ module SPARQL; class Client
   class Query < RDF::Query
     ##
     # @return [Symbol]
-    # @see    http://www.w3.org/TR/rdf-sparql-query/#QueryForms
+    # @see    http://www.w3.org/TR/sparql11-query/#QueryForms
     attr_reader :form
 
     ##
@@ -24,7 +24,7 @@ module SPARQL; class Client
     #
     # @param  [Hash{Symbol => Object}] options
     # @return [Query]
-    # @see    http://www.w3.org/TR/rdf-sparql-query/#ask
+    # @see    http://www.w3.org/TR/sparql11-query/#ask
     def self.ask(options = {})
       self.new(:ask, options)
     end
@@ -38,7 +38,7 @@ module SPARQL; class Client
     # @overload self.select(*variables, options)
     #   @param  [Array<Symbol>]          variables
     #   @return [Query]
-    # @see    http://www.w3.org/TR/rdf-sparql-query/#select
+    # @see    http://www.w3.org/TR/sparql11-query/#select
     def self.select(*variables)
       options = variables.last.is_a?(Hash) ? variables.pop : {}
       self.new(:select, options).select(*variables)
@@ -53,7 +53,7 @@ module SPARQL; class Client
     # @overload self.describe(*variables, options)
     #   @param  [Array<Symbol, RDF::URI>] variables
     #   @return [Query]
-    # @see    http://www.w3.org/TR/rdf-sparql-query/#describe
+    # @see    http://www.w3.org/TR/sparql11-query/#describe
     def self.describe(*variables)
       options = variables.last.is_a?(Hash) ? variables.pop : {}
       self.new(:describe, options).describe(*variables)
@@ -69,7 +69,7 @@ module SPARQL; class Client
     #   @param  [Array<RDF::Query::Pattern, Array>] patterns
     #   @param  [Hash{Symbol => Object}]            options
     #   @return [Query]
-    # @see    http://www.w3.org/TR/rdf-sparql-query/#construct
+    # @see    http://www.w3.org/TR/sparql11-query/#construct
     def self.construct(*patterns)
       options = patterns.last.is_a?(Hash) ? patterns.pop : {}
       self.new(:construct, options).construct(*patterns) # FIXME
@@ -89,7 +89,7 @@ module SPARQL; class Client
 
     ##
     # @return [Query]
-    # @see    http://www.w3.org/TR/rdf-sparql-query/#ask
+    # @see    http://www.w3.org/TR/sparql11-query/#ask
     def ask
       @form = :ask
       self
@@ -98,7 +98,7 @@ module SPARQL; class Client
     ##
     # @param  [Array<Symbol>] variables
     # @return [Query]
-    # @see    http://www.w3.org/TR/rdf-sparql-query/#select
+    # @see    http://www.w3.org/TR/sparql11-query/#select
     def select(*variables)
       @values = variables.map { |var| [var, RDF::Query::Variable.new(var)] }
       self
@@ -107,7 +107,7 @@ module SPARQL; class Client
     ##
     # @param  [Array<Symbol>] variables
     # @return [Query]
-    # @see    http://www.w3.org/TR/rdf-sparql-query/#describe
+    # @see    http://www.w3.org/TR/sparql11-query/#describe
     def describe(*variables)
       @values = variables.map { |var|
         [var, var.is_a?(RDF::URI) ? var : RDF::Query::Variable.new(var)]
@@ -118,6 +118,7 @@ module SPARQL; class Client
     ##
     # @param  [Array<RDF::Query::Pattern, Array>] patterns
     # @return [Query]
+    # @see    http://www.w3.org/TR/sparql11-query/#construct
     def construct(*patterns)
       options[:template] = build_patterns(patterns)
       self
@@ -125,7 +126,7 @@ module SPARQL; class Client
 
     # @param [RDF::URI] uri
     # @return [Query]
-    # @see http://www.w3.org/TR/rdf-sparql-query/#specDataset
+    # @see http://www.w3.org/TR/sparql11-query/#specifyingDataset
     def from(uri)
       options[:from] = uri
       self
@@ -134,7 +135,7 @@ module SPARQL; class Client
     ##
     # @param  [Array<RDF::Query::Pattern, Array>] patterns
     # @return [Query]
-    # @see    http://www.w3.org/TR/rdf-sparql-query/#GraphPattern
+    # @see    http://www.w3.org/TR/sparql11-query/#GraphPattern
     def where(*patterns)
       @patterns += build_patterns(patterns)
       self
@@ -145,7 +146,7 @@ module SPARQL; class Client
     ##
     # @param  [Array<Symbol, String>] variables
     # @return [Query]
-    # @see    http://www.w3.org/TR/rdf-sparql-query/#modOrderBy
+    # @see    http://www.w3.org/TR/sparql11-query/#modOrderBy
     def order(*variables)
       options[:order_by] = variables
       self
@@ -166,7 +167,7 @@ module SPARQL; class Client
 
     ##
     # @return [Query]
-    # @see    http://www.w3.org/TR/rdf-sparql-query/#modDistinct
+    # @see    http://www.w3.org/TR/sparql11-query/#modDuplicates
     def distinct(state = true)
       options[:distinct] = state
       self
@@ -174,16 +175,30 @@ module SPARQL; class Client
 
     ##
     # @return [Query]
-    # @see    http://www.w3.org/TR/rdf-sparql-query/#modReduced
+    # @see    http://www.w3.org/TR/sparql11-query/#modDuplicates
     def reduced(state = true)
       options[:reduced] = state
       self
     end
 
+    ##
+    # @param  [RDF::Value] graph_uri_or_var
+    # @return [Query]
+    # @see    http://www.w3.org/TR/sparql11-query/#queryDataset
+    def graph(graph_uri_or_var)
+      options[:graph] = case graph_uri_or_var
+        when Symbol then RDF::Query::Variable.new(graph_uri_or_var)
+        when String then RDF::URI(graph_uri_or_var)
+        when RDF::Value then graph_uri_or_var
+        else raise ArgumentError
+      end
+      self
+    end
+
     ##
     # @param  [Integer, #to_i] start
     # @return [Query]
-    # @see    http://www.w3.org/TR/rdf-sparql-query/#modOffset
+    # @see    http://www.w3.org/TR/sparql11-query/#modOffset
     def offset(start)
       slice(start, nil)
     end
@@ -191,7 +206,7 @@ module SPARQL; class Client
     ##
     # @param  [Integer, #to_i] length
     # @return [Query]
-    # @see    http://www.w3.org/TR/rdf-sparql-query/#modResultLimit
+    # @see    http://www.w3.org/TR/sparql11-query/#modResultLimit
     def limit(length)
       slice(nil, length)
     end
@@ -208,7 +223,7 @@ module SPARQL; class Client
 
     ##
     # @return [Query]
-    # @see    http://www.w3.org/TR/rdf-sparql-query/#prefNames
+    # @see    http://www.w3.org/TR/sparql11-query/#prefNames
     def prefix(string)
       (options[:prefixes] ||= []) << string
       self
@@ -216,7 +231,7 @@ module SPARQL; class Client
 
     ##
     # @return [Query]
-    # @see    http://www.w3.org/TR/rdf-sparql-query/#optionals
+    # @see    http://www.w3.org/TR/sparql11-query/#optionals
     def optional(*patterns)
       (options[:optionals] ||= []) << build_patterns(patterns)
       self
@@ -298,15 +313,17 @@ module SPARQL; class Client
     # @return [String]
     def to_s
       buffer = [form.to_s.upcase]
+
       case form
         when :select, :describe
           only_count = values.empty? and options[:count]
           buffer << 'DISTINCT' if options[:distinct] and not only_count
           buffer << 'REDUCED'  if options[:reduced]
-          buffer << ((values.empty? and not options[:count]) ? '*' : values.map { |v| serialize_value(v[1]) }.join(' '))
+          buffer << ((values.empty? and not options[:count]) ? '*' : values.map { |v| SPARQL::Client.serialize_value(v[1]) }.join(' '))
           if options[:count]
             options[:count].each do |var, count|
-              buffer << '( COUNT(' + (options[:distinct] ? 'DISTINCT ' : '') + (var.is_a?(String) ? var : "?#{var}") + ') AS ' + (count.is_a?(String) ? count : "?#{count}") + ' )'
+              buffer << '( COUNT(' + (options[:distinct] ? 'DISTINCT ' : '') +
+                (var.is_a?(String) ? var : "?#{var}") + ') AS ' + (count.is_a?(String) ? count : "?#{count}") + ' )'
             end
           end
         when :construct
@@ -315,10 +332,15 @@ module SPARQL; class Client
           buffer << '}'
       end
 
-      buffer << "FROM #{serialize_value(options[:from])}" if options[:from]
+      buffer << "FROM #{SPARQL::Client.serialize_value(options[:from])}" if options[:from]
 
       unless patterns.empty? && form == :describe
         buffer << 'WHERE {'
+
+        if options[:graph]
+          buffer << 'GRAPH ' + SPARQL::Client.serialize_value(options[:graph])
+          buffer << '{'
+        end
         buffer += serialize_patterns(patterns)
         if options[:optionals]
           options[:optionals].each do |patterns|
@@ -330,7 +352,11 @@ module SPARQL; class Client
         if options[:filters]
           buffer += options[:filters].map { |filter| "FILTER(#{filter})" }
         end
-        buffer << '}'
+        if options[:graph]
+          buffer << '}' # GRAPH
+        end
+
+        buffer << '}' # WHERE
       end
 
       if options[:group_by]
@@ -345,7 +371,7 @@ module SPARQL; class Client
 
       buffer << "OFFSET #{options[:offset]}" if options[:offset]
       buffer << "LIMIT #{options[:limit]}"   if options[:limit]
-      options[:prefixes].reverse.each {|e| buffer.unshift("PREFIX #{e}") } if options[:prefixes]
+      options[:prefixes].reverse.each { |e| buffer.unshift("PREFIX #{e}") } if options[:prefixes]
 
       buffer.join(' ')
     end
@@ -353,8 +379,16 @@ module SPARQL; class Client
     ##
     # @private
     def serialize_patterns(patterns)
-      patterns.map do |p|
-        p.to_triple.map { |v| serialize_value(v) }.join(' ') + " ."
+      rdf_type = RDF.type
+      patterns.map do |pattern|
+        serialized_pattern = pattern.to_triple.each_with_index.map do |v, i|
+          if i == 1 && v.equal?(rdf_type)
+            'a' # abbreviate RDF.type in the predicate position per SPARQL grammar
+          else
+            SPARQL::Client.serialize_value(v)
+          end
+        end
+        serialized_pattern.join(' ') + ' .'
       end
     end
 
@@ -374,20 +408,5 @@ module SPARQL; class Client
     def inspect
       sprintf("#<%s:%#0x(%s)>", self.class.name, __id__, to_s)
     end
-
-    ##
-    # Serializes an RDF::Value into a format appropriate for select, construct, and where clauses
-    #
-    # @param  [RDF::Value] value
-    # @return [String]
-    # @private
-    def serialize_value(value)
-      # SPARQL queries are UTF-8, but support ASCII-style Unicode escapes, so
-      # the N-Triples serializer is fine unless it's a variable:
-      case
-        when value.variable? then value.to_s
-        else RDF::NTriples.serialize(value)
-      end
-    end
   end
 end; end

data/lib/sparql/client/version.rb

@@ -1,7 +1,7 @@
 module SPARQL; class Client
   module VERSION
-    VERSION_FILE = File.expand_path("../../../../VERSION", __FILE__)
-    MAJOR, MINOR, TINY, EXTRA = File.read(VERSION_FILE).chop.split(".")
+    VERSION_FILE = File.expand_path('../../../../VERSION', __FILE__)
+    MAJOR, MINOR, TINY, EXTRA = File.read(VERSION_FILE).chop.split('.')
     STRING = [MAJOR, MINOR, TINY, EXTRA].compact.join('.')
 
     ##

metadata

@@ -1,25 +1,26 @@
 --- !ruby/object:Gem::Specification
 name: sparql-client
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.3
   prerelease: 
 platform: ruby
 authors:
 - Arto Bendiken
 - Ben Lavender
+- Gregg Kellogg
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-09 00:00:00.000000000 Z
+date: 2013-01-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: json_pure
+  name: rdf
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 1.4.6
+        version: 0.3.5
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -27,15 +28,15 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 1.4.6
+        version: 0.3.5
 - !ruby/object:Gem::Dependency
-  name: rdf
+  name: net-http-persistent
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 0.3.5
+        version: 1.4.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -43,15 +44,15 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 0.3.5
+        version: 1.4.1
 - !ruby/object:Gem::Dependency
-  name: net-http-persistent
+  name: json_pure
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 1.4.1
+        version: 1.4.6
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -59,15 +60,15 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 1.4.1
+        version: 1.4.6
 - !ruby/object:Gem::Dependency
-  name: yard
+  name: rdf-spec
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 0.7.5
+        version: 0.3.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -75,7 +76,7 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 0.7.5
+        version: 0.3.5
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -93,13 +94,13 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 2.10.0
 - !ruby/object:Gem::Dependency
-  name: rdf-spec
+  name: yard
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 0.3.5
+        version: 0.8.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -107,7 +108,7 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 0.3.5
+        version: 0.8.3
 description: SPARQL client for RDF.rb.
 email: public-rdf-ruby@w3.org
 executables: []