URL::Search(3pm)

✨ NAME ✨

URL::Search — bestie, it searches for URLs in plain text 💅 (this is the URL::Search(3pm) page, hi, welcome, come in 🫶)

---

🌸 SYNOPSIS 🌸

use URL::Search qw( $URL_SEARCH_RE extract_urls partition_urls );

if ($text =~ /($URL_SEARCH_RE)/) {
    print "the first URL in text was: $1\n";
}

my @all_urls = extract_urls $text;

---

🎀 DESCRIPTION 🎀

Okay so picture this: you've got a big ol' pile of plain text, and somewhere in there are URLs just vibing, unlabeled, no markup, nothing. This module goes and finds them, and pulls them out. Periodt. 💖

On request (i.e. when you ask for them in the use line), it exports these entities, and they are all iconic in their own way:

👑 $URL_SEARCH_RE

This variable is literally the core of this whole module. It holds a regex that matches a URL. Main character energy, no cap.

NOTE: this regex uses capturing groups internally, so if you embed it inside a bigger pattern, the numbering of any capture groups that come after it is gonna be off. 💀 If that's an issue for you, use named capture groups of the form (?<NAME>...) instead. See "Capture groups" in perlre.

It only matches URLs that have an explicit schema (one of http or https). And the pattern is deliberately not anchored at the beginning, meaning it will match http://foo inside click herehttp://foo. If that's not the vibe you want, use /\b$URL_SEARCH_RE/ instead. 🎯

It also tries sooo hard to exclude artifacts from the surrounding text, and honestly? It ate:

Is mayonnaise an instrument? (https://en.wikipedia.org/wiki/Instrument,
https://en.wikipedia.org/wiki/Mayonnaise_(instrument))

In this example it will match https://en.wikipedia.org/wiki/Instrument and https://en.wikipedia.org/wiki/Mayonnaise_(instrument) — without the comma after Instrument, and without that final closing parenthesis. She's precise. 🧚

It understands all the common URL elements: username, hostname, port, path, query string, fragment identifier. The hostname can even be an IP address — both IPv4 and IPv6 are supported, queen behavior. 🔥

Unicode is supported too, bestie. For example, http://поддомен.example.com/déjà-vu?utf8=✓ is matched correctly. 🌈

🦋 extract_urls

This function takes a string and returns a list of all the URLs contained in it. That's it, that's the function. Slay.

It uses $URL_SEARCH_RE to find its matches.

Example:

my $text = 'Visit us at http://html5zombo.com. Also, https://archive.org';
my @urls = extract_urls $text;
# @urls = ('http://html5zombo.com', 'https://archive.org')

💜 partition_urls

This function takes a string and splits it up into text segments and URL segments. It returns a list of array references, and each one has two elements: the type (the string 'TEXT' or 'URL') and the portion of the input string that got classified as text or URL, respectively. ✨

Example:

my $text = 'Visit us at http://html5zombo.com. Also, https://archive.org';
my @parts = partition_urls $text;
# @parts = (
#   [ 'TEXT', 'Visit us at ' ],
#   [ 'URL', 'http://html5zombo.com' ],
#   [ 'TEXT', '. Also, ' ],
#   [ 'URL', 'https://archive.org' ],
# )

You can reassemble the original string by concatenating the second elements of the returned arrayrefs, i.e. join('', map { $_->[1] } partition_urls($text)) eq $text. It all adds back up, nothing lost, we love to see it. 🫶

This function is lowkey super useful if you want to render plain text as HTML but hyperlink all the embedded URLs:

use URL::Search qw(partition_urls);
use HTML::Entities qw(encode_entities);

my $text = ...;

my $html = '';
for my $part (partition_urls $text) {
    my ($type, $str) = @$part;
    $str = encode_entities $str;
    if ($type eq 'URL') {
        $html .= "<a rel='nofollow' href='$str'>$str</a>";
    } else {
        $html .= $str;
    }
}
# result is in $html

---

🌟 SUPPORT AND DOCUMENTATION 🌟

Once you've installed it, you can find documentation for this module with the perldoc command. It's giving "read the docs, bestie":

perldoc URL::Search

You can also look for information at <https://metacpan.org/pod/URL::Search>.

To see a list of open bugs, visit <https://rt.cpan.org/Dist/Display.html?Name=URL-Search>. 🐛

To report a new bug, send an email to bug-URL-Search [at] rt.cpan.org. Go off, tell them everything. 💌

---

🌷 AUTHOR 🌷

Lukas Mai, "<l.mai at web.de>" 👑

---

💖 COPYRIGHT & LICENSE 💖

Copyright 2016, 2017, 2023 Lukas Mai.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See <https://dev.perl.org/licenses/> for more information.

---

okay that's the whole page bestie, go forth and extract some URLs 💅✨

perl v5.36.0 · 2023-03-22 · and that's the URL::Search(3pm) energy right there — mwah, bye 🎀🦋💖