diff options
author | Justus Winter <justus@sequoia-pgp.org> | 2020-05-27 13:39:54 +0200 |
---|---|---|
committer | Justus Winter <justus@sequoia-pgp.org> | 2020-05-27 13:41:31 +0200 |
commit | 707275685fe643a479aec88eb665eccfb0873f7e (patch) | |
tree | 713767b1684c040906f2dde5b51c209dff5f792b /openpgp/src | |
parent | 40792400dd4fac8c0d3876432daddf29adb40034 (diff) |
openpgp: Improve documentation for PacketParserEOF.
- See #471.
Diffstat (limited to 'openpgp/src')
-rw-r--r-- | openpgp/src/parse.rs | 212 |
1 files changed, 206 insertions, 6 deletions
diff --git a/openpgp/src/parse.rs b/openpgp/src/parse.rs index eb9e1175..3b4ba821 100644 --- a/openpgp/src/parse.rs +++ b/openpgp/src/parse.rs @@ -2984,6 +2984,50 @@ enum ParserResult<'a> { /// Information about the stream of packets parsed by the /// `PacketParser`. +/// +/// Once the [`PacketParser`] reaches the end of the input stream, it +/// returns a [`PacketParserResult::EOF`] with a `PacketParserEOF`. +/// This object provides information about the parsed stream, notably +/// whether or not the packet stream was a well-formed [`Message`], +/// [`Cert`] or keyring. +/// +/// [`PacketParser`]: struct.PacketParser.html +/// [`PacketParserResult::EOF`]: enum.PacketParserResult.html#variant.EOF +/// [`Message`]: ../struct.Message.html +/// [`Cert`]: ../cert/struct.Cert.html +/// +/// # Examples +/// +/// Parse some OpenPGP stream using a [`PacketParser`] and detects the +/// kind of data: +/// +/// ```rust +/// # fn main() -> sequoia_openpgp::Result<()> { +/// use sequoia_openpgp as openpgp; +/// use openpgp::Packet; +/// use openpgp::parse::{Parse, PacketParserResult, PacketParser}; +/// +/// let openpgp_data: &[u8] = // ... +/// # include_bytes!("../tests/data/keys/public-key.gpg"); +/// let mut ppr = PacketParser::from_bytes(openpgp_data)?; +/// while let PacketParserResult::Some(mut pp) = ppr { +/// // Start parsing the next packet, recursing. +/// ppr = pp.recurse()?.1; +/// } +/// +/// if let PacketParserResult::EOF(eof) = ppr { +/// if eof.is_message().is_ok() { +/// // ... +/// } else if eof.is_cert().is_ok() { +/// // ... +/// } else if eof.is_keyring().is_ok() { +/// // ... +/// } else { +/// // ... +/// } +/// } +/// # Ok(()) } +/// ``` #[derive(Debug)] pub struct PacketParserEOF { state: PacketParserState, @@ -3005,9 +3049,43 @@ impl PacketParserEOF { } } - /// Whether the message is an OpenPGP Message. + /// Returns whether the stream is an OpenPGP Message. + /// + /// A [`Message`] has a very specific structure. Returns `true` + /// if the stream is of that form, as opposed to a [`Cert`] or + /// just a bunch of packets. + /// + /// [`Message`]: ../struct.Message.html + /// [`Cert`]: ../cert/struct.Cert.html /// - /// As opposed to a Cert or just a bunch of packets. + /// # Examples + /// + /// Parse some OpenPGP stream using a [`PacketParser`] and detects the + /// kind of data: + /// + /// [`PacketParser`]: struct.PacketParser.html + /// + /// ```rust + /// # fn main() -> sequoia_openpgp::Result<()> { + /// use sequoia_openpgp as openpgp; + /// use openpgp::Packet; + /// use openpgp::parse::{Parse, PacketParserResult, PacketParser}; + /// + /// let openpgp_data: &[u8] = // ... + /// # include_bytes!("../tests/data/keys/public-key.gpg"); + /// let mut ppr = PacketParser::from_bytes(openpgp_data)?; + /// while let PacketParserResult::Some(mut pp) = ppr { + /// // Start parsing the next packet, recursing. + /// ppr = pp.recurse()?.1; + /// } + /// + /// if let PacketParserResult::EOF(eof) = ppr { + /// if eof.is_message().is_ok() { + /// // ... + /// } + /// } + /// # Ok(()) } + /// ``` pub fn is_message(&self) -> Result<()> { use crate::message::MessageValidity; @@ -3018,9 +3096,42 @@ impl PacketParserEOF { } } - /// Whether the message is an OpenPGP keyring. + /// Returns whether the message is an OpenPGP keyring. + /// + /// A keyring has a very specific structure. Returns `true` if + /// the stream is of that form, as opposed to a [`Message`] or + /// just a bunch of packets. + /// + /// [`Message`]: ../struct.Message.html + /// + /// # Examples /// - /// As opposed to a Message or just a bunch of packets. + /// Parse some OpenPGP stream using a [`PacketParser`] and detects the + /// kind of data: + /// + /// [`PacketParser`]: struct.PacketParser.html + /// + /// ```rust + /// # fn main() -> sequoia_openpgp::Result<()> { + /// use sequoia_openpgp as openpgp; + /// use openpgp::Packet; + /// use openpgp::parse::{Parse, PacketParserResult, PacketParser}; + /// + /// let openpgp_data: &[u8] = // ... + /// # include_bytes!("../tests/data/keys/public-key.gpg"); + /// let mut ppr = PacketParser::from_bytes(openpgp_data)?; + /// while let PacketParserResult::Some(mut pp) = ppr { + /// // Start parsing the next packet, recursing. + /// ppr = pp.recurse()?.1; + /// } + /// + /// if let PacketParserResult::EOF(eof) = ppr { + /// if eof.is_keyring().is_ok() { + /// // ... + /// } + /// } + /// # Ok(()) } + /// ``` pub fn is_keyring(&self) -> Result<()> { match self.state.keyring_validator.check() { KeyringValidity::Keyring => Ok(()), @@ -3029,9 +3140,43 @@ impl PacketParserEOF { } } - /// Whether the message is an OpenPGP Cert. + /// Returns whether the message is an OpenPGP Cert. + /// + /// A [`Cert`] has a very specific structure. Returns `true` if + /// the stream is of that form, as opposed to a [`Message`] or + /// just a bunch of packets. + /// + /// [`Message`]: ../struct.Message.html + /// [`Cert`]: ../cert/struct.Cert.html + /// + /// # Examples + /// + /// Parse some OpenPGP stream using a [`PacketParser`] and detects the + /// kind of data: + /// + /// [`PacketParser`]: struct.PacketParser.html + /// + /// ```rust + /// # fn main() -> sequoia_openpgp::Result<()> { + /// use sequoia_openpgp as openpgp; + /// use openpgp::Packet; + /// use openpgp::parse::{Parse, PacketParserResult, PacketParser}; + /// + /// let openpgp_data: &[u8] = // ... + /// # include_bytes!("../tests/data/keys/public-key.gpg"); + /// let mut ppr = PacketParser::from_bytes(openpgp_data)?; + /// while let PacketParserResult::Some(mut pp) = ppr { + /// // Start parsing the next packet, recursing. + /// ppr = pp.recurse()?.1; + /// } /// - /// As opposed to a Message or just a bunch of packets. + /// if let PacketParserResult::EOF(eof) = ppr { + /// if eof.is_cert().is_ok() { + /// // ... + /// } + /// } + /// # Ok(()) } + /// ``` pub fn is_cert(&self) -> Result<()> { match self.state.cert_validator.check() { CertValidity::Cert => Ok(()), @@ -3041,6 +3186,34 @@ impl PacketParserEOF { } /// Returns the path of the last packet. + /// + /// # Examples + /// + /// Parse some OpenPGP stream using a [`PacketParser`] and returns + /// the path (see [`PacketPile::path_ref`]) of the last packet: + /// + /// [`PacketPile::path_ref`]: ../struct.PacketPile.html#method.path_ref + /// [`PacketParser`]: struct.PacketParser.html + /// + /// ```rust + /// # fn main() -> sequoia_openpgp::Result<()> { + /// use sequoia_openpgp as openpgp; + /// use openpgp::Packet; + /// use openpgp::parse::{Parse, PacketParserResult, PacketParser}; + /// + /// let openpgp_data: &[u8] = // ... + /// # include_bytes!("../tests/data/keys/public-key.gpg"); + /// let mut ppr = PacketParser::from_bytes(openpgp_data)?; + /// while let PacketParserResult::Some(mut pp) = ppr { + /// // Start parsing the next packet, recursing. + /// ppr = pp.recurse()?.1; + /// } + /// + /// if let PacketParserResult::EOF(eof) = ppr { + /// let _ = eof.last_path(); + /// } + /// # Ok(()) } + /// ``` pub fn last_path(&self) -> &[usize] { &self.last_path[..] } @@ -3049,6 +3222,33 @@ impl PacketParserEOF { /// /// A top-level packet has a recursion depth of 0. Packets in a /// top-level container have a recursion depth of 1, etc. + /// + /// # Examples + /// + /// Parse some OpenPGP stream using a [`PacketParser`] and returns + /// the recursion depth of the last packet: + /// + /// [`PacketParser`]: struct.PacketParser.html + /// + /// ```rust + /// # fn main() -> sequoia_openpgp::Result<()> { + /// use sequoia_openpgp as openpgp; + /// use openpgp::Packet; + /// use openpgp::parse::{Parse, PacketParserResult, PacketParser}; + /// + /// let openpgp_data: &[u8] = // ... + /// # include_bytes!("../tests/data/keys/public-key.gpg"); + /// let mut ppr = PacketParser::from_bytes(openpgp_data)?; + /// while let PacketParserResult::Some(mut pp) = ppr { + /// // Start parsing the next packet, recursing. + /// ppr = pp.recurse()?.1; + /// } + /// + /// if let PacketParserResult::EOF(eof) = ppr { + /// let _ = eof.last_recursion_depth(); + /// } + /// # Ok(()) } + /// ``` pub fn last_recursion_depth(&self) -> Option<isize> { if self.last_path.len() == 0 { None |