مرجع صياغة 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

التباعد التلقائي: فواصل الكلمات مثل <and> أو <or> تُحاط تلقائياً بمسافات: <and> ينتج  and . فواصل علامات الترقيم (<,>) لا تُكمَّل.

تباديل مع تركيبات

عدد أدنى/أقصى قابل للتكوين من العناصر والفواصل:

[<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. متغيرات وقت التشغيل (الأقوى) — تُمرر عبر الشورت كود: [spintax slug="greeting" name="Alice"]
2. المتغيرات المحلية — تُعرَّف بـ #set أو #def داخل القالب
3. المتغيرات العامة (الأضعف) — تُعرَّف في صفحة الإعدادات

الشروط {?VAR?then|else}

الشروط هي الامتداد المميز لـ spintax.net على عائلة GTW. بينما {a|b} هو اختيار عشوائي موحد يتجاهل المتغيرات، يختار {?VAR?then|else} بناءً على ما إذا كانت %VAR% تحمل قيمة.

استخدمه للاختيارات المعتمدة على القيم: إظهار سطر الخطة المجانية فقط عند وجودها، عرض كتلة الميزات الاحترافية فقط عندما يكون المستخدم على خطة مدفوعة، إخفاء CTA غير قابل للتطبيق.

يُنفَّذ التمرير المسبق قبل توسيع %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?غائبة}
• أول | على عمق 0 يفصل then عن else؛ ما بعده يبقى حرفيًا في else
• تُقَيَّم الشروط المتداخلة من الخارج إلى الداخل — الفرع falsy يقصر الدائرة
• المنطق المركب (&&، ||، المقارنات) غير مدعوم — احسب متغير حماية في المُجمّع
• الأشكال المشوهة ({??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

الصيغ حسب اللغة

تُطابَق اللغة عبر وسمها الفرعي، لذا تتصرف ru-RU وru بالطريقة نفسها:

إذا لم يطابق عدد الصيغ ما تحتاجه اللغة، يبلّغ المحرك عن plural.arity ويترك الكتلة ظاهرة بأقواس كاملة العرض — فلا يمر جمع خاطئ بصمت.

قواعد الجمع

• الافتتاح حرفي بما فيه المسافة: {plural . أما {plural: x} و{pluralN: x} فليستا كتلتَي جمع
• النقطتان إلزاميتان — فهما تفصلان العدّاد عن الصيغ
• العدّاد إما إشارة %Var% أو عدد صحيح حرفي؛ وتُستبدل المتغيرات داخل العدّاد قبل اختيار الصيغة
• الأعداد السالبة تُؤخذ بقيمتها المطلقة، و0 يأخذ صيغة «كل ما عدا ذلك»
• متغير العدّاد يجب أن يكون #def لا #set — فـ#set ماكرو، وقيمة مثل {1|4|9} تبقى spintax غير محلول لحظة اختيار الصيغة فتُعرض الكتلة فارغة. تشير الساحة إلى ذلك بالرمز plural.count-macro
• العدّاد غير الرقمي أو غير المعرّف يمحو الكتلة بدل التخمين
• التعمق: راجع دليل الجمع لقواعد الصيغ الثلاث في الروسية وأمثلة مشروحة

التضمينات #include

يدمج قالبًا آخر في موضع التوجيه.

#include "hero-text"

قواعد التضمين

• مرجع القالب بين علامتي اقتباس مزدوجتين
• يُحل بواسطة slug القالب أو المعرّف الرقمي
• القوالب المضمنة يمكن أن تحتوي على متغيراتها و spintax الخاصة بها
• التضمينات العودية مدعومة
• المراجع الدائرية يتم اكتشافها وحظرها
• القوالب الفرعية ترث المتغيرات العامة ومتغيرات وقت التشغيل لكن ليس محليات #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 والبريد الإلكتروني والنطاقات والأعداد العشرية والاختصارات من التكبير
2. يزيل المسافات وعلامات التبويب المكررة
3. يزيل المسافات قبل علامات الترقيم (, . ! ?)
4. يضيف مسافة بعد علامات الترقيم عند فقدانها
5. يجعل الحرف الأول من المخرجات كبيرًا (مع تخطي وسوم HTML)
6. تكبير بعد علامات ترقيم نهاية الجملة
7. تكبير بعد وسوم HTML على مستوى الكتلة
8. تكبير بعد فواصل الأسطر
9. استعادة العناصر النائبة المحمية

ملخص الصياغة

الصياغة متوافقة مع معيار Generating The Web (GTW).