File: README

package info (click to toggle)
libdata-validate-domain-perl 0.10-1.1
  • links: PTS
  • area: main
  • in suites: bullseye, sid
  • size: 80 kB
  • sloc: perl: 95; makefile: 2
file content (250 lines) | stat: -rw-r--r-- 9,026 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
NAME
    Data::Validate::Domain - domain validation methods

SYNOPSIS
      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,\%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;

DESCRIPTION
    This module collects domain validation routines to make input
    validation, and untainting easier and more readable.

    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'))

    The value to test is always the first (and often only) argument.

FUNCTIONS
    new - constructor for OO usage
          $obj = Data::Validate::Domain->new();

          my %options = (
                        domain_allow_single_label => 1,
                        domain_private_tld => {
                                'privatetld1 '   =>      1,
                                'privatetld2'    =>      1,
                        }
          );

          or

          my %options = (
                        domain_allow_single_label => 1,
                        domain_private_tld        => qr /^(?:privatetld1|privatetld2)$/,
          );

          $obj = Data::Validate::Domain->new(%options);

        *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
            Data::Validate::Domain::function_name() format.

        *Options*

            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
                domain_private_tld

            domain_private_tld
                By default is_domain requires all domains to have a valid
                TLD (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 TLD's, or you can supply a
                precompiled regular expression.

                NOTE: The TLD is normalized to the lower case form prior to
                the check being done. This is done only for the TLD check,
                and does not alter the output in any way.

                        The hash reference example:     

                                domain_private_tld => {
                                        'privatetld1 '   =>      1,
                                        'privatetld2'    =>      1,
                                }

                        The precompiled regualar expression example:

                                domain_private_tld        => qr /^(?:privatetld1|privatetld2)$/,

        *Returns*
            Returns a Data::Validate::Domain object

    is_domain - does the value look like a domain name?
          is_domain($value);
          or
          $obj->is_domain($value);
          or
          is_domain($value,\%options);
          or
          $obj->is_domain($value,\%options);

        *Description*
            Returns the untainted domain name if the test value appears to
            be a well-formed domain name.

            Note: See new for list of options and how those alter the
            behavior of this funciton.

        *Arguments*

            $value
                The potential domain to test.

        *Returns*
            Returns the untainted domain on success, undef on failure.

        *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.

            A dotted quad (such as 127.0.0.1) is not considered a domain and
            will return false. See Data::Validate::IP(3) for IP Validation.

            Performs a lookup via Net::Domain::TLD to verify that the TLD is
            valid for this domain.

            Does not consider "domain.com." a valid format.

        *From RFC 952*
               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.

        *From RFC 1035*
                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.

        *From RFC 1123*
                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.

    is_hostname - does the value look like a hostname
          is_hostname($value);
          or
          $obj->is_hostname($value);
          or
          is_hostname($value,\%options);
          or
          $obj->is_hostname($value,\%options);

        *Description*
            Returns the untainted hostname if the test value appears to be a
            well-formed hostname.

            Note: See new for list of options and how those alter the
            behavior of this funciton.

        *Arguments*

            $value
                The potential hostname to test.

        *Returns*
            Returns the untainted hostname on success, undef on failure.

        *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.

            Functions much like is_domain, except that it does not verify
            whether or not a valid TLD has been supplied and allows for
            there to only be a single component of the hostname (i.e www)

            Hostnames might or might not have a valid TLD attached.

    is_domain_label - does the value look like a domain label?
          is_domain_label($value);
          or
          $obj->is_domain_label($value);
          or
          is_domain_label($value,\%options);
          or
          $obj->is_domain_label($value,\%options);

        *Description*
            Returns the untainted domain label if the test value appears to
            be a well-formed domain label.

            Note: See new for list of options and how those alter the
            behavior of this funciton.

        *Arguments*

            $value
                The potential ip to test.

        *Returns*
            Returns the untainted domain label on success, undef on failure.

        *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.

SEE ALSO
        [RFC 1034] [RFC 1035] [RFC 2181] [RFC 1123]

        Data::Validate(3)
        Data::Validate::IP(3)

AUTHOR
        Neil Neely <neil@neely.cx>.

ACKNOWLEDGEMENTS
        Thanks to Richard Sonnen <sonnen@richardsonnen.com> for writing the
        Data::Validate module.

        Thanks to Len Reed <lreed@levanta.com> for helping develop the
        options mechanism for Data::Validate modules.

COPYRIGHT AND LICENSE
        Copyright (c) 2005-2006 Neil Neely.

        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.