My title & stuff

package FU::XMLWriter 1.3; use v5.36; use Carp 'confess'; use Exporter 'import'; our $XSPRINT; BEGIN { require FU::XS unless $XSPRINT } my @NORMAL_TAGS = qw/ a_ abbr_ address_ article_ aside_ audio_ b_ bb_ bdo_ blockquote_ body_ button_ canvas_ caption_ cite_ code_ colgroup_ datagrid_ datalist_ dd_ del_ details_ dfn_ dialog_ div_ dl_ dt_ em_ fieldset_ figure_ footer_ form_ h1_ h2_ h3_ h4_ h5_ h6_ head_ header_ i_ iframe_ ins_ kbd_ label_ legend_ li_ main_ map_ mark_ menu_ meter_ nav_ noscript_ object_ ol_ optgroup_ option_ output_ p_ pre_ progress_ q_ rp_ rt_ ruby_ samp_ script_ section_ select_ small_ span_ strong_ style_ sub_ summary_ sup_ table_ tbody_ td_ textarea_ tfoot_ th_ thead_ time_ title_ tr_ ul_ var_ video_ /; my @SELFCLOSE_TAGS = qw/ area_ base_ br_ col_ command_ embed_ hr_ img_ input_ link_ meta_ param_ source_ /; # Used by FU.xs to generate an XS function for each tag. # (Wrapping tag_() within Perl is slow, using ALIAS is possible but still benefits from code gen) if ($XSPRINT) { sub f($name, $selfclose) { my $tag = $name =~ s/_$//r; my $len = length $tag; printf <<~_; void $name(...) CODE: if (!fuxmlwr_tail) fu_confess("No active FU::XMLWriter instance"); fuxmlwr_tag(aTHX_ fuxmlwr_tail, ax, 0, items, $selfclose, "$tag", $len); _ } f $_, 0 for @NORMAL_TAGS; f $_, 1 for @SELFCLOSE_TAGS; } our %EXPORT_TAGS = ( html5_ => [ qw/tag_ html_ lit_ txt_/, @NORMAL_TAGS, @SELFCLOSE_TAGS ], xml_ => [ qw/xml_ tag_ lit_ txt_/ ], ); our @EXPORT_OK = ( qw/fragment xml_ xml_escape/, @{$EXPORT_TAGS{html5_}}, ); my %XML = qw/& & < < " "/; sub xml_escape($s) { return '' if !defined $s; $s =~ s/([&<"])/$XML{$1}/gr; } sub fragment :prototype(&) ($f) { my $wr = _new(); $f->(); $wr->_done; } sub html_(@arg) { fragment { lit_("\n"); tag_('html', @arg); } } sub xml_ :prototype(&) ($f) { fragment { lit_(qq{\n}); $f->(); } } 1; __END__ =head1 NAME FU::XMLWriter - Convenient and efficient XML and HTML generator. =head1 SYNOPSIS use FU::XMLWriter ':html5_'; my $html_string = html_ sub { head_ sub { title_ 'Document title!'; }; body_ sub { h1_ 'Main title!'; p_ class => 'description', sub { txt_ 'Here we have data.'; br_; a_ href => '/path', 'And a link.'; }; }; }; # Or XML: use FU::XMLWriter ':xml_'; my $xml_string = xml_ sub { tag_ feed => xmlns => 'http://www.w3.org/2005/Atom', 'xml:lang' => 'en', 'xml:base' => 'https://mywebsite/atom.feed', sub { tag_ title => 'My awesome Atom feed'; # etc }; }; =head1 DESCRIPTION This is a convenient XML writer that provides an imperative API to generating dynamic XML. It just so happens that XML syntax is also completely valid for HTML5, so this module is primarily abused for that purpose. As a naming convention, all XML/HTML output functions are suffixed with an underscore (C<_>) to make their functionality easy to identify and avoid potential naming collisions. You are encouraged to follow this convention in your own code. For example, if you have a function to convert some data into a nicely formatted table, you could name it C or something. It's like having composable custom HTML elements, but in the backend! Generating HTML is something that website backends tend to do a I, but calling tons of Perl functions is generally not very fast. For that reason, this is an XS module implemented in C. It compares favorably against a few other XML writing modules on CPAN that I tried, but whether this approach is faster than typical templating solutions... I've no idea. Check out L for some benchmarks. =head1 Top-level functions These functions all return a byte string with (UTF-8) encoded XML. =over =item fragment($block) Executes C<$block> and captures the output of all L called within the same scope into a string. This function can be safely nested: my $string = fragment { p_ 'Stuff here'; my $subfragment = fragment { div_ 'More stuff here'; }; # $subfragment = '

More stuff here

' }; # $string = '

Stuff here

' =item xml_($block) Like C but adds a C<< >> declaration. =item html_(@args) Like C but adds a suitable DOCTYPE of HTML5. The C<@args> are passed to the C call for the top-level C<< >> element. =back =head1 Output functions =over =item tag_($name, @attrs, $content) This is the meat of this module. Output an XML element with the given C<$name>. C<$content> can either be C to create a self-closing tag: tag_ 'br', undef; #
Or a string: tag_ 'title', 'My title & stuff'; # My title & stuff Or a subroutine: tag_ 'div', sub { tag_ 'br', undef; }; #

Attributes can be given as key/value pairs: tag_ 'a', href => '/?f&c', title => 'Homepage', 'link'; # link An C value causes the attribute to be ignored: tag_ 'option', selected => time % 2 == 0 ? 'selected' : undef, ''; # Depending on the time: # # Or # A C<'+'> attribute name can be used to append a string to the previously given attribute: tag_ 'div', class => $is_hidden ? 'hidden' : undef, '+' => $is_warning ? 'warning' : undef, 'Text'; # Results in either: #

Text

# #

Text

# =item txt_($string) Takes a Unicode string and outputs it, escaping any special XML characters in the process. =item lit_($string) Takes a Unicode string and outputs it literally, i.e. without any XML escaping. =item _(@attrs, $content) This module provides a short-hand function for every HTML5 tag. Using these is less typing and also slightly more performant than calling C. The following C-like wrapper functions are provided: a_ abbr_ address_ article_ aside_ audio_ b_ bb_ bdo_ blockquote_ body_ button_ canvas_ caption_ cite_ code_ colgroup_ datagrid_ datalist_ dd_ del_ details_ dfn_ dialog_ div_ dl_ dt_ em_ fieldset_ figure_ footer_ form_ h1_ h2_ h3_ h4_ h5_ h6_ head_ header_ i_ iframe_ ins_ kbd_ label_ legend_ li_ main_ map_ mark_ menu_ meter_ nav_ noscript_ object_ ol_ optgroup_ option_ output_ p_ pre_ progress_ q_ rp_ rt_ ruby_ samp_ script_ section_ select_ small_ span_ strong_ style_ sub_ summary_ sup_ table_ tbody_ td_ textarea_ tfoot_ th_ thead_ time_ title_ tr_ ul_ var_ video_ Additionally, the following self-closing-tag functions are provided: area_ base_ br_ col_ command_ embed_ hr_ img_ input_ link_ meta_ param_ source_ The self-closing functions do not require a C<$content> argument; if none is provided it defaults to C. =back =head1 Utility function =over =item xml_escape($string) Return the XML-escaped version of C<$string>. The characters C<&>, C>, and C<"> are replaced with their XML entity. =back =head1 Import options All of the functions mentioned in this document can be imported individually. There are also two import groups: use FU::XMLWriter ':html5_'; Exports C, C, C, C and all of the C<< _ >> functions mentioned above. use FU::XMLWriter ':xml_'; Exports C, C, C and C. =head1 SEE ALSO This module is part of the L framework, although it can be used independently of it. This module was based on L, which was in turn inspired by L, which is more powerful but less convenient. There's also L, a slightly more featureful, heavyweight and opinionated HTML-templating-inside-Perl module, based on L. And there's L, which is conceptually simpler than both this and L, but its syntax isn't quite as nice. And there's also L, L, L and many more modules on CPAN. In fact I don't know why you should use this module instead of whatever is available on CPAN. =head1 COPYRIGHT MIT. =head1 AUTHOR Yorhel