Move all preamble definitions to a new pdl-runtime crate

The pdl-runtime crate will hold all common definitions for the
generated modules. Currently it defines
  - Error: type of parsing errors
  - Packet: trait for top-level packets
  - Private: wrapper for opaque scalar fields

Cargo.toml

@@ -2,4 +2,5 @@
 members = [
     "pdl-compiler",
     "pdl-derive",
+    "pdl-runtime",
 ]

doc/rust-generated-code-guide.rst

@@ -9,7 +9,8 @@ using the `pdl` proc_macro attribute. Example usage:
 
 .. sourcecode:: rust
 
-        use pdl_derive::pdl
+        use pdl_derive::pdl;
+        use pdl_runtime::*;
 
         #[pdl("my-protocol.pdl")]
         mod my_protocol {
@@ -32,8 +33,8 @@ Language bindings
 This section contains the generated rust bindings for language constructs that
 are stabilized.
 
-Preamble
-^^^^^^^^
+Runtime
+^^^^^^^
 
 Private prevents users from creating arbitrary scalar values in situations where
 the value needs to be validated. Users can freely deref the value, but only the

pdl-compiler/src/backends/rust/preamble.rs

@@ -55,48 +55,9 @@ pub fn generate(path: &Path) -> proc_macro2::TokenStream {
         use std::convert::{TryFrom, TryInto};
         use std::cell::Cell;
         use std::fmt;
-        use thiserror::Error;
+        use pdl_runtime::{Error, Packet, Private};
 
         type Result<T> = std::result::Result<T, Error>;
-
-        /// Private prevents users from creating arbitrary scalar values
-        /// in situations where the value needs to be validated.
-        /// Users can freely deref the value, but only the backend
-        /// may create it.
-        #[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)]
-        pub struct Private<T>(T);
-
-        impl<T> std::ops::Deref for Private<T> {
-            type Target = T;
-            fn deref(&self) -> &Self::Target {
-                &self.0
-            }
-        }
-
-        #[derive(Debug, Error)]
-        pub enum Error {
-            #[error("Packet parsing failed")]
-            InvalidPacketError,
-            #[error("{field} was {value:x}, which is not known")]
-            ConstraintOutOfBounds { field: String, value: u64 },
-            #[error("Got {actual:x}, expected {expected:x}")]
-            InvalidFixedValue { expected: u64, actual: u64 },
-            #[error("when parsing {obj} needed length of {wanted} but got {got}")]
-            InvalidLengthError { obj: String, wanted: usize, got: usize },
-            #[error("array size ({array} bytes) is not a multiple of the element size ({element} bytes)")]
-            InvalidArraySize { array: usize, element: usize },
-            #[error("Due to size restrictions a struct could not be parsed.")]
-            ImpossibleStructError,
-            #[error("when parsing field {obj}.{field}, {value} is not a valid {type_} value")]
-            InvalidEnumValueError { obj: String, field: String, value: u64, type_: String },
-            #[error("expected child {expected}, got {actual}")]
-            InvalidChildError { expected: &'static str, actual: String },
-        }
-
-        pub trait Packet {
-            fn to_bytes(self) -> Bytes;
-            fn to_vec(self) -> Vec<u8>;
-        }
     }
 }
 

pdl-compiler/tests/generated/custom_field_declaration_big_endian.rs

@@ -4,45 +4,8 @@ use bytes::{Buf, BufMut, Bytes, BytesMut};
 use std::convert::{TryFrom, TryInto};
 use std::cell::Cell;
 use std::fmt;
-use thiserror::Error;
+use pdl_runtime::{Error, Packet, Private};
 type Result<T> = std::result::Result<T, Error>;
-/// Private prevents users from creating arbitrary scalar values
-/// in situations where the value needs to be validated.
-/// Users can freely deref the value, but only the backend
-/// may create it.
-#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)]
-pub struct Private<T>(T);
-impl<T> std::ops::Deref for Private<T> {
-    type Target = T;
-    fn deref(&self) -> &Self::Target {
-        &self.0
-    }
-}
-#[derive(Debug, Error)]
-pub enum Error {
-    #[error("Packet parsing failed")]
-    InvalidPacketError,
-    #[error("{field} was {value:x}, which is not known")]
-    ConstraintOutOfBounds { field: String, value: u64 },
-    #[error("Got {actual:x}, expected {expected:x}")]
-    InvalidFixedValue { expected: u64, actual: u64 },
-    #[error("when parsing {obj} needed length of {wanted} but got {got}")]
-    InvalidLengthError { obj: String, wanted: usize, got: usize },
-    #[error(
-        "array size ({array} bytes) is not a multiple of the element size ({element} bytes)"
-    )]
-    InvalidArraySize { array: usize, element: usize },
-    #[error("Due to size restrictions a struct could not be parsed.")]
-    ImpossibleStructError,
-    #[error("when parsing field {obj}.{field}, {value} is not a valid {type_} value")]
-    InvalidEnumValueError { obj: String, field: String, value: u64, type_: String },
-    #[error("expected child {expected}, got {actual}")]
-    InvalidChildError { expected: &'static str, actual: String },
-}
-pub trait Packet {
-    fn to_bytes(self) -> Bytes;
-    fn to_vec(self) -> Vec<u8>;
-}
 #[derive(Debug, Clone, Copy, Hash, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[cfg_attr(feature = "serde", serde(from = "u32", into = "u32"))]

pdl-compiler/tests/generated/custom_field_declaration_little_endian.rs

@@ -4,45 +4,8 @@ use bytes::{Buf, BufMut, Bytes, BytesMut};
 use std::convert::{TryFrom, TryInto};
 use std::cell::Cell;
 use std::fmt;
-use thiserror::Error;
+use pdl_runtime::{Error, Packet, Private};
 type Result<T> = std::result::Result<T, Error>;
-/// Private prevents users from creating arbitrary scalar values
-/// in situations where the value needs to be validated.
-/// Users can freely deref the value, but only the backend
-/// may create it.
-#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)]
-pub struct Private<T>(T);
-impl<T> std::ops::Deref for Private<T> {
-    type Target = T;
-    fn deref(&self) -> &Self::Target {
-        &self.0
-    }
-}
-#[derive(Debug, Error)]
-pub enum Error {
-    #[error("Packet parsing failed")]
-    InvalidPacketError,
-    #[error("{field} was {value:x}, which is not known")]
-    ConstraintOutOfBounds { field: String, value: u64 },
-    #[error("Got {actual:x}, expected {expected:x}")]
-    InvalidFixedValue { expected: u64, actual: u64 },
-    #[error("when parsing {obj} needed length of {wanted} but got {got}")]
-    InvalidLengthError { obj: String, wanted: usize, got: usize },
-    #[error(
-        "array size ({array} bytes) is not a multiple of the element size ({element} bytes)"
-    )]
-    InvalidArraySize { array: usize, element: usize },
-    #[error("Due to size restrictions a struct could not be parsed.")]
-    ImpossibleStructError,
-    #[error("when parsing field {obj}.{field}, {value} is not a valid {type_} value")]
-    InvalidEnumValueError { obj: String, field: String, value: u64, type_: String },
-    #[error("expected child {expected}, got {actual}")]
-    InvalidChildError { expected: &'static str, actual: String },
-}
-pub trait Packet {
-    fn to_bytes(self) -> Bytes;
-    fn to_vec(self) -> Vec<u8>;
-}
 #[derive(Debug, Clone, Copy, Hash, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[cfg_attr(feature = "serde", serde(from = "u32", into = "u32"))]

pdl-compiler/tests/generated/enum_declaration_big_endian.rs

@@ -4,45 +4,8 @@ use bytes::{Buf, BufMut, Bytes, BytesMut};
 use std::convert::{TryFrom, TryInto};
 use std::cell::Cell;
 use std::fmt;
-use thiserror::Error;
+use pdl_runtime::{Error, Packet, Private};
 type Result<T> = std::result::Result<T, Error>;
-/// Private prevents users from creating arbitrary scalar values
-/// in situations where the value needs to be validated.
-/// Users can freely deref the value, but only the backend
-/// may create it.
-#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)]
-pub struct Private<T>(T);
-impl<T> std::ops::Deref for Private<T> {
-    type Target = T;
-    fn deref(&self) -> &Self::Target {
-        &self.0
-    }
-}
-#[derive(Debug, Error)]
-pub enum Error {
-    #[error("Packet parsing failed")]
-    InvalidPacketError,
-    #[error("{field} was {value:x}, which is not known")]
-    ConstraintOutOfBounds { field: String, value: u64 },
-    #[error("Got {actual:x}, expected {expected:x}")]
-    InvalidFixedValue { expected: u64, actual: u64 },
-    #[error("when parsing {obj} needed length of {wanted} but got {got}")]
-    InvalidLengthError { obj: String, wanted: usize, got: usize },
-    #[error(
-        "array size ({array} bytes) is not a multiple of the element size ({element} bytes)"
-    )]
-    InvalidArraySize { array: usize, element: usize },
-    #[error("Due to size restrictions a struct could not be parsed.")]
-    ImpossibleStructError,
-    #[error("when parsing field {obj}.{field}, {value} is not a valid {type_} value")]
-    InvalidEnumValueError { obj: String, field: String, value: u64, type_: String },
-    #[error("expected child {expected}, got {actual}")]
-    InvalidChildError { expected: &'static str, actual: String },
-}
-pub trait Packet {
-    fn to_bytes(self) -> Bytes;
-    fn to_vec(self) -> Vec<u8>;
-}
 #[repr(u64)]
 #[derive(Debug, Clone, Copy, Hash, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]

pdl-compiler/tests/generated/enum_declaration_little_endian.rs

@@ -4,45 +4,8 @@ use bytes::{Buf, BufMut, Bytes, BytesMut};
 use std::convert::{TryFrom, TryInto};
 use std::cell::Cell;
 use std::fmt;
-use thiserror::Error;
+use pdl_runtime::{Error, Packet, Private};
 type Result<T> = std::result::Result<T, Error>;
-/// Private prevents users from creating arbitrary scalar values
-/// in situations where the value needs to be validated.
-/// Users can freely deref the value, but only the backend
-/// may create it.
-#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)]
-pub struct Private<T>(T);
-impl<T> std::ops::Deref for Private<T> {
-    type Target = T;
-    fn deref(&self) -> &Self::Target {
-        &self.0
-    }
-}
-#[derive(Debug, Error)]
-pub enum Error {
-    #[error("Packet parsing failed")]
-    InvalidPacketError,
-    #[error("{field} was {value:x}, which is not known")]
-    ConstraintOutOfBounds { field: String, value: u64 },
-    #[error("Got {actual:x}, expected {expected:x}")]
-    InvalidFixedValue { expected: u64, actual: u64 },
-    #[error("when parsing {obj} needed length of {wanted} but got {got}")]
-    InvalidLengthError { obj: String, wanted: usize, got: usize },
-    #[error(
-        "array size ({array} bytes) is not a multiple of the element size ({element} bytes)"
-    )]
-    InvalidArraySize { array: usize, element: usize },
-    #[error("Due to size restrictions a struct could not be parsed.")]
-    ImpossibleStructError,
-    #[error("when parsing field {obj}.{field}, {value} is not a valid {type_} value")]
-    InvalidEnumValueError { obj: String, field: String, value: u64, type_: String },
-    #[error("expected child {expected}, got {actual}")]
-    InvalidChildError { expected: &'static str, actual: String },
-}
-pub trait Packet {
-    fn to_bytes(self) -> Bytes;
-    fn to_vec(self) -> Vec<u8>;
-}
 #[repr(u64)]
 #[derive(Debug, Clone, Copy, Hash, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]

pdl-compiler/tests/generated/packet_decl_24bit_enum_array_big_endian.rs

@@ -4,45 +4,8 @@ use bytes::{Buf, BufMut, Bytes, BytesMut};
 use std::convert::{TryFrom, TryInto};
 use std::cell::Cell;
 use std::fmt;
-use thiserror::Error;
+use pdl_runtime::{Error, Packet, Private};
 type Result<T> = std::result::Result<T, Error>;
-/// Private prevents users from creating arbitrary scalar values
-/// in situations where the value needs to be validated.
-/// Users can freely deref the value, but only the backend
-/// may create it.
-#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)]
-pub struct Private<T>(T);
-impl<T> std::ops::Deref for Private<T> {
-    type Target = T;
-    fn deref(&self) -> &Self::Target {
-        &self.0
-    }
-}
-#[derive(Debug, Error)]
-pub enum Error {
-    #[error("Packet parsing failed")]
-    InvalidPacketError,
-    #[error("{field} was {value:x}, which is not known")]
-    ConstraintOutOfBounds { field: String, value: u64 },
-    #[error("Got {actual:x}, expected {expected:x}")]
-    InvalidFixedValue { expected: u64, actual: u64 },
-    #[error("when parsing {obj} needed length of {wanted} but got {got}")]
-    InvalidLengthError { obj: String, wanted: usize, got: usize },
-    #[error(
-        "array size ({array} bytes) is not a multiple of the element size ({element} bytes)"
-    )]
-    InvalidArraySize { array: usize, element: usize },
-    #[error("Due to size restrictions a struct could not be parsed.")]
-    ImpossibleStructError,
-    #[error("when parsing field {obj}.{field}, {value} is not a valid {type_} value")]
-    InvalidEnumValueError { obj: String, field: String, value: u64, type_: String },
-    #[error("expected child {expected}, got {actual}")]
-    InvalidChildError { expected: &'static str, actual: String },
-}
-pub trait Packet {
-    fn to_bytes(self) -> Bytes;
-    fn to_vec(self) -> Vec<u8>;
-}
 #[repr(u64)]
 #[derive(Debug, Clone, Copy, Hash, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]

pdl-compiler/tests/generated/packet_decl_24bit_enum_array_little_endian.rs

@@ -4,45 +4,8 @@ use bytes::{Buf, BufMut, Bytes, BytesMut};
 use std::convert::{TryFrom, TryInto};
 use std::cell::Cell;
 use std::fmt;
-use thiserror::Error;
+use pdl_runtime::{Error, Packet, Private};
 type Result<T> = std::result::Result<T, Error>;
-/// Private prevents users from creating arbitrary scalar values
-/// in situations where the value needs to be validated.
-/// Users can freely deref the value, but only the backend
-/// may create it.
-#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)]
-pub struct Private<T>(T);
-impl<T> std::ops::Deref for Private<T> {
-    type Target = T;
-    fn deref(&self) -> &Self::Target {
-        &self.0
-    }
-}
-#[derive(Debug, Error)]
-pub enum Error {
-    #[error("Packet parsing failed")]
-    InvalidPacketError,
-    #[error("{field} was {value:x}, which is not known")]
-    ConstraintOutOfBounds { field: String, value: u64 },
-    #[error("Got {actual:x}, expected {expected:x}")]
-    InvalidFixedValue { expected: u64, actual: u64 },
-    #[error("when parsing {obj} needed length of {wanted} but got {got}")]
-    InvalidLengthError { obj: String, wanted: usize, got: usize },
-    #[error(
-        "array size ({array} bytes) is not a multiple of the element size ({element} bytes)"
-    )]
-    InvalidArraySize { array: usize, element: usize },
-    #[error("Due to size restrictions a struct could not be parsed.")]
-    ImpossibleStructError,
-    #[error("when parsing field {obj}.{field}, {value} is not a valid {type_} value")]
-    InvalidEnumValueError { obj: String, field: String, value: u64, type_: String },
-    #[error("expected child {expected}, got {actual}")]
-    InvalidChildError { expected: &'static str, actual: String },
-}
-pub trait Packet {
-    fn to_bytes(self) -> Bytes;
-    fn to_vec(self) -> Vec<u8>;
-}
 #[repr(u64)]
 #[derive(Debug, Clone, Copy, Hash, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]