caruby-core 1.4.2 → 1.4.3

data/lib/caruby/util/cache.rb

@@ -8,13 +8,16 @@ module CaRuby
     attr_reader :sticky
     
     # Returns a new Cache whose value key is determined by calling the given
-    # extractor block on the cached value.
+    # extractor block on the cached value. The key must uniquely identify the
+    # cached value within the scope of the value class.
     #
     # If the value is not cached and there is a factory Proc, then the result of
     # calling the factory on the missing value is cached with the value key.
     #
     # @param [Proc] optional factory Proc called with a missing value as argument
     #   to create a cached object
+    # @yield [value] returns the value key
+    # @yieldparam value the value to cach
     def initialize(factory=nil, &extractor)
       @factory = factory
       # Make the class => { key => value } hash.

data/lib/caruby/util/class.rb

@@ -3,7 +3,7 @@ require 'enumerator'
 class Class
   # Returns an Enumerable on this class and its ancestors.
   def class_hierarchy
-    @hierarchy ||= Enumerable::Enumerator.new(self, :each_class_in_hierarchy)
+    @class__hierarchy ||= Enumerable::Enumerator.new(self, :each_class_in_hierarchy)
   end
 
   # Returns this class's superclass, thereby enabling class ranges, e.g.
@@ -58,6 +58,53 @@ class Class
     end
   end
 
+  # Defines an instance variable accessor attribute whose reader calls the block given
+  # to this method to create a new instance variable on demand, if necessary.
+  #
+  # For example, the declaration
+  #   class AlertHandler
+  #     attr_create_on_demand_accessor(:pings) { Array.new }
+  #   end
+  # is equivalent to:
+  #   class AlertHandler
+  #     attr_writer :pings
+  #     def pings
+  #       instance_variable_defined?(@pings) ? @pings : Array.new
+  #     end
+  #   end
+  #
+  # This method is useful either as a short-hand for the create-on-demand idiom
+  # as shown in the example above, or when it is desirable to dynamically add a
+  # mix-in attribute to a class at runtime whose name is not known when the class
+  # is defined.
+  #
+  # @example
+  #   class AlertHandler
+  #     def self.handle(alert)
+  #       attr_create_on_demand_accessor(alert) { AlertQueue.new }
+  #     end
+  #   end
+  #   ...
+  #   AlertHandler.handle(:pings)
+  #   AlertHandler.new.pings #=> empty AlertQueue
+  #
+  # @param [Symbol] symbol the attribute to define
+  # @yield [obj] factory to create the new attribute value for the given instance
+  # @yieldparam obj the class instance for which the attribute will be set
+  def attr_create_on_demand_accessor(symbol)
+    attr_writer(symbol)
+    wtr = "#{symbol}=".to_sym
+    iv = "@#{symbol}".to_sym
+    # the attribute reader creates a new proxy on demand
+    define_method(symbol) do
+      instance_variable_defined?(iv) ? instance_variable_get(iv) : send(wtr, yield(self))
+    end
+  end
+
+  # Enumerates each class in the hierarchy.
+  #
+  # @yield [klass] the enumeration block
+  # @yieldparam [Class] klass the class in the hierarchy
   def each_class_in_hierarchy
     current = self
     until current.nil?

data/lib/caruby/util/collection.rb

@@ -151,6 +151,8 @@ module Enumerable
   # Note, however, that unlike select, filter does not return an Array.
   # The default filter block returns the passed item.
   #
+  # @yield [item] filter the selection filter
+  # @yieldparam item the collection member to filter
   # @return [Enumerable] the filtered result
   # @example
   #   [1, nil, 3].filter.to_a #=> [1, 3]
@@ -174,7 +176,7 @@ module Enumerable
   # Returns an Enumerable which iterates over items in this Enumerable and the other Enumerable in sequence, e.g.:
   #   [1, 2, 3] + [3, 4] #=> [1, 2, 3, 3, 4]
   #
-  # Unlike Array#+, {#union} reflects changes to the underlying enumerators.
+  # Unlike the Array plus (+) operator, {#union} reflects changes to the underlying enumerators.
   #
   # @example
   #   a = [1, 2]
@@ -183,7 +185,8 @@ module Enumerable
   #   ab #=> [1, 2, 4, 5]
   #   a << 3
   #   ab #=> [1, 2, 3, 4, 5]
-  # @return [Enumerable] self followed by other
+  # @param [Enumerable] other the Enumerable to compose with this Enumerable
+  # @return [Enumerable] an enumerator over self followed by other
   def union(other)
     MultiEnumerator.new(self, other)
   end
@@ -207,16 +210,31 @@ module Enumerable
   # Returns a new Enumerable that iterates over the base Enumerable applying the transformer block to each item, e.g.:
   #   [1, 2, 3].transform { |n| n * 2 }.to_a #=> [2, 4, 6]
   #
-  # Unlike #collect, {#wrap} reflects changes to the base Enumerable, e.g.:
+  # Unlike Array.map, {#wrap} reflects changes to the base Enumerable, e.g.:
   #   a = [2, 4, 6]
 ``#   transformed = a.wrap { |n| n * 2 }
   #   a << 4
   #   transformed.to_a #=> [2, 4, 6, 8]
   #
   # In addition, transform has a small, fixed storage requirement, making it preferable to select for large collections.
-  # Note, however, that unlike collect, transform does not return an Array.
-  def wrap(&transformer) # :yields: item
-    Transformer.new(self, &transformer)
+  # Note, however, that unlike map, transform does not return an Array.
+  #
+  # @yield [item] the transformer on the enumerated items
+  # @yieldparam item an enumerated item
+  # @return [Enumerable] an enumeration on the transformed values
+  def wrap(&mapper)
+    Transformer.new(self, &mapper)
+  end
+  
+  def join(other)
+    Joiner.new(self, other)
+  end
+  
+  # @yield [item] the transformer on the enumerated items
+  # @yieldparam item an enumerated item
+  # @return [Enumerable] the mapped values excluding null values
+  def compact_map(&mapper)
+    wrap(&mapper).compact
   end
 
   private
@@ -229,30 +247,45 @@ module Enumerable
       @filter = filter
     end
 
-    # Calls block on each item which passes this Filter's filter test.
-    def each(&block)
+    # Calls the given block on each item which passes this Filter's filter test.
+    #
+    # @yield [item] the block called on each item
+    # @yieldparam item the enumerated item
+    def each
       @base.each { |item| yield(item) if @filter ? @filter.call(item) : item }
     end
 
     # Optimized for a Set base.
+    #
+    # @param [item] the item to check
+    # @return [Boolean] whether the item is a member of this Enumerable
     def include?(item)
       return false if Set === @base and not @base.include?(item)
       super
     end
 
-    # Adds value to the base Enumerable, if the base supports it.
-    def <<(value)
+    # Adds an item to the base Enumerable, if thif Filter's base supports it.
+    #
+    # @param item the item to add
+    # @return [Filter] self
+    def <<(item)
       @base << value
+      self
     end
 
-    # @return a new Array consisting of this Filter's filtered content merged with the other Enumerable
+    # @param [Enumerable] other the Enumerable to merge
+    # @return [Array] this Filter's filtered content merged with the other Enumerable
     def merge(other)
-      to_a.merge(other)
+      to_a.merge!(other)
     end
 
     # Merges the other Enumerable into the base Enumerable, if the base supports it.
+    #
+    # @param other (see #merge)
+    # @return [Filter, nil] this Filter's filtered content merged with the other Enumerable
     def merge!(other)
       @base.merge!(other)
+      self
     end
   end
 
@@ -272,7 +305,7 @@ module Enumerable
       self
     end
 
-    # Calls block on each item after this Transformer's transformer block is applied.
+    # Calls the block on each item after this Transformer's transformer block is applied.
     def each
       @base.each { |item| yield(item.nil? ? nil : @xfm.call(item)) }
     end
@@ -400,7 +433,7 @@ end
 module Hashable
   include Enumerable
 
-  # @see Hash#each
+  # @see Hash#each_pair
   def each_pair(&block)
     each(&block)
   end
@@ -992,15 +1025,18 @@ class Array
     base__flatten
   end
 
-  # Adds the other Enumerable to this array.
+  # Concatenates the other Enumerable to this array.
   #
-  # Raises ArgumentError if other does not respond to the +to_a+ method.
+  # @param [#to_a] other the other Enumerable
+  # @raise [ArgumentError] if other does not respond to the +to_a+ method
   def add_all(other)
     return concat(other) if Array === other
     begin
-      return add_all(other.to_a)
+      add_all(other.to_a)
+    rescue NoMethodError
+      raise
     rescue
-      raise ArgumentError.new("Can't convert #{other.class.name} to array") unless other.respond_to?(:to_a)
+      raise ArgumentError.new("Can't convert #{other.class.name} to array")
     end
   end
 

data/lib/caruby/util/inflector.rb

@@ -17,4 +17,11 @@ class String
   def capitalize_first
     sub(/(?:^)(.)/) { $1.upcase }
   end
+  
+  # @return this String with the first letter decapitalized and other letters preserved.
+  # @example
+  #   "RosesAreRed".decapitalize #=> "rosesAreRed"
+  def decapitalize
+    sub(/(?:^)(.)/) { $1.downcase }
+  end
 end

data/lib/caruby/util/options.rb

@@ -42,42 +42,46 @@ class Options
     end
   end
 
-  # Merges the others options with options and returns the new merged option hash.
+  # Returns the given argument list as a hash, determined as follows:
+  # * If the sole argument member is a hash, then that hash is the options.
+  # * An argument list of option symbols followed by zero, one or more non-option parameters is composed as the option hash.
+  # * An empty argument list is a new empty option hash.
   #
   # @example
-  #   Options.merge(nil, :create) #=> {:create => :true}
-  #   Options.merge(:create, :optional => :a, :required => :b) #=> {:create => :true, :optional => :a, :required => :b}
-  #   Options.merge({:required => [:b]}, :required => [:c]) #=> {:required => [:b, :c]}
-  def self.merge(options, others)
-    options = options.dup if Hash === options
-    self.merge!(options, others)
-  end
-
-  # Merges the others options into the given options and returns the created or modified option hash.
-  # This method differs from {Options.merge} by modifying an existing options hash.
-  def self.merge!(options, others)
-    to_hash(options).merge!(to_hash(others)) { |key, oldval, newval| oldval.respond_to?(:merge) ? oldval.merge(newval) : newval }
-  end
-
-  # Returns the options as a hash. If options is already a hash, then this method returns hash.
-  # * If options is a Symbol _s_, then this method returns +{+_s_+=>true}+.
-  # * An Array of Symbols is enumerated as individual Symbol options.
-  # * If options is nil, then this method returns a new empty hash.
-  def self.to_hash(options)
-    return Hash.new if options.nil?
-    case options
-    when Hash then
-      options
-    when Array then
-      options.to_hash { |item| Symbol === item or raise ArgumentError.new("Option is not supported; expected Symbol, found: #{options.class}") }
-    when Symbol then
-      {options => true}
-    else
-      raise ArgumentError.new("Options argument type is not supported; expected Hash or Symbol, found: #{options.class}")
+  #   Options.to_hash() #=> {}
+  #   Options.to_hash(nil) #=> {}
+  #   Options.to_hash(:a => 1) #=> {:a => 1}
+  #   Options.to_hash(:a) #=> {:a => true}
+  #   Options.to_hash(:a, 1, :b, 2) #=> {:a => 1, :b => 2}
+  #   Options.to_hash(:a, 1, :b, :c, 2, 3) #=> {:a => 1, :b => true, :c => [2, 3]}
+  # @param [Array] args the option list
+  # @return [Hash] the option hash
+  def self.to_hash(*args)
+    unless Enumerable === args then
+      raise ArgumentError.new("Expected Enumerable, found #{args.class.qp}")
+    end
+    oargs = {}
+    opt = args.first
+    return oargs if opt.nil?
+    return opt if oargs.empty? and Hash === opt
+    unless Symbol === opt then
+      raise ArgumentError.new("Expected Symbol as first argument, found #{args.first.class.qp}")
+    end
+    args.inject(nil) do |list, item|
+      Symbol === item ? oargs[item] = Array.new : list << item
     end
+    # convert the value list to true, a single value or leave as an array
+    oargs.transform do |list|
+      case list.size
+        when 0 then true
+        when 1 then list.first
+        else list
+      end
+    end.to_hash
   end
 
-  # Raises a ValidationError if the given options are not in the given allowable choices.
+  # @param [Hash, Symbol, nil] opts the options to validate
+  # @raise [ValidationError] if the given options are not in the given allowable choices
   def self.validate(options, choices)
     to_hash(options).each_key do |opt|
       raise ValidationError.new("Option is not supported: #{opt}") unless choices.include?(opt)

data/lib/caruby/util/partial_order.rb

@@ -9,7 +9,7 @@
 #   module Queued
 #     attr_reader :queue
 #     def <=>(other)
-#       raise TypeError.new("Comparison argument is not another Queued item") unless Queued == other
+#       raise TypeError.new("Comparison argument is not another Queued item") unless Queued === other
 #       queue.index(self) <=> queue.index(other) if queue.equal?(other.queue)
 #     end
 #   end

data/lib/caruby/util/properties.rb

@@ -97,8 +97,8 @@ module CaRuby
     # or nil if key is neither a String nor a Symbol.
     def alternate_key(key)
       case key
-      when String then key.to_sym
-      when Symbol then key.to_s
+        when String then key.to_sym
+        when Symbol then key.to_s
       end
     end
 

data/lib/caruby/util/stopwatch.rb

@@ -4,36 +4,42 @@ require 'benchmark'
 class Stopwatch
   # Time accumulates elapsed real time and total CPU time.
   class Time
-    # The Benchmark::Tms wrapped by this Time.
+    # @return [Benchmark::Tms] the Tms wrapped by this Time
     attr_reader :tms
 
+    # @param [Benchmark::Tms, nil] the starting time (default is now)
     def initialize(tms=nil)
       @tms = tms || Benchmark::Tms.new
     end
 
-    # Returns the cumulative elapsed real clock time.
+    # @return [Numeric] the cumulative elapsed real clock time
     def elapsed
       @tms.real
     end
 
-    # Returns the cumulative CPU total time.
+    #  @return [Numeric] the cumulative CPU total time
     def cpu
       @tms.total
     end
 
-    # Adds the time to execute the given block to this time. Returns the split execution Time.
+    # Adds the time to execute the given block to this time.
+    #
+    #  @return [Numeric] the split execution Time
     def split(&block)
       stms = Benchmark.measure(&block)
       @tms += stms
       Time.new(stms)
     end
 
+    # Sets this benchmark timer to zero.
     def reset
       @tms = Benchmark::Tms.new
     end
   end
   
-  # Executes the given block. Returns the execution Time.
+  # Executes the given block
+  #
+  # @return [Numeric] the execution Time
   def self.measure(&block)
     new.run(&block)
   end
@@ -44,17 +50,19 @@ class Stopwatch
   end
 
   # Executes the given block. Accumulates the execution time in this Stopwatch. 
-  # Returns the execution Time.
+  #
+  #  @return [Numeric] the execution run Time
   def run(&block)
     @time.split(&block)
   end
 
-  # Returns the cumulative elapsed real clock time spent in {#run} executions.
+  # @return [Numeric] the cumulative elapsed real clock time spent in {#run} executions
   def elapsed
     @time.elapsed
   end
 
-  # Returns the cumulative CPU total time spent in {#run} executions for the current process and its children.
+  # @return [Numeric] the cumulative CPU total time spent in {#run} executions for the
+  #  current process and its children
   def cpu
     @time.cpu
   end

data/lib/caruby/util/transitive_closure.rb

@@ -26,7 +26,7 @@ class Object
   def transitive_closure(method=nil)
     raise ArgumentError.new("Missing both a method argument and a block") if method.nil? and not block_given?
     return transitive_closure() { |node| node.send(method) } if method
-    Visitor.new(:depth_first) { |node| yield node }.to_enum(self).to_a.reverse
+    CaRuby::Visitor.new(:depth_first) { |node| yield node }.to_enum(self).to_a.reverse
   end
 end
 

data/lib/caruby/util/visitor.rb

@@ -5,346 +5,360 @@ require 'caruby/util/options'
 require 'enumerator'
 require 'generator'
 
-# Error raised on a visit failure.
-class VisitError < RuntimeError; end
-
-# Visitor traverses items and applies an operation, e.g.:
-#   class Node
-#     attr_accessor :children, :value
-#     def initialize(value, parent=nil)
-#       @value = value
-#       @children = []
-#       @parent = parent
-#       @parent.children << self if @parent
-#     end
-#   end
-#   parent = Node.new(1)
-#   child = Node.new(2, parent)
-#   multiplier = 2
-#   Visitor.new { |node| node.children }.visit(parent) { |node| node.value *= multiplier } #=> 2
-#   parent.value #=> 2
-#   child.value #=> 4
-#
-# The visit result is the result of evaluating the operation block on the initial visited node.
-# Visiting a collection returns an array of the result of visiting each member of the collection,
-# e.g. augmenting the preceding example:
-#   parent2 = Node.new(3)
-#   child2 = Node.new(4, parent2)
-#   Visitor.new { |node| node.children }.visit([parent, parent2]) { |node| node.value *= multiplier } #=> [2, 6]
-# Each visit captures the visit result in the +visited+ hash, e.g.:
-#   parent = Node.new(1)
-#   child = Node.new(2, parent)
-#   visitor = Visitor.new { |node| node.children }
-#   visitor.visit([parent]) { |node| node.value += 1 }
-#   parent.value #=> 2
-#   visitor.visited[parent] #=> 2
-#   child.value #=> 3
-#   visitor.visited[child] #=> 3
-#
-# A +return+ from the operation block terminates the visit and exits from the defining scope with the block return value,
-# e.g. given the preceding example:
-#   def increment(parent, limit)
-#     Visitor.new { |node| node.children }.visit(parent) { |node| node.value < limit ? node.value += 1 : return }
-#   end
-#   increment(parent, 2) #=> nil
-#   parent.value #=> 2
-#   child.value #=> 2
-#
-# The to_enum method allows navigator iteration, e.g.:
-#   Visitor.new { |node| node.children }.to_enum(parent).detect { |node| node.value == 2 }
-class Visitor
-
-  attr_reader :options, :visited, :lineage, :cycles
-
-  # Creates a new Visitor which traverses the child objects returned by the navigator block.
-  # The navigator block takes a parent argument and returns the children to visit. If the block
-  # return value is not nil and not a collection, then the returned object is visited. A nil or
-  # empty child is not visited.
-  #
-  # options is a symbol => value hash. A Symbol argument _symbol_ is the same as +{+_symbol_+=>true}+.
-  # Supported options include the follwing:
-  #
-  # The value of :depth_first can be +true+, +false+ or a Proc. If the value is a Proc, then
-  # value determines whether a child is visited depth-first. See the {#visit} method for more information.
-  #
-  # If the the :visited option is set, then the visited nodes are recorded in the :visited option hash.
-  # In that case, the {#visit} call does not clear the visited hash.
-  #
-  # If the :operator option is set, then the visit operator block is called when a node is visited.
-  # The operator block argument is the visited node.
-  #
-  # @param [Symbol, {Symbol => Object}] options the visit options. A symbol argument is the same
-  #   as symbol => true
-  # @option options [String] :depth_first depth-first traversal
-  # @option options [Hash] :visited the hash to use when recording visited node => value associations
-  # @option options [Proc] :operator the visit operator block
-  # @option options [String] :prune_cycle flag indicating whether to exclude cycles to the root in a visit
-  # @yield [parent] the parent being visited
-  def initialize(options=nil, &navigator)
-    @navigator = navigator
-    @options = Options.to_hash(options)
-    @depth_first_flag = @options[:depth_first]
-    @visited = @options[:visited] || {}
-    @prune_cycle_flag = @options[:prune_cycle]
-    @lineage = []
-    @cycles = []
-    @exclude = Set.new
-  end
-
-  # Navigates to node and the children returned by this Visitor's navigator block.
-  # Applies the optional operator block to each child node if the block is given to this method.
-  # Returns the result of the operator block if given, or the node itself otherwise.
-  #
-  # The nodes to visit from a parent node are determined in the following sequence:
-  # * Return if the parent node has already been visited.
-  # * If depth_first, then call the navigator block defined in the initializer on
-  #   the parent node and visit each child node.
-  # * Visit the parent node.
-  # * If not depth-first, then call the navigator block defined in the initializer
-  #   on the parent node and visit each child node.
-  # The :depth option value constrains child traversal to that number of levels.
-  #
-  # This method first clears the _visited_ hash, unless the :visited option was set in the initializer.
+module CaRuby
+  # Error raised on a visit failure.
+  class VisitError < RuntimeError; end
+  
+  # Visitor traverses items and applies an operation, e.g.:
+  #   class Node
+  #     attr_accessor :children, :value
+  #     def initialize(value, parent=nil)
+  #       @value = value
+  #       @children = []
+  #       @parent = parent
+  #       @parent.children << self if @parent
+  #     end
+  #   end
+  #   parent = Node.new(1)
+  #   child = Node.new(2, parent)
+  #   multiplier = 2
+  #   CaRuby::Visitor.new { |node| node.children }.visit(parent) { |node| node.value *= multiplier } #=> 2
+  #   parent.value #=> 2
+  #   child.value #=> 4
   #
-  # @param node the root object to visit
-  # @yield [visited] an operator applied to each visited object
-  # @yieldparam visited the object currently being visited
-  # @return the result of the yield block on node, or node itself if no block is given
-  def visit(node, &operator)
-    visit_root(node, &operator)
-  end
-
-  # @param node the node to check
-  # @return whether the node was visited
-  def visited?(node)
-    @visited.has_key?(node)
-  end
-
-  # @return the top node visited
-  def root
-    @lineage.first
-  end
-
-  # @return the current node being visited
-  def current
-    @lineage.last
-  end
-
-  # @return the node most recently passed as an argument to this visitor's navigator block, or nil if
-  #   visiting the first node
-  def parent
-    @lineage[-2]
-  end
-
-  # @return [Enumerable] iterator over each visited node
-  def to_enum(node)
-    # could use Generator, but that results in dire behavior on any error by crashing with an elided Java lineage trace
-    VisitorEnumerator.new(self, node)
-  end
-
-  # Returns a new visitor that traverses a collection of parent nodes in lock-step fashion using this visitor.
-  # The synced {#visit} method applies the visit operator block to an array of child nodes taken
-  # from each parent node, e.g. given the class documentation example:
-  #   parent1 = Node.new(1)
-  #   child11 = Node.new(2, parent1)
-  #   child12 = Node.new(3, parent1)
-  #   parent2 = Node.new(1)
-  #   child21 = Node.new(3, parent2)
-  #   Visitor.new { |node| node.children }.sync.enum.to_a #=> [
-  #    [parent1, parent2],
-  #    [child11, child21],
-  #    [child12, nil]
-  #   ]
+  # The visit result is the result of evaluating the operation block on the initial visited node.
+  # Visiting a collection returns an array of the result of visiting each member of the collection,
+  # e.g. augmenting the preceding example:
+  #   parent2 = Node.new(3)
+  #   child2 = Node.new(4, parent2)
+  #   CaRuby::Visitor.new { |node| node.children }.visit([parent, parent2]) { |node| node.value *= multiplier } #=> [2, 6]
+  # Each visit captures the visit result in the +visited+ hash, e.g.:
+  #   parent = Node.new(1)
+  #   child = Node.new(2, parent)
+  #   visitor = CaRuby::Visitor.new { |node| node.children }
+  #   visitor.visit([parent]) { |node| node.value += 1 }
+  #   parent.value #=> 2
+  #   visitor.visited[parent] #=> 2
+  #   child.value #=> 3
+  #   visitor.visited[child] #=> 3
   #
-  # By default, the children are grouped in enumeration order. If a block is given to this
-  # method, then the block is called to match child nodes, e.g. using the above example:
-  #   visitor = Visitor.new { |node| node.children }
-  #   synced = visitor.sync { |node, others| others.detect { |other| node.value == other.value }
-  #   synced.enum.to_a #=> [
-  #     [parent1, parent2],
-  #     [child11, nil],
-  #     [child12, child21]
-  #   ]
+  # A +return+ from the operation block terminates the visit and exits from the defining scope with the block return value,
+  # e.g. given the preceding example:
+  #   def increment(parent, limit)
+  #     CaRuby::Visitor.new { |node| node.children }.visit(parent) { |node| node.value < limit ? node.value += 1 : return }
+  #   end
+  #   increment(parent, 2) #=> nil
+  #   parent.value #=> 2
+  #   child.value #=> 2
   #
-  # @yield [node, others] matches node in others (optional)
-  # @yieldparam [Resource] node the visited node to match
-  # @yieldparam [<Resource>] the candidates for matching the node
-  def sync(&matcher) # :yields: node, others
-    SyncVisitor.new(self, &matcher)
-  end
-
-  # Returns a new Visitor which determines which nodes to visit by applying the given block
-  # to this visitor, e.g.:
-  #   Visitor.new { |node| node.children }.filter { |parent, children| children.first if parent.age >= 18 }
-  # navigates to the first child of parents 18 or older.
-  #
-  # The filter block arguments consist of a parent node and an array of children nodes for the parent.
-  # The  block can return nil, a single node to visit or a collection of nodes to visit.
-  #
-  # @return [Visitor] the filter visitor
-  # @yield [parent, children] the filter to select which of the children to visit next
-  # @yieldparam parent the currently visited node
-  # @yieldparam children the nodes slated by this Visitor to visit next
-  # @raise [ArgumentError] if a block is not given to this method
-  def filter
-    raise ArgumentError.new("Filter block not given to visitor filter method") unless block_given?
-    Visitor.new(@options) { |node| yield(node, node_children(node)) }
-  end
-
-  protected
-
-  # Resets this visitor's state in preparation for a new visit.
-  def clear
-    # clear the lineage
-    @lineage.clear
-    # if the visited hash is not shared, then clear it
-    @visited.clear unless @options.has_key?(:visited)
-    # clear the cycles
-    @cycles.clear
-  end
-
-  # Sets the visited hash.
-  def visited=(hash)
-    @visited = hash ||= {}
-  end
-
-  # Visits the given node using the block given to this method.
-  # The default block returns node.
-  def visit_node(node)
-    @visited[node] = block_given? ? yield(node) : node
-  end
-
-  # Returns the children to visit for the given node.
-  def node_children(node)
-    children = @navigator.call(node)
-    return Array::EMPTY_ARRAY if children.nil?
-    Enumerable === children ? children.to_a.compact : [children]
-  end
-
-  private
-
-  # Visits the root node and all descendants.
-  def visit_root(node, &operator)
-    clear
-    prune_cycle_nodes(node) if @prune_cycle_flag
-    # visit the root node
-    visit_recursive(node, &operator)
-  end
-
-  # Excludes the internal nodes in cycles starting and ending at the given root.
-  def prune_cycle_nodes(root)
-    @exclude.clear
-    # visit the root, which will detect cycles, and remove the visited nodes afterwords
-    @prune_cycle_flag = false
-    to_enum(root).collect.each { |node| @visited.delete(node) }
-    @prune_cycle_flag = true
-    # add each cyclic internal node to the exclude list
-    @cycles.each { |cycle| cycle[1...-1].each { |node| @exclude << node } if cycle.first == root }
-  end
-
-  def visit_recursive(node, &operator)
-    return if node.nil? or @exclude.include?(node)
-    # return the visited value if the node has already been visited
-    if @visited.has_key?(node) then
-      #capture a cycle
-      index = @lineage.index(node)
-      if index then
-        cycle = @lineage[index..-1] << node
-        @cycles << cycle
-      end
-      return @visited[node]
+  # The to_enum method allows navigator iteration, e.g.:
+  #   CaRuby::Visitor.new { |node| node.children }.to_enum(parent).detect { |node| node.value == 2 }
+  class Visitor
+  
+    attr_reader :options, :visited, :lineage, :cycles
+  
+    # Creates a new Visitor which traverses the child objects returned by the navigator block.
+    # The navigator block takes a parent argument and returns the children to visit. If the block
+    # return value is not nil and not a collection, then the returned object is visited. A nil or
+    # empty child is not visited.
+    #
+    # options is a symbol => value hash. A Symbol argument _symbol_ is the same as +{+_symbol_+=>true}+.
+    # Supported options include the follwing:
+    #
+    # The value of :depth_first can be +true+, +false+ or a Proc. If the value is a Proc, then
+    # value determines whether a child is visited depth-first. See the {#visit} method for more information.
+    #
+    # If the the :visited option is set, then the visited nodes are recorded in the :visited option hash.
+    # In that case, the {#visit} call does not clear the visited hash.
+    #
+    # If the :operator option is set, then the visit operator block is called when a node is visited.
+    # The operator block argument is the visited node.
+    #
+    # @param [Symbol, {Symbol => Object}] opts the visit options. A symbol argument is the same
+    #   as symbol => true
+    # @option opts [String] :depth_first depth-first traversal
+    # @option opts [Hash] :visited the hash to use when recording visited node => value associations
+    # @option opts [Proc] :operator the visit operator block
+    # @option opts [String] :prune_cycle flag indicating whether to exclude cycles to the root in a visit
+    # @yield [parent] the parent being visited
+    def initialize(opts=nil, &navigator)
+      @navigator = navigator
+      @options = Options.to_hash(opts)
+      @depth_first_flag = @options[:depth_first]
+      @visited = @options[:visited] || {}
+      @prune_cycle_flag = @options[:prune_cycle]
+      @lineage = []
+      @cycles = []
+      @exclude = Set.new
     end
-    # return nil if the node has not been visited but has been navigated in a depth-first visit
-    return if @lineage.include?(node)
-    visit_node_and_children(node, &operator)
-  end
-
-  def visit_node_and_children(node, &operator)
-    # set the current node
-    @lineage.push(node)
-    # if depth-first, then visit the children before the current node
-    visit_children(node, &operator) if @depth_first_flag
-    # visit the current node
-    result = visit_node(node, &operator)
-    # if not depth-first, then visit the children after the current node
-    visit_children(node, &operator) unless @depth_first_flag
-    @lineage.pop
-    # return the visit result
-    result
-  end
-
-  def visit_children(node, &operator)
-    children = node_children(node)
-    children.each { |child| visit_recursive(child, &operator) }
-  end
-
-  class VisitorEnumerator
-    include Enumerable
-
-    def initialize(visitor, node)
-      @visitor = visitor
-      @root = node
+  
+    # Navigates to node and the children returned by this Visitor's navigator block.
+    # Applies the optional operator block to each child node if the block is given to this method.
+    # Returns the result of the operator block if given, or the node itself otherwise.
+    #
+    # The nodes to visit from a parent node are determined in the following sequence:
+    # * Return if the parent node has already been visited.
+    # * If depth_first, then call the navigator block defined in the initializer on
+    #   the parent node and visit each child node.
+    # * Visit the parent node.
+    # * If not depth-first, then call the navigator block defined in the initializer
+    #   on the parent node and visit each child node.
+    # The :depth option value constrains child traversal to that number of levels.
+    #
+    # This method first clears the _visited_ hash, unless the :visited option was set in the initializer.
+    #
+    # @param node the root object to visit
+    # @yield [visited] an operator applied to each visited object
+    # @yieldparam visited the object currently being visited
+    # @return the result of the yield block on node, or node itself if no block is given
+    def visit(node, &operator)
+      visit_root(node, &operator)
     end
-
-    def each
-      @visitor.visit(@root) { |node| yield(node) }
+  
+    # @param node the node to check
+    # @return whether the node was visited
+    def visited?(node)
+      @visited.has_key?(node)
     end
-  end
-
-  class SyncVisitor < Visitor
-    # @param [Visitor] visitor the Visitor which will visit synchronized input
-    # @yield (see Visitor#sync)
-    def initialize(visitor, &matcher)
-      # the next node to visit is an array of child node pairs matched by the given matcher block
-      super() { |nodes| match_children(visitor, nodes, &matcher) }
+  
+    # @return the top node visited
+    def root
+      @lineage.first
     end
-
-    # Visits the given pair of nodes.
+  
+    # @return the current node being visited
+    def current
+      @lineage.last
+    end
+  
+    # @return the node most recently passed as an argument to this visitor's navigator block,
+    #   or nil if visiting the first node
+    def parent
+      @lineage[-2]
+    end
+  
+    # @return [Enumerable] iterator over each visited node
+    def to_enum(node)
+      # JRuby alert - could use Generator instead, but that results in dire behavior on any error
+      # by crashing with an elided Java lineage trace.
+      VisitorEnumerator.new(self, node)
+    end
+  
+    # Returns a new visitor that traverses a collection of parent nodes in lock-step fashion using
+    # this visitor. The synced {#visit} method applies the visit operator block to an array of child
+    # nodes taken from each parent node, e.g.:
+    #   parent1 = Node.new(1)
+    #   child11 = Node.new(2, parent1)
+    #   child12 = Node.new(3, parent1)
+    #   parent2 = Node.new(1)
+    #   child21 = Node.new(3, parent2)
+    #   CaRuby::Visitor.new { |node| node.children }.sync.to_enum.to_a #=> [
+    #    [parent1, parent2],
+    #    [child11, child21],
+    #    [child12, nil]
+    #   ]
     #
-    # Raises ArgumentError if nodes does not consist of either two node arguments or one two-item Array
-    # argument.
-    def visit(*nodes)
-      if nodes.size == 1 then
-        nodes = nodes.first
-        raise ArgumentError.new("Sync visitor requires a pair of entry nodes") unless nodes.size == 2
-      end
-      super(nodes)
+    # By default, the children are grouped in enumeration order. If a block is given to this method,
+    # then the block is called to match child nodes, e.g. using the above example:
+    #   visitor = CaRuby::Visitor.new { |node| node.children }
+    #   synced = visitor.sync { |nodes, others| nodes.to_compact_hash { others.detect { |other| node.value == other.value } } }
+    #   synced.to_enum.to_a #=> [
+    #     [parent1, parent2],
+    #     [child11, nil],
+    #     [child12, child21]
+    #   ]
+    #
+    # @yield [nodes, others] matches node in others (optional)
+    # @yieldparam [<Resource>] nodes the visited nodes to match
+    # @yieldparam [<Resource>] others the candidates for matching the node
+    def sync(&matcher)
+      SyncVisitor.new(self, &matcher)
     end
-
-    # Returns an Enumerable which applies the given block to each matched node starting at the given nodes.
+  
+    # Returns a new Visitor which determines which nodes to visit by applying the given block
+    # to this visitor, e.g.:
+    #   CaRuby::Visitor.new { |node| node.children }.filter { |parent, children| children.first if parent.age >= 18 }
+    # navigates to the first child of parents 18 or older.
     #
-    # Raises ArgumentError if nodes does not consist of either two node arguments or one two-item Array
-    # argument.
-    def to_enum(*nodes)
-      if nodes.size == 1 then
-        nodes = nodes.first
-        raise ArgumentError.new("Sync visitor requires a pair of entry nodes") unless nodes.size == 2
-      end
-      super(nodes)
+    # The filter block arguments consist of a parent node and an array of children nodes for the parent.
+    # The  block can return nil, a single node to visit or a collection of nodes to visit.
+    #
+    # @return [Visitor] the filter visitor
+    # @yield [parent, children] the filter to select which of the children to visit next
+    # @yieldparam parent the currently visited node
+    # @yieldparam children the nodes slated by this Visitor to visit next
+    # @raise [ArgumentError] if a block is not given to this method
+    def filter
+      raise ArgumentError.new("Filter block not given to visitor filter method") unless block_given?
+      Visitor.new(@options) { |node| yield(node, node_children(node)) }
     end
-
+  
+    protected
+  
+    # Resets this visitor's state in preparation for a new visit.
+    def clear
+      # clear the lineage
+      @lineage.clear
+      # if the visited hash is not shared, then clear it
+      @visited.clear unless @options.has_key?(:visited)
+      # clear the cycles
+      @cycles.clear
+    end
+  
+    # Sets the visited hash.
+    def visited=(hash)
+      @visited = hash ||= {}
+    end
+  
+    # Visits the given node using the block given to this method.
+    # The default block returns node.
+    def visit_node(node)
+      @visited[node] = block_given? ? yield(node) : node
+    end
+  
+    # Returns the children to visit for the given node.
+    def node_children(node)
+      children = @navigator.call(node)
+      return Array::EMPTY_ARRAY if children.nil?
+      Enumerable === children ? children.to_a.compact : [children]
+    end
+  
     private
-
-    # Returns an array of arrays of matched children from the given parent nodes. The children are matched
-    # using the block given to this method, if supplied, or by index otherwise.
-    #
-    # @see #sync a usage example
-    def match_children(visitor, nodes) # :yields: child, others
-      # the parent nodes
-      p1, p2 = nodes
-      # this visitor's children
-      c1 = visitor.node_children(p1)
-      c2 = p2 ? visitor.node_children(p2) : []
-
-      # apply the matcher block on each of this visitor's children and the other children.
-      # if no block, then group the children by index, which is the transpose of the array of children arrays.
-      if block_given? then
-        c1.map { |c| [c, yield(c, c2)] }
-      else
-        # ensure that both children arrays are the same size
-        others = c2.size <= c1.size ? c2.fill(nil, c2.size...c1.size) : c2[0, c1.size]
-        # the children grouped by index is the transpose of the array of children arrays
-        [c1, others].transpose
+    
+    def depth_first?
+      @depth_first_flag
+    end
+  
+    # Visits the root node and all descendants.
+    def visit_root(node, &operator)
+      clear
+      prune_cycle_nodes(node) if @prune_cycle_flag
+      # visit the root node
+      visit_recursive(node, &operator)
+    end
+  
+    # Excludes the internal nodes in cycles starting and ending at the given root.
+    def prune_cycle_nodes(root)
+      @exclude.clear
+      # visit the root, which will detect cycles, and remove the visited nodes afterwords
+      @prune_cycle_flag = false
+      to_enum(root).collect.each { |node| @visited.delete(node) }
+      @prune_cycle_flag = true
+      # add each cyclic internal node to the exclude list
+      @cycles.each { |cycle| cycle[1...-1].each { |node| @exclude << node } if cycle.first == root }
+    end
+  
+    def visit_recursive(node, &operator)
+      # bail if no node or the node is specifically excluded
+      return if node.nil? or @exclude.include?(node)
+      # return the visited value if the node has already been visited
+      if @visited.has_key?(node) then
+        #capture a cycle
+        index = @lineage.index(node)
+        if index then
+          cycle = @lineage[index..-1] << node
+          @cycles << cycle
+        end
+        return @visited[node]
+      end
+      # return nil if the node has not been visited but has been navigated in a depth-first visit
+      return if @lineage.include?(node)
+      # all systems go: visit the node graph
+      visit_node_and_children(node, &operator)
+    end
+  
+    def visit_node_and_children(node, &operator)
+      # set the current node
+      @lineage.push(node)
+      # if depth-first, then visit the children before the current node
+      visit_children(node, &operator) if depth_first?
+      # visit the current node
+      result = visit_node(node, &operator)
+      # if not depth-first, then visit the children after the current node
+      visit_children(node, &operator) unless depth_first?
+      @lineage.pop
+      # return the visit result
+      result
+    end
+  
+    def visit_children(node, &operator)
+      children = node_children(node)
+      children.each { |child| visit_recursive(child, &operator) }
+    end
+  
+    class VisitorEnumerator
+      include Enumerable
+  
+      def initialize(visitor, node)
+        @visitor = visitor
+        @root = node
+      end
+  
+      def each
+        @visitor.visit(@root) { |node| yield(node) }
+      end
+    end
+  
+    class SyncVisitor < Visitor
+      # @param [Visitor] visitor the Visitor which will visit synchronized input
+      # @yield (see Visitor#sync)
+      def initialize(visitor, &matcher)
+        # the next node to visit is an array of child node pairs matched by the given matcher block
+        super() { |nodes| match_children(visitor, nodes, &matcher) }
+      end
+  
+      # Visits the given pair of nodes.
+      #
+      # Raises ArgumentError if nodes does not consist of either two node arguments or one two-item Array
+      # argument.
+      def visit(*nodes)
+        if nodes.size == 1 then
+          nodes = nodes.first
+          raise ArgumentError.new("Sync visitor requires a pair of entry nodes") unless nodes.size == 2
+        end
+        super(nodes)
+      end
+  
+      # Returns an Enumerable which applies the given block to each matched node starting at the given nodes.
+      #
+      # Raises ArgumentError if nodes does not consist of either two node arguments or one two-item Array
+      # argument.
+      def to_enum(*nodes)
+        if nodes.size == 1 then
+          nodes = nodes.first
+          raise ArgumentError.new("Sync visitor requires a pair of entry nodes") unless nodes.size == 2
+        end
+        super(nodes)
+      end
+  
+      private
+  
+      # Returns an array of arrays of matched children from the given parent nodes. The children are matched
+      # using the block given to this method, if supplied, or by index otherwise.
+      #
+      # @see #sync a usage example
+      # @yield (see Visitor#sync)
+      def match_children(visitor, nodes)
+        # the parent nodes
+        p1, p2 = nodes
+        # this visitor's children
+        c1 = visitor.node_children(p1)
+        c2 = p2 ? visitor.node_children(p2) : []
+  
+        # Apply the matcher block on each of this visitor's children and the other children.
+        # If no block is given, then group the children by index, which is the transpose of the array of
+        # children arrays.
+        if block_given? then
+          # Match each item in the first children array to an item from the second children array using
+          # then given block.
+          matches = yield(c1, c2)
+          c1.map { |c| [c, matches[c]] }
+        else
+          # Ensure that both children arrays are the same size.
+          others = c2.size <= c1.size ? c2.fill(nil, c2.size...c1.size) : c2[0, c1.size]
+          # The children grouped by index is the transpose of the array of children arrays.
+          [c1, others].transpose
+        end
       end
     end
   end