TWINE TO JSON

A basic utility library / script to convert a Snowman-formatted Twine story file into a more easily parseable JSON format. Useable as both a Node library and as a command line tool.

NOTE: This library is still currently in development! Use at your own risk!

Install

npm install twine_to_json --save

Usage

To use from the command line, see:

twinetojson --help

To use as a library with default values:

var twineToJSON = require("twine_to_json");
twineToJSON({
   in: "path_to_story_file",
   out: "path_to_write_JSON_file",
   ignoreComments: false,
   renderMarkdown: true,
   writeToFile: true,
   prettyPrint: false,
   ignorePassages: [],
   transformPassages: [],
   customTags: [],
   linkFormat: null,
   callback: function(err, story) { /* optional */ }
}).then(function(story) {
    // ...
}).catch(function(err) {
    // ...
});

twineToJSON(options)

Returns: Promise

options

Type: Object

Hash of options. See below for details.

Options

in

Type: String

Path to the Twine story file. Required.

out

Type: String

Path to output the JSON file to. Defaults to the current working directory.

ignoreComments

Type: Boolean

Whether or not to remove block comments (i.e. /* */). Defaults to false.

renderMarkdown

Type: Boolean

Whether or not to render Markdown in story passages. Defaults to true.

writeToFile

Type: Boolean

Whether or not to write the JSON file to disk. Defaults to true.

prettyPrint

Type: Boolean

Whether or not to write the JSON file in a human-readable format. Defaults to false.

ignorePassages

Type: Array of Numbers

An array of passage ids (pids) to exclude from processing. Allows certain passages to be skipped over. These passages will not be parsed and will not appear in the final JSON output.

Usage

twineToJSON({
   ignorePassages: [ 1, 2, 3 ] // ids to ignore
   // ...
});

transformPassages

Type: Function or Array of Functions

A function or array of functions to apply to a passage. The function(s) will be provided with two arguments: passage (the Passage object) and story (the Story object). Note that any transform functions will be run on the passage before any other processing or parsing is done!

Usage

twineToJSON({
    transformPassages: function(passage, story) {
        // do something to the passage text here...
    },
    // or:
    transformPassages: [
        (passage, story) => {
            // do something to passage here
        },
        (passage, story) => {
            // do something to passage here
        },
        (passage, story) => {
            // etc.
        }
    ]
});

customTags

Type: Array of Objects

Allows the replacement of custom HTML tags within the passage text. Each object specifies the custom tag to replace. It should/can have the following properties:

• name: (String) the tag's name [required]
• swap: (String) an HTML string to swap the tag with. The tag's children will be appended to the elements in the string.

Usage

twineToJSON({
    // ...
    customTags: [
        {
            name: "options",
            swap: '<div class="options"></div>'
            // this will take anything within an <options> tag, wrap it in a 
            // <div> with class 'options', and replace the original tag.
        }
    ] 
});

linkFormat

Type: Function or String

Specifies how to format the links in the passage text. Can be either an Underscore template string or a function. Functions will be given an object with three properties:

• id: String representing a generated unique identifier for the link.
• label: String representing the link's intended display text.
• passageId: the pid of the passage the link goes to.

Usage

twineToJSON({
    // ...
    linkFormat: function(link) {
      return '<a data-passage="' + link.passageId + '">' + link.label + '</a>';
    },
    // or as Underscore template string
    linkFormat: '<a id="<%=id%>" data-passage="<%=passageId%>"><%=label%></a>'
});
 
### callback
 
Type: `Function`
 
Standard callback function for those who don't like Promises. Optional.
 
## Tests
 
``` bash
npm test

License

Created by Jon Stout. Licensed under the MIT license.