carton_db 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: aecfa7225f91fad95b3a8eaa417a155248195aff
+  data.tar.gz: 7e64f92388321296900fa4774b7fec3e608fb388
+SHA512:
+  metadata.gz: b0afb5be66793688c004e8eca157cee2e53ea2aacb8df21afa600fa93f616d9df25a99ecf905a183e7d1be0c461da3eaf60e60f92ec978793bca1add8f50042f
+  data.tar.gz: 2bceb896fbcf2a4ba811ce5548f90cfde7a451ca7417b58a2aa846681452f44b89564a5755c05af82f020d0b37e1612ef365ac5eff3fe00c480a5d2b4cda9e71

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.ruby-version

@@ -0,0 +1 @@
+2.3.1

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.2.2
+before_install: gem install bundler -v 1.14.6

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in carton_db.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Steve Jorgensen
+
+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

@@ -0,0 +1,140 @@
+# CartonDb
+
+A pure Ruby key/value data storage system where the values may
+consist of simple data structures.
+
+The primary goals of this library are simplicity of implementation
+and reliable, predicatble behavior when used as intended, along
+with documentation making it reasonably clear what is intended.
+
+## Uses
+
+Uses for this gem seem pretty limited, but you might have a
+purpose for it that the author has not thought about.
+
+This is a formalization of a solution that was created to solve
+a specific problem. The problem was adding a feature to a
+Ruby program running on Heroku to collect data into a map of
+sets of elements that would be too large to be effectively
+handled in memory. The application didn't already have any use
+for a relational database server, and I didn't want to add one
+just for this requirement. A redis db with sufficient capacity
+would have been expensive, and solutions such as SQLite are
+specifically not supported by Heroku so people don't mistakenly
+expect the data to be preserved. Ruby's `DBM` and `SDMB` proved
+to be too unpredicatable and flakey to be practical solutions.
+
+Although this tool was initially developed to store transient
+data for use within a single process invocation and then
+discarded, it is also quite well suited for long term data
+storage on a system that preserves filesystem data over time.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'carton_db'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install carton_db
+
+## Characteristics
+
+Each database has a name which is the path of a directory in the
+filesystem containing the files that store the data.
+
+A database is accessed through an instance of a database class.
+
+An instance of a database class maintains no state in memory
+between calls to its methods except for the database name.
+
+An empty directory is a valid empty database.
+
+Concurrent reads from a database are supported and safe.
+
+Writing to a database concurrently with reads or writes by
+other processes or threads is not supported, and the results of
+attempting to do that are unpredictable.
+
+Initializing a new database class instance creates its directory
+in the filesystem if it does not already exist. The parent of the
+database directory is expected to already  exist, and an error
+will occur if it doesn't.
+
+The database structure is designed to effectively handle up to
+several million elements with entries containing up to 1 or 2
+thousand elements each.
+
+The speed of database operations is relatively good, but this is
+not a high performance database management system. See the
+code documentation in the classes for more details about the
+performance of particular database operations.
+
+## Usage
+
+Currently, this gem includes only one kind of database, which is
+implemented by the `CartonDB::ListMapDb` class. It is a map of
+lists where each entry has a string for a key and a list of of 0
+or more string elements as content.
+
+The name of the database is the path of a directory in the
+filesystem that either already exists or shall be created as
+a container for the stored data.
+
+Example:
+
+    require 'carton_db'
+
+    db = CartonDb::ListMapDb.new('/tmp/my_list_map')
+
+    db['Some Key'] = ['element 1', 'element 2']
+
+    db['Another Key'] = []
+
+    db.append_to 'Yet Another', 'abc'
+    db.append_to 'Yet Another', 'def'
+
+    p db.count
+    # 3
+
+    p db['Some Key']
+    # ["element 1", "element 2"]
+
+    p db['Another Key']
+    # []
+
+    p db['Yet Another']
+    # ["abc", "def"]
+
+    p db['Something Else']
+    # nil
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies.
+Then, run `rake spec` to run the tests. You can also run `bin/console`
+for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake
+install`. To release a new version, update the version number in
+`version.rb`, and then run `bundle exec rake release`, which will
+create a git tag for the version, push git commits and tags, and push
+the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/[USERNAME]/carton_db.
+
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,22 @@
+# coding: utf-8
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+namespace :spec do
+
+  desc 'Run all RSpec code examples'
+  RSpec::Core::RakeTask.new(:all)
+
+  desc 'Run RSpec code examples except those tagged as slow'
+  RSpec::Core::RakeTask.new(:fast) do |t|
+    t.rspec_opts = '--tag ~slow'
+  end
+
+  desc 'Run RSpec code examples that are tagged as slow'
+  RSpec::Core::RakeTask.new(:slow) do |t|
+    t.rspec_opts = '--tag slow'
+  end
+
+end
+
+task :default => 'spec:all'

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# -*- coding: UTF-8 -*-
+
+require "bundler/setup"
+require "carton_db"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# -*- coding: UTF-8 -*-
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/carton_db.gemspec

@@ -0,0 +1,27 @@
+# -*- coding: UTF-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'carton_db/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "carton_db"
+  spec.version       = CartonDb::VERSION
+  spec.authors       = ["Steve Jorgensen"]
+  spec.email         = ["stevej@stevej.name"]
+
+  spec.summary       = "A pure Ruby key/value data storage system where the" \
+                      " values may consist of simple data structures."
+  spec.homepage      = "https://github.com/stevecj/carton_db.js"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.14"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

data/lib/carton_db/datum.rb

@@ -0,0 +1,147 @@
+require 'digest'
+
+module CartonDb
+
+  module Datum
+
+    def self.for_plain(plain_text, auto_placeholder: false)
+      if auto_placeholder && plain_text.nil?
+        Datum::Placeholder
+      else
+        Datum::ForPlain.new(plain_text)
+      end
+    end
+
+    def self.for_escaped(escaped_text, auto_placeholder: false)
+      if auto_placeholder && escaped_text.nil?
+        Datum::Placeholder
+      else
+        Datum::ForEscaped.new(escaped_text)
+      end
+    end
+
+    def self.placeholder
+      Datum::Placeholder
+    end
+
+    class Base
+      def plain
+        raise NotImplementedError, "Subclass responsibility."
+      end
+
+      def escaped
+        raise NotImplementedError, "Subclass responsibility."
+      end
+
+      def placeholder?
+        raise NotImplementedError, "Subclass responsibility."
+      end
+
+      def storage_hashcode
+        return nil if placeholder?
+        @storage_hashcode ||= Digest::MD5.digest(plain)
+      end
+
+      def eql?(other)
+        raise NotImplementedError, "Subclass responsibility."
+      end
+
+      alias == eql?
+
+      def hash
+        raise NotImplementedError, "Subclass responsibility."
+      end
+    end
+
+    class ForPlain < Datum::Base
+      attr_reader :plain
+
+      def initialize(plain)
+        if plain.nil?
+          raise ArgumentError "A non-nil 'plain' value is required."
+        end
+        @plain = plain
+      end
+
+      def escaped
+        @escaped ||= CartonDb::Escaping.escape(@plain)
+      end
+
+      def placeholder?
+        false
+      end
+
+      def eql?(other)
+        return false unless other.is_a?(Datum::Base)
+        return true if other.class == self.class && @plain == other.plain
+        return escaped == other.escaped
+      end
+
+      alias == eql?
+
+      def hash
+        escaped.hash
+      end
+    end
+
+    class ForEscaped < Datum::Base
+      attr_reader :escaped
+
+      def initialize(escaped)
+        if escaped.nil?
+          raise ArgumentError "A non-nil 'escaped' value is required."
+        end
+        @escaped = escaped
+      end
+
+      def plain
+        @plain ||= CartonDb::Escaping.unescape(@escaped)
+      end
+
+      def placeholder?
+        false
+      end
+
+      def eql?(other)
+        return false unless other.is_a?(Datum::Base)
+        return true if other.class == self.class && @escaped == other.escaped
+        return escaped == other.escaped
+      end
+
+      alias == eql?
+
+      def hash
+        escaped.hash
+      end
+    end
+
+    class PlaceholderClass < Datum::Base
+      def plain
+        nil
+      end
+
+      def escaped
+        nil
+      end
+
+      def placeholder?
+        true
+      end
+
+      def eql?(other)
+        return false unless other.is_a?(Datum::Base)
+        return other.placeholder?
+      end
+
+      alias == eql?
+
+      def hash
+        PlaceholderClass.hash
+      end
+    end
+
+    Placeholder = PlaceholderClass.new
+
+  end
+
+end

data/lib/carton_db/escaping.rb

@@ -0,0 +1,60 @@
+module CartonDb
+
+  module Escaping
+
+    ESCAPING_MAP = {
+      "\u0000".freeze => '\x00'.freeze,
+      "\u0001".freeze => '\x01'.freeze,
+      "\u0002".freeze => '\x02'.freeze,
+      "\u0003".freeze => '\x03'.freeze,
+      "\u0004".freeze => '\x04'.freeze,
+      "\u0005".freeze => '\x05'.freeze,
+      "\u0006".freeze => '\x06'.freeze,
+      "\u0007".freeze => '\a'.freeze,
+      "\u0008".freeze => '\b'.freeze,
+      "\u0009".freeze => '\t'.freeze,
+      "\u000A".freeze => '\n'.freeze,
+      "\u000B".freeze => '\v'.freeze,
+      "\u000C".freeze => '\f'.freeze,
+      "\u000D".freeze => '\r'.freeze,
+      "\u000E".freeze => '\x0E'.freeze,
+      "\u000F".freeze => '\x0F'.freeze,
+      "\u0010".freeze => '\x10'.freeze,
+      "\u0011".freeze => '\x11'.freeze,
+      "\u0012".freeze => '\x12'.freeze,
+      "\u0013".freeze => '\x13'.freeze,
+      "\u0014".freeze => '\x14'.freeze,
+      "\u0015".freeze => '\x15'.freeze,
+      "\u0016".freeze => '\x16'.freeze,
+      "\u0017".freeze => '\x17'.freeze,
+      "\u0018".freeze => '\x18'.freeze,
+      "\u0019".freeze => '\x19'.freeze,
+      "\u001A".freeze => '\x1A'.freeze,
+      "\u001B".freeze => '\x1B'.freeze,
+      "\u001C".freeze => '\x1C'.freeze,
+      "\u001D".freeze => '\x1D'.freeze,
+      "\u001E".freeze => '\x1E'.freeze,
+      "\u001F".freeze => '\x1F'.freeze,
+      "\u007F".freeze => '\x7F'.freeze,
+      "\\".freeze     => "\\\\".freeze,
+    }.freeze
+
+    UNESCAPING_MAP = ESCAPING_MAP.invert.freeze
+
+    def self.escape(value)
+      value.gsub(
+        /[\x00-\x1F\x7F\\]/,
+        ESCAPING_MAP
+      )
+    end
+
+    def self.unescape(esc)
+      esc.gsub(
+        /\\(?:\\|x[01][0-9A-F]|x7F|[abtnvfr])/,
+        UNESCAPING_MAP
+      )
+    end
+
+  end
+
+end

data/lib/carton_db/list_map_db/segment.rb

@@ -0,0 +1,130 @@
+# -*- coding: UTF-8 -*-
+require 'fileutils'
+
+module CartonDb
+  class ListMapDb
+
+    class Segment
+
+      def self.in_db_for_hashcode(db_name, hashcode)
+        seg_hash_part = hashcode[-1]
+        seg_num = seg_hash_part.bytes[0] & 127
+
+        group_hashcode = hashcode[0..-2]
+        seg_group = ListMapDb::SegmentGroup.
+          in_db_for_hashcode(db_name, group_hashcode)
+
+        new(seg_group, "#{seg_num}.txt")
+      end
+
+      def self.each_in_db(db_name)
+        ListMapDb::SegmentGroup.each_in_db db_name do |seg_group|
+          Dir.entries(seg_group.directory_path).each do |de|
+            next unless de =~ /^\d{1,3}[.]txt$/
+            yield new(seg_group, de)
+          end
+        end
+      end
+
+      def self.clear_all_in_db(db_name)
+        ListMapDb::SegmentGroup.each_in_db db_name do |seg_group|
+          filenames = []
+          Dir.entries(seg_group.directory_path).each do |de|
+            next unless de =~ /^\d{1,3}[.]txt$/
+            filename = File.join(seg_group.directory_path, de)
+            filenames << filename
+          end
+          FileUtils.rm *filenames
+        end
+      end
+
+      attr_accessor :segment_group,  :segment_filename
+      private       :segment_group=, :segment_filename=
+
+      def initialize(segment_group, segment_filename)
+        self.segment_group = segment_group
+        self.segment_filename = segment_filename
+      end
+
+      def filename
+        File.join(segment_group.directory_path, segment_filename)
+      end
+
+      def content?
+        stat && ! stat.zero?
+      end
+
+      def empty?
+        ! content?
+      end
+
+      def each_entry
+        entries = nil
+        each_entry_element_line do |key_d, elem_d, _line|
+          entries ||= {}
+          content = entries[key_d] ||= []
+          content << elem_d.plain unless elem_d.placeholder?
+        end
+        return unless entries
+        entries.each do |key_d, content|
+          yield key_d.plain, content
+        end
+      end
+
+      def each_entry_element_line
+        return if empty?
+        each_line do |line|
+          esc_key, esc_element = line.strip.split("\t", 2)
+          key_d = CartonDb::Datum.for_escaped(esc_key)
+          element_d = CartonDb::Datum.for_escaped(
+            esc_element, auto_placeholder: true)
+          yield key_d, element_d, line
+        end
+      end
+
+      def open_append
+        touch_dir
+        File.open filename, 'a', **FILE_ENCODING_OPTS do |io|
+          yield io
+        end
+      end
+
+      def open_overwrite
+        touch_dir
+        File.open filename, 'w', **FILE_ENCODING_OPTS do |io|
+          yield io
+        end
+      end
+
+      private
+
+      def stat
+        return @stat if defined? @stat
+        return @stat = nil unless File.file?(filename)
+        return @stat = File.stat(filename)
+      end
+
+      def open_read
+        File.open filename, 'r', **FILE_ENCODING_OPTS do |io|
+          yield io
+        end
+      end
+
+      def touch_dir
+        dir = File.dirname(filename)
+        return if File.directory?(dir)
+        FileUtils.mkdir dir
+      end
+
+      def each_line
+        open_read do |io|
+          io.each_line do |line|
+            yield line
+          end
+        end
+      end
+
+    end
+
+  end
+end

data/lib/carton_db/list_map_db/segment_group.rb

@@ -0,0 +1,38 @@
+# -*- coding: UTF-8 -*-
+require 'fileutils'
+
+module CartonDb
+  class ListMapDb
+
+    class SegmentGroup
+
+      def self.in_db_for_hashcode(db_name, hashcode)
+        group_hash_part = hashcode[-1]
+        group_num = group_hash_part.bytes[0] & 127
+        new(db_name, group_num.to_s)
+      end
+
+      def self.each_in_db(db_name)
+        Dir.entries(db_name).each do |de|
+          next unless de =~ /^\d{1,3}$/
+          seg_group = new(db_name, de)
+          next unless File.directory?(seg_group.directory_path)
+          yield seg_group
+        end
+      end
+
+      attr_accessor :db_name,  :name_part
+      private       :db_name=, :name_part=
+
+      def initialize(db_name, name_part)
+        self.db_name   = db_name
+        self.name_part = name_part
+      end
+
+      def directory_path
+        @directory_path ||= File.join(db_name, name_part)
+      end
+    end
+
+  end
+end

data/lib/carton_db/list_map_db.rb

@@ -0,0 +1,312 @@
+# -*- coding: UTF-8 -*-
+require 'forwardable'
+require 'fileutils'
+require 'carton_db/list_map_db/segment'
+require 'carton_db/list_map_db/segment_group'
+
+module CartonDb
+
+  # A map with string keys lists of strings as contents.
+  #
+  # This is suitable for storing a total number of elements as
+  # large as the low millions, with each entry containing a
+  # number of elements in the hundreds or low thousands.
+  class ListMapDb
+    extend Forwardable
+    include Enumerable
+
+    FILE_ENCODING_OPTS = {
+      internal_encoding: Encoding::UTF_8,
+      external_encoding: Encoding::UTF_8
+    }.freeze
+
+    # Initializes an instance that interacts with the database
+    # identified by the given name, which is the full path to a
+    # directory in the filesystem.
+    #
+    # The directory for the database will be created if it does
+    # not already exist.
+    #
+    # This is a very fast operation.
+    #
+    # @param name [String] The full path of the directory in the
+    #   filesystem in which the data is stored or will be stored.
+    def initialize(name)
+      self.name = name
+      FileUtils.mkdir name unless File.directory?(name)
+    end
+
+    # Creates a new entry or replaces the contents of the
+    # existing entry identified by the given key.
+    #
+    # The is a fairly fast operation, but can be somewhat
+    # slower in a large database. Note that appending and
+    # concatenating may be faster than assignment.
+    #
+    # @param key [String] The key identifying the entry.
+    # @param content [Array<String>] An array or other
+    #   enumerable collection of 0 or more list element string
+    #   values to be stored.
+    def []=(key, content)
+      key_d = CartonDb::Datum.for_plain(key)
+      segment = segment_containing(key_d)
+      if segment.empty?
+        concat_elements key_d.plain, content
+      else
+        replace_entry_in_file segment, key_d, content
+      end
+    end
+
+    # Returns the content of the entry identified by the given
+    # key or nil if no such entry exists.
+    #
+    # This operation is fast, but may be slower for a larger
+    # database.
+    #
+    # @param key [String] The key identifying the entry.
+    # @return [Array<String>] if a matching entry exists.
+    # @return [nil] if no matching entry exists.
+    def [](key)
+      key_d = CartonDb::Datum.for_plain(key)
+      segment = segment_containing(key_d)
+
+      ary = nil
+      segment.each_entry_element_line do |kd, ed, _line|
+        next ary unless kd == key_d
+        ary ||= []
+        ary << ed.plain unless ed.placeholder?
+      end
+      ary
+    end
+
+    def key?(key)
+      key_d = CartonDb::Datum.for_plain(key)
+      segment = segment_containing(key_d)
+
+      segment.each_entry_element_line do |kd, _ed, _line|
+        return true if kd = key_d
+      end
+      false
+    end
+
+    # Returns true if the map has no entries.
+    #
+    # This is a fairly fast operation.
+    #
+    # @return [Boolean]
+    def empty?
+      ListMapDb::Segment.each_in_db name do |segment|
+        return false unless segment.empty?
+      end
+      true
+    end
+
+    # Returns the number of entries in the map.
+    #
+    # This operation scans the entire database to count the keys,
+    # so it can be be a slow operation if the database is large.
+    #
+    # @return [Fixnum]
+    def count
+      key_count = 0
+      file_key_datum_set = Set.new
+      ListMapDb::Segment.each_in_db name do |segment|
+        next if segment.empty?
+        file_key_datum_set.clear
+        segment.each_entry_element_line do |kd, _ed, _line|
+          file_key_datum_set << kd
+        end
+        key_count += file_key_datum_set.length
+      end
+      key_count
+    end
+
+    # Creates an entry with an empty list as its content if no
+    # entry exists for the given key. Has no effect on the content
+    # of the entry if it already exists.
+    #
+    # Using :small optimization (the default), the operation may
+    # be slow for a large database since it checks for the
+    # existence of the key before marking its existence.
+    #
+    # Using :fast optimization, the operation will always be
+    # fast, but it will add a mark for the existence of the key
+    # even if that is redundant, thus adding to the size of the
+    # stored data.
+    #
+    # @param key [String] The key identifying the entry.
+    # @param optimization[:small, :fast] The optimization mode.
+    def touch(key, optimization: :small)
+      if optimization != :small && optimization != :fast
+        raise ArgumentError, "Invalid optimization value. Must be :small or :fast"
+      end
+
+      key_d = CartonDb::Datum.for_plain(key)
+      segment = segment_containing(key_d)
+
+      if optimization == :small && segment.content?
+        segment.each_entry_element_line do |kd, _ed, _line|
+          return if kd == key_d
+        end
+      end
+
+      segment.open_append do |io|
+        io << key_d.escaped << "\n"
+      end
+    end
+
+    # Removes all entries from the database, leaving it empty.
+    #
+    # This operation can be somewhat slow for a large database.
+    #
+    def clear
+      ListMapDb::Segment.clear_all_in_db name
+    end
+
+    # Yields each entry in the database as a key/array pair.
+    #
+    # This operation can take a lot of total time for a large
+    # database, but yields entries pretty rapidly regardless
+    # of database size.
+    #
+    # @yieldparam key [String] The key of the entry.
+    # @yeildparam array [Array<String>] The elements of the list
+    #   entry's content.
+    def each
+      key_arrays_slice = {}
+      ListMapDb::Segment.each_in_db name do |segment|
+        segment.each_entry do |key, content|
+          yield key, content
+        end
+      end
+    end
+
+    # Removes an entry from the database. Has no effect if the
+    # entry already does not exist.
+    #
+    # This operation is fast, but may be slower for a larger
+    # database.
+    #
+    # @param key [String] The key identifying the entry to be
+    #   deleted.
+    def delete(key)
+      key_d = CartonDb::Datum.for_plain(key)
+      segment = segment_containing(key_d)
+      return if segment.empty?
+
+      new_segment = ListMapDb::Segment.new(
+        segment.segment_group, "#{segment.segment_filename}.new")
+      new_segment.open_overwrite do |io|
+        segment.each_entry_element_line do |kd, _ed, line|
+          io << line unless kd == key_d
+        end
+      end
+
+      File.unlink segment.filename
+      File.rename new_segment.filename, segment.filename
+    end
+
+    # Appends an element string to the content of an entry.
+    # If the entry does not already exist, then one is
+    # created with a list containing the given element as its
+    # content.
+    #
+    # Since this will only append text to a file within the
+    # database, it is a very fast operation.
+    #
+    # @param key [String] The key identifying the entry.
+    # @param element [String] The element to be appended to the
+    #   content of the entry.
+    def append_element(key, element)
+      key_d = CartonDb::Datum.for_plain(key)
+      element_d = CartonDb::Datum.for_plain(element)
+      segment = segment_containing(key_d)
+      FileUtils.mkpath File.dirname(segment.filename)
+      segment.open_append do |io|
+        io << "#{key_d.escaped}\t#{element_d.escaped}\n"
+      end
+    end
+
+    # Appends any number of element strings to the content of an
+    # entry. If the entry does not already exist, then one is
+    # created with the given list as its content.
+    #
+    # Appending an empty or nil collection is equivalent to
+    # invoking `db.touch key, optimization: :small`.
+    #
+    # When appending a non-empty collection, this is a fast
+    # operation since it only appends text to an existing file.
+    #
+    # @param key [String] The key identifying the entry.
+    # @param elements [Array<String>] An array or other
+    #   enumerable collection of elements to append.
+    def concat_elements(key, elements)
+      if empty_collection?(elements)
+        touch key, optimization: :small
+      else
+        concat_any_elements key, elements
+      end
+    end
+
+    # Appends any number of element strings to the content of an
+    # entry. If the given elements collection is empty or nil,
+    # then the database is unchanged, and a new entry is not
+    # created if one did not exist previously.
+    #
+    # This is a fast operation since it only appends text to an
+    # existing file.
+    #
+    # @param key [String] The key identifying the entry.
+    # @param elements [Array<String>] An array or other
+    #   enumerable collection of elements to append.
+    def concat_any_elements(key, elements)
+      key_d = CartonDb::Datum.for_plain(key)
+      segment = segment_containing(key_d)
+      segment.open_append do |io|
+        elements.each do |element|
+          element_d = CartonDb::Datum.for_plain(element)
+          io<< "#{key_d.escaped}\t#{element_d.escaped}\n"
+        end
+      end
+    end
+
+    private
+
+    attr_accessor :name
+
+    def replace_entry_in_file(segment, key_d, content)
+      new_segment = ListMapDb::Segment.new(
+        segment.segment_group, "#{segment.segment_filename}.new")
+      new_segment.open_overwrite do |nf_io|
+        segment.each_entry_element_line do |kd, _ed, line|
+          nf_io.print line unless kd == key_d
+        end
+        element_count = 0
+        content.each do |element|
+          element_d = CartonDb::Datum.for_plain(element)
+          element_count += 1
+          nf_io.puts "#{key_d.escaped}\t#{element_d.escaped}"
+        end
+        if element_count.zero?
+          nf_io.puts key_d.escaped
+        end
+      end
+      File.unlink segment.filename
+      File.rename new_segment.filename, segment.filename
+    end
+
+    def segment_containing(key)
+      ListMapDb::Segment.in_db_for_hashcode(
+        name, key.storage_hashcode
+      )
+    end
+
+    def empty_collection?(collection)
+      return true if collection.nil?
+      occupied = collection.any? { true }
+      ! occupied
+    end
+
+  end
+
+end

data/lib/carton_db/version.rb

@@ -0,0 +1,4 @@
+# -*- coding: UTF-8 -*-
+module CartonDb
+  VERSION = "1.0.0"
+end

data/lib/carton_db.rb

@@ -0,0 +1,8 @@
+# -*- coding: UTF-8 -*-
+require "carton_db/version"
+require "carton_db/escaping"
+require "carton_db/datum"
+require "carton_db/list_map_db"
+
+module CartonDb
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: carton_db
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Steve Jorgensen
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-05-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: 
+email:
+- stevej@stevej.name
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".ruby-version"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- carton_db.gemspec
+- lib/carton_db.rb
+- lib/carton_db/datum.rb
+- lib/carton_db/escaping.rb
+- lib/carton_db/list_map_db.rb
+- lib/carton_db/list_map_db/segment.rb
+- lib/carton_db/list_map_db/segment_group.rb
+- lib/carton_db/version.rb
+- tmp/.gitkeep
+homepage: https://github.com/stevecj/carton_db.js
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.10
+signing_key: 
+specification_version: 4
+summary: A pure Ruby key/value data storage system where the values may consist of
+  simple data structures.
+test_files: []