iambic: Data extraction and rendering library for Shakespearean text. :scroll:

Let computers do the hard work for you! iambic provides:

1. The most accurate method for counting lines automatically.
2. Automatically track which characters are speaking in any scene.
3. Deterministic, repeatable results, with the ability to store your data as JSON with strictly defined schema for passing over the wire or storing locally or in a NoSQL database between runtimes.

Installation

In order to install the latest version, simply pip3 install -U iambic.

This library requires Python 3.6 or greater.

What is it?

iambic was originally envisioned as a tool for translating Shakespearean text into actionable information, i.e.:

1. How many lines are in this particular play?
2. How many lines does a given character speak in this play?
3. Which characters speak, in which scenes and acts?

As a result of the implementation, this tool can be applied to any body of text which adhere's to its parsing syntax.

How it works

In Shakespeare's work, every line of text has meaning and communicates volumes beyond the individual words. As such, iambic's root object is the individual line, or node. Each node is assigned a specific type based upon simple syntactical rules. These rules can be broken out into the following logical groups:

1. Locales

A Locale will be denoted by header formatting (H1-5) and represents a logical break in the forward action of the play. These can be thought of as the entries that may show up in a Table of Contents, and can include:

• Act
• Scene
• Prologue or Epilogue

An Act may have many nested Scene, Prologue, and Epilogue sections.

A Scene will be always be nested under an act Act. A Scene contains speeches, dialogue, and actions.

A Prologue or Epilogue may or may not be nested under an Act, but have the same internal structure as a Scene.

2. Actions and Directions

Actions and Directions will be denoted by an italicized paragraph of any length and represent a physical action that takes place on stage. These can include:

• Character Action (Action)
• Stage Direction (Direction)
• Entrance/Exit (Entrance or Exit)

An Action object represents an action of a specific character and are usually found within or just after a speech. If these are more than one word (such as Aside), they will either reference the character by pronoun, or begin with To .... In order for iambic to understand that the given paragraph is an Action, the paragraph should be wrapped in brackets ([]) in addition to italicized. ex: [He brandishes his sword], [To JULIET]).

A Direction is more straightforward - it is simply a stage direction, meaning a paragraph of text which illucidates some on-stage action between any number of characters. A Direction will always be written in third-person omniscient and reference characters by name and be denoted simply by italics. ex: Flourish, They fight, HAMLET stabs CLAUDIUS.

An Entrance or Exit will usually lead or finish with Enter, Exit, or Exeunt and be italicized.

3. Personae

The Persona object is in its own category and is initially denoted by a bolded line preceding a block of dialogue. ex:

HAMLET
Not so, my lord, I am too much i'th'sun.

Once a persona is created, that object is tracked throughout the rest of the play.

4. Lines

Finally, the meat of the text. Having filtered out all other syntactical notations, whatever is remaining is considered a line of Dialogue. Dialogue objects represent a single line of spoken word and are grouped within larger Speech objects, which are associated to the character speaking and nested directly under the Scene, Prologue, or Epilogue object in which it occurs.

The Schema

The full schema specification has been written in JSON Schema 7.0 and can be found here

Documentation

Full documentation coming soon!

How to Contribute

1. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.
2. Create a branch on Github for your issue or fork the repository on GitHub to start making your changes to the master branch.
3. Write a test which shows that the bug was fixed or that the feature works as expected.
4. Send a pull request and bug the maintainer until it gets merged and published. :)