|
Check-in Number:
|
3376 | |
| Date: |
2003-May-23 13:09:56 (local)
2003-May-23 11:09:56 (UTC) |
| User: | rse |
| Branch: | |
| Comment: |
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 |
| Tickets: |
|
| Inspections: |
|
| Files: |
|
ossp-pkg/string-divert/ChangeLog -> 1.1
*** /dev/null Sat May 18 20:00:33 2024
--- - Sat May 18 20:00:37 2024
***************
*** 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
+
|
|
ossp-pkg/string-divert/Divert.pm 1.1 -> 1.2
--- 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 <rse@engelschall.com>
+## String::Divert - String Object supporting Folding and Diversion
+## Copyright (c) 2003 Ralf S. Engelschall <rse@engelschall.com>
##
-## 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)) {
|
|
ossp-pkg/string-divert/Divert.pod 1.1 -> 1.2
--- 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 <rse@engelschall.com>
+## String::Divert - String Object supporting Folding and Diversion
+## Copyright (c) 2003 Ralf S. Engelschall <rse@engelschall.com>
##
-## 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::Divert> - String Object with Folding and Diversions
+B<String::Divert> - String Object supporting Folding and Diversions
=head1 SYNOPSIS
@@ -57,24 +57,50 @@
=head1 ABSTRACT
-B<String::Divert> is small Perl 5 module providing a scalar-like
-string object with some overloaded operators, providing the concept of
-I<Diversions> for supporting nested output generation.
+B<String::Divert> is small Perl 5 module providing a scalar-like string
+object with some overloaded operators, supporting the concept of
+I<Folding> and I<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.
-=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<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.
-B<String::Divert> is small Perl 5 module providing a scalar-like
-string object with some overloaded operators, providing the concept of
-I<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.
+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<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 B<overload>).
+convenience in using the functionality (see also method B<overload>).
=head2 Object Lifetime
@@ -184,7 +210,7 @@
=item XAPI: C<$x E<gt>E<gt> $y;>
-I<Content Folding>. This folds the contents of string cobject C<$x> at
+I<Content Folding>. This folds the contents of string object C<$x> at
the current position by appending a B<String::Divert> sub object (given
in existing object C<$y> or created on-the-fly with name I<name>). 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 .=
"<html>\n" .
@@ -283,39 +309,39 @@
" " . $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" .
+ " " . $html->folder("left") .
" </td>\n" .
- " <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;
@@ -345,9 +371,9 @@
=over 0
-=item B<m4>'s C<divert()> function.
+=item B<m4>'s C<divert()> function.
-=item B<Perl> module B<Data::Location>.
+=item B<Perl> module B<Data::Location>.
=item B<WML>'s C<wml_p5_divert> filter.
|
|
ossp-pkg/string-divert/Makefile.PL 1.1 -> 1.2
--- 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 <rse@engelschall.com>
+##
+## 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 <rse@engelschall.com>'
);
|
|
ossp-pkg/string-divert/TODO 1.1 -> 1.2
--- 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.
|
|
ossp-pkg/string-divert/sample2.pl 1.1 -> 1.2
--- 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 .= "<table>\n" .
" <tr>\n" .
- " <td>\n" .
- " " . $html->folder("left") .
+ " <td>\n" .
+ " " . $html->folder("left") .
" </td>\n" .
- " <td>\n" .
+ " <td>\n" .
" " . $html->folder("right") .
" </td>\n" .
" </tr>\n" .
|
|
ossp-pkg/string-divert/test.pl 1.1 -> 1.2
--- 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 <rse@engelschall.com>
+## String::Divert - String Object supporting Folding and Diversion
+## Copyright (c) 2003 Ralf S. Engelschall <rse@engelschall.com>
##
-## 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
|
|
