Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Data::Validate::DomainUser Contributed Perl DocumentaData::Validate::Domain(3)

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.

perl v5.24.1			  2010-12-29	     Data::Validate::Domain(3)

NAME | SYNOPSIS | DESCRIPTION | FUNCTIONS | SEE ALSO | AUTHOR | ACKNOWLEDGEMENTS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Data::Validate::Domain&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help