Jouvence (version 1.0.1)
Jouvence is a javascript library to parse a screenplay written in Fountain.
Fountain is a text format, similar to Markdown, but designed specifically to write screenplays.
To quote from the Fountain web site:
Fountain allows you to write screenplays in any text editor on any device. Because it’s just text, it’s portable and future-proof.
Jouvence is an event driven parser
Jouvence is an event-driven parser: it operates on each piece of the Fountain input sequentially and reports each parsing event as it happens.
Jouvence sends notification while it is parsing the content instead of providing a model of the content of the Fountain document at the end of the parsing.
Installation
To install the jouvence package, just type:
npm install jouvence
if you want to update your package.json
file:
npm install --save jouvence
Usage
If you have a Fountain file, like the sample file BrickAndSteel.fountain that you can find on the Fountain website, you can parse it with this simple code:
var jouvence = ; var input = jouvenceinput;var parser = jouvence; parser ;
API details
Once you have imported the jouvence API with `require('jouvence'), you then have access to 3 classes:
Input : jouvence.input()
This class allows you to define the way you want to inject your fountain screenplay into the parser.
You have 3 options:
- you can provide a file (like the example above):
jouvence.input().fromFile(<path of the file>)
- you can provide a string:
jouvence.input().fromString('<your fountain data>')
- you can provide a regular (node/Stream) Readable:
jouvence.input().fromReadStream(<readable instance>)
All those methods return an object which can be parsed by the Fountain parser:
Fountain parser: jouvence.parser()
This parser has a single method parse()
which takes 2 parameters:
- the
input
as returned from thejouvence.input()
class - a class which will provide all the callbacks require to process the parsing events (see next section).
As the parsing is asynchronous, the parse()
method returns a Promise : when the processing is over, the then()
method is called.
parsing notification callbacks
As mentioned above, the parser expects a class which will provide all the callbacks methods to receive the parsing events.
There is a helper class, returned by jouvence.dummyNotification()
which will provide a starting point for your own implementation.
With the example above, this class outputs the events it receives from the parser:
tartOfDocumenttitlePage:
The easiest way to create your own callback class is to copy and paste the code from this sample notification class and provide your own implementation.
Callbacks description
Callback name | Description |
---|---|
startOfDocument |
called when the parsing starts |
titlePage (metainformation) |
called when the title page information is parsed. metainformation contains is a map with all the key/values from the title page |
sceneHeading(sceneHeading, extra) |
called when a scene heading is parsed. extra.lineno contains the line number of the input. |
action(action, blocks, options) |
called when an action is parsed. blocks contains the comments or notes which may have been inserted in the action |
pageBreak |
called when a page break is parsed |
dualDialogueStart |
called when a dual dialogue is about to start |
dualDialogueEnd |
called when a dual dialogue ends |
dialogueStart |
called when a dialogue is about to start |
dialogueEnd |
called when a dialogue ends |
character(character, option) |
called when a character is parsed. option.extension contains the optional extension |
parenthetical(parenthetical) |
called when a parenthetical is parsed |
dialogue(dialogue) |
called when a dialogue is parsed |
transition(transition) |
called when a transition is parsed |
section(section, level, extra) |
(optional) Called when a section is parsed. |
synopsis(synopsis) |
(optional) called when a synopsis is parsed. |
block(blocks) |
(optional) Called when a comments or notes have been parsed |
endOfDocument |
Called when the end of the input is reached |
emphasis parser: jouvence.parseEmphasis()
This last class allows you to parse the emphasis in the strings returned in the API parsing events.
This is a synchronous parser which returns a data structure describing the different parts of the string:
var parts = emParser; console;
The result is:
Parts :{ type: '.', parts: [