sparql 3.0.2 → 3.1.5

data/lib/rack/sparql.rb

@@ -18,7 +18,7 @@ module Rack
     # @param  [Hash{Symbol => Object}] options
     # @option options [Boolean]        :overwrite (false)
     # @return [void]
-    def self.register_mime_types!(options = {})
+    def self.register_mime_types!(**options)
       if defined?(Rack::Mime::MIME_TYPES)
         RDF::Format.each do |format|
           if !Rack::Mime::MIME_TYPES.has_key?(file_ext = ".#{format.to_sym}") || options[:overwrite]

data/lib/rack/sparql/conneg.rb

@@ -43,7 +43,7 @@ module Rack; module SPARQL
     #
     # @param  [Hash{String => String}] env
     # @return [Array(Integer, Hash, #each)]
-    # @see    http://www.rubydoc.info/github/rack/rack/Rack/Runtime#call-instance_method
+    # @see    https://www.rubydoc.info/github/rack/rack/Rack/Runtime#call-instance_method
     def call(env)
       env['ORDERED_CONTENT_TYPES'] = parse_accept_header(env['HTTP_ACCEPT']) if env.has_key?('HTTP_ACCEPT')
       response = app.call(env)
@@ -71,7 +71,7 @@ module Rack; module SPARQL
         serialize_options = {}
         serialize_options[:content_types] = env['ORDERED_CONTENT_TYPES'] if env['ORDERED_CONTENT_TYPES']
         serialize_options.merge!(@options)
-        results = ::SPARQL.serialize_results(body, serialize_options)
+        results = ::SPARQL.serialize_results(body, **serialize_options)
         raise RDF::WriterError, "can't serialize results" unless results
         headers = headers.merge(VARY).merge('Content-Type' => results.content_type) # FIXME: don't overwrite existing Vary headers
         [status, headers, [results]]
@@ -89,7 +89,7 @@ module Rack; module SPARQL
     #
     # @param  [String, #to_s] header
     # @return [Array<String>]
-    # @see    http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1
+    # @see    https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1
     def parse_accept_header(header)
       entries = header.to_s.split(',')
       entries.map { |e| accept_entry(e) }.sort_by(&:last).map(&:first)

data/lib/sinatra/sparql.rb

@@ -8,7 +8,7 @@ module Sinatra
   #
   # To override negotiation on Content-Type, set :format in `sparql_options` to a RDF Format class, or symbol identifying a format.
   #
-  # @see http://www.sinatrarb.com/extensions.html
+  # @see https://www.sinatrarb.com/extensions.html
   module SPARQL
     ##
     # Helper methods.
@@ -25,9 +25,9 @@ module Sinatra
       #   URI of the service endpoint, defaults to "/sparql" in the current realm.
       # @return [RDF::Graph]
       #
-      # @see http://www.w3.org/TR/sparql11-service-description
-      # @see http://www.w3.org/TR/void/
-      def service_description(options = {})
+      # @see https://www.w3.org/TR/sparql11-service-description
+      # @see https://www.w3.org/TR/void/
+      def service_description(**options)
         repository = options[:repository]
 
         g = RDF::Graph.new
@@ -103,7 +103,7 @@ module Sinatra
       app.helpers(Sinatra::SPARQL::Helpers)
       app.send(:include, ::SPARQL)
       app.send(:include, ::RDF)
-      app.send(:include, ::LinkedData)
+      app.send(:include, ::LinkedData) if defined?(::LinkedData)
     end
   end
 end

data/lib/sparql.rb

@@ -1,16 +1,18 @@
+require 'sxp'
 require 'sparql/extensions'
+require 'sparql/algebra/sxp_extensions'
 
 ##
 # A SPARQL for RDF.rb.
 #
-# @see http://www.w3.org/TR/sparql11-query
+# @see https://www.w3.org/TR/sparql11-query
 module SPARQL
   autoload :Algebra, 'sparql/algebra'
   autoload :Grammar, 'sparql/grammar'
   autoload :Results, 'sparql/results'
   autoload :VERSION, 'sparql/version'
 
-  # @see http://rubygems.org/gems/sparql-client
+  # @see https://rubygems-client
   autoload :Client,  'sparql/client'
 
   ##
@@ -28,8 +30,8 @@ module SPARQL
   #   a `queryable` object such as an RDF::Graph
   #   or RDF::Repository. 
   # @raise  [Parser::Error] on invalid input
-  def self.parse(query, options = {})
-    query = Grammar::Parser.new(query, options).parse(options[:update] ? :UpdateUnit : :QueryUnit)
+  def self.parse(query, **options)
+    query = Grammar::Parser.new(query, **options).parse(options[:update] ? :UpdateUnit : :QueryUnit)
   end
 
   ##
@@ -52,12 +54,13 @@ module SPARQL
   #   results = SPARQL.execute("SELECT * WHERE { ?s ?p ?o }", repository)
   #
   # @param  [IO, StringIO, String, #to_s]  query
+  # @param  [RDF::Queryable]  queryable
   # @param  [Hash{Symbol => Object}] options
-  # @option options  [RDF::Queryable]  :queryable
-  # @option options [RDF::URI, String, Array<RDF::URI, String>] :load_datasets
-  #   One or more URIs used to initialize a new instance of `queryable` in the default graph.
+  # @option options [Boolean] :optimize
+  #   Optimize query before execution.
   # @option options [RDF::URI, String, Array<RDF::URI, String>] :default_graph_uri
-  #   One or more URIs used to initialize a new instance of `queryable` in the default graph.
+  # @option options [RDF::URI, String, Array<RDF::URI, String>] :load_datasets
+  #   One or more URIs used to initialize a new instance of `queryable` in the default graph. One or more URIs used to initialize a new instance of `queryable` in the default graph.
   # @option options [RDF::URI, String, Array<RDF::URI, String>] :named_graph_uri
   #   One or more URIs used to initialize the `queryable` as a named graph.
   # @yield  [solution]
@@ -67,15 +70,13 @@ module SPARQL
   # @return [RDF::Graph, Boolean, RDF::Query::Solutions::Enumerator]
   #   Note, results may be used with {SPARQL.serialize_results} to obtain appropriate output encoding.
   # @raise  [SPARQL::MalformedQuery] on invalid input
-  def self.execute(query, queryable, options = {}, &block)
-    query = self.parse(query, options)
+  def self.execute(query, queryable, **options, &block)
+    query = self.parse(query, **options)
+    query = query.optimize(**options) if options[:optimize]
     queryable = queryable || RDF::Repository.new
-    
-    case options.fetch(:debug, nil)
-    when TrueClass
-      puts query.to_sxp
-    when Array
-      options[:debug] << query.to_sxp
+
+    if options[:logger]
+      options[:logger].debug("SPARQL.execute") {SXP::Generator.string query.to_sxp_bin}
     end
 
     if options.has_key?(:load_datasets)

data/lib/sparql/algebra.rb

@@ -1,4 +1,4 @@
-require 'rdf' # @see http://rubygems.org/gems/rdf
+require 'rdf' # @see https://rubygems.org/gems/rdf
 require 'rdf/xsd'
 
 module SPARQL
@@ -141,21 +141,21 @@ module SPARQL
   # ## Constructing operator expressions manually
   # 
   #     Operator(:isBlank).new(RDF::Node(:foobar)).to_sxp                        #=> "(isBlank _:foobar)"
-  #     Operator(:isIRI).new(RDF::URI('http://rubygems.org/gems/rdf/')).to_sxp       #=> "(isIRI <http://rubygems.org/gems/rdf/>)"
-  #     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))"
+  #     Operator(:isIRI).new(RDF::URI('https://rubygems.org/gems/rdf/')).to_sxp       #=> "(isIRI <https://rubygems.org/gems/rdf/>)"
+  #     Operator(:isLiteral).new(RDF::Literal(3.1415)).to_sxp                    #=> "(isLiteral 3.1415e0)"
+  #     Operator(:str).new(Operator(:datatype).new(RDF::Literal(3.1415))).to_sxp #=> "(str (datatype 3.1415e0))"
   # 
   # ## Constructing operator expressions using SSE forms
   # 
   #     SPARQL::Algebra::Expression[:isBlank, RDF::Node(:foobar)].to_sxp                          #=> "(isBlank _:foobar)"
-  #     SPARQL::Algebra::Expression[:isIRI, RDF::URI('http://rubygems.org/gems/rdf/')].to_sxp         #=> "(isIRI <http://rubygems.org/gems/rdf/>)"
-  #     SPARQL::Algebra::Expression[:isLiteral, RDF::Literal(3.1415)].to_sxp                      #=> "(isLiteral 3.1415)"
-  #     SPARQL::Algebra::Expression[:str, [:datatype, RDF::Literal(3.1415)]].to_sxp               #=> "(str (datatype 3.1415))"
+  #     SPARQL::Algebra::Expression[:isIRI, RDF::URI('https://rubygems.org/gems/rdf/')].to_sxp         #=> "(isIRI <https://rubygems.org/gems/rdf/>)"
+  #     SPARQL::Algebra::Expression[:isLiteral, RDF::Literal(3.1415)].to_sxp                      #=> "(isLiteral 3.1415e0)"
+  #     SPARQL::Algebra::Expression[:str, [:datatype, RDF::Literal(3.1415)]].to_sxp               #=> "(str (datatype 3.1415e0))"
   # 
   # ## Constructing operator expressions using SSE strings
   # 
   #     SPARQL::Algebra::Expression.parse('(isBlank _:foobar)')
-  #     SPARQL::Algebra::Expression.parse('(isIRI <http://rubygems.org/gems/rdf/>)')
+  #     SPARQL::Algebra::Expression.parse('(isIRI <https://rubygems.org/gems/rdf/>)')
   #     SPARQL::Algebra::Expression.parse('(isLiteral 3.1415)')
   #     SPARQL::Algebra::Expression.parse('(str (datatype 3.1415))')
   # 
@@ -165,11 +165,6 @@ module SPARQL
   #     Operator(:isIRI).evaluate(RDF::Vocab::DC.title)                                 #=> RDF::Literal::TRUE
   #     Operator(:isLiteral).evaluate(RDF::Literal(3.1415))                      #=> RDF::Literal::TRUE
   # 
-  # ## Optimizing expressions containing constant subexpressions
-  # 
-  #     SPARQL::Algebra::Expression.parse('(sameTerm ?var ?var)').optimize            #=> RDF::Literal::TRUE
-  #     SPARQL::Algebra::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:
@@ -372,8 +367,8 @@ module SPARQL
     # @param  [Hash{Symbol => Object}] options
     #   any additional options (see {Operator#initialize})
     # @return [SPARQL::Algebra::Operator]
-    def parse(sse, options = {})
-      Expression.parse(sse, options)
+    def parse(sse, **options)
+      Expression.parse(sse, **options)
     end
     module_function :parse
 
@@ -390,8 +385,8 @@ module SPARQL
     # @yieldparam  [SPARQL::Algebra::Expression] expression
     # @yieldreturn [void] ignored
     # @return [Expression]
-    def open(sse, options = {})
-      Expression.open(sse, options)
+    def open(sse, **options)
+      Expression.open(sse, **options)
     end
     module_function :open
 
@@ -405,8 +400,7 @@ module SPARQL
     def Expression(*sse)
       Expression.for(*sse)
     end
-    alias_method :Expr, :Expression
-    module_function :Expr, :Expression
+    module_function :Expression
 
     ##
     # @example
@@ -417,8 +411,7 @@ module SPARQL
     def Operator(name, arity = nil)
       Operator.for(name, arity)
     end
-    alias_method :Op, :Operator
-    module_function :Op, :Operator
+    module_function :Operator
 
     ##
     # @example
@@ -430,8 +423,7 @@ module SPARQL
     def Variable(name)
       Variable.new(name)
     end
-    alias_method :Var, :Variable
-    module_function :Var, :Variable
+    module_function :Variable
 
     Variable = RDF::Query::Variable
   end # Algebra

data/lib/sparql/algebra/aggregate.rb

@@ -6,8 +6,8 @@ module SPARQL; module Algebra
   # or more operands which are `Enumerable` lists of `RDF::Term`
   # and return a single `RDF::Term` or `TypeError`.
   #
-  # @see http://www.w3.org/TR/sparql11-query/#setFunctions
-  # @see http://www.w3.org/TR/sparql11-query/#aggregates
+  # @see https://www.w3.org/TR/sparql11-query/#setFunctions
+  # @see https://www.w3.org/TR/sparql11-query/#aggregates
   #
   # @abstract
   module Aggregate
@@ -24,12 +24,12 @@ module SPARQL; module Algebra
     # @return [RDF::Term]
     # @raise [TypeError]
     # @abstract
-    def aggregate(solutions = [], options = {})
+    def aggregate(solutions = [], **options)
       operands.shift if distinct = (operands.first == :distinct)
       args_enum = solutions.map do |solution|
         operands.map do |operand|
           begin
-            operand.evaluate(solution, options.merge(depth: options[:depth].to_i + 1))
+            operand.evaluate(solution, depth: options[:depth].to_i + 1, **options)
           rescue TypeError
             # Ignore errors
             nil

data/lib/sparql/algebra/evaluatable.rb

@@ -13,8 +13,8 @@ module SPARQL; module Algebra
     #   options passed from query
     # @return [RDF::Term]
     # @abstract
-    def evaluate(bindings, options = {})
-      args = operands.map { |operand| operand.evaluate(bindings, options.merge(depth: options[:depth].to_i + 1)) }
+    def evaluate(bindings, **options)
+      args = operands.map { |operand| operand.evaluate(bindings, depth: options[:depth].to_i + 1, **options) }
       options[:memoize] ? memoize(*args) : apply(*args)
     end
 

data/lib/sparql/algebra/expression.rb

@@ -19,14 +19,7 @@ module SPARQL; module Algebra
     # @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'
-      
+    def self.parse(sse, **options, &block)
       sse = sse.encode(Encoding::UTF_8)
       sxp = SXP::Reader::SPARQL.new(sse) do |reader|
         # Set base_uri if we have one
@@ -38,7 +31,7 @@ module SPARQL; module Algebra
       Operator.base_uri = options.delete(:base_uri) if options.has_key?(:base_uri)
       Operator.prefixes = sxp.prefixes || {}
 
-      expression = self.new(sxp_result, options)
+      expression = self.new(sxp_result, **options)
 
       yield(expression) if block_given?
       expression
@@ -57,10 +50,10 @@ module SPARQL; module Algebra
     # @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|
+    def self.open(filename, **options, &block)
+      RDF::Util::File.open_file(filename, **options) do |file|
         options[:base_uri] ||= filename
-        Expression.parse(file, options, &block)
+        Expression.parse(file, **options, &block)
       end
     end
 
@@ -87,7 +80,7 @@ module SPARQL; module Algebra
     #   any additional options (see {Operator#initialize})
     # @return [Expression]
     # @raise  [TypeError] if any of the operands is invalid
-    def self.new(sse, options = {})
+    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)
@@ -95,7 +88,7 @@ module SPARQL; module Algebra
         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))}
+          sse.map {|s| self.new(s, depth: options[:depth].to_i + 1, **options)}
         else
           debug(options) {"No operator found for #{sse.first}"}
           sse.map do |s|
@@ -110,7 +103,7 @@ module SPARQL; module Algebra
         debug(options) {"Operator=#{operator.inspect}, Operand=#{operand.inspect}"}
         case operand
           when Array
-            self.new(operand, options.merge(depth: options[:depth].to_i + 1))
+            self.new(operand, depth: options[:depth].to_i + 1, **options)
           when Operator, Variable, RDF::Term, RDF::Query, Symbol
             operand
           when TrueClass, FalseClass, Numeric, String, DateTime, Date, Time
@@ -120,9 +113,12 @@ module SPARQL; module Algebra
       end
 
       debug(options) {"#{operator.inspect}(#{operands.map(&:inspect).join(',')})"}
-      options.delete_if {|k, v| [:debug, :depth, :prefixes, :base_uri, :update, :validate].include?(k) }
-      operands << options unless options.empty?
-      operator.new(*operands)
+      options.delete_if {|k, v| [:debug, :logger, :depth, :prefixes, :base_uri, :update, :validate].include?(k) }
+      begin
+        operator.new(*operands, **options)
+      rescue ArgumentError => e
+        error(options) {"Operator=#{operator.inspect}: #{e}"}
+      end
     end
 
     ##
@@ -175,8 +171,8 @@ module SPARQL; module Algebra
     # @param [RDF::URI] function
     # @param [Array<RDF::Term>] args splat of args to function
     # @return [RDF::Term]
-    # @see http://www.w3.org/TR/sparql11-query/#extensionFunctions
-    # @see http://www.w3.org/TR/sparql11-query/#FunctionMapping
+    # @see https://www.w3.org/TR/sparql11-query/#extensionFunctions
+    # @see https://www.w3.org/TR/sparql11-query/#FunctionMapping
     def self.extension(function, *args)
       if function.to_s.start_with?(RDF::XSD.to_s)
         self.cast(function, args.first)
@@ -197,7 +193,7 @@ module SPARQL; module Algebra
     #   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 [RDF::Term]
-    # @see http://www.w3.org/TR/sparql11-query/#FunctionMapping
+    # @see https://www.w3.org/TR/sparql11-query/#FunctionMapping
     def self.cast(datatype, value)
       case datatype
       when RDF::XSD.dateTime
@@ -229,21 +225,45 @@ module SPARQL; module Algebra
         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)
+          RDF::Literal::Boolean.new(value.value, datatype: datatype, validate: true)
         end
       when RDF::XSD.decimal, RDF::XSD.integer
         case value
         when RDF::Literal::Boolean
           RDF::Literal.new(value.object ? 1 : 0, datatype: datatype)
-        when RDF::Literal::Integer, RDF::Literal::Decimal
-          RDF::Literal.new(value, datatype: datatype)
+        when RDF::Literal::Numeric
+          RDF::Literal.new(value.object, 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)
+        # Cast to string rules based on https://www.w3.org/TR/xpath-functions/#casting-to-string
+        case value
+        when RDF::Literal::Integer
+          RDF::Literal.new(value.canonicalize.to_s, datatype: datatype)
+        when RDF::Literal::Decimal
+          if value == value.ceil
+            RDF::Literal.new(value.ceil, datatype: datatype)
+          else
+            RDF::Literal.new(value.canonicalize.to_s, datatype: datatype)
+          end
+        when RDF::Literal::Float, RDF::Literal::Double
+          if value.abs >= 0.000001 && value.abs < 1000000
+            # If SV has an absolute value that is greater than or equal to 0.000001 (one millionth) and less than 1000000 (one million), then the value is converted to an xs:decimal and the resulting xs:decimal is converted to an xs:string according to the rules above, as though using an implementation of xs:decimal that imposes no limits on the totalDigits or fractionDigits facets.
+            cast(datatype, RDF::Literal::Decimal.new(value.object))
+          elsif value.object.zero?
+            # If SV has the value positive or negative zero, TV is "0" or "-0" respectively.
+            RDF::Literal.new(value.to_s.start_with?('-') ? '-0' : '0', datatype: datatype)
+          else
+            # If SV is positive or negative infinity, TV is the string "INF" or "-INF" respectively.
+            # In other cases, the result consists of a mantissa, which has the lexical form of an xs:decimal, followed by the letter "E", followed by an exponent which has the lexical form of an xs:integer. Leading zeroes and "+" signs are prohibited in the exponent. For the mantissa, there must be a decimal point, and there must be exactly one digit before the decimal point, which must be non-zero. The "+" sign is prohibited. There must be at least one digit after the decimal point. Apart from this mandatory digit, trailing zero digits are prohibited.
+            RDF::Literal.new(value.canonicalize.to_s, datatype: datatype)
+          end
+        else
+          RDF::Literal.new(value.canonicalize.to_s, datatype: datatype)
+        end
       else
         raise TypeError, "Expected datatype (#{datatype}) to be a recognized XPath function"
       end
@@ -280,12 +300,26 @@ module SPARQL; module Algebra
     ##
     # Returns an optimized version of this expression.
     #
-    # This is the default implementation, which simply returns `self`.
+    # This is the default implementation, which simply returns a copy of `self`.
     # Subclasses can override this method in order to implement something
     # more useful.
     #
-    # @return [Expression] `self`
-    def optimize
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options for optimization
+    # @return [Expression] a copy of `self`
+    # @see    RDF::Query#optimize
+    def optimize(**options)
+      self.deep_dup.optimize!(**options)
+    end
+
+    ##
+    # Optimizes this query.
+    #
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options for optimization
+    # @return [self]
+    # @see    RDF::Query#optimize!
+    def optimize!(**options)
       self
     end
 
@@ -301,7 +335,7 @@ module SPARQL; module Algebra
     # @param [Hash{Symbol => Object}] options ({})
     #   options passed from query
     # @return [Expression] `self`
-    def evaluate(bindings, options = {})
+    def evaluate(bindings, **options)
       self
     end
 
@@ -313,7 +347,7 @@ module SPARQL; module Algebra
     # more useful.
     #
     # @return [Array] `self`
-    # @see    http://openjena.org/wiki/SSE
+    # @see    https://openjena.org/wiki/SSE
     def to_sxp_bin
       self
     end
@@ -349,7 +383,7 @@ module SPARQL; module Algebra
     #   @param [String] node processing node
     #   @param [String] message
     #   @param [Hash{Symbol => Object}] options
-    #   @option options [Boolean] :debug output debug messages to $stderr
+    #   @option options [Logger] :logger for logging progress
     #   @option options [Integer] :depth (@productions.length)
     #     Processing depth for indenting message output.
     #   @yieldreturn [String] appended to message, to allow for lazy-evaulation of message
@@ -357,7 +391,7 @@ module SPARQL; module Algebra
     # @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 [Logger] :logger for logging progress
     #   @option options [Integer] :depth (@productions.length)
     #     Processing depth for indenting message output.
     #   @yieldreturn [String] appended to message, to allow for lazy-evaulation of message
@@ -365,22 +399,14 @@ module SPARQL; module Algebra
     # @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 [Logger] :logger for logging progress
     #   @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)
+    def self.debug(*args, &block)
       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
-      case options[:debug]
-      when Array
-        options[:debug] << "#{' ' * depth}#{message}"
-      else
-        $stderr.puts("#{' ' * depth}#{message}")
-      end
+      return unless options[:logger]
+      options[:logger].debug(*args, **options, &block)
     end
     
     def debug(*args, &block)