Untwisting a Hypertext Narrative - PEG to the Rescue!
In this post you’ll learn why I think Parsing Expression Grammars are awesome and see an example of how I built one to scratch an itch.
After spending some time writing Choose Your Own Adventure-style books in markdown, I quickly realized there were some tools missing that could greatly improve the writing process. A few missing items were:
- Knowing if there are any unreachable sections that have been orphaned in the writing process.
- Being able to see all the branches within a book.
- Knowing each branch is coherent by having an easy way to read through them.
“Never fear,” I say to myself, “I can just write some code to parse the markdown files and pluck out the paths. This will be easy.”
As a quick reminder, the format for a single section looks something like this:
1 2 3 4 5 6 7
(Headers specify new sections starting and have some anchor. Links direct you to new sections.)
There are plenty of ways to slurp in a story file and parse it. You could write a naive line-by-line loop that breaks it into sections based on the presence of a header and then parse the links within sections with substring matching. You could write some complicated regular expression because we all know how much fun regular expressions can become. Or you could do something saner like write a parsing expression grammar (hereafter PEG).
Why a PEG?
Generally, a regex makes for a beautiful collection of cryptic ascii art that you’ll either comment-to-death or be confused by when you stumble across it weeks or months later. PEGs take a different approach and instead seek define “a formal language in terms of a set of rules for recognizing strings in the language.” Because they’re a set of rules, you can slowly TDD your way up from parsing a single phrase to parsing an entire document (or at least the parts you care about).
(It is worth mentioning that because the format here is pretty trivial, either the naive line-by-line solution or a regex is fine. PEGs are without a doubt the right choice IMHO for complicated grammars.)
Show me some code
We’ll be using Parslet to write our PEG. Parslet provides a succinct syntax and exponentially better error messages than other competing ruby PEGs (
parse_with_debug is my friend). My biggest complaint about Parslet is that the documentation was occasionally lacking, but it only slowed things down a bit – and there’s an IRC channel and mailing list.
Let’s start off simple, just parsing the links out of a single section of markdown. Being a TDD’er, we’ll write a few simple tests first (in MiniTest::Spec):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
And the working implementation of LinkParser:
1 2 3 4 5 6 7 8 9 10 11
“Foul,” you cry, “this is much more complicated than a regular expression!” And I reply “Yes, but it is also more intelligible long-term as you build upon it.” You don’t look completely satisfied, but you’ll continue reading.
It is worth noting that everything has a name:
- link_text encompasses everything between the two brackets in the markdown link.
- link_href is the content within the parens. Because we are specifically linking only to anchors, we also include the # and then we’ll name the id we’re linking to via
- link is just link_text + link_href
- non_link is anything that isn’t a link. It could be other markdown or plain text. It may or may not actually contain any characters at all.
- content is the whole markdown content. We can see it is made up of some number of the following: non_link + link + non_link
We’ve specified that “content” is our root so the parser starts there.
The Scratch: Adding the 3 missing features
Now we have an easy way to extract links from sections within a story. We’ll be able to leverage this to map the branches and solve all three problems.
But in order to break the larger story into sections we’ll need to write a StoryParser which can parse an entire story file (for an example file, see the previous post). Again, this was TDD’ed, but we’ll cut to the chase:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
Now we can parse out each section’s heading text, id, and content into a tree that looks something like this:
1 2 3 4 5 6 7 8 9 10 11 12 13
“That’s well and good,” you say, “but how do we turn that into something useful?”
Enter Parslet’s Transform class (and exit your remaining skepticism). Parslet::Transform takes a tree and lets you convert it into whatever you want. The following code takes a section tree from above, cleans up some whitespace, and then returns an instantiated Section class based on the input.
1 2 3 4 5 6 7 8 9 10 11 12 13 14
Example of an instantiated Section:
1 2 3 4 5 6
So now we have the building blocks for parsing a story into sections and then our Section class internally uses the LinkParser from above to determine where the section branches outward.
Let’s finish this by encapsulating the entire story in a Story class:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38
A few notes:
- You instantiate the Story class with a File object pointing to your story.
- It parses out the sections
- Then you can call methods to fill in the missing pieces of functionality we identified at the beginning of this post.
1 2 3 4 5 6 7 8 9 10 11 12 13
If you made it this far, you deserve a cookie and my undying affection. I’m all out of cookies and any I had would be gluten-free anyway, so how about I just link you to the example code instead and we call it even?
If you’d like to learn more about Parslet from someone who knows it better than me, check out Jason Garber’s Wicked Good Ruby talk.