Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
BIND::Conf_Parser(3)  User Contributed Perl Documentation BIND::Conf_Parser(3)

NAME
       BIND::Conf_Parser - Parser class	for BIND configuration files

SYNOPSIS
	       # 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; };");

DESCRIPTION
       "BIND::Conf_Parser" implements a	virtual	base class for parsing BIND
       (Berkeley Internet Name Domain) server version 8	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 class:

       $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.

USAGE
       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;
	       Parser->parse_file("/etc/named.conf");

       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);
	       }

BUGS
       "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 intergers 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 completly parsed form.  No	attempt	is
       made to delay the invocation of callbacks to the	completion of toplevel
       statements.

NOTE
       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.

       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 persistant 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
       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.

perl v5.32.0			  1999-10-21		  BIND::Conf_Parser(3)

NAME | SYNOPSIS | DESCRIPTION | USAGE | BUGS | NOTE | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=BIND::Conf_Parser&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help