Skip to main content

Crate layline

Crate layline 

Source
Expand description

§layline

Binary wire formats as Rust types.

Derive Layout for fixed-size records and Message for variable-length ones. Fields must cover every bit, or the build fails. Encode fills in counts, lengths and checksums; decode checks them.

[dependencies]
layline = "0.5"

§Layouts

use layline::Layout;

#[derive(Layout, Debug, PartialEq)]
#[layout(bits = 16, endian = be, order = msb)]
pub struct Header {
    #[bits(4)] pub version: u8,
    #[bits(1)] pub urgent: bool,
    #[bits(11)] pub length: u16,
}

let header = Header::decode(&[0x1A, 0x05]);
assert_eq!((header.version, header.urgent, header.length), (1, true, 0x205));
assert_eq!(header.encode(), [0x1A, 0x05]);

A layout of up to 64 bits is shifts and masks on one integer. At 8, 16, 32 or 64 bits it also converts to and from that integer: Header::from_bits(0x1A05) is the header above, read big-endian. Add truncate to #[layout(..)] to have encode keep the low bits of an oversized value, as a hardware register does, instead of panicking.

Add view to #[layout(..)] for <Name>View, which reads and writes fields in place. A view reads any bytes, so a reader can inspect a corrupt record; verify() runs the checks decode runs, checked(&wire) views only bytes that pass them, and seal() restamps magic bytes and checksums after the setters.

In a bytes = N layout a bool is one byte that must be 0 or 1: decode refuses any other value. A flag byte that any nonzero value sets is #[codec(8)] halted: layline::Nonzero.

§Messages

use layline::Message;
use layline::checksum::Crc;

type Crc16 = Crc<u16, 0x1021, 0xFFFF, 0x0000, false>;

#[derive(Message, Debug, PartialEq)]
pub struct Frame {
    #[magic(0xFE)] pub start: u8,
    pub len: u8,
    #[count(len)] pub payload: Vec<u8>,
    #[checksum(Crc16, over = len..)] pub crc: u16,
}

let frame = Frame { start: 0, len: 0, payload: vec![1, 2, 3], crc: 0 };
let wire = frame.encode();
assert_eq!(wire[..5], [0xFE, 3, 1, 2, 3]);

let (back, used) = Frame::decode(&wire).unwrap();
assert_eq!((back.payload, used), (vec![1, 2, 3], wire.len()));

#[align(N)] after a #[len(n)] field adds zero padding up to a multiple of N bytes that n does not count, as a RIFF chunk’s odd body has.

A field can be present when a flag is clear: #[when(flags & 0x4 == 0)] or #[when(!flag)]. Encode writes the flag from the field, setting the bits for None.

A struct with a lifetime borrows its byte runs from the input instead of copying them, so it decodes without an allocator. It implements MessageRef<'a>:

use layline::{Message, MessageRef};

#[derive(Message, Debug, PartialEq)]
pub struct Chunk<'a> {
    pub offset: u32,
    #[fill]
    pub data: &'a [u8],
}

let wire = [0x10, 0, 0, 0, 0xAA, 0xBB];
let (chunk, _) = Chunk::decode(&wire).unwrap();
assert_eq!(chunk.data, &[0xAA, 0xBB]);

§Switches

use layline::{Layout, Message};

#[derive(Layout, Debug, Clone, PartialEq)]
#[layout(bytes = 4)]
pub struct Ping { pub seq: u32 }

#[derive(Message, Debug, Clone, PartialEq)]
pub enum Body {
    #[value(1)] #[bytes(4)] Ping(Ping),
    #[other] Unknown(Vec<u8>),
}

#[derive(Message, Debug, PartialEq)]
pub struct Packet {
    pub kind: u8,
    #[switch(kind)] pub body: Body,
}

let (packet, _) = Packet::decode(&[1, 7, 0, 0, 0]).unwrap();
assert_eq!(packet.body, Body::Ping(Ping { seq: 7 }));

Every attribute is documented on its derive.

§Features

FeatureEnablesDefault
deriveThe derive macrosYes
allocVec, String and Box fieldsYes
frameStream framingNo
numLEB128, Exp-Golomb and reserved valuesNo
serdeSerialize for U, I and ReservedNo

§Crates

  • layline-core: the no_std runtime, with no dependencies.
  • layline-derive: the derive macros.
  • layline-codegen: generates Rust source from a model, for formats defined outside Rust.

§License

MPL-2.0

Modules§

audit
The audit format: every table of a type, one record per line.
checksum
The Checksum trait, and built-in checksums.
frameframe
Stream framing.
numnum
Number codings: reserved values, LEB128 and Exp-Golomb.
table
Table row types, and the const fns that check them.
textalloc
Text encodings for #[text] fields.

Structs§

BitReader
A bit cursor that reads from a byte slice.
BitWriter
A bit cursor that appends to a Buffer.
Extent
A field’s bit offset and width, numbered LSB0.
Fixed
A Buffer over a caller’s byte slice, for encoding without an allocator.
I
A two’s-complement signed integer exactly N bits wide, with N in 1..=64.
Nonzero
A flag stored in BITS bits that is set when any of them is.
Overflow
A buffer ran out of room during encode.
U
An unsigned integer exactly N bits wide, with N in 1..=64.

Enums§

LayoutError
Why a field table does not exactly cover its container.
ParseError
Why a decode failed.

Constants§

MAX_NESTING_DEPTH
The nesting depth, in messages, past which decode returns ParseError::TooDeep.

Traits§

BitCodec
A value whose width in bits is read from the wire.
Buffer
A byte buffer that encode appends to and patches.
Checksum
The algorithm in #[checksum(Algorithm, over = ..)].
Choice
The arms of a #[switch] field. #[derive(Message)] on an enum implements it.
Dispatch
A catalogue of payloads keyed by id. #[derive(Dispatch)] implements it.
FieldCodec
A type stored in a fixed number of bits.
Layout
A fixed-size type whose named fields cover every bit.
Message
A variable-length type, described by a segment table.
MessageRef
A variable-length type whose fields borrow the bytes it decodes from.
Slot
The variant of Self that holds a T.
TextCodecalloc
The encoding of a #[text(Codec)] field. A bare #[text] uses Utf8.
VarCodec
A value whose width in bytes is read from the wire.
View
A #[repr(transparent)] view over a Layout’s wire bytes.
WireInt
An integer read from the wire, such as a count, length or offset.

Derive Macros§

Dispatchderive
Derives Dispatch for an enum of Layout payloads selected by an id.
FieldCodecderive
Derives FieldCodec and WireInt for an integer newtype or an enum of named values, and FieldCodec for a group of bit fields.
Layoutderive
Derives Layout for a fixed-size struct.
Messagederive
Derives Message for a variable-size struct or enum, or Choice for an enum that #[switch] selects.