dottie 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a050415bffe078f5aa5be713416cfb686a9ec913
+  data.tar.gz: 6f9af95ef6a28fbd9a07ae1fdc3b519c9c4a77d9
+SHA512:
+  metadata.gz: 46a17f46eb85e0757d222f1e1c2e81ab6e1cccc4657d5e6f723a091edf69013c6553b0b3cfe8e37409bd0c43a46eef739a8f85a7ce4c3f5a2241dea843e9b744
+  data.tar.gz: 06f2654c46e34627a7de943f59c9f2209413a5f3306733a4e34ebdfdbfc7322f89e780610a34ee890893770c23652cc4697cb5390f0be58536eb9f18025b8ff2

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Nick Pearson
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,289 @@
+# Dottie
+
+Dottie lets you access a Hash or Array (possibly containing other Hashes and Arrays) using a dot-delimited string as the key. The string is parsed into individual keys, and Dottie traverses the data structure to find the target value. If at any point along the way a node is not found, Dottie will return `nil` rather than raising an error.
+
+A great place Dottie is useful is when accessing a data structure parsed from a JSON string, such as when consuming a JSON API. Since the only structural elements JSON can contain are objects and arrays, Dottie can easily access anything parsed from JSON.
+
+Here's a simple example showing a data structure as well as why Dottie is a nice way of accessing the values, especially when certain parts of the data are not guaranteed to be present:
+
+```ruby
+car = {
+  'color' => 'black',
+  'type' => {
+    'make' => 'Tesla',
+    'model' => 'Model S'
+  }
+}
+
+# normal Hash access
+car['color']            # => "black"
+car['type']['make']     # => "Tesla"
+car['specs']['mileage'] # => # undefined method `[]' for nil:NilClass
+
+# with Dottie
+d = Dottie(car)
+d['color']         # => "black"
+d['type.make']     # => "Tesla"
+d['specs.mileage'] # => nil
+```
+
+Here's another example showing a hash containing an array:
+
+```ruby
+family = {
+  'mom' => 'Alice',
+  'dad' => 'Bob',
+  'kids' => [
+    { 'name' => 'Carol' },
+    { 'name' => 'Dan' }
+  ]
+}
+
+# normal Hash/Array access
+family['kids'][0]['name'] # => "Carol"
+family['kids'][2]['name'] # => # undefined method `[]' for nil:NilClass
+family['pets'][0]['name'] # => # undefined method `[]' for nil:NilClass
+
+# with Dottie
+d = Dottie(family)
+d['kids[0].name'] # => "Carol"
+d['kids[2].name'] # => nil (array only has two elements)
+d['pets[0].name'] # => nil ('pets' does not exist)
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'dottie'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install dottie
+
+If you want the mixin behavior described below (where you can call `dottie` and `dottie!` on `Hash` and `Array` objects), require `'dottie/ext'` in your Gemfile:
+
+    gem 'dottie', require: 'dottie/ext'
+
+## Usage
+
+First, let's start with some examples of Dottie's behaviors. After that, we'll see how we can access those behaviors.
+
+```ruby
+# Since we have to start somewhere, here's one way of getting Dottie's
+# behaviors. See the usage options below for different ways of doing
+# this and to choose the best option for your app.
+data = Dottie({
+  'a' => { 'b' => 'c' }
+})
+
+# access data with normal keys or with Dottie-style keys
+data['a']   # => {"b"=>"c"}
+data['a.b'] # => "c"
+data.fetch('a.b') # => "c"
+data.has_key?('a.b') # => true
+
+# store a value in a nested Hash, then check the Hash
+data['a.b'] = 'd'
+data['a.b'] # => "d"
+data.hash # => {"a"=>{"b"=>"d"}}
+
+# store a value at a new key
+data['a.e'] = 'f'
+data.hash # => {"a"=>{"b"=>"d", "e"=>"f"}}
+
+# store a value deep in a Hash
+# (Dottie fills in the structure when necessary)
+h = Dottie({})
+h['a.b.c'] = 'd'
+h.hash # => {"a"=>{"b"=>{"c"=>"d"}}}
+
+# Dottie can also work with nested Arrays
+complex = Dottie({
+  'a' => [{ 'b' => 'c' }, { 'd' => 'e' }]
+})
+complex['a[1].d'] # => "e"
+
+# change the first array element value
+complex['a[first].b'] = 'x'
+complex.hash # => {"a"=>[{"b"=>"x"}, {"d"=>"e"}]}
+
+# add another array element
+complex['a[2]'] = 'y'
+complex.hash # => {"a"=>[{"b"=>"x"}, {"d"=>"e"}, "y"]}
+```
+
+### Dottie Usage Options
+
+There are three basic ways of using Dottie:
+
+1. By mixing Dottie's behavior into a `Hash`/`Array` (most versatile)
+2. As a wrapper around a Hash or Array (doesn't modify the `Hash`/`Array`)
+3. By calling Dottie's module methods directly (more verbose, good for one-off uses)
+
+Here are examples of each of these usage options:
+
+#### 1. Using Dottie as a Mixin
+
+This is the simplest usage. You must `require 'dottie/ext'` in order for the `dottie!` method to be added to `Hash` and `Array`. This can be done in your Gemfile as shown above.
+
+```ruby
+require 'dottie/ext' # not necessary if done in the Gemfile
+
+# create a hash and add Dottie's behavior to it
+hash = {
+  'a' => 'b',
+  'c' => {
+    'd' => 'e'
+  }
+}.dottie!
+
+# the hash is still a Hash
+hash.class # => Hash
+
+# and it still does normal lookups
+hash['a'] # => "b"
+
+# but it can also look up Dottie-style keys now
+hash['c.d'] # => "e"
+```
+
+The `Hash` and `Array` extensions are a nice but optional way to get convenient access to Dottie's behavior on built-in classes. To add Dottie's behavior to a `Hash` or `Array` without the use of the class extensions, you can extend the object with Dottie's methods. This is what the `dottie!` extension methods do internally.
+
+```ruby
+h = {
+  'a' => { 'b' => 'c' }
+}
+h.extend(Dottie::Methods)
+h['a.b'] # => "c"
+```
+
+#### 2. Using Dottie as a Wrapper
+
+This is the preferred method if you do not wish to modify the `Hash` or `Array` you're working with. In this case, your object will be wrapped in a `Dottie::Freckle`, which will more or less act like the original object. There are a few exceptions to this, such as when checking for equality. (For this, use `.hash` or `.array` to get access to the wrapped object.)
+
+To wrap an object, use `Dottie()` or `Dottie[]` (which are equivalent), or manually create a `Dottie::Freckle` instance. Or, if you have required `'dottie/ext'`, you can call `dottie` (not `dottie!`) on your object.
+
+```ruby
+# create a Hash
+hash = {
+  'a' => { 'b' => 'c' }
+}
+
+# then wrap the hash in a Dottie::Freckle with one of these (all equivalent)
+d_hash = Dottie(hash)
+d_hash = Dottie[Hash]
+d_hash = hash.dottie # only available if 'dottie/ext' has been required
+
+# regardless of how the Freckle was created, we can now access its data
+d_hash['a'] # => {"b"=>"c"} (a standard Hash lookup)
+d_hash['a.b'] # => "c" (a Dottie-style lookup)
+
+# works the same way with Arrays
+arr = ['a', { 'b' => 'c' }, 'd']
+d_arr = Dottie(arr) # or Dottie[arr] or arr.dottie
+d_arr['[1].b'] #=> "c"
+
+# or do it in one line
+d_hash = Dottie({ 'a' => 'b' })  # => <Dottie::Freckle {"a"=>"b"}>
+d_arr  = Dottie(['a', 'b', 'c']) # => <Dottie::Freckle ["a", "b", "c"]>
+
+# or, use the class extensions (must require 'dottie/ext')
+d_hash = { 'a' => 'b' }.dottie  # => <Dottie::Freckle {"a"=>"b"}>
+d_arr  = ['a', 'b', 'c'].dottie # => <Dottie::Freckle ["a", "b", "c"]>
+```
+
+#### 3. Using Dottie's Methods Directly
+
+This is an easy way to use Dottie's behaviors without modifying your objects and without wrapping them. For this, the syntax is more verbose, but if this suits you, here it is:
+
+```ruby
+# create a Hash
+hash = {
+  'a' => { 'b' => 'c' }
+}
+
+# perform a Dottie-style lookup
+Dottie.get(hash, 'a.b') # => "c"
+
+# perform a standard lookup to verify there's no Dottie behavior
+hash['a.b'] # => nil (there is no literal "a.b" key)
+
+# store a value, Dottie-style
+Dottie.set(hash, 'a.b', 'x')
+hash # => {"a"=>{"b"=>"x"}}
+
+# store a value, Hash-style
+hash['a.b'] = 'z'
+hash # => {"a"=>{"b"=>"x"}, "a.b"=>"z"} # stored literally as "a.b"
+
+# let's do another Dottie-style lookup on the modified hash
+Dottie.get(hash, 'a.b') # => "x"
+
+# and another standard lookup now that there's a literal "a.b" key
+hash['a.b'] # => "z"
+```
+
+### Traversing Arrays
+
+Array elements can be targeted with a bracketed index, which is a positive or negative integer or a `first` or `last` named index.
+
+```ruby
+me = Dottie({
+  'pets' => ['dog', 'cat', 'bird', 'fish']
+})
+me['pets[first]'] # => "dog"
+me['pets[1]']     # => "cat"
+me['pets[-2]']    # => "bird"
+me['pets[last]']  # => "fish"
+```
+
+### Dottie Key Format
+
+Dottie uses periods and brackets to delimit key parts. In general, hash keys are strings separated by periods, and array indexes are integers surrounded by brackets. For example, in the key `a.b[1]`, `a` and `b` are strings (hash keys) and `1` is a bracketed integer (an array index). Here's an example of how this key would be used:
+
+```ruby
+d = Dottie({
+  'a' => {
+    'b' => ['x', 'y', 'z']
+  }
+})
+d['a.b[1]'] # => "y"
+```
+
+For readability and convenience, `first` and `last`, when enclosed with brackets (such as `[first]`), are treated as named array indexes and are converted to `0` and `-1`, respectively.
+
+Besides `first` and `last`, any other non-integer string is handled like a normal, dot-delimited string. For example, the key `a[b].c` is equivalent to `a.b.c`.
+
+Brackets can also be used to quote key segments that contain periods. For example, `a[b.c].d` is interpreted internally as `['a', 'b.c', 'd']`. (If you need to see how a key will be interpreted, use `Dottie#key_parts` in an IRB session.)
+
+Dottie is forgiving in its key parsing. Periods are optional around brackets. For example, the key `a[1]b[2]c` is the same as `a.[1].b.[2].c`. Ruby-like syntax is preferred, where a period follows each closing bracket but does not preceed any opening brackets. The preferred key in this case is `a[1].b[2].c`.
+
+### What Dottie Doesn't Do
+
+When mixing Dottie into a `Hash` or `Array`, or when wrapping one in a `Dottie::Freckle` (which passes unrecognized method calls on to the wrapped object), Dottie provides `[]`, `[]=`, `fetch`, and `has_key?` methods, with the latter two assuming you're working with a `Hash`.
+
+By design, Dottie does not provide an implementation for `keys`, `each`, or other built-in `Hash` and `Array` methods where the expected behavior might be ambiguous. Dottie is meant to be an easy way to store and retrieve data in a JSON-like data structure (hashes and/or arrays nested within each other) and is not meant as a replacement for any core classes.
+
+## FAQ
+
+**Q:** Will Dottie make my life easier?  
+**A:** Probably.
+
+**Q:** Will Dottie brush my teeth for me?  
+**A:** Probably not.
+
+**Q:** Why is the wrapper class named `Freckle`?  
+**A:** Why not?
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,8 @@
+require 'rspec/core/rake_task'
+require 'bundler/gem_tasks'
+
+RSpec::Core::RakeTask.new(:spec) do |task|
+  task.rspec_opts = ['--color', '--format', 'nested']
+end
+
+task default: :spec

data/dottie.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'dottie/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "dottie"
+  spec.version       = Dottie::VERSION
+  spec.authors       = ["Nick Pearson"]
+  spec.email         = ["nick@banyantheory.com"]
+  spec.summary       = %q{Deep Hash and Array access with dotted keys}
+  spec.description   = %q{Deeply access nested Hash/Array data structures
+                          without checking for the existence of every node
+                          along the way.}
+  spec.homepage      = "https://github.com/nickpearson/dottie"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.5"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+end

data/lib/dottie.rb

@@ -0,0 +1,153 @@
+require 'dottie/methods'
+require 'dottie/freckle'
+require 'dottie/helper'
+require 'dottie/version'
+require 'strscan'
+
+module Dottie
+  
+  ##
+  # Creates a new Dottie::Freckle from a standard Ruby Hash or Array.
+  
+  def self.[](obj)
+    Dottie::Freckle.new(obj)
+  end
+  
+  ##
+  # Gets a value from an object. Does not assume the object has been extended
+  # with Dottie methods.
+  
+  def self.get(obj, key)
+    Dottie.key_parts(key).each do |k|
+      obj = case obj
+      when Hash, Array
+        obj[k]
+      else
+        nil
+      end
+    end
+    obj
+  end
+  
+  ##
+  # Sets a value in an object, creating missing nodes (Hashes and Arrays) as
+  # needed. Does not assume the object has been extended with Dottie methods.
+  
+  def self.set(obj, key, value)
+    key_parts = Dottie.key_parts(key)
+    key_parts.each_with_index do |k, i|
+      # set the value if this is the last key part
+      if i == key_parts.size - 1
+        case obj
+        when Hash, Array
+          obj[k] = value
+        else
+          raise TypeError.new("expected Hash or Array but got #{obj.class.name}")
+        end
+      # otherwise, walk down the tree, creating missing nodes along the way
+      else
+        obj = case obj
+        when Hash, Array
+          # look ahead at the next key to see if an array should be created
+          if key_parts[i + 1].is_a?(Integer)
+            obj[k] ||= []
+          else
+            obj[k] ||= {}
+          end
+        when nil
+          # look at the key to see if an array should be created
+          case k
+          when Integer
+            obj[k] = []
+          else
+            obj[k] = {}
+          end
+        else
+          raise TypeError.new("expected Hash, Array, or nil but got #{obj.class.name}")
+        end
+      end
+    end
+    # return the value that was set
+    value
+  end
+  
+  ##
+  # Checks whether a Hash or Array contains the last part of a Dottie-style key.
+  
+  def self.has_key?(obj, key)
+    key_parts = Dottie.key_parts(key)
+    key_parts.each_with_index do |k, i|
+      # look for the key if this is the last key part
+      if i == key_parts.size - 1
+        if obj.is_a?(Array) && k.is_a?(Integer)
+          return obj.size > k
+        elsif obj.is_a?(Hash)
+          return obj.has_key?(k)
+        else
+          return false
+        end
+      else
+        obj = case obj
+        when Hash, Array
+          obj[k]
+        else
+          return false
+        end
+      end
+    end
+  end
+  
+  ##
+  # Mimics the behavior of Hash#fetch, raising an error if a key does not exist
+  # and no default value or block is provided.
+  
+  def self.fetch(obj, key, default = :_fetch_default_)
+    if Dottie.has_key?(obj, key)
+      Dottie.get(obj, key)
+    elsif block_given?
+      yield(key)
+    elsif default != :_fetch_default_
+      default
+    else
+      raise KeyError.new(%{key not found: "#{key}"})
+    end
+  end
+  
+  ##
+  # Checks whether a key looks like a key Dottie understands.
+  
+  def self.dottie_key?(key)
+    !!(key.is_a?(String) && key =~ /[.\[]/) || key.is_a?(Array)
+  end
+  
+  ##
+  # Parses a Dottie key into an Array of strings and integers.
+  
+  def self.key_parts(key)
+    if key.is_a?(String)
+      parts = []
+      s = StringScanner.new(key)
+      loop do
+        if s.scan(/\./)
+          next
+        elsif (p = s.scan(/[^\[\].]+/))
+          parts << p
+        elsif (p = s.scan(/\[-?\d+\]/))
+          parts << p.scan(/-?\d+/).first.to_i
+        elsif (p = s.scan(/\[(first|last)\]/))
+          parts << (p[1..-2] == 'first' ? 0 : -1)
+        elsif (p = s.scan(/\[.+?\]/))
+          parts << p[1..-2] # remove '[' and ']'
+        else
+          break
+        end
+      end
+      parts
+    elsif key.is_a?(Array)
+      key
+    else
+      raise TypeError.new("expected String or Array but got #{key.class.name}")
+    end
+  end
+  
+end