borsh 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f889d5e7f96680cfdb852425c23b8053c0c2b9b6c783e8cc2ba5929821091712
-  data.tar.gz: 9fb32d11e1f054a12aa752bf33ee94ff109ca5dae8c0555e28c41bd7c6217201
+  metadata.gz: fcc938b4a07232e5c9b0cb6c770c45cd1eb71224f5436f137cb5854744324d06
+  data.tar.gz: 3da887c2ae7d8465c63d77b36a383a64f7c0b659e854d22b66ce630af232d5e5
 SHA512:
-  metadata.gz: e5321fc35e88b65794c7c22670667713f036b0b5a5a6217d72af8142179bc91fa15ef1ba079b22bc07098f81cb9f2c3eea040239723b2a63e10a2ba5dd7eb180
-  data.tar.gz: bb3dcf4db0c101e30450eaee3333745e5ba35829c35f17ee1c778fbde9a79b70673a977a61b7abf630195a1c893c90ed064dd239891d361b958e1ade0cf5557c
+  metadata.gz: 320fa7c330c3a6eb92e827bfa452df8111e3c9a5c2c6950bb6ca12630d4d4969f507f9ee27bdaabe41f64979e1c0587e1d55ad7c534917b34bf32124ad6d472f
+  data.tar.gz: a50d8f139195bb973a8b598f08f9b22daf6dc4d30220262259c3ef178d0dad234916eafce7bfa787122298c26ec7cdd37e81fa11d2f177c7ab25cbb3678d722e

data/CHANGES.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.2.0 - 2025-05-12
+### Changed
+- Bump the Ruby requirement to Ruby 3.0+
+- Serialize symbols as strings
+### Added
+- Implement `Borsh::Sizer`
+### Fixed
+- Force UTF-8 encoding on deserialized strings (#1)
+
 ## 0.1.0 - 2025-01-11
 
 ## 0.0.0 - 2025-01-09

data/README.md

@@ -1,16 +1,28 @@
 # Borsh for Ruby
 
 [![License](https://img.shields.io/badge/license-Public%20Domain-blue.svg)](https://unlicense.org)
-[![Compatibility](https://img.shields.io/badge/ruby-2.6%2B-blue)](https://rubygems.org/gems/borsh)
+[![Compatibility](https://img.shields.io/badge/ruby-3.0%2B-blue)](https://rubyreferences.github.io/rubychanges/3.0.html)
 [![Package](https://img.shields.io/gem/v/borsh)](https://rubygems.org/gems/borsh)
+[![Documentation](https://img.shields.io/badge/rubydoc-latest-blue)](https://rubydoc.info/gems/borsh)
 
-A Ruby library for the [Borsh] binary serialization format.
+**Borsh.rb** is a [Ruby] library for encoding and decoding data in the
+[Borsh] binary serialization format designed for security-critical
+projects where consistency, safety, and performance matter.
 
-[Borsh]: https://borsh.io
+## ✨ Features
+
+- 100% pure Ruby with zero dependencies and no bloat.
+- Implements the full Borsh specification with support for every type.
+- Supports both in-memory buffers and I/O streams for serialization.
+- Provides a simple and intuitive API for reading and writing data.
+- Provides a convenient buffer interface layered on top of `StringIO`.
+- Supports customizable serialization using the `#to_borsh` protocol.
+- Plays nice with others: entirely contained in the `Borsh` module.
+- 100% free and unencumbered public domain software.
 
 ## 🛠️ Prerequisites
 
-- [Ruby](https://ruby-lang.org) 2.6+
+- [Ruby] 3.0+
 
 ## ⬇️ Installation
 
@@ -28,20 +40,6 @@ gem install borsh
 require 'borsh'
 ```
 
-### Writing to an output stream
-
-```ruby
-$stdout.extend(Borsh::Writable)
-$stdout.write_string("Hello, world!")
-```
-
-### Reading from an input stream
-
-```ruby
-$stdin.extend(Borsh::Readable)
-p $stdin.read_string
-```
-
 ### Writing to an in-memory buffer
 
 ```ruby
@@ -50,6 +48,8 @@ serialized_data = Borsh::Buffer.open do |buf|
   buf.write_bool(true)
   buf.write_u8(255)
   buf.write_i32(-12345)
+  buf.write_u128(2**100)
+  buf.write_i128(-2**100)
   buf.write_f64(3.14159)
   buf.write_string("Hello, Borsh!")
 
@@ -58,6 +58,12 @@ serialized_data = Borsh::Buffer.open do |buf|
 
   # Dynamic-sized array (array with a length prefix):
   buf.write_vector(['a', 'b', 'c'])
+
+  # Set of integers:
+  buf.write_set(Set.new([1, 2, 3]))
+
+  # Map with string keys and integer values:
+  buf.write_map({a: 1, b: 2})
 end
 ```
 
@@ -69,17 +75,39 @@ Borsh::Buffer.new(serialized_data) do |buf|
   bool_val = buf.read_bool             # => true
   u8_val = buf.read_u8                 # => 255
   i32_val = buf.read_i32               # => -12345
+  u128_val = buf.read_u128             # => 2**100
+  i128_val = buf.read_i128             # => -2**100
   f64_val = buf.read_f64               # => 3.14159
   string_val = buf.read_string         # => "Hello, Borsh!"
 
   # Fixed-size array:
-  array = buf.read_array(:i32, 3)      # => [1, 2, 3]
+  array = buf.read_array(:i64, 3)      # => [1, 2, 3]
 
   # Dynamic-sized array (array with a length prefix):
   vector = buf.read_vector(:string)    # => ['a', 'b', 'c']
+
+  # Set of integers:
+  set = buf.read_set(:i64)             # => Set.new([1, 2, 3])
+
+  # Map with string keys and integer values:
+  map = buf.read_map(:string, :i64)    # => {'a' => 1, 'b' => 2}
 end
 ```
 
+### Writing to any output stream
+
+```ruby
+$stdout.extend(Borsh::Writable)
+$stdout.write_string("Hello, world!")
+```
+
+### Reading from any input stream
+
+```ruby
+$stdin.extend(Borsh::Readable)
+puts $stdin.read_string
+```
+
 ## 📚 Reference
 
 | Informal Type | `Borsh::Writable` | `Borsh::Readable` |
@@ -101,12 +129,12 @@ end
 | string | `write_string(x)` | `read_string()` |
 | array | `write_array(x)` | `read_array(element_type, count)` |
 | vector | `write_vector(x)` | `read_vector(element_type)` |
-| struct | `write_struct(x)` | `read_struct(struct_class)` |
-| enum | `write_enum(x)` | `read_enum(variants)` |
-| map/hash | `write_map(x)` | `read_map(key_type, value_type)` |
 | set | `write_set(x)` | `read_set(element_type)` |
+| map/hash | `write_map(x)` | `read_map(key_type, value_type)` |
 | option | `write_option(x)` | `read_option(element_type)` |
-| result | `write_result(x)` | `read_result(ok_type, err_type)` |
+| result | `write_result([ok, value])` | `read_result(ok_type, err_type)` |
+| enum | `write_enum([ordinal, value])` | `read_enum(variants)` |
+| struct | `write_struct(x)` | `read_struct(struct_class)` |
 
 ## 👨‍💻 Development
 
@@ -114,9 +142,13 @@ end
 git clone https://github.com/dryruby/borsh.rb.git
 ```
 
-- - -
+---
 
-[![Share on Twitter](https://img.shields.io/badge/share%20on-twitter-03A9F4?logo=twitter)](https://twitter.com/share?url=https://github.com/dryruby/borsh.rb&text=Borsh+for+Ruby)
+[![Share on X](https://img.shields.io/badge/share%20on-x-03A9F4?logo=x)](https://x.com/intent/post?url=https://github.com/dryruby/borsh.rb&text=Borsh+for+Ruby)
 [![Share on Reddit](https://img.shields.io/badge/share%20on-reddit-red?logo=reddit)](https://reddit.com/submit?url=https://github.com/dryruby/borsh.rb&title=Borsh+for+Ruby)
-[![Share on Hacker News](https://img.shields.io/badge/share%20on-hacker%20news-orange?logo=ycombinator)](https://news.ycombinator.com/submitlink?u=https://github.com/dryruby/borsh.rb&t=Borsh+for+Ruby)
-[![Share on Facebook](https://img.shields.io/badge/share%20on-facebook-1976D2?logo=facebook)](https://www.facebook.com/sharer/sharer.php?u=https://github.com/dryruby/borsh.rb)
+[![Share on Hacker News](https://img.shields.io/badge/share%20on-hn-orange?logo=ycombinator)](https://news.ycombinator.com/submitlink?u=https://github.com/dryruby/borsh.rb&t=Borsh+for+Ruby)
+[![Share on Facebook](https://img.shields.io/badge/share%20on-fb-1976D2?logo=facebook)](https://www.facebook.com/sharer/sharer.php?u=https://github.com/dryruby/borsh.rb)
+[![Share on LinkedIn](https://img.shields.io/badge/share%20on-linkedin-3949AB?logo=linkedin)](https://www.linkedin.com/sharing/share-offsite/?url=https://github.com/dryruby/borsh.rb)
+
+[Borsh]: https://borsh.io
+[Ruby]: https://ruby-lang.org

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/lib/borsh/buffer.rb

@@ -7,11 +7,11 @@ require_relative 'writable'
 ##
 # A buffer for reading and writing Borsh data.
 class Borsh::Buffer
-  include Borsh::Readable
   include Borsh::Writable
+  include Borsh::Readable
 
   ##
-  # @param [String, nil] data
+  # @param [String, #to_s, nil] data
   # @yield [buffer]
   # @yieldreturn [Object]
   # @return [String]
@@ -22,12 +22,12 @@ class Borsh::Buffer
   end
 
   ##
-  # @param [String] data
+  # @param [String, #to_s] data
   # @yield [buffer]
   # @yieldreturn [void]
   # @return [void]
   def initialize(data = '', &block)
-    @buffer = StringIO.new(data)
+    @buffer = StringIO.new(data.to_s)
     @buffer.binmode
     block.call(self) if block_given?
   end
@@ -45,16 +45,21 @@ class Borsh::Buffer
   # Returns `true` if the buffer is closed.
   #
   # @return [Boolean]
-  def closed?
-    @buffer.closed?
-  end
+  def closed?; @buffer.closed?; end
 
   ##
   # Closes the buffer.
   #
   # @return [void]
-  def close;
-    @buffer.close
+  def close; @buffer.close; end
+
+  ##
+  # Writes data to the buffer.
+  #
+  # @param [String, #to_s] data
+  # @return [Integer]
+  def write(data)
+    @buffer.write(data.to_s)
   end
 
   ##
@@ -65,13 +70,4 @@ class Borsh::Buffer
   def read(length)
     @buffer.read(length.to_i)
   end
-
-  ##
-  # Writes data to the buffer.
-  #
-  # @param [String, #to_s] data
-  # @return [Integer]
-  def write(data)
-    @buffer.write(data.to_s)
-  end
 end # Borsh::Buffer

data/lib/borsh/readable.rb

@@ -105,7 +105,7 @@ module Borsh::Readable
   end
 
   def read_string
-    self.read(self.read_u32)
+    self.read(self.read_u32).force_encoding('UTF-8')
   end
 
   def read_array(element_type, count)
@@ -118,19 +118,13 @@ module Borsh::Readable
   end
   alias_method :read_vec, :read_vector
 
-  def read_struct(struct_class)
-    values = struct_class.members.map { |member|
-      type = struct_class::MEMBER_TYPES.fetch(member)
-      self.read_object(type)
-    }
-    struct_class.new(*values)
-  end
-
-  def read_enum(variants)
-    ordinal = self.read_u8
-    type = variants.fetch(ordinal)
-    value = self.read_object(type)
-    [ordinal, value]
+  def read_set(element_type)
+    count = self.read_u32
+    result = Set.new
+    count.times do
+      result << self.read_object(element_type)
+    end
+    result
   end
 
   def read_map(key_type, value_type)
@@ -145,15 +139,6 @@ module Borsh::Readable
   end
   alias_method :read_hash, :read_map
 
-  def read_set(element_type)
-    count = self.read_u32
-    result = Set.new
-    count.times do
-      result << self.read_object(element_type)
-    end
-    result
-  end
-
   def read_option(element_type)
     if self.read_bool
       self.read_object(element_type)
@@ -162,10 +147,25 @@ module Borsh::Readable
     end
   end
 
-  def read_result(ok_type, err_type)
+  def read_result(ok_type, err_type = ok_type)
     ok = self.read_bool
     type = ok ? ok_type : err_type
     value = self.read_object(type)
     [ok, value]
   end
+
+  def read_enum(variants)
+    ordinal = self.read_u8
+    type = variants.fetch(ordinal)
+    value = self.read_object(type)
+    [ordinal, value]
+  end
+
+  def read_struct(struct_class)
+    values = struct_class.members.map { |member|
+      type = struct_class::MEMBER_TYPES.fetch(member)
+      self.read_object(type)
+    }
+    struct_class.new(*values)
+  end
 end # Borsh::Readable

data/lib/borsh/sizer.rb

@@ -0,0 +1,67 @@
+# This is free and unencumbered software released into the public domain.
+
+require_relative 'writable'
+
+##
+# A byte counter for writing Borsh data.
+class Borsh::Sizer
+  include Borsh::Writable
+
+  ##
+  # @yield [buffer]
+  # @yieldparam [Borsh::Sizer] buffer
+  # @yieldreturn [void]
+  # @return [Integer]
+  def self.open(&block)
+    buffer = self.new(&block)
+    buffer.close
+    buffer.bytesize
+  end
+
+  ##
+  # @yield [buffer]
+  # @yieldparam [Borsh::Sizer] buffer
+  # @yieldreturn [void]
+  # @return [void]
+  def initialize(&block)
+    self.reset!
+    block.call(self) if block_given?
+  end
+
+  ##
+  # Returns the buffer size in bytes.
+  #
+  # @return [Integer]
+  attr_reader :bytesize
+  alias_method :size, :bytesize
+
+  ##
+  # Returns `true` if the buffer is closed.
+  #
+  # @return [Boolean]
+  def closed?; @closed; end
+
+  ##
+  # Closes the buffer.
+  #
+  # @return [void]
+  def close; @closed ||= true; end
+
+  ##
+  # Writes data to the buffer.
+  #
+  # @param [String, #to_s] data
+  # @return [Integer]
+  def write(data)
+    raise IOError, "closed stream" if self.closed?
+    @bytesize += data.to_s.bytesize
+  end
+
+  ##
+  # @return [Integer]
+  def reset!
+    result = @bytesize
+    @bytesize, @closed = 0, false
+    result
+  end
+end # Borsh::Sizer

data/lib/borsh/writable.rb

@@ -11,6 +11,7 @@ module Borsh::Writable
       when TrueClass  then self.write_bool(x)
       when Integer    then self.write_i64(x)
       when Float      then self.write_f64(x)
+      when Symbol     then self.write_string(x.to_s)
       when String     then self.write_string(x)
       when Array      then self.write_vector(x)
       when Hash       then self.write_map(x)
@@ -100,23 +101,17 @@ module Borsh::Writable
   end
   alias_method :write_vec, :write_vector
 
-  def write_struct(x)
-    raise "value must be a Struct" unless x.is_a?(Struct)
-
-    x.members.each do |k|
-      self.write_object(x[k])
+  def write_set(x)
+    self.write_u32(x.size)
+    keys = case x
+      when Array then x
+      when Hash then x.keys
+      when Set then x.to_a
+      else raise "unsupported type: #{x.class}"
     end
-  end
-
-  def write_enum(x)
-    # An enum should be represented as `[ordinal, value]`:
-    unless x.is_a?(Array) && x.size == 2 && x[0].is_a?(Integer)
-      raise "enum must be [ordinal, value]"
+    keys.sort.each do |k|
+      self.write_object(k)
     end
-
-    ordinal, value = x
-    self.write_u8(ordinal)
-    self.write_object(value)
   end
 
   def write_map(x)
@@ -137,19 +132,6 @@ module Borsh::Writable
   end
   alias_method :write_hash, :write_map
 
-  def write_set(x)
-    self.write_u32(x.size)
-    keys = case x
-      when Array then x
-      when Hash then x.keys
-      when Set then x.to_a
-      else raise "unsupported type: #{x.class}"
-    end
-    keys.sort.each do |k|
-      self.write_object(k)
-    end
-  end
-
   def write_option(x)
     if !x.nil?
       self.write_u8(1)
@@ -169,4 +151,23 @@ module Borsh::Writable
     self.write_u8(ok ? 1 : 0)
     self.write_object(value)
   end
+
+  def write_enum(x)
+    # An enum should be represented as `[ordinal, value]`:
+    unless x.is_a?(Array) && x.size == 2 && x[0].is_a?(Integer)
+      raise "enum must be [ordinal, value]"
+    end
+
+    ordinal, value = x
+    self.write_u8(ordinal)
+    self.write_object(value)
+  end
+
+  def write_struct(x)
+    raise "value must be a Struct" unless x.is_a?(Struct)
+
+    x.members.each do |k|
+      self.write_object(x[k])
+    end
+  end
 end # Borsh::Writable

data/lib/borsh.rb

@@ -4,4 +4,5 @@ module Borsh; end
 
 require_relative 'borsh/buffer'
 require_relative 'borsh/readable'
+require_relative 'borsh/sizer'
 require_relative 'borsh/writable'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: borsh
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Arto Bendiken
 bindir: bin
 cert_chain: []
-date: 2025-01-11 00:00:00.000000000 Z
+date: 2025-05-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.12'
+        version: '3.13'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.12'
+        version: '3.13'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -37,7 +37,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
-description: A Ruby library for the Borsh binary serialization format.
+description: A Ruby library for encoding and decoding data in the Borsh binary serialization
+  format designed for security-critical projects.
 email: arto@bendiken.net
 executables: []
 extensions: []
@@ -51,6 +52,7 @@ files:
 - lib/borsh.rb
 - lib/borsh/buffer.rb
 - lib/borsh/readable.rb
+- lib/borsh/sizer.rb
 - lib/borsh/writable.rb
 homepage: https://github.com/dryruby/borsh.rb
 licenses:
@@ -58,7 +60,7 @@ licenses:
 metadata:
   bug_tracker_uri: https://github.com/dryruby/borsh.rb/issues
   changelog_uri: https://github.com/dryruby/borsh.rb/blob/master/CHANGES.md
-  documentation_uri: https://github.com/dryruby/borsh.rb/blob/master/README.md
+  documentation_uri: https://rubydoc.info/gems/borsh
   homepage_uri: https://github.com/dryruby/borsh.rb
   source_code_uri: https://github.com/dryruby/borsh.rb
 rdoc_options: []
@@ -68,14 +70,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.6'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.3
 specification_version: 4
 summary: Borsh for Ruby
 test_files: []