sparql 3.1.8 → 3.2.3

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

@@ -73,7 +73,7 @@ module SPARQL; module Algebra
     # @example Dataset with two default data sources
     #
     #     (prefix ((: <http://example/>))
-    #       (dataset (<data-g1.ttl> <data-g1.ttl)
+    #       (dataset (<data-g1.ttl> <data-g2.ttl)
     #         (bgp (triple ?s ?p ?o))))
     #
     #     is effectively re-written to the following:
@@ -101,7 +101,21 @@ module SPARQL; module Algebra
     #       (filter ((= ?g <data-g1.ttl>) || (= ?g <data-g2.ttl>))
     #         (graph ?g (bgp (triple ?s ?p ?o))))))
     #
-    # @example Dataset with multiple named graphs
+    #
+    # @example SPARQL Grammar
+    #   BASE     <http://example.org/>
+    #   PREFIX : <http://example.com/>
+    #   
+    #   SELECT * 
+    #   FROM <data-g1.ttl>
+    #   { ?s ?p ?o }
+    #
+    # @example SSE
+    #   (base <http://example.org/>
+    #    (prefix ((: <http://example.com/>))
+    #     (dataset (<data-g1.ttl>)
+    #      (bgp (triple ?s ?p ?o)))))
+    #
     # @see https://www.w3.org/TR/sparql11-query/#specifyingDataset
     class Dataset < Binary
       include Query
@@ -115,6 +129,11 @@ module SPARQL; module Algebra
       #
       # Datasets are specified in operand(1), which is an array of default or named graph URIs.
       #
+      # If `options` contains any of the Protocol attributes, the dataset is constructed on creation, and these operations should be ignored:
+      #
+      # * `default-graph-uri`
+      # * `named-graph-uri`
+      #
       # @param  [RDF::Queryable] queryable
       #   the graph or repository to query
       # @param  [Hash{Symbol => Object}] options
@@ -128,6 +147,11 @@ module SPARQL; module Algebra
       # @see    https://www.w3.org/TR/sparql11-query/#sparqlAlgebra
       def execute(queryable, **options, &base)
         debug(options) {"Dataset"}
+        if %i(default-graph-uri named-graph-uri).any? {|k| options.key?(k)} 
+          debug("=> Skip constructing merge repo due to options", options)
+          return queryable.query(operands.last, depth: options[:depth].to_i + 1, **options, &base)
+        end
+ 
         default_datasets = []
         named_datasets = []
         operand(0).each do |uri|
@@ -158,6 +182,17 @@ module SPARQL; module Algebra
         aggregate.default(*default_datasets.select {|name| queryable.has_graph?(name)})
         aggregate.query(operands.last, depth: options[:depth].to_i + 1, **options, &base)
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # Extracts datasets
+      #
+      # @return [String]
+      def to_sparql(**options)
+        operands.last.to_sparql(datasets: operands.first, **options)
+      end
     end # Dataset
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -3,13 +3,23 @@ module SPARQL; module Algebra
     ##
     # The SPARQL `datatype` operator.
     #
-    # @example
+    # [121] BuiltInCall ::= ... | 'DATATYPE' '(' Expression ')' 
+    #
+    # @example SPARQL Grammar
+    #   PREFIX  xsd: <http://www.w3.org/2001/XMLSchema#>
+    #   PREFIX  : <http://example.org/things#>
+    #   SELECT  ?x ?v
+    #   WHERE
+    #       { ?x :p ?v . 
+    #         FILTER ( datatype(?v) = xsd:double ) .
+    #       }
+    #
+    # @example SSE
     #   (prefix ((xsd: <http://www.w3.org/2001/XMLSchema#>)
-    #            (rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>)
-    #            (: <http://example.org/>))
-    #     (project (?s)
-    #       (filter (= (datatype (xsd:double ?v)) xsd:double)
-    #         (bgp (triple ?s :p ?v)))))
+    #            (: <http://example.org/things#>))
+    #    (project (?x ?v)
+    #     (filter (= (datatype ?v) xsd:double)
+    #      (bgp (triple ?x :p ?v)))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#func-datatype
     class Datatype < Operator::Unary
@@ -33,6 +43,15 @@ module SPARQL; module Algebra
           else raise TypeError, "expected an RDF::Literal, but got #{literal.inspect}"
         end
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "DATATYPE(#{operands.last.to_sparql(**options)})"
+      end
     end # Datatype
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -3,11 +3,20 @@ module SPARQL; module Algebra
     ##
     # The SPARQL logical `day` operator.
     #
-    # @example
-    #     (prefix ((: <http://example.org/>))
-    #       (project (?s ?x)
-    #         (extend ((?x (day ?date)))
-    #           (bgp (triple ?s :date ?date)))))
+    # [121] BuiltInCall ::= ... | 'DAY' '(' Expression ')' 
+    #
+    # @example SPARQL Grammar
+    #   PREFIX : <http://example.org/>
+    #   SELECT ?s (DAY(?date) AS ?x) WHERE {
+    #     ?s :date ?date
+    #   }
+    #
+    # @example SSE
+    #   (prefix
+    #    ((: <http://example.org/>))
+    #    (project (?s ?x)
+    #     (extend ((?x (day ?date)))
+    #      (bgp (triple ?s :date ?date)))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#func-day
     class Day < Operator::Unary
@@ -20,12 +29,21 @@ module SPARQL; module Algebra
       #
       # @param  [RDF::Literal] operand
       #   the operand
-      # @return [RDF::Literal]
+      # @return [RDF::Literal::Temporal]
       # @raise  [TypeError] if the operand is not a simple literal
       def apply(operand, **options)
-        raise TypeError, "expected an RDF::Literal::DateTime, but got #{operand.inspect}" unless operand.is_a?(RDF::Literal::DateTime)
+        raise TypeError, "expected an RDF::Literal::Temporal, but got #{operand.inspect}" unless operand.is_a?(RDF::Literal::Temporal)
         RDF::Literal(operand.object.day)
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "DAY(#{operands.last.to_sparql(**options)})"
+      end
     end # Day
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -6,8 +6,24 @@ module SPARQL; module Algebra
     #
     # The DELETE operation is a form of the DELETE/INSERT operation having no INSERT section
     #
-    # @example
-    #   (delete ((triple ?s ?p ?o))))
+    # [42]  DeleteClause            ::= 'DELETE' QuadPattern
+    #
+    # @example SPARQL Grammar
+    #   PREFIX     : <http://example.org/> 
+    #   PREFIX foaf: <http://xmlns.com/foaf/0.1/> 
+    #   
+    #   DELETE { ?s ?p ?o }
+    #   WHERE  { :a foaf:knows ?s . ?s ?p ?o }
+    #
+    # @example SSE
+    #   (prefix ((: <http://example.org/>)
+    #            (foaf: <http://xmlns.com/foaf/0.1/>))
+    #    (update
+    #     (modify
+    #      (bgp
+    #       (triple :a foaf:knows ?s)
+    #       (triple ?s ?p ?o))
+    #      (delete ((triple ?s ?p ?o))))))
     #
     # @see https://www.w3.org/TR/sparql11-update/#delete
     class Delete < Operator::Unary
@@ -52,6 +68,17 @@ module SPARQL; module Algebra
         end
         queryable
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this term.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "DELETE {\n" +
+          operands.first.to_sparql(delimiter: " .\n", **options) +
+          "\n}"
+      end
     end # Delete
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -6,8 +6,18 @@ module SPARQL; module Algebra
     #
     # The DELETE DATA operation removes some triples, given inline in the request, if the respective graphs in the Graph Store contain those
     #
-    # @example
-    #   (deleteData ((triple :a foaf:knows :c)))
+    # [39]  DeleteData              ::= 'DELETE DATA' QuadData
+    #
+    # @example SPARQL Grammar
+    #   PREFIX     : <http://example.org/> 
+    #   PREFIX foaf: <http://xmlns.com/foaf/0.1/> 
+    #   DELETE DATA {
+    #     :a foaf:knows :b .
+    #   }
+    #
+    # @example SSE
+    #   (prefix ((: <http://example.org/>) (foaf: <http://xmlns.com/foaf/0.1/>))
+    #    (update (deleteData ((triple :a foaf:knows :b)))))
     #
     # @see https://www.w3.org/TR/sparql11-update/#deleteData
     class DeleteData < Operator::Unary
@@ -36,6 +46,17 @@ module SPARQL; module Algebra
         end
         queryable
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this term.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "DELETE DATA {\n" +
+          operands.first.to_sparql(top_level: false, delimiter: ". \n", **options) +
+          "\n}"
+      end
     end # DeleteData
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -6,8 +6,19 @@ module SPARQL; module Algebra
     #
     # The DELETE WHERE operation is a shortcut form for the DELETE/INSERT operation where bindings matched by the WHERE clause are used to define the triples in a graph that will be deleted.
     #
-    # @example
-    #   (deleteWhere ((triple :a foaf:knows ?b))
+    # [40]  DeleteWhere             ::= 'DELETE WHERE' QuadPattern
+    #
+    # @example SPARQL Grammar
+    #   PREFIX     : <http://example.org/> 
+    #   PREFIX foaf: <http://xmlns.com/foaf/0.1/> 
+    #   DELETE WHERE { :a foaf:knows ?b }
+    #
+    # @example SSE
+    #   (prefix
+    #    ((: <http://example.org/>)
+    #     (foaf: <http://xmlns.com/foaf/0.1/>))
+    #    (update
+    #     (deleteWhere ((triple :a foaf:knows ?b)))))
     #
     # @see https://www.w3.org/TR/sparql11-update/#deleteWhere
     class DeleteWhere < Operator::Unary
@@ -52,6 +63,17 @@ module SPARQL; module Algebra
         end
         queryable
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this term.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "DELETE WHERE {\n" +
+          operands.first.to_sparql(top_level: false, delimiter: ". \n", **options) +
+          "\n}"
+      end
     end # DeleteWhere
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -3,7 +3,15 @@ module SPARQL; module Algebra
     ##
     # The SPARQL descending sort operator.
     #
-    # @example
+    # [24]  OrderCondition          ::= ( ( 'ASC' | 'DESC' ) BrackettedExpression ) | ( Constraint | Var )
+    #
+    # @example SPARQL Grammar
+    #   PREFIX foaf:    <http://xmlns.com/foaf/0.1/>
+    #   SELECT ?name
+    #   WHERE { ?x foaf:name ?name }
+    #   ORDER BY DESC(?name)
+    #
+    # @example SSE
     #   (prefix ((foaf: <http://xmlns.com/foaf/0.1/>))
     #     (project (?name)
     #       (order ((desc ?name))
@@ -12,6 +20,17 @@ module SPARQL; module Algebra
     # @see https://www.w3.org/TR/sparql11-query/#modOrderBy
     class Desc < Operator::Asc
       NAME = :desc
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # Provides order to descendant query.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "DESC(#{operands.last.to_sparql(**options)})"
+      end
     end # Desc
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -5,10 +5,16 @@ module SPARQL; module Algebra
     #
     # Generages a graph across specified terms using {RDF::Queryable}`#concise_bounded_description`.
     #
-    # @example
-    #   (prefix ((exOrg: <http://org.example.com/employees#>))
-    #     (describe (?x)
-    #       (bgp (triple ?x exOrg:employeeId "1234"))))
+    # [11]  DescribeQuery           ::= 'DESCRIBE' ( VarOrIri+ | '*' ) DatasetClause* WhereClause? SolutionModifier ValuesClause
+    #
+    # @example SPARQL Grammar
+    #   BASE <http://example.org/>
+    #   DESCRIBE <u> ?u WHERE { <x> <q> ?u . }
+    #
+    # @example SSE
+    #   (base <http://example.org/>
+    #    (describe (<u> ?u)
+    #     (bgp (triple <x> <q> ?u))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#describe
     class Describe < Operator::Binary
@@ -66,6 +72,23 @@ module SPARQL; module Algebra
       def query_yields_statements?
         true
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this term.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        str = "DESCRIBE "
+        str << if operands[0].empty?
+          "*"
+        else
+          operands[0].map { |e| e.to_sparql(**options) }.join(" ")
+        end
+
+        str << "\n"
+        str << operands[1].to_sparql(top_level: true, project: nil, **options)
+      end
     end # Construct
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -3,9 +3,17 @@ module SPARQL; module Algebra
     ##
     # The SPARQL GraphPattern `distinct` operator.
     #
-    # @example
-    #   (prefix ((xsd: <http://www.w3.org/2001/XMLSchema#>)
-    #            (: <http://example/>))
+    # [9] SelectClause ::= 'SELECT' ( 'DISTINCT' | 'REDUCED' )? ( ( Var | ( '(' Expression 'AS' Var ')' ) )+ | '*' )
+    #
+    # @example SPARQL Grammar
+    #   PREFIX : <http://example.org/>
+    #   PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
+    #   SELECT DISTINCT ?v
+    #   WHERE { ?x ?p ?v }
+    #
+    # @example SSE
+    #   (prefix ((: <http://example.org/>)
+    #            (xsd: <http://www.w3.org/2001/XMLSchema#>))
     #     (distinct
     #       (project (?v)
     #         (bgp (triple ?x ?p ?v)))))
@@ -36,6 +44,15 @@ module SPARQL; module Algebra
         @solutions.each(&block) if block_given?
         @solutions
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        operands.first.to_sparql(distinct: true, **options)
+      end
     end # Distinct
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -3,8 +3,23 @@ module SPARQL; module Algebra
     ##
     # The SPARQL numeric `divide` operator.
     #
-    # @example
-    #   (/ 4 2)
+    # [117] MultiplicativeExpression::= UnaryExpression ( '*' UnaryExpression | '/' UnaryExpression )*
+    #
+    # @example SPARQL Grammar
+    #   PREFIX : <http://example.org/>
+    #   SELECT ?s WHERE {
+    #     ?s :p ?o .
+    #     ?s2 :p ?o2 .
+    #     FILTER(?o / ?o2 = 4) .
+    #   }
+    #
+    # @example SSE
+    #   (prefix ((: <http://example.org/>))
+    #    (project (?s)
+    #     (filter (= (/ ?o ?o2) 4)
+    #      (bgp
+    #       (triple ?s :p ?o)
+    #       (triple ?s2 :p ?o2)))))
     #
     # @see https://www.w3.org/TR/xpath-functions/#func-numeric-divide
     class Divide < Operator::Binary
@@ -38,6 +53,15 @@ module SPARQL; module Algebra
           else raise TypeError, "expected two RDF::Literal::Numeric operands, but got #{left.inspect} and #{right.inspect}"
         end
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "(#{operands.first.to_sparql(**options)} / #{operands.last.to_sparql(**options)})"
+      end
     end # Divide
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -8,8 +8,20 @@ module SPARQL; module Algebra
     #
     # Equivalent to `clear` in this implementation
     #
-    # @example
-    #   (drop default)
+    # [33]  Drop                    ::= 'DROP' 'SILENT'? GraphRefAll
+    #
+    # @example SPARQL Grammar (SILENT DEFAULT)
+    #   DROP SILENT DEFAULT
+    #
+    # @example SSE (SILENT DEFAULT)
+    #   (update
+    #    (drop silent default))
+    #
+    # @example SPARQL Grammar (IRI)
+    #   DROP GRAPH <http://example.com/>
+    #
+    # @example SSE (IRI)
+    #   (update (drop <http://example.com/>))
     #
     # @see https://www.w3.org/TR/sparql11-update/#drop
     class Drop < Operator
@@ -34,7 +46,6 @@ module SPARQL; module Algebra
       def execute(queryable, **options)
         debug(options) {"Drop"}
         silent = operands.first == :silent
-        silent = operands.first == :silent
         operands.shift if silent
 
         raise ArgumentError, "drop expected operand to be 'default', 'named', 'all', or an IRI" unless operands.length == 1
@@ -61,6 +72,19 @@ module SPARQL; module Algebra
 
         queryable
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        silent = operands.first == :silent
+        str = "DROP "
+        str << "SILENT " if operands.first == :silent
+        str << "GRAPH " if operands.last.is_a?(RDF::URI)
+        str << operands.last.to_sparql(**options)
+      end
     end # Drop
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -5,8 +5,19 @@ module SPARQL; module Algebra
     ##
     # The SPARQL logical `abs` operator.
     #
-    # @example
-    #   (encode_for_uri ?x)
+    # [121] BuiltInCall ::= ... | 'ENCODE_FOR_URI' '(' Expression ')' 
+    #
+    # @example SPARQL Grammar
+    #   PREFIX : <http://example.org/>
+    #   SELECT ?s ?str (ENCODE_FOR_URI(?str) AS ?encoded) WHERE {
+    #     ?s :str ?str
+    #   }
+    #
+    # @example SSE
+    #   (prefix ((: <http://example.org/>))
+    #    (project (?s ?str ?encoded)
+    #     (extend ((?encoded (encode_for_uri ?str)))
+    #      (bgp (triple ?s :str ?str)))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#func-encode
     # @see https://www.w3.org/TR/xpath-functions/#func-abs
@@ -33,6 +44,15 @@ module SPARQL; module Algebra
           else raise TypeError, "expected an RDF::Literal, but got #{operand.inspect}"
         end
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "ENCODE_FOR_URI(#{operands.last.to_sparql(**options)})"
+      end
     end # EncodeForURI
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -3,8 +3,18 @@ module SPARQL; module Algebra
     ##
     # The SPARQL relational `=` (equal) comparison operator.
     #
-    # @example
-    #   (= ?x ?y)
+    # [114] RelationalExpression    ::= NumericExpression ('=' NumericExpression)?
+    #
+    # @example SPARQL Grammar
+    #   PREFIX  xsd: <http://www.w3.org/2001/XMLSchema#>
+    #   PREFIX  : <http://example.org/things#>
+    #   SELECT  ?x
+    #   WHERE { ?x :p ?v . FILTER ( ?v = 1 ) }
+    #
+    # @example SSE
+    #   (prefix
+    #    ((xsd: <http://www.w3.org/2001/XMLSchema#>) (: <http://example.org/things#>))
+    #    (project (?x) (filter (= ?v 1) (bgp (triple ?x :p ?v)))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#OperatorMapping
     # @see https://www.w3.org/TR/sparql11-query/#func-RDFterm-equal

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

@@ -5,10 +5,21 @@ module SPARQL; module Algebra
     #
     # There is a filter operator EXISTS that takes a graph pattern. EXISTS returns `true`/`false` depending on whether the pattern matches the dataset given the bindings in the current group graph pattern, the dataset and the active graph at this point in the query evaluation. No additional binding of variables occurs. The `NOT EXISTS` form translates into `fn:not(EXISTS{...})`.
     #
-    # @example
-    #    (prefix ((ex: <http://www.example.org/>))
-    #      (filter (exists (bgp (triple ?s ?p ex:o)))
-    #      (bgp (triple ?s ?p ?o))))
+    # [125] ExistsFunc              ::= 'EXISTS' GroupGraphPattern
+    #
+    # @example SPARQL Grammar
+    #   PREFIX :    <http://example/>
+    #   SELECT *
+    #   WHERE {
+    #     ?set a :Set .
+    #     FILTER EXISTS { ?set :member 9 }
+    #   }
+    #
+    # @example SSE
+    #   (prefix ((: <http://example/>))
+    #    (filter
+    #     (exists (bgp (triple ?set :member 9)))
+    #     (bgp (triple ?set a :Set))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#func-filter-exists
     class Exists < Operator::Unary
@@ -32,6 +43,19 @@ module SPARQL; module Algebra
                                        depth: options[:depth].to_i + 1,
                                        **options).empty?
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @param [Boolean] top_level (true)
+      #   Treat this as a top-level, generating SELECT ... WHERE {}
+      # @return [String]
+      def to_sparql(top_level: true, **options)
+        "EXISTS {\n" +
+          operands.last.to_sparql(top_level: false, **options) +
+          "\n}"
+      end
     end # Exists
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -5,8 +5,21 @@ module SPARQL; module Algebra
     #
     # Used for filters with more than one expression.
     #
-    # @example
-    #   (prefix ((: <http://example/>))
+    # [72]  ExpressionList ::= NIL | '(' Expression ( ',' Expression )* ')'
+    #
+    # @example SPARQL Grammar
+    #   PREFIX : <http://example.org/>
+    #
+    #   SELECT ?v ?w
+    #   { 
+    #     FILTER (?v = 2)
+    #     FILTER (?w = 3)
+    #     ?s :p ?v . 
+    #     ?s :q ?w .
+    #   }
+    #
+    # @example SSE
+    #   (prefix ((: <http://example.org/>))
     #     (project (?v ?w)
     #       (filter (exprlist (= ?v 2) (= ?w 3))
     #         (bgp