Debian Codegraph @

README

raw
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