Bind8/DB.pm untested

filter: Statementstmt 0.0% 0 / 295 Branchbran 0.0% 0 / 130 Conditioncond 0.0% 0 / 63 MC/DCmcdc 0.0% 0 / 36 Subroutinesub 0.0% 0 / 31 Podpod 0.0% 0 / 19 totaltotal 0.0% 0 / 574 CC 52 SCAR 34.5
CC
52
Cov
0%
records
90.0
__get_node
56.0
__render_tree
56.0
CRAP 31.6
1 # Bind8 DB handling
2 #
3 # Copyright Karthik Krishnamurthy <karthik.k@extremix.net>
4  
5 =head1 NAME
6  
7 Unix::Conf::Bind8::DB - Class implementing methods for manipulation of
8 a Bind records file.
9  
10 =head1 NOTE
11  
12 Almost all methods need a label. All records are attached to
13 one. If labels are not absolute (not ending in a '.'), they
14 are considered relative to the DB origin (zone name). A label of
15 '' means the records are attached to the origin itself. For
16 example below the origin for the db is extremix.net. So any
17 records with a label of '' is attached for extremix.net.
18 Alternatively it could be specified as 'extremix.net.'
19  
20 When an zone record file is read up, the label attribute is
21 relative to the DB origin, the format it is in the zone record
22 file notwithstanding. Same goes for the 'rdata' attribute.
23  
24 The object must have a valid SOA record, since it is mandatory
25 that every zone have one. If the object destructor is invoked
26 without a defined SOA record, the destructor blows up. It is
27 the responsibility of the user to ensure this.
28  
29 =head1 SYNOPSIS
30  
31 use Unix::Conf::Bind8;
32  
33 my ($conf, $db, $rec, $ret);
34 $conf = Unix::Conf::Bind8->new_conf (
35 FILE => 'named.conf',
36 SECURE_OPEN => 0
37 ) or $conf->die ("couldn't get `named.conf'");
38  
39 $db = $conf->get_db ('extremix.net')
40 or $db ->die ("couldn't get db for `extremix.net'");
41
42 # All records have corresponding new_*, get_*, delete_*
43 # methods. Only SOA doesn't have a set_* version, which
44 # can be simulated by a delete_soa followed by a new_soa.
45  
46 # get a record object.
47 $rec = $db->get_soa () or $rec->die ("couldn't get SOA");
48  
49 # add new A record. similarly for other record types
50 $ret = $db->new_a (
51 LABEL => 'ns3',
52 TTL => '1d',
53 RDATA => '10.0.0.10',
54 ) or $ret->die ("couldn't create A record for `ns3'");
55  
56 # delete a specific NS record
57 $ret = $db->delete_ns ('', 'ns1')
58 or $ret->die ("couldn't delete NS record `ns1' for `extremix.net'");
59  
60 # delete all MX records for domain www.extremix.net
61 $ret = $db->delete_mx ('www')
62 or $ret->die ("couldn't delete MX records for `extremix.net'");
63  
64 # delete all records for a label
65 $ret = $db->delete_records ('subdomain.extremix.net.')
66 or $ret->die ("couldnt delete records for `subdomain'");
67  
68 # get all NS records for extremix.net
69 $ret = $db->get_ns ('')
70 or $ret->die ("couldn't get NS records for `extremix.net'");
71 print ("NS records for extremix.net:\n");
72 print $_->rdata (), "\n" for (@$ret);
73  
74 # get a specific record
75 $rec = $db->get_a ('www', '192.168.1.1')
76 or $rec->die ("couldn't get A record for www.extremix.net");
77 print ("LABEL => www.extremix.net\n");
78 printf ("TTL => %s\n", $ret) if ($ret = $rec->ttl ());
79 printf ("CLASS => %s\n", $ret) if ($ret = $rec->class ());
80 printf ("RTYPE => A\n", $ret);
81 printf ("RDATA => 192.168.1.1");
82  
83 # Iterate over a list of all records.
84 while (my $rec = $db->records ()) {
85 # do stuff
86 }
87  
88 # OR
89  
90 my @records = $db->records ();
91 for (@records) {
92 # do stuff
93 }
94  
95 =head1 DESCRIPTION
96  
97 This class has interfaces for the various classes residing
98 beneath Unix::Conf::Bind8::DB. This is an internal class should
99 not be accessed directly. Methods in this class are to be accessed
100 through a Unix::Conf::Bind8::DB object which is returned
101 by Unix::Conf::Bind8->new_db () or by invoking the get_db ()
102 object method in Unix::Conf::Bind8::Conf or Unix::Conf::Bind8::Conf::Zone.
103  
104 =over 4
105  
106 =cut
107  
108 package Unix::Conf::Bind8::DB;
109  
110 use strict;
111 use warnings;
112  
113 use Unix::Conf;
114 use Unix::Conf::Bind8::DB::SOA;
115 use Unix::Conf::Bind8::DB::NS;
116 use Unix::Conf::Bind8::DB::MX;
117 use Unix::Conf::Bind8::DB::A;
118 use Unix::Conf::Bind8::DB::PTR;
119 use Unix::Conf::Bind8::DB::CNAME;
120 use Unix::Conf::Bind8::DB::Lib;
121  
122 #
123 # Unix::Conf::Bind8::DB object
124 #
125 # SCALARREF -> {
126 # FH
127 # ORIGIN
128 # CLASS
129 # DIRTY
130 # SOA
131 # RECORDS -> {
132 # DATA -> {
133 # 'label' -> {
134 # 'rtype' -> {
135 # 'rdata'
136 # }
137 # }
138 # }
139 # CHILDREN -> {
140 # 'label' -> {
141 # DATA
142 # CHILDREN
143 # }
144 # }
145 # }
146 # }
147 #
148 # Zone:
149 # example.com
150 # Records:
151 # example.com IN A 10.0.0.1
152 # ns.example.com IN A 10.0.0.2
153 # ns.sub.example.com IN A 10.0.0.3
154 #
155 # RECORDS -> {
156 # DATA -> {
157 # '' -> {
158 # 'A' -> {
159 # '10.0.0.1' -> Unix::Conf::Bind8::DB::A object
160 # }
161 # }
162 # 'ns' -> {
163 # 'A' -> {
164 # '10.0.0.2' -> Unix::Conf::Bind8::DB::A object
165 # }
166 # }
167 # }
168 # CHILDREN -> {
169 # 'sub' -> {
170 # DATA -> {
171 # 'ns' -> {
172 # 'A' -> {
173 # '10.0.0.2' -> Unix::Conf::Bind8::DB::A object
174 # }
175 # }
176 # }
177 # }
178 # }
179 # }
180 #
181 # The way this is stored, almost all the information is duplicated in both the object
182 # and the tree. But this seems to be the only way out if we want to come up with a
183 # DB object containing other record objects setup. This is done here to maintain
184 # uniformity with Bind8::Conf where the constituent objects in a Bind8::Conf object
185 # are complicated and different enough to warrant their own classes.
186 #
187  
188 =item new ()
189  
190 Arguments
191 FILE => 'pathname', #
192 ORIGIN => 'value', # origin
193 CLASS => 'class', # ('in'|'hs'|'chaos')
194 SECURE_OPEN => 0/1, # optional (enabled (1) by default)
195  
196 Class constructor
197 Creates a Unix::Conf::Bind8::DB object and returns it if
198 successful, an Err object otherwise. Direct use of this method
199 is deprecated. Use Unix::Conf::Bind8::Zone::get_db (), or
200 Unix::Conf::Bind8::new_db () instead.
201  
202 =cut
203  
204 # ARGUMENTS: hash
205 # FILE
206 # ORIGIN
207 # CLASS
208 # SECURE_OPEN
209 # RETURN
210 # Unix::Conf::Bind8::DB/Unix::Conf::Err object
211 # The object created is a ref to a scalar which contains a ref
212 # to a hash. This is to break the circular reference problem.
213 sub new
214 {
215 my $invocant = shift ();
216 my %args = @_;
217 my ($new, $db, $ret);
218  
219 $args{FILE} || return (Unix::Conf->_err ('new', "DB file not specified"));
220 $args{ORIGIN} || return (Unix::Conf->_err ('new', "DB origin not specified"));
221 $args{ORIGIN} .= "." unless (__is_absolute ($args{ORIGIN}));
222 $args{CLASS} || return (Unix::Conf->_err ('new', "DB class not specifed"));
223 $args{SECURE_OPEN} = defined ($args{SECURE_OPEN}) ? $args{SECURE_OPEN} : 1;
224 $db = Unix::Conf->_open_conf (
225 NAME => $args{FILE}, SECURE_OPEN => $args{SECURE_OPEN}
226 ) or return ($db);
227 # we are blessing a reference to a hashref.
228 $new = bless (\{ RECORDS => {}, DIRTY => 0 });
229 $$new->{FH} = $db;
230 $ret = $new->origin ($args{ORIGIN}) or return ($ret);
231 $ret = $new->class ($args{CLASS}) or return ($ret);
232 # check for any syntax probs in the classes. change parser later.
233 eval { $ret = $new->__parse_db (); } or return ($@);
234 return ($new);
235 }
236  
237 sub DESTROY
238 {
239 my $self = $_[0];
240  
241 die (
242 Unix::Conf->_err (
243 "DESTROY",
244 sprintf ("SOA not defined for zone `%s'", $self->origin ())
245 )
246 ) unless ($self->get_soa ());
247  
248 if ($$self->{DIRTY}) {
249 my $fh = $self->fh ();
250 my $str = __render ($self);
251 $fh->set_scalar ($str);
252 }
253 # release all contained stuff
254 undef (%$$self);
255 }
256  
257 =item origin ()
258  
259 Arguments
260 'origin', # optional. if the argument is not absolute, i.e.
261 # having a trailing '.', the existing origin, if
262 # any will be appended to the argument.
263  
264 Object method.
265 Get/Set DB origin. If argument is passed, the method tries to set the
266 origin of the DB object to 'origin' and returns true on success, an Err
267 object otherwise. If no argument is specified, returns the name of the
268 zone, if defined, an Err object otherwise.
269  
270 =cut
271  
272 sub origin
273 {
274 my ($self, $origin) = @_;
275
276 if (defined ($origin)) {
277 $$self->{ORIGIN} = __is_absolute ($origin) ? $origin :
278 (defined ($$self->{ORIGIN}) ? $origin.$$self->{ORIGIN} : $origin.'.');
279 return (1);
280 }
281 return (
282 defined ($$self->{ORIGIN}) ? $$self->{ORIGIN} : Unix::Conf->_err ('origin', "origin not defined")
283 );
284 }
285  
286 =item fh ()
287  
288 Object method.
289 Returns the Unix::Conf::ConfIO object representing the DB file.
290  
291 =cut
292  
293 sub fh
294 {
295 my $self = $_[0];
296 return ($$self->{FH});
297 }
298  
299 =item dirty ()
300  
301 Object method.
302 Get/Set the DIRTY flag in invoking Unix::Conf::Bind8::DB object.
303  
304 =cut
305  
306 sub dirty
307 {
308 my ($self, $dirty) = @_;
309  
310 if (defined ($dirty)) {
311 $$self->{DIRTY} = $dirty;
312 return (1);
313 }
314 return ($$self->{DIRTY});
315 }
316  
317 =item class ()
318  
319 Arguments
320 'class' # ('in'|'hs'|'chaos')
321  
322 Object method.
323 Get/Set object class. If argument is passed, the method tries to set the
324 class attribute to 'class' and returns true if successful, an Err object
325 otherwise. If no argument is passed, returns the value of the class
326 attribute if defined, an Err object otherwise.
327 Note:
328 Typically class is set in the zone statement. Each record can have a
329 zone specified. But that cannot be different from the value set here.
330  
331 =cut
332  
333 # Typically class is set in the zone statement. Each record can have a
334 # zone specified. But that cannot be different from the value set here.
335 sub class
336 {
337 my ($self, $class) = @_;
338  
339 if (defined ($class)) {
340 return (Unix::Conf->_err ('class', "illegal class `$class'"))
341 if ($class !~ /^(in|hs|chaos)$/i);
342 $$self->{CLASS} = $class;
343 $$self->{DIRTY} = 1;
344 return (1);
345 }
346 return (
347 defined ($$self->{CLASS}) ? $$self->{CLASS} : Unix::Conf->_err ('class', "class not defined")
348 );
349 }
350  
351  
352 =item delete_methods ()
353  
354 Argument
355 'label'
356  
357 Object method.
358 Deletes all records attached to a label. Returns true on success,
359 an Err object otherwise.
360  
361 =cut
362  
363 sub delete_records
364 {
365 my ($self, $label) = @_;
366
367 $label = __make_relative ($self->origin (), $label);
368  
369 # dont' use __get_node as it is for a single record to be attached to a label
370 # and does not work right for getting hold of an entire branch
371 my ($leaf, $nodes) = ($label =~ /^((?:[\w-]+)?)\.?(.*)$/);
372 my @nodes = split (/\./, $nodes);
373 unshift (@nodes, $leaf);
374 my $node = $$self->{RECORDS};
375 while (@nodes) {
376 $_ = pop (@nodes);
377 # assume it is a branch first
378 if ($node->{CHILDREN} && $node->{CHILDREN}{$_}) {
379 $node = $node->{CHILDREN}{$_}
380 }
381 elsif ($node->{DATA} && $node->{DATA}{$_}) {
382 $node = $node->{DATA}{$_};
383 }
384 else {
385 return (Unix::Conf->_err ("delete_records", "no records defined for `$label'"));
386 }
387 }
388 return (Unix::Conf->_err ("delete_records", "no records defined for `$label'"))
389 unless (keys (%$node));
390 # delete all keys
391 undef (%$node);
392 $$self->{DIRTY} = 1;
393 return (1);
394 }
395  
396 =item new_soa ()
397  
398 Arguments
399 CLASS =>
400 TTL =>
401 AUTH_NS =>
402 MAIL_ADDR =>
403 SERIAL =>
404 REFRESH =>
405 RETRY =>
406 EXPIRE =>
407 MIN_TTL =>
408  
409 Object method.
410 Creates and associates a new Unix::Conf::Bind8::DB::SOA object
411 with the invoking Unix::Conf::Bind8::DB object and returns it
412 on success, an Err object otherwise.
413  
414 =cut
415  
416 # The only new_* method where this method adds the SOA to the
417 # the DB object. In other methods it is done by the corresponding
418 # new_* constructors.
419 sub new_soa
420 {
421 my $self = shift ();
422 my (%args, $new);
423 return (Unix::Conf->_err ('new_soa', "SOA already defined"))
424 if ($$self->{SOA});
425 %args = ( @_ );
426 # make sure an illegal class is not set.
427 return (Unix::Conf->_err ('new_soa', "illegal class `$args{CLASS}'for SOA"))
428 if ($args{CLASS} ne $$self->{CLASS});
429 $new = Unix::Conf::Bind8::DB::SOA->new ( @_, RTYPE => 'SOA', PARENT => $$self ) or Unix::Conf->_err ($new);
430 $$self->{DIRTY} = 1;
431 return ($$self->{SOA} = $new);
432 }
433  
434 =item get_soa ()
435  
436 Object method.
437 Returns the Unix::Conf::Bind8::DB::SOA object associated with the invoking
438 Unix::Conf::Bind8::DB object if defined, an Err object otherwise.
439  
440 =cut
441  
442 sub get_soa
443 {
444 my $self = $_[0];
445  
446 return (
447 $$self->{SOA} ? $$self->{SOA} : Unix::Conf->_err ('get_soa', "SOA not defined")
448 );
449 }
450  
451 =item delete_soa ()
452  
453 Object method.
454 Deletes the Unix::Conf::Bind8::DB::SOA object associated with the invoking
455 Unix::Conf::Bind8::DB object if defined and returns true, an Err object
456 otherwise.
457  
458 =cut
459  
460 sub delete_soa
461 {
462 my $self = $_[0];
463  
464 return (Unix::Conf->_err ('delete_soa', "SOA not defined"))
465 unless ($$self->{SOA});
466 delete ($$self->{SOA});
467 $$self->{DIRTY} = 1;
468 return (1);
469 }
470  
471 =item new_ns ()
472  
473 =item new_a ()
474  
475 =item new_ptr ()
476  
477 =item new_cname ()
478  
479 Arguments
480 LABEL =>
481 CLASS =>
482 TTL =>
483 RDATA =>
484  
485 Object method.
486 Creates and associates a corresponding Unix::Conf::Bind8::DB::*
487 object with the invoking Unix::Conf::Bind8::DB object and
488 returns it, on success an Err object otherwise.
489  
490 =cut
491  
492 =item new_mx ()
493  
494 Arguments
495 LABEL =>
496 MXPREF =>
497 CLASS =>
498 TTL =>
499 RDATA =>
500  
501 Object method.
502 Creates and associates a new Unix::Conf::Bind8::DB::MX object
503 with the invoking Unix::Conf::Bind8::DB object and returns it,
504 on success an Err object otherwise.
505  
506 =item get_ns ()
507  
508 =item get_a ()
509  
510 =item get_ptr ()
511  
512 =item get_cname ()
513  
514 =item get_mx ()
515  
516 Arguments
517 'label',
518 'rdata' # optional
519  
520 Object method.
521 Returns the corresponding Unix::Conf::Bind8::DB::* object
522 associated with the invoking Unix::Conf::Bind8::DB object,
523 with label 'label' and rdata 'rdata'. If the rdata argument
524 is not passed, then all `rdata' record objects attached to label
525 'label' are returned in an anonymous array. On failure an
526 Err object is returned.
527  
528 =cut
529  
530 =item set_ns ()
531  
532 =item set_a ()
533  
534 =item set_ptr ()
535  
536 =item set_cname ()
537  
538 Arguments
539 'label',
540 [
541 { CLASS => 'class', TTL => 'ttl', RDATA => 'rdata', },
542 { CLASS => 'class', TTL => 'ttl', RDATA => 'rdata', },
543 ....
544 ],
545  
546 Object method.
547 Creates and associates corresponding Unix::Conf::Bind8::DB::*
548 objects with the relevant attributes with the invoking
549 Unix::Conf::Bind8::DB object. Returns true on success, an
550 Err object otherwise. The existing
551 Unix::Conf::Bind8::DB::* objects attached to this label are
552 deleted.
553  
554 =cut
555  
556 =item set_mx ()
557  
558 Arguments
559 'label',
560 [
561 { CLASS => 'class', TTL => 'ttl', MXPREF => pref, RDATA => 'rdata', },
562 { CLASS => 'class', TTL => 'ttl', MXPREF => pref, RDATA => 'rdata', },
563 ....
564 ],
565  
566 Object method.
567 Creates and associates Unix::Conf::Bind8::DB::MX objects with the
568 relevant attributes with the invoking Unix::Conf::Bind8::DB object.
569 Returns true on success, an Err object otherwise. The existing
570 Unix::Conf::Bind8::DB::MX objects attached to this label are
571 deleted.
572  
573 =cut
574  
575 =item delete_ns ()
576  
577 =item delete_a ()
578  
579 =item delete_ptr ()
580  
581 =item delete_cname ()
582  
583 =item delete_mx ()
584  
585 Arguments
586 'label',
587 'rdata',
588  
589 Object method.
590 Deletes the corresponding Unix::Conf::Bind8::DB::* object with
591 label 'label' and rdata 'rdata', associated with the invoking
592 Unix::Conf::Bind8::DB object if defined and returns true, an
593 Err object. If the rdata argument is not passed, then all
594 corresponding records attached to label 'label' are deleted.
595  
596 =cut
597  
598 for my $rtype qw (NS A MX PTR CNAME)
599 {
600 no strict 'refs';
601 # new_*
602 my $meth = lc ($rtype);
603 my $newmeth = "new_$meth";
604 my $delmeth = "delete_$meth";
605 *$newmeth = sub {
606 my $self = shift ();
607 return ("Unix::Conf::Bind8::DB::$rtype"->new ( @_, RTYPE => $rtype, PARENT => $$self ));
608 };
609  
610 *{"get_$meth"} = sub {
611 my ($self, $label, $rdata) = @_;
612 return (Unix::Conf->_err ("get_$meth", "label not specified"))
613 unless (defined ($label));
614 my $node = __get_node ($$self, $label);
615 return (Unix::Conf->_err ("get_$meth", "$rtype record for `$label' not defined"))
616 unless ($node->{$rtype});
617 # get a record with value of $rdata for $label
618 if (defined ($rdata)) {
619 return (Unix::Conf->_err ("get_$meth", "$rtype record for `$label' with rdata of `$rdata' not defined"))
620 unless ($node->{$rtype}{$rdata});
621 return ($node->{$rtype}{$rdata});
622 }
623 # else return all records for of that particular RTYPE for $label
624 return ( [ values (%{$node->{$rtype}}) ] );
625 };
626  
627 *{"set_$meth"} = sub {
628 my ($self, $label, $arg) = @_;
629 my ($rdata, $ret);
630 return (Unix::Conf->_err ("set_$meth", "label not passed"))
631 unless (defined ($label));
632 return (Unix::Conf->_err ("set_$meth", "RDATA not passed"))
633 unless ($arg);
634 if (ref ($arg)) {
635 if (UNIVERSAL::isa ($arg, 'HASH')) {
636 $rdata = [ $arg ];
637 }
638 elsif (UNIVERSAL::isa ($arg, 'ARRAY')) {
639 $rdata = $arg;
640 }
641 else {
642 Unix::Conf->_err ("set_$meth", "RDATA type is either a hash ref or an array ref");
643 }
644 }
645 else {
646 Unix::Conf->_err ("set_$meth", "RDATA type is either a hash ref or an array ref");
647 }
648 # first delete all old values for that label
649 $ret = $delmeth->($self, $label) or return ($ret);
650 for (@$rdata) {
651 $_->{LABEL} = $label;
652 $ret = $newmeth->($self, %{$_}) or return ($ret);
653 }
654 return (1);
655 };
656  
657 *$delmeth = sub {
658 my ($self, $label, $rdata) = @_;
659 return (Unix::Conf->_err ("delete_$meth", "label not specified"))
660 unless (defined ($label));
661 my $node = __get_node ($$self, $label);
662 return (Unix::Conf->_err ("delete_$meth", "$rtype record for `$label' not defined"))
663 unless ($node->{$rtype});
664  
665 # delete the $rtype record with value $rdata for $label
666 if (defined ($rdata)) {
667 $rdata = __make_relative ($$self->{ORIGIN}, $rdata);
668 return (Unix::Conf->_err ("delete_$meth", "$rtype record for `$label' with rdata of `$rdata' not defined"))
669 unless ($node->{$rtype}{$rdata});
670 delete ($node->{$rtype}{$rdata});
671 # delete rtype if there are no types left.
672 delete ($node->{$rtype})
673 unless (keys (%{$node->{$rtype}}));
674 $self->dirty (1);
675 return (1);
676 }
677  
678 # else delete all $rtype records for $label
679 delete ($node->{$rtype});
680 $self->dirty (1);
681 return (1);
682 };
683 }
684  
685 =item records ()
686  
687 Object method.
688 Returns records defined in the zone. When called in a list context,
689 returns all defined records. Iterates over defined records, when
690 called in a scalar method. Returns `undef' at the end of one
691 iteration, and starts over if called again.
692  
693 =cut
694  
695 {
696 sub __traverse ($$;$);
697 sub records
698 {
699 my ($self, $label) = @_;
700 my $travarg;
701 # create a list of records only it iterator is at start
702 unless ($$self->{ITR}) {
703 undef (@{$$self->{RECARRAY}});
704 push (@{$$self->{RECARRAY}}, $$self->{SOA}) unless (defined ($label));
705 my $node = $$self->{RECORDS};
706 if ($label) {
707 my ($leaf, $nodes) = ($label =~ /^((?:[\w-]+)?)\.?(.*)$/);
708 my @nodes = split (/\./, $nodes);
709 unshift (@nodes, $leaf);
710 while (@nodes) {
711 $_ = pop (@nodes);
712 # assume it is a branch first
713 if ($node->{CHILDREN} && $node->{CHILDREN}{$_}) {
714 $node = $node->{CHILDREN}{$_}
715 }
716 elsif ($node->{DATA} && $node->{DATA}{$_}) {
717 # if there is a valid value for $_ under DATA
718 # there @nodes should be empty. Sanity check.
719 return (Unix::Conf->_err ("records", "internal consistency error"))
720 if (@nodes);
721 # force __traverse to iterate only through all records for
722 # $_ under $node->{DATA} instead of all records under all labels
723 # under $node->{DATA}
724 $travarg = $_;
725 last;
726 }
727 else {
728 return (Unix::Conf->_err ("records", "no records defined for `$label'"));
729 }
730 }
731 }
732 __traverse ($$self->{RECARRAY}, $node, $travarg);
733 }
734  
735 if (wantarray ()) {
736 # reset iterator before returning
737 $$self->{ITR} = 0;
738 return (@{$$self->{RECARRAY}})
739 }
740 # return undef on completion of one iteration
741 return () if ($$self->{ITR} && !($$self->{ITR} %= scalar (@{$$self->{RECARRAY}})));
742 return (${$$self->{RECARRAY}}[$$self->{ITR}++]);
743 }
744  
745 sub __traverse ($$;$)
746 {
747 my ($arrref, $node, $label) = @_;
748 my @labels = defined ($label) ? ($label) : sort (keys (%{$node->{DATA}}));
749  
750 for my $_label (@labels) {
751 for my $rectype (sort (keys (%{$node->{DATA}{$_label}}))) {
752 for my $rec (sort (keys (%{$node->{DATA}{$_label}{$rectype}}))) {
753 push (@$arrref, $node->{DATA}{$_label}{$rectype}{$rec});
754 }
755 }
756 }
757  
758 # if $label is defined, there will be no CHILDREN, or at least there
759 # ought not to be.
760 unless (defined ($label)) {
761 for my $child (sort (keys (%{$node->{CHILDREN}}))) {
762 __traverse ($arrref, $node->{CHILDREN}{$child});
763 }
764 }
765 }
766 }
767  
768 # Utility functions used to insert/delete objects from the database tree
769 # ARGUMENT: Unix::Conf::Bind8::DB::Record or derived object.
770 #
771 # NOTE: If the label is relative, it is assumed to be relative to
772 # the zone origin.
773 #
774 sub _insert_object
775 {
776 my $object = $_[0];
777  
778 return (Unix::Conf->_err ('_insert_object', "Record object not specified"))
779 unless ($object);
780 return (Unix::Conf->_err ('_insert_object', "Record object not a child class of type Unix::Conf::Bind8::DB::Record"))
781 unless ($object->isa ('Unix::Conf::Bind8::DB::Record'));
782 my $root = $object->_parent ();
783  
784 my ($label, $rtype, $rdata);
785 defined ($label = $object->label ()) or return ($label);
786 $rtype = $object->rtype () or return ($rtype);
787 $rdata = $object->rdata () or return ($rdata);
788 $rdata = __make_relative ($root->{ORIGIN}, $rdata)
789 if ($rtype ne 'A');
790  
791 my $node = __get_node ($root, $label);
792 return (Unix::Conf->_err ('_insert_object', "Record with label `$label' of type `$rtype' with data `$rdata' already defined"))
793 if ($node->{$rtype}{$rdata});
794 return ($node->{$rtype}{$rdata} = $object);
795 }
796  
797 # ARGUMENT: Unix::Conf::Bind8::DB::Record or derived object.
798 sub _delete_object
799 {
800 my $object = $_[0];
801  
802 return (Unix::Conf->_err ('_delete_object', "Record object not specified"))
803 unless ($object);
804 return (Unix::Conf->_err ('_delete_object', "Record object not a child class of type Unix::Conf::Bind8::DB::Record"))
805 unless ($object->isa ('Unix::Conf::Bind8::DB::Record'));
806 my $root = $object->_parent ();
807 my ($label, $rtype, $rdata);
808 defined ($label = $object->label ()) or return ($label);
809 $rtype = $object->rtype () or return ($rtype);
810 $rdata = $object->rdata () or return ($rdata);
811 $rdata = __make_relative ($root->{ORIGIN}, $rdata)
812 if ($rtype ne 'A');
813  
814 my $node = __get_node ($root, $label);
815 return (Unix::Conf->_err ('_delete_object', "Record with label `$label' of type `$rtype' with data `$rdata' not defined"))
816 unless ($node->{$rtype}{$rdata});
817 delete ($node->{$rtype}{$rdata});
818 delete ($node->{$rtype})
819 unless (keys (%{$node->{$rtype}}));
820 return (1);
821 }
822  
823 #sub _get_object
824 #{
825 # my ($root, $label, $rtype, $rdata) = @_;
826 #
827 # return (Unix::Conf->_err ('_get_object', "label not specified"))
828 # unless (defined ($label));
829 # return (Unix::Conf->_err ('_get_object', "rtype not specified"))
830 # unless (defined ($rtype));
831 # return (Unix::Conf->_err ('_get_object', "rdata not specified"))
832 # unless (defined ($rdata));
833 #
834 # my $node = __get_node ($root, $label);
835 # return (Unix::Conf->_err ('_get_object', "Record with label `$label' of type `$rtype' with data `$rdata' not defined"))
836 # unless ($node->{$rtype}{$rdata});
837 # return ($node->{$rtype}{$rdata});
838 #}
839  
840 sub __get_node
841 {
842 my ($root, $olabel) = @_;
843 my $label;
844 return (Unix::Conf->_err ('__get_node', "`$olabel' lies outside `$root->{ORIGIN}'"))
845 unless (defined ($label = __make_relative ($root->{ORIGIN}, $olabel)));
846  
847 my $ptr = $root->{RECORDS};
848 # use regex to pull out a pattern so that the $leaf will be '', not undef
849 # in case of $label being ''
850 my ($leaf, $nodes) = ($label =~ /^((?:[\w-]+)?)\.?(.*)$/);
851 my @nodes = split (/\./, $nodes);
852 unshift (@nodes, $leaf);
853  
854 TRAVERSE:
855 # traverse the tree
856 while (@nodes) {
857 $_ = pop (@nodes);
858  
859 # if @nodes has exactly one element left, then we will
860 # need to create another branch, by attaching an anon hash
861 # to $ptr->{CHILDREN}{$_}. The element left in @node, will
862 # be attached to $ptr->{CHILDREN}{$_}{DATA}{element}. Now
863 # if we find that {DATA} is already defined for $_, we
864 # need to move it to under $ptr->{CHILDREN}{$_}{DATA}{''}.
865 # The result of this is, if no branch exists, the leaf node
866 # will be the leftmost part (with '.' as separators). But
867 # if a branch exists, the leaf will be a '', and the leftmost
868 # part shifted as another branch.
869 # Thus, assuming an origin of extremix.net, an A record for
870 # www will be attached to $root->{RECORDS}{DATA}{www}{A}{rdata}.
871 # Similarly for a NS record for sub. But, if then a record like www.sub is
872 # encountered, then when sub is in $_ and www is still in @nodes,
873 # the code below finds out that sub is going to be a branch.
874 # So it will move $root->{RECORDS}{DATA}{sub} to
875 # $root->{RECORDS}{CHILDREN}{sub}{DATA}{''}.
876 # So while, the www A record will be written out as
877 # www IN A rdata
878 # the sub NS record (after encountering www.sub record), will be
879 # written out as
880 # $ORIGIN sub.extremix.net.
881 # IN NS rdata
882 # www IN RTYPE rdata
883 if (@nodes == 1 && $ptr->{DATA}{$_}) {
884 $ptr->{CHILDREN}{$_}{DATA}{''} = $ptr->{DATA}{$_};
885 delete ($ptr->{DATA}{$_});
886 }
887  
888 # this is to ensure that if CHILDREN 'foo' already exist, the correct
889 # node for a label 'foo' is not under $ptr->{DATA}{foo}, but under
890 # $ptr->{CHILDREN}{foo}{DATA}{''}. If no children the former course is
891 # adopted. If later branch is created at foo, data attached to
892 # $ptr->{DATA}{foo} will be shifted down by the previous block of code.
893 # as @nodes now has something, it will not enter the unless (@nodes)
894 # below and loop again travelling down the tree and will be attached
895 # with a label of ''.
896 push (@nodes, '')
897 if (!@nodes && $ptr->{CHILDREN} && $ptr->{CHILDREN}{$_});
898  
899 unless (@nodes) {
900 $ptr->{DATA}{$_} = {} unless ($ptr->{DATA}{$_});
901 $ptr = $ptr->{DATA}{$_};
902 last TRAVERSE;
903 }
904  
905 # if this part of the tree doesn't exist create it.
906 $ptr->{CHILDREN}{$_} = {} unless (defined ($ptr->{CHILDREN}{$_}));
907 $ptr = $ptr->{CHILDREN}{$_}
908 }
909 return ($ptr);
910 }
911  
912 # shared amongst __render_tree and __render
913 my ($Rendered, $Class, $DB_Origin);
914  
915 # forward declaration
916 sub __render_tree ($$$$);
917 sub __render
918 {
919 my $self = $_[0];
920 $DB_Origin = $$self->{ORIGIN};
921 $Class = $self->class ();
922  
923 # render SOA for the zone
924 $Rendered = "\$ORIGIN $DB_Origin\n@\t";
925 $Rendered .= "$$self->{SOA}{TTL}\t" if (defined ($$self->{SOA}{TTL}));
926 my $auth_ns = __make_absolute ($DB_Origin, $$self->{SOA}{AUTH_NS});
927 my $mail_addr = __make_absolute ($DB_Origin, $$self->{SOA}{MAIL_ADDR});
928 $Rendered .= "$Class\tSOA\t$auth_ns\t$mail_addr (\n\t\t$$self->{SOA}{SERIAL}\n\t\t$$self->{SOA}{REFRESH}\n\t\t$$self->{SOA}{RETRY}\n\t\t$$self->{SOA}{EXPIRE}\n\t\t$$self->{SOA}{MIN_TTL})\n";
929  
930 __render_tree ($$self->{RECORDS}, $DB_Origin, 1, 1);
931 return (\$Rendered);
932 }
933  
934 sub __render_tree ($$$$)
935 {
936 my ($node, $origin, $origin_printed, $at_printed) = @_;
937 # print ORIGIN
938 my $start = "\n";
939 $start .= "\$ORIGIN $origin\n" unless ($origin_printed);
940  
941 # print all nodes in this level
942 # sorting the keys will ensure that records with empty
943 # labels '', will be printed first. it will be a serious
944 # error if this is not so, as label is carried forward from
945 # the previous record, in case of records with empty labels.
946 for my $label (sort (keys (%{$node->{DATA}}))) {
947 # do not do anything here as it is possible that
948 # there is a hash attached to $label, but with no records
949 # defined as they have all been deleted.
950 for my $rectype (sort (keys (%{$node->{DATA}{$label}}))) {
951 # print '@' if the label is empty right after
952 # ORIGIN is printed.
953 if (!$at_printed && !$label) {
954 $start .= '@';
955 }
956 else {
957 $start .= "$label";
958 }
959 # once the first label is printed, whether it is a '@'
960 # or an actual label, we don't need to print @ for
961 # empty labels.
962 $at_printed = 1;
963 for my $rec (sort (keys (%{$node->{DATA}{$label}{$rectype}}))) {
964 my ($obj, $tmp);
965 # print this only if there are records
966 if ($start) { $Rendered .= $start; undef ($start); }
967 #else { $Rendered .= "\t"; }
968 $Rendered .= "\t";
969 $obj = $node->{DATA}{$label}{$rectype}{$rec};
970 $Rendered .= "$tmp\t"
971 if ($tmp = $obj->ttl ());
972 $Rendered .= "$Class\t\U$rectype\E\t";
973 $Rendered .= "$tmp\t"
974 if ($rectype eq 'MX' && ($tmp = $obj->mxpref ()));
975 # any relative labels are relative to DB_Origin. so make it abs
976 # then relative to last printed origin before printing
977 if ($rectype ne 'A') {
978 $Rendered .= sprintf ("%s\n", __make_relative ($origin, __make_absolute ($DB_Origin, $rec)));
979 }
980 else {
981 $Rendered .= "$rec\n";
982 }
983 }
984 }
985 }
986 for my $child (sort (keys (%{$node->{CHILDREN}}))) {
987 __render_tree ($node->{CHILDREN}{$child}, "$child.$origin", 0, 0);
988 }
989 }
990  
991 ################################# PARSER #####################################
992 # #
993 require 'Unix/Conf/Bind8/DB/Parser.pm';
994 # END #
995 ################################# PARSER #####################################
996  
997 1;
998  
999 =head1 TODO
1000  
1001 1. Finalise on the interface. Remove superfluous ones.