yaml_record 0.0.1 → 0.0.2

data/README.md

@@ -2,74 +2,174 @@
 
 ## Introduction ##
 
-YAML Record allows you to persist data to a yaml file and manage it with activemodel API
+YAML Record is a data persistence library that complies with the ActiveModel API. Using YAMLRecord should be familiar to anyone that has used ActiveRecord before to manage your database. Using this library, the data is persisted in a YAML backed file.
+
+## Rationale ##
+
+*Why a YAML-based persistence store?* In certain situations, there are collections of simple data in which there are very few records which are by nature infrequently accessed and that are ideally able to be scanned easily within a text file. These can include a simple contact form, landing page interest, feedback forms, surveys, team pages, etc where there is simply no need for the overhead of a fully persisted database solution.
+
+There are many cases where YAMLRecord is **not the correct** persistence strategy. Any collection that is going to have substantial number of records, will be frequently updated, or is accessible by a large volume of users should not be stored in a YAML text file for obvious reasons. However, for specific cases, the convenience of storing things in a simple text file becomes apparent. Being able to access the text file data as if the records were in a familiar database ORM has many conveniences and advantages such as keeping the controllers standard and leveraging existing ORM knowledge.
 
 ## Installation ##
 
+Install using rubygems:
+
     gem install yaml_record
-    
-## Usage ##
 
-To use YAML Record add gem to your Gemfile
+Or add gem to your Gemfile:
 
     # Gemfile
     gem 'yaml_record'
-    
-Next define your YAML Record class 
-    
-    class Post < YamlRecord::Base
-      # Declare your properties
-      properties :title, :body, :user_id
-      
-      # Declare source file path
-      source Rails.root.join("config/posts")
-    end
-    
-Use as any activerecord object.
-
-Retrieve all items:
+
+## Usage ##
+
+### Declaration ###
+
+Create any ruby object and inherit from `YamlRecord:Base` to define a type:
+
+```ruby
+class Post < YamlRecord::Base
+  # Declare your properties
+  properties :title, :body, :user_id
+
+  # Declare source file path
+  source Rails.root.join("config/posts")
+end
+```
+
+Use this new object the same way as any ActiveRecord object.
+
+### Retrieval ###
+
+Retrieve the collection:
 
     Post.all => [@p1, @p2]
-    
-Retrieve item by ID:
+
+Retrieve item by id:
 
     Post.find("a1b2") => @p1
-    
-Retrieve by attribute
+
+Retrieve by attribute:
 
     Post.find_by_attribute(:title, "some title") => @p
-    
+
+### Create ###
+
 Initialize post:
 
     @p = Post.new(:title => "...", :body => "...", :user_id => 5)
-    
-Save post:
-
     @p.save
-    # or Post.create(:title => "...", :body => "...", :user_id => 5)
-    
-Access attributes
+
+Create post:
+
+    @p = Post.create(:title => "...", :body => "...", :user_id => 6)
+
+### Update ###
+
+Update attributes using the expected method:
+
+    @p.update_attributes(:title => "new title")
+
+### Destroy ###
+
+Destroy a given record:
+
+    @p.destroy
+
+### Access ###
+
+Access attributes:
 
     @p = Post.find("a1b2")
     @p.title => "..."
-    
-Assign attributes 
+
+Assign attributes:
 
     @p.title = "new title"
+    @p.save
 
-Update attributes
+### Callbacks ###
 
-    @p.update_attributes(:title => "new title")
-    
-Destroy record
+Create callbacks:
 
-    @p.destroy
+```ruby
+class Submission < YamlRecord::Base
+  # ...
+  before_create :do_something # or before_save, before_destroy, ...
+
+  def do_something
+    # something here
+  end
+end
+```
+
+## Example ##
+
+Imagine a simple contact form that accepts a name and email from a user along with a body:
+
+```ruby
+class Submission < YamlRecord::Base
+  # Declare your properties
+  properties :name, :email, :body
+
+  # Declare source file path (config/contact.yml)
+  source Rails.root.join("config/contact")
+end
+```
+
+Once we define the Contact model, we can setup a controller and form just the same as in ActiveRecord:
+
+```ruby
+class SubmissionsController < AC::Base
+  def create
+    @submission = Submission.create(params[:submission])
+  end
+
+  def index
+    @submissions = Submission.all
+  end
+
+  def show
+    @submission = Submission.find(params[:id])
+  end
+
+  def update
+    @submission = Submission.find(params[:id])
+    @submission.update_attributes(params[:submission])
+  end
+
+  def destroy
+    @submission = Submission.find(params[:id])
+    @submission.destroy
+  end
+end
+```
+
+As you can see the controller appears the same as any ActiveRecord controller would and this makes managing the YAML data easy and convenient. You can even define callbacks in your object as you would in ActiveRecord:
+
+```ruby
+class Submission < YamlRecord::Base
+  # ...
+  before_create :do_something # or before_save, before_destroy, ...
+
+  def do_something
+    # something here
+  end
+end
+```
+
+And that's all! Each record will be persisted to the source file for easy access.
+
+## Issues ##
+
+ * Validations should be supported `validates_presence_of :name`
+ * Property type declarations should be available `property :age, Integer`
 
 ## Contributors ##
 
 Created at Miso by Nico Taing and Nathan Esquenazi
 
-Contributors are welcome!
+Contributors and patches are welcome! Please send a pull request!
 
 ## License ##
 

data/lib/yaml_record/base.rb

@@ -1,17 +1,17 @@
 module YamlRecord
-  class Base  
-    attr_accessor :attributes, :is_created, :is_destroyed 
-    
+  class Base
+    attr_accessor :attributes, :is_created, :is_destroyed
+
     include ActiveSupport::Callbacks
     define_callbacks :before_save, :after_save, :before_destroy, :after_destroy, :before_validation, :before_create, :after_create
-    
+
     before_create :set_id!
 
     # Constructs a new YamlRecord instance based on specified attribute hash
     #
     # === Example:
     #
-    #   class Post < YamlRecord::Base; properties :foo; end 
+    #   class Post < YamlRecord::Base; properties :foo; end
     #
     #   Post.new(:foo  => "bar")
     #
@@ -21,14 +21,13 @@ module YamlRecord
 
       self.attributes ||= {}
       self.is_created = attr_hash.delete(:persisted) || false
-      self.setup_properties!
       attr_hash.each do |k,v|
         self.send("#{k}=", v) # self.attributes[:media] = "foo"
       end
     end
 
     # Accesses given attribute from YamlRecord instance
-    # 
+    #
     # === Example:
     #
     #   @post[:foo] => "bar"
@@ -38,7 +37,7 @@ module YamlRecord
     end
 
     # Assign given attribute from YamlRecord instance with specified value
-    # 
+    #
     # === Example:
     #
     #   @post[:foo] = "baz"
@@ -50,7 +49,7 @@ module YamlRecord
     # Saved YamlRecord instance to file
     # Executes save and create callbacks
     # Returns true if record saved; false otherwise
-    # 
+    #
     # === Example:
     #
     #   @post.save => true
@@ -61,7 +60,7 @@ module YamlRecord
 
       existing_items = self.class.all
       if self.new_record?
-        existing_items << self 
+        existing_items << self
       else # update existing record
         updated_item = existing_items.find { |item| item.id == self.id }
         return false unless updated_item
@@ -69,7 +68,7 @@ module YamlRecord
       end
 
       raw_data = existing_items ? existing_items.map { |item| item.persisted_attributes } : []
-      self.class.write_contents(raw_data) if self.valid? 
+      self.class.write_contents(raw_data) if self.valid?
 
       run_callbacks(:after_create) unless self.is_created
       run_callbacks(:after_save)
@@ -77,10 +76,10 @@ module YamlRecord
     rescue IOError
       false
     end
-    
+
     # Update YamlRecord instance with specified attributes
     # Returns true if record updated; false otherwise
-    # 
+    #
     # === Example:
     #
     #   @post.update_attributes(:foo  => "baz", :miso => "awesome") => true
@@ -89,9 +88,9 @@ module YamlRecord
       updated_attrs.each { |k,v| self.send("#{k}=", v) }
       self.save
     end
-    
+
     # Returns array of instance attributes names; An attribute is a value stored for this record (persisted or not)
-    # 
+    #
     # === Example:
     #
     #   @post.column_names => ["foo", "miso"]
@@ -101,22 +100,22 @@ module YamlRecord
       self.attributes.each_key { |k| array << k.to_s }
       array
     end
-    
+
     # Returns hash of attributes to be persisted to file.
     # A persisted attribute is a value stored in the file (specified with the properties declaration)
-    # 
+    #
     # === Example:
     #
-    #   class Post < YamlRecord::Base; properties :foo, :miso; end 
+    #   class Post < YamlRecord::Base; properties :foo, :miso; end
     #   @post = Post.create(:foo => "bar", :miso => "great")
     #   @post.persisted_attributes => { :id => "a1b2c3", :foo => "bar", :miso => "great" }
     #
     def persisted_attributes
       self.attributes.slice(*self.class.properties).reject { |k, v| v.nil? }
     end
-    
+
     # Returns true if YamlRecord instance hasn't persisted; false otherwise
-    # 
+    #
     # === Example:
     #
     #   @post = Post.new(:foo => "bar", :miso => "great")
@@ -129,7 +128,7 @@ module YamlRecord
     end
 
     # Returns true if YamlRecord instance has been destroyed; false otherwise
-    # 
+    #
     # === Example:
     #
     #   @post = Post.new(:foo => "bar", :miso => "great")
@@ -144,7 +143,7 @@ module YamlRecord
 
     # Remove a persisted YamlRecord object
     # Returns true if destroyed; false otherwise
-    # 
+    #
     # === Example:
     #
     #   @post = Post.create(:foo => "bar", :miso => "great")
@@ -162,11 +161,11 @@ module YamlRecord
     rescue IOError
       false
     end
-    
+
     # Execute validations for instance
     # Returns true if record is valid; false otherwise
     # TODO Implement validation
-    # 
+    #
     # === Example:
     #
     #   @post.valid? => true
@@ -174,10 +173,10 @@ module YamlRecord
     def valid?
       true
     end
-    
+
     # Returns errors messages if record isn't valid; empty array otherwise
     # TODO Implement validation
-    # 
+    #
     # === Example:
     #
     #   @post.errors => ["Foo can't be blank"]
@@ -185,10 +184,10 @@ module YamlRecord
     def errors
       []
     end
-    
+
     # Returns YamlRecord Instance
     # Complies with ActiveModel api
-    # 
+    #
     # === Example:
     #
     #   @post.to_model => @post
@@ -196,9 +195,9 @@ module YamlRecord
     def to_model
       self
     end
-    
+
     # Reload YamlRecord instance attributes from file
-    # 
+    #
     # === Example:
     #
     #   @post = Post.create(:foo => "bar", :miso => "great")
@@ -214,7 +213,7 @@ module YamlRecord
 
     # Find YamlRecord instance given attribute name and expected value
     # Returns instance if found; false otherwise
-    # 
+    #
     # === Example:
     #
     #   Post.find_by_attribute(:foo, "bar")  => @post
@@ -222,17 +221,17 @@ module YamlRecord
     def self.find_by_attribute(attribute, expected_value)
       self.all.find do |record|
         value = record.send(attribute) if record.respond_to?(attribute)
-        value.is_a?(Array) ? 
+        value.is_a?(Array) ?
           value.include?(expected_value) :
           value == expected_value
       end
     end
-    
+
     class << self;
-      
+
       # Find YamlRecord instance given id
       # Returns instance if found; false otherwise
-      # 
+      #
       # === Example:
       #
       #   Post.find_by_id("a1b2c3")  => @post
@@ -242,10 +241,10 @@ module YamlRecord
       end
       alias :find :find_by_id
     end
-    
+
     # Returns collection of all YamlRecord instances
     # Caches results during request
-    # 
+    #
     # === Example:
     #
     #   Post.all  => [@post1, @post2, ...]
@@ -259,7 +258,7 @@ module YamlRecord
 
     # Find last YamlRecord instance given a limit
     # Returns an array of instances if found; empty otherwise
-    # 
+    #
     # === Example:
     #
     #   Post.last  => @post6
@@ -271,7 +270,7 @@ module YamlRecord
 
     # Find first YamlRecord instance given a limit
     # Returns an array of instances if found; empty otherwise
-    # 
+    #
     # === Example:
     #
     #   Post.first  => @post
@@ -280,60 +279,66 @@ module YamlRecord
     def self.first(limit=1)
       limit == 1 ? self.all.first : self.all.first(limit)
     end
-    
+
     # Initializes YamlRecord instance given an attribute hash and saves afterwards
     # Returns instance if successfully saved; false otherwise
-    # 
+    #
     # === Example:
     #
     #   Post.create(:foo => "bar", :miso => "great")  => @post
     #
     def self.create(attributes={})
       @fs = self.new(attributes)
-      if @fs.save == true 
+      if @fs.save == true
         @fs.is_created = true;
         @fs
       else
         false
       end
     end
-    
+
     # Declares persisted attributes for YamlRecord class
-    # 
+    #
     # === Example:
     #
     #   class Post < YamlRecord::Base; properties :foo, :miso; end
     #   Post.create(:foo => "bar", :miso => "great")  => @post
     #
     def self.properties(*names)
-      names = names | [:id] if names.size > 0
-      names.size == 0 ? @_properties : @_properties = names
+      @_properties ||= []
+      if names.size == 0 # getter
+        @_properties
+      elsif names.size > 0 # setter
+        names = names | [:id]
+        setup_properties!(*names)
+        @_properties += names
+      end
     end
-    
+
     # Declares source file for YamlRecord class
-    # 
+    #
     # === Example:
     #
-    #   class Post < YamlRecord::Base 
+    #   class Post < YamlRecord::Base
     #     source "path/to/yaml/file"
     #   end
     #
     def self.source(file=nil)
       file ? @file = (file.to_s + ".yml") : @file
     end
-    
+
     protected
-    
+
     # Validates each persisted attributes
     # TODO Implement validation
     #
     def self.validates_each(*args, &block)
       true
     end
-    
+
     # Write raw yaml data to file
     # Protected method, not called during usage
-    # 
+    #
     # === Example:
     #
     #   Post.write_content([{ :foo => "bar"}, { :foo => "baz"}, ...]) # writes to source file
@@ -342,27 +347,26 @@ module YamlRecord
       File.open(self.source, 'w') {|f| f.write(raw_data.to_yaml) }
       @records = nil
     end
-    
+
     # Creates reader and writer methods for each persisted attribute
     # Protected method, not called during usage
-    # 
+    #
     # === Example:
     #
-    #   Post.setup_properties!
+    #   Post.setup_properties!(:foo)
     #   @post.foo = "baz"
     #   @post.foo => "baz"
     #
-    def setup_properties!
-     self.class.properties.each do |name|
-        self.class_eval do
-          define_method(name) { self[name.to_sym] }  # def media; self.attributes[:media]; end
-          define_method("#{name}=") { |val| self[name.to_sym] = val  }  # def media; self.attributes[:media]; end
-        end
+    def self.setup_properties!(*names)
+      names.each do |name|
+        define_method(name) { self[name.to_sym] }
+        define_method("#{name}=") { |val| self[name.to_sym] = val  }
       end
     end
-    
+
     # Assign YamlRecord a unique id if not set
     # Invoke before create of an instance
+    # Protected method, not called during usage
     #
     def set_id!
       self.id = ActiveSupport::SecureRandom.hex(15)

data/lib/yaml_record/version.rb

@@ -1,3 +1,3 @@
 module YamlRecord
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: yaml_record
 version: !ruby/object:Gem::Version 
-  hash: 29
+  hash: 27
   prerelease: 
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - Nico Taing
@@ -16,8 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-07-11 00:00:00 -07:00
-default_executable: 
+date: 2011-07-12 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: activesupport
@@ -86,7 +85,6 @@ files:
 - test/base_test.rb
 - test/test_helper.rb
 - yaml_record.gemspec
-has_rdoc: true
 homepage: https://github.com/nico-taing/yaml_record
 licenses: []
 
@@ -116,7 +114,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: yaml_record
-rubygems_version: 1.6.2
+rubygems_version: 1.7.2
 signing_key: 
 specification_version: 3
 summary: YAML file persistence engine