Welcome to Plot, a domain-specific language (DSL) for writing type-safe HTML, XML and RSS in Swift. It can be used to build websites, documents and feeds, as a templating tool, or as a renderer for higher-level components and tools. It’s primary focus is on static site generation and Swift-based web development.
Plot is used to build and render all of swiftbysundell.com.
Plot enables you to write HTML using native, fully compiled Swift code, by modeling the HTML5 standard’s various elements as Swift APIs. The result is a very lightweight DSL that lets you build complete web pages in a highly expressive way:
let html = HTML(
.head(
.title("My website"),
.stylesheet("styles.css")
),
.body(
.div(
.h1("My website"),
.p("Writing HTML in Swift is pretty great!")
)
)
)Looking at the above, it may at first seem like Plot simply maps each function call directly to an equivalent HTML element — and while that’s the case for some elements, Plot also inserts many kinds of highly valuable metadata automatically. For example, the above expression will result in this HTML:
<!DOCTYPE html>
<html>
<head>
<title>My website</title>
<meta name="twitter:title" content="My website"/>
<meta name="og:title" content="My website"/>
<link rel="stylesheet" href="styles.css" type="text/css"/>
</head>
<body>
<div>
<h1>My website</h1>
<p>Writing HTML in Swift is pretty great!</p>
</div>
</body>
</html>As you can see above, Plot added both all of the necessary attributes to load the requested CSS stylesheet, along with additional metadata for the page’s title as well — improving page rendering, social media sharing, and search engine optimization.
Plot ships with a very wide coverage of the HTML5 standard, enabling all sorts of elements to be defined using the same lightweight syntax — such as tables, lists, and inline text styling:
let html = HTML(
.body(
.h2("Countries and their capitals"),
.table(
.tr(.th("Country"), .th("Capital")),
.tr(.td("Sweden"), .td("Stockholm")),
.tr(.td("Japan"), .td("Tokyo"))
),
.h2("List of ", .strong("programming languages")),
.ul(
.li("Swift"),
.li("Objective-C"),
.li("C")
)
)
)Above we’re also using Plot’s powerful composition capabilities, which lets us express all sorts of HTML hierarchies by simply adding new elements as comma-separated values.
Attributes can also be applied the exact same way as child elements are added, by simply adding another entry to an element’s comma-separated list of content. For example, here’s how an anchor element with both a CSS class and a URL can be defined:
let html = HTML(
.body(
.a(.class("link"), .href("https://github.com"), "GitHub")
)
)The fact that attributes, elements and inline text are all defined the same way both makes Plot’s API easier to learn, and also enables a really fast and fluid typing experience — as you can simply type . within any context to keep defining new attributes and elements.
Plot makes heavy use of Swift’s advanced generics capabilities to not only make it possible to write HTML and XML using native code, but to also make that process completely type-safe as well.
All of Plot’s elements and attributes are implemented as context-bound nodes, which both enforces valid HTML semantics, and also enables Xcode and other IDEs to provide rich autocomplete suggestions when writing code using Plot’s DSL.
For example, above the href attribute was added to an <a> element, which is completely valid. However, if we instead attempted to add that same attribute to a <p> element, we’d get a compiler error:
let html = HTML(.body(
// Compiler error: Referencing static method 'href' on
// 'Node' requires that 'HTML.BodyContext' conform to
// 'HTMLLinkableContext'.
.p(.href("https://github.com"))
))Plot also leverages the Swift type system to verify each document’s element structure as well. For example, within HTML lists (such as <ol> and <ul>), it’s only valid to place <li> elements — and if we break that rule, we’ll again get a compiler error:
let html = HTML(.body(
// Compiler error: Member 'p' in 'Node<HTML.ListContext>'
// produces result of type 'Node<Context>', but context
// expects 'Node<HTML.ListContext>'.
.ul(.p("Not allowed"))
))This high degree of type safety both results in a really pleasant development experience, and that the HTML and XML documents created using Plot will have a much higher chance of being semantically correct — especially when compared to writing documents and markup using raw strings.
The same context-bound Node architecture that gives Plot its high degree of type safety also enables more higher-level components to be defined, which can then be mixed and composed the exact same way as elements defined within Plot itself.
For example, let’s say that we’re building a news website using Plot, and that we’re rendering NewsArticle models in multiple places. Here’s how we could define a reusable newsArticle component that’s bound to the context of an HTML document’s <body>:
extension Node where Context: HTML.BodyContext {
static func newsArticle(_ article: NewsArticle) -> Self {
return .article(
.class("news"),
.img(.src(article.imagePath)),
.h1(.text(article.title)),
.span(
.class("description"),
.text(article.description)
)
)
}
}With the above in place, we can now render any of our NewsArticle models using the exact same syntax as we use for built-in elements:
func newsArticlePage(for article: NewsArticle) -> HTML {
return HTML(.body(
.div(
.class("wrapper"),
.newsArticle(article)
)
))
}It’s highly recommended that you use the above component-based approach as much as possible when building websites and documents with Plot — as doing so will let you build up a growing library of reusable components, which will most likely accelerate your overall workflow over time.
Since Plot is focused on static site generation, it also ships with several control flow mechanisms that let you inline logic when using its DSL. For example, using the .if() command, you can optionally add a node only when a given condition is true:
let rating: Rating = ...
let html = HTML(.body(
.if(rating.hasEnoughVotes,
.span("Average score: \(rating.averageScore)")
)
))You can also attach an else clause to the .if() command as well, which will act as a fallback node to be displayed when the condition is false:
let html = HTML(.body(
.if(rating.hasEnoughVotes,
.span("Average score: \(rating.averageScore)"),
else: .span("Not enough votes yet.")
)
))Optional values can also be unwrapped inline using the .unwrap() command, which takes an optional to unwrap, and a closure used to transform its value into a node — for example to conditionally display a part of an HTML page only if a user is logged in:
let user: User? = loadUser()
let html = HTML(.body(
.unwrap(user) {
.p("Hello, \($0.name)")
}
))Finally, the .forEach() command can be used to transform any Swift Sequence into a group of nodes, which is incredibly useful when constructing lists:
let names: [String] = ...
let html = HTML(.body(
.h2("People"),
.ul(.forEach(names) {
.li(.class("name"), .text($0))
})
))Using the above control flow mechanisms, especially when combined with the approach of defining custom components, lets you build really flexible templates, documents and HTML pages — all in a completely type-safe way.
While Plot aims to cover as much of the standards associated with the document formats that it supports (see “Compatibility with standards” for more info), chances are that you’ll eventually encounter some form of element or attribute that Plot doesn’t yet cover.
Thankfully, Plot also makes it trivial to define custom elements and attributes — which is both useful when building more free-form XML documents, and as an “escape hatch” when Plot does not yet support a given part of a standard:
let html = HTML(.body(
.element(named: "custom", text: "Hello..."),
.p(
.attribute(named: "custom", value: "...world!")
)
))While the above APIs are great for constructing one-off custom elements, or for temporary working around a limitation in Plot’s built-in functionality, it’s (in most cases) recommended to instead either:
- Add and submit the missing API if it’s for an element or attribute that Plot should ideally cover.
- Define your own type-safe elements and attributes the same way Plot does — by first extending the relevant document format in order to add your own context type, and then extending the
Nodetype with your own DSL APIs:
extension XML {
enum ProductContext {}
}
extension Node where Context == XML.DocumentContext {
static func product(_ nodes: Node<XML.ProductContext>...) -> Self {
.element(named: "product", nodes: nodes)
}
}
extension Node where Context == XML.ProductContext {
static func name(_ name: String) -> Self {
.element(named: "name", text: name)
}
static func isAvailable(_ bool: Bool) -> Self {
.attribute(named: "available", value: String(bool))
}
}The above may at first seem like unnecessary busywork, but just like Plot itself, it can really improve the stability and predictability of your custom documents going forward.
Once you’ve finished constructing a document using Plot’s DSL, call the render method to render it into a String, which can optionally be indented using either tabs or spaces:
let html = HTML(...)
let nonIndentedString = html.render()
let spacesIndentedString = html.render(indentedBy: .spaces(4))
let tabsIndentedString = html.render(indentedBy: .tabs(1))Individual nodes can also be rendered independently, which makes it possible to use Plot to construct just a single part of a larger document:
let header = Node.header(
.h1("Title"),
.span("Description")
)
let string = header.render()Plot was built with performance in mind, so regardless of how you render a document, the goal is for that rendering process to be as fast as possible — with very limited node tree traversal and as little string copying and interpolation as possible.
Besides HTML and free-form XML, Plot also ships with DSL APIs for constructing RSS and podcast feeds, as well as SiteMap XMLs for search engine indexing.
While these APIs are most likely only relevant when building tools and custom generators (the upcoming static site generator Publish includes implementations of all of these formats), they provide the same level of type safety as when building HTML pages using Plot:
let rss = RSS(
.item(
.guid("https://mysite.com/post", .isPermaLink(true)),
.title("My post"),
.link("https://mysite.com/post")
)
)
let podcastFeed = PodcastFeed(
.title("My podcast"),
.owner(
.name("John Appleseed"),
.email("[email protected]")
),
.item(
.title("My first episode"),
.audio(
url: "https://mycdn.com/episode.mp3",
byteSize: 79295410,
title: "My first episode"
)
)
)
let siteMap = SiteMap(
.url(
.loc("https://mysite.com/post"),
.lastmod(Date()),
.changefreq(.daily),
.priority(1)
)
)For more information about what data is required to build a podcast feed, see Apple’s podcasting guide, and for more information about the SiteMap format, see its official spec.
Plot is distributed using the Swift Package Manager. To install it into a project, simply add it as a dependency within your Package.swift manifest:
let package = Package(
...
dependencies: [
.package(url: "https://github.com/johnsundell/plot.git", from: "0.1.0")
],
...
)Then import Plot wherever you’d like to use it:
import PlotFor more information on how to use the Swift Package Manager, check out this article, or its official documentation.
Plot consists of four core parts, that together make up both its DSL and its overall document rendering API:
Nodeis the core building block for all elements and attributes within any Plot document. It can represent elements and attributes, as well as text content and groups of nodes. Each node is bound to aContexttype, which determines which kind of DSL APIs that it gets access to (for exampleHTML.BodyContextfor nodes placed within the<body>of an HTML page).Elementrepresents an element, and can either be opened and closed using two separate tags (like<body></body>) or self-closed (like<img/>). You normally don’t have to interact with this type when using Plot, since you can create instances of it through its DSL.Attributerepresents an attribute attached to an element, such as thehrefof an<a>element, or thesrcof an<img>element. You can either constructAttributevalues through its initializer, or through the DSL, using the.attribute()command.DocumentandDocumentFormatrepresent documents of a given format, such asHTML,RSSandPodcastFeed. These are the top level types that you use in order to start a document building session using Plot’s DSL.
Plot makes heavy use of a technique known as Phantom Types, which is when types are used as “markers” for the compiler, to be able to enforce type safety through generic constraints. Both DocumentFormat, and the Context of a node, element or attribute, are used this way — as these types are never instantiated, but rather just there to associate their values with a given context or format.
Plot also uses a very lightweight API design, minimizing external argument labels in favor of reducing the amount of syntax needed to render a document — giving its API a very “DSL-like” design.
Plot’s ultimate goal to be fully compatible with all standards that back the document formats that it supports. However, being a very young project, it will most likely need the community’s help to move it closer to that goal.
The following standards are intended to be covered by Plot’s DSL:
If you discover an element or attribute that’s missing, please add it and open a Pull Request with that addition.
Plot was originally written by John Sundell as part of the Publish suite of static site generation tools, which is used to build and generate Swift by Sundell. That suite also includes the Markdown parser Ink, as well as Publish itself (which will be open sourced soon).
The idea of using Swift to generate HTML has also been explored by many other people and projects in the community, some of them similar to Plot, some of them completely different. For example Leaf by Vapor, swift-html by Point-Free, and the Swift Talk backend by objc.io. The fact that there’s a lot of simultaneous innovation within this area is a great thing — since all of these tools (including Plot) have made different decisions around their overall API design and scope, which lets each developer pick the tool that best fits their individual taste and needs (or perhaps build yet another one?).
Plot’s main focus is on Swift-based static site generation, and on supporting a wide range of formats used when building websites, including RSS and podcast feeds. It’s also tightly integrated with the upcoming Publish static site generator, and was built to enable Publish to be as fast and flexible as possible, without having to take on any third-party dependencies. It was open sourced as a separate project both from an architectural perspective, and to enable other tools to be built on top of it without having to depend on Publish.
Plot is developed completely in the open, and your contributions are more than welcome.
Before you start using Plot in any of your projects, it’s highly recommended that you spend a few minutes familiarizing yourself with its documentation and internal implementation, so that you’ll be ready to tackle any issues or edge cases that you might encounter.
Since this is a very young project, it’s likely to have many limitations and missing features, which is something that can really only be discovered and addressed as more people start using it. While Plot is used in production to build and render all of Swift by Sundell, it’s recommended that you first try it out for your specific use case, to make sure it supports the features that you need.
This project does not come with GitHub Issues-based support, and users are instead encouraged to become active participants in its continued development — by fixing any bugs that they encounter, or by improving the documentation wherever it’s found to be lacking.
If you wish to make a change, open a Pull Request — even if it just contains a draft of the changes you’re planning, or a test that reproduces an issue — and we can discuss it further from there. See Plot’s contribution guide for more information about how to contribute to this project.
Hope you’ll enjoy using Plot!