Hyperion

Hyperion is a TypeScript module for parsing Fountain screenplay markup.

For a working implementation, see Fairfax. For more on Fountain, see the website.

Usage

Hyperion can take any Fountain string as input and will return a Document object (see Documents below).

import { Parser } from "hyperion"

const parser = new Parser();
const fountainDocument = parser.parse(myFountainString);

However, Hyperion is an incremental parser, meaning it's also capable of processing a single line of input at an arbitrary position in the screenplay. Because Fountain is context-based, if we do this, then we also need to pass in a ParserContext with some extra information about the input.

import { Parser, ParserContext } from "hyperion"

const parser = new Parser();
const context = new ParserContext(
    isDocumentStart,
    isInDialogue,
    isInDualDialogue,
    nextLineIsBlank,
    previousLineIsBlank
);

const fountainDocument = parser.parse(myPartialFountainString, context);

Documents

Hyperion returns a Document object, which contains a few other elements that define a Fountain screenplay.

• Document.titlePage is a Map object of key/value pairs from the screenplay's title page. Note that this isn't the actual text of the title page, which is still contained in the document blocks, but a set of already-paired values for easy access.
• Document.blocks is an array of Block objects (see Blocks below) that represents the full parsed content of the input.
• Document.activeMultilines and Document.openMultilines are collections of MultilineStructures (see Multilines below). These allow an editor to handle multiline comments that might extend beyond the parsed section.

Blocks

A Block has a type (like Action, Dialogue, or Transition) and some Runs. Each Run contains some raw text and a set of RunStyles which define how the text should be displayed. See the following example of how a chunk of Fountain would be returned by Hyperion.

DAN
Let's retire them.
_Permanently_.

[
    {
        type: Character,
        runs: [ { text: "DAN", styles: [] } ]
    },
    {
        type: Dialogue,
        runs: [ { text: "Let's retire them.", styles: [] } ]
    },
    {
        type: Dialogue,
        runs: [
            { text: "_", styles: [Markup] },
            { text: "Permanently", styles: [Underline] },
            { text: "_", styles: [Markup] },
            { text: ".", styles: [] }
        ]
    }
]

Multilines

While Fountain is primarily a line-based language, it allows two kinds of multiline elements: boneyards and notes.

So that an editor can handle elements that extend outside of the input section, Hyperion sends back some information about these elements.

MultilineStructures have a type, a start index, and an end index. OpenMultilineStructures have a type, an index, and a boolean forward that marks whether the element opens forward or backward.

Compatibility

Hyperion conforms to the official Fountain spec. Where the spec is ambiguous, behavior is based on the official source code, Highland, and CommonMark. Broadly, Hyperion aims to be generous and interpret markup as the user most likely intended.

License

Hyperion is available under the MIT license. If you want to build an editor using Hyperion, consider starting with Fairfax instead, a minimal implementation which is also MIT-licensed.

Zach Lo

https://zachlo.com