Zum Inhalt springen

Eine Live-Coding-Musik-App bauen · Teil 17 von 18 der Serie

Teil 17: Ein Editor, der hilft

Bring dem Editor die Wörter der App bei: Vorschläge für Funktionen, Optionen, Werte und Drum-Namen beim Tippen und eine Erklärung für das Wort unter der Maus. Alles kommt aus dem Schema, das schon die API baut, und der Syntaxbaum sagt, wo der Cursor steht.

Quest-Ziele

  • Eine Completion Source für CodeMirror schreiben
  • Über den Syntaxbaum herausfinden, wo der Cursor steht
  • Funktionen, Optionen, Werte und das, was auf einen Punkt folgt, aus dem Schema vorschlagen
  • Einen Aufruf als Snippet einfügen, das den Cursor zwischen die Klammern setzt
  • Eine Erklärung für das Wort unter der Maus zeigen

Um in loopcode einen Song zu schreiben, musst du seine Wörter kennen: dass der Synth für Basslinien monoSynth heißt, dass sein Filter mit cutoff eingestellt wird, dass seine Welle sawtooth heißt und nicht saw. Teil 11 hat die Fehler lesbar gemacht. Dieser Teil hilft vor dem Fehler: Der Editor schlägt die Wörter beim Tippen vor und erklärt ein Wort, wenn die Maus darauf ruht.

Alles, was er sagt, kommt aus dem Schema aus Teil 9. Das Schema hat die API gebaut, in Teil 11 hat es die Optionen geprüft, und jetzt wird es ein drittes Mal gebraucht. Am Klang ändert sich in diesem Teil nichts.

Zwei Pakete

Die Liste der Vorschläge kommt von @codemirror/autocomplete, und der Typ eines Knotens im Syntaxbaum kommt aus @lezer/common, einem Teil des Parsers, den CodeMirror benutzt. Beide sind schon installiert, als Teile des Editors. Code, der ein Paket importiert, sollte es aber als eigene Abhängigkeit nennen, und genau das passiert, wenn du die beiden mit Namen installierst:

~/loopcode
$ npm install @codemirror/autocomplete @lezer/commonup to date, audited 37 packages in 402ms

Wörter, die keine Bausteine sind

Das Schema erklärt jeden Baustein, also alles, was der Code erzeugen kann, und jede Option. Vier Wörter der API sind keins von beiden: bpm, out, to und mod. Sie bekommen ihre Erklärungen neben den anderen. Ergänze in src/schema.ts über OUT:

src/schema.ts
/** The words of the API that are not units, explained. */
export const WORDS: Record<string, string> = {
  bpm: 'bpm(124) sets the tempo, in beats per minute. A bar has four beats.',
  out: 'The speakers. Whatever is connected to out is heard: bass.to(out)',
  to: 'a.to(b) connects the output of a to the input of b. It gives back b, so calls can be chained: bass.to(delay()).to(out)',
  mod: 'lfo().mod(bass.cutoff) lets an LFO move a setting of another unit.',
};

Wie der Editor nach Vorschlägen fragt

Die Liste, die sich beim Tippen öffnet, gibt es seit Teil 9: basicSetup enthält die Autovervollständigung, und die Sprache JavaScript legt eigene Vorschläge hinein. Was in der Liste steht, entscheiden Completion Sources. Eine Source ist eine Funktion, die der Editor beim Tippen aufruft. Sie bekommt einen Kontext: den State des Editors, die Position des Cursors als pos und explicit, das wahr ist, wenn du die Liste mit Strg+Leertaste verlangt hast. Sie antwortet mit null, also „hier nichts von mir“, oder mit einem Ergebnis aus drei Teilen:

  • from: wo das Wort beginnt, das gerade getippt wird. Ein gewählter Vorschlag ersetzt den Text von dort bis zum Cursor.

  • options: die Vorschläge. Jeder hat ein label, das Wort selbst. Dazu kann er ein detail haben, das neben dem Label steht, eine info, die in einem Kasten neben der Liste erscheint, einen type, der sein Symbol bestimmt, und ein apply, wenn etwas anderes als das Label eingefügt werden soll.

  • validFor: ein regulärer Ausdruck für das, was getippt werden darf, ohne dass neu gefragt wird. Solange der Text von from bis zum Cursor darauf passt, grenzt der Editor die Liste selbst ein.

Lege src/complete.ts an. Die Datei hat vier Abschnitte, die aufeinander folgen. Der erste enthält die Importe, die Namen der Drum-Sounds und zwei Hilfsfunktionen:

src/complete.ts
import { snippetCompletion, type Completion, type CompletionContext, type CompletionResult } from '@codemirror/autocomplete';
import { javascriptLanguage } from '@codemirror/lang-javascript';
import { syntaxTree } from '@codemirror/language';
import type { EditorState } from '@codemirror/state';
import { hoverTooltip } from '@codemirror/view';
import type { SyntaxNode } from '@lezer/common';
import { sampleNames } from './samples.ts';
import { UNITS, WORDS, type OptionSpec } from './schema.ts';

const DRUMS: Record<string, string> = {
  bd: 'bass drum',
  sd: 'snare drum',
  hh: 'closed hi-hat',
  oh: 'open hi-hat',
  cp: 'clap',
  rim: 'rim shot',
  lt: 'low tom',
  mt: 'mid tom',
  ht: 'high tom',
  cb: 'cowbell',
  cy: 'cymbal',
};

const text = (state: EditorState, node: SyntaxNode): string => state.sliceDoc(node.from, node.to);

/** "default 300, from 30 to 8000", or the words a text can be. */
function range(option: OptionSpec): string {
  if (option.choices) return option.choices.join(' | ');
  const limits = option.min !== undefined ? `, from ${option.min} to ${option.max}` : '';
  return `default ${JSON.stringify(option.default)}${limits}`;
}

Das Schema nennt die Drum-Sounds nur in einem Satz, deshalb stehen sie hier mit dem, wofür sie stehen. text() liest das Stück Code, das ein Knoten des Baums abdeckt. range() beschreibt eine Option in wenigen Worten: Für den cutoff des Mono-Synths ergibt es „default 300, from 30 to 8000“, für seine wave die vier Wörter, die die Welle sein kann.

Wo steht der Cursor?

Eine Source, die überall jedes Wort anböte, wäre im Weg. Was passt, hängt vom Ort ab: im Text eines Patterns, in den geschweiften Klammern von monoSynth({ … }), hinter einem Punkt. Das aus den Zeichen vor dem Cursor zu lesen, wird schnell schwierig, denn Klammern können verschachtelt sein, und in einem String kann alles stehen. Der Syntaxbaum des Editors hat das schon geklärt. Teil 16 ist von oben durch den Baum gegangen, um die Patterns zu finden. Hier geht es in die andere Richtung. resolveInner(position, -1) liefert den innersten Knoten an einer Position. Die -1 sagt, welcher gemeint ist, wenn die Position zwischen zwei Knoten liegt: der, der dort endet, also der, hinter dem der Cursor steht. Von diesem Knoten führt parent Schritt für Schritt nach außen: vom Namen einer Option zur Option, zu den geschweiften Klammern, zur Liste der Argumente, zum Aufruf. Die Knoten auf diesem Weg sagen, wo der Cursor steht. Ergänze den zweiten Abschnitt:

src/complete.ts
// ---------------------------------------------------------------------------
// Where is the cursor? The editor's syntax tree answers by walking up from it.

/** The call a node is the first argument of, such as `pattern` for the text in pattern('…'). */
function calleeOf(state: EditorState, argument: SyntaxNode): string | undefined {
  const list = argument.parent;
  if (list?.name !== 'ArgList' || list.firstChild?.nextSibling?.from !== argument.from) return undefined;
  const callee = list.parent?.firstChild;
  return callee?.name === 'VariableName' ? text(state, callee) : undefined;
}

/**
 * The unit whose options a position is in, as in `monoSynth({ … })`. If the position is
 * behind the colon of an option, `option` is that option's name.
 */
function optionsAt(state: EditorState, position: number): { type: string; option: string | undefined } | undefined {
  let option: string | undefined;
  for (let node: SyntaxNode | null = syntaxTree(state).resolveInner(position, -1); node; node = node.parent) {
    if (node.name === 'Property') {
      const colon = node.getChild(':');
      if (colon && position > colon.from && node.firstChild) option = text(state, node.firstChild);
    }
    if (node.name !== 'ObjectExpression') continue;
    // The options are the first argument, or the one after a pattern's text.
    const callee = node.parent?.name === 'ArgList' ? node.parent.parent?.firstChild : undefined;
    const type = callee?.name === 'VariableName' ? text(state, callee) : '';
    return UNITS[type] ? { type, option } : undefined;
  }
  return undefined;
}

/** The type of the unit a variable holds, if it was declared as `const bass = monoSynth(…)`. */
function typeOfVariable(state: EditorState, name: string): string | undefined {
  let type: string | undefined;
  syntaxTree(state).iterate({
    enter(node) {
      if (node.name !== 'VariableDefinition' || text(state, node.node) !== name) return;
      const value = node.node.nextSibling?.nextSibling;
      const callee = value?.name === 'CallExpression' ? value.firstChild : undefined;
      if (callee?.name === 'VariableName' && UNITS[text(state, callee)]) type = text(state, callee);
    },
  });
  return type;
}
  • calleeOf() nimmt einen Knoten und prüft, ob er das erste Argument eines Aufrufs ist. Wenn ja, liefert es den Namen der aufgerufenen Funktion. Das unterscheidet den Text eines Patterns von jedem anderen String.

  • optionsAt() geht hinauf bis zur nächsten ObjectExpression, einem Paar geschweifter Klammern. Sind die Klammern ein Argument eines Aufrufs von einem der Bausteine, liefert es den Typ dieses Bausteins. Kommt der Weg an einer Property vorbei, einer Option samt Wert, und liegt die Position hinter ihrem Doppelpunkt, dann steht der Cursor im Wert, und option ist der Name vor dem Doppelpunkt.

  • typeOfVariable() sucht im ganzen Baum die Stelle, an der eine Variable deklariert wird, eine VariableDefinition. Zwei Geschwister weiter, hinter dem Gleichheitszeichen, steht der Wert, den sie bekommt. Ist das ein Aufruf von einem der Bausteine, hält die Variable einen Baustein dieses Typs.

Vorschläge für vier Orte

Die Source selbst fragt diese drei Funktionen, wo der Cursor steht, einen Ort nach dem anderen. Ergänze den dritten Abschnitt:

src/complete.ts
// ---------------------------------------------------------------------------
// Suggestions

function complete(context: CompletionContext): CompletionResult | null {
  const { state, pos } = context;
  const node = syntaxTree(state).resolveInner(pos, -1);

  if (node.name === 'String') {
    // Inside a pattern: the names of the drum sounds.
    if (calleeOf(state, node) === 'pattern') {
      const word = context.matchBefore(/[a-z]+/);
      if (!word && !context.explicit) return null;
      return {
        from: word?.from ?? pos,
        options: Object.entries(DRUMS).map(([label, detail]) => ({ label, detail, type: 'constant' })),
        validFor: /^[a-z]*$/,
      };
    }
    // Inside the text of an option: the words it can be, or the names of the samples.
    const at = optionsAt(state, pos);
    const option = at?.option ? UNITS[at.type].options[at.option] : undefined;
    const words = at?.option === 'sample' ? sampleNames() : option?.choices;
    if (!words) return null;
    return {
      from: node.from + 1,
      to: Math.max(pos, node.to - 1),
      options: words.map((label) => ({ label, type: 'constant' })),
    };
  }

  // After a dot: what a unit can do, and its settings an LFO can move.
  const member = context.matchBefore(/[\w$)]\.\w*/);
  if (member) {
    const variable = /([\w$]+)\.\w*$/.exec(state.sliceDoc(state.doc.lineAt(pos).from, pos))?.[1];
    const type = variable ? typeOfVariable(state, variable) : undefined;
    // A variable that holds no unit, or something like Math: not ours to help with.
    if (variable && !type) return null;
    const options: Completion[] = [];
    if (type !== 'lfo') options.push(snippetCompletion('to(${})', { label: 'to', type: 'method', info: WORDS.to }));
    if (!type || type === 'lfo') options.push(snippetCompletion('mod(${})', { label: 'mod', type: 'method', info: WORDS.mod }));
    for (const [label, info] of Object.entries((type && UNITS[type].targets) || {})) {
      options.push({ label, info, type: 'property', detail: 'for an lfo' });
    }
    return { from: member.from + 2, options, validFor: /^\w*$/ };
  }

  const word = context.matchBefore(/[\w$]+/);
  if (!word && !context.explicit) return null;
  const from = word?.from ?? pos;

  // Inside the braces of a unit: its options.
  const at = optionsAt(state, pos);
  if (at) {
    if (at.option) return null;
    return {
      from,
      options: Object.entries(UNITS[at.type].options)
        .filter(([name]) => name !== 'source')
        .map(([label, option]) => ({ label, apply: `${label}: `, detail: range(option), info: option.doc, type: 'property' })),
      validFor: /^\w*$/,
    };
  }

  // Anywhere else: the functions of the API.
  return {
    from,
    options: [
      ...Object.entries(UNITS).map(([label, unit]) =>
        snippetCompletion(label === 'pattern' ? "pattern('${}')" : `${label}(\${})`, { label, info: unit.doc, type: 'function' }),
      ),
      snippetCompletion('bpm(${120})', { label: 'bpm', info: WORDS.bpm, type: 'function' }),
      { label: 'out', info: WORDS.out, type: 'variable' },
    ],
    validFor: /^\w*$/,
  };
}

In Anführungszeichen. Ist der String das erste Argument von pattern, werden die Namen der Drum-Sounds angeboten, jeder mit dem, wofür er steht. matchBefore() sucht vor dem Cursor nach Text, der auf einen regulären Ausdruck passt, hier Kleinbuchstaben, und das Wort beginnt dort, wo sie beginnen. Sonst kann der String der Wert einer Option sein. Dann hat das Schema die Wörter, die er sein kann, in choices, und für die Option sample werden die Namen der geladenen Samples angeboten, deine eigenen aus Teil 15 eingeschlossen. Das Ergebnis reicht von hinter dem öffnenden Anführungszeichen bis zum schließenden, ein gewählter Vorschlag ersetzt also den ganzen Wert.

Hinter einem Punkt. Der reguläre Ausdruck passt auf einen Punkt, der auf einen Namen oder eine schließende Klammer folgt. Steht ein Name vor dem Punkt, sagt typeOfVariable(), was er hält. Ein Baustein bekommt to und die Einstellungen, die ein LFO, die langsame Welle aus Teil 14, bewegen kann. Das Schema führt sie als targets. Ein LFO bekommt stattdessen mod. Ein Name, der keinen Baustein hält, etwa Math, ist nicht unsere Sache: Die Source antwortet null und überlässt die Stelle JavaScript. Ohne Namen, wie hinter drums()., werden to und mod beide angeboten.

In den geschweiften Klammern eines Bausteins. Die Optionen dieses Bausteins werden angeboten, mit ihrem Bereich als Detail und ihrer Erklärung als Info. apply fügt den Namen mit Doppelpunkt und Leerzeichen dahinter ein. source fehlt: Der Text eines Patterns ist sein erstes Argument, keine Option zum Hinschreiben. Hinter einem Doppelpunkt antwortet die Source null, denn eine Zahl wählst du selbst.

Überall sonst. Die Funktionen der API werden angeboten, eine pro Baustein des Schemas, dazu bpm und out.

Die Funktionen werden als Snippets eingefügt. snippetCompletion() nimmt eine Vorlage, in der ${} die Stelle für den Cursor markiert. Die Vorlage monoSynth(${}) schreibt den Namen und beide Klammern und lässt den Cursor dazwischen. Bei pattern('${}') landet er zwischen den Anführungszeichen. In bpm(${120}) ist die Stelle mit einer Zahl gefüllt, die markiert ist, sodass Tippen sie ersetzt.

Erklärungen unter der Maus

Die Erklärungen benutzen dieselben Abfragen. hoverTooltip() nimmt eine Funktion, die der Editor mit einer Position aufruft, wenn die Maus auf dem Text ruht. Sie antwortet mit null oder beschreibt einen Tooltip: das Stück Text, zu dem er gehört, und eine Funktion, die sein Element baut. Ergänze den vierten Abschnitt:

src/complete.ts
// ---------------------------------------------------------------------------
// Explanations: what the word under the mouse means

const docs = hoverTooltip((view, position) => {
  const { state } = view;
  const word = state.wordAt(position);
  if (!word) return null;
  const name = state.sliceDoc(word.from, word.to);
  const node = syntaxTree(state).resolveInner(position, 1);

  let explanation: string | undefined;
  if (node.name === 'PropertyDefinition') {
    // The name of an option, inside the braces of a unit.
    const at = optionsAt(state, position);
    const option = at ? UNITS[at.type].options[name] : undefined;
    if (option) explanation = `${name}: ${option.doc} (${range(option)})`;
  } else if (node.name === 'VariableName') {
    explanation = UNITS[name]?.doc ?? WORDS[name];
  } else if (node.name === 'PropertyName') {
    explanation = WORDS[name];
  } else if (node.name === 'String' && calleeOf(state, node) === 'pattern' && DRUMS[name]) {
    explanation = `${name}: ${DRUMS[name]}`;
  }
  if (!explanation) return null;

  return {
    pos: word.from,
    end: word.to,
    above: true,
    create() {
      const dom = document.createElement('div');
      dom.className = 'doc';
      dom.textContent = explanation;
      return { dom };
    },
  };
});

/** Everything the editor needs to help: suggestions next to JavaScript's own, and explanations. */
export const help = [javascriptLanguage.data.of({ autocomplete: complete }), docs];

wordAt() liefert das Wort an der Position, und der Name des Knotens sagt, wo es nachzuschlagen ist. Eine PropertyDefinition ist der Name einer Option in geschweiften Klammern: Ihre Erklärung und ihr Bereich kommen aus dem Schema des Bausteins darum herum. Ein VariableName ist eine Funktion der API oder out. Ein PropertyName ist ein Name hinter einem Punkt: to oder mod. Und im Text eines Patterns kann das Wort ein Drum-Sound sein.

Die letzte Zeile fasst beides zusammen. javascriptLanguage.data.of() meldet die Source für JavaScript an, neben den Sources, die die Sprache mitbringt. Ihre Vorschläge landen in einer gemeinsamen Liste.

Einschalten

Importiere in src/editor.ts help aus ./complete.ts und nimm es in die Extensions auf, hinter javascript(). Ersetze createEditor():

src/editor.ts
/** A code editor in `parent`, holding `code`. */
export function createEditor(parent: HTMLElement, code: string, keys: EditorKeys): EditorView {
  return new EditorView({
    parent,
    doc: code,
    extensions: [
      // Before the basic setup, and with the highest precedence: Ctrl+Enter means
      // something else there.
      Prec.highest(
        keymap.of([
          { key: 'Mod-Enter', run: () => (keys.run(), true) },
          { key: 'Mod-.', run: () => (keys.stop(), true) },
        ]),
      ),
      basicSetup,
      javascript(),
      help,
      playingMarks,
      look,
      oneDark,
    ],
  });
}

Der Kasten eines Tooltips kommt von CodeMirror. Sein Inhalt bekommt eine Breite und etwas Luft. Ergänze in src/style.css hinter der Regel für .cm-playing:

src/style.css
.editor .doc {
  max-width: 420px;
  padding: 4px 8px;
}

Probier es aus

Geh in eine leere Zeile am Ende des Codes und tipp mon. Die Liste bietet monoSynth an, mit seiner Erklärung in einem Kasten daneben. Enter schreibt monoSynth() und setzt den Cursor zwischen die Klammern. Tipp dort { c: Die Liste bietet cutoff an, daneben steht „default 300, from 30 to 8000“, und Enter schreibt den Namen samt Doppelpunkt. Tipp eine Zahl und ein Komma, dann wave: 's: Die Liste bietet sawtooth, sine und square an.

Für den Punkt beginne mit zwei Variablen:

javascript
const bass = monoSynth()
const wobble = lfo()

Tipp in einer neuen Zeile bass., und die Liste bietet cutoff, pitch, to und volume an. Hinter wobble. bietet sie mod an. Tipp in einem Pattern pattern('b, und sie bietet bd an, die Bassdrum. Strg+Leertaste in einer leeren Zeile öffnet die Liste mit allen Funktionen der API.

Lass dann die Maus auf monoSynth ruhen, auf dem Namen einer Option, auf to, auf out, auf bpm und auf dem Namen eines Drum-Sounds in einem Pattern. Jedes zeigt seine Erklärung über dem Wort.

Tipp im Editor: Beim Schreiben erscheinen Vorschläge, und Enter übernimmt einen. Lass die Maus auf einem Wort wie monoSynth oder cutoff ruhen, um seine Erklärung zu lesen. Play startet den Song.
In neuem Tab öffnen

Kommentare

Die Kommentare sind GitHub Discussions: Zum Schreiben mit GitHub anmelden.

Die Kommentare kommen über giscus von GitHub. Beim Laden gehen deine IP-Adresse an giscus.app und GitHub.