geist 0.1.0

data/.gitignore

@@ -0,0 +1,3 @@
+.yardoc/
+doc/
+pkg/

data/.yardopts

@@ -0,0 +1,4 @@
+lib/**/*.rb
+--files Changelog.md,LICENSE
+--private
+--title Geist — API Documentation

data/Changelog.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## Version 0.1.0
+
+ **September 22<sup>nd</sup>, 2011**
+
+ * Converted the Codebrawl contest entry into a gem
+
+ See the [Git history](https://github.com/koraktor/metior/commits/0.1.0) for
+ version 0.1.0
+
+## Codebrawl contest entry
+
+ **September 1<sup>st</sup>, 2011**
+
+ See the
+ ["Key/value stores" contest](http://codebrawl.com/contests/key-value-stores)
+ on Codebrawl to see the initial code

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,20 @@
+PATH
+  remote: .
+  specs:
+    geist (0.1.0)
+      open4 (~> 1.1.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    open4 (1.1.0)
+    rake (0.9.2)
+    yard (0.7.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  geist!
+  rake (~> 0.9.2)
+  yard (~> 0.7.2)

data/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2011, Sebastian Staudt
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+* Neither the name of the author nor the names of its contributors
+  may be used to endorse or promote products derived from this software
+  without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,61 @@
+Geist
+=====
+
+Geist is a Git-backed key-value store written in Ruby.
+
+## Usage
+
+    require 'geist'
+
+    g = Geist.new '~/some/storage/path'
+    g.set :foo, 'bar'
+    g.set :baz, 123
+    g.set :name => 'geist', :platform => 'ruby'
+
+    g.keys                 #=> ["foo", "name", "platform"]
+    g.get :foo             #=> "bar"
+    g.get :baz             #=> 123
+    g.get :name, :platform #=> ["geist", "ruby"]
+
+    g.delete :baz
+    g.get :baz             #=> nil
+
+## Internals
+
+To be honest, the introduction was an outright fabrication. Geist is just a
+Ruby API to misuse Git as a simple key-value store. Git itself is a pretty good
+key-value store used to preserve blob (file), tree (directory), commit and tag
+objects. A key-value store used to store versioned file histories in general.
+
+Geist instead uses some low-level Git commands to store arbitrary Ruby objects
+in a Git repository. The Ruby objects to store as values will be marshalled
+into Git blob objects. These objects are referenced with lightweight Git tags
+named by the given key.
+
+Git will not double store duplicate values. Instead, the different key tags
+will refer the same Git object.
+
+## Caveats
+
+As Geist uses Git tags as keys, only objects with a working `#to_s` method can
+be used as keys. Additionally, based on Git's [ref naming rules][1], Geist
+rejects keys that can't be used as Git tag names, e.g. containing non-printable
+characters or backslashes.
+
+## History
+
+Geist was an idea for the Codebrawl contest ["Key/value stores"][2] and made it
+to a honorable 6th place out of 18 contestants with a final score of 3.6.
+
+## License
+
+This code is free software; you can redistribute it and/or modify it under the
+terms of the new BSD License. A copy of this license can be found in the
+LICENSE file.
+
+## Credits
+
+ * Sebastian Staudt – koraktor(at)gmail.com
+
+ [1]: http://www.kernel.org/pub/software/scm/git/docs/git-check-ref-format.html
+ [2]: http://codebrawl.com/contests/key-value-stores

data/Rakefile

@@ -0,0 +1,38 @@
+# -*- encoding: utf-8 -*-
+
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
+#
+# Copyright (c) 2011, Sebastian Staudt
+
+require 'rubygems/package_task'
+
+# Rake tasks for building the gem
+spec = Gem::Specification.load('geist.gemspec')
+Gem::PackageTask.new(spec) do |pkg|
+end
+
+# Check if YARD is installed
+begin
+  require 'yard'
+
+  # Create a rake task `:doc to build the documentation using YARD
+  YARD::Rake::YardocTask.new do |yardoc|
+    yardoc.name    = 'doc'
+    yardoc.files   = [ 'lib/**/*.rb', 'Changelog.md', 'LICENSE', 'README.md' ]
+    yardoc.options = [ '--markup', 'markdown', '--private', '--title', 'Geist — API Documentation' ]
+  end
+rescue LoadError
+  # Create a rake task `:doc` to show that YARD is not installed
+  desc 'Generate YARD Documentation (not available)'
+  task :doc do
+    $stderr.puts 'You need YARD to build the documentation. Install it using `gem install yard`.'
+  end
+end
+
+# Task for cleaning documentation and package directories
+desc 'Clean documentation and package directories'
+task :clean do
+  FileUtils.rm_rf 'doc'
+  FileUtils.rm_rf 'pkg'
+end

data/geist.gemspec

@@ -0,0 +1,27 @@
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
+#
+# Copyright (c) 2011, Sebastian Staudt
+
+require File.expand_path(File.dirname(__FILE__) + '/lib/geist/version')
+
+Gem::Specification.new do |s|
+  s.name        = 'geist'
+  s.version     = Geist::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = [ 'Sebastian Staudt' ]
+  s.email       = [ 'koraktor@gmail.com' ]
+  s.homepage    = 'https://github.com/koraktor/geist'
+  s.summary     = 'A Git-backed key-value store'
+  s.description = 'Geist is a Git-backed key-value store that stores Ruby objects into a Git repository.'
+
+  s.add_dependency 'open4', '~> 1.1.0'
+
+  s.add_development_dependency 'rake', '~> 0.9.2'
+  s.add_development_dependency 'yard', '~> 0.7.2'
+
+  s.requirements = [ 'git >= 1.6' ]
+
+  s.files         = `git ls-files`.split("\n")
+  s.require_paths = [ 'lib' ]
+end

data/lib/geist.rb

@@ -0,0 +1,153 @@
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
+#
+# Copyright (c) 2011, Sebastian Staudt
+
+require 'fileutils'
+
+require 'open4'
+
+# Geist is a Git-backed key-value store written in Ruby
+#
+# @author Sebastian Staudt
+class Geist
+
+  # Create a new Geist instance storing into the given Git repository
+  #
+  # @param [String] path The path of the Git repository to store objects into
+  # @raise [RuntimeError] if the directory is not empty and not a Git
+  #        repository
+  def initialize(path)
+    @path = File.expand_path path
+
+    if !File.exist? @path
+      FileUtils.mkdir_p @path
+      cmd 'init'
+    elsif !cmd('ls-files').success?
+      raise "#{@path} is not a Git repository."
+    end
+  end
+
+  # Delete the objects with the given keys from the storage
+  #
+  # @param [#to_s, ...] keys One or more keys where the corresponding values
+  #        should be removed from the storage
+  # @return [Boolean] `true` if the objects have been removed from the
+  #         repository
+  # @todo This does not really remove the objects from the repository but only
+  #       the tags. This should also trigger Git's garbage collection to remove
+  #       the objects completely.
+  def delete(*keys)
+    success = true
+
+    keys.each do |key|
+      if id_for(key).nil?
+        success = false
+      else
+        cmd "tag -d '#{key}'"
+      end
+    end
+
+    success
+  end
+
+  # Retrieve the objects with the given keys from the storage
+  #
+  # @param [#to_s, ...] keys One or more keys where the corresponding values
+  #        should be loaded from the storage
+  # @return [Object, Array<Object>] One or more objects that belong to the
+  #         given keys
+  def get(*keys)
+    return nil if keys.empty?
+
+    values = []
+    keys.each do |key|
+      value = nil
+      status = cmd "show '#{key}'" do |stdin, stdout|
+        if select [stdout]
+          blob = stdout.read.strip
+          value = Marshal.load blob unless blob.empty?
+        end
+      end
+      values << (status.success? ? value : nil)
+    end
+
+    keys.size == 1 ? values.first : values
+  end
+
+  # Returns all keys which have objects available in the storage
+  #
+  # @return [Array<String>] The keys available in the storage
+  def keys
+    keys = nil
+    cmd 'tag -l' do |stdin, stdout|
+      keys = stdout.lines.to_a.map(&:strip) if select [stdout]
+    end
+    keys
+  end
+
+  # Saves one ore more values into the storage
+  #
+  # @param [#to_s, Hash<#to_s, Object>] keys The key to use to store the value
+  #        or a hash of multiple keys and values to store
+  # @param [Object] value The object to store as a value (only if a single key
+  #        is given)
+  def set(keys, value = nil)
+    keys = { keys => value } unless keys.is_a? Hash
+
+    keys.each do |key, val|
+      if key.to_s.match(/(?:[\s^~:?*\[\\]|\.\.|@\{|(?:\/|\.|\.lock)$|^$)/)
+        warn "Warning: Invalid key '#{key}'"
+        return
+      end
+
+      delete key unless id_for(key).nil?
+
+      id = nil
+      cmd 'hash-object --stdin -w' do |stdin, stdout|
+        stdin.write Marshal.dump(val)
+        stdin.close
+        id = stdout.read.strip if select [stdout]
+      end
+
+      cmd "tag -f '#{key}' #{id}"
+    end
+  end
+
+  private
+
+  # Execute a Git command in the path of the Git repository of the current
+  # Geist instance
+  #
+  # @param [String] git_cmd The Git command to execute
+  # @param [Proc] block A block that can be used to read and write to and from
+  #        the Git process' STDOUT and STDIN.
+  # @return [Process::Status] The exit status of the Git process
+  def cmd(git_cmd, &block)
+    cmd = "git --git-dir #{@path} #{git_cmd}"
+    status = Open4::popen4 cmd do |pid, stdin, stdout, stderr|
+      block.call stdin, stdout if block_given?
+
+      stdin.close unless stdin.closed?
+      stdout.close
+      stderr.close
+    end
+    status
+  end
+
+  # Returns the Git SHA ID of the blob where the value for the given key is
+  # stored
+  #
+  # @param [String, #to_s] key The key for which the Git SHA ID should be
+  #        returned
+  # @return [String, nil] The SHA ID of the value's Git blob or `nil` if no
+  #         such object exists
+  def id_for(key)
+    id = nil
+    status = cmd "rev-parse '#{key}'" do |stdin, stdout|
+      id = stdout.read.strip if select [stdout]
+    end
+    status.success? ? id : nil
+  end
+
+end

data/lib/geist/version.rb

@@ -0,0 +1,11 @@
+# This code is free software; you can redistribute it and/or modify it under
+# the terms of the new BSD License.
+#
+# Copyright (c) 2011, Sebastian Staudt
+
+class Geist
+
+  # This is the current version of the Geist gem
+  VERSION = '0.1.0' unless const_defined? :VERSION
+
+end

metadata

@@ -0,0 +1,123 @@
+--- !ruby/object:Gem::Specification 
+name: geist
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Sebastian Staudt
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-09-22 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: open4
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 19
+        segments: 
+        - 1
+        - 1
+        - 0
+        version: 1.1.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 63
+        segments: 
+        - 0
+        - 9
+        - 2
+        version: 0.9.2
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 0
+        - 7
+        - 2
+        version: 0.7.2
+  type: :development
+  version_requirements: *id003
+description: Geist is a Git-backed key-value store that stores Ruby objects into a Git repository.
+email: 
+- koraktor@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- .yardopts
+- Changelog.md
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- Rakefile
+- geist.gemspec
+- lib/geist.rb
+- lib/geist/version.rb
+homepage: https://github.com/koraktor/geist
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: 
+- git >= 1.6
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: A Git-backed key-value store
+test_files: []
+