messagepack 1.0.0

data/docs/_pages/streaming.adoc

@@ -0,0 +1,97 @@
+---
+title: Streaming
+parent: Core topics
+nav_order: 7
+---
+
+[[streaming]]
+= Streaming unpacking
+
+== Purpose
+
+The streaming unpacker allows incremental parsing of MessagePack data as it
+becomes available.
+
+== References
+
+* link:../guides/io-streaming[IO streaming guide] - Working with streams
+* link:../references/api[API reference] - Unpacker class documentation
+
+== Concepts
+
+=== Feeding data incrementally
+
+[source,ruby]
+----
+unpacker = Messagepack::Unpacker.new
+unpacker.feed("\x81")       # Feed partial data
+unpacker.feed("\xA3")       # Feed more
+unpacker.feed("foo")        # Feed final part
+obj = unpacker.read         # => {"foo"=>nil}
+----
+
+Where,
+
+* `Unpacker.new` creates a new unpacker instance
+* `feed(data)` appends data to the buffer
+* `read` returns one complete object or `nil` if more data is needed
+
+=== Streaming from IO
+
+[source,ruby]
+----
+unpacker = Messagepack::Unpacker.new(io)
+obj = unpacker.read         # Reads from IO as needed
+----
+
+Where,
+
+* `Unpacker.new(io)` creates an unpacker attached to an IO
+* The unpacker automatically reads from the IO when needed
+* Use `full_unpack` to read a single object and reset
+
+=== Iterating over multiple objects
+
+[source,ruby]
+----
+unpacker = Messagepack::Unpacker.new
+unpacker.feed(data1)
+unpacker.feed(data2)
+unpacker.feed_each { |obj| process(obj) }
+----
+
+Where,
+
+* `feed_each` yields each complete object as it's parsed
+* Useful for processing multiple objects from a stream
+
+== Examples
+
+.Streaming unpacking from network
+====
+[source,ruby]
+----
+require 'socket'
+
+# Simulate receiving data in chunks
+unpacker = Messagepack::Unpacker.new
+
+chunks = ["\x81\xA3", "foo", "\xA5", "world"]
+
+chunks.each do |chunk|
+  unpacker.feed(chunk)
+  obj = unpacker.read
+  if obj
+    puts "Received: #{obj.inspect}"
+  else
+    puts "Waiting for more data..."
+  end
+end
+
+# Output:
+# Waiting for more data...
+# Waiting for more data...
+# Waiting for more data...
+# Received: {"foo"=>"world"}
+----
+====

data/docs/_pages/symbol-extension.adoc

@@ -0,0 +1,69 @@
+---
+title: Symbol extension
+parent: Core topics
+nav_order: 5
+---
+
+[[symbol-extension]]
+= Symbol extension
+
+== Purpose
+
+The symbol extension (type 0) provides efficient serialization of Ruby symbols.
+
+== References
+
+* link:../references/extensions[Extension types reference] - Symbol extension documentation
+
+== Concepts
+
+=== Registering symbol type
+
+[source,ruby]
+----
+factory.register_type(0, Symbol)
+----
+
+Where,
+
+* `0` is the type ID for symbols
+* The extension uses `to_sym` and `to_s` for packing/unpacking
+
+=== Symbol serialization
+
+[source,ruby]
+----
+factory.register_type(0, Symbol)
+binary = factory.pack(:hello_symbol)
+result = factory.unpack(binary) # => :hello_symbol
+----
+
+Where,
+
+* Symbols are serialized as their string representation
+* Deserialization converts the string back to a symbol
+* This is more efficient than serializing as strings
+
+== Examples
+
+.Symbol serialization in data structures
+====
+[source,ruby]
+----
+factory = Messagepack::Factory.new
+factory.register_type(0, Symbol)
+
+data = {
+  status: :active,
+  priority: :high,
+  tags: [:important, :urgent]
+}
+
+binary = factory.pack(data)
+result = factory.unpack(binary)
+# => {:status=>:active, :priority=>:high, :tags=>[:important, :urgent]}
+----
+====
+
+NOTE: The symbol extension is not registered by default. You must register it
+explicitly if you want to preserve symbols when serializing.

data/docs/_pages/timestamp-extension.adoc

@@ -0,0 +1,88 @@
+---
+title: Timestamp extension
+parent: Core topics
+nav_order: 4
+---
+
+[[timestamp-extension]]
+= Timestamp extension
+
+== Purpose
+
+The timestamp extension (type -1) provides nanosecond precision time handling
+for Time objects.
+
+== References
+
+* link:../references/extensions[Extension types reference] - Timestamp specification
+* link:../references/format[Format specification] - MessagePack timestamp format
+
+== Concepts
+
+=== Timestamp formats
+
+.MessagePack automatically selects the appropriate format
+====
+[source]
+----
+Timestamp32  - 4 bytes (seconds only, 32-bit)
+              Used when: nanoseconds == 0 and
+                         seconds fit in 32 bits
+
+Timestamp64  - 8 bytes (seconds + nanoseconds)
+              Used when: nanoseconds != 0 and
+                         timestamp fits in 64 bits
+
+Timestamp96 - 12 bytes (seconds + nanoseconds, 96-bit)
+              Used when: timestamp requires 96 bits
+----
+====
+
+=== Using timestamp with Time
+
+[source,ruby]
+----
+factory.register_type(-1, Time,
+  packer: Messagepack::Time::Packer,
+  unpacker: Messagepack::Time::Unpacker
+)
+----
+
+Where,
+
+* `-1` is the reserved type ID for timestamps
+* `Messagepack::Time::Packer` handles serialization with nanosecond precision
+* `Messagepack::Time::Unpacker` handles deserialization
+
+== Examples
+
+.Timestamp serialization examples
+====
+[source,ruby]
+----
+factory = Messagepack::Factory.new
+factory.register_type(-1, Time,
+  packer: Messagepack::Time::Packer,
+  unpacker: Messagepack::Time::Unpacker
+)
+
+# Current time with nanosecond precision
+now = Time.now
+binary = factory.pack(now)
+restored = factory.unpack(binary)
+puts restored.tv_nsec # Nanoseconds preserved
+
+# Historical date
+time = Time.utc(2020, 1, 1, 12, 30, 45)
+binary = factory.pack(time)
+puts binary.size # => 6 (fixext4 format)
+
+# Future date with nanoseconds
+future = Time.utc(2100, 6, 15, 0, 0, 0, 123456789)
+binary = factory.pack(future)
+puts binary.size # => 15 (ext8 with timestamp96)
+----
+====
+
+NOTE: The default factory automatically includes the timestamp extension for Time
+objects. You don't need to register it unless you create a custom factory.

data/docs/_references/api.adoc

@@ -0,0 +1,360 @@
+---
+title: API reference
+nav_order: 1
+---
+
+== Purpose
+
+Complete API reference for the MessagePack Ruby library.
+
+== Module: Messagepack
+
+=== pack(value, io = nil)
+
+Serialize a Ruby object to MessagePack binary format.
+
+[source,ruby]
+----
+Messagepack.pack(value) => binary_string
+Messagepack.pack(value, io) => nil
+----
+
+* `value` - The Ruby object to serialize
+* `io` - Optional IO object to write to
+* Returns - Binary string if no IO, nil if writing to IO
+
+[source,ruby]
+----
+binary = Messagepack.pack({hello: "world"})
+File.open("data.msgpack", "wb") { |f| Messagepack.pack(data, f) }
+----
+
+=== unpack(data, options = {})
+
+Deserialize MessagePack binary to a Ruby object.
+
+[source,ruby]
+----
+Messagepack.unpack(data) => object
+Messagepack.unpack(io) => object
+----
+
+* `data` - Binary string or IO object
+* `options` - Hash of options:
+  ** `:symbolize_keys` - Convert hash keys to symbols (default: false)
+* Returns - The deserialized Ruby object
+
+[source,ruby]
+----
+obj = Messagepack.unpack("\x81\xA5hello\xA5world")
+obj = Messagepack.unpack(file)
+obj = Messagepack.unpack(data, symbolize_keys: true)
+----
+
+=== load(data, options = {})
+
+Alias for `unpack`.
+
+=== dump(value, io = nil)
+
+Alias for `pack`.
+
+== Class: Messagepack::Factory
+
+=== new()
+
+Create a new factory instance.
+
+[source,ruby]
+----
+factory = Messagepack::Factory.new
+----
+
+=== register_type(type_id, class, packer:, unpacker:, recursive: false)
+
+Register a custom extension type.
+
+[source,ruby]
+----
+factory.register_type(0x01, MyClass,
+  packer: :to_msgpack_ext,
+  unpacker: :from_msgpack_ext
+)
+
+factory.register_type(0x02, MyContainer,
+  packer: ->(obj, pk) { pk.write(obj.to_h) },
+  unpacker: ->(up) { MyContainer.from_hash(up.read) },
+  recursive: true
+)
+----
+
+* `type_id` - Integer from -128 to 127
+* `class` - Ruby class to register
+* `packer` - Symbol, method, or proc for serialization
+* `unpacker` - Symbol, method, or proc for deserialization
+* `recursive` - Enable recursive packing (default: false)
+
+=== packer()
+
+Create a new packer instance.
+
+[source,ruby]
+----
+packer = factory.packer
+----
+
+=== unpacker()
+
+Create a new unpacker instance.
+
+[source,ruby]
+----
+unpacker = factory.unpacker
+----
+
+=== pack(value, io = nil)
+
+Pack a value using this factory.
+
+[source,ruby]
+----
+binary = factory.pack(value)
+factory.pack(value, io)
+----
+
+=== unpack(data, options = {})
+
+Unpack data using this factory.
+
+[source,ruby]
+----
+obj = factory.unpack(data)
+----
+
+=== pool(size = 4)
+
+Create a thread-safe pool.
+
+[source,ruby]
+----
+pool = factory.pool(10)
+data = pool.pack(object)
+obj = pool.unpack(binary)
+----
+
+=== freeze()
+
+Freeze the factory for thread safety.
+
+[source,ruby]
+----
+factory.freeze
+----
+
+== Class: Messagepack::Packer
+
+=== write(value)
+
+Write a value to the buffer.
+
+[source,ruby]
+----
+packer.write(nil)
+packer.write(42)
+packer.write("hello")
+packer.write([1, 2, 3])
+packer.write({a: 1})
+----
+
+=== to_s
+
+Get the packed binary data.
+
+[source,ruby]
+----
+binary = packer.to_s
+----
+
+=== full_pack
+
+Alias for `to_s`.
+
+=== write_array_header(size)
+
+Write an array header for streaming.
+
+[source,ruby]
+----
+packer.write_array_header(3)
+packer.write(1)
+packer.write(2)
+packer.write(3)
+----
+
+=== write_map_header(size)
+
+Write a map header for streaming.
+
+[source,ruby]
+----
+packer.write_map_header(2)
+packer.write("key1")
+packer.write("value1")
+packer.write("key2")
+packer.write("value2")
+----
+
+== Class: Messagepack::Unpacker
+
+=== new(io = nil, options = {})
+
+Create a new unpacker.
+
+[source,ruby]
+----
+unpacker = Messagepack::Unpacker.new
+unpacker = Messagepack::Unpacker.new(io)
+unpacker = Messagepack::Unpacker.new(symbolize_keys: true)
+----
+
+=== feed(data)
+
+Feed data to the buffer.
+
+[source,ruby]
+----
+unpacker.feed(partial_data)
+unpacker.feed(more_data)
+----
+
+=== read
+
+Read one complete object.
+
+[source,ruby]
+----
+obj = unpacker.read
+# Returns nil if more data needed
+----
+
+=== read_map_header
+
+Read map header and return size.
+
+[source,ruby]
+----
+size = unpacker.read_map_header
+----
+
+=== read_array_header
+
+Read array header and return size.
+
+[source,ruby]
+----
+size = unpacker.read_array_header
+----
+
+=== skip
+
+Skip one complete object.
+
+[source,ruby]
+----
+unpacker.skip
+----
+
+=== feed_each {|obj| ...}
+
+Iterate over objects in the buffer.
+
+[source,ruby]
+----
+unpacker.feed_each(data) do |obj|
+  process(obj)
+end
+----
+
+=== full_unpack
+
+Read one object and reset.
+
+[source,ruby]
+----
+obj = unpacker.full_unpack(data)
+----
+
+== Class: Messagepack::BinaryBuffer
+
+=== new(io = nil)
+
+Create a new buffer.
+
+[source,ruby]
+----
+buffer = Messagepack::BinaryBuffer.new
+buffer = Messagepack::BinaryBuffer.new(io)
+----
+
+=== <<(data)
+
+Append data to buffer.
+
+[source,ruby]
+----
+buffer << "data"
+----
+
+=== read(n)
+
+Read n bytes from buffer.
+
+[source,ruby]
+----
+data = buffer.read(4)
+----
+
+=== to_s
+
+Get remaining data.
+
+[source,ruby]
+----
+data = buffer.to_s
+----
+
+=== skip
+
+Skip one object.
+
+[source,ruby]
+----
+buffer.skip
+----
+
+== Exceptions
+
+=== Messagepack::UnpackError
+
+Base class for unpacking errors.
+
+=== Messagepack::MalformedFormatError
+
+Raised when data is not valid MessagePack format.
+
+[source,ruby]
+----
+begin
+  Messagepack.unpack("invalid")
+rescue Messagepack::MalformedFormatError => e
+  puts e.message
+end
+----
+
+=== Messagepack::StackError
+
+Raised when data is too deeply nested.
+
+=== Messagepack::TypeError
+
+Raised when a type cannot be serialized.