plain_record 0.1 → 0.2

data/.gitignore

@@ -0,0 +1,8 @@
+*.DS_Store
+*~
+
+.yardoc/
+doc/
+pkg/
+
+.bundle

data/.rspec

@@ -0,0 +1 @@
+--format documentation --colour

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - ruby-head
+  - jruby-18mode
+  - rbx-18mode

data/.yardopts

@@ -0,0 +1,4 @@
+--charset utf-8
+-
+README.md
+ChangeLog

data/ChangeLog

@@ -0,0 +1,9 @@
+== 0.2 (Smallpox)
+* Add associations.
+* Add special syntax for virtual properties.
+* Add properties from entry file name.
+* Add before/after callbacks.
+* Add support for models with all entries in one file.
+
+== 0.1 (Plague)
+* Initial release

data/Gemfile

@@ -0,0 +1,6 @@
+source :rubygems
+
+gem 'rake'
+gem 'yard'
+gem 'rspec'
+gem 'redcarpet'

data/Gemfile.lock

@@ -0,0 +1,24 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.3)
+    rake (0.9.2.2)
+    redcarpet (2.1.1)
+    rspec (2.10.0)
+      rspec-core (~> 2.10.0)
+      rspec-expectations (~> 2.10.0)
+      rspec-mocks (~> 2.10.0)
+    rspec-core (2.10.0)
+    rspec-expectations (2.10.0)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.10.1)
+    yard (0.8.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rake
+  redcarpet
+  rspec
+  yard

data/LICENSE

@@ -1,4 +1,4 @@
-		   GNU LESSER GENERAL PUBLIC LICENSE
+                   GNU LESSER GENERAL PUBLIC LICENSE
                        Version 3, 29 June 2007
 
  Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
@@ -10,7 +10,7 @@
 the terms and conditions of version 3 of the GNU General Public
 License, supplemented by the additional permissions listed below.
 
-  0. Additional Definitions. 
+  0. Additional Definitions.
 
   As used herein, "this License" refers to version 3 of the GNU Lesser
 General Public License, and the "GNU GPL" refers to version 3 of the GNU
@@ -111,7 +111,7 @@ the following:
        a copy of the Library already present on the user's computer
        system, and (b) will operate properly with a modified version
        of the Library that is interface-compatible with the Linked
-       Version. 
+       Version.
 
    e) Provide Installation Information, but only if you would otherwise
    be required to provide such information under section 6 of the
@@ -163,4 +163,3 @@ whether future versions of the GNU Lesser General Public License shall
 apply, that proxy's public statement of acceptance of any version is
 permanent authorization for you to choose that version for the
 Library.
-

data/README.md

@@ -0,0 +1,124 @@
+# Plain Record
+
+Plaint Record is a data persistence, which use human editable and readable plain
+text files. It’s ideal for static generated sites, like blog or homepage.
+
+If you want to write another static website generator, you don’t need to write
+another file parser – you can use Plain Record.
+
+## How To
+
+For example we will create simple blog storage with posts and comments.
+
+1. Add Plain Record to your application Gemfile:
+
+     ```ruby
+    gem "plain_record"
+     ```
+
+2. Set storage root – dir, which will contain all data files:
+
+     ```ruby
+    PlainRecord.root = 'data/'
+     ```
+
+3. Create Post class, include `Plain::Resource` module, set glob pattern
+   to posts files and define properties:
+
+     ```ruby
+    class Post
+      include Plain::Resource
+
+      entry_in '*/post.md'
+
+      virtual  :name,     in_filepath(1)
+      virtual  :comments, many(Comment)
+      property :title
+      property :tags
+      text     :summary
+      text     :content
+    end
+     ```
+
+4. Create new post file `data/first/post.md`. Properties will be saved as
+   YAML and text will be placed as plain text, which is separated by 3 dashes:
+
+     ```
+    title: My first post
+    tags: test, first
+    ---
+    It is short post summary.
+    ---
+    And this is big big post text.
+    In several lines.
+     ```
+
+5. Also you can use files with list of entries. For example, comments:
+
+     ```ruby
+    class Comment
+      include Plain::Resource
+
+      list_in '*/comments.yml'
+
+      virtual  :post_name, in_filepath(1)
+      virtual  :post,      one(Post)
+      property :author
+      property :comment
+    end
+     ```
+   You can’t use text fields in list files.
+6. List files is a just YAML array. For example, `data/first/comments.yml`:
+
+     <pre><code>\- author: Anonymous
+      comment: I like it!
+   \- author: Friend
+      comment: You first post it shit.</pre></code>
+
+7. Get all post:
+
+     ```ruby
+    Post.all # will return array with our first post
+     ```
+
+8. Get specify enrties:
+
+     ```ruby
+    Comment.all(author: 'Anonymous')
+    Post.all(title: /first/)
+    Post.all { |i| i.tags.length == 2 }
+     ```
+
+9. To get one entry use `first` method, which also can take matchers. You can
+   access for properties and text by methods with same name:
+
+     ```ruby
+    post = Post.first(title: /first/)
+    post.file    #=> "data/first/post.md"
+    post.name    #=> "first"
+    post.title   #=> "My first post"
+    post.tags    #=> ["test", "first"]
+    post.summary #=> "It is short post summary."
+     ```
+
+10. You can also change and save entries:
+
+      ```ruby
+    post.title = 'First post'
+    post.save
+      ```
+
+11. And delete it (with empty dirs in it file path):
+
+      ```ruby
+    post.destroy
+      ```
+
+## License
+
+Plain Record is licensed under the GNU Lesser General Public License version 3.
+See the LICENSE file or http://www.gnu.org/licenses/lgpl.html.
+
+## Author
+
+Andrey “A.I.” Sitnik <andrey@sitnik.ru> 

data/Rakefile

@@ -1,57 +1,34 @@
 # encoding: utf-8
-gem 'rspec'
-require 'spec/rake/spectask'
-require 'rake/rdoctask'
-require 'rake/gempackagetask'
-
-Spec::Rake::SpecTask.new('spec') do |t|
-  t.spec_opts = ['--format', 'specdoc', '--colour']
-  t.spec_files = Dir['spec/**/*_spec.rb'].sort
-end
 
-Rake::RDocTask.new do |rdoc|
-  rdoc.main = 'README.rdoc'
-  rdoc.rdoc_files.include('*.rdoc', 'lib/**/*.rb')
-  rdoc.title = 'Plain Record'
-  rdoc.rdoc_dir = 'doc'
-  rdoc.options << '--charset=utf-8'
-  rdoc.options << '--all'
-  rdoc.options << '--inline-source'
+require 'rubygems'
+
+begin
+  require 'bundler/setup'
+  Bundler::GemHelper.install_tasks
+rescue LoadError
+  puts "Bundler not available. Install it with: gem install bundler"
 end
 
-require File.join(File.dirname(__FILE__), 'lib', 'plain_record', 'version')
-
-spec = Gem::Specification.new do |s|
-  s.platform = Gem::Platform::RUBY
-  s.name = 'plain_record'
-  s.version = PlainRecord::VERSION
-  s.summary = 'Data persistence, which use human editable and ' +
-              'readable plain text files.'
-  s.description = <<-DESC
-      Plain Record is a data persistence, which use human editable and readable
-      plain text files. It’s ideal for static generated sites, like blog or
-      homepage.
-    DESC
-  
-  s.files = FileList[
-    'lib/**/*',
-    'spec/**/*',
-    'Rakefile',
-    'LICENSE',
-    'README.rdoc']
-  s.test_files = FileList['spec/**/*']
-  s.extra_rdoc_files = ['README.rdoc', 'LICENSE']
-  s.require_path = 'lib'
-  s.has_rdoc = true
-  s.rdoc_options << '--title "Plain Record"' << '--main README.rdoc' <<
-                    '--charset=utf-8' << '--all' << '--inline-source'
-  
-  s.author = 'Andrey "A.I." Sitnik'
-  s.email = 'andrey@sitnik.ru'
-  s.homepage = 'http://github.com/ai/plain_record'
-  s.rubyforge_project = 'plainrecord'
+require File.join(File.dirname(__FILE__), 'lib/plain_record/version')
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new
+
+require 'yard'
+YARD::Rake::YardocTask.new do |yard|
+  yard.options << "--title='Plain Record #{PlainRecord::VERSION}'"
 end
 
-Rake::GemPackageTask.new(spec) do |pkg|
-  pkg.gem_spec = spec
+task :clobber_doc do
+  rm_r 'doc'     rescue nil
+  rm_r '.yardoc' rescue nil
+end
+task :clobber_package do
+  rm_r 'pkg' rescue nil
 end
+
+desc 'Delete all generated files'
+task :clobber => [:clobber_package, :clobber_doc]
+
+task :default => :spec

data/lib/plain_record/association_proxy.rb

@@ -0,0 +1,59 @@
+=begin
+Storage for one-to-many virtual associations.
+
+Copyright (C) 2009 Andrey “A.I.” Sitnik <andrey@sitnik.ru>
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser 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 Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+=end
+
+module PlainRecord
+  # Storage for one-to-many virtual associations. When new object will pushed,
+  # proxy change it mapped properties.
+  class AssociationProxy < Array
+    # Model with association.
+    attr_accessor :owner
+
+    # Associations property name.
+    attr_accessor :property
+
+    # Create proxy for one-to-many virtual associations +property+ in +owner+
+    # and put +array+ into it.
+    def self.link(array, owner, property)
+      proxy = new(array, owner, property)
+      proxy.each { |i| proxy.link(i) }
+      proxy
+    end
+
+    # Create proxy for one-to-many virtual associations +property+ in +owner+
+    # with +array+ in value.
+    def initialize(array, owner, property)
+      @owner = owner
+      @property = property
+      super(array)
+    end
+
+    # Push new item in association and change it property by association map.
+    def <<(obj)
+      link(obj)
+      super(obj)
+    end
+
+    # Change properties in +obj+ by association map.
+    def link(obj)
+      @owner.class.association_maps[@property].each do |from, to|
+        obj.send(from.to_s + '=', @owner.send(to))
+      end
+    end
+  end
+end

data/lib/plain_record/associations.rb

@@ -0,0 +1,271 @@
+=begin
+Extention to store or have link to another model.
+
+Copyright (C) 2009 Andrey “A.I.” Sitnik <andrey@sitnik.ru>
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser 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 Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+=end
+
+module PlainRecord
+  # Extention for model to store or have link to another model. There is two
+  # type of association.
+  #
+  # == Virtual property
+  # In +virtual+ method this definer create only _link_ to another model. When
+  # you try to use this virtual property, model will find association object by
+  # rules in +map+.
+  #
+  # Rules in +map+ is only Hash with model properties in key and association
+  # properties in value. For example, if model contain +name+ property and
+  # association must have +post_name+ with same value, +map+ will be 
+  # <tt>{ :name => :post_name }</tt>.
+  #
+  # If you didn’t set +map+ definer will try to find it automatically:
+  # it will find in model and association class all property pairs, what have
+  # name like +property+ → <tt>model</tt>_<tt>property</tt>. For example,
+  # if model +Post+ have property +name+ and +Comment+ have +post_name+, you
+  # may not set +map+ – definer will find it automatically.
+  #
+  #   class Review
+  #     include PlainRecord::Resource
+  #
+  #     entry_in 'reviews/*.md'
+  #
+  #     virtual  :author, one(Author)
+  #     property :author_login
+  #     text     :review
+  #   end
+  #
+  #   class Author
+  #     include PlainRecord::Resource
+  #
+  #     list_in 'authors.yml'
+  #
+  #     virtual  :reviews, many(Review)
+  #     property :login
+  #     property :name
+  #   end
+  #
+  # == Real property
+  # If you will use this definer in +property+ method, association object data
+  # will store in you model file. For example model:
+  #
+  #   class Movie
+  #     include PlainRecord::Resource
+  #
+  #     property :title
+  #     property :genre
+  #     property :release_year
+  #   end
+  #
+  #   class Tag
+  #     include PlainRecord::Resource
+  #     property :name
+  #   end
+  #
+  #   class Review
+  #     include PlainRecord::Resource
+  #
+  #     entry_in 'reviews/*.md'
+  #
+  #     property :author
+  #     property :movie, one(Movie)
+  #     property :tags, many(Tag)
+  #     text     :review
+  #   end
+  #
+  # will be store as:
+  #
+  #   author: John Smith 
+  #   movie:
+  #     title: Watchmen
+  #     genre: action
+  #     release_year: 2009
+  #   tags:
+  #   - name: Great movies
+  #   - name: Comics
+  #   ---
+  #   Movie is great!
+  module Associations
+    # Hash with map for virtual associations.
+    attr_accessor :association_maps
+
+    # Hash with cached values for virtual associations.
+    attr_accessor :association_cache
+
+    private
+
+    # Return definer for one-to-one association with +klass+. Have different
+    # logic in +property+ and +virtual+ methods.
+    def one(klass, map = { })
+      proc do |property, caller|
+        if :property == caller
+          Associations.define_real_one(self, property, klass)
+          :accessor
+        elsif :virtual == caller
+          map = Associations.map(self, klass, "#{property}_") if map.empty?
+          Associations.define_link_one(self, klass, property, map)
+          nil
+        else
+          raise ArgumentError, "You couldn't create association property" +
+                               " #{property} by text creator"
+        end
+      end
+    end
+
+    # Return definer for one-to-many or many-to-many association with +klass+.
+    # Have different login in +property+ and +virtual+ methods.
+    def many(klass, prefix = nil, map = { })
+      proc do |property, caller|
+        if :property == caller
+          Associations.define_real_many(self, property, klass)
+          :accessor
+        elsif :virtual == caller
+          unless prefix
+            prefix = self.to_s.gsub!(/[A-Z]/, '_\0')[1..-1].downcase + '_'
+          end
+          map = Associations.map(klass, self, prefix) if map.empty?
+          Associations.define_link_many(self, klass, property, map)
+          nil
+        else
+          raise ArgumentError, "You couldn't create association property" +
+                               " #{property} by text creator"
+        end
+      end
+    end
+
+    class << self
+      # Define, that +property+ in +klass+ contain in file data from +model+.
+      def define_real_one(klass, property, model)
+        name = property.to_s
+        klass.after :load do |result, entry|
+          entry.data[name] = model.new(entry.file, entry.data[name])
+          result
+        end
+        klass.before :save do |entry|
+          model.call_before_callbacks(:save, [entry.data[name]])
+          entry.data[name] = entry.data[name]
+        end
+        klass.after :save do |result, entry|
+          entry.data[name] = model.new(entry.file, entry.data[name])
+          model.call_after_callbacks(:save, nil, [entry.data[name]])
+          result
+        end
+      end
+
+      # Define, that +property+ in +klass+ contain in file array of data from
+      # +model+ objects.
+      def define_real_many(klass, property, model)
+        name = property.to_s
+        klass.after :load do |result, entry|
+          if entry.data[name].is_a? Enumerable
+            entry.data[name].map! { |i| model.new(entry.file, i) }
+          else
+            entry.data[name] = []
+          end
+          result
+        end
+        klass.before :save do |entry|
+          if entry.data[name].empty?
+            entry.data.delete(name)
+          else
+            entry.data[name].map! do |obj|
+              model.call_before_callbacks(:save, [obj])
+              obj.data
+            end
+          end
+        end
+        klass.after :save do |result, entry|
+          entry.data[name].map! { |i| model.new(entry.file, i) }
+          entry.data[name].each do |i|
+            model.call_after_callbacks(:save, nil, [i])
+          end
+          result
+        end
+      end
+
+      # Find properties pairs in +from+ and +to+ models, witch is like
+      # <tt>prefix</tt>_<tt>from</tt> → +to+.
+      #
+      # For example, if Comment contain +post_name+ property and Post contain
+      # +name+:
+      #
+      #   Associations.map(Comment, Post, :post) #=> { :post_name => :name }
+      def map(from, to, prefix)
+        from_fields = (from.properties + from.virtuals).map { |i| i.to_s }
+        mapped = { }
+        (to.properties + to.virtuals).each do |to_field|
+          from_field = prefix + to_field.to_s
+          if from_fields.include? from_field
+            mapped[from_field.to_sym] = to_field
+          end
+        end
+        mapped
+      end
+
+      # Define that virtual property +name+ in +klass+ contain link to +model+
+      # witch is finded by +map+.
+      def define_link_one(klass, model, name, map)
+        klass.association_cache ||= { }
+        klass.association_maps  ||= { }
+        klass.association_maps[name] = map
+
+        klass.class_eval <<-EOS, __FILE__, __LINE__
+          def #{name}
+            unless self.class.association_cache[:#{name}]
+              search = Hash[
+                self.class.association_maps[:#{name}].map do |from, to|
+                  [to, send(from)]
+                end]
+              self.class.association_cache[:#{name}] = #{model}.first(search)
+            end
+            self.class.association_cache[:#{name}]
+          end
+          def #{name}=(value)
+            self.class.association_maps[:#{name}].each do |from, to|
+              value.send(to.to_s + '=', send(from))
+            end
+            self.class.association_cache[:#{name}] = value
+          end
+        EOS
+      end
+
+      # Define that virtual property +name+ in +klass+ contain links to +model+
+      # witch are finded by +map+.
+      def define_link_many(klass, model, name, map)
+        klass.association_cache ||= { }
+        klass.association_maps  ||= { }
+        klass.association_maps[name] = map
+
+        klass.class_eval <<-EOS, __FILE__, __LINE__
+          def #{name}
+            unless self.class.association_cache[:#{name}]
+              search = Hash[
+                self.class.association_maps[:#{name}].map do |from, to|
+                  [from, send(to)]
+                end]
+              self.class.association_cache[:#{name}] = AssociationProxy.new(
+                  #{model}.all(search), self, :#{name})
+            end
+            self.class.association_cache[:#{name}]
+          end
+          def #{name}=(values)
+            self.class.association_cache[:#{name}] = AssociationProxy.link(
+                values, self, :#{name})
+          end
+        EOS
+      end
+    end
+  end
+end