memstore 1.2.0 → 1.2.1

data/lib/memstore.rb

@@ -7,18 +7,22 @@ require "memstore/queries"
 
 module MemStore
 
+  # Shortcut to ObjectStore::new
   def self.new(key=nil, items={})
     ObjectStore.new(key, items)
   end
 
+  # Shortcut to ObjectStore::from_binary
   def self.from_binary(binary)
     ObjectStore.from_binary(binary)
   end
 
+  # Shortcut to ObjectStore::from_file
   def self.from_file(file)
     ObjectStore.from_file(file)
   end
 
+  # Shortcut to ObjectStore::with_file
   def self.with_file(file, key=nil, items={}, &block)
     ObjectStore.with_file(file, key, items, &block)
   end

data/lib/memstore/hashstore.rb

@@ -2,11 +2,61 @@
 
 module MemStore
 
+  # A HashStore accesses item attributes through item[attribute].
   class HashStore < ObjectStore
 
+    # Initializes a HashStore.
+    #
+    # key   - Optional Object used as an item’s key attribute (default: nil).
+    #         When no key is specified, Object#hash will be used for uniquely identifying items.
+    # items - Optional Hash of items to initialize the data store with (default: empty Hash).
+    #
+    # Examples
+    #
+    #   store = HashStore.new
+    #   store = HashStore.new(:id)
+    #   store = HashStore.new(nil, { a.hash => a, b.hash => b, c.hash => c })
+    #   store = HashStore.new(:id, { 1 => a, 2 => b, 3 => c })
+    #
+    # Returns initialized ObjectStore.
+    def initialize(key=nil, items={})
+      @key, @items = key, items
+    end
+
+    # Returns data store as a Hash with the fields :key and :items.
+    def to_hash
+      { key: @key, items: @items }
+    end
+
+    # Restores a data store from binary format.
+    #
+    # binary - Binary data containing a serialized instance of HashStore.
+    #
+    # Examples
+    #
+    #   store = HashStore.from_binary(IO.read(file))
+    #
+    # Returns instance of HashStore
+    #   or nil if marshalling failed or marshalled object isn’t a HashStore.
+    # Raises whatever Marshal::load raises.
+    def self.from_binary(binary)
+      restored = Marshal.load(binary) rescue nil
+      if restored.instance_of?(HashStore) then restored else nil end
+    end
+
+    # Restores a data store from a Hash.
+    #
+    # hash - Hash that contains a serialized HashStore.
+    #        It must have the fields :key/"key" and :items/"items".
+    #
+    # Examples
+    #
+    #   store = HashStore.from_hash(hash)
+    #
+    # Returns instance of HashStore
+    #   or nil if hash isn’t a Hash or doesn’t have the required fields.
     def self.from_hash(hash)
       begin
-
         if hash.has_key?(:key) then key = hash[:key]
         elsif hash.has_key? "key" then key = hash["key"]
         else return nil end
@@ -16,26 +66,30 @@ module MemStore
         else return nil end
 
         if items.is_a?(Hash) then self.new(key, items) else self.new(key) end
-
       rescue
         nil
       end
     end
 
-    def initialize(key=nil, items={})
-      @key, @items = key, items
-    end
-
-    def to_hash
-      { key: @key, items: @items }
-    end
-
     private
 
+    # Internal: Obtains the key attribute of an item.
+    #
+    # item - Object that responds to the [] operator (e.g. Hash).
+    #
+    # Returns result of calling the [] operator with the key attribute on the item.
+    # Raises NoMethodError when item does’t respond to the key attribute method.
     def key(item)
       if @key.nil? then item.hash else item[@key] end
     end
 
+    # Internal: Obtains the specified attribute of an item.
+    #
+    # item - Object that responds to the [] operator (e.g. Hash).
+    # attribute - Object used as the attribute key in the item.
+    #
+    # Returns result of calling the [] operator with the attribute on the item.
+    # Raises NoMethodError when item does’t respond to the [] operator.
     def attr(item, attribute)
       item[attribute]
     end

data/lib/memstore/json.rb

@@ -23,7 +23,7 @@ module MemStore
     end
 
     def self.with_json_file(file, key=nil, items={}, &block)
-      self.run_with_file(:from_json_file, :to_json_file, file, key, items, &block)
+      self.execute_with_file(:from_json_file, :to_json_file, file, key, items, &block)
     end
 
   end

data/lib/memstore/msgpack.rb

@@ -23,7 +23,7 @@ module MemStore
     end
 
     def self.with_msgpack_file(file, key=nil, items={}, &block)
-      self.run_with_file(:from_msgpack_file, :to_msgpack_file, file, key, items, &block)
+      self.execute_with_file(:from_msgpack_file, :to_msgpack_file, file, key, items, &block)
     end
 
   end

data/lib/memstore/objectstore.rb

@@ -2,39 +2,100 @@
 
 module MemStore
 
+  # An ObjectStore accesses item attributes through item#attribute.
   class ObjectStore
 
+    # Initializes an ObjectStore.
+    #
+    # key   - Optional Symbol or String naming the method to obtain an item’s key attribute (default: nil).
+    #         When no key is specified, Object#hash will be used for uniquely identifying items.
+    # items - Optional Hash of items to initialize the data store with (default: empty Hash).
+    #
+    # Examples
+    #
+    #   store = ObjectStore.new
+    #   store = ObjectStore.new(:id)
+    #   store = ObjectStore.new(nil, { a.hash => a, b.hash => b, c.hash => c })
+    #   store = ObjectStore.new(:id, { 1 => a, 2 => b, 3 => c })
+    #
+    # Returns initialized ObjectStore.
     def initialize(key=nil, items={})
       @key = key || :hash
       @items = items
     end
 
+    # Provides access to internal items collection (which is simply a Hash).
     attr_accessor :items
 
+    # Inserts one or more items into the data store, can be chained.
+    # Also available as #<<, which only allows for one item at a time.
+    #
+    # items - One or more Objects that respond to the method specified as key attribute.
+    #
+    # Examples
+    #
+    #   store.insert(a).insert(b).insert(c)
+    #   store.insert(a, b, c)
+    #   store << a << b << c
+    #
+    # Returns the data store itself to enable chaining.
+    # Raises NoMethodError when an item does’t respond to the key attribute method.
     def insert(*items)
       items.each { |item| @items[key(item)] = item }
       self
     end
     alias_method :<<, :insert
     
+    # Returns total number of items in the data store. Also available as #size.
     def length
       @items.length
     end
     alias_method :size, :length
-    alias_method :count, :length
 
+    # Retrieves one or more items by key.
+    #
+    # keys - One or more Objects or Ranges that are keys of items.
+    #        For a Range, all items with keys in that range are returned.
+    #
+    # Examples
+    #
+    #   store[1]
+    #   store[1, 2, 3]
+    #   store[1..3]
+    #   store[1, 3..5, 7]
+    #
+    # Returns an Object if a single key was given
+    #   or nil if no item with that key exists
+    #   or an Array of Objects when multiple keys were given
+    #   in which nil is placed wherever there isn’t an item with that key.
     def [](*keys)
       return @items[keys.first] if keys.length == 1 && !keys.first.is_a?(Range)
-      keys.inject [] do |items, key|
+      keys.inject([]) do |items, key|
         if key.is_a?(Range) then key.inject(items) { |i, k| i << @items[k] }
         else items << @items[key] end
       end
     end
 
+    # Returns all items as an Array.
     def all
       @items.values
     end
 
+    # Deletes one or more items by reference. Also available as #delete_item and #delete.
+    #
+    # items - One or more Objects that respond to the method specified as key attribute.
+    #
+    # Examples
+    #
+    #   store.delete_item(a)
+    #   store.delete_items(a, b, c)
+    #   store.delete(a)
+    #   store.delete(a, b, c)
+    #
+    # Returns the Object that was removed if a single item was given
+    #   or nil if the item isn’t in the data store
+    #   or an Array of Objects that were removed when multiple items were given
+    #   in which nil is placed wherever that item isn’t in the data store.
     def delete_items(*items)
       return @items.delete(key(items.first)) if items.length == 1
       items.collect { |item| @items.delete(key(item)) }
@@ -42,47 +103,147 @@ module MemStore
     alias_method :delete_item, :delete_items
     alias_method :delete, :delete_items
 
+    # Deletes one or more items by key. Also available as #delete_key.
+    #
+    # keys - One or more Objects or Ranges that are keys of items.
+    #        For a Range, all items with keys in that range are deleted.
+    #
+    # Examples
+    #
+    #   store.delete_key(1)
+    #   store.delete_keys(1, 2, 3)
+    #   store.delete_keys(1..3)
+    #   store.delete_keys(1, 3..5, 7)
+    #
+    # Returns the Object that was removed if a single key was given
+    #   or nil if no item with that key exists
+    #   or an Array of Objects that were removed when multiple keys were given
+    #   in which nil is placed wherever there isn’t an item with that key.
     def delete_keys(*keys)
       return @items.delete(keys.first) if keys.length == 1 && !keys.first.is_a?(Range)
-      keys.inject [] do |items, key|
+      keys.inject([]) do |items, key|
         if key.is_a?(Range) then key.inject(items) { |i, k| i << @items.delete(k) }
         else items << @items.delete(key) end
       end
     end
     alias_method :delete_key, :delete_keys
 
-    def self.from_binary(binary)
-      restored = Marshal.load(binary) rescue nil
-      if restored.kind_of?(ObjectStore) || restored.kind_of?(HashStore) then restored else nil end
-    end
-
-    def self.from_file(file)
-      self.from_binary(IO.read(file)) rescue nil
-    end
-
+    # Returns data store in binary format.
+    # Raises whatever Marshal::dump raises.
     def to_binary
       Marshal.dump(self)
     end
 
+    # Writes data store to a file in binary format.
+    #
+    # file - IO stream of file name as String.
+    #
+    # Returns number of bytes that were written to the file.
+    # Raises whatever IO::write raises.
     def to_file(file)
       IO.write(file, self.to_binary)
     end
 
+    # Restores a data store from binary format.
+    #
+    # binary - Binary data containing a serialized instance of ObjectStore.
+    #
+    # Examples
+    #
+    #   store = ObjectStore.from_binary(IO.read(file))
+    #
+    # Returns instance of ObjectStore
+    #   or nil if marshalling failed or marshalled object isn’t an ObjectStore.
+    # Raises whatever Marshal::load raises.
+    def self.from_binary(binary)
+      restored = Marshal.load(binary) rescue nil
+      if restored.instance_of?(ObjectStore) then restored else nil end
+    end
+
+    # Restores a data store from a binary file.
+    #
+    # file - IO stream or file name as String.
+    #
+    # Examples
+    #
+    #   store = ObjectStore.from_file(file)
+    #
+    # Returns instance of ObjectStore or nil (result of ::from_binary)
+    #   or nil if file IO failed, e.g. because file doesn’t exist or isn’t readable.
+    # Raises whatever IO::read or Marshal::load raise.
+    def self.from_file(file)
+      self.from_binary(IO.read(file)) rescue nil
+    end
+
+    # Executes a given block while keeping an exclusive lock on a file.
+    # Allows to use the same file for persistence from multiple threads/processes.
+    # Tries to deserialize a data store from the file using ::from_file.
+    # If that fails, a new one will be created using the supplied key and items.
+    # Writes data store back to file using #to_file after block returns.
+    #
+    # file - IO stream or file name as String.
+    # key - Optional key attribute (Symbol or String) to use in ::new (default: nil).
+    # items - Optional items Hash to use in ::new (default: empty Hash).
+    # block - Block that will be called after a data store was restored or created.
+    #
+    # Yields the restored or newly created data store.
+    #
+    # Examples
+    #
+    #   size_after_changes = ObjectStore.with_file(file, :id) do |store|
+    #     store.delete(a, b, c, d, e)
+    #     store.insert(f, g, h)
+    #     store.size
+    #   end
+    # 
+    # Returns whatever the block returns.
+    # Raises whatever File::open, IO::read, Marshal::load, Marshal::dump or IO::write raise.
     def self.with_file(file, key=nil, items={}, &block)
-      self.run_with_file(:from_file, :to_file, file, key, items, &block)
+      self.execute_with_file(:from_file, :to_file, file, key, items, &block)
     end
 
     private
 
+    # Internal: Obtains the key attribute of an item.
+    #
+    # item - Object that responds to the attribute.
+    #
+    # Returns result of calling the key attribute method on the item.
+    # Raises NoMethodError when item does’t respond to the key attribute method.
     def key(item)
       item.send(@key)
     end
 
+    # Internal: Obtains the specified attribute of an item.
+    #
+    # item - Object that responds to the attribute.
+    # attribute - Symbol or String naming the attribute.
+    #
+    # Returns result of calling the attribute method on the item.
+    # Raises NoMethodError when item does’t respond to the attribute method.
     def attr(item, attribute)
       item.send(attribute)
     end
 
-    def self.run_with_file(from_file_method, to_file_method, file, key=nil, items={}, &block)
+    # Internal: Used to implement with_file and variants for different formats/subclasses.
+    # Takes required method names, can therefore be used by any subclass.
+    # Executes a given block while keeping an exclusive lock on a file.
+    # Tries to deserialize a data store from the file using from_file_method.
+    # If that fails, a new one will be created using the supplied key and items.
+    # Writes data store back to file using to_file_method after block returns.
+    #
+    # from_file_method - Name of class method (Symbol or String) to deserialize data store from file.
+    # to_file_method - Name of instance method (Symbol or String) to serialize data store to file.
+    # file - IO stream or file name as String.
+    # key - Optional key attribute (Symbol or String) to use in ::new (default: nil).
+    # items - Optional items Hash to use in ::new (default: empty Hash).
+    # block - Block that will be called after a data store was restored or created.
+    #
+    # Yields the restored or newly created data store.
+    # 
+    # Returns whatever the block returns.
+    # Raises whatever File::open, IO::read, Marshal::load, Marshal::dump or IO::write raise.
+    def self.execute_with_file(from_file_method, to_file_method, file, key=nil, items={}, &block)
       File.open(file) do |file|
         file.flock(File::LOCK_EX)
         store = self.send(from_file_method, file) || self.new(key, items)

data/lib/memstore/queries.rb

@@ -4,91 +4,141 @@ module MemStore
 
   class ObjectStore
 
+    # All methods have the following signature:
+    #
+    # conditions - Hash mapping attributes to conditions.
+    #              Attributes can be Symbols or String for ObjectStore
+    #              and any kind of Object for HashStore.
+    #              Conditions can be any kind of Object that responds to #===.
+    # block - Optional block taking an item and returning a bool indicating
+    #         whether the item passed the tests within the block.
+    #
+    # Yields every item in the data store after the conditions were evaluated for it.
+
+    ### find ###
+
+    # Also available as #find.
+    # Returns an Array of items that fulfill all conditions.
     def find_all(conditions={}, &block)
       all.select { |item| instance_exec(item, conditions, block, &FIND_ALL) }
     end
     alias_method :find, :find_all
 
+    # Returns an Array of items that fulfill at least one condition.
     def find_any(conditions={}, &block)
       all.select { |item| instance_exec(item, conditions, block, &FIND_ANY) }
     end
 
+    # Returns an Array of items that fulfill exactly one condition.
     def find_one(conditions={}, &block)
       all.select { |item| instance_exec(item, conditions, block, &FIND_ONE) }
     end
 
+    # Returns an Array of items that violate at least one condition.
     def find_not_all(conditions={}, &block)
       all.reject { |item| instance_exec(item, conditions, block, &FIND_ALL) }
     end
 
+    # Returns an Array of items that violate all conditions.
     def find_none(conditions={}, &block)
       all.select { |item| instance_exec(item, conditions, block, &FIND_NONE) }
     end
 
+    ### first ###
+
+    # Also available as #first.
+    # Returns the first item that fulfills all conditions.
     def first_all(conditions={}, &block)
       all.detect { |item| instance_exec(item, conditions, block, &FIND_ALL) }
     end
     alias_method :first, :first_all
 
+    # Returns the first item that fulfills at least one condition.
     def first_any(conditions={}, &block)
       all.detect { |item| instance_exec(item, conditions, block, &FIND_ANY) }
     end
 
+    # Returns the first item that fulfills exactly one condition.
     def first_one(conditions={}, &block)
       all.detect { |item| instance_exec(item, conditions, block, &FIND_ONE) }
     end
 
+    # which is equivalent to: !condition || !condition || ... [|| !block]
+    # Returns the first item that violates at least one condition.
     def first_not_all(conditions={}, &block)
       all.detect { |item| !instance_exec(item, conditions, block, &FIND_ALL) }
     end
 
+    # Returns the first item that violates all conditions.
     def first_none(conditions={}, &block)
       all.detect { |item| instance_exec(item, conditions, block, &FIND_NONE) }
     end
 
+    ### count ###
+
+    # Also available as #count.
+    # Returns the number of items that fulfill all conditions.
     def count_all(conditions={}, &block)
       all.count { |item| instance_exec(item, conditions, block, &FIND_ALL) }
     end
     alias_method :count, :count_all
 
+    # Returns the number of items that fulfill at least one condition.
     def count_any(conditions={}, &block)
       all.count { |item| instance_exec(item, conditions, block, &FIND_ANY) }
     end
 
+    # Returns the number of items that fulfill exactly one condition.
     def count_one(conditions={}, &block)
       all.count { |item| instance_exec(item, conditions, block, &FIND_ONE) }
     end
 
+    # which is equivalent to: !condition || !condition || ... [|| !block]
+    # Returns the number of items that violate at least one condition.
     def count_not_all(conditions={}, &block)
       all.count { |item| !instance_exec(item, conditions, block, &FIND_ALL) }
     end
 
+    # Returns the number of items that violate all conditions.
     def count_none(conditions={}, &block)
       all.count { |item| instance_exec(item, conditions, block, &FIND_NONE) }
     end
 
     private
-  
+    
+    # All blocks have the following signature:
+    #
+    # item - The item (Object for ObjectStore, Hash for HashStore) to be tested.
+    # conditions - Hash of conditions to be evaluated.
+    # block - Optional block that can test the item after the conditions are evaluated.
+    #
+    # Returns a bool indicating whether the item was a match
+    #   for the given conditions and matching logic.
+
+    # Internal: Evaluates conditions using AND, i.e. condition && condition && ... [&& block]
     FIND_ALL = Proc.new do |item, conditions, block|
         conditions.all? { |attribute, condition| condition === attr(item, attribute) } &&
           if block then !!block.call(item) else true end
       end
   
+    # Internal: Evaluates conditions using OR, i.e. condition || condition || ... [|| block]
     FIND_ANY = Proc.new do |item, conditions, block|
         conditions.any? { |attribute, condition| condition === attr(item, attribute) } ||
           if block then !!block.call(item) else false end
       end
 
-    FIND_NONE = Proc.new do |item, conditions, block|
-        conditions.none? { |attribute, condition| condition === attr(item, attribute) } &&
-          if block then !!block.call(item) else true end
-      end
-
+    # Internal: Evaluates conditions using XOR, i.e. condition ^ condition ^ condition ... [^ block]
     FIND_ONE = Proc.new do |item, conditions, block|
-        conditions.one? { |attribute, condition| condition === attr(item, attribute) } ||
+        conditions.one? { |attribute, condition| condition === attr(item, attribute) } ^
           if block then !!block.call(item) else false end
       end
 
+    # Internal: Evaluates condition using AND NOT, i.e. !condition && !condition && ... [&& !block]
+    FIND_NONE = Proc.new do |item, conditions, block|
+        conditions.none? { |attribute, condition| condition === attr(item, attribute) } &&
+          if block then !!!block.call(item) else true end
+      end
+
   end
   
 end

data/lib/memstore/version.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 module MemStore
-  VERSION = "1.2.0"
+  VERSION = "1.2.1"
 end

data/lib/memstore/yaml.rb

@@ -27,7 +27,7 @@ module MemStore
     end
 
     def self.with_yaml_file(file, key=nil, items={}, &block)
-      self.run_with_file(:from_yaml_file, :to_yaml_file, file, key, items, &block)
+      self.execute_with_file(:from_yaml_file, :to_yaml_file, file, key, items, &block)
     end
 
   end

data/spec/hashstore_spec.rb

@@ -34,6 +34,15 @@ describe MemStore::HashStore do
     restored.instance_variable_get(:@key).must_equal @store.instance_variable_get(:@key)
   end
 
+  it "returns nil when conversion from binary fails" do
+    MemStore::HashStore.from_binary(nil).must_equal nil
+    MemStore::HashStore.from_binary(Marshal.dump(Object.new)).must_equal nil
+  end
+
+  it "returns nil when marshalled object isn’t instance of HashStore" do
+    MemStore::HashStore.from_binary(MemStore::ObjectStore.new.to_binary).must_equal nil
+  end
+
   it "can be serialized to and deserialized from a binary file" do
     tmp = Tempfile.new("memstore")
     @store.to_file(tmp)

data/spec/objectstore_spec.rb

@@ -82,6 +82,10 @@ describe MemStore::ObjectStore do
     MemStore::ObjectStore.from_binary(Marshal.dump(Object.new)).must_equal nil
   end
 
+  it "returns nil when marshalled object isn’t instance of ObjectStore" do
+    MemStore::ObjectStore.from_binary(MemStore::HashStore.new.to_binary).must_equal nil
+  end
+
   it "can be serialized to and deserialized from a binary file" do
     tmp = Tempfile.new("memstore")
     @store.to_file(tmp)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: memstore
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.2.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-20 00:00:00.000000000 Z
+date: 2013-02-21 00:00:00.000000000 Z
 dependencies: []
 description: MemStore is a simple in-memory data store that supports adding, retrieving
   and deleting items as well as complex search queries and easy serialization.