Provided by: libbind-confparser-perl_0.95-5_all bug


       BIND::Conf_Parser - Parser class for BIND configuration files


               # Should really be a subclass
               use BIND::Conf_Parser;
               $p = BIND::Conf_Parser->new;
               $p->parse("server { bogus yes; };");

               # For one-shot parsing
               BIND::Conf_Parser->parse("server { bogus yes; };");


       "BIND::Conf_Parser" implements a virtual base class for parsing BIND (Berkeley Internet
       Name Domain) server version 8 (and sometimes version 9) configuration files
       ("named.conf").  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

       $p = BIND::Conf_Parser->new
           The object constructor takes no arguments.

       $p->parse_file( $filename )
           The given filename is parsed in its entirety.

       $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 "a file handle" will be used.

       $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 "a scalar"
           will be used.

       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
       new() method and use the resulting object.  All three return the object used, whether
       passed in or constructed at call-time.

       In order to make the parser useful, you must make a subclass where you override one or
       more of the following methods as appropriate:

       $self->handle_logging_category( $name, \@names )
       $self->handle_logging_channel( $name, \%options )
       $self->handle_key( $name, $algo, $secret )
       $self->handle_acl( $name, $addrmatchlist )
       $self->handle_option( $option, $argument )
       $self->handle_server( $name, \%options )
       $self->handle_trusted_key( $domain, \@key_definition)
       $self->handle_empty_zone( $name, $class, \%options )
       $self->handle_zone( $name, $class, $type, \%options )
       $self->handle_control( $socket_type, \@type_specific_data )

       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.


       A typical usage would run something like:

               # 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're 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;

       WARNING: if the subclass is defined at the end of the main program source file, the
       assignment to @ISA may need to be wrapped in a "BEGIN" block, ala

               BEGIN {
                   @ISA = qw(BIND::Conf_Parser);


       "BIND::Conf_Parser" does not perform all the syntactic checks performed by the parser in
       named itself.  For example, port numbers are not verified to be positive integers in the
       range 0 to 65535.

       The parse() method cannot be called multiple times with parts of statements.

       Comments are not passed to a callback method.

       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


       This version of "BIND::Conf_Parser" corresponds to BIND version 8.2.2 and understands the
       statements, options, and forms of that version.  Since the BIND developers have only made
       upward compatible changes to the syntax, "BIND::Conf_Parser" will correctly parse valid
       config files for previous versions of BIND.  Some support for simple version 9
       configuration files has been added, but there are probably new statements that are not yet

       A "BIND::Conf_Parser" 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 (handle_foo()) and other subclass methods should
       prefix its keys names with its own name separated by _'s. For example, a hypothetical
       "BIND::Conf_Parser::Keys" 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 "BIND::Conf_Parser").  "BIND::Conf_Parser" reserves for itself all keys
       beginning with an underbar.


       Copyright 1998-1999 Philip Guenther. All rights reserved.

       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.

       This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
       without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.