sparsify 1.0.1 → 1.1.0

data/.travis.yml

@@ -0,0 +1,9 @@
+---
+language: ruby
+script: "bundle exec rspec"
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0
+  - jruby-19mode
+  - rbx

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## v1.1.0 (2015-06-04)
+
+ - Added Sparsify::expand(), which expands a subset of the given sparse hash (@yaauie)
+ - Fixed extraneous characters in documentation (@yaauie)
+ - Actually provided Sparsify#sparse_get to line up with documentation (@yaauie)
+
 ## v1.0.1 (2013-12-22)
 
  - Made Sparsify() and Unsparsify() helpers private methods on Kernel instead

data/Gemfile

@@ -1,5 +1,4 @@
 # encoding: utf-8
-source 'http://gems.production.int.simplymeasured.com:9292'
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in sparsify.gemspec

data/lib/sparsify.rb

@@ -3,6 +3,7 @@
 require 'sparsify/version'
 require 'sparsify/utility_methods'
 require 'sparsify/guard_methods'
+require 'sparsify/separator'
 require 'sparsify/core_ext/kernel'
 
 # Provides sparse-key access to a Hash.
@@ -39,7 +40,7 @@ module Sparsify
   # Used internally by both Sparsify::Utility#sparse and
   # Sparsify::Utility#unsparse
   #
-  # @overload sparse_eachrm (options = {}, &block)
+  # @overload sparse_each(options = {}, &block)
   #   Yields once per key in sparse version of itself.
   #   @param options (see #sparse)
   #   @yieldparam [(sparse_key,value)]
@@ -74,8 +75,8 @@ module Sparsify
   # @overload sparse_get(sparse_key, options = {})
   #   @param options (see #sparse)
   #   @return [Object] at that address or nil if none found
-  def sparse_fetch(*args, &block)
-    Sparsify.sparse_fetch(self, *args, &block)
+  def sparse_get(*args)
+    Sparsify.sparse_get(self, *args)
   end
 
   # Returns a deeply-nested hash version of self.

data/lib/sparsify/deprecations.rb

@@ -0,0 +1,28 @@
+# encoding: utf-8
+
+require 'set'
+
+module Sparsify
+  module Deprecations
+    class << self
+      def deprecate(message, target)
+        @deprecations ||= Set.new
+        msg = "Sparsify: #{message} is deprecated " +
+              "and will be removed in #{target} (at #{external_callpoint})"
+        warn(msg) if @deprecations.add?(msg)
+      end
+
+      private
+
+      def external_callpoint
+        caller.drop_while { |loc| loc['lib/sparsify/'] }.first
+      end
+    end
+
+    private
+
+    def deprecate(message, target)
+      Deprecations.deprecate(message, target)
+    end
+  end
+end

data/lib/sparsify/separator.rb

@@ -0,0 +1,75 @@
+# encoding: utf-8
+
+require 'sparsify/deprecations'
+
+module Sparsify
+  # Container for a separator and functionality for splitting &
+  # joining with proper escaping.
+  # @api private
+  class Separator
+    include Deprecations
+
+    @separators = {}
+
+    # Returns a memoized Separator object for the given separator_character
+    # Evicts a member at random if memoized pool grows beyond 100.
+    #
+    # @param separator_character [String] (see #initialize)
+    def self.[](separator_character)
+      @separators[separator_character] ||= begin
+        @separators.delete(@separators.keys.sample) if @separators.size > 100
+        new(separator_character)
+      end
+    end
+
+    # @param separator [String] single-character string
+    def initialize(separator)
+      unless separator.kind_of?(String) && separator.size > 0
+        fail ArgumentError, "separator must be a non-empty String " +
+                            "got #{separator.inspect}"
+      end
+      deprecate('multi-character separator', '2.0') unless separator.size == 1
+      @separator = separator
+    end
+
+    # Joins a pre-escaped string with a not-yet escaped string on our separator,
+    # escaping the new part before joining.
+    # @param pre_escaped_prefix [String]
+    # @param new_part [String] - will be escaped before joining
+    # @return [String]
+    def join(pre_escaped_prefix, new_part)
+      [pre_escaped_prefix, escape(new_part)].compact.join(@separator)
+    end
+
+    # Splits a string by our separator into non-escaped parts
+    # @param str [String]
+    # @return [Array<String>]
+    def split(str)
+      @unescaped_separator ||= /(?<!\\)(#{Regexp.escape(@separator)})/
+      # String#split(<Regexp>) on non zero-width matches yields the match
+      # as the even entries in the array.
+      parts = str.split(@unescaped_separator).each_slice(2).map(&:first)
+      parts.map do |part|
+        unescape(part)
+      end
+    end
+
+    private
+
+    # backslash-escapes our separator and backlashes in a string
+    # @param str [String]
+    # @return [String]
+    def escape(str)
+      @escape_pattern ||= /(\\|#{Regexp.escape(@separator)})/
+      str.gsub(@escape_pattern, '\\\\\1')
+    end
+
+    # removes backslash-escaping of our separator and backslashes from a string
+    # @param str [String]
+    # @return [String]
+    def unescape(str)
+      @unescape_pattern ||= /\\(\\|#{Regexp.escape(@separator)})/
+      str.gsub(@unescape_pattern, '\1')
+    end
+  end
+end

data/lib/sparsify/utility_methods.rb

@@ -128,49 +128,71 @@ module Sparsify
       sparse_fetch(hsh, sparse_key, options) { nil }
     end
 
-    private
+    # Given a sparse hash, unsparsify a subset by address, returning
+    # a *modified copy* of the original sparse hash.
+    #
+    # @overload expand(sparse_hsh, sparse_key, options = {}, &block)
+    #   @param sparse_hsh [Hash{String=>Object}]
+    #   @param sparse_key [String]
+    #   @param options (see Sparsify::UtilityMethods#sparse)
+    #   @return [Object]
+    #
+    # @example
+    # ~~~ ruby
+    # sparse = {'a.b' => 2, 'a.c.d' => 4, 'a.c.e' => 3, 'b.f' => 4}
+    # Sparsify::expand(sparse, 'a.c')
+    # # => {'a.b' => 2, 'a.c' => {'d' => 4, 'e' => 3}, 'b.f' => 4}
+    # ~~~
+    def expand(sparse_hsh, sparse_key, *args)
+      # if sparse_hsh includes our key, its value is already expanded.
+      return sparse_hsh if sparse_hsh.include?(sparse_key)
+
+      options = (args.last.kind_of?(Hash) ? args.pop : {})
+      separator = options.fetch(:separator, DEFAULT_SEPARATOR)
+      pattern = /\A#{Regexp.escape(sparse_key)}#{Regexp.escape(separator)}/i
+
+      match = {}
+      unmatch = {}
+      sparse_hsh.each do |k, v|
+        if pattern =~ k
+          sk = k.gsub(pattern, '')
+          match[sk] = v
+        else
+          unmatch[k] = v
+        end
+      end
 
-    # Utility method for backslash-escaping a string
-    # @param str [String]
-    # @param separator [String] single-character string
-    # @return [String]
-    def escape(str, separator)
-      pattern = /(\\|#{Regexp.escape(separator)})/
-      str.gsub(pattern, '\\\\\1')
+      unmatch.update(sparse_key => unsparse(match, options)) unless match.empty?
+      unmatch
     end
 
-    # Utility method for removing backslash-escaping from a string
-    # @param str [String]
-    # @param separator [String] single-character string
-    # @return [String]
-    def unescape(str, separator)
-      pattern = /\\(\\|#{Regexp.escape(separator)})/
-      str.gsub(pattern, '\1')
+    # Given a sparse hash, unsparsify a subset by address *in place*
+    # (@see Sparsify::UtilityMethods#expand)
+    def expand!(sparse_hsh, *args)
+      sparse_hsh.replace expand(sparse_hsh, *args)
     end
 
+    private
+
     # Utility method for splitting a string by a separator into
     # non-escaped parts
+    # @api private
     # @param str [String]
     # @param separator [String] single-character string
     # @return [Array<String>]
     def escaped_split(str, separator)
-      unescaped_separator = /(?<!\\)(#{Regexp.escape(separator)})/
-      # String#split(<Regexp>) on non zero-width matches yields the match
-      # as the even entries in the array.
-      parts = str.split(unescaped_separator).each_slice(2).map(&:first)
-      parts.map do |part|
-        unescape(part, separator)
-      end
+      Separator[separator].split(str)
     end
 
     # Utility method for joining a pre-escaped string with a not-yet escaped
     # string on a given separator, escaping the new part before joining.
+    # @api private
     # @param pre_escaped_prefix [String]
     # @param new_part [String] - will be escaped before joining
     # @param separator [String] single-character string
     # @return [String]
     def escaped_join(pre_escaped_prefix, new_part, separator)
-      [pre_escaped_prefix, escape(new_part, separator)].compact.join(separator)
+      Separator[separator].join(pre_escaped_prefix, new_part)
     end
   end
 

data/lib/sparsify/version.rb

@@ -1,4 +1,4 @@
 # encoding: utf-8
 module Sparsify
-  VERSION = '1.0.1'
+  VERSION = '1.1.0'
 end

data/spec/sparsify_spec.rb

@@ -50,6 +50,11 @@ describe 'Sparsify' do
       end
       it { should eq nested_hash }
     end
+    context 'deprecated multi-character separators (remove in 2.0)' do
+      it 'only escapes the first character in the separator'
+      it 'round-trips ok'
+      it 'warns appropriately'
+    end
   end
 
   context 'sparse_array' do
@@ -194,4 +199,51 @@ describe 'Sparsify' do
       end
     end
   end
+
+  shared_examples_for('.expand') do
+    let(:source_sparse_hash) do
+      {
+        'foo.bar.baz' => 'bingo',
+        'foo.bar.whee' => {},
+        'asdf' => 'qwer',
+      }
+    end
+    let(:sparse_key) { 'foo.bar' }
+    let(:expander) { proc { Sparsify.send(method, source_sparse_hash, sparse_key) } }
+    let(:the_result) { expander.call }
+
+    it 'expands the item at the address' do
+      expect(the_result).to eq({'foo.bar' => {'baz'=>'bingo', 'whee'=> {}},'asdf'=>'qwer'})
+    end
+    context 'when no item exists at the address' do
+      let(:sparse_key) { 'qwer' }
+      it 'is a no-op' do
+        expect(the_result).to eq(source_sparse_hash)
+      end
+    end
+    context 'when an object exists at the address exactly' do
+      let(:sparse_key) { 'foo.bar.baz' }
+      it 'is a no-op' do
+        expect(the_result).to eq(source_sparse_hash)
+      end
+    end
+  end
+
+  context '.expand' do
+    let(:method) { :expand }
+    include_examples('.expand') do
+      it 'does not modify the original' do
+        expect(the_result).to_not equal(source_sparse_hash)
+      end
+    end
+  end
+
+  context '.expand!' do
+    let(:method) { :expand! }
+    include_examples('.expand') do
+      it 'modifies the original' do
+        expect(the_result).to equal(source_sparse_hash)
+      end
+    end
+  end
 end

metadata

@@ -1,18 +1,20 @@
 --- !ruby/object:Gem::Specification
 name: sparsify
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
+  prerelease: 
 platform: ruby
 authors:
 - Ryan Biesemeyer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-08 00:00:00.000000000 Z
+date: 2015-06-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -20,6 +22,7 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -27,6 +30,7 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -34,6 +38,7 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -41,6 +46,7 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -48,6 +54,7 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -55,6 +62,7 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-appraiser-rubocop
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -62,6 +70,7 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -74,6 +83,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .travis.yml
 - CHANGELOG.md
 - CONTRIBUTING.md
 - Gemfile
@@ -83,7 +93,9 @@ files:
 - git_hooks/pre-commit/ruby-appraiser
 - lib/sparsify.rb
 - lib/sparsify/core_ext/kernel.rb
+- lib/sparsify/deprecations.rb
 - lib/sparsify/guard_methods.rb
+- lib/sparsify/separator.rb
 - lib/sparsify/utility_methods.rb
 - lib/sparsify/version.rb
 - sparsify.gemspec
@@ -91,27 +103,27 @@ files:
 homepage: https://www.github.com/simplymeasured/sparsify
 licenses:
 - Apache 2
-metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 1.8.23
 signing_key: 
-specification_version: 4
+specification_version: 3
 summary: Flattens deeply-nested hashes into sparse hashes
 test_files:
 - spec/sparsify_spec.rb
-has_rdoc: 

checksums.yaml

@@ -1,15 +0,0 @@
----
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    ZjU2OWYwNjg0ZGU2NDhmMTQ1NDY5MGExYWFhNmM4ZjQzMjU5OWMyOQ==
-  data.tar.gz: !binary |-
-    YzFiMmYzYzU2ODdjYTFiZmE4ODkzYmM1MWVhMTVmZmZhNDhjOGY2OQ==
-SHA512:
-  metadata.gz: !binary |-
-    N2JiMDE4MTE1ZDliN2JiMTVkMDJhMzg0Yzg5MDJjZDk4ZmI3ODEyNGRlZjQ1
-    MDM5MjU5NGE5YjZjNDI3OGRhOGFiNjVhMWUyYTFiNjM3MWU2ODIxOThmM2Jj
-    M2ZlMDViYjE4OThmNjBkZmI3M2NkN2U3ZjY0NWQzMTAyMzQwNDY=
-  data.tar.gz: !binary |-
-    YTgyOGIyY2ZjNTdhZjU0YWQ1NzA5OGQwMzJiZDFiZmYwN2QyMjI4Njc4MGMx
-    MGIxYWIxMzhiYzhmNzc3NzZhZjdmYTk3N2I4N2RhMWMxYjE1ODM2MjNhOWE5
-    ODk4ZmYzNDE5NTU3MDViOTNlMTFkYTNkOWFiMmVhOTRmMzUxY2Y=