pstore 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3de8bbd117d11303d2372e9fd0b9db5a15fb4d6b566905101e70689cd82fbe4d
-  data.tar.gz: bbab746d38d3e6fc07bfaf54235bcb6e34727a2a20ae586620064a16de834dc2
+  metadata.gz: 4ca86b8693a69b67fa1864f055fb547d881d62979a047a7fa24e43aa0688cc01
+  data.tar.gz: b4af87cbe5e36edcf852c5465e686e477cb8ae301cd00c4dd8a38f56aa23f6e2
 SHA512:
-  metadata.gz: 4a4f1df2cafeee50e8c82a1755e8f0836f7c2b685f5372df1461cdac183d43cf3ad19b1dfa9a516ab3698e0ad1837f050be0e86b1b4944dbd5d3c625665f2b5d
-  data.tar.gz: f2b9d2cb5172cc4e09eba1ae2ec499bce9972b54028e0b89e6d26e6f66f16918254d3d643dc49d4caed17fe45ffc3278737431864de1d9a87bc429bf4c345c5b
+  metadata.gz: 8f87e2b27466bcb3dfb2b910b1fb2fafcec06beef6d4aa49c9dad2acdf170c9d5db8631b9c08097b97334ec3797043c89b96b138c363805205407d0cc0b08590
+  data.tar.gz: 0efcfca9e94dae981be03cfd191265d10c348241b243c2fd7f7ae0fa07b63781ddcf70853dea07889294fd85794fbbc34f7b00b2de67de2b16950b882fe302f2

data/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    schedule:
+      interval: 'weekly'

data/.github/workflows/test.yml

@@ -0,0 +1,22 @@
+name: test
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    name: build (${{ matrix.ruby }} / ${{ matrix.os }})
+    strategy:
+      matrix:
+        ruby: [ 2.7, 2.6, 2.5, 2.4, head ]
+        os: [ ubuntu-latest, macos-latest ]
+    runs-on: ${{ matrix.os }}
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+    - name: Install dependencies
+      run: bundle install
+    - name: Run test
+      run: rake test

data/Rakefile

@@ -7,4 +7,11 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList["test/**/test_*.rb"]
 end
 
+task :sync_tool do
+  require 'fileutils'
+  FileUtils.cp "../ruby/tool/lib/core_assertions.rb", "./test/lib"
+  FileUtils.cp "../ruby/tool/lib/envutil.rb", "./test/lib"
+  FileUtils.cp "../ruby/tool/lib/find_executable.rb", "./test/lib"
+end
+
 task :default => :test

data/lib/pstore.rb

@@ -10,88 +10,324 @@
 
 require "digest"
 
-#
-# 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.
+# \PStore implements a file based persistence mechanism based on a Hash.
+# User code can store hierarchies of Ruby objects (values)
+# into the data store 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.
+# 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.
+#
+# There are three important concepts here (details at the links):
+#
+# - {Store}[rdoc-ref:PStore@The+Store]: a store is an instance of \PStore.
+# - {Entries}[rdoc-ref:PStore@Entries]: the store is hash-like;
+#   each entry is the key for a stored object.
+# - {Transactions}[rdoc-ref:PStore@Transactions]: each transaction is a collection
+#   of prospective changes to the store;
+#   a transaction is defined in the block given with a call
+#   to PStore#transaction.
+#
+# == About the Examples
+#
+# Examples on this page need a store that has known properties.
+# They can get a new (and populated) store by calling thus:
+#
+#   example_store do |store|
+#     # Example code using store goes here.
+#   end
+#
+# All we really need to know about +example_store+
+# is that it yields a fresh store with a known population of entries;
+# its implementation:
+#
+#   require 'pstore'
+#   require 'tempfile'
+#   # Yield a pristine store for use in examples.
+#   def example_store
+#     # Create the store in a temporary file.
+#     Tempfile.create do |file|
+#       store = PStore.new(file)
+#       # Populate the store.
+#       store.transaction do
+#         store[:foo] = 0
+#         store[:bar] = 1
+#         store[:baz] = 2
+#       end
+#       yield store
+#     end
+#   end
+#
+# == The Store
+#
+# The contents of the store are maintained in a file whose path is specified
+# when the store is created (see PStore.new).
+# The objects are stored and retrieved using
+# module Marshal, which means that certain objects cannot be added to the store;
+# see {Marshal::dump}[https://docs.ruby-lang.org/en/master/Marshal.html#method-c-dump].
+#
+# == Entries
+#
+# A store may have any number of entries.
+# Each entry has a key and a value, just as in a hash:
+#
+# - Key: as in a hash, the key can be (almost) any object;
+#   see {Hash Keys}[https://docs.ruby-lang.org/en/master/Hash.html#class-Hash-label-Hash+Keys].
+#   You may find it convenient to keep it simple by using only
+#   symbols or strings as keys.
+# - Value: the value may be any object that can be marshalled by \Marshal
+#   (see {Marshal::dump}[https://docs.ruby-lang.org/en/master/Marshal.html#method-c-dump])
+#   and in fact may be a collection
+#   (e.g., an array, a hash, a set, a range, etc).
+#   That collection may in turn contain nested objects,
+#   including collections, to any depth;
+#   those objects must also be \Marshal-able.
+#   See {Hierarchical Values}[rdoc-ref:PStore@Hierarchical+Values].
+#
+# == Transactions
+#
+# === The Transaction Block
+#
+# The block given with a call to method #transaction#
+# contains a _transaction_,
+# which consists of calls to \PStore methods that
+# read from or write to the store
+# (that is, all \PStore methods except #transaction itself,
+# #path, and Pstore.new):
+#
+#   example_store do |store|
+#     store.transaction do
+#       store.keys # => [:foo, :bar, :baz]
+#       store[:bat] = 3
+#       store.keys # => [:foo, :bar, :baz, :bat]
+#     end
+#   end
+#
+# Execution of the transaction is deferred until the block exits,
+# and is executed _atomically_ (all-or-nothing):
+# either all transaction calls are executed, or none are.
+# This maintains the integrity of the store.
+#
+# Other code in the block (including even calls to #path and PStore.new)
+# is executed immediately, not deferred.
+#
+# The transaction block:
+#
+# - May not contain a nested call to #transaction.
+# - Is the only context where methods that read from or write to
+#   the store are allowed.
+#
+# As seen above, changes in a transaction are made automatically
+# when the block exits.
+# The block may be exited early by calling method #commit or #abort.
+#
+# - Method #commit triggers the update to the store and exits the block:
+#
+#     example_store do |store|
+#       store.transaction do
+#         store.keys # => [:foo, :bar, :baz]
+#         store[:bat] = 3
+#         store.commit
+#         fail 'Cannot get here'
+#       end
+#       store.transaction do
+#         # Update was completed.
+#         store.keys # => [:foo, :bar, :baz, :bat]
+#       end
+#     end
+#
+# - Method #abort discards the update to the store and exits the block:
+#
+#     example_store do |store|
+#       store.transaction do
+#         store.keys # => [:foo, :bar, :baz]
+#         store[:bat] = 3
+#         store.abort
+#         fail 'Cannot get here'
+#       end
+#       store.transaction do
+#         # Update was not completed.
+#         store.keys # => [:foo, :bar, :baz]
+#       end
+#     end
+#
+# === Read-Only Transactions
+#
+# By default, a transaction allows both reading from and writing to
+# the store:
+#
+#   store.transaction do
+#     # Read-write transaction.
+#     # Any code except a call to #transaction is allowed here.
+#   end
+#
+# If argument +read_only+ is passed as +true+,
+# only reading is allowed:
+#
+#   store.transaction(true) do
+#     # Read-only transaction:
+#     # Calls to #transaction, #[]=, and #delete are not allowed here.
+#   end
+#
+# == Hierarchical Values
+#
+# The value for an entry may be a simple object (as seen above).
+# It may also be a hierarchy of objects nested to any depth:
+#
+#   deep_store = PStore.new('deep.store')
+#   deep_store.transaction do
+#     array_of_hashes = [{}, {}, {}]
+#     deep_store[:array_of_hashes] = array_of_hashes
+#     deep_store[:array_of_hashes] # => [{}, {}, {}]
+#     hash_of_arrays = {foo: [], bar: [], baz: []}
+#     deep_store[:hash_of_arrays] = hash_of_arrays
+#     deep_store[:hash_of_arrays]  # => {:foo=>[], :bar=>[], :baz=>[]}
+#     deep_store[:hash_of_arrays][:foo].push(:bat)
+#     deep_store[:hash_of_arrays]  # => {:foo=>[:bat], :bar=>[], :baz=>[]}
+#   end
+#
+# And recall that you can use
+# {dig methods}[https://docs.ruby-lang.org/en/master/dig_methods_rdoc.html]
+# in a returned hierarchy of objects.
+#
+# == Working with the Store
+#
+# === Creating a Store
+#
+# Use method PStore.new to create a store.
+# The new store creates or opens its containing file:
+#
+#   store = PStore.new('t.store')
+#
+# === Modifying the Store
+#
+# Use method #[]= to update or create an entry:
+#
+#   example_store do |store|
+#     store.transaction do
+#       store[:foo] = 1 # Update.
+#       store[:bam] = 1 # Create.
+#     end
+#   end
+#
+# Use method #delete to remove an entry:
+#
+#   example_store do |store|
+#     store.transaction do
+#       store.delete(:foo)
+#       store[:foo] # => nil
+#     end
+#   end
+#
+# === Retrieving Values
+#
+# Use method #fetch (allows default) or #[] (defaults to +nil+)
+# to retrieve an entry:
+#
+#   example_store do |store|
+#     store.transaction do
+#       store[:foo]             # => 0
+#       store[:nope]            # => nil
+#       store.fetch(:baz)       # => 2
+#       store.fetch(:nope, nil) # => nil
+#       store.fetch(:nope)      # Raises exception.
+#     end
+#   end
+#
+# === Querying the Store
+#
+# Use method #key? to determine whether a given key exists:
 #
-# 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.
+#   example_store do |store|
+#     store.transaction do
+#       store.key?(:foo) # => true
+#     end
+#   end
 #
-# == Usage example:
+# Use method #keys to retrieve keys:
+#
+#   example_store do |store|
+#     store.transaction do
+#       store.keys # => [:foo, :bar, :baz]
+#     end
+#   end
+#
+# Use method #path to retrieve the path to the store's underlying file;
+# this method may be called from outside a transaction block:
+#
+#   store = PStore.new('t.store')
+#   store.path # => "t.store"
+#
+# == Transaction Safety
+#
+# For transaction safety, see:
+#
+# - Optional argument +thread_safe+ at method PStore.new.
+# - Attribute #ultra_safe.
+#
+# Needless to say, if you're storing valuable data with \PStore, then you should
+# backup the \PStore file from time to time.
+#
+# == An Example Store
 #
 #  require "pstore"
 #
-#  # a mock wiki object...
+#  # A mock wiki object.
 #  class WikiPage
-#    def initialize( page_name, author, contents )
+#
+#    attr_reader :page_name
+#
+#    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 }
+#    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..." )
+#  # Create a new wiki 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...
+#  # Update page data and the index together, or not at all.
+#  wiki.transaction do
+#    # Store page.
 #    wiki[home_page.page_name] = home_page
-#    # ensure that an index has been created...
+#    # Create page index.
 #    wiki[:wiki_index] ||= Array.new
-#    # update wiki index...
+#    # Update wiki index.
 #    wiki[:wiki_index].push(*home_page.wiki_page_references)
-#  end                   # commit changes to wiki data store file
-#
-#  ### Some time later... ###
+#  end
 #
-#  # 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]
+#  # Read wiki data, setting argument read_only to true.
+#  wiki.transaction(true) do
+#    wiki.keys.each do |key|
+#      puts key
+#      puts wiki[key]
 #    end
 #  end
 #
-# == Transaction modes
-#
-# By default, file integrity is only ensured as long as the operating system
-# (and the underlying hardware) doesn't raise any unexpected I/O errors. If an
-# I/O error occurs while PStore is writing to its file, then the file will
-# become corrupted.
-#
-# You can prevent this by setting <em>pstore.ultra_safe = true</em>.
-# However, this results in a minor performance loss, and only works on platforms
-# that support atomic file renames. Please consult the documentation for
-# +ultra_safe+ for details.
-#
-# Needless to say, if you're storing valuable data with PStore, then you should
-# backup the PStore files from time to time.
 class PStore
+  VERSION = "0.1.2"
+
   RDWR_ACCESS = {mode: IO::RDWR | IO::CREAT | IO::BINARY, encoding: Encoding::ASCII_8BIT}.freeze
   RD_ACCESS = {mode: IO::RDONLY | IO::BINARY, encoding: Encoding::ASCII_8BIT}.freeze
   WR_ACCESS = {mode: IO::WRONLY | IO::CREAT | IO::TRUNC | IO::BINARY, encoding: Encoding::ASCII_8BIT}.freeze
@@ -100,21 +336,38 @@ class PStore
   class Error < StandardError
   end
 
-  # Whether PStore should do its best to prevent file corruptions, even when under
-  # unlikely-to-occur error conditions such as out-of-space conditions and other
-  # unusual OS filesystem errors. Setting this flag comes at the price in the form
-  # of a performance loss.
+  # Whether \PStore should do its best to prevent file corruptions,
+  # even when an unlikely error (such as memory-error or filesystem error) occurs:
+  #
+  # - +true+: changes are posted by creating a temporary file,
+  #   writing the updated data to it, then renaming the file to the given #path.
+  #   File integrity is maintained.
+  #   Note: has effect only if the filesystem has atomic file rename
+  #   (as do POSIX platforms Linux, MacOS, FreeBSD and others).
+  #
+  # - +false+ (the default): changes are posted by rewinding the open file
+  #   and writing the updated data.
+  #   File integrity is maintained if the filesystem raises
+  #   no unexpected I/O error;
+  #   if such an error occurs during a write to the store,
+  #   the file may become corrupted.
   #
-  # This flag only has effect on platforms on which file renames are atomic (e.g.
-  # all POSIX platforms: Linux, MacOS X, FreeBSD, etc). The default value is false.
   attr_accessor :ultra_safe
 
+  # Returns a new \PStore object.
+  #
+  # Argument +file+ is the path to the file in which objects are to be stored;
+  # if the file exists, it should be one that was written by \PStore.
+  #
+  #   path = 't.store'
+  #   store = PStore.new(path)
   #
-  # To construct a PStore object, pass in the _file_ path where you would like
-  # the data to be stored.
+  # A \PStore object is
+  # {reentrant}[https://en.wikipedia.org/wiki/Reentrancy_(computing)].
+  # If argument +thread_safe+ is given as +true+,
+  # the object is also thread-safe (at the cost of a small performance penalty):
   #
-  # PStore objects are always reentrant. But if _thread_safe_ is set to true,
-  # then it will become thread-safe at the cost of a minor performance hit.
+  #   store = PStore.new(path, true)
   #
   def initialize(file, thread_safe = false)
     dir = File::dirname(file)
@@ -145,169 +398,160 @@ class PStore
   end
   private :in_transaction, :in_transaction_wr
 
+  # Returns the value for the given +key+ if the key exists.
+  # +nil+ otherwise;
+  # if not +nil+, the returned value is an object or a hierarchy of objects:
   #
-  # Retrieves a value from the PStore file data, by _name_.  The hierarchy of
-  # Ruby objects stored under that root _name_ will be returned.
+  #   example_store do |store|
+  #     store.transaction do
+  #       store[:foo]  # => 0
+  #       store[:nope] # => nil
+  #     end
+  #   end
   #
-  # *WARNING*:  This method is only valid in a PStore#transaction.  It will
-  # raise PStore::Error if called at any other time.
+  # Returns +nil+ if there is no such key.
   #
-  def [](name)
+  # See also {Hierarchical Values}[rdoc-ref:PStore@Hierarchical+Values].
+  #
+  # Raises an exception if called outside a transaction block.
+  def [](key)
     in_transaction
-    @table[name]
+    @table[key]
   end
+
+  # Like #[], except that it accepts a default value for the store.
+  # If the +key+ does not exist:
   #
-  # 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.
+  # - Raises an exception if +default+ is +PStore::Error+.
+  # - Returns the value of +default+ otherwise:
   #
-  # *WARNING*:  This method is only valid in a PStore#transaction.  It will
-  # raise PStore::Error if called at any other time.
+  #     example_store do |store|
+  #       store.transaction do
+  #         store.fetch(:nope, nil) # => nil
+  #         store.fetch(:nope)      # Raises an exception.
+  #       end
+  #     end
   #
-  def fetch(name, default=PStore::Error)
+  # Raises an exception if called outside a transaction block.
+  def fetch(key, default=PStore::Error)
     in_transaction
-    unless @table.key? name
+    unless @table.key? key
       if default == PStore::Error
-        raise PStore::Error, format("undefined root name `%s'", name)
+        raise PStore::Error, format("undefined key `%s'", key)
       else
         return default
       end
     end
-    @table[name]
+    @table[key]
   end
+
+  # Creates or replaces the value for the given +key+:
   #
-  # 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_hierarchy] = { "Kev Jackson" => ["rational.rb", "pstore.rb"],
-  #                              "James Gray"  => ["erb.rb", "pstore.rb"] }
-  #  end                   # commit changes to data store file
+  #   example_store do |store|
+  #     temp.transaction do
+  #       temp[:bat] = 3
+  #     end
+  #   end
   #
-  # *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.
+  # See also {Hierarchical Values}[rdoc-ref:PStore@Hierarchical+Values].
   #
-  def []=(name, value)
+  # Raises an exception if called outside a transaction block.
+  def []=(key, value)
     in_transaction_wr
-    @table[name] = value
+    @table[key] = value
   end
+
+  # Removes and returns the value at +key+ if it exists:
   #
-  # Removes an object hierarchy from the data store, by _name_.
+  #   example_store do |store|
+  #     store.transaction do
+  #       store[:bat] = 3
+  #       store.delete(:bat)
+  #     end
+  #   end
   #
-  # *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.
+  # Returns +nil+ if there is no such key.
   #
-  def delete(name)
+  # Raises an exception if called outside a transaction block.
+  def delete(key)
     in_transaction_wr
-    @table.delete name
+    @table.delete key
   end
 
+  # Returns an array of the existing keys:
   #
-  # Returns the names of all object hierarchies currently in the store.
+  #   example_store do |store|
+  #     store.transaction do
+  #       store.keys # => [:foo, :bar, :baz]
+  #     end
+  #   end
   #
-  # *WARNING*:  This method is only valid in a PStore#transaction.  It will
-  # raise PStore::Error if called at any other time.
+  # Raises an exception if called outside a transaction block.
   #
-  def roots
+  # PStore#roots is an alias for PStore#keys.
+  def keys
     in_transaction
     @table.keys
   end
+  alias roots keys
+
+  # Returns +true+ if +key+ exists, +false+ otherwise:
   #
-  # Returns true if the supplied _name_ is currently in the data store.
+  #   example_store do |store|
+  #     store.transaction do
+  #       store.key?(:foo) # => true
+  #     end
+  #   end
   #
-  # *WARNING*:  This method is only valid in a PStore#transaction.  It will
-  # raise PStore::Error if called at any other time.
+  # Raises an exception if called outside a transaction block.
   #
-  def root?(name)
+  # PStore#root? is an alias for PStore#key?.
+  def key?(key)
     in_transaction
-    @table.key? name
+    @table.key? key
   end
-  # Returns the path to the data store file.
+  alias root? key?
+
+  # Returns the string file path used to create the store:
+  #
+  #   store.path # => "flat.store"
+  #
   def path
     @filename
   end
 
+  # Exits the current transaction block, committing any changes
+  # specified in the transaction block.
+  # See {Committing or Aborting}[rdoc-ref:PStore@Committing+or+Aborting].
   #
-  # 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.
-  #
+  # Raises an exception if called outside a transaction block.
   def commit
     in_transaction
     @abort = false
     throw :pstore_abort_transaction
   end
+
+  # Exits the current transaction block, discarding any changes
+  # specified in the transaction block.
+  # See {Committing or Aborting}[rdoc-ref:PStore@Committing+or+Aborting].
   #
-  # 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.
-  #
+  # Raises an exception if called outside a transaction block.
   def abort
     in_transaction
     @abort = true
     throw :pstore_abort_transaction
   end
 
+  # Opens a transaction block for the store.
+  # See {Transactions}[rdoc-ref:PStore@Transactions].
   #
-  # 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.
+  # With argument +read_only+ as +false+, the block may both read from
+  # and write to the store.
   #
-  # Note that PStore does not support nested transactions.
+  # With argument +read_only+ as +true+, the block may not include calls
+  # to #transaction, #[]=, or #delete.
   #
+  # Raises an exception if called within a transaction block.
   def transaction(read_only = false)  # :yields:  pstore
     value = nil
     if !@thread_safe

data/pstore.gemspec

@@ -1,17 +1,22 @@
-lib = File.expand_path("lib", __dir__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "pstore/version"
+# frozen_string_literal: true
+
+name = File.basename(__FILE__, ".gemspec")
+version = ["lib", Array.new(name.count("-")+1, "..").join("/")].find do |dir|
+  break File.foreach(File.join(__dir__, dir, "#{name.tr('-', '/')}.rb")) do |line|
+    /^\s*VERSION\s*=\s*"(.*)"/ =~ line and break $1
+  end rescue nil
+end
 
 Gem::Specification.new do |spec|
-  spec.name          = "pstore"
-  spec.version       = PStore::VERSION
-  spec.authors       = ["Hiroshi SHIBATA"]
-  spec.email         = ["hsbt@ruby-lang.org"]
+  spec.name          = name
+  spec.version       = version
+  spec.authors       = ["Yukihiro Matsumoto"]
+  spec.email         = ["matz@ruby-lang.org"]
 
   spec.summary       = %q{Transactional File Storage for Ruby Objects}
   spec.description   = spec.summary
   spec.homepage      = "https://github.com/ruby/pstore"
-  spec.license       = "BSD-2-Clause"
+  spec.licenses      = ["Ruby", "BSD-2-Clause"]
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/ruby/pstore"
@@ -19,7 +24,7 @@ Gem::Specification.new do |spec|
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+    `git ls-files -z 2>/dev/null`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   end
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }

metadata

@@ -1,24 +1,25 @@
 --- !ruby/object:Gem::Specification
 name: pstore
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
-- Hiroshi SHIBATA
-autorequire: 
+- Yukihiro Matsumoto
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2019-11-06 00:00:00.000000000 Z
+date: 2022-12-05 00:00:00.000000000 Z
 dependencies: []
 description: Transactional File Storage for Ruby Objects
 email:
-- hsbt@ruby-lang.org
+- matz@ruby-lang.org
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/dependabot.yml"
+- ".github/workflows/test.yml"
 - ".gitignore"
-- ".travis.yml"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -26,15 +27,15 @@ files:
 - bin/console
 - bin/setup
 - lib/pstore.rb
-- lib/pstore/version.rb
 - pstore.gemspec
 homepage: https://github.com/ruby/pstore
 licenses:
+- Ruby
 - BSD-2-Clause
 metadata:
   homepage_uri: https://github.com/ruby/pstore
   source_code_uri: https://github.com/ruby/pstore
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -49,8 +50,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.4.0.dev
+signing_key:
 specification_version: 4
 summary: Transactional File Storage for Ruby Objects
 test_files: []

data/.travis.yml

@@ -1,7 +0,0 @@
----
-sudo: false
-language: ruby
-cache: bundler
-rvm:
-  - 2.6.3
-before_install: gem install bundler -v 2.0.2

data/lib/pstore/version.rb

@@ -1,3 +0,0 @@
-class PStore
-  VERSION = "0.1.0"
-end