Provided by: libdata-validate-domain-perl_0.10-1.1_all bug

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_underscore => 1,
             );

             or

             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_underscore
                   According to RFC underscores are forbidden in "hostnames" but not
                   "domainnames".  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.

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