keyvaluetree 0.0.4 → 0.0.5

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Udo Schneider <Udo.Schneider@homeaddress.de>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -1,6 +1,6 @@
-# Keyvaluetree
+# keyvaluetree
 
-TODO: Write a gem description
+keyvalutree provides an wrapper around a flat KeyValueStore which emulates an hierachical store (i.e. nested Hashes).
 
 ## Installation
 
@@ -18,7 +18,25 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Simple
+
+    config = KeyValueTree::Hash.new()
+
+    config.server.name = 'localhost'
+    config.server['port'] = '123'
+
+    config.server['name'] => 'localhost'
+    config.server.port = '123'
+
+### Using explicit MemoryStore
+
+    config = KeyValueTree::Hash.new(KeyValueTree::MemoryStore.new())
+
+    config.server.name = 'localhost'
+    config.server['port'] = '123'
+
+    config.server['name'] => 'localhost'
+    config.server.port = '123'
 
 ## Contributing
 

data/lib/keyvaluetree/hash.rb

@@ -1,5 +1,6 @@
 module KeyValueTree
 
+  # Hash implements an hierachical Hash (i.e. Hashes in Hashes) backed by a flat-hash Store.
   class Hash
 
     attr_reader :store
@@ -10,6 +11,11 @@ module KeyValueTree
       @store = store
     end
 
+    # @!group Operations
+
+    # Return the value for the given key. If the the key is nil return self. If the value is nil (empty) return a new instance of Hash for the key
+    # @param [String]key The key to fetch
+    # @return [String,KeyValueTree::Hash] The result
     def [] (key)
       return self if key.nil?
       value = @store.key(key_path_string(key))
@@ -17,6 +23,10 @@ module KeyValueTree
       return KeyValueTree::Hash.new(@store, key, self)
     end
 
+    # Set a value for the given key.
+    # @param [String]key The key to set
+    # @param [String]value The value to set
+    # @return [String] The value
     def []= (key, value)
       if value.is_a?(::Hash)
         value.each do |hash_key, hash_value|
@@ -34,6 +44,58 @@ module KeyValueTree
       return value
     end
 
+    # Return the value for the given key. If the the key is nil return self. If the value is nil (empty) return a new instance of Hash for the key
+    # @param [String]key The key to fetch
+    # @return [String,KeyValueTree::Hash] The result
+    def [] (key)
+      return self if key.nil?
+      value = @store.key(key_path_string(key))
+      return value unless value.nil?
+      return KeyValueTree::Hash.new(@store, key, self)
+    end
+
+    # Delete the value for the given key
+    # @param [String]key The key to delete
+    # @return [String,KeyValueTree::Hash] The value of the deleted key
+    def delete(key)
+      @store.delete(key_path_string(key.to_s))
+    end
+
+    # Delete the value for the given key and it's sub-keys
+    # @note This method might raise an exception if the store does not support the operation.
+    # @param [String]key The key to delete
+    # @return [nil] Undefined
+    def delete_all(key)
+      @store.delete_all(key_path_string(key.to_s))
+    end
+
+    # Import the given ::Hash into the Hash.
+    # @param [Hash]object The object to import
+    # @return [self]
+    def import(object)
+      self[nil] = object
+    end
+
+    # Return all keys.
+    # @note This method might raise an exception if the store does not support the operation.
+    # @return [Array<String>] An Array of keys
+    def keys
+      @store.keys_starting_with(key_path_string()).map { |each| each.split(".").first }.uniq
+    end
+
+    # Return true if the Hash is the root Hash (i.e. has no parent)
+    # @return [Boolean]
+    def root?
+      @parent.nil?
+    end
+
+    # @!endgroup
+
+    # @!group Helpers
+
+    # Handle method dispatch for missing methods. Provides the functionality to access a value using hash.key or set it via hash.key = value.
+    # @param [Symbol]method The called method
+    # @param [Array]args Provided arguments (if any)
     def method_missing(method, *args)
       property = method.to_s
       if property =~ /=$/
@@ -43,6 +105,9 @@ module KeyValueTree
       end
     end
 
+    # Return the keypath to self as Array of keys. Append key is given
+    # @param [String,nil]key The subkey (if any)
+    # @return [Array<String>] An array of keys (starting with the root key)
     def key_path(key = nil)
       if root?
         return [] if key.nil?
@@ -53,6 +118,9 @@ module KeyValueTree
       end
     end
 
+    # Return the keypath to self as dot separated String of keys. Append key is given
+    # @param [String,nil]key The subkey (if any)
+    # @return [String] A dot separated String of keys (starting with the root key)
     def key_path_string(key = nil)
       result = ''
       key_path(key).each_with_index do |value, index|
@@ -66,21 +134,8 @@ module KeyValueTree
       return result
     end
 
-    def root?
-      @parent.nil?
-    end
+    # @!endgroup
 
-    def delete(key)
-      @store.delete(key_path_string(key.to_s))
-    end
-
-    def keys
-      @store.keys_starting_with(key_path_string()).map { |each| each.split(".").first }.uniq
-    end
-
-    def import(object)
-      self[nil] = object
-    end
   end
 
 end

data/lib/keyvaluetree/memory_store.rb

@@ -14,7 +14,7 @@ module KeyValueTree
       @hash[key.to_s] = value
     end
 
-    def basic_delete(key)
+    def delete(key)
       @hash.delete(key.to_s)
     end
 

data/lib/keyvaluetree/store.rb

@@ -1,47 +1,68 @@
 module KeyValueTree
 
+  # This class defines the methods expected by KeyValueTree::Hash for it's Store backend
   class Store
 
-    def initialize(hash={})
-      raise NotImplementedError
-    end
+    # @!group Required methods
 
+    # Return the value for the given key
+    # @param [String]key The key to fetch
+    # @return [String] The value for key or nil
     def key(key)
       raise NotImplementedError
     end
 
+    # Store the value at the given key
+    # @param [String]key The key to store
+    # @param [String]value The value to store
+    # @return [String] The value
     def store(key, value)
       raise NotImplementedError
     end
 
-    def basic_delete(key)
+    # Delete the given key
+    # @param [String]key The key to delete
+    # @return [String] The value for key or nil
+    def delete(key)
       raise NotImplementedError
     end
 
-    def keys
-      raise NotImplementedError
-    end
+    # @!endgroup
 
-    def to_hash
+    # @!group Optional methods (as some stores don't support (sub-) key enumeration)
+
+    # Fetch all keys in store
+    # @return [Array<String>] All keys in store
+    def keys
       raise NotImplementedError
     end
 
-    def delete(key)
-      self.delete_keys_start_with(key.to_s)
+    # Fetch all keys in store with the given key prefix
+    # @param [String]key The key prefix
+    # @return [Array<String>] All keys in store
+    def keys_starting_with(key)
+      self.keys.select do |sub_key|
+        sub_key.start_with?(key.to_s)
+      end
     end
 
-    def delete_keys_start_with(key)
+    # Delete all keys starting with the given prefix
+    # @param [String]key The key prefix
+    # @return nil
+    def delete_all(key)
       keys_starting_with(key.to_s).each do |each|
-        self.basic_delete(each)
+        self.delete(each)
       end
     end
 
-    def keys_starting_with(key)
-      self.keys.select do |sub_key|
-        sub_key.start_with?(key.to_s)
-      end
+    # Convert the store to a *hierachical* Hash
+    # return [Hash]
+    def to_hash
+      raise NotImplementedError
     end
 
+    # @!endgroup
+
   end
 
 end

data/lib/keyvaluetree/transaction_store.rb

@@ -24,7 +24,7 @@ module KeyValueTree
       end
     end
 
-    def basic_delete(key)
+    def delete(key)
       @access_mutex.synchronize do
         @changed_properties.delete(key)
         @deleted_property_keys << key

data/lib/keyvaluetree/version.rb

@@ -1,3 +1,3 @@
 module KeyValueTree
-  VERSION = '0.0.4'
+  VERSION = '0.0.5'
 end

data/test/hash_test.rb

@@ -66,7 +66,7 @@ class HashTest < Test::Unit::TestCase
       @root.one.a.delete(:A)
       assert_equal 3, @store.keys.size
 
-      @root.delete(:two)
+      @root.delete_all(:two)
       assert_equal 1, @store.keys.size
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keyvaluetree
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-09-01 00:00:00.000000000 Z
+date: 2013-09-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -87,6 +87,7 @@ files:
 - .idea/misc.xml
 - .idea/vcs.xml
 - Gemfile
+- LICENSE
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -116,7 +117,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3979295287032402634
+      hash: -1788352517375914173
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -125,7 +126,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3979295287032402634
+      hash: -1788352517375914173
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24