Referenca Spintax sintakse

Kompletna referenca za spintax markup šablona.

Nabrajanja { }

Nasumično bira jednu opciju sa liste.

{option1|option2|option3}

Primeri

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

Pravila

• Graničnici: { i }
• Separator opcija: |
• Podržava ugnežđivanje proizvoljne dubine
• Prazne opcije su dozvoljene (daju prazan string)
• Razrešavanje ide od najdubljeg izraza ka spolja

Permutacije [ ]

Bira N elemenata, meša ih i spaja separatorima.

Jednostavne permutacije

Svi elementi su uključeni, razdvojeni razmacima:

[1|2|3|4]

Primeri rezultata: 1 4 3 2, 2 3 4 1, 3 2 4 1

Sa separatorom

Zajednički separator se navodi u < > na početku:

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

Primeri rezultata: 2, 1, 4, 3 · 4, 3, 2, 1

Važno: Nema razmaka između [ i <separator>.

Separatori po elementu

Svaka opcija može imati sopstveni separator zadat kroz <sep> pre prethodnog |. Separator putuje sa svojim elementom tokom mešanja.

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

Primeri rezultata: 1, 3, 2 and 4 · 3, 1, 2 and 4

Auto-razmaci: Separatori-reči poput <i> ili <ili> automatski se dopunjuju razmacima, pa <i> daje  i . Interpunkcijski separatori (<,>) se ne dopunjuju.

Permutacije sa kombinacijama

Podesiv min./maks. broj elemenata i separatori:

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

Primeri rezultata: apple, plum and orange · apple and apricot · orange

Parametri konfiguracije

Pravila permutacija

• Graničnici: [ i ]
• Konfiguracioni blok <...> mora ići odmah posle [
• Parametri konfiguracije se razdvajaju tačkom i zarezom
• String vrednosti u konfiguraciji idu pod navodnike: sep=", "
• Nabrajanja i permutacije mogu biti ugnežđeni u opcije
• HTML elementi mogu biti opcije
• sep spaja sve pre poslednjeg para, lastsep spaja taj par: kada su izabrana dva elementa pojavljuje se samo lastsep, a kada je jedan — nijedan

Promenljive %var%

Definiše promenljivu za višekratnu upotrebu koja se zamenjuje svuda gde se pojavi. Deklarišu je dve direktive, i izbor nije kozmetički: #set je makro — njegova vrednost se iznova zamenjuje pri svakoj referenci, pa se spintax u njoj iznova baca; #def baca vrednost jednom po renderu i predaje taj jedan rezultat svakoj referenci. (Jedan render je jedan izlaz; isti seed ga reprodukuje.) Dok je vrednost običan tekst, njih dve su identične; razlika se pojavljuje onog trenutka kada vrednost sadrži izbor.

#set %VARIABLE_NAME% = value or spintax structure

#def %VARIABLE_NAME% = value or spintax structure

Primeri

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

Pravila promenljivih

• #set i #def moraju da počnu od početka reda
• Imena promenljivih se stavljaju u %: %name%
• Imena čine slova, cifre i donja crta, a reference ne razlikuju veličinu slova: %Tone% i %tone% su ista promenljiva
• Vrednosti mogu da sadrže bilo koju spintax sintaksu (nabrajanja, permutacije, druge promenljive)
• #set je makro: širi se pri referenci, ne pri definiciji, i njegova vrednost — zajedno sa spintax-om u njoj — iznova se zamenjuje i iznova baca pri svakoj referenci
• #def razrešava vrednost jednom po renderu i drži taj rezultat svuda. Upravo to drži ponavljanja usklađenim: imenicu i oblike izvedene iz nje, broj koji hrani {plural} blok, svaku frazu čija ponavljanja moraju da se poklope reč po reč
• #def čini jednu promenljivu doslednom sa samom sobom; on ne povezuje dve promenljive. #def %Noun% i #def %NounGen% su dva nezavisna bacanja i mogu da padnu na različite reči — oblici koji moraju da se slažu treba da dođu iz jednog bacanja: jedna #def osnova na koju upućuje svaki oblik, ili sinonimi koji se menjaju isto, sa nastavkom napisanim izvan definicije
• Ime se definiše jednom. Druga definicija istog imena prijavljuje se kao definition.duplicate-name i render ipak ide dalje: između dve iste direktive pobeđuje kasnija, a kada #set i #def dele ime, pobeđuje #def — svejedno koja je bila prva
• Referenca bez definicije ispisuje samu sebe: %missing% ostaje u izlazu umesto da nestane
• Nijedna direktiva ne prelazi preko #include: uključeni šablon ne vidi roditeljeve lokalne promenljive, a njegove ne cure nazad. Već bačeni oblik stiže do deteta samo kao promenljiva iz izvršavanja
• Redovi #set i #def se uklanjaju iz izlaza
• Detaljnije: vidi vodič za promenljive (opsezi i zamka ponovnog bacanja) i gramatički bezbednu sinonimizaciju (padežne porodice)

Opsezi promenljivih

Host može da isporuči promenljive sa više mesta. Kada isto ime postoji na nekoliko njih, pobeđuje najjače:

1. Promenljive iz izvršavanja (najjače) — ono što host prosleđuje pozivu rendera: context u @spintax/core, atributi shortcode-a u WordPress dodatku: [spintax slug="greeting" name="Alice"]
2. Lokalne promenljive — definisane sa #set ili #def unutar šablona
3. Globalne promenljive (najslabije) — podrazumevane vrednosti na nivou hosta, poput stranice podešavanja dodatka

Uslovi {?VAR?then|else}

Uslovi su sopstvena konstrukcija jezika — u GTW prototipu ništa slično nije postojalo. Dok je {a|b} ravnomeran nasumičan izbor koji ignoriše promenljive, {?VAR?then|else} bira prema tome da li %VAR% ima vrednost.

Koristite ga za izbore vođene vrednošću: prikažite red o besplatnom paketu samo kad besplatan paket postoji, renderujte blok pro funkcija samo kad je korisnik na plaćenom planu, sakrijte CTA koji se ne primenjuje.

Pre-pass se izvršava pre razvijanja %var% i pre nasumičnog birača grana, pa se falsy grana odbacuje u celini — ništa u njoj se ne izračunava.

Oblici

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

Pravilo je namerno jednostavnije nego u JavaScriptu — truthy = bar jedan znak koji nije razmak:

Pravila uslova

• Imena promenljivih prate isti regex kao %var% (bez razlikovanja velikih i malih slova)
• Prefiks ! obrće proveru: {?!VAR?nema podataka}
• Prvi | na dubini 0 razdvaja then od else; kasniji | na vrhu ostaju literali u else
• Ugnežđeni uslovi se izračunavaju outer-first — falsy grane se kratko spajaju
• Složena logika (&&, ||, poređenja) nije podržana — izračunajte guard promenljivu u asembleru
• Neispravni oblici ({??yes}, {?VAR}) nikad ne bacaju grešku — playground ih obeležava kao upozorenja
• Detaljno: pogledajte vodič za uslovni spintax sa razrađenim primerima i anti-šablonima

Plurali {plural %n%: varijanta|varijante|varijanti}

Bira gramatički ispravan oblik reči za broj. Brojač ide pre dvotačke, oblici posle nje, razdvojeni sa |.

Oblik bira lokal renderovanja, a ne šablon — pa broj oblika koje morate navesti zavisi od tog lokala. Srpskom trebaju tri, engleskom dva.

{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

Oblici po lokalu

Lokal se poklapa po jezičkom subtagu, pa se sr-RS i sr ponašaju identično:

Navedete li pogrešan broj oblika, motor prijavljuje plural.arity i ostavlja blok vidljivim u zagradama pune širine — pogrešan plural nikada ne odlazi u produkciju ćutke.

Pravila plurala

• Otvaranje je literalno, uključujući razmak: {plural . {plural: x} i {pluralN: x} nisu plural blokovi
• Dvotačka je obavezna — razdvaja brojač od oblika
• Brojač je referenca %Var% ili celobrojni literal; promenljive u brojaču se zamenjuju pre izbora oblika
• Negativni brojevi koriste apsolutnu vrednost; 0 uzima oblik „sve ostalo“ (u srpskom — „varijanti“)
• Promenljiva-brojač mora biti #def, a ne #set — #set je makro, pa je vrednost poput {1|4|9} u trenutku izbora oblika i dalje nerazrešen spintax i ceo blok se renderuje prazan. Playground to obeležava kao plural.count-macro
• Nenumerički ili nedefinisan brojač briše blok umesto da pogađa
• Detaljno: pogledajte vodič za plurale — pravila tri oblika i razrađeni primeri

Uključivanja #include

Ugrađuje drugi šablon na mesto direktive. #include je jedina konstrukcija koju motor ne može sam da opsluži: ne drži skladište šablona, pa host isporučuje resolver koji referencu pretvara u tekst šablona. Tamo gde resolver nije instaliran — playground i MCP server na ovom sajtu, oboje namerno — direktiva je inertna i ostaje u izlazu kao doslovan tekst.

#include "hero-text"

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

Pravila uključivanja

• Direktiva mora da zauzme ceo red. Uvlačenje s leve strane je u redu, tekst posle reference nije — Tekst #include "hero" ostaje doslovan
• Referenca ide pod dvostruke navodnike; sa jednostrukim ili bez navodnika to više nije direktiva
• Razrešavanje pripada hostu: WordPress dodatak razrešava po slug-u ili numeričkom ID-u, JavaScript host prosleđuje includeResolver
• Bez resolvera red ostaje doslovan u izlazu; ako resolver nema taj šablon, red se umesto toga uklanja — nepoznata meta te tiho košta celog bloka
• Uključeni šabloni mogu imati sopstvene promenljive i spintax, i sopstveni #include
• Uključivanja se razrešavaju pošto su nabrajanja i permutacije roditelja već izvučeni: uključivanje u grani koja je pobedila biva ugrađeno — ono u odbačenoj grani se nikada ne dešava
• Lanci rade (šablon uključuje šablon koji uključuje sledeći); šablon koji uključuje sam sebe, direktno ili u ciklusu, seče se na prvom ponavljanju — bez greške i bez dijagnostike
• Šabloni deca nasleđuju globalne promenljive i one iz izvršavanja, ali ne roditeljeve lokalne #set / #def, a sopstvene ne cure nazad
• Uključivanje ne može biti vrednost definicije: #def %x% = #include "y" odbija se kao def.include-in-value
• Pre rendera validate() prijavljuje nepoznatu metu samo ako host prosledi listu poznatih referenci; extract() vraća reference koje šablonu trebaju, i tako ih host unapred učitava
• Detaljnije: vidi vodič za kompoziciju šablona — obrazac asemblera koji većina pipeline-a koristi umesto ovoga

Komentari /#...#/

Tekst između markera komentara uklanja se iz rezultata pre svake druge obrade.

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

Pravila komentara

• Početni graničnik: /#
• Završni graničnik: #/
• Može se protezati kroz više redova
• Ugnežđivanje nije podržano
• Uklanjaju se pre svake druge obrade

Ugnežđivanje

Svi elementi sintakse mogu se ugnežđivati jedni u druge do proizvoljne dubine:

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

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

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

Postobrada

Motor automatski koriguje tekst posle generisanja:

1. Zaštita URL-ova, imejl adresa, domena, decimalnih brojeva i skraćenica od promene velikih slova
2. Sažimanje dupliranih razmaka i tabulatora
3. Uklanjanje razmaka pre interpunkcije (, . ! ?)
4. Dodavanje razmaka posle interpunkcije gde nedostaje
5. Veliko slovo na početku rezultata (uz preskakanje HTML tagova)
6. Veliko slovo posle znakova kraja rečenice
7. Veliko slovo posle blokovskih HTML tagova
8. Veliko slovo posle preloma reda
9. Vraćanje zaštićenih čuvara mesta

Pregled sintakse

Jezik je prerastao svoj prototip, Generating The Web (GTW): šabloni napisani za GTW i dalje rade bez izmena.