Riferimento sintassi Spintax

Riferimento completo per il markup dei template spintax.

Enumerazioni { }

Seleziona casualmente una opzione dalla lista.

{option1|option2|option3}

Esempi

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

Regole

• Delimitatori: { e }
• Separatore: |
• Supporta l'annidamento a profondità arbitraria
• Le opzioni vuote sono valide (producono stringa vuota)
• La risoluzione avviene dall'espressione più interna verso l'esterno

Permutazioni [ ]

Seleziona N elementi, li mescola e li unisce con separatori.

Permutazioni semplici

Tutti gli elementi inclusi, separati da spazi:

[1|2|3|4]

Esempi di output: 1 4 3 2, 2 3 4 1, 3 2 4 1

Con separatore

Separatore uniforme specificato in < > all'inizio:

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

Esempi di output: 2, 1, 4, 3 · 4, 3, 2, 1

Importante: Nessuno spazio tra [ e <separatore>.

Separatori per elemento

Ogni opzione può avere il proprio separatore definito con <sep> prima del | precedente. Il separatore viaggia con il suo elemento durante la mescolanza.

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

Esempi di output: 1, 3, 2 and 4 · 3, 1, 2 and 4

Spaziatura automatica: I separatori testuali come <and> o <or> vengono automaticamente circondati da spazi: <and> produce  and . I separatori di punteggiatura (<,>) non vengono completati.

Permutazioni con combinazioni

Numero minimo/massimo di elementi e separatori configurabili:

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

Esempi di output: apple, plum and orange · apple and apricot · orange

Parametri di configurazione

Regole delle permutazioni

• Delimitatori: [ e ]
• Il blocco di configurazione <...> deve seguire immediatamente [
• I parametri di configurazione sono separati da punto e virgola
• I valori stringa nella configurazione sono tra virgolette: sep=", "
• Le enumerazioni e le permutazioni possono essere annidate nelle opzioni
• Gli elementi HTML possono essere opzioni
• sep unisce tutto ciò che precede l'ultima coppia, lastsep unisce quella coppia: con due elementi appare solo lastsep, con uno nessuno dei due

Variabili %var%

Definisce una variabile riutilizzabile, sostituita ovunque compaia. Due direttive la dichiarano, e la scelta non è cosmetica: #set è una macro — il suo valore viene risostituito a ogni riferimento, quindi lo spintax al suo interno viene riestratto; #def estrae il valore una volta per rendering e consegna quell’unico risultato a ogni riferimento. (Un rendering è un output; lo stesso seed lo riproduce.) Finché il valore è testo semplice le due sono identiche; la differenza compare nel momento in cui il valore contiene una scelta.

#set %VARIABLE_NAME% = value or spintax structure

#def %VARIABLE_NAME% = value or spintax structure

Esempi

#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.

Regole delle variabili

• #set e #def devono iniziare a inizio riga
• I nomi delle variabili sono racchiusi tra %: %name%
• I nomi sono alfanumerici + underscore, e i riferimenti non distinguono maiuscole e minuscole: %Tone% e %tone% sono la stessa variabile
• I valori possono contenere qualsiasi sintassi spintax (enumerazioni, permutazioni, altre variabili)
• #set è una macro: si espande al riferimento, non alla definizione, e il suo valore — compreso lo spintax al suo interno — viene risostituito e riestratto a ogni riferimento
• #def risolve il suo valore una volta per rendering e mantiene quel risultato ovunque. È questo che tiene concordi le ripetizioni: un sostantivo e le forme costruite da esso, un numero che alimenta un blocco {plural}, qualsiasi frase le cui ripetizioni devono coincidere parola per parola
• #def rende una variabile coerente con sé stessa; non correla due variabili. #def %Noun% e #def %NounGen% sono due estrazioni indipendenti e possono cadere su parole diverse — le forme che devono concordare devono venire da una sola estrazione: una radice in #def a cui ogni forma fa riferimento, oppure sinonimi che si declinano allo stesso modo con la desinenza scritta fuori dalla definizione
• Un nome si definisce una volta. Una seconda definizione dello stesso nome viene segnalata come definition.duplicate-name e il rendering prosegue comunque: fra due direttive uguali vince l’ultima, e quando un #set e un #def condividono il nome vince il #def, qualunque dei due venga prima
• Un riferimento senza definizione stampa sé stesso: %missing% resta nell’output invece di sparire
• Nessuna delle due direttive attraversa un #include: il template incluso non vede le locali del genitore, e le proprie non risalgono. Una forma già estratta raggiunge il figlio solo come variabile di runtime
• Le righe #set e #def vengono rimosse dall’output
• Approfondire: vedi la guida alle variabili (ambiti e trappola della riestrazione) e la sinonimizzazione grammaticalmente sicura (famiglie di casi)

Ambiti delle variabili

Un host può fornire variabili da più punti. Quando lo stesso nome esiste in più di uno, vince il più forte:

1. Variabili di runtime (le più forti) — ciò che l’host passa alla chiamata di rendering: context in @spintax/core, attributi dello shortcode nel plugin WordPress: [spintax slug="greeting" name="Alice"]
2. Variabili locali — definite con #set o #def dentro il template
3. Variabili globali (le più deboli) — impostazioni predefinite dell’host, come la pagina Impostazioni del plugin

Condizionali {?VAR?then|else}

I condizionali sono un costrutto proprio del linguaggio: nulla di simile esisteva nel prototipo GTW. Mentre {a|b} è una scelta casuale uniforme che ignora le variabili, {?VAR?then|else} sceglie in base al fatto che %VAR% abbia un valore.

Usalo per scelte guidate dai valori: mostrare una riga sul piano gratuito solo se esiste, renderizzare un blocco funzionalità pro solo se l'utente è su un piano a pagamento, nascondere un CTA non applicabile.

Il pre-pass gira prima dell'espansione di %var% e prima del selettore casuale di rami, così un ramo falsy viene scartato completamente — nulla al suo interno viene valutato.

Forme

{?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 e falsy

La regola è volutamente più semplice di JavaScript — truthy = almeno un carattere non-spazio:

Regole dei condizionali

• I nomi delle variabili seguono la stessa regex di %var% (case-insensitive)
• Il prefisso ! inverte il controllo: {?!VAR?assente}
• Il primo | a profondità 0 separa then da else; quelli successivi restano letterali in else
• I condizionali annidati si valutano dall'esterno — i rami falsy fanno short-circuit
• La logica composita (&&, ||, confronti) non è supportata — pre-calcola una variabile guardia nell'assemblatore
• Forme malformate ({??yes}, {?VAR}) non lanciano mai — il playground le segnala come avvisi
• Approfondire: vedi la guida allo spintax condizionale con esempi e anti-pattern

Plurali {plural %n%: lingua|lingue}

Sceglie la forma grammaticalmente corretta di una parola in base a un numero. Il contatore precede i due punti, le forme seguono, separate da |.

La forma è scelta dalla locale di render, non dal template: quante forme devi fornire dipende quindi da quella locale. L'inglese ne richiede due, il russo tre.

{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

Forme per locale

La locale viene confrontata sul suo subtag di lingua, quindi ru-RU e ru si comportano allo stesso modo:

Se il numero di forme non corrisponde, il motore segnala plural.arity e lascia il blocco visibile con parentesi a tutta larghezza: un plurale sbagliato non va mai in produzione in silenzio.

Regole dei plurali

• L'apertura è letterale, spazio incluso: {plural . {plural: x} e {pluralN: x} non sono blocchi plurali
• I due punti sono obbligatori: separano il contatore dalle forme
• Il contatore è un riferimento %Var% o un intero letterale; le variabili nel contatore vengono sostituite prima della scelta della forma
• I numeri negativi si prendono in valore assoluto; lo 0 riceve la forma «tutto il resto»
• Una variabile contatore deve essere #def, non #set: #set è una macro, quindi un valore come {1|4|9} è ancora spintax non risolto quando si decide il plurale e il blocco viene reso vuoto. Il playground lo segnala come plural.count-macro
• Un contatore non numerico o indefinito cancella il blocco invece di indovinare
• Approfondire: vedi la guida ai plurali con le regole russe a tre forme ed esempi svolti

Include #include

Incorpora un altro template nella posizione della direttiva. #include è l’unico costrutto che il motore non può soddisfare da solo: non conserva template, quindi è l’host a fornire un resolver che trasforma un riferimento in testo di template. Dove nessun resolver è installato — il playground e il server MCP di questo sito, entrambi di proposito — la direttiva è inerte e resta nell’output come testo letterale.

#include "hero-text"

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

Regole degli include

• La direttiva deve occupare l’intera riga. L’indentazione va bene, il testo dopo il riferimento no — Testo #include "hero" resta letterale
• Il riferimento va tra virgolette doppie; con apici singoli o senza virgolette non è più la direttiva
• La risoluzione spetta all’host: il plugin WordPress risolve per slug o ID numerico, un host JavaScript passa un includeResolver
• Senza resolver la riga resta letterale nell’output; se il resolver non ha quel template la riga viene invece rimossa — una destinazione sconosciuta ti costa il blocco in silenzio
• I template inclusi possono contenere variabili e spintax propri, e propri #include
• Le inclusioni si risolvono dopo che enumerazioni e permutazioni del genitore sono state estratte: un’inclusione nel ramo vincente viene incorporata — una in un ramo scartato non accade mai
• Le catene funzionano (un template ne include un altro che ne include un terzo); un template che include sé stesso, direttamente o in un ciclo, viene troncato alla prima ripetizione — senza errore e senza diagnostica
• I template figli ereditano variabili globali e di runtime ma non le locali #set / #def del genitore, e le proprie non risalgono
• Un’inclusione non può essere il valore di una definizione: #def %x% = #include "y" viene rifiutato come def.include-in-value
• Prima del rendering validate() segnala una destinazione sconosciuta solo se l’host passa l’elenco dei riferimenti noti; extract() restituisce i riferimenti che servono al template, ed è così che l’host li precarica
• Approfondire: vedi la guida alla composizione dei template, il pattern dell’assemblatore che la maggior parte delle pipeline usa al suo posto

Commenti /#...#/

Il testo tra i marcatori di commento viene rimosso dall'output prima di qualsiasi altra elaborazione.

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

Regole dei commenti

• Delimitatore di inizio: /#
• Delimitatore di fine: #/
• Possono estendersi su più righe
• Non possono essere annidati
• Rimossi prima di qualsiasi altra elaborazione

Annidamento

Tutti gli elementi di sintassi possono essere annidati l'uno nell'altro a profondità arbitraria:

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

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

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

Post-elaborazione

Il motore applica la correzione automatica del testo dopo la generazione:

1. Protegge URL, email, domini, decimali e abbreviazioni dalla capitalizzazione
2. Elimina spazi e tabulazioni duplicati
3. Rimuove gli spazi prima della punteggiatura (, . ! ?)
4. Aggiunge uno spazio dopo la punteggiatura dove manca
5. Capitalizza la prima lettera dell'output (saltando i tag HTML)
6. Capitalizza dopo la punteggiatura di fine frase
7. Capitalizza dopo i tag HTML a livello di blocco
8. Capitalizza dopo le interruzioni di riga
9. Ripristina i segnaposto protetti

Riepilogo della sintassi

Il linguaggio ha superato il suo prototipo, Generating The Web (GTW): i template scritti per GTW funzionano ancora senza modifiche.