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