.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "BIND::Conf_Parser 3pm"
.TH BIND::Conf_Parser 3pm "2022-12-06" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
BIND::Conf_Parser \- Parser class for BIND configuration files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\&        # Should really be a subclass
\&        use BIND::Conf_Parser;
\&        $p = BIND::Conf_Parser\->new;
\&        $p\->parse_file("/etc/named.conf");
\&        $p\->parse_fh(STDIN);
\&        $p\->parse("server 10.0.0.1 { bogus yes; };");
\&
\&        # For one\-shot parsing
\&        BIND::Conf_Parser\->parse_file("/etc/named.conf")
\&        BIND::Conf_Parser\->parse_fh(STDIN);
\&        BIND::Conf_Parser\->parse("server 10.0.0.1 { bogus yes; };");
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`BIND::Conf_Parser\*(C'\fR implements a virtual base class for parsing \s-1BIND\s0
(Berkeley Internet Name Domain) server version 8 (and sometimes version 9)
configuration files (\*(L"named.conf\*(R").  The parsing methods shown in the
synopsis perform syntactic analysis only.  As each meaningful semantic
\&'chunk' is parsed, a callback method is invoked with the parsed information.
The following methods are the public entry points for the base class:
.ie n .IP "$p = BIND::Conf_Parser\->new" 4
.el .IP "\f(CW$p\fR = BIND::Conf_Parser\->new" 4
.IX Item "$p = BIND::Conf_Parser->new"
The object constructor takes no arguments.
.ie n .IP "$p\->parse_file( $filename )" 4
.el .IP "\f(CW$p\fR\->parse_file( \f(CW$filename\fR )" 4
.IX Item "$p->parse_file( $filename )"
The given filename is parsed in its entirety.
.ie n .IP "$p\->parse_fh( $fh [, $filename] )" 4
.el .IP "\f(CW$p\fR\->parse_fh( \f(CW$fh\fR [, \f(CW$filename\fR] )" 4
.IX Item "$p->parse_fh( $fh [, $filename] )"
The given filehandle is parsed in its entirety.  An optional filename
may be given for inclusion in any error messages that are generated
during the parsing.  If it is not included a default of \*(L"a file handle\*(R"
will be used.
.ie n .IP "$p\->parse( $statements [, $filename] );" 4
.el .IP "\f(CW$p\fR\->parse( \f(CW$statements\fR [, \f(CW$filename\fR] );" 4
.IX Item "$p->parse( $statements [, $filename] );"
The given scalar is parsed in its entirety.  Partial statements will be
treated as a syntax error.  An optional filename may be given for
inclusion in any error messages that are generated during the parsing.
If it is not included a default of \*(L"a scalar\*(R" will be used.
.PP
For conveniance, the last three methods may also be called as class
methods (that is, with the class name instead of a constructed object
reference), in which case they will call \fBnew()\fR method and use the
resulting object.  All three return the object used, whether passed in
or constructed at call-time.
.PP
In order to make the parser useful, you must make a subclass where you
override one or more of the following methods as appropriate:
.ie n .IP "$self\->handle_logging_category( $name, \e@names )" 4
.el .IP "\f(CW$self\fR\->handle_logging_category( \f(CW$name\fR, \e@names )" 4
.IX Item "$self->handle_logging_category( $name, @names )"
.PD 0
.ie n .IP "$self\->handle_logging_channel( $name, \e%options )" 4
.el .IP "\f(CW$self\fR\->handle_logging_channel( \f(CW$name\fR, \e%options )" 4
.IX Item "$self->handle_logging_channel( $name, %options )"
.ie n .IP "$self\->handle_key( $name, $algo, $secret )" 4
.el .IP "\f(CW$self\fR\->handle_key( \f(CW$name\fR, \f(CW$algo\fR, \f(CW$secret\fR )" 4
.IX Item "$self->handle_key( $name, $algo, $secret )"
.ie n .IP "$self\->handle_acl( $name, $addrmatchlist )" 4
.el .IP "\f(CW$self\fR\->handle_acl( \f(CW$name\fR, \f(CW$addrmatchlist\fR )" 4
.IX Item "$self->handle_acl( $name, $addrmatchlist )"
.ie n .IP "$self\->handle_option( $option, $argument )" 4
.el .IP "\f(CW$self\fR\->handle_option( \f(CW$option\fR, \f(CW$argument\fR )" 4
.IX Item "$self->handle_option( $option, $argument )"
.ie n .IP "$self\->handle_server( $name, \e%options )" 4
.el .IP "\f(CW$self\fR\->handle_server( \f(CW$name\fR, \e%options )" 4
.IX Item "$self->handle_server( $name, %options )"
.ie n .IP "$self\->handle_trusted_key( $domain, \e@key_definition)" 4
.el .IP "\f(CW$self\fR\->handle_trusted_key( \f(CW$domain\fR, \e@key_definition)" 4
.IX Item "$self->handle_trusted_key( $domain, @key_definition)"
.ie n .IP "$self\->handle_empty_zone( $name, $class, \e%options )" 4
.el .IP "\f(CW$self\fR\->handle_empty_zone( \f(CW$name\fR, \f(CW$class\fR, \e%options )" 4
.IX Item "$self->handle_empty_zone( $name, $class, %options )"
.ie n .IP "$self\->handle_zone( $name, $class, $type, \e%options )" 4
.el .IP "\f(CW$self\fR\->handle_zone( \f(CW$name\fR, \f(CW$class\fR, \f(CW$type\fR, \e%options )" 4
.IX Item "$self->handle_zone( $name, $class, $type, %options )"
.ie n .IP "$self\->handle_control( $socket_type, \e@type_specific_data )" 4
.el .IP "\f(CW$self\fR\->handle_control( \f(CW$socket_type\fR, \e@type_specific_data )" 4
.IX Item "$self->handle_control( $socket_type, @type_specific_data )"
.PD
.PP
The exact format of the data passed to the above routines is not
currently documented outside of the source to the class, but should be
found to be fairly natural.
.SH "USAGE"
.IX Header "USAGE"
A typical usage would run something like:
.PP
.Vb 2
\&        # Define a subclass
\&        package Parser;
\&
\&        use BIND::Conf_Parser;
\&        use vars qw(@ISA);
\&        @ISA = qw(BIND::Conf_Parser);
\&
\&        # implement handle_* methods for config file statements that
\&        # we\*(Aqre interested in
\&        sub handle_option {
\&            my($self, $option, $argument) = @_;
\&            return unless $option eq "directory";
\&            $named_dir = $argument;
\&        }
\&
\&        sub handle_zone {
\&            my($self, $name, $class, $type, $options) = @_;
\&            return unless $type eq "master" && $class eq "in";
\&            $files{$name} = $options\->{file};
\&        }
\&
\&        # later, back at the ranch...
\&        package main;
\&        Parser\->parse_file("/etc/named.conf");
.Ve
.PP
\&\fI\s-1WARNING:\s0\fR if the subclass is defined at the end of the main program
source file, the assignment to \fI\f(CI@ISA\fI\fR may need to be wrapped in a
\&\f(CW\*(C`BEGIN\*(C'\fR block, ala
.PP
.Vb 3
\&        BEGIN {
\&            @ISA = qw(BIND::Conf_Parser);
\&        }
.Ve
.SH "BUGS"
.IX Header "BUGS"
\&\f(CW\*(C`BIND::Conf_Parser\*(C'\fR does not perform all the syntactic checks
performed by the parser in \fInamed\fR itself.  For example, port numbers
are not verified to be positive integers in the range 0 to 65535.
.PP
The \fBparse()\fR method cannot be called multiple times with parts of
statements.
.PP
Comments are not passed to a callback method.
.PP
Some callbacks are invoked before the semicolon that terminates the
corresponding syntactic form is actually recognized.  It is therefore
possible for a syntax error to not be detected until after a callback
is invoked for the presumably completely parsed form.  No attempt is
made to delay the invocation of callbacks to the completion of toplevel
statements.
.SH "NOTE"
.IX Header "NOTE"
This version of \f(CW\*(C`BIND::Conf_Parser\*(C'\fR corresponds to \s-1BIND\s0 version 8.2.2
and understands the statements, options, and forms of that version.
Since the \s-1BIND\s0 developers have only made upward compatible changes to
the syntax, \f(CW\*(C`BIND::Conf_Parser\*(C'\fR will correctly parse valid config files
for previous versions of \s-1BIND.\s0  Some support for simple version 9
configuration files has been added, but there are probably new statements
that are not yet recognized.
.PP
A \f(CW\*(C`BIND::Conf_Parser\*(C'\fR object is a blessed anonymous hash.  In an
attempt to prevent modules trampling on each other I propose that any
subclass that requires persistent state between calls to the callback
routines (\fBhandle_foo()\fR) and other subclass methods should prefix its
keys names with its own name separated by _'s. For example, a
hypothetical \f(CW\*(C`BIND::Conf_Parser::Keys\*(C'\fR module would keep data under
keys that started with 'bind_conf_parser_keys_', e.g.,
\&'bind_conf_parser_keys_key_count'.  The 'state' key is reserved for use
by application specific one-shot parsers (this is expected to encompass
most uses of \f(CW\*(C`BIND::Conf_Parser\*(C'\fR).  \f(CW\*(C`BIND::Conf_Parser\*(C'\fR reserves for
itself all keys beginning with an underbar.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 1998\-1999 Philip Guenther. All rights reserved.
.PP
This library is free software; you can redistribute it and/or This
program is free software; redistribution and modification in any form
is explicitly permitted provided that all versions retain this
copyright notice and the following disclaimer.
.PP
This library is distributed in the hope that it will be useful, but
\&\s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0