Provides functionality to decode Smile binary format into Elixir terms.

The decoder parses Smile-encoded binary data and reconstructs the original Elixir data structures. It handles all token types defined in the Smile specification and maintains back-reference tables for shared names and values.

Decoding Process

The decoder performs the following steps:

1. Parse and validate the 4-byte Smile header
2. Extract header flags (shared names, shared values, raw binary)
3. Initialize decoding state with appropriate back-reference tables
4. Parse tokens and recursively decode values
5. Maintain back-reference lists for shared names and values

Supported Output Types

The decoder produces the following Elixir types:

• Smile null → nil
• Smile boolean → true or false
• Smile integer → Elixir integer
• Smile float → Elixir float
• Smile string → Binary string
• Smile array → Elixir list
• Smile object → Elixir map with string keys

Error Handling

The decoder returns descriptive errors for various failure scenarios:

• :invalid_header - Invalid or missing Smile header
• :incomplete_string - String data is truncated
• :incomplete_int32 / :incomplete_int64 - Integer data is truncated
• :incomplete_float32 / :incomplete_float64 - Float data is truncated
• :missing_string_terminator - Long string missing end marker
• {:unknown_token, byte} - Unrecognized token byte
• {:invalid_shared_reference, index} - Invalid back-reference index

Examples

# Basic decoding
iex> binary = <<58, 41, 10, 3, 33>>  # Smile null
iex> Smile.Decoder.decode(binary)
{:ok, nil}

# Decoding with error
iex> Smile.Decoder.decode(<<1, 2, 3>>)
{:error, :invalid_header}

Implementation Details

The decoder implements:

• Header validation with version and flag parsing
• Token-based parsing with pattern matching
• Back-reference management for shared names and values (up to 1024 entries each)
• Variable-length integer decoding (VInt)
• ZigZag decoding for signed integers
• Recursive decoding for nested structures (arrays and objects)