@datamoc/mw_games 0.8.2 → 0.9.0

package/dist/mwl/grammar.js

@@ -1,3 +1,4 @@
+import JSON5 from 'json5';
 /**
  * The error a malformed MWL document throws, carrying the diagnostic that describes it.
  *
@@ -6,7 +7,7 @@
  * import { parse, MwlSyntaxError } from '@datamoc/mw_games/mwl';
  *
  * try {
- *   parse('[game', 'broken.mwl');
+ *   parse('[{ tag: "game" }]', 'broken.mwl');
  * } catch (error) {
  *   if (error instanceof MwlSyntaxError) console.log(error.diagnostic.code);
  * }
@@ -21,13 +22,16 @@ export class MwlSyntaxError extends Error {
 }
 const directiveNames = new Set(['define', 'enddef', 'arg', 'ifdef', 'ifndef', 'else', 'endif', 'include']);
 /**
- * Expands MWL macros, `#ifdef` blocks and `#include`s into flat source text.
+ * Expands MWL macros, `#ifdef` blocks and `#include`s into flat source text,
+ * then rewrites the `_("...")` gettext marker into a form the JSON5 parser
+ * accepts. The marker keeps working because this pass already runs before
+ * structural parsing, the same reason macros survive a change of grammar.
  *
  * @example
  * ```ts
  * import { preprocess } from '@datamoc/mw_games/mwl';
  *
- * console.log(preprocess('[game]\nschema=0.1\n[/game]'));
+ * console.log(preprocess("[{ tag: 'game', schema: 0.1 }]"));
  * ```
  */
 export function preprocess(source, options = {}) {
@@ -104,152 +108,442 @@ export function preprocess(source, options = {}) {
         throw syntax('MWL_ENDDEF', `macro ${macro.name} is missing #enddef`, options.file, lines.length - 1, lines.at(-1) ?? '');
     if (active.length !== 1)
         throw syntax('MWL_ENDIF', 'conditional is missing #endif', options.file, lines.length - 1, lines.at(-1) ?? '');
-    return expandMacros(output.join('\n'), macros, options);
+    return rewriteGettextMarkers(expandMacros(output.join('\n'), macros, options));
 }
 function expandMacros(source, macros, options) {
-    return source.replace(/\{([^{}]*)\}/g, (whole, inner) => {
-        const parts = splitWords(inner);
-        const definition = macros.get(parts[0]);
-        if (!definition)
-            return whole;
-        let body = definition.body;
-        for (let i = 0; i < definition.parameters.length; i++) {
-            const parameter = definition.parameters[i];
-            const keyword = parts.find((part) => part.startsWith(`${parameter}=`));
-            const value = keyword ? keyword.slice(parameter.length + 1) : (parts[i + 1] ?? '');
-            body = body.replaceAll(`{${parameter}}`, value);
+    let out = '';
+    let index = 0;
+    while (index < source.length) {
+        const stop = skipStringOrComment(source, index);
+        if (stop !== index) {
+            out += source.slice(index, stop);
+            index = stop;
+            continue;
         }
-        return expandMacros(body, macros, options);
-    });
-}
-export function parse(source, file = '<mwl>') {
-    const roots = [];
-    const stack = [];
-    const lines = source.split(/\r?\n/);
-    for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
-        const raw = lines[lineIndex];
-        const line = raw.trim();
-        if (!line || line.startsWith('#'))
+        const character = source[index];
+        if (character !== '{') {
+            out += character;
+            index++;
             continue;
-        const location = { file, line: lineIndex + 1, column: Math.max(1, raw.indexOf(line) + 1) };
-        const opening = /^\[([A-Za-z_][\w-]*)\]$/.exec(line);
-        if (opening) {
-            const node = { tag: opening[1], attributes: {}, children: [], location, gettext: [] };
-            if (stack.length)
-                stack.at(-1).children.push(node);
-            else
-                roots.push(node);
-            stack.push(node);
+        }
+        const close = source.indexOf('}', index + 1);
+        if (close < 0) {
+            out += character;
+            index++;
             continue;
         }
-        const closing = /^\[\/([A-Za-z_][\w-]*)\]$/.exec(line);
-        if (closing) {
-            const node = stack.pop();
-            if (!node || node.tag !== closing[1])
-                throw new MwlSyntaxError({
-                    code: 'MWL_TAG',
-                    message: `mismatched closing tag ${closing[1]}`,
-                    location,
-                    lineText: raw,
-                });
+        const whole = source.slice(index, close + 1);
+        const inner = source.slice(index + 1, close);
+        const parts = splitWords(inner);
+        const definition = macros.get(parts[0]);
+        if (definition) {
+            let body = definition.body;
+            for (let parameterIndex = 0; parameterIndex < definition.parameters.length; parameterIndex++) {
+                const parameter = definition.parameters[parameterIndex];
+                const keyword = parts.find((part) => part.startsWith(`${parameter}=`));
+                const value = keyword ? keyword.slice(parameter.length + 1) : (parts[parameterIndex + 1] ?? '');
+                body = body.replaceAll(`{${parameter}}`, value);
+            }
+            out += expandMacros(body, macros, options);
+        }
+        else if (options.macroPolicy !== 'ignore' && isMacroInvocation(parts[0])) {
+            throw syntaxAt('MWL_MACRO', `unknown macro "${parts[0]}"`, source, options.file, index);
+        }
+        else
+            out += whole;
+        index = close + 1;
+    }
+    return out;
+}
+function isMacroInvocation(name) {
+    return name !== undefined && namePattern.test(name);
+}
+/**
+ * Rewrites `_("text")` to `{"$gettext": "text"}` before the JSON5 parser runs.
+ * The scan skips string literals and `//`/`block` comments, so prose that merely
+ * mentions the marker (a dialogue line about the syntax itself) survives intact.
+ * An `_("...")` the rewrite does not match, such as one with an unquoted string,
+ * is left for the JSON5 parser to reject with its own line and column.
+ */
+function rewriteGettextMarkers(source) {
+    const marker = /^_\(\s*("(?:[^"\\]|\\[\s\S])*"|'(?:[^'\\]|\\[\s\S])*')\s*\)/;
+    let out = '';
+    let index = 0;
+    while (index < source.length) {
+        const stop = skipStringOrComment(source, index);
+        if (stop !== index) {
+            out += source.slice(index, stop);
+            index = stop;
             continue;
         }
-        const attribute = /^([A-Za-z_][\w-]*)\s*=\s*(.*)$/.exec(line);
-        if (attribute && stack.length) {
-            const node = stack.at(-1);
-            const block = readBlockValue(attribute[2], location, lines, lineIndex);
-            if (block) {
-                node.attributes[attribute[1]] = block.text;
-                if (block.gettext)
-                    node.gettext.push(attribute[1]);
-                lineIndex += block.extraLines;
+        const character = source[index];
+        if (character === '_') {
+            const match = marker.exec(source.slice(index));
+            if (match) {
+                out += `{"$gettext": ${match[1]}}`;
+                index += match[0].length;
                 continue;
             }
-            if (isGettext(attribute[2]))
-                node.gettext.push(attribute[1]);
-            node.attributes[attribute[1]] = parseValue(attribute[2], location, raw);
+        }
+        out += character;
+        index++;
+    }
+    return out;
+}
+/** Copies one JSON5 string literal verbatim, escapes included, so the rewrite never edits inside it. */
+function copyJson5String(source, from) {
+    const quote = source[from];
+    let index = from + 1;
+    while (index < source.length) {
+        const character = source[index];
+        if (character === '\\') {
+            index += 2;
             continue;
         }
-        throw new MwlSyntaxError({
-            code: 'MWL_TOKEN',
-            message: 'expected a tag or key=value attribute',
-            location,
-            lineText: raw,
-        });
+        if (character === quote)
+            return index + 1;
+        // A raw newline ends the literal here; the JSON5 parser reports it.
+        if (character === '\n')
+            return index;
+        index++;
     }
-    if (stack.length) {
-        const node = stack.at(-1);
-        throw new MwlSyntaxError({ code: 'MWL_TAG', message: `unclosed tag ${node.tag}`, location: node.location });
+    return index;
+}
+/**
+ * If `index` starts a JSON5 string or a `//`/`` /* `` comment, returns the index just past it;
+ * otherwise returns `index` unchanged. Every hand-rolled scan over raw MWL text (macro
+ * expansion, the gettext rewrite, tag-site collection) shares this, so none of them mistakes a
+ * `{`, `}`, `tag`, or macro name that only appears inside a string or a comment for the real thing.
+ */
+function skipStringOrComment(source, index) {
+    const character = source[index];
+    if (character === '"' || character === "'")
+        return copyJson5String(source, index);
+    const next = source[index + 1];
+    if (character === '/' && (next === '/' || next === '*')) {
+        const end = next === '/' ? source.indexOf('\n', index) : source.indexOf('*/', index + 2);
+        return end < 0 ? source.length : next === '/' ? end : end + 2;
     }
-    return roots;
+    return index;
 }
 /**
- * Reads the `"""..."""` value form, the one that may span lines. Its text is exactly what sits
- * between the delimiters, so wrapped message text survives a round trip; a `"""` block may
- * carry the `_` gettext marker like any other value. Returns null for every other form, which
- * `parseValue` handles on the one line it was given.
+ * Parses MWL source (a top-level array of `{ tag, ...attrs, children }` objects, or the
+ * equivalent named-node sugar such as `{ unit_type: { id: 'hero' } }`)
+ * into nodes. Numbers and booleans become their string form on the node, so the
+ * schema, compiler, and runtime see exactly the strings they always have; the
+ * JSON5 literal only decides what an author types and what a JSON5-aware tool
+ * can check before validation runs.
  */
-function readBlockValue(raw, location, lines, from) {
-    const gettext = /^_\s*"""/.test(raw);
-    const source = gettext ? raw.replace(/^_\s*/, '') : raw;
-    if (!source.startsWith('"""'))
-        return null;
-    let text = source.slice(3);
-    let index = from;
-    let end = text.indexOf('"""');
-    while (end < 0) {
-        index++;
-        if (index >= lines.length)
-            throw new MwlSyntaxError({ code: 'MWL_STRING', message: 'unterminated """ value', location });
-        text += `\n${lines[index]}`;
-        end = text.indexOf('"""');
+export function parse(source, file = '<mwl>') {
+    // The marker rewrite is idempotent, so parsing already-preprocessed source
+    // (the `compile` path) is a no-op while a direct `parse` of authored source
+    // keeps working, the way the old tag parser read `_ "..."` inline.
+    const rewritten = rewriteGettextMarkers(source);
+    if (rewritten.trim() === '')
+        return [];
+    let value;
+    try {
+        value = JSON5.parse(rewritten);
+    }
+    catch (error) {
+        throw json5SyntaxError(error, rewritten, file);
     }
-    if (text.slice(end + 3).trim() !== '')
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new MwlSyntaxError({
+            code: 'MWL_DOCUMENT',
+            message: 'MWL document must be a top-level array of nodes',
+            location: { file, line: 1, column: 1 },
+            lineText: rewritten.split(/\r?\n/)[0] ?? '',
+        });
+    const context = {
+        file,
+        sites: collectTagSites(rewritten, file),
+        cursor: { index: 0 },
+        parent: undefined,
+    };
+    return normalizeNamedDocument(value).map((entry) => toNode(entry, context));
+}
+function normalizeNamedDocument(value) {
+    const nodes = [];
+    for (const entry of value) {
+        const normalized = normalizeNamedNode(entry);
+        if (Array.isArray(normalized))
+            nodes.push(...normalized);
+        else
+            nodes.push(normalized);
+    }
+    return nodes;
+}
+/** Converts schema-neutral `{ tag: { ... } }` sugar into the canonical node envelope. */
+function normalizeNamedNode(value) {
+    if (Array.isArray(value))
+        return value.flatMap((entry) => normalizeNamedNode(entry));
+    if (typeof value !== 'object' || value === null)
+        return value;
+    const record = value;
+    if (typeof record.tag !== 'string') {
+        const keys = Object.keys(record);
+        if (keys.length !== 1 || !namePattern.test(keys[0]))
+            return value;
+        const tag = keys[0];
+        const body = record[tag];
+        if (Array.isArray(body))
+            return body.map((entry) => namedNode(tag, entry));
+        return namedNode(tag, body);
+    }
+    const normalized = { ...record };
+    const children = [];
+    if (Array.isArray(record.children))
+        children.push(...record.children.flatMap((child) => normalizeNamedNode(child)));
+    for (const [key, child] of Object.entries(record)) {
+        if (key === 'tag' || key === 'children' || !namePattern.test(key) || !isNamedChild(child))
+            continue;
+        const entries = Array.isArray(child) ? child : [child];
+        children.push(...entries.map((entry) => namedNode(key, entry)));
+        delete normalized[key];
+    }
+    if (children.length)
+        normalized.children = children;
+    return normalized;
+}
+function namedNode(tag, body) {
+    if (typeof body !== 'object' || body === null || Array.isArray(body))
+        return { tag, value: body };
+    return normalizeNamedNode({ tag, ...body });
+}
+function isNamedChild(value) {
+    return ((typeof value === 'object' && value !== null && !Array.isArray(value) && !('$gettext' in value)) ||
+        (Array.isArray(value) &&
+            value.every((entry) => typeof entry === 'object' && entry !== null && !Array.isArray(entry))));
+}
+function toNode(entry, context) {
+    if (typeof entry !== 'object' || entry === null || Array.isArray(entry))
+        throw new MwlSyntaxError({
+            code: 'MWL_TAG',
+            message: 'MWL node must be an object with a tag',
+            location: context.parent ?? { file: context.file, line: 1, column: 1 },
+        });
+    const record = entry;
+    if (typeof record.tag !== 'string' || !namePattern.test(record.tag))
+        throw new MwlSyntaxError({
+            code: 'MWL_TAG',
+            message: 'MWL node needs a tag name',
+            location: context.parent ?? { file: context.file, line: 1, column: 1 },
+        });
+    const tag = record.tag;
+    const site = locate(context, tag);
+    const location = site.location;
+    const rawChildren = record.children ?? [];
+    if (!Array.isArray(rawChildren))
         throw new MwlSyntaxError({
-            code: 'MWL_STRING',
-            message: 'unexpected text after a """ value',
+            code: 'MWL_TAG',
+            message: `children of [${tag}] must be an array`,
             location,
         });
-    return { text: text.slice(0, end), gettext, extraLines: index - from };
+    const attributes = {};
+    const attributeLocations = {};
+    const valueLocations = {};
+    const gettext = [];
+    for (const [name, raw] of Object.entries(record)) {
+        if (name === 'tag' || name === 'children')
+            continue;
+        attributes[name] = toAttribute(tag, name, raw, location, gettext);
+        const property = site.properties?.get(name);
+        if (property) {
+            attributeLocations[name] = property.location;
+            valueLocations[name] = property.valueLocation;
+        }
+    }
+    const childContext = { ...context, parent: location };
+    const node = {
+        tag,
+        attributes,
+        children: rawChildren.map((child) => toNode(child, childContext)),
+        location,
+        gettext,
+    };
+    Object.defineProperties(node, {
+        attributeLocations: { value: attributeLocations, enumerable: false },
+        valueLocations: { value: valueLocations, enumerable: false },
+    });
+    return node;
+}
+function toAttribute(tag, name, raw, location, gettext) {
+    if (!namePattern.test(name) || name.startsWith('$') || name.startsWith('_'))
+        throw new MwlSyntaxError({
+            code: 'MWL_ATTRIBUTE',
+            message: `unknown attribute "${name}" on [${tag}]`,
+            location,
+        });
+    if (typeof raw === 'string')
+        return raw;
+    if (typeof raw === 'number' && Number.isFinite(raw))
+        return String(raw);
+    if (typeof raw === 'boolean')
+        return raw ? 'true' : 'false';
+    if (typeof raw === 'object' && raw !== null && !Array.isArray(raw)) {
+        const keys = Object.keys(raw);
+        const text = raw.$gettext;
+        if (keys.length === 1 && keys[0] === '$gettext' && typeof text === 'string') {
+            gettext.push(name);
+            return text;
+        }
+    }
+    throw new MwlSyntaxError({
+        code: 'MWL_ATTRIBUTE',
+        message: `attribute "${name}" on [${tag}] must be a string, number, boolean, or _("...")`,
+        location,
+    });
+}
+const namePattern = /^[A-Za-z_][\w-]*$/;
+/** Every authored `tag` object and its direct JSON5 properties, in source order. */
+function collectTagSites(source, file) {
+    const sites = [];
+    const stack = [];
+    for (let index = 0; index < source.length;) {
+        const stop = skipStringOrComment(source, index);
+        if (stop !== index) {
+            index = stop;
+            continue;
+        }
+        const character = source[index];
+        if (character === '{') {
+            const object = { start: index, properties: new Map() };
+            stack.push(object);
+            index++;
+            continue;
+        }
+        if (character === '}') {
+            stack.pop();
+            index++;
+            continue;
+        }
+        const key = /[A-Za-z_$][\w$-]*/y;
+        key.lastIndex = index;
+        const match = key.exec(source);
+        if (!match) {
+            index++;
+            continue;
+        }
+        let colon = match.index + match[0].length;
+        while (/\s/.test(source[colon] ?? ''))
+            colon++;
+        if (source[colon] !== ':') {
+            index = match.index + match[0].length;
+            continue;
+        }
+        let valueStart = colon + 1;
+        while (/\s/.test(source[valueStart] ?? ''))
+            valueStart++;
+        const current = stack.at(-1);
+        if (current) {
+            current.properties.set(match[0], {
+                location: offsetToLocation(source, file, match.index),
+                valueLocation: offsetToLocation(source, file, valueStart),
+            });
+            if (match[0] === 'tag' && (source[valueStart] === '"' || source[valueStart] === "'")) {
+                const stop = copyJson5String(source, valueStart);
+                const literal = source.slice(valueStart, stop);
+                let tag;
+                try {
+                    tag = JSON5.parse(literal);
+                }
+                catch {
+                    tag = undefined;
+                }
+                if (typeof tag === 'string')
+                    sites.push({
+                        tag,
+                        location: offsetToLocation(source, file, match.index),
+                        properties: current.properties,
+                    });
+            }
+        }
+        index = match.index + match[0].length;
+    }
+    return sites;
+}
+function locate(context, tag) {
+    for (let index = context.cursor.index; index < context.sites.length; index++) {
+        if (context.sites[index].tag === tag) {
+            context.cursor.index = index + 1;
+            return context.sites[index];
+        }
+    }
+    return { tag, location: context.parent ?? { file: context.file, line: 1, column: 1 } };
+}
+function offsetToLocation(source, file, offset) {
+    let line = 1;
+    let column = 1;
+    for (let index = 0; index < offset; index++) {
+        if (source[index] === '\n') {
+            line++;
+            column = 1;
+        }
+        else
+            column++;
+    }
+    return { file, line, column };
+}
+function json5SyntaxError(error, source, file) {
+    const lines = source.split(/\r?\n/);
+    const detail = error;
+    const line = typeof detail?.lineNumber === 'number' ? detail.lineNumber : 1;
+    const column = typeof detail?.columnNumber === 'number' ? detail.columnNumber : 1;
+    let message = error instanceof Error ? error.message : String(error);
+    if (message.includes("'_'"))
+        message += ' (write translatable text as _("..."))';
+    return new MwlSyntaxError({
+        code: 'MWL_SYNTAX',
+        message,
+        location: { file, line: Math.max(1, line), column: Math.max(1, column) },
+        lineText: lines[Math.max(1, line) - 1],
+    });
 }
 /**
- * Unquotes one raw attribute value and strips the `_ "..."` gettext marker.
+ * Unquotes one raw attribute value and strips the `_("...")` gettext marker.
  *
  * @example
  * ```ts
  * import { parseValue } from '@datamoc/mw_games/mwl';
  *
- * console.log(parseValue('_ "Hold the line"', { file: 'a.mwl', line: 1, column: 1 })); // 'Hold the line'
+ * console.log(parseValue('_("Hold the line")', { file: 'a.mwl', line: 1, column: 1 })); // 'Hold the line'
  * ```
  */
 export function parseValue(raw, location, lineText = raw) {
-    // The gettext marker is `_` followed by a quoted string. Requiring the
-    // quote is deliberate: values such as `aliasof=_bas` start with an
-    // underscore and must survive unchanged.
-    let value = raw.trim();
-    const marker = /^_\s*"/.exec(value);
-    if (marker)
-        value = value.slice(marker[0].length - 1);
-    if (value.startsWith('"')) {
-        if (!value.endsWith('"') || value.length < 2)
-            throw new MwlSyntaxError({ code: 'MWL_STRING', message: 'unterminated quoted value', location, lineText });
-        return value.slice(1, -1).replaceAll('""', '"');
+    const value = raw.trim();
+    const marker = /^_\(\s*([\s\S]*?)\s*\)$/.exec(value);
+    const literal = marker ? marker[1] : value;
+    if (literal.startsWith('"') || literal.startsWith("'")) {
+        try {
+            const parsed = JSON5.parse(literal);
+            if (typeof parsed === 'string')
+                return parsed;
+        }
+        catch {
+            // Fall through to the syntax error below.
+        }
+        throw new MwlSyntaxError({ code: 'MWL_STRING', message: 'unterminated string value', location, lineText });
     }
+    if (marker)
+        throw new MwlSyntaxError({ code: 'MWL_STRING', message: '_("...") needs a quoted string', location, lineText });
     return value;
 }
 /**
- * True when a raw attribute value carries the gettext marker `_ "..."`.
+ * True when a raw attribute value carries the gettext marker `_("...")`.
  *
  * @example
  * ```ts
  * import { isGettext } from '@datamoc/mw_games/mwl';
  *
- * console.log(isGettext('_ "Hello"')); // true
+ * console.log(isGettext('_("Hello")')); // true
  * console.log(isGettext('Hello')); // false
  * ```
  */
 export function isGettext(raw) {
-    return /^_\s*"/.test(raw.trim());
+    return /^_\(\s*["']/.test(raw.trim());
 }
 function splitWords(value) {
     const result = [];
@@ -282,4 +576,13 @@ function syntax(code, message, file, index, lineText) {
         lineText,
     });
 }
+function syntaxAt(code, message, source, file, offset) {
+    const location = offsetToLocation(source, file ?? '<mwl>', offset);
+    return new MwlSyntaxError({
+        code,
+        message,
+        location,
+        lineText: source.split(/\r?\n/)[location.line - 1],
+    });
+}
 //# sourceMappingURL=grammar.js.map