sparql 0.0.1 → 0.0.2

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

@@ -0,0 +1,77 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL GraphPattern `dataset` operator.
+    #
+    # Instintiated with two operands, the first being an array of data source URIs,
+    # either bare, indicating a default dataset, or expressed as an array [:named, <uri>],
+    # indicating that it represents a named data source.
+    #
+    # @example
+    #   (prefix ((: <http://example/>))
+    #     (dataset (<data-g1.ttl> (named <data-g2.ttl>))
+    #       (bgp (triple ?s ?p ?o))))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#specifyingDataset
+    class Dataset < Binary
+      include Query
+      
+      NAME = [:dataset]
+
+      ##
+      # Executes this query on the given `queryable` graph or repository.
+      # Reads specified data sources into queryable. Named data sources
+      # are added using a _context_ of the data source URI.
+      #
+      # Datasets are specified in operand(1), which is an array of default or named graph 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) {"Dataset"}
+        operand(0).each do |ds|
+          load_opts = {}
+          case ds
+          when Array
+            # Format is (named <uri>), only need the URI part
+            uri = if self.base_uri
+              u = self.base_uri.join(ds.last)
+              u.lexical = "<#{ds.last}>" unless u.to_s == ds.last.to_s
+              u
+            else
+              ds.last
+            end
+            uri = self.base_uri ? self.base_uri.join(ds.last) : ds.last
+            uri.lexical = ds.last
+            load_opts[:context] = uri
+            debug(options) {"=> read named data source #{uri}"}
+          else
+            debug(options) {"=> array: join #{self.base_uri.inspect} to #{ds.inspect}"}
+            uri = self.base_uri ? self.base_uri.join(ds) : ds
+            debug(options) {"=> read default data source #{uri}"}
+          end
+          load_opts[:base_uri] = uri
+          queryable.load(uri.to_s, load_opts)
+        end
+
+        @solutions = operands.last.execute(queryable, options.merge(:depth => options[:depth].to_i + 1))
+      end
+      
+      ##
+      # Returns an optimized version of this query.
+      #
+      # If optimize operands, and if the first two operands are both Queries, replace
+      # with the unique sum of the query elements
+      #
+      # @return [Union, RDF::Query] `self`
+      def optimize
+        operands.last.optimize
+      end
+    end # Dataset
+  end # Operator
+end; end # SPARQL::Algebra

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

@@ -0,0 +1,42 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL `datatype` operator.
+    #
+    # @example
+    #   (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)))))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#func-datatype
+    class Datatype < Operator::Unary
+      include Evaluatable
+
+      NAME = :datatype
+
+      ##
+      # Returns the datatype IRI of the operand.
+      #
+      # If the operand is a simple literal, returns a datatype of
+      # `xsd:string`.
+      #
+      # @param  [RDF::Literal] literal
+      #   a typed or simple literal
+      # @return [RDF::URI] the datatype IRI, or `xsd:string` for simple literals
+      # @raise  [TypeError] if the operand is not a typed or simple literal
+      def apply(literal)
+        case literal
+          when RDF::Literal then case
+            when literal.typed?  then RDF::URI(literal.datatype)
+            when literal.simple? then RDF::XSD.string
+            else raise TypeError, "expected a typed or simple RDF::Literal, but got #{literal.inspect}"
+          end
+          else raise TypeError, "expected an RDF::Literal, but got #{literal.inspect}"
+        end
+      end
+    end # Datatype
+  end # Operator
+end; end # SPARQL::Algebra

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

@@ -0,0 +1,17 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL descending sort operator.
+    #
+    # @example
+    #   (prefix ((foaf: <http://xmlns.com/foaf/0.1/>))
+    #     (project (?name)
+    #       (order ((desc ?name))
+    #         (bgp (triple ?x foaf:name ?name)))))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#func-isLiteral
+    class Desc < Operator::Asc
+      NAME = :desc
+    end # Desc
+  end # Operator
+end; end # SPARQL::Algebra

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

@@ -0,0 +1,71 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL GraphPattern `describe` operator.
+    #
+    # 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"))))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#describe
+    class Describe < Operator::Binary
+      include Query
+      
+      NAME = [:describe]
+
+      ##
+      # Executes this query on the given {RDF::Queryable} object.
+      # Generates a graph containing the Concise Bounded Description
+      # variables and URIs listed in the first operand.
+      #
+      # @example
+      #   (describe (<http://example/>))
+      #
+      # @example
+      #   (prefix ((foaf: <http://xmlns.com/foaf/0.1/>))
+      #     (describe (?x)
+      #       (bgp (triple ?x foaf:mbox <mailto:alice@org>))))
+      #
+      # @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/#describe
+      def execute(queryable, options = {})
+        debug(options) {"Describe #{operands.first}, #{options.inspect}"}
+
+        # Describe any constand URIs
+        to_describe = operands.first.select {|t| t.uri?}
+        
+        to_describe.each {|t| debug(options) {"=> describe #{t}"}}
+
+        operands.last.execute(queryable).each do |solution|
+          solution.each_variable do |v|
+            if operands.first.any? {|bound| v.eql?(bound)}
+              debug(options) {"=> describe #{v}"}
+              to_describe << v.value
+            end
+          end
+        end
+
+        # Return Concise Bounded Description
+        queryable.concise_bounded_description(*to_describe)
+      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

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

@@ -0,0 +1,50 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL GraphPattern `distinct` operator.
+    #
+    # @example
+    #   (prefix ((xsd: <http://www.w3.org/2001/XMLSchema#>)
+    #            (: <http://example/>))
+    #     (distinct
+    #       (project (?v)
+    #         (bgp (triple ?x ?p ?v)))))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#sparqlAlgebra
+    class Distinct < Operator::Unary
+      include Query
+      
+      NAME = [:distinct]
+
+      ##
+      # Executes this query on the given `queryable` graph or repository.
+      # Removes duplicate solutions from the solution set.
+      #
+      # @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) {"Distinct"}
+        @solutions = operands.last.execute(queryable, options.merge(:depth => options[:depth].to_i + 1))
+        debug(options) {"=>(before) #{@solutions.inspect}"}
+        @solutions = @solutions.distinct
+        debug(options) {"=>(after) #{@solutions.inspect}"}
+        @solutions
+      end
+      
+      ##
+      # Returns an optimized version of this query.
+      #
+      # Return optimized query
+      #
+      # @return [Union, RDF::Query] `self`
+      def optimize
+        operands = operands.map(&:optimize)
+      end
+    end # Distinct
+  end # Operator
+end; end # SPARQL::Algebra

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

@@ -0,0 +1,43 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL numeric `divide` operator.
+    #
+    # @example
+    #   (/ 4 2)
+    #
+    # @see http://www.w3.org/TR/xpath-functions/#func-numeric-divide
+    class Divide < Operator::Binary
+      include Evaluatable
+
+      NAME = [:'/', :divide]
+
+      ##
+      # Returns the arithmetic quotient 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)
+            # For xsd:decimal and xsd:integer operands, if the divisor is
+            # (positive or negative) zero, an error is raised.
+            raise ZeroDivisionError, "divided by #{right}" if left.is_a?(RDF::Literal::Decimal) && right.zero?
+
+            # As a special case, if the types of both operands are
+            # xsd:integer, then the return type is xsd:decimal.
+            if left.is_a?(RDF::Literal::Integer) && right.is_a?(RDF::Literal::Integer)
+              RDF::Literal(left.to_d / right.to_d)
+            else
+              left / right
+            end
+          else raise TypeError, "expected two RDF::Literal::Numeric operands, but got #{left.inspect} and #{right.inspect}"
+        end
+      end
+    end # Divide
+  end # Operator
+end; end # SPARQL::Algebra

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

@@ -0,0 +1,32 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL relational `=` (equal) comparison operator.
+    #
+    # @example
+    #   (= ?x ?y)
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#OperatorMapping
+    # @see http://www.w3.org/TR/rdf-sparql-query/#func-RDFterm-equal
+    class Equal < Compare
+      NAME = :'='
+
+      ##
+      # Returns `true` if the operands are equal; returns `false` otherwise.
+      #
+      # @param  [RDF::Term] term1
+      #   an RDF term
+      # @param  [RDF::Term] term2
+      #   an RDF term
+      # @return [RDF::Literal::Boolean] `true` or `false`
+      # @raise  [TypeError] if either operand is not an RDF term or operands are not comperable
+      #
+      # @see {RDF::Term#==}
+      def apply(term1, term2)
+        term1 = term1.dup.extend(RDF::TypeCheck)
+        term2 = term2.dup.extend(RDF::TypeCheck)
+        RDF::Literal(term1 == term2)
+      end
+    end # Equal
+  end # Operator
+end; end # SPARQL::Algebra

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

@@ -0,0 +1,52 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL GraphPattern `exprlist` operator.
+    #
+    # Used for filters with more than one expression.
+    #
+    # @example
+    #   (prefix ((: <http://example/>))
+    #     (project (?v ?w)
+    #       (filter (exprlist (= ?v 2) (= ?w 3))
+    #         (bgp
+    #           (triple ?s :p ?v)
+    #           (triple ?s :q ?w)
+    #         ))))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#evaluation
+    class Exprlist < Operator
+      include Evaluatable
+
+      NAME = [:exprlist]
+
+      ##
+      # Returns `true` if all operands evaluate to `true`.
+      #
+      # Note that this operator operates on the effective boolean value
+      # (EBV) of its operands.
+      #
+      # @example
+      #
+      #   (exprlist (= 1 1) (!= 1 0))
+      #
+      # @param  [RDF::Query::Solution, #[]] bindings
+      # @return [RDF::Literal::Boolean] `true` or `false`
+      # @raise  [TypeError] if the operands could not be coerced to a boolean literal
+      def evaluate(bindings = {})
+        res = operands.all? {|op| boolean(op.evaluate(bindings)).true? }
+        RDF::Literal(res) # FIXME: error handling
+      end
+
+      ##
+      # Returns an optimized version of this query.
+      #
+      # Return optimized query
+      #
+      # @return [Union, RDF::Query] `self`
+      def optimize
+        operands = operands.map(&:optimize)
+      end
+    end # Exprlist
+  end # Operator
+end; end # SPARQL::Algebra

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

@@ -0,0 +1,71 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL GraphPattern `filter` operator.
+    #
+    # @example
+    #   (select (?v)
+    #     (project (?v)
+    #       (filter (= ?v 2)
+    #         (bgp (triple ?s <http://example/p> ?v)))))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#evaluation
+    class Filter < Operator::Binary
+      include Query
+      
+      NAME = [:filter]
+
+      ##
+      # Executes this query on the given `queryable` graph or repository.
+      # Then it passes each solution through one or more filters and removes
+      # those that evaluate to false or generate a _TypeError_.
+      #
+      # Note that the last operand returns a solution set, while the first
+      # is an expression. This may be a variable, simple expression,
+      # or exprlist.
+      #
+      # @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
+      # @see    http://www.w3.org/TR/rdf-sparql-query/#ebv
+      def execute(queryable, options = {})
+        debug(options) {"Filter #{operands.first}"}
+        @solutions = operands.last.execute(queryable, options.merge(:depth => options[:depth].to_i + 1))
+        debug(options) {"=>(before) #{@solutions.map(&:to_hash).inspect}"}
+        @solutions = @solutions.filter do |solution|
+          # Evaluate the solution, which will return true or false
+          #debug(options) {"===>(evaluate) #{operands.first.inspect} against #{solution.to_hash.inspect}"}
+          
+          # From http://www.w3.org/TR/rdf-sparql-query/#tests
+          # FILTERs eliminate any solutions that, when substituted into the expression, either
+          # result in an effective boolean value of false or produce an error.
+          begin
+            res = boolean(operands.first.evaluate(solution)).true?
+            debug(options) {"===>#{res} #{solution.to_hash.inspect}"}
+            res
+          rescue
+            debug(options) {"rescue(#{$!}): #{solution.to_hash.inspect}"}
+            false
+          end
+        end
+        @solutions = RDF::Query::Solutions.new(@solutions)
+        debug(options) {"=>(after) #{@solutions.map(&:to_hash).inspect}"}
+        @solutions
+      end
+      
+      ##
+      # Returns an optimized version of this query.
+      #
+      # Return optimized query
+      #
+      # @return [Union, RDF::Query] `self`
+      def optimize
+        operands = operands.map(&:optimize)
+      end
+    end # Filter
+  end # Operator
+end; end # SPARQL::Algebra