NAME

String::Divert - String Object with Folding and Diversions

SYNOPSIS

use String::Divert;

#   standard object-oriented API (SAPI)
$x = new String::Divert;
$x->assign("foo");
$x->fold("sub");
$x->append("quux");
$x->divert("sub");
$x->append("bar");
$x->undivert(0);
print "x=".$x->string()."\n";
$x->destroy();

#   extended operator-overloaded API (XAPI)
$x = new String::Divert;
$x->overload(1);
$x .= "foo";
$x *= "sub";
$x .= "quux";
$x >> "sub";
$x .= "bar";
$x << 0;
print "x=$x\n";
undef $x;

ABSTRACT

String::Divert is small Perl 5 module providing a scalar-like string object with some overloaded operators, providing the concept of Diversions for supporting nested output generation.

DESCRIPTION

String::Divert is small Perl 5 module providing a scalar-like string object with some overloaded operators, providing the concept of Diversions. This supports the nested generation of structured outputs. The idea is to decouple the sequential generation of structured output from the nested and non-sequential structure of the output.

APPLICATION PROGRAMMING INTERFACE (API)

String::Divert provides two Application Programming Interfaces (API): a standard object-oriented API (SAPI) providing the core functionality and an extended operator-overloading API (XAPI) providing additional convinience in using the functionality (see also method overload).

Object Lifetime

The following methods deal with the lifetime of a String::Divert object:

SAPI: $x = new String::Divert [$name];

Object Construction. This creates a new string object with either an empty initial name or the one given in $name.

SAPI: $x->destroy;

SAPI: undef $x;

Object Destruction. This destroys the string object in $x and this way releases all of its resources. Folding sub objects are destroyed implicitly unless they are still references by the application.

Object Attributes

The following methods adjust attributes of a String::Divert object:

SAPI: $overloaded = $x->overload;

SAPI: [$old_overloaded =] $x->overload($new_overloaded);

Object Operator Overloading. Either just retrieves whether string object $x is operator overloaded or sets new operator overloading. If $new_overloaded is false, operator overloading is disabled (only SAPI is active); if it is true, operator overloading is enabled (both SAPI and XAPI are active).

SAPI: $name = $x->name;

SAPI: [$old_name =] $x->name($new_name);

Object Naming. Either just retrieves the current name of string object $x or sets a new name. The name of a string object is used to identify the object on folding and diversion in case no object reference is used.

SAPI: $mode = $x->overwrite;

SAPI: [$old_mode =] $x->overwrite($new_mode);

Overwrite Mode. Retrieves the current overwrite mode of string object $x or sets a new overwrite mode. The mode can be "none" (no overwriting), "once" (no overwriting once on next append operation only), or "always" (overwriting on every append operation).

Content Manipulation

The following methods manipulate the contents of a String::Divert object:

SAPI: [$x =] $x->assign($string);

Content Assignment. Assigns $string as the new contents of the string object $x. The existing contents is lost.

SAPI: [$x =] $x->append($string);

XAPI: $x .= $string;

Content Appending. Appends $string to the existing contents of the string object $x. If the overwrite mode (see above) is "once", the previous contents is removed first and the overwrite mode set to "none". If it is "always", the previous contents is removed every time.

SAPI: $string = $x->string;

XAPI: $string = "$x";

Content Unfolding (Temporary). This unfolds the contents of string object $x and returns it as a string. The contents of the string object is still kept in folded internal format. For permanently unfolding the contents in string object $x, you have to use operation unfold.

Content Folding

The following methods deal with content folding of a String::Divert object:

SAPI: [$y =] $x->fold($name);

SAPI: $x->fold($y);

XAPI: [$y = (]$x >>= $name[)];

XAPI: $x >> $y;

Content Folding. This folds the contents of string cobject $x at the current position by appending a String::Divert sub object (given in existing object $y or created on-the-fly with name name). The sub-object representing the folding is allowed to be re-appended by name or through $y.

SAPI: [$string =] $x->unfold;

XAPI: [$string =] <$x>;

Content Unfolding (Permanently). This unfolds the contents of string object $x and stores the result permanently as the new contents. For temporarily unfolding the contents in string object $x, you can use operation string.

SAPI: $y = $x->folding($name);

XAPI: $y = ($x <<= $name);

Content Folding Lookup. This lookups in string object $x the contained folding sub-object with name $name.

SAPI: $x->folder($format, $regex);

SAPI: $string = $x->folder($name);

Content Folding Textual Representation. This configures (if the two argument form is used) or generates (if the one argument form is used) textual representation of a content folding. For configuring, the $format has to be a Perl sprintf() format string (containing only a single %s for expanding the name of the folding object) generating the textual representation and $regex a Perl regular expression (containing a single clustering parenthesis pair) for matching a generated textual representation and returning the name of the folding object. The defaults are "{#%s#}" and "\{#([a-zA-Z_][a-zA-Z0-9_]*)#\}". In the one argument form, the function applies $name to the previously configured $format and returns the result for inclusion into a string which in turn is assigned or appended to the string object.

Operation Diversion

The following methods deal with operation diversion of a String::Divert object:

SAPI: [$x =] $x->divert($name);

SAPI: [$x =] $x->divert($y);

XAPI: $x >> $name;

XAPI: $x >> $y;

Content Diversion Activation. This activates in string object $x a content diversion to a sub-object (given by name $name or object reference $y). The diversion target should be a folded sub-object of $x, but is not technically required.

SAPI: [$x =] $x->undivert($num);

XAPI: $x << $num;

Content Diversion Deactivation. This deactivates the last $num activated diversions. If $num is 0, deactivates all activated diversions.

SAPI: $y = $x->diversion;

SAPI: @y = $x->diversion;

Content Diversion Lookup. This lookups and returns the last or all (in reverse oder of activation) sub-objects of activated diversion.

EXAMPLE

The following part of a fictive CGI program demonstrates how to generate the structured HTML code in a nested, clean and intuitive fashion:

#   create new object with operator overloading activated
use String::Divert;
my $html = new String::Divert;
$html->overload(1);

#   generate outer HTML framework
$html .=
    "<html>\n" .
    "  <head>\n" .
    "    " . $html->folder("head") .
    "  </head>\n" .
    "  <body>\n" .
    "    " . $html->folder("body") .
    "  </body>\n" .
    "</html>\n";

#   generate header
$html >> "head";
$html .= "<title>foo</title>\n";
$html << 1;

#   generate body
$html >> "body";
$html .= "<table>\n" .
         "  <tr>\n" .
         "   <td>\n" . 
         "     " . $html->folder("left") . 
         "   </td>\n" .
         "   <td>\n" . 
         "     " . $html->folder("right") .
         "   </td>\n" .
         "  </tr>\n" .
         "</table>\n";

#   generate left contents
$html >> "left";
$html .= "bar1\n" .
         "bar2\n";

#   generate right contents
$html >> "right";
$html .= "quux1\n" .
         "quux2\n";

#   undivert all diversions and output unfolded HTML
$html << 0;
print $html;

#   destroy object
$html->destroy;

The output of this program obviously is:

<html>
  <head>
    <title>foo</title>
  </head>
  <body>
    <table>
      <tr>
       <td>
         bar1
         bar2
       </td>
       <td>
         quux1
         quux2
       </td>
      </tr>
    </table>
  </body>
</html>

SEE ALSO

m4's divert() function.

Perl module Data::Location.

WML's wml_p5_divert filter.

HISTORY

String::Divert was implemented in May 2003 by Ralf S. Engelschall <rse@engelschall.com> for reducing the complexity in conditional generation of HTML code within a web application.

AUTHOR

Ralf S. Engelschall <rse@engelschall.com>

cpanm String::Divert

perl -MCPAN -e shell
install String::Divert