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::Document
    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 location, or to use
    kluges like *splice* on the arrays.

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 `_list' and `string' methods) as a group within a
    group:

        $g1 = new RTF::Group(g1);
        $g2 = new RTF::Group(g2);
        $g1->append($g2);
        print $g1->string;         # emits '{g1{g2}}'

    If we disable the `subgroup' property, we get the following:

        $g1 = new RTF::Group(g1);
        $g2 = new RTF::Group(g2, {subgroup=>0});
        $g1->append($g2);
        print $g1->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.

    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, controls,
    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 `_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 `_list()'. For
    insance,

        sub generator
        {
            return 'g2';
        }

        $g1 = new RTF::Group(g1);
        $g1->append( \&generator, [] );
        print $g1->string();       # emits '{g1 g2}'

    Note that `\&generator' cannot have any arguments. However, the
    next argument in the list is a reference to a list of arguments.

  string

        print $group->string();

    Returns the group as a string that would appear in an RTF
    document.

  is_empty

        if ($group->is_empty) { ... }

    Returns true if the group is empty, false if it contains
    something. Zero-length strings are considered nothing.

  _list

        @RTF = $group->_list LIST;

    "Parses" LIST by dereferencing scalars, arrays or subgroups. 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 `_list()' method into a string. This
    is a private method and may go away in future versions: use the
    `string' method instead.

  _escape

        $atom = RTF::Group::_escape( SCALAR );

    Does simple RTF escaping of brackets and 8-bit characters.

SEE ALSO
    Microsoft Technical Support and Application Note, "Rich Text
    Format (RTF) Specification and Sample Reader Program", Version
    1.5.

AUTHOR
    Robert Rothenberg <wlkngowl@unix.asb.com>

LICENSE
    Copyright (c) 1999-2000 Robert Rothenberg. All rights reserved.
    This program is free software; you can redistribute it and/or
    modify it under the same terms as Perl itself.