sparql 0.0.1 → 0.0.2

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

@@ -0,0 +1,34 @@
+module SPARQL; module Algebra
+  class Operator
+    include Evaluatable
+
+    ##
+    # The SPARQL numeric `add` operator.
+    #
+    # @example
+    #   (+ 1 ?x)
+    #   (add 1 ?x)
+    #
+    # @see http://www.w3.org/TR/xpath-functions/#func-numeric-add
+    class Add < Operator::Binary
+      NAME = [:+, :add]
+
+      ##
+      # Returns the arithmetic sum of the operands.
+      #
+      # @param  [RDF::Literal::Numeric] left
+      #   a numeric literal
+      # @param  [RDF::Literal::Numeric] right
+      #   a numeric literal
+      # @return [RDF::Literal::Numeric]
+      # @raise  [TypeError] if either operand is not a numeric literal
+      def apply(left, right)
+        case
+          when left.is_a?(RDF::Literal::Numeric) && right.is_a?(RDF::Literal::Numeric)
+            left + right
+          else raise TypeError, "expected two RDF::Literal::Numeric operands, but got #{left.inspect} and #{right.inspect}"
+        end
+      end
+    end # Add
+  end # Operator
+end; end # SPARQL::Algebra

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

@@ -0,0 +1,65 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL logical `and` operator.
+    #
+    # @example
+    #   (&& ?x ?y)
+    #   (and ?x ?y)
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#func-logical-and
+    # @see http://www.w3.org/TR/rdf-sparql-query/#evaluation
+    class And < Operator::Binary
+      include Evaluatable
+
+      NAME = [:and, :'&&']
+
+      ##
+      # Initializes a new operator instance.
+      #
+      # @param  [RDF::Literal::Boolean] left
+      #   the left operand
+      # @param  [RDF::Literal::Boolean] right
+      #   the right operand
+      # @param  [Hash{Symbol => Object}] options
+      #   any additional options (see {Operator#initialize})
+      # @raise  [TypeError] if any operand is invalid
+      def initialize(left, right, options = {})
+        super
+      end
+
+      ##
+      # Returns the logical `AND` of the left operand and the right operand.
+      #
+      # Note that this operator operates on the effective boolean value
+      # (EBV) of its operands.
+      #
+      # @param  [RDF::Query::Solution, #[]] bindings
+      # @return [RDF::Literal::Boolean] `true` or `false`
+      # @raise  [TypeError] if the operands could not be coerced to boolean literals
+      def evaluate(bindings = {})
+        begin
+          left = boolean(operand(0).evaluate(bindings)).true?
+        rescue TypeError
+          left = nil
+        end
+        
+        begin
+          right = boolean(operand(1).evaluate(bindings)).true?
+        rescue TypeError
+          right = nil
+        end
+
+        # From http://www.w3.org/TR/rdf-sparql-query/#evaluation
+        # A logical-and that encounters an error on only one branch will return an error if the other branch is
+        # TRUE and FALSE if the other branch is FALSE.
+        case
+        when left.nil? && right.nil? then raise(TypeError)
+        when left.nil?               then right ? raise(TypeError) : RDF::Literal::FALSE
+        when right.nil?              then left  ? raise(TypeError) : RDF::Literal::FALSE
+        else                              RDF::Literal(left && right)
+        end
+      end
+    end # And
+  end # Operator
+end; end # SPARQL::Algebra

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

@@ -0,0 +1,29 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL ascending sort operator.
+    #
+    # @example
+    #   (prefix ((foaf: <http://xmlns.com/foaf/0.1/>))
+    #     (project (?name)
+    #       (order ((asc ?name))
+    #         (bgp (triple ?x foaf:name ?name)))))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#func-isLiteral
+    class Asc < Operator::Unary
+      include Evaluatable
+
+      NAME = :asc
+
+      ##
+      # Returns the evaluation of it's operand. Default comparison is in
+      # ascending order. Ordering is applied in {Order}.
+      #
+      # @param  [RDF::Query::Solution, #[]] bindings
+      # @return [RDF::Term]
+      def evaluate(bindings = {})
+        operand(0).evaluate(bindings)
+      end
+    end # Asc
+  end # Operator
+end; end # SPARQL::Algebra

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

@@ -0,0 +1,46 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL GraphPattern `ask` operator.
+    #
+    # @example
+    #   (prefix ((: <http://example/>))
+    #     (ask
+    #       (bgp (triple :x :p ?x))))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#ask
+    class Ask < Operator::Unary
+      include Query
+      
+      NAME = [:ask]
+
+      ##
+      # Executes this query on the given `queryable` graph or repository.
+      # Returns true if any solutions are found, false otherwise.
+      #
+      # @param  [RDF::Queryable] queryable
+      #   the graph or repository to query
+      # @param  [Hash{Symbol => Object}] options
+      #   any additional keyword options
+      # @return [RDF::Literal::Boolean]
+      #   the resulting solution sequence
+      # @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?)
+      end
+      
+      ##
+      # Returns an optimized version of this query.
+      #
+      # Return optimized query
+      #
+      # @return [Union, RDF::Query] `self`
+      def optimize
+        operands = operands.map(&:optimize)
+      end
+    end # Ask
+  end # Operator
+end; end # SPARQL::Algebra

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

@@ -0,0 +1,46 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL GraphPattern `base` operator.
+    #
+    # @example
+    #   (base <http://example.org/>
+    #     (bgp (triple <a> <b> 123.0)))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#QSynIRI
+    class Base < Binary
+      include Query
+      
+      NAME = [:base]
+
+      ##
+      # Executes this query on the given `queryable` graph or repository.
+      # Really a pass-through, as this is a syntactic object used for providing
+      # context for relative URIs.
+      #
+      # @param  [RDF::Queryable] queryable
+      #   the graph or repository to query
+      # @param  [Hash{Symbol => Object}] options
+      #   any additional keyword options
+      # @return [RDF::Query::Solutions]
+      #   the resulting solution sequence
+      # @see    http://www.w3.org/TR/rdf-sparql-query/#sparqlAlgebra
+      def execute(queryable, options = {})
+        debug(options) {"Base #{operands.first}"}
+        @solutions = operands.last.execute(queryable, options.merge(:depth => options[:depth].to_i + 1))
+        debug(options) {"=> #{@solutions.inspect}"}
+        @solutions
+      end
+      
+      ##
+      # Returns an optimized version of this query.
+      #
+      # Return optimized query
+      #
+      # @return [Union, RDF::Query] `self`
+      def optimize
+        operands.last.optimize
+      end
+    end # Base
+  end # Operator
+end; end # SPARQL::Algebra

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

@@ -0,0 +1,26 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL GraphPattern `bgp` operator.
+    #
+    # Query with `context` set to false.
+    #
+    # @example
+    #   (prefix ((: <http://example/>))
+    #     (bgp (triple ?s ?p ?o)))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#sparqlAlgebra
+    class BGP < Operator
+      NAME = [:bgp]
+      ##
+      # A `graph` is an RDF::Query with a context.
+      #
+      # @param [RDF::URI, RDF::Query::Variable] context
+      # @param [RDF::Query] bgp
+      # @return [RDF::Query]
+      def self.new(*patterns)
+        RDF::Query.new(*(patterns + [{:context => false}]))
+      end
+    end # BGP
+  end # Operator
+end; end # SPARQL::Algebra

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

@@ -0,0 +1,48 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL `bound` operator.
+    #
+    # @example
+    #   (prefix ((: <http://example.org/ns#>))
+    #     (project (?a ?c)
+    #       (filter (! (bound ?e))
+    #         (leftjoin
+    #           (bgp (triple ?a :b ?c))
+    #           (bgp (triple ?c :d ?e))))))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#func-bound
+    class Bound < Operator::Unary
+      include Evaluatable
+
+      NAME = :bound
+
+      ##
+      # Initializes a new operator instance.
+      #
+      # @param  [RDF::Query::Variable] var
+      #   a variable
+      # @param  [Hash{Symbol => Object}] options
+      #   any additional options (see {Operator#initialize})
+      # @raise  [TypeError] if any operand is invalid
+      def initialize(var, options = {})
+        super
+      end
+
+      ##
+      # Returns `true` if the operand is a variable that is bound to a
+      # value in the given `bindings`, `false` otherwise.
+      #
+      # @param  [RDF::Query::Solution, #[]] bindings
+      # @return [RDF::Literal::Boolean] `true` or `false`
+      # @raise  [TypeError] if the operand is not a variable
+      def evaluate(bindings = {})
+        case var = operand
+          when Variable
+            operand.evaluate(bindings) ? RDF::Literal::TRUE : RDF::Literal::FALSE
+          else raise TypeError, "expected an RDF::Query::Variable, but got #{var.inspect}"
+        end
+      end
+    end # Bound
+  end # Operator
+end; end # SPARQL::Algebra

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

@@ -0,0 +1,84 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # A SPARQL relational `<=>` comparison operator.
+    #
+    # @example
+    #   (<=> ?x ?y)
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#OperatorMapping
+    # @see http://www.w3.org/TR/xpath-functions/#func-compare
+    class Compare < Operator::Binary
+      include Evaluatable
+
+      NAME = :<=>
+
+      ##
+      # Returns -1, 0, or 1, depending on whether the first operand is
+      # respectively less than, equal to, or greater than the second
+      # operand.
+      #
+      # SPARQL also fixes an order between some kinds of RDF terms that would not otherwise be ordered:
+      #
+      #   (Lowest) no value assigned to the variable or expression in this solution.
+      #   Blank nodes
+      #   IRIs
+      #   RDF literals
+      #
+      # @param  [RDF::Literal] left
+      #   a literal
+      # @param  [RDF::Literal] right
+      #   a literal
+      # @return [RDF::Literal::Integer] `-1`, `0`, or `1`
+      # @raise  [TypeError] if either operand is not a literal
+      def apply(left, right)
+        case
+        # @see http://www.w3.org/TR/rdf-sparql-query/#OperatorMapping
+        # @see http://www.w3.org/TR/rdf-sparql-query/#modOrderBy
+        when left.is_a?(RDF::Literal) && right.is_a?(RDF::Literal)
+          case
+          # @see http://www.w3.org/TR/xpath-functions/#string-compare
+          # @see http://www.w3.org/TR/xpath-functions/#comp.numeric
+          # @see http://www.w3.org/TR/xpath-functions/#op.boolean
+          # @see http://www.w3.org/TR/xpath-functions/#comp.duration.datetime
+          when (left.simple? && right.simple?) ||
+               (left.is_a?(RDF::Literal::Numeric) && right.is_a?(RDF::Literal::Numeric)) ||
+               (left.datatype == right.datatype && left.language == right.language)
+            RDF::Literal(left.send(self.class.const_get(:NAME), right))
+
+          # A plain literal is lower than an RDF literal with type xsd:string of the same lexical form.
+          when left.simple? && right.datatype == RDF::XSD.string && left.value == right.value
+            RDF::Literal(-1)
+          when right.simple? && left.datatype == RDF::XSD.string && right.value == left.value
+            RDF::Literal(-1)
+
+          else raise TypeError, "unable to compare #{left.inspect} and #{right.inspect}"
+          end
+          
+        when left.is_a?(RDF::URI) && right.is_a?(RDF::URI)
+          # Pairs of IRIs are ordered by comparing them as simple literals.
+          RDF::Literal(RDF::Literal(left.to_s).send(self.class.const_get(:NAME), RDF::Literal(right.to_s)))
+        when left.is_a?(RDF::Node) && right.is_a?(RDF::Node)
+          # BNode comparison is undefined.
+          RDF::Literal(0)
+        when left.nil? && right.nil?
+          RDF::Literal(0)
+        
+        # SPARQL also fixes an order between some kinds of RDF terms that would not otherwise be ordered:
+        # 2. Blank nodes
+        when left.is_a?(RDF::Node) && right.is_a?(RDF::Term)
+          RDF::Literal(-1)
+        when right.is_a?(RDF::Node) && left.is_a?(RDF::Term)
+          RDF::Literal(1)
+
+        # 3. IRIs
+        when left.is_a?(RDF::URI) && right.is_a?(RDF::Term)
+          RDF::Literal(-1)
+        when right.is_a?(RDF::URI) && left.is_a?(RDF::Term)
+          RDF::Literal(1)
+        else raise TypeError, "expected two RDF::Term operands, but got #{left.inspect} and #{right.inspect}"
+        end
+      end
+    end # Compare
+  end # Operator
+end; end # SPARQL::Algebra

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

@@ -0,0 +1,85 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL GraphPattern `construct` operator.
+    #
+    # @example
+    #   (prefix ((rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>)
+    #            (foaf: <http://xmlns.com/foaf/0.1/>))
+    #     (construct ((triple ?s ?p ?o))
+    #       (project (?s ?p ?o)
+    #         (bgp (triple ?s ?p ?o)))))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#ask
+    class Construct < Operator::Binary
+      include Query
+      
+      NAME = [:construct]
+
+      ##
+      # Executes this query on the given {RDF::Queryable} object.
+      # Binds variables to the array of patterns in the first operand and returns the resulting RDF::Graph object
+      #
+      # If any such instantiation produces a triple containing an unbound variable or an illegal RDF construct,
+      # such as an RDF::Literal in _subject_ or _predicate_ position, then that triple is not included in the output RDF
+      # graph. The graph template can contain triples with no variables (known as ground or explicit triples),
+      # and these also appear in the output RDF graph returned by the CONSTRUCT query form.
+      #
+      # @param  [RDF::Queryable] queryable
+      #   the graph or repository to query
+      # @param  [Hash{Symbol => Object}] options
+      #   any additional keyword options
+      # @return [RDF::Query::Solutions]
+      #   the resulting solution sequence
+      # @see    http://www.w3.org/TR/rdf-sparql-query/#construct
+      def execute(queryable, options = {})
+        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"}
+          
+          # Create a mapping from BNodes within the pattern list to newly constructed BNodes
+          nodes = {}
+          patterns.each do |pattern|
+            terms = {}
+            [:subject, :predicate, :object].each do |r|
+              terms[r] = case o = pattern.send(r)
+              when RDF::Node            then nodes[o] ||= RDF::Node.new
+              when RDF::Query::Variable then solution[o]
+              else                           o
+              end
+            end
+            
+            statement = RDF::Statement.from(terms)
+
+            # 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}"}
+              next
+            end
+
+            debug(options) {"==> add #{statement.inspect}"}
+            graph << statement
+          end
+        end
+        
+        debug(options) {"=>\n#{graph.dump(:ttl, :standard_prefixes => true)}"}
+        graph
+      end
+      
+      ##
+      # Returns an optimized version of this query.
+      #
+      # Return optimized query
+      #
+      # @return [Union, RDF::Query] `self`
+      def optimize
+        operands = operands.map(&:optimize)
+      end
+    end # Construct
+  end # Operator
+end; end # SPARQL::Algebra