123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229 |
- export interface MacroTags {
- /**
- * Return the named macro tag's parents array (includes the names of all macros who have registered the tag as a
- * child), or null on failure.
- * @param name Name of the macro tag whose parents array should be returned.
- * @since 2.0.0
- * @example
- * Macro.tags.get("else") // For the standard library, returns: ["if"]
- */
- get(name: string): string[];
- /**
- * Returns whether the named macro tag exists.
- * @param name Name of the macro tag to search for.
- * @since 2.0.0
- */
- has(name: string): boolean;
- }
- export interface MacroArgsArray extends Array<any> {
- /**
- * The current tag's argument string after converting all TwineScript syntax elements into their
- * native JavaScript counterparts. Equivalent in function to <MacroContext>.args.full.
- */
- full: string;
- /**
- * The current tag's unprocessed argument string. Equivalent in function to <MacroContext>.args.raw.
- */
- raw: string;
- }
- export interface MacroContextObject {
- /**
- * Name of the current tag.
- */
- name: string;
- /**
- * The current tag's argument string parsed into an array of discrete arguments.
- * Equivalent in function to <MacroContext>.args.
- */
- args: MacroArgsArray;
- /**
- * The current tag's contents — i.e. the text between the current tag and the next.
- */
- contents: string;
- }
- type ShadowWrapperCallback<T extends any[]> = (this: MacroContext, ...args: T) => void;
- export interface MacroContext {
- /**
- * The argument string parsed into an array of discrete arguments.
- * @since 2.0.0
- */
- args: MacroArgsArray;
- /**
- * The name of the macro.
- * @since 2.0.0
- */
- name: string;
- /**
- * The current output element.
- * @since 2.0.0
- */
- output: DocumentFragment | HTMLElement;
- /**
- * The (execution) context object of the macro's parent, or null if the macro has no parent.
- * @since 2.0.0
- */
- parent: null | object;
- /**
- * The parser instanced that generated the macro call.
- * @since 2.0.0
- */
- parser: unknown;
- /**
- * The text of a container macro parsed into discrete payload objects by tag.
- * @since 2.0.0
- */
- payload: MacroContextObject[];
- /**
- * The macro's definition — created via @see Macro.add()
- * @since 2.0.0
- */
- self: object;
- /**
- * Returns whether any of the macro's ancestors passed the test implemented by the given
- * filter function.
- * @param filter he function used to test each ancestor execution context object, which
- * is passed in as its sole parameter.
- * @since 2.0.0
- */
- contextHas(filter: (context: MacroContextObject) => boolean): boolean;
- /**
- * Returns the first of the macro's ancestors which passed the test implemented by the given
- * filter function or null, if no members pass.
- * @param filter The function used to test each ancestor execution context object, which is
- * passed in as its sole parameter.
- * @since 2.0.0
- */
- contextSelect(filter: (context: MacroContextObject) => boolean): object;
- /**
- * Returns a new array containing all of the macro's ancestors which passed the test implemented
- * by the given filter function or an empty array, if no members pass.
- * @since 2.0.0
- * @param filter
- */
- contextSelectAll(filter: (context: MacroContextObject) => boolean): object[];
- /**
- * Returns a callback function that wraps the given callbacks to provide access to the variable
- * shadowing system.
- * This is only useful if you have an asynchronous callback (such as a button being pressed)
- * that invokes code/content that needs to access variables shadowed by `<<capture>>`.
- * @param callback Executed when the wrapper is invoked. Receives access to variable shadows.
- * @param doneCallback Executed after the main callback returns. Does not have access.
- * @param startCallback Executed before the main callback is invoked. Does not have access.
- * @since 2.14.0
- */
- createShadowWrapper<T extends any[]>(
- callback: ShadowWrapperCallback<T>,
- doneCallback?: ShadowWrapperCallback<T>,
- startCallback?: ShadowWrapperCallback<T>,
- ): (...args: T) => void;
- /**
- * Renders the message prefixed with the name of the macro and returns false.
- * @param message The error message to output.
- * @since 2.0.0
- */
- error(message: string): false;
- }
- export interface MacroDefinition {
- handler: (this: MacroContext) => void;
- /**
- * Having this property signifies that this is a container macro
- * This should be an array of child tag names or `null`
- * @since 2.0.0
- */
- tags?: string[] | null | undefined;
- /**
- * Disables parsing argument strings into discrete arguments.
- * This is used by macros that only use the raw/full argument strings.
- * `true` to affect all tags
- * Or Array of tags to affect
- * @since 2.0.0
- */
- skipArgs?: boolean | undefined | string[];
- }
- export interface MacroAPI {
- /**
- * Add new macro(s).
- * @param name Name, or array of names, of the macro(s) to add.
- * @param definition Definition of the macro(s) or the name of an existing macro whose definition to copy.
- * Definition object:
- * A macro definition object should have some of the following properties (only handler is absolutely required):
- * skipArgs: (optional, boolean) Disables parsing argument strings into discrete arguments. Used by macros which
- * only use the raw/full argument strings.
- * tags: (optional, null | string array) Signifies that the macro is a container macro—i.e. not self-closing. An
- * array of the names of the child tags, or null if there are no child tags.
- * handler: (function) The macro's main function. It will be called without arguments, but with its this set to a
- * macro context object.
- * @param deep Enables deep cloning of the definition. Used to give macros separate instances of the same
- * definition.
- * @since 2.0.0
- * @example
- * // Example of a very simple/naive <<if>>/<<elseif>>/<<else>> macro implementation.
- * Macro.add('if', {
- * skipArgs: true,
- * tags: ['elseif', 'else'],
- * handler: function () {
- * try {
- * for (var i = 0, len = this.payload.length; i < len; ++i) {
- * if (
- * this.payload[i].name === 'else' ||
- * !!Scripting.evalJavaScript(this.payload[i].args.full)
- * ) {
- * jQuery(this.output).wiki(this.payload[i].contents);
- * break;
- * }
- * }
- * }
- * catch (ex) {
- * return this.error('bad conditional expression: ' + ex.message);
- * }
- * }
- * });
- */
- add(name: string | string[], definition: MacroDefinition, deep?: boolean): void;
- /**
- * Remove existing macro(s).
- * @param name Name, or array of names, of the macro(s) to remove.
- * @since 2.0.0
- */
- delete(name: string | string[]): void;
- /**
- * Return the named macro definition, or null on failure.
- * @param name Name of the macro whose definition should be returned.
- * @since 2.0.0
- */
- get(name: string): MacroDefinition;
- /**
- * Returns whether the named macro exists.
- * @param name Name of the macro to search for.
- * @since 2.0.0
- */
- has(name: string): boolean;
- /**
- * @since 2.0.0
- */
- tags: MacroTags;
- }
- export {};
|