Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Divert(3)	      User Contributed Perl Documentation	     Divert(3)

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>

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 427:
	   Can't have a	0 in =over 0

perl v5.32.1			  2005-11-16			     Divert(3)

NAME | SYNOPSIS | ABSTRACT | DESCRIPTION | EXAMPLE | SEE ALSO | HISTORY | AUTHOR | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=String::Divert&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help