GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  STRING::DIVERT (3)

.ds Aq ’

NAME

String::Divert - String Object supporting Folding and Diversions

CONTENTS

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

<B>String::DivertB> 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 <B>String::DivertB> 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

<B>String::DivertB> 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 <B>overloadB>).

    Object Lifetime

The following methods deal with the lifetime of a <B>String::DivertB> object:
SAPI: $x = <B>new String::DivertB> [$name]; Object Construction. This creates a new string object with either an empty initial name or the one given in $name.
SAPI: $y = $x-><B>cloneB>; Object Cloning. This recursively clones the string object in $x.
SAPI: $x-><B>destroyB>;
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 <B>String::DivertB> object:
SAPI: $overloaded = $x-><B>overloadB>;
SAPI: [$old_overloaded =] $x-><B>overloadB>($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-><B>nameB>;
SAPI: [$old_name =] $x-><B>nameB>($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-><B>overwriteB>;
SAPI: [$old_mode =] $x-><B>overwriteB>($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 <B>appendB> operation only), or "always" (overwriting on every <B>appendB> operation). The default is "none".
SAPI: $mode = $x-><B>storageB>;
SAPI: [$old_mode =] $x-><B>storageB>($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-><B>copyingB>;
SAPI: [$old_mode =] $x-><B>copyingB>($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 <B>String::DivertB> object:
SAPI: [$x =] $x-><B>assignB>($string); Content Assignment. Assigns $string as the new contents of the string object $x. The existing contents is lost.
SAPI: [$x =] $x-><B>appendB>($string);
XAPI: $x .= $string; Content Appending. Appends $string to the existing contents of the string object $x. If the <B>overwriteB> mode (see above) is "once", the previous contents is removed first and the <B>overwriteB> mode set to "none". If it is "always", the previous contents is removed every time.
SAPI: $string = $x-><B>stringB>;
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 <B>unfoldB>.
SAPI: $bool = $x-><B>boolB>; 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 <B>String::DivertB> object:
SAPI: [$y =] $x-><B>foldB>($name);
SAPI: [$y =] $x-><B>foldB>($y);
SAPI: [$y =] $x-><B>foldB>();
XAPI: [$y = (]$x >>= $name[)];
XAPI: $x >> $y; Content Folding. This folds the contents of string object $x at the current position by appending a <B>String::DivertB> 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 <B>divertB> without arguments).
SAPI: [$string =] $x-><B>unfoldB>;
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 <B>stringB>.
SAPI: $y = $x-><B>foldingB>($name);
SAPI: @y = $x-><B>foldingB>();
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-><B>folderB>($format, $regex);
SAPI: $string = $x-><B>folderB>($name);
SAPI: $string = $x-><B>folderB>(); 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 <B>divertB> without arguments).

    Operation Diversion

The following methods deal with operation diversion of a <B>String::DivertB> object:
SAPI: [$x =] $x-><B>divertB>($name);
SAPI: [$x =] $x-><B>divertB>($y);
SAPI: [$x =] $x-><B>divertB>();
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-><B>undivertB>($num);
SAPI: [$x =] $x-><B>undivertB>($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-><B>diversionB>;
SAPI: @y = $x-><B>diversionB>; 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

<B>m4B>’s divert() function.
<B>PerlB> module <B>Data::LocationB>.
<B>WMLB>’s wml_p5_divert filter.

HISTORY

<B>String::DivertB> 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>

POD ERRORS

Hey! <B>The above document had some coding errors, which are explained below:B>
Around line 427: Can’t have a 0 in =over 0
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 DIVERT (3) 2005-11-16

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.