Manual:Parser functions/ar

إن دوال المحلل اللغوي التي أضيفت في نسخة ميدياويكي 1.7 هي أحد أنواع الامتدادات التي تندمج اندماجا وثيقا مع المحلل اللغوي. يجب ألا تخلط بين عبارة «دوال المحلل اللغوي – parser functions» وبين ، التي هي عبارة عن مجموعة من دوال المحلل اللغوي البسيطة. (اذهب إلى كي تطالع تلك).

الوصف
منذ أن امتداد Tag متوقع منه أن يتناول نص غير معالج ويرد نص إتش تي إم إل إلى المتصفح، يمكن لدالة معرب لغوي ’التفاعل‘ مع عناصر الويكي الأخرى في الصفحة. يمكن على سبيل المثال استخدام مخرجات دوال المعرب اللغوي في صفة متغير في قالب أو في توليد وصلة شبكية.

البنية اللغوية المعتادة لدالة معرب لغوي هي كما يلي:

لمزيد من المعلومات، طالع المخصص لمتغير ‎‎. تذكر أعمال التوثيق هذه ما يلي:


 * يجب أن تكون صيغة دالة الاستدعاء كما يلي:
 * أو باستخدام :
 * أو باستخدام :

The first variant of the call passes all arguments as plain text. The second passes all arguments as an array of s, except for the first, which is currently text, though this may change in the future. These represent the unexpanded wikitext. The  parameter can be used to expand these arguments as needed. This is commonly used for conditional processing so that only the "true" case is evaluated with an if- or switch-like parser function. The frame object can also climb up the document tree to get information about the caller and has functions to determine and manage call depth, time-to-live, and whether the result of the parser function is volatile.

إن استحداث دالة معرب لغوي معقد قليلًا مقارنة باستحداث وسم جديد لأن اسم الدالة يتعين أن يكون كلمة سحرية، كملة مفتاحية تساند الأسماء المستعارة وأعمال الأقلمة.

مثال بسيط
ما يلي هو مثال على امتداد ينشئ دالة معرب لغوي.

يذهب التسجيل في ملف extension.json ويذهب الكود البرمجي في ملف src/ExampleExtensionHooks.php على الترتيب:

يجب أن يحتوي ملف آخر يحمل الاسم ExampleExtension.i18n.php في مجلد الامتدادات لديك (لا في المجلد الفرعي src/) على ما يلي:

حينما يكون هذا الامتداد مفعلًا،



ينتج عنه:


 * param1 is hello and param2 is hi and param3 is hey

دوال أطول
في حالات الدوال الطويلة، ربما ترغب في تقسيم دوال الربط إلى ملف ‎_body.php أو ‎.hooks.php وجعلها دوال ثابتة تحت فئة واحدة. يمكنك من ثمّ تحميل الفئة مستخدمًا ‎ واستدعاء الدوال الثابتة في الروابط؛ مثل:

ضع ما يلي في ملف ‎ لديك:
 * طالع: كتابة مداول أحداث كي ترى أساليب أخرى.

ثم ضع ما يلي في ملف ‎ لديك:

الحفظ المؤقت
كما هو الحال في امتدادات الوسم، يجوز استخدام ‎$parser->disableCache‎ في تعطيل الحفظ المؤقت لأغراض الامتدادات التفاعلية. يحمل هذا الأمر أثرًا سلبيًا على الأداء، لذا استخدمه إن استلزم الأمر ذلك لا غير.

التحكم في الإعراب اللغوي للمخرجات
إن أردت أن تُعرَب نصوص الويكي التي تُرجِعها دوال المعرب اللغوي إعرابًا برمجيًا كاملًا (يشمل ذلك توسيع القوالب)، اضبط قيمة خيار  لتصبح «false» أثناء الرجوع:

يبدو أن القيمة الافتراضية لخيار  تغيرت من «false» إلى «true»، على الأقل في بعض الحالات، في وقت ما قريب من الإصدار 1.12.

بالعكس، كي تجعل دوال المعرب اللغوي لديك ترد نص إتش تي إم إل يظل دون إعراب برمجي، بدلا من رده في صيغة نصوص ويكي، استخدم التالي:

إلا أن This is a test. سوف ينتج عنه ما يشبه التالي:

This is

المتغير الأول هو «hello» والمتغير الثاني هو «hi» والمتغير الثالث هو «hey a test».

يحدث هذا بسبب أن المتغير «\n\n» مضمّن في النص البرمجي المرفق في مخرجات إتش تي إم إل لدوال المعرب اللغوي. كي نتجنب هذا ونضمن أن كود إتش تي إم إل قد عُرِضَ في السطر مع النص المحيط به، يمكنك استخدام التالي:

التسمية
تضيف برمجيات ميدياويكي بصفة افتراضية محرف «هاش» (علامة الرقم، «#») إلى اسم كل دالة من دوال المعرب اللغوي. كي توقف هذه الإضافة (والحصول على دوال معرب لغوي لا يضاف إليها البادئة «#»)، أضف الثابت ‎SFH_NO_HASH‎ في وسيطة الوسوم الاختيارية إلى setFunctionHook، كما هو مبين فيما يلي.

حينما تختار اسم لا يحتوي على البادئة «هاش»، لاحظ أن ضم صفحة تحمل اسم يبدأ باسم تلك الدالة يتبعه علامة النقطتين لن يصبح ممكنًا. تجنب على وجه التحديد أسماء الدوال التي تساوي اسم نطاق اسم. في حالة أن ضم بين مواقع الويكي مفعّل، تجنب أيضًا أسماء الدوال التي تساوي بادئة وصل بين مواقع الويكي.

الرابط setFunctionHook
لمزيد من التفاصيل عن الواجهة في المعرب اللغوي، طالع توثيق رابط setFunctionHook في ملف ‎includes/Parser.php‎. إليك نسخة (يحتمل أن تكون متقادمة) من تلك التعليقات:

function setFunctionHook( $id, $callback, $flags = 0 ) Parameters:


 * ‎$id النص – معرف الكلمة السحرية
 * ‎$callback مختلط – دالة الاستدعاء (والعنصر) المطلوب استخدامها
 * ‎$flags الأعداد الصحيحة – اختياري، ضبطت قيمته لتكون ثابت ‎SFH_NO_HASH‎ كي تستدعي الدالة دون استخدام «#».

القيمة المردودة: دالة الاستدعاء القديمة لهذا الاسم، في حال وجودها

صغ دالة، مثل، ‎ ‎. يجب أن تكون دالة الاستدعاء على الشكل التالي:

يجوز أن يرد الاستدعاء إما النتيجة النصية للدالة أو متوالية يوجد النص فيها في العنصر «0» وعدد من الوسوم في العناصر الأخرى. تحدد أسماء الوسوم في المفاتيح. الوسوم الصالحة كما يلي:


 * found : النص المردود صالح، أوقف معالجة القالب. هذا الخيار مفعّل بصفة افتراضية.
 * nowiki : يجب تخطي ترميز الويكي الموجود في القيمة المردودة
 * noparse : يجب نزع وسوم إتش تي إم إل غير الآمنة، وخلافه
 * noargs : لا تضع أي شيء محل الوسيطات الموضوعة في أقواس ثلاثية في القيمة المردودة
 * isHTML : النص المردود هو نص إتش تي إم إل، احفظه من أن يتغير إلى نصوص ويكي

متغيرات تحمل اسم
لا تدعم دوال المعرب اللغوي المتغيرات التي تحمل أسماء بذات الطريقة التي تدعمها القوالب وامتدادات الوسوم، إلا أنه من المفيد أحيانًا اختلاقها. يعتاد غالبًا المستخدمين على استخدام الشريط العمودي (|) في أغراض فصل الوسيطات، لذا من الجيد أن يكون هذا ممكنًا في سياق دوال المعرب اللغوي أيضًا. إليك مثال بسيط على كيفية تحقيق هذا الأمر:

انظر أيضا

 * إن امتداد ParserFunctions هو تشكيلة ذائعة الصيت من دوال المعرب اللغوي.
 * , an (incomplete) list of parser functions provided by core and extensions.
 * مكتبة روابط المعرب اللغوي لبي إتش بي، وهي تقدم واجهة تعتمد على العناصر لروابط المعرب اللغوي الخبرية
 * إن امتداد ParserFunctions هو تشكيلة ذائعة الصيت من دوال المعرب اللغوي.
 * , an (incomplete) list of parser functions provided by core and extensions.
 * مكتبة روابط المعرب اللغوي لبي إتش بي، وهي تقدم واجهة تعتمد على العناصر لروابط المعرب اللغوي الخبرية
 * إن امتداد ParserFunctions هو تشكيلة ذائعة الصيت من دوال المعرب اللغوي.
 * , an (incomplete) list of parser functions provided by core and extensions.
 * مكتبة روابط المعرب اللغوي لبي إتش بي، وهي تقدم واجهة تعتمد على العناصر لروابط المعرب اللغوي الخبرية
 * مكتبة روابط المعرب اللغوي لبي إتش بي، وهي تقدم واجهة تعتمد على العناصر لروابط المعرب اللغوي الخبرية