Flatbuffer (flatbuffer v0.5.0)

Flatbuffer binary serialization for Elixir.

Provides functions to read from and write to Flatbuffer binaries using schema definitions. Supports direct access to nested data without parsing the entire buffer.

Usage

# Read/Write
{:ok, data} = Flatbuffer.read(buffer, schema)
binary = Flatbuffer.to_binary(map, schema)

# Direct access
value = Flatbuffer.get(buffer, [:table, :field], schema)

# With schema file
def YourThing do
  use Flatbuffer, file: "schema.fbs"
end

# Read/Write
{:ok, data} = YourThing.read(buffer)
binary = YourThing.to_binary(map)

Summary

Functions

__using__(opts)

Generates schema-aware functions (read, get, to_iolist, etc.) in the caller module. Options

fetch(buffer, path, schema)

Fetches the value for a specific key (or key path) without decoding the entire buffer.

fetch!(buffer, path, schema)

Fetches the value for a specific key (or key path) without decoding the entire buffer.

get(buffer, path, schema, default \\ nil)

Gets the value for a specific key without decoding the entire buffer.

read(buffer, schema)

Reads a Flatbuffer into a map using the given schema. Field, struct, and enum names are atoms by default, or binaries when the schema was built with safe: true. Returns {:ok, map} or {:error, reason}.

read!(buffer, schema)

Same as read/2 but raises on error.

to_binary(map, schema)

Serializes a map into a Flatbuffer binary using the schema.

to_iolist(map, schema)

Serializes a map into a Flatbuffer iolist using the schema. Both atom and binary field names are accepted.

Types

field_key()

@type field_key() :: String.t() | atom()

path()

@type path() :: field_key() | [field_key() | non_neg_integer()]

Functions

using(opts)

(macro)

Generates schema-aware functions (read, get, to_iolist, etc.) in the caller module. Options:

:file - Required schema file path.
:path - Base path for schema includes.
:safe - Decode schema-defined names as binaries instead of atoms. Defaults to false.

fetch(buffer, path, schema)

@spec fetch(buffer :: iodata(), path(), Flatbuffer.Schema.t()) :: any()

Fetches the value for a specific key (or key path) without decoding the entire buffer.

If the buffer contains the key/path, then its value is returned in the shape of {:ok, value}. If the value cannot be found, :error is returned. If the buffer does not pass the id-check, {:error, {:id_mismatch, {buffer_id, schema_id}}}

fetch!(buffer, path, schema)

@spec fetch!(buffer :: iodata(), path(), Flatbuffer.Schema.t()) :: any()

Fetches the value for a specific key (or key path) without decoding the entire buffer.

If the buffer contains the key/path, the corresponding value is returned. If buffer doesn't contain it, a KeyError exception is raised.

get(buffer, path, schema, default \\ nil)

@spec get(
  buffer :: iodata(),
  path(),
  Flatbuffer.Schema.t(),
  nil | default
) :: default
when default: term()

Gets the value for a specific key without decoding the entire buffer.

Both atom and binary field names are accepted. Lookup never creates atoms.

If the key (or path) is present in the buffer then its value value is returned. Otherwise, default is returned.

If default is not provided, nil is used.

If an unparseable buffer is provided, an BadFlatbufferError is raised.

read(buffer, schema)

@spec read(buffer :: iodata(), Flatbuffer.Schema.t()) ::
  {:ok, map()}
  | {:error, {:id_mismatch, %{buffer_id: binary(), schema_id: binary()}}}

read!(buffer, schema)

@spec read!(buffer :: iodata(), Flatbuffer.Schema.t()) :: map()

Same as read/2 but raises on error.

to_binary(map, schema)

@spec to_binary(map(), Flatbuffer.Schema.t()) :: binary()

Serializes a map into a Flatbuffer binary using the schema.

to_iolist(map, schema)

@spec to_iolist(map(), Flatbuffer.Schema.t()) :: iolist()

Serializes a map into a Flatbuffer iolist using the schema. Both atom and binary field names are accepted.