accessory 0.1.2 → 0.1.7

data/lib/accessory/accessors/attribute_accessor.rb

@@ -1,29 +1,72 @@
 require 'accessory/accessor'
 
-class Accessory::AttributeAccessor < Accessory::Accessor
-  def initialize(attr_name, **kwargs)
-    super(**kwargs)
+##
+# Traverses an abstract "attribute" of an arbitrary object, represented by a
+# named getter/setter method pair.
+#
+# For example, <tt>AttributeAccessor.new(:foo)</tt> will traverse through
+# the getter/setter pair <tt>.foo</tt> and <tt>.foo=</tt>.
+#
+# The abstract "attribute" does not have to correspond to an actual
+# +attr_accessor+; the {AttributeAccessor} will work as long as the relevant
+# named getter/setter methods exist on the receiver.
+#
+# *Aliases*
+# * {Access.attr}
+# * {Access::FluentHelpers#attr} (included in {Lens} and {BoundLens})
+#
+# <b>Default constructor</b> used by predecessor accessor
+#
+# * +OpenStruct.new+
+
+class Accessory::Accessors::AttributeAccessor < Accessory::Accessor
+  # @param attr_name [Symbol] the attribute name (i.e. name of the getter method)
+  # @param default [Object] the default to use if the predecessor accessor passes +nil+ data
+  def initialize(attr_name, default: nil)
+    super(default)
     @getter_method_name = :"#{attr_name}"
     @setter_method_name = :"#{attr_name}="
   end
 
+  # @!visibility private
+  def name; "attr"; end
+
+  # @!visibility private
   def inspect_args
     @getter_method_name.inspect
   end
 
-  def default_fn_for_previous_step
-    lambda do
+  # @!visibility private
+  def inspect(format: :long)
+    case format
+    when :long
+      super()
+    when :short
+      ".#{@getter_method_name}"
+    end
+  end
+
+  # @!visibility private
+  def ensure_valid(traversal_result)
+    if traversal_result
+      traversal_result
+    else
       require 'ostruct'
       OpenStruct.new
     end
   end
 
-  def value_from(data)
+  # @!visibility private
+  def traverse(data)
     data.send(@getter_method_name)
   end
 
+  # Finds <tt>data.send(:"#{attr_name}")</tt>, feeds it down the accessor chain,
+  # and returns the result.
+  # @param data [Object] the object to traverse
+  # @return [Object] the value derived from the rest of the accessor chain
   def get(data)
-    value = value_or_default(data)
+    value = traverse_or_default(data)
 
     if block_given?
       yield(value)
@@ -32,8 +75,17 @@ class Accessory::AttributeAccessor < Accessory::Accessor
     end
   end
 
+  # Finds <tt>data.send(:"#{attr_name}")</tt>, feeds it down the accessor chain,
+  # and uses <tt>data.send(:"#{attr_name}=")</tt> to overwrite the stored value
+  # with the returned result.
+  #
+  # If +:pop+ is returned from the accessor chain, the stored value will be
+  # overwritten with `nil`.
+  #
+  # @param data [Object] the object to traverse
+  # @return [Array] a two-element array containing 1. the original value found; and 2. the result value from the accessor chain
   def get_and_update(data)
-    value = value_or_default(data)
+    value = traverse_or_default(data)
 
     case yield(value)
     in [result, new_value]

data/lib/accessory/accessors/between_each_accessor.rb

@@ -1,14 +1,36 @@
 require 'accessory/accessor'
-require 'accessory/array_cursor_position'
+require 'accessory/traversal_position/enumerable_before_offset'
 
-class Accessory::BetweenEachAccessor < Accessory::Accessor
-  def default_fn_for_previous_step
-    lambda{ Array.new }
+##
+# Traverses the positions "between" the elements of an +Enumerable+, including
+# the positions at the "edges" (i.e. before the first, and after the last.)
+#
+# {BetweenEachAccessor} can be used with {Lens#put_in} to insert new
+# elements into an Enumerable between the existing ones.
+#
+# *Aliases*
+# * {Access.between_each}
+# * {Access::FluentHelpers#between_each} (included in {Lens} and {BoundLens})
+#
+# <b>Default constructor</b> used by predecessor accessor
+#
+# * +Array.new+
+
+class Accessory::Accessors::BetweenEachAccessor < Accessory::Accessor
+  # @!visibility private
+  def ensure_valid(traversal_result)
+    if traversal_result.kind_of?(Enumerable)
+      traversal_result
+    else
+      []
+    end
   end
 
+  # @!visibility private
   def inspect_args; nil; end
 
-  def value_from(data)
+  # @!visibility private
+  def traverse(data)
     data_len = data.length
 
     positions = [
@@ -18,12 +40,17 @@ class Accessory::BetweenEachAccessor < Accessory::Accessor
     ]
 
     positions.transpose.map do |(i, b, a)|
-      Accessory::ArrayCursorPosition.new(i, b, a, is_first: i == 0, is_last: i == data_len)
+      Accessory::TraversalPosition::EnumerableBeforeOffset.new(i, b, a, is_first: i == 0, is_last: i == data_len)
     end
   end
 
+  # Feeds {TraversalPosition::EnumerableBeforeOffset}s representing the
+  # positions between the elements of +data+ down the accessor chain.
+  #
+  # @param data [Enumerable] the +Enumerable+ to iterate through
+  # @return [Array] the generated {TraversalPosition::EnumerableBeforeOffset}s
   def get(data)
-    positions = value_or_default(data || [])
+    positions = traverse_or_default(data || [])
 
     if block_given?
       positions.map{ |rec| yield(rec) }
@@ -32,11 +59,24 @@ class Accessory::BetweenEachAccessor < Accessory::Accessor
     end
   end
 
+  # Feeds {TraversalPosition::EnumerableBeforeOffset}s representing the
+  # positions between the elements of +data+ down the accessor chain,
+  # manipulating +data+ using the results.
+  #
+  # If a new element is returned up the accessor chain, the element is inserted
+  # between the existing elements.
+  #
+  # If +:pop+ is returned up the accessor chain, no new element is added.
+  #
+  # @param data [Enumerable] the +Enumerable+ to iterate through
+  # @return [Array] a two-element array containing
+  #   1. the {TraversalPosition::EnumerableBeforeOffset}s
+  #   2. the new {data}
   def get_and_update(data)
     results = []
     new_data = []
 
-    positions = value_or_default(data || [])
+    positions = traverse_or_default(data || [])
 
     positions.each do |pos|
       case yield(pos)

data/lib/accessory/accessors/betwixt_accessor.rb

@@ -1,34 +1,79 @@
 require 'accessory/accessor'
-require 'accessory/array_cursor_position'
+require 'accessory/traversal_position/enumerable_before_offset'
 
-class Accessory::BetwixtAccessor < Accessory::Accessor
-  def initialize(offset, **kwargs)
-    super(**kwargs)
+##
+# Traverses into a specified cursor-position "between" two elements of an
+# +Enumerable+, including the positions at the "edges" (i.e. before the first,
+# or after the last.)
+#
+# If the provided +offset+ is positive, this accessor will traverse the position
+# between <tt>offset - 1</tt>  and +offset+; if +offset+ is negative, this accessor
+# will traverse the position _after_ +offset+.
+#
+# The +offset+ in this accessor has equivalent semantics to the offset in
+# <tt>Array#insert(offset, obj)</tt>.
+#
+# {BetwixtAccessor} can be used with {Lens#put_in} to insert new
+# elements into an Enumerable between the existing ones. If you want to extend
+# an +Enumerable+ as you would with <tt>#push</tt> or <tt>#unshift</tt>, this
+# accessor will have better behavior than using {SubscriptAccessor} would.
+#
+# *Aliases*
+# * {Access.betwixt}
+# * {Access::FluentHelpers#betwixt} (included in {Lens} and {BoundLens})
+#
+# <b>Default constructor</b> used by predecessor accessor
+#
+# * +Array.new+
+
+class Accessory::Accessors::BetwixtAccessor < Accessory::Accessor
+  # @param offset [Integer] the cursor position (i.e. the index of the element after the cursor)
+  # @param default [Object] the default to use if the predecessor accessor passes +nil+ data
+  def initialize(offset, default: nil)
+    super(default)
     @offset = offset
   end
 
+  # @!visibility private
   def inspect_args
     @offset.inspect
   end
 
-  def default_fn_for_previous_step
-    lambda{ Array.new }
+  # @!visibility private
+  def ensure_valid(traversal_result)
+    if traversal_result.kind_of?(Enumerable)
+      traversal_result
+    else
+      []
+    end
   end
 
-  def value_from(data)
-    data_len = data.length
+  # @!visibility private
+  def traverse(data)
+    nil
+    # return :error unless data.kind_of?(Enumerable)
+
+    # data_len = data.length
+
+    # ebo = Accessory::TraversalPosition::EnumerableBeforeOffset.new(
+    #   @offset,
+    #   (@offset > 0) ? data[@offset - 1] : nil,
+    #   (@offset < (data_len - 1)) ? data[@offset + 1] : nil,
+    #   is_first: @offset == 0,
+    #   is_last: @offset == data_len
+    # )
 
-    Accessory::ArrayCursorPosition.new(
-      @offset,
-      (@offset > 0) ? data[@offset - 1] : nil,
-      (@offset < (data_len - 1)) ? data[@offset + 1] : nil,
-      is_first: @offset == 0,
-      is_last: @offset == data_len
-    )
+    # [:ok, ebo]
   end
 
+  # Feeds a {TraversalPosition::EnumerableBeforeOffset} representing the
+  # position between the elements of +data+ at +@offset+ down the accessor
+  # chain.
+  #
+  # @param data [Enumerable] the +Enumerable+ to traverse into
+  # @return [Array] the generated {TraversalPosition::EnumerableBeforeOffset}
   def get(data)
-    pos = value_or_default(data || [])
+    pos = traverse_or_default(data || [])
 
     if block_given?
       yield(pos)
@@ -37,8 +82,21 @@ class Accessory::BetwixtAccessor < Accessory::Accessor
     end
   end
 
+  # Feeds a {TraversalPosition::EnumerableBeforeOffset} representing the
+  # position between the elements of +data+ at +@offset+ down the accessor
+  # chain, manipulating +data+ using the result.
+  #
+  # If a new element is returned up the accessor chain, the element is inserted
+  # at the specified position, using <tt>data.insert(@offset, e)</tt>.
+  #
+  # If +:pop+ is returned up the accessor chain, no new element is added.
+  #
+  # @param data [Enumerable] the +Enumerable+ to traverse into
+  # @return [Array] a two-element array containing
+  #   1. the generated {TraversalPosition::EnumerableBeforeOffset}
+  #   2. the new {data}
   def get_and_update(data)
-    pos = value_or_default(data || [])
+    pos = traverse_or_default(data || [])
 
     case yield(pos)
     in [result, new_value]

data/lib/accessory/accessors/filter_accessor.rb

@@ -1,18 +1,51 @@
 require 'accessory/accessor'
 
-class Accessory::FilterAccessor < Accessory::Accessor
-  def initialize(pred)
-    @pred = pred
+##
+# Traverses the elements of an +Enumerable+ that return a truthy value from
+# a passed-in predicate block.
+#
+# *Aliases*
+# * {Access.filter}
+# * {Access::FluentHelpers#filter} (included in {Lens} and {BoundLens})
+#
+# *Equivalents* in Elixir's {https://hexdocs.pm/elixir/Access.html +Access+} module
+# * {https://hexdocs.pm/elixir/Access.html#filter/1 +Access.filter/1+}
+#
+# <b>Default constructor</b> used by predecessor accessor
+#
+# * +Array.new+
+
+class Accessory::Accessors::FilterAccessor < Accessory::Accessor
+  # Returns a new instance of {FilterAccessor}.
+  #
+  # The predicate function may be passed in as either a positional argument,
+  # or a block.
+  #
+  # @param pred [Proc] The predicate function to use, as an object
+  # @param pred_blk [Proc] The predicate function to use, as a block
+  # @param default [Object] the default to use if the predecessor accessor passes +nil+ data
+  def initialize(pred = nil, default: nil, &pred_blk)
+    @pred = blk || pred
   end
 
+  # @!visibility private
   def inspect_args
     @pred.inspect
   end
 
-  def default_fn_for_previous_step
-    lambda{ Array.new }
+  # @!visibility private
+  def ensure_valid(traversal_result)
+    if traversal_result.kind_of?(Enumerable)
+      traversal_result
+    else
+      []
+    end
   end
 
+  # Feeds each element of +data+ matching the predicate down the accessor chain,
+  # returning the results.
+  # @param data [Enumerable] the +Enumerable+ to iterate through
+  # @return [Array] the values derived from the rest of the accessor chain
   def get(data, &succ)
     if succ
       (data || []).filter(&@pred).map(&succ)
@@ -21,6 +54,14 @@ class Accessory::FilterAccessor < Accessory::Accessor
     end
   end
 
+  # Feeds each element of +data+ matching the predicate down the accessor chain,
+  # overwriting +data+ with the results.
+  #
+  # If +:pop+ is returned from the accessor chain, the element is dropped
+  # from the new +data+.
+  #
+  # @param data [Enumerable] the +Enumerable+ to iterate through
+  # @return [Array] a two-element array containing 1. the original values found during iteration; and 2. the new +data+
   def get_and_update(data)
     results = []
     new_data = []

data/lib/accessory/accessors/first_accessor.rb

@@ -1,18 +1,43 @@
 require 'accessory/accessor'
 
-class Accessory::FirstAccessor < Accessory::Accessor
-  def default_fn_for_previous_step
-    lambda{ Array.new }
+##
+# Traverses into the "first" element within an +Enumerable+, using
+# <tt>#first</tt>.
+#
+# This accessor can be preferable to {SubscriptAccessor} for objects that
+# are not subscriptable, e.g. {Range}.
+#
+# *Aliases*
+# * {Access.first}
+# * {Access::FluentHelpers#first} (included in {Lens} and {BoundLens})
+#
+# <b>Default constructor</b> used by predecessor accessor
+#
+# * +Array.new+
+
+class Accessory::Accessors::FirstAccessor < Accessory::Accessor
+  # @!visibility private
+  def ensure_valid(traversal_result)
+    if traversal_result.kind_of?(Enumerable)
+      traversal_result
+    else
+      []
+    end
   end
 
+  # @!visibility private
   def inspect_args; nil; end
 
-  def value_from(data)
+  # @!visibility private
+  def traverse(data)
     data.first
   end
 
+  # Feeds <tt>data.first</tt> down the accessor chain, returning the result.
+  # @param data [Object] the object to traverse
+  # @return [Object] the value derived from the rest of the accessor chain
   def get(data)
-    value = value_or_default(data)
+    value = traverse_or_default(data)
 
     if block_given?
       yield(value)
@@ -21,12 +46,24 @@ class Accessory::FirstAccessor < Accessory::Accessor
     end
   end
 
+  # Finds <tt>data.first</tt>, feeds it down the accessor chain, and overwrites
+  # the stored value with the returned result.
+  #
+  # If +:pop+ is returned from the accessor chain, the stored value will be
+  # removed using <tt>data.delete_at(0)</tt>.
+  #
+  # @param data [Object] the object to traverse
+  # @return [Array] a two-element array containing 1. the original value found; and 2. the result value from the accessor chain
   def get_and_update(data)
-    old_value = value_or_default(data)
+    old_value = traverse_or_default(data)
 
     case yield(old_value)
     in [result, new_value]
-      data[0] = new_value
+      if data.respond_to?(:"first=")
+        data.first = new_value
+      else
+        data[0] = new_value
+      end
       [result, data]
     in :pop
       data.delete_at(0)