.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Zonemaster::Engine::DNSName 3pm"
.TH Zonemaster::Engine::DNSName 3pm 2024-04-22 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Zonemaster::Engine::DNSName \- class representing DNS names
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\&    my $name1 = Zonemaster::Name\->new(\*(Aqwww.example.org\*(Aq);
\&    my $name2 = Zonemaster::Name\->new(\*(Aqns.example.org\*(Aq);
\&    say "Yay!" if $name1\->common($name2) == 2;
.Ve
.SH ATTRIBUTES
.IX Header "ATTRIBUTES"
.IP labels 4
.IX Item "labels"
A reference to a list of strings, being the labels the DNS name is made up from.
.SH METHODS
.IX Header "METHODS"
.IP "new($input) _or_ new({ labels => \e@labellist})" 4
.IX Item "new($input) _or_ new({ labels => @labellist})"
The constructor can be called with either a single argument or with a reference
to a hash as in the example above.
.Sp
If there is a single argument, it must be either a non-reference, a
Zonemaster::Engine::DNSName object or a Zonemaster::Engine::Zone object.
.Sp
If it's a non-reference, it will be split at period characters (possibly after
stringification) and the resulting list used as the name's labels.
.Sp
If it's a Zonemaster::Engine::DNSName object it will simply be returned.
.Sp
If it's a Zonemaster::Engine::Zone object, the value of its \f(CW\*(C`name\*(C'\fR attribute will
be returned.
.IP from_string($domain) 4
.IX Item "from_string($domain)"
A specialized constructor that must be called with a string.
.IP \fBstring()\fR 4
.IX Item "string()"
Returns a string representation of the name. The string representation is created by joining the labels with dots. If there are no labels, a
single dot is returned. The names created this way do not have a trailing dot.
.Sp
The stringification operator is overloaded to this function, so it should rarely be necessary to call it directly.
.IP \fBfqdn()\fR 4
.IX Item "fqdn()"
Returns the name as a string complete with a trailing dot.
.IP str_cmp($other) 4
.IX Item "str_cmp($other)"
Overloads string comparison. Comparison is made after converting the names to upper case, and ignores any trailing dot on the other name.
.IP \fBnext_higher()\fR 4
.IX Item "next_higher()"
Returns a new Zonemaster::Engine::DNSName object, representing the name of the called one with the leftmost label removed.
.IP common($other) 4
.IX Item "common($other)"
Returns the number of labels from the rightmost going left that are the same in both names. Used by the recursor to check for redirections going
up the DNS tree.
.IP is_in_bailiwick($other) 4
.IX Item "is_in_bailiwick($other)"
Returns true if \f(CW$other\fR is in-bailiwick of \f(CW$self\fR, and false otherwise.
See also <https://tools.ietf.org/html/rfc7719#section\-6>.
.IP prepend($label) 4
.IX Item "prepend($label)"
Returns a new Zonemaster::Engine::DNSName object, representing the called one with the given label prepended.
.IP TO_JSON 4
.IX Item "TO_JSON"
Helper method for JSON encoding.