palsy 0.0.1

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+html
+coverage

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Erik Hollensbe
+
+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,91 @@
+# Palsy - Set and forget it
+
+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.
+
+This was largely written to deal with problems I had to resolve in
+[chef-workflow](https://github.com/chef-workflow). If you like the idea but
+would like something more general or support for your favorite database, check
+out [Moneta](https://github.com/minad/moneta) which is a little more geared
+towards having a flexible backend.
+
+## Usage Example
+
+Here's an example for dealing with several collections.
+
+```ruby
+require 'palsy'
+
+# only one palsy instance exists in a given ruby process
+Palsy.database = 'test.db'
+# first arg is table name, second is object name.
+# standard datatypes are aggressive indexed and constrained. just because we
+# don't care about performance doesn't mean we ignore easy wins.
+set_a = Palsy::Set.new('some_sets', 'set_a')
+set_b = Palsy::Set.new('some_sets', 'set_b')
+set_c = Palsy::Set.new('some_sets', 'set_c')
+
+set_a.add('something')
+set_b.add('something_else')
+# they are nestable like you'd expect.
+set_c.add(set_a)
+
+# enumerable works with collections like you'd expect. the results however are
+# not palsy objects, so you cannot expect persistence by transformating them.
+# consequently, most bang methods will not work as you expect either.
+set_a.group_by(&:length)
+
+# they are not ruby 'Set' objects, they just act like them.
+# to get at more esoteric methods you'll need to convert them to the proper
+# ruby type.
+#
+# For example, Set theory operators on Palsy::Set are not first class, you need
+# to convert to a ruby Set first. Casting to array, hash and set is something
+# we try to support wherever possible.
+#
+# Below we get the union of set_a and set_b
+
+set_a.to_set | set_b.to_set
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'palsy'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install palsy
+
+## Contributing
+
+1. Fork it
+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 new Pull Request
+
+Changes to author, license or version information without prior approval will
+be rejected regardless of other changes.
+
+## Author
+
+Erik Hollensbe <erik+github@hollensbe.org>

data/Rakefile

@@ -0,0 +1,38 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+require 'rdoc/task'
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/test_*.rb']
+  t.verbose = true
+end
+
+RDoc::Task.new do |rdoc|
+  rdoc.title = "Palsy: a simple sqlite layer for persisting data structures"
+  rdoc.rdoc_files.include("lib/**/*.rb")
+  rdoc.rdoc_files -= ["lib/palsy/version.rb"]
+  if ENV["RDOC_COVER"]
+    rdoc.options << "-C"
+  end
+end
+
+desc "run tests with coverage report"
+task "test:coverage" do
+  ENV["COVERAGE"] = "1"
+  Rake::Task["test"].invoke
+end
+
+desc "run rdoc with coverage report"
+task :rdoc_cov do
+  # ugh
+  ENV["RDOC_COVER"] = "1"
+  ruby "-S rake rerdoc"
+end
+
+desc "Clean up build products"
+task :clean do
+  %w[html coverage].each do |dir|
+    FileUtils.rm_rf(dir)
+  end
+end

data/lib/palsy/basic/collection.rb

@@ -0,0 +1,46 @@
+require 'palsy/basic/generic'
+
+class Palsy
+  #
+  # Base class for Collections. This includes Enumerable and makes the object
+  # name a required value. That's literally all it does.
+  #
+  # For more information on how to use this, see Palsy::Generic. If you want to
+  # exploit the Enumerable mixin, you need to define #each.
+  #
+  # Almost all Palsy::Collection objects are instantiated this way (using
+  # Palsy::Map as an example):
+  #
+  #     obj = Palsy::Map.new("some_maps", "a_specific_map")
+  #     obj[1] = 2
+  #     obj[1] == 2 #=> true
+  #
+  # This will create a table called "some_maps" and all i/o will be directed to
+  # that table with an additional key of "a_specific_map". This allows you to
+  # coordinate multiple maps in a single table.
+  #
+  # Another example:
+  #
+  #     obj1 = Palsy::Map.new("some_maps", "a_specific_map")
+  #     obj2 = Palsy::Map.new("some_maps", "a_specific_map")
+  #     obj3 = Palsy::Map.new("some_maps", "a_different_map")
+  #
+  #     obj1 == obj2 #=> true
+  #     obj1[1] = 2
+  #     obj2[1] == 2 #=> also true
+  #     obj3 == obj1 #=> false (different map keys)
+  #     obj3[1] = 3
+  #     obj2[1] == 3 #=> also false
+  #
+  class Collection < Generic
+    include Enumerable
+
+    #
+    # See the documentation for Palsy::Collection.
+    #
+    def initialize(table_name, object_name)
+      raise "an object_name must be provided!" unless object_name
+      super
+    end
+  end
+end

data/lib/palsy/basic/generic.rb

@@ -0,0 +1,89 @@
+require 'palsy'
+
+class Palsy
+  #
+  # Palsy::Generic is the base type for Palsy types. It implements the basic
+  # things needed for Palsy to work.
+  #
+  # Creating your own type is just a function of subclassing this and
+  # overriding the method Palsy::Generic#create_table, and adding methods you
+  # expect users to use to operate against the type. For example, this is what
+  # Palsy::Object#create_table looks like:
+  #
+  #     class Palsy::Object < Palsy::Generic
+  #       def create_table
+  #         @db.execute %Q[
+  #           create table if not exists #{@table_name} (
+  #             id integer not null primary key autoincrement,
+  #             key varchar(255) not null,
+  #             value text not null,
+  #             UNIQUE(key)
+  #           )
+  #         ]
+  #       end
+  #     end
+  #
+  class Generic
+    # The instance of Palsy. Overwriting this is probably not a good idea.
+    attr_accessor :db
+    # The name of the table this object is bound to.
+    attr_reader :table_name
+    # The name of the object this object is bound to inside the table. May be
+    # nil for certain types.
+    attr_reader :object_name
+
+    #
+    # This is the base constructor for all Palsy types and should always be run
+    # in subclasses before any action is taken by the class's initializer.
+    #
+    def initialize(table_name, object_name=nil)
+      raise "a table_name must be provided!" unless table_name
+
+      @table_name   = table_name
+      @object_name  = object_name
+      post_marshal_init
+      create_table
+    end
+
+    #
+    # Marshal helper to load objects.
+    #
+    def self._load(value)
+      obj = self.new(*Marshal.load(value))
+      return obj
+    end
+
+    #
+    # Marshal helper to dump objects. Only the table and object names are
+    # preserved.
+    #
+    def _dump(level)
+      self.db = nil
+      res = Marshal.dump([@table_name, @object_name])
+      post_marshal_init
+      return res
+    end
+
+    #
+    # Helper to manage the database instance for Marshal operations.
+    #
+    def post_marshal_init
+      @db = Palsy.instance
+    end
+
+    #
+    # Virtual method to define the create_table interface. Just raises,
+    # intended to be overridden.
+    #
+    def create_table
+      raise "Do not use the Generic type directly!"
+    end
+
+    #
+    # Equality method for comparing Palsy objects.
+    #
+    def ==(other)
+      [:db, :table_name, :object_name].all? { |x| self.send(x) == other.send(x) }
+    end
+  end
+end

data/lib/palsy/basic/list.rb

@@ -0,0 +1,134 @@
+require 'palsy/basic/collection'
+
+class Palsy
+  #
+  # Palsy::List is a kind of Palsy::Collection and implements List semantics
+  # similar to Ruby's Array class. For more random-access behavior that Array
+  # provides, convert to a Ruby array with Palsy::List#to_a.
+  #
+  # All values of the list must be capable of being Marshalled.
+  #
+  # Here's an example:
+  #
+  #     obj = Palsy::List.new("some_lists", "a_specific_list")
+  #     obj.push 2
+  #     obj.pop == 2 #=> true
+  #
+  # This will create a table called "some_lists" and all i/o will be directed to
+  # that table with an additional key of "a_specific_list". This allows you to
+  # coordinate multiple lists in a single table.
+  #
+  # Another example:
+  #
+  #     obj1 = Palsy::List.new("some_lists", "a_specific_list")
+  #     obj2 = Palsy::List.new("some_lists", "a_specific_list")
+  #     obj3 = Palsy::List.new("some_lists", "a_different_list")
+  #
+  #     obj1 == obj2 #=> true
+  #     obj1.push 2
+  #     obj2.pop == 2 #=> also true
+  #     obj3 == obj1 #=> false (different list keys)
+  #     obj.push 2
+  #     obj3.push 3
+  #     obj2.pop == 3 #=> also false
+  #
+  class List < Collection
+    #
+    # Add a value to the tail of the list.
+    #
+    def push(val)
+      @db.execute(
+        "insert into #{@table_name} (name, value) values (?, ?)",
+        [@object_name, Marshal.dump(val)]
+      )
+    end
+
+    alias << push
+
+    #
+    # Add a value to the head of the list.
+    #
+    def unshift(val)
+      replace([val] + to_a)
+    end
+
+    #
+    # Helper method for mutators.
+    #
+    def mutate(meth)
+      a = to_a
+      val = a.send(meth)
+      replace(a)
+      return val
+    end
+
+    #
+    # Returns the head of the list. Destructive.
+    #
+    def shift
+      mutate(:shift)
+    end
+
+    #
+    # Returns the tail of the list. Destructive.
+    #
+    def pop
+      mutate(:pop)
+    end
+
+    #
+    # Replace the list with the argument, which should be something that acts
+    # like an Enumerable.
+    #
+    def replace(ary)
+      clear
+
+      value_string = ("(?, ?)," * ary.count).chop
+
+      @db.execute(
+          "insert into #{@table_name} (name, value) values #{value_string}",
+          ary.map { |x| [@object_name, Marshal.dump(x)] }.flatten
+      )
+    end
+
+    #
+    # Empty the list.
+    #
+    def clear
+      @db.execute("delete from #{@table_name} where name=?", [@object_name])
+    end
+
+    #
+    # Yield each item in the list successively. Note that changes made to the
+    # items yielded will not persist, unless they are Palsy types themselves.
+    #
+    def each
+      to_a.each { |x| yield x }
+    end
+
+    #
+    # Convert the list to a Ruby Array.
+    #
+    def to_a
+      @db.execute(
+        "select value from #{@table_name} where name=? order by id",
+        [@object_name]
+      ).map { |x| Marshal.load(x.first) }
+    end
+
+    #
+    # Define the schema for this type.
+    #
+    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,
+          value text not null
+        )
+      EOF
+
+      @db.execute "create index if not exists #{@table_name}_name_index on #{@table_name} (name)"
+    end
+  end
+end

data/lib/palsy/basic/map.rb

@@ -0,0 +1,92 @@
+require 'palsy/basic/set'
+
+class Palsy
+  #
+  # Palsy::Map is an emulation of Ruby's Hash class, where objects are
+  # unordered and unique by the keyed value. They are a Palsy::Set and
+  # Palsy::Collection and have Enumerable support. Take a look at Palsy::Object
+  # which is similar but semantically different in a few ways.
+  #
+  # Palsy::Map keys and values must be marshallable, and their uniqueness for
+  # sanity's sake must also be enforced in their marshalled output.
+  #
+  # Here's an example:
+  #
+  #     obj = Palsy::Map.new("some_maps", "a_specific_map")
+  #     obj[1] = 2
+  #     obj[1] == 2 #=> true
+  #
+  # This will create a table called "some_maps" and all i/o will be directed to
+  # that table with an additional key of "a_specific_map". This allows you to
+  # coordinate multiple maps in a single table.
+  #
+  # Another example:
+  #
+  #     obj1 = Palsy::Map.new("some_maps", "a_specific_map")
+  #     obj2 = Palsy::Map.new("some_maps", "a_specific_map")
+  #     obj3 = Palsy::Map.new("some_maps", "a_different_map")
+  #
+  #     obj1 == obj2 #=> true
+  #     obj1[1] = 2
+  #     obj2[1] == 2 #=> also true
+  #     obj3 == obj1 #=> false (different map keys)
+  #     obj3[1] = 3
+  #     obj2[1] == 3 #=> also false
+  #
+  class Map < Set
+
+    #
+    # Obtain the value for a given key. Returns nil if the key does not have an
+    # entry.
+    #
+    def [](key)
+      value = @db.execute("select value from #{@table_name} where name=? and key=?", [@object_name, Marshal.dump(key)]).first.first rescue nil
+      return value && Marshal.load(value)
+    end
+
+    #
+    # Associate a value with a given key. Keys will be deleted from the
+    # database before attempting to write the new pair.
+    #
+    def []=(key, value)
+      delete(key)
+      @db.execute("insert into #{@table_name} (name, key, value) values (?, ?, ?)", [@object_name, Marshal.dump(key), Marshal.dump(value)])
+      value
+    end
+
+    #
+    # Successively yields key and value for each item in the map. Modifications
+    # to either the key or value yielded will not persist.
+    #
+    def each
+      keys.each do |key|
+        yield key, self[key]
+      end
+    end
+
+    #
+    # Convert this map to a Ruby Hash object.
+    #
+    def to_hash
+      rows = @db.execute("select key, value from #{@table_name} where name=?", [@object_name])
+      Hash[rows.map { |x| x.map { |y| Marshal.load(y) } }]
+    end
+
+    #
+    # Defines the schema for Maps.
+    #
+    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,
+          value text 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/object.rb

@@ -0,0 +1,64 @@
+require 'palsy/basic/generic'
+
+class Palsy
+  #
+  # Basic "symbol table"-ish object.
+  #
+  # The difference between using this over Palsy::Map is that objects take a
+  # full database table, treat all indexes as strings, and do not act like
+  # Palsy::Collection subclasses.
+  #
+  # Example:
+  #
+  #     obj = Palsy::Object.new("object_table")
+  #     obj["var1"] = 1
+  #     obj["var2"] = 2
+  #     obj["var1"] == 1 #=> true
+  #
+  # This will create a table in the database named "object_table" and all i/o
+  # against this object (unless specified otherwise on a per-method basis) will
+  # go through it.
+  #
+  # Note that while all object keys are treated as strings, values are
+  # marshalled and must be capable of doing so.
+  #
+  class Object < Generic
+    #
+    # Get an object by referencing its key. Returns nil unless it exists.
+    #
+    def [](key)
+      value = @db.execute("select value from #{@table_name} where key=?", [key]).first.first rescue nil
+      return value && Marshal.load(value)
+    end
+
+    #
+    # Set an object. Returns the object. The object must be able to be Marshalled.
+    #
+    def []=(key, value)
+      delete(key)
+      @db.execute("insert into #{@table_name} (key, value) values (?, ?)", [key, Marshal.dump(value)])
+      value
+    end
+
+    #
+    # Deletes an object.
+    #
+    def delete(key)
+      @db.execute("delete from #{@table_name} where key=?", [key])
+    end
+
+    #
+    # Defines the schema for this data type.
+    #
+    def create_table
+      @db.execute <<-EOF
+        create table if not exists #{@table_name} (
+          id integer not null primary key autoincrement,
+          key varchar(255) not null,
+          value text not null,
+          UNIQUE(key)
+        )
+      EOF
+    end
+  end
+end