squares 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 09592e711ca540e1b0fb97bb9e841af69cb34175
+  data.tar.gz: e3d626d74d1184b164f5ba4f90b1cf1c7567610e
+SHA512:
+  metadata.gz: 60351a2a9e968f992a4c578e2853729a090d15e3c4ec0d9d8d153d99686eb7b81081c4808ad3485d35ed71938ea3130b0079ec9f3d2bfc6ac888881128d4e3df
+  data.tar.gz: fc865c89c8de7e4fbbb5f6ffc0ca5e344a772848b29456f2cbc7618ede6c6e601e2c38951a2b088fad7aed3e166b76262510d1808961fe5cfe6788ae019e6ee0

data/.gitignore

@@ -0,0 +1,16 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+.ruby-version
+.ruby-gemset

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.1.5

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Joel Helbling
+
+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,189 @@
+# Squares \[\*\]
+
+A lightweight ORM backed by any hash-like storage.  Hand-crafted from a solid piece of pure
+aircraft-grade Ruby and drawing distilled awesomeness from atmospheric pollutants, its only
+dependency is you.
+
+## Installation Blah, Blah, Blah
+
+_I swear, this part of the README just rolled right out of `bundle gem squares`._
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'squares'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install squares
+
+_And yeah, I did enjoy typing `bundle gem squares`.  It sounds like something to
+eat.  Now I'm hungry._
+
+## Usage
+
+_Because you are going to use it._
+
+```ruby
+require 'squares'
+```
+
+### Write Models
+
+_How come they never write back?_
+
+```ruby
+class Person < Squares::Base
+  properties :real_name, :age
+end
+```
+
+You can also provide a default value if you switch to the `property` variant:
+
+```ruby
+class Person < Squares::Base
+  property :eye_color, default: 'brown'
+end
+```
+
+### Bootstrapping
+
+_A funny word for "setup & configure".  Bootstrapping.  Bootstrapping.  See?  Funny._
+
+Now you can bootstrap `;)` your model to a hash-like storage object like so:
+
+```ruby
+people_storage = Redis::Namespace.new(
+                   Person.underscore_name,
+                   :redis => $redis_connection )
+
+Person.store = people_storage
+```
+
+Or setup a bunch of 'em like this:
+
+```ruby
+[Person, Place, Thing].each do |model|
+  model.store = LevelDB::DB.new("./tmp/#{model.underscore_name}")
+end
+```
+
+...or if you just want to use a plain ole in-memory hash:
+
+```ruby
+tom_sellecks_mustache = {}
+Soup.store = tom_sellecks_mustache
+```
+
+Squares actually defaults the store to an empty hash, which means if you're ok
+with in-memory, transient storage (e.g. when writing tests, etc.) you don't have
+to do any config-- er, bootstrapping `;)` at all!
+
+### Onward To The Fun
+
+Squares does not auto-generate an `:id` for each new object --you'll do that
+and it will be used as the "key" in the hash storage.  In the following example,
+we're creating a new `Person` and using 'spiderman' as the key:
+
+```ruby
+pete = Person.new('spiderman', real_name: 'Peter Parker', age: 17)
+#                 ^^^ key ^^^  ^^^^^^^^^^^ properties ^^^^^^^^^^^
+pete.save
+
+Person.has_key? 'spiderman' #=> true
+pete.id                     #=> 'spiderman'
+```
+
+When we retrieve an object, it returns an instance of that model:
+
+```ruby
+wallcrawler = Person['spiderman']
+wallcrawler = Person.find 'spiderman' #=> same, shmame.
+wallcrawler.id                        #=> 'spiderman'
+wallcrawler.real_name                 #=> 'Peter Parker'
+wallcrawler.class                     #=> Person
+```
+
+Of course, for some types of storage, the model object has to be serialized and
+de-serialized when it's stored and retrieved.  Squares uses `Marshal.dump` and
+`Marshal.restore` to do that.  This means that custom marshalling can be added
+to your models (see [documentation on ruby Marshal][marshal]).
+
+### Even More Fun
+
+You can use the ActiveRecord-esque `.where` method with a block to retrieve records
+for which the block returns true:
+
+```ruby
+Person.where { |p| p.left_handed == true } #=> all the lefties
+```
+
+The `.where` method is actually just an alias of `.select`...which means, yeah!
+Squares are enumerable, yay!
+
+```ruby
+Person.map(&:name) #=> an array containing all the names
+```
+
+### What It Doesn't Do
+
+Much like Wolverine, Squares doesn't do relationships.  You'll have to
+maintain those in your code.  If you have an issue with that, leave me
+an issue, and I'll think about what that might mean.
+
+Squares neither knows nor cares about the type or contents of your model
+instance's properties.  This has consequences.
+
+First, anything you stash had darn well better be marshal-able, or there
+will be blood on the roller-rink.  Or at least errors.  Yeah, I've made
+sure there won't be blood (you're welcome), but watch out for errors.
+If you run into problems, refer to the [documentation on ruby Marshal][marshal].
+
+Second, there is no magic-fu for stuff like generating question methods
+for boolean properties.  For example, it doesn't make a `#left_handed?` method
+out of your `property :left_handed`).  But hey, you know what you can
+do?  Behold:
+
+```ruby
+class Person
+  property :awesome?, default: true #=> What?! is that a "?"
+end
+```
+
+Ok, don't interrupt me, I'm selling here...
+
+```ruby
+you = Person.new
+you.awesome? #=> true
+```
+
+Of course, Squares doesn't mind how you use `#awesome?` and the corresponding `#awesome=` methods:
+
+```ruby
+you.awesome = 'yak hair'
+you.awesome? #=> 'yak hair'
+```
+
+or
+
+```ruby
+you.awesome = nil
+you.awesome? #=> nil
+```
+
+But hey, who cares, as long as yak hair is truthy?
+
+[marshal]:http://www.ruby-doc.org/core-2.1.5/Marshal.html
+
+## Contributing
+
+1. Fork it ( https://github.com/joelhelbling/squares/fork )
+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 a new Pull Request

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+

data/lib/squares/base.rb

@@ -0,0 +1,144 @@
+module Squares
+  class Base
+    attr_accessor :id
+
+    def initialize *args
+      apply *args
+    end
+
+    def save
+      store[@id] = Marshal.dump self
+      nil
+    end
+
+    def == other
+      @id == other.id && properties_equal(other)
+    end
+
+    def properties
+      self.class.properties
+    end
+
+    private
+
+    def properties_equal other
+      ! properties.detect do |property|
+        self.send(property) != other.send(property)
+      end
+    end
+
+    def apply *args
+      @id, value_hash = *args
+      self.class.properties.each do |property|
+        value = args.last.to_h[property] || self.class.defaults[property]
+        # self.class.method_for(property)
+        self.send "#{property.to_s.gsub(/\?$/,'')}=".to_sym, value
+      end
+    end
+
+    def store
+      self.class.store
+    end
+
+    #############
+    class << self
+      include Enumerable
+
+      def [] id
+        if item = store[id]
+          Marshal.restore item
+        end
+      end
+      alias_method :find, :[]
+
+      def []= *args
+        id, instance = *args
+        if instance.class == self
+          instance.id = id
+          instance.save
+        elsif instance.respond_to?(:to_h)
+          self.new(id, instance).save
+        else
+          raise ArgumentError.new(<<-ERR)
+          You must provide an instance of #{self.name} or at least
+          something which responds to #to_h"
+          ERR
+        end
+      end
+      alias_method :create, :[]=
+
+      def has_key? key
+        store.has_key? key
+      end
+      alias_method :key?,      :has_key?
+      alias_method :member?,   :has_key?
+      alias_method :includes?, :has_key?
+
+      def each &block
+        store.values.map{ |i| Marshal.restore i }.each &block
+      end
+      alias_method :where, :select
+
+      def property prop, opts
+        @_properties ||= []
+        @_properties << prop
+        uniquify_properties
+        if prop.to_s.match(/\?$/)
+          define_method prop do
+            instance_variable_get "@#{self.class.instance_var_for prop}"
+          end
+          define_method prop.to_s.gsub(/\?$/, '=') do |v|
+            instance_variable_set "@#{self.class.instance_var_for prop}", v
+          end
+        else
+          attr_accessor prop
+        end
+        if default = opts[:default]
+          defaults[prop] = default
+        end
+      end
+
+      def properties *props
+        props.each do |prop|
+          property prop, {}
+        end
+        @_properties
+      end
+
+      def defaults
+        @_defaults ||= {}
+      end
+
+      def underscore_name
+        self.name.
+          gsub(/::/, '/').
+          gsub(/([^\/])([A-Z])/, '\1_\2').
+          downcase
+      end
+
+      def store= storage
+        @store = storage
+      end
+
+      def store
+        @store ||= {}
+      end
+
+      def instance_var_for property
+        if property.to_s.match(/\?$/)
+          "#{property.to_s.gsub(/\?$/,'')}__question__".to_sym
+        else
+          property
+        end
+      end
+
+      private
+
+      def uniquify_properties
+        @_properties = @_properties.uniq.compact
+      end
+
+    end
+  end
+end
+

data/lib/squares/version.rb

@@ -0,0 +1,3 @@
+module Squares
+  VERSION = "0.2.0"
+end

data/lib/squares.rb

@@ -0,0 +1,6 @@
+require 'squares/version'
+require 'squares/base'
+
+module Squares
+  # Your code goes here...
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+
+require 'pry'
+require 'rspec-given'
+require 'squares'

data/spec/squares/base_spec.rb

@@ -0,0 +1,164 @@
+require 'spec_helper'
+require 'squares/base'
+
+module Marvel
+  class SuperHero < Squares::Base
+    properties :real_name, :special_powers
+  end
+  class Villain < Squares::Base
+    properties :vehicle, :lair
+    property :really_evil?, default: true
+  end
+end
+
+module Squares
+  describe Base do
+    Given(:storage)    { {}                                                                         }
+    Given(:test_class) { Marvel::SuperHero                                                          }
+    Given              { test_class.store = storage                                                 }
+
+    Given(:id)         { 'Captain America'                                                          }
+    Given(:name)       { 'Steve Rogers'                                                             }
+    Given(:powers)     { ['super strength', 'strategy', 'leadership']                               }
+    When(:hero)        { test_class.new id, real_name: name, special_powers: powers                 }
+
+    describe 'class' do
+
+      describe '.underscore_name' do
+        Then { test_class.underscore_name == 'marvel/super_hero'                                    }
+      end
+
+      describe '.properties' do
+        Then { test_class.properties == [:real_name, :special_powers]                               }
+      end
+
+      describe '.use_storage' do
+        Given(:storage) { {attack: :fwoosh }                                                        }
+        When            { test_class.store = storage                                                }
+        Then            { test_class.store == storage                                               }
+      end
+
+      describe '.[]' do
+        Given { storage[id] = Marshal.dump hero                                                     }
+        When(:recovered_hero) { Marvel::SuperHero['Captain America']                                }
+        Then                  { recovered_hero.class     == Marvel::SuperHero                       }
+        Then                  { recovered_hero.id        == 'Captain America'                       }
+        Then                  { recovered_hero.real_name == 'Steve Rogers'                          }
+        Then                  { recovered_hero.special_powers.include? 'leadership'                 }
+      end
+
+      describe '.[]= creates & stores a new instance' do
+        Given(:id)     { 'Spiderman'                                                                }
+        Given(:name)   { 'Peter Parker'                                                             }
+        Given(:powers) { [ 'wall crawling', 'web spinning', 'cracking wise' ]                       }
+
+        context 'whether created with an instance' do
+          Given(:instance) { test_class.new(id, real_name: name, special_powers: powers)            }
+
+          When             { test_class[id] = instance                                              }
+          When(:spidey)    { Marshal.restore storage.values.first                                   }
+
+          Then             { spidey.class     == Marvel::SuperHero                                  }
+          Then             { spidey.id        == 'Spiderman'                                        }
+          Then             { spidey.real_name == 'Peter Parker'                                     }
+          Then             { spidey.special_powers.include? 'cracking wise'                         }
+        end
+
+        context 'or creating using a hash' do
+          When { test_class[id] = { real_name: name, special_powers: powers }                       }
+
+          When(:spidey) { Marshal.restore storage.values.first                                      }
+          Then { spidey.class     == Marvel::SuperHero                                              }
+          Then { spidey.id        == 'Spiderman'                                                    }
+          Then { spidey.real_name == 'Peter Parker'                                                 }
+          Then { spidey.special_powers.include? 'cracking wise'                                     }
+        end
+
+        context 'but creating with an invalid object' do
+          Then { expect{ test_class[id] = 12 } .to raise_error(ArgumentError)                       }
+        end
+      end
+
+      describe '.has_key?' do
+        Given { hero.save                                                                           }
+        Then  { expect(test_class).to have_key(id)                                                  }
+        Then  { expect(test_class).to be_key(id)                                                    }
+        Then  { expect(test_class).to be_member(id)                                                 }
+        Then  { expect(test_class).to be_includes(id)                                               }
+      end
+
+      describe 'more cool stuff' do
+        Given do
+          Marvel::SuperHero['Superman'] = { real_name: 'Clark Kent',   special_powers: ['flying'] }
+          Marvel::SuperHero['Hulk']     = { real_name: 'Bruce Banner', special_powers: ['smash']  }
+          Marvel::SuperHero['Batman']   = { real_name: 'Bruce Wayne',  special_powers: ['stuff']  }
+        end
+
+        describe '.where' do
+          When(:result) { Marvel::SuperHero.where { |h| h.real_name =~ /^Bruce/ } }
+          Then { result.count == 2 }
+        end
+
+        describe 'models are enumerable!' do
+          When(:result) { Marvel::SuperHero.map(&:special_powers).flatten }
+          Then { result == %w[ flying smash stuff ] }
+        end
+      end
+
+    end
+
+    describe 'instances' do
+      describe '#{{property}}' do
+        Then { hero.id             == id                                                            }
+        Then { hero.real_name      == name                                                          }
+        Then { hero.special_powers == powers                                                        }
+      end
+
+      describe '#save' do
+        When { hero.save                                                                            }
+        When(:frozen_hero) { Marshal.restore storage.values.first                                   }
+        Then { storage.keys.first    == 'Captain America'                                           }
+        Then { frozen_hero.real_name == 'Steve Rogers'                                              }
+        Then { frozen_hero.class     == Marvel::SuperHero                                           }
+      end
+
+      describe '#==' do
+        Given(:hero1) { test_class.new id, real_name: name, special_powers: powers                  }
+        Given(:hero2) { test_class.new id, real_name: name, special_powers: powers                  }
+
+        context 'when they are equal' do
+          Then { hero1 == hero2                                                                     }
+        end
+
+        context 'when some property(ies) are not equal' do
+          Given { hero2.real_name = 'Steven Rogers'                                                 }
+          Then  { hero1 != hero2                                                                    }
+        end
+      end
+
+      describe 'default values' do
+        Given do
+          class Marvel::SuperHero < Squares::Base
+            property :hair_color, default: 'black'
+          end
+        end
+        When(:hero) { test_class.new id, real_name: name                                            }
+        Then { hero.special_powers == nil                                                           }
+        Then { hero.hair_color == 'black'                                                           }
+        Then { Marvel::SuperHero.defaults == { hair_color: 'black' }                                }
+      end
+
+    end
+
+    describe "models' properties don't bleed into each other" do
+      When(:villain) { Marvel::Villain.new 'Dr. Octopus', vehicle: 'jets', lair: 'abandonned sewer' }
+      Then { villain.class              == Marvel::Villain                                          }
+      Then { Marvel::Villain.properties == [:vehicle, :lair, :really_evil?]                         }
+      Then { villain.properties         == [:vehicle, :lair, :really_evil?]                         }
+      Then { expect(villain).to_not respond_to(:hair_color)                                         }
+      Then { expect(villain).to respond_to(:really_evil?)                                           }
+      Then { expect(villain).to respond_to(:really_evil=)                                           }
+      Then { expect(villain).to be_really_evil                                                      }
+    end
+  end
+end

data/spec/squares_spec.rb

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

data/squares.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'squares/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "squares"
+  spec.version       = Squares::VERSION
+  spec.authors       = ["Joel Helbling"]
+  spec.email         = ["joel@joelhelbling.com"]
+  spec.summary       = %q{Lightweight ORM backed by any hash-like storage. [*]}
+  spec.description   = %q{Redis, LevelDB or plain old hashes --any form of hash-like storage can be used to back Squares.}
+  spec.homepage      = "http://github.com/joelhelbling/squares"
+  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.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "rspec-given"
+  spec.add_development_dependency "pry"
+end

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification
+name: squares
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Joel Helbling
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-12-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-given
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Redis, LevelDB or plain old hashes --any form of hash-like storage can
+  be used to back Squares.
+email:
+- joel@joelhelbling.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/squares.rb
+- lib/squares/base.rb
+- lib/squares/version.rb
+- spec/spec_helper.rb
+- spec/squares/base_spec.rb
+- spec/squares_spec.rb
+- squares.gemspec
+homepage: http://github.com/joelhelbling/squares
+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.3
+signing_key: 
+specification_version: 4
+summary: Lightweight ORM backed by any hash-like storage. [*]
+test_files:
+- spec/spec_helper.rb
+- spec/squares/base_spec.rb
+- spec/squares_spec.rb