Document the use of the pdl attribute with examples and tests

Author: hchataing

doc/rust-generated-code-guide.rst

@@ -4,7 +4,23 @@ Rust Generated Code Guide
 Usage
 -----
 
-Example invocation:
+The crate `pdl_derive` lets developers embed their grammar in a source module
+using the `pdl` proc_macro attribute. Example usage:
+
+.. sourcecode:: rust
+
+        use pdl_derive::pdl
+
+        #[pdl("my-protocol.pdl")]
+        mod my_protocol {
+        }
+
+The `pdl` proc_macro attribute must be attached to a module declaration.
+`pdl` preserves the original name, attributes, and items of the associated
+module.
+
+The backend can also be pre-generated from the `pdlc` tool,
+and compiled as source. Example invocation:
 
 .. sourcecode:: bash
 

pdl-compiler/examples/jpeg.pdl examples/jpeg.pdl

@@ -61,13 +61,13 @@ enum MarkerType : 8 {
 
 struct Marker {
     _fixed_ = 0xff : 8,
-    type: MarkerType,
+    type : MarkerType,
     _payload_,
 }
 
 struct Segment: Marker {
-    _size_(_payload_): 16,
-    _payload_ [+2],
+    _size_(_payload_) : 16,
+    _payload_ : [+2],
 }
 
 struct StartOfImage : Marker(type = SOI) {}

pdl-compiler/examples/pcap.pdl examples/pcap.pdl

@@ -26,3 +26,7 @@ proc-macro2 = "1.0.66"
 quote = "1.0.33"
 syn = {version = "2.0.29", features = ["full"]}
 termcolor = "1.2.0"
+
+[dev-dependencies]
+bytes = "1.4.0"
+thiserror = "1.0.47"

pdl-derive/Cargo.toml

@@ -0,0 +1,53 @@
+// Copyright 2023 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! PDL tests.
+
+use pdl_derive::pdl;
+
+#[test]
+fn test_pcap() {
+    #[pdl("../examples/pcap.pdl")]
+    mod pcap {}
+
+    use pcap::*;
+    let pcap_file = PcapFileBuilder {
+        header: PcapHeader {
+            version_major: 1,
+            version_minor: 0,
+            thiszone: 0,
+            sigfigs: 0,
+            snaplen: 512,
+            network: 42,
+        },
+        records: vec![PcapRecord {
+            ts_sec: 0xdead,
+            ts_usec: 0xbeef,
+            orig_len: 1024,
+            payload: vec![1, 2, 3],
+        }],
+    }
+    .build();
+
+    assert!(PcapFile::parse(&pcap_file.to_vec()).is_ok());
+}
+
+#[test]
+#[cfg(disabled)]
+fn test_jpeg() {
+    // The JPEG syntax depends on struct inheritance which is currently
+    // not supported. https://github.com/google/pdl/issues/62
+    #[pdl("../examples/jpeg.pdl")]
+    mod jpeg {}
+}