Trait Scanner

pub trait Scanner {
    type Octets: AsRef<[u8]>;
    type OctetsBuilder: OctetsBuilder + AsRef<[u8]> + AsMut<[u8]> + Truncate + FreezeBuilder<Octets = Self::Octets>;
    type Name: ToName;
    type Error: ScannerError;

    // Required methods
    fn has_space(&self) -> bool;
    fn continues(&mut self) -> bool;
    fn scan_symbols<F>(&mut self, op: F) -> Result<(), Self::Error>
       where F: FnMut(Symbol) -> Result<(), Self::Error>;
    fn scan_entry_symbols<F>(&mut self, op: F) -> Result<(), Self::Error>
       where F: FnMut(EntrySymbol) -> Result<(), Self::Error>;
    fn convert_token<C: ConvertSymbols<Symbol, Self::Error>>(
        &mut self,
        convert: C,
    ) -> Result<Self::Octets, Self::Error>;
    fn convert_entry<C: ConvertSymbols<EntrySymbol, Self::Error>>(
        &mut self,
        convert: C,
    ) -> Result<Self::Octets, Self::Error>;
    fn scan_octets(&mut self) -> Result<Self::Octets, Self::Error>;
    fn scan_ascii_str<F, T>(&mut self, op: F) -> Result<T, Self::Error>
       where F: FnOnce(&str) -> Result<T, Self::Error>;
    fn scan_name(&mut self) -> Result<Self::Name, Self::Error>;
    fn scan_charstr(&mut self) -> Result<CharStr<Self::Octets>, Self::Error>;
    fn scan_string(&mut self) -> Result<Str<Self::Octets>, Self::Error>;
    fn scan_charstr_entry(&mut self) -> Result<Self::Octets, Self::Error>;
    fn scan_opt_unknown_marker(&mut self) -> Result<bool, Self::Error>;
    fn octets_builder(&mut self) -> Result<Self::OctetsBuilder, Self::Error>;
}

A type that can produce tokens of data in presentation format.

The presentation format is a relatively simple text format that provides a sequence of entries each consisting of a sequence of tokens. An implementation of the Scanner trait provides access to the tokens of a single entry.

Most methods of the trait process a single token to the caller. Exceptions are those methods suffixed with _entry, which process all the remaining tokens of the entry. In addition, has_space reports whether the token was prefixed with white space (which is relevant in some cases), and continues reports whether there are more tokens in the entry. It it returns `false, all the other token and entry methods will return an error. That is, calling these methods assumes that the caller requires at least one more token.

Because an implementation may be able to optimize the process of converting tokens into output data types, there are a number of methods for different output. Each of these methods assumes that the next token (or the remaining tokens in the entry) is required to contain the presentation format of the given type and is should produce an error if that is not the case.

This allows for instance to optimize the creation of domain names and avoid copying around data in the most usual cases.

As a consequence, an implementation gets to choose how to return tokens. This mostly concerns the octets types to be used, but also allows it to creatively employing the name::Chain type to deal with a zone’s changing origin.

Required Associated Types

type Octets: AsRef<[u8]>

The type of octet sequences returned by the scanner.

type OctetsBuilder: OctetsBuilder + AsRef<[u8]> + AsMut<[u8]> + Truncate + FreezeBuilder<Octets = Self::Octets>

The octets builder used internally and returned upon request.

type Name: ToName

The type of a domain name returned by the scanner.

type Error: ScannerError

The error type of the scanner.

Required Methods

fn has_space(&self) -> bool

Returns whether the next token is preceded by white space.

fn continues(&mut self) -> bool

Returns whether there are more tokens in the entry.

This method takes a &mut self to allow implementations to peek on request.

fn scan_symbols<F>(&mut self, op: F) -> Result<(), Self::Error>

where F: FnMut(Symbol) -> Result<(), Self::Error>,

Scans a token into a sequence of symbols.

Each symbol is passed to the caller via the closure and can be processed there.

fn scan_entry_symbols<F>(&mut self, op: F) -> Result<(), Self::Error>

where F: FnMut(EntrySymbol) -> Result<(), Self::Error>,

Scans the remainder of the entry as symbols.

Each symbol is passed to the caller via the closure and can be processed there.

fn convert_token<C: ConvertSymbols<Symbol, Self::Error>>( &mut self, convert: C, ) -> Result<Self::Octets, Self::Error>

Converts the symbols of a token into an octets sequence.

Each symbol is passed to the provided converter which can return octet slices to be used to construct the returned value. When the token is complete, the converter is called again to ask for any remaining data to be added.

fn convert_entry<C: ConvertSymbols<EntrySymbol, Self::Error>>( &mut self, convert: C, ) -> Result<Self::Octets, Self::Error>

Converts the symbols of a token into an octets sequence.

Each symbol is passed to the provided converter which can return octet slices to be used to construct the returned value. When the token is complete, the converter is called again to ask for any remaining data to be added.

fn scan_octets(&mut self) -> Result<Self::Octets, Self::Error>

Scans a token into an octets sequence.

The returned sequence has all symbols converted into their octets. It can be of any length.

fn scan_ascii_str<F, T>(&mut self, op: F) -> Result<T, Self::Error>

where F: FnOnce(&str) -> Result<T, Self::Error>,

Scans a token as a borrowed ASCII string.

If the next token contains non-ascii characters, returns an error. The string is given to the caller via the provided closure.

fn scan_name(&mut self) -> Result<Self::Name, Self::Error>

Scans a token into a domain name.

fn scan_charstr(&mut self) -> Result<CharStr<Self::Octets>, Self::Error>

Scans a token into a character string.

Note that character strings have a length limit. If you want a sequence of indefinite length, use scan_octets instead.

fn scan_string(&mut self) -> Result<Str<Self::Octets>, Self::Error>

Scans a token as a UTF-8 string.

fn scan_charstr_entry(&mut self) -> Result<Self::Octets, Self::Error>

Scans a sequence of character strings until the end of the entry.

The returned octets will contain the sequence of character strings in wire format.

fn scan_opt_unknown_marker(&mut self) -> Result<bool, Self::Error>

Scans an optional unknown rdata marker.

If the next token is \#, i.e., an unquoted, escaped hash sign, consumes the token and returns Ok(true). If the next token is anything else or if there is no next token, does nothing and returns Ok(false). If there is an error, returns an error.

fn octets_builder(&mut self) -> Result<Self::OctetsBuilder, Self::Error>

Returns an empty octets builder.

This builder can be used to create octets sequences in cases where the other methods can’t be used.

Object Safety

This trait is not object safe.

Implementors

impl<Iter, Item, Octets> Scanner for IterScanner<Iter, Octets>

where Item: AsRef<str>, Iter: Iterator<Item = Item>, Octets: FromBuilder, <Octets as FromBuilder>::Builder: EmptyBuilder + Composer,

type Octets = Octets

type OctetsBuilder = <Octets as FromBuilder>::Builder

type Name = Name<Octets>

type Error = StrError