NAME

YAPE::HTML::Element - sub-classes for YAPE::HTML elements

SYNOPSIS

  use YAPE::HTML 'MyExt::Mod';
  # this sets up inheritence in MyExt::Mod
  # see YAPE::HTML documentation

`YAPE` MODULES

The YAPE hierarchy of modules is an attempt at a unified means of parsing and extracting content. It attempts to maintain a generic interface, to promote simplicity and reusability. The API is powerful, yet simple. The modules do tokenization (which can be intercepted) and build trees, so that extraction of specific nodes is doable.

DESCRIPTION

This module provides the classes for the YAPE::HTML objects. The base class for these objects is YAPE::HTML::Element; the four object classes are YAPE::HTML::opentag, YAPE::HTML::closetag, YAPE::HTML::text, and YAPE::HTML::comment.

Methods for `YAPE::HTML::Element`

This class contains fallback methods for the other classes.

my $content = $obj->text;

Returns an array reference of objects between an open and close tag, or a string of plain text for a block of text or a comment. This method merely returns the TEXT value in the object hash. This returns undef for dtd, pi, and ssi objects.
my $string = $obj->string;

Returns a string representing the single object (for tags, this does not include the elements found in between the open and close tag). This method merely calls the object's text method.
my $complete = $obj->fullstring;

Returns a string representing the object (and all objects found within it, in the case of a tag). This method merely calls the object's string method.
my $type = $obj->type;

Returns the type of the object: tag, closetag, text, or comment.

Methods for `YAPE::HTML::opentag`

This class represents tags. Object has the following methods:

my $tag = YAPE::HTML::opentag->new($name, $attr, $text, $closed, $impl);

Creates a YAPE::HTML::opentag object. Takes five arguments: the name of the HTML element, a hash reference of attribute-value pairs, an array reference of objects to be included in between the open and closing tags, whether the tag is explicitly closed or not, and whether the tag is implicitly closed or not. The attribute hash reference must have the keys in lowercase text.
```
  my $attr = { src => 'foo.png', alt => 'foo' };
  my $img = YAPE::HTML::opentag->new('img', $attr, [], 0, 1);
  
  my $text = [ YAPE::HTML::text->new("Bar!"), $img ];
  my $name = YAPE::HTML::opentag->new('a', { name => 'foo' }, $text);
```
my $str = $tag->string;

Creates a string representation of the tag only. This means the tag, and any attributes of the tag only. No closing tag (if any) is returned.
```
  print $img->string;
  # <img src="foo.png" alt="foo" />
  
  print $name->string;
  # <a name="foo">
```
my $str = $tag->fullstring($exclude, $depth);

Creates a string representation of the tag, the content enclosed between the open and closing tags, and the closing tag (if applicable). The method can take two arguments: an array reference of tag names not to render, and the depth with which to render tags. The $exclude defaults to none, and $depth defaults to -1, which means there is no depth limit.
```
  print $img->fullstring;
  # <img src="foo.png" width=20 height=43 />
  
  print $name->fullstring;
  # <a name="foo">Bar!<img src="foo.png" alt="foo" /></a>
  
  print $name->fullstring(0);
  # Bar!
  
  print $name->fullstring(['img']);
  # <a name="foo">Bar!</a>
  
  print $name->fullstring(1);
  # <a name="foo">Bar!</a>
```
my $attr = $tag->get_attr($name);
my @attrs = $tag->get_attr(@names);
my %attrs = $tag->get_attr;

Fetches any number of attribute values from a tag. Note: tags which contain attributes with no value have a value of undef returned for that attribute -- this is indistinguishable from the undef returned for a tag that does not have an attribute. This is on the list of things to be fixed. In the meantime, use the has_attr method beforehand.
```
  print $name->get_attr('name');
  # 'foo'
  
  my %list = $img->get_attr;
  # alt => 'foo', src => 'foo.png'
```
my $attr = $tag->has_attr($name);
my @attrs = $tag->has_attr(@names);

Returns 1 or "" depending on the existence of the attribute in the tag.
```
  my @on = $name->has_attr(qw( name href ));  # (1,0)
```
$tag->set_attr(%pairs);

Sets a list of attributes to the associated values for the tag.
```
  $img->set_attr( width => 40, height => 16 );
```
$tag->rem_attr(@names);

Removes (and returns) the specified attributes from a tag. See the caveat above for the get_attr method about undef values.
```
  my $src = $img->rem_attr('src');
```
my $closed = $tag->closed;

Returns 1 or 0, depending on whether or not the tag is closed. This means it has a closing tag -- tags like <hr /> are not closed.
my $impl = $tag->implied_closed;

Returns 1 or 0, depending on whether or not the tag is implicitly closed with a / at the end of the tag (like <hr />).
my $tagname = $tag->tag;

Returns the name of the HTML element.
```
  print $name->tag;  # 'a'
```

Methods for `YAPE::HTML::closetag`

This class represents closing tags. Object has the following methods:

my $tag = YAPE::HTML::closetag->new($name);

Creates a YAPE::HTML::closetag object. Takes one argument: the name of the HTML element. These objects are never included in the HTML tree structure, since the parser uses the CLOSED attribute of an opentag object to figure out if there needs to be a closing tag. However, they are returned in the parsing stage so that you know when they've been reached.
```
  my $close = YAPE::HTML::closetag->new('a');
```
my $str = $tag->string;

Creates a string representation of the closing tag.
```
  print $close->string;  # '</a>'
```
my $tagname = $tag->tag;

Returns the name of the HTML element.
```
  print $close->tag;  # 'a'
```

Methods for `YAPE::HTML::text`

This class represents blocks of plain text. Objects have the following methods:

my $text = YAPE::HTML::text->new($content);

Creates a YAPE::HTML::text object. Takes one argument: the text of the block.

  my $para = YAPE::HTML::text->new(<< "END");
  Perl is not an acronym -- rather "Practical Extraction
  and Report Language" was developed after the fact.
  END

Methods for `YAPE::HTML::comment`

This class represents comments. Objects have the following methods:

my $comment = YAPE::HTML::comment->new($content);

Creates a YAPE::HTML::comment object. Takes one argument: the text of the comment.
```
  my $todo = YAPE::HTML::comment->new(<< "END");
  This table should be formatted differently.
  END
```
my $str = $comment->string;

Creates a string representation of the comment, with  after it.
```
  print $todo->string;
  # 
```

Methods for `YAPE::HTML::dtd`

This class represents <!DOCTYPE> tags. Objects have the following methods:

my $dtd = YAPE::HTML::dtd->new(\@fields);

Creates a YAPE::HTML::dtd object. Takes one argument: an array reference of the four fields (should be two unquoted strings, and two quoted strings (?)).
```
  my $dtd = YAPE::HTML::dtd->new([
    'HTML',
    'PUBLIC',
    '"-//W3C//DTD HTML 4.01//EN"',
    '"http://www.w3.org/TR/html4/strict.dtd"'
  ]);
```

my $str = $dtd->string;

Creates a string representation of the DTD.

  print $dtd->string;
  # (line breaks added for readability)
  # <!DOCTYPE HTML PUBLIC
  #   "-//W3C//DTD HTML 4.01//EN"
  #   "http://www.w3.org/TR/html4/strict.dtd">

my @attrs = $dtd->get_attrs;

Returns the four attributes of the DTD.
$dtd->set_attrs(@attrs);

Sets the four attributes of the DTD (can't be done piecemeal).

Methods for `YAPE::HTML::pi`

This class represents process instruction tags. Objects have the following methods:

my $pi = YAPE::HTML::pi->new($name, $attr);

Creates a YAPE::HTML::pi object. Takes two arguments: the name of the processing instruction, and a hash reference of attribute-value pairs. The attribute hash reference must have the keys in lowercase text.
```
  my $attr = { order => 'alphabetical', need => 'examples' };
  my $pi = YAPE::HTML::pi->new(sample => $attr);
```
my $str = $pi->string;

Creates a string representation of the processing instruction.
```
  print $pi->string;
  # <?sample need="examples" order="alphabetical"?>
```
my $attr = $pi->get_attr($name);
my @attrs = $pi->get_attr(@names);
my %attrs = $pi->get_attr;
my $attr = $pi->has_attr($name);
my @attrs = $pi->has_attr(@names);
$pi->set_attr(%pairs);
$pi->rem_attr(@names);

See the identical methods for opentag objects above.
my $name = $pi->name;

Returns the name of the processing instruction.
```
  print $pi->name;  # 'first'
```

Methods for `YAPE::HTML::ssi`

This class represents server-side includes. Objects have the following methods:

my $ssi = YAPE::HTML::ssi->new($name, $attr);

Creates a YAPE::HTML::ssi object. Takes two arguments: the SSI command, and a hash reference of attribute-value pairs. The attribute hash reference must have the keys in lowercase text.
```
  my $attr = { var => 'REMOTE_HOST' };
  my $ssi = YAPE::HTML::ssi->new(echo => $attr);
```
my $str = $ssi->string;

Creates a string representation of the processing instruction.
```
  print $ssi->string;
  # 
```
my $attr = $ssi->get_attr($name);
my @attrs = $ssi->get_attr(@names);
my %attrs = $ssi->get_attr;
my $attr = $ssi->has_attr($name);
my @attrs = $ssi->has_attr(@names);
$ssi->set_attr(%pairs);
$ssi->rem_attr(@names);

See the identical methods for opentag objects above.
my $command = $ssi->command;

Returns the SSI command's name.
```
  print $ssi->command;  # 'echo'
```

CAVEATS

The <script> and <xmp> tags are given special treatment. When they are encountered, all text up to the first occurrence of the appropriate closing tag is taken as plain text.

Tag attributes are displayed in the default sort() order.

TO DO

This is a listing of things to add to future versions of this module.

SSI commands if, elif, and else

These need to contain content, since the text between them is associated with a given condition.

BUGS

Following is a list of known or reported bugs.

This documentation might be incomplete.

SUPPORT

Visit YAPE's web site at http://www.pobox.com/~japhy/YAPE/.

AUTHOR

  Jeff "japhy" Pinyan
  CPAN ID: PINYAN
  japhy@pobox.com
  http://www.pobox.com/~japhy/

1 POD Error

The following errors were encountered while parsing the POD:

Around line 650:: =cut found outside a pod block. Skipping to next block.

To install YAPE::HTML, copy and paste the appropriate command in to your terminal.

cpanm

cpanm YAPE::HTML

CPAN shell

perl -MCPAN -e shell
install YAPE::HTML

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

YAPE MODULES

DESCRIPTION

Methods for YAPE::HTML::Element

Methods for YAPE::HTML::opentag

Methods for YAPE::HTML::closetag

Methods for YAPE::HTML::text

Methods for YAPE::HTML::comment

Methods for YAPE::HTML::dtd

Methods for YAPE::HTML::pi

Methods for YAPE::HTML::ssi