Loreline

View source
loreline.Loreline (Class)

The main public API for Loreline runtime. Provides easy access to the core functionality for parsing and running Loreline scripts.

Static Members

lastError(): Null<Error>
See: _lastError
Returns
Null<Error>
parse(input: String, ?filePath: String, ?handleFile: Null<ImportsFileHandler>, ?callback: Function): Null<Script>

Parses the given text input and creates an executable Script instance from it.

This is the first step in working with a Loreline script. The returned Script object can then be passed to methods play() or resume().

Name Type Default Description
input String The Loreline script content as a string (.lor format)
filePath String (optional) (optional) The file path of the input being parsed. If provided, requires handleFile as well.
handleFile Null<ImportsFileHandler> (optional) * (optional) A file handler to read imports. If that handler is asynchronous, then parse() method will return null and callback argument should be used to get the final script
callback Function (optional) If provided, will be called with the resulting script as argument. Mostly useful when reading file imports asynchronously. When a callback is supplied, parse errors are reported by invoking it with null and the error becomes readable via Loreline.lastError(). parse() itself never throws in that mode. Without a callback, the call throws on error as usual.
Returns Description
Null<Script> The parsed script as an AST Script instance (if loaded synchronously)
loadLocale(locale: String, script: Script, ?filePath: String, ?handleFile: Null<ImportsFileHandler>, ?callback: Function): Null<Map>

Loads translations for a specific locale, walking the script's full import tree.

For each file involved in the script (root + transitively imported), the corresponding translation file is looked up by inserting .<locale> before the extension (e.g. characters.lor -> characters.fr.lor). Missing translation files are silently skipped.

Each translation key is stored under both:

  • a global key <id> (first occurrence wins, root file priority)
  • a scoped key <source-rel-path>#<id> (always set per file, allows override)

The interpreter prefers the scoped key when looking up a translation.

Name Type Default Description
locale String The locale code (e.g. "fr")
script Script The parsed source script (must have been parsed with a file path or filePath must be provided)
filePath String (optional) (optional) Override where to look for translation files. If null, defaults to script.filePath. Can be a .lor/.lor.txt file path (translations sit alongside source files) or a directory path (translations are all in that directory).
handleFile Null<ImportsFileHandler> (optional) (optional) File handler for reading translation files
callback Function (optional) (optional) Called with the merged translations map. Required for async file handlers. When supplied, errors are routed by calling the callback with null; the call never throws and Loreline.lastError() returns the underlying error (including the file path that failed). Without a callback, the call throws on error as usual.
Returns Description
Null<Map> The merged translations map (synchronously, when handleFile is sync), or null if a translation file exists but is invalid. Missing translation files are still skipped silently. lastError() is only set when a file is present but can't be parsed (broken .lor, malformed .po/.xliff/.csv, etc.).
play(script: Script, handleDialogue: DialogueHandler, handleChoice: ChoiceHandler, handleFinish: FinishHandler, ?beatName: String, ?options: InterpreterOptions): Interpreter

Starts playing a Loreline script from the beginning or a specific beat.

This function takes care of initializing the interpreter and starting execution immediately. You'll need to provide handlers for dialogues, choices, and script completion.

Name Type Default Description
script Script The parsed script (result from parse())
handleDialogue DialogueHandler Function called when dialogue text should be displayed
handleChoice ChoiceHandler Function called when player needs to make a choice
handleFinish FinishHandler Function called when script execution completes
beatName String (optional) Optional name of a specific beat to start from (defaults to first beat)
options InterpreterOptions (optional) Additional options
Returns Description
Interpreter The interpreter instance that is running the script
resume(script: Script, handleDialogue: DialogueHandler, handleChoice: ChoiceHandler, handleFinish: FinishHandler, saveData: SaveData, ?beatName: String, ?options: InterpreterOptions): Interpreter

Resumes a previously saved Loreline script from its saved state.

This allows you to continue a story from the exact point where it was saved, restoring all state variables, choices, and player progress.

Name Type Default Description
script Script The parsed script (result from parse())
handleDialogue DialogueHandler Function called when dialogue text should be displayed
handleChoice ChoiceHandler Function called when player needs to make a choice
handleFinish FinishHandler Function called when script execution completes
saveData SaveData The saved game data (typically from interpreter.save())
beatName String (optional) Optional beat name to override where to resume from
options InterpreterOptions (optional)
Returns Description
Interpreter The interpreter instance that is running the script
extractTranslations(script: Script): Map

Extracts translations from a parsed translation script.

Given a translation file parsed with parse(), this returns a translations map that can be passed as options.translations to play() or resume().

Name Type Description
script Script The parsed translation script (result from parse() on a .XX.lor file)
Returns Description
Map A translations map to pass as InterpreterOptions.translations
translationFormat(name: String, enabled: Bool): Void

Enable or disable runtime support for an alternate translation file format.

By default, only .<locale>.lor files are tried by loadLocale. Call this to opt in to additional formats. Known names:

  • "po": GNU gettext PO (.po)
  • "xliff": XLIFF 1.2 / 2.x (.xliff, .xlf)
  • "csv": CSV / TSV (.csv, .tsv)

Unknown names are accepted silently (forward-compat for future formats).

Malformed files in an enabled format (e.g. broken XML in a .xliff, a .po with an unterminated quoted string) surface as loreline.Error out of loadLocale, caught via try/catch in sync mode, or via Loreline.lastError() after a callback fires with null in async mode.

Name Type Description
name String The format identifier (see above)
enabled Bool True to enable the format, false to disable
generateTranslationFile(script: Script, ?existing: Map, ?format: String, ?locale: String): String

Generates a translation file body for the given source script.

Each translatable string in the source that has an #id marker becomes one entry in the output. If existing is provided (typically the result of extractTranslations on a previously-saved translation file), entries already filled in there are preserved verbatim; otherwise each entry seeds with the source text.

Companion to the loreline translate ... --lang xx CLI command.

Name Type Default Description
script Script The parsed source script
existing Map (optional) (optional) Existing translations to preserve when merging
format String (optional)
locale String (optional)
Returns Description
String The translation file body as a string, ready to write to disk
insertLocalizationKeys(content: String, script: Script, ?includeImports: Bool = true, ?reservedIds: Map): String

Inserts #id markers after every translatable string in content that doesn't already have one. script must be the AST parsed from the same content. Returns the rewritten content.

When includeImports is false, imported scripts are skipped, their byte offsets refer to other files' contents and would corrupt content. Tooling that walks imports externally should pass false.

When reservedIds is provided, it's used (and mutated) as the shared existing-IDs set across calls, useful for coordinating ID generation across multiple per-file invocations so that file B's auto-IDs avoid every ID already in file A. Existing IDs from this file's hash comments are added to the map; newly-generated IDs are added too.

Equivalent to the --auto-ids flag of the loreline translate CLI.

Name Type Default
content String
script Script
includeImports Bool true
reservedIds Map (optional)
Returns
String
collectHashIds(content: String, ?out: Map): Map

Lex-only scan of content for every hash-comment identifier (#xxxx). Cheap compared to a full parse. Runs the lexer over the text and pulls out every CommentHash payload. Use to build project-wide reserved-IDs registries.

Fills and returns out (or a fresh map when out is null).

Name Type Default
content String
out Map (optional)
Returns
Map
removeLocalizationKeys(content: String, script: Script): String

Strips every #id marker emitted by insertLocalizationKeys (or authored manually). The inverse operation. Returns the rewritten content. Equivalent to the --clear flag of the loreline translate CLI.

Name Type
content String
script Script
Returns
String
extractTranslatableEntries(script: Script): Array<AnonStruct>

Returns every #id-tagged translatable string in script paired with its id. Strings WITHOUT an #id marker are filtered out. Use hasUntaggedTranslatableStrings to detect those.

Name Type
script Script
Returns
Array
hasUntaggedTranslatableStrings(script: Script): Bool

Returns true if script contains at least one translatable string (text statement, dialogue, or choice option) that has no #id hash comment. Non-mutating, purely an AST inspection. Used by tooling to gate "add tags?" prompts before generating translation files.

Name Type
script Script
Returns
Bool
print(script: Script, ?indent: String, ?newline: String): String

Prints a parsed script back into Loreline source code.

Name Type Default Description
script Script The parsed script (result from parse())
indent String (optional) The indentation string to use (defaults to two spaces)
newline String (optional) The newline string to use (defaults to "\n")
Returns Description
String The printed source code as a string
update(delta: Float): Void

Ticks pending wait() timers. Call this from your game loop every frame. The first call enables non-blocking deferred mode for wait() on sys targets; before this is called, wait() falls back to blocking Sys.sleep() (correct for CLI tools).

Name Type Description
delta Float Time elapsed since last frame in seconds

Private Members

relativePath(fromDir: String, toPath: String): String

Computes a relative path from fromDir to toPath, both expected to be normalized absolute paths. Returns a forward-slash-separated relative path.

Name Type
fromDir String
toPath String
Returns
String

Metadata

Name Parameters
:expose -