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.

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…)

#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"
• 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

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, e-mails, domeinen, decimalen en afkortingen tegen hoofdlettergebruik
2. Elimineert dubbele spaties en tabs
3. Verwijdert spaties vóór interpunctie (, . ! ?)
4. Voegt spatie toe na interpunctie waar deze ontbreekt
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

Syntaxisoverzicht

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