API References

A declarative de-ser for binary data. Inspired by Construct.

Construct{T}

Construct is used for serializing and deserializing objects.

Methods

• deserialize(cons::Construct{T}, s::IO; contextkw...)
• serialize(cons::Construct{T}, s::IO, obj::T; contextkw...)
• estimatesize(cons::Construct{T}; contextkw...) - optional

Construct(T) -> Construct{T}

Get default construct for type T.

serialize(cons::Construct, s::IO, obj; contextkw...)
serialize(T, s::IO, obj; contextkw...)
serialize(s::IO, obj; contextkw...)

Serialize an object into a stream.

serialize(cons::Construct, filename::AbstractString, obj; contextkw...)
serialize(T, filename::AbstractString, obj; contextkw...)
serialize(filename::AbstractString, obj; contextkw...)

Serialize an object to the file.

serialize(cons::Construct, obj; contextkw...) -> Vector{UInt8}
serialize(T, obj; contextkw...) -> Vector{UInt8}
serialize(obj; contextkw...) -> Vector{UInt8}

Serialize an object in memory (a byte array).

deserialize(cons::Construct{T}, s::IO; contextkw...) -> T
deserialize(T, s::IO; contextkw...) -> T

Deserialize a stream to an object.

deserialize(cons::Construct{T}, filename::AbstractString; contextkw...) -> T
deserialize(T, filename::AbstractString; contextkw...) -> T

Deserialize a file to an object.

deserialize(cons::Construct{T}, bytes::AbstractVector{UInt8}; contextkw...) -> T
deserialize(T, bytes::AbstractVector{UInt8}; contextkw...) -> T

Deserialize a byte array to an object.

estimatesize(cons::Construct; contextkw...) -> ConstructSize
estimatesize(T; contextkw...) -> ConstructSize

Estimate the size of the type.

default(cons::Construct{T}; contextkw...) -> T
default(T; contextkw...) -> T

Get default value for the construct/type.

This method is usually called for anonymous fields in @construct.

Wrapper{TSub, T} <: Construct{T}

Abstract wrapper for TSub.

Methods

• subcon(wrapper::Wrapper{TSub, T})

subcon(wrapper::Wrapper{TSub, T}) -> Construct{TSub}

Get sub-construct of wrapper.

Adapter{TSub, T} <: Wrapper{TSub, T}

Abstract adapter type.

Methods

• subcon(adapter::Adapter{TSub, T})
• encode(adapter::Adapter{TSub, T}, obj::T; contextkw...)
• decode(adapter::Adapter{TSub, T}, obj::TSub; contextkw...)

Adapter(T|subcon, U) -> Adapter{T, U}

Create a adapter for type U.

Arguments

• T: the underlying data type.
• subcon::Construct{T}: the underlying construct.
• U: the object type.

SymmetricAdapter{T} <: Adapter{T, T}

Abstract adapter type. encode both for serializing and deserializing.

Methods

• subcon(adapter::SymmetricAdapter{T})
• encode(adapter::SymmetricAdapter{T}, obj::T; contextkw...)

Adapter(T|subcon, encode) -> SymmetricAdapter{T}
SymmetricAdapter(T|subcon, encode) -> SymmetricAdapter{T}

Create a symmetric adapter based on the encode function.

Arguments

• subcon::Construct{T}: the underlying construct.
• encode: the encoding function. the function should have signature like (::T; contextkw...)->T and satisfies involution (encode(encode(x)) == x).

encode(adapter::Adapter{TSub, T}, obj::T; contextkw...) -> TSub

Encode the input object when serializing.

decode(adapter::Adapter{TSub, T}, obj::TSub; contextkw...) -> T

Decode the output object when deserializing.

Validator{T} <: SymmetricAdapter{T}

Abstract validator type. Validates a condition on the encoded/decoded object..

Methods

• subcon(validator::Validator{T})
• validate(validator::Validator{T}, obj::T; contextkw...)

Validator(T|subcon, validate) -> Validator{T}

Create a validator based on the validate function.

Arguments

• subcon::Construct{T}: the underlying construct.
• validate: the validate function. the function should have signature like (::T; contextkw...)->Bool.

validate(validator::Validator{T}, obj::T; contextkw...) -> Bool

Checks whether the given obj is a valid value for the validator.

Should return a Bool or throw a ValidationError.

PrimitiveIO(T) -> Construct{T}

Defines a primitive IO construct for type based on read and write.

This is the default construct for Bool, Char, UInt8, UInt16, UInt32, UInt64, UInt128, Int8, Int16, Int32, Int64, Int128, Float16, Float32 and Float64.

Examples

julia> serialize(PrimitiveIO(Complex{Bool}), im)
2-element Vector{UInt8}:
 0x00
 0x01

Singleton(T) -> Construct{T}
Singleton(instance::T) -> Construct{T}

Defines an empty construct for singleton type.

This is the default constructor for Nothing and Missing.

Examples

julia> serialize(missing)
UInt8[]

julia> deserialize(Singleton(pi), UInt8[])
π = 3.1415926535897...

JuliaSerializer([T = Any]) -> Construct{T}

Create the standard Julia serializer.

See also: Serialization

RaiseError(error::Exception) -> Construct{Union{}}
RaiseError(message::String) -> Construct{Union{}}

Raise specific error or ErrorException(message) when serializing or deserializing any data.

NullTerminatedString([T], [encoding]) -> Construct{T}

String ending in a terminating null character.

This is the default construct for the subtypes of AbstractString.

Arguments

• T<:AbstractString: the underlying string type.
• encoding::Union{Encoding, String}: the string encoding.

PaddedString([T], n, [encoding]) -> Construct{T}

String padded to n bytes.

Arguments

• T<:AbstractString: the underlying string type.
• n::Integer: the size of the string in bytes.
• encoding::Union{Encoding, String}: the string encoding.

PrefixedString([T], S|size, [encoding]) -> Construct{T}

String with the size in the header.

Arguments

• T<:AbstractString: the underlying string type.
• S<:Integer: the typeof the string size.
• size::Construct{S}: the construct of the string size (in bytes).
• encoding::Union{Encoding, String}: the string encoding.

LittleEndian(T) -> Construct{T}

Defines the little endian format T.

Examples

julia> deserialize(LittleEndian(UInt16), b"\x12\x34")
0x3412

BigEndian(T) -> Construct{T}

Defines the big endian format T.

Examples

julia> deserialize(BigEndian(UInt16), b"\x12\x34")
0x1234

Float16be = BigEndian(Float16)

Float16le = LittleEndian(Float16)

Float32be = BigEndian(Float32)

Float32le = LittleEndian(Float32)

Float64be = BigEndian(Float64)

Float64le = LittleEndian(Float64)

Int128be = BigEndian(Int128)

Int128le = LittleEndian(Int128)

Int16be = BigEndian(Int16)

Int16le = LittleEndian(Int16)

Int32be = BigEndian(Int32)

Int32le = LittleEndian(Int32)

Int64be = BigEndian(Int64)

Int64le = LittleEndian(Int64)

UInt128be = BigEndian(UInt128)

UInt128le = LittleEndian(UInt128)

UInt16be = BigEndian(UInt16)

UInt16le = LittleEndian(UInt16)

UInt32be = BigEndian(UInt32)

UInt32le = LittleEndian(UInt32)

UInt64be = BigEndian(UInt64)

UInt64le = LittleEndian(UInt64)

IntEnum([T|subcon], E) -> Construct{E}

Defines the (exhaustive) enumeration based on integer type T.

This is the default constructor for Base.Enum{T}.

Arguments

• T<:Integer: the underly integer type, default is the base type of E.
• subcon::Construct{T}: the underly integer construct.
• E<:Base.Enum: the enum type.

Examples

julia> @enum Fruit::UInt8 apple=1 banana=2 orange=3

julia> deserialize(IntEnum(Fruit), b"\x02")
banana::Fruit = 0x02

julia> deserialize(IntEnum(Fruit), b"\x04")
ERROR: ArgumentError: invalid value for Enum Fruit: 4
[...]

julia> serialize(IntEnum(UInt16le, Fruit), orange)
2-element Vector{UInt8}:
 0x03
 0x00

IntEnum{EnumNonExhaustive}([T|subcon], E) -> Construct{E}

Defines the non-exhaustive enumeration based on integer type T.

Arguments

• T<:Integer: the underly integer type, default is the base type of E.
• subcon::Construct{T}: the underly integer construct.
• E<:Base.Enum: the enum type.

Examples

julia> @enum Fruit::UInt8 apple=1 banana=2 orange=3

julia> deserialize(IntEnum{EnumNonExhaustive}(Fruit), b"\x04")
<invalid #4>::Fruit = 0x04

EnumNonExhaustive <: EnumExhaustibility

Indicates the enumeration is non-exhaustive.

EnumExhaustive <: EnumExhaustibility

Indicates the enumeration is exhaustive.

Sequence(Ts|elements...) -> Construct{Tuple{Ts...}}

Defines the sequence of construct data based on elements.

This is the default constructor for Tuple{Ts...}.

Examples

julia> serialize((true, 0x23))
2-element Vector{UInt8}:
 0x01
 0x23

julia> deserialize(Sequence(Bool, UInt8), b"\xab\xcd")
(true, 0xcd)

Known problems

In Julia 1.6, if the number of Sequence elements is greater than 9, @construct cannot deduce the field type correctly.

SizedArray([TA], T|element, size...) -> Construct{TA}

Defines an array with specific size and element.

Arguments

• TA<:AbstractArray{T}: the target array type, the default is Array{T, N}.
• T: the type of elements.
• element::Construct{T}: the construct of elements.
• size: the size of the array.

PrefixedArray([TA], S|size, T|element) -> Construct{TA}

Defines an array with its size in the header.

Arguments

• TA<:AbstractArray{T, N}: the target array type, the default is Array{T, N}.
• S<:Union{Integer, NTuple{N, Integer}}: the type of the size in the header.
• T: the type of elements.
• size::Construct{S}: the construct of size.
• element::Construct{T}: the construct of elements.

GreedyVector(T|element) -> Construct{Vector{T}}

Defines an unknown-sized vector, which will deserialize elements as much as possible.

Arguments

• T: the type of elements.
• element::Construct{T}: the construct of elements.

Optional(T|subcon, [default = nothing]) -> Construct{Union{T, TV}}
Optional{TU}(T|subcon, [default = nothing]) -> Construct{TU}

Optional construct with a default value.

Arguments

• TU: the common type of the construct and the default value.
• T<:TU: the type of the sub construct.
• TV<:TU: the type of the default value.
• subcon::Construct{T}: the sub construct.
• default::TV: the default value.

Try(T1|subcon1, T2|subcon2, ...) -> Construct{Union{T1, T2, ...}}
Try{TU}(T1|subcon1, T2|subcon2, ...) -> Construct{TU}

Try each subcon and use the first successful one.

Examples

Another non-exhaustive enum:

julia> @enum Fruit::UInt8 apple=1 banana=2 orange=3

julia> deserialize(Try(Fruit, UInt8), b"\x02")
banana::Fruit = 0x02

julia> deserialize(Try(Fruit, UInt8), b"\x04")
0x04

Padded([T|subcon = Nothing], n) -> Construct{T}

Create n-bytes padded data from subcon.

Arguments

• subcon::Construct{T}: the construct to be padded.
• n::Integer: the size in bytes after padded.

Examples

julia> deserialize(Padded(Int8, 2), b"\x01\xfc")
1

julia> serialize(Padded(Int8, 2), Int8(1))
2-element Vector{UInt8}:
 0x01
 0x00

Const([T|subcon], value::T) -> Construct{T}

Defines a constant value, usually used for file headers.

Arguments

• subcon::Construct{T}: the underlying construct.
• value::T: the expected value.

Examples

julia> serialize(Const(0x01), 0x01)
1-element Vector{UInt8}:
 0x01

julia> deserialize(Const(0x01), b"\x01")
0x01

julia> serialize(Const(0x01), 0x03)
ERROR: ValidationError: 3 mismatch the const value 1.
[...]

julia> deserialize(Const(0x01), b"\x02")
ERROR: ValidationError: 2 mismatch the const value 1.
[...]

Overwrite(T, value::T) -> Construct{T}
Overwrite(T, getter) -> Construct{T}
Overwrite(subcon::Construct{T}, value::T) -> Construct{T}
Overwrite(subcon::Construct{T}, getter) -> Construct{T}

Overwrite the value when serializing from getter/value. Deserialization simply passes down.

Arguments

• subcon::Construct{T}: the underlying construct.
• value::T: the value to overwrite when serializing.
• getter: the function to overwrite when serializing. the function should have signature like (::T; contextkw...) and satisfies idempotence (getter(getter(x)) == getter(x)).

Examples

julia> serialize(Overwrite(UInt8, 0x01), 2)
1-element Vector{UInt8}:
 0x01

julia> serialize(Overwrite(Int8, abs), -2)
1-element Vector{UInt8}:
 0x02

julia> deserialize(Overwrite(UInt8, 0x01), b"\x05")
0x05

@construct [ConstructName] structdefinition

Generate a Construct subtype with ConstructName for the given struct.

Examples

julia> @construct struct Bitmap
           ::Const(b"BMP")
           width::UInt16le
           height::UInt16le
           pixel::SizedArray(UInt8, this.height, this.width)
       end

julia> deserialize(Bitmap, b"BMP\x03\x00\x02\x00\x01\x02\x03\x04\x05\x06")
Bitmap(0x0003, 0x0002, UInt8[0x01 0x03 0x05; 0x02 0x04 0x06])

julia> serialize(Bitmap(2, 3, UInt8[1 2; 4 6; 8 9]))
13-element Vector{UInt8}:
 0x42
 0x4d
 0x50
 0x02
 0x00
 0x03
 0x00
 0x01
 0x04
 0x08
 0x02
 0x06
 0x09

julia> estimatesize(Bitmap)
UnboundedSize(0x0000000000000007)

this

Placeholder to access properties of the current object in @construct context.

Container{T}

Intermediate container for a struct object when serializing/deserializing it.

Container{T}()

Create an uninitialized container for T.

Examples

julia> Container{Complex{Int64}}()
Container{Complex{Int64}}:
  re: Int64 = #undef
  im: Int64 = #undef

Container(object)

Create a container from object.

Examples

julia> Container(3+4im)
Container{Complex{Int64}}:
  re: Int64 = 3
  im: Int64 = 4

UndefProperty{T}

Placeholder for undefined properties in Container.

PropertyPath(segments)

Represents a property path.

ConstructSize

Abstract super type of construct size.

ExactSize(value)

Exact construct size (upper bound and lower bound are same).

RangedSize(lower, upper)

Ranged construct size.

UnboundedSize(lower)

Unbounded ranged size.

UnboundedUpper

Unsigned infinity.

AbstractConstructError <: Exception

Abstract error type for constructs.

ValidationError(msg)

Error thrown when the validatiion failed.

ExceedMaxIterations(msg, [max_iter])

Error thrown when exceed the max iterations.

PaddedError(msg)

Error thrown when the encoded string or bytes takes more bytes than padding allows, or the pad value is improper.