A recent question from my friend and colleague Mohammad got me thinking about the way we identify data in web applications.

While working on the DBIC component of a REST API, he came across the term enumeration attack. In this type of attack, an attacker systematically guesses resource identifiers in order to access data they shouldn’t be able to see.

For example, if your API exposes URLs like this:

GET /users/123
GET /users/124
GET /users/125

then it’s easy for someone to try a large range of identifiers and see what they get back.

Mohammad’s question was simple:

Should we replace sequential IDs with UUIDs? And if we do, should we index the UUID column?

As is often the case, the answer turned out to be “it depends”.

Two Different Types of Data

The first thing I realised is that not all data objects have the same requirements.

Some objects are naturally public.

For example, books on a publishing website are intended to be discovered. In fact, you probably want people to be able to guess their URLs:

/books/design-patterns-in-modern-perl

In this case, a human-readable slug makes perfect sense. Other objects are private by nature. User accounts, orders, invoices and API resources generally shouldn’t be enumerable. In those cases, a UUID is often a better choice:

/users/550e8400-e29b-41d4-a716-446655440000

The important observation is that slugs and UUIDs solve different problems.

• Slugs are for humans (and, perhaps, search engines).
• UUIDs are for machines.

Database Design

A common question is whether a UUID should replace the primary key.

In most cases, I don’t think it should.

My preferred design is:

CREATE TABLE users (
  id BIGINT PRIMARY KEY,
  uuid UUID NOT NULL UNIQUE
);

The integer primary key remains the internal identifier used for joins and foreign keys.

The UUID becomes the public identifier exposed through APIs.

This gives you the best of both worlds:

• Small, efficient foreign keys.
• Fast joins.
• Unguessable public identifiers.

If the application regularly searches by UUID then the UUID column should be indexed. In practice, declaring it UNIQUE will usually create the appropriate index automatically.

The Hybrid Approach

Thinking about this reminded me that many large sites use a hybrid approach.

Amazon product URLs contain both a human-readable title and a stable identifier:

/Design-Patterns-Modern-Perl/dp/B0XXXXX123

The ASIN is what really identifies the product.

The title is there for humans.

Stack Overflow does something similar:

/questions/12345/how-do-i-index-a-uuid-column

Again, the question ID is authoritative. The title is helpful context.

My Line of Succession website uses the same idea.

A person page looks like this:

/p/2b5998-the-prince-william-prince-of-wales

The important part is the identifier:

2b5998

The rest is descriptive text.

This turns out to be particularly useful for royalty because titles change constantly. Someone might be “Prince William”, then “The Prince of Wales”, and eventually “King William V”.

By separating identity from presentation, old links continue to work regardless of title changes.

A Tiny Bug

While thinking about all of this, I discovered a small bug in Line of Succession.

The site allows any descriptive text after the identifier. These URLs all resolve to the same person:

/p/2b5998-the-prince-william-prince-of-wales
/p/2b5998-prince-billy
/p/2b5998-fred

The application correctly ignores the descriptive text and uses only the identifier.

However, there was a problem.

The page was generating its canonical URL from the incoming request path rather than from the person record.

That meant a request for:

/p/2b5998-prince-billy

generated:

<link rel="canonical"
      href="https://lineofsuccession.co.uk/p/2b5998-prince-billy">

which is obviously not the canonical URL.

The fix was surprisingly small:

sub canonical( $self ) {
   if ($self->request->is_date_page) {
     return '/' . $self->canonical_date;
+  } elsif($self->request->is_person_page) {
+    return '/p/' . $self->request->person->slug;
   } else {
     return $self->request->path;
   }
 }

At the same time I simplified another method by making it reuse the canonical URL logic.

The result was a six-line patch that fixed the SEO issue and made the code slightly cleaner.

Those are my favourite kinds of fixes.

Future Improvements

The fix also revealed an emerging abstraction in the code.

At the moment, various parts of the application know how to construct URLs for different object types.

A cleaner approach would be to give objects responsibility for generating their own URLs.

I’m considering a HasURL role that would require an object to provide an identifier and optionally a prefix, and then build the URL automatically.

That’s a job for another day.

For now, a small question about UUIDs led to a useful discussion about public identifiers, a review of URL design, and a tiny production fix. Not bad for an afternoon’s work.

The post Public Identifiers, UUIDs and a Tiny SEO Fix first appeared on Perl Hacks.

If you’ve spent any time around AI tooling recently, you’ve probably seen people talking about MCP. It’s often described as “USB for AI”, which is perhaps a little overblown, but the basic idea is sound. MCP provides a standard way for AI assistants to discover and use external tools and data sources.

In practical terms, it means that instead of building bespoke integrations for ChatGPT, Claude, Gemini and whatever comes next, you expose a standard MCP endpoint and let the AI clients do the rest.

For a data-driven site like Line of Succession, that seemed like an obvious experiment.

What is MCP?

The Model Context Protocol was originally developed by Anthropic and has rapidly become one of the emerging standards in the AI ecosystem.

An MCP server exposes:

• Information about itself
• A list of available tools
• Schemas describing how those tools should be called
• The results returned by those tools

An AI client can connect to the server, discover the available tools and invoke them when needed.

Instead of scraping web pages or attempting to infer information from HTML, the AI gets access to structured data.

That’s exactly the kind of thing Line of Succession is good at.

Why Add MCP?

The site already exposes information through a traditional web interface and a JSON API.

But those interfaces were designed for humans and developers respectively.

MCP gives AI systems a much cleaner integration point.

For example, an AI assistant can now answer questions like:

• Who was the British sovereign on 14 November 1948?
• What did the line of succession look like in 1980?
• Who was next in line when Queen Victoria died?

without having to scrape pages or understand the site’s internal URLs.

More importantly, it ensures that the information comes directly from the same database that powers the website.

The AI isn’t guessing.

It’s querying the source of truth.

As someone who runs a reference website, that’s a pretty attractive proposition.

The Initial Design

My first goal was to keep things simple.

Rather than exposing dozens of narrowly-focused tools, I started with just two:

• sovereign_on_date
• line_of_succession

Those two tools cover a surprisingly large proportion of the questions people are likely to ask.

The first returns the sovereign reigning on a given date. The second returns the line of succession for a specified date, with a configurable limit on the number of entries returned.

The implementation currently caps the list at thirty people. That’s enough for most use cases while preventing someone from accidentally asking for all six thousand people currently in the line of succession.

One thing I learned quite quickly is that MCP isn’t really about exposing huge amounts of data. It’s about exposing useful questions that can be answered from your data.

MCP Is Mostly JSON-RPC

One thing that surprised me when I first started reading the specification was how little protocol code is actually required.

At its core, MCP uses JSON-RPC.

A client sends requests like:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

and the server responds with:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    ...
  }
}

Once I’d written helper methods for creating standard JSON-RPC responses, most of the complexity disappeared.

The MCP module contains methods like:

sub rpc_result ($self, $id, $result)

and:

sub rpc_error ($self, $id, $code, $message)

which means the Dancer route handlers remain pleasantly small.

The protocol logic lives in one place and the web application simply delegates to it.

Separating the MCP Logic

I didn’t want protocol-specific code scattered throughout the web application.

Instead, I created a dedicated module:

package Succession::MCP;

This module is responsible for:

• Initialisation
• Tool discovery
• Tool execution
• JSON-RPC response generation
• Error handling

That keeps the Dancer routes thin and makes the MCP implementation easier to test independently.

It also means that if I ever decide to expose the same MCP server through a different transport mechanism, most of the work is already done.

Tool Calls Are Mostly Adapters

One pleasant surprise was how little new application logic I actually had to write.

The MCP server needs to expose tools, but those tools ultimately just answer questions about the succession database. The code to answer those questions already existed.

For example, the application’s model layer already contained methods such as:

• sovereign_on_date()
• line_of_succession()

These methods power parts of the website itself, so they already encapsulate all of the business rules and database queries.

The MCP implementation simply acts as an adapter.

When a tool call arrives, the server extracts the arguments, validates them and passes them to the existing model methods:

sub _call_tool ($self, $tool_name, $args) {
  my $tool = $self->_tool_dispatch->{$tool_name};

  return $tool->($args);
}

The tool implementations themselves are deliberately thin:

sub sovereign_on_date ($self, $args) {
  my $date = $args->{date};

  my $sovereign = $self->model->sovereign_on_date($date);

  ...

}

That’s exactly how I wanted it to work.

The MCP layer doesn’t know how to calculate a line of succession or determine who was sovereign on a particular date. It simply knows how to expose those capabilities through the protocol.

This is one of the advantages of adding MCP to an existing application. If your business logic is already cleanly separated from your web interface, an MCP server often becomes surprisingly straightforward to implement.

In many ways, adding MCP feels less like building a new application and more like adding another interface alongside the website and API.

The YAML Epiphany

The most interesting design decision came a little later.

Initially, the tool definitions lived in Perl data structures.

That worked, but it quickly became obvious that I was duplicating information.

The MCP server needed tool descriptions.

The documentation page needed tool descriptions.

The schemas needed to be defined somewhere.

And every change required updating multiple places.

The obvious answer was to move all of the tool definitions into a YAML file.

The MCP module now loads its tool definitions at startup:

sub _build__tools ($self) { return LoadFile($self->tools_file); }

The result is a single source of truth.

The same YAML file drives:

• The tools/list response
• Tool metadata
• JSON schemas
• Human-readable documentation

Adding a new tool now involves updating one file and writing the code that implements it.

Everything else follows automatically.

Here’s the current YAML file:

# data/mcp-tools.yml

- name: sovereign_on_date
  description: Return the British sovereign on a given date.
  documentation: |
    Looks up the reigning British sovereign for the supplied date.

    Use this when answering questions such as “Who was sovereign on
    6 February 1952?”
  inputSchema:
    type: object
    properties:
      date:
        type: string
        description: Date in YYYY-MM-DD format.
    required:
      - date

- name: line_of_succession
  description: Return the line of succession on a given date.
  documentation: |
    Returns people in the line of succession.

    If no date is supplied, the current line of succession is returned.
  inputSchema:
    type: object
    properties:
      date:
        type: string
        description: Optional date in YYYY-MM-DD format. Omit for the current line of succession.
      limit:
        type: integer
        description: Maximum number of successors to return.
        minimum: 1
        maximum: 100
      required: []

Looking back, this is probably the part of the design I’m happiest with. It feels very Perl-ish: keep configuration as data and avoid duplicating information wherever possible.

Human Documentation Matters

One thing I noticed while exploring other MCP servers is that many of them are effectively invisible to humans.

You know an endpoint exists.

You know it speaks MCP.

But unless you inspect the protocol responses manually, you don’t really know what it does.

I decided to add a conventional web page at /mcp.

The page lists all available tools, their descriptions and their schemas.

The nice part is that there is no duplicated documentation.

The page is generated from the same YAML definitions used by the MCP server itself.

If I add a new tool tomorrow, both the machine-readable and human-readable views update automatically.

Structured Data and Text Responses

Another nice feature of MCP is that tool results can include both structured data and human-readable text.

For example, a tool response might contain:

{
  "content": [ {
    "type": "text",
    "text": "The sovereign on 14 November 1948 was George VI."
    } ],
  "structuredContent": {
    ...
  }
}

The structured content is useful for software.

The text is useful for humans and language models.

Both are generated from the same underlying data.

That gives AI clients flexibility while ensuring consistency.

Getting Listed

Once everything was working, I submitted the server to the MCP directory at mcpservers.org.

That might seem like a small step, but discoverability is important.

An MCP server hidden on a random website isn’t much use if nobody knows it exists.

Directories like that are rapidly becoming the equivalent of API catalogues for the AI era.

Being listed means developers and AI enthusiasts can find the service without first discovering the website.

Was It Worth It?

Absolutely.

The amount of code required was surprisingly small. Most of the work wasn’t implementing the protocol; it was deciding how best to expose the data.

More importantly, it opens the site up to an entirely new audience: AI agents.

Historically, websites were built for humans and APIs were built for developers.

MCP introduces a third category: services designed specifically for AI systems.

For a structured-data site like Line of Succession, that’s a natural fit.

Will MCP still be the dominant standard in five years’ time? I have no idea. The AI industry changes too quickly to make confident predictions.

But right now it has significant momentum, broad industry support and a growing ecosystem of tools.

And if nothing else, it’s rather satisfying to ask an AI who was on the throne on a particular date and know that the answer came directly from my database rather than from whatever the model happened to remember.

The post Teaching AI About the British Monarchy with MCP first appeared on Perl Hacks.

That sounds abstract, but it turns out to explain a huge amount of the progress we’ve made in software development over the last twenty-five years.

And nowhere is that clearer than in Perl web development.

Many of us who built web applications during the dotcom boom spent years learning this lesson the hard way.

We wrote CGI programs that:

• parsed HTTP requests
• generated HTML by hand
• connected directly to databases
• embedded SQL inline
• mixed business logic with presentation
• relied on Apache behaviour
• assumed specific filesystem layouts
• and often only worked on one particular server configuration

It all worked. Until it didn’t.

The history of Perl web development is, in many ways, the history of gradually moving implementation details into more appropriate architectural layers.

The Early CGI Years

Early Perl CGI applications were often a single giant script.

You’d open a file and see:

• request handling
• authentication
• HTML generation
• SQL queries
• business logic
• configuration
• deployment assumptions

…all mixed together in a glorious ball of mud.

Something like this:

#!/usr/bin/perl

use CGI;
use DBI;

my $cgi = CGI->new;

print $cgi->header;
print "<html><body>";

my $dbh = DBI->connect(
  "dbi:mysql:test",
  "user",
  "pass"
);

my $sth = $dbh->prepare(
  "select * from users where id = ?"
);

$sth->execute($cgi->param('id'));

while (my $row = $sth->fetchrow_hashref) {
  print "<h1>$row->{name}</h1>";
}

print "</body></html>";

And to be fair, it was a huge step forward from static HTML sites.

But the design had a fundamental problem:

Everything knew too much about everything else.

The application logic knew:

• how HTTP worked
• how HTML worked
• how Apache launched CGI scripts
• how the database worked
• how the operating system was configured

Every concern leaked into every other concern.

That made systems:

• hard to test
• hard to reuse
• hard to deploy
• hard to scale
• and terrifying to change

The First Big Lesson: Put Logic in Libraries

One of the first signs of a developer maturing is the realisation that application logic should live in reusable modules, not in front-end scripts.

Instead of this:

if ($user->{status} eq 'gold') {
  $discount = 0.2;
}

my $discount = $user->discount_rate;

Now the business logic lives in a library.

And once that happens, several good things follow automatically.

Multiple Interfaces Become Possible

If the logic is in modules, then:

• a web front-end
• a CLI tool
• a REST API
• a cron job
• a queue worker

…can all use the same underlying code.

The interface layer becomes thin.

The application itself becomes independent of how users interact with it.

That’s a huge increase in flexibility.

Testing Becomes Easier

Testing CGI scripts was always awkward.

Testing modules is straightforward.

You can instantiate objects, call methods, and inspect results without needing a web server or HTTP requests.

The easier code is to test, the more likely it is to be tested.

And tested code tends to survive longer.

Deployment Becomes Safer

Once the core behaviour is isolated from the interface layer, replacing the interface becomes far less risky.

You can redesign the UI without rewriting the application.

That separation is one of the foundations of maintainable software.

The PSGI Revolution

The next big architectural leap in Perl web development came with PSGI and Plack.

Younger developers may not fully appreciate how painful web deployment used to be.

In the early 2000s, moving an application between hosting environments could require substantial rewrites.

• A CGI application worked one way.
• A mod_perl application worked another way.
• FastCGI had its own quirks.
• Embedded Apache handlers behaved differently again.

Many Perl developers spent years repeatedly rewriting applications simply because deployment environments changed.

That was madness.

The deployment model is an operational concern.

It should not affect application architecture.

PSGI fixed this by defining a standard interface between web applications and web servers.

The core idea was beautifully simple:

A web application is just a function that receives an environment and returns a response.

Once that abstraction existed, applications no longer cared whether they were running:

• as CGI
• under mod_perl
• inside FastCGI
• under Starman
• behind nginx
• on a development laptop
• or inside a cloud container

The deployment details moved down a layer.

Exactly where they belonged.

This was one of the most important architectural improvements Perl web development ever made.

And it reflected a broader truth:

Good abstractions stop lower-level implementation details leaking upward.

The Transitional Era: FatPacker and cpanfile

There was also an interesting intermediate stage between traditional Perl deployments and full containerisation.

For years, one of the hardest parts of deploying Perl applications was dependency management.

You’d move an application to a new server and discover:

• the wrong module version
• missing XS libraries
• incompatible Perl versions
• or an entire dependency tree that worked perfectly on the developer’s machine and nowhere else

Large parts of Perl deployment culture evolved around coping with this problem.

Tools like cpanfile improved things by making dependencies explicit and reproducible.

Instead of vaguely documenting requirements in a README, applications could formally declare:

requires 'Dancer2';
requires 'DBIx::Class';
requires 'Template';

Then tools like App::FatPacker went even further by packaging dependencies directly alongside applications.

Instead of relying on the target server’s Perl environment, applications could carry much of their runtime context with them.

These tools didn’t completely solve deployment portability:

• system libraries still mattered
• Perl versions still mattered
• operating system differences still mattered

…but they represented an important shift in thinking.

The industry was gradually realising that:

• deployment environments were part of the application
• reproducibility mattered
• and infrastructure assumptions needed to be controlled

Containers eventually pushed this idea to its logical conclusion by packaging not just Perl dependencies, but the entire runtime environment.

In hindsight, tools like cpanfile and FatPacker were stepping stones toward modern container-based deployment models.

Containers Are the Same Idea Again

Docker and containers are simply the same architectural principle repeated one layer lower.

Before containers, deployments were often fragile and highly environment-specific.

Applications depended on:

• particular Linux distributions
• specific Perl versions
• installed system libraries
• hand-configured servers
• undocumented setup steps

Developers became experts in “works on my machine”.

Operations teams became experts in swearing.

Containers changed the model.

Instead of deploying:

• source code

…you deploy:

• a complete runtime environment

Now the application no longer cares whether it runs:

• on bare metal
• on a VPS
• in Kubernetes
• in ECS
• in Cloud Run
• or on someone’s laptop

Again:

• infrastructure concerns move downward
• application concerns stay upward

The boundaries become cleaner.

The Pattern Repeats Everywhere

Once you notice this pattern, you see it throughout software engineering.

Templates

Template systems separate:

• presentation

from

• application logic

HTML should not contain database code.

Business logic should not contain giant blobs of HTML.

ORMs and Database Layers

DBI separates applications from database engines.

ORMs separate applications from raw SQL structure.

Again:

• implementation details move downward

Configuration

Configuration belongs outside code.

Deployment-specific values should not be embedded in applications.

APIs

Clients should not care whether data comes from:

• PostgreSQL
• Redis
• another service
• a queue
• flat files
• or magic elves

That’s the implementation’s problem.

The Goal Is Not Abstraction for Its Own Sake

Of course, experienced developers also know that abstractions can become ridiculous.

Some abstractions simplify systems.

Others merely hide complexity behind six additional layers of YAML.

Joel Spolsky’s “Law of Leaky Abstractions” remains painfully relevant.

The goal is not abstraction itself.

The goal is to isolate genuinely volatile details.

Good abstractions protect systems from change.

Bad abstractions merely obscure reality.

The Real Skill

The deeper lesson here is that software architecture is largely about deciding:

“What belongs where?”

Experienced developers develop an instinct for:

• which details are likely to change
• which layers should know about which concerns
• and where boundaries should exist

That instinct is often more important than language choice, frameworks, or technology stacks.

And if you spent the early 2000s rewriting CGI applications to run under mod_perl, you probably learned that lesson the hard way.

The post The Long Road from CGI to Containers first appeared on Perl Hacks.

Because, as I’m sure you’ve noticed, it’s very easy to forget.

So this month, I decided to automate it.

(And, if you’re interested in the end result, this is also a good excuse to mention that the newsletter exists. Two birds, one stone.)

The Problem

All of my Git repositories live somewhere under /home/dave/git. Over time, that’s become… less organised than it might be. Some repos are directly under that directory, others are buried a couple of levels down, and I’m fairly sure there are a few I’ve completely forgotten about.

What I wanted was:

• Given a month and a year
• Find all Git repositories under that directory
• Identify which ones had commits in that month
• Summarise the work done in each repo

The first three are straightforward enough. The last one is where things get interesting.

Finding the Repositories

The first step is walking the directory tree and finding .git directories. This is a classic Perl task — File::Find still does exactly what you need.

use v5.40;
use File::Find;

sub find_repos ($root) {
  my @repos;

  find(
    sub {
      return unless $_ eq '.git';
      push @repos, $File::Find::dir;
    },
    $root
  );

  return @repos;
}

(There are, of course, other ways to do this — you could shell out to fd or find, for example — but keeping it in Perl keeps everything nicely self-contained.)

Getting Commits for a Month

For each repo, we can run git log with appropriate date filters.

sub commits_for_month ($repo, $since, $until) {
  my $cmd = sprintf(
    q{git -C %s log --since="%s" --until="%s" --pretty=format:"%%s"},
    $repo, $since, $until
  );

  my @commits = `$cmd`;
  chomp @commits;

  return @commits;
}

my $since = "$year-$month-01";
my $until = "$year-$month-31"; # good enough for this purpose

A Small Gotcha

It turns out I have a few repositories where I never got around to making a first commit. In that case, git log helpfully explodes with:

The fix is simply to ignore failures:

my @commits = `$cmd 2>/dev/null`;

This is one of those little bits of defensive programming that makes the difference between a script you run once and a script you’re happy to run every month.

Summarising the Work

Once we have a list of commit messages, we can summarise them.

And this is where I cheated slightly.

I used OpenAPI::Client::OpenAI to feed the commit messages into an LLM and ask it to produce a short summary.

Something along these lines:

use OpenAPI::Client::OpenAI;

sub summarise_commits ($commits) {
  my $client = OpenAPI::Client::OpenAI->new(
    api_key => $ENV{OPENAI_API_KEY},
  );

  my $text = join "\n", @$commits;

  my $response = $client->chat->completions->create({
    model => 'gpt-4.1-mini',
    messages => [{
      role => 'user',
      content => "Summarise the following commit messages:\n\n$text",
    }],
  });

  return $response->choices->[0]->message->content;
}

Could I have written some heuristics to group and summarise commit messages? Possibly.

Would it have been as much fun? Definitely not.

And in practice, it works remarkably well. Even messy, inconsistent commit messages tend to turn into something that looks like a coherent summary of work.

Putting It Together

For each repo:

1. Get commits for the month
2. Skip if there are none
3. Generate a summary
4. Print the repo name and summary

The output looks something like:

my-project
-----------
Refactored database layer, added caching, and fixed several edge-case bugs.

another-project
---------------
Initial scaffolding, basic API endpoints, and deployment configuration.

A Nice Side Effect

One unexpected benefit of this approach is that it surfaces projects I’d forgotten about.

Because the script walks the entire directory tree, it finds everything — including half-finished experiments, abandoned ideas, and repos I created at 11pm and never touched again.

Sometimes that’s useful. Sometimes it’s mildly embarrassing.

But it’s always interesting.

What Next?

This is very much a first draft.

It works, but it’s currently a script glued together with shell commands and assumptions about my directory structure. The obvious next step is to:

• Turn it into a proper module
• Add tests
• Clean up the API
• Release it to CPAN

At that point, it becomes something other people might actually want to use — not just a personal tool with hard-coded paths and questionable date handling.

A Future Enhancement

One idea I particularly like is to run this automatically using GitHub Actions.

For example:

• Run monthly
• Generate summaries for that month
• Commit the results to a repository
• Publish them via GitHub Pages

Over time, that would build up a permanent, browsable record of what I’ve been working on.

It’s a nice combination of:

• automation
• documentation
• and a gentle nudge towards accountability

Which is either a fascinating historical archive…

…or a slightly alarming reminder of how many half-finished projects I have.

Closing Thoughts

This started as a small piece of automation to help me write a newsletter. But it’s turned into a nice example of what Perl is still very good at:

• Gluing systems together
• Wrapping command-line tools
• Handling messy real-world data
• Adding just enough intelligence to make the output useful

And, occasionally, outsourcing the hard thinking to a machine.

The code (such as it is currently is) is on GitHub at https://github.com/davorg/git-month-summary.

If you’re interested in the kind of projects this helps summarise, you can find my monthly newsletter over on Substack.

And if I get round to turning this into a CPAN module, I’ll let you know – well, if you’re subscribed to the newsletter!

The post Summarising a Month of Git Activity with Perl (and a Little Help from AI) first appeared on Perl Hacks.

So the obvious Perl question is: *“Ok, where’s the CPAN module?”*

This post explains what TOON is, why some people think it’s useful, and why I decided to write a Perl module for it — with an interface that should feel very familiar to anyone who has used JSON.pm.

I should point out that I knew about [Data::Toon](https://metacpan.org/pod/Data::TOON) but I wanted something with an interface that was more like JSON.pm.

—

## What TOON Is

TOON stands for **Token-Oriented Object Notation**. It’s a textual format for representing structured data — the same data model as JSON:

* Objects (hashes)
* Arrays
* Strings
* Numbers
* Booleans
* Null

The idea behind TOON is that it is designed to be **easy for both humans and language models to read and write**. It tries to reduce punctuation noise and make the structure of data clearer.

If you think of the landscape like this:

| Format | Human-friendly | Machine-friendly | Very common |
| —— | ————– | —————- | ———– |
| JSON | Medium | Very | Yes |
| YAML | High | Medium | Yes |
| TOON | High | High | Not yet |

TOON is trying to sit in the middle: simpler than YAML, more readable than JSON.

Whether it succeeds at that is a matter of taste — but it’s an interesting idea.

—

## TOON vs JSON vs YAML

It’s probably easiest to understand TOON by comparing it to JSON and YAML. Here’s the same “person” record written in all three formats.

### JSON

{
“name”: “Arthur Dent”,
“age”: 42,
“email”: “arthur@example.com”,
“alive”: true,
“address”: {
“street”: “High Street”,
“city”: “Guildford”
},
“phones”: [
“01234 567890”,
“07700 900123”
]
}

### YAML

name: Arthur Dent
age: 42
email: arthur@example.com
alive: true
address:
street: High Street
city: Guildford
phones:
– 01234 567890
– 07700 900123

### TOON

name: Arthur Dent
age: 42
email: arthur@example.com
alive: true
address:
street: High Street
city: Guildford
phones[2]: 01234 567890,07700 900123

You can see that TOON sits somewhere between JSON and YAML:

* Less punctuation and quoting than JSON
* More explicit structure than YAML
* Still very easy to parse
* Still clearly structured for machines

That’s the idea, anyway.

—

## Why People Think TOON Is Useful

The current interest in TOON is largely driven by AI/LLM workflows.

People are using it because:

1. It is easier for humans to read than JSON.
2. It is less ambiguous and complex than YAML.
3. It maps cleanly to the JSON data model.
4. It is relatively easy to parse.
5. It works well in prompts and generated output.

In other words, it’s not trying to replace JSON for APIs, and it’s not trying to replace YAML for configuration files. It’s aiming at the space where humans and machines are collaborating on structured data.

You may or may not buy that argument — but it’s an interesting niche.

—

## Why I Wrote a Perl Module

I don’t have particularly strong opinions about TOON as a format. It might take off, it might not. We’ve seen plenty of “next big data format” ideas over the years.

But what I *do* have a strong opinion about is this:

> If a data format exists, then Perl should have a CPAN module for it that works the way Perl programmers expect.

Perl already has very good, very consistent interfaces for data serialisation:

* JSON
* YAML
* Storable
* Sereal

They all tend to follow the same pattern, particularly the object-oriented interface:

use JSON;
my $json = JSON->new->pretty->canonical;
my $text = $json->encode($data);
my $data = $json->decode($text);

So I wanted a TOON module that worked the same way.

—

## Design Goals

When designing the module, I had a few simple goals.

### 1. Familiar OO Interface

The primary interface should be object-oriented and feel like JSON.pm:

use TOON;
my $toon = TOON->new
->pretty
->canonical
->indent(2);
my $text = $toon->encode($data);
my $data = $toon->decode($text);

If you already know JSON, you already know how to use TOON.

There are also convenience functions, but the OO interface is the main one.

### 2. Pure Perl Implementation

Version 0.001 is pure Perl. That means:

* Easy to install
* No compiler required
* Works everywhere Perl works

If TOON becomes popular and performance matters, someone can always write an XS backend later.

### 3. Clean Separation of Components

Internally, the module is split into:

* **Tokenizer** – turns text into tokens
* **Parser** – turns tokens into Perl data structures
* **Emitter** – turns Perl data structures into TOON text
* **Error handling** – reports line/column errors cleanly

This makes it easier to test and maintain.

### 4. Do the Simple Things Well First

Version 0.001 supports:

* Scalars
* Arrayrefs
* Hashrefs
* undef → null
* Pretty printing
* Canonical key ordering

It does **not** (yet) try to serialise blessed objects or do anything clever. That can come later if people actually want it.

—

## Example Usage (OO Style)

Here’s a simple Perl data structure:

my $data = {
name => “Arthur Dent”,
age => 42,
drinks => [ “tea”, “coffee” ],
alive => 1,
};

### Encoding

use TOON;
my $toon = TOON->new->pretty->canonical;
my $text = $toon->encode($data);
print $text;

### Decoding

use TOON;
my $toon = TOON->new;
my $data = $toon->decode($text);
print $data->{name};

### Convenience Functions

use TOON qw(encode_toon decode_toon);
my $text = encode_toon($data);
my $data = decode_toon($text);

But the OO interface is where most of the flexibility lives.

—

## Command Line Tool

There’s also a command-line tool, toon_pp, similar to json_pp:

cat data.toon | toon_pp

Which will pretty-print TOON data.

—

## Final Thoughts

I don’t know whether TOON will become widely used. Predicting the success of data formats is a fool’s game. But the cost of supporting it in Perl is low, and the potential usefulness is high enough to make it worth doing.

And fundamentally, this is how CPAN has always worked:

> See a problem. Write a module. Upload it. See if anyone else finds it useful.

So now Perl has a TOON module. And if you already know how to use JSON.pm, you already know how to use it.

That was the goal.

The post Writing a TOON Module for Perl first appeared on Perl Hacks.

I still think that’s true.

But every now and then, the bleading edge reminds you why it’s called that.

Recently, I lost a couple of days to a bug that turned out not to be in my code, not in the module I was installing, and not even in the module that module depended on — but in the installer’s understanding of modern Perl syntax.

This is the story.

The Symptom

I was building a Docker image for Aphra. As part of the build, I needed to install App::HTTPThis, which depends on Plack::App::DirectoryIndex, which depends on WebServer::DirIndex.

The Docker build failed with this error:

#13 45.66 --> Working on WebServer::DirIndex
#13 45.66 Fetching https://www.cpan.org/authors/id/D/DA/DAVECROSS/WebServer-DirIndex-0.1.3.tar.gz ... OK
#13 45.83 Configuring WebServer-DirIndex-v0.1.3 ... OK
#13 46.21 Building WebServer-DirIndex-v0.1.3 ... OK
#13 46.75 Successfully installed WebServer-DirIndex-v0.1.3
#13 46.84 ! Installing the dependencies failed: Installed version (undef) of WebServer::DirIndex is not in range 'v0.1.0'
#13 46.84 ! Bailing out the installation for Plack-App-DirectoryIndex-v0.2.1.

Now, that’s a deeply confusing error message.

It clearly says that WebServer::DirIndex was successfully installed. And then immediately says that the installed version is undef and not in the required range.

At this point you start wondering if you’ve somehow broken version numbering, or if there’s a packaging error, or if the dependency chain is wrong.

But the version number in WebServer::DirIndex was fine. The module built. The tests passed. Everything looked normal.

So why did the installer think the version was undef?

When This Bug Appears

This only shows up in a fairly specific situation:

• A module uses modern Perl class syntax
• The module defines a $VERSION
• Another module declares a prerequisite with a specific version requirement
• The installer tries to check the installed version without loading the module
• It uses Module::Metadata to extract $VERSION
• And the version of Module::Metadata it is using doesn’t properly understand class

If you don’t specify a version requirement, you’ll probably never see this. Which is why I hadn’t seen it before. I don’t often pin minimum versions of my own modules, but in this case, the modules are more tightly coupled than I’d like, and specific versions are required.

So this bug only appears when you combine:

modern Perl syntax + version checks + older toolchain

Which is pretty much the definition of “bleading edge”.

The Real Culprit

The problem turned out to be an older version of Module::Metadata that had been fatpacked into cpanm.

cpanm uses Module::Metadata to inspect modules and extract $VERSION without loading the module. But the older Module::Metadata didn’t correctly understand the class keyword, so it couldn’t work out which package the $VERSION belonged to.

So when it checked the installed version, it found… nothing.

Hence:

Installed version (undef) of WebServer::DirIndex is not in range ‘v0.1.0’

The version wasn’t wrong. The installer just couldn’t see it.

An aside, you may find it amusing to hear an anecdote from my attempts to debug this problem.

I spun up a new Ubuntu Docker container, installed cpanm and tried to install Plack::App::DirectoryIndex. Initially, this gave the same error message. At least the problem was easily reproducible.

I then ran code that was very similar to the code cpanm uses to work out what a module’s version is.

$ perl -MModule::Metadata -E'say Module::Metadata->new_from_module("WebServer::DirIndex")->version'

This displayed an empty string. I was really onto something here. Module::Metadata couldn’t find the version.

I was using Module::Metadata version 1.000037 and, looking at the change log on CPAN, I saw this:

1.000038 2023-04-28 11:25:40Z

- detects "class" syntax

$ perl -MModule::Metadata -E'say Module::Metadata->new_from_module("WebServer::DirIndex")->version'
0.1.3

The Workaround

I found a workaround. That was to add a redundant package declaration alongside the class declaration, so older versions of Module::Metadata can still identify the package that owns $VERSION.

So instead of just this:

class WebServer::DirIndex {
  our $VERSION = '0.1.3';
  ...
}

package WebServer::DirIndex;

class WebServer::DirIndex {
  our $VERSION = '0.1.3';
  ...
}

But it allows older tooling to work out the version correctly, and everything installs cleanly again.

The Proper Fix

Of course, the real fix was to update the toolchain.

So I raised an issue against App::cpanminus, pointing out that the fatpacked Module::Metadata was too old to cope properly with modules that use class.

Tatsuhiko Miyagawa responded very quickly, and a new release of cpanm appeared with an updated version of Module::Metadata.

This is one of the nice things about the Perl ecosystem. Sometimes you report a problem and the right person fixes it almost immediately.

When Do I Remove the Workaround?

This leaves me with an interesting question.

The correct fix is “use a recent cpanm”.

But the workaround is “add a redundant package line so older tooling doesn’t get confused”.

So when do I remove the workaround?

The answer is probably: not yet.

Because although a fixed cpanm exists, that doesn’t mean everyone is using it. Old Docker base images, CI environments, bootstrap scripts, and long-lived servers can all have surprisingly ancient versions of cpanm lurking in them.

And the workaround is harmless. It just offends my sense of neatness slightly.

So for now, the redundant package line stays. Not because modern Perl needs it, but because parts of the world around modern Perl are still catching up.

Life on the Bleading Edge

This is what life on the bleading edge actually looks like.

Not dramatic crashes. Not language bugs. Not catastrophic failures.

Just a tool, somewhere in the install chain, that looks at perfectly valid modern Perl code and quietly decides that your module doesn’t have a version number.

And then you lose two days proving that you are not, in fact, going mad.

But I’m still using class. And I’m still happy I am.

You just have to keep an eye on the whole toolchain — not just the language — when you decide to live a little closer to the future than everyone else.

The post Still on the [b]leading edge first appeared on Perl Hacks.

It isn’t.

Or rather, that’s not all it is.

The interesting thing — the thing that genuinely changes how you work — is that you can assign GitHub issues to Copilot.

And it behaves like a contributor.

Over the past day, I’ve been doing exactly that on my new CPAN module, WebServer::DirIndex. I’ve opened issues, assigned them to Copilot, and watched a steady stream of pull requests land. Ten issues closed in about a day, each one implemented via a Copilot-generated PR, reviewed and merged like any other contribution.

That still feels faintly futuristic. But it’s not “vibe coding”. It’s surprisingly structured.

Let me explain how it works.

It Starts With a Proper Issue

This workflow depends on discipline. You don’t type “please refactor this” into a chat window. You create a proper GitHub issue. The sort you would assign to another human maintainer. For example, here are some of the recent issues Copilot handled in WebServer::DirIndex:

• Add CPAN scaffolding
• Update the classes to use Feature::Compat::Class
• Replace DirHandle
• Add WebServer::DirIndex::File
• Move render() method
• Use :reader attribute where useful
• Remove dependency on Plack

Each one was a focused, bounded piece of work. Each one had clear expectations.

The key is this: Copilot works best when you behave like a maintainer, not a magician.

You describe the change precisely. You state constraints. You mention compatibility requirements. You indicate whether tests need to be updated.

Then you assign the issue to Copilot.

And wait.

The Pull Request Arrives

After a few minutes — sometimes ten, sometimes less — Copilot creates a branch and opens a pull request.

The PR contains:

• Code changes
• Updated or new tests
• A descriptive PR message

And because it’s a real PR, your CI runs automatically. The code is evaluated in the same way as any other contribution.

This is already a major improvement over editor-based prompting. The work is isolated, reviewable, and properly versioned.

But the most interesting part is what happens in the background.

Watching Copilot Think

If you visit the Agents tab in the repository, you can see Copilot reasoning through the issue.

It reads like a junior developer narrating their approach:

• Interpreting the problem
• Identifying the relevant files
• Planning changes
• Considering test updates
• Running validation steps

And you can interrupt it.

If it starts drifting toward unnecessary abstraction or broad refactoring, you can comment and steer it:

• Please don’t change the public API.
• Avoid experimental Perl features.
• This must remain compatible with Perl 5.40.

It responds. It adjusts course.

This ability to intervene mid-flight is one of the most useful aspects of the system. You are not passively accepting generated code — you’re supervising it.

Teaching Copilot About Your Project

Out of the box, Copilot doesn’t really know how your repository works. It sees code, but it doesn’t know policy.

That’s where repository-level configuration becomes useful.

1. Custom Repository Instructions

GitHub allows you to provide a .github/copilot-instructions.md file that gives Copilot repository-specific guidance. The documentation for this lives here:

• Adding repository custom instructions for GitHub Copilot

When GitHub offers to generate this file for you, say yes.

Then customise it properly.

In a CPAN module, I tend to include:

• Minimum supported Perl version
• Whether Feature::Compat::Class is preferred
• Whether experimental features are forbidden
• CPAN layout expectations (lib/, t/, etc.)
• Test conventions (Test::More, no stray diagnostics)
• A strong preference for not breaking the public API

Without this file, Copilot guesses.

With this file, Copilot aligns itself with your house style.

That difference is impressive.

2. Customising the Copilot Development Environment

There’s another piece that many people miss: Copilot can run a special workflow event called copilot_agent_setup.

You can define a workflow that prepares the environment Copilot works in. GitHub documents this here:

• Customizing the development environment for GitHub Copilot coding agent

In my Perl projects, I use this standard setup:

name: Copilot Setup Steps

on:
  workflow_dispatch:
  push:
    paths:
      - .github/workflows/copilot-setup-steps.yml
  pull_request:
    paths:
      - .github/workflows/copilot-setup-steps.yml

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    permissions:
      contents: read
  steps:
    - name: Check out repository
      uses: actions/checkout@v4

    - name: Set up Perl 5.40
      uses: shogo82148/actions-setup-perl@v1
      with:
        perl-version: '5.40'

    - name: Install dependencies
      run: cpanm --installdeps --with-develop --notest .

Firstly, it ensures Copilot is working with the correct Perl version.

Secondly, it installs the distribution dependencies, meaning Copilot can reason in a context that actually resembles my real development environment.

Without this workflow, Copilot operates in a kind of generic space.

With it, Copilot behaves like a contributor who has actually checked out your code and run cpanm.

That’s a useful difference.

Reviewing the Work

This is the part where it’s important not to get starry-eyed.

I still review the PR carefully.

I still check:

• Has it changed behaviour unintentionally?
• Has it introduced unnecessary abstraction?
• Are the tests meaningful?
• Has it expanded scope beyond the issue?

I check out the branch and run the tests. Exactly as I would with a PR from a human co-worker.

You can request changes and reassign the PR to Copilot. It will revise its branch.

The loop is fast. Faster than traditional asynchronous code review.

But the responsibility is unchanged. You are still the maintainer.

Why This Feels Different

What’s happening here isn’t just “AI writing code”. It’s AI integrated into the contribution workflow:

• Issues
• Structured reasoning
• Pull requests
• CI
• Review cycles

That architecture matters.

It means you can use Copilot in a controlled, auditable way.

In my experience with WebServer::DirIndex, this model works particularly well for:

• Mechanical refactors
• Adding attributes (e.g. :reader where appropriate)
• Removing dependencies
• Moving methods cleanly
• Adding new internal classes

It is less strong when the issue itself is vague or architectural. Copilot cannot infer the intent you didn’t articulate.

But given a clear issue, it’s remarkably capable — even with modern Perl using tools like Feature::Compat::Class.

A Small but Important Point for the Perl Community

I’ve seen people saying that AI tools don’t handle Perl well. That has not been my experience.

With a properly described issue, repository instructions, and a defined development environment, Copilot works competently with:

• Modern Perl syntax
• CPAN distribution layouts
• Test suites
• Feature::Compat::Class (or whatever OO framework I’m using on a particular project)

The constraint isn’t the language. It’s how clearly you explain the task.

The Real Shift

The most interesting thing here isn’t that Copilot writes Perl. It’s that GitHub allows you to treat AI as a contributor.

• You file an issue.
• You assign it.
• You supervise its reasoning.
• You review its PR.

It’s not autocomplete. It’s not magic. It’s just another developer on the project. One who works quickly, doesn’t argue, and reads your documentation very carefully.

Have you been using AI tools to write or maintain Perl code? What successes (or failures!) have you had? Are there other tools I should be using?

Links

If you want to have a closer look at the issues and PRs I’m talking about, here are some links?

• WebServer::DirIndex repo
• Closed issues
• Closed PRs

The post Treating GitHub Copilot as a Contributor first appeared on Perl Hacks.

For that job, I’ve been using App::HTTPThis for years.

It’s a simple local web server you run from the command line. Point it at a directory, and it serves it. That’s it. No vhosts. No config bureaucracy. No “why is this module not enabled”. Just: run a command and you’ve got a website.

Why I’ve used it for years

Static sites are deceptively simple… right up until they aren’t.

• You want to check that relative links behave the way you think they do.

• You want to confirm your CSS and images are loading with the paths you expect.

• You want to reproduce “real HTTP” behaviour (caching headers, MIME types, directory handling) rather than viewing files directly from disk.

Sure, you can open file:///.../index.html in a browser, but that’s not the same thing as serving it over HTTP. And setting up Apache (or friends) feels like bringing a cement mixer to butter some toast.

With http_this, the workflow is basically:

• cd into your site directory

• run a single command

• open a URL

• get on with your life

It’s the “tiny screwdriver” that’s always on my desk.

Why I took it over

A couple of years ago, the original maintainer had (entirely reasonably!) become too busy elsewhere and the distribution wasn’t getting attention. That happens. Open source is like that.

But I was using App::HTTPThis regularly, and I had one small-but-annoying itch: when you visited a directory URL, it would always show a directory listing – even if that directory contained an index.html. So instead of behaving like a typical web server (serve index.html by default), it treated index.html as just another file you had to click.

That’s exactly the sort of thing you notice when you’re using a tool every day, and it was irritating enough that I volunteered to take over maintenance.

(If you want to read more on this story, I wrote a couple of blog posts.)

What I’ve done since taking it over

Most of the changes are about making the “serve a directory” experience smoother, without turning it into a kitchen-sink web server.

1) Serve index pages by default (autoindex)

The first change was to make directory URLs behave like you’d expect: if index.html exists, serve it automatically. If it doesn’t, you still get a directory listing.

2) Prettier index pages

Once autoindex was in place, I then turned my attention to the fallback directory listing page. If there isn’t an index.html, you still need a useful listing — but it doesn’t have to look like it fell out of 1998. So I cleaned up the listing output and made it a bit nicer to read when you do end up browsing raw directories.

3) A config file

Once you’ve used a tool for a while, you start to realise you run it the same way most of the time.

A config file lets you keep your common preferences in one place instead of re-typing options. It keeps the “one command” feel, but gives you repeatability when you want it.

4) --host option

The ability to control the host binding sounds like an edge case until it isn’t.

Sometimes you want:

• only localhost access for safety;

• access from other devices on your network (phone/tablet testing);

• behaviour that matches a particular environment.

A --host option gives you that control without adding complexity to the default case.

The Bonjour feature (and what it’s for)

This is the part I only really appreciated recently: App::HTTPThis can advertise itself on your local network using mDNS / DNS-SD – commonly called Bonjour on Apple platforms, Avahi on Linux, and various other names depending on who you’re talking to.

It’s switched on with the --name option.

When you do that, http_this publishes an _http._tcp service on your local network with the instance name you chose (MyService in this case). Any device on the same network that understands mDNS/DNS-SD can then discover it and resolve it to an address and port, without you having to tell anyone, “go to http://192.168.1.23:7007/”.

Confession time: I ignored this feature for ages because I’d mentally filed it under “Apple-only magic” (Bonjour! very shiny! probably proprietary!). It turns out it’s not Apple-only at all; it’s a set of standard networking technologies that are supported on pretty much everything, just under a frankly ridiculous number of different names. So: not Apple magic, just local-network service discovery with a branding problem.

Because I’d never really used it, I finally sat down and tested it properly after someone emailed me about it last week, and it worked nicely, nicely enough that I’ve now added a BONJOUR.md file to the repo with a practical explanation of what’s going on, how to enable it, and a few ways to browse/discover the advertised service.

(If you’re curious, look for _http._tcp and your chosen service name.)

It’s a neat quality-of-life feature if you’re doing cross-device testing or helping someone else on the same network reach what you’re running.

Related tools in the same family

App::HTTPThis is part of a little ecosystem of “run a thing here quickly” command-line apps. If you like the shape of http_this, you might also want to look at these siblings:

• https_this : like http_this, but served over HTTPS (useful when you need to test secure contexts, service workers, APIs that require HTTPS, etc.)

• cgi_this : for quick CGI-style testing without setting up a full web server stack

• dav_this : serves content over WebDAV (handy for testing clients or workflows that expect DAV)

• ftp_this : quick FTP server for those rare-but-real moments when you need one

They all share the same basic philosophy: remove the friction between “I have a directory” and “I want to interact with it like a service”.

Wrapping up

I like tools that do one job, do it well, and get out of the way. App::HTTPThis has been that tool for me for years and it’s been fun (and useful) to nudge it forward as a maintainer.

If you’re doing any kind of static site work — docs sites, little prototypes, generated output, local previews — it’s worth keeping in your toolbox.

And if you’ve got ideas, bug reports, or platform notes (especially around Bonjour/Avahi weirdness), I’m always happy to hear them.

The post App::HTTPThis: the tiny web server I keep reaching for first appeared on Perl Hacks.

It’s been a while since we last released a new title, and in the meantime, the world of eBooks has moved on – Amazon don’t use .mobi any more, tools have changed, and my old “it mostly works if you squint” build pipeline was starting to creak.

On top of that, we had a hard deadline: we wanted the book ready in time for the London Perl Workshop. As the date loomed, last-minute fixes and manual tweaks became more and more terrifying. We really needed a reliable, reproducible way to go from manuscript to “good quality PDF + EPUB” every time.

So over the last couple of weeks, I’ve been rebuilding the Perl School book pipeline from the ground up. This post is the story of that process, the tools I ended up using, and how you can steal it for your own books.

The old world, and why it wasn’t good enough

The original Perl School pipeline dates back to a very different era:

• Amazon wanted .mobi files.

• EPUB support was patchy.

• I was happy to glue things together with shell scripts and hope for the best.

It worked… until it didn’t. Each book had slightly different scripts, slightly different assumptions, and a slightly different set of last-minute manual tweaks. It certainly wasn’t something I’d hand to a new author and say, “trust this”.

Coming back to it for Design Patterns in Modern Perl made that painfully obvious. The book itself is modern and well-structured; the pipeline that produced it shouldn’t feel like a relic.

Choosing tools: Pandoc and wkhtmltopdf (and no LaTeX, thanks)

The new pipeline is built around two main tools:

• Pandoc – the Swiss Army knife of document conversion. It can take Markdown/Markua plus metadata and produce HTML, EPUB, and much, much more.

• wkhtmltopdf – which turns HTML into a print-ready PDF using a headless browser engine.

Why not LaTeX? Because I’m allergic. LaTeX is enormously powerful, but every time I’ve tried to use it seriously, I end up debugging page breaks in a language I don’t enjoy. HTML + CSS I can live with; browsers I can reason about. So the PDF route is:

• Markdown → HTML (via Pandoc) → PDF (via wkhtmltopdf)

And the EPUB route is:

• Markdown → EPUB (via Pandoc) → validated with epubcheck

The front matter (cover page, title page, copyright, etc.) is generated with Template Toolkit from a simple book-metadata.yml file, and then stitched together with the chapters to produce a nice, consistent book.

That got us a long way… but then a reader found a bug.

The iBooks bug report

Shortly after publication, I got an email from a reader who’d bought the Leanpub EPUB and was reading it in Apple Books (iBooks). Instead of happily flipping through Design Patterns in Modern Perl, they were greeted with a big pink error box.

Apple’s error message boiled down to:

There’s something wrong with the XHTML in this EPUB.

That was slightly worrying. But, hey, every day is a learning opportunity. And, after a bit of digging, this is what I found out.

EPUB 3 files are essentially a ZIP containing:

• XHTML content files

• a bit of XML metadata

• CSS, images, and so on

Apple Books is quite strict about the “X” in XHTML: it expects well-formed XML, not just “kind of valid HTML”. So when working with EPUB, you need to forget all of that nice HTML5 flexibility that you’ve got used to over the last decade or so.

The first job was to see if we could reproduce the error and work out where it was coming from.

Discovering epubcheck

Enter epubcheck.

epubcheck is the reference validator for EPUB files. Point it at an .epub and it will unpack it, parse all the XML/XHTML, check the metadata and manifest, and tell you exactly what’s wrong.

Running it on the book immediately produced this:

Fatal Error while parsing file: The element type br must be terminated by the matching end-tag </br>.

That’s the XML parser’s way of saying:

• In HTML, <br> is fine.

• In XHTML (which is XML), you must use <br /> (self-closing) or <br></br>.

And there were a number of these scattered across a few chapters.

In other words: perfectly reasonable raw HTML in the manuscript had been passed straight through by Pandoc into the EPUB, but that HTML was not strictly valid XHTML, so Apple Books rejected it. I should note at this point that the documentation for Pandoc’s EPUB creation explicitly says that it won’t touch HTML fragments it finds in a Markdown file when converting it to EPUB. It’s down to the author to ensure they’re using valid XHTML

A quick (but not scalable) fix

Under time pressure, the quickest way to confirm the diagnosis was:

1. Unzip the generated EPUB.

2. Open the offending XHTML file.

3. Manually turn <br> into <br /> in a couple of places.

4. Re-zip the EPUB.

5. Run epubcheck again.

6. Try it in Apple Books.

That worked. The errors vanished, epubcheck was happy, and the reader confirmed that the fixed file opened fine in iBooks.

But clearly:

Open the EPUB in a text editor and fix the XHTML by hand

is not a sustainable publishing strategy.

So the next step was to move from “hacky manual fix” to “the pipeline prevents this from happening again”.

HTML vs XHTML, and why linters matter

The underlying issue is straightforward once you remember it:

• HTML is very forgiving. Browsers will happily fix up all kinds of broken markup.

• XHTML is XML, so it’s not forgiving:

  • empty elements must be self-closed (<br />, <img />, <hr />, etc.),

  • tags must be properly nested and balanced,

  • attributes must be quoted.

EPUB 3 content files are XHTML. If you feed them sloppy HTML, some readers (like Apple Books) will just refuse to load the chapter.

So I added a manuscript HTML linter to the toolchain, before we ever get to Pandoc or epubcheck.

Roughly, the linter:

• Reads the manuscript (ignoring fenced code blocks so it doesn’t complain about < in Perl examples).

• Extracts any raw HTML chunks.

• Wraps those chunks in a temporary root element.

• Uses XML::LibXML to check they’re well-formed XML.

• Reports any errors with file and line number.

It’s not trying to be a full HTML validator; it’s just checking: “If this HTML ends up in an EPUB, will the XML parser choke?”

That would have caught the <br> problem before the book ever left my machine.

Hardening the pipeline: epubcheck in the loop

The linter catches the obvious issues in the manuscript; epubcheck is still the final authority on the finished EPUB.

So the pipeline now looks like this:

1. Lint the manuscript HTML
   Catch broken raw HTML/XHTML before conversion.

2. Build PDF + EPUB via make_book

   • Generate front matter from metadata (cover, title pages, copyright).

   • Turn Markdown + front matter into HTML.

   • Use wkhtmltopdf for a print-ready PDF.

   • Use Pandoc for the EPUB.

3. Run epubcheck on the EPUB
   Ensure the final file is standards-compliant.

4. Only then do we upload it to Leanpub and Amazon, making it available to eager readers.

The nice side-effect of this is that any future changes (new CSS, new template, different metadata) still go through the same gauntlet. If something breaks, the pipeline shouts at me long before a reader has to.

Docker and GitHub Actions: making it reproducible

Having a nice Perl script and a list of tools installed on my laptop is fine for a solo project; it’s not great if:

• other authors might want to build their own drafts, or

• I want the build to happen automatically in CI.

So the next step was to package everything into a Docker image and wire it into GitHub Actions.

The Docker image is based on a slim Ubuntu and includes:

• Perl + cpanm + all CPAN modules from the repo’s cpanfile

• pandoc

• wkhtmltopdf

• Java + epubcheck

• The Perl School utility scripts themselves (make_book, check_ms_html, etc.)

The workflow in a book repo is simple:

• Mount the book’s Git repo into /work.

• Run check_ms_html to lint the manuscript.

• Run make_book to build built/*.pdf and built/*.epub.

• Run epubcheck on the EPUB.

• Upload the built/ artefacts.

GitHub Actions then uses that same image as a container for the job, so every push or pull request can build the book in a clean, consistent environment, without needing each author to install Pandoc, wkhtmltopdf, Java, and a large chunk of CPAN locally.

Why I’m making this public

At this point, the pipeline feels:

• modern (Pandoc, HTML/CSS layout, EPUB 3),

• robust (lint + epubcheck),

• reproducible (Docker + Actions),

• and not tied to Perl in any deep way.

Yes, Design Patterns in Modern Perl is a Perl book, and the utilities live under the “Perl School” banner, but nothing is stopping you from using the same setup for your own book on whatever topic you care about.

So I’ve made the utilities available in a public repository (the perlschool-util repo on GitHub). There you’ll find:

• the build scripts,

• the Dockerfile and helper script,

• example GitHub Actions configuration,

• and notes on how to structure a book repo.

If you’ve ever thought:

I’d like to write a small technical book, but I don’t want to fight with LaTeX or invent a build system from scratch…

then you’re very much the person I had in mind.

eBook publishing really is pretty easy once you’ve got a solid pipeline. If these tools help you get your ideas out into the world, that’s a win.

And, of course, if you’d like to write a book for Perl School, I’m still very interested in talking to potential authors – especially if you’re doing interesting modern Perl in the real world.

The post Behind the scenes at Perl School Publishing first appeared on Perl Hacks.

This reflexive aversion isn’t just a preference. It’s what I call Dotcom Survivor Syndrome: a long-standing bias formed by the messy, experimental, high-pressure environment of the early web, where Perl was both a lifeline and a liability.

Perl wasn’t the problem. The conditions under which we used it were. And unfortunately, those conditions, combined with a separate, prolonged misstep over versioning, continue to distort Perl’s reputation to this day.

The Glory Days: Perl at the Heart of the Early Web

In the mid- to late-1990s, Perl was the web’s duct tape.

• It powered CGI scripts on Apache servers.

• It automated deployments before DevOps had a name.

• It parsed logs, scraped data, processed form input, and glued together whatever needed glueing.

Perl 5, released in 1994, introduced real structure: references, modules, and the birth of CPAN, which became one of the most effective software ecosystems in the world.

Perl wasn’t just part of the early web—it was instrumental in creating it.

The Dotcom Boom: Shipping Fast and Breaking Everything

To understand the long shadow Perl casts, you have to understand the speed and pressure of the dot-com boom.

We weren’t just building websites.
We were inventing how to build websites.

Best practices? Mostly unwritten.
Frameworks? Few existed.
Code reviews? Uncommon.
Continuous integration? Still a dream.

The pace was frantic. You built something overnight, demoed it in the morning, and deployed it that afternoon. And Perl let you do that.

But that same flexibility—its greatest strength—became its greatest weakness in that environment. With deadlines looming and scalability an afterthought, we ended up with:

• Thousands of lines of unstructured CGI scripts

• Minimal documentation

• Global variables everywhere

• Inline HTML mixed with business logic

• Security holes you could drive a truck through

When the crash came, these codebases didn’t age gracefully. The people who inherited them, often the same people who now run engineering orgs, remember Perl not as a powerful tool, but as the source of late-night chaos and technical debt.

Dotcom Survivor Syndrome: Bias with a Backstory

Many senior engineers today carry these memories with them. They associate Perl with:

• Fragile legacy systems

• Inconsistent, “write-only” code

• The bad old days of early web development

And that’s understandable. But it also creates a bias—often unconscious—that prevents Perl from getting a fair hearing in modern development discussions.

Version Number Paralysis: The Perl 6 Effect

If Dotcom Boom Survivor Syndrome created the emotional case against Perl, then Perl 6 created the optical one.

In 2000, Perl 6 was announced as a ground-up redesign of the language. It promised modern syntax, new paradigms, and a bright future. But it didn’t ship—not for a very long time.

In the meantime:

• Perl 5 continued to evolve quietly, but with the implied expectation that it would eventually be replaced.

• Years turned into decades, and confusion set in. Was Perl 5 deprecated? Was Perl 6 compatible? What was the future of Perl?

To outsiders—and even many Perl users—it looked like the language was stalled. Perl 5 releases were labelled 5.8, 5.10, 5.12… but never 6. Perl 6 finally emerged in 2015, but as an entirely different language, not a successor.

Eventually, the community admitted what everyone already knew: Perl 6 wasn’t Perl. In 2019, it was renamed Raku.

But the damage was done. For nearly two decades, the version number “6” hung over Perl 5 like a storm cloud – a constant reminder that its future was uncertain, even when that wasn’t true.

This is what I call Version Number Paralysis:

• A stalled major version that made the language look obsolete.

• A missed opportunity to signal continued relevance and evolution.

• A marketing failure that deepened the sense that Perl was a thing of the past.

Even today, many developers believe Perl is “stuck at version 5,” unaware that modern Perl is actively maintained, well-supported, and quite capable.

While Dotcom Survivor Syndrome left many people with an aversion to Perl, Version Number Paralysis gave them an excuse not to look closely at Perl to see if it had changed.

What They Missed While Looking Away

While the world was confused or looking elsewhere, Perl 5 gained:

• Modern object systems (Moo, Moose)

• A mature testing culture (Test::More, Test2)

• Widespread use of best practices (Perl::Critic, perltidy, etc.)

• Core team stability and annual releases

• Huge CPAN growth and refinements

But those who weren’t paying attention, especially those still carrying dotcom-era baggage, never saw it. They still think Perl looks like it did in 2002.

Can We Move On?

Dotcom Survivor Syndrome is real. So is Version Number Paralysis. Together, they’ve unfairly buried a language that remains fast, expressive, and battle-tested.

We can’t change the past. But we can:

• Acknowledge the emotional and historical baggage

• Celebrate the role Perl played in inventing the modern web

• Educate developers about what Perl really is today

• Push back against the assumption that old == obsolete

Conclusion

Perl’s early success was its own undoing. It became the default tool for the first web boom, and in doing so, it took the brunt of that era’s chaos. Then, just as it began to mature, its versioning story confused the industry into thinking it had stalled.

But the truth is that modern Perl is thriving quietly in the margins – maintained by a loyal community, used in production, and capable of great things.

The only thing holding it back is a generation of developers still haunted by memories of CGI scripts, and a version number that suggested a future that never came.

Maybe it’s time we looked again.

The post Dotcom Survivor Syndrome – How Perl’s Early Success Created the Seeds of Its Downfall first appeared on Perl Hacks.