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.