sparql 1.1.1 → 1.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 83b4375ca13302d7cdc8a6c81d7b6543cea34481
-  data.tar.gz: 26e31f363b9b86f7786ab848ff9c655c7441260e
+  metadata.gz: ec306ea47d79b90b84acd927ef5169c6a745875b
+  data.tar.gz: 6e5860abfd989c5751c778c4212fdc3eb47368aa
 SHA512:
-  metadata.gz: 47e5858870bc37a4a6be21ec9b117e1d53e75d1a384cdc1e89636b7a7ad9943382c972daea03fe6bc1ad5dc93e76678889a048ad351ad1ea56530edb6fabcb7b
-  data.tar.gz: aaa54ca0274fcecec14f8720c0ab1fa27449a825988c34badbde60908975c2aae3c6a78951d8fa31ceb7ef954d61edda246a524e32cc4db34dab724bf3f945a3
+  metadata.gz: b5f110a1767a95d2e2c194b2b903fd4f4db9cf470ad14529525a3ae64cc3b2b785bf25d9c95e760475a519a53c01a33ef2b0de3cfb06bee5a39e6c0c72a6337d
+  data.tar.gz: bf1dd65ca43bfe141f152de212ca6d9c7b2b1e11487fc8bbcaac03dabd241da86f58320926225fc784b398a5b0af4c6142636d909375e92426727fe91452b5ef

data/README.md

@@ -69,6 +69,11 @@ will be in later release along with:
 
 either in this, or related gems.
 
+### Updates for RDF 1.1
+Starting with version 1.1.2, the SPARQL gem uses the 1.1 version of the [RDF.rb][], which adheres to [RDF 1.1 Concepts](http://www.w3.org/TR/rdf11-concepts/) rather than [RDF 1.0](http://www.w3.org/TR/rdf-concepts/). The main difference is that there is now no difference between a _Simple Literal_ (a literal with no datatype or language) and a Literal with datatype _xsd:string_; this causes some minor differences in the way in which queries are understood, and when expecting different results.
+
+Additionally, queries now take a block, or return an `Enumerator`; this is in keeping with much of the behavior of [RDF.rb][] methods, including `Queryable#query`, and with version 1.1 or [RDF.rb][], Query#execute. As a consequence, all queries which used to be of the form `query.execute(repository)` may equally be called as `repository.query(query)`. Previously, results were returned as a concrete class implementing `RDF::Queryable` or `RDF::Query::Solutions`, these are now `Enumerators`.
+
 ### SPARQL Extension Functions
 Extension functions may be defined, which will be invoked during query evaluation. For example:
 
@@ -94,8 +99,8 @@ See {SPARQL::Algebra::Expression.register_extension} for details.
 ### Middleware
 
 {Rack::SPARQL} is a superset of [Rack::LinkedData][] to allow content negotiated results
-to be returned any `RDF::Enumerable` or `RDF::Query::Solutions` compatible results.
-You would typically return an instance of `RDF::Graph`, `RDF::Repository` or `RDF::Query::Solutions`
+to be returned any `RDF::Enumerable` or an enumerator extended with `RDF::Query::Solutions` compatible results.
+You would typically return an instance of `RDF::Graph`, `RDF::Repository` or an enumerator extended with `RDF::Query::Solutions`
 from your Rack application, and let the `Rack::SPARQL::ContentNegotiation` middleware
 take care of serializing your response into whatever format the HTTP
 client requested and understands.
@@ -133,11 +138,21 @@ a full set of RDF formats.
     require 'rubygems'
     require 'sparql'
 
+### Querying a repository with a SPARQL query
+
+    queryable = RDF::Repository.load("etc/doap.ttl")
+    sse = SPARQL.parse("SELECT * WHERE { ?s ?p ?o }")
+    queryable.query(sse) do |result|
+      result.inspect
+    end
+
 ### Executing a SPARQL query against a repository
 
     queryable = RDF::Repository.load("etc/doap.ttl")
     sse = SPARQL.parse("SELECT * WHERE { ?s ?p ?o }")
-    sse.execute(queryable)
+    sse.execute(queryable) do |result|
+      result.inspect
+    end
 
 ### Rendering solutions as JSON, XML, CSV, TSV or HTML
     queryable = RDF::Repository.load("etc/doap.ttl")
@@ -272,6 +287,7 @@ To get a local working copy of the development repository, do:
 * [Pius Uzamere](http://github.com/pius) - <http://pius.me/>
 
 ## Contributing
+This repository uses [Git Flow](https://github.com/nvie/gitflow) to mange development and release activity. All submissions _must_ be on a feature branch based on the _develop_ branch to ease staging and integration.
 
 * Do your best to adhere to the existing coding conventions and idioms.
 * Don't use hard tabs, and don't leave trailing whitespace on any line.
@@ -290,7 +306,9 @@ To get a local working copy of the development repository, do:
 This is free and unencumbered public domain software. For more information,
 see <http://unlicense.org/> or the accompanying {file:UNLICENSE} file.
 
-A copy of the [SPARQL 1.0 tests][] and [SPARQL 1.1 tests][] are included in the repository, which are not covered under the UNLICENSE; see the references for test copyright information.
+A copy of the [SPARQL 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](http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231).
+
+A copy of the [SPARQL 1.0 tests][] and [SPARQL 1.1 tests][] are also included in the repository, which are not covered under the UNLICENSE; see the references for test copyright information.
 
 [Ruby]:             http://ruby-lang.org/
 [RDF]:              http://www.w3.org/RDF/
@@ -314,6 +332,7 @@ A copy of the [SPARQL 1.0 tests][] and [SPARQL 1.1 tests][] are included in the
 [SPARQL doc]:       http://rubydoc.info/github/ruby-rdf/sparql/frames
 [SPARQL XML]:       http://www.w3.org/TR/rdf-sparql-XMLres/
 [SPARQL JSON]:      http://www.w3.org/TR/rdf-sparql-json-res/
+[SPARQL EBNF]:      http://www.w3.org/TR/sparql11-query/#sparqlGrammar
 [Property Paths]:   http://www.w3.org/TR/2013/REC-sparql11-query-20130321/#propertypaths
 
 [SSD]:              http://www.w3.org/TR/sparql11-service-description/

data/VERSION

@@ -1 +1 @@
-1.1.1
+1.1.2

data/lib/rack/sparql/conneg.rb

@@ -34,15 +34,18 @@ module Rack; module SPARQL
     end
 
     ##
-    # Handles a Rack protocol request.
+    # Handles a Rack protocol request. Parses Accept header to find appropriate mime-type and sets content_type accordingly.
     #
     # If result is `RDF::Literal::Boolean`, `RDF::Query::Results`, or `RDF::Enumerable`
     # The result is serialized using {SPARQL::Results}
     #
+    # Inserts ordered content types into the environment as `ORDERED_CONTENT_TYPES` if an Accept header is present
+    #
     # @param  [Hash{String => String}] env
     # @return [Array(Integer, Hash, #each)]
     # @see    http://rack.rubyforge.org/doc/SPEC.html
     def call(env)
+      env['ORDERED_CONTENT_TYPES'] = parse_accept_header(env['HTTP_ACCEPT']) if env.has_key?('HTTP_ACCEPT')
       response = app.call(env)
       body = response[2].respond_to?(:body) ? response[2].body : response[2]
       case body
@@ -66,7 +69,7 @@ module Rack; module SPARQL
     def serialize(env, status, headers, body)
       begin
         serialize_options = {}
-        serialize_options[:content_types] = parse_accept_header(env['HTTP_ACCEPT']) if env.has_key?('HTTP_ACCEPT')
+        serialize_options[:content_types] = env['ORDERED_CONTENT_TYPES'] if env['ORDERED_CONTENT_TYPES']
         serialize_options.merge!(@options)
         results = ::SPARQL.serialize_results(body, serialize_options)
         raise RDF::WriterError, "can't serialize results" unless results

data/lib/sinatra/sparql.rb

@@ -4,28 +4,23 @@ require 'rack/sparql'
 
 module Sinatra
   ##
-  # The Sinatra::SPARQL module adds Rack::SPARQL} middleware support for responding to
-  # SPARQL requests. It is the responsibility of the application to manage
-  # the SPARQL endpoint and perform the query. The query results are then sent
-  # as the response body. {Rack::SPARQL} middleware uses content negotiation
-  # to format the results appropriately.
+  # The Sinatra::SPARQL module adds {Rack::SPARQL} middleware support for responding to SPARQL requests. It is the responsibility of the application to manage the SPARQL endpoint and perform the query. The query results are then sent as the response body. {Rack::SPARQL} middleware uses content negotiation to format the results appropriately.
+  #
+  # To override negotiation on Content-Type, set :format in `sparql_options` to a RDF Format class, or symbol identifying a format.
+  #
   # @see http://www.sinatrarb.com/extensions.html
   module SPARQL
     ##
     # Helper methods.
     module Helpers
       ##
-      # This is useful when a GET request is performed against a SPARQL endpoint and
-      # no query is performed. Provide a set of datasets, including a default dataset
-      # along with optional triple count, dump location, and description of the dataset.
+      # This is useful when a GET request is performed against a SPARQL endpoint and no query is performed. Provide a set of datasets, including a default dataset along with optional triple count, dump location, and description of the dataset.
       #
-      # The results are serialized using content negotiation. For text/html, authors
-      # should generate RDFa for the serivce description directly.
+      # The results are serialized using content negotiation. For text/html, authors should generate RDFa for the serivce description directly.
       #
       # @param [Hash{Symbol => Object}] options
       # @option options [RDF::Enumerable] :repository
-      #   An enumerable, typically a type of `RDF::Repository` containing the dataset used for
-      #   queries against the service.
+      #   An enumerable, typically a type of `RDF::Repository` containing the dataset used for queries against the service.
       # @option options [RDF::URI, #to_s] :endpoint
       #   URI of the service endpoint, defaults to "/sparql" in the current realm.
       # @return [RDF::Graph]
@@ -94,12 +89,10 @@ module Sinatra
     end
 
     ##
-    # * Registers Rack::SPARQL::ContentNegotiation
+    # * Registers {Rack::SPARQL::ContentNegotiation}
     # * adds helpers
     # * includes SPARQL, RDF and LinkedData
-    # * defines `sparql_options`, which are passed to the Rack middleware
-    #   available as `settings.sparql_options` and as options within
-    #   the {Rack::SPARQL} middleware.
+    # * defines `sparql_options`, which are passed to the Rack middleware available as `settings.sparql_options` and as options within the {Rack::SPARQL} middleware.
     #
     # @param  [Sinatra::Base] app
     # @return [void]

data/lib/sinatra/sparql/extensions.rb

@@ -7,8 +7,6 @@ class Sinatra::Response
       headers.delete "Content-Type"
     elsif RDF::Query::Solutions === body
       # Don't calculate content-length here
-    elsif Array === body and not [204, 304].include?(status.to_i)
-      headers["Content-Length"] = body.inject(0) { |l, p| l + Rack::Utils.bytesize(p) }.to_s
     end
 
     # Rack::Response#finish sometimes returns self as response body. We don't want that.

data/lib/sparql.rb

@@ -58,11 +58,14 @@ module SPARQL
   #   One or more URIs used to initialize a new instance of `queryable` in the default context.
   # @option options [RDF::URI, String, Array<RDF::URI, String>] :named_graph_uri
   #   One or more URIs used to initialize the `queryable` as a named context.
-  # @return [RDF::Graph, RDF::Query::Solutions, Boolean]
-  #   Note, results may be used with {SPARQL.serialize_results} to obtain appropriate
-  #   output encoding.
+  # @yield  [solution]
+  #   each matching solution, statement or boolean
+  # @yieldparam  [RDF::Statement, RDF::Query::Solution, Boolean] solution
+  # @yieldreturn [void] ignored
+  # @return [RDF::Graph, Boolean, RDF::Query::Solutions::Enumerator]
+  #   Note, results may be used with {SPARQL.serialize_results} to obtain appropriate output encoding.
   # @raise  [SPARQL::MalformedQuery] on invalid input
-  def self.execute(query, queryable, options = {})
+  def self.execute(query, queryable, options = {}, &block)
     query = self.parse(query, options)
     queryable = queryable || RDF::Repository.new
     
@@ -82,7 +85,7 @@ module SPARQL
         queryable.load(uri, :context => uri)
       end
     end
-    solutions = query.execute(queryable)
+    query.execute(queryable, &block)
   rescue SPARQL::Grammar::Parser::Error => e
     raise MalformedQuery, e.message
   rescue TypeError => e

data/lib/sparql/algebra/expression.rb

@@ -27,7 +27,7 @@ module SPARQL; module Algebra
       end
       require 'sparql/algebra/sxp_extensions'
       
-      sse = sse.dup.force_encoding(Encoding::UTF_8)
+      sse = sse.encode(Encoding::UTF_8)
       sxp = SXP::Reader::SPARQL.new(sse) do |reader|
         # Set base_uri if we have one
         reader.base_uri = options[:base_uri] if options[:base_uri]

data/lib/sparql/algebra/extensions.rb

@@ -175,7 +175,7 @@ module RDF::Term
   def compatible?(other)
     return false unless literal?  && other.literal? && plain? && other.plain?
 
-    dtr = RDF::VERSION.to_s >= "1.1" ? other.datatype : (other.has_language? ? RDF.langString : RDF::XSD.string)
+    dtr = other.datatype
 
     # * The arguments are simple literals or literals typed as xsd:string
     # * The arguments are plain literals with identical language tags
@@ -209,16 +209,27 @@ module RDF::Queryable
   # @yieldreturn [void] ignored
   # @return [Enumerator]
   # @see    RDF::Queryable#query_pattern
-  def query(pattern, &block)
-    raise TypeError, "#{self} is not readable" if respond_to?(:readable?) && !readable?
+  def query(pattern, options = {}, &block)
+    raise TypeError, "#{self} is not queryable" if respond_to?(:queryable?) && !queryable?
 
     if pattern.is_a?(SPARQL::Algebra::Operator) && pattern.respond_to?(:execute)
       before_query(pattern) if respond_to?(:before_query)
-      query_execute(pattern, &block)
+      solutions = if method(:query_execute).arity == 1
+        query_execute(pattern, &block)
+      else
+        query_execute(pattern, options, &block)
+      end
       after_query(pattern) if respond_to?(:after_query)
-      enum_for(:query_execute, pattern)
+
+      if !pattern.respond_to?(:query_yeilds_solutions?) || pattern.query_yields_solutions?
+        # Just return solutions
+        solutions
+      else
+        # Return an enumerator
+        enum_for(:query, pattern, options)
+      end
     else
-      query_without_sparql(pattern, &block)
+      query_without_sparql(pattern, options, &block)
     end
   end
   
@@ -249,6 +260,23 @@ class RDF::Query
     res = [:bgp] + patterns.map(&:to_sxp_bin)
     (context ? [:graph, context, res] : res)
   end
+  # Query results in a boolean result (e.g., ASK)
+  # @return [Boolean]
+  def query_yields_boolean?
+    false
+  end
+
+  # Query results statements (e.g., CONSTRUCT, DESCRIBE, CREATE)
+  # @return [Boolean]
+  def query_yields_statements?
+    false
+  end
+
+  # Query results solutions (e.g., SELECT)
+  # @return [Boolean]
+  def query_yields_solutions?
+    true
+  end
 end
 
 class RDF::Query::Pattern

data/lib/sparql/algebra/operator/ask.rb

@@ -22,14 +22,16 @@ module SPARQL; module Algebra
       #   the graph or repository to query
       # @param  [Hash{Symbol => Object}] options
       #   any additional keyword options
-      # @return [RDF::Literal::Boolean]
-      #   the resulting solution sequence
+      # @yield  [RDF::Literal::Boolean]
+      # @yieldparam  [RDF::Query::Solution] solution
+      # @yieldreturn [void] ignored
+      # @return [RDF::Literal::Boolean]\
       # @see    http://www.w3.org/TR/rdf-sparql-query/#sparqlAlgebra
       def execute(queryable, options = {})
         debug(options) {"Ask #{operands.first}"}
-        boolean(!operands.last.
-          execute(queryable, options.merge(:depth => options[:depth].to_i + 1)).
-          empty?)
+        res = boolean(!queryable.query(operands.last, options.merge(:depth => options[:depth].to_i + 1)).empty?)
+        yield res if block_given?
+        res
       end
       
       ##
@@ -41,6 +43,12 @@ module SPARQL; module Algebra
       def optimize
         operands = operands.map(&:optimize)
       end
+
+      # Query results in a boolean result (e.g., ASK)
+      # @return [Boolean]
+      def query_yields_boolean?
+        true
+      end
     end # Ask
   end # Operator
 end; end # SPARQL::Algebra

data/lib/sparql/algebra/operator/base.rb

@@ -22,15 +22,17 @@ module SPARQL; module Algebra
       #   the graph or repository to query
       # @param  [Hash{Symbol => Object}] options
       #   any additional keyword options
-      # @return [RDF::Query::Solutions]
+      # @yield  [solution]
+      #   each matching solution, statement or boolean
+      # @yieldparam  [RDF::Statement, RDF::Query::Solution, Boolean] solution
+      # @yieldreturn [void] ignored
+      # @return [RDF::Queryable, RDF::Query::Solutions]
       #   the resulting solution sequence
       # @see    http://www.w3.org/TR/rdf-sparql-query/#sparqlAlgebra
-      def execute(queryable, options = {})
+      def execute(queryable, options = {}, &block)
         debug(options) {"Base #{operands.first}"}
         Operator.base_uri = operands.first
-        @solutions = operands.last.execute(queryable, options.merge(:depth => options[:depth].to_i + 1))
-        debug(options) {"=> #{@solutions.inspect}"}
-        @solutions
+        queryable.query(operands.last, options.merge(:depth => options[:depth].to_i + 1), &block)
       end
       
       ##
@@ -42,6 +44,18 @@ module SPARQL; module Algebra
       def optimize
         operands.last.optimize
       end
+
+      # Query results in a boolean result (e.g., ASK)
+      # @return [Boolean]
+      def query_yields_boolean?
+        operands.last.query_yields_boolean?
+      end
+
+      # Query results statements (e.g., CONSTRUCT, DESCRIBE, CREATE)
+      # @return [Boolean]
+      def query_yields_statements?
+        operands.last.query_yields_statements?
+      end
     end # Base
   end # Operator
 end; end # SPARQL::Algebra

data/lib/sparql/algebra/operator/bgp.rb

@@ -17,9 +17,13 @@ module SPARQL; module Algebra
       #
       # @overload self.new(*patterns)
       #   @param [Array<RDF::Query::Pattern>] patterns
+      # @yield  [solution]
+      #   each matching solution
+      # @yieldparam  [RDF::Query::Solution] solution
+      # @yieldreturn [void] ignored
       # @return [RDF::Query]
-      def self.new(*patterns)
-        RDF::Query.new(*(patterns + [{:context => false}]))
+      def self.new(*patterns, &block)
+        RDF::Query.new(*(patterns + [{:context => false}]), &block)
       end
     end # BGP
   end # Operator

data/lib/sparql/algebra/operator/construct.rb

@@ -29,17 +29,21 @@ module SPARQL; module Algebra
       #   the graph or repository to query
       # @param  [Hash{Symbol => Object}] options
       #   any additional keyword options
-      # @return [RDF::Query::Solutions]
-      #   the resulting solution sequence
+      # @yield  [statement]
+      #   each matching statement
+      # @yieldparam  [RDF::Statement] solution
+      # @yieldreturn [void] ignored
+      # @return [RDF::Queryable]
+      #   A Queryable with constructed triples
       # @see    http://www.w3.org/TR/rdf-sparql-query/#construct
-      def execute(queryable, options = {})
+      def execute(queryable, options = {}, &block)
         debug(options) {"Construct #{operands.first}, #{options.inspect}"}
         graph = RDF::Graph.new
         patterns = operands.first
         query = operands.last
 
-        query.execute(queryable, options.merge(:depth => options[:depth].to_i + 1)).each do |solution|
-          debug(options) {"=> Apply #{solution.inspect} to BGP"}
+        queryable.query(query, options.merge(:depth => options[:depth].to_i + 1)).each do |solution|
+          debug(options) {"(construct apply) #{solution.inspect} to BGP"}
           
           # Create a mapping from BNodes within the pattern list to newly constructed BNodes
           nodes = {}
@@ -58,16 +62,17 @@ module SPARQL; module Algebra
             # Sanity checking on statement
             if statement.subject.nil? || statement.predicate.nil? || statement.object.nil? ||
                statement.subject.literal? || statement.predicate.literal?
-              debug(options) {"==> skip #{statement.inspect}"}
+              debug(options) {"(construct skip) #{statement.inspect}"}
               next
             end
 
-            debug(options) {"==> add #{statement.inspect}"}
+            debug(options) {"(construct add) #{statement.inspect}"}
             graph << statement
           end
         end
-        
+
         debug(options) {"=>\n#{graph.dump(:ttl, :standard_prefixes => true)}"}
+        graph.each(&block) if block_given?
         graph
       end
       
@@ -80,6 +85,12 @@ module SPARQL; module Algebra
       def optimize
         operands = operands.map(&:optimize)
       end
+
+      # Query results statements (e.g., CONSTRUCT, DESCRIBE, CREATE)
+      # @return [Boolean]
+      def query_yields_statements?
+        true
+      end
     end # Construct
   end # Operator
 end; end # SPARQL::Algebra

data/lib/sparql/algebra/operator/dataset.rb

@@ -109,7 +109,8 @@ module SPARQL; module Algebra
       NAME = [:dataset]
       # Selected accept headers, from those available
       ACCEPTS = (%w(
-        text/turtle
+        application/turtle
+        text/turtle;q=0.9
         application/rdf+xml;q=0.8
         application/n-triples;q=0.4
         text/plain;q=0.1
@@ -130,10 +131,14 @@ module SPARQL; module Algebra
       #   the graph or repository to query
       # @param  [Hash{Symbol => Object}] options
       #   any additional keyword options
+      # @yield  [solution]
+      #   each matching solution
+      # @yieldparam  [RDF::Query::Solution] solution
+      # @yieldreturn [void] ignored
       # @return [RDF::Query::Solutions]
       #   the resulting solution sequence
       # @see    http://www.w3.org/TR/rdf-sparql-query/#sparqlAlgebra
-      def execute(queryable, options = {})
+      def execute(queryable, options = {}, &base)
         debug(options) {"Dataset"}
         default_datasets = []
         named_datasets = []
@@ -176,8 +181,7 @@ module SPARQL; module Algebra
         aggregate = RDF::AggregateRepo.new(queryable)
         named_datasets.each {|name| aggregate.named(name) if queryable.has_context?(name)}
         aggregate.default(*default_datasets.select {|name| queryable.has_context?(name)})
-        executable = operands.last
-        @solutions = executable.execute(aggregate, options.merge(:depth => options[:depth].to_i + 1))
+        aggregate.query(operands.last, options.merge(:depth => options[:depth].to_i + 1), &base)
       end
       
       ##