Module parse2

tor_netdoc

Module parse2 

Source
Available on crate feature parse2 only.
Expand description

New netdoc parsing arrangements, with derive

§Parsing principles

A parseable network document is a type implementing NetdocParseable. usually via the NetdocParseable derive=deftly macro`.

A document type is responsible for recognising its own heading item. Its parser will also be told other of structural items that it should not consume. The structural lines can then be used to pass control to the appropriate parser.

§Ordering

We don’t parse things into a sorted order. Sorting will be done on output.

§Types, and signature handling

Most top-level network documents are signed somehow. In this case there are three types:

  • FooSigned: a signed Foo, with its signatures, not yet verified. Implements [NetdocSigned], typically by invoking the NetdocSigned derive macro on Foo.

    Type-specific methods are provided for verification, to obtain a Foo.

  • Foo: the body data for the document. This doesn’t contain any signatures. Having one of these to play with means signatures have already been validated. Implement NetdocParseable, via derive.

  • FooSignatures: the signatures for a Foo. Implement NetdocParseable, via derive, with #[deftly(netdoc(signatures))].

§Naming conventions

  • DocumentName: important types, including network documents or sub-documents, eg NetworkStatsuMd and RouterVote, and types that are generally useful.
  • NddDoucmnetSection: sections and sub-documents that the user won’t normally need to name.
  • NdiItemValue: parsed value for a network document Item. eg NdiVoteStatus representing the whole of the RHS of a vote-status Item. Often not needed since ItemValueParseable is implemented for suitable tuples.
  • NdaArgumentValue: parsed value for a single argument; eg NdaVoteStatus representing the vote or status argument.

§Relationship to tor_netdoc::parse

This is a completely new parsing approach, based on different principles. The key principle is the recognition of “structural keywords”, recursively within a parsing stack, via the pNetdocParseable] trait.

This allows the parser to be derived. We have type-driven parsing of whole Documents, Items, and their Arguments and Objects, including of their multiplicity.

The different keyword handling means we can’t use most of the existing lexer, and need new item parsing API:

The different error handling means we have our own error types. (The crate’s existing parse errors have information that we don’t track, and is also a portmanteau error for parsing, writing, and other functions.)

Document signing is handled in a more abstract way.

Some old netdoc constructs are not supported. For example, the obsolete opt prefix on safe-to-ignore Items. The parser may make different decisions about netdocs with anomalous item ordering.

Re-exports§

pub use keyword::KeywordRef;

Modules§

keyword
Keywords in netdocs
multiplicity
Multiplicity of fields (Items and Arguments)
poc
Proof-of-concept parser using parse2 for network status documents
sig_hash_methods
Methods suitable for use with #[deftly(netdoc(sig_hash = "METHOD"))]

Structs§

ArgumentStream
Reader for arguments on an Item
ItemStream
Top-level reader: Netdoc text interpreted as a stream of items
Lines
Version of std::str::Lines that tracks line numbers and has remainder()
NdaSystemTimeDeprecatedSyntax
Date and time in deprecated ISO8601-with-space separate arguments syntax
NoFurtherArguments
End of an argument list that does not accept any further (unknown) arguments
ParseError
Error encountered when parsing a document, including its location
Peeked
Information about the next line we have peeked
SignatureHashInputs
Inputs needed to calculate a specific signature hash for a specific Item
StopAt
Predicate for testing whether a keyword is a structural one that we should stop at
UnparsedItem
An Item that has been lexed but not parsed
UnparsedObject
An Object that has been lexed but not parsed

Enums§

ErrorProblem
Problem found when parsing a document
VerifyFailed
Error from signature verification (and timeliness check)

Traits§

ItemArgumentParseable
An (individual) argument that can appear in a netdoc
ItemObjectParseable
A possibly-optional Object value that can appear in netdoc
ItemValueParseable
An item (value) that can appear in a netdoc
NetdocParseable
A document or section that can be parsed
SignatureItemParseable
A signature item that can appear in a netdoc
StopPredicate
Raw predicate, usually a closure, that can appear within StopAt.
StrExt
Extension trait adding a method to str

Functions§

check_validity_time
Utility function to check that a time is within a validity period
parse_netdoc
Parse a network document - toplevel entrypoint
parse_netdoc_multiple
Parse a network document - toplevel entrypoint