dbmlite3 1.0.a1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 546ca0010f91757ca1346cd87ca9f2846318e65123668363239b61e8f1f5bbdd
+  data.tar.gz: 5500f44eec01f68da64ed8e8d8ec73a1325ffafeab274a2ae00604a68e16ae61
+SHA512:
+  metadata.gz: 45e67ef18cff8f3f17610e888a7153bb83d83438334c8ce0d204fdda7c599926e5ec210e09cb67bf909dbfa829fb17046b46a540e5373960b049bccb77526cf1
+  data.tar.gz: 7c113a41818d9bdea1aec2b8e3d5fe1f54c4c134e8fa777a6e19a6c0f8546c326f6ef901caddc4b65985df1b50a89d809db6b32196eb157034e619fd9cebade5

data/.yardopts

@@ -0,0 +1,3 @@
+--markup markdown
+--readme README.md
+lib/*.rb

data/DBMLite3.gemspec

@@ -0,0 +1,39 @@
+
+# Skeleton gemspec
+
+Gem::Specification.new do |s|
+  s.name        = 'dbmlite3'
+  s.version     = '1.0.a1'
+  s.date        = '2022-02-21'
+  s.summary     = "A DBM-style key-value store using SQLite3"
+  s.description = <<-EOF
+    Lite3::DBM is an object that behaves like a Ruby Hash but stores
+    its data in a SQLite3 database table.  It is a drop-in replacement
+    for DBM.
+
+    Values are optionally serialized with YAML or Marshal, allowing
+    (almost) any Ruby type to be stored.  In addition, there is
+    rudimentary support for transactions with emphasis on simplicity
+    and safety.
+EOF
+  s.authors     = ["Chris Reuter"]
+  s.email       = 'chris@isplitonyourgrave.com'
+
+  # 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       = ["README.md", "LICENSE.txt", "DBMLite3.gemspec",
+                   "Rakefile", ".yardopts"] +
+                  Dir.glob('doc/**/*') +
+                  Dir.glob('{spec,lib}/*.rb')
+
+  s.required_ruby_version = '>= 2.7.0'
+  s.requirements << "sqlite3, the usual devtools"
+
+  s.add_runtime_dependency "sqlite3", '~> 1.4'
+  
+  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/dbmlite3-ruby'
+  s.license     = 'MIT'
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Chris Reuter
+
+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,137 @@
+# Simple DBM-style key-value database using SQLite3
+
+## Description
+
+`dbmlite3` is a simple key-value store built on top of SQLite3 that
+provides a Hash-like interface.  It is a drop-in replacement for `DBM`
+or `YAML::DBM` that uses SQLite3 to do the underlying storage.
+
+## Why?
+
+Because DBM is really simple and SQLite3 is solid, reliable,
+ubiquitous, and file-format-compatible across all platforms. This gem
+gives you the best of both worlds.
+
+
+## Synopsis
+
+```ruby
+require 'dbmlite3'
+
+# Open a table in a database
+settings = Lite3::DBM.new("config.sqlite3", "settings")
+
+# You use it like a hash
+settings["speed"] = 88
+settings["date"] = Date.new(1955, 11, 5)  # Normal Ruby values are allowed
+settings["power_threshold"] = 2.2
+
+puts settings['power_threshold']
+
+settings.each{|k,v| puts "setting: #{k} = #{v}" }
+
+# But you also have transactions
+settings.transaction{
+  settings["speed"] = settings["speed"] * 2
+}
+
+# You can open other tables in the same database if you want, as above
+# or with a block
+Lite3::DBM.open("config.sqlite3", "stats") { |stats|
+  stats["max"] = 42
+
+  # You can even open multiple handles to the same table if you need to
+  Lite3::DBM.open("config.sqlite3", "stats") { |stats2|
+    stats2["max"] += 1
+  }
+
+  puts "stats=#{stats["max"]}"
+}
+
+settings.close
+```
+
+Complete documentation is available in the accompanying rdoc.
+
+## Installation
+
+`dbmlite3` is available as a gem:
+
+    $ [sudo] gem install dbmlite3
+
+Alternately, you can fetch the source code from GitLab and build it yourself:
+
+    $ git clone https://gitlab.com/suetanvil/dbmlite3
+    $ cd dbmlite3
+    $ rake
+
+Obviously, it depends on the gem `sqlite3`.
+
+## Quirks and Hints
+
+### Remember that a `DBM` is a (potentially) shared file
+
+It is important to keep in mind that while `Lite3::DBM` objects
+look like Hashes, they are accessing files on disk that other
+processes could modify at any time.
+
+For example, an innocuous-looking expression like 
+
+    db['foo'] = db['foo'] + 1
+
+or its shorter equivalent
+
+    db['foo'] += 1
+
+contains a race condition. If (e.g.) two copies of this script are
+running at the same time, it is possible for both to perform the read
+before one of them writes, losing the others' result.
+
+There are two ways to deal with this.  You can wrap the
+read-modify-write cycle in a transaction:
+
+    db.transaction { db['foo'] += 1 }
+
+Or, of course, you could just design your script or program so that
+only one program accesses the table at a time.
+
+
+### Transactions and performance
+
+If you need to do a large number of accesses in a short amount of
+time (e.g. loading data from a file), it is significantly faster to
+do these in batches in one or more transactions.
+
+### Forking safely
+
+It is a documented limitation of SQLite3 that database objects
+cannot be carried across a process fork.  Either the parent or the
+child process will keep the open handle and the other one must
+forget it completely.
+
+For this reason, if you need both the parent and child process to
+be able to use `Lite3::DBM` after a `fork`, you must first call
+`Lite3::SQL.close_all`.  Not only will this make it safe but it
+also lets the child and parent use the same `Lite3::DBM` objects.
+
+### `Lite3::DBM` objects act like file handles but are not
+
+While it is generally safe to treat `Lite3::DBM` as a wrapper
+around file handle (i.e. `open` and `close` work as expected), you
+should be aware that this is not precisely the way things
+actually work.  Instead, the gem maintains a pool of database
+handles, one per file, and associates them with `Lite3::DBM`
+instances as needed.  This is necessary for transactions to work
+correctly.
+
+See the reference doc for `Lite3::SQL` for more details.
+
+Mostly, you don't need to worry about this but certain types of
+bugs could behave in unexpected ways and knowing this may help you
+make sense of them.
+
+
+
+
+
+

data/Rakefile

@@ -0,0 +1,29 @@
+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) do |t|
+  t.files = ['lib/*.rb']
+end
+
+task :gem do
+  `gem build dbmlite3`
+end
+
+task :clean do
+  gems = Dir.glob("dbmlite3-*.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 => [:doc, :test, :gem]