accessory 0.1.1 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53b2b8b8fbe8103678c758221525a6a52d693dacd337cc3ee0c68c88e7b2c563
-  data.tar.gz: f38ef7a0bfdfb1470bbefb9c4b6692a100873d002dbdd1e38dd85e22884a228c
+  metadata.gz: 9880e7e5ea88c0b373a1cc3d5d4861788f368905c761b2ec3a7236d7282ada39
+  data.tar.gz: 7386d98dc728a663904564e0a6825de0d7690e806950e5e95d6e8b39d4d20cd6
 SHA512:
-  metadata.gz: 595c30b506f8c0547366660a33bdc9bea94bc3367bc4210ca54c3033061b12d2da8fc008e2fc1e642a4ad86b3445aa2fad84a2fb8a229d197f0d6d9e48238ed0
-  data.tar.gz: 96fafa2029446d184645b823e8398d5002e8d8487fbeb869442d37cd393b20ec8d7fae13ce9d71b7baec29cc56a551d02c86b7f9463bb3590d1024e456d1dba7
+  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)
+    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,89 +10,135 @@ 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::SubscriptAccessor)
+  def self.subscript(...)
+    Accessory::SubscriptAccessor.new(...)
+  end
+
+  # (see Accessory::AttributeAccessor)
+  def self.attr(...)
+    Accessory::AttributeAccessor.new(...)
   end
 
+  # (see Accessory::InstanceVariableAccessor)
   def self.ivar(...)
     Accessory::InstanceVariableAccessor.new(...)
   end
 
+  # (see Accessory::BetwixtAccessor)
   def self.betwixt(...)
     Accessory::BetwixtAccessor.new(...)
   end
 
+  # Alias for +Accessory::Access.betwixt(0)+. See {Access.betwixt}
   def self.before_first
     self.betwixt(0)
   end
 
+  # Alias for +Accessory::Access.betwixt(-1)+. See {Access.betwixt}
   def self.after_last
     self.betwixt(-1)
   end
 
+  # (see Accessory::BetweenEachAccessor)
   def self.between_each
     Accessory::BetweenEachAccessor.new
   end
 
+  # (see Accessory::AllAccessor)
   def self.all
     Accessory::AllAccessor.new
   end
 
+  # (see Accessory::FirstAccessor)
   def self.first
     Accessory::FirstAccessor.new
   end
 
+  # (see Accessory::LastAccessor)
   def self.last
     Accessory::LastAccessor.new
   end
 
+  # (see Accessory::FilterAccessor)
   def self.filter(&pred)
     Accessory::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)
+  def subscript(...)
+    self.then(Accessory::SubscriptAccessor.new(...))
+  end
+
+  # Alias for {#subscript}
   def [](...)
     self.then(Accessory::SubscriptAccessor.new(...))
   end
 
-  def field(...)
-    self.then(Accessory::FieldAccessor.new(...))
+  # (see Accessory::AttributeAccessor)
+  def attr(...)
+    self.then(Accessory::AttributeAccessor.new(...))
   end
 
+  # (see Accessory::InstanceVariableAccessor)
   def ivar(...)
     self.then(Accessory::InstanceVariableAccessor.new(...))
   end
 
+  # (see Accessory::BetwixtAccessor)
   def betwixt(...)
     self.then(Accessory::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::BetweenEachAccessor)
   def between_each
     self.then(Accessory::BetweenEachAccessor.new)
   end
 
+  # (see Accessory::AllAccessor)
   def all
     self.then(Accessory::AllAccessor.new)
   end
 
+  # (see Accessory::FirstAccessor)
   def first
     self.then(Accessory::FirstAccessor.new)
   end
 
+  # (see Accessory::LastAccessor)
   def last
     self.then(Accessory::LastAccessor.new)
   end
 
+  # (see Accessory::FilterAccessor)
   def filter(&pred)
     self.then(Accessory::FilterAccessor.new(pred))
   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#default_data_constructor}
+
 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.
+  #
+  # 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.
+  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

data/lib/accessory/accessors/all_accessor.rb

@@ -1,12 +1,37 @@
 require 'accessory/accessor'
 
+##
+# 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::AllAccessor < Accessory::Accessor
-  def default_fn_for_previous_step
-    lambda{ Array.new }
+  # @!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 = []