Spintax-syntaxreferentie

Volledige referentie voor spintax-sjabloonmarkup.

Enumeraties { }

Selecteert willekeurig één optie uit de lijst.

{option1|option2|option3}

Voorbeelden

{blue|grey|clear}
{|free|paid} plan                 ← empty option = sometimes nothing
{Acme {Pro|Lite}}                ← nested enumerations
{order {|#42-A} confirmed}       ← nesting with empty option

Regels

• Scheidingstekens: { en }
• Separator: |
• Ondersteunt nesting tot willekeurige diepte
• Lege opties zijn geldig (produceren lege string)
• Resolutie gaat van de binnenste expressie naar buiten

Permutaties [ ]

Selecteert N elementen, schudt ze en voegt ze samen met scheidingstekens.

Eenvoudige permutaties

Alle elementen opgenomen, gescheiden door spaties:

[1|2|3|4]

Uitvoervoorbeelden: 1 4 3 2, 2 3 4 1, 3 2 4 1

Met scheidingsteken

Uniform scheidingsteken opgegeven in < > aan het begin:

[<, > 1|2|3|4]

Uitvoervoorbeelden: 2, 1, 4, 3 · 4, 3, 2, 1

Belangrijk: Geen spatie tussen [ en <scheidingsteken>.

Scheidingstekens per element

Elke optie kan een eigen scheidingsteken hebben, gedefinieerd met <sep> vóór de voorgaande |. Het scheidingsteken verplaatst zich mee met het element bij het schudden.

[<, > 1|2|3 < and >|4]

Uitvoervoorbeelden: 1, 3, 2 and 4 · 3, 1, 2 and 4

Auto-spatiëring: Woord-scheidingstekens zoals <and> of <or> worden automatisch met spaties aangevuld: <and> resulteert in  and . Leesteken-scheidingstekens (<,>) worden niet aangevuld. Twee uitzonderingen: een scheidingsteken dat alleen uit Han-, Hiragana-, Katakana-, Thai-, Lao-, Khmer- of Myanmar-schrift bestaat, wordt zonder spaties aangesloten (<和> geeft a和b), en onder de locale ar worden de voegwoorden و en ف aan het volgende Arabische woord vastgeschreven (الكازينو والبث), net als ו onder he.

Permutaties met combinaties

Configureerbaar minimum/maximum aantal elementen en scheidingstekens:

[<minsize=1;maxsize=3;sep=", ";lastsep=" and "> apple|plum|orange|apricot]

Uitvoervoorbeelden: apple, plum and orange · apple and apricot · orange

Configuratieparameters

Permutatieregels

• Scheidingstekens: [ en ]
• Configuratieblok <...> moet direct na [ volgen
• Configuratieparameters worden gescheiden door puntkomma's
• Tekenreekswaarden in configuratie staan tussen aanhalingstekens: sep=", "
• Enumeraties en permutaties kunnen genest worden binnen opties
• HTML-elementen kunnen opties zijn
• sep verbindt alles vóór het laatste paar, lastsep dat paar zelf: bij twee gekozen items verschijnt alleen lastsep, bij één geen van beide

Variabelen %var%

Definieert een herbruikbare variabele die wordt ingevuld waar ze ook voorkomt. Twee directives declareren er een, en de keuze is niet cosmetisch: #set is een macro — de waarde wordt bij elke verwijzing opnieuw ingevuld, dus de spintax erin wordt opnieuw gerold; #def rolt de waarde eenmaal per rendering en geeft dat ene resultaat aan elke verwijzing. (Eén rendering is één uitvoer; dezelfde seed reproduceert die.) Zolang de waarde platte tekst is zijn ze identiek; het verschil verschijnt zodra de waarde een keuze bevat.

#set %VARIABLE_NAME% = value or spintax structure

#def %VARIABLE_NAME% = value or spintax structure

Voorbeelden

#set %name% = John
#set %greeting% = {Hello|Hi|Hey}
#set %items% = [<minsize=2;maxsize=3;sep=", ";lastsep=" and "> apples|oranges|bananas]
Some text with %name% and %greeting%, also %items%.
And once more, %greeting% — a second reference.

/# %greeting% above may differ between the two references — #set re-rolls.
   #def picks once and keeps it: #/
#def %tone% = {friendly|warm|upbeat}
A %tone% intro, and a %tone% outro — always the same word.

Variabelenregels

• #set en #def moeten aan het begin van een regel staan
• Variabelenamen staan tussen %: %name%
• Namen zijn alfanumeriek + underscore, en verwijzingen zijn hoofdletterongevoelig: %Tone% en %tone% zijn één variabele
• Waarden mogen elke spintax-syntaxis bevatten (opsommingen, permutaties, andere variabelen)
• #set is een macro: hij wordt uitgeklapt bij de verwijzing, niet bij de definitie, en zijn waarde — inclusief de spintax erin — wordt bij elke verwijzing opnieuw ingevuld en opnieuw gerold
• #def lost zijn waarde eenmaal per rendering op en houdt dat resultaat overal vast. Dat is wat herhalingen congruent houdt: een zelfstandig naamwoord en de vormen die eruit worden gebouwd, een telling voor een {plural}-blok, elke zin waarvan de herhalingen woord voor woord moeten kloppen
• #def maakt één variabele consistent met zichzelf; het correleert geen twee variabelen. #def %Noun% en #def %NounGen% zijn twee onafhankelijke worpen en kunnen op verschillende woorden landen — vormen die moeten overeenkomen, moeten uit één worp komen: één #def-stam waarnaar elke vorm verwijst, of synoniemen die gelijk verbuigen met de uitgang buiten de definitie
• Een naam wordt eenmaal gedefinieerd. Een tweede definitie van dezelfde naam wordt gemeld als definition.duplicate-name en de rendering gaat toch door: tussen twee gelijke directives wint de latere, en delen een #set en een #def een naam, dan wint de #def — welke er ook eerst stond
• Een verwijzing zonder definitie print zichzelf: %missing% blijft in de uitvoer staan in plaats van te verdwijnen
• Geen van beide directives steekt een #include over: het ingevoegde sjabloon ziet de lokale variabelen van de ouder niet, en de eigen lekken niet terug. Een gerolde vorm bereikt het kind alleen als runtime-variabele
• #set- en #def-regels worden uit de uitvoer verwijderd
• Verdieping: zie de variabelengids (scopes en de reroll-valkuil) en de grammaticaal veilige synonimisering (naamvalfamilies)

Scopes van variabelen

Een host kan variabelen uit meerdere plaatsen aanleveren. Bestaat dezelfde naam op meerdere plekken, dan wint de sterkste:

1. Runtime-variabelen (sterkst) — wat de host aan de render-aanroep meegeeft: context in @spintax/core, shortcode-attributen in de WordPress-plugin: [spintax slug="greeting" name="Alice"]
2. Lokale variabelen — gedefinieerd met #set of #def in het sjabloon
3. Globale variabelen (zwakst) — host-brede standaarden, zoals de instellingenpagina van de plugin

Voorwaarden {?VAR?then|else}

Voorwaarden zijn een eigen constructie van de taal — in het GTW-prototype bestond niets vergelijkbaars. Waar {a|b} een uniforme willekeurige keuze is die variabelen negeert, kiest {?VAR?then|else} op basis van of %VAR% een waarde heeft.

Gebruik het voor waarde-gestuurde keuzes: een free-tier-regel alleen tonen als er een free tier is, een pro-features-blok alleen renderen wanneer de gebruiker een betaald plan heeft, een niet-toepasselijke CTA verbergen.

De pre-pass loopt vóór %var%-uitbreiding en vóór de willekeurige tak-kiezer, dus een falsy-tak wordt volledig verworpen — niets erbinnen wordt geëvalueerd.

Vormen

{?VAR?then}                ← truthy ⇒ then; falsy ⇒ empty
{?VAR?then|else}           ← truthy ⇒ then; falsy ⇒ else
{?!VAR?then|else}          ← inverted

{?HasFreeTier? — free tier available since %founded%|, trusted since %founded%}

Truthy en falsy

De regel is bewust eenvoudiger dan in JavaScript — truthy = minstens één niet-witruimte-teken:

Regels voor voorwaarden

• Variabelennamen volgen dezelfde regex als %var% (hoofdletterongevoelig)
• Het !-prefix keert de controle om: {?!VAR?afwezig}
• De eerste | op diepte 0 scheidt then van else; volgende blijven letterlijk in else
• Geneste voorwaarden worden van buiten naar binnen geëvalueerd — falsy-takken kortsluiten
• Samengestelde logica (&&, ||, vergelijkingen) wordt niet ondersteund — bereken een guard-variabele in de assembler
• Misvormde vormen ({??yes}, {?VAR}) gooien nooit — het playground markeert ze als waarschuwingen
• Verdieping: zie de conditional-spintax-gids met voorbeelden en anti-patronen

Meervouden {plural %n%: taal|talen}

Kiest de grammaticaal juiste woordvorm bij een getal. De teller staat vóór de dubbele punt, de vormen erna, gescheiden door |.

De vorm wordt bepaald door de render-locale, niet door het sjabloon — hoeveel vormen je moet aanleveren hangt dus van die locale af. Engels vraagt er twee, Russisch drie.

{plural %n%: form1|form2}          ← 2-form locale (en, de, es…)

{plural %n%: form1|form2|form3}    ← 3-form locale (ru, uk, sr…)

{plural %n%: zero|one|two|few|many|other}  ← 6-form locale (ar)

#def %LangCount% = 5
supports %LangCount% {plural %LangCount%: language|languages}
← supports 5 languages

Vormen per locale

De locale wordt vergeleken op zijn taalsubtag, dus ru-RU en ru gedragen zich identiek:

Klopt het aantal vormen niet, dan meldt de engine plural.arity en laat het blok zichtbaar staan met volle-breedte accolades — een fout meervoud gaat nooit stilletjes live.

Meervoudsregels

• De opening is letterlijk, inclusief de spatie: {plural . {plural: x} en {pluralN: x} zijn geen meervoudsblokken
• De dubbele punt is verplicht — die scheidt de teller van de vormen
• De teller is een %Var%-verwijzing of een letterlijk geheel getal; variabelen in de teller worden vervangen vóór de vormkeuze
• Negatieve getallen tellen als absolute waarde; 0 krijgt de vorm "al het overige" (onder ar de eerste, eigen vorm)
• Een tellervariabele moet #def zijn, geen #set — #set is een macro, dus een waarde als {1|4|9} is nog onopgeloste spintax op het moment van de keuze en het blok rendert leeg. De playground markeert dit als plural.count-macro
• Een niet-numerieke of ongedefinieerde teller wist het blok in plaats van te gokken
• Verdieping: zie de meervouden-gids met de Russische drievormregels en uitgewerkte voorbeelden

Includes #include

Voegt een ander sjabloon in op de plek van de directive. #include is de enige constructie die de engine niet zelf kan afhandelen: hij bewaart geen sjablonen, dus levert de host een resolver die een verwijzing omzet in sjabloontekst. Waar geen resolver is geïnstalleerd — de playground en de MCP-server op deze site, beide met opzet — is de directive inert en blijft ze als letterlijke tekst in de uitvoer staan.

#include "hero-text"

/# wrong: text before the directive on the same line leaves it literal #/
Intro: #include "hero-text"

Include-regels

• De directive moet de hele regel beslaan. Inspringen mag; tekst na de verwijzing niet — Tekst #include "hero" blijft letterlijk
• De verwijzing staat tussen dubbele aanhalingstekens; met enkele of zonder aanhalingstekens is het de directive niet meer
• Het oplossen is aan de host: de WordPress-plugin zoekt op slug of numeriek ID, een JavaScript-host geeft een includeResolver mee
• Zonder resolver blijft de regel letterlijk in de uitvoer; kent de resolver het sjabloon niet, dan wordt de regel juist verwijderd — een onbekend doel kost je het blok in stilte
• Ingevoegde sjablonen mogen eigen variabelen en spintax bevatten, en eigen #include
• Includes worden opgelost nadat de opsommingen en permutaties van de ouder zijn gerold: een include in de winnende tak wordt ingevoegd — een in een afgevallen tak gebeurt nooit
• Ketens werken (een sjabloon voegt een sjabloon in dat er weer een invoegt); een sjabloon dat zichzelf invoegt, direct of via een cyclus, wordt bij de eerste herhaling afgekapt — zonder fout en zonder diagnose
• Kindsjablonen erven globale en runtime-variabelen, maar niet de lokale #set / #def van de ouder, en de hunne lekken niet terug
• Een include kan niet de waarde van een definitie zijn: #def %x% = #include "y" wordt geweigerd als def.include-in-value
• Vóór het renderen meldt validate() een onbekend doel alleen als de host de lijst met bekende verwijzingen meegeeft; extract() geeft de verwijzingen terug die een sjabloon nodig heeft — zo laadt een host ze vooraf
• Verdieping: zie de gids voor sjabloon­compositie, het assembler-patroon dat de meeste pipelines in plaats hiervan gebruiken

Opmerkingen /#...#/

Tekst tussen opmerkingenmarkeringen wordt uit de uitvoer verwijderd vóór enige andere verwerking.

/#
  This is a comment section.
  It can span multiple lines.
  It won't appear in output.
#/

Opmerkingenregels

• Beginscheidingsteken: /#
• Eindscheidingsteken: #/
• Kunnen meerdere regels beslaan
• Kunnen niet genest worden
• Verwijderd vóór enige andere verwerking
• Het tegenovergestelde is het letterlijke blok /!...!/: dat behoudt zijn tekst in plaats van die weg te laten

Letterlijk blok /!...!/

Tekst tussen de letterlijke markeringen komt precies zoals geschreven in de uitvoer terecht. Niets erin is syntaxis, en de nabewerking komt er niet aan. Gebruik het voor tekst die op spintax lijkt maar het niet is: een Markdown-link, een macro die een andere tool uitvouwt, BBCode of een spintax-voorbeeld dat je wilt tonen in plaats van renderen.

Het blok is nieuw in @spintax/core 0.14.0. De andere engines voegen het toe naarmate elk ervan het uitbrengt.

Docs: /![Spintax](https://spintax.net)!/
→ Docs: [Spintax](https://spintax.net)

Write /!{Hello|Hi}!/ to get two variants.
→ Write {Hello|Hi} to get two variants.

Pull from /!#file[D:\kw.txt,1,S]!/ here.
→ Pull from #file[D:\kw.txt,1,S] here.

Regels voor letterlijke blokken

• Beginscheidingsteken: /!; de eerste !/ daarna sluit het blok
• Kan meerdere regels beslaan en kan niet genest worden
• Binnen een blok zijn {, [, |, %var% en #set gewone tekst
• Werkt in een #set- of #def-waarde, zodat één blok herbruikbaar is
• De nabewerking werkt zoals gewoonlijk rond het blok, maar verandert de tekst erin nooit, zet er geen hoofdletters in en trimt hem niet
• Een leeg blok /!!/ wordt verwijderd
• Wat van /# en /! het eerst komt, wint: een opmerking kan een /! verbergen, en een blok kan een /# behouden
• Een /! zonder afsluiting is gewone tekst, en de validator waarschuwt met verbatim.unclosed
• Alleen het sjabloon wordt zo gelezen: een /! in de waarde van een runtimevariabele is gewoon twee tekens. Wil je onbetrouwbare data letterlijk houden, haal die dan door neutralize(). Het beschermt | niet, dus houd zo'n waarde buiten {…} en […], en het zet de nabewerking niet uit: voor uitvoer die byte voor byte gelijk blijft, geef je ook postProcess: false mee

Nesting

Alle syntaxiselementen kunnen in willekeurige diepte in elkaar genest worden:

{option1|[<, > sub1|sub2|sub3]|option3}

[<minsize=2;maxsize=3;sep=", ";lastsep=" and "> {red|blue} apples|{big|small} oranges|bananas]

#set %var% = {a|[b|c]}

Nabewerking

De engine past automatische tekstcorrectie toe na de generatie:

1. Beschermt URLs (ook een losse https://), e-mails, domeinen, decimalen, afkortingen en tokens die met een punt beginnen (.NET, .gitignore, .xlsx) tegen hoofdlettergebruik en spatiëring
2. Elimineert dubbele spaties en tabs
3. Verwijdert spaties vóór interpunctie (, . ! ?)
4. Voegt spatie toe na interpunctie waar deze ontbreekt, maar nooit tussen een teken en het aanhalingsteken of de haak die het afsluit ("Really?", (etc.))
5. Maakt de eerste letter van de uitvoer een hoofdletter (HTML-tags worden overgeslagen)
6. Hoofdletter na zin-beëindigende interpunctie
7. Hoofdletter na block-level HTML-tags
8. Hoofdletter na regelafbrekingen
9. Herstelt beschermde plaatshouders

Hoofdlettergebruik volgt de render-locale: onder tr en az begint een zin die met i opent met İ. Een letterlijk blok wordt door elke stap overgeslagen.

Syntaxisoverzicht

De taal is haar prototype, Generating The Web (GTW), ontgroeid — sjablonen die voor GTW zijn geschreven, werken nog steeds ongewijzigd.