accessory 0.1.2 → 0.1.7

data/lib/accessory/accessors/instance_variable_accessor.rb

@@ -1,8 +1,24 @@
 require 'accessory/accessor'
 
-class Accessory::InstanceVariableAccessor < Accessory::Accessor
-  def initialize(ivar_name, **kwargs)
-    super(**kwargs)
+##
+# 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 {Lens} and {BoundLens})
+#
+# <b>Default constructor</b> used by predecessor accessor
+#
+# * +Object.new+
+
+class Accessory::Accessors::InstanceVariableAccessor < Accessory::Accessor
+  # @param ivar_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,20 +27,27 @@ class Accessory::InstanceVariableAccessor < Accessory::Accessor
     @ivar_name = ivar_name
   end
 
+  # @!visibility private
   def inspect_args
     @ivar_name.to_s
   end
 
-  def default_fn_for_previous_step
-    lambda{ Object.new }
+  # @!visibility private
+  def ensure_valid(traversal_result)
+    traversal_result || Object.new
   end
 
-  def value_from(data)
+  # @!visibility private
+  def traverse(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)
+    value = traverse_or_default(data)
 
     if block_given?
       yield(value)
@@ -33,8 +56,18 @@ 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)
+    value = traverse_or_default(data)
 
     case yield(value)
     in [result, new_value]

data/lib/accessory/accessors/last_accessor.rb

@@ -1,18 +1,43 @@
 require 'accessory/accessor'
 
-class Accessory::LastAccessor < Accessory::Accessor
-  def default_fn_for_previous_step
-    lambda{ Array.new }
+##
+# 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 {Lens} and {BoundLens})
+#
+# <b>Default constructor</b> used by predecessor accessor
+#
+# * +Array.new+
+
+class Accessory::Accessors::LastAccessor < 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
 
-  def value_from(data)
+  # @!visibility private
+  def traverse(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)
+    value = traverse_or_default(data)
 
     if block_given?
       yield(value)
@@ -21,12 +46,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)
+    old_value = traverse_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,44 @@
 require 'accessory/accessor'
 
-class Accessory::SubscriptAccessor < 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 {Lens} and {BoundLens})
+# * {Access::FluentHelpers#[]} (included in {Lens} and {BoundLens})
+# * just passing a +key+ will also work, when +not(key.kind_of?(Accessor))+
+#   (this is a special case in {Lens#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::Accessors::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,20 +48,31 @@ class Accessory::SubscriptAccessor < Accessory::Accessor
     end
   end
 
+  # @!visibility private
   def inspect_args
     @key.inspect
   end
 
-  def default_fn_for_previous_step
-    lambda{ Hash.new }
+  # @!visibility private
+  def ensure_valid(traversal_result)
+    if traversal_result.respond_to?(:[])
+      traversal_result
+    else
+      {}
+    end
   end
 
-  def value_from(data)
+  # @!visibility private
+  def traverse(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)
+    value = traverse_or_default(data)
 
     if block_given?
       yield(value)
@@ -37,8 +81,15 @@ 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)
+    value = traverse_or_default(data)
 
     case yield(value)
     in [result, new_value]

data/lib/accessory/bound_lens.rb

@@ -0,0 +1,139 @@
+module Accessory; end
+
+require 'accessory/lens'
+
+##
+# A BoundLens represents a {Lens} bound to a specified subject document.
+# See {Lens} for the general theory.
+#
+# A BoundLens can be used to traverse its subject document, using {get_in},
+# {put_in}, {pop_in}, etc.
+#
+# Ordinarily, you don't create and hold onto a BoundLens, but rather you will
+# temporarily create Lenses in method-call chains when doing traversals.
+#
+# It may sometimes be useful to create a collection of Lenses and then "build
+# them up" by extending their {Lens}es over various collection-passes, rather
+# than building up {Lens}es and only binding them to subjects at the end.
+#
+# Lenses are created frozen. Methods that "extend" a BoundLens actually
+# create and return new derived Lenses.
+
+class Accessory::BoundLens
+
+  # Creates a BoundLens that will traverse +subject+.
+  #
+  # @overload on(subject, lens)
+  #   Creates a BoundLens that will traverse +subject+ along +lens+.
+  #
+  #   @param subject [Object] the data-structure this BoundLens will traverse
+  #   @param lens [Lens] the {Lens} that will be used to traverse +subject+
+  #
+  # @overload on(subject, *accessors)
+  #   Creates a BoundLens that will traverse +subject+ using a {Lens} built
+  #   from +accessors+.
+  #
+  #   @param subject [Object] the data-structure this BoundLens will traverse
+  #   @param accessors [Array] the accessors for the new {Lens}
+  def self.on(subject, *accessors)
+    lens =
+      if accessors.length == 1 && accessors[0].kind_of?(Lens)
+        accessors[0]
+      else
+        Accessory::Lens[*accessors]
+      end
+
+    self.new(subject, lens).freeze
+  end
+
+  class << self
+    private :new
+  end
+
+  # @!visibility private
+  def initialize(subject, lens)
+    @subject = subject
+    @lens = lens
+  end
+
+  # @return [Lens] the +subject+ this BoundLens will traverse
+  attr_reader :subject
+
+  # @return [Lens] the {Lens} for this BoundLens
+  attr_reader :lens
+
+  # @!visibility private
+  def inspect
+    "#<BoundLens on=#{@subject.inspect} #{@lens.inspect(format: :short)}>"
+  end
+
+  # Returns a new BoundLens resulting from appending +accessor+ to the
+  # receiver's {Lens}.
+  #
+  # === See also:
+  # * {Lens#then}
+  #
+  # @param accessor [Object] the accessor to append
+  # @return [Lens] the new BoundLens, containing a new joined Lens
+  def then(accessor)
+    d = self.dup
+    d.instance_eval do
+      @lens = @lens.then(accessor)
+    end
+    d.freeze
+  end
+
+  # Returns a new BoundLens resulting from concatenating +other+ to the
+  # receiver's {Lens}.
+  #
+  # === See also:
+  # * {Lens#+}
+  #
+  # @param other [Object] an accessor, an +Array+ of accessors, or a {Lens}
+  # @return [Lens] the new BoundLens, containing a new joined Lens
+  def +(other)
+    d = self.dup
+    d.instance_eval do
+      @lens = @lens + other
+    end
+    d.freeze
+  end
+
+  alias_method :/, :+
+
+  # (see Lens#get_in)
+  def get_in
+    @lens.get_in(@subject)
+  end
+
+  # (see Lens#get_and_update_in)
+  def get_and_update_in(&mutator_fn)
+    @lens.get_and_update_in(@subject, &mutator_fn)
+  end
+
+  # (see Lens#update_in)
+  def update_in(&new_value_fn)
+    @lens.update_in(@subject, &new_value_fn)
+  end
+
+  # (see Lens#put_in)
+  def put_in(new_value)
+    @lens.put_in(@subject, new_value)
+  end
+
+  # (see Lens#pop_in)
+  def pop_in
+    @lens.pop_in(@subject)
+  end
+end
+
+class Accessory::Lens
+  # Returns a new {BoundLens} wrapping this Lens, bound to the specified
+  # +subject+.
+  # @param subject [Object] the data-structure to traverse
+  # @return [BoundLens] a new BoundLens that will traverse +subject+ using
+  #   this Lens
+  def on(subject)
+    Accessory::BoundLens.on(subject, self)
+  end
+end

data/lib/accessory/lens.rb

@@ -1,68 +1,239 @@
 module Accessory; end
 
-require 'accessory/lens_path'
+require 'accessory/accessor'
+require 'accessory/accessors/subscript_accessor'
+
+##
+# A Lens is a "free-floating" lens (i.e. not bound to a subject document.)
+# It serves as a container for {Accessor} instances, and represents the
+# traversal path one would take to get from a hypothetical subject document,
+# to a data value nested somewhere within it.
+#
+# A Lens can be used directly to traverse documents, using {get_in},
+# {put_in}, {pop_in}, etc. These methods take an explicit subject document to
+# traverse, rather than requiring that the Lens be bound to a document
+# first.
+#
+# As such, a Lens is reusable. A common use of a Lens is to access the
+# same deeply-nested traversal position within a large collection of subject
+# documents, e.g.:
+#
+#    foo_bar_baz = Lens[:foo, :bar, :baz]
+#    docs.map{ |doc| foo_bar_baz.get_in(doc) }
+#
+# A Lens can also be bound to a specific subject document to create a
+# {BoundLens}. See {BoundLens.on}.
+#
+# Lenses are created frozen. Methods that "extend" a Lens actually create and
+# return new derived Lenses.
 
 class Accessory::Lens
-  def self.on(doc, path: nil)
-    self.new(doc, path || Accessory::LensPath.empty).freeze
+  # Returns the empty (identity) Lens.
+  # @return [Lens] the empty (identity) Lens.
+  def self.empty
+    @empty_lens ||= (new([]).freeze)
+  end
+
+  # Returns a {Lens} containing the specified +accessors+.
+  # @return [Lens] a Lens containing the specified +accessors+.
+  def self.[](*accessors)
+    new(accessors).freeze
   end
 
   class << self
     private :new
   end
 
-  def initialize(doc, lens_path)
-    @doc = doc
-    @path = lens_path
+  # @!visibility private
+  def initialize(initial_parts)
+    @parts = []
+
+    for part in initial_parts
+      append_accessor!(part)
+    end
+  end
+
+  # @!visibility private
+  def to_a
+    @parts
   end
 
-  attr_reader :path
+  # @!visibility private
+  def inspect(format: :long)
+    parts_desc = @parts.map{ |part| part.inspect(format: :short) }.join(', ')
+    parts_desc = "[#{parts_desc}]"
 
-  def inspect
-    "#<Lens on=#{@doc.inspect} #{@path.inspect(format: :short)}>"
+    case format
+    when :long
+      "#Lens#{parts_desc}"
+    when :short
+      parts_desc
+    end
   end
 
+  # Returns a new {Lens} resulting from appending +accessor+ to the receiver.
+  # @param accessor [Object] the accessor to append
+  # @return [Lens] the new joined Lens
   def then(accessor)
     d = self.dup
     d.instance_eval do
-      @path = @path.then(accessor)
+      @parts = @parts.dup
+      append_accessor!(accessor)
     end
     d.freeze
   end
 
-  def +(lens_path)
+  # Returns a new {Lens} resulting from concatenating +other+ to the end
+  # of the receiver.
+  # @param other [Object] an accessor, an +Array+ of accessors, or another Lens
+  # @return [Lens] the new joined Lens
+  def +(other)
+    parts =
+      case other
+      when Accessory::Lens
+        other.to_a
+      when Array
+        other
+      else
+        [other]
+      end
+
     d = self.dup
     d.instance_eval do
-      @path = @path + lens_path
+      for part in parts
+        append_accessor!(part)
+      end
     end
     d.freeze
   end
 
   alias_method :/, :+
 
-  def get_in
-    @path.get_in(@doc)
+  # Traverses +subject+ using the chain of accessors held in this Lens,
+  # 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?
+      subject
+    else
+      get_in_step(subject, @parts)
+    end
   end
 
-  def get_and_update_in(&mutator_fn)
-    @path.get_and_update_in(@doc, &mutator_fn)
+  # Traverses +subject+ using the chain of accessors held in this Lens,
+  # 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?
+      subject
+    else
+      get_and_update_in_step(subject, @parts, mutator_fn)
+    end
   end
 
-  def update_in(&new_value_fn)
-    @path.update_in(@doc, &new_value_fn)
+  # Traverses +subject+ using the chain of accessors held in this Lens,
+  # 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(new_value)
-    @path.put_in(@doc, new_value)
+  # Traverses +subject+ using the chain of accessors held in this Lens,
+  # 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
-    @path.pop_in(@doc)
+  # Traverses +subject+ using the chain of accessors held in this Lens,
+  # 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
-end
 
-class Accessory::LensPath
-  def on(doc)
-    Accessory::Lens.on(doc, path: self)
+  def append_accessor!(part)
+    accessor =
+      case part
+      when Accessory::Accessor
+        part
+      when Array
+        Accessory::Accessors::SubscriptAccessor.new(part[0], default: part[1])
+      else
+        Accessory::Accessors::SubscriptAccessor.new(part)
+      end
+
+    unless @parts.empty?
+      @parts.last.successor = accessor
+    end
+
+    @parts.push(accessor)
+  end
+  private :append_accessor!
+
+  def get_in_step(data, path)
+    step_accessor = path.first
+    rest_of_path = path[1..-1]
+
+    if rest_of_path.empty?
+      step_accessor.get(data)
+    else
+      step_accessor.get(data){ |v| get_in_step(v, rest_of_path) }
+    end
+  end
+  private :get_in_step
+
+  def get_and_update_in_step(data, path, mutator_fn)
+    step_accessor = path.first
+    rest_of_path = path[1..-1]
+
+    if rest_of_path.empty?
+      step_accessor.get_and_update(data, &mutator_fn)
+    else
+      step_accessor.get_and_update(data){ |v| get_and_update_in_step(v, rest_of_path, mutator_fn) }
+    end
   end
+  private :get_and_update_in_step
 end