group(3)
NAME
RTF::Group - Base class for manipulating Rich Text Format
(RTF) groups
DESCRIPTION
This is a base class for manipulating RTF groups. Groups
are stored internally as lists. Lists may contain
(sub)groups or atoms (raw text or control words).
Unlike the behavior of groups in the original "RTF::Docu
ment module" (versions 0.63 and earlier), references to
arrays (lists) are not treated as subgroups, but are
dereferenced when expanded (as lists or strings).
This allows more flexibility for changing control codes
within a group, without having to know their exact loca
tion, or to use kluges like splice on the arrays.
I am in the process of writing a "RTF::Generator" module
which will supercede "RTF::Document".
METHODS
- new
- $group = new RTF::Group LIST, PROPERTIES;
- Creates a new group. If LIST is specified, it is appended
to the group. PROPERTIES are optional, and are used to
set properties for the object. - By default, the "subgroup" property is set. This means
that if the group is appended to another group, it will be
emitted (using the "_rtf_list" and "as_string" methods) as
a group within a group:
$g1 = new RTF::Group(g1);
$g2 = new RTF::Group(g2);
$g1->append($g2);
print $g1->as_string; # emits '{g1{g2}}'- If we disable the "subgroup" property, we get the follow
ing:
$g1 = new RTF::Group(g1);
$g2 = new RTF::Group(g2, {subgroup=>0});
$g1->append($g2);
print $g1->as_string; # emits '{g1 g2}'- The "escape" property enables automatic escaping of
unescaped curly brackets when a group is emitted as a
string. (This property is also enabled by default.) - The "wrap" property is not used in this version.
- Each property is also a method for getting or setting it's
value. For example,
unless ($g2->subgroup)
{$g2->subgroup(1);- }
- See the "append" method for more details on how groups are
handled. - append
$group->append LIST;- Appends LIST to the group. LIST may be plain text, con
trols, other groups, or references to a SCALAR or another
LIST. - If LIST contains another RTF::Group, it will be embedded
as a subgroup (how this is handled is explained in the the
documentation for the "new" method). - If LIST contains a reference to a SCALAR, the value it
points to will be emitted when the "_rtf_list()" or
"_string" methods are called. - If LIST contains a reference to CODE, the value that code
returns will be emitted as if it were returned by
"_rtf_list()". For instance,
sub generator
{my $arg = shift;
return uc($arg);- }
- $g1 = new RTF::Group(g1);
$g1->append( generator, 'g2' ); - print $g1->as_string(); # emits '{g1 G2}'
- Note that "generator" must have one and only one argu
ment, which is following item on the list. The argument is
not processed by "RTF::Group". (Versions of this module
prior to 1.00 specified an array reference as the argu
ment. This is not necessarily the case now.) - prepend
$group->prepend LIST- Opposite of "append", in that the LIST is added before
everything else in the group. Use with caution. - as_string
print $group->as_string();- Returns the group as a string that would appear in an RTF
document. (The deprecated "string" method is an alias for
"as_string".) - is_empty
if ($group->is_empty) { ... }- Returns true if the group is empty, false if it contains
something. Zero-length strings are considered nothing. - _rtf_list
@RTF = $group->_rtf_list LIST;- "Parses" LIST by dereferencing scalars, arrays or sub
groups. If LIST is not specified, parses group. (Although
this may useful for parsers, it is intended for internal
use (read: private method).) - _list_as_string
$output = $group->_list_as_string( LIST )- Converts the output of the "_rtf_list()" method into a
string. This is a private method and may go away in future
versions: use the "as_string" method instead. - _escape
$atom = RTF::Group::_escape( SCALAR );- Does simple RTF escaping of brackets and 8-bit characters.
It is also a private method. - escape_simple
use RTF::Group qw( escape_simple );- $text = escape_simple( SCALAR );
- Does simple escaping of characters not handled by _escape.
Special characters (such as tabs) are not changed into
their equivalent RTF control words. - check_params
- This is a utility function used by some modules in the
RTF-Generator distribution (since RTF::Group is used by
all modules). It may go away in future versions.
CAVEATS
Incompatabilities with Previous Versions
This version is a rewrite. Some embarassingly wrongheaded
code was changed.
Earlier versions of "RTF::Group" specified that code ref
erences required an array reference to follow as an argu
ment. That is now not the case: while one and only one
argument is still required, it can be anything: a scalar,
a scalar reference, a hash reference, an array reference,
etc.
Circular References
- "RTF::Group" cannot handle circular references. This ver
sion does not even check for them. Which means that - $g1 = new RTF::Group();
$g2 = new RTF::Group(); - $g1->append($g2);
$g2->append($g1); - will cause bad things to happen. Do not do this.
SEE ALSO
Microsoft Technical Support and Application Note, "Rich
Text Format (RTF) Specification and Sample Reader Pro
gram", Version 1.5.
FUTURE ENHANCEMENTS
Possibly the ability to parse a stream into an
"RTF::Group" and some hooks to plug in a parser (so that
the "RTF::Parser" module will work nicely with this).
AUTHOR
Robert Rothenberg <rrwo@cpan.org>
LICENSE
- Copyright (c) 1999-2001 Robert Rothenberg. All rights
reserved. This program is free software; you can redis
tribute it and/or modify it under the same terms as Perl
itself.