ArtNet.Packet.BitField (ArtNet v0.1.0)

View Source

DSL for defining packed bit-field structs.

ArtNet.Packet.BitField maps named struct fields to bit ranges inside a single unsigned integer. Packet schemas use bit-field modules with the {:bit_field, Module} field format.

defmodule ArtNet.Packet.BitField.TalkToMe do
  use ArtNet.Packet.BitField

  defbitfield bit_size: 8 do
    field(:reply_on_change, :boolean, offset: 1)
    field(:diagnostics, :boolean)
    field(:diag_unicast, :boolean)
    field(:vlc, :boolean)
  end
end

Fields are packed from the least-significant bit upward. Each field starts at the current bit offset unless the :offset option is provided, in which case that offset is added before placing the field. After a field is placed, the current offset advances by the field size.

A bit-field module generated by defbitfield/2 receives:

  • bit_field_schema/0 - returns field formats and bit ranges.
  • bit_size/0 - returns the total bit size declared for the field.
  • decode/1 - converts an unsigned integer into the generated struct.
  • encode/1 - converts the generated struct into an unsigned integer.

Field formats

  • :boolean - a one-bit boolean value.
  • {:enum_table, module} - an enum value whose size is taken from the referenced ArtNet.Packet.EnumTable module's bit_size/0.

Summary

Types

schema_type()

Functions

decode(value, module)

Decodes an unsigned integer into a bit-field struct.

defbitfield(opts, list)

Defines a packed bit-field schema and generates its typed struct.

encode(struct, module)

Encodes a bit-field struct into an unsigned integer.

extract_bits(value, offset, length)

Extracts bits from a value.

field(name, format, opts \\ [])

Defines a field in a bit-field schema.

Types

schema_type()

@type schema_type() :: ArtNet.Packet.Schema.bit_field_format()

Functions

decode(value, module)

@spec decode(non_neg_integer(), module()) :: {:ok, struct()} | :error

Decodes an unsigned integer into a bit-field struct.

The module must be a module generated with defbitfield/2.

defbitfield(opts, list)

(macro)

Defines a packed bit-field schema and generates its typed struct.

Inside a defbitfield block, each field is defined through the field/3 macro.

Options

  • :bit_size - required total bit size of the encoded integer.

encode(struct, module)

@spec encode(
  struct(),
  module()
) :: {:ok, non_neg_integer()} | :error

Encodes a bit-field struct into an unsigned integer.

The module must be a module generated with defbitfield/2.

extract_bits(value, offset, length)

@spec extract_bits(integer(), non_neg_integer(), pos_integer()) :: non_neg_integer()

Extracts bits from a value.

Examples

iex> ArtNet.Packet.BitField.extract_bits(0b0110, 0, 2)
0b10

iex> ArtNet.Packet.BitField.extract_bits(0b0110, 2, 2)
0b01

iex> ArtNet.Packet.BitField.extract_bits(0b0110, 2, 4)
0b0001

field(name, format, opts \\ [])

(macro)

Defines a field in a bit-field schema.

Fields are positioned from the least-significant bit upward. :boolean fields consume one bit, and {:enum_table, module} fields consume the referenced enum table's bit_size/0.

Options

  • :default - default struct value. Without this option, the field is an enforced key.
  • :offset - number of bits to skip before placing this field.
  • :description - field description shown in the generated bit layout docs.