active_hash 0.6.1

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,6 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg
+.idea

data/CHANGELOG

@@ -0,0 +1,13 @@
+2009-08-19
+  - Added custom finders for multiple fields, such as .find_all_by_name_and_age
+
+2009-07-23
+  - Added support for auto-defining methods based on hash keys in ActiveHash::Base
+  - Changed the :field and :fields API so that they don't overwrite existing methods (useful when ActiveHash auto-defines methods)
+  - Fixed a bug where ActiveFile incorrectly set the root_path to be the path in the gem directory, not the current working directory
+
+2009-07-24
+  - ActiveFile no longer reloads files by default
+  - Added ActiveFile.reload_active_file= so you can cause ActiveFile to reload
+  - Setting data to nil correctly causes .all to return an empty array
+  - Added reload(force) method, so that you can force a reload from files in ActiveFile, useful for tests

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Jeff Dean
+
+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,202 @@
+# ActiveHash
+
+ActiveHash is a simple base class that allows you to use a ruby hash as a readonly datasource for an ActiveRecord-like model.
+
+ActiveHash assumes that every hash has an :id key, which is what you would probably store in a database.  This allows you to seemlessly upgrade from ActiveHash objects to full ActiveRecord objects without having to change any code in your app, or any foreign keys in your database.
+
+It also allows you to use #belongs_to in your AR objects.
+
+ActiveHash can also be useful to create simple test classes that run without a database - ideal for testing plugins or gems that rely on simple AR behavior, but don't want to deal with databases or migrations for the spec suite.
+
+ActiveHash also ships with:
+
+  * ActiveFile: a base class that will reload data from a flat file every time the flat file is changed
+  * ActiveYaml: a base class that will turn YAML into a hash and load the data into an ActiveHash object
+
+## Installation
+
+    sudo gem install zilkey-active_hash
+
+## Usage
+
+To use ActiveHash, you need to:
+
+ * Inherit from ActiveHash::Base
+ * Define your data
+ * (optionally) Define your fields and/or default values
+
+A quick example would be:
+
+    class Country < ActiveHash::Base
+      self.data = [
+        {:id => 1, :name => "US"},
+        {:id => 2, :name => "Canada"}
+      ]
+    end
+
+    country = Country.new(:name => "Mexico")
+    country.name  # => "Mexico"
+    country.name? # => true
+
+## Auto-Defined fields
+
+ActiveHash will auto-define all fields for you when you load the hash.  For example, if you have the following class:
+
+    class CustomField < ActiveYaml::Base
+      self.data = [
+        {:custom_field_1 => "foo"},
+        {:custom_field_2 => "foo"},
+        {:custom_field_3 => "foo"}
+      ]
+    end
+
+Once you call CustomField.all it will define methods for :custom_field_1, :custom_field_2 etc...
+
+If you need the fields at load time, as opposed to after .all is called, you can also define them manually, like so:
+
+    class CustomField < ActiveYaml::Base
+      fields :custom_field_1, :custom_field_2, :custom_field_3
+    end
+
+NOTE: auto-defined fields will _not_ override fields you've defined, either on the class or on the instance.
+
+## Defining Fields with default values
+
+If some of your hash values contain nil, and you want to provide a default, you can specify defaults with the :field method:
+
+    class Country < ActiveHash::Base
+      field   :is_axis_of_evil, :default => false
+    end
+
+## Defining Data
+
+You can define data inside your class or outside.  For example, you might have a class like this:
+
+    # app/models/country.rb
+    class Country < ActiveHash::Base
+    end
+
+    # config/initializers/data.rb
+    Country.data = [
+        {:id => 1, :name => "US"},
+        {:id => 2, :name => "Canada"}
+    ]
+
+If you prefer to store your data in YAML, see below.
+
+## Class Methods
+
+ActiveHash gives you ActiveRecord-esque methods like:
+
+    Country.all             # => returns all Country objects
+    Country.count           # => returns the length of the .data array
+    Country.first           # => returns the first country object
+    Country.last            # => returns the last country object
+    Country.find 1          # => returns the first country object with that id
+    Country.find [1,2]      # => returns all Country objects with ids in the array
+    Country.find :all       # => same as .all
+    Country.find :all, args # => the second argument is totally ignored, but allows it to play nicely with AR
+    Country.find_by_id 1    # => find the first object that matches the id
+
+It also gives you a few dynamic finder methods.  For example, if you defined :name as a field, you'd get:
+
+    Country.find_by_name "foo"      # => returns the first object matching that name
+    Country.find_all_by_name "foo"  # => returns an array of the objects with matching names
+
+## Instance Methods
+
+ActiveHash objects implement enough of the ActiveRecord api to satisfy most common needs.  For example:
+
+    Country#id          # => returns the numeric id or nil
+    Country#quoted_id   # => returns the numeric id
+    Country#to_param    # => returns the id as a string
+    Country#new_record? # => false
+    Country#readonly?   # => true
+    Country#hash        # => the hash of the id (or the hash of nil)
+    Country#eql?        # => compares type and id, returns false if id is nil
+
+ActiveHash also gives you methods related to the fields you defined.  For example, if you defined :name as a field, you'd get:
+
+    Country#name        # => returns the passed in name
+    Country#name?       # => returns true if the name is not blank
+
+## Integration with Rails
+
+You can create .belongs_to associations from rails objects, like so:
+
+    class Country < ActiveHash::Base
+    end
+
+    class Person < ActiveRecord::Base
+      belongs_to :country
+    end
+
+You can also use standard rails view helpers, like #collection_select:
+
+    <%= collection_select :person, :country_id, Country.all, :id, :name %>
+
+## ActiveYaml
+
+If you want to store your data in YAML files, just inherit from ActiveYaml and specify your path information:
+
+    class Country < ActiveYaml::Base
+    end
+
+By default, this class will look for a yml file named "countries.yml" in the same directory as the file.  You can either change the directory it looks in, the filename it looks for, or both:
+
+    class Country < ActiveYaml::Base
+      set_root_path "/u/data"
+      set_filename "sample"
+    end
+
+The above example will look for the file "/u/data/sample.yml".
+
+ActiveYaml, as well as ActiveFile, check the mtime of the file you specified, and reloads the data if the mtime has changed.  So you can replace the data in the files even if your app is running in production mode in rails.
+
+Since ActiveYaml just creates a hash from the YAML file, you will have all fields specified in YAML auto-defined for you once you call all.
+
+## ActiveFile
+
+If you store encrypted data, or you'd like to store your flat files as CSV or XML or any other format, you can easily extend ActiveHash to parse and load your file.  Just add a custom ::load_file method, and define the extension you want the file to use:
+
+    class Country < ActiveFile::Base
+      set_root_path "/u/data"
+      set_filename "sample"
+
+      class << self
+        def extension
+          ".super_secret"
+        end
+
+        def load_file
+          MyAwesomeDecoder.load_file(full_path)
+        end
+      end
+    end
+
+The two methods you need to implement are load_file, which needs to return an array of hashes, and .extension, which returns the file extension you are using.  You have full_path available to you if you wish, or you can provide your own path.
+
+Setting the default file location in Rails:
+
+    # config/initializers/active_file.rb
+    ActiveFile.set_root_path "config/activefiles"
+
+By default, ActiveFile will not reload data from the file when it changes.  You can enable this by setting:
+
+    ActiveFile.reload_active_file = true
+
+In Rails, in development mode, it reloads the entire class, which reloads the file, so you don't need to turn this on in development.
+
+NOTE:  By default, .full_path refers to the current working directory.  In a rails app, this will be RAILS_ROOT.
+
+## Authors
+
+Written by Jeff Dean, Mike Dalessio and Ben Woosley 
+
+## Development
+
+The only thing I think I'd really like to add here is support for typecasting the fields.
+
+== Copyright
+
+Copyright (c) 2009 Jeff Dean. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,49 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "active_hash"
+    gem.summary = %Q{An ActiveRecord-like model that uses a hash as a datasource}
+    gem.email = "jeff@zilkey.com"
+    gem.homepage = "http://github.com/zilkey/active_hash"
+    gem.authors = ["Jeff Dean", "Mike Dalessio", "Corey Innis", "Peter Jaros"]
+    gem.add_dependency('activesupport')
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "active_hash #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.6.1

data/active_hash.gemspec

@@ -0,0 +1,59 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{active_hash}
+  s.version = "0.6.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Jeff Dean", "Mike Dalessio", "Corey Innis", "Peter Jaros"]
+  s.date = %q{2009-08-19}
+  s.email = %q{jeff@zilkey.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.md"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "CHANGELOG",
+     "LICENSE",
+     "README.md",
+     "Rakefile",
+     "VERSION",
+     "active_hash.gemspec",
+     "lib/active_file/base.rb",
+     "lib/active_hash.rb",
+     "lib/active_hash/base.rb",
+     "lib/active_yaml/base.rb",
+     "spec/active_file/base_spec.rb",
+     "spec/active_hash/base_spec.rb",
+     "spec/active_yaml/base_spec.rb",
+     "spec/active_yaml/sample.yml",
+     "spec/spec_helper.rb"
+  ]
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/zilkey/active_hash}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{An ActiveRecord-like model that uses a hash as a datasource}
+  s.test_files = [
+    "spec/active_file/base_spec.rb",
+     "spec/active_hash/base_spec.rb",
+     "spec/active_yaml/base_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<activesupport>, [">= 0"])
+    else
+      s.add_dependency(%q<activesupport>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<activesupport>, [">= 0"])
+  end
+end

data/lib/active_file/base.rb

@@ -0,0 +1,60 @@
+module ActiveFile
+
+  class Base < ActiveHash::Base
+    class_inheritable_accessor :filename, :root_path, :cached_mtime, :reload_active_file, :data_has_been_set
+
+    class << self
+      def all
+        reload
+        super
+      end
+
+      def reload(force = false)
+        if force || should_reload?
+          self.data = load_file
+        end
+      end
+
+      def data=(array_of_hashes)
+        write_inheritable_attribute :data_has_been_set, true
+        super
+      end
+
+      def set_filename(name)
+        write_inheritable_attribute :filename, name
+      end
+
+      def set_root_path(path)
+        write_inheritable_attribute :root_path, path
+      end
+
+      def load_file
+        raise "Override Me"
+      end
+
+      def full_path
+        root_path = read_inheritable_attribute(:root_path)  || Dir.pwd
+        filename  = read_inheritable_attribute(:filename)   || name.tableize
+        File.join(root_path, "#{filename}.#{extension}")
+      end
+
+      def should_reload?
+        return false if read_inheritable_attribute(:data_has_been_set) && ! read_inheritable_attribute(:reload_active_file)
+        return false if (mtime = File.mtime(full_path)) == read_inheritable_attribute(:cached_mtime)
+
+        write_inheritable_attribute :cached_mtime, mtime
+        true
+      end
+
+      private :should_reload?
+
+      def extension
+        raise "Override Me"
+      end
+
+      protected :extension
+
+    end
+  end
+
+end

data/lib/active_hash.rb

@@ -0,0 +1,5 @@
+require 'rubygems'
+require 'activesupport'
+require 'active_hash/base'
+require 'active_file/base'
+require 'active_yaml/base'

data/lib/active_hash/base.rb

@@ -0,0 +1,188 @@
+module ActiveHash
+  class Base
+    class_inheritable_accessor :data
+    class << self
+      attr_reader :field_names
+
+      def data=(array_of_hashes)
+        @records = nil
+        write_inheritable_attribute(:data, array_of_hashes)
+      end
+
+      def all
+        unless @records
+          records = read_inheritable_attribute(:data) || []
+          @records = records.collect {|hash| new(hash)}
+          auto_assign_fields( records )
+        end
+        @records
+      end
+
+      def count
+        all.length
+      end
+
+      def find(id, *args)
+        case id
+          when :all
+            all
+          when Array
+            all.select {|record| id.map(&:to_i).include?(record.id) }
+          else
+            find_by_id(id)
+        end
+      end
+
+      def find_by_id(id)
+        all.detect {|record| record.id == id.to_i}
+      end
+
+      delegate :first, :last, :to => :all
+
+      def fields(*args)
+        options = args.extract_options!
+        args.each do |field|
+          field(field, options)
+        end
+      end
+
+      def field(field_name, options = {})
+        @field_names ||= []
+        @field_names << field_name
+
+        define_getter_method(field_name, options[:default])
+        define_interrogator_method(field_name)
+        define_custom_find_method(field_name)
+        define_custom_find_all_method(field_name)
+      end
+
+      def respond_to?(method_name)
+        super ||
+          begin
+            config = configuration_for_custom_finder(method_name)
+            config && config[:fields].all? { |field| field_names.include?(field.to_sym) }
+          end
+      end
+
+      def method_missing(method_name, *args)
+        return super unless respond_to? method_name
+
+        config = configuration_for_custom_finder(method_name)
+        attribute_pairs = config[:fields].zip(args)
+        matches = all.select { |base| attribute_pairs.all? { |field, value| base.send(field) == value } }
+        config[:all?] ? matches : matches.first
+      end
+
+      def configuration_for_custom_finder(finder_name)
+        if finder_name.to_s.match(/^find_(all_)?by_(.*)/)
+          {
+            :all?   => !!$1,
+            :fields => $2.split('_and_')
+          }
+        end
+      end
+
+      def define_getter_method(field, default_value)
+        unless instance_methods.include?(field.to_s)
+          define_method(field) do
+            attributes[field] || default_value
+          end
+        end
+      end
+
+      private :define_getter_method
+
+      def define_interrogator_method(field)
+        method_name = "#{field}?"
+        unless instance_methods.include?(method_name)
+          define_method(method_name) do
+            attributes[field].present?
+          end
+        end
+      end
+
+      private :define_interrogator_method
+
+      def define_custom_find_method(field_name)
+        method_name = "find_by_#{field_name}"
+        unless singleton_methods.include?(method_name)
+          metaclass.instance_eval do
+            define_method(method_name) do |name|
+              all.detect {|record| record.send(field_name) == name }
+            end
+          end
+        end
+      end
+
+      private :define_custom_find_method
+
+      def define_custom_find_all_method(field_name)
+        method_name = "find_all_by_#{field_name}"
+        unless singleton_methods.include?(method_name)
+          metaclass.instance_eval do
+            unless singleton_methods.include?(method_name)
+              define_method(method_name) do |name|
+                all.select {|record| record.send(field_name) == name }
+              end
+            end
+          end
+        end
+      end
+
+      private :define_custom_find_all_method
+
+      def auto_assign_fields(array_of_hashes)
+        array_of_hashes.inject([]) do |array, row|
+          row.symbolize_keys!
+          row.keys.each do |key|
+            unless key.to_s == "id"
+              array << key
+            end
+          end
+          array
+        end.uniq.each do |key|
+          field key
+        end
+      end
+
+      private :auto_assign_fields
+
+    end
+
+    attr_reader :attributes
+
+    def initialize(options = {})
+      options.symbolize_keys!
+      @attributes = options
+    end
+
+    def id
+      attributes[:id] ? attributes[:id].to_i : nil
+    end
+
+    alias quoted_id id
+
+    def new_record?
+      false
+    end
+
+    def readonly?
+      true
+    end
+
+    def to_param
+      id.to_s
+    end
+
+    def eql?(other)
+      other.instance_of?(self.class) and not id.nil? and (id == other.id)
+    end
+
+    alias == eql?
+
+    def hash
+      id.hash
+    end
+
+  end
+end