cs::HTML - support for parsing and generating HTML markup
use cs::HTML;
This module supplies methods for decomposing HTML text into a data structure and also methods for converting a perl-friendly data structure into HTML text.
A cs::HTML object does not represent a tag but a token source from which HTML tokens may be read. See OBJECT CREATION below.
Test whether a tag needs a closing </tag> partner.
Compose the arguments into a hashref of the form:
{ TAG => tag, ATTRS => attrs, TOKENS => [ subtokens... ] }
If omitted, attrs defaults to {}.
Take a hand constructed array of HTML tokens, which may contain a mix of tokens in the form
{ TAG => tag, ATTRS => attrs, TOKENS => [ subtokens... ] }
and the form
[ tag, attrs, subtokens... ]
and return a list of these tokens converted into the first form, suitable for analysis.
Take some HTML tokens and return a string containing the textual component, with all markup discarded.
take a list of HTML tokens and return the HTML text, nicely indented if doindent = 1. If omitted, doindent defaults to 0. In a scalar context returns a single string with the HTML in it. In an array context returns an array of strings, each an HTML token.
Take a list of HTML tokens and write the HTML text to sink (a cs::Sink), nicely indented if doindent = 1. If omitted, doindent defaults to 0.
If tag is one of the special ones we don't indent, return 0. Otherwise, return currentindent.
Convert a character entity name entity (as is found inside &entity; in HTML text) or number (of the form #n) into the corresponding character. Returns the character, of the entity name unchanged if unrecognised.
Convert plaintext to HTML, converting special characters like < into character entities. Also recognised is nroff-style bold and underline (cBSc and _<BS>c respectively).
Replace saces with +. Replace special characters with %xx escapes. Used to massage a string for use with a GET HTML query.
OBSOLETE. Emit HTML text for an <A HREF= anchor.
Convert text into HTML text in a heuristic fashion, recognising markup and URLs. Hoped to be handy for mail/news->HTML conversion.
Emit HTML text with a <A HREF=news:message-id anchor.
Walk the tokens, handing each to the subroutine editsub for manipulation.
Seach the tokens, returning an array of items matching grep. grep is either a subroutine expecting a token as argument or a string naming a tag to match.
Return an array of HTML tokens with the white space in string replaced with .
UNIMPLEMENTED: if the optional flag keepWide is supplied, uses as many s as spaces in the original text, otherwise uses just one between words.
OBSOLETE. Return all the URls referenced by HREF= attributes from the string.
Attach to the cs::Source object source, ready to return HTML tokens via the Tok method, below.
Call new cs::Source SourceType,SourceArgs... to open a cs::Source object and attach, ready to return HTML tokens via the Tok method, below.
Fetch the next HTML token from the source.
close is an optional hashref whose keys name tags which imply a close of an active (``open'') tag (for example, an opening <TR> tag implicitly closes any active <TD> tag).
pertok is an optional subroutine to manipulate a tag before it is returned from Tok. It takes the token as argument.
Tok returns completed tags, with nested structure embedded in the TOKENS field of the returned token. Per-markup element parsing should use the cs::SGML module, on which cs::HTML is built.
cs::HTML::Form(3), cs::CGI(3), cs::SGML(3), cs::Sink(3), cs::Source(3), cs::Tokenise(3)
Cameron Simpson <cs@zip.com.au>