accessory 0.1.2 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8065ca0c8cb368dc5a7e0a6f11b4d582a2448a0255590a6aa4ae557c62c321f
-  data.tar.gz: 2854d2fc74ffa690a95f0ad9db698497f037b2a7b74e4ceae9a380ba89796b7b
+  metadata.gz: 9f4517af7f1ae501a9dea6721f8dd0966a85c2fd9e8ada3d1d444f8b58cb297e
+  data.tar.gz: 4e8bcc0130b9cb5078779642cc0e81f4d4121ac6275ead2fe7a5decd873a5047
 SHA512:
-  metadata.gz: 274e4559b3d8e4a788b0f23c7831bfe5dbc1ada32dddb82a21ba0bcff9097ec7c04aa0d82af746e22f959dc7c336f2473c5ade8445f0035d704a64e218681e7a
-  data.tar.gz: 6320c7cc7a436ef043d6993d33b68ad56f4e1e30e0bd37b03b110d067f55ebc3c03aec7a4e14602d0c64d9bea15625069b5da34e9d8d13f5c4e92db8557c243c
+  metadata.gz: 295b43b1f100522c1dcc9e659acbcf174a9725c38448d68b8eb3be10603b9ad9df643f82dced994849616d194ccef080697febc3f934440b45420eae8229fa31
+  data.tar.gz: 5d9d93d0a17668ba39313dd8151cf7324a562df362fbbeb0a34bdc6c24b2dc7a8996f36f8e0b1be1c0d489dafc435f645e1b8a4348e3a080bdd66e9efe5dbc61

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

@@ -1,7 +1,7 @@
 module Accessory; end
 
 require 'accessory/accessors/subscript_accessor'
-require 'accessory/accessors/field_accessor'
+require 'accessory/accessors/attribute_accessor'
 require 'accessory/accessors/filter_accessor'
 require 'accessory/accessors/instance_variable_accessor'
 require 'accessory/accessors/betwixt_accessor'
@@ -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
-  def self.field(...)
-    Accessory::FieldAccessor.new(...)
+  # (see Accessory::Accessors::SubscriptAccessor)
+  def self.subscript(...)
+    Accessory::Accessors::SubscriptAccessor.new(...)
+  end
+
+  # (see Accessory::Accessors::AttributeAccessor)
+  def self.attr(...)
+    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
 
-  def field(...)
-    self.then(Accessory::FieldAccessor.new(...))
+  # (see Accessory::Accessors::AttributeAccessor)
+  def attr(...)
+    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,151 @@ 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
+  #   {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
+  #   {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
+  # {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 = []