Swim(3)

💅 Swim(3) — the manual, but make it make sense ✨

ok so real talk: this page comes from the User Contributed Perl Documentation crew 🫶 and it's all about Swim, the markup language that's lowkey a whole vibe. Also heads up: the original page has a <<<cpan-head>>> marker sitting right up top and a <<<cpan-tail>>> marker way down at the bottom — those are just the CPAN injection spots, not part of the actual docs, iykyk 🎀

---

✨ SYNOPSIS ✨

Bestie, here's the whole energy in two lines:

> swim --to=pod doc/MyModule.swim > MyModule.pod

my $pod = Swim->new(file => "doc/MyModule.swim")->to_pod;

That's it. Command line or Perl one-liner, your choice, both iconic 👑

---

🌸 DESCRIPTION 🌸

Swim is a plain text markup language that converts to so many formats, it's genuinely not fair to the other markups. The full roster:

• HTML
  • Rich — Lots of classes and annotations
  • Sparse — Just the tags and content
  • Custom — HTML the way you want it
• MarkDown
  • GitHub Flavored Markdown
• Pod
• Formatted Plain Text
• LaTeX
• DocBook
• Manpage
• AsciiDoc
• MediaWiki

And the Swim framework is easily extensible, so adding new outputs is easy. No cap, you can just... add one. Slay 💅

💖 What Makes Swim Different 💖

Okay so the world already has a LOT of text-to-html languages. Why should you care about Swim? Let me count the ways:

• Very rich capabilities:

Swim is aiming to be a feature superset of the other markups, since it converts to all of them. Which is a flex.

Most of the other markups don't support things like multiple paragraphs in a bullet point — like, hi, you are literally reading one right now 😭

• Simple, consistent markup:

Even though Swim intends to be very rich, it will use a simple set of syntax idioms to accomplish its tasks. One of the author's favorite sayings comes from Larry Wall of Perl fame: "Make simple things simple and hard things possible". Swim does just that (hopefully without looking too much like Perl ;).

• Extensible:

Swim is easy to extend at many levels. You can add new backend formats. You can also define your own markup syntaxes. You can even define sections that parse using a different syntax grammar. For instance, you could inline a markdown section like this:

<<< markdown
This is [Markdown](http://daringfireball.net/projects/markdown/) text.
>>>

Obsessed with that tbh.

• Multiple Implementations:

Swim is written using the Pegex parser framework. This provides 2 very powerful concepts. Firstly, that Swim language is defined in a very simple PEG topdown grammar. That means it is easy to grok, maintain and extend. Second, Pegex parsers work in many languages. That means that you can use Pegex natively in languages like Ruby, JavaScript, Perl, Python and many others. Main character energy across the whole ecosystem fr fr.

• Comments and blank lines:

Most markups don't support comments and they just eat extra blank lines. These things are useful! Swim not only supports comments, they are part of the data model. ie They get rendered as HTML (or comments in other target languages that support comments). Swim also supports throwaway comments, for times when you want to hide part of a document 🙈

🦋 Syntax Concepts 🦋

Before we dive into the actual markup syntax, let's discuss the concepts that drive the decisions that Swim makes. Sit down, this part is important.

Most documents are just plain language using letters and numbers and a few punctuation chars like comma, dash, apostrophe, parentheses and colon. Also endings: period, exclamation point and question mark. We leave those alone (at least in the normal prose context). Not everything needs to be a ✨moment✨.

This leaves a bunch of punctuation characters that we can do special things with. Namely: @#$%^&*_=+|/~[]<>{}. Sometimes context matters. For instance it is very rare for a prose line to start with a period, so we can use that as a markup.

The important thing in all this is that we be able to reverse the meaning for edge cases. ie We need a way to make markup characters be viewed as regular characters. Swim uses a backslash before a character to make it not be seen as markup. For instance this text *not bold* is not bold because it was written like this: \*not bold\*. The escape hatch is right there, bestie 💅

Swim has a document model that views things as blocks and phrases. This is very similar to HTML's DIV and SPAN concepts. Swim views a document as a sequence of top level blocks. Blocks are further subdivided into either a sequence of blocks or a sequence of phrases. Phrases can only be subdivided into more phrases. It's giving nesting doll, but make it markup 🪆

Consider this example document:

A paragraph *is* a block. It gets divided into phrases like 'pure text' and
*bold text*. A bold phrase can be divided: *all bold /some italic/*.

* Lists are blocks.
* Each item is a block.
  * A sublist is a block.
  * The text within in contains *phrases*.

Common blocks and phrases have an implicit (DWIM) syntax, that reads very natural. For instance a paragraph is just left justified text that is terminated by a blank line. There is also an explicit syntax for blocks and phrases. Every implicit syntax can be written explicitly. For instance, here is an implicit syntax example followed by its explicit equivalent:

A paragraph with some *bold text* in it.

<<< para
A paragraph with some <bold bold text> in it.
>>>

Same thing, two fits. Pick your fighter 🫶

🎀 Two Space Indent 🎀

Swim uses a 2 space indentation and it is very instrumental to its design. It allows for a very nice and natural embedding of blocks within blocks. Consider this list:

* Point one has
  text on 2 lines
  * Subpoint a
* Point two

  A paragraph for point 2 followed by some preformatted text:
    # Code example
* Point three

As you can see, 2 space indent is very natural here and allows for putting blocks inside blocks in a way that is not available in most markups. It's genuinely so clean, I'm not okay 😭✨

👑 Swim Syntax 👑

There are 4 sets of syntax to define: block/implicit, phrase/implicit, block/explicit and phrase/explicit. There are also escaping mechanisms. Four sets, no more, no less. Periodt.

💜 Block/Implicit Syntaxes 💜

A paragraph is a contiguous set of plain text lines. It is terminated by a blank line or by another block syntax at that level.

To be continued

---

aaaand that's the page, bestie 💖 that <<<cpan-tail>>> marker at the bottom is just where CPAN stuff gets injected, so don't stress about it.

Sign-off time: this was perl v5.42.0, dated 2025-07-25, filed under Swim(3). Go write something cute in Swim 🦋💅