collapsium 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 15f88a96badb4dff1a23e1eac842de71b86e4b27
-  data.tar.gz: 1ad64e9ec74b0d125292d1424280d149389a4609
+  metadata.gz: 0565523a24719d83a3a81ec99005231cb86155df
+  data.tar.gz: eb817e05d8dec93788ecc51337579315a6719c70
 SHA512:
-  metadata.gz: a97d7feaf6c43dcd442c5342970563c7665d5d45c812284ebd24620db7a25ea5d6adf97fe73a8e16331b8587d214a4627be1c88f86021221d3fdfaa210192668
-  data.tar.gz: 3c8a5e286cd04e4d79957d94e3e22aef249c0be5352848f2f22b2061449637ad90f41ec1cff3d517b81d594fc83f1700332d0d7dd14801b08bf5878de87d3884
+  metadata.gz: c3e20a3f37be0496fd1ac6c6f653e845aaf57d7dd8b149347bddef882ac2ddf7b414b656370e65c49070fb8a638c4beb9ba139fc18bd485765f7fe695ea738da
+  data.tar.gz: 45ed48ecbc31111ac87689f7ffc84cdb5769d6a19bde8368e6cf5e0f60902af1c1753894d011f059b286e989db398f50e65984b8cd336e132a9a09b4b0197ca3

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    collapsium (0.3.0)
+    collapsium (0.4.0)
 
 GEM
   remote: https://rubygems.org/
@@ -11,7 +11,7 @@ GEM
       simplecov (>= 0.7.1, < 1.0.0)
     diff-lcs (1.2.5)
     docile (1.1.5)
-    json (2.0.1)
+    json (2.0.2)
     parser (2.3.1.2)
       ast (~> 2.2)
     powerpack (0.1.1)
@@ -21,7 +21,7 @@ GEM
       rspec-core (~> 3.5.0)
       rspec-expectations (~> 3.5.0)
       rspec-mocks (~> 3.5.0)
-    rspec-core (3.5.1)
+    rspec-core (3.5.2)
       rspec-support (~> 3.5.0)
     rspec-expectations (3.5.0)
       diff-lcs (>= 1.2.0, < 2.0)
@@ -30,7 +30,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.5.0)
     rspec-support (3.5.0)
-    rubocop (0.41.2)
+    rubocop (0.42.0)
       parser (>= 2.3.1.1, < 3.0)
       powerpack (~> 0.1)
       rainbow (>= 1.99.1, < 3.0)
@@ -43,7 +43,7 @@ GEM
       simplecov-html (~> 0.10.0)
     simplecov-html (0.10.0)
     unicode-display_width (1.1.0)
-    yard (0.9.0)
+    yard (0.9.5)
 
 PLATFORMS
   ruby
@@ -54,7 +54,7 @@ DEPENDENCIES
   collapsium!
   rake (~> 11.2)
   rspec (~> 3.5)
-  rubocop (~> 0.41)
+  rubocop (~> 0.42)
   simplecov (~> 0.12)
   yard (~> 0.9)
 

data/collapsium.gemspec

@@ -35,7 +35,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 2.0'
 
   spec.add_development_dependency "bundler", "~> 1.12"
-  spec.add_development_dependency "rubocop", "~> 0.41"
+  spec.add_development_dependency "rubocop", "~> 0.42"
   spec.add_development_dependency "rake", "~> 11.2"
   spec.add_development_dependency "rspec", "~> 3.5"
   spec.add_development_dependency "simplecov", "~> 0.12"

data/lib/collapsium.rb

@@ -9,8 +9,13 @@
 
 require 'collapsium/version'
 
-require 'collapsium/recursive_merge'
+require 'collapsium/environment_override'
 require 'collapsium/indifferent_access'
 require 'collapsium/pathed_access'
+require 'collapsium/prototype_match'
+require 'collapsium/recursive_dup'
+require 'collapsium/recursive_merge'
+require 'collapsium/recursive_sort'
+require 'collapsium/viral_capabilities'
 
 require 'collapsium/uber_hash'

data/lib/collapsium/environment_override.rb

@@ -0,0 +1,167 @@
+# coding: utf-8
+#
+# collapsium
+# https://github.com/jfinkhaeuser/collapsium
+#
+# Copyright (c) 2016 Jens Finkhaeuser and other collapsium contributors.
+# All rights reserved.
+#
+
+require 'collapsium/support/hash_methods'
+require 'collapsium/support/methods'
+
+require 'collapsium/viral_capabilities'
+
+module Collapsium
+
+  ##
+  # The EnvironmentOverride module wraps read access methods to return
+  # the contents of environment variables derived from the key instead of
+  # the value contained in the Hash.
+  #
+  # The environment variable to use is derived from the key by replacing
+  # all consecutive occurrences of non-alphanumeric characters with an
+  # underscore (_), and converting the alphabetic characters to upper case.
+  # Leading and trailing underscores will be stripped.
+  #
+  # For example, the key "some!@email.org" will become "SOME_EMAIL_ORG".
+  #
+  # If PathedAccess is also used, the :path_prefix of nested hashes will
+  # be consulted after converting it in the same manner.
+  module EnvironmentOverride
+    ##
+    # If the module is included, extended or prepended in a class, it'll
+    # wrap accessor methods.
+    class << self
+      include ::Collapsium::Support::HashMethods
+      include ::Collapsium::Support::Methods
+
+      ##
+      # Returns a proc read access.
+      ENV_ACCESS_READER = proc do |super_method, *args, &block|
+        # If there are no arguments, there's nothing to do with paths. Just
+        # delegate to the hash.
+        if args.empty?
+          next super_method.call(*args, &block)
+        end
+
+        # The method's receiver is encapsulated in the super_method; we'll
+        # use it a few times so let's reduce typing. This is essentially the
+        # equivalent of `self`.
+        receiver = super_method.receiver
+
+        # All KEYED_READ_METHODS have a key as the first argument.
+        key = args[0]
+
+        # Grab matching environment variable names. We consider first a pathed
+        # name, if pathed access is supported, followed by the unpathed name.
+        env_keys = [key.to_s]
+        if receiver.respond_to?(:path_prefix) and not
+            (receiver.path_prefix.nil? or receiver.path_prefix.empty?)
+          prefix_components = receiver.path_components(receiver.path_prefix)
+
+          if prefix_components.last == key
+            env_keys.unshift(receiver.path_prefix)
+          else
+            env_keys.unshift(receiver.path_prefix + receiver.separator + key.to_s)
+          end
+        end
+        env_keys.map! { |k| receiver.key_to_env(k) }
+        env_keys.select! { |k| not k.empty? }
+        env_keys.uniq!
+
+        # When we have the keys (in priority order), try to see if the
+        # environment yields something useful.
+        value = nil
+        env_keys.each do |env_key|
+          # Grab the environment value; skip if there's nothing there.
+          env_value = ENV[env_key]
+          if env_value.nil?
+            next
+          end
+
+          # If the environment variable parses as JSON, that's great, we'll use
+          # the parsed result. Otherwise use it as a string.
+          require 'json'
+          # rubocop:disable Lint/HandleExceptions
+          begin
+            env_value = JSON.parse(env_value)
+          rescue JSON::ParserError
+            # Do nothing. We just use the env_value verbatim.
+          end
+          # rubocop:enable Lint/HandleExceptions
+
+          # For the given key, retrieve the current value. We'll need it later.
+          # Note that we deliberately do not use any of KEYED_READ_METHODS,
+          # because that would recurse infinitely.
+          old_value = nil
+          receiver.each do |k, v|
+            if k == key
+              old_value = v
+              break
+            end
+          end
+
+          # Note that we re-assign the value only if it's changed, but we
+          # break either way. If env_value exists, it must be used, but
+          # changing it always will lead to an infinite recursion.
+          # The double's super_method will never be called, but rather
+          # always this wrapper.
+          if env_value != old_value
+            value = env_value
+          end
+          break
+        end
+        if not value.nil?
+          # We can't just return the value, because that doesn't respect the
+          # method being called. We can deal with this by duplicating the
+          # receiver, writing the value we found into the appropriate key,
+          # and then sending the super_method to the duplicate.
+          double = receiver.dup
+          double[key] = value
+          meth = double.method(super_method.name)
+          next meth.call(*args, &block)
+        end
+
+        # Otherwise, fall back on the super method.
+        next super_method.call(*args, &block)
+      end.freeze # proc
+
+      def included(base)
+        enhance(base)
+      end
+
+      def extended(base)
+        enhance(base)
+      end
+
+      def prepended(base)
+        enhance(base)
+      end
+
+      def enhance(base)
+        # Make the capabilities of classes using PathedAccess viral.
+        base.extend(ViralCapabilities)
+
+        # Wrap read accessor functions to deal with paths
+        KEYED_READ_METHODS.each do |method|
+          wrap_method(base, method, &ENV_ACCESS_READER)
+        end
+      end
+    end # class << self
+
+    def key_to_env(key)
+      # First, convert to upper case
+      env_key = key.upcase
+
+      # Next, replace non-alphanumeric characters to underscore. This also
+      # collapses them into a single undescore.
+      env_key.gsub!(/[^[:alnum:]]+/, '_')
+
+      # Strip leading and trailing underscores.
+      env_key.gsub!(/^_*(.*?)_*$/, '\1')
+
+      return env_key
+    end
+  end # module EnvironmentOverride
+end # module Collapsium

data/lib/collapsium/pathed_access.rb

@@ -7,6 +7,11 @@
 # All rights reserved.
 #
 
+require 'collapsium/support/hash_methods'
+require 'collapsium/support/methods'
+
+require 'collapsium/viral_capabilities'
+
 module Collapsium
 
   ##
@@ -28,17 +33,16 @@ module Collapsium
       return @separator
     end
 
-    # @api private
-    # Methods redefined to support pathed read access.
-    READ_METHODS = [
-      :[], :default, :delete, :fetch, :has_key?, :include?, :key?, :member?,
-    ].freeze
+    ##
+    # Assume any pathed access has this prefix.
+    def path_prefix=(value)
+      @path_prefix = normalize_path(value)
+    end
 
-    # @api private
-    # Methods redefined to support pathed write access.
-    WRITE_METHODS = [
-      :[]=, :store,
-    ].freeze
+    def path_prefix
+      @path_prefix ||= ''
+      return @path_prefix
+    end
 
     # @api private
     # Default path separator
@@ -50,95 +54,183 @@ module Collapsium
       /(?<!\\)#{Regexp.escape(separator)}/
     end
 
-    (READ_METHODS + WRITE_METHODS).each do |method|
-      # Wrap all accessor functions to deal with paths
-      define_method(method) do |*args, &block|
-        # If there are no arguments, there's nothing to do with paths. Just
-        # delegate to the hash.
-        if args.empty?
-          return super(*args, &block)
-        end
+    ##
+    # If the module is included, extended or prepended in a class, it'll
+    # wrap accessor methods.
+    class << self
+      include ::Collapsium::Support::HashMethods
+      include ::Collapsium::Support::Methods
+
+      ##
+      # Returns a proc for either read or write access. Procs for write
+      # access will create intermediary hashes when e.g. setting a value for
+      # `foo.bar.baz`, and the `bar` Hash doesn't exist yet.
+      def create_proc(write_access)
+        return proc do |super_method, *args, &block|
+          # If there are no arguments, there's nothing to do with paths. Just
+          # delegate to the hash.
+          if args.empty?
+            next super_method.call(*args, &block)
+          end
+
+          # The method's receiver is encapsulated in the super_method; we'll
+          # use it a few times so let's reduce typing. This is essentially the
+          # equivalent of `self`.
+          receiver = super_method.receiver
 
-        # With any of the dispatch methods, we know that the first argument has
-        # to be a key. We'll try to split it by the path separator.
-        components = args[0].to_s.split(split_pattern)
-        loop do
-          if components.empty? or not components[0].empty?
-            break
+          # With any of the dispatch methods, we know that the first argument has
+          # to be a key. We'll try to split it by the path separator.
+          components = receiver.path_components(args[0].to_s)
+
+          # If there are no components, return the receiver itself/the root
+          if components.empty?
+            next receiver
+          end
+
+          # Try to find the leaf, based on the given components.
+          leaf = recursive_fetch(components, receiver, [], create: write_access)
+
+          # The tricky part is what to do with the leaf.
+          meth = nil
+          if receiver.object_id == leaf.object_id
+            # a) if the leaf and the receiver are identical, then the receiver
+            #    itself was requested, and we really just need to delegate to its
+            #    super_method.
+            meth = super_method
+          else
+            # b) if the leaf is different from the receiver, we want to delegate
+            #    to the leaf.
+            meth = leaf.method(super_method.name)
           end
-          components.shift
+
+          # If the first argument was a symbol key, we want to use it verbatim.
+          # Otherwise we had pathed access, and only want to pass the last
+          # component to whatever method we're calling.
+          the_args = args
+          if not args[0].is_a?(Symbol)
+            the_args = args.dup
+            the_args[0] = components.last
+          end
+
+          # Then we can continue with that method.
+          next meth.call(*the_args, &block)
+        end # proc
+      end # create_proc
+
+      # Create a reader and write proc, because we only know
+      PATHED_ACCESS_READER = PathedAccess.create_proc(false).freeze
+      PATHED_ACCESS_WRITER = PathedAccess.create_proc(true).freeze
+
+      def included(base)
+        enhance(base)
+      end
+
+      def extended(base)
+        enhance(base)
+      end
+
+      def prepended(base)
+        enhance(base)
+      end
+
+      def enhance(base)
+        # Make the capabilities of classes using PathedAccess viral.
+        base.extend(ViralCapabilities)
+
+        # Wrap all accessor functions to deal with paths
+        KEYED_READ_METHODS.each do |method|
+          wrap_method(base, method, &PATHED_ACCESS_READER)
+        end
+        KEYED_WRITE_METHODS.each do |method|
+          wrap_method(base, method, &PATHED_ACCESS_WRITER)
         end
+      end
 
-        # If there are no components, return self/the root
-        if components.empty?
-          return self
+      ##
+      # Given the path components, recursively fetch any but the last key.
+      def recursive_fetch(path, data, current_path = [], options = {})
+        # Split path into head and tail; for the next iteration, we'll look use
+        # only head, and pass tail on recursively.
+        head = path[0]
+        current_path << head
+        tail = path.slice(1, path.length)
+
+        # We know that the data has the current path. We also know that thanks to
+        # virality, data will respond to :path_prefix. So we might as well set the
+        # path, as long as it is more specific than what was previously there.
+        current_normalized = data.normalize_path(current_path)
+        if current_normalized.length > data.path_prefix.length
+          data.path_prefix = current_normalized
         end
 
-        # This is already the leaf-most Hash
-        if components.length == 1
-          # Weird edge case: if we didn't have to shift anything, then it's
-          # possible we inadvertently changed a symbol key into a string key,
-          # which could mean looking fails.
-          # We can detect that by comparing copy[0] to a symbolized version of
-          # components[0].
-          copy = args.dup
-          if copy[0] != components[0].to_sym
-            copy[0] = components[0]
-          end
-          return super(*copy, &block)
+        # For the leaf element, we do nothing because that's where we want to
+        # dispatch to.
+        if path.length == 1
+          return data
         end
 
-        # Deal with other paths. The frustrating part here is that for nested
-        # hashes, only this outermost one is guaranteed to know anything about
-        # path splitting, so we'll have to recurse down to the leaf here.
-        #
-        # For write methods, we need to create intermediary hashes.
-        leaf = recursive_fetch(components, self,
-                               create: WRITE_METHODS.include?(method))
-        if leaf.is_a? Hash
-          leaf.default_proc = default_proc
+        # If we're a write function, then we need to create intermediary objects,
+        # i.e. what's at head if nothing is there.
+        if data[head].nil?
+          # If the head is nil, we can't recurse. In create mode that means we
+          # want to create hash children, but in read mode we're done recursing.
+          # By returning a hash here, we allow the caller to send methods on to
+          # this temporary, making a PathedAccess Hash act like any other Hash.
+          if not options[:create]
+            return {}
+          end
+
+          data[head] = {}
         end
 
-        # If we have a leaf, we want to send the requested method to that
-        # leaf.
-        copy = args.dup
-        copy[0] = components.last
-        return leaf.send(method, *copy, &block)
+        # Ok, recurse.
+        return recursive_fetch(tail, data[head], current_path, options)
       end
-    end
+    end # class << self
 
-    private
+    ##
+    # Break path into components. Expects a String path separated by the
+    # `#separator`, and returns the path split into components (an Array of
+    # String).
+    def path_components(path)
+      return filter_components(path.split(split_pattern))
+    end
 
     ##
-    # Given the path components, recursively fetch any but the last key.
-    def recursive_fetch(path, data, options = {})
-      # For the leaf element, we do nothing because that's where we want to
-      # dispatch to.
-      if path.length == 1
-        return data
-      end
+    # Given path components, filters out unnecessary ones.
+    def filter_components(components)
+      return components.select { |c| not c.nil? and not c.empty? }
+    end
 
-      # Split path into head and tail; for the next iteration, we'll look use only
-      # head, and pass tail on recursively.
-      head = path[0]
-      tail = path.slice(1, path.length)
-
-      # If we're a write function, then we need to create intermediary objects,
-      # i.e. what's at head if nothing is there.
-      if data[head].nil?
-        # If the head is nil, we can't recurse. In create mode that means we
-        # want to create hash children, but in read mode we're done recursing.
-        # By returning a hash here, we allow the caller to send methods on to
-        # this temporary, making a PathedAccess Hash act like any other Hash.
-        if not options[:create]
-          return {}
-        end
+    ##
+    # Join path components with the `#separator`.
+    def join_path(components)
+      return components.join(separator)
+    end
 
-        data[head] = {}
+    ##
+    # Normalizes a String path so that there are no empty components, and it
+    # starts with a separator.
+    def normalize_path(path)
+      components = []
+      if path.respond_to?(:split) # likely a String
+        components = path_components(path)
+      elsif path.respond_to?(:join) # likely an Array
+        components = filter_components(path)
       end
+      return separator + join_path(components)
+    end
 
-      # Ok, recurse.
-      return recursive_fetch(tail, data[head], options)
+    ##
+    # Ensure that all values have their path_prefix set.
+    def virality(value)
+      # If a value was set via a nested Hash, it may not have got its
+      # path_prefix set during storing (i.e. x[key] = { nested: some_hash }
+      # In that case, we do always know that the value's path prefix is the same
+      # as the receiver.
+      value.path_prefix = path_prefix
+      return value
     end
+
   end # module PathedAccess
 end # module Collapsium