Bind8/Conf.pm

filter: Statementstmt 47.3% 45 / 95 Branchbran 0.0% 0 / 22 Conditioncond 0.0% 0 / 8 MC/DCmcdc 0.0% 0 / 5 Subroutinesub 78.9% 15 / 19 Podpod n/a totaltotal 40.2% 60 / 149 CC 15 SCAR 35.0
CC
15
Cov
36%
new
90.0
DESTROY
42.0
dirty
6.0
CRAP 33.1
« Bind8/Conf/Include.pm ↑ Summary Bind8/DB.pm »
1 # Bind8 Conf class.
2 #
3 # Copyright Karthik Krishnamurthy <karthik.k@extremix.net>
4  
5 =head1 NAME
6  
7 Unix::Conf::Bind8::Conf - Front end for a suite of classes for manipulating
8 a Bind8 style configuration file.
9  
10 =head1 SYNOPSIS
11  
12 my ($conf, $obj, $ret);
13  
14 $conf = Unix::Conf::Bind8->new_conf (
15 FILE => 'named.conf',
16 SECURE_OPEN => '/etc/named.conf',
17 ) or $conf->die ("couldn't create `named.conf'");
18  
19 #
20 # All directives have corrresponding new_*, get_*, delete_*
21 # methods
22 #
23  
24 $obj = $conf->new_zone (
25 NAME => 'extremix.net',
26 TYPE => 'master',
27 FILE => 'db.extremix.net',
28 ) or $obj->die ("couldn't create zone `extremix.net'");
29  
30 # For objects that have a name attribute, name is to
31 # be specified, otherwise no arguments are needed.
32 $obj = $conf->get_zone ('extremix.net')
33 or $obj->die ("couldn't get zone `extremix.net'");
34  
35 $obj = $conf->get_options ()
36 or $obj->die ("couldn't get options");
37  
38 # For objects that have a name attribute, name is to
39 # be specified, otherwise no arguments are needed.
40 $obj = $conf->delete_zone ('extremix.net')
41 or $obj->die ("couldn't delete zone `extremix.net'");
42  
43 $obj = $conf->delete_options ()
44 or $obj->die ("couldn't get options");
45  
46 # directives that have a name attribute, have iterator
47 # methods
48 printf ("Zones defined in %s:\n", $conf->fh ());
49 for my $zone ($conf->zones ()) {
50 printf ("%s\n", $zone->name ();
51 }
52  
53 printf ("Directives defined in %s:\n", $conf->fh ());
54 for my $dir ($conf->directives ()) {
55 print ("$dir\n");
56 }
57  
58 $db = $conf->get_db ('extremix.net')
59 or $db->die ("couldn't get db for `extremix.net'");
60  
61 =head1 DESCRIPTION
62  
63 This class has interfaces for the various class methods of the classes that
64 reside beneath Unix::Conf::Bind8::Conf. This class is an internal class and
65 should not be accessed directly. Methods in this class can be accessed
66 through a Unix::Conf::Bind8::Conf object which is returned by
67 Unix::Conf::Bind8->new_conf ().
68  
69 =head1 METHODS
70  
71 =cut
72  
73 package Unix::Conf::Bind8::Conf;
74  
75 10 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
76 10 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
77  
78 10 ▶use Unix::Conf;
Subroutine BEGIN: called CC=1 SCAR=0.0
79 10 ▶use Unix::Conf::Bind8::Conf::Comment;
Subroutine BEGIN: called CC=1 SCAR=0.0
80 10 ▶use Unix::Conf::Bind8::Conf::Lib;
Subroutine BEGIN: called CC=1 SCAR=0.0
81 10 ▶use Unix::Conf::Bind8::Conf::Logging;
Subroutine BEGIN: called CC=1 SCAR=0.0
82 10 ▶use Unix::Conf::Bind8::Conf::Options;
Subroutine BEGIN: called CC=1 SCAR=0.0
83 10 ▶use Unix::Conf::Bind8::Conf::Acl;
Subroutine BEGIN: called CC=1 SCAR=0.0
84 10 ▶use Unix::Conf::Bind8::Conf::Zone;
Subroutine BEGIN: called CC=1 SCAR=0.0
85 10 ▶use Unix::Conf::Bind8::Conf::Trustedkeys;
Subroutine BEGIN: called CC=1 SCAR=0.0
86 10 ▶use Unix::Conf::Bind8::Conf::Key;
Subroutine BEGIN: called CC=1 SCAR=0.0
87 10 ▶use Unix::Conf::Bind8::Conf::Controls;
Subroutine BEGIN: called CC=1 SCAR=0.0
88 10 ▶use Unix::Conf::Bind8::Conf::Server;
Subroutine BEGIN: called CC=1 SCAR=0.0
89 10 ▶use Unix::Conf::Bind8::Conf::Include;
Subroutine BEGIN: called CC=1 SCAR=0.0
90 10 ▶use Unix::Conf::Bind8::Conf::Lib;
Subroutine BEGIN: called CC=1 SCAR=0.0
91  
92 #
93 # Unix::Conf::Bind8::Conf object
94 # The object is a reference to reference to an anonymous hash.
95 # The anonymous hash is referred to here as CONFDS for conf datastructure.
96 # => {
97 # ROOT => CONFDS of the first Conf object in the tree.
98 # FH
99 # HEAD
100 # TAIL
101 # LOGGING
102 # OPTION
103 # ACL
104 # ZONE
105 # INCLUDE
106 # ALL_LOGGING defined only in a ROOT node
107 # ALL_OPTION defined only in a ROOT node
108 # ALL_ACL defined only in a ROOT node
109 # ALL_ZONE defined only in a ROOT node
110 # ALL_INCLUDE defined only in a ROOT node
111 # ERRORS
112 # DIRTY
113 # }
114 #
115  
116 =over 4
117  
118 =item new ()
119  
120 Arguments
121 FILE => 'path of the configuration file',
122 SECURE_OPEN => 0/1, # default 1 (enabled)
123  
124 Class constructor.
125 Creates a new Unix::Conf::Bind8::Conf object. The constructor parses the
126 Bind8 file specified by FILE and contains subobjects representing various
127 directives like options, logging, zone, acl etc. Direct use of this
128 constructor is deprecated. Use Unix::Conf::Bind8->new_conf () instead.
129 Returns a Unix::Conf::Bind8::Conf object on success, or an Err object on
130 failure.
131  
132 =cut
133  
134 sub new
135 0 ▶{
Subroutine new: not called CC=9 SCAR=45.0
136 0 my $invocant = shift ();
137 0 my %args = @_;
138 0 my ($new, $conf_fh, $ret);
139  
140 # get and validate arguments
141 0 ▶ my $conf_path = $args{FILE} || return (Unix::Conf->_err ('new', "FILE not specified"));
Condition0%0/2
$args{'FILE'} || (return 'Unix::Conf'->_err('new', 'FILE not specified'))
l!l
00
MC/DC0%0/1
$args{'FILE'} || (return 'Unix::Conf'->_err('new', 'FILE not specified'))
$args{'FILE'}
Truth table0%0/2
A
A= $args{'FILE'}
Aresult
11
00
142 0 ▶ my $secure_open = defined ($args{SECURE_OPEN}) ? $args{SECURE_OPEN} : 1;
Branch: 1 branch
BranchTrueFalseTotal
defined $args{'SECURE_OPEN'} ? : 0 0 0
143 0 ▶ $conf_fh = Unix::Conf->_open_conf (
Branch: 1 branch
BranchTrueFalseTotal
$conf_fh = "Unix::Conf"->_open_conf("NAME", $conf_path, "SECURE_OPEN", $secure_open) or return $conf_fh 0 0 0
144 NAME => $conf_path,
145 SECURE_OPEN => $secure_open,
146 ) or return ($conf_fh);
147  
148 0 my $head = { PREV => undef };
149 0 my $tail = { NEXT => undef };
150 0 $head->{NEXT} = $tail;
151 0 $tail->{PREV} = $head;
152  
153 0 $new = bless (
154 \{
155 DIRTY => 0,
156 ITR => 0,
157 DIRARR => [],
158 HEAD => $head,
159 TAIL => $tail,
160 ERRORS => [],
161 },
162 );
163 0 $$new->{FH} = $conf_fh;
164 # in case no ROOT was passed then we were not called from
165 # Unix::Conf::Bind8::Conf::Include->new (). So set ourself
166 # as ROOT.
167 # NOTE: we set the hashref to which the object (a scalar ref)
168 # points to as the value for ROOT, to solve the circular ref problem
169 0 ▶ $ret = $new->__root ($args{ROOT} ? $args{ROOT} : $$new) or return ($ret);
Branch: 2 branches
BranchTrueFalseTotal
$ret = $new->__root($args{"ROOT"} ? $args{"ROOT"} : $$new) or return $ret 0 0 0
$args{'ROOT'} ? : 0 0 0
170 0 ▶ eval { $ret = $new->__parse_conf () } or do {
Branch: 1 branch
BranchTrueFalseTotal
eval { do { $ret = $new->__parse_conf } } or do { return $@ if ref $@ and UNIVERSAL::isa($@, "Unix::Conf::Err"); return "Unix::Conf"->_err("new", "Parse of $conf_fh failed because\n$@") } 0 0 0
171 0 ▶ return ($@) if (ref ($@) && UNIVERSAL::isa ($@, 'Unix::Conf::Err'));
Branch: 1 branch
BranchTrueFalseTotal
if ref $@ and UNIVERSAL::isa($@, "Unix::Conf::Err") 0 0 0
Condition0%0/3
ref $@ and UNIVERSAL::isa($@, "Unix::Conf::Err")
!ll&&!rl&&r
000
MC/DC0%0/2
ref $@ and UNIVERSAL::isa($@, "Unix::Conf::Err")
ref $@ UNIVERSAL::isa($@, "Unix::Conf::Err")
Truth table0%0/3
A and B
A= ref $@B= UNIVERSAL::isa($@, "Unix::Conf::Err")
ABresult
0X0
100
111
172 # if a run time perl error has been trapped, make it into an Err obj.
173 return (
174 0 Unix::Conf->_err ('new', "Parse of $conf_fh failed because\n$@")
175 );
176 };
177 0 return ($new);
178 }
179  
180 # Class destructor.
181 sub DESTROY
182 0 ▶{
Subroutine DESTROY: not called CC=6 SCAR=37.4
183 0 my $self = $_[0];
184 0 my $dirty = $self->dirty ();
185 #print sprintf ("destructor for conf object (%s:%x)\n", $self->fh (), $self);
186 0 my $file;
187  
188 # make sure we destroy DIRARR (used for iteration first)
189 0 undef ($$self->{DIRARR});
190  
191 # go through the array of directives and create a string representing
192 # the whole file.
193 0 my ($ptr, $tmp, $tws);
194 0 $ptr = $$self->{HEAD}{NEXT};
195 0 $$self->{HEAD}{NEXT} = undef;
196 0 ▶ while ($ptr && $ptr ne $$self->{TAIL}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($ptr and $ptr ne $$self->{"TAIL"}) 0 0 0
Condition0%0/3
$ptr and $ptr ne $$self->{"TAIL"}
!ll&&!rl&&r
000
MC/DC0%0/2
$ptr and $ptr ne $$self->{"TAIL"}
$ptr $ptr ne $$self->{"TAIL"}
Truth table0%0/3
A and B
A= $ptrB= $ptr ne $$self->{"TAIL"}
ABresult
0X0
100
111
197 0 ▶ if ($dirty) {
Branch: 1 branch
BranchTrueFalseTotal
if ($dirty) 0 0 0
198 0 $file .= ${$ptr->_rstring ()};
199 0 $tws = $ptr->_tws ();
200 0 ▶ $file .= defined ($tws) ? $$tws : "\n";
Branch: 1 branch
BranchTrueFalseTotal
defined $tws ? : 0 0 0
201 }
202 0 $tmp = $ptr;
203 0 $ptr = $ptr->{NEXT};
204 # remove circular references
205 0 $tmp->{NEXT} = undef;
206 0 $tmp->{PREV} = undef;
207 }
208 # clear TAIL's prev pointer too.
209 0 $ptr->{PREV} = undef;
210  
211 # set the string as the contents of the ConfIO object.
212 0 ▶ $$self->{FH}->set_scalar (\$file) if ($file);
Branch: 1 branch
BranchTrueFalseTotal
if $file 0 0 0
213 # ensure that we release our own Conf file first.
214 0 undef ($$self->{FH});
215 # then include directives
216 0 undef ($$self->{INCLUDE});
217 0 undef ($$self->{ALL_INCLUDE});
218 # then the rest
219 0 undef (%{$$self});
220 0 undef ($self);
221 }
222  
223 =item fh ()
224  
225 Object method.
226 Returns the ConfIO object representing the configuration file.
227  
228 =cut
229  
230 sub fh
231 0 ▶{
Subroutine fh: not called CC=1 SCAR=6.9
232 0 my $self = $_[0];
233 0 return ($$self->{FH});
234 }
235  
236 sub dirty
237 0 ▶{
Subroutine dirty: not called CC=2 SCAR=17.9
238 0 my ($self, $dirty) = @_;
239  
240 0 ▶ if (defined ($dirty)) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $dirty) 0 0 0
241 0 $$self->{DIRTY} = $dirty;
242 0 return (1);
243 }
244 0 return ($$self->{DIRTY});
245 }
246  
247 #
248 # The _add_dir* routines, insert an object into the per Conf hash and the
249 # ALL_* hash which resides in the ROOT Conf.
250  
251 for my $dir qw (zone acl key server include comment) {
252 no strict 'refs';
253  
254 my $_add = "_add_$dir";
255 my $_get = "_get_$dir";
256 my $_del = "_del_$dir";
257 my $new = "new_$dir";
258 my $get = "get_$dir";
259 my $delete = "delete_$dir";
260 my $itr = "${dir}s";
261  
262 *$_add = sub {
263 my $obj = $_[0];
264 my ($root, $parent, $name);
265 $parent = $obj->_parent () or return ($root);
266 $root = $parent->{ROOT};
267 $name = $obj->name () or return ($name);
268 return (Unix::Conf->_err ("$_add", "$dir `$name' already defined"))
269 if ($root->{"ALL_\U$dir\E"}{$name});
270 # store in per Conf hash as well as in the ROOT Conf object
271 $parent->{"\U$dir\E"}{$name} = $root->{"ALL_\U$dir\E"}{$name} = $obj;
272 return (1);
273 };
274  
275 # we get from the ROOT ALL_DIR* hash, so we can get a directive
276 # defined in any Conf file from any Conf object.
277 # maybe it is better to restrict _get_* to directives defined in
278 # that file only.
279 # added later. validation routines in Unix::Conf::Bind8::Conf::Lib
280 # get confds structures and need to validate names defined throughout.
281 # some more thought needed.
282 *$_get = sub {
283 my ($confds, $name) = @_;
284 return (Unix::Conf->_err ("$_get", "$dir `$name' not defined"))
285 unless ($confds->{ROOT}{"ALL_\U$dir\E"}{$name});
286 return ($confds->{ROOT}{"ALL_\U$dir\E"}{$name});
287 };
288  
289 *$_del = sub {
290 my $obj = $_[0];
291 my ($root, $parent, $name);
292 $parent = $obj->_parent () or return ($root);
293 $root = $parent->{ROOT};
294 $name = $obj->name () or return ($name);
295 return (Unix::Conf->_err ("$_del", "$dir `$name' not defined"))
296 unless ($root->{"ALL_\U$dir\E"}{$name});
297 delete ($root->{"ALL_\U$dir\E"}{$name});
298 delete ($parent->{"\U$dir\E"}{$name});
299 return (1);
300 };
301  
302 ##################################################################
303 # PUBLIC INTERFACE #
304 ##################################################################
305  
306 if ($dir eq 'include') {
307 *$new = sub {
308 my $self = shift ();
309  
310 return (Unix::Conf->_err ("$new", "not a class constructor"))
311 unless (ref ($self));
312 my $class = "Unix::Conf::Bind8::Conf::\u$dir";
313 return ($class->new (@_, PARENT => $$self, ROOT => $self->__root ()));
314 };
315 # no real need to create this here.
316 my $get_conf = "get_include_conf";
317 *$get_conf = sub {
318 my ($self, $name) = @_;
319  
320 return (Unix::Conf->_err ("$get_conf", "not a class method"))
321 unless (ref ($self));
322 return (Unix::Conf->_err ("$get_conf", "name not specified"))
323 unless (defined ($name));
324 my $ret;
325 $ret = _get_include ($$self, $name) or return ($ret);
326 return ($ret->conf ());
327 };
328 }
329 else {
330 *$new = sub {
331 my $self = shift ();
332  
333 return (Unix::Conf->_err ("$new", "not a class constructor"))
334 unless (ref ($self));
335 my $class = "Unix::Conf::Bind8::Conf::\u$dir";
336 return ($class->new (@_, PARENT => $$self));
337 };
338 }
339
340 # no get_ and delete_, iterator methods for comment. at least for now
341 if ($dir ne 'comment') {
342 *$get = sub {
343 my ($self, $name) = @_;
344 return (Unix::Conf->_err ("$get", "not a class constructor"))
345 unless (ref ($self));
346 return (Unix::Conf->_err ("$get", "$dir name not passed"))
347 unless ($name);
348 return (&$_get($$self, $name));
349 };
350  
351 *$delete = sub {
352 my ($self, $name) = @_;
353 return (Unix::Conf->_err ("$delete", "not a class constructor"))
354 unless (ref ($_[0]));
355 return (Unix::Conf->_err ("$delete", "$dir name not passed"))
356 unless ($name);
357 my $obj;
358 $obj = &$_get($$self, $name) or return ($obj);
359 return ($obj->delete ());
360 };
361
362 *$itr = sub {
363 my ($self, $context) = @_;
364  
365 return (Unix::Conf->_err ("$delete", "not a class constructor"))
366 unless (ref ($self));
367 if ($context && __valid_yesno ($context)) {
368 return (
369 wantarray () ? values (%{$$self->{ROOT}{"ALL_\U$dir\E"}}) :
370 (each (%{$$self->{ROOT}{"ALL_\U$dir\E"}}))[1]
371 );
372 }
373 return (
374 wantarray () ? values (%{$$self->{"\U$dir\E"}}) :
375 (each (%{$$self->{"\U$dir\E"}}))[1]
376 );
377 };
378 }
379 }
380  
381 # directives that do not have names, and hence
382 # defined once only.
383 for my $dir qw (options logging trustedkeys controls) {
384 no strict 'refs';
385  
386 my $_add = "_add_$dir";
387 my $_get = "_get_$dir";
388 my $_del = "_del_$dir";
389 my $new = "new_$dir";
390 my $get = "get_$dir";
391 my $delete = "delete_$dir";
392  
393 *$_add = sub {
394 my $obj = $_[0];
395 my ($root, $parent);
396 $parent = $obj->_parent () or return ($parent);
397 $root = $parent->{ROOT};
398 return (Unix::Conf->_err ("$_add", "`$dir' already defined"))
399 if ($root->{"ALL_\U$dir\E"});
400 $root->{"ALL_\U$dir\E"} = $parent->{"\U$dir\E"} = $obj;
401 return (1);
402 };
403  
404 # we get from the ROOT ALL_DIR* hash, so we can get a directive
405 # defined in any Conf file from any Conf object.
406 # maybe it is better to restrict _get_* to directives defined in
407 # that file only.
408 *$_get = sub {
409 my $confds = $_[0];
410 return (Unix::Conf->_err ("$_get", "`$dir' not defined"))
411 unless ($confds->{ROOT}{"ALL_\U$dir\E"});
412 return ($confds->{ROOT}{"ALL_\U$dir\E"});
413 };
414  
415 $_del = "_del_$dir";
416 *$_del = sub {
417 my $obj = $_[0];
418 my ($root, $parent);
419 $parent = $obj->_parent () or return ($root);
420 $root = $parent->{ROOT};
421 return (Unix::Conf->_err ("$_del", "`$dir' not defined"))
422 unless ($root->{"ALL_\U$dir\E"});
423 delete ($root->{"ALL_\U$dir\E"});
424 delete ($parent->{"\U$dir\E"});
425 return (1);
426 };
427  
428 ##################################################################
429 # PUBLIC INTERFACE #
430 ##################################################################
431  
432 *$new = sub {
433 my $self = shift ();
434  
435 return (Unix::Conf->_err ("$new", "not a class constructor"))
436 unless (ref ($self));
437 my $class = "Unix::Conf::Bind8::Conf::\u$dir";
438 return ($class->new (@_, PARENT => $$self));
439 };
440  
441 *$get = sub {
442 return (Unix::Conf->_err ("$get", "not a class constructor"))
443 unless (ref ($_[0]));
444 return (&$_get(${$_[0]}));
445 };
446  
447 *$delete = sub {
448 my $obj;
449  
450 return (Unix::Conf->_err ("$delete", "not a class constructor"))
451 unless (ref ($_[0]));
452 $obj = &$_get(${$_[0]}) or return ($obj);
453 return ($obj->delete ());
454 };
455 }
456  
457 # ARGUMENTS:
458 # Unix::Conf::Bind8::Conf::Directive subclass instalce
459 # WHERE => ('FIRST'|'LAST'|'BEFORE'|'AFTER')
460 # WARG => Unix::Conf::Bind8::Conf::Directive subclass instance
461 # # in case WHERE =~ /('BEFORE'|'AFTER')/
462 # This routine uses the PARENT ref in an object to insert itself in the
463 # doubly linked list in the parent Unix::Conf::Bind8::Conf object.
464 sub _insert_in_list ($$;$)
465 {
466 my ($obj, $where, $arg) = @_;
467  
468 return (Unix::Conf->_err ("__insert_in_list", "`$obj' not instance of a subclass of Unix::Conf::Bind8::Conf::Directive"))
469 unless (UNIVERSAL::isa ($obj, "Unix::Conf::Bind8::Conf::Directive"));
470 return (Unix::Conf->_err ("__insert_in_list", "`$where', illegal argument"))
471 if ($where !~ /^(FIRST|LAST|BEFORE|AFTER)$/i);
472 my $conf = $obj->_parent ();
473  
474 # now insert the directive in the doubly linked list
475 # insert at the head
476 (uc ($where) eq 'FIRST') && do {
477 $obj->{PREV} = $conf->{HEAD};
478 $obj->{NEXT} = $conf->{HEAD}{NEXT};
479 $conf->{HEAD}{NEXT}{PREV} = $obj;
480 $conf->{HEAD}{NEXT} = $obj;
481 goto END;
482 };
483 # insert at tail
484 (uc ($where) eq 'LAST') && do {
485 $obj->{NEXT} = $conf->{TAIL};
486 $obj->{PREV} = $conf->{TAIL}{PREV};
487 $conf->{TAIL}{PREV}{NEXT} = $obj;
488 $conf->{TAIL}{PREV} = $obj;
489 goto END;
490 };
491  
492 return (Unix::Conf->_err ("__insert_in_list", "$where not an child of Unix::Conf::Bind8::Conf::Directive"))
493 unless (UNIVERSAL::isa ($arg, "Unix::Conf::Bind8::Conf::Directive"));
494 # before $arg
495 (uc ($where) eq 'BEFORE') && do {
496 $obj->{NEXT} = $arg;
497 $obj->{PREV} = $arg->{PREV};
498 $arg->{PREV}{NEXT} = $obj;
499 $arg->{PREV} = $obj;
500 goto END;
501 };
502 # after $arg
503 (uc ($where) eq 'AFTER') && do {
504 $obj->{NEXT} = $arg->{NEXT};
505 $obj->{PREV} = $arg;
506 $arg->{NEXT}{PREV} = $obj;
507 $arg->{NEXT} = $obj;
508 };
509 END:
510 return (1);
511 }
512  
513 # ARGUMENTS
514 # Unix::Conf::Bind8::Conf::Directive subclass object
515 # Delete object from the doubly linked list.
516 sub _delete_from_list ($)
517 {
518 my $obj = $_[0];
519  
520 return (
521 Unix::Conf->_err (
522 "__delete_from_list",
523 "`$obj' not instance of a subclass of Unix::Conf::Bind8::Conf::Directive"
524 )
525 ) unless (UNIVERSAL::isa ($obj, "Unix::Conf::Bind8::Conf::Directive"));
526 $obj->{NEXT}{PREV} = $obj->{PREV};
527 $obj->{PREV}{NEXT} = $obj->{NEXT};
528 return (1);
529 }
530  
531 sub __root
532 {
533 my ($self, $root) = @_;
534  
535 if ($root) {
536 $$self->{ROOT} = $root;
537 return (1);
538 }
539 return (
540 defined ($$self->{ROOT}) ? $$self->{ROOT} :
541 Unix::Conf->_err ('__root', "ROOT not defined")
542 );
543 }
544  
545 =item parse_errors ()
546  
547 Object method.
548 Returns a list of Err objects, created during the parse of the conf file.
549 There represent warnings generated.
550  
551 =cut
552  
553 sub parse_errors
554 {
555 my $self = $_[0];
556 return (@{$$self->{ERRORS}});
557 }
558  
559  
560 # ARGUMENTS:
561 # Unix::Conf::Err obj
562 # called by the parser to push errors messages generated during parsing.
563 sub __add_err
564 {
565 my ($self, $errobj, $lineno) = @_;
566  
567 $errobj = Unix::Conf->_err ('add_err', "argument not passed")
568 unless (defined ($errobj));
569 push (@{$$self->{ERRORS}}, $errobj);
570 }
571  
572 =item directives ()
573  
574 Arguments
575 SCALAR # Optional
576  
577 Object method.
578 Returns defined directives (comments too, if argument is defined). When
579 called in a list context, returns all defined directives. Iterates over
580 defined directives, when called in a scalar method. Returns `undef' at
581 the end of one iteration, and starts over if called again.
582  
583 NOTE: This method returns objects which represent directives. Make sure
584 that the variable holding these objects is undef'ed or goes out of scope
585 before or at the same time as the one holding the invocant. For example
586 if you hold an Include object, while the parent Conf object has been released
587 and then the code tries to create a new Conf object for the same conf file,
588 it will return with an error, because the include file is still open and locked
589 as you hold the Include object.
590  
591 Also this method returns only those directives that are defined in the invocant
592 Conf object and not those in embedded objects.
593  
594 =cut
595  
596 sub directives
597 {
598 my ($self, $nocomment) = @_;
599
600 # create list of directives only if iterator is at start
601 unless ($$self->{ITR}) {
602 undef (@{$$self->{DIRARR}});
603 for (my $ptr = $$self->{HEAD}{NEXT}; $ptr && $ptr ne $$self->{TAIL}; $ptr = $ptr->{NEXT}) {
604 next if ($nocomment && UNIVERSAL::isa ($ptr, "Unix::Conf::Bind8::Conf::Comment"));
605 push (@{$$self->{DIRARR}}, $ptr);
606 }
607 }
608  
609 if (wantarray ()) {
610 # reset iterator before returning
611 $$self->{ITR} = 0;
612 return (@{$$self->{DIRARR}})
613 }
614 # return undef on completion of one iteration
615 return () if ($$self->{ITR} && !($$self->{ITR} %= scalar (@{$$self->{DIRARR}})));
616 return (${$$self->{DIRARR}}[$$self->{ITR}++]);
617 }
618  
619  
620 =item new_comment ()
621  
622 Arguments
623 # WARG is to be provided only in case WHERE eq 'BEFORE
624 # or WHERE eq 'AFTER'
625  
626 Object method.
627 Creates a Unix::Conf::Bind8::Conf::Comment object, links it in the invocant
628 Conf object and returns it, on success, an Err object otherwise.
629 Such directives are used to hold comments between two directives.
630  
631 =cut
632  
633 =item new_options ()
634  
635 Arguments
636 SUPPORTED-OPTION-NAME-IN-CAPS => value
637 WHERE => 'FIRST'|'LAST'|'BEFORE'|'AFTER'
638 WARG => Unix::Conf::Bind8::Conf::Directive subclass object
639 # WARG is to be provided only in case WHERE eq 'BEFORE
640 # or WHERE eq 'AFTER'
641  
642 Object Method.
643 Refer to Unix::Conf::Bind8::Conf::Options for supported options. The
644 arguments should be same as expected by various the various methods of
645 Unix::Conf::Bind8::Conf::Options.
646 Creates a Unix::Conf::Bind8::Conf::Options object, links it in the invocant
647 Conf object and returns it, on success, an Err object on otherwise.
648  
649 =cut
650
651 =item get_options ()
652  
653 Object method.
654 Returns the Unix::Conf::Bind8::Conf::Options object if defined (either
655 through a call to new_options or one created when the configuration file
656 is parsed) or Err if none is defined.
657  
658 =cut
659  
660 =item delete_options ()
661  
662 Object method
663 Deletes the defined (either through a call to new_options or one created
664 when the configuration file is parsed) Unix::Conf::Bind8::Conf::Options
665 object.
666 Returns true if a Unix::Conf::Bind8::Conf::Options object is present, an
667 Err object otherwise.
668  
669 =cut
670  
671 =item new_logging ()
672  
673 Arguments
674 CHANNELS => [
675 {
676 NAME => 'channel-name1',
677 OUTPUT => 'value', # syslog|file|null
678 SEVERITY => 'severity', # if OUTPUT eq 'syslog'
679 FILE => 'path', # if OUTPUT eq 'file'
680 'PRINT-TIME' => 'value', # 'yes|no'
681 'PRINT-SEVERITY' => 'value', # 'yes|no'
682 'PRINT-CATEGORY' => 'value', # 'yes|no'
683 },
684 ],
685 CATEGORIES => [
686 [ category1 => [ qw (channel1 channel2) ],
687 [ category2 => [ qw (channel1 channel2) ],
688 ],
689 WHERE => 'FIRST'|'LAST'|'BEFORE'|'AFTER'
690 WARG => Unix::Conf::Bind8::Conf::Directive subclass object
691 # WARG is to be provided only in case WHERE eq 'BEFORE
692 # or WHERE eq 'AFTER'
693  
694 Object method.
695 Creates a new Unix::Conf::Bind8::Conf::Logging object, links it to the invocant
696 Conf object and returns it, on success, an Err object otherwise.
697  
698 =cut
699  
700 =item get_logging ()
701  
702 Object method.
703 Returns the Unix::Conf::Bind8::Logging object if defined (either through a
704 call to new_logging () or one created when parsing the configuration file),
705 an Err object otherwise.
706  
707 =cut
708  
709 =item delete_logging ()
710  
711 Object method.
712 Deletes the Unix::Conf::Bind8::Logging object if defined (either through a
713 call to new_logging () or one created when parsing the configuration file)
714 and returns true, or returns an Err object otherwise.
715  
716 =cut
717  
718 =item new_trustedkeys ()
719  
720 Arguments
721 KEYS => [ domain flags protocol algorithm key ]
722 or
723 KEYS => [ [ domain flags protocol algorithm key ], [..] ]
724 WHERE => 'FIRST'|'LAST'|'BEFORE'|'AFTER'
725 WARG => Unix::Conf::Bind8::Conf::Directive subclass object
726 # WARG is to be provided only in case WHERE eq 'BEFORE
727 # or WHERE eq 'AFTER'
728  
729 Object method.
730 Creates a new Unix::Conf::Bind8::Conf::Trustedkeys object, links it in the
731 invocant Conf object and returns it if successful, an Err object otherwise.
732  
733 =cut
734  
735 =item get_trustedkeys ()
736  
737 Object method.
738 Returns the Unix::Conf::Bind8::Conf::Trustedkeys object if defined (either
739 through a call to new_trustedkeys or one created when the configuration file
740 is parsed) or Err if none is defined.
741  
742 =cut
743  
744 =item delete_trustedkeys ()
745  
746 Object method
747 Deletes the defined (either through a call to new_trustedkeys or one created
748 when the configuration file is parsed) Unix::Conf::Bind8::Conf::Trustedkeys
749 object.
750 Returns true if a Unix::Conf::Bind8::Conf::Trustedkeys object is present, an
751 Err object otherwise.
752  
753 =cut
754  
755 =item new_controls ()
756  
757 Arguments
758 UNIX => [ PATH, PERM, OWNER, GROUP ],
759 INET => [ ADDR, PORT, ALLOW ]
760 WHERE => 'FIRST'|'LAST'|'BEFORE'|'AFTER'
761 WARG => Unix::Conf::Bind8::Conf::Directive subclass object
762 # WARG is to be provided only in case WHERE eq 'BEFORE
763 # or WHERE eq 'AFTER'
764  
765 Object method.
766 ALLOW in INET can either be an Acl object or an anonymous array of elements.
767 Creates a new Unix::Conf::Bind8::Conf::Controls object, links it in the invocant
768 Conf object if successful, and returns it, an Err object otherwise.
769  
770 =cut
771  
772 =item get_controls ()
773  
774 Object method.
775 Returns the Unix::Conf::Bind8::Conf::Controls object if defined (either
776 through a call to new_trustedkeys or one created when the configuration file
777 is parsed) or Err if none is defined.
778  
779 =cut
780  
781 =item delete_controls ()
782  
783 Object method
784 Deletes the defined (either through a call to new_trustedkeys or one created
785 when the configuration file is parsed) Unix::Conf::Bind8::Conf::Controls
786 object.
787 Returns true if a Unix::Conf::Bind8::Conf::Controls object is present, an
788 Err object otherwise.
789  
790 =cut
791  
792 =item new_zone ()
793
794 Arguments
795 NAME => 'zone-name',
796 CLASS => 'zone-class', # in|hs|hesiod|chaos
797 TYPE => 'zone-type', # master|slave|forward|stub|hint
798 FILE => 'records-file',
799 MASTERS => [ qw (10.0.0.1 10.0.0.2) ],
800 FORWARD => 'value', # yes|no
801 FORWARDERS => [ qw (192.168.1.1 192.168.1.2) ],
802 CHECK-NAMES => 'value' # fail|warn|ignore
803 ALLOW-UPDATE => Unix::Conf::Bind8::Conf::Acl object,
804 ALLOW-QUERY => Unix::Conf::Bind8::Conf::Acl object,
805 ALLOW-TRANSFER=> Unix::Conf::Bind8::Conf::Acl object,
806 NOTIFY => 'value, # yes|no
807 ALSO-NOTIFY => [ qw (10.0.0.3) ],
808 WHERE => 'FIRST'|'LAST'|'BEFORE'|'AFTER'
809 WARG => Unix::Conf::Bind8::Conf::Directive subclass object
810 # WARG is to be provided only in case WHERE eq 'BEFORE
811 # or WHERE eq 'AFTER'
812  
813 Object method.
814 Creates and returns a new Unix::Conf::Bind8::Conf::Zone object, links it
815 in the invocant Conf object, and returns it, on success, an Err
816 object otherwise.
817  
818 =cut
819  
820 =item get_zone ()
821  
822 Arguments
823 'ZONE-NAME',
824  
825 Object method.
826 Returns the Unix::Conf::Bind8::Conf::Zone object representing ZONE-NAME
827 if defined (either through a call to new_zone () or one created when
828 parsing the configuration file), an Err object otherwise.
829  
830 =cut
831  
832 =item delete_zone ()
833  
834 Arguments
835 'ZONE-NAME',
836  
837 Object method.
838 Deletes the Unix::Conf::Bind8::Conf::Zone object representing ZONE-NAME
839 if defined (either through a call to new_zone () or one created when
840 parsing the configuration file) and returns true, or returns an Err
841 object otherwise.
842  
843 =cut
844  
845 =item zones ()
846  
847 Arguments
848 ALL # Optional
849  
850 Object method.
851 Iterates through a list of defined Unix::Conf::Bind8::Conf::Zone objects
852 (either through a call to new_zone () or ones created when parsing the
853 configuration file), returning one at a time when called in scalar context,
854 or a list of all objects when called in list context.
855 Argument ALL can either be 0, no, 1, or yes. When ALL is 1 or 'yes', it
856 returns all defined Zone objects across files. Else only those defined
857 in the invocant are returned.
858  
859 =cut
860  
861 =item new_acl ()
862  
863 Arguments
864 NAME => 'acl-name', # Optional
865 ELEMENTS => [ qw (10.0.0.1 10.0.0.2 192.168.1.0/24) ],
866 WHERE => 'FIRST'|'LAST'|'BEFORE'|'AFTER'
867 WARG => Unix::Conf::Bind8::Conf::Directive subclass object
868 # WARG is to be provided only in case WHERE eq 'BEFORE
869 # or WHERE eq 'AFTER'
870  
871 Object method.
872 Creates a new Unix::Conf::Bind8::Conf::Acl object, links it in the invocant
873 Conf object, on success, an Err object otherwise.
874  
875 =cut
876  
877 =item get_acl ()
878  
879 Arguments
880 'ACL-NAME',
881  
882 Object method.
883 Returns the Unix::Conf::Bind8::Conf::Acl object representing 'ACL-NAME' if
884 defined (either through a call to new_acl or one created when the
885 configuration file is parsed), an Err object otherwise.
886  
887 =cut
888  
889 =item delete_acl ()
890  
891 Arguments
892 'ACL-NAME',
893  
894 Object method.
895 Deletes the Unix::Conf::Bind8::Conf::Acl object representing 'ACL-NAME'
896 if defined (either through a call to new_acl or one created when the
897 configuration file is parsed) and returns true, or returns an Err object
898 otherwise.
899  
900 =cut
901  
902 =item acls ()
903  
904 Arguments
905 ALL # Optional
906  
907 Object method.
908 Iterates through the list of defined Unix::Conf::Bind8::Conf::Acl objects
909 (either through a call to new_acl or ones created when parsing the file,
910 returning an object at a time when called in scalar context, or a list of
911 all objects when called in list context.
912 Argument ALL can either be 0, no, 1, or yes. When ALL is 1 or 'yes', it
913 returns all defined Acl objects across files. Else only those defined
914 in the invocant are returned.
915  
916 =cut
917  
918 =item new_key
919
920 Arguments
921 NAME => scalar,
922 ALGORITHM => scalar, # number
923 SECRET => scalar, # quoted string
924 WHERE => 'FIRST'|'LAST'|'BEFORE'|'AFTER'
925 WARG => Unix::Conf::Bind8::Conf::Directive subclass object
926 # WARG is to be provided only in case WHERE eq 'BEFORE
927 # or WHERE eq 'AFTER'
928  
929 Object method.
930 Creates a new Unix::Conf::Bind8::Conf::Key object links it in
931 the invocant Conf object and returns it, on success, an Err object
932 on failure.
933  
934 =cut
935  
936 =item get_key ()
937  
938 Arguments
939 'KEY-NAME',
940  
941 Object method.
942 Returns the Unix::Conf::Bind8::Conf::Key object representing 'KEY-NAME' if
943 defined (either through a call to new_key or one created when the
944 configuration file is parsed), an Err object otherwise.
945  
946 =cut
947  
948 =item delete_key ()
949  
950 Arguments
951 'KEY-NAME',
952  
953 Object method.
954 Deletes the Unix::Conf::Bind8::Conf::Key object representing 'KEY-NAME'
955 if defined (either through a call to new_key or one created when the
956 configuration file is parsed) and returns true, or returns an Err object
957 otherwise.
958  
959 =cut
960  
961 =item keys ()
962  
963 Arguments
964 ALL # Optional
965  
966 Object method.
967 Iterates through the list of defined Unix::Conf::Bind8::Conf::Key objects
968 (either through a call to new_key or ones created when parsing the file,
969 returning an object at a time when called in scalar context, or a list of
970 all objects when called in list context.
971 Argument ALL can either be 0, no, 1, or yes. When ALL is 1 or 'yes', it
972 returns all defined Key objects across files. Else only those defined
973 in the invocant are returned.
974  
975 =cut
976  
977  
978 =item new_server ()
979  
980 Arguments
981 NAME => scalar,
982 BOGUS => scalar, # Optional
983 TRANSFERS => scalar, # Optional
984 TRANSFER-FORMAT=> scalar, # Optional
985 KEYS => [elements ], # Optional
986 WHERE => 'FIRST'|'LAST'|'BEFORE'|'AFTER'
987 WARG => Unix::Conf::Bind8::Conf::Directive subclass object
988 # WARG is to be provided only in case WHERE eq 'BEFORE
989 # or WHERE eq 'AFTER'
990
991 Object method.
992 Creates a new Unix::Conf::Bind8::Conf::Server object, links it in the invocant
993 Conf object and returns it, on success, an Err object otherwise.
994  
995 =cut
996  
997 =item get_server ()
998  
999 Arguments
1000 'SERVER-NAME',
1001  
1002 Object method.
1003 Returns the Unix::Conf::Bind8::Conf::Server object representing 'SERVER-NAME' if
1004 defined (either through a call to new_server or one created when the
1005 configuration file is parsed), an Err object otherwise.
1006  
1007 =cut
1008  
1009 =item delete_server ()
1010  
1011 Arguments
1012 'SERVER-NAME',
1013  
1014 Object method.
1015 Deletes the Unix::Conf::Bind8::Conf::Server object representing 'SERVER-NAME'
1016 if defined (either through a call to new_server or one created when the
1017 configuration file is parsed) and returns true, or returns an Err object
1018 otherwise.
1019  
1020 =cut
1021  
1022 =item servers ()
1023  
1024 Arguments
1025 ALL # Optional
1026  
1027 Object method.
1028 Iterates through the list of defined Unix::Conf::Bind8::Conf::Server objects
1029 (either through a call to new_servers or ones created when parsing the file,
1030 returning an object at a time when called in scalar context, or a list of
1031 all objects when called in list context.
1032 Argument ALL can either be 0, no, 1, or yes. When ALL is 1 or 'yes', it
1033 returns all defined Key objects across files. Else only those defined
1034 in the invocant are returned.
1035  
1036 =cut
1037  
1038 =item new_include ()
1039  
1040 Arguments
1041 FILE => 'path of the configuration file',
1042 SECURE_OPEN => 0/1, # default 1 (enabled)
1043 WHERE => 'FIRST'|'LAST'|'BEFORE'|'AFTER'
1044 WARG => Unix::Conf::Bind8::Conf::Directive subclass object
1045 # WARG is to be provided only in case WHERE eq 'BEFORE
1046 # or WHERE eq 'AFTER'
1047  
1048 Object method.
1049 Creates a new Unix::Conf::Bind8::Conf::Include object which contains an
1050 Unix::Conf::Bind8::Conf object representing FILE, links it in the invocant
1051 Conf object and returns it, on success, an Err object otherwise.
1052  
1053 =cut
1054  
1055 =item get_include ()
1056  
1057 Arguments
1058 'INCLUDE-NAME',
1059  
1060 Object method.
1061 Returns the Unix::Conf::Bind8::Conf::Include object representing INCLUDE-NAME
1062 if defined (either through a call to new_include () or one created when
1063 parsing the configuration file), an Err object otherwise.
1064  
1065 =cut
1066  
1067 =item get_include_conf ()
1068  
1069 Arguments
1070 'INCLUDE-NAME'
1071  
1072 Object method.
1073 Return the Unix::Conf::Bind8::Conf object inside a defined
1074 Unix::Conf::Bind8::Conf::Include of name INCLUDE-NAME.
1075  
1076 =cut
1077  
1078 =item delete_include ()
1079  
1080 Arguments
1081 'INCLUDE-NAME',
1082  
1083 Object method.
1084 Deletes the Unix::Conf::Bind8::Conf::Include object representing INCLUDE-NAME
1085 if defined (either through a call to new_include () or one created when
1086 parsing the configuration file) and returns true, or returns an Err
1087 object otherwise.
1088  
1089 =cut
1090  
1091 =item includes ()
1092  
1093 Arguments
1094 ALL # Optional
1095  
1096 Object method.
1097 Iterates through defined Unix::Conf::Bind8::Conf::Include objects (either
1098 through a call to new_include () or ones created when parsing the
1099 configuration file), returning one at a time when called in scalar context,
1100 or a list of all defined includes when called in list context.
1101 Argument ALL can either be 0, no, 1, or yes. When ALL is 1 or 'yes', it
1102 returns all defined Include objects across files. Else only those defined
1103 in the invocant are returned.
1104  
1105 =cut
1106  
1107 =item get_db ()
1108  
1109 Arguments
1110 'ZONE-NAME',
1111 0/1, # SECURE_OPEN (OPTIONAL). If not specified the value
1112 # for the ConfIO object is taken.
1113  
1114 Object method
1115 Returns a Unix::Conf::Bind8::DB object representing the records file for
1116 zone 'ZONE-NAME' if successful, an Err object otherwise.
1117  
1118 =cut
1119  
1120 sub get_db
1121 {
1122 my ($self, $zone, $secure_open) = @_;
1123 my $ret;
1124  
1125 return (Unix::Conf->_err ('get_db', "not a class method"))
1126 unless (ref ($self));
1127 $secure_open = $self->fh ()->secure_open ()
1128 unless (defined ($secure_open));
1129 $ret = $self->get_zone ($zone) or return ($ret);
1130 return ($ret->get_db ($secure_open));
1131 }
1132  
1133 ################################# PARSER #####################################
1134 # #
1135 require 'Unix/Conf/Bind8/Conf/Parser.pm';
1136 # END #
1137 ################################# PARSER #####################################
1138  
1139 1;
1140 __END__
« Bind8/Conf/Include.pm ↑ Summary Bind8/DB.pm »