Index: ossp-pkg/string-divert/ChangeLog RCS File: /v/ossp/cvs/ossp-pkg/string-divert/ChangeLog,v co -q -kk -p'1.1' '/v/ossp/cvs/ossp-pkg/string-divert/ChangeLog,v' | diff -u /dev/null - -L'ossp-pkg/string-divert/ChangeLog' 2>/dev/null --- ossp-pkg/string-divert/ChangeLog +++ - 2025-04-12 01:59:17.357104070 +0200 @@ -0,0 +1,12 @@ + + ChangeLog + ========= + + 0.91 (23-Apr-2003) + o direct MakeMaker to not install sample[12].pl + o cleanup naming of module, etc. + o remove trailing whitespaces from codes + o cleanup and extend documentation + 0.90 (22-Apr-2003) + o initial release + Index: ossp-pkg/string-divert/Divert.pm RCS File: /v/ossp/cvs/ossp-pkg/string-divert/Divert.pm,v rcsdiff -q -kk '-r1.1' '-r1.2' -u '/v/ossp/cvs/ossp-pkg/string-divert/Divert.pm,v' 2>/dev/null --- Divert.pm 2003/05/22 18:56:50 1.1 +++ Divert.pm 2003/05/23 11:09:56 1.2 @@ -1,9 +1,9 @@ ## -## String::Divert - Diversion String Object -## Copyright (c) 2003 Ralf S. Engelschall +## String::Divert - String Object supporting Folding and Diversion +## Copyright (c) 2003 Ralf S. Engelschall ## -## This file is part of String::Divert, a Perl module for -## dealing with strings containing nested diversions. +## This file is part of String::Divert, a Perl module providing +## a string object supporting folding and diversion. ## ## This program is free software; you can redistribute it and/or ## modify it under the terms of the GNU General Public License @@ -22,7 +22,7 @@ ## Divert.pm: Module Implementation ## -use 5.005; +use 5.006; use strict; use warnings; @@ -36,14 +36,15 @@ require Exporter; +our $VERSION = '0.91'; + our @ISA = qw(Exporter); -our @EXPORT_OK = qw(new destroy DESTROY +our @EXPORT_OK = qw(new destroy DESTROY name overwrite assign append string bool fold unfold folding folder divert undivert diversion overload); -our $VERSION = '0.90'; # object construction sub new ($;$) { @@ -74,7 +75,7 @@ # object destruction (implicit) sub DESTROY ($) { return; -} +} # operation: set/get name of object sub name ($;$) { @@ -148,7 +149,7 @@ if (not defined($string)); die "cannot assign reference as string" if (ref($string)); - if ( $self->{overwrite} eq 'once' + if ( $self->{overwrite} eq 'once' or $self->{overwrite} eq 'always') { $self->{chunks} = []; foreach my $chunk ($self->_chunking($string)) { Index: ossp-pkg/string-divert/Divert.pod RCS File: /v/ossp/cvs/ossp-pkg/string-divert/Divert.pod,v rcsdiff -q -kk '-r1.1' '-r1.2' -u '/v/ossp/cvs/ossp-pkg/string-divert/Divert.pod,v' 2>/dev/null --- Divert.pod 2003/05/22 18:56:50 1.1 +++ Divert.pod 2003/05/23 11:09:57 1.2 @@ -1,9 +1,9 @@ ## -## String::Divert - Diversion String Object -## Copyright (c) 2003 Ralf S. Engelschall +## String::Divert - String Object supporting Folding and Diversion +## Copyright (c) 2003 Ralf S. Engelschall ## -## This file is part of String::Divert, a Perl module for -## dealing with strings containing nested diversions. +## This file is part of String::Divert, a Perl module providing +## a string object supporting folding and diversion. ## ## This program is free software; you can redistribute it and/or ## modify it under the terms of the GNU General Public License @@ -26,7 +26,7 @@ =head1 NAME -B - String Object with Folding and Diversions +B - String Object supporting Folding and Diversions =head1 SYNOPSIS @@ -57,24 +57,50 @@ =head1 ABSTRACT -B is small Perl 5 module providing a scalar-like -string object with some overloaded operators, providing the concept of -I for supporting nested output generation. +B is small Perl 5 module providing a scalar-like string +object with some overloaded operators, supporting the concept of +I and I. 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. -=head1 DESCRIPTION +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 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. -B is small Perl 5 module providing a scalar-like -string object with some overloaded operators, providing the concept of -I. 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. +This is achieved by leveraging two basic concepts: content folding +and operation diversion. + +=head2 Content Folding -=head1 APPLICATION PROGRAMMING INTERFACE (API) +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. + +=head2 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. + +=head1 DESCRIPTION B 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 B). +convenience in using the functionality (see also method B). =head2 Object Lifetime @@ -184,7 +210,7 @@ =item XAPI: C<$x EE $y;> -I. This folds the contents of string cobject C<$x> at +I. This folds the contents of string object C<$x> at the current position by appending a B sub object (given in existing object C<$y> or created on-the-fly with name I). The sub-object representing the folding is allowed to be re-appended by name @@ -272,7 +298,7 @@ use String::Divert; my $html = new String::Divert; $html->overload(1); - + # generate outer HTML framework $html .= "\n" . @@ -283,39 +309,39 @@ " " . $html->folder("body") . " \n" . "\n"; - + # generate header $html >> "head"; $html .= "foo\n"; $html << 1; - + # generate body $html >> "body"; $html .= "\n" . " \n" . - " \n" . - " \n" . " \n" . "
\n" . - " " . $html->folder("left") . + " \n" . + " " . $html->folder("left") . " \n" . + " \n" . " " . $html->folder("right") . "
\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; @@ -345,9 +371,9 @@ =over 0 -=item B's C function. +=item B's C function. -=item B module B. +=item B module B. =item B's C filter. Index: ossp-pkg/string-divert/Makefile.PL RCS File: /v/ossp/cvs/ossp-pkg/string-divert/Makefile.PL,v rcsdiff -q -kk '-r1.1' '-r1.2' -u '/v/ossp/cvs/ossp-pkg/string-divert/Makefile.PL,v' 2>/dev/null --- Makefile.PL 2003/05/22 18:56:50 1.1 +++ Makefile.PL 2003/05/23 11:09:57 1.2 @@ -1,10 +1,36 @@ +## +## String::Divert - String Object supporting Folding and Diversion +## Copyright (c) 2003 Ralf S. Engelschall +## +## This file is part of String::Divert, a Perl module providing +## a string object supporting folding and diversion. +## +## This program is free software; you can redistribute it and/or +## modify it under the terms of the GNU General Public License +## as published by the Free Software Foundation; either version +## 2.0 of the License, or (at your option) any later version. +## +## This program is distributed in the hope that it will be useful, +## but WITHOUT ANY WARRANTY; without even the implied warranty of +## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +## General Public License for more details. +## +## You should have received a copy of the GNU General Public License +## along with this file; if not, write to the Free Software Foundation, +## Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. +## +## Makefile.PL: Module Build Specification +## -use 5.005; +use 5.006; use ExtUtils::MakeMaker; WriteMakefile( NAME => 'String::Divert', VERSION_FROM => 'Divert.pm', + ABSTRACT => 'String Object supporting Folding and Diversion', + PM => { 'Divert.pm' => '$(INST_LIBDIR)/Divert.pm', + 'Divert.pod' => '$(INST_LIBDIR)/Divert.pod' }, PREREQ_PM => {}, AUTHOR => 'Ralf S. Engelschall ' ); Index: ossp-pkg/string-divert/TODO RCS File: /v/ossp/cvs/ossp-pkg/string-divert/TODO,v rcsdiff -q -kk '-r1.1' '-r1.2' -u '/v/ossp/cvs/ossp-pkg/string-divert/TODO,v' 2>/dev/null --- TODO 2003/05/22 18:56:50 1.1 +++ TODO 2003/05/23 11:09:57 1.2 @@ -2,6 +2,9 @@ TODO ==== - o recursion by fold und divert checken - o resurrect TIE mechanism for assignment once Perl is no longer buggy + o check recursion on folding and diversion to avoid loops + + o resurrect TIE mechanism for assignment operator once Perl + is no longer buggy (see "BUGS" in "perldoc overload") and + no longer looses the overloading after STORE. Index: ossp-pkg/string-divert/sample2.pl RCS File: /v/ossp/cvs/ossp-pkg/string-divert/sample2.pl,v rcsdiff -q -kk '-r1.1' '-r1.2' -u '/v/ossp/cvs/ossp-pkg/string-divert/sample2.pl,v' 2>/dev/null --- sample2.pl 2003/05/22 18:56:51 1.1 +++ sample2.pl 2003/05/23 11:09:57 1.2 @@ -26,10 +26,10 @@ $html >> "body"; $html .= "\n" . " \n" . - " \n" . - " \n" . " \n" . Index: ossp-pkg/string-divert/test.pl RCS File: /v/ossp/cvs/ossp-pkg/string-divert/test.pl,v rcsdiff -q -kk '-r1.1' '-r1.2' -u '/v/ossp/cvs/ossp-pkg/string-divert/test.pl,v' 2>/dev/null --- test.pl 2003/05/22 18:56:51 1.1 +++ test.pl 2003/05/23 11:09:57 1.2 @@ -1,9 +1,9 @@ ## -## String::Divert - Diversion String Object -## Copyright (c) 2003 Ralf S. Engelschall +## String::Divert - String Object supporting Folding and Diversion +## Copyright (c) 2003 Ralf S. Engelschall ## -## This file is part of String::Divert, a Perl module for -## dealing with strings containing nested diversions. +## This file is part of String::Divert, a Perl module providing +## a string object supporting folding and diversion. ## ## This program is free software; you can redistribute it and/or ## modify it under the terms of the GNU General Public License @@ -22,6 +22,7 @@ ## test.pl: Module Test Suite ## +use 5.006; use Test::More tests => 36; # test: module loading
\n" . - " " . $html->folder("left") . + " \n" . + " " . $html->folder("left") . " \n" . + " \n" . " " . $html->folder("right") . "