sparql 3.2.0 → 3.2.4

data/lib/sparql/algebra/operator.rb

@@ -55,12 +55,14 @@ module SPARQL; module Algebra
     autoload :Timezone,           'sparql/algebra/operator/timezone'
     autoload :TZ,                 'sparql/algebra/operator/tz'
     autoload :Year,               'sparql/algebra/operator/year'
+    autoload :Triple,             'sparql/algebra/operator/triple'
     autoload :IsTriple,           'sparql/algebra/operator/is_triple'
     autoload :Subject,            'sparql/algebra/operator/subject'
     autoload :Predicate,          'sparql/algebra/operator/predicate'
     autoload :Object,             'sparql/algebra/operator/object'
 
     # Binary operators
+    autoload :Adjust,             'sparql/algebra/operator/adjust'
     autoload :And,                'sparql/algebra/operator/and'
     autoload :Compare,            'sparql/algebra/operator/compare'
     autoload :Concat,             'sparql/algebra/operator/concat'
@@ -95,7 +97,9 @@ module SPARQL; module Algebra
     autoload :NotOneOf,           'sparql/algebra/operator/notoneof'
     autoload :PathOpt,            'sparql/algebra/operator/path_opt'
     autoload :PathPlus,           'sparql/algebra/operator/path_plus'
+    autoload :PathRange,          'sparql/algebra/operator/path_range'
     autoload :PathStar,           'sparql/algebra/operator/path_star'
+    autoload :PathZero,            'sparql/algebra/operator/path_zero'
     autoload :Path,               'sparql/algebra/operator/path'
     autoload :Reverse,            'sparql/algebra/operator/reverse'
     autoload :Seq,                'sparql/algebra/operator/seq'
@@ -106,6 +110,7 @@ module SPARQL; module Algebra
     autoload :Coalesce,           'sparql/algebra/operator/coalesce'
     autoload :Desc,               'sparql/algebra/operator/desc'
     autoload :Exprlist,           'sparql/algebra/operator/exprlist'
+    autoload :FunctionCall,       'sparql/algebra/operator/function_call'
     autoload :GroupConcat,        'sparql/algebra/operator/group_concat'
     autoload :In,                 'sparql/algebra/operator/in'
     autoload :NotIn,              'sparql/algebra/operator/notin'
@@ -129,6 +134,7 @@ module SPARQL; module Algebra
     autoload :Prefix,             'sparql/algebra/operator/prefix'
     autoload :Project,            'sparql/algebra/operator/project'
     autoload :Reduced,            'sparql/algebra/operator/reduced'
+    autoload :Service,            'sparql/algebra/operator/service'
     autoload :Slice,              'sparql/algebra/operator/slice'
     autoload :Table,              'sparql/algebra/operator/table'
     autoload :Union,              'sparql/algebra/operator/union'
@@ -172,6 +178,7 @@ module SPARQL; module Algebra
         when :>               then GreaterThan
         when :>=              then GreaterThanOrEqual
         when :abs             then Abs
+        when :adjust          then Adjust
         when :alt             then Alt
         when :and, :'&&'      then And
         when :avg             then Avg
@@ -214,9 +221,11 @@ module SPARQL; module Algebra
         when :now             then Now
         when :or, :'||'       then Or
         when :path            then Path
+        when :path0           then PathZero
         when :path?           then PathOpt
-        when :"path*"         then PathStar
         when :"path+"         then PathPlus
+        when :"path*"         then PathStar
+        when :pathrange       then PathRange
         when :plus            then Plus
         when :rand            then Rand
         when :regex           then Regex
@@ -228,6 +237,7 @@ module SPARQL; module Algebra
         when :seconds         then Seconds
         when :seq             then Seq
         when :sequence        then Sequence
+        when :service         then Service
         when :sha1            then SHA1
         when :sha256          then SHA256
         when :sha384          then SHA384
@@ -254,6 +264,7 @@ module SPARQL; module Algebra
         when :asc             then Asc
         when :desc            then Desc
         when :exprlist        then Exprlist
+        when :function_call   then FunctionCall
 
         # Datasets
         when :dataset         then Dataset
@@ -300,7 +311,9 @@ module SPARQL; module Algebra
 
         # RDF-star
         when :istriple        then IsTriple
-        when :triple          then RDF::Query::Pattern
+        when :triple          then Triple
+        when :qtriple         then RDF::Query::Pattern
+        when :quad            then RDF::Query::Pattern
         when :subject         then Subject
         when :predicate       then Predicate
         when :object          then Object
@@ -336,31 +349,41 @@ module SPARQL; module Algebra
     # Generate a top-level Grammar, using collected options
     #
     # @param [String] content
-    # @param [Hash{Symbol => Operator}] extensions
-    #   Variable bindings
+    # @param [Operator] datasets ([])
     # @param [Operator] distinct (false)
+    # @param [Hash{String => Operator}] extensions
+    #   Variable bindings
     # @param [Array<Operator>] filter_ops ([])
     #   Filter Operations
     # @param [Integer] limit (nil)
     # @param [Array<Operator>] group_ops ([])
+    # @param [Array<Operator>] having_ops ([])
     # @param [Integer] offset (nil)
     # @param [Array<Operator>] order_ops ([])
     #   Order Operations
     # @param [Array<Symbol,Operator>] project (%i(*))
     #   Terms to project
     # @param [Operator] reduced (false)
+    # @param [Operator] values_clause (nil)
+    #   Top-level Values clause
+    # @param [Operator] where_clause (true)
+    #   Emit 'WHERE' before GroupGraphPattern
     # @param [Hash{Symbol => Object}] options
     # @return [String]
     def self.to_sparql(content,
+                       datasets: [],
                        distinct: false,
                        extensions: {},
                        filter_ops: [],
                        group_ops: [],
+                       having_ops: [],
                        limit: nil,
                        offset: nil,
                        order_ops: [],
                        project: %i(*),
                        reduced: false,
+                       values_clause: nil,
+                       where_clause: true,
                        **options)
       str = ""
 
@@ -371,29 +394,41 @@ module SPARQL; module Algebra
         str << "REDUCED " if reduced
 
         str << project.map do |p|
-          if expr = extensions.delete(p)
+          if expr = extensions.delete(p.to_s)
+            v = expr.to_sparql(**options)
+            pp = RDF::Query::Variable.new(p).to_sparql(**options)
             # Replace projected variables with their extension, if any
-            "(" + [expr, :AS, p].to_sparql(**options) + ")"
+            '(' + v + ' AS ' + pp + ')'
           else
             p.to_sparql(**options)
           end
         end.join(" ") + "\n"
       end
 
-      # Extensions
+      # DatasetClause
+      datasets.each do |ds|
+        str << "FROM #{ds.to_sparql(**options)}\n"
+      end
+
+      # Bind
       extensions.each do |as, expression|
-        content << "\nBIND (#{expression.to_sparql(**options)} AS #{as.to_sparql(**options)}) ."
+        v = expression.to_sparql(**options)
+        pp = RDF::Query::Variable.new(as).to_sparql(**options)
+        content << "\nBIND (" << v << " AS " << pp << ") ."
       end
 
-      # Filters
+      # Filter
       filter_ops.each do |f|
-        content << "\nFILTER #{f.to_sparql(**options)} ."
+        content << "\nFILTER (#{f.to_sparql(**options)}) ."
       end
 
-      # Where clause
-      str << "WHERE {\n#{content}\n}\n"
+      # WhereClause / GroupGraphPattern
+      str << (where_clause ? "WHERE {\n#{content}\n}\n" : "{\n#{content}\n}\n")
 
-      # Group
+      ##
+      # SolutionModifier
+      #
+      # GroupClause
       unless group_ops.empty?
         ops = group_ops.map do |o|
           # Replace projected variables with their extension, if any
@@ -404,14 +439,22 @@ module SPARQL; module Algebra
         str << "GROUP BY #{ops.join(' ')}\n"
       end
 
-      # Order
+      # HavingClause
+      unless having_ops.empty?
+        str << "HAVING #{having_ops.to_sparql(**options)}"
+      end
+
+      # OrderClause
       unless order_ops.empty?
         str << "ORDER BY #{order_ops.to_sparql(**options)}\n"
       end
 
-      # Offset and Limmit
+      # LimitOffsetClauses
       str << "OFFSET #{offset}\n" unless offset.nil?
       str << "LIMIT #{limit}\n" unless limit.nil?
+
+      # Values Clause
+      str << values_clause.to_sparql(top_level: false, **options) if values_clause
       str
     end
 
@@ -640,12 +683,8 @@ module SPARQL; module Algebra
     # @return [SPARQL::Algebra::Expression] `self`
     def rewrite(&block)
       @operands = @operands.map do |op|
-        # Rewrite the operand
-        unless new_op = block.call(op)
-          # Not re-written, rewrite
-          new_op = op.respond_to?(:rewrite) ? op.rewrite(&block) : op
-        end
-        new_op
+        new_op = block.call(op)
+        new_op.respond_to?(:rewrite) ? new_op.rewrite(&block) : new_op
       end
       self
     end
@@ -671,7 +710,6 @@ module SPARQL; module Algebra
     end
 
     ##
-    #
     # Returns a partial SPARQL grammar for the operator.
     #
     # @return [String]
@@ -765,6 +803,15 @@ module SPARQL; module Algebra
       operands.each {|op| op.validate! if op.respond_to?(:validate!)}
       self
     end
+
+    ##
+    # The variables used in this query.
+    #
+    # @return [Hash{Symbol => RDF::Query::Variable}]
+    def variables
+      operands.inject({}) {|hash, o| o.respond_to?(:variables) ? hash.merge(o.variables) : hash}
+    end
+
   protected
 
     ##

data/lib/sparql/algebra/query.rb

@@ -16,13 +16,13 @@ module SPARQL; module Algebra
       @operands.unshift(query)
       self
     end
-    
+
     ##
     # The variables used in this query.
     #
     # @return [Hash{Symbol => RDF::Query::Variable}]
     def variables
-      operands.inject({}) {|hash, o| o.executable? ? hash.merge(o.variables) : hash}
+      operands.inject({}) {|hash, o| o.respond_to?(:variables) ? hash.merge(o.variables) : hash}
     end
 
     ##
@@ -38,7 +38,9 @@ module SPARQL; module Algebra
     #   the graph or repository to query
     # @param  [Hash{Symbol => Object}] options
     #   any additional keyword options
-    # @option options [Boolean] debug
+    # @option options  [RDF::Query::Solution] :bindings
+    #   a query solution containing zero or more variable bindings
+    # @option options [Boolean] :debug
     #   Query execution debugging
     # @option options [RDF::Term, RDF::Query::Variable] :graph_name
     # @yield  [solution]

data/lib/sparql/algebra.rb

@@ -19,6 +19,24 @@ module SPARQL
   #
   # {RDF::Query} and {RDF::Query::Pattern} are used as primitives for `bgp` and `triple` expressions.
   #
+  # # Background
+  #
+  # The SPARQL Algebra, and the S-Expressions used to represent it, are based on those of [Jena](https://jena.apache.org/documentation/notes/sse.html). Generally, an S-Expression generated by this Gem can be used as an SSE input to Jena, or an SSE output from Jena can also be used as input to this Gem.
+  #
+  # S-Expressions generally follow a standardized nesting resulting from parsing the original SPARQL Grammar. The individual operators map to SPARQL Grammar productions, and in most cases, the SPARQL Grammar can be reproduced by turning the S-Expression back into SPARQL (see {SPARQL::Algebra::Operator#to_sparql}). The order of operations will typically be as follows:
+  #
+  #  * {SPARQL::Algebra::Operator::Base}
+  #  * {SPARQL::Algebra::Operator::Prefix}
+  #  * {SPARQL::Algebra::Operator::Slice}
+  #  * {SPARQL::Algebra::Operator::Distinct}
+  #  * {SPARQL::Algebra::Operator::Reduced}
+  #  * {SPARQL::Algebra::Operator::Project}
+  #  * {SPARQL::Algebra::Operator::Order}
+  #  * {SPARQL::Algebra::Operator::Filter}
+  #  * {SPARQL::Algebra::Operator::Extend}
+  #  * {SPARQL::Algebra::Operator::Group}
+  #  * {SPARQL::Algebra::Query} (many classes implement Query)
+  #
   # # Queries
   # 
   #     require 'sparql/algebra'
@@ -215,7 +233,7 @@ module SPARQL
   # scarcity.
   # 
   # [memoization]:      http://en.wikipedia.org/wiki/Memoization
-  # [RDF::Util::Cache]: http://www.rubydoc.info/github/ruby-rdf/rdf/RDF/Util/Cache
+  # [RDF::Util::Cache]: https://ruby-rdf.github.io/rdf/RDF/Util/Cache
   # 
   # ## Documentation
   # 
@@ -228,12 +246,15 @@ module SPARQL
   #   * {SPARQL::Algebra::Operator}
   #     * {SPARQL::Algebra::Operator::Abs}
   #     * {SPARQL::Algebra::Operator::Add}
+  #     * {SPARQL::Algebra::Operator::Adjust}
+  #     * {SPARQL::Algebra::Operator::Alt}
   #     * {SPARQL::Algebra::Operator::And}
   #     * {SPARQL::Algebra::Operator::Asc}
   #     * {SPARQL::Algebra::Operator::Ask}
   #     * {SPARQL::Algebra::Operator::Avg}
   #     * {SPARQL::Algebra::Operator::Base}
   #     * {SPARQL::Algebra::Operator::BGP}
+  #     * {SPARQL::Algebra::Operator::Bnode}
   #     * {SPARQL::Algebra::Operator::Bound}
   #     * {SPARQL::Algebra::Operator::Ceil}
   #     * {SPARQL::Algebra::Operator::Clear}
@@ -248,9 +269,9 @@ module SPARQL
   #     * {SPARQL::Algebra::Operator::Dataset}
   #     * {SPARQL::Algebra::Operator::Datatype}
   #     * {SPARQL::Algebra::Operator::Day}
-  #     * {SPARQL::Algebra::Operator::Delete}
   #     * {SPARQL::Algebra::Operator::DeleteData}
   #     * {SPARQL::Algebra::Operator::DeleteWhere}
+  #     * {SPARQL::Algebra::Operator::Delete}
   #     * {SPARQL::Algebra::Operator::Desc}
   #     * {SPARQL::Algebra::Operator::Describe}
   #     * {SPARQL::Algebra::Operator::Distinct}
@@ -258,10 +279,12 @@ module SPARQL
   #     * {SPARQL::Algebra::Operator::Drop}
   #     * {SPARQL::Algebra::Operator::EncodeForURI}
   #     * {SPARQL::Algebra::Operator::Equal}
+  #     * {SPARQL::Algebra::Operator::Exists}
   #     * {SPARQL::Algebra::Operator::Exprlist}
   #     * {SPARQL::Algebra::Operator::Extend}
   #     * {SPARQL::Algebra::Operator::Filter}
   #     * {SPARQL::Algebra::Operator::Floor}
+  #     * {SPARQL::Algebra::Operator::FunctionCall}
   #     * {SPARQL::Algebra::Operator::Graph}
   #     * {SPARQL::Algebra::Operator::GreaterThan}
   #     * {SPARQL::Algebra::Operator::GreaterThanOrEqual}
@@ -277,9 +300,11 @@ module SPARQL
   #     * {SPARQL::Algebra::Operator::IsIRI}
   #     * {SPARQL::Algebra::Operator::IsLiteral}
   #     * {SPARQL::Algebra::Operator::IsNumeric}
+  #     * {SPARQL::Algebra::Operator::IsTriple}
   #     * {SPARQL::Algebra::Operator::Join}
   #     * {SPARQL::Algebra::Operator::Lang}
   #     * {SPARQL::Algebra::Operator::LangMatches}
+  #     * {SPARQL::Algebra::Operator::LCase}
   #     * {SPARQL::Algebra::Operator::LeftJoin}
   #     * {SPARQL::Algebra::Operator::LessThan}
   #     * {SPARQL::Algebra::Operator::LessThanOrEqual}
@@ -297,20 +322,32 @@ module SPARQL
   #     * {SPARQL::Algebra::Operator::NotEqual}
   #     * {SPARQL::Algebra::Operator::NotExists}
   #     * {SPARQL::Algebra::Operator::NotIn}
+  #     * {SPARQL::Algebra::Operator::NotOneOf}
   #     * {SPARQL::Algebra::Operator::Now}
+  #     * {SPARQL::Algebra::Operator::Object}
   #     * {SPARQL::Algebra::Operator::Or}
   #     * {SPARQL::Algebra::Operator::Order}
+  #     * {SPARQL::Algebra::Operator::Path}
+  #     * {SPARQL::Algebra::Operator::PathOpt}
+  #     * {SPARQL::Algebra::Operator::PathPlus}
+  #     * {SPARQL::Algebra::Operator::PathRange}
+  #     * {SPARQL::Algebra::Operator::PathStar}
+  #     * {SPARQL::Algebra::Operator::PathZero}
   #     * {SPARQL::Algebra::Operator::Plus}
+  #     * {SPARQL::Algebra::Operator::Predicate}
   #     * {SPARQL::Algebra::Operator::Prefix}
   #     * {SPARQL::Algebra::Operator::Project}
   #     * {SPARQL::Algebra::Operator::Rand}
   #     * {SPARQL::Algebra::Operator::Reduced}
   #     * {SPARQL::Algebra::Operator::Regex}
   #     * {SPARQL::Algebra::Operator::Replace}
+  #     * {SPARQL::Algebra::Operator::Reverse}
   #     * {SPARQL::Algebra::Operator::Round}
   #     * {SPARQL::Algebra::Operator::SameTerm}
   #     * {SPARQL::Algebra::Operator::Sample}
   #     * {SPARQL::Algebra::Operator::Seconds}
+  #     * {SPARQL::Algebra::Operator::Seq}
+  #     * {SPARQL::Algebra::Operator::Sequence}
   #     * {SPARQL::Algebra::Operator::SHA1}
   #     * {SPARQL::Algebra::Operator::SHA256}
   #     * {SPARQL::Algebra::Operator::SHA384}
@@ -330,6 +367,7 @@ module SPARQL
   #     * {SPARQL::Algebra::Operator::Sum}
   #     * {SPARQL::Algebra::Operator::Table}
   #     * {SPARQL::Algebra::Operator::Timezone}
+  #     * {SPARQL::Algebra::Operator::Triple}
   #     * {SPARQL::Algebra::Operator::TZ}
   #     * {SPARQL::Algebra::Operator::Ucase}
   #     * {SPARQL::Algebra::Operator::Union}
@@ -339,11 +377,9 @@ module SPARQL
   #     * {SPARQL::Algebra::Operator::With}
   #     * {SPARQL::Algebra::Operator::Year}
   # 
-  # TODO
-  # ====
-  # * Operator#optimize needs to be completed and tested.
   # 
   # @see http://www.w3.org/TR/sparql11-query/#sparqlAlgebra
+  # @see https://jena.apache.org/documentation/notes/sse.html
   module Algebra
     include RDF
 
@@ -419,7 +455,7 @@ module SPARQL
     #
     # @param  [Symbol, #to_sym] name
     # @return [Variable]
-    # @see    http://www.rubydoc.info/github/ruby-rdf/rdf/RDF/Query/Variable
+    # @see    https://ruby-rdf.github.io/rdf/RDF/Query/Variable
     def Variable(name)
       Variable.new(name)
     end