accessory 0.1.4 → 0.1.9

data/lib/accessory/accessors/attribute_accessor.rb

@@ -8,18 +8,18 @@ require 'accessory/accessor'
 # 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.
+# +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 {LensPath} and {Lens})
+# * {Access::FluentHelpers#attr} (included in {Lens} and {BoundLens})
 #
 # <b>Default constructor</b> used by predecessor accessor
 #
 # * +OpenStruct.new+
 
-class Accessory::AttributeAccessor < Accessory::Accessor
+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)
@@ -47,15 +47,17 @@ class Accessory::AttributeAccessor < Accessory::Accessor
   end
 
   # @!visibility private
-  def default_fn_for_previous_step
-    lambda do
+  def ensure_valid(traversal_result)
+    if traversal_result
+      traversal_result
+    else
       require 'ostruct'
       OpenStruct.new
     end
   end
 
   # @!visibility private
-  def value_from(data)
+  def traverse(data)
     data.send(@getter_method_name)
   end
 
@@ -64,7 +66,7 @@ class Accessory::AttributeAccessor < Accessory::Accessor
   # @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)
@@ -83,15 +85,17 @@ class Accessory::AttributeAccessor < Accessory::Accessor
   # @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]
+    in [:clean, result, _]
+      [:clean, result, data]
+    in [:dirty, result, new_value]
       data.send(@setter_method_name, new_value)
-      [result, data]
+      [:dirty, result, data]
     in :pop
       data.send(@setter_method_name, nil)
-      [value, data]
+      [:dirty, value, data]
     end
   end
 end

data/lib/accessory/accessors/between_each_accessor.rb

@@ -1,32 +1,36 @@
 require 'accessory/accessor'
-require 'accessory/array_cursor_position'
+require 'accessory/traversal_position/enumerable_before_offset'
 
 ##
 # 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 {LensPath#put_in} to insert new
+# 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 {LensPath} and {Lens})
+# * {Access::FluentHelpers#between_each} (included in {Lens} and {BoundLens})
 #
 # <b>Default constructor</b> used by predecessor accessor
 #
 # * +Array.new+
 
-class Accessory::BetweenEachAccessor < Accessory::Accessor
+class Accessory::Accessors::BetweenEachAccessor < Accessory::Accessor
   # @!visibility private
-  def default_fn_for_previous_step
-    lambda{ Array.new }
+  def ensure_valid(traversal_result)
+    if traversal_result.kind_of?(Enumerable)
+      traversal_result
+    else
+      []
+    end
   end
 
   # @!visibility private
   def inspect_args; nil; end
 
   # @!visibility private
-  def value_from(data)
+  def traverse(data)
     data_len = data.length
 
     positions = [
@@ -36,17 +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 {ArrayCursorPosition}s representing the positions between the elements
-  # of +data+ down the accessor chain.
+  # 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 {ArrayCursorPosition}s
+  # @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) }
@@ -55,8 +59,9 @@ class Accessory::BetweenEachAccessor < Accessory::Accessor
     end
   end
 
-  # Feeds {ArrayCursorPosition}s representing the positions between the elements
-  # of +data+ down the accessor chain, manipulating +data+ using the results.
+  # 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.
@@ -64,19 +69,26 @@ class Accessory::BetweenEachAccessor < Accessory::Accessor
   # 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 {ArrayCursorPosition}s; and 2. the new {data}
+  # @return [Array] a two-element array containing
+  #   1. the {TraversalPosition::EnumerableBeforeOffset}s
+  #   2. the new {data}
   def get_and_update(data)
     results = []
     new_data = []
+    dirty = false
 
-    positions = value_or_default(data || [])
+    positions = traverse_or_default(data || [])
 
     positions.each do |pos|
       case yield(pos)
-      in [result, new_value]
+      in [:clean, result, _]
+        results.push(result)
+      in [:dirty, result, new_value]
         new_data.push(new_value)
         results.push(result)
+        dirty = true
       in :pop
+        # ok
       end
 
       unless pos.last?
@@ -84,6 +96,10 @@ class Accessory::BetweenEachAccessor < Accessory::Accessor
       end
     end
 
-    [results, new_data]
+    if dirty
+      [:dirty, results, new_data]
+    else
+      [:clean, results, data]
+    end
   end
 end

data/lib/accessory/accessors/betwixt_accessor.rb

@@ -1,5 +1,5 @@
 require 'accessory/accessor'
-require 'accessory/array_cursor_position'
+require 'accessory/traversal_position/enumerable_before_offset'
 
 ##
 # Traverses into a specified cursor-position "between" two elements of an
@@ -13,20 +13,21 @@ require 'accessory/array_cursor_position'
 # The +offset+ in this accessor has equivalent semantics to the offset in
 # <tt>Array#insert(offset, obj)</tt>.
 #
-# {BetwixtAccessor} can be used with {LensPath#put_in} to insert new
+# {Accessors::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.
+# accessor will have better behavior than using {Accessors::SubscriptAccessor}
+# would.
 #
 # *Aliases*
 # * {Access.betwixt}
-# * {Access::FluentHelpers#betwixt} (included in {LensPath} and {Lens})
+# * {Access::FluentHelpers#betwixt} (included in {Lens} and {BoundLens})
 #
 # <b>Default constructor</b> used by predecessor accessor
 #
 # * +Array.new+
 
-class Accessory::BetwixtAccessor < Accessory::Accessor
+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)
@@ -40,30 +41,40 @@ class Accessory::BetwixtAccessor < Accessory::Accessor
   end
 
   # @!visibility private
-  def default_fn_for_previous_step
-    lambda{ Array.new }
+  def ensure_valid(traversal_result)
+    if traversal_result.kind_of?(Enumerable)
+      traversal_result
+    else
+      []
+    end
   end
 
   # @!visibility private
-  def value_from(data)
-    data_len = data.length
+  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 an {ArrayCursorPosition} representing the position between the
-  # elements of +data+ at +@offset+ down the accessor chain.
+  # 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 {ArrayCursorPosition}
+  # @return [Array] the generated {TraversalPosition::EnumerableBeforeOffset}
   def get(data)
-    pos = value_or_default(data || [])
+    pos = traverse_or_default(data || [])
 
     if block_given?
       yield(pos)
@@ -72,9 +83,9 @@ class Accessory::BetwixtAccessor < Accessory::Accessor
     end
   end
 
-  # Feeds an {ArrayCursorPosition} representing the position between the
-  # elements of +data+ at +@offset+ down the accessor chain, manipulating
-  # +data+ using the result.
+  # 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>.
@@ -82,17 +93,21 @@ class Accessory::BetwixtAccessor < Accessory::Accessor
   # 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 {ArrayCursorPosition}; and 2. the new {data}
+  # @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]
+    in [:dirty, result, new_value]
       data ||= []
       data.insert(@offset, new_value)
-      [result, data]
+      [:dirty, result, data]
     in :pop
-      [nil, data]
+      [:clean, nil, data]
+    in [:clean, result, _]
+      [:clean, result, data]
     end
   end
 end

data/lib/accessory/accessors/filter_accessor.rb

@@ -6,7 +6,7 @@ require 'accessory/accessor'
 #
 # *Aliases*
 # * {Access.filter}
-# * {Access::FluentHelpers#filter} (included in {LensPath} and {Lens})
+# * {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+}
@@ -15,7 +15,7 @@ require 'accessory/accessor'
 #
 # * +Array.new+
 
-class Accessory::FilterAccessor < Accessory::Accessor
+class Accessory::Accessors::FilterAccessor < Accessory::Accessor
   # Returns a new instance of {FilterAccessor}.
   #
   # The predicate function may be passed in as either a positional argument,
@@ -34,8 +34,12 @@ class Accessory::FilterAccessor < Accessory::Accessor
   end
 
   # @!visibility private
-  def default_fn_for_previous_step
-    lambda{ Array.new }
+  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,
@@ -61,6 +65,7 @@ class Accessory::FilterAccessor < Accessory::Accessor
   def get_and_update(data)
     results = []
     new_data = []
+    dirty = false
 
     (data || []).each do |pos|
       unless @pred.call(pos)
@@ -69,14 +74,23 @@ class Accessory::FilterAccessor < Accessory::Accessor
       end
 
       case yield(pos)
-      in [result, new_value]
+      in [:clean, result, _]
+        results.push(result)
+        new_data.push(pos)
+      in [:dirty, result, new_value]
         results.push(result)
         new_data.push(new_value)
+        dirty = true
       in :pop
         results.push(pos)
+        dirty = true
       end
     end
 
-    [results, new_data]
+    if dirty
+      [:dirty, results, new_data]
+    else
+      [:clean, results, data]
+    end
   end
 end

data/lib/accessory/accessors/first_accessor.rb

@@ -4,28 +4,32 @@ require 'accessory/accessor'
 # 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}.
+# This accessor can be preferable to {Accessors::SubscriptAccessor} for objects
+# that are not subscriptable, e.g. +Range+.
 #
 # *Aliases*
 # * {Access.first}
-# * {Access::FluentHelpers#first} (included in {LensPath} and {Lens})
+# * {Access::FluentHelpers#first} (included in {Lens} and {BoundLens})
 #
 # <b>Default constructor</b> used by predecessor accessor
 #
 # * +Array.new+
 
-class Accessory::FirstAccessor < Accessory::Accessor
+class Accessory::Accessors::FirstAccessor < Accessory::Accessor
   # @!visibility private
-  def default_fn_for_previous_step
-    lambda{ Array.new }
+  def ensure_valid(traversal_result)
+    if traversal_result.kind_of?(Enumerable)
+      traversal_result
+    else
+      []
+    end
   end
 
   # @!visibility private
   def inspect_args; nil; end
 
   # @!visibility private
-  def value_from(data)
+  def traverse(data)
     data.first
   end
 
@@ -33,7 +37,7 @@ class Accessory::FirstAccessor < Accessory::Accessor
   # @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)
@@ -51,19 +55,21 @@ class Accessory::FirstAccessor < Accessory::Accessor
   # @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]
+    in [:clean, result, _]
+      [:clean, result, data]
+    in [:dirty, result, new_value]
       if data.respond_to?(:"first=")
         data.first = new_value
       else
         data[0] = new_value
       end
-      [result, data]
+      [:dirty, result, data]
     in :pop
       data.delete_at(0)
-      [old_value, data]
+      [:dirty, old_value, data]
     end
   end
 end