Struct Parser

pub struct Parser<'a> { /* private fields */ }

Available on crate feature text-parsing only.

5. ZONE FILES

Zone files are text files that contain RRs in text form.  Since the
contents of a zone can be expressed in the form of a list of RRs a
Zone File is most often used to define a zone, though it can be used
to list a cache's contents.  Hence, this section first discusses the
format of RRs in a Zone File, and then the special considerations when
a Zone File is used to create a zone in some name server.

5.1. Format

The format of these files is a sequence of entries.  Entries are
predominantly line-oriented, though parentheses can be used to continue
a list of items across a line boundary, and text literals can contain
CRLF within the text.  Any combination of tabs and spaces act as a
delimiter between the separate items that make up an entry.  The end of
any line in the Zone File can end with a comment.  The comment starts
with a ";" (semicolon).

The following entries are defined:

    <blank>[<comment>]

    $ORIGIN <domain-name> [<comment>]

    $INCLUDE <file-name> [<domain-name>] [<comment>]

    <domain-name><rr> [<comment>]

    <blank><rr> [<comment>]

Blank lines, with or without comments, are allowed anywhere in the file.

Two control entries are defined: $ORIGIN and $INCLUDE.  $ORIGIN is
followed by a domain name, and resets the current origin for relative
domain names to the stated name.  $INCLUDE inserts the named file into
the current file, and may optionally specify a domain name that sets the
relative domain name origin for the included file.  $INCLUDE may also
have a comment.  Note that a $INCLUDE entry never changes the relative
origin of the parent file, regardless of changes to the relative origin
made within the included file.

The last two forms represent RRs.  If an entry for an RR begins with a
blank, then the RR is assumed to be owned by the last stated owner.  If
an RR entry begins with a <domain-name>, then the owner name is reset.

<rr> contents take one of the following forms:

    [<TTL>] [<class>] <type> <RDATA>

    [<class>] [<TTL>] <type> <RDATA>

The RR begins with optional TTL and class fields, followed by a type and
RDATA field appropriate to the type and class.  Class and type use the
standard mnemonics, TTL is a decimal integer.  Omitted class and TTL
values are default to the last explicitly stated values.  Since type and
class mnemonics are disjoint, the parse is unique.  (Note that this
order is different from the order used in examples and the order used in
the actual RRs; the given order allows easier parsing and defaulting.)

<domain-name>s make up a large share of the data in the Zone File.
The labels in the domain name are expressed as character strings and
separated by dots.  Quoting conventions allow arbitrary characters to be
stored in domain names.  Domain names that end in a dot are called
absolute, and are taken as complete.  Domain names which do not end in a
dot are called relative; the actual domain name is the concatenation of
the relative part with an origin specified in a $ORIGIN, $INCLUDE, or as
an argument to the Zone File loading routine.  A relative name is an
error when no origin is available.

<character-string> is expressed in one or two ways: as a contiguous set
of characters without interior spaces, or as a string beginning with a "
and ending with a ".  Inside a " delimited string any character can
occur, except for a " itself, which must be quoted using \ (back slash).

Because these files are text files several special encodings are
necessary to allow arbitrary data to be loaded.  In particular:

                of the root.

@               A free standing @ is used to denote the current origin.

\X              where X is any character other than a digit (0-9), is
                used to quote that character so that its special meaning
                does not apply.  For example, "\." can be used to place
                a dot character in a label.

\DDD            where each D is a digit is the octet corresponding to
                the decimal number described by DDD.  The resulting
                octet is assumed to be text and is not checked for
                special meaning.

( )             Parentheses are used to group data that crosses a line
                boundary.  In effect, line terminations are not
                recognized within parentheses.

;               Semicolon is used to start a comment; the remainder of
                the line is ignored.

Implementations

impl<'a> Parser<'a>

pub fn new( input: impl Into<Cow<'a, str>>, path: Option<PathBuf>, origin: Option<Name>, ) -> Self

Returns a new Zone file parser

The path argument’s parent directory is used to resolve relative $INCLUDE paths. Relative $INCLUDE paths will yield an error if path is None.

pub fn parse(self) -> ParseResult<(Name, BTreeMap<RrKey, RecordSet>)>

Parse a file from the Lexer

Return

A pair of the Zone origin name and a map of all Keys to RecordSets

pub fn parse_time(ttl_str: &str) -> ParseResult<u32>

parses the string following the rules from: https://tools.ietf.org/html/rfc2308 (NXCaching RFC) and https://www.zytrax.com/books/dns/apa/time.html

default is seconds #s = seconds = # x 1 seconds (really!) #m = minutes = # x 60 seconds #h = hours = # x 3600 seconds #d = day = # x 86400 seconds #w = week = # x 604800 seconds

returns the result of the parsing or and error

Example

use hickory_proto::serialize::txt::Parser;

assert_eq!(Parser::parse_time("0").unwrap(),  0);
assert!(Parser::parse_time("s").is_err());
assert!(Parser::parse_time("").is_err());
assert_eq!(Parser::parse_time("0s").unwrap(), 0);
assert_eq!(Parser::parse_time("1").unwrap(),  1);
assert_eq!(Parser::parse_time("1S").unwrap(), 1);
assert_eq!(Parser::parse_time("1s").unwrap(), 1);
assert_eq!(Parser::parse_time("1M").unwrap(), 60);
assert_eq!(Parser::parse_time("1m").unwrap(), 60);
assert_eq!(Parser::parse_time("1H").unwrap(), 3600);
assert_eq!(Parser::parse_time("1h").unwrap(), 3600);
assert_eq!(Parser::parse_time("1D").unwrap(), 86400);
assert_eq!(Parser::parse_time("1d").unwrap(), 86400);
assert_eq!(Parser::parse_time("1W").unwrap(), 604800);
assert_eq!(Parser::parse_time("1w").unwrap(), 604800);
assert_eq!(Parser::parse_time("1s2d3w4h2m").unwrap(), 1+2*86400+3*604800+4*3600+2*60);
assert_eq!(Parser::parse_time("3w3w").unwrap(), 3*604800+3*604800);
assert!(Parser::parse_time("7102w").is_err());