loreline 0.10.0 → 0.11.0

package/README.md

@@ -61,24 +61,28 @@ For loreline-lua, run `--lua` first.
 Python, Lua, PHP, JS, JVM and GDScript tests require running the corresponding build step first (e.g. `node ./setup --py` before Python tests). GDScript tests also need a Godot 4 binary on the PATH (or pointed to by the `GODOT_BIN` environment variable).
 
 ```sh
-node run test ./test                    # Run Neko tests only
-python3 py/test-runner.py ./test        # Run Python tests only
-lua5.4 lua/test-runner.lua ./test       # Run Lua tests only
-php php/test-runner.php ./test          # Run PHP tests only
-php build/php-cli/index.php test ./test # Run PHP CLI tests only
-npx tsx js/test-runner.ts ./test        # Run JS tests only
+node run test ./test --internal                    # Run Neko tests only
+python3 py/test-runner.py ./test                   # Run Python tests only
+lua5.4 lua/test-runner.lua ./test                  # Run Lua tests only
+php php/test-runner.php ./test                     # Run PHP tests only
+php build/php-cli/index.php test ./test --internal # Run PHP CLI tests only
+npx tsx js/test-runner.ts ./test                   # Run JS tests only
 java -cp jvm/loreline.jar:build/jvm/test TestRunner ./test  # Run JVM tests only
-node ./setup --gdscript-test            # Run GDScript tests only (headless Godot)
-node ./setup --test                     # Build and run all test suites (Neko + C# + C# AOT + C# (with generics) + JS + C++ lib + Python + Lua + PHP + PHP CLI + JVM)
+node ./setup --gdscript-test                       # Run GDScript tests only (headless Godot)
+node ./setup --test                                # Build and run all test suites (Neko + C# + C# AOT + C# (with generics) + JS + C++ lib + Python + Lua + PHP + PHP CLI + JVM)
 ```
 
-### How Loreline is authored
+Each `test/*.lor` file ends with a `<test>` YAML block describing its test cases (`choices`, `beat`, `expected`, ...). `saveAtDialogue` and `saveAtChoice` take one index or a list of indices (`saveAtDialogue: [2, 5]`), counted over an uninterrupted run: at each one, the runner saves, restores in a new interpreter and continues, so the saved event shows twice in `expected`.
 
-Loreline's runtime is essentially handwritten, so the code you embed when depending on it can be considered almost entirely free of AI-generated code.
+On top of the explicit cases, the Haxe runners (Neko, C# with generics, PHP CLI, GDScript) run a save sweep: every test case is saved and restored at each of its events (and at every pair of events in files with insertions), and must give the uninterrupted output with the saved events shown twice. Files relying on randomness are skipped, and a test case can opt out with `saveSweep: false`.
 
-That said, I used coding assistants for peripheral work: unit-tests, scaffolding, debugging, documenting the code, continuous integration, and help in making surgical changes to the runtime. These improve the overall reliability and quality of Loreline, make sure that anything tested won't break in the future, and give me more bandwidth for the more creative, interesting and trickier parts of Loreline itself. I weighed that this targeted use would benefit the users of the project, and I take entire responsibility for all the code and design choices in this repository.
+## How Loreline is authored
 
-For some context on where I stand, I don't endorse the use of generative AI as a general rule: I do care a lot about writing code myself and human authorship in general, and I also don't use any AI-generated assets or content for the games I make.
+Loreline's core runtime (its lexer, parser, interpreter and the overall architecture that ties them together) has been written by hand. The Loreline language is also the result of many design iterations that are essentially human authored.
+
+That said, I have used coding assistants for unit tests, scaffolding, debugging, documenting the code, continuous integration, fixes to the runtime and help implementing new features. All of this improves the overall reliability and quality of Loreline and makes sure that anything tested won't break in the future. I considered that this use would benefit the users of the project, and I take full responsibility for all the code and design choices in this repository.
+
+For some context on where I stand, I don't endorse the use of generative AI as a general rule: I care a lot about writing code myself, especially when used as a creative medium, as well as human authorship in general. I reject the use of any AI-generated asset or content in the games I make.
 
 ## License
 

package/js/loreline.d.ts

@@ -13,7 +13,7 @@ export type ImportsFileHandler = (path: string, callback: (data: string) => void
 export type ImportsErrorHandler = (error: Error) => void;
 
 /**
- * Tokens type
+ * List of tokens produced by the lexer.
  */
 export type Tokens = Array<any>;
 
@@ -24,7 +24,7 @@ export type SaveData = any;
 
 /**
  * Opaque type for a translations map.
- * Obtained from `Loreline.extractTranslations()` and passed to `InterpreterOptions.translations`.
+ * Obtained from `Loreline.loadLocale()` and passed to `InterpreterOptions.translations`.
  */
 export type Translations = any;
 
@@ -47,6 +47,17 @@ export interface Error {
      */
     stack: Array<any>;
 
+    /**
+     * The English template the message was made from, when tools can show it
+     * in another language. The message itself is always in English.
+     */
+    template?: string | null;
+
+    /**
+     * The parameters of the template, by name.
+     */
+    params?: any;
+
     /**
      * Converts the error to a human-readable string.
      * @return Formatted error message with position
@@ -54,6 +65,35 @@ export interface Error {
     toString(): string;
 }
 
+/**
+ * The texts the Loreline tools show, in English or in other languages. Errors
+ * keep their English message for games; a tool can show them in French by
+ * loading `loreline-fr.js` and asking `errorText` for French.
+ *
+ * ```ts
+ * import { I18n } from './loreline.js';
+ * import fr from './loreline-fr.js';
+ * I18n.registerObject('fr', fr);
+ * const text = I18n.errorText(error, 'fr');
+ * ```
+ */
+export class I18n {
+    /** The language of the texts: `en` or `fr`. */
+    static locale: string;
+
+    /** Adds the translations of a table, `{ english: translated }`, for a language. */
+    static registerObject(locale: string, table: { [english: string]: string }): void;
+
+    /** The message of an error in a language, from its template, or its English message. */
+    static errorText(error: Error, locale?: string): string;
+
+    /** A template in a language, its `{name}` parameters filled. */
+    static format(template: string, params?: any, locale?: string): string;
+
+    /** The language for a language tag: `fr-CA` gives `fr`, anything not French gives `en`. */
+    static fromTag(tag: string | null): string;
+}
+
 /**
  * Represents a position within source code, tracking line number, column, and offset information.
  * Used throughout the compiler to pinpoint locations of tokens, nodes, and error messages.
@@ -65,14 +105,14 @@ export interface Position {
     line: number;
 
     /**
-     * The column number in the source code, starting from 1.
-     * Represents the character position within the current line.
+     * The column in the source code, starting from 1, in UTF-16 units, those
+     * of a JavaScript string: a character above U+FFFF counts for two.
      */
     column: number;
 
     /**
-     * The absolute character offset from the start of the source code.
-     * Used for precise positioning and span calculations.
+     * The offset from the start of the source code, in UTF-16 units: an index
+     * into the source as a JavaScript string.
      */
     offset: number;
 
@@ -90,7 +130,7 @@ export interface Position {
 }
 
 /**
- * Represents a choice option presented to the user.
+ * Represents a choice option presented to the player.
  */
 export interface ChoiceOption {
     /**
@@ -124,7 +164,11 @@ export interface TextTag {
     value: string;
 
     /**
-     * The offset in the text where this tag appears.
+     * Where the tag appears in the text, in characters (Unicode code points)
+     * from its start, the same on every target. A JavaScript string counts
+     * UTF-16 units instead, where a character above U+FFFF, such as most emoji,
+     * takes two: split the text with `[...text]` to index it in characters, for
+     * example `[...text].slice(0, tag.offset).join('')` for the text before the tag.
      */
     offset: number;
 }
@@ -147,7 +191,7 @@ export type DialogueHandler = (interpreter: Interpreter, character: string | nul
  *
  * @param interpreter The interpreter instance
  * @param options The available choice options
- * @param callback Function to call with the index of the selected choice
+ * @param callback Function to call with the index of the selected option
  */
 export type ChoiceHandler = (interpreter: Interpreter, options: Array<ChoiceOption>, callback: (index: number) => void) => void;
 
@@ -174,15 +218,20 @@ export interface InterpreterOptions {
     strictAccess?: boolean;
 
     /**
-     * A custom instantiator to create fields objects.
+     * A custom instantiator for the objects that hold fields.
      */
     customCreateFields?: (interpreter: Interpreter, type: string, node: Node) => any;
 
     /**
-     * Optional translations map for localization.
-     * Built from a parsed translation file using `Loreline.extractTranslations()`.
+     * Optional translations map for localization, as `Loreline.loadLocale()` returns it.
      */
     translations?: Translations;
+
+    /**
+     * If set to true, the interpreter prepares its caches when it is created,
+     * before the script starts, like `Interpreter.prepareCaches()`.
+     */
+    prepareCaches?: boolean;
 }
 
 /**
@@ -191,7 +240,7 @@ export interface InterpreterOptions {
 export type FunctionsMap = Record<string, Function>;
 
 /**
- * The main public API for Loreline runtime.
+ * The main public API for the Loreline runtime.
  * Provides easy access to the core functionality for parsing and running Loreline scripts.
  */
 export class Loreline {
@@ -203,7 +252,7 @@ export class Loreline {
      *
      * @param input The Loreline script content as a string (`.lor` format)
      * @param filePath Optional file path of the input being parsed. If provided, requires `handleFile` as well.
-     * @param handleFile Optional file handler to read imports. If that handler is asynchronous, then `parse()` will return null and `callback` argument should be used
+     * @param handleFile Optional file handler used to read imports. If it is asynchronous, `parse()` returns null and you should use the `callback` argument instead.
      * @param callback If provided, will be called with the resulting script as argument. Mostly useful when reading file imports asynchronously
      * @returns The parsed script as an AST `Script` instance (if loaded synchronously)
      * @throws If the script contains syntax errors or other parsing issues
@@ -219,7 +268,7 @@ export class Loreline {
      *
      * @param script The parsed script (result from `parse()`)
      * @param handleDialogue Function called when dialogue text should be displayed
-     * @param handleChoice Function called when player needs to make a choice
+     * @param handleChoice Function called when the player needs to make a choice
      * @param handleFinish Function called when script execution completes
      * @param beatName Optional name of a specific beat to start from (defaults to first beat)
      * @param options Additional options
@@ -235,18 +284,18 @@ export class Loreline {
     ): Interpreter;
 
     /**
-     * Resumes a previously saved Loreline script from its saved state.
+     * Resumes a Loreline script from a 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.
      *
      * @param script The parsed script (result from `parse()`)
      * @param handleDialogue Function called when dialogue text should be displayed
-     * @param handleChoice Function called when player needs to make a choice
+     * @param handleChoice Function called when the player needs to make a choice
      * @param handleFinish Function called when script execution completes
      * @param saveData The saved game data (typically from `interpreter.save()`)
      * @param beatName Optional beat name to override where to resume from
-     * @param options Optional options to configure interpreter behavior
+     * @param options Optional interpreter options
      * @returns The interpreter instance that is running the script
      */
     static resume(
@@ -260,13 +309,13 @@ export class Loreline {
     ): Interpreter;
 
     /**
-     * Extracts translations from a parsed translation script.
+     * Extracts the translations of a parsed translation file, by their `#id`.
      *
-     * Given a translation file parsed with `parse()`, this returns a translations map
-     * that can be passed as `options.translations` to `play()` or `resume()`.
+     * To play a story in a language, use `loadLocale()` instead: the interpreter
+     * looks translations up by file, which this map doesn't hold.
      *
      * @param script The parsed translation script (result from `parse()` on a `.XX.lor` file)
-     * @returns A translations map to pass as `InterpreterOptions.translations`
+     * @returns The translations of the file, by `#id`
      */
     static extractTranslations(script: Script): Translations;
 
@@ -298,7 +347,7 @@ export class Loreline {
     ): Translations | null;
 
     /**
-     * Enable or disable runtime support for an alternate translation file format.
+     * Enables or disables runtime support for an alternative translation file format.
      *
      * By default only `.<locale>.lor` files are tried by `loadLocale`. Call
      * this to opt in to additional formats:
@@ -319,13 +368,23 @@ export class Loreline {
      *
      * In async mode (callback supplied) the callback fires with `null` on
      * failure and this method tells you what went wrong. In sync mode the
-     * call throws, and this is set to the same error so it can be inspected
-     * after the catch.
+     * call throws, and this method returns the same error so it can be
+     * inspected after the catch.
      *
      * Not thread-safe: read immediately after the call returns.
      */
     static lastError(): Error | null;
 
+    /**
+     * The names of the functions a script declares without a body, imports
+     * included. The app running the story must provide them in the `functions`
+     * option: calling one it doesn't provide is an error. A tool that plays
+     * scripts on their own, such as a preview, can provide stand-ins for these.
+     *
+     * @param script The parsed script (result from `parse()`)
+     */
+    static externalFunctions(script: Script): string[];
+
     /**
      * Prints a parsed script back into Loreline source code.
      *
@@ -376,9 +435,11 @@ export class Interpreter {
     /**
      * Restores the interpreter state from a SaveData object.
      * This allows resuming execution from a previously saved state.
+     * Live child interpreters are disposed, and saved children can then be
+     * continued with `resumeSpawn()`.
      *
      * @param saveData The SaveData object containing the serialized state
-     * @throws RuntimeError If the save data version is incompatible
+     * @throws RuntimeError If the save data version is incompatible, or if called on a child interpreter
      */
     restore(saveData: SaveData): void;
 
@@ -388,6 +449,83 @@ export class Interpreter {
      */
     resume(): void;
 
+    /**
+     * Key of this interpreter when it was spawned from another one, null for a root interpreter.
+     */
+    readonly key: string | null;
+
+    /**
+     * Whether this interpreter is a root interpreter (not spawned from another one).
+     */
+    isRoot(): boolean;
+
+    /**
+     * Spawns a new child interpreter that shares everything with this one (script, state,
+     * characters, functions) except the playhead. The child is not started: call `start()`
+     * on it. Any live child using the same key is disposed first, and a restored flow still
+     * pending for that key is discarded (use `resumeSpawn()` to continue it instead).
+     *
+     * Calling `save()` on any interpreter of the family saves the shared state and every playhead.
+     *
+     * A function stored as a value in shared state stays bound to the interpreter that
+     * read it: calling it from another interpreter reads the playhead of the first one.
+     * Call functions by name instead of storing them in shared state.
+     *
+     * @param key Identifies the child, notably to resume it after a restore
+     * @param handleDialogue Dialogue handler of the child (defaults to the one of this interpreter)
+     * @param handleChoice Choice handler of the child (defaults to the one of this interpreter)
+     * @param handleFinish Finish handler of the child (defaults to the one of this interpreter)
+     * @returns The child interpreter
+     */
+    spawn(key: string, handleDialogue?: DialogueHandler | null, handleChoice?: ChoiceHandler | null, handleFinish?: FinishHandler | null): Interpreter;
+
+    /**
+     * Rebuilds a child interpreter from the flow saved under the given key, after `restore()`
+     * was called on the root interpreter (or after `Loreline.resume()`). The child is not
+     * resumed yet: call `resume()` on it.
+     *
+     * @param key The key the child had when it was saved (see `resumableSpawnKeys()`)
+     * @param handleDialogue Dialogue handler of the child (defaults to the one of this interpreter)
+     * @param handleChoice Choice handler of the child (defaults to the one of this interpreter)
+     * @param handleFinish Finish handler of the child (defaults to the one of this interpreter)
+     * @returns The restored child interpreter
+     * @throws RuntimeError If no restored flow is pending for this key
+     */
+    resumeSpawn(key: string, handleDialogue?: DialogueHandler | null, handleChoice?: ChoiceHandler | null, handleFinish?: FinishHandler | null): Interpreter;
+
+    /**
+     * Keys of the child interpreters read by the last restore that were not
+     * resumed with `resumeSpawn()` (nor replaced with `spawn()`) yet.
+     */
+    resumableSpawnKeys(): Array<string>;
+
+    /**
+     * Reseeds the random generator shared by this interpreter, its root and every child.
+     * The generator is part of save data, so a restored game draws the same random values
+     * as it would have without the save. Call this after a restore to break that on purpose.
+     *
+     * @param seed The seed of the new sequence. Without one, a seed is taken from the clock.
+     */
+    seedRandom(seed?: number | null): void;
+
+    /**
+     * Builds now what the interpreter would otherwise build the first time it needs it,
+     * so that the cost is paid at a chosen moment, like a loading screen, rather than
+     * during play: for now, what each `when` block needs to pick a rule, which takes a
+     * moment on blocks of thousands of rules. Optional, it never changes what the script
+     * plays, and a second call only builds what is missing. Interpreters spawned from
+     * this one share these caches. See also the `prepareCaches` option.
+     */
+    prepareCaches(): void;
+
+    /**
+     * Stops a child interpreter for good: its playhead is cleared, it is not part of
+     * saves anymore, and callbacks it handed out become no-ops.
+     *
+     * @throws RuntimeError If called on a root interpreter
+     */
+    dispose(): void;
+
     /**
      * Gets a character by name.
      *
@@ -470,7 +608,7 @@ export class Interpreter {
 }
 
 /**
- * An object to store a Int64 from two `high` and `low` number values.
+ * An object that stores an Int64 as two numbers, `high` and `low`.
  */
 export interface Int64 {
     /**
@@ -558,6 +696,14 @@ export class Script extends Node {
      */
     filePath: string | null;
 
+    /**
+     * Gets a field of the story's metadata block, as written in the script.
+     *
+     * @param name The name of the field to get
+     * @return The field value or null if not found
+     */
+    getMetadataField(name: string): any;
+
     /**
      * Reconstructs a Script from a JSON representation.
      * @param json The JSON object (as returned by script.toJson())
@@ -567,8 +713,8 @@ export class Script extends Node {
 }
 
 /**
- * Base interface to hold loreline values
- * This interface allows to map loreline object fields to game-specific objects.
+ * Base interface for objects that hold Loreline values.
+ * It lets you map Loreline object fields to game-specific objects.
  */
 export interface Fields {
     /**
@@ -577,12 +723,12 @@ export interface Fields {
     lorelineCreate(interpreter: Interpreter): void;
 
     /**
-     * Get the value associated to the given field key
+     * Gets the value associated with the given field key
      */
     lorelineGet(interpreter: Interpreter, key: string): any;
 
     /**
-     * Set the value associated to the given field key
+     * Sets the value associated with the given field key
      */
     lorelineSet(interpreter: Interpreter, key: string, value: any): void;