1Data::Validate::Domain(U3s)er Contributed Perl DocumentatDiaotna::Validate::Domain(3)
2
6 Data::Validate::Domain - Domain and host name validation
7
9 version 0.15
10
12 use Data::Validate::Domain qw(is_domain);
13 # as a function
15 my $test = is_domain($suspect);
16 die "$test is not a domain" unless $test;
17 # or
19 die "$test is not a domain" unless is_domain($suspect, \%options);
21 # or as an object
23 my $v = Data::Validate::Domain->new(%options);
24 die "$test is not a domain" unless $v->is_domain($suspect);
26
28 This module offers a few subroutines for validating domain and host
29 names.
30
32 All of the functions below are exported by default.
33 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 The value to test is always the first (and often only) argument.
40 Note that none of these functions test whether a domain or hostname is
42 actually resolvable or reachable.
43 Data::Validate::Domain->new()
45 This method constructs a validation object. It accepts the following
46 arguments:
47 • domain_allow_underscore
49 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 • domain_allow_single_label
57 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 • domain_disable_tld_validation
65 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 • domain_private_tld
71 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 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 Hashref example:
83 domain_private_tld => {
85 privatetld1 => 1,
86 privatetld2 => 1,
87 }
88 Regular expression example:
90 domain_private_tld => qr /^(?:privatetld1|privatetld2)$/,
92 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 This returns the untainted domain name if the given $domain is a valid
99 domain.
100 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 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 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 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 From RFC 1035
121 labels 63 octets or less
122 names 255 octets or less
123 [snip] limit the label to 63 octets or less.
125 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 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 Host software MUST handle host names of up to 63 characters and
137 SHOULD handle host names of up to 255 characters.
138 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 This returns the untainted hostname if the given $hostname is a valid
145 hostname.
146 Hostnames are not required to end in a valid TLD.
148 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 This returns the untainted label if the given $label is a valid label.
155 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
161 [RFC 1034] [RFC 1035] [RFC 2181] [RFC 1123]
162 Data::Validate
164 Data::Validate::IP
165
167 Thanks to Richard Sonnen <sonnen@richardsonnen.com> for writing the
168 Data::Validate module.
169 Thanks to Len Reed <lreed@levanta.com> for helping develop the options
171 mechanism for Data::Validate modules.
172
174 Bugs may be submitted at
175 <https://github.com/houseabsolute/Data-Validate-Domain/issues>.
176 I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
178
180 The source code repository for Data-Validate-Domain can be found at
181 <https://github.com/houseabsolute/Data-Validate-Domain>.
182
184 • Neil Neely <neil@neely.cx>
185 • Dave Rolsky <autarch@urth.org>
187
189 • Anirvan Chatterjee <anirvan@users.noreply.github.com>
190 • David Steinbrunner <dsteinbrunner@pobox.com>
192 • Felipe Gasper <felipe@felipegasper.com>
194 • Gregory Oschwald <goschwald@maxmind.com>
196
198 This software is copyright (c) 2021 by Neil Neely.
199 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 The full text of the license can be found in the LICENSE file included
204 with this distribution.
205perl v5.36.0 2023-01-20 Data::Validate::Domain(3)