bathysphere 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: cf41646c705b635a1110c58b0dee1f78b1aefc0a
+  data.tar.gz: 5ac3f636dc2358b1e0c1d08b25d00561a1eabfa0
+SHA512:
+  metadata.gz: 3aeb845bec1800bbe7d32fb10a72b7ccf12f3f4be264fab0ede971b3c01dd0de7e50f34e12b0937706c7a97d23cb8044e2d863e192b96c4301961e5ed678fdb1
+  data.tar.gz: 9024f28ac5f208c7dd244f1ed4a9734cbbae521c388cbf83174538f1958de2749cfcc5e1d46cd6f12939ca95d6db893a3857fa9775b9e5d4c031dcdaac36fbe7

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in bathysphere.gemspec
+gemspec
+

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2016, 2017 Redbubble
+
+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,254 @@
+Bathysphere
+===========
+
+[![Gem Version](https://badge.fury.io/rb/bathysphere.svg)](http://badge.fury.io/rb/bathysphere)
+[![Build Status](https://travis-ci.org/redbubble/bathysphere.svg?branch=master)](https://travis-ci.org/redbubble/bathysphere)
+[![Code Climate](https://codeclimate.com/github/redbubble/bathysphere.svg)](https://codeclimate.com/github/redbubble/bathysphere)
+[![Dependency Status](https://gemnasium.com/redbubble/bathysphere.svg)](https://gemnasium.com/redbubble/bathysphere)
+[![Inline docs](http://inch-ci.org/github/redbubble/bathysphere.svg?branch=master)](http://inch-ci.org/github/redbubble/bathysphere)
+
+Fetch arbitrarily deep properties from YAML files without loosing your breath.
+
+Bathysphere takes benefit of a self-describing YAML-based data format to
+normalize options fetching, so the same option can be stored at different
+depths in distinct configuration files.
+
+> **NOTICE**: Contributions to make Bathysphere amazing are highly encouraged! And at any moment, [feedback][issues] is welcome! : )
+
+  [intent]: doc/README.md
+  [issues]: https://github.com/redbubble/bathysphere/issues
+
+Installation
+------------
+
+Add the gem to your `Gemfile`:
+
+```ruby
+# Gemfile
+
+gem 'bathysphere', '~> 1.0' # see semver.org
+```
+
+  [gemfury]: https://gemfury.com
+
+Usage
+-----
+
+### Basics
+
+Define your configuration files. The `key` is the self-documenting part of the configuration file, and it defines how deep the `values` must be fetched:
+
+
+```yaml
+# config/products/fruit.yml
+
+---
+display_name:
+  key: 'size,color'
+  values:
+    small:
+      green: 'Grape'
+      orange: 'Kumquat'
+      purple: 'Blueberry'
+    medium:
+      green: 'Pear'
+      orange: 'Orange'
+      purple: 'Plum'
+    large:
+      green: 'Watermelon'
+      orange: 'Melon'
+      purple: 'Eggplant'
+```
+
+```yaml
+# config/product/vehicle.yml
+
+---
+display_name:
+  key: 'size'
+  values:
+    large: 'Train'
+    medium: 'Bus'
+    small: 'Bike'
+```
+
+Create a `Bathysphere::Parser` for each configuration file (note that you don't need to know how deep the values are defined):
+
+
+```ruby
+# app/models/product.rb
+
+require 'bathysphere'
+
+class Product
+
+  def self.configuration
+    @configuration ||= Bathysphere::Parser.new("config/products/#{name}.yml")
+  end
+
+  def configuration
+    self.class.configuration
+  end
+
+  def display_name
+    raise NotImplementedError
+  end
+end
+```
+
+The same `Bathysphere::Parser#fetch` method can be used to fetch all the `display_name` values, using exactly the required arguments:
+
+```ruby
+# app/models/fruit.rb
+
+class Fruit < Product
+
+  def initialize(size, color)
+    @size = size
+    @color = color
+  end
+
+  def display_name
+    configuration.fetch(:display_name, @size, @color)
+  end
+end
+```
+
+```ruby
+# app/models/vehicle.rb
+
+class Vehicle < Product
+
+  def initialize(size)
+    @size = size
+  end
+
+  def display_name
+    configuration.fetch(:display_name, @size)
+  end
+end
+```
+
+A nice and easy way to implement duck types for different kinds of products!
+
+
+```ruby
+# anywhere
+
+products = [
+  Fruit.new(:large, :purple),
+  Vehicle.new(:small),
+  Fruit.new(:small, :green),
+  Fruit.new(:small, :orange),
+  Vehicle.new(:large),
+]
+
+products.map(&display_name)
+# => ["Eggplant", "Bike", "Grape", "Kumquat", "Train"]
+```
+
+### Further automation
+
+Sometimes, defining the reader methods for the configurable properites is not practical. (Maybe your products are generated dynamically, or you want to keep the duck type obvious by keeping these readers in the `Product` class.)
+
+Optionally, the additional arguments to the `Parser#fetch` method can be retrieved automatically from any object provided to the `Parser#using` method:
+
+```ruby
+# app/models/product.rb
+
+require 'bathysphere'
+
+class Product
+
+  def self.configuration
+    @configuration ||= Bathysphere::Parser.new("config/products/#{name}.yml")
+  end
+
+  def configuration
+    self.class.configuration
+  end
+
+  def display_name
+    # Note that only :display_name was provided as an argument to Parser#fetch,
+    # the additional arguments will be retrieved by calling the corresponding
+    # reader methods on whatever object is provided to Parser#using, which in
+    # this case is the product instance.
+    configuration.using(self).fetch(:display_name)
+  end
+end
+```
+
+```ruby
+# app/models/fruit.rb
+
+class Fruit < Product
+
+  # These readers will be automatically called by Bathysphere::Parser#fetch
+  # to retrieve the Fruit#display_name - note that the parser is using(self)
+  attr_reader :color, :size
+
+  def initialize(size, color)
+    @size = size
+    @color = color
+  end
+end
+```
+
+```ruby
+# app/models/vehicle.rb
+
+class Vehicle < Product
+
+  # This reader will be automatically called by Bathysphere::Parser#fetch
+  # to retrieve the Vehicle#display_name - note that the parser is using(self)
+  attr_reader :size
+
+  def initialize(size)
+    @size = size
+  end
+end
+```
+
+Contributions
+-------------
+
+Contributions are welcome! Please feel free to open issues or pull requests to get help or discuss ideas or implementations. Note that opening pull requests with work in progress is not only welcome, but encouraged! Talk early, talk often, and we will all learn in the way :)
+
+Finally, please note that this project is released with a [Contributor Code of Conduct][coc]. By participating in this project you agree to abide by its terms.
+
+  [coc]: ./CODE_OF_CONDUCT.md
+
+Credits
+-------
+
+[![](doc/redbubble.png)][redbubble]
+
+Bathysphere is maintained and funded by [Redbubble][redbubble].
+
+  [redbubble]: https://www.redbubble.com
+
+License
+-------
+
+		Bathysphere
+		Copyright (C) 2016, 2017 Redbubble
+
+		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/Rakefile

@@ -0,0 +1,12 @@
+require "bundler/gem_tasks"
+require 'cucumber/rake/task'
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+Cucumber::Rake::Task.new(:features) do |t|
+  t.cucumber_opts = 'features --format pretty'
+end
+
+task default: [:features, :spec]
+

data/doc/README.md

@@ -0,0 +1,21 @@
+Intended API
+============
+
+This document is intended to allow discussing the Bathysphere API before it is implemented.
+
+Its contents will be moved to the gem [`README`][readme] when the corresponding features are implemented.
+
+  [readme]: ../README.md
+
+Installation
+------------
+
+Add the gem to your `Gemfile`:
+
+```ruby
+# Gemfile
+
+gem 'bathysphere', '~> 1,0' # see semver.org
+```
+
+_There are no other upcoming changes at the moment._

data/lib/bathysphere.rb

@@ -0,0 +1,4 @@
+require "bathysphere/parser"
+require "bathysphere/version"
+
+module Bathysphere; end

data/lib/bathysphere/parser.rb

@@ -0,0 +1,65 @@
+require 'yaml'
+
+module Bathysphere
+  class Parser
+
+    attr_reader :file, :refinements_store
+    private :file, :refinements_store
+
+    def initialize(file_path)
+      @file = file_path.downcase
+      @data = YAML.load_file(file)
+    end
+
+    # Set a refinements store
+    #
+    # When a refinements store is available, the #fetch
+    # method will attempt to retrieve the refinements by
+    # calling reader methods on the store instead of using
+    # additional refinement arguments.
+    #
+    # Returns self (i.e. is a chainable method).
+    def using(refinements_store)
+      @refinements_store = refinements_store
+      self
+    end
+
+    def fetch(option_name, *refinements)
+
+      option_value = @data.fetch(option_name.to_s) do
+        raise KeyError, "key not found #{option_name.to_s.inspect} in #{file}"
+      end
+
+      if option_value.kind_of?(Hash)
+        fetch_recursively(option_value, *refinements)
+      else
+        option_value
+      end
+    end
+
+    private
+
+      def fetch_recursively(option_value, *refinements)
+        keys(option_value).inject(values(option_value)) { |data, key|
+          refinement = refinements.shift.to_s
+          data.fetch(refinement) do
+            refinement = refinements_store.send(key).to_s
+            data.fetch(refinement) do
+              raise KeyError, "refinement not found #{refinement.inspect} in #{file}"
+            end
+          end
+        }
+      end
+
+      def keys(option_value)
+
+        option_value.fetch('key', '').split(',')
+      end
+
+      def values(option_value)
+        option_value.fetch('values') do
+          raise KeyError, "key not found \"values\" in #{file}"
+        end
+      end
+  end
+end

data/lib/bathysphere/version.rb

@@ -0,0 +1,3 @@
+module Bathysphere
+  VERSION = '1.0.0'.freeze
+end

data/spec/fixtures/deeply_nested_with_a_key_but_no_values.yml

@@ -0,0 +1,6 @@
+---
+display_name:
+  key: 'size'
+  large: 'kangaroo'
+  medium: 'wombat'
+  small: 'possum'

data/spec/fixtures/deeply_nested_with_no_key.yml

@@ -0,0 +1,6 @@
+---
+display_name:
+  values:
+    large: 'kangaroo'
+    medium: 'wombat'
+    small: 'possum'

data/spec/fixtures/fruit.yml

@@ -0,0 +1,16 @@
+---
+display_name:
+  key: 'size,color'
+  values:
+    small:
+      green: 'Grape'
+      orange: 'Kumquat'
+      purple: 'Blueberry'
+    medium:
+      green: 'Pear'
+      orange: 'Orange'
+      purple: 'Plum'
+    large:
+      green: 'Watermelon'
+      orange: 'Melon'
+      purple: 'Eggplant'

data/spec/fixtures/simple.yml

@@ -0,0 +1,2 @@
+---
+display_name: 'Mountain'

data/spec/lib/bathysphere/parser_spec.rb

@@ -0,0 +1,118 @@
+require 'spec_helper'
+
+module Bathysphere
+  describe Parser do
+
+    let(:file) { 'spec/fixtures/fruit.yml' }
+    let(:parser) { Parser.new(file) }
+
+    it { expect(parser).to respond_to :fetch }
+    it { expect(parser).to respond_to :using }
+
+    describe '#fetch' do
+
+      context 'when built from a valid YAML file' do
+
+        context 'with deeply nested properties' do
+
+          let(:file) { 'spec/fixtures/fruit.yml' }
+
+          context 'when the property is available' do
+
+            it 'returns its value' do
+              expect(parser.fetch(:display_name, :large, :purple)).to eq 'Eggplant'
+            end
+          end
+
+          context 'when the property is not available' do
+
+            it 'raises KeyError and mentions the parsed file in the message' do
+              expect{ parser.fetch(:weight, :large, :purple) }.to raise_error KeyError, Regexp.new(file)
+            end
+          end
+
+          context 'when a property of the path is not available' do
+
+            it 'raises KeyError and mentions the parsed file in the message' do
+              expect{ parser.fetch(:weight, :tiny, :purple) }.to raise_error KeyError, Regexp.new(file)
+            end
+          end
+        end
+
+        context 'with deeply nested values but no :key' do
+
+          let(:file) { 'spec/fixtures/deeply_nested_with_no_key.yml' }
+
+          it 'treats the nested hash as the property value' do
+            expect{ parser.fetch(:display_name, :large) }.not_to raise_error
+            expect(parser.fetch(:display_name, :large)).to eq({ 'large' => 'kangaroo', 'medium' => 'wombat', 'small' => 'possum' })
+          end
+        end
+
+        context 'with deeply nested properties, a :key but no :values' do
+
+          let(:file) { 'spec/fixtures/deeply_nested_with_a_key_but_no_values.yml' }
+
+          it 'raises KeyError and mentions the parsed file in the message' do
+            expect{ parser.fetch(:display_name, :large) }.to raise_error KeyError, Regexp.new(file)
+          end
+        end
+
+        context 'with no deeply nested properties' do
+
+          let(:file) { 'spec/fixtures/simple.yml' }
+
+          context 'when the property is available' do
+
+            it 'returns its value (as Hash#fetch does)' do
+              expect(parser.fetch(:display_name)).to eq 'Mountain'
+            end
+          end
+
+          context 'when the property is not available' do
+
+            it 'raises KeyError and mentions the parsed file in the message' do
+              expect{ parser.fetch(:weight) }.to raise_error KeyError, Regexp.new(file)
+            end
+          end
+        end
+      end
+    end
+
+    describe '#using' do
+
+      let(:refinements_store) { double }
+
+      it 'is chainable' do
+        expect(parser.using(refinements_store)).to be_instance_of Parser
+      end
+    end
+
+    context 'when both the :size and :color refinements are required' do
+
+      let(:file) { 'spec/fixtures/fruit.yml' }
+
+      context 'and #using(refinements_store)' do
+
+        let(:refinements_store) { double }
+        let(:parser) { Parser.new(file).using(refinements_store) }
+
+        context 'when the refinements_store implements the :size and :color readers' do
+
+          before(:each) do
+            allow(refinements_store).to receive(:size).and_return(:large)
+            allow(refinements_store).to receive(:color).and_return(:purple)
+          end
+
+          describe '#fetch' do
+
+            it 'returns the property value as expected with no need of custom refinements' do
+              expect(parser.fetch(:display_name)).to eq('Eggplant')
+            end
+
+          end
+        end
+      end
+    end
+  end
+end

data/spec/lib/bathysphere_spec.rb

@@ -0,0 +1,8 @@
+require 'spec_helper'
+
+describe Bathysphere do
+
+  it 'has a version number' do
+    expect(Bathysphere::VERSION).not_to be nil
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+require 'bathysphere'

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: bathysphere
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Redbubble
+- Gonzalo Bulnes Guilpain
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-01-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: aruba
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.14.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.14.0
+- !ruby/object:Gem::Dependency
+  name: cucumber
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '10.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '10.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '12'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Bathysphere takes benefit of a self-describing YAML-based data format
+  to normalize options fetching, so the same option can be stored at different depths
+  in distinct configuration files.
+email:
+- developers@redbubble.com
+- gonzalo.bulnes@redbubble.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- doc/README.md
+- doc/redbubble.png
+- lib/bathysphere.rb
+- lib/bathysphere/parser.rb
+- lib/bathysphere/version.rb
+- spec/fixtures/deeply_nested_with_a_key_but_no_values.yml
+- spec/fixtures/deeply_nested_with_no_key.yml
+- spec/fixtures/fruit.yml
+- spec/fixtures/simple.yml
+- spec/lib/bathysphere/parser_spec.rb
+- spec/lib/bathysphere_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/redbubble/bathysphere.git
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5.1
+signing_key: 
+specification_version: 4
+summary: Fetch arbitrarily deep properties from YAML files without loosing your breath.
+test_files:
+- spec/fixtures/deeply_nested_with_a_key_but_no_values.yml
+- spec/fixtures/deeply_nested_with_no_key.yml
+- spec/fixtures/fruit.yml
+- spec/fixtures/simple.yml
+- spec/lib/bathysphere/parser_spec.rb
+- spec/lib/bathysphere_spec.rb
+- spec/spec_helper.rb