class PStore

PStore 实现了一种基于 Hash 的文件持久化机制。用户代码可以通过名称（键）将 Ruby 对象（值）的层次结构存储到数据存储中。对象层次结构可以只是一个单独的对象。用户代码稍后可以从数据存储中读取值，甚至可以根据需要更新数据。

事务行为确保任何更改都会一起成功或失败。这可以用来确保数据存储不会处于临时状态，即某些值已更新而其他值未更新。

在幕后，Ruby 对象使用 Marshal 存储到数据存储文件中。这带有通常的限制。例如，Proc 对象无法被编组。

这里有三个重要的概念（详情请查看链接）

• 存储：存储是 PStore 的一个实例。

• 条目：存储类似哈希；每个条目都是存储对象的键。

• 事务：每个事务都是对存储的预期更改的集合；事务在调用 PStore#transaction 时给定的块中定义。

关于示例¶ ↑

此页面上的示例需要一个具有已知属性的存储。它们可以通过调用以下内容来获取新的（和填充的）存储

example_store do |store|
  # Example code using store goes here.
end

我们真正需要了解 example_store 的是，它会产生一个具有已知条目填充的新存储；它的实现

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

存储¶ ↑

存储的内容保存在一个文件中，该文件的路径在创建存储时指定（请参阅 PStore.new）。对象使用模块 Marshal 进行存储和检索，这意味着某些对象无法添加到存储中；请参阅 Marshal::dump。

条目¶ ↑

一个存储可以有任意数量的条目。每个条目都有一个键和一个值，就像在哈希中一样

• 键：就像在哈希中一样，键可以是（几乎）任何对象；请参阅 Hash。您可能会发现只使用符号或字符串作为键会很方便。

• 值：该值可以是任何可以被 Marshal 编组的对象（请参阅 Marshal::dump），并且实际上可以是集合（例如，数组、哈希、集合、范围等）。该集合又可以包含嵌套的对象，包括任何深度的集合；这些对象也必须是可 Marshal 的。请参阅 分层值。

事务¶ ↑

事务块¶ ↑

在调用 transaction 方法时给定的块包含一个事务，该事务包含对 PStore 方法的调用，这些方法从存储中读取或写入存储（即，除了 transaction 本身、path 和 Pstore.new 之外的所有 PStore 方法）

example_store do |store|
  store.transaction do
    store.keys # => [:foo, :bar, :baz]
    store[:bat] = 3
    store.keys # => [:foo, :bar, :baz, :bat]
  end
end

事务的执行会延迟到块退出，并且是原子执行的（全有或全无）：要么执行所有事务调用，要么都不执行。这保持了存储的完整性。

块中的其他代码（甚至包括对 path 和 PStore.new 的调用）会立即执行，而不是延迟执行。

事务块

• 可能不包含对 transaction 的嵌套调用。

• 是唯一允许从存储读取或写入存储的方法的上下文。

如上所述，当块退出时，事务中的更改会自动进行。可以通过调用方法 commit 或 abort 来提前退出块。

• 方法 commit 会触发对存储的更新并退出块

  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
  

• 方法 abort 会丢弃对存储的更新并退出块

  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
  

只读事务¶ ↑

默认情况下，事务允许从存储读取和写入存储

store.transaction do
  # Read-write transaction.
  # Any code except a call to #transaction is allowed here.
end

如果参数 read_only 作为 true 传递，则只允许读取

store.transaction(true) do
  # Read-only transaction:
  # Calls to #transaction, #[]=, and #delete are not allowed here.
end

分层值¶ ↑

条目的值可以是一个简单的对象（如上所述）。它也可以是嵌套到任何深度的对象层次结构

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

请记住，您可以在返回的对象层次结构中使用 dig 方法。

使用存储¶ ↑

创建存储¶ ↑

使用方法 PStore.new 创建存储。新存储会创建或打开其包含文件

store = PStore.new('t.store')

修改存储¶ ↑

使用方法 []= 更新或创建条目

example_store do |store|
  store.transaction do
    store[:foo] = 1 # Update.
    store[:bam] = 1 # Create.
  end
end

使用方法 delete 删除条目

example_store do |store|
  store.transaction do
    store.delete(:foo)
    store[:foo] # => nil
  end
end

检索值¶ ↑

使用方法 fetch（允许默认值）或 []（默认为 nil）检索条目

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

查询存储¶ ↑

使用方法 key? 确定给定的键是否存在

example_store do |store|
  store.transaction do
    store.key?(:foo) # => true
  end
end

使用方法 keys 检索键

example_store do |store|
  store.transaction do
    store.keys # => [:foo, :bar, :baz]
  end
end

使用方法 path 检索存储的底层文件的路径；此方法可以在事务块之外调用

store = PStore.new('t.store')
store.path # => "t.store"

事务安全性¶ ↑

有关事务安全性，请参阅

• 方法 PStore.new 的可选参数 thread_safe。

• 属性 ultra_safe。

不用说，如果您使用 PStore 存储有价值的数据，那么您应该不时备份 PStore 文件。

示例存储¶ ↑

require "pstore"

# A mock wiki object.
class WikiPage

  attr_reader :page_name

  def initialize(page_name, author, contents)
    @page_name = page_name
    @revisions = Array.new
    add_revision(author, contents)
  end

  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 wiki page.
home_page = WikiPage.new("HomePage", "James Edward Gray II",
                         "A page about the JoysOfDocumentation..." )

wiki = PStore.new("wiki_pages.pstore")
# Update page data and the index together, or not at all.
wiki.transaction do
  # Store page.
  wiki[home_page.page_name] = home_page
  # Create page index.
  wiki[:wiki_index] ||= Array.new
  # Update wiki index.
  wiki[:wiki_index].push(*home_page.wiki_page_references)
end

# 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