sparql 0.0.1 → 0.0.2

data/lib/sparql/algebra.rb

@@ -0,0 +1,369 @@
+require 'rdf' # @see http://rubygems.org/gems/rdf
+require 'rdf/xsd'
+
+module SPARQL
+  ##
+  # A SPARQL algebra for RDF.rb.
+  #
+  # Parses Sparql S-Expressions (SSE) into SPARQL Algebra operators.
+  #
+  # Operators implementing {SPARQL::Algebra::Query#execute} may directly
+  # execute an object implementing {RDF::Queryable}, and so may be treated
+  # equivalently to {RDF::Query}.
+  #
+  # Operators implementing {SPARQL::Algebra::Expression#evaluate} may be
+  # evaluated with RDF::Query::Solution bindings to yield an appropriate result.
+  #
+  # An entire SSE expression is parsed into a recursive set of {SPARQL::Algebra::Operator}
+  # instances, with each operand representing an additional operator.
+  #
+  # {RDF::Query} and {RDF::Query::Pattern} are used as primitives for `bgp` and `triple` expressions.
+  #
+  # # Queries
+  # 
+  #     require 'sparql/algebra'
+  # 
+  #     include SPARQL::Algebra
+  # 
+  # ## Basic Query
+  #     BASE <http://example.org/x/> 
+  #     PREFIX : <>
+  # 
+  #     SELECT * WHERE { :x ?p ?v } 
+  # 
+  # is equivalent to
+  # 
+  #     (base <http://example.org/x/>
+  #       (prefix ((: <>))
+  #         (bgp (triple :x ?p ?v))))
+  # 
+  # ## Prefixes
+  # 
+  #     PREFIX ns: <http://example.org/ns#>
+  #     PREFIX x:  <http://example.org/x/>
+  # 
+  #     SELECT * WHERE { x:x ns:p ?v } 
+  # 
+  # is equivalent to
+  # 
+  #     (prefix ((ns: <http://example.org/ns#>)
+  #              (x: <http://example.org/x/>))
+  #       (bgp (triple x:x ns:p ?v)))
+  # 
+  # ## Ask
+  # 
+  #     PREFIX :  <http://example/>
+  # 
+  #     ASK WHERE { :x :p ?x } 
+  # 
+  # is equivalent to
+  # 
+  #     (prefix ((: <http://example/>))
+  #       (ask
+  #         (bgp (triple :x :p ?x))))
+  # 
+  # ## Datasets
+  # 
+  #     PREFIX : <http://example/> 
+  # 
+  #     SELECT * 
+  #     FROM <data-g1.ttl>
+  #     FROM NAMED <data-g2.ttl>
+  #     { ?s ?p ?o }
+  # 
+  # is equivalent to
+  # 
+  #     (prefix ((: <http://example/>))
+  #       (dataset (<data-g1.ttl> (named <data-g2.ttl>))
+  #         (bgp (triple ?s ?p ?o))))
+  # 
+  # ## Join
+  # 
+  #     PREFIX : <http://example/> 
+  # 
+  #     SELECT * 
+  #     { 
+  #        ?s ?p ?o
+  #        GRAPH ?g { ?s ?q ?v }
+  #     }
+  # 
+  # is equivalent to
+  # 
+  #     (prefix ((: <http://example/>))
+  #       (join
+  #         (bgp (triple ?s ?p ?o))
+  #         (graph ?g
+  #           (bgp (triple ?s ?q ?v)))))
+  # 
+  # ## Union
+  # 
+  #     PREFIX : <http://example/> 
+  # 
+  #     SELECT * 
+  #     { 
+  #        { ?s ?p ?o }
+  #       UNION
+  #        { GRAPH ?g { ?s ?p ?o } }
+  #     }
+  # 
+  # is equivalent to
+  # 
+  #     (prefix ((: <http://example/>))
+  #       (union
+  #         (bgp (triple ?s ?p ?o))
+  #         (graph ?g
+  #           (bgp (triple ?s ?p ?o)))))
+  # 
+  # ## LeftJoin
+  # 
+  #     PREFIX :    <http://example/>
+  # 
+  #     SELECT *
+  #     { 
+  #       ?x :p ?v .
+  #       OPTIONAL
+  #       { 
+  #         ?y :q ?w .
+  #         FILTER(?v=2)
+  #       }
+  #     }
+  # 
+  # is equivalent to
+  # 
+  #     (prefix ((: <http://example/>))
+  #       (leftjoin
+  #         (bgp (triple ?x :p ?v))
+  #         (bgp (triple ?y :q ?w))
+  #         (= ?v 2)))
+  # 
+  # # Expressions
+  # 
+  # ## Constructing operator expressions manually
+  # 
+  #     Operator(:isBlank).new(RDF::Node(:foobar)).to_sxp                        #=> "(isBlank _:foobar)"
+  #     Operator(:isIRI).new(RDF::URI('http://rdf.rubyforge.org/')).to_sxp       #=> "(isIRI <http://rdf.rubyforge.org/>)"
+  #     Operator(:isLiteral).new(RDF::Literal(3.1415)).to_sxp                    #=> "(isLiteral 3.1415)"
+  #     Operator(:str).new(Operator(:datatype).new(RDF::Literal(3.1415))).to_sxp #=> "(str (datatype 3.1415))"
+  # 
+  # ## Constructing operator expressions using SSE forms
+  # 
+  #     Expression[:isBlank, RDF::Node(:foobar)].to_sxp                          #=> "(isBlank _:foobar)"
+  #     Expression[:isIRI, RDF::URI('http://rdf.rubyforge.org/')].to_sxp         #=> "(isIRI <http://rdf.rubyforge.org/>)"
+  #     Expression[:isLiteral, RDF::Literal(3.1415)].to_sxp                      #=> "(isLiteral 3.1415)"
+  #     Expression[:str, [:datatype, RDF::Literal(3.1415)]].to_sxp               #=> "(str (datatype 3.1415))"
+  # 
+  # ## Constructing operator expressions using SSE strings
+  # 
+  #     Expression.parse('(isBlank _:foobar)')
+  #     Expression.parse('(isIRI <http://rdf.rubyforge.org/>)')
+  #     Expression.parse('(isLiteral 3.1415)')
+  #     Expression.parse('(str (datatype 3.1415))')
+  # 
+  # ## Evaluating operators standalone
+  # 
+  #     Operator(:isBlank).evaluate(RDF::Node(:foobar))                          #=> RDF::Literal::TRUE
+  #     Operator(:isIRI).evaluate(RDF::DC.title)                                 #=> RDF::Literal::TRUE
+  #     Operator(:isLiteral).evaluate(RDF::Literal(3.1415))                      #=> RDF::Literal::TRUE
+  # 
+  # ## Optimizing expressions containing constant subexpressions
+  # 
+  #     Expression.parse('(sameTerm ?var ?var)').optimize            #=> RDF::Literal::TRUE
+  #     Expression.parse('(* -2 (- (* (+ 1 2) (+ 3 4))))').optimize  #=> RDF::Literal(42)
+  # 
+  # ## Evaluating expressions on a solution sequence
+  # 
+  #     # Find all people and their names & e-mail addresses:
+  #     solutions = RDF::Query.execute(RDF::Graph.load('etc/doap.ttl')) do |query|
+  #       query.pattern [:person, RDF.type,  RDF::FOAF.Person]
+  #       query.pattern [:person, RDF::FOAF.name, :name]
+  #       query.pattern [:person, RDF::FOAF.mbox, :email], :optional => true
+  #     end
+  # 
+  #     # Find people who have a name but don't have a known e-mail address:
+  #     expression = Expression[:not, [:bound, Variable(:email)]]    # ...or just...
+  #     expression = Expression.parse('(not (bound ?email))')
+  #     solutions.filter!(expression)
+  # 
+  # @example Optimizations
+  # 
+  # Some very simple optimizations are currently implemented for `FILTER`
+  # expressions. Use the following to obtain optimized SSE forms:
+  # 
+  #     Expression.parse(sse).optimize.to_sse
+  # 
+  # ## Constant comparison folding
+  # 
+  #     (sameTerm ?x ?x)   #=> true
+  # 
+  # ## Constant arithmetic folding
+  # 
+  #     (!= ?x (+ 123))    #=> (!= ?x 123)
+  #     (!= ?x (- -1.0))   #=> (!= ?x 1.0)
+  #     (!= ?x (+ 1 2))    #=> (!= ?x 3)
+  #     (!= ?x (- 4 5))    #=> (!= ?x -1)
+  #     (!= ?x (* 6 7))    #=> (!= ?x 42)
+  #     (!= ?x (/ 0 0.0))  #=> (!= ?x NaN)
+  # 
+  # ## Memoization
+  # 
+  # Expressions can optionally be [memoized][memoization], which can speed up
+  # repeatedly executing the expression on a solution sequence:
+  # 
+  #     Expression.parse(sse, :memoize => true)
+  #     Operator.new(*operands, :memoize => true)
+  # 
+  # Memoization is implemented using RDF.rb's [RDF::Util::Cache][] utility
+  # library, a weak-reference cache that allows values contained in the cache to
+  # be garbage collected. This allows the cache to dynamically adjust to
+  # changing memory conditions, caching more objects when memory is plentiful,
+  # but evicting most objects if memory pressure increases to the point of
+  # scarcity.
+  # 
+  # [memoization]:      http://en.wikipedia.org/wiki/Memoization
+  # [RDF::Util::Cache]: http://rdf.rubyforge.org/RDF/Util/Cache.html
+  # 
+  # ## Documentation
+  # 
+  # * {SPARQL::Algebra}
+  #   * {SPARQL::Algebra::Expression}
+  #   * {SPARQL::Algebra::Query}
+  #   * {SPARQL::Algebra::Operator}
+  #     * {SPARQL::Algebra::Operator::Add}
+  #     * {SPARQL::Algebra::Operator::And}
+  #     * {SPARQL::Algebra::Operator::Asc}
+  #     * {SPARQL::Algebra::Operator::Ask}
+  #     * {SPARQL::Algebra::Operator::Base}
+  #     * {SPARQL::Algebra::Operator::Bound}
+  #     * {SPARQL::Algebra::Operator::Compare}
+  #     * {SPARQL::Algebra::Operator::Construct}
+  #     * {SPARQL::Algebra::Operator::Dataset}
+  #     * {SPARQL::Algebra::Operator::Datatype}
+  #     * {SPARQL::Algebra::Operator::Desc}
+  #     * {SPARQL::Algebra::Operator::Describe}
+  #     * {SPARQL::Algebra::Operator::Distinct}
+  #     * {SPARQL::Algebra::Operator::Divide}
+  #     * {SPARQL::Algebra::Operator::Equal}
+  #     * {SPARQL::Algebra::Operator::Exprlist}
+  #     * {SPARQL::Algebra::Operator::Filter}
+  #     * {SPARQL::Algebra::Operator::Graph}
+  #     * {SPARQL::Algebra::Operator::GreaterThan}
+  #     * {SPARQL::Algebra::Operator::GreaterThanOrEqual}
+  #     * {SPARQL::Algebra::Operator::IsBlank}
+  #     * {SPARQL::Algebra::Operator::IsIRI}
+  #     * {SPARQL::Algebra::Operator::IsLiteral}
+  #     * {SPARQL::Algebra::Operator::Join}
+  #     * {SPARQL::Algebra::Operator::Lang}
+  #     * {SPARQL::Algebra::Operator::LangMatches}
+  #     * {SPARQL::Algebra::Operator::LeftJoin}
+  #     * {SPARQL::Algebra::Operator::LessThan}
+  #     * {SPARQL::Algebra::Operator::LessThanOrEqual}
+  #     * {SPARQL::Algebra::Operator::Minus}
+  #     * {SPARQL::Algebra::Operator::Multiply}
+  #     * {SPARQL::Algebra::Operator::Not}
+  #     * {SPARQL::Algebra::Operator::NotEqual}
+  #     * {SPARQL::Algebra::Operator::Or}
+  #     * {SPARQL::Algebra::Operator::Order}
+  #     * {SPARQL::Algebra::Operator::Plus}
+  #     * {SPARQL::Algebra::Operator::Prefix}
+  #     * {SPARQL::Algebra::Operator::Project}
+  #     * {SPARQL::Algebra::Operator::Reduced}
+  #     * {SPARQL::Algebra::Operator::Regex}
+  #     * {SPARQL::Algebra::Operator::SameTerm}
+  #     * {SPARQL::Algebra::Operator::Slice}
+  #     * {SPARQL::Algebra::Operator::Str}
+  #     * {SPARQL::Algebra::Operator::Subtract}
+  #     * {SPARQL::Algebra::Operator::Union}
+  # 
+  # TODO
+  # ====
+  # * Need to come up with appropriate SXP for SPARQL 1.1
+  # * Operator#optimize needs to be completed and tested.
+  # 
+  # @see http://www.w3.org/TR/rdf-sparql-query/#sparqlAlgebra
+  module Algebra
+    include RDF
+
+    autoload :Evaluatable, 'sparql/algebra/evaluatable'
+    autoload :Expression,  'sparql/algebra/expression'
+    autoload :Operator,    'sparql/algebra/operator'
+    autoload :Query,       'sparql/algebra/query'
+
+    ##
+    # @example
+    #   sse = (prefix ((foaf: <http://xmlns.com/foaf/0.1/>))
+    #           (project (?name ?mbox)
+    #             (join
+    #               (bgp (triple ?x foaf:name ?name))
+    #               (bgp (triple ?x foaf:mbox ?mbox)))))
+    #   }
+    # @param  [String] sse
+    #   a SPARQL S-Expression (SSE) string
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options (see {Operator#initialize})
+    # @return [SPARQL::Algebra::Operator]
+    def parse(sse, options = {})
+      Expression.parse(sse, options)
+    end
+    module_function :parse
+
+    ##
+    # Parses input from the given file name or URL.
+    #
+    # @param  [String, #to_s] filename
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options (see {Operator#initialize})
+    # @option options [RDF::URI, #to_s] :base_uri
+    #   Base URI used for loading relative URIs.
+    #
+    # @yield  [expression]
+    # @yieldparam  [SPARQL::Algebra::Expression] expression
+    # @yieldreturn [void] ignored
+    # @return [Expression]
+    def open(sse, options = {})
+      Expression.open(sse, options)
+    end
+    module_function :open
+
+    ##
+    # @example
+    #   Expression(:isLiteral, RDF::Literal(3.1415))
+    #
+    # @param  [Array] sse
+    #   a SPARQL S-Expression (SSE) form
+    # @return [SPARQL::Algebra::Expression]
+    def Expression(*sse)
+      Expression.for(*sse)
+    end
+    alias_method :Expr, :Expression
+    module_function :Expr, :Expression
+
+    ##
+    # @example
+    #   Operator(:isLiteral)
+    #
+    # @param  [Symbol, #to_sym] name
+    # @return [Class]
+    def Operator(name, arity = nil)
+      Operator.for(name, arity)
+    end
+    alias_method :Op, :Operator
+    module_function :Op, :Operator
+
+    ##
+    # @example
+    #   Variable(:foobar)
+    #
+    # @param  [Symbol, #to_sym] name
+    # @return [Variable]
+    # @see    http://rdf.rubyforge.org/RDF/Query/Variable.html
+    def Variable(name)
+      Variable.new(name)
+    end
+    alias_method :Var, :Variable
+    module_function :Var, :Variable
+
+    Variable = RDF::Query::Variable
+  end # Algebra
+end # SPARQL
+
+require 'sparql/algebra/extensions'

data/lib/sparql/algebra/evaluatable.rb

@@ -0,0 +1,37 @@
+module SPARQL; module Algebra
+  ##
+  # Mixin for Algebra::Operator sub-classes that evaluate bindings to return a result
+  #
+  # @abstract
+  module Evaluatable
+    ##
+    # Evaluates this operator using the given variable `bindings`.
+    #
+    # @param  [RDF::Query::Solution, #[]] bindings
+    #   a query solution containing zero or more variable bindings
+    # @return [RDF::Term]
+    # @abstract
+    def evaluate(bindings = {})
+      args = operands.map { |operand| operand.evaluate(bindings) }
+      options[:memoize] ? memoize(*args) : apply(*args)
+    end
+
+    ##
+    # @param  [Array<RDF::Term>] operands
+    #   evaluated operands
+    # @return [RDF::Term] the memoized result
+    def memoize(*operands)
+      @cache ||= RDF::Util::Cache.new(options[:memoize].is_a?(Integer) ? options[:memoize] : -1)
+      @cache[operands] ||= apply(*operands)
+    end
+
+    ##
+    # @param  [Array<RDF::Term>] operands
+    #   evaluated operands
+    # @return [RDF::Term]
+    # @abstract
+    def apply(*operands)
+      raise NotImplementedError, "#{self.class}#apply(#{operands.map(&:class).join(', ')})"
+    end
+  end # Query
+end; end # SPARQL::Algebra

data/lib/sparql/algebra/expression.rb

@@ -0,0 +1,284 @@
+module SPARQL; module Algebra
+  ##
+  # A SPARQL algebra expression.
+  #
+  # @abstract
+  module Expression
+    ##
+    # @example
+    #   Expression.parse('(isLiteral 3.1415)')
+    #
+    # @param  [IO, String, #read, #to_s] sse
+    #   a SPARQL S-Expression (SSE) string or IO object responding to #read
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options (see {Operator#initialize})
+    # @option options [RDF::URI, #to_s] :base_uri
+    #   Base URI used for loading relative URIs.
+    #
+    # @yield  [expression]
+    # @yieldparam  [SPARQL::Algebra::Expression] expression
+    # @yieldreturn [void] ignored
+    # @return [Expression]
+    def self.parse(sse, options = {}, &block)
+      begin
+        require 'sxp' # @see http://rubygems.org/gems/sxp
+      rescue LoadError
+        abort "SPARQL::Algebra::Expression.parse requires the SXP gem (hint: `gem install sxp')."
+      end
+      require 'sparql/algebra/sxp_extensions'
+      
+      if sse.respond_to?(:force_encoding)      # Ruby 1.9+
+        sse = sse.dup.force_encoding(Encoding::UTF_8)
+      end
+      sxp = SXP::Reader::SPARQL.new(sse) do |reader|
+        # Set base_uri if we have one
+        reader.base_uri = options[:base_uri] if options[:base_uri]
+      end
+      sxp_result = sxp.read
+
+      debug(options) {"base_uri: #{options[:base_uri]}"}
+      Operator.base_uri = options.delete(:base_uri) if options.has_key?(:base_uri)
+      Operator.prefixes = sxp.prefixes || {}
+
+      expression = self.new(sxp_result, options)
+
+      yield(expression) if block_given?
+      expression
+    end
+
+    ##
+    # Parses input from the given file name or URL.
+    #
+    # @param  [String, #to_s] filename
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options (see {Operator#initialize})
+    # @option options [RDF::URI, #to_s] :base_uri
+    #   Base URI used for loading relative URIs.
+    #
+    # @yield  [expression]
+    # @yieldparam  [SPARQL::Algebra::Expression] expression
+    # @yieldreturn [void] ignored
+    # @return [Expression]
+    def self.open(filename, options = {}, &block)
+      RDF::Util::File.open_file(filename, options) do |file|
+        options[:base_uri] ||= filename
+        Expression.parse(file, options, &block)
+      end
+    end
+
+    ##
+    # @example
+    #   Expression.for(:isLiteral, RDF::Literal(3.1415))
+    #   Expression[:isLiteral, RDF::Literal(3.1415)]
+    #
+    # @param  [Array] sse
+    #   a SPARQL S-Expression (SSE) form
+    # @return [Expression]
+    def self.for(*sse)
+      self.new(sse)
+    end
+    class << self; alias_method :[], :for; end
+
+    ##
+    # @example
+    #   Expression.new([:isLiteral, RDF::Literal(3.1415)], :version => 1.0)
+    #
+    # @param  [Array] sse
+    #   a SPARQL S-Expression (SSE) form
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options (see {Operator#initialize})
+    # @return [Expression]
+    # @raise  [TypeError] if any of the operands is invalid
+    def self.new(sse, options = {})
+      raise ArgumentError, "invalid SPARQL::Algebra::Expression form: #{sse.inspect}" unless sse.is_a?(Array)
+
+      operator = Operator.for(sse.first, sse.length - 1)
+      unless operator
+        return case sse.first
+        when Array
+          debug(options) {"Map array elements #{sse}"}
+          sse.map {|s| self.new(s, options.merge(:depth => options[:depth].to_i + 1))}
+        else
+          debug(options) {"No operator found for #{sse.first}"}
+          sse.map do |s|
+            s.is_a?(Array) ?
+              self.new(s, options.merge(:depth => options[:depth].to_i + 1)) :
+              s
+          end
+        end
+      end
+
+      operands = sse[1..-1].map do |operand|
+        debug(options) {"Operator=#{operator.inspect}, Operand=#{operand.inspect}"}
+        case operand
+          when Array
+            self.new(operand, options.merge(:depth => options[:depth].to_i + 1))
+          when Operator, Variable, RDF::Term, RDF::Query, Symbol
+            operand
+          when TrueClass, FalseClass, Numeric, String, DateTime, Date, Time
+            RDF::Literal(operand)
+          else raise TypeError, "invalid SPARQL::Algebra::Expression operand: #{operand.inspect}"
+        end
+      end
+
+      debug(options) {"#{operator.inspect}(#{operands.map(&:inspect).join(',')})"}
+      options.delete_if {|k, v| [:debug, :depth, :prefixes, :base_uri].include?(k) }
+      operands << options unless options.empty?
+      operator.new(*operands)
+    end
+
+    ##
+    # Casts operand as the specified datatype
+    #
+    # @param [RDF::URI] datatype
+    #   Datatype to evaluate, one of:
+    #   xsd:integer, xsd:decimal xsd:float, xsd:double, xsd:string, xsd:boolean, or xsd:dateTime
+    # @param [RDF::Term] value
+    #   Value, which should be a typed literal, where the type must be that specified
+    # @raise [TypeError] if datatype is not a URI or value cannot be cast to datatype
+    # @return [Boolean]
+    # @see http://www.w3.org/TR/rdf-sparql-query/#FunctionMapping
+    def self.cast(datatype, value)
+      case datatype
+      when RDF::XSD.dateTime
+        case value
+        when RDF::Literal::DateTime, RDF::Literal::Date, RDF::Literal::Time
+          RDF::Literal.new(value, :datatype => datatype)
+        when RDF::Literal::Numeric, RDF::Literal::Boolean, RDF::URI, RDF::Node
+          raise TypeError, "Value #{value.inspect} cannot be cast as #{datatype}"
+        else
+          RDF::Literal.new(value.value, :datatype => datatype, :validate => true)
+        end
+      when RDF::XSD.float, RDF::XSD.double
+        case value
+        when RDF::Literal::Numeric, RDF::Literal::Boolean
+          RDF::Literal.new(value, :datatype => datatype)
+        when RDF::Literal::DateTime, RDF::Literal::Date, RDF::Literal::Time, RDF::URI, RDF::Node
+          raise TypeError, "Value #{value.inspect} cannot be cast as #{datatype}"
+        else
+          RDF::Literal.new(value.value, :datatype => datatype, :validate => true)
+        end
+      when RDF::XSD.boolean
+        case value
+        when RDF::Literal::Boolean
+          value
+        when RDF::Literal::Numeric
+          RDF::Literal::Boolean.new(value.value != 0)
+        when RDF::Literal::DateTime, RDF::Literal::Date, RDF::Literal::Time, RDF::URI, RDF::Node
+          raise TypeError, "Value #{value.inspect} cannot be cast as #{datatype}"
+        else
+          RDF::Literal.new(!value.to_s.empty?, :datatype => datatype, :validate => true)
+        end
+      when RDF::XSD.decimal, RDF::XSD.integer
+        case value
+        when RDF::Literal::Integer, RDF::Literal::Decimal, RDF::Literal::Boolean
+          RDF::Literal.new(value, :datatype => datatype)
+        when RDF::Literal::DateTime, RDF::Literal::Date, RDF::Literal::Time, RDF::URI, RDF::Node
+          raise TypeError, "Value #{value.inspect} cannot be cast as #{datatype}"
+        else
+          RDF::Literal.new(value.value, :datatype => datatype, :validate => true)
+        end
+      when RDF::XSD.string
+         RDF::Literal.new(value, :datatype => datatype)
+      else
+        raise TypeError, "Expected datatype (#{datatype}) to be an XSD type"
+      end
+    rescue
+      raise TypeError, $!.message
+    end
+    
+    ##
+    # Returns `false`.
+    #
+    # @return [Boolean] `true` or `false`
+    # @see    #variable?
+    def variable?
+      false
+    end
+
+    ##
+    # Returns `true`.
+    #
+    # @return [Boolean] `true` or `false`
+    # @see    #variable?
+    def constant?
+      !(variable?)
+    end
+
+    ##
+    # Returns an optimized version of this expression.
+    #
+    # This is the default implementation, which simply returns `self`.
+    # Subclasses can override this method in order to implement something
+    # more useful.
+    #
+    # @return [Expression] `self`
+    def optimize
+      self
+    end
+
+    ##
+    # Evaluates this expression using the given variable `bindings`.
+    #
+    # This is the default implementation, which simply returns `self`.
+    # Subclasses can override this method in order to implement something
+    # more useful.
+    #
+    # @param  [RDF::Query::Solution, #[]] bindings
+    # @return [Expression] `self`
+    def evaluate(bindings = {})
+      self
+    end
+
+    ##
+    # Returns the SPARQL S-Expression (SSE) representation of this expression.
+    #
+    # This is the default implementation, which simply returns `self`.
+    # Subclasses can override this method in order to implement something
+    # more useful.
+    #
+    # @return [Array] `self`
+    # @see    http://openjena.org/wiki/SSE
+    def to_sse
+      self
+    end
+    
+    private
+    # @overload: May be called with node, message and an option hash
+    #   @param [String] node processing node
+    #   @param [String] message
+    #   @param [Hash{Symbol => Object}] options
+    #   @option options [Boolean] :debug output debug messages to $stderr
+    #   @option options [Integer] :depth (@productions.length)
+    #     Processing depth for indenting message output.
+    #   @yieldreturn [String] appended to message, to allow for lazy-evaulation of message
+    #
+    # @overload: May be called with node and an option hash
+    #   @param [String] node processing node
+    #   @param [Hash{Symbol => Object}] options
+    #   @option options [Boolean] :debug output debug messages to $stderr
+    #   @option options [Integer] :depth (@productions.length)
+    #     Processing depth for indenting message output.
+    #   @yieldreturn [String] appended to message, to allow for lazy-evaulation of message
+    #
+    # @overload: May be called with only options, in which case the block is used to return the output message
+    #   @param [String] node processing node
+    #   @param [Hash{Symbol => Object}] options
+    #   @option options [Boolean] :debug output debug messages to $stderr
+    #   @option options [Integer] :depth (@productions.length)
+    #     Processing depth for indenting message output.
+    #   @yieldreturn [String] appended to message, to allow for lazy-evaulation of message
+    def self.debug(*args)
+      options = args.last.is_a?(Hash) ? args.pop : {}
+      return unless options[:debug]
+      message = args.join(": ")
+      message = message + yield if block_given?
+      depth = options[:depth] || 0
+      $stderr.puts("#{' ' * depth}#{message}") if options[:debug]
+    end
+    
+    def debug(*args, &block)
+      Expression.debug(*args, &block)
+    end
+  end # Expression
+end; end # SPARQL::Algebra