Даведнік сінтаксісу Spintax

Поўны даведнік па шаблоннай разметцы spintax.

Пералікі { }

Выпадковым чынам выбірае адзін варыянт са спісу.

{option1|option2|option3}

Прыклады

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

Правілы

• Абмежавальнікі: { і }
• Падзяляльнік варыянтаў: |
• Падтрымлівае ўкладзенасць адвольнай глыбіні
• Пустыя варыянты дапушчальныя (даюць пусты радок)
• Разгортванне ідзе ад самага ўнутранага выразу вонкі

Перастаноўкі [ ]

Выбірае N элементаў, перамешвае іх і аб’ядноўвае з падзяляльнікамі.

Простыя перастаноўкі

Усе элементы ўключаны, падзелены прабеламі:

[1|2|3|4]

Прыклады выніку: 1 4 3 2, 2 3 4 1, 3 2 4 1

З падзяляльнікам

Адзіны падзяляльнік указваецца ў < > у пачатку:

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

Прыклады выніку: 2, 1, 4, 3, 4, 3, 2, 1

Важна: Паміж [ і <падзяляльнік> няма прабелу.

Падзяляльнікі для кожнага элемента

У кожнага варыянта можа быць свой падзяляльнік, зададзены праз <sep> перад папярэднім |. Падзяляльнік перамяшчаецца разам са сваім элементам пры перамешванні.

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

Прыклады выніку: 1, 3, 2 and 4, 3, 1, 2 and 4

Аўта-прабелы: Слоўныя падзяляльнікі кшталту <і> ці <або> аўтаматычна дапаўняюцца прабеламі: <і> дае  і . Знакі прыпынку (<,>) не дапаўняюцца.

Перастаноўкі з камбінацыямі

Наладжвальная мін./макс. колькасць элементаў і падзяляльнікі:

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

Прыклады выніку: apple, plum and orange, apple and apricot, orange

Параметры канфігурацыі

Правілы перастановак

• Абмежавальнікі: [ і ]
• Блок канфігурацыі <...> павінен ісці адразу за [
• Параметры канфігурацыі падзяляюцца кропкай з коскай
• Радковыя значэнні ў канфігурацыі бяруцца ў двукоссі: sep=", "
• Пералікі і перастаноўкі могуць быць укладзены ў варыянты
• HTML-элементы могуць быць варыянтамі

Зменныя %var%

Вызначае зменную для шматразовага выкарыстання, якая падстаўляецца ўсюды, дзе сустракаецца.

#set %VARIABLE_NAME% = value or spintax structure
#def %VARIABLE_NAME% = value or spintax structure

Прыклады

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

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

Правілы зменных

• #set і #def павінны пачынацца з пачатку радка
• Імёны зменных бяруцца ў %: %name%
• Імёны зменных складаюцца з літар, лічбаў і падкрэсленняў
• Значэнні могуць змяшчаць любы сінтаксіс spintax (пералікі, перастаноўкі, іншыя зменныя)
• #set-зменныя разгортваюцца пры звароце, а не пры вызначэнні (лянівае вылічэнне)
• #set — макрас: яго значэнне падстаўляецца нанава, і spintax унутры перакідваецца, пры кожнай спасылцы. #def разгортвае значэнне адзін раз за рэндэр і трымае вынік усюды
• Радкі #set і #def выдаляюцца з выніку

Вобласці бачнасці зменных у плагіне WordPress

Плагін падтрымлівае тры вобласці бачнасці зменных. Калі адно і тое ж імя існуе ў некалькіх абласцях, перамагае наймацнейшая:

1. Runtime-зменныя (наймацнейшыя) — перадаюцца праз шорткод: [spintax slug="greeting" name="Alice"]
2. Лакальныя зменныя — вызначаюцца праз #set ці #def унутры шаблона
3. Глабальныя зменныя (найслабейшыя) — вызначаюцца на старонцы налад

Умовы {?VAR?then|else}

Умоўны сінтаксіс — адметнае пашырэнне spintax.net над сямействам GTW. Калі {a|b} — гэта раўнамерны выпадковы выбар, які не глядзіць на зменныя, то {?VAR?then|else} выбірае паводле таго, ці мае %VAR% значэнне.

Выкарыстоўвайце для рашэнняў паводле значэння: паказваць радок пра бясплатны тарыф толькі калі тарыф ёсць, рэндэрыць блок пра-магчымасцяў толькі калі карыстальнік на платным тарыфе, хаваць CTA, які цяпер не дастасоўны.

Pre-pass адпрацоўвае да разгортвання %var% і да выпадковага выбару галін, таму falsy-галіна адкідваецца цалкам — нішто ўнутры яе не вылічаецца.

Формы

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

Правіла прасцейшае, чым у JavaScript — truthy = хаця б адзін непрабельны сімвал:

Правілы ўмоў

• Імёны зменных адпавядаюць таму ж regex, што і %var% (без уліку рэгістра)
• Прэфікс ! інвертуе праверку: {?!VAR?няма даных}
• Першы | на нулявой глыбіні падзяляе then і else; наступныя | застаюцца літараламі ў else
• Укладзеныя ўмовы разгортваюцца outer-first — falsy-галіны короткозамыкаюцца
• Састаўная логіка (&&, ||, параўнанні) не падтрымліваецца — вылічыце guard-зменную ў асэмблеры
• Крывыя формы ({??yes}, {?VAR}) не падаюць — пясочніца пазначае іх папярэджаннямі
• Падрабязна: гл. гайд па ўмоўным spintax з прыкладамі і анты-патэрнамі

Плюралы {plural %n%: мова|мовы|моў}

Падбірае граматычна правільную форму слова пад лік. Лічыльнік ідзе да двукроп’я, формы — пасля, праз |.

Форму выбірае лакаль рэндэра, а не шаблон, таму колькасць формаў залежыць ад лакалі: беларускай патрэбныя тры, англійскай — дзве.

{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

Формы па лакалях

Лакаль супастаўляецца па моўным субтэгу, так што be-BY і be паводзяць сябе аднолькава:

Калі формаў не столькі, колькі трэба лакалі, рухавік аддае plural.arity і пакідае блок бачным у поўнашырынных дужках — моўчкі няправільная форма ў прадакшн не паедзе.

Правілы плюралаў

• Адкрывальная частка літаральная, разам з прабелам: {plural . {plural: x} і {pluralN: x} плюраламі не з’яўляюцца
• Двукроп’е абавязковае — яно аддзяляе лічыльнік ад формаў
• Лічыльнік — гэта спасылка %Var% ці цэлалікавы літарал; зменныя ў лічыльніку падстаўляюцца да выбару формы
• Адмоўныя лікі бяруцца па модулі; 0 атрымлівае форму «усё астатняе» (па-беларуску — «моў»)
• Зменная-лічыльнік мусіць быць #def, а не #set — #set гэта макрас, таму значэнне кшталту {1|4|9} на момант выбару формы ўсё яшчэ неразгорнуты spintax, і блок адрэндэрыцца пустым. У пясочніцы гэта plural.count-macro
• Нелікавы ці нявызначаны лічыльнік сцірае блок, а не адгадвае форму
• Падрабязна: гл. гайд па плюралах — правілы трох формаў і разборы прыкладаў

Уключэнні #include

Убудоўвае іншы шаблон у пазіцыю дырэктывы.

#include "hero-text"

Правілы ўключэнняў

• Спасылка на шаблон указваецца ў двайных двукоссях
• Разгортваецца па slug ці лікавым ID шаблона
• Уключаныя шаблоны могуць змяшчаць уласныя зменныя і сінтаксіс spintax
• Рэкурсіўныя ўключэнні падтрымліваюцца
• Цыклічныя спасылкі выяўляюцца і блакуюцца
• Даччыныя шаблоны ўспадкоўваюць глабальныя і runtime-зменныя, але не лакальныя #set / #def бацькоўскага

Каментары /#...#/

Тэкст паміж маркерамі каментароў выдаляецца з выніку да любой іншай апрацоўкі.

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

Правілы каментароў

• Адкрывальны абмежавальнік: /#
• Закрывальны абмежавальнік: #/
• Можа займаць некалькі радкоў
• Укладзенасць не падтрымліваецца
• Выдаляюцца да пачатку любой іншай апрацоўкі

Укладзенасць

Усе элементы сінтаксісу могуць быць укладзены адзін у адзін на адвольную глыбіню:

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

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

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

Постапрацоўка

Рухавік аўтаматычна карэктуе тэкст пасля генерацыі:

1. Абарона URL, email-адрасоў, даменаў, дзесятковых лікаў і абрэвіятур ад змены рэгістра
2. Выдаленне паўторных прабелаў і табуляцый
3. Выдаленне прабелаў перад знакамі прыпынку (, . ! ?)
4. Даданне прабелу пасля знакаў прыпынку там, дзе яго не хапае
5. Вялікая літара ў пачатку выніку (з пропускам HTML-тэгаў)
6. Вялікая літара пасля знакаў канца сказа
7. Вялікая літара пасля блокавых HTML-тэгаў
8. Вялікая літара пасля пераносаў радкоў
9. Аднаўленне абароненых запаўняльнікаў

Зводка сінтаксісу

Сінтаксіс сумяшчальны са стандартам Generating The Web (GTW).