Glossary.pm

filter: Statementstmt 90.2% 139 / 154 Branchbran 83.3% 40 / 48 Conditioncond 69.2% 18 / 26 MC/DCmcdc 47.0% 8 / 17 Subroutinesub 100% 13 / 13 Podpod 75.0% 6 / 8 totaltotal 84.2% 224 / 266 CC 35 SCAR 20.0
CC
35
Cov
86%
process_result
14.7
register_namespace
9.2
start_element
7.0
CRAP 7.4
↑ Summary Glossary/XBEL.pm »
1 =head1 NAME
2  
3 XML::Filter::Glossary - SAX2 filter for keyword lookup and replacement
4  
5 =head1 SYNOPSIS
6  
7 use XML::SAX::Writer;
8 use XML::Filter::Glossary;
9 use XML::SAX::ParserFactory;
10  
11 my $writer = XML::SAX::Writer->new();
12 my $glossary = XML::Filter::Glossary->new(Handler=>$writer);
13 my $parser = XML::SAX::ParserFactory->parser(Handler=>$glossary);
14  
15 $glossary->set_glossary("/usr/home/asc/bookmarks.xbel");
16 $parser->parse_string("<?xml version = '1.0' ?><root>This is \"aaronland\"</root>");
17  
18 # prints :
19  
20 <?xml version = "1.0" ?>
21 <root>
22 This is <a href='http://www.aaronland.net'>aaronland</a>
23 </root>
24  
25 =head1 DESCRIPTION
26  
27 This package is modelled after the UserLand glossary system where words, or phrases, wrapped in double-quotes are compared against a lookup table and are replaced by their corresponding entries.
28  
29 Currently only one type of lookup table is supported : a well-formed XBEL bookmarks file. Support for other kinds of lookup tables may be added at a later date.
30  
31 =head1 KEYWORDS
32  
33 Keywords are flagged as being any word, or words, between double quotes which are then looked up in the glossary. Alternately, you may specify keyword phrases with singleton elements that are the property of a user-defined namespace.
34  
35 If no match is found, the text is left unaltered.
36  
37 If a match is located, the result is then parsed with Robert Cameron's REX shallow parsing regular expressions. Chunks of balanced markup are then re-inserted into the SAX stream via I<XML::Filter::Merger>. Anything else, including markup not determined to be well-formed, is added as character data.
38  
39 =cut
40  
41 package XML::Filter::Glossary;
42 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
43  
44 2 ▶use XML::Filter::Merger;
Subroutine BEGIN: called CC=1 SCAR=0.0
45 2 ▶use XML::SAX::ParserFactory;
Subroutine BEGIN: called CC=1 SCAR=0.0
46  
47 2 ▶use vars qw( @ISA );
Subroutine BEGIN: called CC=1 SCAR=0.0
48 2 @ISA = qw( XML::Filter::Merger );
49  
50 2 $XML::Filter::Glossary::VERSION = '0.2';
51  
52 # REX/Perl 1.0
53 # Robert D. Cameron "REX: XML Shallow Parsing with Regular Expressions",
54 # Technical Report TR 1998-17, School of Computing Science, Simon Fraser
55 # University, November, 1998.
56 # Copyright (c) 1998, Robert D. Cameron.
57 # The following code may be freely used and distributed provided that
58 # this copyright and citation notice remains intact and that modifications
59 # or additions are clearly identified.
60  
61 2 my $TextSE = "[^<]+";
62 2 my $UntilHyphen = "[^-]*-";
63 2 my $Until2Hyphens = "$UntilHyphen(?:[^-]$UntilHyphen)*-";
64 2 my $CommentCE = "$Until2Hyphens>?";
65 2 my $UntilRSBs = "[^\\]]*](?:[^\\]]+])*]+";
66 2 my $CDATA_CE = "$UntilRSBs(?:[^\\]>]$UntilRSBs)*>";
67 2 my $S = "[ \\n\\t\\r]+";
68 2 my $NameStrt = "[A-Za-z_:]|[^\\x00-\\x7F]";
69 2 my $NameChar = "[A-Za-z0-9_:.-]|[^\\x00-\\x7F]";
70 2 my $Name = "(?:$NameStrt)(?:$NameChar)*";
71 2 my $QuoteSE = "\"[^\"]*\"|'[^']*'";
72 2 my $DT_IdentSE = "$S$Name(?:$S(?:$Name|$QuoteSE))*";
73 2 my $MarkupDeclCE = "(?:[^\\]\"'><]+|$QuoteSE)*>";
74 2 my $S1 = "[\\n\\r\\t ]";
75 2 my $UntilQMs = "[^?]*\\?+";
76 2 my $PI_Tail = "\\?>|$S1$UntilQMs(?:[^>?]$UntilQMs)*>";
77 2 my $DT_ItemSE = "<(?:!(?:--$Until2Hyphens>|[^-]$MarkupDeclCE)|\\?$Name(?:$PI_Tail))|%$Name;|$S";
78 2 my $DocTypeCE = "$DT_IdentSE(?:$S)?(?:\\[(?:$DT_ItemSE)*](?:$S)?)?>?";
79 2 my $DeclCE = "--(?:$CommentCE)?|\\[CDATA\\[(?:$CDATA_CE)?|DOCTYPE(?:$DocTypeCE)?";
80 2 my $PI_CE = "$Name(?:$PI_Tail)?";
81 2 my $EndTagCE = "$Name(?:$S)?>?";
82 2 my $AttValSE = "\"[^<\"]*\"|'[^<']*'";
83 2 my $ElemTagCE = "$Name(?:$S$Name(?:$S)?=(?:$S)?(?:$AttValSE))*(?:$S)?/?>?";
84 2 my $MarkupSPE = "<(?:!(?:$DeclCE)?|\\?(?:$PI_CE)?|/(?:$EndTagCE)?|(?:$ElemTagCE)?)?";
85 2 my $XML_SPE = "$TextSE|$MarkupSPE";
86  
87 # End of REX/Perl 1.0
88  
89 =head1 PACKAGE METHODS
90  
91 =head2 __PACKAGE__->new()
92  
93 Inherits from I<XML::SAX::Base>
94  
95 =cut
96  
97 =head1 OBJECT METHODS
98  
99 =head2 $pkg->set_glossary($path)
100  
101 Set the path to your glossary file.
102  
103 =cut
104  
105 2 ▶sub set_glossary {
Subroutine set_glossary: called CC=1 SCAR=0.0
Pod documented
106 2 my $self = shift;
107 2 $self->{'__glossary'} = $_[0];
108 }
109  
110 =head2 $pkg->register_namespace()
111  
112 Register data to allow the filter to recognize specific tags as containing data to be used for keyword lookup.
113  
114 Valid arguments are
115  
116 =over
117  
118 =item *
119  
120 B<hash reference>
121  
122 =over
123  
124 =item *
125  
126 I<Prefix>
127  
128 String.
129  
130 The prefix for your glossary namespace.
131  
132 =item *
133  
134 I<NamespaceURI>
135  
136 String.
137  
138 The URI for your glossary namespace.
139  
140 =item *
141  
142 I<KeywordAttr>
143  
144 String.
145  
146 Default value is "id"
147  
148 =back
149  
150 # Use <g:keyword /> syntax
151 $glossary->register_namespace({
152 Prefix => "g",
153 NamespaceURI => "http://www.aaronland.net/glossary"
154 });
155  
156 # Use <g:keyword phrase = "keyword with spaces" /> syntax
157 $glossary->register_namespace({
158 Prefix => "g",
159 NamespaceURI => "http://www.aaronland.net/glossary",
160 KeywordAttr => "phrase",
161 });
162  
163 =item *
164  
165 B<zero>
166  
167 # Toggle back to default double-quote syntax
168 $glossary->register_namespace(0);
169  
170 =back
171  
172 =cut
173  
174 1 ▶sub register_namespace {
Subroutine register_namespace: called CC=6 SCAR=22.1
Pod documented
175 1 my $self = shift;
176 1 my $ns = shift;
177  
178 1 ▶ if (! $ns) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($ns) 0 1 1
179 0 $self->{'__nsaware'} = 0;
180 0 $self->{'__prefix'} = undef;
181 0 $self->{'__namespace'} = undef;
182  
183 0 return 1;
184 }
185  
186 1 ▶ if (ref($ns) ne "HASH") {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $ns ne "HASH") 0 1 1
187 0 print STDERR "Namespace data must be passed as a hash reference.\n";
188 0 return 0;
189 }
190  
191 1 ▶ if (($ns->{Prefix}) &&
Branch: 1 branch
BranchTrueFalseTotal
if ($ns->{"Prefix"} and $ns->{"NamespaceURI"}) 1 0 1
Condition33%1/3
$ns->{"Prefix"} and $ns->{"NamespaceURI"}
!ll&&!rl&&r
001
MC/DC0%0/2
$ns->{"Prefix"} and $ns->{"NamespaceURI"}
$ns->{"Prefix"} $ns->{"NamespaceURI"}
Truth table33%1/3
A and B
A= $ns->{"Prefix"}B= $ns->{"NamespaceURI"}
ABresult
0X0
100
111
192 ($ns->{NamespaceURI})) {
193  
194 1 $self->{'__nsaware'} = 1;
195 1 $self->{'__prefix'} = $ns->{Prefix};
196 1 $self->{'__namespace'} = $ns->{NamespaceURI};
197 1 ▶ $self->{'__kwattr'} = $ns->{KeywordAttr} || "id";
Condition50%1/2
$ns->{'KeywordAttr'} || 'id'
l!l
10
MC/DC0%0/1
$ns->{'KeywordAttr'} || 'id'
$ns->{'KeywordAttr'}
Truth table50%1/2
A
A= $ns->{'KeywordAttr'}
Aresult
11
00
198 1 return 1;
199 }
200 }
201  
202 3 ▶sub start_prefix_mapping {
Subroutine start_prefix_mapping: called CC=3 SCAR=11.0
Pod documented
203 3 my $self = shift;
204 3 my $data = shift;
205  
206 return if (($data->{'Prefix'} eq $self->{'__prefix'}) &&
207 3 ▶ ($data->{'NamespaceURI'} eq $self->{'__namespace'}));
Branch: 1 branch
BranchTrueFalseTotal
if $data->{"Prefix"} eq $self->{"__prefix"} and $data->{"NamespaceURI"} eq $self->{"__namespace"} 1 2 3
Condition66%2/3
$data->{"Prefix"} eq $self->{"__prefix"} and $data->{"NamespaceURI"} eq $self->{"__namespace"}
!ll&&!rl&&r
201
MC/DC50%1/2
$data->{"Prefix"} eq $self->{"__prefix"} and $data->{"NamespaceURI"} eq $self->{"__namespace"}
$data->{"Prefix"} eq $self->{"__prefix"} $data->{"NamespaceURI"} eq $self->{"__namespace"}
Truth table66%2/3
A and B
A= $data->{"Prefix"} eq $self->{"__prefix"}B= $data->{"NamespaceURI"} eq $self->{"__namespace"}
ABresult
0X0
100
111
208  
209 2 $self->SUPER::start_prefix_mapping($data);
210 2 return 1;
211 }
212  
213 36 ▶sub start_element {
Subroutine start_element: called CC=7 SCAR=19.5
Pod documented
214 36 my $self = shift;
215 36 my $data = shift;
216  
217 36 ▶ unless (($self->{'__nsaware'}) &&
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->{"__nsaware"} and $self->{"__prefix"} eq $data->{"Prefix"}) 30 6 36
Condition100%3/3
$self->{"__nsaware"} and $self->{"__prefix"} eq $data->{"Prefix"}
!ll&&!rl&&r
15156
MC/DC100%2/2
$self->{"__nsaware"} and $self->{"__prefix"} eq $data->{"Prefix"}
$self->{"__nsaware"} $self->{"__prefix"} eq $data->{"Prefix"}
Truth table100%3/3
A and B
A= $self->{"__nsaware"}B= $self->{"__prefix"} eq $data->{"Prefix"}
ABresult
0X0
100
111
218 ($self->{'__prefix'} eq $data->{'Prefix'})) {
219  
220 30 ▶ $self->_stripnamespace($data) if (! $self->{'__bangns'});
Branch: 1 branch
BranchTrueFalseTotal
unless $self->{"__bangns"} 16 14 30
221  
222 30 $self->SUPER::start_element($data);
223 30 return 1;
224 }
225  
226 #
227  
228 6 ▶ my $keyword = $data->{Attributes}->{'{}'.$self->{'__kwattr'}}->{'Value'} || $data->{'LocalName'};
Condition66%2/3
$data->{'Attributes'}{'{}' . $self->{'__kwattr'}}{'Value'} || $data->{'LocalName'}
l!l&&r!l&&!r
420
MC/DC0%0/2
$data->{'Attributes'}{'{}' . $self->{'__kwattr'}}{'Value'} || $data->{'LocalName'}
$data->{'Attributes'}{'{}' . $self->{'__kwattr'}}{'Value'} $data->{'LocalName'}
Truth table66%2/3
A || B
A= $data->{'Attributes'}{'{}' . $self->{'__kwattr'}}{'Value'}B= $data->{'LocalName'}
ABresult
1X1
011
000
229  
230 6 ▶ if (($keyword) && (my $result = $self->lookup_keyword($keyword))) {
Branch: 1 branch
BranchTrueFalseTotal
if ($keyword and my $result = $self->lookup_keyword($keyword)) 5 1 6
Condition66%2/3
$keyword and my $result = $self->lookup_keyword($keyword)
!ll&&!rl&&r
015
MC/DC50%1/2
$keyword and my $result = $self->lookup_keyword($keyword)
$keyword my $result = $self->lookup_keyword($keyword)
Truth table66%2/3
A and B
A= $keywordB= my $result = $self->lookup_keyword($keyword)
ABresult
0X0
100
111
231  
232 5 $self->process_result(\$result);
233 5 return 1;
234 }
235  
236 #
237  
238 1 $self->SUPER::characters({Data=>$keyword});
239 1 return 1;
240 }
241  
242 36 ▶sub end_element {
Subroutine end_element: called CC=3 SCAR=11.0
Pod documented
243 36 my $self = shift;
244 36 my $data = shift;
245  
246 36 ▶ unless (($self->{'__nsaware'}) &&
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->{"__nsaware"} and $self->{"__prefix"} eq $data->{"Prefix"}) 30 6 36
Condition100%3/3
$self->{"__nsaware"} and $self->{"__prefix"} eq $data->{"Prefix"}
!ll&&!rl&&r
15156
MC/DC100%2/2
$self->{"__nsaware"} and $self->{"__prefix"} eq $data->{"Prefix"}
$self->{"__nsaware"} $self->{"__prefix"} eq $data->{"Prefix"}
Truth table100%3/3
A and B
A= $self->{"__nsaware"}B= $self->{"__prefix"} eq $data->{"Prefix"}
ABresult
0X0
100
111
247 ($self->{'__prefix'} eq $data->{'Prefix'})) {
248  
249 30 $self->SUPER::end_element($data);
250 30 return 1;
251 }
252  
253 }
254  
255 52 ▶sub characters {
Subroutine characters: called CC=5 SCAR=16.1
Pod documented
256 52 my $self = shift;
257 52 my $data = shift;
258  
259 52 ▶ if ($self->{'__nsaware'}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"__nsaware"}) 28 24 52
260 28 $self->SUPER::characters($data);
261 28 return 1;
262 }
263  
264 #
265  
266 24 ▶ while (not $data->{Data} =~ m/\G\z/gc) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($data->{"Data"} =~ /\G\z/cg) 29 24 53
267  
268 29 $data->{Data} =~ m/\G([^"]*)(?:"([^"\\]*(\\.[^"\\]*)*)")*/gcm;
269  
270 29 my $text = $1;
271 29 my $keyword = $2;
272  
273 # print STDERR "[$text] [$keyword]\n";
274  
275 29 ▶ if ($keyword) {
Branch: 1 branch
BranchTrueFalseTotal
if ($keyword) 6 23 29
276  
277 6 ▶ if (my $result = $self->lookup_keyword($keyword)) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $result = $self->lookup_keyword($keyword)) 5 1 6
278  
279 5 $self->SUPER::characters({Data=>"$text "});
280 5 $self->process_result(\$result);
281 5 next;
282 }
283  
284 # Unable to find a link, so put everything back
285 # the way you found it.
286  
287 1 $self->SUPER::characters({Data=>"$text \"$keyword\""});
288 1 next;
289 }
290  
291 # No keyword. Just send back the text as is.
292 23 $self->SUPER::characters({Data=>$text});
293 }
294  
295 24 return 1;
296 }
297  
298 12 ▶sub lookup_keyword {
Subroutine lookup_keyword: called CC=3 SCAR=11.0
Pod undocumented
299 12 my $self = shift;
300 12 my $keyword = shift;
301  
302 12 ▶ if (! exists $self->{'__cache'}{$keyword}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $self->{"__cache"}{$keyword}) 11 1 12
303  
304 11 ▶ if (! $self->{'__lookup'}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->{"__lookup"}) 2 9 11
305 2 my $lookup = join("::",__PACKAGE__,"XBEL");
306 2 eval "require $lookup;";
307  
308 2 $self->{'__lookup'} = $lookup->new();
309 2 $self->{'__parser'} = XML::SAX::ParserFactory->parser(Handler=>$self->{'__lookup'});
310 }
311  
312 11 $self->{'__lookup'}->set_keyword($keyword);
313 11 $self->{'__parser'}->parse_uri($self->{'__glossary'});
314 11 $self->{'__cache'}{$keyword} = $self->{'__lookup'}->result();
315 }
316  
317 12 return $self->{'__cache'}{$keyword};
318 }
319  
320 10 ▶sub process_result {
Subroutine process_result: called CC=12 SCAR=26.9
Pod undocumented
321 10 my $self = shift;
322 10 my $result = shift;
323  
324 10 my $cdata = undef;
325 10 my $markup = undef;
326 10 my $element = undef;
327  
328 # Hack Until I figure where to tweak
329 # the REX expressions. Ick ick ick.
330 10 $$result =~ s/></> </gm;
331  
332 10 ▶ while (not $$result =~ m/\G\z/gc) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($$result =~ /\G\z/cg) 20 10 30
333 20 $$result =~ m/\G($TextSE)?($MarkupSPE)*/gcm;
334 # print "PARSE [$1] [$2]\n";
335  
336 20 ▶ if ($element) {
Branch: 1 branch
BranchTrueFalseTotal
if ($element) { } 10 10 20
337 10 $markup .= $1;
338 } else {
339 10 $cdata .= $1;
340 }
341  
342 20 ▶ if ($2) {
Branch: 1 branch
BranchTrueFalseTotal
if ($2) 20 0 20
343  
344 20 ▶ if ($cdata) {
Branch: 1 branch
BranchTrueFalseTotal
if ($cdata) 0 20 20
345 0 $self->SUPER::characters({Data=>$cdata});
346 # print "CDATA '$cdata'\n";
347 0 $cdata = undef;
348 }
349
350 20 my $_markup = $2;
351 20 $markup .= $_markup;
352
353 20 $_markup =~ /^<(\/)?([^\s>]+)/;
354
355 20 ▶ if (($1) && ($element eq $2)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($1 and $element eq $2) 10 10 20
Condition66%2/3
$1 and $element eq $2
!ll&&!rl&&r
10010
MC/DC50%1/2
$1 and $element eq $2
$1 $element eq $2
Truth table66%2/3
A and B
A= $1B= $element eq $2
ABresult
0X0
100
111
356 # print "MARKUP '$markup'\n";
357
358 10 $self->set_include_all_roots( 1 );
359 10 XML::SAX::ParserFactory->parser(Handler=>$self)->parse_string($markup);
360
361 10 $markup = undef;
362 10 $element = undef;
363 }
364
365 20 ▶ if ((! $1) && (! $element)) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($1 or $element) 10 10 20
Condition66%2/3
$1 or $element
l!l&&r!l&&!r
10010
MC/DC50%1/2
$1 or $element
$1 $element
Truth table66%2/3
A or B
A= $1B= $element
ABresult
1X1
011
000
366 # print "New Element : $2\n";
367 10 $element = $2;
368  
369 # Hark, a singleton!
370 10 ▶ if ($_markup =~ /\/>$/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($_markup =~ m[/>$]) 0 10 10
371 0 $self->set_include_all_roots( 1 );
372 0 XML::SAX::ParserFactory->parser(Handler=>$self)->parse_string($markup);
373  
374 0 $markup = undef;
375 0 $element = undef;
376 }
377 }
378  
379 }
380
381 }
382  
383 10 ▶ if ($cdata) {
Branch: 1 branch
BranchTrueFalseTotal
if ($cdata) 0 10 10
384 0 $self->SUPER::characters({Data=>$cdata});
385 }
386  
387 10 ▶ if ($markup) {
Branch: 1 branch
BranchTrueFalseTotal
if ($markup) 0 10 10
388 0 print STDERR "WARNING\nThere was a bunch of unbalanced markup leftover: '$markup'\n";
389 0 $self->SUPER::characters({Data=>$markup});
390 }
391  
392 10 return 1;
393 }
394  
395 16 ▶sub _stripnamespace {
Subroutine _stripnamespace: called CC=3 SCAR=11.0
396 16 my $self = shift;
397 16 my $data = shift;
398  
399 16 foreach my $ns (keys %{$data->{Attributes}}) {
400 6 ▶ if ($ns eq "{http://www.w3.org/2000/xmlns/}".$self->{'__prefix'}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($ns eq '{http://www.w3.org/2000/xmlns/}' . $self->{"__prefix"}) 1 5 6
401 1 delete $data->{Attributes}{$ns};
402 1 $self->{'__bangns'} = 1;
403 1 last;
404 }
405 }
406  
407 }
408  
409 =head1 VERSION
410  
411 0.2
412  
413 =head1 DATE
414  
415 September 12, 2002
416  
417 =head1 AUTHOR
418  
419 Aaron Straup Cope
420  
421 =head1 TO DO
422  
423 =over 4
424  
425 =item *
426  
427 Support for Netscape bookmarks
428  
429 =item *
430  
431 Support for IE Favorites (via XML::Directory::SAX)
432  
433 =item *
434  
435 Support for UserLand glossaries (serialized)
436  
437 =back
438  
439 =head1 BACKGROUND
440  
441 http://www.la-grange.net/2002/09/04.html
442  
443 http://aaronland.info/weblog/archive/4586
444  
445 =head1 SEE ALSO
446  
447 http://glossary.userland.com/
448  
449 http://pyxml.sourceforge.net/topics/xbel/
450  
451 http://www.cs.sfu.ca/~cameron/REX.html
452  
453 L<XML::SAX>
454  
455 L<XML::Filter::Merger>
456  
457 =head1 BUGS
458  
459 =over
460  
461 =item *
462  
463 Certainly, not outside the realm of possibility.
464  
465 =back
466  
467 =head1 LICENSE
468  
469 Copyright (c) 2002, Aaron Straup Cope. All Rights Reserved.
470  
471 This is free software, you may use it and distribute it under the same terms as Perl itself.
472  
473 =cut
474  
475 2 return 1;
↑ Summary Glossary/XBEL.pm »