Trait NetdocParseable

Source

pub trait NetdocParseable: Sized {
    // Required methods
    fn doctype_for_error() -> &'static str;
    fn is_intro_item_keyword(kw: KeywordRef<'_>) -> bool;
    fn from_items(
        input: &mut ItemStream<'_>,
        stop_at: StopAt<impl StopPredicate>,
    ) -> Result<Self, ErrorProblem>;
    fn is_structural_keyword(kw: KeywordRef<'_>) -> Option<IsStructural>;
}

Available on crate feature parse2 only.

Expand description

A document or section that can be parsed

Normally derived.

Required Methods§

Source

fn doctype_for_error() -> &'static str

Document type for errors, normally its intro keyword

Source

fn is_intro_item_keyword(kw: KeywordRef<'_>) -> bool

Is Keyword an intro Item Keyword for this kind of document?

This is used with 1-keyword lookahead, to allow us to push or pop the parsing state into or out of a sub-document.

For signatures sections, this should report every recognised keyword.

Source

fn from_items( input: &mut ItemStream<'_>, stop_at: StopAt<impl StopPredicate>, ) -> Result<Self, ErrorProblem>

Parse the document from a stream of Items

Should stop before reading any keyword matching stop_at. (Except, right at the start.)

Should also stop before reading a 2nd intro keyword, so that successive calls to this function can parse successive sub-documents of this kind.

Otherwise, should continue until EOF.

Must check whether the first item is this document’s is_intro_item_keyword, and error if not.

Source

fn is_structural_keyword(kw: KeywordRef<'_>) -> Option<IsStructural>

Is Keyword a structural keyword for this kind of document?

Returns Some(IsStructural) for:

this type’s intro item keyword (is_intro_item_keyword)
the intro items or structural items for any of its sub-documents and sections #[deftly(netdoc(subdoc))]

(This means it returns true for any item in a signatures subdocument ie any field in a struct decorated #[deftly(netdoc(signatures))] since those are considered intro items.)

Used for avoiding parsing ambiguity when a netdoc from a semi-trusted source is embedded into another netdoc. See https://spec.torproject.org/dir-spec/creating-key-certificates.html#nesting.

§Return type and relationship to `is_intro_item_keyword`

Returns Option<IsStructural> so that it has a different type to NetdocParseable::is_intro_item_keyword, preventing accidental confusion between the two kinds of keyword property enquiry.

Our parsing algorithms actually only care about intro keywords for sub-documents. We don’t need to worry about anything else; notably, we don’t need to care about other structural items within those sub-documents.

Except for authcerts in votes,, which are nested documents with partially trusted content. That is what this method is for.

So, we privilege is_intro_item_keyword by having it return bool and by the affordances in StopAt.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

NetdocParseable

Trait NetdocParseable Copy item path

Required Methods§

fn doctype_for_error() -> &'static str

fn is_intro_item_keyword(kw: KeywordRef<'_>) -> bool

fn from_items( input: &mut ItemStream<'_>, stop_at: StopAt<impl StopPredicate>, ) -> Result<Self, ErrorProblem>

fn is_structural_keyword(kw: KeywordRef<'_>) -> Option<IsStructural>

§Return type and relationship to is_intro_item_keyword

Dyn Compatibility§

Implementations on Foreign Types§

impl<T: NetdocParseable> NetdocParseable for Arc<T>

fn doctype_for_error() -> &'static str

fn is_intro_item_keyword(kw: KeywordRef<'_>) -> bool

fn is_structural_keyword(kw: KeywordRef<'_>) -> Option<IsStructural>

fn from_items( input: &mut ItemStream<'_>, stop_at: StopAt<impl StopPredicate>, ) -> Result<Self, EP>

Implementors§

impl NetdocParseable for AuthCert

impl NetdocParseable for AuthCertSignatures

impl NetdocParseable for AuthCertSigned

impl NetdocParseable for EncodedAuthCert

impl NetdocParseable for tor_netdoc::doc::netstatus::md::RouterStatus

impl NetdocParseable for tor_netdoc::doc::netstatus::plain::RouterStatus

impl NetdocParseable for tor_netdoc::doc::netstatus::vote::RouterStatus

impl NetdocParseable for tor_netdoc::parse2::poc::netstatus::cons::NddAuthorityEntry

impl NetdocParseable for tor_netdoc::parse2::poc::netstatus::cons::NddAuthoritySection

impl NetdocParseable for tor_netdoc::parse2::poc::netstatus::cons::NddDirectoryFooter

impl NetdocParseable for tor_netdoc::parse2::poc::netstatus::cons::NetworkStatusSignatures

impl NetdocParseable for tor_netdoc::parse2::poc::netstatus::md::NddAuthorityEntry

impl NetdocParseable for tor_netdoc::parse2::poc::netstatus::md::NddAuthoritySection

impl NetdocParseable for tor_netdoc::parse2::poc::netstatus::md::NddDirectoryFooter

impl NetdocParseable for tor_netdoc::parse2::poc::netstatus::md::NetworkStatusSignatures

impl NetdocParseable for tor_netdoc::parse2::poc::netstatus::NetworkStatusMd

impl NetdocParseable for tor_netdoc::parse2::poc::netstatus::NetworkStatusNs

impl NetdocParseable for tor_netdoc::parse2::poc::netstatus::NetworkStatusSignedMd

impl NetdocParseable for tor_netdoc::parse2::poc::netstatus::NetworkStatusSignedNs

impl NetdocParseable for tor_netdoc::parse2::poc::netstatus::NetworkStatusSignedVote

impl NetdocParseable for tor_netdoc::parse2::poc::netstatus::NetworkStatusVote

impl NetdocParseable for tor_netdoc::parse2::poc::netstatus::vote::NddAuthorityEntry

impl NetdocParseable for tor_netdoc::parse2::poc::netstatus::vote::NddAuthoritySection

impl NetdocParseable for tor_netdoc::parse2::poc::netstatus::vote::NddDirectoryFooter

impl NetdocParseable for tor_netdoc::parse2::poc::netstatus::vote::NetworkStatusSignatures

Trait NetdocParseable

§Return type and relationship to `is_intro_item_keyword`