Before any code gets written, I'd like to hash out the interface for HTML::Tagset 5.00+. Following is my proposal and I welcome your feedback. Some points may run counter to prior things I've said. This is what I think makes most sense right now, and after seeing the discussion we've been having the past few weeks.
Guiding principles
- Upgrading to HTML::Tagset 5.00 will not break existing code.
use HTML::Tagset;
must give you HTML4 data, in existing hash format.
- If you want to have HTML5 support, you must:
- Install HTML::Tagset 5.00 or higher.
- Change your
use
statement: use HTML::Tagset 'v5'
- Add new hashes with more consistent naming, and in some cases, easier and more consistent data layout.
- Add subs to provide an easier interface to the hashes.
- Add ability to export subs and hashes.
- Encourage people to use new subs and hashes.
- We only support HTML4 or HTML5 at one time. You cannot do
use HTML::Tagset ( 'v4', 'v5' );
.
Existing HTML4 support
Existing code that uses HTML::Tagset without parameters will behave identically. You will get the same hashes you always have.
use HTML::Tagset;
my $is_head = $HTML::Tagset::isHeadElement{ $tag };
# Specifying 'v4' is identical.
use HTML::Tagset 'v4';
my $is_head = $HTML::Tagset::isHeadElement{ $tag };
You will also be able to use newly-named hashes and subs. All new names will be lowercase-and-underscores, and begin with tag_
.
my $is_head = $HTML::Tagset::tag_is_head_element{ $tag };
my $is_head = HTML::Tagset::tag_is_head_element( $tag );
The newly-named hashes are NOT necessarily identical to the old hashes.
For example, the existing %linkElements
looks like this:
our %linkElements = ( 'a' => ['href'], 'applet' => ['archive', 'codebase', 'code'] ... );
The newly-named hash %tag_is_link_attribute
's values will be hashrefs. Same data, different layout.
our %tag_is_link_attribute = ( a => { href => 1 }, applet => { archive => 1, codebase => 1, code => 1 }, ... );
The new hashes will be easier to use.
# The old way.
my $linkElements = %HTML::Tagset::linkElements{ $tag };
if ( $linkElements ) {
my %h = map { $_ => 1 } @{$linkElements};
$is_link_attribute = $h{ $attr };
}
# The new way
my $is_link_attribute = $HTML::Tagset::tag_is_link_attribute{ $tag }{ $attr };
my $is_link_attribute = HTML::Tagset::tag_is_link_attribute( $tag, $attr );
HTML5 support
You can specify 'v5' to get HTML5-based data.
use HTML::Tagset 'v5';
# Same as 'v4' but with v5 hashes and subs.
my $is_head = $HTML::Tagset::isHeadElement{ $tag };
my $is_head = $HTML::Tagset::tag_is_head_element{ $tag };
my $is_head = HTML::Tagset::tag_is_head_element( $tag );
You will also be able to export hashes and subs.
use HTML::Tagset qw( v4 :hashes );
use HTML::Tagset qw( v4 :subs );
use HTML::Tagset qw( v5 :all );
my $is_head = tag_is_head( $tag );
If you export, you MUST pass a version. You may not pass multiple versions.
use HTML::Tagset qw( :all ); # Fails, no version
use HTML::Tagset qw( v4 v5 ); # Fails, too many versions
Disallow use of HTML::Tagset::* namespace
There will be no way to support both v4 and v5 at the same time.
Behind the scenes, the HTML::Tagset hashes and subs will probably be aliases to their ::v4 or ::v5 counterparts. I don't think we want to support people referring to the version-specific namespaces directly. They are only there for ease of development.
# YES
use HTML::Tagset 'v5';
my $is_head = HTML::Tagset::tag_is_head_element( $tag );
my $is_head = tag_is_head_element( $tag );
# NO, not guaranteed to be supported in the future.
my $is_head = HTML::Tagset::v5::tag_is_head_element( $tag );