Screenplay Tools

https://github.com/wildwinter/screenplay-tools
Admin
Multi-language utils for parsing and writing screenplays in the Fountain and FDX scriptwriting...
Tokens:5,691
Snippets:78
Trust Score:7.6
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Installation Rules

Source: https://github.com/wildwinter/screenplay-tools/blob/main/cpp/CMakeLists.txt

Specifies how to install the built library and its headers. Libraries are placed in 'lib' and headers in 'include/screenplay_tools'.

```cmake
# Install target
install(TARGETS ${PROJECT_NAME}
    LIBRARY DESTINATION lib  # For shared libraries
    ARCHIVE DESTINATION lib  # For static libraries
    PUBLIC_HEADER DESTINATION include/screenplay_tools
)
```

--------------------------------

### Testing Framework Setup

Source: https://github.com/wildwinter/screenplay-tools/blob/main/cpp/CMakeLists.txt

Enables CMake's built-in testing support and registers the compiled test executable to be run as a test suite named 'ScreenplayToolsTests'.

```cmake
# Enable testing (CMake's built-in test support)
enable_testing()

# Register the test executable
add_test(NAME ScreenplayToolsTests COMMAND tests -r console)
```

--------------------------------

### Fountain Script Example

Source: https://github.com/wildwinter/screenplay-tools/blob/main/README.md

This is an example of a screenplay written in the Fountain format. It demonstrates scene headings, action lines, character names, parentheticals, and dialogue.

```text
INT. DAVE'S APARTMENT - DAY

Dave is standing in the open window looking out at the pouring rain.

            DAVE
        (cheerfully)
    Nice day for it!

            CUT TO:
```

--------------------------------

### Parse and Write Screenplay Text with Python

Source: https://github.com/wildwinter/screenplay-tools/blob/main/README.md

This Python snippet demonstrates parsing screenplay text using the `screenplay_tools.fountain.parser` and then writing it back to a formatted string using `screenplay_tools.fountain.writer`. Ensure the library is installed.

```python
from screenplay_tools.fountain.parser import Parser
from screenplay_tools.fountain.writer import Writer

script_text = """
INT. ROOM - DAY
        DAVE
    (loudly)
Hello, fellow kids!
"""

# Initialize parser and writer
parser = Parser()
writer = Writer()

# Parse the script
parser.add_text(script_text)

# Write the script back to text
formatted_script = writer.write(parser.script)

print(formatted_script)
```

--------------------------------

### Parse Screenplay Text with C++

Source: https://github.com/wildwinter/screenplay-tools/blob/main/README.md

This C++ example demonstrates how to build and use the Screenplay Tools library. It includes parsing Fountain script text and outputting the parsed script structure to the console. Ensure you have the source code and build it for your project.

```cpp
#include "screenplay_tools/fountain/parser.h"
#include "screenplay_tools/screenplay.h"
#include <iostream>
#include <string>

// Use the namespace
using namespace ScreenplayTools;
using namespace ScreenplayTools::Fountain;

int main() {
    // Create an instance of Parser
    Parser parser;

    // Example Fountain script text
    std::string scriptText = R"(Title: Example Script
Author: Test Author

INT. ROOM - DAY

A description of the scene.

CHARACTER
Dialogue line.)";

    // Add text to the parser
    parser.addText(scriptText);

    // Assuming the parser has a way to get the parsed script (e.g., via a 'getScript()' method)
    const auto& script = parser.getScript();

    // Dump the parsed script to the console
    std::cout << script->dump() << std::endl;

    return 0;
}
```

--------------------------------

### Fountain Text Input

Source: https://github.com/wildwinter/screenplay-tools/blob/main/README.md

Example of a screenplay scene written in Fountain format.

```text
INT. DAVE'S APARTMENT - DAY

Dave is standing in the open window looking out at the pouring rain.

            DAVE
        (cheerfully)
    Nice day for it!

            CUT TO:

INT. SPACE STATION - EARTHDAWN #1a#

Jennifer is upside down, looking out through a round porthole of a window, at the sun rising over Earth.

            JENNIFER
        (bitter)
    Nice day for it.

            COLIN (O.S.)
    Oh no. Not again.
```

--------------------------------

### Fountain Callback Parser Events

Source: https://github.com/wildwinter/screenplay-tools/blob/main/README.md

Example of events triggered by the `Fountain.CallbackParser` during parsing, useful for on-screen dialogue display.

```javascript
onSceneHeading: { text: "INT. DAVE'S APARTMENT - DAY" }

onAction: { text: "Dave is standing in the open window looking out at the pouring rain." }

onDialogue: { character: "DAVE", parenthetical:  "cheerfully", line: "Nice day for it!" }

onTransition: { text: "CUT TO:" }

onSceneHeading: { text: "INT. SPACE STATION - EARTHDAWN", sceneNumber: "1a"}

onAction: { text: "Jennifer is upside down, looking out through a round porthole of a window, at the sun rising over Earth." }

onDialogue: { character: "JENNIFER" , parenthetical: "bitter", line: "Nice day for it." }

onDialogue: { character: "COLIN", extension: "O.S." line: "Oh no. Not again." }
```

--------------------------------

### Parse Screenplay Text with C#

Source: https://github.com/wildwinter/screenplay-tools/blob/main/README.md

Example of using the Screenplay Tools DLL in C# to parse screenplay text. Ensure the DLL is referenced in your project. This snippet shows basic parsing and dumping the script structure.

```csharp
using System; 
using ScreenplayTools;
using ScreenplayTools.Fountain;

class Program
{
    static void Main(string[] args)
    {
        Parser parser = new Parser();
        parser.AddText("INT. SCENE HEADER\n\nDAVE\nHello, fellow kids!");

        Console.WriteLine(parser.Script.Dump());
    }
}
```

--------------------------------

### Parse Screenplay Text in Browser with ESM

Source: https://github.com/wildwinter/screenplay-tools/blob/main/README.md

Integrate Screenplay Tools into a web page using an ES6 module import. This example demonstrates parsing screenplay text directly within the browser's script tag.

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Screenplay Tools</title>
</head>
<body>
    <script type="module">
        import { FountainParser } from './screenplayTools.js';

        const parser = new FountainParser();
        parser.addText("INT. SCENE HEADER\n\nDAVE\nHello, fellow kids!");

        console.log(parser.script.dump());
    </script>
</body>
</html>
```

--------------------------------

### Test Executable Configuration

Source: https://github.com/wildwinter/screenplay-tools/blob/main/cpp/CMakeLists.txt

Defines the test executable, lists its source files including Catch2, and links it against the main project library. Includes necessary headers for tests.

```cmake
# Add test executable
add_executable(tests 
    test/catch_amalgamated.cpp
    test/fountain/test_parser.cpp
    test/fountain/test_format_helper.cpp
    test/fountain/test_callback_parser.cpp
    test/fountain/test_writer.cpp
    test/fdx/test_parser.cpp
    test/test_utils.cpp)

# Link the library to the test executable
target_link_libraries(tests PRIVATE ScreenplayTools)

# Include Catch2 header (if not installed globally)
target_include_directories(tests PRIVATE include)
```

--------------------------------

### Library Creation and Properties

Source: https://github.com/wildwinter/screenplay-tools/blob/main/cpp/CMakeLists.txt

Defines the project library, optionally as a shared library, and sets its public include directories and header files for export.

```cmake
# Create the library (static or shared)
option(BUILD_SHARED_LIBS "Build shared libraries instead of static" ON)
add_library(${PROJECT_NAME} ${LIB_SOURCES} ${LIB_HEADERS})

# Set include directories for the target
target_include_directories(${PROJECT_NAME} PUBLIC include)

# Set properties for export
set_target_properties(${PROJECT_NAME} PROPERTIES
    PUBLIC_HEADER "${LIB_HEADERS}"
)
```

--------------------------------

### Project Configuration

Source: https://github.com/wildwinter/screenplay-tools/blob/main/cpp/CMakeLists.txt

Sets the minimum CMake version, project name, and C++ standard. Ensures C++20 is required and enables export of compile commands for IDE integration.

```cmake
cmake_minimum_required(VERSION 3.15)
project(ScreenplayTools LANGUAGES CXX)

# Set C++ standard
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Export compile commands for IDE support
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
```

--------------------------------

### Source and Header File Globbing

Source: https://github.com/wildwinter/screenplay-tools/blob/main/cpp/CMakeLists.txt

Uses file(GLOB) to find all source and header files within specified directories. This is useful for projects with many files but can be less maintainable than explicit lists.

```cmake
# Source files
file(GLOB LIB_SOURCES "src/*.cpp" "src/fountain/*.cpp" "src/fdx/*.cpp")
file(GLOB LIB_HEADERS "include/screenplay_tools/*.h" "include/screenplay_tools/fountain/*.h" "include/screenplay_tools/fdx/*.h")
```

--------------------------------

### FDX Writer Write

Source: https://github.com/wildwinter/screenplay-tools/blob/main/README.md

Takes a Script object and returns a string containing the FDX XML.

```APIDOC
## FDX Writer Write

### Description
Takes a `Script` object and returns a string containing the FDX XML.

### Method

#### Write(script:Script)
Takes a `Script` object and returns a string containing the FDX XML.
```

--------------------------------

### CallbackParser

Source: https://github.com/wildwinter/screenplay-tools/blob/main/README.md

A parser that allows setting up callbacks for different elements as lines are parsed. Supports callbacks for title page entries, dialogue, action, scene headings, lyrics, transitions, sections, and synopsis.

```APIDOC
## CallbackParser

### Description
A version of the parser which lets you set up callbacks which will be called as lines are parsed.

### Methods

#### onTitlePage
* `entries` - a list of key/values for the title page.

#### onDialogue
* `character` - the character name in the script
* `extension` - optional bracketed extension e.g. DAVE (V.O.)
* `parenthetical` - optional parenthetical before the dialogue line e.g. (loudly) or (angrily)
* `line` - line of dialogue,
* `isDualDialogue` - True if the caret ^ is present indicating dual dialogue in the script

#### onAction
* `text`

#### onSceneHeading
* `text`
* `sceneNumber` - optional

#### onLyrics
* `text`

#### onTransition
* `text`

#### onSection
* `text`
* `level` - number

#### onSynopsis
* `text`

#### onPageBreak

### Properties

#### ignoreBlanks: bool
Set to false if you want empty dialogue and actions.
```

--------------------------------

### FDX Parser Parse

Source: https://github.com/wildwinter/screenplay-tools/blob/main/README.md

Parses a Final Draft XML string and returns a Script object.

```APIDOC
## FDX Parser Parse

### Description
Parses the FDX XML string and returns a `Script` object.

### Method

#### Parse(xml:string)
Parses the FDX XML string and returns a `Script` object.
```

--------------------------------

### fountainToHtml

Source: https://github.com/wildwinter/screenplay-tools/blob/main/README.md

Converts Fountain markup (italic, bold, bolditalic, underline) to HTML.

```APIDOC
## fountainToHtml

### Description
Convert Fountain markup (*italic*, **bold**, ***bolditalic*** *underline*) to HTML.

### Parameters
None explicitly documented beyond the input script format.
```

--------------------------------

### Writer

Source: https://github.com/wildwinter/screenplay-tools/blob/main/README.md

A simple writer to output a script as UTF-8 text. Supports a prettyPrint option to control indentation.

```APIDOC
## Writer

### Description
A simpler writer to write a script as UTF-8 text.

### Properties

#### prettyPrint: bool
Set to false if you don't want indents in the output.

### Methods

#### write(script)
Pass in a Script, get back a UTF-8 string.
```

--------------------------------

### Element

Source: https://github.com/wildwinter/screenplay-tools/blob/main/README.md

The superclass for all script elements, providing a common interface for accessing type and text content.

```APIDOC
## Element

### Description
Superclass for all elements within a parsed script. Provides methods to identify the element type and retrieve its main text content.

### Methods
*   **type / getType()**: Returns an `ElementType` enum indicating the type of script element.
*   **text / getText()**: Returns the main text content of the element, excluding other parsed information.
```

--------------------------------

### Fountain Parser Output Objects

Source: https://github.com/wildwinter/screenplay-tools/blob/main/README.md

Structured JavaScript objects generated by the `Fountain.Parser` from Fountain text.

```javascript
HEADING: { text: "INT. DAVE'S APARTMENT - DAY" }

ACTION: { text: "Dave is standing in the open window looking out at the pouring rain." }

CHARACTER: { name: "DAVE" }

PARENTHETICAL: { text: "cheerfully" }

DIALOGUE: { text: "Nice day for it!" }

TRANSITION: { text: "CUT TO:" }

HEADING: { text: "INT. SPACE STATION - EARTHDAWN", sceneNumber: "1a"}

ACTION: { text: "Jennifer is upside down, looking out through a round porthole of a window, at the sun rising over Earth." }

CHARACTER: { name: "JENNIFER" }

PARENTHETICAL: { text: "bitter" }

DIALOGUE: { text: "Nice day for it." }

CHARACTER: { name: "COLIN", extension: "O.S." }

DIALOGUE: { text: "Oh no. Not again." }
```

--------------------------------

### Parse Script Lines in C#

Source: https://github.com/wildwinter/screenplay-tools/blob/main/README.md

Parses a list of script lines incrementally using C#. This method is useful when lines are available as a collection.

```csharp
// C#
using System;
using System.Collections.Generic;
using ScreenplayTools;
using ScreenplayTools.Fountain;

class Program
{
    static void Main(string[] args)
    {
        Parser fp = new Parser();

        // Example lines from the script
        List<string> lines = new List<string>
        {
            "EXT. MY BASEMENT",
            "DAVE",
            "",
            "(Shouting)",
            "Hey, anyone home?"
        };

        // Add a whole set of lines to the parser
        fp.AddLines(lines);

        // Dump a debug version of the script
        Console.WriteLine(fp.Script.Dump());
    }
}
```

--------------------------------

### Script

Source: https://github.com/wildwinter/screenplay-tools/blob/main/README.md

Represents the parsed script, providing access to various components like title pages, elements, notes, and boneyards.

```APIDOC
## Script

### Description
Represents the entire parsed screenplay, offering methods to retrieve different parts of the script.

### Methods
*   **titleEntries / getTitleEntries()**: Returns a list of `TitleEntry` objects from the script's title page.
*   **elements / getElements()**: Returns a list of parsed `Element` objects in the script. Use `element.getType()` to determine the element type.
*   **notes / getNotes()**: Returns a list of embedded `Note` objects, preserving information from the original Fountain file.
*   **boneyards / getBoneyards()**: Returns a list of commented-out text chunks as `Boneyard` objects, preserving information from the original Fountain file.
```

--------------------------------

### FountainParser

Source: https://github.com/wildwinter/screenplay-tools/blob/main/README.md

The normal incremental parser for Fountain files. It stores the parsed script in the `script` property. Consider `CallbackParser` if you want something which bundles up the dialogue in a more useful way.

```APIDOC
## FountainParser

### Description
Provides incremental parsing of Fountain files, storing the result in a script property. An alternative `CallbackParser` is available for bundled dialogue.

### Properties
*   **mergeActions** (bool) - Default: True. Controls merging of multiple dialogue or action lines.
*   **mergeDialogue** (bool) - Default: True. Controls merging of multiple dialogue or action lines.
*   **useTags** (bool) - Default: False. If True, extracts and parses tags from the Fountain file.

### Methods
*   **addText(text:string)**: Split UTF-8 text into lines and parse them.
*   **addLines(lines:list)**: Parse an array of UTF-8 text lines.
*   **addLine(line:string)**: Parse a single UTF-8 text line.
*   **script / getScript()**: Parsed script. Grows as more lines are parsed!
```

--------------------------------

### Parse Script Line by Line in Python

Source: https://github.com/wildwinter/screenplay-tools/blob/main/README.md

Parses a Fountain script by adding individual lines one at a time using Python. Remember to call finalize() after adding all lines.

```python
# Python
from screenplay_tools.fountain.parser import Parser

# Create an instance of Parser
fp = Parser()

# Add individual lines to the parser
fp.add_line("EXT. MY BASEMENT")
fp.add_line("")
fp.add_line("DAVE")
fp.add_line("(Shouting)")
fp.add_line("Hey, anyone home?")

# Need to use finalize() after individual lines
# as some lines care about what gets added next.
fp.finalize()

# Dump the parsed script
print(fp.script.dump())
```

--------------------------------

### MIT License

Source: https://github.com/wildwinter/screenplay-tools/blob/main/README.md

The MIT License governs the use of the screenplay-tools software. It grants broad permissions for use, modification, and distribution.

```plaintext
MIT License

Copyright (c) 2024 Ian Thomas

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

--------------------------------

### Parse Fountain with Tags in Javascript

Source: https://github.com/wildwinter/screenplay-tools/blob/main/README.md

Parses Fountain content that includes tags, enabling the `useTags=true` option. Tags are stored in the `tags` property of each `Element`.

```javascript
HEADING: { text: "INT. DAVE'S APARTMENT - DAY", tags:["slow_load"]}

ACTION: { text: "Dave is standing in the open window looking out at the pouring rain." }

CHARACTER: { name: "DAVE" }

PARENTHETICAL: { text: "cheerfully" }

DIALOGUE: { text: "Nice day for it!", tags:["color:blue", "useAnim"]}
```

--------------------------------

### Parse Fountain File Content

Source: https://github.com/wildwinter/screenplay-tools/blob/main/README.md

Parses the entire content of a Fountain file using Javascript. Ensure the file content is read as UTF-8.

```javascript
// Javascript
import { FountainParser } from "screenplayTools.js";

const filePath = '../examples/Test.fountain';
const fileContent = readFileSync(filePath, 'utf-8');

let fp = new FountainParser();

// Expects a file full of UTF8 script
fp.addText(fileContent);

// Dump a debug version of the script
console.log(fp.script.dump());
```

--------------------------------

### Parse Screenplay Text in Browser with IIFE

Source: https://github.com/wildwinter/screenplay-tools/blob/main/README.md

Utilize the minified IIFE version of Screenplay Tools in a browser. This method accesses the parser through a global 'ScreenplayTools' object after including the 'screenplayTools.min.js' script.

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Screenplay Tools</title>
    <script src="screenplayTools.min.js"></script>
</head>
<body>
    <script>
        // Access the global ScreenplayTools object
        const parser = new ScreenplayTools.Fountain.FountainParser();
        parser.addText("INT. SCENE HEADER\n\nDAVE\nHello, fellow kids!");

        // Use the imported function
        console.log(parser.script.dump());
    </script>
</body>
</html>
```

--------------------------------

### Parse Screenplay Text with JavaScript ES6 Module

Source: https://github.com/wildwinter/screenplay-tools/blob/main/README.md

Use this snippet to parse screenplay text within a JavaScript ES6 module environment. Ensure the 'screenplayTools.js' module is correctly imported.

```javascript
import { FountainParser } from './screenplayTools.js';

const parser = new FountainParser();
parser.addText("INT. SCENE HEADER\n\nDAVE\nHello, fellow kids!");

console.log(parser.script.dump());
```
Tokens:
Raw