Data::Validate::Domain(3pm)

1Data::Validate::Domain(U3s)er Contributed Perl DocumentatDiaotna::Validate::Domain(3)
2
3
4

NAME

6       Data::Validate::Domain - Domain and host name validation
7

VERSION

9       version 0.14
10

SYNOPSIS

12         use Data::Validate::Domain qw(is_domain);
13
14         # as a function
15         my $test = is_domain($suspect);
16         die "$test is not a domain" unless $test;
17
18         # or
19
20         die "$test is not a domain" unless is_domain($suspect, \%options);
21
22         # or as an object
23         my $v = Data::Validate::Domain->new(%options);
24
25         die "$test is not a domain" unless $v->is_domain($suspect);
26

DESCRIPTION

28       This module offers a few subroutines for validating domain and host
29       names.
30

FUNCTIONS

32       All of the functions below are exported by default.
33
34       All of the functions return an untainted value on success and a false
35       value ("undef" or an empty list) on failure. In scalar context, you
36       should check that the return value is defined, because something like
37       "is_domain_label('0')" will return a defined but false value.
38
39       The value to test is always the first (and often only) argument.
40
41       Note that none of these functions test whether a domain or hostname is
42       actually resolvable or reachable.
43
44   Data::Validate::Domain->new()
45       This method constructs a validation object. It accepts the following
46       arguments:
47
48       •   domain_allow_underscore
49
50           According to RFC underscores are forbidden in hostnames but not
51           domain names.  By default "is_domain()", "is_domain_label()", and
52           "is_hostname()" will fail if the value to be checked includes
53           underscores. Setting this to a true value with allow the use of
54           underscores in all functions.
55
56       •   domain_allow_single_label
57
58           By default "is_domain()" will fail if you ask it to verify a domain
59           that only has a single label i.e. "neely.cx" is good, but "com"
60           would fail. If you set this option to a true value then
61           "is_domain()" will allow single label domains through. This is most
62           likely to be useful in combination with the "domain_private_tld"
63           argument.
64
65       •   domain_disable_tld_validation
66
67           Disables TLD validation for "is_domain()". This may be useful if
68           you need to check domains with new gTLDs that have not yet been
69           added to Net::Domain::TLD.
70
71       •   domain_private_tld
72
73           By default "is_domain()" requires all domains to have a valid
74           public TLD (i.e. com, net, org, uk, etc). This is verified using
75           the Net::Domain::TLD module. This behavior can be extended in two
76           different ways. You can provide either a hash reference where
77           additional TLDs are keys or you can supply a regular expression.
78
79           NOTE: The TLD is normalized to the lower case form prior to the
80           check being done. This is done only for the TLD check, and does not
81           alter the output in any way.
82
83           Hashref example:
84
85             domain_private_tld => {
86                 privatetld1 => 1,
87                 privatetld2 => 1,
88             }
89
90           Regular expression example:
91
92            domain_private_tld => qr /^(?:privatetld1|privatetld2)$/,
93
94   is_domain($domain, \%options)
95       This can be called as either a subroutine or a method. If called as a
96       sub, you can pass any of the arguments accepted by the constructor as
97       options. If called as a method, any additional options are ignored.
98
99       This returns the untainted domain name if the given $domain is a valid
100       domain.
101
102       A dotted quad (such as 127.0.0.1) is not considered a domain and will
103       return false.  See Data::Validate::IP for IP Validation.
104
105       Per RFC 1035, this sub does accept a value ending in a single period
106       (i.e. "domain.com.") to be a valid domain. This is called an absolute
107       domain name, and should be properly resolved by any DNS tool (tested
108       with "dig", "ssh", and Net::DNS).
109
110       From RFC 952
111              A "name" (Net, Host, Gateway, or Domain name) is a text string up
112              to 24 characters drawn from the alphabet (A-Z), digits (0-9), minus
113              sign (-), and period (.). Note that periods are only allowed when
114              they serve to delimit components of "domain style names".
115
116              No blank or space characters are permitted as part of a
117              name. No distinction is made between upper and lower case. The first
118              character must be an alpha character [Relaxed in RFC 1123] . The last
119              character must not be a minus sign or period.
120
121       From RFC 1035
122               labels          63 octets or less
123               names           255 octets or less
124
125               [snip] limit the label to 63 octets or less.
126
127               To simplify implementations, the total length of a domain name (i.e.,
128               label octets and label length octets) is restricted to 255 octets or
129               less.
130
131       From RFC 1123
132               One aspect of host name syntax is hereby changed: the
133               restriction on the first character is relaxed to allow either a
134               letter or a digit. Host software MUST support this more liberal
135               syntax.
136
137               Host software MUST handle host names of up to 63 characters and
138               SHOULD handle host names of up to 255 characters.
139
140   is_hostname($hostname, \%options)
141       This can be called as either a subroutine or a method. If called as a
142       sub, you can pass any of the arguments accepted by the constructor as
143       options. If called as a method, any additional options are ignored.
144
145       This returns the untainted hostname if the given $hostname is a valid
146       hostname.
147
148       Hostnames are not required to end in a valid TLD.
149
150   is_domain_label($label, \%options)
151       This can be called as either a subroutine or a method. If called as a
152       sub, you can pass any of the arguments accepted by the constructor as
153       options. If called as a method, any additional options are ignored.
154
155       This returns the untainted label if the given $label is a valid label.
156
157       A domain label is simply a single piece of a domain or hostname. For
158       example, the "www.foo.com" hostname contains the labels "www", "foo",
159       and "com".
160

ACKNOWLEDGEMENTS

168       Thanks to Richard Sonnen <sonnen@richardsonnen.com> for writing the
169       Data::Validate module.
170
171       Thanks to Len Reed <lreed@levanta.com> for helping develop the options
172       mechanism for Data::Validate modules.
173

SUPPORT

175       Bugs may be submitted through the RT bug tracker
176       <http://rt.cpan.org/Public/Dist/Display.html?Name=Data-Validate-Domain>
177       (or bug-data-validate-domain@rt.cpan.org <mailto:bug-data-validate-
178       domain@rt.cpan.org>).
179
180       I am also usually active on IRC as 'drolsky' on "irc://irc.perl.org".
181

AUTHORS

183       •   Neil Neely <neil@neely.cx>
184
185       •   Dave Rolsky <autarch@urth.org>
186

CONTRIBUTORS

188       •   David Steinbrunner <dsteinbrunner@pobox.com>
189
190       •   Gregory Oschwald <goschwald@maxmind.com>
191

COPYRIGHT AND LICENSE

193       This software is copyright (c) 2016 by Neil Neely.
194
195       This is free software; you can redistribute it and/or modify it under
196       the same terms as the Perl 5 programming language system itself.
197
198
199
200perl v5.34.0                      2021-07-22         Data::Validate::Domain(3)