File Manager

# 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
#
# ## 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 *pstore.ultra_safe = true*. 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
  public

  # 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 []: (untyped name) -> untyped

  # 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
  #
  # **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 []=: (untyped name, untyped value) -> untyped

  # 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: () -> untyped

  # 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: () -> nil

  # 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: (untyped name) -> untyped

  # 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: (untyped name, ?untyped default) -> untyped

  # Returns the path to the data store file.
  #
  def path: () -> untyped

  # 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?: (untyped name) -> bool

  # 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: () -> Array[untyped]

  # 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: (?untyped read_only) -> untyped

  # 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.
  #
  # 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.
  #
  def ultra_safe: () -> untyped

  def ultra_safe=: (untyped) -> untyped

  private

  def dump: (untyped table) -> untyped

  def empty_marshal_checksum: () -> untyped

  def empty_marshal_data: () -> untyped

  # Raises PStore::Error if the calling code is not in a PStore#transaction.
  #
  def in_transaction: () -> untyped

  # 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: () -> untyped

  # To construct a PStore object, pass in the *file* path where you would like the
  # data to be stored.
  #
  # 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.
  #
  def initialize: (untyped file, ?boolish thread_safe) -> untyped

  def load: (untyped content) -> untyped

  # Load the given PStore file. If `read_only` is true, the unmarshalled Hash will
  # be returned. If `read_only` is false, a 3-tuple will be returned: the
  # unmarshalled Hash, a checksum of the data, and the size of the data.
  #
  def load_data: (untyped file, untyped read_only) -> untyped

  def on_windows?: () -> bool

  # Open the specified filename (either in read-only mode or in read-write mode)
  # and lock it for reading or writing.
  #
  # The opened File object will be returned. If *read_only* is true, and the file
  # does not exist, then nil will be returned.
  #
  # All exceptions are propagated.
  #
  def open_and_lock_file: (untyped filename, untyped read_only) -> untyped

  def save_data: (untyped original_checksum, untyped original_file_size, untyped file) -> untyped

  def save_data_with_atomic_file_rename_strategy: (untyped data, untyped file) -> untyped

  def save_data_with_fast_strategy: (untyped data, untyped file) -> untyped
end

PStore::EMPTY_MARSHAL_CHECKSUM: String

PStore::EMPTY_MARSHAL_DATA: String

PStore::EMPTY_STRING: String

PStore::RDWR_ACCESS: Hash[untyped, untyped]

PStore::RD_ACCESS: Hash[untyped, untyped]

PStore::VERSION: String

PStore::WR_ACCESS: Hash[untyped, untyped]