palsy 0.0.1

data/lib/palsy/basic/set.rb

@@ -0,0 +1,115 @@
+require 'palsy/basic/collection'
+require 'set'
+
+class Palsy
+  #
+  # Palsy::Set is an emulation of Ruby's Set class, where items are unordered and unique.
+  #
+  # Sets depend heavily on Marshal and so does their uniqueness. It's your job
+  # to ensure you're dealing with types that are easily marshalled.
+  #
+  # Palsy::Set is a Palsy::Collection and provides #to_set by way of Ruby's
+  # Enumerable and Set libraries.
+  #
+  # Here's an example:
+  #
+  #     obj = Palsy::Set.new("some_sets", "a_specific_set")
+  #     obj.add 2
+  #     obj.include? 2 #=> true
+  #
+  # This will create a table called "some_sets" and all i/o will be directed to
+  # that table with an additional key of "a_specific_set". This allows you to
+  # coordinate multiple sets in a single table.
+  #
+  # Another example:
+  #
+  #     obj1 = Palsy::Set.new("some_sets", "a_specific_set")
+  #     obj2 = Palsy::Set.new("some_sets", "a_specific_set")
+  #     obj3 = Palsy::Set.new("some_sets", "a_different_set")
+  #
+  #     obj1 == obj2 #=> true
+  #     obj1.add 2
+  #     obj2.include? 2 #=> also true
+  #     obj3 == obj1 #=> false (different set keys)
+  #     obj.add 2
+  #     obj3.add 3
+  #     obj2.include? 3 #=> also false
+  class Set < Collection
+
+    #
+    # Add a value to the set -- if it exists already, it will be replaced to
+    # avoid raising a constraint from sqlite.
+    #
+    def add(key)
+      delete(key)
+      @db.execute("insert into #{@table_name} (name, key) values (?, ?)", [@object_name, Marshal.dump(key)])
+    end
+
+    #
+    # Remove a value from the Set.
+    #
+    def delete(key)
+      @db.execute("delete from #{@table_name} where name=? and key=?", [@object_name, Marshal.dump(key)])
+    end
+
+    #
+    # Predicate to determine if a value is in this set.
+    #
+    def has_key?(key)
+      @db.execute("select count(*) from #{@table_name} where name=? and key=?", [@object_name, Marshal.dump(key)]).first.first.to_i > 0
+    end
+
+    alias include? has_key?
+
+    #
+    # Remove all values from the set.
+    #
+    def clear
+      @db.execute("delete from #{@table_name} where name=?", [@object_name])
+    end
+
+    #
+    # Replace the existing contents of the set with the contents of another
+    # set, or any Enumerable that has a set of unique values.
+    #
+    def replace(set)
+      clear
+
+      return if set.empty?
+
+      value_string = ("(?, ?)," * set.count).chop
+
+      @db.execute("insert into #{@table_name} (name, key) values #{value_string}", set.map { |x| [@object_name, Marshal.dump(x)] }.flatten)
+    end
+
+    #
+    # Return a ruby Array of the set. Used for #to_a and #to_set by various Ruby libraries.
+    #
+    def keys
+      @db.execute("select distinct key from #{@table_name} where name=?", [@object_name]).map { |x| Marshal.load(x.first) }
+    end
+
+    #
+    # Iterate over the set and yield each item. Modifications made to the values yielded will not be persisted.
+    #
+    def each
+      keys.each { |x| yield x }
+    end
+
+    #
+    # Defines the schema for a set.
+    #
+    def create_table
+      @db.execute <<-EOF
+        create table if not exists #{@table_name} (
+          id integer not null primary key autoincrement,
+          name varchar(255) not null,
+          key varchar(255) not null,
+          UNIQUE(name, key) 
+        )
+      EOF
+
+      @db.execute "create index if not exists #{@table_name}_name_idx on #{@table_name} (name)"
+    end
+  end
+end

data/lib/palsy/basic.rb

@@ -0,0 +1,4 @@
+require 'palsy/basic/object'
+require 'palsy/basic/list'
+require 'palsy/basic/set'
+require 'palsy/basic/map'

data/lib/palsy/version.rb

@@ -0,0 +1 @@
+PalsyVersion = "0.0.1"

data/lib/palsy.rb

@@ -0,0 +1,92 @@
+require 'sqlite3'
+require 'singleton'
+require 'delegate'
+require "palsy/version"
+
+# Present ruby core data structures in a manner similar to perl's tie backed by a
+# SQLite database. Intended to be as simple as possible, sacrificing performance
+# and flexibility to do so.
+#
+# It is not a 1:1 emulation of tie, as ruby cannot support this. What it does do
+# is provide a convincing enough facsimile by emulating the interface, and making
+# it easy to convert to native ruby types when that's not enough.
+#
+# This library is completely unapologetic with regards to how little it does or
+# how slow it does things.
+#
+# All writes are fully consistent, which is something SQLite gives us. Reads
+# always hit the database. This allows us to reason more clearly about how our
+# data persists, even in concurrent models where shared state can get very
+# complicated to use.
+
+class Palsy < DelegateClass(SQLite3::Database)
+
+  include Singleton
+
+  # Palsy's version, as a string.
+  VERSION = PalsyVersion
+
+  class << self
+    ##
+    # The name of the database Palsy will manipulate. Set this before using
+    # Palsy. Look at Palsy.change_db for a better way to swap DB's during
+    # runtime.
+    attr_accessor :database
+  end
+
+  #
+  # Given a db name, assigns that to Palsy and initiates a reconnection.
+  #
+  # Note that existing Palsy objects will immediately start working against
+  # this new database, and expect everything needed to read the data to exist,
+  # namely the tables they're keyed against.
+  #
+  def self.change_db(db_name)
+    self.database = db_name
+    self.reconnect
+  end
+
+  #
+  # Initiates a reopening of the SQLite database.
+  #
+  def self.reconnect
+    self.instance.reconnect
+  end
+
+  #
+  # Closes the SQLite database.
+  #
+  def self.close
+    self.instance.close
+  end
+
+  #
+  # Initializer. Since Palsy is a proper Ruby singleton, calling Palsy.instance
+  # will run this the first time, but calling this directly is not advised. Use
+  # the Palsy class methods like Palsy.change_db, or set Palsy.database= before
+  # working with the rest of the library.
+  #
+  def initialize
+    super(connect)
+  end
+
+  #
+  # Initiates a reopening of the SQLite database. Instance method that
+  # Palsy.reconnect uses.
+  #
+  def reconnect
+    close rescue nil
+    __setobj__(connect)
+  end
+
+  #
+  # Opens the database. Note that this is a no-op unless Palsy.database= is set.
+  #
+  def connect
+    if self.class.database
+      SQLite3::Database.new(self.class.database)
+    end
+  end
+end
+
+require 'palsy/basic'

data/palsy.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'palsy/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "palsy"
+  gem.version       = PalsyVersion
+  gem.authors       = ["Erik Hollensbe"]
+  gem.email         = ["erik+github@hollensbe.org"]
+  gem.description   = %q{An extremely simple marshalling persistence layer for SQLite based on perl's tie()}
+  gem.summary       = %q{An extremely simple marshalling persistence layer for SQLite based on perl's tie()}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency 'sqlite3', '~> 1.3.6'
+
+  gem.add_development_dependency 'minitest', '~> 4.5.0'
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'rdoc', "~> 3.12"
+  gem.add_development_dependency 'simplecov'
+end

data/test/helper.rb

@@ -0,0 +1,51 @@
+require 'minitest/unit'
+require 'tempfile'
+require 'palsy'
+
+if ENV["COVERAGE"]
+  require 'simplecov'
+  SimpleCov.start
+end
+
+module Palsy::TestHelper
+  def new_dbfile
+    @dbfiles ||= [ ]
+    dbfile = Tempfile.new('palsy-db')
+    @dbfiles << dbfile
+    return dbfile
+  end
+
+  def reinitialize
+    dbfile = new_dbfile
+    Palsy.database = dbfile.path
+    Palsy.reconnect
+    return dbfile
+  end
+
+  # intended to be run in teardown
+  def trash_databases
+    Palsy.close rescue nil
+
+    if @dbfiles
+      @dbfiles.each do |dbfile|
+        dbfile.unlink rescue nil
+      end
+    end
+  end
+end
+
+class MiniTest::Unit::TestCase
+  include Palsy::TestHelper
+end
+
+class PalsyTypeTest < MiniTest::Unit::TestCase
+  def setup
+    Palsy.change_db(new_dbfile.path)
+  end
+
+  def teardown
+    trash_databases
+  end
+end
+
+require 'minitest/autorun'

data/test/test_collection.rb

@@ -0,0 +1,18 @@
+require 'helper'
+
+# it has the same requirements Generic does, so here's a shim to walk around
+# that for certain tests.
+class InheritedCollection < Palsy::Collection
+  def create_table
+  end
+end
+
+class TestCollection < PalsyTypeTest
+  def test_initialize
+    assert_includes(Palsy::Collection.ancestors, Palsy::Generic, 'collections are also generics')
+    assert_includes(Palsy::Collection.ancestors, Enumerable, 'collections include enumerable')
+    assert_raises(RuntimeError, "an object_name must be provided!") { Palsy::Collection.new('blah', nil) }
+    assert_raises(RuntimeError, "Do not use the Generic type directly!") { Palsy::Collection.new('blah', 'barf') }
+    assert(InheritedCollection.new('blah', 'foo'))
+  end
+end

data/test/test_generic.rb

@@ -0,0 +1,35 @@
+require 'helper'
+
+# stub class to assist with testing the generic functionality
+class InheritedGeneric < Palsy::Generic
+  def create_table
+  end
+end
+
+class TestGeneric < PalsyTypeTest
+  def test_initialize
+    assert_raises(RuntimeError, "a table_name must be provided!") { Palsy::Generic.new(nil) }
+    assert_raises(RuntimeError, "Do not use the Generic type directly!") { Palsy::Generic.new('some_table') }
+    assert_raises(RuntimeError, "a table_name must be provided!") { InheritedGeneric.new(nil) }
+    InheritedGeneric.new('some_table')
+  end
+
+  def test_type_marshalling
+    ig = InheritedGeneric.new('some_table')
+    assert_equal(Palsy.instance, ig.db, 'database is held by the type')
+    duped = Marshal.load(Marshal.dump(ig))
+    assert_equal(Palsy.instance, duped.db, 'duped type is still holding the connection')
+  end
+
+  def test_attrs
+    ig = InheritedGeneric.new('some_table')
+    assert_equal(Palsy.instance, ig.db, 'db is associated with palsy instance')
+    assert_equal('some_table', ig.table_name, 'table name is getting set properly')
+    refute(ig.object_name, 'object name does not exist if not specified')
+
+    ig = InheritedGeneric.new('some_other_table', 'some_object')
+    assert_equal(Palsy.instance, ig.db, 'db is associated with palsy instance')
+    assert_equal('some_other_table', ig.table_name, 'table name is getting set properly')
+    assert_equal('some_object', ig.object_name, 'object name is getting set properly')
+  end
+end

data/test/test_init.rb

@@ -0,0 +1,41 @@
+require 'helper'
+
+class TestInit < MiniTest::Unit::TestCase
+  def teardown
+    trash_databases
+  end
+
+  def test_connection_roundtrip
+    dbfile = new_dbfile
+    Palsy.change_db(dbfile.path)
+    refute(Palsy.instance.closed?, 'the database is available')
+    Palsy.close
+    assert(Palsy.instance.closed?, 'the database is closed')
+  end
+
+  def test_reconnect_with_new_db
+    # SQLite3::Database has no target/filename attribute, so we detect by
+    # writing to the original db, swapping the dbfile, reconnecting and trying
+    # to read the value. If we get a value back, we fail.
+
+    dbfile = new_dbfile
+    Palsy.change_db(dbfile.path)
+    refute(Palsy.instance.closed?, 'the database is available')
+    Palsy.instance.execute "create table foo (bar integer);"
+    Palsy.instance.execute "insert into foo (bar) values (1);"
+    result = Palsy.instance.execute("select bar from foo").first.first rescue nil
+    assert_equal(1, result, 'the value was returned')
+
+    dbfile = new_dbfile
+    Palsy.change_db(dbfile.path)
+    refute(Palsy.instance.closed?, 'the second database is available')
+    result = Palsy.instance.execute("select bar from foo").first.first rescue nil
+    refute_equal(1, result, 'the value was returned')
+  end
+
+  def test_connect_with_no_db
+    Palsy.database = nil
+    Palsy.reconnect
+    assert_raises(NoMethodError) { Palsy.instance.closed? }
+  end
+end

data/test/test_list.rb

@@ -0,0 +1,53 @@
+require 'helper'
+
+class TestList < PalsyTypeTest
+  def setup
+    super
+    @list = Palsy::List.new('test_list', 'a_list')
+  end
+
+  def test_semantics
+    assert_empty(@list.to_a, 'an uninitialized list with no data is empty')
+  end
+
+  def test_mutators
+    # this, by side effect tests the ordering code, which is why there aren't
+    # any explicit ordering tests.
+
+    @list.push(1)
+    assert_equal([1], @list.to_a, 'pushing appends the list')
+
+    @list << 2
+    assert_equal([1, 2], @list.to_a, 'left shift appends the list')
+
+    @list.unshift(3)
+    assert_equal([3, 1, 2], @list.to_a, 'unshift prepends the list')
+
+    assert_equal(2, @list.pop, 'pop returns the last value')
+    assert_equal([3, 1], @list.to_a, 'pop also removes the last value')
+
+    assert_equal(3, @list.shift, 'shift returns the first value')
+    assert_equal([1], @list.to_a, 'shift also removes the first value')
+
+    @list.replace([2,3,4])
+    assert_equal([2,3,4], @list.to_a, 'replace replaces the contents')
+
+    @list.clear
+    assert_empty(@list.to_a, 'clearing the list makes it empty')
+  end
+
+  def test_iterator
+    array = [1,2,3]
+    @list.replace(array)
+    duped_array = array.dup
+    @list.each do |item|
+      assert_equal(duped_array.shift, item, 'value in #each is correct')
+    end
+
+    assert_equal(
+      [[1], [2, 3]],
+      @list.partition { |x| x == 1 },
+      'enumerable methods work as expected'
+    )
+  end
+end

data/test/test_map.rb

@@ -0,0 +1,78 @@
+require 'helper'
+
+class TestMap < PalsyTypeTest
+  def setup
+    super
+    @map = Palsy::Map.new('test_map', 'a_map')
+    @map2 = Palsy::Map.new('test_map', 'a_map')
+  end
+
+  def test_inherits
+    assert_includes(Palsy::Map.ancestors, Palsy::Set, 'maps are also sets')
+  end
+
+  def test_mutators
+    @map[1] = "foo"
+    assert_equal("foo", @map[1], "persistence works")
+    assert_equal("foo", @map2[1], "persistence works across multiple objects")
+
+    @map["stuff"] = "other stuff"
+
+    assert_equal("other stuff", @map["stuff"], "persistence works (type check)")
+    assert_equal("other stuff", @map2["stuff"], "persistence works across multiple objects (type check)")
+
+    @map["1"] = "bar"
+
+    assert_equal("bar", @map["1"], "string/integer doesn't collide")
+    assert_equal("foo", @map[1], "string/integer doesn't collide")
+    assert_equal("bar", @map2["1"], "string/integer doesn't collide (across objects)")
+    assert_equal("foo", @map2[1], "string/integer doesn't collide (across objects)")
+
+    another_map = Palsy::Map.new('test_map', 'another_map')
+    another_map["inner"] = "secret"
+
+    @map["outer"] = another_map
+
+    assert_equal(another_map, @map["outer"], "maps encapsulate other palsy objects")
+    assert_equal(another_map, @map2["outer"], "maps encapsulate other palsy objects (across objects)")
+    assert_equal("secret", @map["outer"]["inner"], "nested traversal")
+    assert_equal("secret", @map2["outer"]["inner"], "nested traversal (across objects)")
+  end
+
+  def test_to_hash
+    @map[1] = "foo"
+    @map["stuff"] = "other stuff"
+
+    assert_equal(
+      { 1 => "foo", "stuff" => "other stuff" },
+      @map.to_hash,
+      "#to_hash includes all the map contents"
+    )
+
+    assert_equal(
+      { 1 => "foo", "stuff" => "other stuff" },
+      @map2.to_hash,
+      "#to_hash includes all the map contents (across objects)"
+    )
+  end
+
+  def test_iterators
+    @map[1] = "foo"
+    @map["stuff"] = "other stuff"
+
+    keys = [1, "stuff"]
+
+    refute_empty(@map.keys)
+
+    @map.keys.each do |k|
+      assert_includes(keys, k, "#keys encompasses all the keys in the map")
+    end
+
+    assert_equal(@map.keys.uniq, @map.keys)
+
+    @map.each do |k, v|
+      assert_includes(keys, k, "#each yields each key")
+      assert_equal(@map[k], v, "#each yields each value")
+    end
+  end
+end

data/test/test_object.rb

@@ -0,0 +1,40 @@
+require 'helper'
+
+class TestObject < PalsyTypeTest
+  def test_index
+    obj   = Palsy::Object.new('test_object')
+    obj2  = Palsy::Object.new('test_object')
+    obj['foo'] = 1
+    assert_equal(1, obj2['foo'], 'both objects have atomic shared state')
+    obj[2] = 3
+    assert_equal(3, obj2[2], 'also works with integer indexes')
+    refute(obj['something'], 'returns nil properly on non-existent indexes')
+    refute(obj[1], 'returns nil properly on non-existent indexes')
+  end
+
+  def test_marshal
+    obj   = Palsy::Object.new('test_object')
+    obj2  = Palsy::Object.new('test_object')
+    obj[0] = [1,2,3]
+    assert_equal([1,2,3], obj2[0], 'marshals complex types')
+    obj3 = Palsy::Object.new('test_object2')
+    obj[1] = obj3
+    assert_equal(obj3, obj[1], 'marshals palsy objects')
+    assert_equal(obj3, obj2[1], 'marshals palsy objects (with a different object)')
+    obj4 = Palsy::Object.new('test_object')
+    assert_equal(obj3, obj4[1], 'marshals palsy objects (with a brand new object)')
+  end
+
+  def test_delete
+    obj   = Palsy::Object.new('test_object')
+    obj2  = Palsy::Object.new('test_object')
+    obj[0] = 1
+    assert_equal(1, obj[0], 'set object exists')
+    assert_equal(1, obj2[0], 'set object exists (second object)')
+    obj.delete(0)
+    refute(obj[0], 'set object no longer exists')
+    refute(obj2[0], 'set object no longer exists (other object)')
+
+    obj.delete('something_that_does_not_exist')
+  end
+end

data/test/test_set.rb

@@ -0,0 +1,81 @@
+require 'helper'
+
+class TestSet < PalsyTypeTest
+  def setup
+    super
+    @set = Palsy::Set.new('test_set', 'a_set')
+  end
+
+  def test_semantics
+    assert_empty(@set.to_set, 'an uninitialized set is empty')
+  end
+
+  def test_mutators
+    # this, by side effect tests the ordering code, which is why there aren't
+    # any explicit ordering tests.
+
+    @set.add(1)
+    assert_equal(Set.new([1]), @set.to_set, '#add adds to the set')
+    @set.add("2")
+    assert_equal(Set.new([1, "2"]), @set.to_set, "#add handles types correctly")
+
+    @set.delete(1)
+    refute_equal(Set.new([1, "2"]), @set.to_set, "#delete works")
+    assert_equal(Set.new(["2"]), @set.to_set, "#delete works")
+
+    @set.add(2)
+    assert_equal(Set.new([2, "2"]), @set.to_set, "no implicit string/integer casting")
+
+    @set.delete("2")
+    refute_equal(Set.new([2, "2"]), @set.to_set, "#delete works (type check)")
+    assert_equal(Set.new([2]), @set.to_set, "#delete works (type check)")
+
+    @set.replace([3,4,5])
+    assert_equal(Set.new([3,4,5]), @set.to_set, "#replace replaces the set")
+
+    @set.clear
+    assert_empty(@set.to_set, '#clear empties the set')
+
+    another_set = Palsy::Map.new('test_set', 'another_set')
+    another_set.add("secret")
+
+    @set.add(another_set)
+    assert_includes(@set, another_set, "sets encapsulate other palsy objects")
+
+    @set.clear
+  end
+
+  def test_predicates
+    @set.add(1)
+    @set.add("2")
+
+    assert(@set.has_key?(1), "has_key? reports inclusion")
+    assert(@set.has_key?("2"), "has_key? reports inclusion (type check)")
+    refute(@set.has_key?("stuff"), "has_key? reports exclusion")
+    refute(@set.has_key?(2), "has_key? reports exclusion (type check)")
+  end
+
+  def test_iterators
+    @set.add(1)
+    @set.add("2")
+    @set.add(2)
+
+    duped_set = @set.to_set
+
+    refute_empty(@set.keys)
+
+    # a nice side effect of the backing db is that we can't actually reliably
+    # predict the ordering, and there's nothing keeping it predictable. So,
+    # while less obvious, this is how we test #keys.
+
+    @set.keys.each do |k|
+      assert_includes(duped_set, k, '#keys returns all the keys in the set')
+    end
+
+    assert_equal(@set.keys.uniq, @set.keys, "keys are unique")
+
+    @set.each do |k|
+      assert_includes(duped_set, k, '#each yields each key in the set')
+    end
+  end
+end