From: James Edward Gray II Date: 2005-10-27T05:49:23+09:00 Subject: [PATCH] PStore Documentation --Apple-Mail-8--418779434 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset=US-ASCII; delsp=yes; format=flowed The attached patch completely documents the PStore library. Please let me know if there are any issues with it. Otherwise, would some kind soul please apply this? James Edward Gray II --Apple-Mail-8--418779434 Content-Transfer-Encoding: 7bit Content-Type: application/octet-stream; x-unix-mode=0644; name="pstore_docs.diff" Content-Disposition: attachment; filename=pstore_docs.diff Index: lib/.document =================================================================== RCS file: /src/ruby/lib/.document,v retrieving revision 1.1.2.7 diff -u -r1.1.2.7 .document --- lib/.document 25 Oct 2005 06:38:26 -0000 1.1.2.7 +++ lib/.document 26 Oct 2005 20:45:39 -0000 @@ -25,6 +25,7 @@ observer.rb optionparser.rb pathname.rb +pstore.rb rational.rb set.rb shellwords.rb Index: lib/pstore.rb =================================================================== RCS file: /src/ruby/lib/pstore.rb,v retrieving revision 1.17.2.3 diff -u -r1.17.2.3 pstore.rb --- lib/pstore.rb 27 Oct 2004 09:16:20 -0000 1.17.2.3 +++ lib/pstore.rb 26 Oct 2005 20:45:39 -0000 @@ -1,24 +1,92 @@ +# = PStore -- Transactional File Storage for Ruby Objects # -# How to use: +# pstore.rb - +# by unknown +# documentation by Kev Jackson and James Edward Gray II # -# db = PStore.new("/tmp/foo") -# db.transaction do -# p db.roots -# ary = db["root"] = [1,2,3,4] -# ary[0] = [1,1.5] -# end - -# db.transaction do -# p db["root"] -# end +# See PStore for documentation. + require "fileutils" require "digest/md5" +# +# PStore implements a file based persistance 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, of course. +# Then later user code may 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 upated but others were not. +# +# Behind the seens, Ruby objects are stored to the data store file with Marhsal. +# 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 + # The error type thrown by all PStore methods. class Error < StandardError end + # + # To construct a PStore object, simply 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 @@ -32,19 +100,41 @@ @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) unless @table.key? name if default==PStore::Error @@ -55,38 +145,137 @@ end self[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, dicard 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) raise PStore::Error, "nested transaction" if @transaction begin @@ -155,19 +344,23 @@ value end - def dump(table) + # This method is just a wrapped around Marshal.dump(). + def dump(table) # :nodoc: Marshal::dump(table) end - def load(content) + # This method is just a wrapped around Marshal.load(). + def load(content) # :nodoc: Marshal::load(content) end - def load_file(file) + # 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 @@ -180,6 +373,8 @@ end end +# :enddoc: + if __FILE__ == $0 db = PStore.new("/tmp/foo") db.transaction do --Apple-Mail-8--418779434--