graph.rb in sparql-1.1.6

- old
+ new

@@ -2,26 +2,59 @@
 module SPARQL; module Algebra
   class Operator
     ##
     # The SPARQL GraphPattern `graph` operator.
     #
-    # This is a wrapper to add a `context` to the query.
+    # This is a wrapper to add a `context` to the query, or an array of statements.
     #
-    # @example
+    # @example of a query
     #   (prefix ((: <http://example/>))
     #     (graph ?g
     #       (bgp (triple ?s ?p ?o))))
     #
+    # @example named set of statements
+    #   (prefix ((: <http://example/>))
+    #     (graph :g
+    #       ((triple :s :p :o))))
+    #
     # @see http://www.w3.org/TR/rdf-sparql-query/#sparqlAlgebra
     class Graph < Operator::Binary
       include Query
       
       NAME = [:graph]
+      ##
+      # A `graph` is an RDF::Query with a context. It can also be used as a container of statements or patterns, or other queryable operators (see GraphGraphPattern)
+      #
+      # @overload self.new(name, bgp)
+      #   @param [RDF::Resource] name
+      #   @param [RDF::Query] patterns
+      #     A sub-query (bgp)
+      # @overload self.new(name, bgp)
+      #   @param [RDF::Resource] name
+      #   @param [Operator] patterns
+      #     A sub-query (GraphGraphPattern)
+      # @overload self.new(name, patterns)
+      #   @param [RDF::Resource] name
+      #   @param [Array<RDF::Query::Pattern>] patterns
+      #     Quads
+      # @return [RDF::Query]
+      def self.new(name, patterns, &block)
+        case patterns
+        when RDF::Query
+          # Record that the argument as a (bgp) for re-serialization back to SSE
+          RDF::Query.new(*(patterns.patterns + [{context: name,}]), &block)
+        when Operator
+          super
+        else
+          RDF::Query.new(*(patterns + [{context: name, as_container: true}]), &block)
+        end
+      end
 
       ##
-      # Executes this query on the given `queryable` graph or repository.
-      # Applies the given `context` to the query, limiting the scope of the query to the specified `context`, which may be an `RDF::URI` or `RDF::Query::Variable`.
+      # If the second operand is a Query operator:
+      #   Executes this query on the given `queryable` graph or repository.
+      #   Applies the given `context` to the query, limiting the scope of the query to the specified `context`, which may be an `RDF::URI` or `RDF::Query::Variable`.
       #
       # @param  [RDF::Queryable] queryable
       #   the graph or repository to query
       # @param  [Hash{Symbol => Object}] options
       #   any additional keyword options
@@ -33,11 +66,11 @@
       #   the resulting solution sequence
       # @see    http://www.w3.org/TR/rdf-sparql-query/#sparqlAlgebra
       def execute(queryable, options = {}, &block)
         debug(options) {"Graph #{operands.first}"}
         context, query = operands.first, operands.last
-        @solutions = queryable.query(query, options.merge(:context => context), &block)
+        @solutions = queryable.query(query, options.merge(context: context), &block)
       end
       
       ##
       # Returns an optimized version of this query.
       #
@@ -48,9 +81,10 @@
         operands = operands.map(&:optimize)
       end
       
       ##
       # Don't do any more rewriting
+      # FIXME: if ooperator is JOIN, and rewritten sub-operators are queries, can do simple merge of sub-graphs
       # @return [SPARQL::Algebra::Expression] `self`
       def rewrite(&block)
         self
       end
     end # Graph