db-struct 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2cafa77dd62d6126979c75a2453805e5ae07a9537e664e73da4fb1530159ace5
+  data.tar.gz: 7e1b5397788a38864f6d07c8c14ba9cd75da0a00bd33f83c2d1e239442ba794f
+SHA512:
+  metadata.gz: aba9d9fad1a29bebf9b9d538d8b723254558e34648d4280f7d397aae930c3b4f3c4c438d07cc75cfc30c9b70de5a009a091a59e70d92548561bef0837b7f352f
+  data.tar.gz: ed5362fe8a6b51a32c0957c526b4a8d67b9cc21f04c4ef7c78fc35ee3ef14c08dafe64787df09a45711714efbf57b4bf9363c0fdc6a9608fea430a861ee00860

data/README.md

@@ -0,0 +1,125 @@
+# Persistant Sets of Structured Data
+
+`db-struct` is a Ruby gem that provides class `DBStruct`, a class that
+is similar to Ruby's built-in `Struct` class but stores its data in a
+SQLite database.  In addition, each subclass also provides access to
+the database via an interface that closely mimics a Ruby Hash,
+including support for enumeration.
+
+It is currently at the "experimental toy" stage of development.
+
+## Installation
+
+Simply install it via `gem`:
+
+    gem install --prerelease db-struct
+
+Note that you will also need to install SQLite3 separately.  On stock
+Ruby, that's:
+
+    gem install sqlite3
+
+while with JRuby, it's:
+
+    gem install jdbc-sqlite3
+
+It uses [Sequel](https://sequel.jeremyevans.net/) to do the heavy
+lifting.  This is installed as a dependency, but you'll need to know
+how to open a database with it.
+
+
+## Overview
+
+Let's start with a simple example, a table of books.  The first thing
+we need to do is create a database connection:
+
+    DB = Sequel.sqlite("books.sqlite3")
+
+We can then define the structure and the underlying table:
+
+    Book = DBStruct.with(DB, :books) do
+      field :title,     String
+      field :author,    String
+      field :date,      Time
+      field :edition,   Integer
+    end
+
+`Book` is now a subclass of `DBStruct`; creating it will also create a
+table named `:books` if it doesn't exist.
+
+We can create an instance of `Book` like this:
+
+    b1 = Book.new(title:   "Diseases of the Dragon",
+                  author:  "Lady Sybil Ramkin",
+                  date:    Time.new(1989, 11, 1),
+                  edition: 1)
+
+The contents are immediately written to the database, but this object
+behaves more or less like a Ruby `Struct`:
+
+    puts b1.title
+    b1.author = "Lady Sybil Ramkin-Vimes"
+    puts b1.author
+
+Note that these are not part of a transaction.  If you need that (and
+you probably will), you can the `transaction` method:
+
+    Book.transaction {
+      puts b1.title
+      b1.author = "Lady Sybil Ramkin-Vimes"
+      puts b1.author
+    }
+
+This starts a transaction, evaluates the block and commits.  If there
+is an exception inside the block, the transaction is rolled back
+instead.  Transactions can be safely nested.  (`DBStruct#transaction`
+is simply a thin wrapper around `Sequel::Database#transaction`.)
+
+The class method `items` returns a `DBStruct::BogoHash`, which behaves
+like a Hash mapping numeric row IDs to corresponding `Book` objects:
+
+    puts Book.items[b1.rowid].title
+
+The usual enumeration operations are also available:
+
+    Book.items.values.each{|book|
+        puts "  #{book.title} by #{book.author}"
+    }
+
+    first_editions = Book.items
+      .select{|id, book| book.edition == 1}
+      .map{|id, _| id}
+
+You can also add a special field type called a `group`.  This can be
+used to subdivide the table:
+
+    Book = DBStruct.with(DB, :books) do
+      group :category,  String
+      field :title,     String
+      field :author,    String
+      field :date,      Time
+      field :edition,   Integer
+    end
+
+    b1 = Book.new(category:"non-fiction",
+                  title:   "Diseases of the Dragon",
+                  author:  "Lady Sybil Ramkin",
+                  date:    Time.new(1989, 11, 1),
+                  edition: 1)
+
+A `group` is just an ordinary field except that `Books.items` will
+filter by them:
+
+    non_fiction = Book.items("non-fiction")
+
+Multiple groups are allowed and `nil` can be used as a wildcard when
+selection them.
+
+Alternately, you can filter using a `Sequel` `where` clause:
+
+    dragon_books = Book.where(Sequel.like(:title, "%Dragon%"))
+
+but if you need that often, you may well be better off dealing with
+`Sequel` directly.
+
+

data/Rakefile

@@ -0,0 +1,35 @@
+# Starter Rakefile for a gem.
+#
+
+require 'rake'
+require 'rspec/core/rake_task'
+require 'yard'
+
+RSpec::Core::RakeTask.new(:test) do |t|
+  t.pattern = Dir.glob('spec/*_spec.rb')
+end
+
+YARD::Rake::YardocTask.new(:docs_via_yard)
+
+# Install dependencies
+task :install_deps do
+  sh "gem install -g"
+end
+
+task gem: [:docs_via_yard] do
+  sh "gem build db-struct.gemspec"
+end
+
+task :clean do
+  gems = Dir.glob("db-struct-*.gem")
+  rm gems if gems.size > 0
+  rm_rf "doc"
+end
+
+task :clobber => [:clean] do
+  rm_rf ".yardoc"
+end
+
+task :doc => :docs_via_yard
+
+task :default => [:docs_via_yard, :test, :gem]

data/db-struct.gemspec

@@ -0,0 +1,37 @@
+
+
+Gem::Specification.new do |s|
+  s.name        = "db-struct"
+  s.version     = '0.1.0'
+  s.date        = '2024-09-09'
+  s.summary     = "Persistant storage of sets of structured records."
+  s.description = <<-EOF
+    DBStruct is a class that, like Struct, provides a convenient way
+    to create subclasses with named fields that can be accessed via
+    the usual Ruby setters and getters.  Unlike Struct, their contents
+    are stored in a SQLite3 database.
+
+    In addition, each subclass also provides access to the database
+    via an interface that closely mimics a Ruby Hash, including
+    support for enumeration.
+EOF
+  s.authors     = ["Chris Reuter"]
+  s.email       = 'chris@remove-this-part.blit.ca'
+
+  # I'm just going to add everything so that if you've got the gem,
+  # you've also got the source distribution.  Yay! Open source!
+  s.files       =
+    Dir.glob('doc/**/*') +
+    `git ls-files`.split.reject {|f| f =~ /\.org$/}
+
+  s.required_ruby_version = '>= 3.0.0'
+  s.requirements << "Sequel"
+
+  s.add_runtime_dependency "sequel", '~> 5.76.0'
+
+  s.add_development_dependency "rspec", '~> 3.10', '>= 3.10.0'
+  s.add_development_dependency "yard", '~> 0.9.25', '>= 0.9.25'
+
+  s.homepage    = 'https://codeberg.org/suetanvil/db-struct'
+  s.license     = 'MIT'
+end