diff options
author | Justus Winter <justus@sequoia-pgp.org> | 2020-04-30 14:13:17 +0200 |
---|---|---|
committer | Justus Winter <justus@sequoia-pgp.org> | 2020-04-30 14:13:17 +0200 |
commit | 4083319ae3ad384b2da5cb52c52013389d571745 (patch) | |
tree | 3bfb9f1cfcaffbf5ed22eec80abcd8e414e93382 /openpgp/src/parse/map.rs | |
parent | 722e2893f1091dfd2083329823c8067c4726f6df (diff) |
openpgp: Improve documentation of the parse module.
- See #471.
Diffstat (limited to 'openpgp/src/parse/map.rs')
-rw-r--r-- | openpgp/src/parse/map.rs | 129 |
1 files changed, 105 insertions, 24 deletions
diff --git a/openpgp/src/parse/map.rs b/openpgp/src/parse/map.rs index 994ad208..ceca8bc6 100644 --- a/openpgp/src/parse/map.rs +++ b/openpgp/src/parse/map.rs @@ -3,6 +3,26 @@ //! If configured to do so, a `PacketParser` will create a map that //! charts the byte-stream, describing where the information was //! extracted from. +//! +//! # Examples +//! +//! ``` +//! # f().unwrap(); fn f() -> sequoia_openpgp::Result<()> { +//! use sequoia_openpgp as openpgp; +//! use openpgp::parse::{Parse, PacketParserBuilder}; +//! +//! let message_data = b"\xcb\x12t\x00\x00\x00\x00\x00Hello world."; +//! let pp = PacketParserBuilder::from_bytes(message_data)? +//! .map(true) // Enable mapping. +//! .build()? +//! .expect("One packet, not EOF"); +//! let map = pp.map().expect("Mapping is enabled"); +//! +//! assert_eq!(map.iter().nth(0).unwrap().name(), "CTB"); +//! assert_eq!(map.iter().nth(0).unwrap().offset(), 0); +//! assert_eq!(map.iter().nth(0).unwrap().as_bytes(), &[0xcb]); +//! # Ok(()) } +//! ``` use std::cmp; @@ -49,33 +69,26 @@ impl Map { /// Creates an iterator over the map. /// - /// Items returned are a small string indicating what kind of - /// information is extracted (e.g. "header", or "version"), and a - /// slice containing the actual bytes. + /// Returns references to [`Field`]s. /// - /// # Example + /// [`Field`]: struct.Field.html + /// + /// # Examples /// /// ``` - /// # extern crate sequoia_openpgp as openpgp; - /// # use openpgp::Result; - /// # use openpgp::parse::{Parse, PacketParser, PacketParserBuilder}; - /// # f(); - /// # - /// # fn f() -> Result<()> { - /// let msg = b"\xcb\x12t\x00\x00\x00\x00\x00Hello world."; - /// let ppo = PacketParserBuilder::from_bytes(msg)? - /// .map(true).build()?; - /// assert_eq!(ppo.unwrap().map().unwrap().iter() - /// .map(|f| (f.name(), f.as_bytes())) - /// .collect::<Vec<(&str, &[u8])>>(), - /// [("CTB", &b"\xcb"[..]), - /// ("length", &b"\x12"[..]), - /// ("format", b"t"), - /// ("filename_len", b"\x00"), - /// ("date", b"\x00\x00\x00\x00"), - /// ("body", b"Hello world.")]); - /// # Ok(()) - /// # } + /// # f().unwrap(); fn f() -> sequoia_openpgp::Result<()> { + /// use sequoia_openpgp as openpgp; + /// use openpgp::parse::{Parse, PacketParserBuilder}; + /// + /// let message_data = b"\xcb\x12t\x00\x00\x00\x00\x00Hello world."; + /// let pp = PacketParserBuilder::from_bytes(message_data)? + /// .map(true) // Enable mapping. + /// .build()? + /// .expect("One packet, not EOF"); + /// let map = pp.map().expect("Mapping is enabled"); + /// + /// assert_eq!(map.iter().count(), 6); + /// # Ok(()) } /// ``` pub fn iter<'a>(&'a self) -> impl Iterator<Item = Field<'a>> { Iter::new(self) @@ -83,6 +96,14 @@ impl Map { } /// Represents an entry in the map. +/// +/// A field has a [`name`] returning a human-readable field name +/// (e.g. "CTB", or "version"), an [`offset`] into the packet, and the +/// read [`data`]. +/// +/// [`name`]: #method.name +/// [`offset`]: #method.offset +/// [`data`]: #method.data #[derive(Clone, Debug)] pub struct Field<'a> { /// Name of the field. @@ -129,16 +150,76 @@ impl<'a> Field<'a> { /// /// Note: The returned names are for display purposes only and may /// change in the future. + /// + /// # Examples + /// + /// ``` + /// # f().unwrap(); fn f() -> sequoia_openpgp::Result<()> { + /// use sequoia_openpgp as openpgp; + /// use openpgp::parse::{Parse, PacketParserBuilder}; + /// + /// let message_data = b"\xcb\x12t\x00\x00\x00\x00\x00Hello world."; + /// let pp = PacketParserBuilder::from_bytes(message_data)? + /// .map(true) // Enable mapping. + /// .build()? + /// .expect("One packet, not EOF"); + /// let map = pp.map().expect("Mapping is enabled"); + /// + /// assert_eq!(map.iter().nth(0).unwrap().name(), "CTB"); + /// assert_eq!(map.iter().nth(1).unwrap().name(), "length"); + /// assert_eq!(map.iter().nth(2).unwrap().name(), "format"); + /// # Ok(()) } + /// ``` pub fn name(&self) -> &'a str { self.name } /// Returns the offset of the field in the packet. + /// + /// # Examples + /// + /// ``` + /// # f().unwrap(); fn f() -> sequoia_openpgp::Result<()> { + /// use sequoia_openpgp as openpgp; + /// use openpgp::parse::{Parse, PacketParserBuilder}; + /// + /// let message_data = b"\xcb\x12t\x00\x00\x00\x00\x00Hello world."; + /// let pp = PacketParserBuilder::from_bytes(message_data)? + /// .map(true) // Enable mapping. + /// .build()? + /// .expect("One packet, not EOF"); + /// let map = pp.map().expect("Mapping is enabled"); + /// + /// assert_eq!(map.iter().nth(0).unwrap().offset(), 0); + /// assert_eq!(map.iter().nth(1).unwrap().offset(), 1); + /// assert_eq!(map.iter().nth(2).unwrap().offset(), 2); + /// # Ok(()) } + /// ``` pub fn offset(&self) -> usize { self.offset } /// Returns the value of the field. + /// + /// # Examples + /// + /// ``` + /// # f().unwrap(); fn f() -> sequoia_openpgp::Result<()> { + /// use sequoia_openpgp as openpgp; + /// use openpgp::parse::{Parse, PacketParserBuilder}; + /// + /// let message_data = b"\xcb\x12t\x00\x00\x00\x00\x00Hello world."; + /// let pp = PacketParserBuilder::from_bytes(message_data)? + /// .map(true) // Enable mapping. + /// .build()? + /// .expect("One packet, not EOF"); + /// let map = pp.map().expect("Mapping is enabled"); + /// + /// assert_eq!(map.iter().nth(0).unwrap().as_bytes(), &[0xcb]); + /// assert_eq!(map.iter().nth(1).unwrap().as_bytes(), &[0x12]); + /// assert_eq!(map.iter().nth(2).unwrap().as_bytes(), "t".as_bytes()); + /// # Ok(()) } + /// ``` pub fn as_bytes(&self) -> &'a [u8] { self.data } |