accessory 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a3ac947a1bb5743f72e27fca953624b93a0fdab7c94a483e4f2577f3833ccb0
-  data.tar.gz: 4c8570697b002e4513d2ee117e0ec5290418186e2ea9ad2879a2ba14308b7c25
+  metadata.gz: 9880e7e5ea88c0b373a1cc3d5d4861788f368905c761b2ec3a7236d7282ada39
+  data.tar.gz: 7386d98dc728a663904564e0a6825de0d7690e806950e5e95d6e8b39d4d20cd6
 SHA512:
-  metadata.gz: 8dc468e225a4150d392727c30d2eb6104fedccc29bcbb22b18320d6b8b3b4afb311a74857540fcb9653d4ad1837f29d4bc1b20800d8d7179d7244c031da3177a
-  data.tar.gz: ae313d407b95a1079f93ad71adb8296a5c8b3c177bc001a5b9866ebe7945dbb2ac46b152c199d2648ac03afc2bb1609aff6190e6beeea170944ac1fe19d16628
+  metadata.gz: dbee544b8dc699adb962559b98278d48edeed2a4d5b9c4d3c6c92ad3c4a38ffb4df5ced18274b465dfe68fd34dd15a50c06c2febae4e54049a4049d377cb10cd
+  data.tar.gz: 0d1be0f43650e87a1616b5c2ac968b7407c5d8e380abb7e30ad84823816d486341a2c1b791814c55695dc77f2bf0337df834816c2a703bacbb2a3f582f362907

data/lib/accessory.rb

@@ -1,14 +1,17 @@
+##
+#
+
 module Accessory; end
 
 require 'accessory/version'
-require 'accessory/lens_path'
 require 'accessory/lens'
+require 'accessory/bound_lens'
 require 'accessory/access'
 
 module Accessory
   refine ::Object do
     def lens(...)
-      ::Accessory::Lens.on(self, ...)
+      ::Accessory::BoundLens.on(self, ...)
     end
   end
 end

data/lib/accessory/access.rb

@@ -10,6 +10,13 @@ require 'accessory/accessors/all_accessor'
 require 'accessory/accessors/first_accessor'
 require 'accessory/accessors/last_accessor'
 
+##
+# A set of convenient module-function helpers to use with <tt>Lens[...]</tt>.
+#
+# These functions aren't very convenient unless you
+#
+#    include Accessory
+
 module Accessory::Access
   # (see Accessory::SubscriptAccessor)
   def self.subscript(...)
@@ -67,6 +74,14 @@ module Accessory::Access
   end
 end
 
+##
+# A set of convenient "fluent API" builder methods
+# that get mixed into {Lens} and {BoundLens}.
+#
+# These do the same thing as the {Access} helper of the same name, but
+# wrap the resulting accessor in a call to <tt>#then</tt>, deriving a new
+# {Lens} or {BoundLens} from the addition of the accessor.
+
 module Accessory::Access::FluentHelpers
   # (see Accessory::SubscriptAccessor)
   def subscript(...)
@@ -133,6 +148,6 @@ class Accessory::Lens
   include Accessory::Access::FluentHelpers
 end
 
-class Accessory::LensPath
+class Accessory::BoundLens
   include Accessory::Access::FluentHelpers
 end

data/lib/accessory/accessor.rb

@@ -22,16 +22,12 @@ module Accessory; end
 # * {Accessor#default_data_constructor}
 
 class Accessory::Accessor
-  # @!visibility private
-  DEFAULT_NOT_SET_SENTINEL = :"98e47971-e708-42ca-bee7-0c62fe5e11c9"
-
-  # @!visibility private
   TERMINAL_DEFAULT_FN = lambda{ nil }
+  private_constant :TERMINAL_DEFAULT_FN
 
   # @!visibility private
-  def initialize(default = nil)
-    @default_value = default || DEFAULT_NOT_SET_SENTINEL
-    @succ_default_data_constructor = TERMINAL_DEFAULT_FN
+  def initialize(default_value = nil)
+    @default_value = default_value
   end
 
   # @!visibility private
@@ -58,7 +54,8 @@ class Accessory::Accessor
   end
 
   # @!visibility private
-  HIDDEN_IVARS = [:@default_value, :@succ_default_data_constructor]
+  HIDDEN_IVARS = [:@default_value, :@successor]
+  private_constant :HIDDEN_IVARS
 
   # @!visibility private
   def inspect_args
@@ -69,7 +66,7 @@ class Accessory::Accessor
   end
 
   # @!visibility private
-  attr_accessor :succ_default_data_constructor
+  attr_accessor :successor
 
   # @!group Helpers
 
@@ -92,17 +89,12 @@ class Accessory::Accessor
   # calling {default_data_constructor} on the successor-accessor in the accessor
   # chain.
   def traverse_or_default(data)
-    return nil if data.nil?
+    traversal_result = traverse(data) || @default_value
 
-    case traverse(data)
-    in [:ok, traversal_result]
+    if @successor
+      @successor.ensure_valid(traversal_result)
+    else
       traversal_result
-    in :error
-      if DEFAULT_NOT_SET_SENTINEL.equal?(@default_value)
-        @succ_default_data_constructor.call
-      else
-        @default_value
-      end
     end
   end
 
@@ -124,7 +116,7 @@ class Accessory::Accessor
   #
   # @param data [Enumerable] the data yielded by the predecessor accessor.
   # @param succ [Proc] a thunk to the successor accessor. When {get} is called
-  #   by a {LensPath}, this is passed implicitly.
+  #   by a {Lens}, this is passed implicitly.
   # @return [Object] the data to pass back to the predecessor accessor as a
   #   yield result.
   def get(data, &succ)
@@ -171,7 +163,7 @@ class Accessory::Accessor
   #
   # @param data [Enumerable] the data yielded by the predecessor accessor.
   # @param succ [Proc] a thunk to the successor accessor. When {get} is called
-  #   by a {LensPath}, this is passed implicitly.
+  #   by a {Lens}, this is passed implicitly.
   # @return [Object] the modification-command to pass back to the predecessor
   #   accessor as a yield result.
   def get_and_update(data, &succ)
@@ -187,35 +179,36 @@ class Accessory::Accessor
   # traversal-results.
   #
   # This method can assume that +data+ is a valid receiver for the traversal
-  # it performs. {traverse_or_default} takes care of feeding in a default +data+ in
-  # the case where the predecessor passed invalid data.
+  # it performs. {traverse_or_default} takes care of feeding in a default +data+
+  # in the case where the predecessor passed invalid data.
   #
   # @param data [Object] the object to be traversed
-  # @return [Object]
-  #   * <tt>[:ok, traversal_results]</tt> if traversal succeeds
-  #   * +:error+ if traversal fails
+  # @return [Object] the result of traversal
   def traverse(data)
     raise NotImplementedError, "Accessor subclass #{self.class} must implement #traverse to use #traverse_or_default"
   end
 
-  # Constructs a default value; called by {traverse_or_default}.
+  # Ensures that the predecessor accessor's traversal result is one this
+  # accessor can operate on; called by {traverse_or_default}.
+  #
+  # This callback should validate that the +traversal_result+ is one that can
+  # be traversed by the traversal-method of this accessor. If it can, the
+  # +traversal_result+ should be returned unchanged. If it cannot, an object
+  # that _can_ be traversed should be returned instead.
   #
-  # Returns a default constructor Proc for the {traverse_or_default} call in
-  # the *predecessor* accessor to use.
   #
   # For example, if your accessor operates on +Enumerable+ values (like
-  # {AllAccessor}), then a useful default for the predecessor accessor to
-  # pass you as +data+ would be an Array.
+  # {AllAccessor}), then this method should validate that the +traversal_result+
+  # is +Enumerable+; and, if it isn't, return something that is — e.g. an empty
+  # +Array+.
   #
-  # In that case, you can return `lambda{ Array.new }` here. This default
-  # constructor will be passed along the {LensPath} to the predecessor, which
-  # will then use it in {traverse_or_default} if it was not configured with
-  # an explicit default.
+  # This logic is used to replace invalid intermediate values (e.g. `nil`s and
+  # scalars) with containers during {Lens#put_in} et al.
   #
-  # @return [Proc] a Proc that, when called, produces a default traversal-result
-  def default_data_constructor
+  # @return [Object] a now-valid traversal result
+  def ensure_valid(traversal_result)
     lambda do
-      raise NotImplementedError, "Accessor subclass #{self.class} must implement #default_data_constructor to allow chain-predecessor to use #traverse_or_default"
+      raise NotImplementedError, "Accessor subclass #{self.class} must implement #ensure_valid to allow chain-predecessor to use #traverse_or_default"
     end
   end
 

data/lib/accessory/accessors/all_accessor.rb

@@ -5,7 +5,7 @@ require 'accessory/accessor'
 #
 # *Aliases*
 # * {Access.all}
-# * {Access::FluentHelpers#all} (included in {LensPath} and {Lens})
+# * {Access::FluentHelpers#all} (included in {Lens} and {BoundLens})
 #
 # *Equivalents* in Elixir's {https://hexdocs.pm/elixir/Access.html +Access+} module
 # * {https://hexdocs.pm/elixir/Access.html#all/0 +Access.all/0+}
@@ -17,8 +17,12 @@ require 'accessory/accessor'
 
 class Accessory::AllAccessor < 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

data/lib/accessory/accessors/attribute_accessor.rb

@@ -13,7 +13,7 @@ require 'accessory/accessor'
 #
 # *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
 #
@@ -47,8 +47,10 @@ class Accessory::AttributeAccessor < Accessory::Accessor
   end
 
   # @!visibility private
-  def default_data_constructor
-    lambda do
+  def ensure_valid(traversal_result)
+    if traversal_result
+      traversal_result
+    else
       require 'ostruct'
       OpenStruct.new
     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,7 +85,7 @@ 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]

data/lib/accessory/accessors/between_each_accessor.rb

@@ -5,12 +5,12 @@ 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
 #
@@ -18,8 +18,12 @@ require 'accessory/traversal_position/enumerable_before_offset'
 
 class Accessory::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) }
@@ -72,7 +76,7 @@ class Accessory::BetweenEachAccessor < Accessory::Accessor
     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

@@ -13,14 +13,14 @@ 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
+# {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 {LensPath} and {Lens})
+# * {Access::FluentHelpers#betwixt} (included in {Lens} and {BoundLens})
 #
 # <b>Default constructor</b> used by predecessor accessor
 #
@@ -40,21 +40,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 +73,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,7 +96,7 @@ 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]

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+}
@@ -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,

data/lib/accessory/accessors/first_accessor.rb

@@ -9,7 +9,7 @@ require 'accessory/accessor'
 #
 # *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
 #
@@ -17,8 +17,12 @@ require 'accessory/accessor'
 
 class Accessory::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,7 +55,7 @@ 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]