accessory 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3276e22b0eb2ad764f2a1d742962c2b3c2e066f8949b5328c00d4bae0f08edf
-  data.tar.gz: c90330dc2daf7065405406e25b1feed10f3b224a822013af44e4645195d8d76d
+  metadata.gz: 1e6d18076731a0f1b3a28ce6ef77c75ef35dff6b7646f4880286b9bcf64ac393
+  data.tar.gz: '07918b78b0d0b1ae8097f22f36039a04fdefe9e59a10cae62758da84785fac4f'
 SHA512:
-  metadata.gz: 6a98028a9b9e2e1913c098a8858e4994c4793f8451ea6e15bfca2cb5dd54c1ae54b31a5320094632e329767a1ee3cf0baa5e84fc3571c3b104914cbeaf2ab767
-  data.tar.gz: b7b10ab902d4841090f1df7d5c770a16d02400f0d7b12761274928aefaca411f216c61f6a8436e7ee243fb20b45ff1feaa77fb22f9d2a16e1245c3506c61eb65
+  metadata.gz: ccdb07d177f3b436c91303585b921494d64aac6baa30abc32debf6ebc7ee4a6ff032b3db48f51d3c7b5d6498daeb7a298bcfd75840682bdc842e8fd70581bcf0
+  data.tar.gz: 2183b4b3513781e43b99490b4b86617ee8f08624c5c71a1355100fb84199bae2f27865d6b17496802c29c5571d39699e239b4dfc163983e789e618c39daf898d

data/lib/accessory/access.rb

@@ -11,88 +11,119 @@ require 'accessory/accessors/first_accessor'
 require 'accessory/accessors/last_accessor'
 
 module Accessory::Access
+  # (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
 
 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
 
+  # (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

data/lib/accessory/accessor.rb

@@ -1,14 +1,22 @@
 module Accessory; end
 
+##
+# @!visibility private
 class Accessory::Accessor
+
+  # @!visibility private
   DEFAULT_NOT_SET_SENTINEL = :"98e47971-e708-42ca-bee7-0c62fe5e11c9"
+
+  # @!visibility private
   TERMINAL_DEFAULT_FN = lambda{ nil }
 
-  def initialize(default: DEFAULT_NOT_SET_SENTINEL)
-    @default_value = default
+  # @!visibility private
+  def initialize(default = nil)
+    @default_value = default || DEFAULT_NOT_SET_SENTINEL
     @make_default_fn = TERMINAL_DEFAULT_FN
   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 +26,7 @@ class Accessory::Accessor
     n
   end
 
+  # @!visibility private
   def inspect(format: :long)
     case format
     when :long
@@ -30,6 +39,7 @@ class Accessory::Accessor
     end
   end
 
+  # @!visibility private
   HIDDEN_IVARS = [:@default_value, :@make_default_fn]
   def inspect_args
     (instance_variables - HIDDEN_IVARS).map do |ivar_k|
@@ -38,8 +48,10 @@ class Accessory::Accessor
     end.join(' ')
   end
 
+  # @!visibility private
   attr_accessor :make_default_fn
 
+  # @!visibility private
   def value_or_default(data)
     return nil if data.nil?
 

data/lib/accessory/accessors/all_accessor.rb

@@ -1,12 +1,33 @@
 require 'accessory/accessor'
 
+##
+# Traverses all elements of an +Enumerable+.
+#
+# *Aliases*
+# * {Access.all}
+# * {Access::FluentHelpers#all} (included in {LensPath} and {Lens})
+#
+# *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
+  # @!visibility private
   def default_fn_for_previous_step
     lambda{ Array.new }
   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 +36,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 = []

data/lib/accessory/accessors/attribute_accessor.rb

@@ -1,18 +1,42 @@
 require 'accessory/accessor'
 
+##
+# Traverses an abstract "attribute" of an arbitrary object, represented by a
+# named getter/setter method pair.
+#
+# For example, <tt>AttributeAccessor.new(:foo)</tt> will traverse through
+# 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.
+#
+# *Aliases*
+# * {Access.attr}
+# * {Access::FluentHelpers#attr} (included in {LensPath} and {Lens})
+#
+# <b>Default constructor</b> used by predecessor accessor
+#
+# * +OpenStruct.new+
+
 class Accessory::AttributeAccessor < Accessory::Accessor
-  def initialize(attr_name, **kwargs)
-    super(**kwargs)
+  # @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)
+    super(default)
     @getter_method_name = :"#{attr_name}"
     @setter_method_name = :"#{attr_name}="
   end
 
+  # @!visibility private
   def name; "attr"; end
 
+  # @!visibility private
   def inspect_args
     @getter_method_name.inspect
   end
 
+  # @!visibility private
   def inspect(format: :long)
     case format
     when :long
@@ -22,6 +46,7 @@ class Accessory::AttributeAccessor < Accessory::Accessor
     end
   end
 
+  # @!visibility private
   def default_fn_for_previous_step
     lambda do
       require 'ostruct'
@@ -29,10 +54,15 @@ class Accessory::AttributeAccessor < Accessory::Accessor
     end
   end
 
+  # @!visibility private
   def value_from(data)
     data.send(@getter_method_name)
   end
 
+  # Finds <tt>data.send(:"#{attr_name}")</tt>, feeds it down the accessor chain,
+  # and returns the result.
+  # @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)
 
@@ -43,6 +73,15 @@ class Accessory::AttributeAccessor < Accessory::Accessor
     end
   end
 
+  # Finds <tt>data.send(:"#{attr_name}")</tt>, feeds it down the accessor chain,
+  # and uses <tt>data.send(:"#{attr_name}=")</tt> to overwrite the stored value
+  # with the returned result.
+  #
+  # If +:pop+ is returned from the accessor chain, the stored value will be
+  # overwritten with `nil`.
+  #
+  # @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)
 

data/lib/accessory/accessors/between_each_accessor.rb

@@ -1,13 +1,31 @@
 require 'accessory/accessor'
 require 'accessory/array_cursor_position'
 
+##
+# Traverses the positions "between" the elements of an +Enumerable+, including
+# the positions at the "edges" (i.e. before the first, and after the last.)
+#
+# {BetweenEachAccessor} can be used with {LensPath#put_in} to insert new
+# elements into an Enumerable between the existing ones.
+#
+# *Aliases*
+# * {Access.between_each}
+# * {Access::FluentHelpers#between_each} (included in {LensPath} and {Lens})
+#
+# <b>Default constructor</b> used by predecessor accessor
+#
+# * +Array.new+
+
 class Accessory::BetweenEachAccessor < Accessory::Accessor
+  # @!visibility private
   def default_fn_for_previous_step
     lambda{ Array.new }
   end
 
+  # @!visibility private
   def inspect_args; nil; end
 
+  # @!visibility private
   def value_from(data)
     data_len = data.length
 
@@ -22,6 +40,11 @@ class Accessory::BetweenEachAccessor < Accessory::Accessor
     end
   end
 
+  # Feeds {ArrayCursorPosition}s representing the positions between the elements
+  # of +data+ down the accessor chain.
+  #
+  # @param data [Enumerable] the +Enumerable+ to iterate through
+  # @return [Array] the generated {ArrayCursorPosition}s
   def get(data)
     positions = value_or_default(data || [])
 
@@ -32,6 +55,16 @@ class Accessory::BetweenEachAccessor < Accessory::Accessor
     end
   end
 
+  # Feeds {ArrayCursorPosition}s representing the positions between the elements
+  # of +data+ down the accessor chain, manipulating +data+ using the results.
+  #
+  # If a new element is returned up the accessor chain, the element is inserted
+  # between the existing elements.
+  #
+  # If +:pop+ is returned up the accessor chain, no new element is added.
+  #
+  # @param data [Enumerable] the +Enumerable+ to iterate through
+  # @return [Array] a two-element array containing 1. the {ArrayCursorPosition}s; and 2. the new {data}
   def get_and_update(data)
     results = []
     new_data = []

data/lib/accessory/accessors/betwixt_accessor.rb

@@ -1,20 +1,50 @@
 require 'accessory/accessor'
 require 'accessory/array_cursor_position'
 
+##
+# Traverses into a specified cursor-position "between" two elements of an
+# +Enumerable+, including the positions at the "edges" (i.e. before the first,
+# or after the last.)
+#
+# If the provided +offset+ is positive, this accessor will traverse the position
+# between <tt>offset - 1</tt>  and +offset+; if +offset+ is negative, this accessor
+# will traverse the position _after_ +offset+.
+#
+# The +offset+ in this accessor has equivalent semantics to the offset in
+# <tt>Array#insert(offset, obj)</tt>.
+#
+# {BetwixtAccessor} can be used with {LensPath#put_in} to insert new
+# elements into an Enumerable between the existing ones. If you want to extend
+# an +Enumerable+ as you would with <tt>#push</tt> or <tt>#unshift</tt>, this
+# accessor will have better behavior than using {SubscriptAccessor} would.
+#
+# *Aliases*
+# * {Access.betwixt}
+# * {Access::FluentHelpers#betwixt} (included in {LensPath} and {Lens})
+#
+# <b>Default constructor</b> used by predecessor accessor
+#
+# * +Array.new+
+
 class Accessory::BetwixtAccessor < Accessory::Accessor
-  def initialize(offset, **kwargs)
-    super(**kwargs)
+  # @param offset [Integer] the cursor position (i.e. the index of the element after the cursor)
+  # @param default [Object] the default to use if the predecessor accessor passes +nil+ data
+  def initialize(offset, default: nil)
+    super(default)
     @offset = offset
   end
 
+  # @!visibility private
   def inspect_args
     @offset.inspect
   end
 
+  # @!visibility private
   def default_fn_for_previous_step
     lambda{ Array.new }
   end
 
+  # @!visibility private
   def value_from(data)
     data_len = data.length
 
@@ -27,6 +57,11 @@ class Accessory::BetwixtAccessor < Accessory::Accessor
     )
   end
 
+  # Feeds an {ArrayCursorPosition} representing the position between the
+  # elements of +data+ at +@offset+ down the accessor chain.
+  #
+  # @param data [Enumerable] the +Enumerable+ to traverse into
+  # @return [Array] the generated {ArrayCursorPosition}
   def get(data)
     pos = value_or_default(data || [])
 
@@ -37,6 +72,17 @@ class Accessory::BetwixtAccessor < Accessory::Accessor
     end
   end
 
+  # Feeds an {ArrayCursorPosition} representing the position between the
+  # elements of +data+ at +@offset+ down the accessor chain, manipulating
+  # +data+ using the result.
+  #
+  # If a new element is returned up the accessor chain, the element is inserted
+  # at the specified position, using <tt>data.insert(@offset, e)</tt>.
+  #
+  # If +:pop+ is returned up the accessor chain, no new element is added.
+  #
+  # @param data [Enumerable] the +Enumerable+ to traverse into
+  # @return [Array] a two-element array containing 1. the generated {ArrayCursorPosition}; and 2. the new {data}
   def get_and_update(data)
     pos = value_or_default(data || [])
 

data/lib/accessory/accessors/filter_accessor.rb

@@ -1,18 +1,47 @@
 require 'accessory/accessor'
 
+##
+# Traverses the elements of an +Enumerable+ that return a truthy value from
+# a passed-in predicate block.
+#
+# *Aliases*
+# * {Access.filter}
+# * {Access::FluentHelpers#filter} (included in {LensPath} and {Lens})
+#
+# *Equivalents* in Elixir's {https://hexdocs.pm/elixir/Access.html +Access+} module
+# * {https://hexdocs.pm/elixir/Access.html#filter/1 +Access.filter/1+}
+#
+# <b>Default constructor</b> used by predecessor accessor
+#
+# * +Array.new+
+
 class Accessory::FilterAccessor < Accessory::Accessor
-  def initialize(pred)
-    @pred = pred
+  # Returns a new instance of {FilterAccessor}.
+  #
+  # The predicate function may be passed in as either a positional argument,
+  # or a block.
+  #
+  # @param pred [Proc] The predicate function to use, as an object
+  # @param pred_blk [Proc] The predicate function to use, as a block
+  # @param default [Object] the default to use if the predecessor accessor passes +nil+ data
+  def initialize(pred = nil, default: nil, &pred_blk)
+    @pred = blk || pred
   end
 
+  # @!visibility private
   def inspect_args
     @pred.inspect
   end
 
+  # @!visibility private
   def default_fn_for_previous_step
     lambda{ Array.new }
   end
 
+  # Feeds each element of +data+ matching the predicate down the accessor chain,
+  # returning 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 || []).filter(&@pred).map(&succ)
@@ -21,6 +50,14 @@ class Accessory::FilterAccessor < Accessory::Accessor
     end
   end
 
+  # Feeds each element of +data+ matching the predicate 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 = []

data/lib/accessory/accessors/first_accessor.rb

@@ -1,16 +1,37 @@
 require 'accessory/accessor'
 
+##
+# Traverses into the "first" element within an +Enumerable+, using
+# <tt>#first</tt>.
+#
+# This accessor can be preferable to {SubscriptAccessor} for objects that
+# are not subscriptable, e.g. {Range}.
+#
+# *Aliases*
+# * {Access.first}
+# * {Access::FluentHelpers#first} (included in {LensPath} and {Lens})
+#
+# <b>Default constructor</b> used by predecessor accessor
+#
+# * +Array.new+
+
 class Accessory::FirstAccessor < Accessory::Accessor
+  # @!visibility private
   def default_fn_for_previous_step
     lambda{ Array.new }
   end
 
+  # @!visibility private
   def inspect_args; nil; end
 
+  # @!visibility private
   def value_from(data)
     data.first
   end
 
+  # Feeds <tt>data.first</tt> down the accessor chain, returning the result.
+  # @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)
 
@@ -21,12 +42,24 @@ class Accessory::FirstAccessor < Accessory::Accessor
     end
   end
 
+  # Finds <tt>data.first</tt>, feeds it down the accessor chain, and overwrites
+  # the stored value with the returned result.
+  #
+  # If +:pop+ is returned from the accessor chain, the stored value will be
+  # removed using <tt>data.delete_at(0)</tt>.
+  #
+  # @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)
     old_value = value_or_default(data)
 
     case yield(old_value)
     in [result, new_value]
-      data[0] = new_value
+      if data.respond_to?(:"first=")
+        data.first = new_value
+      else
+        data[0] = new_value
+      end
       [result, data]
     in :pop
       data.delete_at(0)

data/lib/accessory/accessors/instance_variable_accessor.rb

@@ -1,8 +1,24 @@
 require 'accessory/accessor'
 
+##
+# Traverses into a named instance-variable of an arbitrary object.
+#
+# For example, given <tt>InstanceVariableAccessor.new(:foo)</tt>, the
+# instance-variable <tt>@foo</tt> of the input data will be traversed.
+#
+# *Aliases*
+# * {Access.ivar}
+# * {Access::FluentHelpers#ivar} (included in {LensPath} and {Lens})
+#
+# <b>Default constructor</b> used by predecessor accessor
+#
+# * +Object.new+
+
 class Accessory::InstanceVariableAccessor < Accessory::Accessor
-  def initialize(ivar_name, **kwargs)
-    super(**kwargs)
+  # @param attr_name [Symbol] the instance-variable name
+  # @param default [Object] the default to use if the predecessor accessor passes +nil+ data
+  def initialize(ivar_name, default: nil)
+    super(default)
 
     ivar_name = ivar_name.to_s
     ivar_name = "@#{ivar_name}" unless ivar_name.to_s.start_with?("@")
@@ -11,18 +27,25 @@ class Accessory::InstanceVariableAccessor < Accessory::Accessor
     @ivar_name = ivar_name
   end
 
+  # @!visibility private
   def inspect_args
     @ivar_name.to_s
   end
 
+  # @!visibility private
   def default_fn_for_previous_step
     lambda{ Object.new }
   end
 
+  # @!visibility private
   def value_from(data)
     data.instance_variable_get(@ivar_name)
   end
 
+  # Finds <tt>data.instance_variable_get(:"@#{ivar_name}")</tt>, feeds it
+  # down the accessor chain, and returns the result.
+  # @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)
 
@@ -33,6 +56,16 @@ class Accessory::InstanceVariableAccessor < Accessory::Accessor
     end
   end
 
+  # Finds <tt>data.instance_variable_get(:"@#{ivar_name}")</tt>, feeds it down
+  # the accessor chain, and uses
+  # <tt>data.instance_variable_set(:"@#{ivar_name}")</tt> to overwrite the
+  # stored value with the returned result.
+  #
+  # If +:pop+ is returned from the accessor chain, the stored value will be
+  # removed using <tt>data.remove_instance_variable(:"@#{ivar_name}")</tt>.
+  #
+  # @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)
 

data/lib/accessory/accessors/last_accessor.rb

@@ -1,16 +1,37 @@
 require 'accessory/accessor'
 
+##
+# Traverses into the "last" element within an +Enumerable+, using
+# <tt>#last</tt>.
+#
+# This accessor can be preferable to {SubscriptAccessor} for objects that
+# are not subscriptable, e.g. {Range}.
+#
+# *Aliases*
+# * {Access.last}
+# * {Access::FluentHelpers#last} (included in {LensPath} and {Lens})
+#
+# <b>Default constructor</b> used by predecessor accessor
+#
+# * +Array.new+
+
 class Accessory::LastAccessor < Accessory::Accessor
+  # @!visibility private
   def default_fn_for_previous_step
     lambda{ Array.new }
   end
 
+  # @!visibility private
   def inspect_args; nil; end
 
+  # @!visibility private
   def value_from(data)
     data.last
   end
 
+  # Feeds <tt>data.last</tt> down the accessor chain, returning the result.
+  # @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)
 
@@ -21,12 +42,24 @@ class Accessory::LastAccessor < Accessory::Accessor
     end
   end
 
+  # Finds <tt>data.last</tt>, feeds it down the accessor chain, and overwrites
+  # the stored value with the returned result.
+  #
+  # If +:pop+ is returned from the accessor chain, the stored value will be
+  # removed using <tt>data.delete_at(-1)</tt>.
+  #
+  # @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)
     old_value = value_or_default(data)
 
     case yield(old_value)
     in [result, new_value]
-      data[-1] = new_value
+      if data.respond_to?(:"last=")
+        data.last = new_value
+      else
+        data[-1] = new_value
+      end
       [result, data]
     in :pop
       data.delete_at(-1)

data/lib/accessory/accessors/subscript_accessor.rb

@@ -1,11 +1,43 @@
 require 'accessory/accessor'
 
+##
+# Traverses into a specified +key+ for an arbitrary container-object which supports the +#[]+ and +#[]=+ methods.
+#
+# @param key [Object] the key to pass to the +#[]+ and +#[]=+ methods.
+#
+# *Aliases*
+# * {Access.subscript}
+# * {Access::FluentHelpers#subscript} (included in {LensPath} and {Lens})
+# * {Access::FluentHelpers#[]} (included in {LensPath} and {Lens})
+# * just passing a +key+ will also work, when +not(key.kind_of?(Accessor))+ (this is a special case in {LensPath#initialize})
+#
+# *Equivalents* in Elixir's {https://hexdocs.pm/elixir/Access.html +Access+} module
+# * {https://hexdocs.pm/elixir/Access.html#at/1 +Access.at/1+}
+# * {https://hexdocs.pm/elixir/Access.html#key/2 +Access.key/2+}
+#
+# <b>Default constructor</b> used by predecessor accessor
+#
+# * +Hash.new+
+#
+# == Usage Notes:
+# Subscripting into an +Array+ will *work*, but may not have the results you expect:
+#
+#   # extends the Array
+#   [].lens[3].put_in(1) # => [nil, nil, nil, 1]
+#
+#   # default-constructs a Hash, not an Array
+#   [].lens[0][0].put_in(1) # => [{0=>1}]
+#
+# Other accessors ({FirstAccessor}, {BetwixtAccessor}, etc.) may fit your expectations more closely for +Array+ traversal.
+
 class Accessory::SubscriptAccessor < Accessory::Accessor
+  # @!visibility private
   def initialize(key, **kwargs)
     super(**kwargs)
     @key = key
   end
 
+  # @!visibility private
   def inspect(format: :long)
     case format
     when :long
@@ -15,18 +47,25 @@ class Accessory::SubscriptAccessor < Accessory::Accessor
     end
   end
 
+  # @!visibility private
   def inspect_args
     @key.inspect
   end
 
+  # @!visibility private
   def default_fn_for_previous_step
     lambda{ Hash.new }
   end
 
+  # @!visibility private
   def value_from(data)
     data[@key]
   end
 
+  # Finds <tt>data[@key]</tt>, feeds it down the accessor chain, and returns
+  # the result.
+  # @param data [Enumerable] the +Enumerable+ to index into
+  # @return [Object] the value derived from the rest of the accessor chain
   def get(data)
     value = value_or_default(data)
 
@@ -37,6 +76,13 @@ class Accessory::SubscriptAccessor < Accessory::Accessor
     end
   end
 
+  # Finds <tt>data[@key]</tt>, feeds it down the accessor chain, and overwrites
+  # <tt>data[@key]</tt> with the returned result.
+  #
+  # If +:pop+ is returned from the accessor chain, the key is instead deleted
+  # from the {data} with <tt>data.delete(@key)</tt>.
+  # @param data [Enumerable] the +Enumerable+ to index into
+  # @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)
 

data/lib/accessory/array_cursor_position.rb

@@ -1,6 +1,12 @@
 module Accessory; end
 
+##
+# Represents a cursor-position "between" two positions in an +Array+ or other
+# integer-indexed +Enumerable+.
+
 class Accessory::ArrayCursorPosition
+  ##
+  # @!visibility private
   def initialize(offset, elem_before, elem_after, is_first: false, is_last: false)
     @offset = offset
     @elem_before = elem_before
@@ -9,10 +15,18 @@ class Accessory::ArrayCursorPosition
     @is_last = is_last
   end
 
+  # @return [Integer] the offset of +elem_after+ in the Enumerable
   attr_reader :offset
+
+  # @return [Object] the element before the cursor, if applicable
   attr_reader :elem_before
+
+  # @return [Object] the element after the cursor, if applicable
   attr_reader :elem_after
 
+  # @return [Object] true when {#elem_after} is the first element of the +Enumerable+
   def first?; @is_first; end
+
+  # @return [Object] true when {#elem_before} is the last element of the +Enumerable+
   def last?; @is_last; end
 end

data/lib/accessory/lens.rb

@@ -3,25 +3,42 @@ module Accessory; end
 require 'accessory/lens_path'
 
 class Accessory::Lens
-  def self.on(doc, path: nil)
-    self.new(doc, path || Accessory::LensPath.empty).freeze
+  # Creates a Lens that will traverse +subject+ along +lens_path+.
+  # @param subject [Object] the data-structure this Lens will traverse
+  # @param lens_path [LensPath] the {LensPath} that will be used to traverse +subject+
+  def self.on(subject, lens_path: Accessory::LensPath.empty)
+    self.new(subject, path).freeze
   end
 
   class << self
     private :new
   end
 
-  def initialize(doc, lens_path)
-    @doc = doc
+  # @!visibility private
+  def initialize(subject, lens_path)
+    @subject = subject
     @path = lens_path
   end
 
+  # @return [LensPath] the +subject+ this Lens will traverse
+  attr_reader :subject
+
+  # @return [LensPath] the {LensPath} for this Lens
   attr_reader :path
 
+  # @!visibility private
   def inspect
-    "#<Lens on=#{@doc.inspect} #{@path.inspect(format: :short)}>"
+    "#<Lens on=#{@subject.inspect} #{@path.inspect(format: :short)}>"
   end
 
+  # Returns a new Lens resulting from appending +accessor+ to the receiver's
+  # {LensPath}.
+  #
+  # === See also:
+  # * {LensPath#then}
+  #
+  # @param accessor [Object] the accessor to append
+  # @return [LensPath] the new Lens, containing a new joined LensPath
   def then(accessor)
     d = self.dup
     d.instance_eval do
@@ -30,39 +47,56 @@ class Accessory::Lens
     d.freeze
   end
 
-  def +(lens_path)
+  # Returns a new Lens resulting from concatenating +other+ to the receiver's
+  # {LensPath}.
+  #
+  # === See also:
+  # * {LensPath#+}
+  #
+  # @param other [Object] an accessor, an +Array+ of accessors, or a {LensPath}
+  # @return [LensPath] the new Lens, containing a new joined LensPath
+  def +(other)
     d = self.dup
     d.instance_eval do
-      @path = @path + lens_path
+      @path = @path + other
     end
     d.freeze
   end
 
   alias_method :/, :+
 
+  # (see LensPath#get_in)
   def get_in
-    @path.get_in(@doc)
+    @path.get_in(@subject)
   end
 
+  # (see LensPath#get_and_update_in)
   def get_and_update_in(&mutator_fn)
-    @path.get_and_update_in(@doc, &mutator_fn)
+    @path.get_and_update_in(@subject, &mutator_fn)
   end
 
+  # (see LensPath#update_in)
   def update_in(&new_value_fn)
-    @path.update_in(@doc, &new_value_fn)
+    @path.update_in(@subject, &new_value_fn)
   end
 
+  # (see LensPath#put_in)
   def put_in(new_value)
-    @path.put_in(@doc, new_value)
+    @path.put_in(@subject, new_value)
   end
 
+  # (see LensPath#pop_in)
   def pop_in
-    @path.pop_in(@doc)
+    @path.pop_in(@subject)
   end
 end
 
 class Accessory::LensPath
-  def on(doc)
-    Accessory::Lens.on(doc, path: self)
+  # Returns a new {Lens} wrapping this LensPath, bound to the specified
+  # +subject+.
+  # @param subject [Object] the data-structure to traverse
+  # @return [Lens] a new Lens that will traverse +subject+ using this LensPath
+  def on(subject)
+    Accessory::Lens.on(subject, lens_path: self)
   end
 end

data/lib/accessory/lens_path.rb

@@ -4,18 +4,23 @@ require 'accessory/accessor'
 require 'accessory/accessors/subscript_accessor'
 
 class Accessory::LensPath
+  # Returns the empty (identity) LensPath.
+  # @return [LensPath] the empty (identity) LensPath.
   def self.empty
     @empty_lens_path ||= (new([]).freeze)
   end
 
-  def self.[](*path)
-    new(path).freeze
+  # Returns a {LensPath} containing the specified +accessors+.
+  # @return [LensPath] a LensPath containing the specified +accessors+.
+  def self.[](*accessors)
+    new(accessors).freeze
   end
 
   class << self
     private :new
   end
 
+  # @!visibility private
   def initialize(initial_parts)
     @parts = []
 
@@ -24,10 +29,12 @@ class Accessory::LensPath
     end
   end
 
+  # @!visibility private
   def to_a
     @parts
   end
 
+  # @!visibility private
   def inspect(format: :long)
     parts_desc = @parts.map{ |part| part.inspect(format: :short) }.join(', ')
     parts_desc = "[#{parts_desc}]"
@@ -40,12 +47,16 @@ class Accessory::LensPath
     end
   end
 
+  # Returns a new {LensPath} resulting from appending +accessor+ to the receiver.
+  # @param accessor [Object] the accessor to append
+  # @return [LensPath] the new joined LensPath
   def then(accessor)
     d = self.dup
     d.append_accessor!(accessor)
     d.freeze
   end
 
+  # @!visibility private
   def dup
     d = super
     d.instance_eval do
@@ -54,15 +65,19 @@ class Accessory::LensPath
     d
   end
 
-  def +(lp_b)
+  # Returns a new {LensPath} resulting from concatenating +other+ to the end
+  # of the receiver.
+  # @param other [Object] an accessor, an +Array+ of accessors, or another LensPath
+  # @return [LensPath] the new joined LensPath
+  def +(other)
     parts =
-      case lp_b
+      case other
       when Accessory::LensPath
-        lp_b.to_a
+        other.to_a
       when Array
-        lp_b
+        other
       else
-        [lp_b]
+        [other]
       end
 
     d = self.dup
@@ -74,54 +89,108 @@ class Accessory::LensPath
 
   alias_method :/, :+
 
-  def append_accessor!(part)
-    accessor =
-      case part
-      when Accessory::Accessor
-        part
-      when Array
-        Accessory::SubscriptAccessor.new(part[0], default: part[1])
-      else
-        Accessory::SubscriptAccessor.new(part)
-      end
-
-    unless @parts.empty?
-      @parts.last.make_default_fn = accessor.default_fn_for_previous_step
-    end
-
-    @parts.push(accessor)
-  end
-
-  protected :append_accessor!
-
-  def get_in(doc)
+  # Traverses +subject+ using the chain of accessors held in this LensPath,
+  # returning the discovered value.
+  #
+  # *Equivalent* in Elixir:  {https://hexdocs.pm/elixir/Kernel.html#get_in/2 +Kernel.get_in/2+}
+  #
+  # @return [Object] the value found after all traversals.
+  def get_in(subject)
     if @parts.empty?
-      doc
+      subject
     else
-      get_in_step(doc, @parts)
+      get_in_step(subject, @parts)
     end
   end
 
-  def get_and_update_in(doc, &mutator_fn)
+  # Traverses +subject+ using the chain of accessors held in this LensPath,
+  # modifying the final value at the end of the traversal chain using
+  # the passed +mutator_fn+, and returning the original targeted value(s)
+  # pre-modification.
+  #
+  # +mutator_fn+ must return one of two data "shapes":
+  # * a two-element +Array+, representing:
+  #   1. the value to surface as the "get" value of the traversal
+  #   2. the new value to replace at the traversal-position
+  # * the Symbol +:pop+ — which will remove the value from its parent, and
+  #   return it as-is.
+  #
+  # *Equivalent* in Elixir: {https://hexdocs.pm/elixir/Kernel.html#get_and_update_in/3 +Kernel.get_and_update_in/3+}
+  #
+  # @param subject [Object] the data-structure to traverse
+  # @param mutator_fn [Proc] a block taking the original value derived from
+  #   traversing +subject+, and returning a modification operation.
+  # @return [Array] a two-element +Array+, consisting of
+  #   1. the _old_ value(s) found after all traversals, and
+  #   2. the updated +subject+
+  def get_and_update_in(subject, &mutator_fn)
     if @parts.empty?
-      doc
+      subject
     else
-      get_and_update_in_step(doc, @parts, mutator_fn)
+      get_and_update_in_step(subject, @parts, mutator_fn)
     end
   end
 
-  def update_in(data, &new_value_fn)
+  # Traverses +subject+ using the chain of accessors held in this LensPath,
+  # replacing the final value at the end of the traversal chain with the
+  # result from the passed +new_value_fn+.
+  #
+  # *Equivalent* in Elixir: {https://hexdocs.pm/elixir/Kernel.html#update_in/3 +Kernel.update_in/3+}
+  #
+  # @param subject [Object] the data-structure to traverse
+  # @param new_value_fn [Proc] a block taking the original value derived from
+  #   traversing +subject+, and returning a replacement value.
+  # @return [Array] a two-element +Array+, consisting of
+  #   1. the _old_ value(s) found after all traversals, and
+  #   2. the updated +subject+
+  def update_in(subject, &new_value_fn)
     _, new_data = self.get_and_update_in(data){ |v| [nil, new_value_fn.call(v)] }
     new_data
   end
 
-  def put_in(data, new_value)
-    _, new_data = self.get_and_update_in(data){ [nil, new_value] }
+  # Traverses +subject+ using the chain of accessors held in this LensPath,
+  # replacing the final value at the end of the traversal chain with
+  # +new_value+.
+  #
+  # *Equivalent* in Elixir: {https://hexdocs.pm/elixir/Kernel.html#put_in/3 +Kernel.put_in/3+}
+  #
+  # @param subject [Object] the data-structure to traverse
+  # @param new_value [Object] a replacement value at the traversal position.
+  # @return [Object] the updated +subject+
+  def put_in(subject, new_value)
+    _, new_data = self.get_and_update_in(subject){ [nil, new_value] }
     new_data
   end
 
-  def pop_in(data)
-    self.get_and_update_in(data){ :pop }
+  # Traverses +subject+ using the chain of accessors held in this LensPath,
+  # removing the final value at the end of the traversal chain from its position
+  # within its parent container.
+  #
+  # *Equivalent* in Elixir: {https://hexdocs.pm/elixir/Kernel.html#pop_in/2 +Kernel.pop_in/2+}
+  #
+  # @param subject [Object] the data-structure to traverse
+  # @return [Object] the updated +subject+
+  def pop_in(subject)
+    self.get_and_update_in(subject){ :pop }
+  end
+
+  protected
+  def append_accessor!(part)
+    accessor =
+      case part
+      when Accessory::Accessor
+        part
+      when Array
+        Accessory::SubscriptAccessor.new(part[0], default: part[1])
+      else
+        Accessory::SubscriptAccessor.new(part)
+      end
+
+    unless @parts.empty?
+      @parts.last.make_default_fn = accessor.default_fn_for_previous_step
+    end
+
+    @parts.push(accessor)
   end
 
   private

data/lib/accessory/version.rb

@@ -1,3 +1,3 @@
 module Accessory
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: accessory
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Levi Aul