accessory 0.1.4 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e6d18076731a0f1b3a28ce6ef77c75ef35dff6b7646f4880286b9bcf64ac393
-  data.tar.gz: '07918b78b0d0b1ae8097f22f36039a04fdefe9e59a10cae62758da84785fac4f'
+  metadata.gz: c03753edaa94362541af5695a93547b6e1f3565f37aa82e7536b3e81d212eb7c
+  data.tar.gz: a3584fbf0b4ee32555feccd642c7225fd6c6f8f85563fcb03b542624f36f7660
 SHA512:
-  metadata.gz: ccdb07d177f3b436c91303585b921494d64aac6baa30abc32debf6ebc7ee4a6ff032b3db48f51d3c7b5d6498daeb7a298bcfd75840682bdc842e8fd70581bcf0
-  data.tar.gz: 2183b4b3513781e43b99490b4b86617ee8f08624c5c71a1355100fb84199bae2f27865d6b17496802c29c5571d39699e239b4dfc163983e789e618c39daf898d
+  metadata.gz: 61015ff40a150d474e43ec454a4c50cb0fd4021660a10cf65d61cd69ec4abe3293523fa53cceda199da7996ed5bea160efc45bf826724647fbc7020f0c666b57
+  data.tar.gz: 3ec8ca3a2f53df27e958621997102d6d10220a15f26c48dc6cdb3f56403f387d629d531433d93f05e6ced2f30ad7d046df0ae27ad620047715b3648bf2ec20dd

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)
+    def lens(...)
+      ::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

@@ -1,19 +1,33 @@
 module Accessory; end
 
 ##
-# @!visibility private
-class Accessory::Accessor
-
-  # @!visibility private
-  DEFAULT_NOT_SET_SENTINEL = :"98e47971-e708-42ca-bee7-0c62fe5e11c9"
+# The parent class for accessors. Contains some shared behavior all accessors
+# can rely on.
+#
+# It doesn't make sense to instantiate this class directly. Instantiate specific
+# {Accessor} subclasses instead.
+#
+# == Implementing an Accessor
+#
+# To implement an {Accessor} subclass, you must define at minimum these two
+# methods (see the method docs of these methods for details):
+#
+# * {Accessor#get}
+# * {Accessor#get_and_update}
+#
+# You may also implement these two methods (again, see method docs for more
+# info):
+#
+# * {Accessor#traverse}
+# * {Accessor#ensure_valid}
 
-  # @!visibility private
+class Accessory::Accessor
   TERMINAL_DEFAULT_FN = lambda{ nil }
+  private_constant :TERMINAL_DEFAULT_FN
 
   # @!visibility private
-  def initialize(default = nil)
-    @default_value = default || DEFAULT_NOT_SET_SENTINEL
-    @make_default_fn = TERMINAL_DEFAULT_FN
+  def initialize(default_value = nil)
+    @default_value = default_value
   end
 
   # @!visibility private
@@ -40,7 +54,10 @@ class Accessory::Accessor
   end
 
   # @!visibility private
-  HIDDEN_IVARS = [:@default_value, :@make_default_fn]
+  HIDDEN_IVARS = [:@default_value, :@successor]
+  private_constant :HIDDEN_IVARS
+
+  # @!visibility private
   def inspect_args
     (instance_variables - HIDDEN_IVARS).map do |ivar_k|
       ivar_v = instance_variable_get(ivar_k)
@@ -49,19 +66,151 @@ class Accessory::Accessor
   end
 
   # @!visibility private
-  attr_accessor :make_default_fn
+  attr_accessor :successor
 
-  # @!visibility private
-  def value_or_default(data)
-    return nil if data.nil?
+  # @!group Helpers
 
-    maybe_value = value_from(data)
-    return maybe_value unless maybe_value.nil?
+  # Safely traverses +data+, with useful defaults; simplifies implementations of
+  # {get} and {get_and_update}.
+  #
+  # Rather than writing redundant traversal logic into both methods, you can
+  # implement the callback method {traverse} to define your traversal, and then
+  # call <tt>traverse_or_default(data)</tt> within your implementation to safely
+  # get a traversal-result to operate on.
+  #
+  # 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)
+    traversal_result = traverse(data) || @default_value
 
-    if DEFAULT_NOT_SET_SENTINEL.equal?(@default_value)
-      @make_default_fn.call
+    if @successor
+      @successor.ensure_valid(traversal_result)
     else
-      @default_value
+      traversal_result
     end
   end
+
+  # @!endgroup
+
+  # Traverses +data+ in some way, and feeds the result of the traversal to the
+  # next step in the accessor chain by yielding the traversal-result to the
+  # passed-in block +succ+. The result from the yield is the result coming from
+  # the end of the accessor chain. Usually, it should be returned as-is.
+  #
+  # +succ+ can be yielded to multiple times, to run the rest of the accessor
+  # chain against multiple parts of +data+. In this case, the yield results
+  # should be gathered up into some container object to be returned together.
+  #
+  # The successor accessor will receive the yielded element as its +data+.
+  #
+  # After returning, the predecessor accessor will receive the result returned
+  # from {get} as the result of its own +yield+.
+  #
+  # @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 {Lens}, this is passed implicitly.
+  # @return [Object] the data to pass back to the predecessor accessor as a
+  #   yield result.
+  def get(data, &succ)
+    raise NotImplementedError, "Accessor subclass #{self.class} must implement #get"
+  end
+
+  # Traverses +data+ in some way, and feeds the result of the traversal to the
+  # next step in the accessor chain by yielding the traversal-result to the
+  # passed-in block +succ+.
+  #
+  # The result of the yield will be a "modification command", one of these two:
+  # * an *update command* <tt>[get_result, new_value]</tt>
+  # * the symbol <tt>:pop</tt>
+  #
+  # In the *update command* case:
+  # * the +get_result+ should be returned as-is (or gathered together into
+  #   a container object if this accessor yields multiple times.) The data flow
+  #   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
+  #   {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
+  #   implies that any {get_and_update} implementation must capture its
+  #   traversal-results before feeding them into yield, in order to return them
+  #   here.
+  # * the traversal-result should be *removed* from +data+. For example, in
+  #   {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+.
+  #
+  # After returning, the predecessor accessor will receive the result returned
+  # from this method as the result of its own +yield+. This implies that
+  # this method should almost always be implemented to *return* an update
+  # command, looking like one of the following:
+  #
+  #   # given [get_result, new_value]
+  #   [get_result, data_after_update]
+  #
+  #   # given :pop
+  #   [traversal_result, data_after_removal]
+  #
+  # @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 {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)
+    raise NotImplementedError, "Accessor subclass #{self.class} must implement #get_and_update"
+  end
+
+  # @!group Callbacks
+
+  # Traverses +data+; called by {traverse_or_default}.
+  #
+  # This method should traverse +data+ however your accessor does that,
+  # producing either one traversal-result or a container-object of gathered
+  # 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.
+  #
+  # @param data [Object] the object to be traversed
+  # @return [Object] the result of traversal
+  def traverse(data)
+    raise NotImplementedError, "Accessor subclass #{self.class} must implement #traverse to use #traverse_or_default"
+  end
+
+  # 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.
+  #
+  #
+  # For example, if your accessor operates on +Enumerable+ values (like
+  # {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+.
+  #
+  # This logic is used to replace invalid intermediate values (e.g. `nil`s and
+  # scalars) with containers during {Lens#put_in} et al.
+  #
+  # @return [Object] a now-valid traversal result
+  def ensure_valid(traversal_result)
+    lambda do
+      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_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
@@ -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