sparql 3.1.0 → 3.1.2

data/lib/sinatra/sparql.rb

@@ -8,7 +8,7 @@ module Sinatra
   #
   # 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
+  # @see https://www.sinatrarb.com/extensions.html
   module SPARQL
     ##
     # Helper methods.
@@ -25,8 +25,8 @@ module Sinatra
       #   URI of the service endpoint, defaults to "/sparql" in the current realm.
       # @return [RDF::Graph]
       #
-      # @see http://www.w3.org/TR/sparql11-service-description
-      # @see http://www.w3.org/TR/void/
+      # @see https://www.w3.org/TR/sparql11-service-description
+      # @see https://www.w3.org/TR/void/
       def service_description(**options)
         repository = options[:repository]
 

data/lib/sparql.rb

@@ -3,14 +3,14 @@ require 'sparql/extensions'
 ##
 # A SPARQL for RDF.rb.
 #
-# @see http://www.w3.org/TR/sparql11-query
+# @see https://www.w3.org/TR/sparql11-query
 module SPARQL
   autoload :Algebra, 'sparql/algebra'
   autoload :Grammar, 'sparql/grammar'
   autoload :Results, 'sparql/results'
   autoload :VERSION, 'sparql/version'
 
-  # @see http://rubygems.org/gems/sparql-client
+  # @see https://rubygems-client
   autoload :Client,  'sparql/client'
 
   ##
@@ -52,12 +52,13 @@ module SPARQL
   #   results = SPARQL.execute("SELECT * WHERE { ?s ?p ?o }", repository)
   #
   # @param  [IO, StringIO, String, #to_s]  query
+  # @param  [RDF::Queryable]  queryable
   # @param  [Hash{Symbol => Object}] options
-  # @option options  [RDF::Queryable]  :queryable
-  # @option options [RDF::URI, String, Array<RDF::URI, String>] :load_datasets
-  #   One or more URIs used to initialize a new instance of `queryable` in the default graph.
+  # @option options [Boolean] :optimize
+  #   Optimize query before execution.
   # @option options [RDF::URI, String, Array<RDF::URI, String>] :default_graph_uri
-  #   One or more URIs used to initialize a new instance of `queryable` in the default graph.
+  # @option options [RDF::URI, String, Array<RDF::URI, String>] :load_datasets
+  #   One or more URIs used to initialize a new instance of `queryable` in the default graph. One or more URIs used to initialize a new instance of `queryable` in the default graph.
   # @option options [RDF::URI, String, Array<RDF::URI, String>] :named_graph_uri
   #   One or more URIs used to initialize the `queryable` as a named graph.
   # @yield  [solution]
@@ -69,6 +70,7 @@ module SPARQL
   # @raise  [SPARQL::MalformedQuery] on invalid input
   def self.execute(query, queryable, **options, &block)
     query = self.parse(query, **options)
+    query = query.optimize(**options) if options[:optimize]
     queryable = queryable || RDF::Repository.new
     
     case options.fetch(:debug, nil)

data/lib/sparql/algebra.rb

@@ -1,4 +1,4 @@
-require 'rdf' # @see http://rubygems.org/gems/rdf
+require 'rdf' # @see https://rubygems.org/gems/rdf
 require 'rdf/xsd'
 
 module SPARQL
@@ -141,21 +141,21 @@ module SPARQL
   # ## Constructing operator expressions manually
   # 
   #     Operator(:isBlank).new(RDF::Node(:foobar)).to_sxp                        #=> "(isBlank _:foobar)"
-  #     Operator(:isIRI).new(RDF::URI('http://rubygems.org/gems/rdf/')).to_sxp       #=> "(isIRI <http://rubygems.org/gems/rdf/>)"
+  #     Operator(:isIRI).new(RDF::URI('https://rubygems.org/gems/rdf/')).to_sxp       #=> "(isIRI <https://rubygems.org/gems/rdf/>)"
   #     Operator(:isLiteral).new(RDF::Literal(3.1415)).to_sxp                    #=> "(isLiteral 3.1415)"
   #     Operator(:str).new(Operator(:datatype).new(RDF::Literal(3.1415))).to_sxp #=> "(str (datatype 3.1415))"
   # 
   # ## Constructing operator expressions using SSE forms
   # 
   #     SPARQL::Algebra::Expression[:isBlank, RDF::Node(:foobar)].to_sxp                          #=> "(isBlank _:foobar)"
-  #     SPARQL::Algebra::Expression[:isIRI, RDF::URI('http://rubygems.org/gems/rdf/')].to_sxp         #=> "(isIRI <http://rubygems.org/gems/rdf/>)"
+  #     SPARQL::Algebra::Expression[:isIRI, RDF::URI('https://rubygems.org/gems/rdf/')].to_sxp         #=> "(isIRI <https://rubygems.org/gems/rdf/>)"
   #     SPARQL::Algebra::Expression[:isLiteral, RDF::Literal(3.1415)].to_sxp                      #=> "(isLiteral 3.1415)"
   #     SPARQL::Algebra::Expression[:str, [:datatype, RDF::Literal(3.1415)]].to_sxp               #=> "(str (datatype 3.1415))"
   # 
   # ## Constructing operator expressions using SSE strings
   # 
   #     SPARQL::Algebra::Expression.parse('(isBlank _:foobar)')
-  #     SPARQL::Algebra::Expression.parse('(isIRI <http://rubygems.org/gems/rdf/>)')
+  #     SPARQL::Algebra::Expression.parse('(isIRI <https://rubygems.org/gems/rdf/>)')
   #     SPARQL::Algebra::Expression.parse('(isLiteral 3.1415)')
   #     SPARQL::Algebra::Expression.parse('(str (datatype 3.1415))')
   # 
@@ -165,11 +165,6 @@ module SPARQL
   #     Operator(:isIRI).evaluate(RDF::Vocab::DC.title)                                 #=> RDF::Literal::TRUE
   #     Operator(:isLiteral).evaluate(RDF::Literal(3.1415))                      #=> RDF::Literal::TRUE
   # 
-  # ## Optimizing expressions containing constant subexpressions
-  # 
-  #     SPARQL::Algebra::Expression.parse('(sameTerm ?var ?var)').optimize            #=> RDF::Literal::TRUE
-  #     SPARQL::Algebra::Expression.parse('(* -2 (- (* (+ 1 2) (+ 3 4))))').optimize  #=> RDF::Literal(42)
-  # 
   # ## Evaluating expressions on a solution sequence
   # 
   #     # Find all people and their names & e-mail addresses:
@@ -405,8 +400,7 @@ module SPARQL
     def Expression(*sse)
       Expression.for(*sse)
     end
-    alias_method :Expr, :Expression
-    module_function :Expr, :Expression
+    module_function :Expression
 
     ##
     # @example
@@ -417,8 +411,7 @@ module SPARQL
     def Operator(name, arity = nil)
       Operator.for(name, arity)
     end
-    alias_method :Op, :Operator
-    module_function :Op, :Operator
+    module_function :Operator
 
     ##
     # @example
@@ -430,8 +423,7 @@ module SPARQL
     def Variable(name)
       Variable.new(name)
     end
-    alias_method :Var, :Variable
-    module_function :Var, :Variable
+    module_function :Variable
 
     Variable = RDF::Query::Variable
   end # Algebra

data/lib/sparql/algebra/aggregate.rb

@@ -6,8 +6,8 @@ module SPARQL; module Algebra
   # or more operands which are `Enumerable` lists of `RDF::Term`
   # and return a single `RDF::Term` or `TypeError`.
   #
-  # @see http://www.w3.org/TR/sparql11-query/#setFunctions
-  # @see http://www.w3.org/TR/sparql11-query/#aggregates
+  # @see https://www.w3.org/TR/sparql11-query/#setFunctions
+  # @see https://www.w3.org/TR/sparql11-query/#aggregates
   #
   # @abstract
   module Aggregate

data/lib/sparql/algebra/expression.rb

@@ -21,7 +21,7 @@ module SPARQL; module Algebra
     # @return [Expression]
     def self.parse(sse, **options, &block)
       begin
-        require 'sxp' # @see http://rubygems.org/gems/sxp
+        require 'sxp' # @see https://rubygems.org/gems/sxp
       rescue LoadError
         abort "SPARQL::Algebra::Expression.parse requires the SXP gem (hint: `gem install sxp')."
       end
@@ -175,8 +175,8 @@ module SPARQL; module Algebra
     # @param [RDF::URI] function
     # @param [Array<RDF::Term>] args splat of args to function
     # @return [RDF::Term]
-    # @see http://www.w3.org/TR/sparql11-query/#extensionFunctions
-    # @see http://www.w3.org/TR/sparql11-query/#FunctionMapping
+    # @see https://www.w3.org/TR/sparql11-query/#extensionFunctions
+    # @see https://www.w3.org/TR/sparql11-query/#FunctionMapping
     def self.extension(function, *args)
       if function.to_s.start_with?(RDF::XSD.to_s)
         self.cast(function, args.first)
@@ -197,7 +197,7 @@ module SPARQL; module Algebra
     #   Value, which should be a typed literal, where the type must be that specified
     # @raise [TypeError] if datatype is not a URI or value cannot be cast to datatype
     # @return [RDF::Term]
-    # @see http://www.w3.org/TR/sparql11-query/#FunctionMapping
+    # @see https://www.w3.org/TR/sparql11-query/#FunctionMapping
     def self.cast(datatype, value)
       case datatype
       when RDF::XSD.dateTime
@@ -280,12 +280,26 @@ module SPARQL; module Algebra
     ##
     # Returns an optimized version of this expression.
     #
-    # This is the default implementation, which simply returns `self`.
+    # This is the default implementation, which simply returns a copy of `self`.
     # Subclasses can override this method in order to implement something
     # more useful.
     #
-    # @return [Expression] `self`
-    def optimize
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options for optimization
+    # @return [Expression] a copy of `self`
+    # @see    RDF::Query#optimize
+    def optimize(**options)
+      self.deep_dup.optimize!(**options)
+    end
+
+    ##
+    # Optimizes this query.
+    #
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options for optimization
+    # @return [self]
+    # @see    RDF::Query#optimize!
+    def optimize!(**options)
       self
     end
 
@@ -313,7 +327,7 @@ module SPARQL; module Algebra
     # more useful.
     #
     # @return [Array] `self`
-    # @see    http://openjena.org/wiki/SSE
+    # @see    https://openjena.org/wiki/SSE
     def to_sxp_bin
       self
     end

data/lib/sparql/algebra/extensions.rb

@@ -27,6 +27,22 @@ class Object
   def to_sse
     SXP::Generator.string(self.to_sxp_bin)
   end
+
+  ##
+  # A duplicate of this object.
+  #
+  # @return [Object] a copy of `self`
+  # @see SPARQL::Algebra::Expression#optimize
+  def optimize(**options)
+    self.deep_dup
+  end
+
+  ##
+  # Default for deep_dup is shallow dup
+  # @return [Object]
+  def deep_dup
+    dup
+  end
 end
 
 ##
@@ -66,11 +82,34 @@ class Array
   # @param  [Hash{Symbol => Object}] options
   # @raise [NotImplementedError]
   #   If an attempt is made to perform an unsupported operation
-  # @see    http://www.w3.org/TR/sparql11-query/#sparqlAlgebra
+  # @see    https://www.w3.org/TR/sparql11-query/#sparqlAlgebra
   def execute(queryable, **options)
     raise NotImplementedError, "SPARQL::Algebra '#{first}' operator not implemented"
   end
 
+  ##
+  # Return an optimized version of this array.
+  #
+  # @return [Array] a copy of `self`
+  # @see SPARQL::Algebra::Expression#optimize
+  def optimize(**options)
+    self.map do |op|
+      op.optimize(**options) if op.respond_to?(:optimize)
+    end
+  end
+
+  ##
+  # Binds the pattern to a solution, making it no longer variable if all variables are resolved to bound variables
+  #
+  # @param [RDF::Query::Solution] solution
+  # @return [self]
+  def bind(solution)
+    map! do |op|
+      op.respond_to?(:bind) ? op.bind(solution) : op
+    end
+    self
+  end
+
   ##
   # Returns `true` if any of the operands are variables, `false`
   # otherwise.
@@ -78,7 +117,7 @@ class Array
   # @return [Boolean] `true` or `false`
   # @see    #constant?
   def variable?
-    any?(&:variable?)
+    any? {|op| op.respond_to?(:variable?) && op.variable?}
   end
   def constant?; !(variable?); end
 
@@ -166,6 +205,12 @@ class Array
     each {|e| e.validate! if e.respond_to?(:validate!)}
     self
   end
+
+  ##
+  # Deep duplicate
+  def deep_dup
+    map(&:deep_dup)
+  end
 end
 
 ##
@@ -179,6 +224,21 @@ class Hash
     to_a.to_sxp_bin
   end
   def to_sxp; to_sxp_bin; end
+
+  ##
+  # A duplicate of this hash.
+  #
+  # @return [Hash] a copy of `self`
+  # @see SPARQL::Algebra::Expression#optimize
+  def optimize(**options)
+    self.deep_dup
+  end
+
+  ##
+  # Deep duplicate
+  def deep_dup
+    inject({}) {|memo, (k, v)| memo.merge(k => v.deep_dup)}
+  end
 end
 
 ##
@@ -210,6 +270,17 @@ module RDF::Term
   def vars
     variable? ? [self] : []
   end
+
+  ##
+  # A duplicate of this term.
+  #
+  # @return [RDF::Term] a copy of `self`
+  # @see SPARQL::Algebra::Expression#optimize
+  def optimize(**options)
+    optimized = self.deep_dup
+    optimized.lexical = nil if optimized.respond_to?(:lexical=)
+    optimized
+  end
 end # RDF::Term
 
 # Override RDF::Queryable to execute against SPARQL::Algebra::Query elements as well as RDF::Query and RDF::Pattern
@@ -258,7 +329,6 @@ module RDF::Queryable
       query_without_sparql(pattern, **options, &block)
     end
   end
-  
 end
 
 class RDF::Statement
@@ -271,6 +341,15 @@ class RDF::Statement
       [:triple, subject, predicate, object]
     end
   end
+
+  ##
+  # A duplicate of this Statement.
+  #
+  # @return [RDF::Statement] a copy of `self`
+  # @see SPARQL::Algebra::Expression#optimize
+  def optimize(**options)
+    self.dup
+  end
 end
 
 class RDF::Query
@@ -306,6 +385,16 @@ class RDF::Query
     end
   end
 
+  ##
+  # Binds the pattern to a solution, making it no longer variable if all variables are resolved to bound variables
+  #
+  # @param [RDF::Query::Solution] solution
+  # @return [self]
+  def bind(solution)
+    patterns.each {|p| p.bind(solution)}
+    self
+  end
+
   # Query results in a boolean result (e.g., ASK)
   # @return [Boolean]
   def query_yields_boolean?
@@ -338,6 +427,27 @@ class RDF::Query
     variables.values
   end
 
+  ##
+  # Optimize the query, removing lexical shortcuts in URIs
+  #
+  # @return [self]
+  # @see SPARQL::Algebra::Expression#optimize!
+  def optimize!(**options)
+    @patterns = @patterns.map do |pattern|
+      components = pattern.to_a.map do |term|
+        if term.respond_to?(:lexical=)
+          term.dup.instance_eval {@lexical = nil; self}
+        else
+          term
+        end
+      end
+      RDF::Query::Pattern.from(components)
+    end.sort! do |a, b|
+      (a.cost || 0) <=> (b.cost || 0)
+    end
+    self
+  end
+
   ##
   # Returns `true` if this is executable (i.e., contains a graph patterns), `false`
   # otherwise.
@@ -390,6 +500,15 @@ class RDF::Query::Variable
     raise TypeError if bindings.respond_to?(:bound?) && !bindings.bound?(self)
     bindings[name.to_sym]
   end
+
+  ##
+  # Return self
+  #
+  # @return [RDF::Query::Variable] a copy of `self`
+  # @see SPARQL::Algebra::Expression#optimize
+  def optimize(**options)
+    self
+  end
 end # RDF::Query::Variable
 
 ##
@@ -419,3 +538,16 @@ class RDF::Query::Solutions
   end
   alias_method :filter!, :filter
 end # RDF::Query::Solutions
+
+##
+# Extensions for `RDF::Query::Solution`.
+class RDF::Query::Solution
+  ##
+  # Returns the SXP representation of this object, defaults to `self`.
+  #
+  # @return [String]
+  def to_sxp_bin
+    to_a.to_sxp_bin
+  end
+  def to_sxp; to_sxp_bin; end
+end # RDF::Query::Solution

data/lib/sparql/algebra/operator.rb

@@ -146,8 +146,6 @@ module SPARQL; module Algebra
     autoload :Using,              'sparql/algebra/operator/using'
     autoload :With,               'sparql/algebra/operator/with'
 
-
-
     ##
     # Returns an operator class for the given operator `name`.
     #
@@ -357,6 +355,22 @@ module SPARQL; module Algebra
       end
     end
 
+    ##
+    # Deep duplicate operands
+    def deep_dup
+      self.class.new(*operands.map(&:deep_dup))
+    end
+
+    ##
+    # Binds the pattern to a solution, making it no longer variable if all variables are resolved to bound variables
+    #
+    # @param [RDF::Query::Solution] solution
+    # @return [self]
+    def bind(solution)
+      @operands.each {|op| op.bind(solution)}
+      self
+    end
+
     ##
     # Base URI used for reading data sources with relative URIs
     #
@@ -434,7 +448,7 @@ module SPARQL; module Algebra
     # @return [Boolean] `true` or `false`
     # @see    #constant?
     def variable?
-      operands.any?(&:variable?)
+      operands.any? {|op| op.respond_to?(:variable?) && op.variable?}
     end
 
     ##
@@ -491,21 +505,35 @@ module SPARQL; module Algebra
     #
     # For constant expressions containing no variables, returns the result
     # of evaluating the expression with empty bindings; otherwise returns
-    # `self`.
+    # a copy of `self`.
     #
     # Optimization is not possible if the expression raises an exception,
     # such as a `TypeError` or `ZeroDivisionError`, which must be conserved
     # at runtime.
     #
     # @return [SPARQL::Algebra::Expression]
-    def optimize
+    # @see    RDF::Query#optimize
+    def optimize(**options)
       if constant?
         # Note that if evaluation results in a `TypeError` or other error,
         # we must return `self` so that the error is conserved at runtime:
         evaluate(RDF::Query::Solution.new) rescue self
       else
-        super # returns `self`
+        super # returns a copy of `self`
+      end
+    end
+
+    ##
+    # Optimizes this query by optimizing its constituent operands
+    # according to their cost estimates.
+    #
+    # @return [self]
+    # @see    RDF::Query#optimize!
+    def optimize!(**options)
+      @operands.map! do |op|
+        op.optimize(**options) if op.respond_to?(:optimize)
       end
+      self
     end
 
     ##
@@ -532,7 +560,7 @@ module SPARQL; module Algebra
     # Returns the SPARQL S-Expression (SSE) representation of this operator.
     #
     # @return [Array]
-    # @see    http://openjena.org/wiki/SSE
+    # @see    https://openjena.org/wiki/SSE
     def to_sxp_bin
       operator = [self.class.const_get(:NAME)].flatten.first
       [operator, *(operands || []).map(&:to_sxp_bin)]
@@ -544,7 +572,7 @@ module SPARQL; module Algebra
     # @return [String]
     def to_sxp
       begin
-        require 'sxp' # @see http://rubygems.org/gems/sxp
+        require 'sxp' # @see https://rubygems.org/gems/sxp
       rescue LoadError
         abort "SPARQL::Algebra::Operator#to_sxp requires the SXP gem (hint: `gem install sxp')."
       end
@@ -647,7 +675,7 @@ module SPARQL; module Algebra
     # @param  [RDF::Literal] literal
     # @return [RDF::Literal::Boolean] `true` or `false`
     # @raise  [TypeError] if the literal could not be coerced to an `RDF::Literal::Boolean`
-    # @see    http://www.w3.org/TR/sparql11-query/#ebv
+    # @see    https://www.w3.org/TR/sparql11-query/#ebv
     def boolean(literal)
       case literal
         when FalseClass then RDF::Literal::FALSE