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.15
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 will 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 is_domain()
61           will allow single label domains through. This is most likely to be
62           useful in combination with the "domain_private_tld" argument.
63
64       •   domain_disable_tld_validation
65
66           Disables TLD validation for is_domain(). This may be useful if you
67           need to check domains with new gTLDs that have not yet been added
68           to Net::Domain::TLD.
69
70       •   domain_private_tld
71
72           By default is_domain() requires all domains to have a valid public
73           TLD (i.e.  com, net, org, uk, etc). This is verified using the
74           Net::Domain::TLD module.  This behavior can be extended in two
75           different ways. You can provide either a hash reference where
76           additional TLDs are keys or you can supply a regular expression.
77
78           NOTE: The TLD is normalized to the lower case form prior to the
79           check being done. This is done only for the TLD check, and does not
80           alter the output in any way.
81
82           Hashref example:
83
84             domain_private_tld => {
85                 privatetld1 => 1,
86                 privatetld2 => 1,
87             }
88
89           Regular expression example:
90
91            domain_private_tld => qr /^(?:privatetld1|privatetld2)$/,
92
93   is_domain($domain, \%options)
94       This can be called as either a subroutine or a method. If called as a
95       sub, you can pass any of the arguments accepted by the constructor as
96       options. If called as a method, any additional options are ignored.
97
98       This returns the untainted domain name if the given $domain is a valid
99       domain.
100
101       A dotted quad (such as 127.0.0.1) is not considered a domain and will
102       return false. See Data::Validate::IP for IP Validation.
103
104       Per RFC 1035, this sub does accept a value ending in a single period
105       (i.e.  "domain.com.") to be a valid domain. This is called an absolute
106       domain name, and should be properly resolved by any DNS tool (tested
107       with "dig", "ssh", and Net::DNS).
108
109       From RFC 952
110              A "name" (Net, Host, Gateway, or Domain name) is a text string up
111              to 24 characters drawn from the alphabet (A-Z), digits (0-9), minus
112              sign (-), and period (.). Note that periods are only allowed when
113              they serve to delimit components of "domain style names".
114
115              No blank or space characters are permitted as part of a
116              name. No distinction is made between upper and lower case. The first
117              character must be an alpha character [Relaxed in RFC 1123] . The last
118              character must not be a minus sign or period.
119
120       From RFC 1035
121               labels          63 octets or less
122               names           255 octets or less
123
124               [snip] limit the label to 63 octets or less.
125
126               To simplify implementations, the total length of a domain name (i.e.,
127               label octets and label length octets) is restricted to 255 octets or
128               less.
129
130       From RFC 1123
131               One aspect of host name syntax is hereby changed: the
132               restriction on the first character is relaxed to allow either a
133               letter or a digit. Host software MUST support this more liberal
134               syntax.
135
136               Host software MUST handle host names of up to 63 characters and
137               SHOULD handle host names of up to 255 characters.
138
139   is_hostname($hostname, \%options)
140       This can be called as either a subroutine or a method. If called as a
141       sub, you can pass any of the arguments accepted by the constructor as
142       options. If called as a method, any additional options are ignored.
143
144       This returns the untainted hostname if the given $hostname is a valid
145       hostname.
146
147       Hostnames are not required to end in a valid TLD.
148
149   is_domain_label($label, \%options)
150       This can be called as either a subroutine or a method. If called as a
151       sub, you can pass any of the arguments accepted by the constructor as
152       options. If called as a method, any additional options are ignored.
153
154       This returns the untainted label if the given $label is a valid label.
155
156       A domain label is simply a single piece of a domain or hostname. For
157       example, the "www.foo.com" hostname contains the labels "www", "foo",
158       and "com".
159

SEE ALSO

161       [RFC 1034] [RFC 1035] [RFC 2181] [RFC 1123]
162
163       Data::Validate
164       Data::Validate::IP
165

ACKNOWLEDGEMENTS

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

SUPPORT

174       Bugs may be submitted at
175       <https://github.com/houseabsolute/Data-Validate-Domain/issues>.
176
177       I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
178

SOURCE

180       The source code repository for Data-Validate-Domain can be found at
181       <https://github.com/houseabsolute/Data-Validate-Domain>.
182

AUTHORS

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

CONTRIBUTORS

189       •   Anirvan Chatterjee <anirvan@users.noreply.github.com>
190
191       •   David Steinbrunner <dsteinbrunner@pobox.com>
192
193       •   Felipe Gasper <felipe@felipegasper.com>
194
195       •   Gregory Oschwald <goschwald@maxmind.com>
196
198       This software is copyright (c) 2021 by Neil Neely.
199
200       This is free software; you can redistribute it and/or modify it under
201       the same terms as the Perl 5 programming language system itself.
202
203       The full text of the license can be found in the LICENSE file included
204       with this distribution.
205
206
207
208perl v5.36.0                      2023-01-20         Data::Validate::Domain(3)
Impressum