ruby-changes:72445
From: Burdette <ko1@a...>
Date: Thu, 7 Jul 2022 07:05:17 +0900 (JST)
Subject: [ruby-changes:72445] 7ba5c0633c (master): [ruby/pstore] Emphasize keys instead of roots, values instead of objects (https://github.com/ruby/pstore/pull/7)
https://git.ruby-lang.org/ruby.git/commit/?id=7ba5c0633c From 7ba5c0633c228b75581c102796a484b6bf515022 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Wed, 6 Jul 2022 17:04:47 -0500 Subject: [ruby/pstore] Emphasize keys instead of roots, values instead of objects (https://github.com/ruby/pstore/pull/7) Modifies RDoc to Emphasize keys instead of roots, values instead of objects. Code: Renames method #root? to #key? and method #roots to #keys. Aliases method #key as #root and method #keys as #roots. Adds testing for all four methods. https://github.com/ruby/pstore/commit/4436ea0891 --- lib/pstore.rb | 89 ++++++++++++++++++++++++++++------------------------- test/test_pstore.rb | 32 +++++++++++++++++++ 2 files changed, 79 insertions(+), 42 deletions(-) diff --git a/lib/pstore.rb b/lib/pstore.rb index 5be7044376..8d7137aa39 100644 --- a/lib/pstore.rb +++ b/lib/pstore.rb @@ -25,11 +25,11 @@ require "digest" https://github.com/ruby/ruby/blob/trunk/lib/pstore.rb#L25 # That carries the usual limitations. Proc objects cannot be marshalled, # for example. # -# There are three key terms here (details at the links): +# There are three important concepts here (details at the links): # # - {Store}[rdoc-ref:PStore@The+Store]: a store is an instance of \PStore. -# - {Roots}[rdoc-ref:PStore@Roots]: the store is hash-like; -# each root is a key for a stored object. +# - {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 @@ -45,7 +45,7 @@ require "digest" https://github.com/ruby/ruby/blob/trunk/lib/pstore.rb#L45 # end # # All we really need to know about +example_store+ -# is that it yields a fresh store with a known population of roots; +# is that it yields a fresh store with a known population of entries; # its implementation: # # require 'pstore' @@ -73,10 +73,10 @@ require "digest" https://github.com/ruby/ruby/blob/trunk/lib/pstore.rb#L73 # 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]. # -# == Roots +# == Entries # -# A store may have any number of entries, called _roots_. -# Each root has a key and a value, just as in a hash: +# 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]. @@ -89,7 +89,7 @@ require "digest" https://github.com/ruby/ruby/blob/trunk/lib/pstore.rb#L89 # That collection may in turn contain nested objects, # including collections, to any depth; # those objects must also be \Marshal-able. -# See {Deep Root Values}[rdoc-ref:PStore@Deep+Root+Values]. +# See {Hierarchical Values}[rdoc-ref:PStore@Hierarchical+Values]. # # == Transactions # @@ -104,9 +104,9 @@ require "digest" https://github.com/ruby/ruby/blob/trunk/lib/pstore.rb#L104 # # example_store do |store| # store.transaction do -# store.roots # => [:foo, :bar, :baz] +# store.keys # => [:foo, :bar, :baz] # store[:bat] = 3 -# store.roots # => [:foo, :bar, :baz, :bat] +# store.keys # => [:foo, :bar, :baz, :bat] # end # end # @@ -132,14 +132,14 @@ require "digest" https://github.com/ruby/ruby/blob/trunk/lib/pstore.rb#L132 # # example_store do |store| # store.transaction do -# store.roots # => [:foo, :bar, :baz] +# store.keys # => [:foo, :bar, :baz] # store[:bat] = 3 # store.commit # fail 'Cannot get here' # end # store.transaction do # # Update was completed. -# store.roots # => [:foo, :bar, :baz, :bat] +# store.keys # => [:foo, :bar, :baz, :bat] # end # end # @@ -147,14 +147,14 @@ require "digest" https://github.com/ruby/ruby/blob/trunk/lib/pstore.rb#L147 # # example_store do |store| # store.transaction do -# store.roots # => [:foo, :bar, :baz] +# store.keys # => [:foo, :bar, :baz] # store[:bat] = 3 # store.abort # fail 'Cannot get here' # end # store.transaction do # # Update was not completed. -# store.roots # => [:foo, :bar, :baz] +# store.keys # => [:foo, :bar, :baz] # end # end # @@ -176,9 +176,9 @@ require "digest" https://github.com/ruby/ruby/blob/trunk/lib/pstore.rb#L176 # # Calls to #transaction, #[]=, and #delete are not allowed here. # end # -# == Deep Root Values +# == Hierarchical Values # -# The value for a root may be a simple object (as seen above). +# 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') @@ -208,7 +208,7 @@ require "digest" https://github.com/ruby/ruby/blob/trunk/lib/pstore.rb#L208 # # === Modifying the Store # -# Use method #[]= to update or create a root: +# Use method #[]= to update or create an entry: # # example_store do |store| # store.transaction do @@ -217,7 +217,7 @@ require "digest" https://github.com/ruby/ruby/blob/trunk/lib/pstore.rb#L217 # end # end # -# Use method #delete to remove a root: +# Use method #delete to remove an entry: # # example_store do |store| # store.transaction do @@ -226,10 +226,10 @@ require "digest" https://github.com/ruby/ruby/blob/trunk/lib/pstore.rb#L226 # end # end # -# === Retrieving Stored Objects +# === Retrieving Values # # Use method #fetch (allows default) or #[] (defaults to +nil+) -# to retrieve a root: +# to retrieve an entry: # # example_store do |store| # store.transaction do @@ -243,19 +243,19 @@ require "digest" https://github.com/ruby/ruby/blob/trunk/lib/pstore.rb#L243 # # === Querying the Store # -# Use method #root? to determine whether a given root exists: +# Use method #key? to determine whether a given key exists: # # example_store do |store| # store.transaction do -# store.root?(:foo) # => true +# store.key?(:foo) # => true # end # end # -# Use method #roots to retrieve root keys: +# Use method #keys to retrieve keys: # # example_store do |store| # store.transaction do -# store.roots # => [:foo, :bar, :baz] +# store.keys # => [:foo, :bar, :baz] # end # end # @@ -319,9 +319,9 @@ require "digest" https://github.com/ruby/ruby/blob/trunk/lib/pstore.rb#L319 # # # Read wiki data, setting argument read_only to true. # wiki.transaction(true) do -# wiki.roots.each do |root| -# puts root -# puts wiki[root] +# wiki.keys.each do |key| +# puts key +# puts wiki[key] # end # end # @@ -398,7 +398,7 @@ class PStore https://github.com/ruby/ruby/blob/trunk/lib/pstore.rb#L398 end private :in_transaction, :in_transaction_wr - # Returns the object for the given +key+ if the key exists. + # 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: # @@ -409,9 +409,9 @@ class PStore https://github.com/ruby/ruby/blob/trunk/lib/pstore.rb#L409 # end # end # - # Returns +nil+ if there is no such root. + # Returns +nil+ if there is no such key. # - # See also {Deep Root Values}[rdoc-ref:PStore@Deep+Root+Values]. + # See also {Hierarchical Values}[rdoc-ref:PStore@Hierarchical+Values]. # # Raises an exception if called outside a transaction block. def [](key) @@ -420,7 +420,7 @@ class PStore https://github.com/ruby/ruby/blob/trunk/lib/pstore.rb#L420 end # Like #[], except that it accepts a default value for the store. - # If the root for the given +key+ does not exist: + # If the +key+ does not exist: # # - Raises an exception if +default+ is +PStore::Error+. # - Returns the value of +default+ otherwise: @@ -437,7 +437,7 @@ class PStore https://github.com/ruby/ruby/blob/trunk/lib/pstore.rb#L437 in_transaction unless @table.key? key if default == PStore::Error - raise PStore::Error, format("undefined root key `%s'", key) + raise PStore::Error, format("undefined key `%s'", key) else return default end @@ -445,8 +445,7 @@ class PStore https://github.com/ruby/ruby/blob/trunk/lib/pstore.rb#L445 @table[key] end - # Creates or replaces an object or hierarchy of objects - # at the root for +key+: + # Creates or replaces the value for the given +key+: # # example_store do |store| # temp.transaction do @@ -454,7 +453,7 @@ class PStore https://github.com/ruby/ruby/blob/trunk/lib/pstore.rb#L453 # end # end # - # See also {Deep Root Values}[rdoc-ref:PStore@Deep+Root+Values]. + # See also {Hierarchical Values}[rdoc-ref:PStore@Hierarchical+Values]. # # Raises an exception if called outside a transaction block. def []=(key, value) @@ -471,7 +470,7 @@ class PStore https://github.com/ruby/ruby/blob/trunk/lib/pstore.rb#L470 # end # end # - # Returns +nil+ if there is no such root. + # Returns +nil+ if there is no such key. # # Raises an exception if called outside a transaction block. def delete(key) @@ -479,33 +478,39 @@ class PStore https://github.com/ruby/ruby/blob/trunk/lib/pstore.rb#L478 @table.delete key end - # Returns an array of the keys of the existing roots: + # Returns an array of the existing keys: # # example_store do |store| # store.transaction do - # store.roots # => [:foo, :bar, :baz] + # store.keys # => [:foo, :bar, :baz] # end # end # # Raises an exception if called outside a transaction block. - def roots + # + # PSt (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/