hash_cabinet 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d284b1a7d996a2e750db02e4db77d2be4afb543ae88da7a385174f00f1533b9c
+  data.tar.gz: 270859870c5130c08e057cb7379f74902bf691db52c87ee8dffe592343b7dd14
+SHA512:
+  metadata.gz: c3e93b6bc0904c02f003b8c913c7d25989d0526e0233bfdd612faedd75cfeb3fd193bf026066371a98fe26a33d8ae4fc4a3c274f0351eb1fbb31f063b609c9c1
+  data.tar.gz: 01d325e99d38b83f73c0e3007d546884af69af974f3193b6908b476ac8cadfb9a10ec16efec49bbd11e75e16aa7886a5e9635128c915ca4be1709f9ec7c93f54

data/README.md

@@ -0,0 +1,48 @@
+Hash Cabinet - File based key-object store
+==================================================
+
+[![Gem Version](https://badge.fury.io/rb/hash_cabinet.svg)](https://badge.fury.io/rb/hash_cabinet)
+
+---
+
+Hash Cabinet is a file-based, key-object store with hash-like access.
+
+
+Highlights
+--------------------------------------------------
+
+- Tiny library, based on Ruby's built in [SDBM].
+- Stores simple values or complex objects through transparent YAML 
+  serialization.
+- Easy hash-like access: `cabinet['key'] = 'value'`.
+- Mirrors most of the native SDBM methods.
+
+
+Installation
+--------------------------------------------------
+
+    $ gem install hash_cabinet
+
+
+
+Usage
+--------------------------------------------------
+
+```ruby
+cabinet = HashCabinet.new 'dbfile'
+
+# Store values
+cabinet['some-key'] = 'some=value'
+cabinet['another-key'] = { color: 'yellow' }
+
+# Retrieve values
+p cabinet['another-key']
+#=> {:color=>"yellow", :shape=>"circle"}
+
+# Show all values
+p cabinet.to_h
+#=> {"some-key"=>"some=value", "another-key"=>{:color=>"yellow"}
+
+```
+
+[SDBM]: https://ruby-doc.org/stdlib-2.6.3/libdoc/sdbm/rdoc/SDBM.html

data/lib/hash_cabinet.rb

@@ -0,0 +1,218 @@
+require 'sdbm'
+require 'yaml'
+
+class HashCabinet
+
+  # Refinements to allow using +from_yaml+ as the opposite of +to_yaml+.
+  module ReverseYAML
+    refine String do
+      def from_yaml
+        YAML.load self
+      end
+    end
+
+    refine NilClass do
+      def from_yaml
+        nil
+      end
+    end
+  end
+
+  using ReverseYAML
+
+  # Returns the path to the database file.
+  attr_reader :path
+
+  # Initialize a new database file at {path}.
+  def initialize(path)
+    @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:
+  #
+  #   cabinet = HashCabinet.new 'filename'
+  #
+  #   cabinet.transaction do |db|
+  #     db.clear
+  #   end
+  #
+  def transaction(&block)
+    SDBM.open path, &block
+  end
+
+  # Returns the value in the database associated with the given +key+.
+  def [](key)
+    transaction { |db| db[key].from_yaml }
+  end
+
+  # Inserts or updates a value in the database with the given key as an index.
+  def []=(key, value)
+    transaction { |db| db[key] = value.to_yaml }
+  end
+
+  # Deletes all key-value pairs from the database.
+  def clear
+    transaction { |db| db.clear }
+  end
+
+  # Deletes the given `key` from the database.
+  def delete(key)
+    transaction { |db| db.delete key }
+  end
+
+  # Iterates over the key-value pairs in the database, deleting those for
+  # which the block returns true.
+  def delete_if(&block)
+    transaction do |db|
+      db.delete_if do |key, value|
+        yield key, value.from_yaml
+      end
+    end
+  end
+
+  # Iterates over each key-value pair in the database.
+  def each(&block)
+    transaction do |db|
+      db.each do |key, value|
+        yield key, value.from_yaml
+      end
+    end
+  end
+
+  
+  # Iterates over each key in the database.
+  def each_key(&block)
+    transaction { |db| db.each_key &block }
+  end
+
+  
+  # Iterates over each key-value pair in the database.
+  def each_value(&block)
+    transaction do |db|
+      db.each_value do |value|
+        yield value.from_yaml
+      end
+    end
+  end
+
+  # Returns +true+ if the database is empty.
+  def empty?
+    transaction { |db| db.empty? }
+  end
+
+  # Returns true if the database contains the given key.
+  def has_key?(key)
+    transaction { |db| db.has_key? key }
+  end
+
+  # Returns +true+ if the database contains the given value.
+  def has_value?(value)
+    transaction { |db| db.has_value? value.to_yaml }
+  end
+
+  # Returns +true+ if the database contains the given key.
+  def include?(key)
+    transaction { |db| db.include? key }
+  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.
+  # If no keys are found, +nil+ will be returned.
+  def key(value)
+    transaction { |db| db.key value.to_yaml }
+  end
+
+  # Returns +true+ if the database contains the given key.
+  def key?(key)
+    transaction { |db| db.key? key }
+  end
+
+  # Returns a new Array containing the keys in the database.
+  def keys
+    transaction { |db| db.keys }
+  end
+
+  # Returns the number of keys in the database.
+  def length
+    transaction { |db| db.length }
+  end
+
+  # Empties the database, then inserts the given key-value pairs.
+  # This method will work with any object which implements an +#each_pair+
+  # method, such as a Hash.
+  def replace(data)
+    data = data.transform_values &:to_yaml
+    data = data.transform_keys &:to_s
+    transaction { |db| db.replace data }
+  end
+
+  # Returns a new Hash of key-value pairs for which the block returns true.
+  def select(&block)
+    transaction do |db|
+      db.select do |key, value|
+        yield key, value.from_yaml
+      end.to_h.transform_values &:from_yaml
+    end
+  end
+
+  # Removes a key-value pair from the database and returns them as an Array.
+  #
+  # If the database is empty, returns nil.
+  def shift
+    transaction do |db| 
+      result = db.shift
+      [result[0], result[1].from_yaml]
+    end
+  end
+
+  # Returns the number of keys in the database.
+  def size
+    transaction { |db| db.size }
+  end
+
+  # Returns 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.
+  def to_h
+    transaction do |db| 
+      db.to_h.transform_values &:from_yaml
+    end
+  end
+
+  # Insert or update key-value pairs.
+  # 
+  # This method will work with any object which implements an +#each_pair+
+  # method, such as a Hash.
+  def update(data)
+    data = data.transform_values &:to_yaml
+    transaction { |db| db.update data }
+  end
+
+  # Returns +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.
+  def values
+    transaction do |db| 
+      db.values.map &:from_yaml
+    end
+  end
+
+  # Returns an Array of values corresponding to the given keys.
+  def values_at(*key)
+    transaction do |db| 
+      db.values_at(*key).map &:from_yaml
+    end
+  end
+
+end

metadata

@@ -0,0 +1,44 @@
+--- !ruby/object:Gem::Specification
+name: hash_cabinet
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Danny Ben Shitrit
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-09-18 00:00:00.000000000 Z
+dependencies: []
+description: Store objects in a file using hash-like syntax
+email: db@dannyben.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/hash_cabinet.rb
+homepage: https://github.com/dannyben/hash_cabinet
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.4
+signing_key: 
+specification_version: 4
+summary: Key-object file database with hash-like access
+test_files: []