NAME

String::Divert - String Object supporting 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, supporting the concept of Folding and Diversion. This allows nested generation of structured output. The idea is to decouple the sequential generation of output from the nested and non-sequential structure of the output.

The two most prominent examples are the generation of code in SGML/XML based languages like [X]HTML (where large and deeply nested structures occur) and the generation of code in typed 3GL procedural languages like C/C++ (where symbols have to be declared before usage). Here String::Divert allows you to generate the code in steps from the outer to the inner level or to append code to already generated previous or later inserted parts.

This is achieved by leveraging two basic concepts: content folding and operation diversion.

Content Folding

The concept of content folding allows you to fold the content at the current output position by inserting a placeholder corresponding to a sub-output and just proceeding with the output generation. The sub-output initially is empty. Once output is appended to it (see diversion below), it will occur at the placeholder position if the content is unfolded later. Folding can be applied to the sub-object again and this way allowing arbitrary nested structures. A sub-output even can be unfolded into multiple placeholder positions.

Operation Diversion

The concept of operation diversion allows you to automatically divert an operation to one object to another object. Usually this is used for diverting output generation operations on a top-level string object to folded sub-objects without having to deal with multiple object variables and without having to know that you are actually operating on a sub-object. Diversions are applied in a stacked fashion, allowing the stepping back to the previous active diversion.

DESCRIPTION

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 convenience 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: $y = $x->clone;

Object Cloning. This recursively clones the string object in $x.

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). The default is "none".

SAPI: $mode = $x->storage;

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

Storage Mode. Retrieves the current storage mode of string object $x or sets a new storage mode. The mode can be "none" (neither contents nor foldings is stored), "fold" (only foldings are stored), or "all" (both contents and foldings are stored). The default is "all".

SAPI: $mode = $x->copying;

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

Copying Mode. Retrieves the current copying mode of string object $x or sets a new copying mode. The mode can be "pass" (just pass-through objects in the "copy constructor" from the XAPI) or "clone" (clone object in the "copy constructor" from the XAPI). The default is "pass".

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.

SAPI: $bool = $x->bool;

Content Unfolding (Temporary). This unfolds the contents of string object $x until its value is already equivalent to the boolean true value or finally equivalent to the boolean false value. The contents of the string object is still kept in folded internal format.

Content Folding

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

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

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

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

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

XAPI: $x >> $y;

Content Folding. This folds the contents of string object $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. If no name or object is given, an anonymous sub object is created on the fly (for use by method divert without arguments).

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);

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

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

Content Folding Lookup. This lookups in string object $x the contained folding sub-object with name $name. If $name is not specified, it returns a list of all folding sub-objects.

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

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

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

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. If no $name is given, an anonymous folder is returned on the fly (for use by method divert without arguments).

Operation Diversion

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

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

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

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

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. If no $name or object $y is specified, a diversion is activated to the folder which was inserted last into the currently or previously active objects.

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

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

XAPI: $x << $num;

XAPI: $x << $name;

Content Diversion Deactivation. This deactivates the last $num activated diversions. If $num is 0, deactivates all activated diversions. If $name is given (i.e. the argument is not numeric), it deactivates all last activated diversion up to and including the one to the string object named $name.

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";
 $html >> "body";

 #   generate 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 header
 $html >> "head";
 $html .= "<title>foo</title>\n";
 $html << 1;

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

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

 #   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