accessory 0.1.5 → 0.1.10

data/lib/accessory/accessors/between_each_accessor.rb

@@ -5,21 +5,25 @@ 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_data_constructor
-    lambda{ Array.new }
+  def ensure_valid(traversal_result)
+    if traversal_result.kind_of?(Enumerable)
+      traversal_result
+    else
+      []
+    end
   end
 
   # @!visibility private
@@ -46,7 +50,7 @@ class Accessory::BetweenEachAccessor < Accessory::Accessor
   # @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) }
@@ -71,15 +75,20 @@ class Accessory::BetweenEachAccessor < Accessory::Accessor
   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?
@@ -87,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

@@ -13,20 +13,21 @@ require 'accessory/traversal_position/enumerable_before_offset'
 # 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,21 +41,30 @@ class Accessory::BetwixtAccessor < Accessory::Accessor
   end
 
   # @!visibility private
-  def default_data_constructor
-    lambda{ Array.new }
+  def ensure_valid(traversal_result)
+    if traversal_result.kind_of?(Enumerable)
+      traversal_result
+    else
+      []
+    end
   end
 
   # @!visibility private
   def traverse(data)
-    data_len = data.length
+    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::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
-    )
+    # [:ok, ebo]
   end
 
   # Feeds a {TraversalPosition::EnumerableBeforeOffset} representing the
@@ -64,7 +74,7 @@ class Accessory::BetwixtAccessor < Accessory::Accessor
   # @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)
@@ -87,15 +97,17 @@ class Accessory::BetwixtAccessor < Accessory::Accessor
   #   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_data_constructor
-    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,21 +4,25 @@ 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_data_constructor
-    lambda{ Array.new }
+  def ensure_valid(traversal_result)
+    if traversal_result.kind_of?(Enumerable)
+      traversal_result
+    else
+      []
+    end
   end
 
   # @!visibility private
@@ -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

data/lib/accessory/accessors/instance_variable_accessor.rb

@@ -8,14 +8,14 @@ require 'accessory/accessor'
 #
 # *Aliases*
 # * {Access.ivar}
-# * {Access::FluentHelpers#ivar} (included in {LensPath} and {Lens})
+# * {Access::FluentHelpers#ivar} (included in {Lens} and {BoundLens})
 #
 # <b>Default constructor</b> used by predecessor accessor
 #
 # * +Object.new+
 
-class Accessory::InstanceVariableAccessor < Accessory::Accessor
-  # @param attr_name [Symbol] the instance-variable name
+class Accessory::Accessors::InstanceVariableAccessor < Accessory::Accessor
+  # @param ivar_name [Symbol] the instance-variable name
   # @param default [Object] the default to use if the predecessor accessor passes +nil+ data
   def initialize(ivar_name, default: nil)
     super(default)
@@ -33,8 +33,8 @@ class Accessory::InstanceVariableAccessor < Accessory::Accessor
   end
 
   # @!visibility private
-  def default_data_constructor
-    lambda{ Object.new }
+  def ensure_valid(traversal_result)
+    traversal_result || Object.new
   end
 
   # @!visibility private
@@ -47,7 +47,7 @@ class Accessory::InstanceVariableAccessor < 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)
@@ -67,15 +67,17 @@ class Accessory::InstanceVariableAccessor < 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.instance_variable_set(@ivar_name, new_value)
-      [result, data]
+      [:dirty, result, data]
     in :pop
       data.remove_instance_variable(@ivar_name)
-      [value, data]
+      [:dirty, value, data]
     end
   end
 end

data/lib/accessory/accessors/last_accessor.rb

@@ -4,21 +4,25 @@ require 'accessory/accessor'
 # Traverses into the "last" element within an +Enumerable+, using
 # <tt>#last</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.last}
-# * {Access::FluentHelpers#last} (included in {LensPath} and {Lens})
+# * {Access::FluentHelpers#last} (included in {Lens} and {BoundLens})
 #
 # <b>Default constructor</b> used by predecessor accessor
 #
 # * +Array.new+
 
-class Accessory::LastAccessor < Accessory::Accessor
+class Accessory::Accessors::LastAccessor < Accessory::Accessor
   # @!visibility private
-  def default_data_constructor
-    lambda{ Array.new }
+  def ensure_valid(traversal_result)
+    if traversal_result.kind_of?(Enumerable)
+      traversal_result
+    else
+      []
+    end
   end
 
   # @!visibility private
@@ -33,7 +37,7 @@ class Accessory::LastAccessor < 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::LastAccessor < 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?(:"last=")
         data.last = new_value
       else
         data[-1] = new_value
       end
-      [result, data]
+      [:dirty, result, data]
     in :pop
       data.delete_at(-1)
-      [old_value, data]
+      [:dirty, old_value, data]
     end
   end
 end

data/lib/accessory/accessors/subscript_accessor.rb

@@ -7,9 +7,10 @@ require 'accessory/accessor'
 #
 # *Aliases*
 # * {Access.subscript}
-# * {Access::FluentHelpers#subscript} (included in {LensPath} and {Lens})
-# * {Access::FluentHelpers#[]} (included in {LensPath} and {Lens})
-# * just passing a +key+ will also work, when +not(key.kind_of?(Accessor))+ (this is a special case in {LensPath#initialize})
+# * {Access::FluentHelpers#subscript} (included in {Lens} and {BoundLens})
+# * {Access::FluentHelpers#[]} (included in {Lens} and {BoundLens})
+# * just passing a +key+ will also work, when +not(key.kind_of?(Accessor))+
+#   (this is a special case in {Lens#initialize})
 #
 # *Equivalents* in Elixir's {https://hexdocs.pm/elixir/Access.html +Access+} module
 # * {https://hexdocs.pm/elixir/Access.html#at/1 +Access.at/1+}
@@ -28,9 +29,9 @@ require 'accessory/accessor'
 #   # default-constructs a Hash, not an Array
 #   [].lens[0][0].put_in(1) # => [{0=>1}]
 #
-# Other accessors ({FirstAccessor}, {BetwixtAccessor}, etc.) may fit your expectations more closely for +Array+ traversal.
+# Other accessors ({Accessors::FirstAccessor}, {Accessors::BetwixtAccessor}, etc.) may fit your expectations more closely for +Array+ traversal.
 
-class Accessory::SubscriptAccessor < Accessory::Accessor
+class Accessory::Accessors::SubscriptAccessor < Accessory::Accessor
   # @!visibility private
   def initialize(key, **kwargs)
     super(**kwargs)
@@ -53,8 +54,12 @@ class Accessory::SubscriptAccessor < Accessory::Accessor
   end
 
   # @!visibility private
-  def default_data_constructor
-    lambda{ Hash.new }
+  def ensure_valid(traversal_result)
+    if traversal_result.respond_to?(:[])
+      traversal_result
+    else
+      {}
+    end
   end
 
   # @!visibility private
@@ -67,7 +72,7 @@ class Accessory::SubscriptAccessor < Accessory::Accessor
   # @param data [Enumerable] the +Enumerable+ to index into
   # @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)
@@ -84,15 +89,17 @@ class Accessory::SubscriptAccessor < Accessory::Accessor
   # @param data [Enumerable] the +Enumerable+ to index into
   # @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[@key] = new_value
-      [result, data]
+      [:dirty, result, data]
     in :pop
       data.delete(@key)
-      [value, data]
+      [:dirty, value, data]
     end
   end
 end