georgi-git_store 0.1 → 0.1.1

data/README.md

@@ -1,5 +1,5 @@
-GitStore - using Git as versioned data store in Ruby
-====================================================
+Git Store - using Git as versioned data store in Ruby
+=====================================================
 
 GitStore is a small Ruby library, providing an easy interface to the
 version control system [Git][1]. It aims to use Git as a versioned
@@ -7,16 +7,31 @@ data store much like the well known PStore. Basically GitStore checks
 out the repository into a in-memory representation, which can be
 modified and finally committed. In this way your data is stored in a
 folder structure and can be checked out and examined, but the
-application may access the data in a convenient hash-like way.
+application may access the data in a convenient hash-like way. This
+library is based on [Grit][2], the main technology behind [GitHub][3].
+
+
+## Installation
+
+GitStore can be installed as gem easily, if you have RubyGems 1.2.0:
+
+    $ gem sources -a http://gems.github.com you only have to do this once)
+    $ sudo gem install georgi-git_store
+
+If you don't have RubyGems 1.2.0, you may download the package on the
+[github page][4] and build the gem yourself:
+
+    $ gem build git_store.gemspec
+    $ sudo gem install git_store
 
-This library is based on [Grit][2], the main technology behind
-[GitHub][3].
 
 ## Usage Example
 
 First thing you should do, is to initialize a new git repository.
 
-    git init
+    $ mkdir test
+    $ cd test
+    $ git init
 
 Now you can instantiate a GitStore instance and store some data. The
 data will be serialized depending on the file extension. So for YAML
@@ -32,19 +47,34 @@ storage you can use the 'yml' extension:
 
     store.commit 'Added user and page'
 
-Note that direcories will be created automatically by using the path
-syntax. Same for multi arguments hash syntax:
+Note that directories will be created automatically.
+
+Another way to access a path is:
 
     store[config', 'wiki.yml'] = { 'name' => 'My Personal Wiki' }
 
-In this case the directory config is created automatically and
-the file wiki.yml contains be the YAML representation of the given Hash.
+Finally you can access the git store as a Hash of Hashes, but in this
+case you have to create the Tree objects manually:
+
+    store['users'] = GitStore::Tree.new
+    store['users']['matthias.yml'] = User.new('Matthias')
+
+## Where is my data?
+
+When you call the `commit` method, your data is written back straight
+into the git repository. No intermediate file representation. So if
+you want to look into your data, you can use some git browser like
+[git-gui][6] or just checkout the files:
+
+    $ git checkout
+
 
 ## Iteration
 
-Iterating over the stored datat is one of the common use cases, so
-this one is really easy and scales well at the same time, if you user
-a clever directory structure:
+Iterating over the data objects is quite easy. Furthermore you can
+iterate over trees and subtrees, so you can partition your data in a
+meaningful way. For example you may separate the config files and the
+pages of a wiki:
 
     store['pages/home.yml'] = WikiPage.new('matthias', 'Home', 'This is the home page...')
     store['pages/about.yml'] = WikiPage.new('matthias', About', 'About this site...')
@@ -54,13 +84,49 @@ a clever directory structure:
     store.each { |obj| ... } # yields all pages and the config hash
     store['pages'].each { |page| ... } # yields only the pages
 
-## References
+
+## Serialization
+
+Serialization is dependent on the filename extension. You can add more
+handlers if you like, the interface is like this:
+
+    class YAMLHandler
+      def read(id, name, data)
+        YAML.load(data)
+      end
+   
+      def write(data)
+        data.to_yaml
+      end    
+    end
+
+    GitStore::Handler['yml'] = YAMLHandler.new
+
+
+Shinmun uses its own handler for files with `md` extension:
+
+    class PostHandler
+      def read(name, data)
+        Post.new(:filename => name, :src => data)
+      end
+   
+      def write(post)
+        post.dump
+      end    
+    end
+
+    GitStore::Handler[md'] = PostHandler.new
+
+
+## Related Work
 
 John Wiegley already has done [something similar for Python][4]. His
 implementation has its own git interface, GitStore uses the wonderful
 [Grit][2] library.
 
 [1]: http://git.or.cz/
-[2]: http://github.com/mojombo/grit/tree/master
+[2]: http://github.com/mojombo/grit
 [3]: http://github.com/
 [4]: http://www.newartisans.com/blog_files/git.versioned.data.store.php
+[5]: http://github.com/georgi/git_store
+[6]: http://www.kernel.org/pub/software/scm/git/docs/git-gui.html

data/git_store.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = 'git_store'
-  s.version = '0.1'
+  s.version = '0.1.1'
   s.date = '2008-12-17'
   s.summary = 'a simple data store based on git'
   s.author = 'Matthias Georgi'

data/lib/git_store.rb

@@ -1,10 +1,22 @@
 require 'grit'
-require 'erb'
+
+# This fix ensures sorted yaml maps.
+class Hash
+	def to_yaml( opts = {} )
+		YAML::quick_emit( object_id, opts ) do |out|
+      out.map( taguri, to_yaml_style ) do |map|
+        sort_by { |k, v| k.to_s }.each do |k, v|
+          map.add( k, v )
+        end
+      end
+    end
+	end
+end
 
 class GitStore
 
   class DefaultHandler
-    def read(id, name, data)
+    def read(name, data)
       data
     end
 
@@ -14,7 +26,7 @@ class GitStore
   end
   
   class YAMLHandler    
-    def read(id, name, data)
+    def read(name, data)
       YAML.load(data)
     end
 
@@ -24,13 +36,13 @@ class GitStore
   end
 
   class RubyHandler
-    def read(id, name, data)
+    def read(name, data)
       Object.module_eval(data)
     end
   end
 
   class ERBHandler
-    def read(id, name, data)
+    def read(name, data)
       ERB.new(data)
     end
   end
@@ -52,7 +64,6 @@ class GitStore
     def initialize(*args)
       if args.first.is_a?(Grit::Blob)
         @blob = args.first
-        @id = @blob.id
         @name = @blob.name
       else
         @name = args[0]
@@ -65,7 +76,7 @@ class GitStore
     end
 
     def load(data)
-      @data = handler.read(id, name, data)
+      @data = handler.read(name, data)
     end
 
     def handler
@@ -93,7 +104,7 @@ class GitStore
   class Tree
     include Enumerable
 
-    attr_reader :id, :data
+    attr_reader :data
     attr_accessor :name
     
     def initialize(name = nil)
@@ -102,7 +113,6 @@ class GitStore
     end
 
     def load(tree)
-      @id = tree.id
       @name = tree.name
       @data = tree.contents.inject({}) do |hash, file|
         if file.is_a?(Grit::Tree)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: georgi-git_store
 version: !ruby/object:Gem::Version 
-  version: "0.1"
+  version: 0.1.1
 platform: ruby
 authors: 
 - Matthias Georgi