rubysl-pstore 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 49e8c464bdca0f27119a2c5e04523932784880e7
+  data.tar.gz: 4e10e4cf5ec7e64f77589b6918b4bb66aadba2d8
+SHA512:
+  metadata.gz: c0194a5e9c670355a299c6cf3c78c74711ede3aef8f2446c2231a3216371256bb3287be3458766ce9e396124cc91841666ecd2fcaaefc4b7e90ac5339efedd52
+  data.tar.gz: d71099fd0bd5172c5ad39ab78f771d4904f6270b8447ead45958e533d1648fcc19c4cf3b284a45f0ade1d1f944db3c2c264dfc7e960dae8acab084523c5c6261

data/.gitignore

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

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+before_install:
+  - gem update --system
+  - gem --version
+  - gem install rubysl-bundler
+script: bundle exec mspec spec
+rvm:
+  - rbx-nightly-18mode

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2013, Brian Shirai
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. 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.
+3. Neither the name of the library 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 <COPYRIGHT HOLDER> 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,29 @@
+# Rubysl::Pstore
+
+TODO: Write a gem description
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'rubysl-pstore'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install rubysl-pstore
+
+## Usage
+
+TODO: Write usage instructions here
+
+## 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

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/pstore.rb

@@ -0,0 +1 @@
+require "rubysl/pstore"

data/lib/rubysl/pstore.rb

@@ -0,0 +1,2 @@
+require "rubysl/pstore/pstore"
+require "rubysl/pstore/version"

data/lib/rubysl/pstore/pstore.rb

@@ -0,0 +1,395 @@
+# = PStore -- Transactional File Storage for Ruby Objects
+#
+# pstore.rb -
+#   originally by matz
+#   documentation by Kev Jackson and James Edward Gray II
+#
+# See PStore for documentation.
+
+
+require "fileutils"
+require "digest/md5"
+
+#
+# PStore implements a file based persistence mechanism based on a Hash.  User
+# code can store hierarchies of Ruby objects (values) into the data store file
+# by name (keys).  An object hierarchy may be just a single object.  User code 
+# may later read values back from the data store or even update data, as needed.
+# 
+# The transactional behavior ensures that any changes succeed or fail together.
+# This can be used to ensure that the data store is not left in a transitory
+# state, where some values were updated but others were not.
+# 
+# Behind the scenes, Ruby objects are stored to the data store file with 
+# Marshal.  That carries the usual limitations.  Proc objects cannot be 
+# marshalled, for example.
+#
+# == Usage example:
+# 
+#  require "pstore"
+#  
+#  # a mock wiki object...
+#  class WikiPage
+#    def initialize( page_name, author, contents )
+#      @page_name = page_name
+#      @revisions = Array.new
+#      
+#      add_revision(author, contents)
+#    end
+#    
+#    attr_reader :page_name
+#    
+#    def add_revision( author, contents )
+#      @revisions << { :created  => Time.now,
+#                      :author   => author,
+#                      :contents => contents }
+#    end
+#    
+#    def wiki_page_references
+#      [@page_name] + @revisions.last[:contents].scan(/\b(?:[A-Z]+[a-z]+){2,}/)
+#    end
+#    
+#    # ...
+#  end
+#  
+#  # create a new page...
+#  home_page = WikiPage.new( "HomePage", "James Edward Gray II",
+#                            "A page about the JoysOfDocumentation..." )
+#  
+#  # then we want to update page data and the index together, or not at all...
+#  wiki = PStore.new("wiki_pages.pstore")
+#  wiki.transaction do  # begin transaction; do all of this or none of it
+#    # store page...
+#    wiki[home_page.page_name] = home_page
+#    # ensure that an index has been created...
+#    wiki[:wiki_index] ||= Array.new
+#    # update wiki index...
+#    wiki[:wiki_index].push(*home_page.wiki_page_references)
+#  end                   # commit changes to wiki data store file
+#  
+#  ### Some time later... ###
+#  
+#  # read wiki data...
+#  wiki.transaction(true) do  # begin read-only transaction, no changes allowed
+#    wiki.roots.each do |data_root_name|
+#      p data_root_name
+#      p wiki[data_root_name]
+#    end
+#  end
+#
+class PStore
+  binmode = defined?(File::BINARY) ? File::BINARY : 0
+  RDWR_ACCESS = File::RDWR | File::CREAT | binmode
+  RD_ACCESS = File::RDONLY | binmode
+  WR_ACCESS = File::WRONLY | File::CREAT | File::TRUNC | binmode
+
+  # The error type thrown by all PStore methods.
+  class Error < StandardError
+  end
+
+  # 
+  # To construct a PStore object, pass in the _file_ path where you would like 
+  # the data to be stored.
+  # 
+  def initialize(file)
+    dir = File::dirname(file)
+    unless File::directory? dir
+      raise PStore::Error, format("directory %s does not exist", dir)
+    end
+    if File::exist? file and not File::readable? file
+      raise PStore::Error, format("file %s not readable", file)
+    end
+    @transaction = false
+    @filename = file
+    @abort = false
+  end
+
+  # Raises PStore::Error if the calling code is not in a PStore#transaction.
+  def in_transaction
+    raise PStore::Error, "not in transaction" unless @transaction
+  end
+  # 
+  # Raises PStore::Error if the calling code is not in a PStore#transaction or
+  # if the code is in a read-only PStore#transaction.
+  # 
+  def in_transaction_wr()
+    in_transaction()
+    raise PStore::Error, "in read-only transaction" if @rdonly
+  end
+  private :in_transaction, :in_transaction_wr
+
+  #
+  # Retrieves a value from the PStore file data, by _name_.  The hierarchy of 
+  # Ruby objects stored under that root _name_ will be returned.
+  # 
+  # *WARNING*:  This method is only valid in a PStore#transaction.  It will
+  # raise PStore::Error if called at any other time.
+  #
+  def [](name)
+    in_transaction
+    @table[name]
+  end
+  #
+  # This method is just like PStore#[], save that you may also provide a 
+  # _default_ value for the object.  In the event the specified _name_ is not 
+  # found in the data store, your _default_ will be returned instead.  If you do 
+  # not specify a default, PStore::Error will be raised if the object is not 
+  # found.
+  # 
+  # *WARNING*:  This method is only valid in a PStore#transaction.  It will
+  # raise PStore::Error if called at any other time.
+  #
+  def fetch(name, default=PStore::Error)
+    in_transaction
+    unless @table.key? name
+      if default==PStore::Error
+	raise PStore::Error, format("undefined root name `%s'", name)
+      else
+	return default
+      end
+    end
+    @table[name]
+  end
+  #
+  # Stores an individual Ruby object or a hierarchy of Ruby objects in the data
+  # store file under the root _name_.  Assigning to a _name_ already in the data
+  # store clobbers the old data.
+  # 
+  # == Example:
+  # 
+  #  require "pstore"
+  #  
+  #  store = PStore.new("data_file.pstore")
+  #  store.transaction do  # begin transaction
+  #    # load some data into the store...
+  #    store[:single_object] = "My data..."
+  #    store[:obj_heirarchy] = { "Kev Jackson" => ["rational.rb", "pstore.rb"],
+  #                              "James Gray"  => ["erb.rb", "pstore.rb"] }
+  #  end                   # commit changes to data store file
+  # 
+  # *WARNING*:  This method is only valid in a PStore#transaction and it cannot
+  # be read-only.  It will raise PStore::Error if called at any other time.
+  #
+  def []=(name, value)
+    in_transaction_wr()
+    @table[name] = value
+  end
+  #
+  # Removes an object hierarchy from the data store, by _name_.
+  # 
+  # *WARNING*:  This method is only valid in a PStore#transaction and it cannot
+  # be read-only.  It will raise PStore::Error if called at any other time.
+  #
+  def delete(name)
+    in_transaction_wr()
+    @table.delete name
+  end
+
+  #
+  # Returns the names of all object hierarchies currently in the store.
+  # 
+  # *WARNING*:  This method is only valid in a PStore#transaction.  It will
+  # raise PStore::Error if called at any other time.
+  #
+  def roots
+    in_transaction
+    @table.keys
+  end
+  #
+  # Returns true if the supplied _name_ is currently in the data store.
+  # 
+  # *WARNING*:  This method is only valid in a PStore#transaction.  It will
+  # raise PStore::Error if called at any other time.
+  #
+  def root?(name)
+    in_transaction
+    @table.key? name
+  end
+  # Returns the path to the data store file.
+  def path
+    @filename
+  end
+
+  #
+  # Ends the current PStore#transaction, committing any changes to the data
+  # store immediately.
+  # 
+  # == Example:
+  # 
+  #  require "pstore"
+  #   
+  #  store = PStore.new("data_file.pstore")
+  #  store.transaction do  # begin transaction
+  #    # load some data into the store...
+  #    store[:one] = 1
+  #    store[:two] = 2
+  #  
+  #    store.commit        # end transaction here, committing changes
+  #  
+  #    store[:three] = 3   # this change is never reached
+  #  end
+  # 
+  # *WARNING*:  This method is only valid in a PStore#transaction.  It will
+  # raise PStore::Error if called at any other time.
+  #
+  def commit
+    in_transaction
+    @abort = false
+    throw :pstore_abort_transaction
+  end
+  #
+  # Ends the current PStore#transaction, discarding any changes to the data
+  # store.
+  # 
+  # == Example:
+  # 
+  #  require "pstore"
+  #   
+  #  store = PStore.new("data_file.pstore")
+  #  store.transaction do  # begin transaction
+  #    store[:one] = 1     # this change is not applied, see below...
+  #    store[:two] = 2     # this change is not applied, see below...
+  #  
+  #    store.abort         # end transaction here, discard all changes
+  #  
+  #    store[:three] = 3   # this change is never reached
+  #  end
+  # 
+  # *WARNING*:  This method is only valid in a PStore#transaction.  It will
+  # raise PStore::Error if called at any other time.
+  #
+  def abort
+    in_transaction
+    @abort = true
+    throw :pstore_abort_transaction
+  end
+
+  #
+  # Opens a new transaction for the data store.  Code executed inside a block
+  # passed to this method may read and write data to and from the data store 
+  # file.
+  # 
+  # At the end of the block, changes are committed to the data store
+  # automatically.  You may exit the transaction early with a call to either 
+  # PStore#commit or PStore#abort.  See those methods for details about how
+  # changes are handled.  Raising an uncaught Exception in the block is 
+  # equivalent to calling PStore#abort.
+  # 
+  # If _read_only_ is set to +true+, you will only be allowed to read from the
+  # data store during the transaction and any attempts to change the data will
+  # raise a PStore::Error.
+  # 
+  # Note that PStore does not support nested transactions.
+  #
+  def transaction(read_only=false)  # :yields:  pstore
+    raise PStore::Error, "nested transaction" if @transaction
+    begin
+      @rdonly = read_only
+      @abort = false
+      @transaction = true
+      value = nil
+      new_file = @filename + ".new"
+
+      content = nil
+      unless read_only
+        file = File.open(@filename, RDWR_ACCESS)
+        file.flock(File::LOCK_EX)
+        commit_new(file) if FileTest.exist?(new_file)
+        content = file.read()
+      else
+        begin
+          file = File.open(@filename, RD_ACCESS)
+          file.flock(File::LOCK_SH)
+          content = (File.open(new_file, RD_ACCESS) {|n| n.read} rescue file.read())
+        rescue Errno::ENOENT
+          content = ""
+        end
+      end
+
+      if content != ""
+	@table = load(content)
+        if !read_only
+          size = content.size
+          md5 = Digest::MD5.digest(content)
+        end
+      else
+	@table = {}
+      end
+      content = nil		# unreference huge data
+
+      begin
+	catch(:pstore_abort_transaction) do
+	  value = yield(self)
+	end
+      rescue Exception
+	@abort = true
+	raise
+      ensure
+	if !read_only and !@abort
+          tmp_file = @filename + ".tmp"
+	  content = dump(@table)
+	  if !md5 || size != content.size || md5 != Digest::MD5.digest(content)
+            File.open(tmp_file, WR_ACCESS) {|t| t.write(content)}
+            File.rename(tmp_file, new_file)
+            commit_new(file)
+          end
+          content = nil		# unreference huge data
+	end
+      end
+    ensure
+      @table = nil
+      @transaction = false
+      file.close if file
+    end
+    value
+  end
+
+  # This method is just a wrapped around Marshal.dump.
+  def dump(table)  # :nodoc:
+    Marshal::dump(table)
+  end
+
+  # This method is just a wrapped around Marshal.load.
+  def load(content)  # :nodoc:
+    Marshal::load(content)
+  end
+
+  # This method is just a wrapped around Marshal.load.
+  def load_file(file)  # :nodoc:
+    Marshal::load(file)
+  end
+
+  private
+  # Commits changes to the data store file.
+  def commit_new(f)
+    f.truncate(0)
+    f.rewind
+    new_file = @filename + ".new"
+    File.open(new_file, RD_ACCESS) do |nf|
+      FileUtils.copy_stream(nf, f)
+    end
+    File.unlink(new_file)
+  end
+end
+
+# :enddoc:
+
+if __FILE__ == $0
+  db = PStore.new("/tmp/foo")
+  db.transaction do
+    p db.roots
+    ary = db["root"] = [1,2,3,4]
+    ary[1] = [1,1.5]
+  end
+
+  1000.times do
+    db.transaction do
+      db["root"][0] += 1
+      p db["root"][0]
+    end
+  end
+
+  db.transaction(true) do
+    p db["root"]
+  end
+end

data/lib/rubysl/pstore/version.rb

@@ -0,0 +1,5 @@
+module RubySL
+  module PStore
+    VERSION = "1.0.0"
+  end
+end

data/rubysl-pstore.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+require './lib/rubysl/pstore/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "rubysl-pstore"
+  spec.version       = RubySL::PStore::VERSION
+  spec.authors       = ["Brian Shirai"]
+  spec.email         = ["brixen@gmail.com"]
+  spec.description   = %q{Ruby standard library pstore.}
+  spec.summary       = %q{Ruby standard library pstore.}
+  spec.homepage      = "https://github.com/rubysl/rubysl-pstore"
+  spec.license       = "BSD"
+
+  spec.files         = `git ls-files`.split($/)
+  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_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "mspec", "~> 1.5"
+  spec.add_development_dependency "rubysl-prettyprint", "~> 1.0"
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: rubysl-pstore
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Brian Shirai
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-12-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: mspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rubysl-prettyprint
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Ruby standard library pstore.
+email:
+- brixen@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .travis.yml
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/pstore.rb
+- lib/rubysl/pstore.rb
+- lib/rubysl/pstore/pstore.rb
+- lib/rubysl/pstore/version.rb
+- rubysl-pstore.gemspec
+homepage: https://github.com/rubysl/rubysl-pstore
+licenses:
+- BSD
+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.0.7
+signing_key: 
+specification_version: 4
+summary: Ruby standard library pstore.
+test_files: []