accessory 0.1.4 → 0.1.9

data/lib/accessory/accessors/instance_variable_accessor.rb

@@ -8,14 +8,14 @@ require 'accessory/accessor'
 #
 # *Aliases*
 # * {Access.ivar}
-# * {Access::FluentHelpers#ivar} (included in {LensPath} and {Lens})
+# * {Access::FluentHelpers#ivar} (included in {Lens} and {BoundLens})
 #
 # <b>Default constructor</b> used by predecessor accessor
 #
 # * +Object.new+
 
-class Accessory::InstanceVariableAccessor < Accessory::Accessor
-  # @param attr_name [Symbol] the instance-variable name
+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)
@@ -33,12 +33,12 @@ class Accessory::InstanceVariableAccessor < Accessory::Accessor
   end
 
   # @!visibility private
-  def default_fn_for_previous_step
-    lambda{ Object.new }
+  def ensure_valid(traversal_result)
+    traversal_result || Object.new
   end
 
   # @!visibility private
-  def value_from(data)
+  def traverse(data)
     data.instance_variable_get(@ivar_name)
   end
 
@@ -47,7 +47,7 @@ class Accessory::InstanceVariableAccessor < Accessory::Accessor
   # @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)
@@ -67,15 +67,17 @@ class Accessory::InstanceVariableAccessor < Accessory::Accessor
   # @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]
+    in [:clean, result, _]
+      [:clean, result, data]
+    in [:dirty, result, new_value]
       data.instance_variable_set(@ivar_name, new_value)
-      [result, data]
+      [:dirty, result, data]
     in :pop
       data.remove_instance_variable(@ivar_name)
-      [value, data]
+      [:dirty, value, data]
     end
   end
 end

data/lib/accessory/accessors/last_accessor.rb

@@ -4,28 +4,32 @@ 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}.
+# This accessor can be preferable to {Accessors::SubscriptAccessor} for objects
+# that are not subscriptable, e.g. +Range+.
 #
 # *Aliases*
 # * {Access.last}
-# * {Access::FluentHelpers#last} (included in {LensPath} and {Lens})
+# * {Access::FluentHelpers#last} (included in {Lens} and {BoundLens})
 #
 # <b>Default constructor</b> used by predecessor accessor
 #
 # * +Array.new+
 
-class Accessory::LastAccessor < Accessory::Accessor
+class Accessory::Accessors::LastAccessor < Accessory::Accessor
   # @!visibility private
-  def default_fn_for_previous_step
-    lambda{ Array.new }
+  def ensure_valid(traversal_result)
+    if traversal_result.kind_of?(Enumerable)
+      traversal_result
+    else
+      []
+    end
   end
 
   # @!visibility private
   def inspect_args; nil; end
 
   # @!visibility private
-  def value_from(data)
+  def traverse(data)
     data.last
   end
 
@@ -33,7 +37,7 @@ class Accessory::LastAccessor < Accessory::Accessor
   # @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)
@@ -51,19 +55,21 @@ class Accessory::LastAccessor < Accessory::Accessor
   # @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]
+    in [:clean, result, _]
+      [:clean, result, data]
+    in [:dirty, result, new_value]
       if data.respond_to?(:"last=")
         data.last = new_value
       else
         data[-1] = new_value
       end
-      [result, data]
+      [:dirty, result, data]
     in :pop
       data.delete_at(-1)
-      [old_value, data]
+      [:dirty, old_value, data]
     end
   end
 end

data/lib/accessory/accessors/subscript_accessor.rb

@@ -7,9 +7,10 @@ require 'accessory/accessor'
 #
 # *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})
+# * {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+}
@@ -28,9 +29,9 @@ require 'accessory/accessor'
 #   # 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.
+# Other accessors ({Accessors::FirstAccessor}, {Accessors::BetwixtAccessor}, etc.) may fit your expectations more closely for +Array+ traversal.
 
-class Accessory::SubscriptAccessor < Accessory::Accessor
+class Accessory::Accessors::SubscriptAccessor < Accessory::Accessor
   # @!visibility private
   def initialize(key, **kwargs)
     super(**kwargs)
@@ -53,12 +54,16 @@ class Accessory::SubscriptAccessor < Accessory::Accessor
   end
 
   # @!visibility private
-  def default_fn_for_previous_step
-    lambda{ Hash.new }
+  def ensure_valid(traversal_result)
+    if traversal_result.respond_to?(:[])
+      traversal_result
+    else
+      {}
+    end
   end
 
   # @!visibility private
-  def value_from(data)
+  def traverse(data)
     data[@key]
   end
 
@@ -67,7 +72,7 @@ class Accessory::SubscriptAccessor < Accessory::Accessor
   # @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)
@@ -84,15 +89,17 @@ class Accessory::SubscriptAccessor < Accessory::Accessor
   # @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]
+    in [:clean, result, _]
+      [:clean, result, data]
+    in [:dirty, result, new_value]
       data[@key] = new_value
-      [result, data]
+      [:dirty, result, data]
     in :pop
       data.delete(@key)
-      [value, data]
+      [:dirty, value, data]
     end
   end
 end

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,13 +1,43 @@
 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
-  # 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
+  # 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
@@ -15,88 +45,204 @@ class Accessory::Lens
   end
 
   # @!visibility private
-  def initialize(subject, lens_path)
-    @subject = subject
-    @path = lens_path
-  end
+  def initialize(initial_parts)
+    @parts = []
 
-  # @return [LensPath] the +subject+ this Lens will traverse
-  attr_reader :subject
+    for part in initial_parts
+      append_accessor!(part)
+    end
+  end
 
-  # @return [LensPath] the {LensPath} for this Lens
-  attr_reader :path
+  # @!visibility private
+  def to_a
+    @parts
+  end
 
   # @!visibility private
-  def inspect
-    "#<Lens on=#{@subject.inspect} #{@path.inspect(format: :short)}>"
+  def inspect(format: :long)
+    parts_desc = @parts.map{ |part| part.inspect(format: :short) }.join(', ')
+    parts_desc = "[#{parts_desc}]"
+
+    case format
+    when :long
+      "#Lens#{parts_desc}"
+    when :short
+      parts_desc
+    end
   end
 
-  # Returns a new Lens resulting from appending +accessor+ to the receiver's
-  # {LensPath}.
-  #
-  # === See also:
-  # * {LensPath#then}
-  #
+  # Returns a new {Lens} resulting from appending +accessor+ to the receiver.
   # @param accessor [Object] the accessor to append
-  # @return [LensPath] the new Lens, containing a new joined LensPath
+  # @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
 
-  # 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
+  # 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 + other
+      for part in parts
+        append_accessor!(part)
+      end
     end
     d.freeze
   end
 
   alias_method :/, :+
 
-  # (see LensPath#get_in)
-  def get_in
-    @path.get_in(@subject)
+  # 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
 
-  # (see LensPath#get_and_update_in)
-  def get_and_update_in(&mutator_fn)
-    @path.get_and_update_in(@subject, &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
 
-  # (see LensPath#update_in)
-  def update_in(&new_value_fn)
-    @path.update_in(@subject, &new_value_fn)
-  end
+  # 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(subject) do |v|
+      case new_value_fn.call(v)
+      in [:set, new_value]
+        [:dirty, nil, new_value]
+      in :keep
+        [:clean, nil, v]
+      end
+    end
 
-  # (see LensPath#put_in)
-  def put_in(new_value)
-    @path.put_in(@subject, new_value)
+    new_data
   end
 
-  # (see LensPath#pop_in)
-  def pop_in
-    @path.pop_in(@subject)
+  # 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){ [:dirty, nil, new_value] }
+    new_data
   end
-end
 
-class Accessory::LensPath
-  # Returns a new {Lens} wrapping this LensPath, bound to the specified
-  # +subject+.
+  # 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 [Lens] a new Lens that will traverse +subject+ using this LensPath
-  def on(subject)
-    Accessory::Lens.on(subject, lens_path: self)
+  # @return [Object] the updated +subject+
+  def pop_in(subject)
+    _, popped_item, new_data = self.get_and_update_in(subject){ :pop }
+    [popped_item, new_data]
+  end
+
+  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