1NAME
2 Template::Extract - Use TT2 syntax to extract data from documents
3
4VERSION
5 This document describes version 0.41 of Template::Extract, released
6 October 16, 2007.
7
8SYNOPSIS
9 use Template::Extract;
10 use Data::Dumper;
11
12 my $obj = Template::Extract->new;
13 my $template = << '.';
14 <ul>[% FOREACH record %]
15 <li><A HREF="[% url %]">[% title %]</A>: [% rate %] - [% comment %].
16 [% ... %]
17 [% END %]</ul>
18 .
19
20 my $document = << '.';
21 <html><head><title>Great links</title></head><body>
22 <ul><li><A HREF="http://slashdot.org">News for nerds.</A>: A+ - nice.
23 this text is ignored.</li>
24 <li><A HREF="http://microsoft.com">Where do you want...</A>: Z! - yeah.
25 this text is ignored, too.</li></ul>
26 .
27
28 print Data::Dumper::Dumper(
29 $obj->extract($template, $document)
30 );
31
32DESCRIPTION
33 This module adds template extraction functionality to the Template
34 toolkit. It can take a rendered document and its template together, and
35 get the original data structure back, effectively reversing the
36 "Template::process" function.
37
38METHODS
39 new(\%options)
40 Constructor. Currently all options are passed into the underlying
41 "Template::Parser" object. The same set of options are also passed to
42 classes responsible to compile and run the extraction process, but they
43 are currently ignored.
44
45 extract($template, $document, \%values)
46 This method takes three arguments: the template string, or a reference
47 to it; a document string to match against; and an optional hash
48 reference to supply initial values, as well as storing the extracted
49 values into.
50
51 The return value is "\%values" upon success, and "undef" on failure. If
52 "\%values" is omitted from the argument list, a new hash reference will
53 be constructed and returned.
54
55 Extraction is done by transforming the result from Template::Parser to a
56 highly esoteric regular expression, which utilizes the "(?{...})"
57 construct to insert matched parameters into the hash reference.
58
59 The special "[% ... %]" directive is taken as the "/.*?/s" regex, i.e.
60 *ignore everything (as short as possible) between this identifier and
61 the next one*. For backward compatibility, "[% _ %]" and "[% __ %]" are
62 also accepted.
63
64 The special "[% // %]" directive is taken as a non-capturing regex,
65 embedded inside "/(?:)/s"; for example, "[% /\d*/ %]" matches any number
66 of digits. Capturing parentheses may not be used with this directive,
67 but you can use the "[% var =~ // %]" directive to capture the match
68 into "var".
69
70 You may set $Template::Extract::DEBUG to a true value to display
71 generated regular expressions.
72
73 The extraction process defaults to succeed even with a partial match. To
74 match the entire document only, set $Template::Extract::EXACT to a true
75 value.
76
77 compile($template)
78 Use Template::Extract::Compile to perform the first phase of "extract",
79 by returning the regular expression compiled from $template.
80
81 run($regex, $document, \%values)
82 Use Template::Extract::Run to perform the second phase of "extract", by
83 applying the regular expression on $document and returning the resulting
84 "\%values".
85
86SUBCLASSING
87 If you would like to use different modules to parse, compile and run the
88 extraction process, simply subclass "Template::Extract" and override the
89 "COMPILE_CLASS", "PARSER_CLASS" and "RUN_CLASS" methods to return
90 alternate class names.
91
92CAVEATS
93 Currently, the "extract" method only supports "[% GET %]", "[% SET %]"
94 and "[% FOREACH %]" directives, because "[% WHILE %]", "[% CALL %]" and
95 "[% SWITCH %]" blocks are next to impossible to extract correctly.
96
97 "[% SET key = "value" %]" only works for simple scalar values.
98
99 Outermost "[% FOREACH %]" blocks must match at least once in the
100 document, but inner ones may occur zero times. This is to prevent the
101 regex optimizer from failing prematurely.
102
103 There is no support for different *PRE_CHOMP* and *POST_CHOMP* settings
104 internally, so extraction could fail silently on extra linebreaks.
105
106 It is somewhat awkward to use global variables to control "EXACT" and
107 "DEBUG" behaviour; patches welcome to promote them into per-instance
108 options.
109
110NOTES
111 This module's companion class, Template::Generate, is still in early
112 experimental stages; it can take data structures and rendered documents,
113 then automagically generates templates to do the transformation. If you
114 are into related research, please mail any ideas to me.
115
116SEE ALSO
117 Template::Extract::Compile, Template::Extract::Run,
118 Template::Extract::Parser
119
120 Template, Template::Generate
121
122 Simon Cozens's introduction to this module, in O'Reilly's *Spidering
123 Hacks*:
124 <http://www.oreillynet.com/pub/a/javascript/excerpt/spiderhacks_chap01/i
125 ndex.html>
126
127 Mark Fowler's introduction to this module, in The 2003 Perl Advent
128 Calendar: <http://perladvent.org/2003/5th/>
129
130AUTHORS
131 Audrey Tang <cpan@audreyt.org>
132
133COPYRIGHT
134 Copyright 2001, 2002, 2003, 2004, 2005, 2007 by Audrey Tang
135 <cpan@audreyt.org>.
136
137 This software is released under the MIT license cited below.
138
139 The "MIT" License
140 Permission is hereby granted, free of charge, to any person obtaining a
141 copy of this software and associated documentation files (the
142 "Software"), to deal in the Software without restriction, including
143 without limitation the rights to use, copy, modify, merge, publish,
144 distribute, sublicense, and/or sell copies of the Software, and to
145 permit persons to whom the Software is furnished to do so, subject to
146 the following conditions:
147
148 The above copyright notice and this permission notice shall be included
149 in all copies or substantial portions of the Software.
150
151 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
152 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
153 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
154 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
155 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
156 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
157 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
158
159