| 1 |
NAME |
| 2 |
URI::Find::Delimited - Find URIs which may be wrapped in enclosing |
| 3 |
delimiters. |
| 4 |
|
| 5 |
DESCRIPTION |
| 6 |
Works like URI::Find, but is prepared for URIs in your text to be |
| 7 |
wrapped in a pair of delimiters and optionally have a title. This will |
| 8 |
be useful for processing text that already has some minimal markup in |
| 9 |
it, like bulletin board posts or wiki text. |
| 10 |
|
| 11 |
SYNOPSIS |
| 12 |
my $finder = URI::Find::Delimited->new; |
| 13 |
my $text = "This is a [http://the.earth.li/ titled link]."; |
| 14 |
$finder->find(\$text); |
| 15 |
print $text; |
| 16 |
|
| 17 |
METHODS |
| 18 |
new |
| 19 |
my $finder = URI::Find::Delimited->new( |
| 20 |
callback => \&callback, |
| 21 |
delimiter_re => [ '\[', '\]' ], |
| 22 |
ignore_quoted => 1 # defaults to 0 |
| 23 |
); |
| 24 |
|
| 25 |
All arguments are optional; defaults are provided (see below). |
| 26 |
|
| 27 |
Creates a new URI::Find::Delimited object. This object works |
| 28 |
similarly to a URI::Find object, but as well as just looking for |
| 29 |
URIs it is also aware of the concept of a wrapped, titled URI. These |
| 30 |
look something like |
| 31 |
|
| 32 |
[http://foo.com/ the foo website] |
| 33 |
|
| 34 |
where: |
| 35 |
|
| 36 |
* "[" is the opening delimiter |
| 37 |
* "]" is the closing delimiter |
| 38 |
* "http://foo.com/" is the URI |
| 39 |
* "the foo website" is the title |
| 40 |
* the URI and title are separated by spaces and/or tabs |
| 41 |
|
| 42 |
The URI::Find::Delimited object will extract each of these parts |
| 43 |
separately and pass them to your callback. |
| 44 |
|
| 45 |
callback |
| 46 |
"callback" is a function which is called on each URI found. It |
| 47 |
is passed five arguments: the opening delimiter (if found), the |
| 48 |
closing delimiter (if found), the URI, the title (if found), and |
| 49 |
any whitespace found between the URI and title. |
| 50 |
|
| 51 |
The return value of the callback will replace the original URI |
| 52 |
in the text. |
| 53 |
|
| 54 |
If you do not supply your own callback, the object will create a |
| 55 |
default one which will put your URIs in 'a href' tags using the |
| 56 |
URI for the target and the title for the link text. If no title |
| 57 |
is provided for a URI then the URI itself will be used as the |
| 58 |
title. If the delimiters aren't balanced (eg if the opening one |
| 59 |
is present but no closing one is found) then the URI is treated |
| 60 |
as not being wrapped. |
| 61 |
|
| 62 |
Note: the default callback will not remove the delimiters from |
| 63 |
the text. It should be simple enough to write your own callback |
| 64 |
to remove them, based on the one in the source, if that's what |
| 65 |
you want. In fact there's an example in this distribution, in |
| 66 |
"t/delimited.t". |
| 67 |
|
| 68 |
delimiter_re |
| 69 |
The "delimiter_re" parameter is optional. If you do supply it |
| 70 |
then it should be a ref to an array containing two regexes. It |
| 71 |
defaults to using single square brackets as the delimiters. |
| 72 |
|
| 73 |
Don't use capturing groupings "( )" in your delimiters or things |
| 74 |
will break. Use non-capturing "(?: )" instead. |
| 75 |
|
| 76 |
ignore_quoted |
| 77 |
If the "ignore_quoted" parameter is supplied and set to a true |
| 78 |
value, then any URIs immediately preceded with a double-quote |
| 79 |
character will not be matched, ie your callback will not be |
| 80 |
executed for them and they'll be treated just as normal text. |
| 81 |
|
| 82 |
This is a bit of a hack but it's in here because I need to be |
| 83 |
able to ignore things like |
| 84 |
|
| 85 |
<img src="http://foo.com/bar.gif"> |
| 86 |
|
| 87 |
A better implementation may happen at some point. |
| 88 |
|
| 89 |
SEE ALSO |
| 90 |
URI::Find. |
| 91 |
|
| 92 |
AUTHOR |
| 93 |
Kake Pugh ([email protected]). |
| 94 |
|
| 95 |
COPYRIGHT |
| 96 |
Copyright (C) 2003 Kake Pugh. All Rights Reserved. |
| 97 |
|
| 98 |
This module is free software; you can redistribute it and/or modify |
| 99 |
it under the same terms as Perl itself. |
| 100 |
|
| 101 |
CREDITS |
| 102 |
Tim Bagot helped me stop faffing over the name, by pointing out that |
| 103 |
RFC 2396 Appendix E uses "delimited". Dave Hinton helped me fix the |
| 104 |
regex to make it work for delimited URIs with no title. Nick Cleaton |
| 105 |
helped me make "ignore_quoted" work. Some of the code was taken from |
| 106 |
URI::Find. |
| 107 |
|