# XML::Grove::AsString - phpMan

## NAME
    [XML::Grove::AsString] - output content of XML objects as a string

## SYNOPSIS
     use [XML::Grove::AsString];

     # Using as_string method on [XML::Grove::Document] or [XML::Grove::Element]:
     $string = $xml_object->as_string OPTIONS;
     $string = $element->attr_as_string $attr, OPTIONS;

     # Using an [XML::Grove::AsString] instance:
     $writer = new [XML::Grove::AsString] OPTIONS;

     $string = $writer->as_string($xml_object);
     $writer->as_string($xml_object, $file_handle);

## DESCRIPTION
    Calling `"as_string"' on an XML object returns the character data
    contents of that object as a string, including all elements below that
    object. Calling `"attr_as_string"' on an element returns the contents of
    the named attribute as a string. Comments, processing instructions, and,
    by default, entities all return an empty string.

    *OPTIONS* may either be a key-value list or a hash containing the
    options described below. *OPTIONS* may be modified directly in the
    object. The default options are no filtering and entities are mapped to
    empty strings.

## OPTIONS
    Filter
        `"Filter"' is an anonymous sub that gets called to process character
        data before it is appended to the string to be returned. This can be
        used, for example, to escape characters that are special in output
        formats. The `"Filter"' sub is called like this:

            $string = &$filter ($character_data);

    EntityMap
        `"EntityMap"' is an object that accepts `"lookup"' methods or an
        anonymous sub that gets called with the entity replacement text
        (data) and mapper options as arguments and returns the corresponding
        character replacements. It is called like this if it is an object:

            $replacement_text = $entity_map->lookup ($entity_data,
                                                     $entity_map_options);

        or this if it is a sub:

            $replacement_text = &$entity_map ($entity_data,
                                              $entity_map_options);

    EntityMapOptions
        `"EntityMapOptions"' is a hash passed through to the `"lookup"'
        method or anonymous sub, the type of value is defined by the entity
        mapping package or the anonymous sub.

    EntityMapFilter
        `"EntityMapFilter"' is a flag to indicate if mapped entities should
        be filtered after mapping.

## EXAMPLES
    Here is an example of entity mapping using the [Text::EntityMap] module:

        use [Text::EntityMap];
        use [XML::Grove::AsString];

        $html_iso_dia = [Text::EntityMap]->load ('ISOdia.2html');
        $html_iso_pub = [Text::EntityMap]->load ('ISOpub.2html');
        $html_map = [Text::EntityMap]->group ($html_iso_dia,
                                            $html_iso_pub);

        $element->as_string (EntityMap => $html_map);

## AUTHOR
    Ken MacLeod, <ken@bitsko.slc.ut.us>

## SEE ALSO
    [perl(1)], XML::[Grove(3)]

    Extensible Markup Language (XML) <<http://www.w3c.org/XML>>