sparql 0.0.1 → 0.0.2

data/lib/sparql/algebra/extensions.rb

@@ -0,0 +1,159 @@
+require 'json'
+
+##
+# Extensions for Ruby's `Object` class.
+class Object
+  ##
+  # Returns the SXP representation of this object, defaults to `self'.
+  #
+  # @return [String]
+  def to_sse
+    self
+  end
+end
+
+##
+# Extensions for Ruby's `Object` class.
+class Array
+  ##
+  # Returns the SXP representation of this object, defaults to `self'.
+  #
+  # @return [String]
+  def to_sse
+    map {|x| x.to_sse}
+  end
+  
+  ##
+  # Evaluates the array using the given variable `bindings`.
+  #
+  # In this case, the Array has two elements, the first of which is
+  # an XSD datatype, and the second is the expression to be evaluated.
+  # The result is cast as a literal of the appropriate type
+  #
+  # @param  [RDF::Query::Solution, #[]] bindings
+  #   a query solution containing zero or more variable bindings
+  # @return [RDF::Term]
+  def evaluate(bindings)
+    dt, val = self.map {|o| o.evaluate(bindings)}
+    SPARQL::Algebra::Expression.cast(*self.map {|o| o.evaluate(bindings)})
+  end
+end
+
+##
+# Extensions for `RDF::Term`.
+module RDF::Term
+  include SPARQL::Algebra::Expression
+  
+  def evaluate(bindings)
+    self
+  end
+end # RDF::Term
+
+# Override RDF::Queryable to execute against SPARQL::Algebra::Query elements as well as RDF::Query and RDF::Pattern
+module RDF::Queryable
+  alias_method :query_without_sparql, :query
+  ##
+  # Queries `self` for RDF statements matching the given `pattern`.
+  #
+  # Monkey patch to RDF::Queryable#query to execute a {SPARQL::Algebra::Operator}
+  # in addition to an {RDF::Query} object.
+  #
+  # @example
+  #     queryable.query([nil, RDF::DOAP.developer, nil])
+  #     queryable.query(:predicate => RDF::DOAP.developer)
+  #
+  #     op = SPARQL::Algebra::Expression.parse(%q((bgp (triple ?a doap:developer ?b))))
+  #     queryable.query(op)
+  #
+  # @param  [RDF::Query, RDF::Statement, Array(RDF::Term), Hash, SPARQL::Operator] pattern
+  # @yield  [statement]
+  #   each matching statement
+  # @yieldparam  [RDF::Statement] statement
+  # @yieldreturn [void] ignored
+  # @return [Enumerator]
+  # @see    RDF::Queryable#query_pattern
+  def query(pattern, &block)
+    raise TypeError, "#{self} is not readable" if respond_to?(:readable?) && !readable?
+
+    if pattern.is_a?(SPARQL::Algebra::Operator) && pattern.respond_to?(:execute)
+      before_query(pattern) if respond_to?(:before_query)
+      query_execute(pattern, &block)
+      after_query(pattern) if respond_to?(:after_query)
+      enum_for(:query_execute, pattern)
+    else
+      query_without_sparql(pattern, &block)
+    end
+  end
+  
+end
+
+class RDF::Query
+  # Equivalence for Queries:
+  #   Same Patterns
+  #   Same Context
+  # @return [Boolean]
+  def ==(other)
+    other.is_a?(RDF::Query) && patterns == other.patterns && context == context
+  end
+
+  # Transform Query into an Array form of an SSE
+  #
+  # If Query is named, it's treated as a GroupGraphPattern, otherwise, a BGP
+  #
+  # @return [Array]
+  def to_sse
+    res = [:bgp] + patterns.map(&:to_sse)
+    (context ? [:graph, context, res] : res)
+  end
+end
+
+class RDF::Query::Pattern
+  # Transform Query Pattern into an SXP
+  # @return [Array]
+  def to_sse
+    [:triple, subject, predicate, object]
+  end
+end
+
+##
+# Extensions for `RDF::Query::Variable`.
+class RDF::Query::Variable
+  include SPARQL::Algebra::Expression
+
+  ##
+  # Returns the value of this variable in the given `bindings`.
+  #
+  # @param  [RDF::Query::Solution, #[]] bindings
+  # @return [RDF::Term] the value of this variable
+  def evaluate(bindings = {})
+    bindings[name.to_sym]
+  end
+end # RDF::Query::Variable
+
+##
+# Extensions for `RDF::Query::Solutions`.
+class RDF::Query::Solutions
+  alias_method :filter_without_expression, :filter
+
+  ##
+  # Filters this solution sequence by the given `criteria`.
+  #
+  # @param  [SPARQL::Algebra::Expression] expression
+  # @yield  [solution]
+  #   each solution
+  # @yieldparam  [RDF::Query::Solution] solution
+  # @yieldreturn [Boolean]
+  # @return [void] `self`
+  def filter(expression = {}, &block)
+    case expression
+      when SPARQL::Algebra::Expression
+        filter_without_expression do |solution|
+          expression.evaluate(solution).true?
+        end
+        filter_without_expression(&block) if block_given?
+        self
+      else filter_without_expression(expression, &block)
+    end
+  end
+  alias_method :filter!, :filter
+end # RDF::Query::Solutions

data/lib/sparql/algebra/operator.rb

@@ -0,0 +1,492 @@
+module SPARQL; module Algebra
+  ##
+  # A SPARQL operator.
+  #
+  # @abstract
+  class Operator
+    include Expression
+
+    # Unary operators
+    autoload :Not,                'sparql/algebra/operator/not'
+    autoload :Plus,               'sparql/algebra/operator/plus'
+    autoload :Minus,              'sparql/algebra/operator/minus'
+    autoload :Bound,              'sparql/algebra/operator/bound'
+    autoload :IsBlank,            'sparql/algebra/operator/is_blank'
+    autoload :IsIRI,              'sparql/algebra/operator/is_iri'
+    autoload :IsURI,              'sparql/algebra/operator/is_iri'
+    autoload :IsLiteral,          'sparql/algebra/operator/is_literal'
+    autoload :Str,                'sparql/algebra/operator/str'
+    autoload :Lang,               'sparql/algebra/operator/lang'
+    autoload :Datatype,           'sparql/algebra/operator/datatype'
+
+    # Binary operators
+    autoload :Or,                 'sparql/algebra/operator/or'
+    autoload :And,                'sparql/algebra/operator/and'
+    autoload :Compare,            'sparql/algebra/operator/compare'
+    autoload :Equal,              'sparql/algebra/operator/equal'
+    autoload :NotEqual,           'sparql/algebra/operator/not_equal'
+    autoload :LessThan,           'sparql/algebra/operator/less_than'
+    autoload :GreaterThan,        'sparql/algebra/operator/greater_than'
+    autoload :LessThanOrEqual,    'sparql/algebra/operator/less_than_or_equal'
+    autoload :GreaterThanOrEqual, 'sparql/algebra/operator/greater_than_or_equal'
+    autoload :Multiply,           'sparql/algebra/operator/multiply'
+    autoload :Divide,             'sparql/algebra/operator/divide'
+    autoload :Add,                'sparql/algebra/operator/add'
+    autoload :Subtract,           'sparql/algebra/operator/subtract'
+    autoload :SameTerm,           'sparql/algebra/operator/same_term'
+    autoload :LangMatches,        'sparql/algebra/operator/lang_matches'
+    autoload :Regex,              'sparql/algebra/operator/regex'
+
+    # Miscellaneous
+    autoload :Asc,                'sparql/algebra/operator/asc'
+    autoload :Desc,               'sparql/algebra/operator/desc'
+    autoload :Exprlist,           'sparql/algebra/operator/exprlist'
+
+    # Query operators
+    autoload :Ask,                'sparql/algebra/operator/ask'
+    autoload :Base,               'sparql/algebra/operator/base'
+    autoload :BGP,                'sparql/algebra/operator/bgp'
+    autoload :Construct,          'sparql/algebra/operator/construct'
+    autoload :Dataset,            'sparql/algebra/operator/dataset'
+    autoload :Describe,           'sparql/algebra/operator/describe'
+    autoload :Distinct,           'sparql/algebra/operator/distinct'
+    autoload :Filter,             'sparql/algebra/operator/filter'
+    autoload :Graph,              'sparql/algebra/operator/graph'
+    autoload :Join,               'sparql/algebra/operator/join'
+    autoload :LeftJoin,           'sparql/algebra/operator/left_join'
+    autoload :Order,              'sparql/algebra/operator/order'
+    autoload :Prefix,             'sparql/algebra/operator/prefix'
+    autoload :Project,            'sparql/algebra/operator/project'
+    autoload :Reduced,            'sparql/algebra/operator/reduced'
+    autoload :Slice,              'sparql/algebra/operator/slice'
+    autoload :Union,              'sparql/algebra/operator/union'
+
+    ##
+    # Returns an operator class for the given operator `name`.
+    #
+    # @param  [Symbol, #to_s]  name
+    # @param  [Integer] arity
+    # @return [Class] an operator class, or `nil` if an operator was not found
+    def self.for(name, arity = nil)
+      # TODO: refactor this to dynamically introspect loaded operator classes.
+      case (name.to_s.downcase.to_sym rescue nil)
+        when :<=>         then Compare # non-standard
+        when :'='         then Equal
+        when :'!='        then NotEqual
+        when :<           then LessThan
+        when :>           then GreaterThan
+        when :<=          then LessThanOrEqual
+        when :>=          then GreaterThanOrEqual
+        when :*           then Multiply
+        when :'/'         then Divide
+        when :+           then arity.eql?(1) ? Plus  : Add
+        when :-           then arity.eql?(1) ? Minus : Subtract
+        when :not, :'!'   then Not
+        when :plus        then Plus
+        when :minus       then Minus
+        when :bound       then Bound
+        when :isblank     then IsBlank
+        when :isiri       then IsIRI
+        when :isuri       then IsIRI # alias
+        when :isliteral   then IsLiteral
+        when :str         then Str
+        when :lang        then Lang
+        when :datatype    then Datatype
+        when :or, :'||'   then Or
+        when :and, :'&&'  then And
+        when :multiply    then Multiply
+        when :divide      then Divide
+        when :add         then Add
+        when :subtract    then Subtract
+        when :sameterm    then SameTerm
+        when :langmatches then LangMatches
+        when :regex       then Regex
+        
+        # Miscellaneous
+        when :asc         then Asc
+        when :desc        then Desc
+        when :exprlist    then Exprlist
+
+        # Datasets
+        when :dataset     then Dataset
+        
+        # Query forms
+        when :ask         then Ask
+        when :base        then Base
+        when :bgp         then BGP
+        when :construct   then Construct
+        when :describe    then Describe
+        when :distinct    then Distinct
+        when :filter      then Filter
+        when :graph       then Graph
+        when :join        then Join
+        when :leftjoin    then LeftJoin
+        when :order       then Order
+        when :prefix      then Prefix
+        when :project     then Project
+        when :reduced     then Reduced
+        when :slice       then Slice
+        when :triple      then RDF::Query::Pattern
+        when :union       then Union
+        else nil # not found
+      end
+    end
+
+    ##
+    # @param  [Array<RDF::Term>] operands
+    # @return [RDF::Term]
+    # @see    Operator#evaluate
+    def self.evaluate(*operands)
+      self.new(*operands).evaluate(RDF::Query::Solution.new)
+    end
+
+    ##
+    # Returns the arity of this operator class.
+    #
+    # @example
+    #   Operator.arity           #=> -1
+    #   Operator::Nullary.arity  #=> 0
+    #   Operator::Unary.arity    #=> 1
+    #   Operator::Binary.arity   #=> 2
+    #   Operator::Ternary.arity  #=> 3
+    #
+    # @return [Integer] an integer in the range `(-1..3)`
+    def self.arity
+      self.const_get(:ARITY)
+    end
+
+    ARITY = -1 # variable arity
+
+    ##
+    # Initializes a new operator instance.
+    #
+    # @param  [Array<RDF::Term>] operands
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options
+    # @option options [Boolean] :memoize (false)
+    #   whether to memoize results for particular operands
+    # @raise  [TypeError] if any operand is invalid
+    def initialize(*operands)
+      @options  = operands.last.is_a?(Hash) ? operands.pop.dup : {}
+      @operands = operands.map! do |operand|
+        case operand
+          when Operator, Variable, RDF::Term, RDF::Query, RDF::Query::Pattern, Array, Symbol
+            operand
+          when TrueClass, FalseClass, Numeric, String, DateTime, Date, Time
+            RDF::Literal(operand)
+          else raise TypeError, "invalid SPARQL::Algebra::Operator operand: #{operand.inspect}"
+        end
+      end
+    end
+
+    ##
+    # Base URI used for reading data sources with relative URIs
+    #
+    # @return [RDF::URI]
+    def base_uri
+      Operator.base_uri
+    end
+    
+    ##
+    # Base URI used for reading data sources with relative URIs
+    #
+    # @return [RDF::URI]
+    def self.base_uri
+      @base_uri
+    end
+    
+    ##
+    # Set Base URI associated with SPARQL document, typically done
+    # when reading SPARQL from a URI
+    #
+    # @param [RDF::URI] base
+    # @return [RDF::URI]
+    def self.base_uri=(uri)
+      @base_uri = RDF::URI(uri)
+    end
+    
+    ##
+    # Prefixes useful for future serialization
+    #
+    # @return [Hash{Symbol => RDF::URI}]
+    #   Prefix definitions
+    def prefixes
+      Operator.prefixes
+    end
+    
+    ##
+    # Prefixes useful for future serialization
+    #
+    # @return [Hash{Symbol => RDF::URI}]
+    #   Prefix definitions
+    def self.prefixes
+      @prefixes
+    end
+    
+    ##
+    # Prefixes useful for future serialization
+    #
+    # @param [Hash{Symbol => RDF::URI}] hash
+    #   Prefix definitions
+    # @return [Hash{Symbol => RDF::URI}]
+    def self.prefixes=(hash)
+      @prefixes = hash
+    end
+    
+    ##
+    # Any additional options for this operator.
+    #
+    # @return [Hash]
+    attr_reader :options
+
+    ##
+    # The operands to this operator.
+    #
+    # @return [Array]
+    attr_reader :operands
+
+    ##
+    # Returns the operand at the given `index`.
+    #
+    # @param  [Integer] index
+    #   an operand index in the range `(0...(operands.count))`
+    # @return [RDF::Term]
+    def operand(index = 0)
+      operands[index]
+    end
+
+    ##
+    # Returns `true` if any of the operands are variables, `false`
+    # otherwise.
+    #
+    # @return [Boolean] `true` or `false`
+    # @see    #constant?
+    def variable?
+      operands.any? do |operand|
+        operand.is_a?(Variable) ||
+          (operand.respond_to?(:variable?) && operand.variable?)
+      end
+    end
+
+    ##
+    # Returns `true` if this is evaluatable (i.e., returns values for a binding), `false`
+    # otherwise.
+    #
+    # @return [Boolean] `true` or `false`
+    def evaluatable?
+      respond_to?(:evaluate)
+    end
+
+    ##
+    # Returns `true` if this is executable (i.e., contains a graph patterns), `false`
+    # otherwise.
+    #
+    # @return [Boolean] `true` or `false`
+    def executable?
+      respond_to?(:execute)
+    end
+
+    ##
+    # Returns `true` if none of the operands are variables, `false`
+    # otherwise.
+    #
+    # @return [Boolean] `true` or `false`
+    # @see    #variable?
+    def constant?
+      !(variable?)
+    end
+
+    ##
+    # Returns an optimized version of this expression.
+    #
+    # For constant expressions containing no variables, returns the result
+    # of evaluating the expression with empty bindings; otherwise returns
+    # `self`.
+    #
+    # Optimization is not possible if the expression raises an exception,
+    # such as a `TypeError` or `ZeroDivisionError`, which must be conserved
+    # at runtime.
+    #
+    # @return [SPARQL::Algebra::Expression]
+    def optimize
+      if constant?
+        # Note that if evaluation results in a `TypeError` or other error,
+        # we must return `self` so that the error is conserved at runtime:
+        evaluate rescue self
+      else
+        super # returns `self`
+      end
+    end
+
+    ##
+    # Returns the SPARQL S-Expression (SSE) representation of this operator.
+    #
+    # @return [Array]
+    # @see    http://openjena.org/wiki/SSE
+    def to_sse
+      operator = [self.class.const_get(:NAME)].flatten.first
+      [operator, *(operands || []).map(&:to_sse)]
+    end
+
+    ##
+    # Returns an S-Expression (SXP) representation of this operator
+    #
+    # @return [String]
+    def to_sxp
+      begin
+        require 'sxp' # @see http://rubygems.org/gems/sxp
+      rescue LoadError
+        abort "SPARQL::Algebra::Operator#to_sxp requires the SXP gem (hint: `gem install sxp')."
+      end
+      require 'sparql/algebra/sxp_extensions'
+      
+      to_sse.to_sxp
+    end
+
+    ##
+    # Returns a developer-friendly representation of this operator.
+    #
+    # @return [String]
+    def inspect
+      sprintf("#<%s:%#0x(%s)>", self.class.name, __id__, operands.map(&:inspect).join(', '))
+    end
+
+    ##
+    # @param  [Statement] other
+    # @return [Boolean]
+    def eql?(other)
+      other.class == self.class && other.operands == self.operands
+    end
+    alias_method :==, :eql?
+  protected
+
+    ##
+    # Returns the effective boolean value (EBV) of the given `literal`.
+    #
+    # @param  [RDF::Literal] literal
+    # @return [RDF::Literal::Boolean] `true` or `false`
+    # @raise  [TypeError] if the literal could not be coerced to an `RDF::Literal::Boolean`
+    # @see    http://www.w3.org/TR/rdf-sparql-query/#ebv
+    def boolean(literal)
+      case literal
+        when FalseClass then RDF::Literal::FALSE
+        when TrueClass  then RDF::Literal::TRUE
+        # If the argument is a typed literal with a datatype of
+        # `xsd:boolean`, the EBV is the value of that argument.
+        # However, the EBV of any literal whose type is `xsd:boolean` is
+        # false if the lexical form is not valid for that datatype.
+        when RDF::Literal::Boolean
+          RDF::Literal(literal.valid? && literal.true?)
+        # If the argument is a numeric type or a typed literal with a
+        # datatype derived from a numeric type, the EBV is false if the
+        # operand value is NaN or is numerically equal to zero; otherwise
+        # the EBV is true.
+        # However, the EBV of any literal whose type is numeric is
+        # false if the lexical form is not valid for that datatype.
+        when RDF::Literal::Numeric
+          RDF::Literal(literal.valid? && !(literal.zero?) && !(literal.respond_to?(:nan?) && literal.nan?))
+        # If the argument is a plain literal or a typed literal with a
+        # datatype of `xsd:string`, the EBV is false if the operand value
+        # has zero length; otherwise the EBV is true.
+        else case
+          when literal.is_a?(RDF::Literal) && (literal.plain? || literal.datatype.eql?(RDF::XSD.string))
+            RDF::Literal(!(literal.value.empty?))
+        # All other arguments, including unbound arguments, produce a type error.
+          else raise TypeError, "could not coerce #{literal.inspect} to an RDF::Literal::Boolean"
+        end
+      end
+    end
+
+  private
+
+    @@subclasses = [] # @private
+
+    ##
+    # @private
+    # @return [void]
+    def self.inherited(child)
+      @@subclasses << child unless child.superclass.equal?(Operator) # grandchildren only
+      super
+    end
+
+    ##
+    # A SPARQL nullary operator.
+    #
+    # Operators of this kind take no operands.
+    #
+    # @abstract
+    class Nullary < Operator
+      ARITY = 0
+
+      ##
+      # @param  [Hash{Symbol => Object}] options
+      #   any additional options (see {Operator#initialize})
+      def initialize(options = {})
+        super
+      end
+    end # Nullary
+
+    ##
+    # A SPARQL unary operator.
+    #
+    # Operators of this kind take one operand.
+    #
+    # @abstract
+    class Unary < Operator
+      ARITY = 1
+
+      ##
+      # @param  [RDF::Term] arg
+      #   the operand
+      # @param  [Hash{Symbol => Object}] options
+      #   any additional options (see {Operator#initialize})
+      def initialize(arg, options = {})
+        super
+      end
+    end # Unary
+
+    ##
+    # A SPARQL binary operator.
+    #
+    # Operators of this kind take two operands.
+    #
+    # @abstract
+    class Binary < Operator
+      ARITY = 2
+
+      ##
+      # @param  [RDF::Term] arg1
+      #   the first operand
+      # @param  [RDF::Term] arg2
+      #   the second operand
+      # @param  [Hash{Symbol => Object}] options
+      #   any additional options (see {Operator#initialize})
+      def initialize(arg1, arg2, options = {})
+        super
+      end
+    end # Binary
+
+    ##
+    # A SPARQL ternary operator.
+    #
+    # Operators of this kind take three operands.
+    #
+    # @abstract
+    class Ternary < Operator
+      ARITY = 3
+
+      ##
+      # @param  [RDF::Term] arg1
+      #   the first operand
+      # @param  [RDF::Term] arg2
+      #   the second operand
+      # @param  [RDF::Term] arg3
+      #   the third operand
+      # @param  [Hash{Symbol => Object}] options
+      #   any additional options (see {Operator#initialize})
+      def initialize(arg1, arg2, arg3, options = {})
+        super
+      end
+    end # Ternary
+  end # Operator
+end; end # SPARQL::Algebra