borsh 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f889d5e7f96680cfdb852425c23b8053c0c2b9b6c783e8cc2ba5929821091712
+  data.tar.gz: 9fb32d11e1f054a12aa752bf33ee94ff109ca5dae8c0555e28c41bd7c6217201
+SHA512:
+  metadata.gz: e5321fc35e88b65794c7c22670667713f036b0b5a5a6217d72af8142179bc91fa15ef1ba079b22bc07098f81cb9f2c3eea040239723b2a63e10a2ba5dd7eb180
+  data.tar.gz: bb3dcf4db0c101e30450eaee3333745e5ba35829c35f17ee1c778fbde9a79b70673a977a61b7abf630195a1c893c90ed064dd239891d361b958e1ade0cf5557c

data/AUTHORS

@@ -0,0 +1 @@
+* Arto Bendiken <arto@bendiken.net>

data/CHANGES.md

@@ -0,0 +1,10 @@
+# Changelog
+
+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.1.0 - 2025-01-11
+
+## 0.0.0 - 2025-01-09

data/README.md

@@ -0,0 +1,122 @@
+# 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)
+[![Package](https://img.shields.io/gem/v/borsh)](https://rubygems.org/gems/borsh)
+
+A Ruby library for the [Borsh] binary serialization format.
+
+[Borsh]: https://borsh.io
+
+## 🛠️ Prerequisites
+
+- [Ruby](https://ruby-lang.org) 2.6+
+
+## ⬇️ Installation
+
+### Installation via RubyGems
+
+```bash
+gem install borsh
+```
+
+## 👉 Examples
+
+### Importing the library
+
+```ruby
+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
+serialized_data = Borsh::Buffer.open do |buf|
+  # Primitive types:
+  buf.write_bool(true)
+  buf.write_u8(255)
+  buf.write_i32(-12345)
+  buf.write_f64(3.14159)
+  buf.write_string("Hello, Borsh!")
+
+  # Fixed-size array:
+  buf.write_array([1, 2, 3])
+
+  # Dynamic-sized array (array with a length prefix):
+  buf.write_vector(['a', 'b', 'c'])
+end
+```
+
+### Reading from an in-memory buffer
+
+```ruby
+Borsh::Buffer.new(serialized_data) do |buf|
+  # Primitive types:
+  bool_val = buf.read_bool             # => true
+  u8_val = buf.read_u8                 # => 255
+  i32_val = buf.read_i32               # => -12345
+  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]
+
+  # Dynamic-sized array (array with a length prefix):
+  vector = buf.read_vector(:string)    # => ['a', 'b', 'c']
+end
+```
+
+## 📚 Reference
+
+| Informal Type | `Borsh::Writable` | `Borsh::Readable` |
+| :------------ | :---------------- | :---------------- |
+| nil/unit | `write_unit()` | `read_unit()` |
+| boolean | `write_bool(x)` | `read_bool()` |
+| u8 integer | `write_u8(n)` | `read_u8()` |
+| u16 integer | `write_u16(n)` | `read_u16()` |
+| u32 integer | `write_u32(n)` | `read_u32()` |
+| u64 integer | `write_u64(n)` | `read_u64()` |
+| u128 integer | `write_u128(n)` | `read_u128()` |
+| i8 integer | `write_i8(n)` | `read_i8()` |
+| i16 integer | `write_i16(n)` | `read_i16()` |
+| i32 integer | `write_i32(n)` | `read_i32()` |
+| i64 integer | `write_i64(n)` | `read_i64()` |
+| i128 integer | `write_i128(n)` | `read_i128()` |
+| f32 float | `write_f32(f)` | `read_f32()` |
+| f64 float | `write_f64(f)` | `read_f64()` |
+| 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)` |
+| option | `write_option(x)` | `read_option(element_type)` |
+| result | `write_result(x)` | `read_result(ok_type, err_type)` |
+
+## 👨‍💻 Development
+
+```bash
+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 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)

data/UNLICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+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 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.
+
+For more information, please refer to <https://unlicense.org/>

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/borsh/buffer.rb

@@ -0,0 +1,77 @@
+# This is free and unencumbered software released into the public domain.
+
+require 'stringio'
+require_relative 'readable'
+require_relative 'writable'
+
+##
+# A buffer for reading and writing Borsh data.
+class Borsh::Buffer
+  include Borsh::Readable
+  include Borsh::Writable
+
+  ##
+  # @param [String, nil] data
+  # @yield [buffer]
+  # @yieldreturn [Object]
+  # @return [String]
+  def self.open(data = nil, &block)
+    buffer = self.new(data || '', &block)
+    buffer.close
+    buffer.data
+  end
+
+  ##
+  # @param [String] data
+  # @yield [buffer]
+  # @yieldreturn [void]
+  # @return [void]
+  def initialize(data = '', &block)
+    @buffer = StringIO.new(data)
+    @buffer.binmode
+    block.call(self) if block_given?
+  end
+
+  ##
+  # Returns the buffer data.
+  #
+  # @return [String]
+  def data
+    @buffer.string
+  end
+  alias_method :string, :data
+
+  ##
+  # Returns `true` if the buffer is closed.
+  #
+  # @return [Boolean]
+  def closed?
+    @buffer.closed?
+  end
+
+  ##
+  # Closes the buffer.
+  #
+  # @return [void]
+  def close;
+    @buffer.close
+  end
+
+  ##
+  # Reads the specified number of bytes from the buffer.
+  #
+  # @param [Integer, #to_i] length
+  # @return [String]
+  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

@@ -0,0 +1,171 @@
+# This is free and unencumbered software released into the public domain.
+
+require 'set'
+
+module Borsh::Readable
+  def read_object(type)
+    case type
+      when :nil     then self.read_unit
+      when :bool    then self.read_bool
+      when :u8      then self.read_u8
+      when :u16     then self.read_u16
+      when :u32     then self.read_u32
+      when :u64     then self.read_u64
+      when :u128    then self.read_u128
+      when :i8      then self.read_i8
+      when :i16     then self.read_i16
+      when :i32     then self.read_i32
+      when :i64     then self.read_i64
+      when :i128    then self.read_i128
+      when :f32     then self.read_f32
+      when :f64     then self.read_f64
+      when :string  then self.read_string
+      when Array
+        case type.first
+          when :array   then self.read_array(type[1], type[2])
+          when :vector  then self.read_vector(type[1])
+          when :map     then self.read_map(type[1], type[2])
+          when :set     then self.read_set(type[1])
+          when :option  then self.read_option(type[1])
+          when :result  then self.read_result(type[1], type[2])
+          else raise "unsupported array type specifier: #{type.inspect}"
+        end
+      when Class
+        raise "unsupported class type: #{type}" unless type < Struct
+        self.read_struct(type)
+      else raise "unsupported type specifier: #{type.inspect}"
+    end
+  end
+
+  def read_unit
+    nil
+  end
+  alias_method :read_nil, :read_unit
+
+  def read_bool
+    self.read_u8 == 1
+  end
+
+  def read_u8
+    self.read(1).unpack('C').first
+  end
+
+  def read_u16
+    self.read(2).unpack('v').first
+  end
+
+  def read_u32
+    self.read(4).unpack('V').first
+  end
+
+  def read_u64
+    self.read(8).unpack('Q<').first
+  end
+
+  def read_u128
+    # Read two 64-bit integers (little-endian):
+    lower = self.read_u64
+    upper = self.read_u64
+    # Combine into a 128-bit number:
+    (upper << 64) | lower
+  end
+
+  def read_i8
+    self.read(1).unpack('c').first
+  end
+
+  def read_i16
+    self.read(2).unpack('s').first
+  end
+
+  def read_i32
+    self.read(4).unpack('l<').first
+  end
+
+  def read_i64
+    self.read(8).unpack('q<').first
+  end
+
+  def read_i128
+    n = self.read_u128
+    # Handle two's complement for negative numbers:
+    if n >= (1 << 127)
+      n - (1 << 128)
+    else
+      n
+    end
+  end
+
+  def read_f32
+    self.read(4).unpack('e').first
+  end
+
+  def read_f64
+    self.read(8).unpack('E').first
+  end
+
+  def read_string
+    self.read(self.read_u32)
+  end
+
+  def read_array(element_type, count)
+    Array.new(count) { self.read_object(element_type) }
+  end
+
+  def read_vector(element_type)
+    count = self.read_u32
+    self.read_array(element_type, count)
+  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]
+  end
+
+  def read_map(key_type, value_type)
+    count = self.read_u32
+    result = {}
+    count.times do
+      key = self.read_object(key_type)
+      value = self.read_object(value_type)
+      result[key] = value
+    end
+    result
+  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)
+    else
+      nil
+    end
+  end
+
+  def read_result(ok_type, err_type)
+    ok = self.read_bool
+    type = ok ? ok_type : err_type
+    value = self.read_object(type)
+    [ok, value]
+  end
+end # Borsh::Readable

data/lib/borsh/writable.rb

@@ -0,0 +1,172 @@
+# This is free and unencumbered software released into the public domain.
+
+require 'set'
+
+module Borsh::Writable
+  def write_object(x)
+    x = x.to_borsh if x.respond_to?(:to_borsh)
+    case x
+      when NilClass   then self.write_unit()
+      when FalseClass then self.write_bool(x)
+      when TrueClass  then self.write_bool(x)
+      when Integer    then self.write_i64(x)
+      when Float      then self.write_f64(x)
+      when String     then self.write_string(x)
+      when Array      then self.write_vector(x)
+      when Hash       then self.write_map(x)
+      when Set        then self.write_set(x)
+      else raise "unsupported type: #{x.class}"
+    end
+  end
+
+  def write_unit()
+    # nothing to write
+  end
+  alias_method :write_nil, :write_unit
+
+  def write_bool(x)
+    self.write_u8(x ? 1 : 0)
+  end
+
+  def write_u8(n)
+    self.write([n].pack('C'))
+  end
+
+  def write_u16(n)
+    self.write([n].pack('v'))
+  end
+
+  def write_u32(n)
+    self.write([n].pack('V'))
+  end
+
+  def write_u64(n)
+    self.write([n].pack('Q<'))
+  end
+
+  def write_u128(n)
+    # Split 128-bit number into two 64-bit parts:
+    lower = n & ((1 << 64) - 1)
+    upper = (n >> 64) & ((1 << 64) - 1)
+    # Write the lower 64 bits first (little-endian):
+    self.write_u64(lower)
+    # Then write the upper 64 bits:
+    self.write_u64(upper)
+  end
+
+  def write_i8(n)
+    self.write([n].pack('c'))
+  end
+
+  def write_i16(n)
+    self.write([n].pack('s'))
+  end
+
+  def write_i32(n)
+    self.write([n].pack('l<'))
+  end
+
+  def write_i64(n)
+    self.write([n].pack('q<'))
+  end
+
+  def write_i128(n)
+    # Convert negative numbers to two's complement:
+    n = (1 << 128) + n if n < 0
+    # Use `#write_u128` to write the bits:
+    self.write_u128(n)
+  end
+
+  def write_f32(f)
+    self.write([f].pack('e'))
+  end
+
+  def write_f64(f)
+    self.write([f].pack('E'))
+  end
+
+  def write_string(x)
+    self.write_u32(x.bytesize)
+    self.write(x)
+  end
+
+  def write_array(x)
+    x.each { |e| self.write_object(e) }
+  end
+
+  def write_vector(x)
+    self.write_u32(x.size)
+    x.each { |e| self.write_object(e) }
+  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])
+    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]"
+    end
+
+    ordinal, value = x
+    self.write_u8(ordinal)
+    self.write_object(value)
+  end
+
+  def write_map(x)
+    self.write_u32(x.size)
+    case x
+      when Array
+        x.sort.each do |(k, v)|
+          self.write_object(k)
+          self.write_object(v)
+        end
+      when Hash
+        x.keys.sort.each do |k|
+          self.write_object(k)
+          self.write_object(x[k])
+        end
+      else raise "unsupported type: #{x.class}"
+    end
+  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)
+      self.write_object(x)
+    else
+      self.write_u8(0)
+    end
+  end
+
+  def write_result(x)
+    # A result should be represented as `[ok, value]`:
+    unless x.is_a?(Array) && x.size == 2
+      raise "result must be [ok, value]"
+    end
+
+    ok, value = x
+    self.write_u8(ok ? 1 : 0)
+    self.write_object(value)
+  end
+end # Borsh::Writable

data/lib/borsh.rb

@@ -0,0 +1,7 @@
+# This is free and unencumbered software released into the public domain.
+
+module Borsh; end
+
+require_relative 'borsh/buffer'
+require_relative 'borsh/readable'
+require_relative 'borsh/writable'

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: borsh
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Arto Bendiken
+bindir: bin
+cert_chain: []
+date: 2025-01-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: A Ruby library for the Borsh binary serialization format.
+email: arto@bendiken.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- AUTHORS
+- CHANGES.md
+- README.md
+- UNLICENSE
+- VERSION
+- lib/borsh.rb
+- lib/borsh/buffer.rb
+- lib/borsh/readable.rb
+- lib/borsh/writable.rb
+homepage: https://github.com/dryruby/borsh.rb
+licenses:
+- Unlicense
+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
+  homepage_uri: https://github.com/dryruby/borsh.rb
+  source_code_uri: https://github.com/dryruby/borsh.rb
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Borsh for Ruby
+test_files: []