accessory 0.1.3 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3276e22b0eb2ad764f2a1d742962c2b3c2e066f8949b5328c00d4bae0f08edf
-  data.tar.gz: c90330dc2daf7065405406e25b1feed10f3b224a822013af44e4645195d8d76d
+  metadata.gz: bad93b39fc1164c938ed170896bfc5d6ef0c7d157a443b05395ef835fcaf6706
+  data.tar.gz: ac0cdef27d42a339c3b640ee06c8231f4e724b2b2e541eb081bc37d33542fa35
 SHA512:
-  metadata.gz: 6a98028a9b9e2e1913c098a8858e4994c4793f8451ea6e15bfca2cb5dd54c1ae54b31a5320094632e329767a1ee3cf0baa5e84fc3571c3b104914cbeaf2ab767
-  data.tar.gz: b7b10ab902d4841090f1df7d5c770a16d02400f0d7b12761274928aefaca411f216c61f6a8436e7ee243fb20b45ff1feaa77fb22f9d2a16e1245c3506c61eb65
+  metadata.gz: ae8c4170a783795b4e436232f1051c7bd3b0ef39132af63fcc0055c27df97eaabcd981f00a338f38bf0a343a582e30db1dc7b2cc4026f07d8dfa93d47177df8c
+  data.tar.gz: f78e0b73341624deb56871906d2dc33e5791a7514f3c6bd9f3db955c6f7e09e95621827d9a7978ec21f5fb7ff1fbbad764feb271e676525e957355e7dd7b6fe1

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,91 +10,137 @@ 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::Accessors::SubscriptAccessor)
+  def self.subscript(...)
+    Accessory::Accessors::SubscriptAccessor.new(...)
+  end
+
+  # (see Accessory::Accessors::AttributeAccessor)
   def self.attr(...)
-    Accessory::AttributeAccessor.new(...)
+    Accessory::Accessors::AttributeAccessor.new(...)
   end
 
+  # (see Accessory::Accessors::InstanceVariableAccessor)
   def self.ivar(...)
-    Accessory::InstanceVariableAccessor.new(...)
+    Accessory::Accessors::InstanceVariableAccessor.new(...)
   end
 
+  # (see Accessory::Accessors::BetwixtAccessor)
   def self.betwixt(...)
-    Accessory::BetwixtAccessor.new(...)
+    Accessory::Accessors::BetwixtAccessor.new(...)
   end
 
+  # Alias for +Accessory::Accessors::Access.betwixt(0)+. See {Access.betwixt}
   def self.before_first
     self.betwixt(0)
   end
 
+  # Alias for +Accessory::Accessors::Access.betwixt(-1)+. See {Access.betwixt}
   def self.after_last
     self.betwixt(-1)
   end
 
+  # (see Accessory::Accessors::BetweenEachAccessor)
   def self.between_each
-    Accessory::BetweenEachAccessor.new
+    Accessory::Accessors::BetweenEachAccessor.new
   end
 
+  # (see Accessory::Accessors::AllAccessor)
   def self.all
-    Accessory::AllAccessor.new
+    Accessory::Accessors::AllAccessor.new
   end
 
+  # (see Accessory::Accessors::FirstAccessor)
   def self.first
-    Accessory::FirstAccessor.new
+    Accessory::Accessors::FirstAccessor.new
   end
 
+  # (see Accessory::Accessors::LastAccessor)
   def self.last
-    Accessory::LastAccessor.new
+    Accessory::Accessors::LastAccessor.new
   end
 
+  # (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::Accessors::SubscriptAccessor)
+  def subscript(...)
+    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::Accessors::AttributeAccessor)
   def attr(...)
-    self.then(Accessory::AttributeAccessor.new(...))
+    self.then(Accessory::Accessors::AttributeAccessor.new(...))
   end
 
+  # (see Accessory::Accessors::InstanceVariableAccessor)
   def ivar(...)
-    self.then(Accessory::InstanceVariableAccessor.new(...))
+    self.then(Accessory::Accessors::InstanceVariableAccessor.new(...))
   end
 
+  # (see Accessory::Accessors::BetwixtAccessor)
   def betwixt(...)
-    self.then(Accessory::BetwixtAccessor.new(...))
+    self.then(Accessory::Accessors::BetwixtAccessor.new(...))
   end
 
+  # Alias for +#betwixt(0)+. See {#betwixt}
   def before_first
     self.betwixt(0)
   end
 
+  # Alias for +#betwixt(-1)+. See {#betwixt}
   def after_last
     self.betwixt(-1)
   end
 
+  # (see Accessory::Accessors::BetweenEachAccessor)
   def between_each
-    self.then(Accessory::BetweenEachAccessor.new)
+    self.then(Accessory::Accessors::BetweenEachAccessor.new)
   end
 
+  # (see Accessory::Accessors::AllAccessor)
   def all
-    self.then(Accessory::AllAccessor.new)
+    self.then(Accessory::Accessors::AllAccessor.new)
   end
 
+  # (see Accessory::Accessors::FirstAccessor)
   def first
-    self.then(Accessory::FirstAccessor.new)
+    self.then(Accessory::Accessors::FirstAccessor.new)
   end
 
+  # (see Accessory::Accessors::LastAccessor)
   def last
-    self.then(Accessory::LastAccessor.new)
+    self.then(Accessory::Accessors::LastAccessor.new)
   end
 
+  # (see Accessory::Accessors::FilterAccessor)
   def filter(&pred)
-    self.then(Accessory::FilterAccessor.new(pred))
+    self.then(Accessory::Accessors::FilterAccessor.new(pred))
   end
 end
 
@@ -102,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,14 +1,36 @@
 module Accessory; end
 
+##
+# 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}
+
 class Accessory::Accessor
-  DEFAULT_NOT_SET_SENTINEL = :"98e47971-e708-42ca-bee7-0c62fe5e11c9"
   TERMINAL_DEFAULT_FN = lambda{ nil }
+  private_constant :TERMINAL_DEFAULT_FN
 
-  def initialize(default: DEFAULT_NOT_SET_SENTINEL)
-    @default_value = default
-    @make_default_fn = TERMINAL_DEFAULT_FN
+  # @!visibility private
+  def initialize(default_value = nil)
+    @default_value = default_value
   end
 
+  # @!visibility private
   def name
     n = self.class.name.split('::').last.gsub(/Accessor$/, '')
     n.gsub!(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
@@ -18,6 +40,7 @@ class Accessory::Accessor
     n
   end
 
+  # @!visibility private
   def inspect(format: :long)
     case format
     when :long
@@ -30,7 +53,11 @@ class Accessory::Accessor
     end
   end
 
-  HIDDEN_IVARS = [:@default_value, :@make_default_fn]
+  # @!visibility private
+  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)
@@ -38,18 +65,152 @@ class Accessory::Accessor
     end.join(' ')
   end
 
-  attr_accessor :make_default_fn
+  # @!visibility private
+  attr_accessor :successor
 
-  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

@@ -1,12 +1,37 @@
 require 'accessory/accessor'
 
-class Accessory::AllAccessor < Accessory::Accessor
-  def default_fn_for_previous_step
-    lambda{ Array.new }
+##
+# Traverses all elements of an +Enumerable+.
+#
+# *Aliases*
+# * {Access.all}
+# * {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+}
+# * {https://hexdocs.pm/elixir/Access.html#key/2 +Access.key/2+}
+#
+# <b>Default constructor</b> used by predecessor accessor
+#
+# * +Array.new+
+
+class Accessory::Accessors::AllAccessor < Accessory::Accessor
+  # @!visibility private
+  def ensure_valid(traversal_result)
+    if traversal_result.kind_of?(Enumerable)
+      traversal_result
+    else
+      []
+    end
   end
 
+  # @!visibility private
   def inspect_args; nil; end
 
+  # Feeds each element of +data+ down the accessor chain, and returns
+  # the results.
+  # @param data [Enumerable] the +Enumerable+ to iterate through
+  # @return [Array] the values derived from the rest of the accessor chain
   def get(data, &succ)
     if succ
       (data || []).map(&succ)
@@ -15,6 +40,13 @@ class Accessory::AllAccessor < Accessory::Accessor
     end
   end
 
+  # Feeds each element of +data+ down the accessor chain, overwriting
+  # +data+ with the results.
+  #
+  # If +:pop+ is returned from the accessor chain, the element is dropped
+  # from the new +data+.
+  # @param data [Enumerable] the +Enumerable+ to iterate through
+  # @return [Array] a two-element array containing 1. the original values found during iteration; and 2. the new +data+
   def get_and_update(data)
     results = []
     new_data = []