@duet3d/monacotokens 3.7.0-alpha.11 → 3.7.0-alpha.13

package/dist/gcodes/index.d.ts

@@ -2,8 +2,11 @@
  * One enumerated value of a parameter (e.g. "1" for G1 H meaning "Stop on endstop")
  */
 export interface GcodeParameterValue {
-    /** Literal value as it appears in source (e.g. "0", "1", "-1") */
-    value: string;
+    /**
+     * Literal value as it appears in source (e.g. "0", "1", "-1"). An array lists equivalent literals that mean
+     * the same thing, e.g. M669 K accepts both the kinematics name and its legacy number ("coreXY" and "1").
+     */
+    value: string | string[];
     /** Human-readable meaning */
     description: string;
 }
@@ -31,6 +34,23 @@ export interface GcodeUnprecedentedParameter {
     /** Description shown in the tooltip when this position is active */
     description: string;
 }
+/**
+ * Description of a parameter that exists once per machine axis (e.g. the per-axis speed limits of M203). Instead of
+ * listing X/Y/Z/U/... explicitly, a code carries a single `axisParameter` that the completion provider expands into
+ * one `GcodeParameter` per axis at runtime, so the suggestion list matches the machine that is actually connected.
+ */
+export interface GcodeAxisParameter {
+    /** Description shown for each generated axis parameter. The placeholder `{axis}` is replaced with the axis letter. */
+    description: string;
+    /** Optional enumeration of valid values, shared by every generated axis parameter */
+    values?: GcodeParameterValue[];
+    /**
+     * Whether the parameter list follows the live machine configuration. Defaults to `true`: expand to the axes the
+     * connected machine reports (falling back to the standard letters when no machine is connected). Set to `false`
+     * for axis-defining codes (e.g. M584, M669) that must offer every standard axis letter regardless of configuration.
+     */
+    dynamic?: boolean;
+}
 /**
  * Description of one G/M/T-code (RRF dialect)
  */
@@ -45,6 +65,8 @@ export interface GcodeInfo {
     unprecedentedParameter?: GcodeUnprecedentedParameter;
     /** Parameter letters this code understands */
     parameters: GcodeParameter[];
+    /** Per-axis parameter expanded into one entry per configured axis at completion time (e.g. M203 speed limits) */
+    axisParameter?: GcodeAxisParameter;
     /** If set, this code is deprecated; the string is shown as the reason */
     deprecated?: string;
 }

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from "./monaco-menu";
 export * from "./gcodes";
 export * from "./expressions";
 export * from "./objectmodel/machine-context";
+export * from "./objectmodel/axes";
 export * from "./gcodes/local-variables";
 export * from "./objectmodel/deprecations";
 export * from "./objectmodel/enums";

package/dist/index.js

@@ -4,6 +4,7 @@ export * from "./monaco-menu";
 export * from "./gcodes";
 export * from "./expressions";
 export * from "./objectmodel/machine-context";
+export * from "./objectmodel/axes";
 export * from "./gcodes/local-variables";
 export * from "./objectmodel/deprecations";
 export * from "./objectmodel/enums";

package/dist/objectmodel/axes.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Supported axis letters, mirroring `Axis.Letters` in DuetAPI (DuetSoftwareFramework). This is the canonical set
+ * of identifiers RepRapFirmware accepts for an axis. Kept in sync by hand - update it if DuetAPI gains new letters.
+ */
+export declare const ALL_AXIS_LETTERS: readonly string[];
+/**
+ * Axis letters offered by completion when the live machine configuration is unavailable (no machine connected) or
+ * when an axis parameter is non-dynamic (axis-defining codes such as M584 that may reference axes which do not
+ * exist yet). Restricted to the three axes every standard machine has; additional axes (U, V, W, ...) are surfaced
+ * dynamically from the connected machine's object model, and any axis can still be typed manually.
+ */
+export declare const DEFAULT_AXIS_LETTERS: readonly string[];

package/dist/objectmodel/axes.js

@@ -0,0 +1,18 @@
+/**
+ * Supported axis letters, mirroring `Axis.Letters` in DuetAPI (DuetSoftwareFramework). This is the canonical set
+ * of identifiers RepRapFirmware accepts for an axis. Kept in sync by hand - update it if DuetAPI gains new letters.
+ */
+export const ALL_AXIS_LETTERS = [
+    "X", "Y", "Z",
+    "U", "V", "W",
+    "A", "B", "C", "D",
+    "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m",
+    "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z"
+];
+/**
+ * Axis letters offered by completion when the live machine configuration is unavailable (no machine connected) or
+ * when an axis parameter is non-dynamic (axis-defining codes such as M584 that may reference axes which do not
+ * exist yet). Restricted to the three axes every standard machine has; additional axes (U, V, W, ...) are surfaced
+ * dynamically from the connected machine's object model, and any axis can still be typed manually.
+ */
+export const DEFAULT_AXIS_LETTERS = ["X", "Y", "Z"];

package/dist/providers.js

@@ -1,12 +1,133 @@
-import { gcodeData, findGcode } from "./gcodes";
+import { gcodeData, findGcode as findGcodeStatic } from "./gcodes";
 import { expressionData } from "./expressions";
 import { getMachineContext } from "./objectmodel/machine-context";
+import { ALL_AXIS_LETTERS, DEFAULT_AXIS_LETTERS } from "./objectmodel/axes";
 import { getLocalVariables } from "./gcodes/local-variables";
 import { getMemberDeprecation, getPathDeprecation } from "./objectmodel/deprecations";
 import { getEnumValuesForPath } from "./objectmodel/enums";
 // Re-export the runtime-context helpers so consumers (Vue DWC, React DuetWebUI, ...) can install a context
 // without adding a separate import path
 export { getMachineContext, onMachineContextChange } from "./objectmodel/machine-context";
+/**
+ * Expand a code's `axisParameter` into one concrete `GcodeParameter` per axis letter. Dynamic parameters (the
+ * default) follow the connected machine's configured, visible axes and fall back to the standard letters when no
+ * machine is connected; non-dynamic parameters always offer the standard letters, for axis-defining codes such as
+ * M584/M669 that may reference axes which do not exist yet.
+ */
+function expandAxisParameter(axisParameter) {
+    let letters = DEFAULT_AXIS_LETTERS;
+    if (axisParameter.dynamic !== false) {
+        const axes = getMachineContext()?.model?.move?.axes;
+        const configured = axes
+            ? axes.filter(a => !!a && a.visible !== false && typeof a.letter === "string" && a.letter.length === 1).map(a => a.letter)
+            : [];
+        if (configured.length > 0) {
+            letters = configured;
+        }
+    }
+    return letters.map(letter => ({
+        letter,
+        description: axisParameter.description.replace(/\{axis\}/g, letter),
+        values: axisParameter.values
+    }));
+}
+/**
+ * Resolve a static code entry against the live machine context, expanding any `axisParameter` into concrete
+ * per-axis parameters placed ahead of the fixed parameters. Returns the entry unchanged when it has no axis
+ * parameter, so every caller can treat the result like a plain `GcodeInfo`.
+ */
+function findGcode(code) {
+    const info = findGcodeStatic(code);
+    if (!info || !info.axisParameter) {
+        return info;
+    }
+    return { ...info, parameters: [...expandAxisParameter(info.axisParameter), ...info.parameters] };
+}
+/**
+ * Canonicalise a parameter/axis token to the letter RepRapFirmware actually uses. RRF folds bare command
+ * letters to upper case, so `a` addresses axis `A`; a leading apostrophe escapes a lower-case axis, so `'a`
+ * addresses axis `a`. The token passed in may carry that leading apostrophe.
+ */
+function canonicalAxisLetter(token) {
+    return token.startsWith("'") ? token.slice(1).toLowerCase() : token.toUpperCase();
+}
+/**
+ * Render a canonical parameter letter the way it must be written in G-code: a lower-case axis needs the leading
+ * apostrophe (otherwise RRF would fold it to upper case), every other letter is written as-is.
+ */
+function gcodeAxisToken(letter) {
+    return /[a-z]/.test(letter) ? "'" + letter : letter;
+}
+/** Build the per-axis parameter for one axis letter from a code's axisParameter, or undefined when the letter is not a supported axis or the code has no axis parameter. */
+function makeAxisParameter(info, letter) {
+    if (!info.axisParameter || !ALL_AXIS_LETTERS.includes(letter)) {
+        return undefined;
+    }
+    return {
+        letter,
+        description: info.axisParameter.description.replace(/\{axis\}/g, letter),
+        values: info.axisParameter.values
+    };
+}
+/**
+ * Resolve a single parameter for hover and signature use from a canonical letter (see {@link canonicalAxisLetter}).
+ * Matches a fixed parameter or an axis already expanded for the connected machine, and otherwise builds the
+ * parameter on the fly for any supported axis letter - so hovering or typing an axis the machine is not configured
+ * with still surfaces its documentation. This is wider than the completion suggestion list and the parameter
+ * summary, which only offer the configured axes.
+ */
+function lookupParameter(info, letter) {
+    const found = info.parameters.find(p => p.letter === letter);
+    return found ?? makeAxisParameter(info, letter);
+}
+/**
+ * Collect the canonical parameter letters present at the top level of a code's argument segment, in order. Letters
+ * inside "..." strings or {...} expressions are skipped because they belong to a value, not to a parameter - e.g.
+ * the `g` in `M98 P"check-filament.g"` and any argument passed on to a macro must not be mistaken for parameters.
+ * A leading apostrophe is honoured so a lower-case axis (`'a`) stays distinct from the upper-case letter.
+ */
+function scanParameterLetters(segment) {
+    const letters = [];
+    let inString = false;
+    let braceDepth = 0;
+    for (let i = 0; i < segment.length; i++) {
+        const ch = segment[i];
+        if (inString) {
+            if (ch === "\"") {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === "\"") {
+            inString = true;
+            continue;
+        }
+        if (ch === "{") {
+            braceDepth++;
+            continue;
+        }
+        if (ch === "}") {
+            if (braceDepth > 0) {
+                braceDepth--;
+            }
+            continue;
+        }
+        if (braceDepth > 0) {
+            continue;
+        }
+        if (ch === ";") {
+            break;
+        }
+        if (/[A-Za-z]/.test(ch)) {
+            const prev = i > 0 ? segment[i - 1] : "";
+            const next = i + 1 < segment.length ? segment[i + 1] : "";
+            if (!/[A-Za-z]/.test(prev) && !/[A-Za-z]/.test(next)) {
+                letters.push(canonicalAxisLetter(prev === "'" ? prev + ch : ch));
+            }
+        }
+    }
+    return letters;
+}
 /**
  * Find the enclosing function call (if any) for the cursor position. Walks back from the end of `beforeCursor`
  * keeping track of paren depth so that `max(a, min(b,|` correctly reports `min` with argIndex 1, not `max`.
@@ -481,7 +602,8 @@ function findParameterAtCursor(line, codeEndColZero, cursorColOne) {
             if (!/[A-Za-z]/.test(prev) && !/[A-Za-z]/.test(next)) {
                 const valRange = findParameterValueRange(line, i);
                 if (cursorColOne >= valRange.startCol && cursorColOne < valRange.endCol) {
-                    return { letterColZero: i, letter: ch };
+                    // A leading apostrophe escapes a lower-case axis (`'a`); a bare letter is folded to upper case
+                    return { letterColZero: i, letter: canonicalAxisLetter(prev === "'" ? prev + ch : ch) };
                 }
                 i = valRange.endCol - 1;
                 continue;
@@ -602,7 +724,8 @@ function buildParameterDoc(info, p) {
     if (p.values && p.values.length > 0) {
         md += "\n\n**Values:**";
         for (const v of p.values) {
-            md += `\n- \`${v.value}\` - ${v.description}`;
+            const literals = (Array.isArray(v.value) ? v.value : [v.value]).map((x) => `\`${x}\``).join(" / ");
+            md += `\n- ${literals} - ${v.description}`;
         }
     }
     const deprecationNote = p.deprecated ?? info.deprecated;
@@ -862,21 +985,16 @@ export function registerProvidersFor(monacoInstance, languageId) {
                     // just typed it, Monaco should show nothing (so the widget auto-closes) rather than list
                     // the very letter that was just typed as the only match
                     const fullTail = lineContent.substring(code.startColumn - 1 + code.code.length);
-                    const used = new Set();
-                    const re = /(?<![A-Za-z])[A-Za-z](?![A-Za-z])/g;
-                    let m;
-                    while ((m = re.exec(fullTail)) !== null) {
-                        used.add(m[0].toUpperCase());
-                    }
+                    const used = new Set(scanParameterLetters(fullTail));
                     const triggerHints = { id: "editor.action.triggerParameterHints", title: "Trigger Parameter Hints" };
                     const suggestions = info.parameters
-                        .filter(p => !used.has(p.letter.toUpperCase()))
+                        .filter(p => !used.has(p.letter))
                         .map(p => ({
-                        label: { label: p.letter, description: p.description },
+                        label: { label: gcodeAxisToken(p.letter), description: p.description },
                         kind: monacoInstance.languages.CompletionItemKind.Property,
                         detail: p.description,
                         documentation: md(buildParameterDoc(info, p)),
-                        insertText: p.letter,
+                        insertText: gcodeAxisToken(p.letter),
                         range,
                         // Re-open the signature help tooltip after accepting a parameter letter (Monaco otherwise
                         // closes parameter hints when any completion item is accepted without a command)
@@ -1003,7 +1121,7 @@ export function registerProvidersFor(monacoInstance, languageId) {
             }
             for (const p of info.parameters) {
                 const start = label.length + 1;
-                label += " " + p.letter;
+                label += " " + gcodeAxisToken(p.letter);
                 parameters.push({
                     label: [start, label.length],
                     documentation: md(buildParameterDoc(info, p))
@@ -1013,18 +1131,31 @@ export function registerProvidersFor(monacoInstance, languageId) {
             // for codes with a unprecedentedParameter, sit on slot 0 while the user is typing that value (no parameter letter typed yet)
             const tail = tailForDismissal;
             let activeParameter = -1;
-            const seen = tail.match(/(?<![A-Za-z])[A-Za-z](?![A-Za-z])/g);
+            const seen = scanParameterLetters(tail);
             const unprecedentedOffset = info.unprecedentedParameter ? 1 : 0;
-            if (seen && seen.length > 0) {
-                const last = seen[seen.length - 1].toUpperCase();
-                const idx = info.parameters.findIndex(p => p.letter.toUpperCase() === last);
+            if (seen.length > 0) {
+                const last = seen[seen.length - 1];
+                const idx = info.parameters.findIndex(p => p.letter === last);
                 if (idx >= 0) {
                     activeParameter = idx + unprecedentedOffset;
                 }
                 else {
-                    // User typed a letter that isn't a documented parameter for this code - hide the popup
-                    // rather than falling back to the generic summary view, which would be misleading
-                    return null;
+                    // Letter isn't one of the listed parameters. If it is a supported axis on an axis code (e.g. a
+                    // U axis the connected machine isn't configured with) append it so its documentation still shows;
+                    // otherwise hide the popup rather than falling back to the misleading generic summary view
+                    const axisParam = makeAxisParameter(info, last);
+                    if (axisParam) {
+                        const start = label.length + 1;
+                        label += " " + gcodeAxisToken(axisParam.letter);
+                        parameters.push({
+                            label: [start, label.length],
+                            documentation: md(buildParameterDoc(info, axisParam))
+                        });
+                        activeParameter = parameters.length - 1;
+                    }
+                    else {
+                        return null;
+                    }
                 }
             }
             else if (info.unprecedentedParameter) {
@@ -1096,7 +1227,7 @@ export function registerProvidersFor(monacoInstance, languageId) {
                     const info = findGcode(enclosingCode.code);
                     const paramAtCursor = info ? findParameterAtCursor(lineContent, enclosingCode.startColumn + enclosingCode.code.length - 1, position.column) : null;
                     if (info && paramAtCursor) {
-                        const param = info.parameters.find(p => p.letter.toUpperCase() === paramAtCursor.letter.toUpperCase());
+                        const param = lookupParameter(info, paramAtCursor.letter);
                         if (param) {
                             const valueRange = findParameterValueRange(lineContent, paramAtCursor.letterColZero);
                             return {
@@ -1147,7 +1278,7 @@ export function registerProvidersFor(monacoInstance, languageId) {
                 // inside `1:2:3` of `E1:2:3`). This covers hovers that don't land on the letter itself
                 const paramAtCursor = findParameterAtCursor(lineContent, enclosing.startColumn + enclosing.code.length - 1, position.column);
                 if (info && paramAtCursor) {
-                    const param = info.parameters.find(p => p.letter.toUpperCase() === paramAtCursor.letter.toUpperCase());
+                    const param = lookupParameter(info, paramAtCursor.letter);
                     if (param) {
                         const valueRange = findParameterValueRange(lineContent, paramAtCursor.letterColZero);
                         return {
@@ -1159,7 +1290,9 @@ export function registerProvidersFor(monacoInstance, languageId) {
                 // Fallback: hovered word starts with a parameter letter (e.g. bare `X` in `M84 X Y Z`, where
                 // the letter has no value after it so findParameterAtCursor may stop before reaching it)
                 if (info && /^[A-Za-z]/.test(word.word)) {
-                    const param = info.parameters.find(p => p.letter.toUpperCase() === firstLetter.toUpperCase());
+                    // A leading apostrophe just before the word marks a lower-case axis (`'a`)
+                    const escaped = word.startColumn >= 2 && lineContent[word.startColumn - 2] === "'";
+                    const param = lookupParameter(info, canonicalAxisLetter(escaped ? "'" + firstLetter : firstLetter));
                     if (param) {
                         const valueRange = findParameterValueRange(lineContent, word.startColumn - 1);
                         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duet3d/monacotokens",
-  "version": "3.7.0-alpha.11",
+  "version": "3.7.0-alpha.13",
   "description": "TypeScript library that holds syntax highlighting files for the Monaco editor",
   "type": "module",
   "main": "dist/index.js",