Add a bunch of Rael plugins.
[matthijs/upstream/blosxom-plugins.git] / general / interpolate_fancy
1 # Blosxom Plugin: interpolate_fancy
2 # Author(s): Rael Dornfest <rael@oreilly.com> 
3 # Version: 2003-09-09:12:10
4 # Documentation: See the bottom of this file or type: 
5 # perldoc interpolate_fancy
6
7 package interpolate_fancy;
8
9 # --- Configurable variables -----
10
11 # Do you want me to recursively interpolate into the story $title
12 # and $body?  Consider and reconsider carefully before turning this
13 # on as if anyone other than you has the ability to post stories,
14 # there's a chance of some tomfoolery, exposing variables and calling
15 # actions/subroutines you might not want called.
16 # 0 = No (default),  1 = Yes
17 my $recurse_into_story = 0;
18
19 # --------------------------------
20
21 sub start {
22   1;
23 }
24
25 sub interpolate {
26   return sub {
27
28     package blosxom;
29
30     # Halt recursive interpolation of story $body
31     # by mangling interpolation tags (to be unmangled in a moment)
32     unless ($recurse_into_story) {
33       $blosxom::title =~ s/<(\@|\??\$)/<#INTERPOLATE_FANCY_DEFANG#$1/gsi;
34       $blosxom::body =~ s/<(\@|\??\$)/<#INTERPOLATE_FANCY_DEFANG#$1/gsi;
35     }
36
37     my $template = shift;
38
39     # Backward Compatibility with core Blosxom style interpolation
40     $template =~ s#(?<!<)(?<!<\?)(?<!<\?!)(\$\w+(?:::)?\w*)#<$1 />#gs; 
41
42     # Defined
43     # e.g. <?$var>display if defined</?>
44     $template =~ s#<\?(\$\w+(?:::)?\w*)>(.*?)<\/\?>#"defined $1 ? \$2 : undef"#gsee;
45
46     # Undefined 
47     # e.g. <?!$var>display if not defined</?>
48     $template =~ s#<\?!(\$\w+(?:::)?\w*)>(.*?)<\/\?>#"!defined $1 ? \$2 : undef"#gsee;
49
50     # Tests 
51     # eq (eq), ne (ne), lt (<), gt (>), like (=~), unlike (!~)
52     # e.g. <?$var lt="123">display if $var less than 123</?>
53     $template =~ s#<\?(\$\w+(?:::)?\w*)\s+?(.+?)>(.*?)<\/\?>#"interpolate_fancy::_test(qq{$1}, q{$2}, q{$3})"#gsee;
54
55     # Unconditional, Recursive 
56     # e.g. <$var />
57     while( $template =~ s/<\$([a-zA-Z?]\w+(?:::)?\w*)\s+?\/>/"defined \$$1 ? \$$1 : undef"/gsee ) { }
58
59     # Actions 
60     # e.g. <@plugin.subroutine arg1="a" output="no" />
61     # e.g. <@plugin.subroutine encoding="Latin1" output="yes">pass content</@> 
62     $template =~ s#<\@(\w+?)\.(\w+?)\s+?(.+?)?(?:>(.*?)<\/\@\1\.\2>|\s+?\/>)#&interpolate_fancy::_action($1,$2,$3,$4)#gse;
63
64     # Unmangle mangled interpolation tags in story $title and $body
65     # (by now in the template itself)
66     unless ($recurse_into_story) {
67       $template =~ s/<#INTERPOLATE_FANCY_DEFANG#(\@|\??\$)/<$1/gsi;
68     }
69
70     return $template;
71
72   };  
73 }
74
75 sub _test {
76   my($variable, $attr, $content) = @_;
77
78   my $result;
79
80   my $attributes = interpolate_fancy::_attributes($attr);
81
82   defined $attributes->{eq} and return $variable eq $attributes->{eq} ? $content : undef;
83   defined $attributes->{ne} and return $variable ne $attributes->{ne} ? $content : undef;
84   defined $attributes->{gt} and return $variable > $attributes->{gt} ? $content : undef;
85   defined $attributes->{lt} and return $variable < $attributes->{lt} ? $content : undef;
86   defined $attributes->{like} and return $variable  =~ /$attributes->{like}/ ? $content : undef;
87   defined $attributes->{unlike} and return $variable  !~ /$attributes->{unlike}/ ? $content : undef;
88
89   return undef;
90 }
91
92 sub _action {
93   my($plugin, $action, $attr, $content) = @_;
94
95   $content =~ s#<\@(\w+?)\.(\w+?)\s+?(.+?)?(?:>(.*?)<\/\@\1\.\2>|\s+?\/>)#&interpolate_fancy::_action($1,$2,$3,$4)#gse;
96
97   my $attributes = interpolate_fancy::_attributes($attr);
98   
99   $blosxom::plugins{$plugin} 
100     and $plugin->can($action) 
101       and $result = $plugin->$action($attributes, $content);
102
103   return $attributes->{'output'} =~ /yes/i ? $result : undef;
104 }
105
106 sub _attributes {
107   my $attr = shift;
108
109   my $attributes = {};
110   while ( $attr =~ /\b(\w+?)\s*?=\s*?(["'])(.*?)\2/g ) {
111     $attributes->{$1} = $3;
112   }
113
114   return $attributes;
115 }
116
117 1;
118
119 __END__
120
121 =head1 NAME
122
123 Blosxom Plug-in: interpolate_fancy
124
125 =head1 SYNOPSIS
126
127 Overrides Blosxom's far simpler to use, but more limited, default interpolate() 
128 subroutine.
129
130 Include bits of text and template variable values in templates, either 
131 conditionally or unconditionally:
132
133 Perform actions (i.e. call plug-in subroutines) at any point in your page, 
134 whether to act on current content and return results or no.
135
136 =head2 Includes
137
138   * Unconditionally and recursively
139
140     e.g. include a link to the story's path using various template variables.
141
142     <a href="<$url /><$path />"><$path /></a>
143
144     Limited by the $recurse_into_story configuration directive (see
145     the CONFIGURATION below).
146
147   * Unconditionally and recursively (backward compatibility with Blosxom's standard interpolation)
148
149     e.g. include a link to the story's path using various template variables.
150
151     <a href="$url$path">$path</a>
152
153     Limited by the $recurse_into_story configuration directive (see
154     the CONFIGURATION below).
155
156   * The template variable has a value (i.e. is defined)
157
158     e.g. include a hyperlink to the story's path if it has a path (i.e.
159     $path is defined).
160
161     <?$path><a href="<$url /><$path />"><$path /></a></?>
162
163   * The template variable doesn't have a value (i.e. is NOT defined)
164
165     e.g. include a hyperlink to home if path is undefined.
166
167     <?!$path><a href="<$url />">home</a></?>
168
169   * The template variable is equal (=) to a particular value
170
171     e.g. include "1 writeback" (singular) if the value of writeback count is 1
172
173     <$writeback::count /> <?$writeback::count eq="1">writeback</?>
174
175   * The template variable is not equal (!=) to a particular value
176
177     e.g. include "x writebacks" (plural) if the value of writeback 
178          count (x) is not 1
179
180     <$writeback::count /> <?$writeback::count ne="1">writebacks</?>
181
182   * The template variable is less than (<) a particular value
183
184     e.g. include "no writebacks" if the value of writeback count is < 1
185
186     <?$writeback::count lt="1">no writebacks</?>
187
188   * The template variable is greater than (>) a particular value
189
190     e.g. include "oodles of writebacks" if the value of writeback count is > 50
191
192     <?$writeback::count gt="50">oodles of writebacks</?>
193
194   * The template variable is like (=~) a particular regular expression
195
196     e.g. Greet a visitor properly, depending on their courtesy title
197
198     Howdy, 
199     <?$user::courtesy like="^(Mr\.?|Sir)$">Sir</?>
200     <?$user::courtesy like="^(Mr?s\.?|Miss)$">M'am</?>
201
202   * The template variable is unlike (!~) a particular regular expression
203
204     e.g. The posting is neither a film nor a book
205
206     <?$path unlike="/(Film|Literature)">no review</?>
207
208 =head2 Actions
209
210 Perform an action (i.e. call a plug-in's subroutine) at any point in your page.
211 Optionally pass arguments as key/value pairs stated as XML-style attributes.
212 For example: 
213
214   <@plugin.subroutine arg1="a" arg2="bee" />
215
216 calls &plugin::subroutine( {'arg1'=>'a', 'arg2'=>'bee' } ).
217
218 Specify that results should be sent to the browser using the output="yes" 
219 attribute like so:
220   
221   <@plugin.subroutine arg1="a" arg2="bee" output="yes" />
222
223 Otherwise, subroutines will still have their effect, but the results will 
224 be tossed out.
225
226 Content wrapped in the action call is sent as another argument to the 
227 subroutine:
228
229   <@plugin.subroutine encoding="Latin1" output="yes">
230   pass this content
231   </@plugin.subroutine> 
232
233 This calls &plugin::subroutine( {'encoding'=>'Latin1', 'output'=>'yes' }, "pass this content" ).
234
235 Actions are recursive, meaning that you can embed an action inside another, 
236 and so on and so on and so on.  Actions are unfolded from the inside out,
237 with the most deeply embedded first, second deepest second, and so forth until
238 the outermost action is performed last.
239
240 Recursion is limited by the $recurse_into_story configuration directive (see
241 the CONFIGURATION below).
242
243 =head3 An Example
244
245 For those of you interested in writing plugin actions or using some of the
246 more advanced features in your Blosxom blog templates, here are a couple of
247 sample actions:
248
249 --
250
251 # For the sake of this example, assume these actions live in a "myplugin"
252 # plugin
253
254 # This action strips HTML from its content
255 sub strip_html {
256   my($self, $attributes, $content) = @_;
257   $content =~ s!</?.+?>!!g;
258   return $content;
259 }
260
261 # This action foreshortens its content to a length specified in the call to
262 # action's length attribute
263 sub foreshorten {
264   my($self, $attributes, $content) = @_;
265   my $default_length = 144;
266   return substr($content, 0, $attributes{'length'}||$default_length);
267 }
268
269 --
270
271 Calling these individually in a Blosxom flavour template looks something like:
272
273 The following bit of text is devoid of HTML:
274 <@myplugin.strip_html output="Yes">
275 Silly <a href="http://www.raelity.org/">me</a>, I plumb 
276 <em>forgot</em> to remove the HTML.
277 </@myplugin.strip_html>
278
279 The following bit of text is only 20 characters in length:
280 <@myplugin.foreshorten output="Yes">
281 This text is far longer than 20 characters on the page, 
282 but will only appear as "This text is far lon" in the
283 resulting page.
284 </@myplugin.foreshorten>
285
286 And in combination, stripping the HTML _before_ foreshortening (notice
287 the strip_html action is embedded inside the foreshorten action and
288 thus is run first):
289
290 The following bit of text is only 20 characters in length and devoid of HTML:
291 <@myplugin.foreshorten output="Yes">
292 <@myplugin.strip_html output="Yes">
293 Silly <a href="http://www.raelity.org/">me</a>, I plumb 
294 <em>forgot</em> to remove the HTML.
295 This text is far longer than 20 characters on the page, 
296 but will only appear as "This text is far lon" in the
297 resulting page.
298 </@myplugin.strip_html>
299 </@myplugin.foreshorten>
300
301 =head1 INSTALLATION
302
303 Drop the interpolate_fancy plug-in into your Blosxom plugins folder.
304
305 =head1 CONFIGURATION
306
307 None necessary; interpolate_fancy will run out of the box with no need
308 of additional configuration or fiddling on your part (caveat: see 
309 BACKWARD COMPATILITY below).
310
311 The interpolate_fancy plugin does sport one configuration directive
312 which you should very much consider leaving alone.  
313
314 # 0 = No (default),  1 = Yes
315 my $recurse_into_story = 0;
316
317 $recurse_into_story decides whether or not the interpolation engine 
318 should respect and interpolate (swap for the associated value) 
319 variables and actions embedded in story $title and $body themselves.
320
321 Off by default, you should consider and reconsider carefully before 
322 turning this on as if anyone other than you has the ability to post 
323 stories to your blog, there's a chance of some tomfoolery, exposing 
324 variables and calling actions/subroutines you might not want called.
325
326 =head1 BACKWARD COMPATIBILITY
327
328 If you've been using core Blosxom's interpolation style 
329 (e.g. $title), this plugin will provide backward compatibility,
330 requiring no template rewriting on your part.
331
332 If you've been using the interpolate_conditional plugin,
333 the conditional bits won't be respected by default.  You should
334 run your templates through the interpolate2fancy utility
335 [http://blosxom.sourceforge.net/downloads/utilities/interpolate2fancy.py].
336
337 =head1 VERSION
338
339 2003-09-09:12:10
340
341 =head1 AUTHOR
342
343 Rael Dornfest  <rael@oreilly.com>, http://www.raelity.org/
344
345 =head1 SEE ALSO
346
347 Blosxom Home/Docs/Licensing: http://www.raelity.org/apps/blosxom/
348
349 Blosxom Plugin Docs: http://www.raelity.org/apps/blosxom/plugin.shtml
350
351 =head1 BUGS
352
353 Address bug reports and comments to the Blosxom mailing list 
354 [http://www.yahoogroups.com/group/blosxom].
355
356 =head1 LICENSE
357
358 Blosxom and this Blosxom Plug-in
359 Copyright 2003, Rael Dornfest 
360
361 Permission is hereby granted, free of charge, to any person obtaining a
362 copy of this software and associated documentation files (the "Software"),
363 to deal in the Software without restriction, including without limitation
364 the rights to use, copy, modify, merge, publish, distribute, sublicense,
365 and/or sell copies of the Software, and to permit persons to whom the
366 Software is furnished to do so, subject to the following conditions:
367
368 The above copyright notice and this permission notice shall be included
369 in all copies or substantial portions of the Software.
370
371 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
372 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
373 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
374 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
375 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
376 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
377 OTHER DEALINGS IN THE SOFTWARE.