URI::F...imited(3pm)

🌸 URI::F...imited(3pm) — bestie edition 🌸

okay so this is the manual page for URI::F...imited, which lives in the User Contributed Perl Documentation corner of the perl universe. buckle up, we're finding links 💅

---

✨ NAME ✨

URI::Find::Delimited — bestie, it finds URIs that might be wrapped up all cozy in enclosing delimiters 🎀

---

💖 DESCRIPTION 💖

okay so it works exactly like URI::Find, but it's prepared. like, it knows your URIs in the text might be wrapped in a little pair of delimiters, and might optionally have a title too. this is lowkey so useful when you're processing text that already has some minimal markup going on — think bulletin board posts, wiki text, that kind of vibe. it's giving "I read the room" ✨

---

🦋 SYNOPSIS 🦋

  my $finder = URI::Find::Delimited->new;
  my $text = "This is a [http://the.earth.li/ titled link].";
  $finder->find(\$text);
  print $text;

---

💅 METHODS 💅

new

my $finder = URI::Find::Delimited->new(
    callback      => \&callback,
    delimiter_re  => [ '\[', '\]' ],
    ignore_quoted => 1               # defaults to 0
);

every single argument here is optional, no cap — defaults are provided and they're listed down below 👇

this makes you a brand new URI::Find::Delimited object. it works similarly to a URI::Find object, but on top of just looking for URIs, it also understands the whole concept of a wrapped, titled URI. those look something like this:

[http://foo.com/ the foo website]

and inside that little situation:

• [ is the opening delimiter
• ] is the closing delimiter
• http://foo.com/ is the URI
• the foo website is the title
• the URI and the title are separated by spaces and/or tabs

the URI::Find::Delimited object will pull each of those parts out separately and hand them over to your callback. iconic behaviour, honestly 🫶

callback

callback is a function that gets called on every URI found. it gets passed five arguments: the opening delimiter (if one was found), the closing delimiter (if one was found), the URI, the title (if one was found), and any whitespace found between the URI and the title.

whatever your callback returns will replace the original URI in the text. main character energy 🔥

if you don't supply your own callback, the object will make a default one for you. that default one puts your URIs in a href tags, using the URI as the target and the title as the link text. if a URI has no title, then the URI itself gets used as the title. and if the delimiters aren't balanced (like, say the opening one is there but no closing one shows up), then the URI gets treated as not being wrapped at all. fair enough 💁

Note: the default callback will not remove the delimiters from the text. if that's what you want, it should be simple enough to write your own callback to strip them out, based on the one in the source. there's literally an example in this distribution, in t/delimited.t. go look, i'll wait 🌸

delimiter_re

the delimiter_re parameter is optional. if you do supply it, it should be a ref to an array containing two regexes. it defaults to using single square brackets as the delimiters.

Don't use capturing groupings ( ) in your delimiters or things will break. use non-capturing (?: ) instead. fr fr, this one matters 💀

ignore_quoted

if the ignore_quoted parameter is supplied and set to a true value, then any URIs immediately preceded by a double-quote character won't be matched. meaning: your callback will not be executed for them, and they'll just be treated like normal text. bye 👋

this is a bit of a hack but it's in here because the author needed to be able to ignore things like

<img src="http://foo.com/bar.gif">

a better implementation may happen at some point. we love an honest queen 🙈

---

🌈 SEE ALSO 🌈

URI::Find.

---

👑 AUTHOR 👑

Kake Pugh (kake@earth.li).

---

🎀 COPYRIGHT 🎀

     Copyright (C) 2003 Kake Pugh.  All Rights Reserved.

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

---

⭐ CREDITS ⭐

Tim Bagot helped stop the faffing over the name, by pointing out that RFC 2396 Appendix E uses "delimited". Dave Hinton helped fix the regex so it works for delimited URIs with no title. Nick Cleaton helped make ignore_quoted actually work. and some of the code was taken from URI::Find. a whole squad, honestly 🫶

---

💀 POD ERRORS 💀

hey! the above document had some coding errors, which are explained below:

Around line 194:

    You forgot a '=back' before '=head1'

---

and that's the whole page, bestie 🌸 brought to you by perl v5.34.0, dated 2022-06-28. mwah, go find some URIs 💅✨