مرجع صياغة 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 يمكن أن تكون خيارات
• sep يصل كل ما قبل الزوج الأخير، وlastsep يصل ذلك الزوج: عند اختيار عنصرين يظهر lastsep وحده، وعند عنصر واحد لا يظهر أي منهما

المتغيرات %var%

يعرّف متغيّرًا قابلًا لإعادة الاستخدام يُستبدل أينما ظهر. يعلنه أمران، والاختيار بينهما ليس تجميليًا: #set ماكرو — تُستبدل قيمته من جديد عند كل إشارة، فيُعاد اختيار الـ spintax بداخلها؛ أما #def فيختار القيمة مرة واحدة لكل تصيير ويسلّم تلك النتيجة الواحدة لكل الإشارات. (التصيير الواحد مخرَج واحد؛ والبذرة نفسها تعيد إنتاجه.) وما دامت القيمة نصًّا بسيطًا فالأمران متطابقان؛ الفرق يظهر لحظة احتواء القيمة على خيار.

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

قواعد المتغيرات

• يجب أن يبدأ #set و#def من بداية السطر
• تُحاط أسماء المتغيّرات بـ %: %name%
• الأسماء حروف وأرقام وشرطة سفلية، والإشارات لا تفرّق بين الحالة الكبيرة والصغيرة: %Tone% و%tone% متغيّر واحد
• يمكن أن تحتوي القيم على أي صياغة spintax (تعدادات، تباديل، متغيّرات أخرى)
• #set ماكرو: يتوسّع عند الإشارة لا عند التعريف، وتُستبدل قيمته — بما فيها الـ spintax بداخلها — من جديد ويُعاد اختيارها عند كل إشارة
• #def يحسب قيمته مرة واحدة لكل تصيير ويحتفظ بالنتيجة في كل مكان. وهذا ما يبقي التكرارات متوافقة: اسم والصيغ المبنية عليه، وعدد يغذّي كتلة {plural}، وأي عبارة يجب أن تتطابق تكراراتها كلمة بكلمة
• #def يجعل المتغيّر متسقًا مع نفسه، لكنه لا يربط متغيّرين. #def %Noun% و#def %NounGen% اختياران مستقلان وقد يقعان على كلمتين مختلفتين — فالصيغ التي يجب أن تتوافق ينبغي أن تأتي من اختيار واحد: جذر واحد في #def تشير إليه كل صيغة، أو مرادفات تتصرّف بالطريقة نفسها مع كتابة النهاية خارج التعريف
• يُعرَّف الاسم مرة واحدة. أي تعريف ثانٍ للاسم نفسه يُبلَّغ عنه بـ definition.duplicate-name ويستمر التصيير رغم ذلك: بين أمرين من النوع نفسه يفوز الأخير، وإذا تشارك #set و#def الاسم نفسه فاز #def أيًّا كان الذي جاء أولًا
• الإشارة بلا تعريف تطبع نفسها: يبقى %missing% في المخرج بدل أن يختفي
• لا يعبر أي من الأمرين حدود #include: القالب المضمَّن لا يرى متغيّرات الأب المحلية، ومتغيّراته لا تتسرّب إلى الأعلى. الصيغة المختارة تصل إلى الابن فقط كمتغيّر وقت تشغيل
• تُحذف أسطر #set و#def من المخرج
• التعمق: راجع دليل المتغيّرات (النطاقات وفخّ إعادة الاختيار) والترادف الآمن نحويًا (عائلات الحالات الإعرابية)

نطاقات المتغيّرات

يستطيع المضيف تزويد المتغيّرات من أكثر من مصدر. وإذا وُجد الاسم نفسه في أكثر من مصدر، يفوز الأقوى:

1. متغيّرات وقت التشغيل (الأقوى) — ما يمرّره المضيف إلى نداء التصيير: context في @spintax/core، وسمات الشورت‌كود في إضافة ووردبريس: [spintax slug="greeting" name="Alice"]
2. المتغيّرات المحلية — المعرّفة بـ #set أو #def داخل القالب
3. المتغيّرات العامة (الأضعف) — قيم افتراضية على مستوى المضيف، مثل صفحة إعدادات الإضافة

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

الشروط بناء خاص باللغة نفسها — لم يكن في نموذج 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 هو التركيب الوحيد الذي لا يستطيع المحرّك تلبيته وحده: فهو لا يحتفظ بمخزن قوالب، لذا يوفّر المضيف محلِّلًا يحوّل الإشارة إلى نص قالب. وحيث لا محلِّل مثبَّت — في الملعب التجريبي وخادم MCP في هذا الموقع، وكلاهما عن قصد — يبقى الأمر خاملًا ويظهر في المخرج كنص حرفي.

#include "hero-text"

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

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

• يجب أن يشغل الأمر السطر كاملًا. المسافة البادئة مقبولة، أما النص بعد الإشارة فلا — نص #include "hero" يبقى حرفيًا
• تُكتب الإشارة بين علامتي اقتباس مزدوجتين؛ ومع علامة مفردة أو بدون علامات لا يعود أمرًا
• الحلّ مسؤولية المضيف: إضافة ووردبريس تحلّ بالـ slug أو بالمعرّف الرقمي، ومضيف JavaScript يمرّر includeResolver
• بلا محلِّل يبقى السطر حرفيًا في المخرج؛ وإذا لم يكن لدى المحلِّل ذلك القالب فإن السطر يُحذف بدلًا من ذلك — الهدف المجهول يكلّفك الكتلة بصمت
• يمكن أن تحتوي القوالب المضمَّنة على متغيّراتها وspintax الخاص بها، وعلى #include خاص بها
• تُحلّ التضمينات بعد اختيار التعدادات والتباديل في القالب الأب: التضمين داخل الفرع الفائز يُدمج — والذي داخل فرع مرفوض لا يحدث أصلًا
• السلاسل تعمل (قالب يضمّن قالبًا يضمّن آخر)؛ أما القالب الذي يضمّن نفسه، مباشرة أو عبر دورة، فيُقطع عند أول تكرار — بلا خطأ وبلا تشخيص
• ترث القوالب الأبناء المتغيّرات العامة ومتغيّرات وقت التشغيل، لكن لا ترث محلّيات الأب #set / #def، ولا تتسرّب متغيّراتها إلى الأعلى
• لا يصلح التضمين قيمةً لتعريف: #def %x% = #include "y" يُرفض بالرمز def.include-in-value
• قبل التصيير، لا يبلّغ validate() عن هدف مجهول إلا إذا مرّر المضيف قائمة الإشارات المعروفة؛ ويعيد extract() الإشارات التي يحتاجها القالب، وبها يجلبها المضيف مسبقًا
• التعمق: راجع دليل تركيب القوالب ونمط المجمِّع الذي تستخدمه معظم خطوط الإنتاج بدلًا من ذلك

التعليقات /#...#/

النص بين علامات التعليق يُزال من المخرجات قبل أي معالجة أخرى.

/#
  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)؛ والقوالب المكتوبة لـ GTW ما زالت تعمل دون تغيير.