The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Unix-Conf-Bind8-0.3
River stage zero No dependents
++
/ Unix::Conf::Bind8::Conf

NAME

Unix::Conf::Bind8::Conf - Front end for a suite of classes for manipulating a Bind8 style configuration file.

SYNOPSIS

    my ($conf, $obj, $ret);

    $conf = Unix::Conf::Bind8->new_conf (
        FILE            => 'named.conf',
        SECURE_OPEN     => '/etc/named.conf',
    ) or $conf->die ("couldn't create `named.conf'");

    #
    # All directives have corrresponding new_*, get_*, delete_*
    # methods
    #

    $obj = $conf->new_zone (
        NAME    => 'extremix.net',
        TYPE    => 'master',
        FILE    => 'db.extremix.net',
    ) or $obj->die ("couldn't create zone `extremix.net'");

    # For objects that have a name attribute, name is to
    # be specified, otherwise no arguments are needed.
    $obj = $conf->get_zone ('extremix.net')
        or $obj->die ("couldn't get zone `extremix.net'");

    $obj = $conf->get_options ()
        or $obj->die ("couldn't get options");

    # For objects that have a name attribute, name is to
    # be specified, otherwise no arguments are needed.
    $obj = $conf->delete_zone ('extremix.net')
        or $obj->die ("couldn't delete zone `extremix.net'");

    $obj = $conf->delete_options ()
        or $obj->die ("couldn't get options");

    # directives that have a name attribute, have iterator
    # methods
    printf ("Zones defined in %s:\n", $conf->fh ());
    for my $zone ($conf->zones ()) {
        printf ("%s\n", $zone->name ();
    }

    printf ("Directives defined in %s:\n", $conf->fh ());
    for my $dir ($conf->directives ()) {
        print ("$dir\n");
    }

    $db = $conf->get_db ('extremix.net')
        or $db->die ("couldn't get db for `extremix.net'");

DESCRIPTION

This class has interfaces for the various class methods of the classes that reside beneath Unix::Conf::Bind8::Conf. This class is an internal class and should not be accessed directly. Methods in this class can be accessed through a Unix::Conf::Bind8::Conf object which is returned by Unix::Conf::Bind8->new_conf ().

METHODS

new ()
 Arguments
 FILE         => 'path of the configuration file',
 SECURE_OPEN  => 0/1,       # default 1 (enabled)

Class constructor. Creates a new Unix::Conf::Bind8::Conf object. The constructor parses the Bind8 file specified by FILE and contains subobjects representing various directives like options, logging, zone, acl etc. Direct use of this constructor is deprecated. Use Unix::Conf::Bind8->new_conf () instead. Returns a Unix::Conf::Bind8::Conf object on success, or an Err object on failure.

fh ()

Object method. Returns the ConfIO object representing the configuration file.

parse_errors ()

Object method. Returns a list of Err objects, created during the parse of the conf file. There represent warnings generated.

directives ()
 Arguments
 SCALAR         # Optional

Object method. Returns defined directives (comments too, if argument is defined). When called in a list context, returns all defined directives. Iterates over defined directives, when called in a scalar method. Returns `undef' at the end of one iteration, and starts over if called again.

NOTE: This method returns objects which represent directives. Make sure that the variable holding these objects is undef'ed or goes out of scope before or at the same time as the one holding the invocant. For example if you hold an Include object, while the parent Conf object has been released and then the code tries to create a new Conf object for the same conf file, it will return with an error, because the include file is still open and locked as you hold the Include object.

Also this method returns only those directives that are defined in the invocant Conf object and not those in embedded objects.

new_comment ()
 Arguments
                  # WARG is to be provided only in case WHERE eq 'BEFORE 
                  # or WHERE eq 'AFTER'

Object method. Creates a Unix::Conf::Bind8::Conf::Comment object, links it in the invocant Conf object and returns it, on success, an Err object otherwise. Such directives are used to hold comments between two directives.

new_options ()
 Arguments
 SUPPORTED-OPTION-NAME-IN-CAPS => value    
 WHERE         => 'FIRST'|'LAST'|'BEFORE'|'AFTER'
 WARG          => Unix::Conf::Bind8::Conf::Directive subclass object
                  # WARG is to be provided only in case WHERE eq 'BEFORE 
                  # or WHERE eq 'AFTER'

Object Method. Refer to Unix::Conf::Bind8::Conf::Options for supported options. The arguments should be same as expected by various the various methods of Unix::Conf::Bind8::Conf::Options. Creates a Unix::Conf::Bind8::Conf::Options object, links it in the invocant Conf object and returns it, on success, an Err object on otherwise.

get_options ()

Object method. Returns the Unix::Conf::Bind8::Conf::Options object if defined (either through a call to new_options or one created when the configuration file is parsed) or Err if none is defined.

delete_options ()

Object method Deletes the defined (either through a call to new_options or one created when the configuration file is parsed) Unix::Conf::Bind8::Conf::Options object. Returns true if a Unix::Conf::Bind8::Conf::Options object is present, an Err object otherwise.

new_logging ()
 Arguments
 CHANNELS   => [
    { 
           NAME             => 'channel-name1',
           OUTPUT           => 'value',      # syslog|file|null
           SEVERITY         => 'severity',   # if OUTPUT eq 'syslog'
           FILE             => 'path',       # if OUTPUT eq 'file'
           'PRINT-TIME'     => 'value',      # 'yes|no'
           'PRINT-SEVERITY' => 'value',      # 'yes|no'
           'PRINT-CATEGORY' => 'value',      # 'yes|no'
   },
 ],
 CATEGORIES  => [
      [ category1        => [ qw (channel1 channel2) ],
      [ category2        => [ qw (channel1 channel2) ],
 ],
 WHERE         => 'FIRST'|'LAST'|'BEFORE'|'AFTER'
 WARG          => Unix::Conf::Bind8::Conf::Directive subclass object
                  # WARG is to be provided only in case WHERE eq 'BEFORE 
                  # or WHERE eq 'AFTER'

Object method. Creates a new Unix::Conf::Bind8::Conf::Logging object, links it to the invocant Conf object and returns it, on success, an Err object otherwise.

get_logging ()

Object method. Returns the Unix::Conf::Bind8::Logging object if defined (either through a call to new_logging () or one created when parsing the configuration file), an Err object otherwise.

delete_logging ()

Object method. Deletes the Unix::Conf::Bind8::Logging object if defined (either through a call to new_logging () or one created when parsing the configuration file) and returns true, or returns an Err object otherwise.

new_trustedkeys ()
 Arguments
 KEYS   => [ domain flags protocol algorithm key ]
 or
 KEYS   => [ [ domain flags protocol algorithm key ], [..] ]
 WHERE  => 'FIRST'|'LAST'|'BEFORE'|'AFTER'
 WARG   => Unix::Conf::Bind8::Conf::Directive subclass object
                  # WARG is to be provided only in case WHERE eq 'BEFORE 
                  # or WHERE eq 'AFTER'

Object method. Creates a new Unix::Conf::Bind8::Conf::Trustedkeys object, links it in the invocant Conf object and returns it if successful, an Err object otherwise.

get_trustedkeys ()

Object method. Returns the Unix::Conf::Bind8::Conf::Trustedkeys object if defined (either through a call to new_trustedkeys or one created when the configuration file is parsed) or Err if none is defined.

delete_trustedkeys ()

Object method Deletes the defined (either through a call to new_trustedkeys or one created when the configuration file is parsed) Unix::Conf::Bind8::Conf::Trustedkeys object. Returns true if a Unix::Conf::Bind8::Conf::Trustedkeys object is present, an Err object otherwise.

new_controls ()
 Arguments
 UNIX   => [ PATH, PERM, OWNER, GROUP ],
 INET   => [ ADDR, PORT, ALLOW ]
 WHERE  => 'FIRST'|'LAST'|'BEFORE'|'AFTER'
 WARG   => Unix::Conf::Bind8::Conf::Directive subclass object
                  # WARG is to be provided only in case WHERE eq 'BEFORE 
                  # or WHERE eq 'AFTER'

Object method. ALLOW in INET can either be an Acl object or an anonymous array of elements. Creates a new Unix::Conf::Bind8::Conf::Controls object, links it in the invocant Conf object if successful, and returns it, an Err object otherwise.

get_controls ()

Object method. Returns the Unix::Conf::Bind8::Conf::Controls object if defined (either through a call to new_trustedkeys or one created when the configuration file is parsed) or Err if none is defined.

delete_controls ()

Object method Deletes the defined (either through a call to new_trustedkeys or one created when the configuration file is parsed) Unix::Conf::Bind8::Conf::Controls object. Returns true if a Unix::Conf::Bind8::Conf::Controls object is present, an Err object otherwise.

new_zone ()
 Arguments
 NAME          => 'zone-name',
 CLASS         => 'zone-class',        # in|hs|hesiod|chaos
 TYPE          => 'zone-type',         # master|slave|forward|stub|hint
 FILE          => 'records-file',
 MASTERS       => [ qw (10.0.0.1 10.0.0.2) ],
 FORWARD       => 'value',             # yes|no
 FORWARDERS    => [ qw (192.168.1.1 192.168.1.2) ],
 CHECK-NAMES   => 'value'              # fail|warn|ignore
 ALLOW-UPDATE  => Unix::Conf::Bind8::Conf::Acl object,
 ALLOW-QUERY   => Unix::Conf::Bind8::Conf::Acl object,
 ALLOW-TRANSFER=> Unix::Conf::Bind8::Conf::Acl object,
 NOTIFY        => 'value,              # yes|no
 ALSO-NOTIFY   => [ qw (10.0.0.3) ],
 WHERE         => 'FIRST'|'LAST'|'BEFORE'|'AFTER'
 WARG          => Unix::Conf::Bind8::Conf::Directive subclass object
                  # WARG is to be provided only in case WHERE eq 'BEFORE 
                  # or WHERE eq 'AFTER'

Object method. Creates and returns a new Unix::Conf::Bind8::Conf::Zone object, links it in the invocant Conf object, and returns it, on success, an Err object otherwise.

get_zone ()
 Arguments
 'ZONE-NAME',

Object method. Returns the Unix::Conf::Bind8::Conf::Zone object representing ZONE-NAME if defined (either through a call to new_zone () or one created when parsing the configuration file), an Err object otherwise.

delete_zone ()
 Arguments
 'ZONE-NAME',

Object method. Deletes the Unix::Conf::Bind8::Conf::Zone object representing ZONE-NAME if defined (either through a call to new_zone () or one created when parsing the configuration file) and returns true, or returns an Err object otherwise.

zones ()
 Arguments
 ALL            # Optional

Object method. Iterates through a list of defined Unix::Conf::Bind8::Conf::Zone objects (either through a call to new_zone () or ones created when parsing the configuration file), returning one at a time when called in scalar context, or a list of all objects when called in list context. Argument ALL can either be 0, no, 1, or yes. When ALL is 1 or 'yes', it returns all defined Zone objects across files. Else only those defined in the invocant are returned.

new_acl ()
 Arguments
 NAME      => 'acl-name',                               # Optional
 ELEMENTS  => [ qw (10.0.0.1 10.0.0.2 192.168.1.0/24) ],
 WHERE     => 'FIRST'|'LAST'|'BEFORE'|'AFTER'
 WARG      => Unix::Conf::Bind8::Conf::Directive subclass object
                  # WARG is to be provided only in case WHERE eq 'BEFORE 
                  # or WHERE eq 'AFTER'

Object method. Creates a new Unix::Conf::Bind8::Conf::Acl object, links it in the invocant Conf object, on success, an Err object otherwise.

get_acl ()
 Arguments
 'ACL-NAME',

Object method. Returns the Unix::Conf::Bind8::Conf::Acl object representing 'ACL-NAME' if defined (either through a call to new_acl or one created when the configuration file is parsed), an Err object otherwise.

delete_acl ()
 Arguments
 'ACL-NAME',

Object method. Deletes the Unix::Conf::Bind8::Conf::Acl object representing 'ACL-NAME' if defined (either through a call to new_acl or one created when the configuration file is parsed) and returns true, or returns an Err object otherwise.

acls ()
 Arguments
 ALL            # Optional

Object method. Iterates through the list of defined Unix::Conf::Bind8::Conf::Acl objects (either through a call to new_acl or ones created when parsing the file, returning an object at a time when called in scalar context, or a list of all objects when called in list context. Argument ALL can either be 0, no, 1, or yes. When ALL is 1 or 'yes', it returns all defined Acl objects across files. Else only those defined in the invocant are returned.

new_key
 Arguments
 NAME       => scalar,
 ALGORITHM  => scalar,  # number
 SECRET     => scalar,  # quoted string
 WHERE      => 'FIRST'|'LAST'|'BEFORE'|'AFTER'
 WARG       => Unix::Conf::Bind8::Conf::Directive subclass object
                  # WARG is to be provided only in case WHERE eq 'BEFORE 
                  # or WHERE eq 'AFTER'

Object method. Creates a new Unix::Conf::Bind8::Conf::Key object links it in the invocant Conf object and returns it, on success, an Err object on failure.

get_key ()
 Arguments
 'KEY-NAME',

Object method. Returns the Unix::Conf::Bind8::Conf::Key object representing 'KEY-NAME' if defined (either through a call to new_key or one created when the configuration file is parsed), an Err object otherwise.

delete_key ()
 Arguments
 'KEY-NAME',

Object method. Deletes the Unix::Conf::Bind8::Conf::Key object representing 'KEY-NAME' if defined (either through a call to new_key or one created when the configuration file is parsed) and returns true, or returns an Err object otherwise.

keys ()
 Arguments
 ALL            # Optional

Object method. Iterates through the list of defined Unix::Conf::Bind8::Conf::Key objects (either through a call to new_key or ones created when parsing the file, returning an object at a time when called in scalar context, or a list of all objects when called in list context. Argument ALL can either be 0, no, 1, or yes. When ALL is 1 or 'yes', it returns all defined Key objects across files. Else only those defined in the invocant are returned.

new_server ()
 Arguments
 NAME           => scalar,
 BOGUS          => scalar,      # Optional
 TRANSFERS      => scalar,      # Optional
 TRANSFER-FORMAT=> scalar,      # Optional
 KEYS           => [elements ], # Optional
 WHERE          => 'FIRST'|'LAST'|'BEFORE'|'AFTER'
 WARG           => Unix::Conf::Bind8::Conf::Directive subclass object
                       # WARG is to be provided only in case WHERE eq 'BEFORE 
                       # or WHERE eq 'AFTER'

Object method. Creates a new Unix::Conf::Bind8::Conf::Server object, links it in the invocant Conf object and returns it, on success, an Err object otherwise.

get_server ()
 Arguments
 'SERVER-NAME',

Object method. Returns the Unix::Conf::Bind8::Conf::Server object representing 'SERVER-NAME' if defined (either through a call to new_server or one created when the configuration file is parsed), an Err object otherwise.

delete_server ()
 Arguments
 'SERVER-NAME',

Object method. Deletes the Unix::Conf::Bind8::Conf::Server object representing 'SERVER-NAME' if defined (either through a call to new_server or one created when the configuration file is parsed) and returns true, or returns an Err object otherwise.

servers ()
 Arguments
 ALL            # Optional

Object method. Iterates through the list of defined Unix::Conf::Bind8::Conf::Server objects (either through a call to new_servers or ones created when parsing the file, returning an object at a time when called in scalar context, or a list of all objects when called in list context. Argument ALL can either be 0, no, 1, or yes. When ALL is 1 or 'yes', it returns all defined Key objects across files. Else only those defined in the invocant are returned.

new_include ()
 Arguments
 FILE         => 'path of the configuration file',
 SECURE_OPEN  => 0/1,        # default 1 (enabled)
 WHERE        => 'FIRST'|'LAST'|'BEFORE'|'AFTER'
 WARG         => Unix::Conf::Bind8::Conf::Directive subclass object
                  # WARG is to be provided only in case WHERE eq 'BEFORE 
                  # or WHERE eq 'AFTER'

Object method. Creates a new Unix::Conf::Bind8::Conf::Include object which contains an Unix::Conf::Bind8::Conf object representing FILE, links it in the invocant Conf object and returns it, on success, an Err object otherwise.

get_include ()
 Arguments
 'INCLUDE-NAME',

Object method. Returns the Unix::Conf::Bind8::Conf::Include object representing INCLUDE-NAME if defined (either through a call to new_include () or one created when parsing the configuration file), an Err object otherwise.

get_include_conf ()
 Arguments
 'INCLUDE-NAME'

Object method. Return the Unix::Conf::Bind8::Conf object inside a defined Unix::Conf::Bind8::Conf::Include of name INCLUDE-NAME.

delete_include ()
 Arguments
 'INCLUDE-NAME',

Object method. Deletes the Unix::Conf::Bind8::Conf::Include object representing INCLUDE-NAME if defined (either through a call to new_include () or one created when parsing the configuration file) and returns true, or returns an Err object otherwise.

includes ()
 Arguments
 ALL            # Optional

Object method. Iterates through defined Unix::Conf::Bind8::Conf::Include objects (either through a call to new_include () or ones created when parsing the configuration file), returning one at a time when called in scalar context, or a list of all defined includes when called in list context. Argument ALL can either be 0, no, 1, or yes. When ALL is 1 or 'yes', it returns all defined Include objects across files. Else only those defined in the invocant are returned.

get_db ()
 Arguments
 'ZONE-NAME',
 0/1,        # SECURE_OPEN (OPTIONAL). If not specified the value
             # for the ConfIO object is taken.

Object method Returns a Unix::Conf::Bind8::DB object representing the records file for zone 'ZONE-NAME' if successful, an Err object otherwise.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 116:

=over without closing =back