README
¶
go-ruby-marshal/marshal
A pure-Go (CGO=0) implementation of Ruby's Marshal binary serialization
format — the wire format produced by Marshal.dump and consumed by
Marshal.load, version 4.8. Its byte output is verified equal to MRI Ruby's
(differential-tested against the reference interpreter, Ruby 4.0.5).
It is part of the go-ruby-* family of standalone front-end/runtime components
(alongside go-ruby-parser and
go-ruby-regexp) that
go-embedded-ruby builds on, but it has no
dependency on any interpreter: it works against its own small, typed value model
and can be bridged into one by converting values at the boundary.
Supported
- nil, true, false
- Integer — both the compact Fixnum form (
[-2³⁰, 2³⁰-1], matching MRI's marshal range) and arbitrary-precision Bignum - Float — the shortest round-tripping decimal, formatted exactly as MRI does
(
1.0→1,100.0→1e2,±inf,nan,-0) - Symbol — with the format's symbol table (repeated symbols become links)
- String — UTF-8, US-ASCII, and ASCII-8BIT (BINARY), plus other named encodings
- Array, Hash (including a default value,
Hash.new(d)) - Object links — shared mutable objects are encoded once and thereafter as
links, so cyclic structures (
a = []; a << a) round-trip exactly as in MRI
Usage
import "github.com/go-ruby-marshal/marshal"
// Encode → Ruby Marshal bytes (Marshal.dump compatible)
b := marshal.Dump(&marshal.Array{Elems: []marshal.Value{
marshal.NewInt(1), marshal.NewString("hi"), marshal.Bool(true),
}})
// Decode ← bytes produced by Ruby's Marshal.dump
v, err := marshal.Load(b)
License
BSD-3-Clause.
WebAssembly
Being pure Go (CGO=0), this library also compiles to WebAssembly — both
GOOS=js GOARCH=wasm (browser / Node.js) and GOOS=wasip1 GOARCH=wasm (WASI).
CI builds both targets on every push, alongside the six 64-bit native/qemu arches.
GOOS=js GOARCH=wasm go build ./... # browser / Node
GOOS=wasip1 GOARCH=wasm go build ./... # WASI (wasmtime, wasmer, wasmedge, …)
Documentation
¶
Overview ¶
Package marshal is a pure-Go (CGO=0) implementation of Ruby's Marshal binary serialization format — the wire format produced by Ruby's Marshal.dump and consumed by Marshal.load, version 4.8.
It operates on its own small, typed value model (Value) rather than on any particular interpreter's objects, so it is reusable on its own and can be bridged into an embedded Ruby (e.g. go-embedded-ruby) by converting that interpreter's values to and from this package's.
Supported types: nil, true, false, Integer (Fixnum and arbitrary-precision Bignum), Float, Symbol, String (UTF-8 / US-ASCII / ASCII-8BIT encodings), Array, and Hash (including a default value). The format's symbol table and object-link table are implemented, so repeated symbols, shared mutable objects, and cyclic structures round-trip exactly as in MRI.
The byte output is verified equal to MRI Ruby's Marshal.dump (differential tests against the reference interpreter).
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrShort = errors.New("marshal: unexpected end of input")
ErrShort is reported when the input ends in the middle of a value.
Functions ¶
Types ¶
type Encoding ¶
type Encoding int
Encoding identifies a Ruby String's encoding for marshalling purposes.
const ( // UTF8 is the default; marshalled as the instance variable E => true. UTF8 Encoding = iota // USASCII is marshalled as E => false. USASCII // ASCII8BIT (BINARY) is marshalled as a bare String with no encoding ivar. ASCII8BIT // Named is any other encoding, marshalled as encoding => <Name>. Named )
type Hash ¶
Hash is a Ruby Hash. Keys and Vals are parallel slices preserving insertion order (as Ruby hashes do). Default, when non-nil, is the hash's default value (Hash.new(default)); it is marshalled with the TYPE_HASH_DEF tag.
type Int ¶
Int is a Ruby Integer of any magnitude. Dump emits the compact Fixnum form for values in [-2**30, 2**30-1] (matching MRI's marshal Fixnum range) and the Bignum form otherwise.
type Str ¶
Str is a Ruby String: raw bytes plus an encoding. The zero value is an empty UTF-8 string. For a Named encoding, Name holds the encoding's name.
type Value ¶
type Value interface{ RubyClass() string }
Value is a Ruby value in the subset this package serializes. The concrete types are Nil, Bool, Int, Float, Symbol, *Str, *Array, and *Hash; RubyClass reports the name of the corresponding Ruby class.
The composite, mutable types (*Str, *Array, *Hash) are pointers so that identity is observable: the same pointer appearing more than once in a structure is encoded once and thereafter as an object link, exactly as MRI does, which is also what makes cyclic structures representable.
Source Files