RubyGems - db-struct - Versions diffs - 0.1.0 - Mend

db-struct 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (35) hide show

checksums.yaml +7 -0
data/README.md +125 -0
data/Rakefile +35 -0
data/db-struct.gemspec +37 -0
data/doc/DBStruct/BogoHash.html +1384 -0
data/doc/DBStruct/ErrorHelpers.html +288 -0
data/doc/DBStruct/Failure.html +139 -0
data/doc/DBStruct/FieldError.html +143 -0
data/doc/DBStruct/MissingRowError.html +143 -0
data/doc/DBStruct/TypeError.html +143 -0
data/doc/DBStruct.html +1652 -0
data/doc/_index.html +189 -0
data/doc/class_list.html +54 -0
data/doc/css/common.css +1 -0
data/doc/css/full_list.css +58 -0
data/doc/css/style.css +503 -0
data/doc/file.README.html +187 -0
data/doc/file_list.html +59 -0
data/doc/frames.html +22 -0
data/doc/index.html +187 -0
data/doc/js/app.js +344 -0
data/doc/js/full_list.js +242 -0
data/doc/js/jquery.js +4 -0
data/doc/method_list.html +342 -0
data/doc/top-level-namespace.html +110 -0
data/gem.deps.rb +7 -0
data/lib/dbstruct.rb +29 -0
data/lib/internal/bogohash.rb +226 -0
data/lib/internal/dbstruct_base.rb +144 -0
data/lib/internal/dbstruct_class.rb +301 -0
data/lib/internal/error.rb +44 -0
data/lib/internal/util.rb +11 -0
data/spec/dbstruct_spec.rb +452 -0
data/spec/spec_helper.rb +48 -0
metadata +138 -0

data/doc/top-level-namespace.html ADDED Viewed

@@ -0,0 +1,110 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Top Level Namespace
+    &mdash; Documentation by YARD 0.9.37
+</title>
+  <link rel="stylesheet" href="css/style.css" type="text/css" />
+  <link rel="stylesheet" href="css/common.css" type="text/css" />
+<script type="text/javascript">
+  pathId = "";
+  relpath = '';
+</script>
+  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
+  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+    <a href="_index.html">Index</a> &raquo;
+    <span class="title">Top Level Namespace</span>
+</div>
+        <div id="search">
+    <a class="full_list_link" id="class_list_link"
+        href="class_list.html">
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+</div>
+        <div class="clear"></div>
+      </div>
+      <div id="content"><h1>Top Level Namespace
+</h1>
+<div class="box_info">
+</div>
+<h2>Defined Under Namespace</h2>
+<p class="children">
+      <strong class="classes">Classes:</strong> <span class='object_link'><a href="DBStruct.html" title="DBStruct (class)">DBStruct</a></span>
+</p>
+</div>
+      <div id="footer">
+  Generated on Wed Sep 11 13:00:26 2024 by
+  <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.37 (ruby-3.1.4).
+</div>
+    </div>
+  </body>
+</html>

data/gem.deps.rb ADDED Viewed

@@ -0,0 +1,7 @@
+# Instruct `gem install -n` to fetch dependencies from the gemspec
+# file.
+source 'https://rubygems.org'
+gemspec

data/lib/dbstruct.rb ADDED Viewed

@@ -0,0 +1,29 @@
+require 'set'
+require 'sequel'
+# `DBStruct` presents a (SQLite3) database table in a way that
+# closely mimics a Ruby `Hash` of `Struct` objects.
+#
+# This is an abstract base class.  To use it, you create a subclass
+# using the `with` method and define the fields to be used.  This also
+# associates the new class with a `Sequel` dataset.
+#
+# Subinstances behave similarly to Ruby's `Struct` class.  However,
+# setting or reading a value accesses the corresponding database row.
+#
+# Each object also knows its database row ID, an integer that can be
+# used to look up this object.  If a subinstance outlives its database
+# row, attempting to access the fields will raise a
+# {DBStruct::MissingRowError}.  You can use methods {.present?} or
+# {.deleted?} to test if this has happened.
+class DBStruct
+  class BogoHash; end
+end
+require 'internal/error'
+require 'internal/util'
+require 'internal/dbstruct_base'
+require 'internal/dbstruct_class'
+require 'internal/bogohash'

data/lib/internal/bogohash.rb ADDED Viewed

@@ -0,0 +1,226 @@
+# `BogoHash` provides a `Hash`-like interface to the database table
+# corresponding to a {DBStruct} subclass.
+#
+# You can think if it as a `Hash` that holds all instances of a
+# particular {DBStruct} subclass keyed on the objects' `rowid`
+# attributes.  Most of the `Hash` interface is available (including
+# `Enumerable`) with the exception of `[]=`.  `delete` and `delete_if`
+# work as expected, however.
+#
+# You should never explicitly create a `BogoHash`.  Instead, use the
+# class's {DBStruct.items} or {DBStruct.where} methods.
+#
+# Since these methods can be used to narrow the range of items, a
+# `BogoHash` does not necessarily encompass all instances of its
+# associated `DBStruct` subclass.  Rows that do not match the
+# selection criteria are not available even when explicitly addressed
+# by row ID.
+#
+# Under the hood, a `BogoHash` is a wrapper around a
+# `Sequel::Dataset`.
+class DBStruct::BogoHash
+  include Enumerable
+  # @!visibility private
+  # Internal use only!
+  def initialize(dbs_klass, dataset, query)
+    @dbs_klass = dbs_klass
+    @dataset = dataset
+    @query = query.dup.freeze      # used for printing only
+  end
+  # Return a human-friendly string describing this object.
+  #
+  # @return [String]
+  def inspect
+    params = ""
+    params = "(#{@query.map(&:inspect).join(", ")})" unless @query.empty?
+    return "#{@dbs_klass}.items#{params}"
+  end
+  alias to_s inspect
+  # Retrieve the item at `rowid` or nil if its not present.
+  def [](rowid)
+    row = @dataset.first(_id: rowid)
+    return nil unless row
+    return @dbs_klass.new(_id: rowid)
+  end
+  # Test if `rowid` is one of the keys in `self`.
+  def has_key?(rowid) = !! self[rowid]
+  alias include? has_key?
+  alias member? has_key?
+  alias key? has_key?
+  # Return the number of items in `self`.
+  def size = @dataset.count
+  alias length size
+  # Test if self has no items
+  def empty? = size() == 0
+  # Return all keys.
+  # @return [Array[Integer]] - the row IDs
+  def keys = map{|k,v| k}
+  # Return all values.
+  # @return [Array[DBStruct.with(...)]]
+  def values = map{|k,v| v}
+  # Return all keys and values as an array of two-element arrays.
+  # @return [Array[Array[Integer, DBStruct.with(...)]]]
+  def to_a = map{|k,v| [k,v]}
+  #
+  # Deletion
+  #
+  # Delete `rowid` and its associated value from the underlying table
+  # (and `self` by extension).  If `rowid` is not present, does
+  # nothing.
+  #
+  # Note that the deleted row object will be returned but can no
+  # longer be used.  In particular, it does not hold the contents of
+  # the deleted row.
+  #
+  # @return [DBStruct.with(...)] The deleted value or nil
+  def delete(rowid, &block)
+    transaction {
+      unless has_key?(rowid)
+        return block.value if block
+        return nil
+      end
+      val = self[rowid]
+      @dataset.where(_id: rowid).delete
+      return val
+    }
+  end
+  # Evaluate the block on each key-value pair in `self` end delete
+  # each entry for which the block returns true.
+  #
+  # Like all enumeration operations, the tests and deletions occur in
+  # a single transaction.
+  #
+  # @yield [value]            The block to evaluate
+  def delete_if(&block)
+    transaction {
+      self.each{ |k, v| block.call(k,v) and delete(k) }
+    }
+    return self
+  end
+  alias reject! delete_if
+  # Delete all entries
+  def clear
+    @dataset.delete
+    return self
+  end
+  #
+  # Enumeration
+  #
+  # Evaluate `block` over each key-and-value pair (i.e. row and
+  # row-id).  If no block is given, returns an Enumerator instead.
+  #
+  # It is safe to perform other database operations inside the block
+  # or enumeration loop.  This includes modifications to the database
+  # being enumerated, although whether or not added or removed items
+  # are still visited is undefined.
+  #
+  # If called with a block, the entire operation happens within a
+  # single transaction.
+  #
+  # Since this class imports Enumerable, all of its functionality is
+  # also available.
+  def each(&block) = each_backend(:basic_each, block)
+  alias each_pair each
+  # Like {.each} but only yields the key (i.e. row ID).
+  def each_key(&block) = each_backend(:basic_each_key, block)
+  # Like {.each} but only yields the value.
+  def each_value(&block) = each_backend(:basic_each_value, block)
+  private
+  def row_id_after(prev_rowid)
+    row = @dataset
+      .where{_id > prev_rowid}
+      .limit(1)
+      .select(:_id)
+      .first
+    return row[:_id] if row
+    return nil
+  end
+  # This is slow, but will usually work even if there are database
+  # operations in the block.
+  def basic_each(&block)
+    return if size == 0
+    curr = -1
+    while true
+      rowid = row_id_after(curr)
+      return unless rowid
+      block.call(rowid, self[rowid])
+      curr = rowid
+    end
+  end
+  def basic_each_key(&block) = basic_each{|k,v| block.call(k)}
+  def basic_each_value(&block) = basic_each{|k,v| block.call(v)}
+  # Handle the enumeration methods (each, each_key, each_value) as
+  # expected: if given, call with the block inside a transaction;
+  # otherwise, return an Enumerator for it.
+  def each_backend(each_method, block)
+    return self.to_enum(each_method) unless block
+    transaction { self.send(each_method, &block) }
+    return self
+  end
+  # TODO: unsafe_each via Dataset.each; faster but troublesome if you
+  # modify things within the block.
+  public
+  #
+  # Advanced Querying
+  #
+  # Expose `Sequel::Dataset#where` for more advanced querying.
+  #
+  # The underlying `Sequel::Dataset`'s `where` method is called with
+  # all of the arguments and the result is a new BogoHash containing
+  # only the items that match the query.
+  #
+  # This is the Bigger Hammer you can use to narrow a down to a subset
+  # of your data when groups are not enough.
+  #
+  # @return [BogoHash]
+  def where(*cond, **kwcond, &block)
+    new_dataset = @dataset.where(*cond, **kwcond, &block)
+    desc = ["SQL:#{new_dataset.sql}"]
+    return self.class.new(@dbs_klass, new_dataset, desc)
+  end
+  #
+  # Helpers
+  #
+  # Calls the underling `Sequel::Database#transaction` methods with
+  # all arguments.
+  #
+  # Convenience method.
+  def transaction(*args, **kwargs, &block) =
+    @dbs_klass.transaction(*args, **kwargs, &block)
+end

data/lib/internal/dbstruct_base.rb ADDED Viewed

@@ -0,0 +1,144 @@
+class DBStruct
+  # Returns the numeric Row ID that is used as the primary key for
+  # this row in both the database and any {DBStruct::BogoHash}
+  # instances that may contain it.
+  attr_reader :rowid
+  # Creates a new instance of class, creates the corresponding
+  # database row and initializes the fields.  This only works if the
+  # class is a subclass of `DBStruct`; `DBStruct` itself cannot be
+  # instantiated.
+  #
+  # If keyword arguments are given, they must correspond to the names
+  # of the fields and have values of the correct type or nil. Omitted
+  # arguments are equivalent to nil.
+  #
+  # The keyword argument `_id:` is intended for internal use only and
+  # should not be used.
+  def initialize(_id: nil,      # Internal use only!
+                 **kwargs)
+    check("Attempted to instantiate abstract class DBStruct.") {
+      self.class < DBStruct
+    }
+    @rowid = nil
+    # Case 1: existing row
+    if _id
+      check("Using '_id' with other arguments!") { kwargs.empty? }
+      @rowid = _id
+      check("Row '#{_id}' does not exist!", MissingRowError) { present? }
+      return
+    end
+    @rowid = dataset().insert({})
+    set_fields(**kwargs)
+  end
+  private
+  def dataset = self.class.dataset
+  def columns = self.class.columns
+  def check_field(name, value)
+    fld = self.class.fields_dict[name]
+    check("Unknown field name '#{name}'", FieldError) {
+      fld
+    }
+    check("Invalid field type: expecting #{fld.type}, got #{value.class}",
+          TypeError
+         ) {
+      value == nil || value.class == fld.type ||
+        (value == false && fld.type == TrueClass)
+    }
+    check("Underlying row-id (#{@rowid}) is not in the database.",
+          MissingRowError) { !deleted? }
+  end
+  public
+  # Test if the database row associated with `self` still exists.
+  # Inverse of `deleted?`.
+  def present? = !deleted?
+  # Test if the database row associated with `self` no longer exists.
+  # Inverse of `present?`
+  def deleted? = dataset().where(_id:@rowid).empty?
+  # Sets the value of the field named by `field` to the given value.
+  # `field` must be one of the declared fields and value must have the
+  # declared class.
+  def get_field(name)
+    check_field(name, nil)
+    return dataset[_id: @rowid][name]
+  end
+  # Retrieve the value of the field named by symbol `field`.  Raises
+  # an exception if `field` is not one of the declared fields.
+  def set_field(name, value)
+    check_field(name, value)
+    dataset()
+      .where(_id: @rowid)
+      .update({name => value})
+    return value
+  end
+  # Set zero or more fields at once.  Keywords must be the names of
+  # defined fields.
+  #
+  # The update is enclosed in an transaction.
+  def set_fields(**kwargs)
+    self.class.transaction {
+      kwargs.each{|k, v| set_field(k, v)}
+    }
+    return self
+  end
+  # Struct-like and hash-like
+  # Return the contents as an array of pairs of key and value
+  def to_a = self.columns.map{|key| [key, get_field(key)] }
+  # Return the contents as a hash
+  def to_h = to_a.to_h
+  # Equivalent to `get_field`
+  def [](field) = get_field(field)
+  # Equivalent to `set_field`
+  def []=(field, value)
+    return set_field(field, value)
+  end
+  # Equality
+  # Test for equality.  Instances are equal if and only if they refer
+  # to the same database row and (as implied) are of the same class.
+  def eql?(other) = self.class == other.class && @rowid == other.rowid
+  alias == eql?
+  # Return a hash; here because we've also overridden {.eql?}
+  def hash = [self.class, @rowid].hash
+  # Etc
+  # Return a human-friendly description.
+  def inspect
+    max_line = 60
+    values = to_h.map{|k,v| "#{k}: #{v.inspect}"}.join(", ")
+    values = values[0..max_line] + "..." if values.size > max_line
+    return "#{self.class}.new(#{values})"
+  end
+  alias to_s inspect
+end