symbolmatrix 0.0.1

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/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - jruby-18mode
+  - jruby-19mode
+  - rbx-18mode
+  - rbx-19mode
+  - ree

data/Gemfile

@@ -0,0 +1,9 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in symbolmatrix.gemspec
+gemspec
+
+# Travis CI me lo pide
+group :test do
+  gem "rake"
+end

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Fernando Via
+
+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,111 @@
+SymbolMatrix
+============
+
+[![Build Status](https://secure.travis-ci.org/Fetcher/symbolmatrix.png)](http://travis-ci.org/Fetcher/symbolmatrix) [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/Fetcher/symbolmatrix)
+
+> Strongly inspired in [SymbolTable][symboltable] gem by [Michael Jackson][michael-jackson-home] (thanks a lot!)
+
+**SymbolMatrix** is a simple Ruby Gem that extends `Hash` so that only `Symbol`s can be used as keys. Why? Because it also allows you to query the SymbolMatrix object using the dot syntax and a string key equivalent to the symbol one, making it more Principle of Least Surprise.
+
+The showdown:
+
+```ruby
+h = Hash.new
+h[:a] = 1
+h[:a]       # => 1
+h['a']      # => nil
+h.a         # => NoMethodError: undefined method `a' for {}:Hash
+
+require 'symbolmatrix'
+
+m = SymbolMatrix.new
+m[:a] = 1
+m[:a]       # => 1
+m['a']      # => 1
+m.a         # => 1
+```
+
+If you are familiar with SymbolTable you may have noticed that, so far, the same functionality is provided in the original gem. SymbolMatrix adds two key features:
+
+1.  **Recursive convertion to SymbolMatrix**
+
+    ```ruby
+    require "symbolmatrix"
+    
+    m = SymbolMatrix.new :quantum => { :nano => "data" }
+
+    m.quatum.nano # => "data"
+    ```
+
+2.  **YAML autoloading**
+    
+    ```ruby
+    require "symbolmatrix"
+    
+    m = SymbolMatrix.new "quantum: of solace"
+    m.quantum   # => "of solace"
+    
+    # Or alternatively
+    m.from_yaml "quantum: of solace"
+    
+    # Provided a file exists "configuration.yaml" with "database_uri: mysql://root@localhost/database"
+    m.from_file "configuration.yaml"
+    m.database_uri  # => "mysql://root@localhost/database"
+    
+    # Or simply
+    m = SymbolMatrix.new "configuration.yaml"
+    ```
+
+[symboltable]: https://github.com/mjijackson/symboltable
+[michael-jackson-home]: http://mjijackson.com/
+
+Further details
+---------------
+
+### Recursive `#to_hash` convertion
+
+SymbolMatrix provides the `#to_hash` method that recursively transforms the matrix into a n-dimentional Hash.
+
+### Disabling the YAML discovery
+
+If for some reason you don't want this class to use YAML, you can just require `symbolmatrix/symbolmatrix` and the YAML functionality will not be loaded.
+
+### Exceptions
+
+Whenever a key is not found in the SymbolMatrix, a custom `SymbolMatrix::KeyNotDefinedException` will be raised. 
+Similarly, if you attempt to use an inconvertible key (inconvertible to `Symbol`) a `SymbolMatrix::InvalidKeyException` will be raised.
+
+Installation
+------------
+
+    gem install symbolmatrix
+
+### Or using Bundler
+Add this line to your application's Gemfile:
+
+    gem 'symbolmatrix'
+
+And then execute:
+
+    bundle install
+
+## Testing
+
+RSpec specs are provided to check functionality.
+
+## License
+
+Copyright (C) 2012 Fetcher
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.

data/Rakefile

@@ -0,0 +1,10 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+desc "Run specs"
+RSpec::Core::RakeTask.new(:spec) do |t|
+t.pattern = "./spec/**/*_spec.rb"
+end
+
+task :default => :spec

data/lib/symbolmatrix.rb

@@ -0,0 +1,2 @@
+require "symbolmatrix/symbolmatrix"
+require "yaml/symbolmatrix"

data/lib/symbolmatrix/symbolmatrix.rb

@@ -0,0 +1,82 @@
+require "symbolmatrix/version"
+
+class SymbolMatrix < Hash
+
+  # Initializes the SymbolMatrix with the passed Hash if a hash is passed
+  def initialize hash = nil
+    super
+    merge! hash unless hash.nil?
+  end
+
+  # Validates whether the given key is usable in a SymbolMatrix
+  def validate_key key
+    unless key.respond_to? :to_sym
+      raise InvalidKeyException, "The key '#{key}' does not respond to #to_sym, so is not a valid key for SymbolMatrix"
+    end
+      
+    return true
+  end
+
+  # Sets the value of the given +key+ to +val+ if the key is valid.
+  def store key, val
+    validate_key key
+    if val.instance_of? Hash
+      super(key.to_sym, SymbolMatrix.new(val))
+    else
+      super(key.to_sym, val)
+    end
+  end
+
+  # Retrieves the value of the given +key+.
+  def [] key
+    validate_key key
+    raise KeyNotDefinedException, "The key :#{key} is not defined" unless self.has_key? key.to_sym
+    super key.to_sym
+  end
+
+  alias []= store  
+  
+  # Returns a hashed version of this SymbolMatrix, with all SymbolMatrix objects within recursively 
+  # converted into hashes
+  def to_hash recursive = true
+    the_hash = {}
+    self.each do |key, value|
+      if value.is_a? SymbolMatrix and recursive
+        the_hash[key] = value.to_hash
+      else
+        the_hash[key] = value
+      end
+    end
+    return the_hash
+  end
+  
+  # Merges the passed hash within self
+  def merge! hash
+    hash.each do |key, value|
+      store key, value
+    end
+  end
+  
+  alias update merge!
+  
+  # Checks the keys for compatibility with SymbolMatrix and calls the merge in Hash
+  def merge hash
+    # Before merging, let's check the keys
+    hash.each_key do |key|
+      validate_key key
+    end
+    super hash
+  end
+
+  # Allows values to be retrieved and set using Ruby's dot method syntax.
+  def method_missing sym, *args
+    if sym.to_s.index "="
+      store sym.to_s[0..-2].to_sym, args.shift
+    else
+      self[sym]
+    end
+  end
+  
+  class KeyNotDefinedException < RuntimeError; end
+  class InvalidKeyException < RuntimeError; end 
+end

data/lib/symbolmatrix/version.rb

@@ -0,0 +1,3 @@
+module Symbolmatrix
+  VERSION = "0.0.1"
+end

data/lib/yaml/symbolmatrix.rb

@@ -0,0 +1,35 @@
+require "yaml"
+
+module YAML
+  module SymbolMatrix
+    # Calls #merge! using the parsed YAML data as argument
+    def from_yaml yaml
+      merge! YAML.load yaml
+    end
+    
+    # Calls #merge! using the parsed YAML data from the file
+    def from_file path
+      merge! YAML.load_file path
+    end
+    
+    # Can I override initialize and call super anyways??
+    def initialize argument = nil
+    end
+  end
+end
+
+class SymbolMatrix
+  include YAML::SymbolMatrix
+  
+  def initialize argument = nil
+    if argument.is_a? String
+      if File.exist? argument
+        from_file argument
+      else
+        from_yaml argument
+      end
+    else
+      merge! argument unless argument.nil?
+    end
+  end
+end

data/spec/symbolmatrix_spec.rb

@@ -0,0 +1,147 @@
+require "symbolmatrix/symbolmatrix"
+
+describe SymbolMatrix do
+
+  describe "#validate_key" do
+    context "an not convertible to Symbol key is passed" do
+      it "should raise a SymbolMatrix::InvalidKeyException" do
+        m = SymbolMatrix.new
+        o = Object.new
+        expect { m.validate_key o
+        }.to raise_error SymbolMatrix::InvalidKeyException, "The key '#{o}' does not respond to #to_sym, so is not a valid key for SymbolMatrix"
+      end
+    end
+  end
+  
+  describe "#store" do
+    context "a key is stored using a symbol" do
+      it "should be foundable with #[<symbol]" do
+        a = SymbolMatrix.new
+        a.store :a, 2
+        a[:a].should == 2
+      end
+    end
+    
+    context "the passed value is a Hash" do
+      it "should be converted into a SymbolTable" do
+        a = SymbolMatrix.new
+        a.store :b, { :c => 3 }
+        a[:b].should be_a SymbolMatrix
+      end
+    end
+  end
+  
+  shared_examples_for "any merging operation" do
+    it "should call :store for every item in the passed Hash" do
+      m = SymbolMatrix.new
+      m.should_receive(:store).exactly(3).times
+      m.send @method, { :a => 1, :b => 3, :c => 4 }
+    end
+  end
+
+  describe "#merge!" do
+    before { @method = :merge! }
+    it_behaves_like "any merging operation"
+  end  
+  
+  describe "#update" do
+    before { @method = :update }
+    it_behaves_like "any merging operation"
+  end
+
+  describe "#merge" do
+    it "should call #validate_key for each passed item" do
+      m = SymbolMatrix.new
+      m.should_receive(:validate_key).exactly(3).times.and_return(true)
+      m.merge :a => 2, :b => 3, :c => 4
+    end
+  end
+
+  describe "#[]" do
+    context "the matrix is empty" do
+      it "should raise a SymbolMatrix::KeyNotDefinedException" do
+        m = SymbolMatrix.new
+        expect { m['t']
+        }.to raise_error SymbolMatrix::KeyNotDefinedException, "The key :t is not defined"
+      end
+    end
+    
+    context "the matrix has a key defined using a symbol" do
+      it "should return the same value when called with a string" do
+        m = SymbolMatrix.new
+        m[:s] = 3
+        m["s"].should == 3
+      end
+    end
+  end
+
+  describe "#to_hash" do
+    it "should return an instance of Hash" do
+      m = SymbolMatrix[:b, 1]
+      m.to_hash.should be_instance_of Hash
+    end
+    
+    it "should have the same keys" do
+      m = SymbolMatrix[:a, 1]
+      m.to_hash[:a].should == 1
+    end
+    
+    context "there is some SymbolMatrix within this SymbolMatrix" do
+      it "should recursively call #to_hash in it" do
+        inside = SymbolMatrix.new
+        inside.should_receive :to_hash
+        
+        m = SymbolMatrix[:a, inside]
+        m.to_hash
+      end
+      
+      context "and recursive is set to false" do
+        it "should not call #to_hash on values" do
+          inside = SymbolMatrix.new
+          inside.should_not_receive :to_hash
+          
+          m = SymbolMatrix[:a, inside]
+          m.to_hash false
+        end
+      end
+    end
+  end
+
+  describe ".new" do
+    context "a Hash is passed as argument" do
+      it "should accept it" do
+        m = SymbolMatrix.new :a => 1
+        m["a"].should == 1
+        m[:a].should == 1
+      end
+    end
+  end    
+
+  describe "method_missing" do
+    it "should store in a key named after the method without the '=' sign" do
+      m = SymbolMatrix.new
+      m.a = 4
+      m[:a].should == 4
+    end
+    
+    it "should return the same as the symbol representation of the method" do
+      m = SymbolMatrix.new
+      m.a = 3
+      m[:a].should == 3
+      m["a"].should == 3
+      m.a.should == 3
+    end
+
+    it "should preserve the class of the argument" do
+      class A < SymbolMatrix; end
+      class B < SymbolMatrix; end
+      
+      a = A.new
+      b = B.new
+
+      a.a = b
+
+      a.a.should be_instance_of B
+    end
+  end
+end

data/spec/yaml-symbolmatrix_spec.rb

@@ -0,0 +1,60 @@
+require "symbolmatrix"
+
+require "fast" # For testing easyness
+
+describe YAML::SymbolMatrix do
+  describe "#from_yaml" do
+    it "should call #merge! on self using the parsed YAML data as argument" do
+      sample_yaml = "a: { nested: { data: with, very: much }, content: to find }"
+      the_stub = stub "a theoretical SymbolMatrix"
+      the_stub.extend YAML::SymbolMatrix
+      the_stub.should_receive(:merge!).with "a" => { "nested" => { "data" => "with", "very" => "much" }, "content" => "to find" }
+      the_stub.from_yaml sample_yaml
+    end
+  end
+  
+  describe "#from_file" do
+    context "there is a YAML file in the given path" do
+      before do
+        Fast.file.write "temp/data.yaml", "a: { nested: { data: with, very: much }, content: to find }"
+      end
+      
+      it "should call #merge! on self using the parsed YAML data found in the file" do
+        the_stub = stub "a theoretical SymbolMatrix"
+        the_stub.extend YAML::SymbolMatrix
+        the_stub.should_receive(:merge!).with "a" => { "nested" => { "data" => "with", "very" => "much" }, "content" => "to find" }
+        the_stub.from_file "temp/data.yaml"
+      end
+      
+      after do
+        Fast.dir.remove! :temp
+      end
+    end
+  end
+end
+
+describe SymbolMatrix do
+  describe "#initialize" do # Soooooo meta... tell me its true!
+    context "a valid path to a file is provided" do
+      before do 
+        Fast.file.write "temp/data.yaml", "a: { nested: { data: with, very: much }, content: to find }"
+      end
+      
+      it "should load the data into self" do
+        f = SymbolMatrix.new "temp/data.yaml"
+        f.a.nested.data.should == "with"
+      end
+
+      after do
+        Fast.dir.remove! :temp
+      end
+    end
+    
+    context "a YAML string is provided" do
+      it "should load the data into self" do
+        e = SymbolMatrix.new "beta: { nano: { data: with, very: much }, content: to find }"
+        e.beta.nano[:very].should == "much"
+      end
+    end
+  end
+end

data/symbolmatrix.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/symbolmatrix/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Xavier Via"]
+  gem.email         = ["xavier.via.canel@gmail.com"]
+  gem.description   = %q{Very useful for configuration files, SymbolMatrix is a hash-like multidimentional Symbol-only class with ability to discover and load YAML data}
+  gem.summary       = %q{Very useful for configuration files, SymbolMatrix is a hash-like multidimentional Symbol-only class with ability to discover and load YAML data}
+  gem.homepage      = "http://github.com/fetcher/symbolmatrix"
+
+  gem.add_development_dependency "rspec"
+  gem.add_development_dependency "pry"
+  gem.add_development_dependency "fast"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "symbolmatrix"
+  gem.require_paths = ["lib"]
+  gem.version       = Symbolmatrix::VERSION
+end

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification 
+name: symbolmatrix
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Xavier Via
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-07-31 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  version_requirements: *id001
+  prerelease: false
+  name: rspec
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  version_requirements: *id002
+  prerelease: false
+  name: pry
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  version_requirements: *id003
+  prerelease: false
+  name: fast
+description: Very useful for configuration files, SymbolMatrix is a hash-like multidimentional Symbol-only class with ability to discover and load YAML data
+email: 
+- xavier.via.canel@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- .travis.yml
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/symbolmatrix.rb
+- lib/symbolmatrix/symbolmatrix.rb
+- lib/symbolmatrix/version.rb
+- lib/yaml/symbolmatrix.rb
+- spec/symbolmatrix_spec.rb
+- spec/yaml-symbolmatrix_spec.rb
+- symbolmatrix.gemspec
+homepage: http://github.com/fetcher/symbolmatrix
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Very useful for configuration files, SymbolMatrix is a hash-like multidimentional Symbol-only class with ability to discover and load YAML data
+test_files: 
+- spec/symbolmatrix_spec.rb
+- spec/yaml-symbolmatrix_spec.rb