persist 0.0.2 → 0.0.3

data/README.md

@@ -1,6 +1,6 @@
-# Persist
+# Persist.db
 
-Persist is a simple gem that allows you to painlessly save Ruby objects in a NoSQL persistent store.
+Persist.db is a simple gem that allows you to painlessly save Ruby Objects in a NoSQL persistent file store.
 
 ## Installation
 
@@ -12,26 +12,30 @@ And then execute:
 
     $ bundle
 
-Or install it yourself as:
+Or install it yourself:
 
     $ gem install persist
 
 ## Usage
 
-Example in Pry (or IRB):
+Example in Pry (or IRB if you must):
 
 ```ruby
 require 'persist'
   #=> true
 
-Persist.pull
-  #=> {}
+Persist.db
+ # => #<PStore:0x007f8c199c9698
+   @abort=false,
+   @filename=".db.pstore",
+   @lock=#<Mutex:0x007f8c199c9580>,
+   @rdonly=true,
+   @table={},
+   @thread_safe=true,
+   @ultra_safe=true>
   
-Persist.store[:siblings] = ["Katie", "Molly", "Shannnon"]
-  #=> ["Katie", "Molly", "Shannnon"]
-
-Persist.push # This saves your Stash to the persistent store.
-  #=> <File:.persistent_store (closed)>
+Persist[:pie] = ['Key Lime', 'Strawberry Rhubarb', 'Blackberry Cobbler']
+  # => ["Key Lime", "Strawberry Rhubarb", "Blackberry Cobbler"]
 ```
 
 You can now quit IRB and your store will persist!
@@ -40,15 +44,14 @@ You can now quit IRB and your store will persist!
 require 'persist'
   #=> true
 
-Persist.pull
-  #=> {:siblings=>["Katie", "Molly", "Shannnon"]}
-  
-Persist.pull[:siblings]
-  #=> ["Katie", "Molly", "Shannnon"]
+Persist[:pie]
+  #=> ["Key Lime", "Strawberry Rhubarb", "Blackberry Cobbler"]
 ```
 
+TODO: Document Persist.db's other public methods such as #transaction, #delete, and #keys. The best documentation in the meanwhile is in the code itself: https://github.com/Havenwood/persist/blob/master/lib/persist.rb
+
 ## Contributing
 
 1. Fork it
-2. Commit your changes (`git commit -am 'Added some feature'`)
+2. Commit your changes (`git commit -am 'Did something'`)
 3. Create new Pull Request

data/lib/persist/version.rb

@@ -1,3 +1,3 @@
 module Persist
-  VERSION = "0.0.2"
+  VERSION = '0.0.3'
 end

data/lib/persist.rb

@@ -1,27 +1,140 @@
-require "persist/version"
+require 'pstore'
+require 'persist/version'
 
+# Public: Implements a DSL around Ruby Standard Library's PStore to facilitate
+# simple file-persistant storage of Ruby objects in a transactional NoSQL
+# database.
 module Persist
   class << self
-    STORE = '.persistent_store'
-  
-    attr_accessor :store
-  
-    def pull
-      unless File.exists? STORE
-        self.reset!
+    # Returns the persistant store Object if one has been initialized.
+    attr_reader :store
+    
+    # Public: Initialize the PStore Object, deserializing the marshalled Hash
+    # stored in the '.db.pstore' file (creating the file if it does't exist).
+    #
+    # Examples
+    #
+    #   Persist.db
+    #   # => #<PStore:0x007f8c199c9698
+    #     @abort=false,
+    #     @filename=".db.pstore",
+    #     @lock=#<Mutex:0x007f8c199c9580>,
+    #     @rdonly=true,
+    #     @table={},
+    #     @thread_safe=true,
+    #     @ultra_safe=true>
+    #
+    # Returns the entire persistent store Object.
+    def db
+      # Initialize a persistent store in the file '.db.pstore' and set
+      # thread_safe to true.
+      @store = PStore.new('.db.pstore', true)
+      
+      # Set ultru_safe to true for extra safety checks regarding full disk, etc.
+      @store.ultra_safe = true
+      
+      # Open a read-only transaction to fetch latest store.
+      @store.transaction(true) {}
+      
+      # Return the entire fetched store Object.
+      @store
+    end
+    
+    # Public: Fetch a list of persistent store root tables.
+    #
+    # Examples
+    #
+    #   Persist.keys
+    #   # => [:author]
+    #
+    # Returns an Array containing the persistent store root tables.
+    def keys
+      # Open a read-only transaction.
+      @store.transaction(true) do
+        #Return a list of all tables in the persistent store.
+        @store.roots
+      end
+    end
+    
+    alias tables keys
+    
+    # Public: Fetch a particular table from the persistent store.
+    #
+    # table - A Symbol.
+    #
+    # Examples
+    #
+    #   Persist[:author]
+    #   # => {:first_name => "Shannon", :last_name => "Skipper"}
+    #
+    #   Persist[:author][:first_name]
+    #   # => "Shannon"
+    #
+    # Returns the value stored in the fetched table.
+    def [] table
+      # Open a read-only transaction.
+      @store.transaction(true) do
+        # Return a particular table from the persistent store.
+        @store[table]
       end
-      @store = Marshal.load File.read(STORE)
     end
-  
-    def push
-      File.open STORE, 'w' do |store|
-        store << Marshal.dump(@store)
+    
+    # Public: Use a single transaction to set a table value.
+    #
+    # table - A Symbol.
+    #
+    # value - Any Ruby Object that is marshallable.
+    #
+    # Examples
+    #
+    #   Persist[:sky] = 'blue'
+    #   # => "blue"
+    #
+    # Returns the value of the table.
+    def []= table, value
+      # Open a writable transaction.
+      @store.transaction do
+        # Process the single transaction.
+        @store[table] = value
+      end # Commit transaction.
+    end
+    
+    # Public: Process multiple transactions to set table values and commit if
+    # all are transactions are successful.
+    #
+    # block - A required block that processes multiple transactions that 
+    #         succeed or fail together to ensure that data is not left in a 
+    #         transitory state.
+    #
+    # Examples
+    #
+    #   Persist.transaction do
+    #     Persist.store[:weather] = 'sunny'
+    #     Persist.store[:hour] = 'midday'
+    #   end
+    #   # => nil
+    #
+    # Returns nothing.
+    def transaction &block
+      @store.transaction do
+        yield
+        @store.commit
       end
     end
-  
-    def reset!
-      File.open STORE, 'w' do |store|
-        store << Marshal.dump({})
+    
+    # Public: Delete an entire root table from the persistent store.
+    #
+    # Examples
+    #
+    #   Persist.delete :author
+    #   # => nil
+    #
+    # Returns nothing.
+    def delete table
+      # Open a writable transaction.
+      @store.transaction do
+        # Delete a particular table from the persistent store.
+        @store.delete table
       end
     end
   end

data/persist.gemspec

@@ -4,13 +4,13 @@ require File.expand_path('../lib/persist/version', __FILE__)
 Gem::Specification.new do |gem|
   gem.authors       = ["Shannon"]
   gem.email         = ["shannonskipper@gmail.com"]
-  gem.description   = %q{Simple NoSQL Persistent Object Store for Ruby}
-  gem.summary       = %q{This gem allows you to save Ruby Objects to a persistent store and recover them later.}
+  gem.description   = %q{A DSL for storing Ruby Objects transactionally in a persistent NoSQL database}
+  gem.summary       = %q{Persist.db is a DSL implemented around Ruby Standard Library's PStore to facilitate simple file-persistant storage of Ruby objects in a transactional NoSQL database.}
   gem.homepage      = "https://github.com/Havenwood/persist"
 
   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.test_files    = gem.files.grep(%r{^test/})
   gem.name          = "persist"
   gem.require_paths = ["lib"]
   gem.version       = Persist::VERSION

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: persist
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,9 +9,10 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-08 00:00:00.000000000 Z
+date: 2012-05-21 00:00:00.000000000 Z
 dependencies: []
-description: Simple NoSQL Persistent Object Store for Ruby
+description: A DSL for storing Ruby Objects transactionally in a persistent NoSQL
+  database
 email:
 - shannonskipper@gmail.com
 executables: []
@@ -49,7 +50,8 @@ rubyforge_project:
 rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
-summary: This gem allows you to save Ruby Objects to a persistent store and recover
-  them later.
+summary: Persist.db is a DSL implemented around Ruby Standard Library's PStore to
+  facilitate simple file-persistant storage of Ruby objects in a transactional NoSQL
+  database.
 test_files: []
 has_rdoc: