gdbmish 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 670c5f7ee70fdebc740db0ac5c14a0615d80288e5049d1456ffc65b33677d639
+  data.tar.gz: 707565737415a2dcb4f4ff4293d124f27e6824ad10b59751e829ab6575006cfe
+SHA512:
+  metadata.gz: d449655a416a969c09b2c8d55cf198d6177ff9b621d946aac1b54c6ec91e40fb37823c98f8af07168aea77d37b3b0d4508ff68ab5dd04b64fcb1feca1b26fffd
+  data.tar.gz: 817c74ee802e6376b4e921a692f7ef747ed98bc19009d132571f4d9b48ca9317f848b749d2a2fb7d8a1e94b4dda13f5353eff9acffca5eda8944dfb8b973faad

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 3.0

data/.yardopts

@@ -0,0 +1,4 @@
+--protected
+--embed-mixins
+--markup markdown
+--files LICENSE.txt,CHANGELOG.md,README.md

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-09-18
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Robert Schulze
+
+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 @@
+# GDBMish
+
+Create and read GDBM dump ASCII files.
+
+Citing [gdbm](https://git.gnu.org.ua/gdbm.git/tree/NOTE-WARNING):
+> Gdbm files have never been `portable' between different operating systems,
+> system architectures, or potentially even different compilers.  Differences
+> in byte order, the size of file offsets, and even structure packing make
+> gdbm files non-portable.
+>
+> Therefore, if you intend to send your database to somebody over the wire,
+> please dump it into a portable format using gdbm_dump and send the resulting
+> file instead. The receiving party will be able to recreate the database from
+> the dump using the gdbm_load command.
+
+GDBMish does that by reimplementing the `gdbm_dump` ASCII format without compiling against `gdbm`
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add gdbmish
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install gdbmish
+```
+
+## Usage
+
+```ruby
+require 'gdbmish'
+
+# Create a dump into a StringIO and read it back
+io = StringIO.new
+dumper = Gdbmish::Dump::Ascii.new(file: "test.db", uid: "1000", user: "ziggy", gid: "1000", group: "staff", mode: 0o640)
+dumper.dump(io) do |dump|
+    dump.push("some_key", "Some Value")
+    dump.push("otherKey", "Other\nValue")
+end
+
+io.rewind
+reader = Gdbmish::Read::Ascii.new(io, load_meta: :count)
+reader.data.to_h  # => {"some_key"=>"Some Value", "otherKey"=>"Other\nValue"}
+reader.meta.count # => 2
+reader.meta.file  # => "test.db"
+reader.meta.uid   # => "1000"
+
+# Dumping a Hash
+
+data = {"key1" => "value", "key2" => "value2"}
+
+# Get dump as String
+string = Gdbmish::Dump.ascii(data)
+
+# Write directly into File (or any other IO)
+File.open("my_db.dump", "w") do |file|
+  Gdbmish::Dump.ascii(data, file)
+end
+
+# Provide an original filename
+Gdbmish::Dump.ascii(data, file: "my.db")
+
+# Provide an original filename and file permissions
+Gdbmish::Dump.ascii(data, file: "my.db", uid: "1000", gid: "1000", mode: 0o600)
+
+# Iterate over a data source and push onto an IO
+fileoptions = {file: "my.db", uid: "1000", user: "ziggy", gid: "1000", group: "staff", mode: 0o600}
+File.open("my.dump", "w") do |file|
+  Gdbmish::Dump::Ascii.new(**fileoptions).dump(io) do |dump|
+    MyDataSource.each do |key, value|
+      dump.push(key.to_s, value.to_s)
+    end
+  end
+end
+
+# Read from a file
+
+file = File.open("my.dump")
+# The file is read lazily, don't close it before you're done reading from it
+reader = Gdbmish::Read::Ascii.new(file)
+
+# get meta data
+reader.meta.file # => "my.db"
+
+# either iterate over data:
+reader.data do |key, value|
+  puts "#{key.inspect} => #{value.inspect}"
+end
+
+# or use the Iterator to transform into Hash
+reader.data.to_h
+
+file.close
+```
+
+### Shenanigans
+
+Reading data from a dump file is a lazy one way street. Once data is read, it's read. You can't seek or peak.  
+However, you can rewind the `IO` and start over.
+
+```ruby
+File.open("my.dump") do |io|
+  reader = Gdbmish::Read::Ascii.new(io)
+  reader.data.to_h # => {"key1"=>"value1", "key2"=>"value2"}
+  reader.data.to_h # => {}
+
+  io.rewind
+  reader.data.to_h # => {"key1"=>"value1", "key2"=>"value2"}
+
+  reader.data.first # => ["key1", "value1"]
+  reader.data.first # => ["key2", "value2"]
+  io.rewind
+  reader.data.first # => ["key1", "value1"]
+end
+```
+
+## 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 the created tag, 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/fnordfih/gdbmish.rb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/fnordfih/gdbmish.rb/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the GDBMish project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/fnordfih/gdbmish.rb/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "standard/rake"
+require "yard"
+
+YARD::Rake::YardocTask.new
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: %i[spec standard]

data/lib/gdbmish/dump.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module Gdbmish
+  # Wrapper for different dump formats, providing various shortcut methods.
+  # Currently, there is only `Ascii` mode.
+  #
+  # Ascii mode optionally dumps file information such as filename, owner, mode.
+  # See {Gdbmish::Dump::Ascii#new} on how they are used.
+  module Dump
+    # Dumping GDBM data as ASCII (aka default) format.
+    class Ascii
+      # Appends and counts {#push}ed data as ASCII dump format onto the given `io`.
+      #
+      # @note
+      #   Users should not use this class directly, as it only represents the
+      #   data part of an dump, without header and footer.
+      #
+      #   An instance of it gets yielded when using `Ascii#dump(io) { |appender| }`
+      # @see Ascii#dump Gdbmish::Dump::Ascii#dump(io) { |appender| }
+      class Appender
+        # @return [Integer] The number of key/value pairs pushed
+        attr_reader :count
+
+        # @param io [IO] The IO to append to
+        def initialize(io)
+          @io = io
+          @count = 0
+        end
+
+        # Push a *key*, *value* pair onto the dump
+        # @param key [String] The key
+        # @param value [String] The value
+        def push(key, value)
+          @count += 1
+          @io << dump_datum(key)
+          @io << dump_datum(value)
+          nil
+        end
+
+        private
+
+        def dump_datum(datum)
+          result = sprintf("#:len=%d\n", datum.bytesize)
+          encoded = Base64.strict_encode64(datum)
+          if encoded.size > GDBM_MAX_DUMP_LINE_LEN
+            encoded.gsub!(/(.{#{GDBM_MAX_DUMP_LINE_LEN}})/o, "\\1\n")
+          end
+          result << encoded << "\n"
+        end
+      end
+
+      # GDBM does not split base64 strings at 60 encoded characters (as defined by RFC 2045).
+      #
+      # See `_GDBM_MAX_DUMP_LINE_LEN` in [gdbmdefs.h](https://git.gnu.org.ua/gdbm.git/tree/src/gdbmdefs.h)
+      GDBM_MAX_DUMP_LINE_LEN = 76
+
+      # Builds a new Ascii format dumper
+      #
+      # Dumping file information is optional.
+      #
+      # - *uid*, *user*, *gid*, *group* and *mode* will only be used when *file* is given
+      # - *user* will only be used when *uid* is given
+      # - *group* will only be used when *gid* is given
+      #
+      # @example
+      #   fileoptions = {file: "test.db", uid: "1000", user: "ziggy", gid: "1000", group: "staff", mode: 0o600}
+      #   File.open("test.dump", "w") do |file|
+      #     Gdbmish::Dump::Ascii.new(**fileoptions).dump(file) do |appender|
+      #       MyDataSource.each do |key, value|
+      #         appender.push(key.to_s, value.to_s)
+      #       end
+      #     end
+      #   end
+      def initialize(file: nil, uid: nil, user: nil, gid: nil, group: nil, mode: nil)
+        @file = file
+        @uid = uid
+        @user = user
+        @gid = gid
+        @group = group
+        @mode = mode
+      end
+
+      # @overload dump(io)
+      #   Dump only the header and footer
+      #   @param io [IO] The IO to dump to
+      #   @return [IO] The IO written to
+      # @overload dump(io, data)
+      #   Dump *data* to *io*
+      #   @param io [IO] The IO to dump to
+      #   @param data [#each_pair] The data to dump
+      #   @return [IO] The IO written to
+      # @overload dump(io, &block)
+      #   Yield an {Appender} to call {Appender#push push} on.
+      #   @param io [IO] The IO to dump to
+      #   @yieldparam appender [Appender] The appender to push data onto the dump
+      #   @return [IO] The IO written to
+      # @overload dump(io, data, &block)
+      #   Dump *data* to *io* and then yield an {Appender} to call {Appender#push push} on.
+      #   @param io [IO] The IO to dump to
+      #   @param data [#each_pair] The data to dump
+      #   @yieldparam appender [Appender] The appender to push data onto the dump
+      #   @return [IO] The IO written to
+      def dump(io, data = nil, &block)
+        appender = Appender.new(io)
+
+        dump_header!(io)
+        data&.each_pair do |k, v|
+          appender.push(k.to_s, v.to_s)
+        end
+        yield appender if block
+        dump_footer!(io, appender.count)
+
+        io
+      end
+
+      private
+
+      def dump_header!(io)
+        io.printf("# GDBM dump file created by GDBMish version %s on %s\n", Gdbmish::VERSION, Time.now.rfc2822)
+        io.puts("#:version=1.1")
+
+        if @file
+          io.printf("#:file=%s\n", @file)
+          l = []
+
+          if @uid
+            l << sprintf("uid=%d", @uid)
+            l << sprintf("user=%s", @user) if @user
+          end
+
+          if @gid
+            l << sprintf("gid=%d", @gid)
+            l << sprintf("group=%s", @group) if @group
+          end
+
+          l << sprintf("mode=%03o", @mode & 0o777) if @mode
+
+          unless l.empty?
+            io << "#:"
+            io.puts(l.join(","))
+          end
+        end
+
+        io.puts("#:format=standard")
+        io.puts("# End of header")
+      end
+
+      def dump_footer!(io, count)
+        io.printf("#:count=%d\n", count)
+        io.puts("# End of data")
+      end
+    end
+
+    # Dump *data* as standard ASCII format.
+    # When an *io* is given, the dump will be written to it. Otherwise, a new `String` will be returned.
+    # See {Dump::Ascii#initialize} for *fileoptions*.
+    # See {Dump::Ascii#dump} for *data* and *block* behaviour.
+    #
+    # @param data [#each_pair,nil] The data to dump
+    # @param io [IO,nil] The IO to dump to
+    # @param fileoptions [Hash] Options for the dump file
+    # @yield [appender] The appender to push data onto the dump
+    # @return [String] The dump as a string when no *io* is given
+    # @return [IO] The IO written to when *io* is given
+    #
+    # @example Dumping simple Hash into an IO
+    #   File.open("test.dump", "w") do |file|
+    #     Gdbmish::Dump.ascii({some: "data"}, file)
+    #   end
+    #
+    # @example Dumping into a String
+    #   string_dump = Gdbmish::Dump.ascii({some: "data"})
+    #
+    # @example Dumping into IO with file information and block
+    #   Gdbmish::Dump.ascii(io, file: "test.db", uid: "1000", user: "ziggy", gid: "1000", group: "staff", mode: 0o600) do |appender|
+    #     MyData.each do |object|
+    #       appender.push(object.id, object.dump)
+    #     end
+    #   end
+    def self.ascii(data = nil, io = nil, **fileoptions, &block)
+      if io.nil?
+        io = StringIO.new
+        to_string = true
+      end
+
+      io = Ascii.new(**fileoptions).dump(io, data, &block)
+      to_string ? io.string : io
+    end
+  end
+end

data/lib/gdbmish/read.rb

@@ -0,0 +1,225 @@
+require "base64"
+
+module Gdbmish
+  # Wrapper for reading GDBM dump files. Currently, only Ascii (aka standard) format is supported.
+  #
+  # See {Gdbmish::Read::Ascii} for the main high level interface.
+  module Read
+    # Main abstraction to read an GDBM Ascii dump file (aka "standard format")
+    #
+    # @example
+    #   File.open("path/to/file.dump") do |io|
+    #     file = Gdbmish::Read::Ascii.new(io)
+    #
+    #     file.data do |key, value|
+    #       puts "#{key.inspect} => #{value.inspect}"
+    #     end
+    #     pp file.meta
+    #
+    #     # Note: your `io`'s file pointer posistion has changed.
+    #     io.pos # => 317
+    #   end
+    #
+    #   # Produces:
+    #   # "some_key" => "Some Value"
+    #   # "otherKey" => "Other\nValue"
+    #   #<Gdbmish::Read::AsciiMetaData @count=nil, @file="test.db", @gid="1000", @group="staff", @mode=384, @uid="1000", @user="ziggy", @version="1.1">
+    class Ascii
+      # Create a new Ascii reader.
+      #
+      # *load_meta* can be:
+      #
+      # - `true` (default) load meta data, but skip `count` for preformance reasons.
+      # - `false` skip loading meta data.
+      # - `:count` load meta data, including `count`.
+      #
+      # @param io [IO] The IO to read from. Assumed to point to the beginning of the GDBM dump.
+      # @param load_meta [Boolean, Symbol] Whether to load meta data.
+      # @param encoding [String,Encoding] The encoding to use for key/value pairs.
+      def initialize(io, load_meta: true, encoding: Encoding::UTF_8)
+        @io = io
+        @load_meta = load_meta
+        @encoding = encoding
+      end
+
+      # Returns an Enumerator over key/value pairs.
+      # Given a block, it will yield each key/value pair, which is a shortcut for `#data.each`.
+      #
+      # @note This will consume the IO, so you can only iterate once. After that, you need to rewind the IO.
+      #
+      # Depending on the size of the dataset, you might want to read everything into an Array or Hash:
+      # ```
+      # Ascii.new(io1).data.to_a # => [["some_key", "Some Value"], ["otherKey", "Other\nValue"]]
+      # Ascii.new(io2).data.to_h # => {"some_key" => "Some Value", "otherKey" => "Other\nValue"}
+      # ```
+      #
+      # @yield [key, value] for each key/value pair
+      # @yieldparam key [String] the key
+      # @yieldparam value [String] the value
+      # @return [AsciiDataIterator] if no block is given
+      def data(&block)
+        load_meta!
+        @data_iterator ||= AsciiDataIterator.new(@io, encoding: @encoding)
+        block ? @data_iterator.each(&block) : @data_iterator
+      end
+
+      # Parses for meta data, depending on the *load_meta* value in {#initialize}
+      # @return [AsciiMetaData,nil] the meta data if loaded
+      def meta
+        load_meta!
+      end
+
+      private
+
+      def load_meta!
+        return unless @load_meta
+
+        @meta ||= AsciiMetaData.parse(@io, ignore_count: @load_meta != :count)
+      end
+    end
+
+    # Header and footer meta data from a GDBM Ascii dump file.
+    class AsciiMetaData
+      attr_reader :version, :file, :uid, :user, :gid, :group, :mode, :count
+
+      def initialize(version: nil, file: nil, uid: nil, user: nil, gid: nil, group: nil, mode: nil, count: nil)
+        @version = version
+        @file = file
+        @uid = uid
+        @user = user
+        @gid = gid
+        @group = group
+        @mode = mode
+        @count = count
+      end
+
+      # Parse given IO for meta data.
+      # Reads from +io+ until a `"# End of header"` line is found (enhancing its `pos`).
+      # By default, ignores reading the `count` (indecating the amount of datasets in the file)
+      # because it is written at the end of the file.
+      def self.parse(io, ignore_count: true)
+        version = nil
+        file = nil
+        uid = nil
+        user = nil
+        gid = nil
+        group = nil
+        mode = nil
+        count = nil
+
+        while (line = io.gets(chomp: true))
+          break if line == "# End of header"
+
+          next unless line.start_with?("#:")
+
+          line[2..].split(",") do |e|
+            k, v = e.split("=")
+            case k
+            when "version"
+              version = v
+            when "file"
+              file = v
+            when "uid"
+              uid = v
+            when "user"
+              user = v
+            when "gid"
+              gid = v
+            when "group"
+              group = v
+            when "mode"
+              mode = v.to_i(8)
+            end
+          end
+        end
+
+        count = read_count(io) unless ignore_count
+
+        new(version: version, file: file, uid: uid, user: user, gid: gid, group: group, mode: mode, count: count)
+      end
+
+      def self.read_count(io)
+        count = nil
+        end_of_header_pos = begin
+          io.pos
+        rescue
+          # ignore error, this io does not support pos
+          nil
+        end
+
+        return if end_of_header_pos.nil?
+
+        while (line = io.gets(chomp: true))
+          next unless line.start_with?("#:count")
+          count = line.split("=")[1].to_i
+        end
+        io.pos = end_of_header_pos
+
+        count
+      end
+
+      private_class_method :read_count
+    end
+
+    # Iterates over lines, skipping comments, joining wrapped lines.
+    # Lines are alternating key or value in encoded form.
+    # @note Users should not need to use this directly, but rather {Gdbmish::Read::Ascii#data}.
+    class AsciiLineIterator
+      include Enumerable
+
+      # Comment lines start with '#'
+      COMMENT_BYTE = "#".ord
+
+      def initialize(io)
+        @io = io
+      end
+
+      # Iterates over encoded lines, skipping comments, joining wrapped lines.
+      # @yield [String] The still encoded, joined line
+      def each
+        while (line = @io.gets(chomp: true))
+          next if line.bytes.first == COMMENT_BYTE
+
+          data = line.dup
+
+          until next_is_comment?
+            data << @io.gets(chomp: true)
+          end
+
+          yield data
+        end
+      end
+
+      private
+
+      def next_is_comment?
+        next_byte = @io.readbyte
+        return false if next_byte.nil?
+
+        @io.seek(-1, IO::SEEK_CUR)
+        next_byte == COMMENT_BYTE
+      end
+    end
+
+    # Iterates over data and returns decoded key/value pairs.
+    # @note Users should not need to use this directly, but rather {Gdbmish::Read::Ascii#data}.
+    class AsciiDataIterator
+      include Enumerable
+
+      def initialize(io, encoding: Encoding::UTF_8)
+        @iterator = AsciiLineIterator.new(io)
+        @encoding = encoding
+      end
+
+      # Iterates over key/value pairs, decoding them.
+      # @yield [String,String] The decoded key and value
+      def each
+        @iterator.each_slice(2) do |k, v|
+          k = Base64.decode64(k).force_encoding(@encoding)
+          v = Base64.decode64(v).force_encoding(@encoding) unless v.nil?
+          yield [k, v]
+        end
+      end
+    end
+  end
+end

data/lib/gdbmish/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Gdbmish
+  VERSION = "0.1.0"
+end

data/lib/gdbmish.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "time"
+require "base64"
+require "stringio"
+
+module Gdbmish
+end
+
+require_relative "gdbmish/version"
+require_relative "gdbmish/read"
+require_relative "gdbmish/dump"

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: gdbmish
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Robert Schulze
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-09-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: stringio
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: time
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: GDBM database files are not portable between different architectures.
+  This gem reimplements the `gdbm_dump` and `gdbm_load` ASCII format in pure Ruby
+  to allow for easy creation and reading of portable GDBM dump files.
+email:
+- robert@dotless.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".standard.yml"
+- ".yardopts"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/gdbmish.rb
+- lib/gdbmish/dump.rb
+- lib/gdbmish/read.rb
+- lib/gdbmish/version.rb
+- test.dump
+homepage: https://github.com/fnordfish/gdbmish.rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/fnordfish/gdbmish.rb
+  source_code_uri: https://github.com/fnordfish/gdbmish.rb
+  changelog_uri: https://github.com/fnordfish/gdbmish.rb/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.17
+signing_key:
+specification_version: 4
+summary: Create and read GDBM dump files.
+test_files: []