hash_cabinet 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bddfb98bc67f51e3aabf476d95da84990f5e271ad26d404e5f5e2722b95275d
-  data.tar.gz: c4a45182a0becb13ddf7915b8c0aa28c2fd43cd1571185f4afff1da21032f702
+  metadata.gz: 4938741a78a6296230b6c7f4585b8dec8cf1ee3da6e7680e13d9192bb4110782
+  data.tar.gz: 92fc7f0ade034f713f7516a54e7a087dbed103853699de85236543eaec38579b
 SHA512:
-  metadata.gz: 0ed28a440b890b56a368619450200c89c5b748c63f6fe52223a3c0767c0403d81771587a062c613a8f681dc06f20a708cca5c2fc10f1420eec5965b229a7926f
-  data.tar.gz: '09684dd6832e8a5bb6156c483c7e1a8a0645215394b7d48e288be4ad654ecc6f68ab89b9082329e745eb9f3e338582034397d4b562dbc0daa4c402cd6753d866'
+  metadata.gz: 02a46e648da4b005b1581660392493af0e35bd32de322d45237ee53948bfbe849c4ce75e5db301199c044e58adb5c304c8bc8caddea72c68dc9f647ff238cd63
+  data.tar.gz: 12f82246384e4887f3ecd99932a3fadb74e39552eddd5e314c27fe83a78f7c22ee24283796ff236017594ba0a4245ff2b96c441d7b9eeacda56a61018dcccebc

data/README.md

@@ -49,40 +49,6 @@ p cabinet.to_h
 
 ```
 
-Quick Reference
---------------------------------------------------
-
-| Method | Description |
-|--------|-------------|
-| `cabinet.transaction { ... }`       | Yields the `SDBM` object. (like `SDBM.open`) |
-| `cabinet[key]`                      | Returns the value at key |
-| `cabinet[key] = value`              | Saves the value at key |
-| `cabinet.clear`                     | Deletes all data |
-| `cabinet.delete key`                | Deletes a key |
-| `cabinet.delete_if { \|k, v\| ... }`| Deletes keys based on the block result |
-| `cabinet.each { \|k, v\| ... }`     | Iterates over the data |
-| `cabinet.each_key { \|k\| ... }`    | Iterates over the keys |
-| `cabinet.each_value { \|v\| ... }`  | Iterates over the values |
-| `cabinet.emoty?`                    | Returns true if the database is empty |
-| `cabinet.has_key? key`              | Returns true if the key exists | 
-| `cabinet.has_value? value`          | Returns true if the value exists | 
-| `cabinet.include? key`              | Same as `cabinet.has_key?` |
-| `cabinet.key value`                 | Returns the key associated with the value |
-| `cabinet.key? key`                  | Same as `cabinet.has_key?` |
-| `cabinet.keys`                      | Returns all the keys |
-| `cabinet.length`                    | Returns the number of key-value pairs |
-| `cabinet.replace data`              | Reset the database with new data |
-| `cabinet.select { \|k, v\| ... }`   | Returns a hash based on the block result |
-| `cabinet.shift`                     | Removes and returns one key-value pair |
-| `cabinet.size`                      | Same as `cabinet.length` |
-| `cabinet.to_a`                      | Returns an array of `[key, value]` pairs |
-| `cabinet.to_h`                      | Returns a hash with all key-value pairs |
-| `cabinet.update data`               | Insert or update new data |
-| `cabinet.value? value`              | Returns true if the value is in the database |
-| `cabinet.values`                    | Returns an array of all the values |
-| `cabinet.values_at key, ...`        | Returns an array of values corresponding to the given keys |
-
-
 Documentation
 --------------------------------------------------
 

data/lib/hash_cabinet.rb

@@ -28,17 +28,20 @@ class HashCabinet
     @path = path
   end
 
-  # Yields the +SDBM+ object to the block. Under most circumstances, this
-  # method should not be used directly, as it is used by all other methods.
-  #
-  # Example:
+  # Yields the +SDBM+ object to the block. 
   #
+  # @example
   #   cabinet = HashCabinet.new 'filename'
   #
   #   cabinet.transaction do |db|
   #     db.clear
   #   end
   #
+  # @note 
+  #   Under most circumstances, this method should not be used directly, 
+  #   as it is used by all other methods.
+  #
+  # @yieldparam [SDBM] db the {SDBM} instance
   def transaction(&block)
     SDBM.open path, &block
   end
@@ -65,6 +68,16 @@ class HashCabinet
 
   # Iterates over the key-value pairs in the database, deleting those for
   # which the block returns true.
+  # 
+  # @example Delete all records with +age < 18+.
+  #   cabinet = HashCabinet.new 'filename'
+  #
+  #   cabinet.delete_if do |key, value|
+  #     value[:age] < 18
+  #   end
+  #
+  # @yieldparam [String] key the pair key
+  # @yieldparam [Object] value the pair value
   def delete_if(&block)
     transaction do |db|
       db.delete_if do |key, value|
@@ -74,6 +87,9 @@ class HashCabinet
   end
 
   # Iterates over each key-value pair in the database.
+  #
+  # @yieldparam [String] key the pair key
+  # @yieldparam [Object] value the pair value
   def each(&block)
     transaction do |db|
       db.each do |key, value|
@@ -83,11 +99,15 @@ class HashCabinet
   end
   
   # Iterates over each key in the database.
+  #
+  # @yieldparam [String] key the pair key
   def each_key(&block)
     transaction { |db| db.each_key &block }
   end
   
   # Iterates over each key-value pair in the database.
+  #
+  # @yieldparam [Object] value the pair value
   def each_value(&block)
     transaction do |db|
       db.each_value do |value|
@@ -96,36 +116,39 @@ class HashCabinet
     end
   end
 
-  # Returns +true+ if the database is empty.
+  # @return [Boolean] +true+ if the database is empty.
   def empty?
     transaction { |db| db.empty? }
   end
 
-  # Returns true if the database contains the given key.
+  # @return [Boolean] +true+ if the database contains the given key.
   def has_key?(key)
     transaction { |db| db.has_key? key.to_s }
   end
   alias include? has_key?
   alias key? has_key?
 
-  # Returns +true+ if the database contains the given value.
+  # @return [Boolean] +true+ if the database contains the given value.
   def has_value?(value)
     transaction { |db| db.has_value? value.to_yaml }
   end
 
-  # Returns the key associated with the given value. If more than one key
-  # corresponds to the given value, then the first key will be returned.
+  # Returns the key associated with the given value.
+  #
+  # If more than one key corresponds to the given value, then the first key will be returned.
   # If no keys are found, +nil+ will be returned.
+  #
+  # @return [String] the key associated with the given value. 
   def key(value)
     transaction { |db| db.key value.to_yaml }
   end
 
-  # Returns a new Array containing the keys in the database.
+  # @return [Array] a new Array containing the keys in the database.
   def keys
     transaction { |db| db.keys }
   end
 
-  # Returns the number of keys in the database.
+  # @return [Integer] the number of keys in the database.
   def length
     transaction { |db| db.length }
   end
@@ -138,6 +161,12 @@ class HashCabinet
   # method, such as a Hash, or with any object that implements an +#each+
   # method, such as an Array. In this case, the array will be converted to 
   # a `key=key` hash before storing it.
+  # 
+  # @example
+  #   cabinet = HashCabinet.new 'filename'
+  #   cabinet.replace key1: 'value1', key2: 'value2'
+  #
+  # @param [Object] data the data to store
   def replace(data)
     if !data.respond_to? :each_pair and data.respond_to? :each
       data = array_to_hash data
@@ -147,7 +176,7 @@ class HashCabinet
     transaction { |db| db.replace data }
   end
 
-  # Returns a new Hash of key-value pairs for which the block returns true.
+  # @return [Hash] a new Hash of key-value pairs for which the block returns true.
   def select(&block)
     transaction do |db|
       db.select do |key, value|
@@ -159,6 +188,8 @@ class HashCabinet
   # Removes a key-value pair from the database and returns them as an Array.
   #
   # If the database is empty, returns nil.
+  #
+  # @return [Array] the key and value.
   def shift
     transaction do |db| 
       result = db.shift
@@ -166,26 +197,33 @@ class HashCabinet
     end
   end
 
-  # Returns a new Array containing each key-value pair in the database.
+  # @return [Array] a new array containing each key-value pair in the 
+  #   database.
   def to_a
     transaction do |db| 
       db.to_a.map { |pair| [pair[0], pair[1].from_yaml] }
     end
   end
 
-  # Returns a new Hash containing each key-value pair in the database.
+  # @return [hash] a new hash containing each key-value pair in the database.
   def to_h
     transaction do |db| 
       db.to_h.transform_values &:from_yaml
     end
   end
 
-  # Insert or update key-value pairs.
+  # Inserts or updates key-value pairs.
   # 
   # This method will work with any object which implements an +#each_pair+
   # method, such as a Hash, or with any object that implements an +#each+
   # method, such as an Array. In this case, the array will be converted to 
   # a `key=key` hash before storing it.
+  #
+  # @example
+  #   cabinet = HashCabinet.new 'filename'
+  #   cabinet.update key1: 'value1', key2: 'value2'
+  #
+  # @param [Object] data the data to store
   def update(data)
     if !data.respond_to? :each_pair and data.respond_to? :each
       data = array_to_hash data
@@ -195,19 +233,19 @@ class HashCabinet
     transaction { |db| db.update data }
   end
 
-  # Returns +true+ if the database contains the given value.
+  # @return [Boolean] +true+ if the database contains the given value.
   def value?(value)
     transaction { |db| db.value? value.to_yaml }
   end
 
-  # Returns a new Array containing the values in the database.
+  # @return [Array] a new array containing the values in the database.
   def values
     transaction do |db| 
       db.values.map &:from_yaml
     end
   end
 
-  # Returns an Array of values corresponding to the given keys.
+  # @return [Array] an Array of values corresponding to the given keys.
   def values_at(*key)
     transaction do |db| 
       db.values_at(*(key.map &:to_s)).map &:from_yaml

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hash_cabinet
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Danny Ben Shitrit
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-09-18 00:00:00.000000000 Z
+date: 2019-09-19 00:00:00.000000000 Z
 dependencies: []
 description: Store objects in a file using hash-like syntax
 email: db@dannyben.com