active_cabinet 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 774c19d270fc5767611ad0b42eaa06f7b98c3bae2bdfa2e4f8f0e382629daf59
+  data.tar.gz: 4d48778ba0cd2294b047d0292c87e963c4c16823a1effe6f93a207afeb182713
+SHA512:
+  metadata.gz: 9e9e84e8ae733967cee88489b45020c68609ef67172d5a0c8b9e3540d946d8a0a9d32e139362f95a3d0aa3f545c1a612c1993f3a4327f67559506d98c3ab8620
+  data.tar.gz: 3a9a02b9f0c0df27479db9ba4f6ae8c6e17cd3f10caad24fe00e669c7402f19b3dddc4461553d25e9b7cf61588b4bf668cf9b194bbf3cce27a319de7c2bb297f

data/README.md

@@ -0,0 +1,136 @@
+ActiveCabinet
+==================================================
+
+---
+
+ActiveCabinet is an ActiveRecord-inspired interface for HashCabinet, the
+file-basd key-object store.
+
+It allows you to create models that are stored in a file-based key-value
+store, backed by Ruby's built in [SDBM].
+
+---
+
+Installation
+--------------------------------------------------
+
+    $ gem install active_cabinet
+
+
+
+Usage
+--------------------------------------------------
+
+Before trying these examples, create a directory named `db` - this is the 
+default directory where the cabinet files are stored.
+
+```ruby
+require 'active_cabinet'
+
+# Define a model
+class Song < ActiveCabinet
+end
+
+# Create the model, and store it in the cabinet
+# Each object must have at least an `id` and can have any number of
+# attributes
+song = Song.create id: 1, title: 'Moonchild', artist: 'Iron Maiden'
+p song
+#=> #<Song @attributes={:id=>1, :title=>"Moonchild", :artist=>"Iron Maiden"}>
+
+# Get all records
+Song.all     #=> Array of Song objects
+Song.count   #=> 1
+
+# Retrieve a specific record
+Song[1]
+Song.find 1
+
+# Read one attribute or all attributes from a record
+song.album
+song.attributes
+
+# Update a single attribute
+song.year = 1988
+song.save
+
+# Update multiple attributes
+song.update year: 1988, artist: 'Metallica'
+song.update! year: 1988, artist: 'Metallica'  # this variant also saves
+```
+
+### Restricting / allowing certain attributes
+
+You may specify required arguments. Records without these attributes will
+not be saved. Note that `id` is always required
+
+```ruby
+class Song < ActiveCabinet
+  required_attributes :title, :artist
+end
+
+song = Song.new title: "Moonchild"
+song.valid?   # => false
+song.error    # => "missing required attributes: [:artist, :id]"
+
+song = Song.new id: 1, title: "Moonchild", artist: 'Iron Maiden'
+song.valid?   # => true
+
+# Additional attributes are still allowed
+song.year = 1988
+song.valid?   # => true
+```
+
+You can also restrict the allowed optional attributes
+
+```
+class Song < ActiveCabinet
+  required_attributes :title
+  optional_attributes :artist
+end
+
+song = Song.new id: 1, title: 'Moonchild', album: 'Seventh Son of a Seventh Son'
+song.valid?  # => false
+song.error   # => "invalid attributes: [:album]"
+```
+
+In order to enforce only the required attributes, without optional ones, set
+the value of `optional_attributes` to `false`
+
+```ruby
+class Song < ActiveCabinet
+  required_attributes :title
+  optional_attributes false
+end
+
+song = Song.new id: 1, title: 'Moonchild', artist: 'Iron Maiden'
+song.valid?  # => false
+song.error   # => "invalid attributes: [:artist]"
+```
+
+### Configuring storage path
+
+By default, `ActiveCabinet` stores all its files (two files per model) in the
+`./db` directory. The file name is determined by the name of the class.
+
+You can override both of these values
+
+```ruby
+# Set the based directory for all cabinets
+ActiveCabinet::Config.dir = "cabinets"
+
+# Set the filename of your model
+class Song < ActiveCabinet
+  cabinet_name "songs_collection"
+end
+```
+
+For the full documentation, see the [Documentation on RubyDoc][docs]
+
+
+[SDBM]: https://ruby-doc.org/stdlib-2.6.3/libdoc/sdbm/rdoc/SDBM.html
+[docs]: https://rubydoc.info/gems/active_cabinet
+
+---
+
+[SDBM]: https://ruby-doc.org/stdlib-2.7.1/libdoc/sdbm/rdoc/SDBM.html

data/lib/active_cabinet.rb

@@ -0,0 +1,167 @@
+require 'hash_cabinet'
+require 'active_cabinet/metaclass'
+
+# @!attribute [r] attributes
+#   @return [Hash] the attributes of the record
+# @!attribute [r] error
+#   @return [String, nil] the last validation error, after calling {valid?}
+class ActiveCabinet
+  attr_reader :attributes, :error
+
+  # @!group Constructor
+
+  # Initializes a new record with {attributes}
+  #
+  # @param [Hash] attributes record attributes
+  def initialize(attributes = {})
+    @attributes = attributes.transform_keys(&:to_sym)
+  end
+
+  # @!group Attribute Management
+
+  # Returns an array containing {required_attributes} and {optional_attributes}.
+  #
+  # @return [Array<Symbol>] array of required attribute keys.
+  def allowed_attributes
+    self.class.allowed_attributes
+  end
+
+  # Returns an array of required record attributes. 
+  #
+  # @see ActiveCabinet.required_attributes.
+  # @return [Array<Symbol>] the array of required attributes
+  def required_attributes
+    self.class.required_attributes
+  end
+
+  # Returns an array of optional record attributes. 
+  #
+  # @see ActiveCabinet.optional_attributes.
+  # @return [Array<Symbol>] the array of optional attributes
+  def optional_attributes
+    self.class.optional_attributes
+  end
+
+  # Returns +true+ if the object is valid.
+  # 
+  # @return [Boolean] +true+ if the record is valid.
+  def valid?
+    missing_keys = required_attributes - attributes.keys
+    if missing_keys.any?
+      @error = "missing required attributes: #{missing_keys}"
+      return false
+    end
+
+    if !optional_attributes or optional_attributes.any?
+      invalid_keys = attributes.keys - allowed_attributes
+      if invalid_keys.any?
+        @error = "invalid attributes: #{invalid_keys}"
+        return false
+      end
+    end
+
+    true
+  end
+
+  # @!group Dynamic Attribute Accessors
+
+  # Provides read/write access to {attributes}
+  def method_missing(method_name, *args, &blk)
+    name = method_name
+    return attributes[name] if attributes.has_key? name
+
+    suffix = nil
+
+    if name.to_s.end_with?('=', '?')
+      suffix = name[-1]
+      name = name[0..-2].to_sym
+    end
+
+    case suffix
+    when "="
+      attributes[name] = args.first
+
+    when "?"
+      !!attributes[name]
+
+    else
+      super
+
+    end
+  end
+
+  # Returns +true+ when calling +#respond_to?+ with an attribute name.
+  #
+  # @return [Boolean] +true+ if there is a matching attribute.
+  def respond_to_missing?(method_name, include_private = false)
+    name = method_name
+    name = name[0..-2].to_sym if name.to_s.end_with?('=', '?')
+    attributes.has_key?(name) || super
+  end
+
+  # @!group Loading and Saving 
+
+  # Reads the attributes of the record from the cabinet and returns the 
+  # record itself. If the record is not stored on disk, returns +nil+.
+  #
+  # @return [self, nil] the object or +nil+ if the object is not stored.
+  def reload
+    return nil unless saved?
+    update cabinet[id]
+    self
+  end
+
+  # Saves the record to the cabinet if it is valid. Returns the record on 
+  # success, or +false+ on failure.
+  #
+  # @return [self, false] the record or +false+ on failure.
+  def save
+    if valid?
+      cabinet[id] = attributes
+      self
+    else
+      false
+    end
+  end
+
+  # Returns +true+ if the record exists in the cabinet.
+  #
+  # @note This method only verifies that the ID of the record exists. The
+  #   attributes of the instance and the stored record may differ.
+  #
+  # @return [Boolean] +true+ if the record is saved in the cabinet.
+  def saved?
+    cabinet.key? id
+  end
+
+  # Update the record with new or modified attributes.
+  #
+  # @param [Hash] new_attributes record attributes
+  def update(new_attributes)
+    @attributes = attributes.merge new_attributes
+  end
+
+  # Update the record with new or modified attributes, and save.
+  #
+  # @param [Hash] new_attributes record attributes
+  def update!(new_attributes)
+    update new_attributes
+    save
+  end
+
+  # @!group Utilities
+
+  # Returns a Hash of attributes
+  #
+  # @return [Hash<Symbol, Object>] the hash of attriibutes/
+  def to_h
+    attributes
+  end
+
+protected
+
+  def cabinet
+    self.class.cabinet
+  end
+
+end

data/lib/active_cabinet/config.rb

@@ -0,0 +1,21 @@
+class ActiveCabinet
+  # Configure the global behavior of {ActiveCabinet}.
+  #
+  # @example
+  #   # Change the directory where cabinets are stored
+  #   ActiveCabinet::Config.dir = "cabinets"
+  #
+  # @attr_writer [String] dir Sets the base directory for all cabinet files (default +'db'+).
+  class Config
+    class << self
+      attr_writer :dir
+
+      # Returns the base directory for all cabinet files.
+      #
+      # @return [String] the base directory for all cabinet files.
+      def dir
+        @dir ||= 'db'
+      end
+    end
+  end
+end

data/lib/active_cabinet/metaclass.rb

@@ -0,0 +1,170 @@
+require 'hash_cabinet'
+require 'forwardable'
+require 'active_cabinet/config'
+
+# {ActiveCabinet} lets you create a +HashCabinet+ collection model by
+# subclassing {ActiveCabinet}:
+#
+#   class Song < ActiveCabinet
+#   end
+#
+# Now, you can perform CRUD operations on this collection, which will be
+# persisted to disk:
+#
+#   # Create
+#   Song.create id: 1, title: 'Moonchild', artist: 'Iron Maiden'
+#
+#   # Read
+#   moonchild = Song[1] # or Song.find 1
+#
+#   # Update
+#   moonchild.title = "22 Acacia Avenue"
+#   moonchild.save
+#   # or
+#   moonchild.update! title: "22 Acacia Avenue"
+#
+#   # Delete
+#   Song.delete 1
+#   
+class ActiveCabinet
+  class << self
+    extend Forwardable
+    def_delegators :cabinet, :count, :delete, :empty?, :keys, :size
+
+    # @!group Creating Records
+
+    # Creates and saves a new record instance.
+    #
+    # @param [String] id the record id.
+    # @param [Hash] attributes the attributes to create.
+    def []=(id, attributes)
+      create attributes.merge(id: id)
+    end
+
+    # Creates and saves a new record instance.
+    #
+    # @param [Hash] attributes the attributes to create.
+    # @return [Object] the record.
+    def create(attributes)
+      record = new attributes
+      record.save || record
+    end
+
+    # @!group Reading Records
+
+    # Returns all records.
+    #
+    # @return [Array] array of all records.
+    def all
+      cabinet.values.map do |attributes|
+        new(attributes)
+      end
+    end
+
+    # Returns all records, as an Array of Hashes.
+    #
+    # @return [Array] array of all records.
+    def all_attributes
+      cabinet.values
+    end
+
+    # Returns an array of records for which the block returns true.
+    #
+    # @yieldparam [Object] record all record instances.
+    def where
+      all.select { |record| yield record }
+    end
+
+    # Returns the record matching the +id+.
+    #
+    # @return [Object, nil] the object if found, or +nil+.
+    def find(id)
+      attributes = cabinet[id]
+      attributes ? new(attributes) : nil
+    end
+    alias [] find
+
+    # @!group Deleting Records
+
+    # Deletes a record matching the +id+
+    #
+    # @param [String] id the record ID.
+    # @return [Boolean] +true+ on success, +false+ otherwise.
+    def delete(id)
+      !!cabinet.delete(id)
+    end
+
+    # Deletes all records.
+    def drop
+      cabinet.clear
+    end
+
+    # @!group Attribute Management
+
+    # Returns an array containing {required_attributes} and {optional_attributes}.
+    #
+    # @return [Array<Symbol>] array of required attribute keys.
+    def allowed_attributes
+      (optional_attributes || []) + required_attributes
+    end
+
+    # Sets the required record attribute names.
+    #
+    # @param [Array<Symbol>] *attributes one or more attribute names.
+    # @return [Array<Symbol>] the array of required attributes.
+    def required_attributes(*args)
+      args = args.first if args.first.is_a? Array
+      if args.any?
+        @required_attributes = args
+        @required_attributes.push :id unless @required_attributes.include? :id
+        @required_attributes
+      else
+        @required_attributes ||= [:id]
+      end
+    end
+
+    # Sets the optional record attribute names.
+    #
+    # @param [Array<Symbol>] *attributes one or more attribute names.
+    # @return [Array<Symbol>] the array of optional attributes.
+    def optional_attributes(*args)
+      args = args.first if args.first.is_a? Array
+      if args.first === false
+        @optional_attributes = false
+      elsif args.any?
+        @optional_attributes = *args
+      else
+        @optional_attributes.nil? ? [] : @optional_attributes
+      end
+    end
+
+    # @!group Utilities
+
+    # Returns all records as a hash, with record IDs as the keys.
+    def to_h
+      cabinet.to_h.map { |id, attributes| [id, new(attributes)] }.to_h
+    end
+
+    # Returns the +HashCabinet+ instance.
+    #
+    # @return [HashCabinet] the +HashCabinet+ object.
+    def cabinet
+      @cabinet ||= HashCabinet.new "#{Config.dir}/#{cabinet_name}"
+    end
+
+    # Returns or sets the cabinet name. 
+    # Defaults to the name of the class, lowercase.
+    #
+    # @param [String] name the name of the cabinet file.
+    # @return [String] name the name of the cabinet file.
+    def cabinet_name(new_name = nil)
+      if new_name
+        @cabinet = nil
+        @cabinet_name = new_name
+      else
+        @cabinet_name ||= self.to_s.downcase.gsub('::', '_')
+      end
+    end
+
+  end
+end

data/lib/active_cabinet/version.rb

@@ -0,0 +1,3 @@
+class ActiveCabinet
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: active_cabinet
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Danny Ben Shitrit
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-09-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: hash_cabinet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+description: ActiveRecord-inspired interface for HashCabinet, the file-basd key-object
+  store.
+email: db@dannyben.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/active_cabinet.rb
+- lib/active_cabinet/config.rb
+- lib/active_cabinet/metaclass.rb
+- lib/active_cabinet/version.rb
+homepage: https://github.com/dannyben/active_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.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key: 
+specification_version: 4
+summary: Database-like interface for HashCabinet
+test_files: []