NAME

SGML::Element - an element of an SGML, XML, or HTML document

SYNOPSIS

  $element->gi;
  $element->name;
  $element->attr ($attr[, $value]);
  $element->attr_as_string ($attr[, $context, ...]);
  $element->attributes [($attributes)];
  $element->contents [($contents)];

  $element->as_string([$context, ...]);

  $element->iter;

  $element->accept($visitor, ...);
  $element->accept_gi($visitor, ...);
  $element->children_accept($visitor, ...);
  $element->children_accept_gi($visitor, ...);

DESCRIPTION

An SGML::Element represents an element in an SGML or XML document. An Element contains a generic identifier, or name, for the element, the elements attributes and the ordered contents of the element.

$element->gi and $element->name are synonyms, they return the generic identifier of the element.

$element->attr returns the value of an attribute, if a second argument is given then that value is assigned to the attribute and returned. The value of an attribute may be an array of scalar or SGML::SData objects, an SGML::Notation, or an array of SGML::Entity or SGML::ExtEntity objects. attr returns undef for implied attributes.

$element->attr_as_string returns the value of an attribute as a string, possibly modified by $context. (XXX undefined results if the attribute is not cdata/sdata.)

$element->attributes returns a reference to a hash containing the attributes of the element, or undef if there are no attributes defined for for this element. The keys of the hash are the attribute names and the values are as defined above. $element->attributes($attributes) assigns the attributes from the hash $attributes. No hash entries are made for implied attributes.

$element->contents returns a reference to an array containing the children of the element. The contents of the element may contain other elements, scalars, SGML::SData, SGML::PI, SGML::Entity, SGML::ExtEntity, or SGML::SubDocEntity objects. $element->contents($contents) assigns the contents from the array $contents.

$element->as_string returns the entire hierarchy of this element as a string, possibly modified by $context. See SGML::SData and SGML::PI for more detail. (XXX does not expand entities.)

$element->iter returns an iterator for the element, see Class::Visitor for details.

$element->accept($visitor[, ...]) issues a call back to $visitor->visit_SGML_Element($element[, ...]). See examples visitor.pl and simple-dump.pl for more information.

$element->accept_gi($visitor[, ...]) issues a call back to $visitor->visit_gi_GI($element[, ...]) where GI is the generic identifier of this element. accept_gi maps strange characters in the GI to underscore (`_') [XXX more specific].

children_accept and children_accept_gi call accept and accept_gi, respectively, on each object in the element's content.

Element handles scalars internally for as_string, children_accept, and children_accept_gi. For children_accept and children_accept_gi (both), Element calls back with $visitor->visit_scalar($scalar[, ...]).

For as_string, Element will use the string unless $context->{cdata_mapper} is defined, in which case it returns the result of calling the cdata_mapper subroutine with the scalar and the remaining arguments. The actual implementation is:

    &{$context->{cdata_mapper}} ($scalar, @_);

AUTHOR

Ken MacLeod, ken@bitsko.slc.ut.us

SEE ALSO

perl(1), SGML::Grove(3), Text::EntityMap(3), SGML::SData(3), SGML::PI(3), Class::Visitor(3).