BinStruct (bin_struct v0.2.16)
Overview
iex> defmodule SimpleChildStruct do
...> use BinStruct
...> field :data, :uint8
...> end
...>
...> defmodule SimpleStructWithChild do
...> use BinStruct
...> field :child, SimpleChildStruct
...> end
...>
...> SimpleStructWithChild.new(child: SimpleChildStruct.new(data: 1))
...> |> SimpleStructWithChild.dump_binary()
...> |> SimpleStructWithChild.parse()
...> |> then(fn {:ok, struct, _rest } -> struct end)
...> |> SimpleStructWithChild.decode()
%{ child: SimpleChildStruct.new(data: 1) }
As you can see from example on above parsed structs and newly created are always equal thanks to intermediate type conversion called unmanaged.
It's neither binary or managed and you are not suppose to work with it directly, by any type (including custom types) can perform
automatic type conversion between binary, managed and unmanaged on developer request (using registered_callback api)
BinStruct will automatically generate set if functions for you:
dump_binary/1size/1parse/2will be present if is terminated (have rules defined to be parsed into finite struct from infinity bytestream)parse_exact/2decode/2new/1
In additional with configuration it supports for now:
tls_receive()
tls_send()
tcp_receive()
tcp_send()Summary
Functions
Overview
With fields you are building the shape of your binary data.
Called in module with use BinStruct defined will implement options interface after struct fully parsed.
Called in module with use BinStruct defined will register callback.
Overview
Called in module with use BinStruct defined will register option with given name.
Overview
Virtual field is powerful system which can help you in many ways working with complex data.
Functions
Overview
With fields you are building the shape of your binary data.
field/3 expected you to pass name and type of your field. Supported types can be found in Se more detailed explanation in types doc.
In additional you can pass another BinStruct itself and BinStructCustomType as type.
Supported Options
length and its length_by dynamic version
field :value, :binary, length: 1
field :value, :binary, length_by: &callback/1length expect you to pass integer and field will be set strict to this length same for length_by but it receiving callback returning integer instead
validate_by
field :value, :uint8, validate_by: &callback/1Expecting callback returning true of data is valid and false if not In case field is invalid parse will stop and { :wrong_data, _wrong_data_binary } will be returned. Used by dynamic variant by dispatching.
optional
field :v_always, :uint8
field :v_opt_tail1, :uint8, optional: true
field :v_opt_tail2, :uint8, optional: trueOptional, also known as optional tail is the way stop parsing struct when there is no more binary data and left all optional fields which not populated set to nil
optional_by
field :value, :uint8, optional_by: &callback/1Conditionally present or not value.
Callback should return either true if value should be present or false otherwise.
item_size and item_size_by (list_of only)
field :value, { :list_of, Item }, item_size: 2
field :value, { :list_of, Item }, item_size_by: &callback/1 Se more detailed explanation in list_of doc
count and count_by (list_of only)
field :value, { :list_of, Item }, count: 2
field :value, { :list_of, Item }, count_by: &callback/1 Se more detailed explanation in list_of doc
take_while_by (list_of only)
field :value, { :list_of, Item }, take_while_by: &callback/1 Se more detailed explanation in list_of doc
builder
field :value, :uint8, builder: &callback/1Builder callback will automatically build value for field. It should return 'managed' value, type conversion to underlying 'unmanaged' and 'binary' will be applied automatically. Builder callback called when you are creating struct via new/1 function. Builder can't request option argument, options are parse only tools. Field built with Builder can be requested from another builder, introducing chain. Calling order will be resolved automatically.
Called in module with use BinStruct defined will implement options interface after struct fully parsed.
iex> defmodule SharedOptions do
...> use BinStructOptionsInterface
...>
...> @type shared_option :: :a | :b
...>
...> register_option :shared_option
...>
...> end
...>
...>
...> defmodule StructImplementingOptionsInterface do
...> use BinStruct
...>
...> register_callback &impl_options_interface_1/1, data: :field
...>
...> impl_interface SharedOptions, &impl_options_interface_1/1
...>
...> field :data, :binary, length: 1
...>
...> defp impl_options_interface_1("A"), do: SharedOptions.option_shared_option(:a)
...> defp impl_options_interface_1("B"), do: SharedOptions.option_shared_option(:b)
...>
...> end
...>
...> defmodule ParentOfStructImplementingOptionsInterface do
...> use BinStruct
...>
...> register_callback &dependent_field_len/1, shared_option: %{ type: :option, interface: SharedOptions }
...>
...> field :child, StructImplementingOptionsInterface
...> field :dependent_field, :binary, length_by: &dependent_field_len/1
...>
...> defp dependent_field_len(:a), do: 1
...> defp dependent_field_len(:b), do: 2
...>
...> end
...>
...> { :ok, _struct, "" = _rest } = ParentOfStructImplementingOptionsInterface.parse("A1")
...> { :ok, _struct, "" = _rest } = ParentOfStructImplementingOptionsInterface.parse("B22")
Called in module with use BinStruct defined will register callback.
RegisteredCallback is main source of dynamic behaviour.
It's binding arguments from current parse routine along with options from total parse tree context to function you pass in. Automatically manipulating with type conversion on request.
iex> defmodule StructWithRegisteredCallbackRequestField do
...> use BinStruct
...>
...> register_callback &len_callback/1, len: :field
...>
...> field :len, :uint32_be
...> field :data, :binary, length_by: &len_callback/1
...>
...> defp len_callback(len), do: len
...>
...> end
iex> defmodule StructWithRegisteredCallbackRequestFieldInTypeConversion do
...> use BinStruct
...>
...> alias BinStruct.TypeConversion.TypeConversionBinary
...>
...> register_callback &payload_builder/1, number: %{ type: :field, type_conversion: TypeConversionBinary }
...>
...> field :number, :uint32_be
...> field :payload, :binary, builder: &payload_builder/1
...>
...> defp payload_builder(number_bin), do: number_bin
...>
...> end
iex> defmodule StructWithRegisteredCallbackRequestOption do
...> use BinStruct
...>
...> register_option :opt
...>
...> register_callback &data_length/1, opt: :option
...>
...> field :data, :binary, length_by: &data_length/1
...>
...> defp data_length(opt), do: opt
...>
...> end
...>
...> { :ok, struct, "" = _rest } = StructWithRegisteredCallbackRequestOption.parse(<<1>>, StructWithRegisteredCallbackRequestOption.option_opt(1))
...> StructWithRegisteredCallbackRequestOption.decode(struct)
%{ data: <<1>> }
Overview
Called in module with use BinStruct defined will register option with given name.
register_option :name_of_optIt can be created using option_(your_option_name)(value) generated function
YourBinStruct.option_name_of_opt(value)Multiple options are chained with pipe operator
YourBinStruct.option_name_of_opt(value)
|> YourBinStruct.option_name_of_opt2(value)
|> YourBinStruct.option_name_of_opt3(value)If requested from same module it's registered in use short notation name_of_opt: :option
register_callback &callback/1, name_of_opt: :optionFull notation is
register_callback &callback/1, name_of_opt: { type: :option, interface: YourBinStruct }Overview
Virtual field is powerful system which can help you in many ways working with complex data.
Virtual field will act as Field at most cases, including automatic type conversion.
It can be represented as any type available for Field and in special :unspecified form.
Setting virtual field to :unspecified type will make automatic type conversions impossible but will give you opportunity to set it to any elixir term.
How virtual fields behave in new context (when creating new struct)
When creating new struct with virtual fields you suppose to provide value for virtual field or attach builder callback if you need intermediate value as cache.
Any builder callbacks can read that value in any type conversion and create for you actual binary data.
How virtual fields behave in parse context (when parsing)
Virtual fields can be requested by any registered callback in any type conversion (in case it's :unspecified only 'managed') available.
Only values for virtual fields requested will be produced and exactly once per field and type conversion pair.
This behaviour can make them useful is a cache while parsing.
Any virtual field in recursive dependency of requested virtual field will be produced as well and only once rule will still work.
If A depends on B and B itself is requested in same type conversion A and B producing callbacks will be called once per such virtual field.
More idea of how and why you can use it currently you can find in test/virtual_field_system
I will try to provide more detailed info on this topic later.
How virtual fields behave in decode context (when reading data)
They will be present in decoded data.
Supported Options
read_by
virtual :v_field_name, :uint8, read_by: &callback/1Source of this virtual field.
This callback will be called once.
On decode it's always called to produce output.
On parse this callback will be called only if this virtual field is direct or indirect dependency of other callbacks.
builder
virtual :v_field_name, :binary_utf16, builder: &callback/1Callback which virtual field will be created from during creation of new struct.
This value could be used from any other builders with any requested automatic type conversion.
Virtual field will act as intermediate storage while you creating new struct. Useful separation effect and cache effect.
optional
virtual :v_field_name, :uint8, optional: trueMakes field optional