general/interpolate_fancy

   1 # Blosxom Plugin: interpolate_fancy
   2 # Author: Rael Dornfest <rael@oreilly.com>,
   3 # Modified by: Matthijs Kooijman <m.kooijman@student.utwente.nl>
   4 # and Barijaona Ramaholimihaso
   5 # Version: 2007-09-27
   6 # Documentation: See the bottom of this file or type:
   7 # perldoc interpolate_fancy
   8
   9 package interpolate_fancy;
  10
  11 use warnings;
  12 use strict;
  13
  14 # --- Configurable variables -----
  15
  16 # Do you want me to recursively interpolate into the story $title
  17 # and $body?  Consider and reconsider carefully before turning this
  18 # on as if anyone other than you has the ability to post stories,
  19 # there's a chance of some tomfoolery, exposing variables and calling
  20 # actions/subroutines you might not want called.
  21 # 0 = No (default),  1 = Yes
  22 our $recurse_into_story = 0;
  23
  24 # --------------------------------
  25
  26 my $parsing_story = 0 ;
  27
  28
  29 sub start {
  30   1;
  31 }
  32
  33
  34 # (Recursively) resolve conditinal includes <?...>...</?>.
  35 # Expects two arguments: The (part of the) template we are expanding and
  36 # wether or not this part will be displayed. When this last argument is false,
  37 # this part of the template will not be displayed, but is still parsed to
  38 # properly resolve nested conditions.
  39 #
  40 # This will resolve and substitute all conditionals on the "current level".
  41 # This effectively means, the routine will search for and resolve all tags it
  42 # finds (with proper nesting), until it finds a closing tag (</?>) for which
  43 # it has not seen the opening tag, or there are no more opening tags in the
  44 # file.
  45 #
  46 # This function will return the template with all conditionals on the current
  47 # level resolved. This will guarantee that if there are any opening or closing
  48 # tags left in the template, the first one will be a closing tag (which can
  49 # then be resolved in the upper level).
  50 sub _resolve_nested {
  51     my $template = shift;
  52     my $display  = shift;
  53
  54     while (1) {
  55         if ($template !~ /(.*?)<\?(\!?\$\w+(?:::\w+)*)(?:\s+?(.+?))?>(.*)/s) {
  56             return $template; # No open tags, normal text
  57         }
  58
  59         my $head = $1;
  60         my $var  = $2;
  61         my $attr = $3;
  62         my $tail = $4;
  63
  64         if ($head =~ /<\/\?>/s) {
  65             return $template; # There is a closing tag before the first open tag,
  66                              # we're done.
  67         }
  68
  69         my $displayitem = $display;
  70         if ($displayitem) { # Don't care about these tests if we're not displayed anyway.
  71             my $negated = ($var =~ s/^\!//); # Remove negation mark
  72             if ($negated || !$attr) {
  73                 if ($attr) {
  74                     warn("<?!$var $attr>: Negated expression can't have attributes, ignoring them.");
  75                 }
  76                 $displayitem = eval("defined $var");
  77                 if ($negated) { $displayitem = !$displayitem; }
  78             } else {
  79                 $displayitem = _test(eval($var), $attr);
  80             }
  81         }
  82
  83
  84         $tail = _resolve_nested($tail, $displayitem);
  85
  86         if ($tail !~ /<\/\?>/s) { # Is there no closing tag?
  87             warn("Invalid nesting: <?$var $attr> missing closing tag.");
  88         }
  89         if ($displayitem)
  90         {
  91             $tail =~ s/<\/\?>//s; # Remove the closing tag
  92         } else {
  93             $tail =~ s/.*?<\/\?>//s; # Remove up to the closing tag
  94         }
  95         $template = $head . $tail;
  96     }
  97     return $template;
  98 }
  99
 100
 101 sub interpolate {
 102   return \&interpolate_fancy::do_interpolate;
 103 }
 104
 105 sub do_interpolate {
 106
 107     package blosxom;
 108
 109     # Halt recursive interpolation of story $body
 110     # by mangling interpolation tags (to be unmangled in a moment)
 111     unless ($recurse_into_story) {
 112       $blosxom::title =~ s/<(\@|\??\$)/<#INTERPOLATE_FANCY_DEFANG#$1/gsi if defined $blosxom::title;
 113       $blosxom::body =~ s/<(\@|\??\$)/<#INTERPOLATE_FANCY_DEFANG#$1/gsi if defined $blosxom::body;
 114     }
 115
 116     my $template = shift;
 117
 118     # Backward Compatibility with core Blosxom style interpolation
 119     unless ($parsing_story)
 120         {$template =~ s#(?<!<)(?<!<\?)(?<!<\?!)(\$\w+(?:::\w+)*)#<$1 />#gs; };
 121
 122     #
 123     # Conditional inclusion
 124     # Defined
 125     # e.g. <?$var>display if defined</?>
 126     # Undefined
 127     # e.g. <?!$var>display if not defined</?>
 128     # Tests
 129     # eq (eq), ne (ne), lt (<), gt (>), like (=~), unlike (!~)
 130     # e.g. <?$var lt="123">display if $var less than 123</?>
 131     $template = interpolate_fancy::_resolve_nested($template, 1);
 132
 133     #
 134     # Variable expansion (unconditional, recursive)
 135     #
 136     # e.g. <$var />
 137     while( $template =~ s/<\$([a-zA-Z?]\w+(?:::\w+)*)\s+?\/>/"defined \$$1 ? \$$1 : ''"/gsee ) { }
 138
 139     #
 140     # Actions
 141     #
 142     # e.g. <@plugin.subroutine arg1="a" output="no" />
 143     # e.g. <@plugin.subroutine encoding="Latin1" output="yes">pass content</@>
 144     $template =~ s#<\@((?:\w|::)+?)\.(\w+?)\s+?(.+?)?(?:>(.*?)<\/\@\1\.\2>|\s+?\/>)#&interpolate_fancy::_action($1,$2,$3,$4)#gse;
 145
 146     # Unmangle mangled interpolation tags in story $title and $body
 147     # (by now in the template itself)
 148     unless ($recurse_into_story) {
 149       $template =~ s/<#INTERPOLATE_FANCY_DEFANG#(\@|\??\$)/<$1/gsi;
 150     }
 151
 152     return $template;
 153
 154 }
 155
 156 sub _test {
 157   my($variable, $attr) = @_;
 158   # If the variable is not defined, treat it as the empty string in
 159   # comparisons below
 160   if (!defined $variable) {
 161     $variable = '';
 162   }
 163   my $attributes = interpolate_fancy::_attributes($attr);
 164
 165   defined $attributes->{eq} and return $variable eq $attributes->{eq};
 166   defined $attributes->{ne} and return $variable ne $attributes->{ne};
 167   defined $attributes->{gt} and return $variable > $attributes->{gt};
 168   defined $attributes->{lt} and return $variable < $attributes->{lt};
 169   defined $attributes->{like} and return $variable  =~ /$attributes->{like}/;
 170   defined $attributes->{unlike} and return $variable  !~ /$attributes->{unlike}/;
 171
 172   return 0;
 173 }
 174
 175 sub _action {
 176   my($plugin, $action, $attr, $content) = @_;
 177   my $result;
 178
 179   $content =~ s#<\@((?:\w|::)+?)\.(\w+?)\s+?(.+?)?(?:>(.*?)<\/\@\1\.\2>|\s+?\/>)#&interpolate_fancy::_action($1,$2,$3,$4)#gse;
 180
 181   my $attributes = interpolate_fancy::_attributes($attr);
 182
 183   $blosxom::plugins{$plugin} > 0
 184     and $plugin->can($action)
 185       and $result = $plugin->$action($attributes, $content);
 186
 187   # Optionally interpolate and/or output the result, if requested.
 188   if ($attributes->{'output'} =~ /yes/i) {
 189     if ($attributes->{'interpolate'} =~ /yes/i) {
 190       $result = interpolate_fancy::do_interpolate($result);
 191     }
 192     return $result;
 193   } else {
 194     return undef;
 195   }
 196 }
 197
 198 sub _attributes {
 199   my $attr = shift;
 200
 201   my $attributes = {};
 202   while ( $attr =~ /\b(\w+?)\s*?=\s*?(["'])(.*?)\2/g ) {
 203     $attributes->{$1} = $3;
 204   }
 205
 206   return $attributes;
 207 }
 208
 209 sub story {
 210         my($pkg, $path, $filename, $story_ref, $title_ref, $body_ref) = @_;
 211
 212  if ($recurse_into_story) {
 213       $parsing_story = 1;
 214       $$title_ref =&$blosxom::interpolate($$title_ref);
 215       $$body_ref =&$blosxom::interpolate($$body_ref);
 216       $parsing_story = 0;
 217      }
 218   return 1;
 219 }
 220
 221 1;
 222
 223 __END__
 224
 225 =head1 NAME
 226
 227 Blosxom Plug-in: interpolate_fancy
 228
 229 =head1 SYNOPSIS
 230
 231 Overrides Blosxom's far simpler to use, but more limited, default interpolate() subroutine.
 232
 233 * Include bits of text and template variable values in templates, either conditionally or unconditionally;
 234
 235 * Perform actions (i.e. call plug-in subroutines) at any point in your page, whether to act on current content and return results or not.
 236
 237 =head2 Inclusions of bits of text and variables
 238
 239 This syntax will expand to the value of the referenced variable and can be used to include dynamic content in your pages.
 240
 241 =over 2
 242
 243 =item Unconditionally and recursively
 244
 245 e.g. include a link to the story's path using various template variables.
 246
 247 <a href="<$url /><$path />"><$path /></a>
 248
 249 Limited by the $recurse_into_story configuration directive (see the CONFIGURATION below).
 250
 251 =item Unconditionally (backward compatibility with Blosxom's standard interpolation)
 252
 253 e.g. include a link to the story's path using various template variables (non-recursive, and only inside templates).
 254
 255 <a href="$url$path">$path</a>
 256
 257 =item If the template variable has a value (i.e. is defined)
 258
 259 e.g. include a hyperlink to the story's path if it has a path (i.e. $path is defined).
 260
 261 <?$path><a href="<$url /><$path />"><$path /></a></?>
 262
 263 =item If the template variable doesn't have a value (i.e. is NOT defined)
 264
 265 e.g. include a hyperlink to home if path is undefined.
 266
 267 <?!$path><a href="<$url />">home</a></?>
 268
 269 =item If the template variable is equal (=) to a particular value
 270
 271 e.g. include "1 writeback" (singular) if the value of writeback count is 1
 272
 273 <$writeback::count /> <?$writeback::count eq="1">writeback</?>
 274
 275 =item If the template variable is not equal (!=) to a particular value
 276
 277 e.g. include "x writebacks" (plural) if the value of Writeback count (x) is not 1
 278
 279 <$writeback::count /> <?$writeback::count ne="1">writebacks</?>
 280
 281 =item If the template variable is less than (<) a particular value
 282
 283 e.g. include "no writebacks" if the value of writeback count is < 1
 284
 285 <?$writeback::count lt="1">no writebacks</?>
 286
 287 =item If the template variable is greater than (>) a particular value
 288
 289 e.g. include "oodles of writebacks" if the value of writeback count is > 50
 290
 291 <?$writeback::count gt="50">oodles of writebacks</?>
 292
 293 =item If the template variable is like (=~) a particular regular expression
 294
 295 e.g. Greet a visitor properly, depending on their courtesy title
 296
 297 Howdy,
 298 <?$user::courtesy like="^(Mr\.?|Sir)$">Sir</?>
 299 <?$user::courtesy like="^(Mr?s\.?|Miss)$">M'am</?>
 300
 301 =item If the template variable is unlike (!~) a particular regular expression
 302
 303 e.g. The posting is neither a film nor a book
 304
 305 <?$path unlike="/(Film|Literature)">no review</?>
 306
 307 =back
 308
 309 =head2 Actions
 310
 311 Performs an action (i.e. calls a plug-in's subroutine) at any point in your page. Optionally passes arguments as key/value pairs stated as XML-style attributes.
 312
 313 For example:
 314
 315 <@thePlugin.subroutine arg1="a" arg2="bee" />
 316
 317 calls &Blosxom::Plugin::ThePlugin::subroutine( {'arg1'=>'a', 'arg2'=>'bee' } ).
 318
 319 Specify that results should be sent to the browser using the output="yes" attribute like so:
 320 <@thePlugin.subroutine arg1="a" arg2="bee" output="yes" />
 321
 322 Otherwise, subroutines will still have their effect, but the results will be tossed out.
 323
 324 Normally, the result from the subroutine is sent as-is, but you can set the interpolate="yes" attribute to let interpolate_fancy interpolate the results, as follows:
 325
 326   <@plugin.subroutine arg1="a" arg2="bee" output="yes" interpolate="yes"/>
 327
 328 Content wrapped in the action call is sent as another argument to the subroutine:
 329
 330   <@thePlugin.subroutine encoding="Latin1" output="yes">
 331   pass this content
 332   </@thePlugin.subroutine>
 333
 334 This calls &thePlugin::subroutine( {'encoding'=>'Latin1', 'output'=>'yes' }, "pass this content" ).
 335
 336 Actions are recursive, meaning that you can embed an action inside another, and so on and so on and so on.  Actions are unfolded from the inside out, with the most deeply embedded first, second deepest second, and so forth until the outermost action is performed last.
 337
 338 Recursion is limited by the $recurse_into_story configuration directive (see the CONFIGURATION below).
 339
 340 =head3 An Example
 341
 342 For those of you interested in writing plugin actions or using some of the
 343 more advanced features in your Blosxom blog templates, here are a couple of
 344 sample actions:
 345
 346 --
 347
 348 # For the sake of this example, assume these actions live in a "myplugin" plugin
 349
 350 # This action strips HTML from its content
 351
 352 sub strip_html {
 353   my($self, $attributes, $content) = @_;
 354   $content =~ s!</?.+?>!!g;
 355   return $content;
 356 }
 357
 358 # This action foreshortens its content to a length specified in the call to action's length attribute
 359
 360 sub foreshorten {
 361   my($self, $attributes, $content) = @_;
 362   my $default_length = 144;
 363   return substr($content, 0, $attributes->{'length'}||$default_length);
 364 }
 365
 366 # This action includes the template specified in the 'name' attribute
 367
 368 sub includetemplate {
 369   my($self, $attributes, $content) = @_;
 370   $name = $attributes->{'name'};
 371   return &$blosxom::template($blosxom::path_info, $name, $blosxom::flavour);
 372 }
 373
 374 --
 375
 376 Calling these individually in a Blosxom flavour template looks something like:
 377
 378 The following bit of text is devoid of HTML:
 379
 380 <@myplugin.strip_html output="Yes">
 381 Silly <a href="http://www.raelity.org/">me</a>, I plumb
 382 <em>forgot</em> to remove the HTML.
 383 </@myplugin.strip_html>
 384
 385 The following bit of text is only 20 characters in length:
 386
 387 <@myplugin.foreshorten length="20" output="Yes">This text is far longer than 20 characters on the page, but will only appear as "This text is far lon" in the
 388 resulting page.
 389 </@myplugin.foreshorten>
 390
 391 And in combination, stripping the HTML _before_ foreshortening (notice
 392 the strip_html action is embedded inside the foreshorten action and
 393 thus is run first).
 394
 395 The following bit of text is only 20 characters in length and devoid of HTML:
 396
 397 <@myplugin.foreshorten length="20" output="Yes"><@myplugin.strip_html output="Yes">Silly <a href="http://www.raelity.org/">me</a>, I plumb
 398 <em>forgot</em> to remove the HTML.
 399 </@myplugin.strip_html>
 400 </@myplugin.foreshorten>
 401
 402 The following includes the 'sidebar' template, while interpolating
 403 the contents of that file:
 404
 405 <@myplugin.include name="sidebar" output="yes" interpolate="yes"/>
 406
 407 =head1 INSTALLATION
 408
 409 Drop the interpolate_fancy plug-in into your Blosxom plugins folder.
 410
 411 =head1 CONFIGURATION
 412
 413 None necessary; interpolate_fancy will run out of the box with no need
 414 of additional configuration or fiddling on your part (caveat: see
 415 BACKWARD COMPATILITY below).
 416
 417 The interpolate_fancy plugin does sport one configuration directive
 418 which you should very much consider leaving alone.
 419
 420 # 0 = No (default),  1 = Yes
 421 my $recurse_into_story = 0;
 422
 423 $recurse_into_story decides whether or not the interpolation engine
 424 should respect and interpolate (swap for the associated value)
 425 variables and actions embedded in story $title and $body themselves.
 426
 427 Off by default, you should consider and reconsider carefully before
 428 turning this on as if anyone other than you has the ability to post
 429 stories to your blog, there's a chance of some tomfoolery, exposing
 430 variables and calling actions/subroutines you might not want called.
 431
 432 =head1 BACKWARD COMPATIBILITY
 433
 434 If you've been using core Blosxom's interpolation style
 435 (e.g. $title), this plugin will provide backward compatibility,
 436 requiring no template rewriting on your part.
 437
 438 If you've been using the interpolate_conditional plugin,
 439 the conditional bits won't be respected by default.  You should
 440 run your templates through the interpolate2fancy utility
 441 [http://www.blosxom.com/downloads/utilities/interpolate2fancy.py].
 442
 443 =head1 VERSION
 444
 445 2007-09-27
 446
 447 =head1 VERSION HISTORY
 448
 449 2007-09-27 : enables more than one :: in variable names
 450
 451 2007-09-13 : corrects the $recurse_into_story feature in XML flavours
 452
 453 v20061114 : fixes from Matthijs Kooijman (including properly support for nested
 454 conditions)
 455
 456 =head1 AUTHOR
 457
 458 Rael Dornfest  <rael@oreilly.com>, http://www.raelity.org/
 459 Modified by Matthijs Kooijman <m.kooijman@student.utwente.nl>, http://katherina.student.utwente.nl/~matthijs/blog
 460
 461 This plugin is now maintained by the Blosxom Sourceforge Team,
 462 <blosxom-devel@lists.sourceforge.net>.
 463
 464 =head1 SEE ALSO
 465
 466 Blosxom Home/Docs/Licensing: http://blosxom.sourceforge.net/
 467
 468 Blosxom Plugin Docs: http://blosxom.sourceforge.net/documentation/users/plugins.html
 469
 470 =head1 BUGS
 471
 472 None known; please send bug reports and feedback to the Blosxom
 473 development mailing list <blosxom-devel@lists.sourceforge.net>.
 474
 475 =head1 LICENSE
 476
 477 Blosxom and this Blosxom Plug-in
 478 Copyright 2003, Rael Dornfest
 479
 480 Permission is hereby granted, free of charge, to any person obtaining a
 481 copy of this software and associated documentation files (the "Software"),
 482 to deal in the Software without restriction, including without limitation
 483 the rights to use, copy, modify, merge, publish, distribute, sublicense,
 484 and/or sell copies of the Software, and to permit persons to whom the
 485 Software is furnished to do so, subject to the following conditions:
 486
 487 The above copyright notice and this permission notice shall be included
 488 in all copies or substantial portions of the Software.
 489
 490 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 491 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 492 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
 493 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
 494 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 495 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 496 OTHER DEALINGS IN THE SOFTWARE.