BIND::..._Parser(3pm)

✨ NAME ✨

BIND::Conf_Parser — the parser class for BIND config files, bestie. This is from the BIND::..._Parser(3pm) page in the User Contributed Perl Documentation, and yes, she eats. 💅

---

🦋 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 💖

Okay so BIND::Conf_Parser is a virtual base class — like, she doesn't do the whole job herself, she's the blueprint — for parsing BIND (Berkeley Internet Name Domain) server version 8 config files, and sometimes version 9 too. The file is named.conf, if you were wondering. 🌸

The parsing methods up in the synopsis do syntactic analysis only — they're just reading the vibes of the syntax, not judging the meaning. But here's the slay part: as each meaningful semantic chunk gets parsed, a callback method gets invoked with the parsed info. So you hook in, and she hands you the tea. 🫖

These next ones are the public entry points for the base class:

• $p = BIND::Conf_Parser->new — the object constructor. She takes no arguments, she's low maintenance like that.
• $p->parse_file( $filename ) — parses the given filename, all of it, top to bottom, no crumbs left. 🍓
• $p->parse_fh( $fh [, $filename] ) — parses the given filehandle in its entirety. You can pass an optional filename, which gets dropped into any error messages that pop up during parsing. Skip it and the default is "a file handle". Very demure.
• $p->parse( $statements [, $filename] ); — parses the given scalar in its entirety. Heads up though: partial statements get treated as a syntax error — no half-finished thoughts allowed, periodt. Optional filename again, for error messages. Skip it and the default is "a scalar".

For conveniance, those last three methods can also be called as class methods — meaning you slap the class name in there instead of a constructed object reference — and in that case they'll call the new() method themselves and use the object they made. All three of them return the object used, whether you passed it in or they built it at call-time. So considerate. 😭

Now, to actually make this parser useful, you gotta make a subclass and override one or more of these 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 )

ngl, the exact format of the data passed to those routines is not currently documented outside of the source to the class. But reportedly you'll find it "fairly natural." iykyk. 💀

---

🎀 USAGE 🎀

A typical usage would run something like this:

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

Do not skip this one bestie, she will simply not know her parents. 🙈

---

💀 BUGS 💀

Okay so, the flaws. We're being honest here, it's giving transparency. 👑

• BIND::Conf_Parser does not perform all the syntactic checks that the parser inside named itself performs. For example, port numbers are not verified to be positive integers in the range 0 to 65535. So she will let you cook and then be shocked.
• The parse() method cannot be called multiple times with parts of statements.
• Comments are not passed to a callback method. (RIP to your cute little comments, they're gone. 🪦)
• Some callbacks are invoked before the semicolon that terminates the corresponding syntactic form is actually recognized. Which means it's possible for a syntax error to not get 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. This is genuinely a gotcha — plan accordingly.

---

🌈 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. Some support for simple version 9 configuration files has been added, but there are probably new statements that are not yet recognized. She's trying her best. 🥺

A BIND::Conf_Parser object is a blessed anonymous hash. Now — in an attempt to prevent modules trampling on each other — the proposal on the table is that any subclass that requires persistent state between calls to the callback routines (handle_foo()) and other subclass methods should prefix its key 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'.

Two important key territories, bestie, memorize them:

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

---

and that's the whole page, no notes, you understood the assignment 💖✨

This lil doc is from perl v5.36.0, dated 2022-12-06 — shoutout to that vintage energy, she's still serving looks. 🎀 Byeee, go write your subclass bestie 🦋