NAME

Net::DNS::ZoneFile::Fast -- parse BIND8/9 zone files

SYNOPSIS

use Net::DNS::ZoneFile::Fast;

my $rr = Net::DNS::ZoneFile::Fast::parse($zone_text);

DESCRIPTION

The Net::DNS::ZoneFile::Fast module provides an ability to parse zone files that BIND8 and BIND9 use, fast. Currently it provides a single function, parse(), which returns a reference to an array of traditional Net::DNS::RR objects, so that no new API has to be learned in order to manipulate zone records.

Great care was taken to ensure that parse() does its job as fast as possible, so it is interesting to use this module to parse huge zones. As an example datapoint, it takes less than 5 seconds to parse a 2.2 MB zone with about 72000 records on an Athlon XP 2600+ box.

On the other hand, it is likely that Net::DNS::RR objects that parse() returns are going to be further processed. To make it easier to link any record back to the zone file (say, to report a logical error like infamous `CNAME and other data' back to the user, or to do a zone file modification), parse() inserts line numbering information into Net::DNS::RR objects.

The module currently understands:

$GENERATE directive

$ORIGIN directive

$TTL directive

A records

AAAA records

CNAME records

HINFO records

LOC records

MX records

NS records

PTR records

SOA records

SRV records

TXT records

Non-standard third-party modules

Net::DNS.

Exports

None.

Subroutines

parse

Parses zone data and returns a reference to an array of Net::DNS::RR objects if successful. Takes the following named (no pun intended) parameters:

text

A semi-mandatory parameter, textual contents of the zone to be parsed.

fh

A semi-mandatory parameter, a file handle from which zone contents can be read for parsing.

file

A semi-mandatory parameter, a file name with the zone to parse.

origin

An optional parameter specifying zone origin. The default is ".". A trailing "." is appended if necessary.

on_error

An optional parameter, user-defined error handler. If specified, it must be a subroutine reference, which will be called on any error. This subroutine will be passed two parameters: a line number in the zone, where the error occurred, and the error description.

soft_errors

By default, parse throws an exception on any error. Set this optional parameter to a true value to avoid this. The default is false, unless on_error is also specified, in which case it is true.

quiet

An optional parameter. By default, on any error, the error description is printed via warn(). Set quiet to a true value if you don't want this. The default is false, unless on_error is also specified, in which case it is true.

debug

An optional parameter. If set to true, will produce some debug printing. You probably don't want to use that.

One of text, fh, file must be specified. If more than one is specified at the same time, fh takes precedence over file, which takes precedence over text.

As a special case, if parse is called with a single, unnamed parameter, it is assumed to be a zone text.

If parse is unsuccessful, and does not throw an exception (because either on_error or soft_errors was specified), parse returns undef.

The returned Net::DNS::RR are normal in every respect, except that each of them has two extra keys, Line and Lines, which correspondingly are the line number in the zone text where the record starts, and the number of lines the record spans. This information can be accessed either via hash lookup ($rr->{Line}), or via an accessor method ($rr->Line).

BUGS

The parse() subroutine is not re-entrant. Plobably will never be.

There is also no guarantee that parse() will successfully parse every zone parsable by BIND, and no guarantee that BIND will parse every zone parsable by parse(). That said, parse() appears to do the right thing on around 50000 real life zones I tested it with.

COPYRIGHT AND LICENSE

Copyright 2003 by Anton Berezin and catpipe Systems ApS

"THE BEER-WARE LICENSE" (Revision 42)
<tobez@tobez.org> wrote this module.  As long as you retain this notice
you can do whatever you want with this stuff. If we meet some day, and
you think this stuff is worth it, you can buy me a beer in return.

Anton Berezin

CREDITS

This module was largely inspired by the Net::DNS::ZoneFile module by Luis E. Munoz.

Many thanks to Phil Regnauld and Luis E. Munoz for discussions.

SEE ALSO

Net::DNS(3), Net::DNS::RR(3).