Recital Output

The result of running the Recital core parser is a JSON file, with a list of tokens for every element that was fed into the parser.

There are two different versions of the JSON output: parse gives you an array of trees, where paragraphs are children of fragments, which are children of scenes, and parseFlat gives you a flat array of tokens that also include tokens to end fragments and scenes. The former is useful for any kind of recursive iteration, the latter for parsing straight through.

All tokens used in the JSON output can be found in src/types.ts.

Tokens

All tokens have the following fields:

• type (string) - the type of the token.

And the following optional fields:

• meta (object) - an optional meta object, which contains any metadata that token can have. Metadata is defined in the spec, and is rendered as a JSON object of its own.
• title (string) - title pulled from definition of a scene / fragment or from the token's metadata
• id (string) - id pulled from token metadata if there's an id defined
• classes (string[]) - pulled from token metadata if classes is defined there. Most likely to be filled with an @ shorthand definition.
• primary (string) - if the token has an id, it's the id. Otherwise, it's the first item in classes.

scene

A scene is the top-level structure of a Recital document. All documents are broken down into scenes, which have one or more fragments (or paragraphs that don't belong to a fragment).

Scenes have type: scene, and for the tree parsed view, also has following fields:

• fragments ((Fragment | Empty)[]) - list of tokens that are children of the scene.

fragment

Fragments always belong to a scene, though don't hold a reference to the parent scene themselves; in the process of parsing tokens the parser must keep track of which scenes a fragment belongs to.

Fragments have type: fragment. For the tree parsed view, it also has the following fields:

• tokens (Token[]) - array of tokens that can be any combination of paragraph, rawText, command, or endCommand tokens.

endScene

{ type: endScene }

Used only in the flat parsed view, this marks the end of a scene that was opened with the scene token. Cannot contain metadata. In the flat view, you are guaranteed to see an endScene token after a scene token.

endFragment

{ type: endFragment }

Used only in the flat parsed view, this marks the end of a fragment that was opened with the fragment token. Cannot contain metadata. Similar to scenes, all fragments are guaranteed to be closed before opening a new one.

empty

A container of tokens, used in the tree parsed view only to hold items that belong to a scene that shouldn't belong to a fragment.

Contains the following fields:

• type: empty
• tokens (Token[]) - array of tokens that can be any combination of paragraph, rawText, command, or endCommand tokens.

paragraph

Represents a paragraph. Because Recital doesn't care about inline markup, all markup for paragraph tags are left untouched, save for trimming whitespace around it.

Paragraphs have the following fields:

• type: paragraph
• text (string) - the contents of the paragraph.

rawText

Represents a raw string, with whitespace and escapes not handled, as described in the spec's !== tag usage. Code and pre-tag text will also be rendered as rawText tokens.

They have the following fields:

• type: rawText
• text (string) - the contents of the text.
• startTag (string) - the starting tag used to create the rawText - this is used to distinguish code tags from pure raw strings, and can also be useful for recreating the input Recital text.
• endTag (string) - the ending tag used to create the rawText - useful to distinguish code tags from pure raw strings.

command

Represents a piece of Logic in the spec; in the Recital script, are lines beginning with $. Recital doesn't by itself handle any logic tags beyond creating commands for them, and instead it is up to individual parsers to manipulate them or pass them onwards.

They have the following fields:

• type: command
• text (string) - the contents of the command as a whole, without the leading $. Mostly useful to pass the entire content of the command to a later parser, in a multi-step parsing environment.
• name (string) - name of the command (string right after the $)
• args ((string | number)[]) - space-deliminated string of arguments, without any further processing.
• open (boolean) - DEPRECATED - if true, the command was open-ended, and we're looking for an endCommand token later to formally 'close' it.

endCommand

DEPRECATED

Used to close any open-ended commands (which are not supported in the current version of the spec, so functionally will not be created.)

• type: endCommand
• name (string) - optional string to denote which command this token closes.