Skip to main content

layline_core/
lib.rs

1//! Runtime for layline.
2//!
3//! `no_std`, with no dependencies.
4//!
5//! - [`Layout`]: a fixed-size type, described by a [`FieldDef`](table::FieldDef) table.
6//! - [`Message`]: a variable-length type, described by a [`SegmentDef`](table::SegmentDef) table.
7//! - [`audit`]: prints those tables.
8//! - [`frame`] (feature `frame`): stream framing.
9//! - [`num`] (feature `num`): LEB128, Exp-Golomb and reserved values.
10
11#![no_std]
12#![cfg_attr(docsrs, feature(doc_cfg))]
13#![deny(missing_docs)]
14
15#[cfg(feature = "alloc")]
16extern crate alloc;
17
18pub mod audit;
19pub mod checksum;
20
21#[cfg(feature = "frame")]
22pub mod frame;
23#[cfg(feature = "num")]
24pub mod num;
25#[cfg(feature = "alloc")]
26pub mod text;
27
28mod bits;
29mod bound;
30mod buffer;
31mod codec;
32mod dispatch;
33mod extent;
34mod field;
35mod int;
36mod mask;
37mod message;
38mod row;
39mod segment;
40mod slot;
41mod var;
42mod view;
43mod word;
44
45#[cfg(test)]
46pub(crate) mod buf {
47    use core::fmt;
48
49    pub(crate) struct Buf([u8; 4096], usize);
50
51    impl fmt::Write for Buf {
52        fn write_str(&mut self, s: &str) -> fmt::Result {
53            self.0[self.1..self.1 + s.len()].copy_from_slice(s.as_bytes());
54            self.1 += s.len();
55            Ok(())
56        }
57    }
58
59    impl Buf {
60        pub(crate) fn of(what: impl fmt::Display) -> Self {
61            use fmt::Write;
62            let mut b = Buf([0; 4096], 0);
63            write!(b, "{what}").unwrap();
64            b
65        }
66
67        pub(crate) fn text(&self) -> &str {
68            core::str::from_utf8(&self.0[..self.1]).unwrap()
69        }
70    }
71}
72
73/// Table row types, and the `const fn`s that check them.
74///
75/// Rows borrow for `'a` rather than `'static`, so a code generator can build them from its own model.
76pub mod table {
77    pub use crate::field::{
78        ConstDef, FieldDef, ParamDef, RangeDef, StatedDef, StatedUnit, TypeDef, check_layout,
79        field_width, type_is,
80    };
81    pub use crate::segment::{
82        ArmCover, ArmDef, By, CoverDef, CoverEdge, Discriminant, Presence, SegmentDef, Span, Start,
83        arms_fit, fixed_bits,
84    };
85}
86
87/// Items used by generated code.
88///
89/// Generated code names only `layline::__private::..` and `::core::..` paths, so a user's own
90/// `Vec`, `String` or `Result` cannot shadow them.
91#[doc(hidden)]
92pub mod __private {
93    pub use ::core;
94
95    #[cfg(feature = "alloc")]
96    pub use alloc::{boxed::Box, string::String, vec, vec::Vec};
97
98    pub use crate::bound::{Nestable, WireFlag, fits_in_field};
99    pub use crate::field::assert_layout;
100    pub use crate::word::BitWord;
101
102    #[cfg(feature = "alloc")]
103    pub use crate::text::{TextCodec, Utf8};
104
105    /// Requires a `#[checksum(..)]` field's type to be the algorithm's [`Checksum::Output`].
106    ///
107    /// [`Checksum::Output`]: crate::Checksum::Output
108    #[diagnostic::on_unimplemented(
109        message = "a `{Self}` checksum does not fit a `{T}` field",
110        label = "this field must be `<{Self} as layline::Checksum>::Output`",
111        note = "a checksum field must have the algorithm's output type. \
112                Change the field's type, or use an algorithm whose output is `{T}`"
113    )]
114    pub trait ChecksumFits<T>: crate::sealed::ChecksumFits {}
115
116    #[diagnostic::do_not_recommend]
117    impl<A> crate::sealed::ChecksumFits for A where A: crate::Checksum {}
118
119    #[diagnostic::do_not_recommend]
120    impl<A, T> ChecksumFits<T> for A where A: crate::Checksum<Output = T> {}
121}
122
123/// Seals the bound traits so only the blanket impls exist.
124mod sealed {
125    pub trait Nestable {}
126    pub trait ChecksumFits {}
127    pub trait WireFlag {}
128    pub trait CrcWord {}
129}
130
131pub use bits::{BitCodec, BitReader, BitWriter};
132pub use bound::WireInt;
133pub use buffer::{Buffer, Fixed, Overflow};
134pub use checksum::Checksum;
135pub use codec::{FieldCodec, Nonzero};
136pub use dispatch::Dispatch;
137pub use extent::Extent;
138pub use field::{Layout, LayoutError};
139pub use int::{I, U};
140pub use message::{MAX_NESTING_DEPTH, ParseError};
141pub use segment::{Choice, Message, MessageRef};
142pub use slot::Slot;
143pub use var::VarCodec;
144pub use view::View;
145
146#[cfg(feature = "alloc")]
147pub use text::TextCodec;