Revisions

Get revised ranges:

const revisedRanges = Beat.revisedRanges()

Beat.revisedRanges() returns a dictionary object with generation as key and revised ranges as an array:

{
    // ranges are saved as [position, length]
    "blue": [ [0, 15], [20, 3] ],
    "orange": [],
    "purple": [],
    "green": []
}

Revisions live as attributes in the editor text, and are not connected to the parser until this data is "baked" into the lines.

Usually this works so that the contents are re-parsed from scratch, and the revised ranges are then applied to the corresponding lines. However, you can bake the data into the currently parsed when needed. With longer screenplays, observe the possible performance hit if you do this often.

Bake the revised ranges into line properties:

Beat.bakeRevisions()

After this operation, you can access the revised ranges using line.ranges.revisions:

Beat.bakeRevisions()

const line = Beat.lines()[index] // Get some line
const blueRevisions = line.ranges.revisions["blue"] // Returns [ [location, length], ... ]

To speed up the operation, you can bake revisions in given range:

Beat.bakeRevisionsInRange(location, length)

NOTE: The revised ranges might be invalid right after baking. The revision ranges are NOT updated into lines while typing, so only use these for one-off operations. You'll need to re-bake the data every time you use it.

Organically getting the revision data

You can also listen to when the document is saved to get the revised ranges, because revisions are written into document settings when creating a document file. Further reading: Saving user and document settings

let revisions
Beat.onDocumentSave(function () {
    // Document was saved, you can now fetch revision ranges from document settings
    revisions = Beat.getRawDocumentSetting("Revision")
});