ivan/site
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fixup

Browse Source
This commit is contained in:
rawley
2026-06-26 11:31:08 -06:00
parent 3382f6d33f
commit 4de7c25d59
1 changed files with 93 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

186
posts/html-composer.html
View File

@@ -1,37 +1,37 @@
<!DOCTYPE html> <!DOCTYPE html>
<html> <html>
<head> <head>
<title>HTML::Composer and Perl HTML templating</title> <title>HTML::Composer and Perl HTML templating</title>
<meta content="Description of post" name="description"> <meta content="Description of post" name="description">
<meta name="robots"> <meta name="robots">
<meta content="Awesome keywords" name="keywords"> <meta content="Awesome keywords" name="keywords">
<meta charset="utf-8" content="utf-8" name="charset"> <meta charset="utf-8" content="utf-8" name="charset">
<link href="/index.css" rel="stylesheet"> <link href="/index.css" rel="stylesheet">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1/styles/default.min.css"> <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1/styles/default.min.css">
</head> </head>
<body> <body>
<a href="/">&lt;&lt; back</a> <a href="/">&lt;&lt; back</a>
<h1>Perl HTML templating</h1> <h1>HTML::Composer and Perl HTML templating</h1>
<div><small>June 25th, 2026</small></div> <div><small>June 25th, 2026</small></div>
<p> <p>
Perl has some great templating libraries for HTML. Most of them are pretty fast, and do what you want. Perl has some great templating libraries for HTML. Most of them are pretty fast, and do what you want.
<a href="https://metacpan.org/pod/Template::Toolkit">Template::Toolkit</a> is sort of the "gold standard", and you see it most <a href="https://metacpan.org/pod/Template::Toolkit">Template::Toolkit</a> is sort of the "gold standard", and you see it most
often in the wild. <a href="https://metacpan.org/pod/Mojo::Template">Mojo::Template</a> is the "newer" kid on the block, and is most often in the wild. <a href="https://metacpan.org/pod/Mojo::Template">Mojo::Template</a> is the "newer" kid on the block, and is most
associated with the <a href="https://metacpan.org/pod/Mojolicious">Mojolicious</a> framework/toolkit, if you're writing a Mojolicious application associated with the <a href="https://metacpan.org/pod/Mojolicious">Mojolicious</a> framework/toolkit, if you're writing a Mojolicious application
you're likely using Mojo::Template. There are also a few niche templating tools, like <a href="https://metacpan.org/pod/Text::Xslate">Text::Xslate</a> (unfortunately, pretty much dead), and you're likely using Mojo::Template. There are also a few niche templating tools, like <a href="https://metacpan.org/pod/Text::Xslate">Text::Xslate</a> (unfortunately, pretty much dead), and
<a href="https://metacpan.org/pod/Template::Tiny">Template::Tiny</a> (supported, but not seen very often). Like I said earlier, all of these libraries are great, <a href="https://metacpan.org/pod/Template::Tiny">Template::Tiny</a> (supported, but not seen very often). Like I said earlier, all of these libraries are great,
you write templated text, and they give you HTML back, awesome. However, they all share a common "problem", they make me write HTML. I'm a Perl developer, you write templated text, and they give you HTML back, awesome. However, they all share a common "problem", they make me write HTML. I'm a Perl developer,
I like writing Perl, I want to write Perl, so when I have to switch contexts to HTML it annoys me. To compound this problem, I just got off a project that used a tool called I like writing Perl, I want to write Perl, so when I have to switch contexts to HTML it annoys me. To compound this problem, I just got off a project that used a tool called
<a href="https://github.com/weavejester/hiccup">hiccup</a>, hiccup let me write code in its native toungue (Clojure), and get back HTML in the form of a string. This rocked! <a href="https://github.com/weavejester/hiccup">hiccup</a>, hiccup let me write code in its native toungue (Clojure), and get back HTML in the form of a string. This rocked!
Not only did I not have to write HTML, it was actually <i>intuitive</i>, it provided me with a DSL for HTML. So I took this idea, and ported it to Perl, in the form of Not only did I not have to write HTML, it was actually <i>intuitive</i>, it provided me with a DSL for HTML. So I took this idea, and ported it to Perl, in the form of
<a href="https://metacpan.org/pod/HTML::Composer">HTML::Composer</a>. HTML::Composer is a library that does its best to emulate that sort of intuitiveness, inside of Perl. To my surprise <a href="https://metacpan.org/pod/HTML::Composer">HTML::Composer</a>. HTML::Composer is a library that does its best to emulate that sort of intuitiveness, inside of Perl. To my surprise
it seems to, and even more suprisingly, it performs incredibly well. it seems to, and even more suprisingly, it performs incredibly well.
</p> </p>
<h2>HTML::Composer</h2> <h2>HTML::Composer</h2>
<p> <p>
HTML::Composer only outputs HTML. It is a Perl data-structure to HTML converter, it takes an ARRAY ref, and outputs a string: HTML::Composer only outputs HTML. It is a Perl data-structure to HTML converter, it takes an ARRAY ref, and outputs a string:
</p> </p>
<pre><code class="language-perl"> <pre><code class="language-perl">
use HTML::Composer; use HTML::Composer;
my $h = HTML::Composer->new(); my $h = HTML::Composer->new();
@@ -53,11 +53,11 @@ my $html = $h->html([
] ]
); );
say $html; # &lt;!DOCTYPE html&gt;&lt;html&gt; ... say $html; # &lt;!DOCTYPE html&gt;&lt;html&gt; ...
</code></pre> </code></pre>
<p> <p>
You can also render partial HTML: You can also render partial HTML:
</p> </p>
<pre><code class="language-perl"> <pre><code class="language-perl">
my $h = HTML::Composer->new; my $h = HTML::Composer->new;
my $html = $h->partial([ my $html = $h->partial([
div => [ div => [
@@ -67,66 +67,66 @@ my $html = $h->partial([
]); ]);
say $html; # &lt;div&gt;Hello, World!&lt;a href="https://www.google.com"&lt; ... say $html; # &lt;div&gt;Hello, World!&lt;a href="https://www.google.com"&lt; ...
</code></pre> </code></pre>
<p> <p>
Since HTML::Composer operates inside of Perl data structures, and doesn't need to do any string parsing, it's quite fast. Faster than any other templating library outputting HTML I could find. Since HTML::Composer operates inside of Perl data structures, and doesn't need to do any string parsing, it's quite fast. Faster than any other templating library outputting HTML I could find.
The following benchmark is the average of five different one-hundred-million iteration runs rendering a medium sized HTML page that changed between iterations, The following benchmark is the average of five different one-hundred-million iteration runs rendering a medium sized HTML page that changed between iterations,
with the caveat being, each of these libraries was expected to take an input scalar and output to a scalar variable (Text::Xslate is optimized to read from a file not a string, so it hated this benchmark): with the caveat being, each of these libraries was expected to take an input scalar and output to a scalar variable (Text::Xslate is optimized to read from a file not a string, so it hated this benchmark):
</p> </p>
<pre><code> <pre><code>
Rate Text::Xslate Mojo::Template Template::Tiny Template::Toolkit HTML::Composer Rate Text::Xslate Mojo::Template Template::Tiny Template::Toolkit HTML::Composer
Text::Xslate 433/s -- -78% -93% -93% -94% Text::Xslate 433/s -- -78% -93% -93% -94%
Mojo::Template 1969/s 354% -- -69% -70% -72% Mojo::Template 1969/s 354% -- -69% -70% -72%
Template::Tiny 6410/s 1379% 226% -- -1% -9% Template::Tiny 6410/s 1379% 226% -- -1% -9%
Template::Toolkit 6494/s 1398% 230% 1% -- -8% Template::Toolkit 6494/s 1398% 230% 1% -- -8%
HTML::Composer 7042/s 1525% 258% 10% 8% -- HTML::Composer 7042/s 1525% 258% 10% 8% --
</code></pre> </code></pre>
<p> <p>
And, while being very quick, it also performs basic HTML validations to ensure you're sending something proper (it does not make sure the tags you pass are correct, this is very expensive). And, while being very quick, it also performs basic HTML validations to ensure you're sending something proper (it does not make sure the tags you pass are correct, this is very expensive).
Instead of spending time parsing and building the HTML tree, the developer has already done the work, so all we need to do is <i>compose</i> it to HTML. It also performs the necessary escapes by default, if you need to avoid escaping, Instead of spending time parsing and building the HTML tree, the developer has already done the work, so all we need to do is <i>compose</i> it to HTML. It also performs the necessary escapes by default, if you need to avoid escaping,
you can use the unsafe method <pre><code class="language-perl">[ div =&gt; $h->unsafe("Stuff that shouldn't be escaped!"); ]</code></pre> you can use the unsafe method <pre><code class="language-perl">[ div =&gt; $h->unsafe("Stuff that shouldn't be escaped!"); ]</code></pre>
</p> </p>
<h3>How it works</h3> <h3>How it works</h3>
<p> <p>
HTML::Composer uses a depth-first search, with a stack to traverse the HTML array you provide, HTML::Composer uses a depth-first search, with a stack to traverse the HTML array you provide,
based on the ordering of the data it makes assumptions about what you want, a string followed by a hash means you want to based on the ordering of the data it makes assumptions about what you want, a string followed by a hash means you want to
write a tag with some attributes, if that is then followed by an array, a tag with attributes and children. We verify if the tag write a tag with some attributes, if that is then followed by an array, a tag with attributes and children. We verify if the tag
is allowed to have children, then, we insert a reference to the current tag's scalar after the hash, and array. If a tag has no children, ie a tag with just is allowed to have children, then, we insert a reference to the current tag's scalar after the hash, and array. If a tag has no children, ie a tag with just
a hash following, then we can finish that tag right now by pushing the HTML string output to the output array. When we encounter an array, a hash following, then we can finish that tag right now by pushing the HTML string output to the output array. When we encounter an array,
simply push all of its elements onto the stack. Rinse and repeat until we encounter a scalar reference, and close the tag. simply push all of its elements onto the stack. Rinse and repeat until we encounter a scalar reference, and close the tag.
</p> </p>
<h3>Optimizations + learnings</h3> <h3>Optimizations + learnings</h3>
<p> <p>
I learned Perl string concatenation is really slow. In the first pass at this project I used a <pre><code class="language-perl">$root</code></pre> scalar to be the final output, I learned Perl string concatenation is really slow. In the first pass at this project I used a <pre><code class="language-perl">$root</code></pre> scalar to be the final output,
and concatenated the HTML in place, however after doing some r&d, I realised that pushing to an array, and then using Perl's <pre><code class="language-perl">join('', @array)</code></pre> and concatenated the HTML in place, however after doing some r&d, I realised that pushing to an array, and then using Perl's <pre><code class="language-perl">join('', @array)</code></pre>
function, was almost one order of magnitude faster. The reason this is faster, is Perl's <a href="https://github.com/Perl/perl5/blob/909c414e5450fe64ba145e6a3f3ed2e97999f060/doop.c#L666">do_join</a> function function, was almost one order of magnitude faster. The reason this is faster, is Perl's <a href="https://github.com/Perl/perl5/blob/909c414e5450fe64ba145e6a3f3ed2e97999f060/doop.c#L666">do_join</a> function
is highly optimized, and seems to allocate the size of string it thinks it needs ahead of time, which saves a lot of CPU time. is highly optimized, and seems to allocate the size of string it thinks it needs ahead of time, which saves a lot of CPU time.
</p> </p>
<p> <p>
The main logic tree uses ref and string eq's, I attempted to swap this to using regexp with a prefix <pre><code class="language-perl">ref($foo) =~ /^SC/ # SCALAR</code></pre>, this is typically how I've optimized The main logic tree uses ref and string eq's, I attempted to swap this to using regexp with a prefix <pre><code class="language-perl">ref($foo) =~ /^SC/ # SCALAR</code></pre>, this is typically how I've optimized
logic in C code in the past, though, instead of regexp its referencing the bytes directly, which in retrospect is obviously going to be much faster than this. logic in C code in the past, though, instead of regexp its referencing the bytes directly, which in retrospect is obviously going to be much faster than this.
However I did expect the prefix check with regexp to be at least slightly faster, but alas it's quite a bit slower. However I did expect the prefix check with regexp to be at least slightly faster, but alas it's quite a bit slower.
</p> </p>
<h2>Conclusion</h2> <h2>Conclusion</h2>
<p> <p>
Perl has great HTML templating libraries. I hate writing HTML so I wrote one that lets me stay in Perl, and export templates via sub-routines. Perl has great HTML templating libraries. I hate writing HTML so I wrote one that lets me stay in Perl, and export templates via sub-routines.
It performs really well, which is to be expected, as it does no parsing of any actual text. I hope someone else with similar pains will try it out at some point. It performs really well, which is to be expected, as it does no parsing of any actual text. I hope someone else with similar pains will try it out at some point.
Thanks for reading! Thanks for reading!
</p> </p>
<h4>Related links:</h4> <h4>Related links:</h4>
<ul> <ul>
<li> <li>
<a href="https://codeberg.org/rawleyfowler/perl-HTML-Composer">HTML::Composer source code</a> <a href="https://codeberg.org/rawleyfowler/perl-HTML-Composer">HTML::Composer source code</a>
</li> </li>
<li> <li>
<a href="https://metacpan.org/pod/HTML::Composer">HTML::Composer</a> <a href="https://metacpan.org/pod/HTML::Composer">HTML::Composer</a>
</li> </li>
</ul> </ul>
<p> <p>
Footnote: yes your eyes do not decieve you, that is codeberg, I'm going to be migrating my work off Github over the next couple weeks. Footnote: yes your eyes do not decieve you, that is codeberg, I'm going to be migrating my work off Github over the next couple weeks.
AI was not involved in this project at all. AI was not involved in this project at all.
</p> </p>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1/highlight.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1/highlight.min.js"></script>
<script>hljs.highlightAll();</script> <script>hljs.highlightAll();</script>
</body> </body>
</html> </html>