Permalink
Browse files

Initial commit.

  • Loading branch information...
0 parents commit 0a3210140eb1b337177c64d725085e5520f43770 Alex Fortuna committed Mar 8, 2012
Showing with 835 additions and 0 deletions.
  1. +11 −0 .gitignore
  2. +2 −0 .rspec
  3. +4 −0 Gemfile
  4. +26 −0 Gemfile.lock
  5. +20 −0 MIT-LICENSE
  6. +152 −0 README.md
  7. +1 −0 Rakefile
  8. +241 −0 lib/smart_hash.rb
  9. +24 −0 lib/smart_hash/loose.rb
  10. +22 −0 smart_hash.gemspec
  11. +293 −0 spec/smart_hash_spec.rb
  12. +39 −0 spec/spec_helper.rb
@@ -0,0 +1,11 @@
+# General Ruby.
+.ref-*
+.old*
+*-old*
+
+# Project-specific.
+/*.rb
+/doc/
+/pkg/
+/.rvmrc
+/.yardoc
2 .rspec
@@ -0,0 +1,2 @@
+--color
+-fn # Tree-like progress.
@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem dependencies in `PROJECT.gemspec`.
+gemspec
@@ -0,0 +1,26 @@
+PATH
+ remote: .
+ specs:
+ smart_hash (0.1.0)
+
+GEM
+ remote: http://rubygems.org/
+ specs:
+ diff-lcs (1.1.3)
+ rspec (2.8.0)
+ rspec-core (~> 2.8.0)
+ rspec-expectations (~> 2.8.0)
+ rspec-mocks (~> 2.8.0)
+ rspec-core (2.8.0)
+ rspec-expectations (2.8.0)
+ diff-lcs (~> 1.1.2)
+ rspec-mocks (2.8.0)
+ yard (0.7.5)
+
+PLATFORMS
+ ruby
+
+DEPENDENCIES
+ rspec
+ smart_hash!
+ yard
@@ -0,0 +1,20 @@
+Copyright (c) 2012 Alex Fortuna
+
+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.
152 README.md
@@ -0,0 +1,152 @@
+
+A smarter alternative to OpenStruct
+===================================
+
+Introduction
+------------
+
+If you're unhappy with `OpenStruct` (like myself), you might consider using `SmartHash` because of these major features:
+
+* You can access attributes as methods or keys. Both `person.name` and `person[:name]` will work.
+* Attribute access is strict by default. `person.invalid_stuff` will raise an exception instead of returning the stupid `nil`.
+* You can use **any** attribute names. `person.size = "XL"` will work as intended.
+* `SmartHash` descends from `Hash` and inherits its rich feature set.
+
+
+Setup
+-----
+
+~~~
+$ gem install smart_hash
+~~~
+
+, or via Bundler's `Gemfile`:
+
+~~~
+gem "smart_hash"
+#gem "smart_hash", :git => "git://github.com/dadooda/smart_hash.git" # Edge version.
+~~~
+
+
+Usage
+-----
+
+Create an object and set a few attributes:
+
+~~~
+>> person = SmartHash[]
+>> person.name = "John"
+>> person.age = 25
+
+>> person
+=> {:name=>"John", :age=>25}
+~~~
+
+Read attributes:
+
+~~~
+>> person.name
+=> "John"
+>> person[:name]
+=> "John"
+~~~
+
+Access an unset attribute:
+
+~~~
+>> person.invalid_stuff
+KeyError: key not found: :invalid_stuff
+>> person[:invalid_stuff]
+=> nil
+~~~
+
+Please note that `[]` access is always non-strict since `SmartHash` behaves as `Hash` here.
+
+Manipulate attributes which exist as methods:
+
+~~~
+>> person = SmartHash[:name => "John"]
+>> person.size
+=> 1
+>> person.size = "XL"
+>> person.size
+=> "XL"
+~~~
+
+**IMPORTANT:** You can use any attribute names excluding these: `default`, `default_proc`, `strict`.
+
+Use `Hash` features, e.g. merge:
+
+~~~
+>> person = SmartHash[:name => "John"]
+>> person.merge(:surname => "Smith", :age => 25)
+=> {:name=>"John", :surname=>"Smith", :age=>25}
+~~~
+
+, or iterate:
+
+~~~
+>> person.each {|k, v| puts "#{k}: #{v}"}
+name: John
+surname: Smith
+age: 25
+~~~
+
+Suppose you want to disable the strict mode:
+
+~~~
+>> person = SmartHash[]
+>> person.strict = false
+
+>> person.name
+=> nil
+>> person.age
+=> nil
+~~~
+
+`SmartHash::Loose` is non-strict upon construction:
+
+~~~
+>> person = SmartHash::Loose[]
+>> person.name
+=> nil
+>> person.age
+=> nil
+~~~
+
+Suppose you **know** you will use the `size` attribute and you don't want any interference from the `#size` method. Use attribute declaration:
+
+~~~
+>> person = SmartHash[]
+>> person.declare(:size)
+>> person.size
+KeyError: key not found: :size
+>> person.size = "XL"
+>> person.size
+=> "XL"
+~~~
+
+Suppose you set an attribute and want to ensure that it's not overwritten. Use attribute protection:
+
+~~~
+>> person = SmartHash[]
+>> person.name = "John"
+>> person.protect(:name)
+
+>> person.name = "Bob"
+ArgumentError: Attribute 'name' is protected
+~~~
+
+
+Copyright
+---------
+
+Copyright © 2012 Alex Fortuna.
+
+Licensed under the MIT License.
+
+
+Feedback
+--------
+
+Send bug reports, suggestions and criticisms through [project's page on GitHub](http://github.com/dadooda/smart_hash).
@@ -0,0 +1 @@
+require "bundler/gem_tasks"
Oops, something went wrong.

0 comments on commit 0a32101

Please sign in to comment.