change_agent 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b77277230a8527bd86be1e4caa5500834b9aef1b
+  data.tar.gz: 43b6adf0ecc54612020d28b9050970cd3279b4c6
+SHA512:
+  metadata.gz: 308dc37a2ce06801aac82ee1bde0113ee23181bc40c3cf0093f72bf03b3c4c47a4f8672f53b4e032d25c596e217428b1590da20b530054ab35b36f2dbe73a3e0
+  data.tar.gz: 26a15963bff1938fdd7418169dfd9bdf0b7e731ba17b527032800e87a209e12340850cb96fe8bd7969071d1b53f69670c7e770344919d997db11b3ea9f3ff721

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in change_agent.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Ben Balter
+
+MIT License
+
+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,68 @@
+# Change Agent
+
+*A Git-backed key-value store, for tracking changes to documents and other files over time.*
+
+### A git-backed key value store sounds like a terrible idea. Why would you do that?
+
+Let's say you're building a scraper to see when Members of Congress post press releases to their websites and to track how those press releases change over time. You could build a purpose-built application, store each revision in a database, and then build an interface to view all the known press releases and compare their history. Stop the insanity!
+
+But wait. What if I told you you could just commit each press release to Git, and let Git/GitHub do the heavy lifting. Without writing a single line of HTML you can browse all the press releases, see when they were changed, diff exactly how they were changed, and you've got hosting baked in.
+
+Having built the first app more times then I'd like to admit, I thought I'd make a Gem to facilitate building lightweight apps that use Git to track changes to scraped documents (or whatever you want, really).
+
+## Okay, I'm sold. How do I use it?
+
+ChangeAgent writes values to the file system based on a given key, and immediately commits the file to Git, providing you with both a snapshot and a timestamp for every change.
+
+### Basic usage
+
+```ruby
+change_agent = ChangeAgent.init "path/to/repo"
+=> #<ChangeAgent::Client repo="path/to/repo">
+
+change_agent.set "foo", "bar"
+=> #<ChangeAgent::Document key="foo">
+
+change_agent.get "foo"
+=> "bar"
+```
+
+### Namespaced usage
+
+Keys (files) are intended to be namespaced when logically grouped. In the above example, if you were storing congressional press releases, you might store Rep. Balter's Nov 26th press release on puppies as "balter/2014/11/26/puppies.html", or just "balter/2014-11-26-puppies.txt" or even just "balter/puppies".
+
+```ruby
+change_agent.set "foo/bar", "baz"
+=> #<ChangeAgent::Document key="foo">
+
+change_agent.get "foo/bar"
+=> "baz"
+```
+
+It's really up to you, but you'll get performance and usability bumps the more you namespace. I'd recommend thinking about what you want the Git repo to look like when browse, and work backwards from there.
+
+## Project status
+
+Initial proof of concept
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+gem 'change_agent'
+
+And then execute:
+
+$ bundle
+
+Or install it yourself as:
+
+$ gem install change_agent
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/change_agent/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,14 @@
+require 'rake'
+require 'rake/testtask'
+require "bundler/gem_tasks"
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_change_agent*.rb'
+  test.verbose = true
+end
+
+desc "Open console with Change Agent loaded"
+task :console do
+  exec "pry -r ./lib/change_agent.rb"
+end

data/change_agent.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'change_agent/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "change_agent"
+  spec.version       = ChangeAgent::VERSION
+  spec.authors       = ["Ben Balter"]
+  spec.email         = ["ben.balter@github.com"]
+  spec.summary       = %q{A Git-backed key-value store, for tracking changes to documents and other files over time.}
+  spec.homepage      = "https://github.com/benbalter/change-agent"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "git"
+  spec.add_dependency "rugged"
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency('shoulda', '~> 3.5')
+end

data/lib/change_agent.rb

@@ -0,0 +1,12 @@
+require_relative "change_agent/version"
+require_relative "change_agent/document"
+require_relative "change_agent/client"
+require "git"
+
+module ChangeAgent
+
+  def self.init(directory=nil)
+    Client.new(directory)
+  end
+
+end

data/lib/change_agent/client.rb

@@ -0,0 +1,37 @@
+module ChangeAgent
+  class Client
+
+    attr_accessor :directory
+
+    def initialize(directory=nil)
+      @directory = File.expand_path(directory || Dir.pwd)
+    end
+
+    def git
+      @git ||= Git.init directory
+    end
+
+    def set(key, value)
+      document = Document.new(key, self)
+      document.contents = value
+      document.write
+      document
+    end
+
+    def get(key)
+      get_document(key).contents
+    end
+
+    def get_document(key)
+      Document.new(key, self)
+    end
+
+    def delete(key)
+      Document.new(key, self).delete
+    end
+
+    def inspect
+      "#<ChangeAgent::Client repo=\"#{directory}\">"
+    end
+  end
+end

data/lib/change_agent/document.rb

@@ -0,0 +1,63 @@
+module ChangeAgent
+  class Document
+
+    attr_accessor :key
+    attr_writer :contents
+
+    def initialize(key, client_or_directory=nil)
+      @key = key
+      if client_or_directory.class == ChangeAgent::Client
+        @client = client_or_directory
+      else
+        @client = ChangeAgent::Client.new(client_or_directory)
+      end
+    end
+
+    def git
+      @client.git
+    end
+
+    # base dir for repo
+    def base_dir
+      @client.directory
+    end
+
+    # directory containing file
+    def directory
+      @directory ||= File.dirname(path)
+    end
+
+    def path
+      File.expand_path key, base_dir
+    end
+
+    def exists?
+      File.exists? path
+    end
+
+    def contents
+      @contents ||= File.open(path).read
+    rescue Errno::ENOENT
+      nil
+    end
+
+    def write
+      FileUtils.mkdir_p directory unless Dir.exists? directory
+      File.write(path, contents)
+      commit
+    end
+
+    def commit
+      git.add(path)
+      git.commit "Updating #{path}"
+    end
+
+    def delete
+      git.remove(path)
+    end
+
+    def inspect
+      "#<ChangeAgent::Document key=\"#{key}\">"
+    end
+  end
+end

data/lib/change_agent/version.rb

@@ -0,0 +1,3 @@
+module ChangeAgent
+  VERSION = "0.0.1"
+end

data/script/bootstrap

@@ -0,0 +1 @@
+bundle install

data/script/cibuild

@@ -0,0 +1 @@
+bundle exec rake test

data/script/console

@@ -0,0 +1 @@
+bundle exec rake console

data/script/release

@@ -0,0 +1,38 @@
+#!/bin/sh
+# Tag and push a release.
+
+set -e
+
+# Make sure we're in the project root.
+
+cd $(dirname "$0")/..
+
+# Build a new gem archive.
+
+rm -rf change_agent-*.gem
+gem build -q change_agent.gemspec
+
+# Make sure we're on the master branch.
+
+(git branch | grep -q '* master') || {
+  echo "Only release from the master branch."
+  exit 1
+}
+
+# Figure out what version we're releasing.
+
+tag=v`ls change_agent-*.gem | sed 's/^change_agent-\(.*\)\.gem$/\1/'`
+
+# Make sure we haven't released this version before.
+
+git fetch -t origin
+
+(git tag -l | grep -q "$tag") && {
+  echo "Whoops, there's already a '${tag}' tag."
+  exit 1
+}
+
+# Tag it and bag it.
+
+gem push change_agent-*.gem && git tag "$tag" &&
+  git push origin master && git push origin "$tag"

data/test/helper.rb

@@ -0,0 +1,17 @@
+require 'rubygems'
+require 'bundler'
+require 'minitest/autorun'
+require 'shoulda'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+def tempdir
+  File.expand_path "../tmp", File.dirname(__FILE__)
+end
+
+def init_tempdir
+  FileUtils.rm_rf tempdir
+  FileUtils.mkdir tempdir
+end
+
+require 'change_agent'

data/test/test_change_agent.rb

@@ -0,0 +1,12 @@
+require 'helper'
+
+class TestChangeAgent < Minitest::Test
+
+  def setup
+    init_tempdir
+  end
+  
+  should "return a ChangeAgent::Client" do
+    assert_equal ChangeAgent::Client, ChangeAgent.init(tempdir).class
+  end
+end

data/test/test_change_agent_client.rb

@@ -0,0 +1,64 @@
+require 'helper'
+
+class TestChangeAgentClient < Minitest::Test
+
+  def setup
+    init_tempdir
+    @client = ChangeAgent::Client.new(tempdir)
+  end
+
+  should "set the directory on init" do
+    assert_equal tempdir, @client.directory
+  end
+
+  should "default to the pwd" do
+    assert_equal Dir.pwd, ChangeAgent::Client.new.directory
+  end
+
+  should "init the git object" do
+    assert_equal Git::Base, @client.git.class
+    expected = File.expand_path ".git", tempdir
+    assert_equal expected, @client.git.repo.path
+  end
+
+  should "store a value" do
+    @client.set "foo", "bar"
+    file = File.expand_path "foo", tempdir
+    assert File.exists? file
+    assert_equal "bar", File.open(file).read
+  end
+
+  should "store a namespaced value" do
+    @client.set "foo/bar", "baz"
+    file = File.expand_path "foo/bar", tempdir
+    assert File.exists? file
+    assert_equal "baz", File.open(file).read
+  end
+
+  should "retrieve a file's value" do
+    file = File.expand_path "foo", tempdir
+    File.write file, "bar"
+    assert_equal "bar", @client.get("foo")
+  end
+
+  should "retrive a namespaced file's value" do
+    file = File.expand_path "foo/bar", tempdir
+    FileUtils.mkdir_p File.dirname(file)
+    File.write file, "baz"
+    assert_equal "baz", @client.get("foo/bar")
+  end
+
+  should "round trip a value" do
+    @client.set "foo", "bar"
+    assert_equal "bar", @client.get("foo")
+  end
+
+  should "round trip a namespaced value" do
+    @client.set "foo/bar", "baz"
+    assert_equal "baz", @client.get("foo/bar")
+  end
+
+  should "not err on an unknown value" do
+    refute @client.get "does/not/exist"
+  end
+end

data/test/test_change_agent_document.rb

@@ -0,0 +1,79 @@
+require 'helper'
+
+class TestChangeAgentDocument < Minitest::Test
+
+  def setup
+    init_tempdir
+    @document = ChangeAgent::Document.new("foo", tempdir)
+    @namespaced_document = ChangeAgent::Document.new("bar/foo", tempdir)
+  end
+
+  should "store the document key on init" do
+    assert_equal "foo", @document.key
+  end
+
+  should "accept a client if passed" do
+    doc = ChangeAgent::Document.new("foo", ChangeAgent::Client.new)
+    assert_equal ChangeAgent::Client, doc.instance_variable_get("@client").class
+  end
+
+  should "build a client from a directory" do
+    assert_equal ChangeAgent::Client, @document.instance_variable_get("@client").class
+  end
+
+  should "expose the git client" do
+    assert_equal Git::Base, @document.git.class
+  end
+
+  should "calcuate the base_dir" do
+    assert_equal tempdir, @document.base_dir
+  end
+
+  should "calcuate the directory" do
+    assert_equal tempdir, @document.directory
+
+    expected = File.expand_path "bar", tempdir
+    assert_equal expected, @namespaced_document.directory
+  end
+
+  should "know the file path" do
+    expected = File.expand_path "foo", tempdir
+    assert_equal expected, @document.path
+
+    expected = File.expand_path "bar/foo", tempdir
+    assert_equal expected, @namespaced_document.path
+  end
+
+  should "know if a file exists" do
+    refute @document.exists?
+    FileUtils.touch @document.path
+    assert @document.exists?
+  end
+
+  should "read a file's contents" do
+    File.write @document.path, "bar"
+    assert_equal "bar", @document.contents
+  end
+
+  should "write a file's contents" do
+    @document.contents = "bar"
+    assert_equal "bar", @document.contents
+    @document.write
+    assert_equal "bar", File.open(@document.path).read
+  end
+
+  should "commit the document to the repo" do
+    @document.contents = "bar"
+    @document.write
+    assert_equal 1, @document.git.log.count
+    assert_equal "Updating #{@document.path}", @document.git.log.first.message
+  end
+
+  should "delete the document" do
+    @document.contents = "bar"
+    @document.write
+    assert File.exists? @document.path
+    @document.delete
+    refute File.exists? @document.path
+  end
+end

metadata

@@ -0,0 +1,151 @@
+--- !ruby/object:Gem::Specification
+name: change_agent
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Ben Balter
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-11-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: git
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rugged
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: shoulda
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+description: 
+email:
+- ben.balter@github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- change_agent.gemspec
+- lib/change_agent.rb
+- lib/change_agent/client.rb
+- lib/change_agent/document.rb
+- lib/change_agent/version.rb
+- script/bootstrap
+- script/cibuild
+- script/console
+- script/release
+- test/helper.rb
+- test/test_change_agent.rb
+- test/test_change_agent_client.rb
+- test/test_change_agent_document.rb
+homepage: https://github.com/benbalter/change-agent
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.0
+signing_key: 
+specification_version: 4
+summary: A Git-backed key-value store, for tracking changes to documents and other
+  files over time.
+test_files:
+- test/helper.rb
+- test/test_change_agent.rb
+- test/test_change_agent_client.rb
+- test/test_change_agent_document.rb