borsh 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '026901148b33570032ecf66ae88dd74df8b510d88846916d84145886ba481547'
-  data.tar.gz: f52074d33c2f1d1c36cb59c1df329cc904b8269a483eefd51a74689d0cac7ce9
+  metadata.gz: f889d5e7f96680cfdb852425c23b8053c0c2b9b6c783e8cc2ba5929821091712
+  data.tar.gz: 9fb32d11e1f054a12aa752bf33ee94ff109ca5dae8c0555e28c41bd7c6217201
 SHA512:
-  metadata.gz: b65f1ce556d96681c15fcb83101b5dcccdd262702c9b44d24c306f1ee60be7188d164e4a497acd78ea69ca6991e18fff936a311c82a61789ba2aa88dfddbee71
-  data.tar.gz: 5818449160d9c19ac06231f738f6fe641001be1c7995c29a97294d8dc2c753a9094272063265006354770db845e2c80f5e6bd93795104890e1e5e2570c5d4bfa
+  metadata.gz: e5321fc35e88b65794c7c22670667713f036b0b5a5a6217d72af8142179bc91fa15ef1ba079b22bc07098f81cb9f2c3eea040239723b2a63e10a2ba5dd7eb180
+  data.tar.gz: bb3dcf4db0c101e30450eaee3333745e5ba35829c35f17ee1c778fbde9a79b70673a977a61b7abf630195a1c893c90ed064dd239891d361b958e1ade0cf5557c

data/CHANGES.md

@@ -5,4 +5,6 @@ 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

@@ -28,15 +28,95 @@ 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
+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/artob/borsh.rb.git
+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/artob/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/artob/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/artob/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/artob/borsh.rb)
+[![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/VERSION

@@ -1 +1 @@
-0.0.0
+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

@@ -1,3 +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

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: borsh
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors:
 - Arto Bendiken
 bindir: bin
 cert_chain: []
-date: 2025-01-09 00:00:00.000000000 Z
+date: 2025-01-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -49,15 +49,18 @@ files:
 - UNLICENSE
 - VERSION
 - lib/borsh.rb
-homepage: https://github.com/artob/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/artob/borsh.rb/issues
-  changelog_uri: https://github.com/artob/borsh.rb/blob/master/CHANGES.md
-  documentation_uri: https://github.com/artob/borsh.rb/blob/master/README.md
-  homepage_uri: https://github.com/artob/borsh.rb
-  source_code_uri: https://github.com/artob/borsh.rb
+  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