fixes to docs etc

Author: doriantaylor

lib/rdf/changeset.rb

@@ -87,9 +87,9 @@ def initialize(insert: [], delete: [], &block)
     end
 
     ##
-    # Returns +false+ to indicate that this changeset is append-only.
+    # Returns `false` to indicate that this changeset is append-only.
     #
-    # Changesets do not support the +RDF::Enumerable+ protocol directly.
+    # Changesets do not support the `RDF::Enumerable` protocol directly.
     # To enumerate the RDF statements to be inserted or deleted, use the
     # {RDF::Changeset#inserts} and {RDF::Changeset#deletes} accessors.
     #
@@ -100,7 +100,7 @@ def readable?
     end
 
     ##
-    # Returns +false+ to indicate that this changeset _itself_ is not writable.
+    # Returns `false` as changesets are not {RDF::Writable}.
     #
     # @return [Boolean]
     # @see    RDF::Writable#writable?
@@ -109,7 +109,7 @@ def writable?
     end
 
     ##
-    # Returns +false+ to indicate that this changeset _itself_ is not mutable.
+    # Returns `false` as changesets are not {RDF::Mutable}.
     #
     # @return [Boolean]
     # @see    RDF::Mutable#mutable?
@@ -130,7 +130,7 @@ def apply(mutable, **options)
     end
 
     ##
-    # @return [Boolean] +true+ iff inserts and deletes are both empty
+    # @return [Boolean] `true` iff inserts and deletes are both empty
     def empty?
       deletes.empty? && inserts.empty?
     end
@@ -146,29 +146,29 @@ def inspect
 
     ##
     # Outputs a developer-friendly representation of this changeset to
-    # +$stderr+.
+    # `$stderr`.
     #
     # @return [void]
     def inspect!
       $stderr.puts(self.inspect)
     end
 
     ##
-    # Returns the sum of both the +inserts+ and +deletes+ counts.
+    # Returns the sum of both the `inserts` and `deletes` counts.
     #
     # @return [Integer]
     def count
       inserts.count + deletes.count
     end
 
-    # Append statements to +inserts+. Statements _should_ be constant
+    # Append statements to `inserts`. Statements _should_ be constant
     # as variable statements will at best be ignored or at worst raise
     # an error when applied.
     #
-    # @param statements [Enumerable, # RDF::Statement] Some statements
+    # @param statements [Enumerable, RDF::Statement] Some statements
     # @return [self]
     def insert(*statements)
-      process_statements(statements) do |stmts|
+      coerce_statements(statements) do |stmts|
         append_statements :inserts, stmts
       end
 
@@ -177,14 +177,14 @@ def insert(*statements)
     alias_method :insert!, :insert
     alias_method :<<, :insert
 
-    # Append statements to +deletes+. Statements _may_ contain
+    # Append statements to `deletes`. Statements _may_ contain
     # variables, although support will depend on the {RDF::Mutable}
     # target.
     #
     # @param statements [Enumerable, RDF::Statement] Some statements
     # @return [self]
     def delete(*statements)
-      process_statements(statements) do |stmts|
+      coerce_statements(statements) do |stmts|
         append_statements :deletes, stmts
       end
 
@@ -196,8 +196,8 @@ def delete(*statements)
     private
 
     ##
-    # Append statements to the appropriate target. This is a crappy
-    # little shim to go in between the other shim and the target.
+    # Append statements to the appropriate target. This is a little
+    # shim to go in between the other shim and the target.
     #
     # @param target [Symbol] the method to send
     # @param arg [Enumerable, RDF::Statement]

lib/rdf/mixin/mutable.rb

@@ -155,7 +155,7 @@ def update(*statements)
     def delete(*statements)
       raise TypeError.new("#{self} is immutable") if immutable?
 
-      process_statements(statements, query: true, constant: true) do |value|
+      coerce_statements(statements, query: true, constant: true) do |value|
         delete_statements(value)
       end
 

lib/rdf/mixin/writable.rb

@@ -59,7 +59,7 @@ def <<(data)
     #   @param  [Enumerable<RDF::Statement>] statements
     #   @return [self]
     def insert(*statements)
-      process_statements(statements) { |value| insert_statements value }
+      coerce_statements(statements) { |value| insert_statements value }
 
       return self
     end

lib/rdf/util/coercions.rb

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 module RDF
   module Util
     module Coercions
@@ -6,20 +7,29 @@ module Coercions
       # preprocessor that is used in e.g. {RDF::Writable#insert} and
       # {RDF::Mutable#delete}.
 
+      protected
+
       ##
-      # Coerce a set of arguments into {RDF::Statement} objects and then
-      # operate over them with a block.
+      # Coerce an array of arguments into {RDF::Statement}, or
+      # {RDF::Enumerable} and then yield to a block. Note that this
+      # code was amalgamated from that which was sandwiched around
+      # both {RDF::Writable#insert_statements} and
+      # {RDF::Mutable#delete_statements}. The parameters `query` and
+      # `constant` are therefore present to handle the conditions
+      # where the statements contain wildcards and what to do about
+      # them.
       # 
       # @example
-      #  process_statements(statements) { |value| do_something(value) }
+      #  coerce_statements(statements) { |value| do_something(value) }
       #
       # @param statements [#map] The arbitrary-ish input to be manipulated
-      # @param query [false, true] Whether to call +query+ before the block
+      # @param query [false, true] Whether to call `query` before the block
+      #  (as expected by {Mutable#delete_statements})
       # @param constant [false, true] Whether to test if the statements
-      #  are constant
+      #  are constant (as expected by {Mutable#delete_statements})
       # @yield [RDF::Statement, RDF::Enumerable] 
       # @return statements
-      def process_statements(statements, query: false, constant: false, &block)
+      def coerce_statements(statements, query: false, constant: false, &block)
         raise ArgumentError, 'expecting a block' unless block_given?
 
         statements = statements.map do |value|
@@ -32,7 +42,7 @@ def process_statements(statements, query: false, constant: false, &block)
             statement
           when query
             # XXX note that this only makes sense when the module is include()d
-            block.call(query(value))
+            block.call(self.query(value))
             nil
           else
             raise ArgumentError, "Not a valid statement: #{value.inspect}"
@@ -45,8 +55,6 @@ def process_statements(statements, query: false, constant: false, &block)
         statements
       end
 
-      # so you can include or call
-      extend self
     end
   end
 end