Data::...te::URI(3pm)

📦
version 0.07 · 2 versions
, in debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Data::Validate::URI 💖 (that's the Data::...te::URI(3pm) page bestie, come get ur URI validation)

okay so real quick, before we dive in: this is the manual page for Data::Validate::URI, a Perl module that does exactly what it says on the tin. it's giving "input validation but make it cute," and honestly? we ate.

🌸 NAME 🌸

Data::Validate::URI — common url validation methods ✨

🎀 SYNOPSIS 🎀

okay the vibe is: you've got a $suspect string and you want to know if it's a URI. say less.

use Data::Validate::URI qw(is_uri);

if(is_uri($suspect)){
      print "Looks like an URI\n";
} else {
      print "Not a URI\n";
}

# or as an object
my $v = Data::Validate::URI->new();

die "not a URI" unless ($v->is_uri('foo'));

like. it's that easy. no notes. 💅

💜 DESCRIPTION 💜

so this module collects a bunch of common URI validation routines together so that input validation and untainting is easier and more readable. iconic behavior honestly. 🫶

the big rule, memorize it: every single function returns an untainted value if the test passes, and returns undef if it fails. that means you should always check for a defined status explicitly. do NOT just assume the return will be true. no cap. fr fr. 🙈

and the value you're testing is always the first argument (and, like, often the only one).

yes bestie there are a bunch of other URI validation modules out there (peep SEE ALSO below 👀). this one is focused on being fast, lightweight, and relatively 'real-world'. i.e. it's the one you want when you're checking user input and you do not need the URI/URL parsed out into chunks. main character energy.

right now the module focuses on HTTP URIs, since they're arguably the most common. if you have a specialized scheme you'd like supported, let the author know.

✨ FUNCTIONS ✨

🦋 new — constructor for OO usage

new(%options);

Description

returns a Data::Validator::URI object. this lets you access all the validator function calls as methods without importing them into your namespace or using that clumsy Data::Validate::URI::function_name() format. we love a method call moment. 💅

Arguments

  • %options — options to be passed into the underlying Data::Validate::Domain module

Returns

returns a Data::Validate::URI object 👑

🍓 is_uri — is the value a well-formed uri?

is_uri($value);

Description

returns the untainted URI if the test value looks well-formed.

heads up bestie: you might actually want one of the more practical methods like is_http_uri or is_https_uri, because the URI standard (RFC 3986) allows a whole lot of things you probably don't want. 😭

Arguments

  • $value — the potential URI to test.

Returns

returns the untainted URI on success, undef on failure.

Notes, Exceptions, & Bugs

this function makes no attempt whatsoever to check whether the URI is accessible or 'makes sense' in any meaningful way. it just checks that it's formatted correctly. that's it. that's the job. 💀

🌈 is_http_uri — is the value a well-formed HTTP uri?

is_http_uri($value, \%options);

Description

this is the specialized version of is_uri() that only likes http:// urls. and because it's specialized, it can also do a much more thorough job validating. also, unlike is_uri(), it's way more concerned with only letting real-world URIs through. things like relative hostnames are allowed by the standards but are probably... not wise. conversely, null paths aren't allowed per RFC 2616 (should be '/' instead), but are allowed by this function. slay, we make our own rules.

this function only works for fully-qualified URIs. /bob.html won't work. see RFC 3986 for the appropriate method to turn a relative URI into an absolute one given its context.

returns the untainted URI if the test value looks well-formed.

📌 note that you probably want to call this in combo with is_https_uri(). i.e.
print "Good" if(is_http_uri($uri) || is_https_uri($uri));

or just use the convenience method is_web_uri, which is equivalent and faster, because it does the work only once. efficiency queen. ⭐

Arguments

  • $value — the potential URI to test.
  • \%options — options to be passed into the underlying Data::Validate::Domain module. if called as a method, the options are ignored.

Returns

returns the untainted URI on success, undef on failure.

Notes, Exceptions, & Bugs

this function makes no attempt to check whether the URI is accessible or 'makes sense' in any meaningful way. it just checks that it's formatted correctly. periodt.

👑 is_https_uri — is the value a well-formed HTTPS uri?

is_https_uri($value. \%options);
(yes the $value. there is exactly how it's written, don't come for me, that's the page 🫶)

Description

see is_http_uri() for details. this version only likes the https URI scheme. other than that it is identical to is_http_uri(). twins. 🧚

Arguments

  • $value — the potential URI to test.
  • \%options — options to be passed into the underlying Data::Validate::Domain module. if called as a method, the options are ignored.

Returns

returns the untainted URI on success, undef on failure.

Notes, Exceptions, & Bugs

this function makes no attempt to check whether the URI is accessible or 'makes sense' in any meaningful way. it just checks that it's formatted correctly.

⭐ is_web_uri — is the value a well-formed HTTP or HTTPS uri?

is_web_uri($value, \%options);

Description

this is just a convinience method (that's how it's spelled on the page, bestie, we keep it 💖) that combines is_http_uri and is_https_uri so you can accept most common real-world URLs. but it's faster, because it does the work only once. two birds, one validation pass. ate.

Arguments

  • $value — the potential URI to test.
  • \%options — options to be passed into the underlying Data::Validate::Domain module. if called as a method, the options are ignored.

Returns

returns the untainted URI on success, undef on failure.

Notes, Exceptions, & Bugs

this function makes no attempt to check whether the URI is accessible or 'makes sense' in any meaningful way. it just checks that it's formatted correctly.

🦄 is_tel_uri — is the value a well-formed telephone uri?

is_tel_uri($value);

Description

specialized version of is_uri() that only likes tel: urls. and as a result, it can also do a much more thorough job validating according to RFC 3966. dialing up the accuracy, literally. 📞

returns the untainted URI if the test value looks well-formed.

Arguments

  • $value — the potential URI to test.

Returns

returns the untainted URI on success, undef on failure.

Notes, Exceptions, & Bugs

this function makes no attempt to check whether the URI is accessible or 'makes sense' in any meaningful way. it just checks that it's formatted correctly.

🔥 SEE ALSO 🔥

URI, RFC 3986, RFC 3966, RFC 4694, RFC 4759, RFC 4904

go read the RFCs, bestie. iykyk. 📚

🫶 AUTHOR 🫶

Richard Sonnen <sonnen@richardsonnen.com>.

is_tel_uri by David Dick <ddick@cpan.org>. 💜

Copyright (c) 2005 Richard Sonnen. All rights reserved.

this program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

and that's the whole page, bestie!! no skips, no summarising, every single flag and function accounted for. 💅✨

this gem was brought to you by perl v5.38.2, dated 2024-03-04, and last seen being its iconic multi-scheme validating self as Data::...te::URI(3pm). mwah. 😘🎀
📦 where this page comes from