.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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 "Data::Validate::Domain 3pm"
.TH Data::Validate::Domain 3pm "2020-12-27" "perl v5.32.0" "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"
Data::Validate::Domain \- domain validation methods
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Data::Validate::Domain qw(is_domain);
\& 
\&  # as a function 
\&  my $test = is_domain($suspect);
\&  die "$test is not a domain" unless defined $test;
\&
\&  or
\&
\&  my $test = is_domain($suspect,\e%options);
\&  die "$test is not a domain" unless defined $test;
\&  
\&
\&  # or as an object
\&  my $v = Data::Validate::Domain\->new(%options);
\&
\&  my $test = $v\->is_domain($suspect);
\&  die "$test is not a domain" unless defined $test;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module collects domain validation routines to make input validation,
and untainting easier and more readable.
.PP
All functions return an untainted value if the test passes, and undef if
it fails.  This means that you should always check for a defined status explicitly.
Don't assume the return will be true. (e.g. is_username('0'))
.PP
The value to test is always the first (and often only) argument.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.IP "\fBnew\fR \- constructor for \s-1OO\s0 usage" 4
.IX Item "new - constructor for OO usage"
.Vb 4
\&  $obj = Data::Validate::Domain\->new();
\&  my %options = (
\&                domain_allow_underscore => 1,
\&  );
\&
\&  or
\&
\&  my %options = (
\&                domain_allow_single_label => 1,
\&                domain_private_tld => {
\&                        \*(Aqprivatetld1 \*(Aq   =>      1,
\&                        \*(Aqprivatetld2\*(Aq    =>      1,
\&                }
\&  );
\&
\&  or
\&
\&  my %options = (
\&                domain_allow_single_label => 1,
\&                domain_private_tld        => qr /^(?:privatetld1|privatetld2)$/,
\&  );
\&
\&
\&
\&
\&  $obj = Data::Validate::Domain\->new(%options);
.Ve
.RS 4
.IP "\fIDescription\fR" 4
.IX Item "Description"
Returns a Data::Validator::Domain object.  This lets you access all the validator function
calls as methods without importing them into your namespace or using the clumsy
\&\fBData::Validate::Domain::function_name()\fR format.
.IP "\fIOptions\fR" 4
.IX Item "Options"
.RS 4
.PD 0
.IP "\fBdomain_allow_underscore\fR" 4
.IX Item "domain_allow_underscore"
.PD
According to \s-1RFC\s0 underscores are forbidden in \*(L"hostnames\*(R" but not \*(L"domainnames\*(R".
By default is_domain,is_domain_label,  and is_hostname will fail if you include underscores, setting 
this to a true value with authorize the use of underscores in all functions.
.IP "\fBdomain_allow_single_label\fR" 4
.IX Item "domain_allow_single_label"
By default is_domain will fail if you ask it to verify a domain that only has a single label
i.e. 'neely.cx' is good, but 'com' would fail.  If you set this option to a true value then
is_domain will allow single label domains through.  This is most likely to be useful in 
combination with \fBdomain_private_tld\fR
.IP "\fBdomain_private_tld\fR" 4
.IX Item "domain_private_tld"
By default is_domain requires all domains to have a valid \s-1TLD\s0 (i.e. com, net, org, uk, etc),
this is verified using the Net::Domain::TLD module.  This behavior can be extended in two
different ways.  Either a hash reference can be supplied keyed by the additional \s-1TLD\s0's, or you
can supply a precompiled regular expression.
.Sp
\&\s-1NOTE:\s0  The \s-1TLD\s0 is normalized to the lower case form prior to the check being done.  This is 
done only for the \s-1TLD\s0 check, and does not alter the output in any way.
.Sp
.Vb 1
\&        The hash reference example:     
\&
\&                domain_private_tld => {
\&                        \*(Aqprivatetld1 \*(Aq   =>      1,
\&                        \*(Aqprivatetld2\*(Aq    =>      1,
\&                }
\&
\&        The precompiled regualar expression example:
\&
\&                domain_private_tld        => qr /^(?:privatetld1|privatetld2)$/,
.Ve
.RE
.RS 4
.RE
.IP "\fIReturns\fR" 4
.IX Item "Returns"
Returns a Data::Validate::Domain object
.RE
.RS 4
.RE
.IP "\fBis_domain\fR \- does the value look like a domain name?" 4
.IX Item "is_domain - does the value look like a domain name?"
.Vb 7
\&  is_domain($value);
\&  or
\&  $obj\->is_domain($value);
\&  or
\&  is_domain($value,\e%options);
\&  or
\&  $obj\->is_domain($value,\e%options);
.Ve
.RS 4
.IP "\fIDescription\fR" 4
.IX Item "Description"
Returns the untainted domain name if the test value appears to be a well-formed
domain name.
.Sp
Note:  See \fBnew\fR for list of options and how those alter the behavior of this 
funciton.
.IP "\fIArguments\fR" 4
.IX Item "Arguments"
.RS 4
.PD 0
.ie n .IP "$value" 4
.el .IP "\f(CW$value\fR" 4
.IX Item "$value"
.PD
The potential domain to test.
.RE
.RS 4
.RE
.IP "\fIReturns\fR" 4
.IX Item "Returns"
Returns the untainted domain on success, undef on failure.
.IP "\fINotes, Exceptions, & Bugs\fR" 4
.IX Item "Notes, Exceptions, & Bugs"
The function does not make any attempt to check whether a domain  
actually exists. It only looks to see that the format is appropriate.
.Sp
A dotted quad (such as 127.0.0.1) is not considered a domain and will return false.
See \fBData::Validate::IP\fR\|(3) for \s-1IP\s0 Validation.
.Sp
Performs a lookup via Net::Domain::TLD to verify that the \s-1TLD\s0 is valid for this domain.
.Sp
Does not consider \*(L"domain.com.\*(R" a valid format.
.IP "\fIFrom \s-1RFC 952\s0\fR" 4
.IX Item "From RFC 952"
.Vb 4
\&   A "name" (Net, Host, Gateway, or Domain name) is a text string up
\&   to 24 characters drawn from the alphabet (A\-Z), digits (0\-9), minus
\&   sign (\-), and period (.).  Note that periods are only allowed when
\&   they serve to delimit components of "domain style names".
\&
\&   No blank or space characters are permitted as part of a
\&   name. No distinction is made between upper and lower case.  The first
\&   character must be an alpha character [Relaxed in RFC 1123] .  The last 
\&   character must not be a minus sign or period.
.Ve
.IP "\fIFrom \s-1RFC 1035\s0\fR" 4
.IX Item "From RFC 1035"
.Vb 2
\&    labels          63 octets or less
\&    names           255 octets or less
\&
\&    [snip] limit the label to 63 octets or less.
\&
\&    To simplify implementations, the total length of a domain name (i.e.,
\&    label octets and label length octets) is restricted to 255 octets or
\&    less.
.Ve
.IP "\fIFrom \s-1RFC 1123\s0\fR" 4
.IX Item "From RFC 1123"
.Vb 4
\&    One aspect of host name syntax is hereby changed: the
\&    restriction on the first character is relaxed to allow either a
\&    letter or a digit.  Host software MUST support this more liberal
\&    syntax.
\&
\&    Host software MUST handle host names of up to 63 characters and
\&    SHOULD handle host names of up to 255 characters.
.Ve
.RE
.RS 4
.RE
.IP "\fBis_hostname\fR \- does the value look like a hostname" 4
.IX Item "is_hostname - does the value look like a hostname"
.Vb 7
\&  is_hostname($value);
\&  or
\&  $obj\->is_hostname($value);
\&  or
\&  is_hostname($value,\e%options);
\&  or
\&  $obj\->is_hostname($value,\e%options);
.Ve
.RS 4
.IP "\fIDescription\fR" 4
.IX Item "Description"
Returns the untainted hostname if the test value appears to be a well-formed
hostname.
.Sp
Note:  See \fBnew\fR for list of options and how those alter the behavior of this 
funciton.
.IP "\fIArguments\fR" 4
.IX Item "Arguments"
.RS 4
.PD 0
.ie n .IP "$value" 4
.el .IP "\f(CW$value\fR" 4
.IX Item "$value"
.PD
The potential hostname to test.
.RE
.RS 4
.RE
.IP "\fIReturns\fR" 4
.IX Item "Returns"
Returns the untainted hostname on success, undef on failure.
.IP "\fINotes, Exceptions, & Bugs\fR" 4
.IX Item "Notes, Exceptions, & Bugs"
The function does not make any attempt to check whether a hostname  
actually exists. It only looks to see that the format is appropriate.
.Sp
Functions much like is_domain, except that it does not verify whether or
not a valid \s-1TLD\s0 has been supplied and allows for there to only
be a single component of the hostname (i.e www)
.Sp
Hostnames might or might not have a valid \s-1TLD\s0 attached.
.RE
.RS 4
.RE
.IP "\fBis_domain_label\fR \- does the value look like a domain label?" 4
.IX Item "is_domain_label - does the value look like a domain label?"
.Vb 7
\&  is_domain_label($value);
\&  or
\&  $obj\->is_domain_label($value);
\&  or
\&  is_domain_label($value,\e%options);
\&  or
\&  $obj\->is_domain_label($value,\e%options);
.Ve
.RS 4
.IP "\fIDescription\fR" 4
.IX Item "Description"
Returns the untainted domain label if the test value appears to be a well-formed
domain label.
.Sp
Note:  See \fBnew\fR for list of options and how those alter the behavior of this 
funciton.
.IP "\fIArguments\fR" 4
.IX Item "Arguments"
.RS 4
.PD 0
.ie n .IP "$value" 4
.el .IP "\f(CW$value\fR" 4
.IX Item "$value"
.PD
The potential ip to test.
.RE
.RS 4
.RE
.IP "\fIReturns\fR" 4
.IX Item "Returns"
Returns the untainted domain label on success, undef on failure.
.IP "\fINotes, Exceptions, & Bugs\fR" 4
.IX Item "Notes, Exceptions, & Bugs"
The function does not make any attempt to check whether a domain label
actually exists. It only looks to see that the format is appropriate.
.RE
.RS 4
.RE
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fB[\s-1RFC 1034\s0] [\s-1RFC 1035\s0] [\s-1RFC 2181\s0] [\s-1RFC 1123\s0]\fR
.IP "\fBData::Validate\fR\|(3)" 4
.IX Item "Data::Validate"
.PD 0
.IP "\fBData::Validate::IP\fR\|(3)" 4
.IX Item "Data::Validate::IP"
.PD
.SH "AUTHOR"
.IX Header "AUTHOR"
Neil Neely <\fIneil@neely.cx\fR>.
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Thanks to Richard Sonnen <\fIsonnen@richardsonnen.com\fR> for writing the Data::Validate module.
.PP
Thanks to Len Reed <\fIlreed@levanta.com\fR> for helping develop the options mechanism for Data::Validate modules.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (c) 2005\-2007 Neil Neely.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.2 or,
at your option, any later version of Perl 5 you may have available.