CLI-contract¶

Dit document beschrijft het functionele contract van de VSA-CLI.

De taakgerichte uitleg hoort in docs/guides/; dit document legt vast welke commando's, exitcodes en hoofdgedragingen onderdeel zijn van de toolinginterface.

VSA CLI referentie¶

Deze referentie beschrijft elk commando afzonderlijk.

Gebruik de gebruikershandleiding (docs/guides/user-guide.md) voor taakgerichte uitleg.

Algemene uitgangspunten¶

De voorbeelden gaan uit van:

cd /d C:\Git\orthodox-ronl\VSA-tooling

Paden zijn relatief aan die map, tenzij je absolute paden gebruikt.

Exitcodes¶

Exitcode	Betekenis
`0`	commando succesvol
`1`	fout gevonden of commando mislukt

In CMD kun je de exitcode direct na een commando bekijken met:

echo %ERRORLEVEL%

`vsa --version`¶

Doel¶

Toon de geïnstalleerde versie van de tool.

Gebruik¶

vsa --version

Output¶

vsa 0.1.0

Fouten¶

Als vsa niet gevonden wordt:

'vsa' is not recognized...

Dan is de tool niet geïnstalleerd in de actieve Python-omgeving.

Oplossing:

test

`vsa validate <bestand-of-map>`¶

Doel¶

Controleer of VSA-invoer bruikbaar is voor verdere verwerking.

Gebruik¶

vsa validate <bestand-of-map>

Inputvarianten¶

Input	Voorbeeld	Gedrag
`.vsa` bestand	`examples\minimal\001_plain_text.vsa`	controleert één VSA-bestand
`.md` bestand	`pagina.md`	controleert VSA-blokken in Markdown
map	`examples\consumer-minimal\content-source`	zoekt recursief naar `.vsa`, `.md`, `.markdown`

Wat wordt gecontroleerd?¶

Fase	Controle
syntaxscan	accolades, lege scopes, whitespace in scopes, pitch-markers
parser	of de VSA naar interne structuur kan worden omgezet
semantiek	of modifier-aantallen logisch bij elkaar passen

Succesoutput¶

OK

Foutoutput¶

Vorm:

bron:regel:kolom: FOUTCODE: uitleg

Voorbeeld:

examples\demo.md:blok-1:1:1: VSA-SYNTAX-EMPTY-SCOPE: Scope zonder zangelement.

Veelvoorkomende foutcodes¶

Foutcode	Betekenis	Wat doen?
`VSA-SYNTAX-EMPTY-SCOPE`	`{}` gevonden	zet tekst of zangelement in de scope
`VSA-SYNTAX-UNCLOSED-SCOPE`	`{tekst` zonder `}`	sluit de scope af
`VSA-SYNTAX-UNEXPECTED-CLOSE-BRACE`	losse `}`	verwijder of herstel de scope
`VSA-SYNTAX-WHITESPACE-IN-SCOPE`	spatie binnen `{...}`	splits tekst buiten de scope of gebruik correcte notatie
`VSA-SYNTAX-UNCLOSED-PITCH-MARKER`	`[` zonder `]`	sluit pitch-marker af
`VSA-SYNTAX-PITCH-MARKER-MISSING-COLON`	pitch-marker zonder `:`	gebruik bijvoorbeeld `[:]`
`VSA-SYNTAX-INVALID-PITCH-TRANSITION`	ongeldige toonhoogte-overgang	gebruik `[<oude-EHM>:<nieuwe-EHM>]` met geldige EHM
`VSA-SEMANTIC-MODIFIER-COUNT-MISMATCH`	aantallen hoogte/lengteposities passen niet	controleer samengestelde modifiers
`VSA-SEMANTIC-HEIGHT-MARKER-MISMATCH`	markering wijkt af van berekende cursor	markering/scopes aanpassen of toonhoogte-overgang gebruiken
`VSA-SEMANTIC-PITCH-TRANSITION-MISMATCH`	linker-EHM van overgang klopt niet met cursor	pas `[oud:nieuw]` of voorgaande notatie aan

Wat doe je bij fouten?¶

Open het genoemde bestand.
Zoek het genoemde VSA-blok.
Corrigeer de genoemde fout.
Draai hetzelfde commando opnieuw.
Herhaal tot OK.

`vsa parse <bestand.vsa> --ast`¶

Doel¶

Debuggen hoe de parser een VSA-bestand intern ziet: de Abstract Syntax Tree (AST) als JSON.

Gebruik¶

vsa parse <bestand.vsa> --ast

Parameters¶

Parameter	Verplicht	Betekenis
`<bestand.vsa>`	ja	VSA-bestand
`--ast`	nee	toon de interne structuur als JSON

Output met `--ast`¶

JSON met nodes (ScopeNode, TextNode, PitchMarkerNode, …).

Voorbeeldvorm:

{
  "type": "Document",
  "nodes": [
    {
      "type": "PitchMarkerNode",
      "height_modifier": ["/"]
    },
    {
      "type": "ScopeNode",
      "height_modifier": ["/"],
      "text": "Hei",
      "length_modifier": ["_"]
    }
  ]
}

Output zonder `--ast`¶

OK

als het bestand gelezen kan worden.

Wanneer gebruiken?¶

Gebruik	Ja/nee
gewone eindcontrole	nee, gebruik `validate`
parserdebugging	ja
regressietest maken	ja
controleren of tekst als `TextNode` wordt gezien	ja

`vsa blocks <bestand.md> [--json]`¶

Doel¶

VSA-blokken in een Markdownbestand vinden.

Gebruik¶

vsa blocks <bestand.md>

vsa blocks <bestand.md> --json

Parameters¶

Parameter	Verplicht	Betekenis
`<bestand.md>`	ja	Markdownbestand
`--json`	nee	toon uitgebreide machineleesbare output

Output zonder `--json`¶

1 VSA-blok(ken) gevonden

Output met `--json`¶

Per blok:

Veld	Betekenis
`start_line`	beginregel in Markdownbestand
`end_line`	eindregel in Markdownbestand
`metadata`	blokinstellingen
`body`	VSA-inhoud
`ast`	interne parserstructuur

Wanneer gebruiken?¶

Situatie	Gebruik
controleren of blokken herkend worden	zonder `--json`
metadata/body/AST bekijken	met `--json`

`vsa svg <input.vsa> <output.svg>`¶

Doel¶

Maak een SVG-afbeelding van één VSA-bestand.

Gebruik¶

vsa svg <input.vsa> <output.svg>

Parameters¶

Parameter	Verplicht	Betekenis
`<input.vsa>`	ja	VSA-bronbestand
`<output.svg>`	ja	doelbestand voor SVG

Opties¶

Optie	Default	Betekenis
`--max-line-width <getal>`	`vsa.toml` of `800`	maximale regelbreedte

Output¶

Een bestand:

output.svg

Let op¶

Dit commando verwerkt geen Markdownblokken.

Voor Markdown gebruik je:

vsa process

of:

vsa build-markdown

`vsa process <bestand-of-map> <output-dir>`¶

Doel¶

SVG-bestanden genereren uit VSA-blokken in Markdown.

Gebruik¶

vsa process <bestand-of-map> <output-dir>

Inputvarianten¶

Input	Gedrag
één Markdownbestand	verwerkt alle VSA-blokken in dat bestand
map	zoekt recursief naar Markdownbestanden

Parameters¶

Parameter	Verplicht	Betekenis
`<bestand-of-map>`	ja	invoer
`<output-dir>`	ja	map voor gegenereerde SVG's

Opties¶

Optie	Default	Betekenis
`--no-validate`	niet actief	validatie overslaan
`--max-line-width <getal>`	`vsa.toml` of `800`	SVG-regelbreedte

Output¶

Alleen SVG-bestanden.

Geen Markdown wordt herschreven.

Wanneer gebruiken?¶

Gebruik dit als je:

alleen SVG's wilt;
wilt controleren hoe SVG-bestanden eruitzien;
nog geen Hugo-Markdown wilt genereren.

`vsa build-markdown <input-dir> <output-dir> <assets-dir>`¶

Doel¶

Maak Hugo-geschikte Markdown en SVG-bestanden.

Gebruik¶

vsa build-markdown <input-dir> <output-dir> <assets-dir>

Parameters¶

Parameter	Verplicht	Betekenis
`<input-dir>`	ja	bronmap met handmatig geschreven Markdown
`<output-dir>`	ja	doelmap voor gegenereerde Markdown
`<assets-dir>`	ja	doelmap voor gegenereerde SVG-bestanden

Output¶

Output	Voorbeeld
Markdown	`generated\content\toon-1.md`
SVG	`generated\static\vsa\toon-1-block-1.svg`

Wat wordt vervangen?¶

In bron-Markdown:

::: vsa-notatie
{tekst}
:::

wordt in output-Markdown:

<img class="vsa-notation" src="/vsa/demo-block-1.svg" alt="VSA notatie">

of:

{{< vsa src="/vsa/demo-block-1.svg" >}}

Opties¶

Optie	Default	Betekenis
`--assets-url-prefix <prefix>`	`vsa.toml` of `/vsa`	URL-prefix in Markdown
`--max-line-width <getal>`	`vsa.toml` of `800`	SVG-regelbreedte
`--output-mode img`	`vsa.toml` of `img`	gebruik `<img>`
`--output-mode shortcode`	`vsa.toml` of `img`	gebruik Hugo shortcode

Padvoorbeelden¶

Commando:

vsa build-markdown examples\consumer-minimal\content-source generated\content generated\static\vsa

Betekenis:

Deel	Pad	Betekenis
input	`examples\consumer-minimal\content-source`	bron
output	`generated\content`	nieuwe Markdown
assets	`generated\static\vsa`	SVG-bestanden

Wat doe je bij problemen?¶

Probleem	Controle
build stopt met fout	draai `vsa validate <input-dir>`
afbeelding niet zichtbaar	controleer `assets-url-prefix`
shortcode zichtbaar als tekst	controleer Hugo shortcode-bestand
oude output blijft zichtbaar	verwijder `generated` en bouw opnieuw

`vsa pdf <bestand.md>`¶

Doel¶

Maak een A4-PDF van één Markdownbestand: VSA-blokken, includes en pagebreaks worden net als bij build-markdown opgelost; daarna print Edge/Chrome.

Gebruik¶

vsa pdf <bestand.md> -o uit.pdf

Output¶

Output	Voorbeeld
PDF	`uit.pdf`

Fouten (validatie) gebruiken hetzelfde formaat als vsa validate.

`vsa.toml`¶

Doel¶

Projectdefaults vastleggen.

Voorbeeld¶

[rendering]
max-line-width = 800

[hugo]
assets-url-prefix = "/vsa"
output-mode = "img"

# Alternatief:
# output-mode = "shortcode"

Defaults¶

Instelling	Default
`max-line-width`	`800`
`assets-url-prefix`	`/vsa`
`output-mode`	`img`

Voorrang¶

CLI-optie
  ↓
vsa.toml
  ↓
default

Scripts¶

Script	Wat doet het?
`test`	installeert lokale omgeving
`scripts\test.cmd`	draait tests
`scripts\ci.cmd`	draait lokale CI
`serve`	MkDocs docs lokaal serveren

Diagnosevolgorde¶

Bij problemen:

vsa validate <input>

Daarna:

scripts\test.cmd

Daarna eventueel:

vsa blocks <bestand.md> --json

En als rendering vreemd is:

vsa svg <bestand.vsa> output.svg
start output.svg

`vsa template validate <pad>`¶

Doel¶

Valideer een template.yaml (of een map met zulke bestanden) tegen schema en documentregels.

Gebruik¶

vsa template validate docs\specification-vsa-templates\library
vsa template validate docs\specification-vsa-templates\library\tropaar-toon-4\template.yaml

Output¶

Bij succes: één OK-regel per bestand. Bij fout: pad: ERROR: CODE: … en exitcode 1.

`vsa text <pad>`¶

Doel¶

Haal platte gezongen tekst uit .vsa, .mvsa, MusicXML (.mxl / .musicxml / .xml) of .mscz — zonder notatie, voor zoekindex, lyrics-producten, of als referentie voor het veld zoektekst. Schrijft geen .mvsa-sibling. Op .vsa / .mvsa negeert extractie een bestaand zoektekst-veld.

Volledige regel (MusicXML-lyrics, stemkeuze, -o): man-pagina reference/cli/text.md.

Gebruik¶

vsa text examples\minimal\001_plain_text.vsa
vsa text lied.mscz.mxl -o generated\lied.mscz.lyrics.txt
vsa text lied.mscz -o generated\lied.mscz.lyrics.txt

Alias voor alleen .mscz: mscz text (zelfde extractie via temp-.mxl).

`vsa zoektekst <pad>…`¶

Doel¶

Vul of controleer YAML-zoektekst in .vsa / .mvsa (editorzoeken). Default: in-place schrijven; --check alleen controleren.

Man-pagina: reference/cli/zoektekst.md. Contract: formats/zoektekst.md.

Gebruik¶

vsa zoektekst examples\mvsa\alleluia-toon-1.mvsa
vsa zoektekst examples\mvsa --check

`vsa mvsa …`¶

Doel¶

Draft-tooling voor meerstemmige .mvsa-bestanden (L + SATB). Zie specification-mvsa en de man-pagina reference/cli/mvsa.md.

Gebruik¶

vsa mvsa validate examples\mvsa
vsa mvsa validate examples\mvsa\alleluia-toon-8.mvsa
vsa mvsa mxl examples\mvsa\kleine-intocht-zondag-hemelum.mvsa
vsa mvsa mxl examples\mvsa\kleine-intocht-zondag-hemelum.mvsa --section schets-a-bladcijfer -o generated\intocht-a.mxl

Opties (`mxl`)¶

Optie	Betekenis
`-o`, `--output`	Uitvoerbestand (default: `<bronnaam>.mxl`, bijv. `lied.mvsa.mxl`).
`--section SECTION`	Alleen deze `@sectie`-id exporteren (default: alle secties).

Output¶

validate: bij succes zonder warnings één regel OK; anders diagnostiek en bij errors exitcode 1.
mxl: Geschreven: <pad> of fout op stderr.

CLI-contract¶

VSA CLI referentie¶

Algemene uitgangspunten¶

Exitcodes¶

vsa --version¶

Doel¶

Gebruik¶

Output¶

Fouten¶

vsa validate <bestand-of-map>¶

Doel¶

Gebruik¶

Inputvarianten¶

Wat wordt gecontroleerd?¶

Succesoutput¶

Foutoutput¶

Veelvoorkomende foutcodes¶

Wat doe je bij fouten?¶

vsa parse <bestand.vsa> --ast¶

Doel¶

Gebruik¶

Parameters¶

Output met --ast¶

Output zonder --ast¶

Wanneer gebruiken?¶

vsa blocks <bestand.md> [--json]¶

Doel¶

Gebruik¶

Parameters¶

Output zonder --json¶

Output met --json¶

Wanneer gebruiken?¶

vsa svg <input.vsa> <output.svg>¶

Doel¶

Gebruik¶

Parameters¶

Opties¶

Output¶

Let op¶

vsa process <bestand-of-map> <output-dir>¶

Doel¶

Gebruik¶

Inputvarianten¶

Parameters¶

Opties¶

Output¶

Wanneer gebruiken?¶

vsa build-markdown <input-dir> <output-dir> <assets-dir>¶

Doel¶

Gebruik¶

Parameters¶

Output¶

Wat wordt vervangen?¶

Opties¶

Padvoorbeelden¶

Wat doe je bij problemen?¶

vsa pdf <bestand.md>¶

Doel¶

Gebruik¶

Output¶

vsa.toml¶

Doel¶

Voorbeeld¶

Defaults¶

Voorrang¶

Scripts¶

Diagnosevolgorde¶

vsa template validate <pad>¶

Doel¶

Gebruik¶

Output¶

vsa text <pad>¶

Doel¶

Gebruik¶

vsa zoektekst <pad>…¶

Doel¶

Gebruik¶

vsa mvsa …¶

Doel¶

Gebruik¶

`vsa --version`¶

`vsa validate <bestand-of-map>`¶

`vsa parse <bestand.vsa> --ast`¶

Output met `--ast`¶

Output zonder `--ast`¶

`vsa blocks <bestand.md> [--json]`¶

Output zonder `--json`¶

Output met `--json`¶

`vsa svg <input.vsa> <output.svg>`¶

`vsa process <bestand-of-map> <output-dir>`¶

`vsa build-markdown <input-dir> <output-dir> <assets-dir>`¶

`vsa pdf <bestand.md>`¶

`vsa.toml`¶

`vsa template validate <pad>`¶

`vsa text <pad>`¶

`vsa zoektekst <pad>…`¶

`vsa mvsa …`¶

Opties (`mxl`)¶