ArtNet.Encoder (ArtNet v0.1.0)

View Source

Low-level field encoders used by packet schemas.

Most callers should use ArtNet.encode/1 or ArtNet.Packet.encode/1. This module works one field at a time and mirrors the formats accepted by ArtNet.Packet.Schema.field/3.

The generic encode/3 dispatcher returns {:ok, binary} or :error. Packet-level encoding wraps those failures in ArtNet.EncodeError with the field name that failed.

Summary

Types

list_encode_error()

Functions

binary(value, size)

Encodes a binary value into a binary.

bit_field(value)

Encodes a bit field value into a binary.

encode(values, arg2, opts)

Encodes one value using a schema field format.

encode_list(values, format, opts)

Encodes a list of values into a binary.

enum_table(value, module)

Encodes an enum value into a binary.

integer(value, size)

Encodes an integer value into a binary.

little_integer(value, size)

Encodes a little-endian integer value into a binary.

Types

list_encode_error()

@type list_encode_error() ::
  :not_list
  | {:invalid_length, expected :: non_neg_integer(),
     actual :: non_neg_integer()}
  | {:invalid_element, value :: any()}
  | {:invalid_element, value :: any(), reason :: any()}

Functions

binary(value, size)

@spec binary(binary(), pos_integer() | nil) :: {:ok, binary()} | :error

Encodes a binary value into a binary.

  • data is the binary to encode.
  • size is the size of the binary in bytes. If the binary is smaller than the size, it is padded with zeros. If nil, the binary is returned as-is.

The function returns {:ok, binary} if the binary was successfully encoded. If the binary could not be encoded, the function returns :error.

Examples

iex> ArtNet.Encoder.binary(<<1, 2>>, 2)
{:ok, <<1, 2>>}

iex> ArtNet.Encoder.binary(<<1>>, 4)
{:ok, <<1, 0, 0, 0>>}

iex> ArtNet.Encoder.binary(<<1, 2>>, 1)
:error

bit_field(value)

@spec bit_field(struct()) :: {:ok, binary()} | :error

Encodes a bit field value into a binary.

  • value is the bit field value to encode.

The function returns {:ok, binary} if the bit field value was successfully encoded, or :error if one of its fields cannot be converted.

Examples

iex> ArtNet.Encoder.bit_field(%ArtNet.Packet.BitField.TalkToMe{reply_on_change: true,diagnostics: true,diag_unicast: false,vlc: false})
{:ok, <<0b00110>>}

encode(values, arg2, opts)

@spec encode(any(), ArtNet.Packet.Schema.format(), Keyword.t()) ::
  {:ok, binary()} | :error

Encodes one value using a schema field format.

The format argument is one of the formats documented in ArtNet.Packet.Schema. For list formats, opts[:length] may require an exact number of elements.

encode_list(values, format, opts)

@spec encode_list([any()], ArtNet.Packet.Schema.format(), Keyword.t()) ::
  {:ok, binary()} | {:error, list_encode_error()}

Encodes a list of values into a binary.

  • values is the list of values to encode.
  • format is the format of the values.
  • opts is a keyword of format options.

The function returns {:ok, binary} if the values were successfully encoded. If the values could not be encoded, the function returns an error tuple describing the list failure.

Examples

iex> ArtNet.Encoder.encode_list([1, 2, 3], {:integer, 8}, [])
{:ok, <<1, 2, 3>>}

iex> ArtNet.Encoder.encode_list([1, 2, 0x1111], {:integer, 16}, [])
{:ok, <<0, 1, 0, 2, 0x11, 0x11>>}

iex> ArtNet.Encoder.encode_list([1, 2, 0x1111], {:integer, 8}, [])
{:error, {:invalid_element, 0x1111}}

iex> ArtNet.Encoder.encode_list(1, {:integer, 8}, [])
{:error, :not_list}

iex> ArtNet.Encoder.encode_list([1], {:integer, 8}, length: 2)
{:error, {:invalid_length, 2, 1}}

enum_table(value, module)

@spec enum_table(atom(), module()) :: {:ok, binary()} | :error

Encodes an enum value into a binary.

  • value is the enum value to encode.
  • module is the module that defines the enum.

The function returns {:ok, binary} if the enum value was successfully encoded. If the enum value could not be encoded, the function returns :error.

Examples

iex> ArtNet.Encoder.enum_table(:dp_all, ArtNet.Packet.EnumTable.Priority)
{:ok, <<0x00>>}

iex> ArtNet.Encoder.enum_table(:dp_high, ArtNet.Packet.EnumTable.Priority)
{:ok, <<0x80>>}

iex> ArtNet.Encoder.enum_table(:none, ArtNet.Packet.EnumTable.Priority)
:error

integer(value, size)

@spec integer(non_neg_integer(), pos_integer()) :: {:ok, binary()} | :error

Encodes an integer value into a binary.

  • value is the integer to encode.
  • size is the size of the integer in bits.

The function returns {:ok, binary} if the integer was successfully encoded. If the integer could not be encoded, the function returns :error.

Examples

iex> ArtNet.Encoder.integer(0x0102, 16)
{:ok, <<1, 2>>}

iex> ArtNet.Encoder.integer(0x01020304, 32)
{:ok, <<1, 2, 3, 4>>}

iex> ArtNet.Encoder.integer(0x0102, 8)
:error

little_integer(value, size)

@spec little_integer(non_neg_integer(), pos_integer()) :: {:ok, binary()} | :error

Encodes a little-endian integer value into a binary.

The integer must be non-negative and fit in size bits.

Examples

iex> ArtNet.Encoder.little_integer(0x0102, 16)
{:ok, <<2, 1>>}

iex> ArtNet.Encoder.little_integer(0x01020304, 32)
{:ok, <<4, 3, 2, 1>>}

iex> ArtNet.Encoder.little_integer(0x0102, 8)
:error