Trait domain::master::scanner::Scanner[−][src]

pub trait Scanner {
    fn is_eof(&mut self) -> bool;

    fn pos(&self) -> Pos;

    fn scan_word<T, F>(&mut self, f: F) -> ScanResult<T>
    where
        F: FnOnce(&[u8]) -> SyntaxResult<T>;

    fn scan_word_into<T, U, F, G>(
        &mut self, 
        target: T, 
        f: F, 
        g: G
    ) -> ScanResult<U>
    where
        F: FnMut(&mut T, u8, bool) -> SyntaxResult<()>,
        G: FnOnce(T) -> SyntaxResult<U>;

    fn scan_quoted<T, F>(&mut self, f: F) -> ScanResult<T>
    where
        F: FnOnce(&[u8]) -> SyntaxResult<T>;

    fn scan_quoted_bytes<F>(&mut self, f: F) -> ScanResult<()>
    where
        F: FnMut(u8, bool) -> SyntaxResult<()>;

    fn scan_phrase<T, F>(&mut self, f: F) -> ScanResult<T>
    where
        F: FnOnce(&[u8]) -> SyntaxResult<T>;

    fn scan_phrase_bytes<F>(&mut self, f: F) -> ScanResult<()>
    where
        F: FnMut(u8, bool) -> SyntaxResult<()>;

    fn scan_newline(&mut self) -> ScanResult<()>;

    fn scan_space(&mut self) -> ScanResult<()>;

    fn scan_opt_space(&mut self) -> ScanResult<()>;

    fn skip_entry(&mut self) -> ScanResult<()>;

    fn scan_word_bytes<F>(&mut self, f: F) -> ScanResult<()>
    where
        F: FnMut(u8, bool) -> SyntaxResult<()>,
    { ... }

    fn scan_str_phrase<T, F>(&mut self, f: F) -> ScanResult<T>
    where
        F: FnOnce(&str) -> SyntaxResult<T>,
    { ... }

    fn scan_phrase_copy(&mut self) -> ScanResult<Vec<u8>> { ... }

    fn scan_u16(&mut self) -> ScanResult<u16> { ... }

    fn scan_u32(&mut self) -> ScanResult<u32> { ... }

    fn scan_hex_word<F>(&mut self, f: F) -> ScanResult<()>
    where
        F: FnMut(u8) -> SyntaxResult<()>,
    { ... }

    fn skip_literal(&mut self, literal: &[u8]) -> ScanResult<()> { ... }

    fn scan_dname(
        &mut self, 
        origin: Option<&DNameSlice>
    ) -> ScanResult<DNameBuf> { ... }

    fn scan_dname_into(
        &mut self, 
        origin: Option<&DNameSlice>, 
        target: &mut Vec<u8>
    ) -> ScanResult<()> { ... }

    fn scan_charstr(&mut self) -> ScanResult<CharStrBuf> { ... }

    fn scan_charstr_into(&mut self, target: &mut Vec<u8>) -> ScanResult<()> { ... }
}

A trait for a scanner of master format tokens.

The master format is using a small number of different token types. This trait provides a way to access a sequence of such tokens. There is a method prefix by scan_ for each type of token that tries to scan a token of the given type. If it succeeds, it returns the token and progresses to the end of the token. If it fails, it returns an error and reverts to the position before the scanning attempt unless an IO error occured in which case the scanner becomes ‘broken.’

The methods that provide access to the token’s content do so through closures to let the user decide if and how copies ought to be made. Note that since the scanner may throw away the content at any time after the closure returns, you cannot keep the slice references passed in. This is not on purpose, not a mistake with the lifetime arguments.

Required Methods

Fundamental Methods

Returns whether the scanner has reached the end of data.

This will return false if reading results in an IO error.

Returns the current position of the scanner.

Scans a word token.

A word is a sequence of non-special characters and escape sequences followed by a non-empty sequence of space unless it is followed directly by a newline. If successful, the method will position at the end of the space sequence if it is required. That is, you can scan for two subsequent word tokens without worrying about the space between them.

A reference to the content of the actual word (ie., without any trailing space) is passed to the provided closure. This is the raw content without any escape sequences translated. If the closure likes the content, it can return something which will then become the return value of the entire method. Otherwise, it returns a syntax error. In this case, the whole method will fails returning the syntax error and the position of the start of the token.

Scans a quoted word.

A quoted word starts with a double quote ", followed by all sorts of characters or escape sequences until the next (unescaped) double quote. It may contain line feeds. Like a regular word, a quoted word is followed by a non-empty space sequence unless it is directly followed by a newline. This space is not part of the content but quietly skipped over.

The reference to the raw content of the quoted word is given to the closure f which needs to decide of it fulfills its own requirements. If it does, it can translate it into a return value which is also returned by the method. Otherwise, it returns a syntax error which is reported by the method with the position of the first double quote.

Scans a quoted word, processing the content characters separatedly.

This method is similar to scan_quoted() but the closure is called for each character of the content. Escape sequences are translated into the character they stand for. For each character, the closure receives the character value and a boolean indicating whether the character was in fact translated from an escape sequence. Ie., the content b"f" will be translated into one single closure call with f(b'f', false), whereas the content b"\102" will also be just one call but with f(b'f', true).

If the closure returns Ok(()), the method proceeds to the next content character or, if there are no more characters, itself returns Ok(()). If the closure returns an error, the method returns to the start of the token and returns the error with that position.

Scans phrase: a normal or quoted word.

This method behaves like scan_quoted() if the next character is a double quote or like scan_word() otherwise.

Scans a phrase, processing the content characters separatedly.

This method behaves like scan_quoted_bytes() if the next character is a double quote or like scan_word_bytes() otherwise.

Scans a newline.

A newline is either an optional comment followed by either a CR or LF character or the end of file. The latter is so that a file lacking a line feed after its last line is still parsed successfully.

Scans a non-empty sequence of space.

There are two flavors of space. The simple form is any sequence of a space character b' ' or a horizontal tab 'b\t'. However, a parenthesis can be used to turn newlines into normal space. This method recognises parentheses and acts accordingly.

Scans a possibly empty sequence of space.

Skips over an entry.

Keeps reading until it successfully scans a newline. The method tries to be smart about that and considers parentheses, quotes, and escapes but also tries its best to not fail.

Provided Methods

Scans a word, processing each character of its content separatedly.

This method is similar to scan_word() but the closure is called for each character of the content. Escape sequences are translated into the character they stand for. For each character, the closure receives the character value and a boolean indicating whether the character was in fact translated from an escape sequence. Ie., the content b"f" will be translated into one single closure call with f(b'f', false), whereas the content b"\102" will also be just one call but with f(b'f', true).

If the closure returns Ok(()), the method proceeds to the next content character or, if there are no more characters, itself returns Ok(()). If the closure returns an error, the method returns to the start of the token and returns the error with that position.

Scans a phrase and converts it into a string slice.

This method is similar to scan_phrase() but passes a string slice to the closure instead of a bytes slice. There are no allocations and the method syntax errors out if the content contains non-ASCII characters.

Scans a phrase and returns a copy of it.

The copy will have all escape sequences translated.

Helper Methods

Scans a phrase containing a 16 bit integer in decimal representation.

Scans a phrase containing a 32 bit integer in decimal representation.

Scans a word containing a sequence of pairs of hex digits.

Each pair is translated to its byte value and passed to the closure f.

Skips over the word with the content literal.

The content indeed needs to be literally the literal. Escapes are not translated before comparison and case has to be as is.

Scans a domain name and returns an owned domain name.

If the name is relative, it is made absolute by appending origin. If there is no origin given, a syntax error is returned.

Scans a domain name into a bytes vec.

The name is scanned and its wire format representation is appened to the end of target. If the scanned name is relative, it is made absolute by appending origin. If there is no origin given, a syntax error is returned.

Scans a character string and returns it as an owned value.

Scans a character string into a bytes vec.

The string is scanned and its wire format representation is appened to the end of target.

Implementors