Spintax Söz Dizimi Referansı

Spintax şablon işaretlemesi için eksiksiz referans.

Sıralamalar { }

Listeden rastgele bir seçenek seçer.

{option1|option2|option3}

Örnekler

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

Kurallar

• Sınırlayıcılar: { ve }
• Ayırıcı: |
• Rastgele derinlikte iç içe geçmeyi destekler
• Boş seçenekler geçerlidir (boş dize üretir)
• Çözümleme en içteki ifadeden dışa doğru

Permütasyonlar [ ]

N öğe seçer, karıştırır ve ayırıcılarla birleştirir.

Basit permütasyonlar

Tüm öğeler dahil, boşlukla ayrılmış:

[1|2|3|4]

Çıktı örnekleri: 1 4 3 2, 2 3 4 1, 3 2 4 1

Ayırıcı ile

Başlangıçta < > içinde belirtilen tek tip ayırıcı:

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

Çıktı örnekleri: 2, 1, 4, 3 · 4, 3, 2, 1

Önemli: [ ve <ayırıcı> arasında boşluk olmamalıdır.

Öğe başına ayırıcılar

Her seçenek, önceki | işaretinden önce <sep> ile kendi ayırıcısını tanımlayabilir. Ayırıcı, karıştırma sırasında öğesiyle birlikte hareket eder.

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

Çıktı örnekleri: 1, 3, 2 and 4 · 3, 1, 2 and 4

Otomatik boşluk: <and> veya <or> gibi kelime ayırıcıları otomatik olarak boşluklarla doldurulur: <and> ·  and  üretir. Noktalama ayırıcıları (<,>) doldurulmaz.

Kombinasyonlu permütasyonlar

Yapılandırılabilir minimum/maksimum öğe sayısı ve ayırıcılar:

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

Çıktı örnekleri: apple, plum and orange · apple and apricot · orange

Yapılandırma parametreleri

Permütasyon kuralları

• Sınırlayıcılar: [ ve ]
• Yapılandırma bloğu <...> hemen [ sonrasında gelmelidir
• Yapılandırma parametreleri noktalı virgülle ayrılır
• Yapılandırmadaki dize değerleri tırnak içindedir: sep=", "
• Sıralamalar ve permütasyonlar seçeneklerin içinde iç içe geçebilir
• HTML öğeleri seçenek olabilir
• sep son çiftten öncekileri, lastsep ise o çifti birleştirir: iki öğe seçildiğinde yalnızca lastsep görünür, tek öğede ikisi de görünmez

Değişkenler %var%

Göründüğü her yerde yerine konan, yeniden kullanılabilir bir değişken tanımlar. Bunu iki direktif bildirir ve seçim kozmetik değildir: #set bir makrodur — değeri her referansta yeniden yerine konur, içindeki spintax yeniden çekilir; #def değeri her render’da bir kez çeker ve bu tek sonucu her referansa verir. (Bir render bir çıktıdır; aynı seed onu yeniden üretir.) Değer düz metin olduğu sürece ikisi aynıdır; fark, değer bir seçim içerdiği anda ortaya çıkar.

#set %VARIABLE_NAME% = value or spintax structure

#def %VARIABLE_NAME% = value or spintax structure

Örnekler

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

Değişken kuralları

• #set ve #def satır başında başlamalıdır
• Değişken adları % içine alınır: %name%
• Adlar harf, rakam ve alt çizgiden oluşur; referanslar büyük/küçük harfe duyarsızdır: %Tone% ile %tone% tek değişkendir
• Değerler herhangi bir spintax söz dizimi içerebilir (sıralamalar, permütasyonlar, başka değişkenler)
• #set bir makrodur: tanımda değil referansta açılır ve değeri — içindeki spintax dahil — her referansta yeniden yerine konur ve yeniden çekilir
• #def değerini her render’da bir kez çözer ve bu sonucu her yerde korur. Tekrar eden sözcükleri uyumlu tutan da budur: bir ad ve ondan türeyen biçimler, {plural} bloğunu besleyen sayı, tekrarlarının kelimesi kelimesine tutması gereken her ifade
• #def bir değişkeni kendisiyle tutarlı yapar; iki değişkeni ilişkilendirmez. #def %Noun% ile #def %NounGen% iki bağımsız çekimdir ve farklı sözcüklere düşebilir — uyuşması gereken biçimler tek bir çekimden gelmelidir: her biçimin başvurduğu tek bir #def gövdesi ya da aynı şekilde çekimlenen eş anlamlılar ve tanım dışına yazılan ek
• Bir ad bir kez tanımlanır. Aynı adın ikinci tanımı definition.duplicate-name olarak bildirilir, render yine de sürer: aynı türden iki direktif arasında sonraki kazanır, bir #set ile bir #def aynı adı paylaşırsa hangisi önce gelirse gelsin #def kazanır
• Tanımı olmayan bir referans kendini yazdırır: %missing% kaybolmak yerine çıktıda kalır
• İki direktif de #include sınırını geçmez: dahil edilen şablon ebeveynin yerel değişkenlerini görmez, kendisininkiler de yukarı sızmaz. Çekilmiş bir biçim çocuğa yalnızca çalışma zamanı değişkeni olarak ulaşır
• #set ve #def satırları çıktıdan çıkarılır
• Derinleşme: değişkenler kılavuzu (kapsamlar ve yeniden çekim tuzağı) ve dilbilgisel olarak güvenli eş anlamlılaştırma (durum aileleri)

Değişken kapsamları

Bir host değişkenleri birden fazla yerden verebilir. Aynı ad birkaç yerde varsa en güçlüsü kazanır:

1. Çalışma zamanı değişkenleri (en güçlü) — host’un render çağrısına geçirdiği değerler: @spintax/core içinde context, WordPress eklentisinde kısa kod öznitelikleri: [spintax slug="greeting" name="Alice"]
2. Yerel değişkenler — şablon içinde #set veya #def ile tanımlanır
3. Global değişkenler (en zayıf) — eklentinin Ayarlar sayfası gibi, host genelindeki varsayılanlar

Koşullar {?VAR?then|else}

Koşullar dilin kendi yapısıdır; GTW prototipinde buna benzer hiçbir şey yoktu. {a|b} değişkenleri umursamayan tek tip rastgele seçimken, {?VAR?then|else} %VAR%'in değeri olup olmamasına göre seçim yapar.

Değer odaklı seçimler için kullanın: ücretsiz katman varsa ücretsiz katman satırını göstermek, kullanıcı ücretli bir planda olduğunda pro özellik bloğunu render etmek, geçerli olmayan CTA'yı gizlemek.

Ön geçiş %var% genişletmesinden ve rastgele dal seçicisinden önce çalışır, böylece falsy bir dal tamamen elenir — içindeki hiçbir şey değerlendirilmez.

Formlar

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

Kural JavaScript'ten kasıtlı olarak daha basittir — truthy = en az bir boşluk olmayan karakter:

Koşul kuralları

• Değişken adları %var% ile aynı regex'i izler (büyük/küçük harf duyarsız)
• ! öneki kontrolü tersine çevirir: {?!VAR?yok}
• Derinlik 0'daki ilk | then'i else'den ayırır; sonrakiler else içinde literal kalır
• İç içe koşullar dıştan içe değerlendirilir — falsy dallar kısa devre yapar
• Bileşik mantık (&&, ||, karşılaştırmalar) desteklenmez — assembler'da bir koruma değişkenini önceden hesaplayın
• Bozuk formlar ({??yes}, {?VAR}) asla fırlatmaz — playground onları uyarı olarak işaretler
• Derinlemesine: örnekler ve anti-patternler için koşullu spintax kılavuzuna bakın

Çoğullar {plural %n%: dil|dil}

Bir sayıya göre kelimenin dilbilgisel olarak doğru biçimini seçer. Sayaç iki noktadan önce, biçimler ise sonra | ile ayrılarak yazılır.

Biçimi şablon değil render yerel ayarı belirler; dolayısıyla kaç biçim vermeniz gerektiği o yerel ayara bağlıdır. İngilizce iki, Rusça üç biçim ister.

{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

Yerel ayara göre biçimler

Yerel ayar dil alt etiketiyle eşleştirilir, bu yüzden ru-RU ile ru aynı davranır:

Biçim sayısı tutmazsa motor plural.arity bildirir ve bloğu tam genişlikli süslü parantezlerle görünür bırakır — yanlış bir çoğul sessizce yayına çıkmaz.

Çoğul kuralları

• Açılış, boşluk dahil birebirdir: {plural . {plural: x} ve {pluralN: x} çoğul bloğu değildir
• İki nokta zorunludur — sayacı biçimlerden ayırır
• Sayaç bir %Var% referansı veya tam sayı sabitidir; sayaçtaki değişkenler biçim seçilmeden önce yerine konur
• Negatif sayılar mutlak değeriyle işlenir; 0 "geri kalan her şey" biçimini alır
• Sayaç değişkeni #set değil #def olmalıdır — #set bir makrodur, dolayısıyla {1|4|9} gibi bir değer çoğul kararı verilirken hâlâ çözülmemiş spintax'tır ve blok boş render edilir. Playground bunu plural.count-macro olarak işaretler
• Sayısal olmayan veya tanımsız bir sayaç, tahmin yürütmek yerine bloğu siler
• Derinlemesine: Rusçanın üç biçimli kuralları ve işlenmiş örnekler için çoğul spintax kılavuzuna bakın

Dahil Etme #include

Direktifin bulunduğu yere başka bir şablon gömer. #include, motorun tek başına karşılayamadığı tek yapıdır: motor şablon deposu tutmaz, bu yüzden bir referansı şablon metnine çeviren resolver’ı host sağlar. Resolver kurulu olmayan yerlerde — bu sitedeki playground ve MCP sunucusu, ikisi de bilerek — direktif etkisizdir ve çıktıda düz metin olarak kalır.

#include "hero-text"

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

Dahil etme kuralları

• Direktif satırın tamamını kaplamalıdır. Baştaki boşluk sorun değil, referanstan sonra gelen metin sorundur — Metin #include "hero" düz metin olarak kalır
• Referans çift tırnak içindedir; tek tırnakla veya tırnaksız artık direktif sayılmaz
• Çözümleme host’a aittir: WordPress eklentisi slug ya da sayısal ID ile çözer, JavaScript host bir includeResolver geçirir
• Resolver yoksa satır çıktıda düz metin olarak kalır; resolver o şablonu bilmiyorsa satır bunun yerine silinir — bilinmeyen bir hedef bloğu sessizce götürür
• Dahil edilen şablonlar kendi değişkenlerini ve spintax’ını, kendi #include’larını içerebilir
• Dahil etmeler, ebeveynin sıralama ve permütasyonları çekildikten sonra çözülür: kazanan dalın içindeki dahil etme gömülür — elenen daldaki hiç gerçekleşmez
• Zincirler çalışır (bir şablon başkasını, o da bir üçüncüsünü dahil eder); kendini doğrudan ya da döngüyle dahil eden şablon ilk tekrarda kesilir — hata da tanı da vermeden
• Alt şablonlar global ve çalışma zamanı değişkenlerini devralır ama ebeveynin #set / #def yerellerini devralmaz, kendininkiler de yukarı sızmaz
• Dahil etme bir tanımın değeri olamaz: #def %x% = #include "y" def.include-in-value olarak reddedilir
• Render öncesi validate() bilinmeyen hedefi yalnızca host bilinen referans listesini geçirdiğinde bildirir; extract() şablonun ihtiyaç duyduğu referansları döndürür, host da onları böyle önceden yükler
• Derinleşme: şablon kompozisyonu kılavuzu — çoğu hattın bunun yerine kullandığı assembler deseni

Yorumlar /#...#/

Yorum işaretleri arasındaki metin, diğer işlemlerden önce çıktıdan kaldırılır.

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

Yorum kuralları

• Başlangıç sınırlayıcı: /#
• Bitiş sınırlayıcı: #/
• Birden fazla satıra yayılabilir
• İç içe geçemez
• Diğer işlemlerden önce kaldırılır

İç İçe Geçme

Tüm söz dizimi öğeleri rastgele derinlikte birbirinin içine yerleştirilebilir:

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

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

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

Son İşleme

Motor, oluşturma sonrası otomatik metin düzeltmesi uygular:

1. URL'leri, e-postaları, alan adlarını, ondalık sayıları ve kısaltmaları büyük harften korur
2. Yinelenen boşlukları ve sekmeleri temizler
3. Noktalama işaretlerinden önceki boşlukları kaldırır (, . ! ?)
4. Eksik olan yerlerde noktalama işaretlerinden sonra boşluk ekler
5. Çıktının ilk harfini büyük yapar (HTML etiketlerini atlar)
6. Cümle sonu noktalama işaretlerinden sonra büyük harf
7. Blok düzeyinde HTML etiketlerinden sonra büyük harf
8. Satır sonlarından sonra büyük harf
9. Korunan yer tutucuları geri yükler

Söz Dizimi Özeti

Dil, prototipi olan Generating The Web (GTW) uygulamasını geride bıraktı; GTW için yazılmış şablonlar hâlâ değişiklik olmadan çalışır.