accessory 0.1.5 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a3ac947a1bb5743f72e27fca953624b93a0fdab7c94a483e4f2577f3833ccb0
-  data.tar.gz: 4c8570697b002e4513d2ee117e0ec5290418186e2ea9ad2879a2ba14308b7c25
+  metadata.gz: d946b468b04343c14a9a11fc36428673c56d6851365a6b7119db3dec69111dc8
+  data.tar.gz: 5f2ea0b5fbd0edf89d1529428030370c2e7407f1a62ca4048bc9a078350db379
 SHA512:
-  metadata.gz: 8dc468e225a4150d392727c30d2eb6104fedccc29bcbb22b18320d6b8b3b4afb311a74857540fcb9653d4ad1837f29d4bc1b20800d8d7179d7244c031da3177a
-  data.tar.gz: ae313d407b95a1079f93ad71adb8296a5c8b3c177bc001a5b9866ebe7945dbb2ac46b152c199d2648ac03afc2bb1609aff6190e6beeea170944ac1fe19d16628
+  metadata.gz: a20295b442cb3e2be9c9c7fba21438aa48e759192b24169e475354f72516c1536db19a99fbdc5d41c5b95459183a280d34f5bb2289f149b469e16f8c41027911
+  data.tar.gz: 82d72455e0a4f5e0b078966d644da4d0d26a44d015c74347280da273fa3adfba0b194d736a183c816eb6109477cb0a45dbff2d294a2c8b983411823aacc87b1a

data/lib/accessory.rb

@@ -1,14 +1,14 @@
 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,87 +10,102 @@ 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)
+  # (see Accessory::Accessors::SubscriptAccessor)
   def self.subscript(...)
-    Accessory::SubscriptAccessor.new(...)
+    Accessory::Accessors::SubscriptAccessor.new(...)
   end
 
-  # (see Accessory::AttributeAccessor)
+  # (see Accessory::Accessors::AttributeAccessor)
   def self.attr(...)
-    Accessory::AttributeAccessor.new(...)
+    Accessory::Accessors::AttributeAccessor.new(...)
   end
 
-  # (see Accessory::InstanceVariableAccessor)
+  # (see Accessory::Accessors::InstanceVariableAccessor)
   def self.ivar(...)
-    Accessory::InstanceVariableAccessor.new(...)
+    Accessory::Accessors::InstanceVariableAccessor.new(...)
   end
 
-  # (see Accessory::BetwixtAccessor)
+  # (see Accessory::Accessors::BetwixtAccessor)
   def self.betwixt(...)
-    Accessory::BetwixtAccessor.new(...)
+    Accessory::Accessors::BetwixtAccessor.new(...)
   end
 
-  # Alias for +Accessory::Access.betwixt(0)+. See {Access.betwixt}
+  # Alias for +Accessory::Accessors::Access.betwixt(0)+. See {Access.betwixt}
   def self.before_first
     self.betwixt(0)
   end
 
-  # Alias for +Accessory::Access.betwixt(-1)+. See {Access.betwixt}
+  # Alias for +Accessory::Accessors::Access.betwixt(-1)+. See {Access.betwixt}
   def self.after_last
     self.betwixt(-1)
   end
 
-  # (see Accessory::BetweenEachAccessor)
+  # (see Accessory::Accessors::BetweenEachAccessor)
   def self.between_each
-    Accessory::BetweenEachAccessor.new
+    Accessory::Accessors::BetweenEachAccessor.new
   end
 
-  # (see Accessory::AllAccessor)
+  # (see Accessory::Accessors::AllAccessor)
   def self.all
-    Accessory::AllAccessor.new
+    Accessory::Accessors::AllAccessor.new
   end
 
-  # (see Accessory::FirstAccessor)
+  # (see Accessory::Accessors::FirstAccessor)
   def self.first
-    Accessory::FirstAccessor.new
+    Accessory::Accessors::FirstAccessor.new
   end
 
-  # (see Accessory::LastAccessor)
+  # (see Accessory::Accessors::LastAccessor)
   def self.last
-    Accessory::LastAccessor.new
+    Accessory::Accessors::LastAccessor.new
   end
 
-  # (see Accessory::FilterAccessor)
+  # (see Accessory::Accessors::FilterAccessor)
   def self.filter(&pred)
-    Accessory::FilterAccessor.new(pred)
+    Accessory::Accessors::FilterAccessor.new(pred)
   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)
+  # (see Accessory::Accessors::SubscriptAccessor)
   def subscript(...)
-    self.then(Accessory::SubscriptAccessor.new(...))
+    self.then(Accessory::Accessors::SubscriptAccessor.new(...))
   end
 
   # Alias for {#subscript}
   def [](...)
-    self.then(Accessory::SubscriptAccessor.new(...))
+    self.then(Accessory::Accessors::SubscriptAccessor.new(...))
   end
 
-  # (see Accessory::AttributeAccessor)
+  # (see Accessory::Accessors::AttributeAccessor)
   def attr(...)
-    self.then(Accessory::AttributeAccessor.new(...))
+    self.then(Accessory::Accessors::AttributeAccessor.new(...))
   end
 
-  # (see Accessory::InstanceVariableAccessor)
+  # (see Accessory::Accessors::InstanceVariableAccessor)
   def ivar(...)
-    self.then(Accessory::InstanceVariableAccessor.new(...))
+    self.then(Accessory::Accessors::InstanceVariableAccessor.new(...))
   end
 
-  # (see Accessory::BetwixtAccessor)
+  # (see Accessory::Accessors::BetwixtAccessor)
   def betwixt(...)
-    self.then(Accessory::BetwixtAccessor.new(...))
+    self.then(Accessory::Accessors::BetwixtAccessor.new(...))
   end
 
   # Alias for +#betwixt(0)+. See {#betwixt}
@@ -103,29 +118,29 @@ module Accessory::Access::FluentHelpers
     self.betwixt(-1)
   end
 
-  # (see Accessory::BetweenEachAccessor)
+  # (see Accessory::Accessors::BetweenEachAccessor)
   def between_each
-    self.then(Accessory::BetweenEachAccessor.new)
+    self.then(Accessory::Accessors::BetweenEachAccessor.new)
   end
 
-  # (see Accessory::AllAccessor)
+  # (see Accessory::Accessors::AllAccessor)
   def all
-    self.then(Accessory::AllAccessor.new)
+    self.then(Accessory::Accessors::AllAccessor.new)
   end
 
-  # (see Accessory::FirstAccessor)
+  # (see Accessory::Accessors::FirstAccessor)
   def first
-    self.then(Accessory::FirstAccessor.new)
+    self.then(Accessory::Accessors::FirstAccessor.new)
   end
 
-  # (see Accessory::LastAccessor)
+  # (see Accessory::Accessors::LastAccessor)
   def last
-    self.then(Accessory::LastAccessor.new)
+    self.then(Accessory::Accessors::LastAccessor.new)
   end
 
-  # (see Accessory::FilterAccessor)
+  # (see Accessory::Accessors::FilterAccessor)
   def filter(&pred)
-    self.then(Accessory::FilterAccessor.new(pred))
+    self.then(Accessory::Accessors::FilterAccessor.new(pred))
   end
 end
 
@@ -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

@@ -19,19 +19,15 @@ module Accessory; end
 # info):
 #
 # * {Accessor#traverse}
-# * {Accessor#default_data_constructor}
+# * {Accessor#ensure_valid}
 
 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
 
@@ -81,28 +78,20 @@ class Accessory::Accessor
   # call <tt>traverse_or_default(data)</tt> within your implementation to safely
   # get a traversal-result to operate on.
   #
-  # This method will return +nil+ if the input-data is +nil+, _without_ calling
-  # your {traverse} callback. This means that accessors that use
-  # {traverse_or_default} will _forward_ +nil+ traversal-results along the chain
-  # without being confused by them.
-  #
-  # If your {traverse} callback returns <tt>:error</tt>, a default value will
-  # be used. This is either the +default+ passed to {initialize} by your
-  # implementation calling <tt>super(default)</tt>; or it's the result of
-  # calling {default_data_constructor} on the successor-accessor in the accessor
-  # chain.
+  # The value returned by your {traverse} callback will be validated by your
+  # calling the {ensure_valid} callback of the _successor accessor_ in the Lens
+  # path. {ensure_valid} will replace any value it considers invalid with a
+  # reasonable default. This means you don't need to worry about what will
+  # happen if your traversal doesn't find a value and so returns +nil+. The
+  # successor's {ensure_valid} will replace that +nil+ with a value that works
+  # for it.
   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 +113,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)
@@ -145,7 +134,8 @@ class Accessory::Accessor
   #   of the +get_result+s should replicate the data flow of {get}.
   # * the +new_value+ should be used to *replace* or *overwrite* the result of
   #   this accessor's traversal within +data+. For example, in
-  #   {SubscriptAccessor}, <tt>data[key] = new_value</tt> is executed.
+  #   {Accessors::SubscriptAccessor}, <tt>data[key] = new_value</tt> is
+  #   executed.
   #
   # In the <tt>:pop</tt> command case:
   # * the result of the traversal (*before* the yield) should be returned. This
@@ -153,7 +143,7 @@ class Accessory::Accessor
   #   traversal-results before feeding them into yield, in order to return them
   #   here.
   # * the traversal-result should be *removed* from +data+. For example, in
-  #   {SubscriptAccessor}, <tt>data.delete(key)</tt> is executed.
+  #   {Accessors::SubscriptAccessor}, <tt>data.delete(key)</tt> is executed.
   #
   # The successor in the accessor chain will receive the yielded
   # traversal-results as its own +data+.
@@ -171,7 +161,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,37 +177,40 @@ 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.
+  # {Accessors::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
 
   # @!endgroup
 end
+
+module Accessory::Accessors; 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+}
@@ -15,10 +15,14 @@ require 'accessory/accessor'
 #
 # * +Array.new+
 
-class Accessory::AllAccessor < Accessory::Accessor
+class Accessory::Accessors::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
@@ -46,17 +50,28 @@ class Accessory::AllAccessor < Accessory::Accessor
   def get_and_update(data)
     results = []
     new_data = []
+    dirty = false
 
     (data || []).each do |pos|
       case yield(pos)
-      in [result, new_value]
+      in [:clean, result, _]
+        results.push(result)
+        new_data.push(pos)
+        # ok
+      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/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,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,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