calibre - en to ar translation catalogue (257 entries)

en: The calibre template language
ar: لغة قوالب calibre

en: The calibre template language is a calibre-specific language used throughout calibre for tasks such as specifying file paths, formatting values, and computing the value for user-specified columns. Examples:
ar: لغة قوالب calibre هي لغة خاصة بـ calibre تُستخدم في جميع أنحاء calibre لمهام مثل تحديد مسارات الملفات، وتنسيق القيم، و حساب القيمة للأعمدة المحددة من قبل المستخدم. أمثلة:

en: Specify the folder structure and file names when saving files from the calibre library to the disk or e-book reader.
ar: تحديد هيكل المجلد وأسماء الملفات عند حفظ الملفات من مكتبة calibre إلى القرص أو قارئ الكتب الإلكترونية.

en: Define rules for adding icons and colors to the calibre book list.
ar: تحديد قواعد لإضافة الأيقونات والألوان إلى قائمة كتب calibre.

en: Define `virtual columns` that contain data from other columns.
ar: تحديد `أعمدة افتراضية` تحتوي على بيانات من أعمدة أخرى.

en: Advanced library searching.
ar: بحث متقدم في المكتبة.

en: Advanced metadata search and replace.
ar: بحث واستبدال متقدم للبيانات الوصفية.

en: The language is built around the notion of a `template`, which specifies which book metadata to use, computations on that metadata, and how it is to be formatted.
ar: تعتمد اللغة على مفهوم `القالب`، الذي يحدد أي بيانات وصفية للكتاب يجب استخدامها، والعمليات الحسابية على تلك البيانات الوصفية، وكيفية تنسيقها.

en: Basic templates
ar: القوالب الأساسية

en: A basic template consists one or more ``template expressions``. A ``template expression`` consists of text and names in curly brackets (``{}``) that is replaced by the corresponding metadata from the book being processed. For example, the default template in calibre used for saving books to device has 4 ``template expressions``::
ar: يتكون القالب الأساسي من تعبير أو أكثر من ``تعبيرات القالب``. يتكون ``تعبير القالب`` من نص وأسماء داخل أقواس معقوفة (``{}``) يتم استبدالها بالبيانات الوصفية المقابلة من الكتاب الذي تتم معالجته. على سبيل المثال، القالب الافتراضي في calibre المستخدم لحفظ الكتب على الجهاز يحتوي على 4 ``تعبيرات قالب``::

en: For the book "The Foundation" by "Isaac Asimov" the  will become::
ar: بالنسبة لكتاب "المؤسسة" لـ "إسحاق أسيموف" سيصبح::

en: then for "The Foundation" the template produces::
ar: فبالنسبة لـ "المؤسسة"، ينتج القالب::

en: A ``template expression`` can access all the metadata available in calibre, including custom columns (columns you create yourself), by using a column's ``lookup name``. To find the lookup name for a `column` (sometimes called `fields`), hover your mouse over the column header in calibre's book list. Lookup names for custom columns always begin with ``#``. For series type columns there is an additional field named ``#lookup name_index`` that is the series index for that book in the series. For example, if you have a custom series column named ``#myseries``, there will also be a column named ``#myseries_index``. The standard series column's index is named ``series_index``.
ar: يمكن لتعبير ``القالب`` الوصول إلى جميع البيانات الوصفية المتاحة في calibre، بما في ذلك الأعمدة المخصصة (الأعمدة التي تنشئها بنفسك)، باستخدام ``اسم البحث`` الخاص بالعمود. للعثور على اسم البحث لـ `عمود` (يُسمى أحيانًا `حقول`)، مرر الماوس فوق رأس العمود في قائمة كتب calibre. تبدأ أسماء البحث للأعمدة المخصصة دائمًا بـ ``#``. بالنسبة لأعمدة نوع السلسلة، يوجد حقل إضافي يسمى ``#اسم_البحث_فهرس`` وهو فهرس السلسلة لذلك الكتاب في السلسلة. على سبيل المثال، إذا كان لديك عمود سلسلة مخصص يسمى ``#myseries``، فسيكون هناك أيضًا عمود يسمى ``#myseries_index``. فهرس عمود السلسلة القياسي يسمى ``series_index``.

en: In addition to the standard column based fields, you also can use:
ar: بالإضافة إلى الحقول المستندة إلى الأعمدة القياسية، يمكنك أيضًا استخدام:

en: ``{formats}`` - A list of formats available in the calibre library for a book
ar: ``{formats}`` - قائمة بالتنسيقات المتاحة في مكتبة calibre لـ كتاب

en: ``{identifiers:select(isbn)}`` - The ISBN of the book
ar: ``{identifiers:select(isbn)}`` - الرقم المعياري الدولي للكتاب (ISBN) الخاص بالكتاب

en: If the metadata for the field for a given book is not defined then the field in the template is replaced by the empty string (``''``). For example, consider the following template::
ar: إذا لم يتم تعريف البيانات الوصفية للحقل لكتاب معين، فسيتم استبدال الحقل في القالب بسلسلة فارغة (``''``). على سبيل المثال، النظر في القالب التالي::

en: If Asimov's book "Second Foundation" is in the series "Foundation" then the template produces::
ar: إذا كان كتاب أسيموف "المؤسسة الثانية" ضمن سلسلة "المؤسسة"، فإن القالب ينتج::

en: If a series has not been entered for the book then the template produces::
ar: إذا لم يتم إدخال سلسلة للكتاب، فإن القالب ينتج::

en: The template processor automatically removes multiple slashes and leading or trailing spaces.
ar: يزيل معالج القوالب تلقائيًا الشرطات المائلة المتعددة والمسافات البادئة أو اللاحقة.

en: Advanced formatting
ar: تنسيق متقدم

en: In addition to metadata substitution, templates can conditionally include additional text and control how substituted data is formatted.
ar: بالإضافة إلى استبدال البيانات الوصفية، يمكن للقوالب تضمين نص إضافي بشكل شرطي والتحكم في كيفية تنسيق البيانات المستبدلة.

en: **Conditionally including text**
ar: **تضمين النص بشكل شرطي**

en: Sometimes you want text to appear in the output only if a field is not empty. A common case is ``series`` and ``series_index`` where you want either nothing or the two values separated by a hyphen. calibre handles this case using a special ``template expression`` syntax.
ar: أحيانًا ترغب في ظهور نص في الإخراج فقط إذا لم يكن الحقل فارغًا. حالة شائعة هي ``series`` و ``series_index`` حيث تريد إما لا شيء أو القيمتين مفصولتين بشرطة. يتعامل calibre مع هذه الحالة باستخدام صيغة خاصة لـ ``تعبير القالب``.

en: For example and using the above Foundation example, assume you want the template to produce `Foundation - 3 - Second Foundation`. This template produces that output:
ar: على سبيل المثال، وباستخدام مثال المؤسسة أعلاه، افترض أنك تريد أن ينتج القالب `Foundation - 3 - Second Foundation`. ينتج هذا القالب هذا الإخراج:

en: However, if a book has no series the template will produce `- - the title`, which is probably not what you want. Generally, people want the result be the title without the extraneous hyphens. You can accomplish this using the following template syntax:
ar: ومع ذلك، إذا لم يكن للكتاب سلسلة، فسينتج القالب `- - العنوان`، وهو على الأرجح ليس ما تريده. بشكل عام، يريد الناس أن تكون النتيجة العنوان بدون الشرطات الزائدة. يمكنك تحقيق ذلك باستخدام صيغة القالب التالية:

en: ``{field:|prefix_text|suffix_text}``
ar: ``{field:|نص_بادئة|نص_لاحقة}``

en: This ``template expression`` says that if ``field`` has the value `XXXX` then the result will be `prefix_textXXXXXsuffix_text`. If ``field`` is empty (has no value) then the result will be the empty string (nothing) because the prefix and suffix are ignored. The prefix and suffix can contain blanks.
ar: يقول ``تعبير القالب`` هذا أنه إذا كان ``field`` يحتوي على القيمة `XXXX` فإن النتيجة ستكون `نص_بادئةXXXXXنص_لاحقة`. إذا كان ``field`` فارغًا (لا يحتوي على قيمة) فستكون النتيجة سلسلة فارغة (لا شيء) لأن البادئة واللاحقة يتم تجاهلهما. يمكن أن تحتوي البادئة واللاحقة على مسافات فارغة.

en: **Do not use subtemplates (`{ ... }`) or functions (see below) in the prefix or the suffix.**
ar: **لا تستخدم القوالب الفرعية (``{ ... }``) أو الدوال (انظر أدناه) في البادئة أو اللاحقة.**

en: Using this syntax, we can solve the above no-series problem with the template::
ar: باستخدام هذه الصيغة، يمكننا حل مشكلة عدم وجود سلسلة أعلاه باستخدام القالب::

en: The hyphens will be included only if the book has a series index, which it has only if it has a series. Continuing the Foundation example again, the template will produce `Foundation - 1 - Second Foundation`.
ar: سيتم تضمين الشرطات فقط إذا كان الكتاب يحتوي على فهرس سلسلة، وهو ما يحدث فقط إذا كان يحتوي على سلسلة. استمرارًا لمثال المؤسسة مرة أخرى، سينتج القالب `Foundation - 1 - Second Foundation`.

en: Notes:
ar: ملاحظات:

en: You must include the colon after the ``lookup name`` if you are using a prefix or a suffix.
ar: يجب عليك تضمين النقطتين بعد ``اسم البحث`` إذا كنت تستخدم بادئة أو لاحقة.

en: You must either use either no or both ``|`` characters. Using one, as in ``{field:| - }``, is not allowed.
ar: يجب عليك استخدام إما لا شيء أو كلا حرفي ``|``. استخدام حرف واحد، كما في ``{field:| - }``، غير مسموح به.

en: It is OK to provide no text for either the prefix or the suffix, such as in ``{series:|| - }``. The template ``{title:||}`` is the same as ``{title}``.
ar: لا بأس بتقديم نص فارغ للبادئة أو اللاحقة، كما في ``{series:|| - }``. القالب ``{title:||}`` هو نفسه ``{title}``.

en: **Formatting**
ar: **التنسيق**

en: Suppose you want the ``series_index`` to be formatted as three digits with leading zeros. This does the trick:
ar: افترض أنك تريد تنسيق ``series_index`` بثلاثة أرقام مع أصفار بادئة. هذا يؤدي الغرض:

en: ``{series_index:0>3s}`` - Three digits with leading zeros
ar: ``{series_index:0>3s}`` - ثلاثة أرقام مع أصفار بادئة

en: For trailing zeros, use:
ar: للأصفار اللاحقة، استخدم:

en: ``{series_index:0<3s}`` - Three digits with trailing zeros
ar: ``{series_index:0<3s}`` - ثلاثة أرقام مع أصفار لاحقة

en: If you use series indices with fractional values, e.g., 1.1, you might want the decimal points to line up. For example, you might want the indices 1 and 2.5 to appear as 01.00 and 02.50 so that they will sort correctly on a device that does lexical sorting. To do this, use:
ar: إذا كنت تستخدم فهارس سلسلة ذات قيم كسرية، على سبيل المثال، 1.1، فقد ترغب في محاذاة النقاط العشرية. على سبيل المثال، قد ترغب في ظهور الفهارس 1 و 2.5 كـ 01.00 و 02.50 بحيث يتم فرزها بشكل صحيح على جهاز يقوم بالفرز المعجمي. للقيام بذلك، استخدم:

en: ``{series_index:0>5.2f}`` - Five characters consisting of two digits with leading zeros, a decimal point, then 2 digits after the decimal point.
ar: ``{series_index:0>5.2f}`` - خمسة أحرف تتكون من رقمين مع أصفار بادئة، نقطة عشرية، ثم رقمين بعد النقطة العشرية.

en: If you want only the first two letters of the data, use:
ar: إذا كنت تريد فقط الحرفين الأولين من البيانات، استخدم:

en: ``{author_sort:.2}`` - Only the first two letters of the author sort name
ar: ``{author_sort:.2}`` - أول حرفين فقط من اسم ترتيب المؤلف

en: Much of the calibre template language formatting comes from Python. For more details on the syntax of these advanced formatting operations see the `Python documentation <https://docs.python.org/3/library/string.html#formatstrings>`_.
ar: يأتي جزء كبير من تنسيق لغة قوالب calibre من Python. لمزيد من التفاصيل حول صيغة عمليات التنسيق المتقدمة هذه، راجع `وثائق Python <https://docs.python.org/3/library/string.html#formatstrings>`_.

en: Using templates to define custom columns
ar: استخدام القوالب لتعريف الأعمدة المخصصة

en: Templates can be used to display information that isn't in calibre metadata, or to display metadata differently from calibre's normal format. For example, you might want to show the ``ISBN``, a field that calibre does not display. You can accomplish this creating a custom column with the type `Column built from other columns` (hereafter called `composite columns`) and providing a template to generate the displayed text. The column will display the result of evaluating the template. For example, to display the ISBN, create the column and enter ``{identifiers:select(isbn)}`` in the template box. To display a column containing the values of two series custom columns, separated by a comma, use ``{#series1:||,}{#series2}``.
ar: يمكن استخدام القوالب لعرض معلومات غير موجودة في البيانات الوصفية لـ calibre، أو لعرض البيانات الوصفية بشكل مختلف عن التنسيق العادي لـ calibre. على سبيل المثال، قد ترغب في عرض ``ISBN``، وهو حقل لا يعرضه calibre. يمكنك تحقيق ذلك بإنشاء عمود مخصص من نوع `عمود مبني من أعمدة أخرى` (يُشار إليه فيما بعد بـ `الأعمدة المركبة`) و توفير قالب لإنشاء النص المعروض. سيعرض العمود نتيجة تقييم القالب. على سبيل المثال، لعرض ISBN، أنشئ العمود وأدخل ``{identifiers:select(isbn)}`` في مربع القالب. لعرض عمود يحتوي على قيم عمودين مخصصين من السلسلة، مفصولين بفاصلة، استخدم ``{#series1:||,}{#series2}``.

en: Composite columns can use any template option, including formatting.
ar: يمكن للأعمدة المركبة استخدام أي خيار قالب، بما في ذلك التنسيق.

en: Note: You cannot edit the data displayed in a composite column. Instead you edit the source columns. If you edit a composite column, for example by double-clicking it, calibre will open the template for editing, not the underlying data.
ar: ملاحظة: لا يمكنك تحرير البيانات المعروضة في عمود مركب. بدلاً من ذلك، تقوم بتحرير الأعمدة المصدر. إذا قمت بتحرير عمود مركب، على سبيل المثال عن طريق النقر المزدوج عليه، فسيفتح calibre القالب للتحرير، وليس البيانات الأساسية.

en: Templates and plugboards
ar: القوالب ولوحات التوصيل

en: Plugboards are used for changing the metadata written into books during send-to-device and save-to-disk operations. A plugboard permits you to specify a template to provide the data to write into the book's metadata. You can use plugboards to modify the following fields: authors, author_sort, language, publisher, tags, title, title_sort. This feature helps people who want to use different metadata in books on devices to solve sorting or display issues.
ar: تُستخدم لوحات التوصيل لتغيير البيانات الوصفية المكتوبة في الكتب أثناء عمليات الإرسال إلى الجهاز والحفظ على القرص. تسمح لك لوحة التوصيل بتحديد قالب لتوفير البيانات التي ستُكتب في البيانات الوصفية للكتاب. يمكنك استخدام لوحات التوصيل لتعديل الحقول التالية: المؤلفون، ترتيب المؤلفين، اللغة، الناشر، العلامات، العنوان، ترتيب العنوان. تساعد هذه الميزة الأشخاص الذين يرغبون في استخدام بيانات وصفية مختلفة في الكتب على الأجهزة لحل مشاكل الفرز أو العرض.

en: When you create a plugboard, you specify the format and device for which the plugboard is to be used. A special device is provided, ``save_to_disk``, that is used when saving formats (as opposed to sending them to a device). Once you have chosen the format and device, you choose the metadata fields to change, providing templates to supply the new values. These templates are `connected` to their destination fields, hence the name `plugboards`. You can of course use composite columns in these templates.
ar: عند إنشاء لوحة توصيل، تحدد التنسيق والجهاز الذي ستُستخدم لوحة التوصيل من أجله. يتم توفير جهاز خاص، ``save_to_disk``، يُستخدم عند حفظ التنسيقات (على عكس إرسالها إلى جهاز). بمجرد اختيار التنسيق والجهاز، تختار حقول البيانات الوصفية التي سيتم تغييرها، وتوفر قوالب لتوفير القيم الجديدة. هذه القوالب `متصلة` بحقولها الوجهة، ومن هنا جاء اسم `لوحات التوصيل`. يمكنك بالطبع استخدام الأعمدة المركبة في هذه القوالب.

en: Plugboards are quite flexible and can be written in Single Function Mode, Template Program Mode, General Program Mode, or Python Template mode.
ar: لوحات التوصيل مرنة للغاية ويمكن كتابتها في وضع الدالة الواحدة، وضع برنامج القالب، وضع البرنامج العام، أو وضع قالب بايثون.

en: When a plugboard might apply (Content server, save to disk, or send to device), calibre searches the defined plugboards to choose the correct one for the given format and device. For example, to find the appropriate plugboard for an EPUB book being sent to an ANDROID device, calibre searches the plugboards using the following search order:
ar: عندما قد تنطبق لوحة توصيل (خادم المحتوى، الحفظ على القرص، أو الإرسال إلى الجهاز)، يبحث calibre في لوحات التوصيل المحددة لاختيار الصحيحة للتنسيق والجهاز المعنيين. على سبيل المثال، للعثور على لوحة التوصيل المناسبة لكتاب EPUB يتم إرساله إلى جهاز ANDROID، يبحث calibre في لوحات التوصيل باستخدام ترتيب البحث التالي:

en: a plugboard with an exact match on format and device, e.g., ``EPUB`` and ``ANDROID``
ar: لوحة توصيل تتطابق تمامًا مع التنسيق والجهاز، على سبيل المثال، ``EPUB`` و ``ANDROID``

en: a plugboard with an exact match on format and the special ``any device`` choice, e.g., ``EPUB`` and ``any device``
ar: لوحة توصيل تتطابق تمامًا مع التنسيق وخيار ``أي جهاز`` الخاص، على سبيل المثال، ``EPUB`` و ``أي جهاز``

en: a plugboard with the special ``any format`` choice and an exact match on device, e.g., ``any format`` and ``ANDROID``
ar: لوحة توصيل مع خيار ``أي تنسيق`` الخاص ومطابقة دقيقة لـ الجهاز، على سبيل المثال، ``أي تنسيق`` و ``ANDROID``

en: a plugboard with ``any format`` and ``any device``
ar: لوحة توصيل مع ``أي تنسيق`` و ``أي جهاز``

en: The tags and authors fields have special treatment, because both of these fields can hold more than one item. A book can have many tags and many authors. When you specify that one of these two fields is to be changed, the template's result is examined to see if more than one item is there. For tags, the result is cut apart wherever calibre finds a comma. For example, if the template produces the value ``Thriller, Horror``, then the result will be two tags, ``Thriller`` and ``Horror``. There is no way to put a comma in the middle of a tag.
ar: يتم التعامل مع حقلي العلامات والمؤلفين بشكل خاص، لأن كلا هذين الحقلين يمكن أن يحملا أكثر من عنصر واحد. يمكن أن يحتوي الكتاب على العديد من العلامات والعديد من المؤلفين. عندما تحدد أن أحد هذين الحقلين سيتم تغييره، يتم فحص نتيجة القالب لمعرفة ما إذا كان هناك أكثر من عنصر واحد. بالنسبة للعلامات، يتم تقسيم النتيجة حيثما يجد calibre فاصلة. على سبيل المثال، إذا أنتج القالب القيمة ``Thriller, Horror``، فستكون النتيجة علامتين، ``Thriller`` و ``Horror``. لا توجد طريقة لوضع فاصلة في منتصف علامة.

en: The same thing happens for authors, but using a different character for the cut, a `&` (ampersand) instead of a comma. For example, if the template produces the value ``Blogs, Joe&Posts, Susan``, then the book will end up with two authors, ``Blogs, Joe`` and ``Posts, Susan``. If the template produces the value ``Blogs, Joe;Posts, Susan``, then the book will have one author with a rather strange name.
ar: يحدث نفس الشيء للمؤلفين، ولكن باستخدام حرف مختلف للقطع، وهو `&` (علامة العطف) بدلاً من الفاصلة. على سبيل المثال، إذا أنتج القالب القيمة ``Blogs, Joe&Posts, Susan``، فسينتهي الأمر بالكتاب بمؤلفين، ``Blogs, Joe`` و ``Posts, Susan``. إذا أنتج القالب القيمة ``Blogs, Joe;Posts, Susan``، فسيحتوي الكتاب على مؤلف واحد باسم غريب نوعًا ما.

en: Plugboards affect the metadata written into the book when it is saved to disk or written to the device. Plugboards do not affect the metadata used by ``save to disk`` and ``send to device`` to create the file names. Instead, file names are constructed using the templates entered on the appropriate preferences window.
ar: تؤثر لوحات التوصيل على البيانات الوصفية المكتوبة في الكتاب عند حفظه على القرص أو كتابته على الجهاز. لا تؤثر لوحات التوصيل على البيانات الوصفية المستخدمة بواسطة ``الحفظ على القرص`` و ``الإرسال إلى الجهاز`` لإنشاء أسماء الملفات. بدلاً من ذلك، يتم إنشاء أسماء الملفات باستخدام القوالب المدخلة في نافذة التفضيلات المناسبة.

en: Using functions in templates - Single Function Mode
ar: استخدام الدوال في القوالب - وضع الدالة الواحدة

en: Suppose you want to display the value of a field in upper case when that field is normally in title case. You can do this using `template functions`. For example, to display the title in upper case use the ``uppercase`` function, as in ``{title:uppercase()}``. To display it in title case, use ``{title:titlecase()}``.
ar: افترض أنك تريد عرض قيمة حقل بأحرف كبيرة عندما يكون هذا الحقل عادةً بحالة عنوان. يمكنك القيام بذلك باستخدام `دوال القالب`. على سبيل المثال، لعرض العنوان بأحرف كبيرة استخدم دالة ``uppercase``، كما في ``{title:uppercase()}``. لعرضه بحالة عنوان، استخدم ``{title:titlecase()}``.

en: Functions go into the format part of the template, after the ``:`` and before the first ``|`` or the closing ``}`` if no prefix/suffix is used. If you have both a format and a function reference, the function comes after a second ``:``.  Functions return the value of the column specified in the template, suitably modified.
ar: توضع الدوال في جزء التنسيق من القالب، بعد ``:`` و قبل أول ``|`` أو القوس الختامي ``}`` إذا لم يتم استخدام بادئة/لاحقة. إذا كان لديك كل من تنسيق ومرجع دالة، فإن الدالة تأتي بعد ``:`` ثانية. تعيد الدوال قيمة العمود المحدد في القالب، معدلة بشكل مناسب.

en: The syntax for using functions is one of::
ar: صيغة استخدام الدوال هي إحدى::

en: Function names must always be followed by opening and closing parentheses. Some functions require extra values (arguments), and these go inside the parentheses. Arguments are separated by commas. Literal commas (commas as text, not argument separators) must be preceded by a backslash (``\``) . The last (or only) argument cannot contain a textual closing parenthesis.
ar: يجب أن تتبع أسماء الدوال دائمًا أقواس فتح وإغلاق. تتطلب بعض الدوال قيمًا إضافية (وسائط)، وتوضع هذه داخل الأقواس. تُفصل الوسائط بفاصلات. يجب أن تسبق الفواصل الحرفية (الفواصل كنص، وليس فواصل وسيطة) بفاصلة خلفية (``\``). لا يمكن أن يحتوي الوسيط الأخير (أو الوحيد) على قوس إغلاق نصي.

en: Functions are evaluated before format specifications and the prefix/suffix. See further down for an example of using both a format and a function.
ar: يتم تقييم الدوال قبل مواصفات التنسيق والبادئة/اللاحقة. انظر أدناه للحصول على مثال لاستخدام كل من التنسيق والدالة.

en: **Important**: If you have programming experience, please note that the syntax in `Single Function Mode` is not what you expect. Strings are not quoted and spaces are significant. All arguments are considered to be constants; there are no expressions.
ar: **هام**: إذا كان لديك خبرة في البرمجة، يرجى ملاحظة أن صيغة `وضع الدالة الواحدة` ليست ما تتوقعه. السلاسل ليست مقتبسة والمسافات مهمة. تعتبر جميع الوسائط ثوابت؛ لا توجد تعبيرات.

en: **Do not use subtemplates (`{ ... }`) as function arguments.** Instead, use :ref:`Template Program Mode <template_mode>` and :ref:`General Program Mode <general_mode>`.
ar: **لا تستخدم القوالب الفرعية (``{ ... }``) كوسائط دالة.** بدلاً من ذلك، استخدم :ref:`وضع برنامج القالب <template_mode>` و :ref:`وضع البرنامج العام <general_mode>`.

en: Notes on calling functions in Single Function Mode:
ar: ملاحظات حول استدعاء الدوال في وضع الدالة الواحدة:

en: When functions are used in Single Function Mode, the first parameter, ``value``, is automatically replaced by the content of the field specified in the template. For example, when the template ``{title:capitalize()}`` is processed, the content of the ``title`` field is passed as the parameter ``value`` to the capitalize function.
ar: عند استخدام الدوال في وضع الدالة الواحدة، يتم استبدال المعامل الأول، ``value``، تلقائيًا بمحتوى الحقل المحدد في القالب. على سبيل المثال، عندما يتم معالجة القالب ``{title:capitalize()}``، يتم تمرير محتوى حقل ``title`` كمعامل ``value`` إلى دالة capitalize.

en: In the function documentation, the notation ``[something]*`` means that ``something`` can be repeated zero or more times. The notation ``[something]+`` means that the ``something`` is repeated one or more times (must exist at least one time).
ar: في وثائق الدالة، تعني الرموز ``[شيء]*`` أن ``الشيء`` يمكن أن يتكرر صفرًا أو أكثر من المرات. وتعني الرموز ``[شيء]+`` أن ``الشيء`` يتكرر مرة واحدة أو أكثر (يجب أن يوجد مرة واحدة على الأقل).

en: Some functions use regular expressions. In the template language regular expression matching is case-insensitive.
ar: تستخدم بعض الدوال تعبيرات نمطية. في لغة القوالب، مطابقة التعبيرات النمطية غير حساسة لحالة الأحرف.

en: Functions are documented in :ref:`template_functions_reference`. The documentation tells you what arguments the functions require and what the functions do. For example, here is the documentation of the :ref:`ff_ifempty` function.
ar: تم توثيق الدوال في :ref:`template_functions_reference`. تخبرك الوثائق بالوسائط التي تتطلبها الدوال وما تفعله الدوال. على سبيل المثال، إليك وثائق دالة :ref:`ff_ifempty`.

en: You see that the function requires two arguments, ``value`` and ``text_if_empty``. However, because we are using Single Function Mode, we omit the ``value`` argument, passing only ``text_if_empty``. For example, this template::
ar: ترى أن الدالة تتطلب وسيطين، ``value`` و ``text_if_empty``. ومع ذلك، نظرًا لأننا نستخدم وضع الدالة الواحدة، فإننا نحذف الوسيط ``value``، ونمرر فقط ``text_if_empty``. على سبيل المثال، هذا القالب::

en: shows the tags for a book, if any. If it has no tags then it show `No tags on this book`.
ar: يعرض علامات الكتاب، إن وجدت. إذا لم يكن لديه علامات، فإنه يعرض `لا توجد علامات على هذا الكتاب`.

en: The following functions are usable in Single Function Mode because their first parameter is ``value``.
ar: الدوال التالية قابلة للاستخدام في وضع الدالة الواحدة لأن معاملها الأول هو ``value``.

en: **Using functions and formatting in the same template**
ar: **استخدام الدوال والتنسيق في نفس القالب**

en: Suppose you have an integer custom column ``#myint`` that you want displayed with leading zeros, as in ``003``. One way to do this is to use a format of ``0>3s``. However, by default if a number (integer or float) equals zero then the value is displayed as the empty string so zero values will produce the empty string, not ``000``. If you want to see ``000`` values then you use both the format string and the ``ifempty`` function to change the empty value back to a zero. The template would be::
ar: افترض أن لديك عمودًا مخصصًا من نوع عدد صحيح ``#myint`` وتريد عرضه بأصفار بادئة، كما في ``003``. إحدى الطرق للقيام بذلك هي استخدام تنسيق ``0>3s``. ومع ذلك، افتراضيًا إذا كان الرقم (صحيح أو عشري) يساوي صفرًا، فإن القيمة تُعرض كسلسلة فارغة، لذا ستنتج القيم الصفرية سلسلة فارغة، وليس ``000``. إذا كنت تريد رؤية قيم ``000``، فاستخدم سلسلة التنسيق ودالة ``ifempty`` لتغيير القيمة الفارغة مرة أخرى إلى صفر. سيكون القالب::

en: Note that you can use the prefix and suffix as well. If you want the number to appear as ``[003]`` or ``[000]``, then use the template::
ar: لاحظ أنه يمكنك استخدام البادئة واللاحقة أيضًا. إذا كنت تريد أن يظهر الرقم كـ ``[003]`` أو ``[000]``، فاستخدم القالب::

en: General Program Mode
ar: وضع البرنامج العام

en: `General Program Mode` (`GPM`) replaces `template expressions` with a program written in the `template language`. The syntax of the language is defined by the following grammar::
ar: `وضع البرنامج العام` (`GPM`) يستبدل `تعبيرات القالب` بـ برنامج مكتوب بلغة `القالب`. يتم تعريف صيغة اللغة بالقواعد النحوية التالية::

en: a ``top_expression`` always has a value. The value of an ``expression_list`` is the value of the last ``top_expression`` in the list. For example, the value of the expression list ``1;2;'foobar';3`` is ``3``.
ar: لـ ``تعبير_أعلى`` دائمًا قيمة. قيمة ``قائمة_التعبيرات`` هي قيمة آخر ``تعبير_أعلى`` في القائمة. على سبيل المثال، قيمة قائمة التعبيرات ``1;2;'foobar';3`` هي ``3``.

en: In a logical context, any non-empty value is ``True``
ar: في سياق منطقي، أي قيمة غير فارغة هي ``True``

en: In a logical context, the empty value is ``False``
ar: في سياق منطقي، القيمة الفارغة هي ``False``

en: Strings and numbers can be used interchangeably. For example, ``10`` and ``'10'`` are the same thing.
ar: يمكن استخدام السلاسل والأرقام بالتبادل. على سبيل المثال، ``10`` و ``'10'`` هما نفس الشيء.

en: **Operator precedence**
ar: **أسبقية العوامل**

en: The operator precedence (order of evaluation) from highest (evaluated first) to lowest (evaluated last) is:
ar: أسبقية العوامل (ترتيب التقييم) من الأعلى (يتم تقييمه أولاً) إلى الأدنى (يتم تقييمه أخيرًا) هي:

en: Function calls, constants, parenthesized expressions, statement expressions, assignment expressions, field references.
ar: استدعاءات الدوال، الثوابت، التعبيرات بين قوسين، تعبيرات الجمل، تعبيرات الإسناد، مراجع الحقول.

en: Unary plus (``+``) and minus (``-``). These operators evaluate right to left.
ar: الجمع الأحادي (``+``) والطرح الأحادي (``-``). يتم تقييم هذه العوامل من اليمين إلى اليسار.

en: These and all the other arithmetic operators return integers if the expression results in a fractional part equal to zero. For example, if an expression returns ``3.0`` it is changed to ``3``.
ar: تعيد هذه العوامل وجميع العوامل الحسابية الأخرى أعدادًا صحيحة إذا كانت النتيجة تحتوي على جزء كسري يساوي صفرًا. على سبيل المثال، إذا كان التعبير يعيد ``3.0`` فإنه يتغير إلى ``3``.

en: Multiply (``*``) and divide (``/``). These operators are associative and evaluate left to right. Use parentheses if you want to change the order of evaluation.
ar: الضرب (``*``) والقسمة (``/``). هذه العوامل ترابطية و تُقيّم من اليسار إلى اليمين. استخدم الأقواس إذا كنت ترغب في تغيير ترتيب التقييم.

en: Add (``+``) and subtract (``-``). These operators are associative and evaluate left to right.
ar: الجمع (``+``) والطرح (``-``). هذه العوامل ترابطية و تُقيّم من اليسار إلى اليمين.

en: Numeric and string comparisons. These operators return ``'1'`` if the comparison succeeds, otherwise the empty string (``''``). Comparisons are not associative: ``a < b < c`` is a syntax error.
ar: المقارنات العددية والنصية. تعيد هذه العوامل ``'1'`` إذا نجحت المقارنة، وإلا فإنها تعيد السلسلة الفارغة (``''``). المقارنات ليست ترابطية: ``a < b < c`` هو خطأ في الصيغة.

en: String concatenation (``&``). The ``&`` operator returns a string formed by concatenating the left-hand and right-hand expressions. Example: ``'aaa' & 'bbb'`` returns ``'aaabbb'``. The operator is associative and evaluates left to right.
ar: سلسلة الربط (``&``). تعيد عامل التشغيل ``&`` سلسلة مكونة من ربط التعبيرات اليسرى واليمنى. مثال: ``'aaa' & 'bbb'`` يعيد ``'aaabbb'``. عامل التشغيل ترابطي ويُقيّم من اليسار إلى اليمين.

en: Unary logical not (``!``). This operator returns ``'1'`` if the expression is False (evaluates to the empty string), otherwise ``''``.
ar: النفي المنطقي الأحادي (``!``). يعيد هذا العامل ``'1'`` إذا كان التعبير خاطئًا (يُقيّم إلى سلسلة فارغة)، وإلا فإنه يعيد ``''``.

en: Logical and (``&&``). This operator returns '1' if both the left-hand and right-hand expressions are True, or the empty string ``''`` if either is False. It is associative, evaluates left to right, and does `short-circuiting <https://chortle.ccsu.edu/java5/Notes/chap40/ch40_2.html>`_.
ar: المنطقي و (``&&``). يعيد هذا العامل '1' إذا كان كلا التعبيرين الأيسر و الأيمن صحيحين، أو السلسلة الفارغة ``''`` إذا كان أحدهما خاطئًا. إنه ترابطي، يُقيّم من اليسار إلى اليمين، ويقوم بـ `التقصير <https://chortle.ccsu.edu/java5/Notes/chap40/ch40_2.html>`_.

en: Logical or (``||``). This operator returns ``'1'`` if either the left-hand or right-hand expression is True, or ``''`` if both are False. It is associative, evaluates left to right, and does `short-circuiting <https://chortle.ccsu.edu/java5/Notes/chap40/ch40_2.html>`_. It is an `inclusive or`, returning ``'1'`` if both the left- and right-hand expressions are True.
ar: المنطقي أو (``||``). يعيد هذا العامل ``'1'`` إذا كان التعبير الأيسر أو الأيمن صحيحًا، أو ``''`` إذا كان كلاهما خاطئًا. إنه ترابطي، يُقيّم من اليسار إلى اليمين، ويقوم بـ `التقصير <https://chortle.ccsu.edu/java5/Notes/chap40/ch40_2.html>`_. إنه `أو شامل`، يعيد ``'1'`` إذا كان كلا التعبيرين الأيسر والأيمن صحيحين.

en: **Field references**
ar: **مراجع الحقول**

en: A ``field_reference`` evaluates to the value of the metadata field named by lookup name that follows the ``$`` or ``$$``. Using ``$`` is equivalent to using the :ref:`ff_field` function. Using ``$$`` is equivalent to using the :ref:`ff_raw_field` function. Examples::
ar: يُقيّم ``field_reference`` إلى قيمة حقل البيانات الوصفية المسمى بواسطة اسم البحث الذي يتبع ``$`` أو ``$$``. استخدام ``$`` يعادل استخدام دالة :ref:`ff_field`. استخدام ``$$`` يعادل استخدام دالة :ref:`ff_raw_field`. أمثلة::

en: **If expressions**
ar: **تعبيرات الشرط (If)**

en: ``If`` expressions first evaluate the ``condition``. If the ``condition`` is True (a non-empty value) then the ``expression_list`` in the ``then`` clause is evaluated. If it is False then if present the ``expression_list`` in the ``elif`` or ``else`` clause is evaluated. The ``elif`` and ``else`` parts are optional. The words ``if``, ``then``, ``elif``, ``else``, and ``fi`` are reserved; you cannot use them as identifier names. You can put newlines and white space wherever they make sense. The ``condition`` is a ``top_expression`` not an ``expression_list``; semicolons are not allowed. The ``expression_lists`` are semicolon-separated sequences of ``top_expressions``. An ``if`` expression returns the result of the last ``top_expression`` in the evaluated ``expression_list``, or the empty string if no expression list was evaluated.
ar: تعبيرات ``If`` تُقيّم أولاً ``الشرط``. إذا كان ``الشرط`` صحيحًا (قيمة غير فارغة) فسيتم تقييم ``قائمة_التعبيرات`` في بند ``then``. إذا كان خاطئًا، فسيتم تقييم ``قائمة_التعبيرات`` في بند ``elif`` أو ``else`` إن وجدت. أجزاء ``elif`` و ``else`` اختيارية. الكلمات ``if``، ``then``، ``elif``، ``else``، و ``fi`` محجوزة؛ لا يمكنك استخدامها كأسماء معرفات. يمكنك وضع أسطر جديدة ومسافات بيضاء حيثما يكون ذلك منطقيًا. ``الشرط`` هو ``تعبير_أعلى`` وليس ``قائمة_تعبيرات``؛ لا يُسمح بالفواصل المنقوطة. ``قوائم_التعبيرات`` هي تسلسلات مفصولة بفاصلة منقوطة من ``تعبيرات_أعلى``. يعيد تعبير ``if`` نتيجة آخر ``تعبير_أعلى`` في ``قائمة_التعبيرات`` التي تم تقييمها، أو سلسلة فارغة إذا لم يتم تقييم أي قائمة تعبيرات.

en: Examples::
ar: أمثلة::

en: Nested ``if`` example::
ar: مثال ``if`` المتداخل::

en: As said above, an ``if`` produces a value. This means that all the following are equivalent::
ar: كما ذكر أعلاه، ينتج ``if`` قيمة. هذا يعني أن جميع ما يلي متكافئ::

en: For example, this program returns the value of the ``series`` column if the book has a series, otherwise the value of the ``title`` column::
ar: على سبيل المثال، يعيد هذا البرنامج قيمة عمود ``series`` إذا كان الكتاب يحتوي على سلسلة، وإلا فإنه يعيد قيمة عمود ``title``::

en: **For expressions**
ar: **تعبيرات For**

en: The ``for`` expression iterates over a list of values, processing them one at a time. The ``list_expression`` must evaluate either to a metadata field ``lookup name`` e.g., ``tags`` or ``#genre``, or to a list of values. The :ref:`ff_range` generates a list of numbers. If the result is a valid ``lookup name`` then the field's value is fetched and the separator specified for that field type is used. If the result isn't a valid lookup name then it is assumed to be a list of values. The list is assumed to be separated by commas unless the optional keyword ``separator`` is supplied, in which case the list values must be separated by the result of evaluating the ``separator_expr``. A separator cannot be used if the list is generated by ``range()``. Each value in the list is assigned to the specified variable then the ``expression_list`` is evaluated. You can use ``break`` to jump out of the loop, and ``continue`` to jump to the beginning of the loop for the next iteration.
ar: تعبير ``for`` يتكرر على قائمة من القيم، ويعالجها واحدة تلو الأخرى. يجب أن تُقيّم ``list_expression`` إما إلى حقل بيانات وصفية ``اسم البحث``، على سبيل المثال، ``tags`` أو ``#genre``، أو إلى قائمة من القيم. تُنشئ :ref:`ff_range` قائمة من الأرقام. إذا كانت النتيجة ``اسم بحث`` صالحًا، فسيتم جلب قيمة الحقل واستخدام الفاصل المحدد لنوع الحقل هذا. إذا لم تكن النتيجة اسم بحث صالحًا، فإنها تُفترض أنها قائمة من القيم. تُفترض القائمة أنها مفصولة بفاصلات ما لم يتم توفير الكلمة المفتاحية الاختيارية ``separator``، وفي هذه الحالة يجب فصل قيم القائمة بنتيجة تقييم ``separator_expr``. لا يمكن استخدام الفاصل إذا تم إنشاء القائمة بواسطة ``range()``. يتم تعيين كل قيمة في القائمة إلى المتغير المحدد ثم يتم تقييم ``expression_list``. يمكنك استخدام ``break`` للقفز خارج الحلقة، و ``continue`` للقفز إلى بداية الحلقة لـ التكرار التالي.

en: Example: This template removes the first hierarchical name for each value in Genre (``#genre``), constructing a list with the new names::
ar: مثال: يقوم هذا القالب بإزالة الاسم الهرمي الأول لكل قيمة في النوع (``#genre``)، مكونًا قائمة بالأسماء الجديدة::

en: If the original Genre is `History.Military, Science Fiction.Alternate History, ReadMe` then the template returns `Military, Alternate History, ReadMe`. You could use this template in calibre's :guilabel:`Edit metadata in bulk -> Search & replace` with :guilabel:`Search for` set to ``template`` to strip off the first level of the hierarchy and assign the resulting value to Genre.
ar: إذا كان النوع الأصلي هو `History.Military, Science Fiction.Alternate History, ReadMe`، فإن القالب يعيد `Military, Alternate History, ReadMe`. يمكنك استخدام هذا القالب في calibre's :guilabel:`تحرير البيانات الوصفية بالجملة -> بحث واستبدال` مع تعيين :guilabel:`البحث عن` إلى ``template`` لإزالة المستوى الأول من التسلسل الهرمي وتعيين القيمة الناتجة إلى النوع.

en: Note: the last line in the template, ``new_tags``, isn't strictly necessary in this case because ``for`` returns the value of the last top_expression in the expression list. The value of an assignment is the value of its expression, so the value of the ``for`` statement is what was assigned to ``new_tags``.
ar: ملاحظة: السطر الأخير في القالب، ``new_tags``، ليس ضروريًا تمامًا في هذه الحالة لأن ``for`` يعيد قيمة آخر تعبير علوي في قائمة التعبيرات. قيمة التعيين هي قيمة تعبيره، لذا فإن قيمة عبارة ``for`` هي ما تم تعيينه لـ ``new_tags``.

en: **Function definition**
ar: **تعريف الدالة**

en: If you have repeated code in a template then you can put that code into a local function. The ``def`` keyword starts the definition. It is followed by the function name, the argument list, then the code in the function. The function definition ends with the ``fed`` keyword.
ar: إذا كان لديك رمز متكرر في قالب، فيمكنك وضع هذا الرمز في دالة محلية. تبدأ الكلمة المفتاحية ``def`` التعريف. تتبعها اسم الدالة، قائمة الوسائط، ثم الرمز في الدالة. ينتهي تعريف الدالة بالكلمة المفتاحية ``fed``.

en: Arguments are positional. When a function is called the supplied arguments are matched left to right against the defined parameters, with the value of the argument assigned to the parameter. It is an error to provide more arguments than defined parameters. Parameters can have default values, such as ``a = 25``. If an argument is not supplied for that parameter then the default value is used, otherwise the parameter is set to the empty string.
ar: الوسائط موضعية. عند استدعاء دالة، تتم مطابقة الوسائط المقدمة من اليسار إلى اليمين مع المعلمات المحددة، مع تعيين قيمة الوسيط إلى المعلمة. يعد خطأً توفير عدد من الوسائط أكثر من المعلمات المحددة. يمكن أن تحتوي المعلمات على قيم افتراضية، مثل ``a = 25``. إذا لم يتم توفير وسيط لتلك المعلمة، فسيتم استخدام القيمة الافتراضية، وإلا فسيتم تعيين المعلمة إلى سلسلة فارغة.

en: The ``return`` statement can be used in a local function.
ar: يمكن استخدام عبارة ``return`` في دالة محلية.

en: A function must be defined before it can be used.
ar: يجب تعريف الدالة قبل استخدامها.

en: Example: This template computes an approximate duration in years, months, and days from a number of days. The function ``to_plural()`` formats the computed values. Note that the example also uses the ``&`` operator::
ar: مثال: يحسب هذا القالب مدة تقريبية بالسنوات والأشهر والأيام من عدد من الأيام. تقوم الدالة ``to_plural()`` بتنسيق القيم المحسوبة. لاحظ أن المثال يستخدم أيضًا عامل التشغيل ``&``::

en: **Relational operators**
ar: **عوامل التشغيل العلائقية**

en: Relational operators return ``'1'`` if the comparison is true, otherwise the empty string (``''``).
ar: تعيد عوامل التشغيل العلائقية ``'1'`` إذا كانت المقارنة صحيحة، وإلا فإنها تعيد السلسلة الفارغة (``''``).

en: There are two forms of relational operators: string comparisons and numeric comparisons.
ar: هناك شكلان من عوامل التشغيل العلائقية: مقارنات السلاسل و مقارنات الأرقام.

en: String comparisons do case-insensitive string comparison using lexical order. The supported string comparison operators are ``==``, ``!=``, ``<``, ``<=``, ``>``, ``>=``, ``in``, ``inlist``, and ``inlist_field``. For the ``in``, ``inlist``, and ``inlist_field`` operators, the result of the left hand expression is interpreted as a regular expression pattern. They are true if the value of left-hand regular expression matches the value of the right hand expression. The regular expressions are case-insensitive.
ar: تقوم مقارنات السلاسل بمقارنة سلاسل غير حساسة لحالة الأحرف باستخدام الترتيب المعجمي. عوامل مقارنة السلاسل المدعومة هي ``==``، ``!=``، ``<``، ``<=``، ``>``، ``>=``، ``in``، ``inlist``، و ``inlist_field``. بالنسبة لـ عوامل التشغيل ``in``، ``inlist``، و ``inlist_field``، يتم تفسير نتيجة التعبير الأيسر كنمط تعبير نمطي. وهي صحيحة إذا كانت قيمة التعبير النمطي الأيسر تطابق قيمة التعبير الأيمن. التعبيرات النمطية غير حساسة لحالة الأحرف.

en: The ``inlist`` operator is true if the left hand regular expression matches any one of the items in the right hand list where the items in the list are separated by commas. The ``inlist_field`` operator is true if the left hand regular expression matches any of the items in the field (column) named by the right hand expression, using the separator defined for the field. NB: the ``inlist_field`` operator requires the right hand expression to evaluate to a field name, while the ``inlist`` operator requires the right hand expression to evaluate to a string containing a comma-separated list. Because of this difference, ``inlist_field`` is substantially faster than ``inlist`` because no string conversions or list constructions are done.
ar: عامل التشغيل ``inlist`` يكون صحيحًا إذا كان التعبير النمطي الأيسر يطابق أي عنصر من العناصر في القائمة اليمنى حيث يتم فصل العناصر في القائمة بفاصلات. عامل التشغيل ``inlist_field`` يكون صحيحًا إذا كان التعبير النمطي الأيسر يطابق أي من العناصر في الحقل (العمود) المسمى بواسطة التعبير الأيمن، باستخدام الفاصل المحدد للحقل. ملاحظة: يتطلب عامل التشغيل ``inlist_field`` أن يُقيّم التعبير الأيمن إلى اسم حقل، بينما يتطلب عامل التشغيل ``inlist`` أن يُقيّم التعبير الأيمن إلى سلسلة تحتوي على قائمة مفصولة بفاصلات. بسبب هذا الاختلاف، ``inlist_field`` أسرع بكثير من ``inlist`` لأنه لا يتم إجراء تحويلات سلاسل أو إنشاء قوائم.

en: The numeric comparison operators are ``==#``, ``!=#``, ``<#``, ``<=#``, ``>#``, ``>=#``. The left and right expressions must evaluate to numeric values with two exceptions: both the string value "None" (undefined field) and the empty string evaluate to the value zero.
ar: عوامل المقارنة العددية هي ``==#``، ``!=#``، ``<#``، ``<=#``، ``>#``، ``>=#``. يجب أن تُقيّم التعبيرات اليسرى واليمنى إلى قيم عددية باستثناءين: كل من القيمة النصية "None" (حقل غير معرف) والسلسلة الفارغة تُقيّم إلى القيمة صفر.

en: Examples:
ar: أمثلة:

en: ``program: field('series') == 'foo'`` returns ``'1'`` if the book's series is `foo`, otherwise ``''``.
ar: ``program: field('series') == 'foo'`` يعيد ``'1'`` إذا كانت سلسلة الكتاب هي `foo`، وإلا ``''``.

en: ``program: 'f.o' in field('series')`` returns ``'1'`` if the book's series matches the regular expression ``f.o`` (e.g., `foo`, `Off Onyx`, etc.), otherwise ``''``.
ar: ``program: 'f.o' in field('series')`` يعيد ``'1'`` إذا كانت سلسلة الكتاب تطابق التعبير النمطي ``f.o`` (مثل `foo`, `Off Onyx`, إلخ)، وإلا ``''``.

en: ``program: 'science' inlist $#genre`` returns ``'1'`` if any of the values retrieved from the book's genres match the regular expression ``science``, e.g., `Science`, `History of Science`, `Science Fiction` etc., otherwise ``''``.
ar: ``program: 'science' inlist $#genre`` يعيد ``'1'`` إذا كانت أي من القيم المستردة من أنواع الكتاب تطابق التعبير النمطي ``science``، مثل `Science`, `History of Science`, `Science Fiction` إلخ، وإلا ``''``.

en: ``program: '^science$' inlist $#genre`` returns ``'1'`` if any of the book's genres exactly match the regular expression ``^science$``, e.g., `Science`, otherwise ``''``. The genres `History of Science` and `Science Fiction` don't match.
ar: ``program: '^science$' inlist $#genre`` يعيد ``'1'`` إذا كانت أي من أنواع الكتاب تطابق تمامًا التعبير النمطي ``^science$``، مثل `Science`، وإلا ``''``. لا تتطابق أنواع `History of Science` و `Science Fiction`.

en: ``program: 'asimov' inlist $authors`` returns ``'1'`` if any author matches the regular expression ``asimov``, e.g., `Asimov, Isaac` or `Isaac Asimov`, otherwise ``''``.
ar: ``program: 'asimov' inlist $authors`` يعيد ``'1'`` إذا كان أي مؤلف يطابق التعبير النمطي ``asimov``، مثل `Asimov, Isaac` أو `Isaac Asimov`، وإلا ``''``.

en: ``program: 'asimov' inlist_field 'authors'`` returns ``'1'`` if any author matches the regular expression ``asimov``, e.g., `Asimov, Isaac` or `Isaac Asimov`, otherwise ``''``.
ar: ``program: 'asimov' inlist_field 'authors'`` يعيد ``'1'`` إذا كان أي مؤلف يطابق التعبير النمطي ``asimov``، مثل `Asimov, Isaac` أو `Isaac Asimov`، وإلا ``''``.

en: ``program: 'asimov$' inlist_field 'authors'`` returns ``'1'`` if any author matches the regular expression ``asimov$``, e.g., `Isaac Asimov`, otherwise ``''``. It doesn't match `Asimov, Isaac` because of the ``$`` anchor in the regular expression.
ar: ``program: 'asimov$' inlist_field 'authors'`` يعيد ``'1'`` إذا كان أي مؤلف يطابق التعبير النمطي ``asimov$``، مثل `Isaac Asimov`، وإلا ``''``. لا يطابق `Asimov, Isaac` بسبب علامة ``$`` في التعبير النمطي.

en: ``program: if field('series') != 'foo' then 'bar' else 'mumble' fi`` returns ``'bar'`` if the book's series is not `foo`. Otherwise it returns ``'mumble'``.
ar: ``program: if field('series') != 'foo' then 'bar' else 'mumble' fi`` يعيد ``'bar'`` إذا لم تكن سلسلة الكتاب `foo`. وإلا فإنه يعيد ``'mumble'``.

en: ``program: if field('series') == 'foo' || field('series') == '1632' then 'yes' else 'no' fi`` returns ``'yes'`` if series is either `foo` or `1632`, otherwise ``'no'``.
ar: ``program: if field('series') == 'foo' || field('series') == '1632' then 'yes' else 'no' fi`` يعيد ``'yes'`` إذا كانت السلسلة إما `foo` أو `1632`، وإلا ``'no'``.

en: ``program: if '^(foo|1632)$' in field('series') then 'yes' else 'no' fi`` returns ``'yes'`` if series is either `foo` or `1632`, otherwise ``'no'``.
ar: ``program: if '^(foo|1632)$' in field('series') then 'yes' else 'no' fi`` يعيد ``'yes'`` إذا كانت السلسلة إما `foo` أو `1632`، وإلا ``'no'``.

en: ``program: if 11 > 2 then 'yes' else 'no' fi`` returns ``'no'`` because the ``>`` operator does a lexical comparison.
ar: ``program: if 11 > 2 then 'yes' else 'no' fi`` يعيد ``'no'`` لأن عامل التشغيل ``>`` يقوم بمقارنة معجمية.

en: ``program: if 11 ># 2 then 'yes' else 'no' fi`` returns ``'yes'`` because the ``>#`` operator does a numeric comparison.
ar: ``program: if 11 ># 2 then 'yes' else 'no' fi`` يعيد ``'yes'`` لأن عامل التشغيل ``>#`` يقوم بمقارنة عددية.

en: **Functions in General Program Mode**
ar: **الدوال في وضع البرنامج العام**

en: See :ref:`template_functions_reference` for the list of functions built into the template language.
ar: راجع :ref:`template_functions_reference` للحصول على قائمة بالدوال المضمنة في لغة القوالب.

en: As opposed to :ref:`Single Function Mode <single_mode>`, in General Program Mode you must specify the first parameter ``value``.
ar: على عكس :ref:`وضع الدالة الواحدة <single_mode>`، في وضع البرنامج العام يجب عليك تحديد المعامل الأول ``value``.

en: All parameters are expression_lists (see the grammar above).
ar: جميع المعلمات هي expression_lists (انظر القواعد النحوية أعلاه).

en: More complex programs in template expressions - Template Program Mode
ar: برامج أكثر تعقيدًا في تعبيرات القوالب - وضع برنامج القالب

en: `Template Program Mode` (`TPM`) is a blend of :ref:`General Program Mode <general_mode>` and :ref:`Single Function Mode <single_mode>`. `TPM` differs from Single Function Mode in that it permits writing template expressions that refer to other metadata fields, use nested functions, modify variables, and do arithmetic. It differs from `General Program Mode` in that the template is contained between ``{`` and ``}`` characters and doesn't begin with the word ``program:``. The program portion of the template is a General Program Mode expression list.
ar: `وضع برنامج القالب` (`TPM`) هو مزيج من :ref:`وضع البرنامج العام <general_mode>` و :ref:`وضع الدالة الواحدة <single_mode>`. يختلف `TPM` عن وضع الدالة الواحدة في أنه يسمح بكتابة تعبيرات القالب التي تشير إلى حقول بيانات وصفية أخرى، وتستخدم دوال متداخلة، وتعديل المتغيرات، وتقوم بالعمليات الحسابية. يختلف عن `وضع البرنامج العام` في أن القالب محتوى بين أحرف ``{`` و ``}`` ولا يبدأ بالكلمة ``program:``. جزء البرنامج من القالب هو قائمة تعبيرات وضع البرنامج العام.

en: Example: assume you want a template to show the series for a book if it has one, otherwise show the value of a custom field #genre. You cannot do this in the :ref:`Single Function Mode <single_mode>` because you cannot make reference to another metadata field within a template expression. In `TPM` you can, as the following expression demonstrates::
ar: مثال: افترض أنك تريد قالبًا لعرض سلسلة كتاب إذا كان لديه واحدة، وإلا فعرض قيمة حقل مخصص #genre. لا يمكنك القيام بذلك في :ref:`وضع الدالة الواحدة <single_mode>` لأنه لا يمكنك الإشارة إلى حقل بيانات وصفية آخر ضمن تعبير قالب. في `TPM` يمكنك ذلك، كما يوضح التعبير التالي::

en: The example shows several things:
ar: يوضح المثال عدة أمور:

en: `TPM` is used if the expression begins with ``:'`` and ends with ``'}``. Anything else is assumed to be in :ref:`Single Function Mode <single_mode>`.
ar: يُستخدم `TPM` إذا بدأ التعبير بـ ``:'`` وانتهى بـ ``'}``. يُفترض أن أي شيء آخر هو في :ref:`وضع الدالة الواحدة <single_mode>`.

en: If the template contains a prefix and suffix, the expression ends with ``'|`` where the ``|`` is the delimiter for the prefix. Example::
ar: إذا كان القالب يحتوي على بادئة ولاحقة، ينتهي التعبير بـ ``'|`` حيث ``|`` هو الفاصل للبادئة. مثال::

en: Functions must be given all their arguments. For example, the standard built-in functions must be given the initial parameter ``value``.
ar: يجب إعطاء الدوال جميع وسائطها. على سبيل المثال، الدوال المدمجة القياسية يجب أن تُعطى المعامل الأولي ``value``.

en: The variable ``$`` is usable as the ``value`` argument and stands for the value of the field named in the template, ``series`` in this case.
ar: المتغير ``$`` قابل للاستخدام كوسيط ``value`` ويمثل قيمة الحقل المسمى في القالب، ``series`` في هذه الحالة.

en: white space is ignored and can be used anywhere within the expression.
ar: يتم تجاهل المسافات البيضاء ويمكن استخدامها في أي مكان داخل التعبير.

en: constant strings are enclosed in matching quotes, either ``'`` or ``"``.
ar: السلاسل الثابتة محاطة بعلامات اقتباس متطابقة، إما ``'`` أو ``"``.

en: In `TPM`, using ``{`` and ``}`` characters in string literals can lead to errors or unexpected results because they confuse the template processor. It tries to treat them as template expression boundaries, not characters. In some but not all cases you can replace a ``{`` with ``[[`` and a ``}`` with `]]`. Advice: if your program contains ``{`` and ``}`` characters then you should use `General Program Mode`.
ar: في `TPM`، يمكن أن يؤدي استخدام الأحرف ``{`` و ``}`` في السلاسل الحرفية إلى أخطاء أو نتائج غير متوقعة لأنها تربك معالج القوالب. فهو يحاول التعامل معها كحدود لتعبير القالب، وليس كأحرف. في بعض الحالات وليس كلها، يمكنك استبدال ``{`` بـ ``[[`` و ``}`` بـ ``]]``. نصيحة: إذا كان برنامجك يحتوي على أحرف ``{`` و ``}``، يجب عليك استخدام `وضع البرنامج العام`.

en: Python Template Mode
ar: وضع قالب بايثون

en: Python Template Mode (PTM) lets you write templates using native Python and the `calibre API <https://manual.calibre-ebook.com/develop.html#api-documentation-for-various-parts-of-calibre>`_. The database API will be of most use; further discussion is beyond the scope of this manual. PTM templates are faster and can do more complicated operations but you must know how to write code in Python using the calibre API.
ar: يسمح لك وضع قالب بايثون (PTM) بكتابة القوالب باستخدام بايثون الأصلي و `واجهة برمجة تطبيقات calibre <https://manual.calibre-ebook.com/develop.html#api-documentation-for-various-parts-of-calibre>`_. ستكون واجهة برمجة تطبيقات قاعدة البيانات الأكثر فائدة؛ المزيد من المناقشة خارج نطاق هذا الدليل. قوالب PTM أسرع ويمكنها القيام بعمليات أكثر تعقيدًا ولكن يجب عليك معرفة كيفية كتابة التعليمات البرمجية في بايثون باستخدام واجهة برمجة تطبيقات calibre.

en: A PTM template begins with:
ar: يبدأ قالب PTM بـ:

en: You can add the above text to your template using the context menu, usually accessed with a right click. The comments are not significant and can be removed. You must use python indenting.
ar: يمكنك إضافة النص أعلاه إلى القالب الخاص بك باستخدام قائمة السياق، والتي يتم الوصول إليها عادةً بالنقر بزر الماوس الأيمن. التعليقات ليست مهمة ويمكن إزالتها. يجب عليك استخدام المسافة البادئة في بايثون.

en: The context object supports ``str(context)`` that returns a string of the context's contents, and ``context.attributes`` that returns a list of the attribute names in the context.
ar: يدعم كائن السياق ``str(context)`` الذي يعيد سلسلة من محتويات السياق، و ``context.attributes`` الذي يعيد قائمة بأسماء السمات في السياق.

en: The ``context.funcs`` attribute allows calling Built-in and User template functions, and Stored GPM/Python templates, so that you can execute them directly in your code. The functions are retrieved using their names. If the name conflicts with a Python keyword, add an underscore to the end of the name. Examples:
ar: تسمح السمة ``context.funcs`` باستدعاء دوال القوالب المدمجة والمستخدمة، وقوالب GPM/Python المخزنة، بحيث يمكنك تنفيذها مباشرة في التعليمات البرمجية الخاصة بك. يتم استرداد الدوال باستخدام أسمائها. إذا تعارض الاسم مع كلمة مفتاحية في Python، أضف شرطة سفلية إلى نهاية الاسم. أمثلة:

en: Here is an example of a PTM template that produces a list of all the authors for a series. The list is stored in a `Column built from other columns, behaves like tags`. It shows in :guilabel:`Book details` and has the :guilabel:`on separate lines` checked (in :guilabel:`Preferences->Look & feel->Book details`). That option requires the list to be comma-separated. To satisfy that requirement the template converts commas in author names to semicolons then builds a comma-separated list of authors. The authors are then sorted, which is why the template uses author_sort.
ar: إليك مثال لقالب PTM ينتج قائمة بجميع المؤلفين لسلسلة. يتم تخزين القائمة في `عمود مبني من أعمدة أخرى، يتصرف مثل العلامات`. يظهر في :guilabel:`تفاصيل الكتاب` ويحتوي على :guilabel:`على أسطر منفصلة` محدد (في :guilabel:`التفضيلات->المظهر و الشعور->تفاصيل الكتاب`). يتطلب هذا الخيار أن تكون القائمة مفصولة بفاصلات. لتلبية هذا الشرط، يقوم القالب بتحويل الفواصل في أسماء المؤلفين إلى فواصل منقوطة ثم يبني قائمة مفصولة بفاصلات من المؤلفين. يتم فرز المؤلفين بعد ذلك، وهذا هو السبب في أن القالب يستخدم author_sort.

en: The output in :guilabel:`Book details` looks like this:
ar: الإخراج في :guilabel:`تفاصيل الكتاب` يبدو كالتالي:

en: E-book conversion dialog
ar: مربع حوار تحويل الكتاب الإلكتروني

en: Templates and URLs
ar: القوالب وعناوين URL

en: You can use templates to construct URLs. Two cases are described here:
ar: يمكنك استخدام القوالب لإنشاء عناوين URL. يتم وصف حالتين هنا:

en: Custom column :guilabel:`Book details` search URLs
ar: أعمدة مخصصة :guilabel:`تفاصيل الكتاب` عناوين URL للبحث

en: The calibre URL scheme
ar: مخطط عنوان URL لـ calibre

en: **Custom column book details search URLs**
ar: **عناوين URL للبحث في تفاصيل الكتاب في العمود المخصص**

en: When you create a custom column you can provide a URL to be used in :guilabel:`Book details` using a template. For example, if you have a custom column for `Translators` you can define a URL to take you to a site for translators. Book details search URLs can be provided for `Text`, `Enumerated`, `Series`, and `Column built from other column` column types.
ar: عند إنشاء عمود مخصص، يمكنك توفير عنوان URL لاستخدامه في :guilabel:`تفاصيل الكتاب` باستخدام قالب. على سبيل المثال، إذا كان لديك عمود مخصص لـ `المترجمين`، يمكنك تحديد عنوان URL يأخذك إلى موقع للمترجمين. يمكن توفير عناوين URL للبحث في تفاصيل الكتاب لأنواع الأعمدة `نص`، `معدود`، `سلسلة`، و `عمود مبني من عمود آخر`.

en: When an item with a `search template` is clicked in :guilabel:`Book details` the template is evaluated. It is provided the normal book metadata. It is also provided three additional fields:
ar: عند النقر على عنصر يحتوي على `قالب بحث` في :guilabel:`تفاصيل الكتاب`، يتم تقييم القالب. يتم توفير البيانات الوصفية العادية للكتاب. كما يتم توفير ثلاثة حقول إضافية:

en: ``item_value``: the value of the clicked item.
ar: ``item_value``: قيمة العنصر الذي تم النقر عليه.

en: ``item_value_quoted``: the value of clicked item, URL-encoded. Special characters are escaped to make them valid in URLs and spaces are replaced by ``'+'`` (plus) signs.
ar: ``item_value_quoted``: قيمة العنصر الذي تم النقر عليه، مشفرة لعنوان URL. يتم الهروب من الأحرف الخاصة لجعلها صالحة في عناوين URL ويتم استبدال المسافات بـ علامات ``'+'`` (زائد).

en: ``item_value_no_plus``: the value of clicked item, URL-encoded. Special characters are escaped to make them valid in URLs and spaces are replaced by the ``%20``, not plus.
ar: ``item_value_no_plus``: قيمة العنصر الذي تم النقر عليه، مشفرة لعنوان URL. يتم الهروب من الأحرف الخاصة لجعلها صالحة في عناوين URL ويتم استبدال المسافات بـ ``%20``، وليس علامة زائد.

en: There are several ways to construct the URL. The following use Wikipedia as an example.
ar: هناك عدة طرق لإنشاء عنوان URL. تستخدم الأمثلة التالية ويكيبيديا كـ مثال.

en: The simplest is a basic template::
ar: الأبسط هو قالب أساسي::

en: In some cases you might want to do more processing. There are four template functions you can use, depending on the complexity of the processing.
ar: في بعض الحالات قد ترغب في إجراء المزيد من المعالجة. هناك أربع دوال قالب يمكنك استخدامها، اعتمادًا على تعقيد المعالجة.

en: For example, assume you have a custom column `Translators` (``#translators``) where the names are `Last name, First name`. You might need to convert the name to `First name Last name` when creating the URL. You can use the :ref:`ff_make_url` function to do this::
ar: على سبيل المثال، افترض أن لديك عمودًا مخصصًا `المترجمون` (``#translators``) حيث الأسماء هي `اسم العائلة، الاسم الأول`. قد تحتاج إلى تحويل الاسم إلى `الاسم الأول اسم العائلة` عند إنشاء عنوان URL. يمكنك استخدام دالة :ref:`ff_make_url` للقيام بذلك::

en: If we assume that the translator's name is `Boy-Żeleński, Tadeusz` then the above template produces the link::
ar: إذا افترضنا أن اسم المترجم هو `Boy-Żeleński, Tadeusz`، فإن القالب أعلاه ينتج الرابط::

en: Note that the person's first name is now first, the space is now a plus, and that the non-English characters in the last name are URL-encoded.
ar: لاحظ أن الاسم الأول للشخص أصبح الآن أولاً، والمسافة أصبحت علامة زائد، و أن الأحرف غير الإنجليزية في اسم العائلة مشفرة لعنوان URL.

en: The functions :ref:`ff_make_url_extended`, :ref:`ff_query_string`, and :ref:`ff_encode_for_url` might be useful depending upon any additional processing complexity.
ar: قد تكون الدوال :ref:`ff_make_url_extended`، :ref:`ff_query_string`، و :ref:`ff_encode_for_url` مفيدة اعتمادًا على أي تعقيد معالجة إضافي.

en: **The calibre URL scheme**
ar: **مخطط عنوان URL لـ calibre**

en: Calibre supports several different URLs to navigate your calibre libraries. This section shows how to use templates to construct some of the URLs. See :doc:`url_scheme` for details on the URLs available.
ar: يدعم Calibre عدة عناوين URL مختلفة للتنقل في مكتبات calibre الخاصة بك. يوضح هذا القسم كيفية استخدام القوالب لإنشاء بعض عناوين URL. راجع :doc:`url_scheme` للحصول على تفاصيل حول عناوين URL المتاحة.

en: Switch to a specific library. The syntax of this URL is::
ar: التبديل إلى مكتبة معينة. صيغة عنوان URL هذا هي::

en: ``Library_Name`` must be replaced with the name of the calibre library you wish to open. The library name is shown in the title bar of the window. It is a simple name, not the file path to the library. You must spell it as shown in the title bar, including letter case. The character ``_`` (underscore) stands for the current library. If the name contains any spaces or special characters then it must be hex encoded using the :ref:`ff_to_hex` function, as in the following example::
ar: يجب استبدال ``Library_Name`` باسم مكتبة calibre التي ترغب في فتحها. يظهر اسم المكتبة في شريط عنوان النافذة. إنه اسم بسيط، وليس مسار الملف إلى المكتبة. يجب أن تكتبه كما يظهر في شريط العنوان، بما في ذلك حالة الأحرف. الحرف ``_`` (شرطة سفلية) يرمز إلى المكتبة الحالية. إذا كان الاسم يحتوي على أي مسافات أو أحرف خاصة، فيجب ترميزه سداسيًا عشريًا باستخدام دالة :ref:`ff_to_hex`، كما في المثال التالي::

en: The template generates the URL::
ar: ينشئ القالب عنوان URL::

en: You can replace the ``current_library_name()`` function with the actual name of the library, as in::
ar: يمكنك استبدال دالة ``current_library_name()`` بالاسم الفعلي للمكتبة، كما في::

en: Links to show books. These links select a book in the calibre library. The syntax for this URL is::
ar: روابط لعرض الكتب. تحدد هذه الروابط كتابًا في مكتبة calibre. صيغة عنوان URL هذا هي::

en: The ``book id`` is the numeric calibre id for the book, available to templates as ``$id``. As above, the library name might need to be hex encoded. Here is an example::
ar: معرف ``book id`` هو معرف calibre الرقمي للكتاب، متاح لـ القوالب كـ ``$id``. كما هو الحال أعلاه، قد يحتاج اسم المكتبة إلى ترميز سداسي عشري. إليك مثال::

en: It produces the URL::
ar: ينتج عنوان URL::

en: Searching for books. These links search for books in the specified calibre library. The syntax for this URL is::
ar: البحث عن الكتب. تبحث هذه الروابط عن الكتب في مكتبة calibre المحددة. صيغة عنوان URL هذا هي::

en: where `query` is any valid calibre search expression. You must hex encode any query containing spaces or special characters, which generally means all of them. For example, the calibre search expression for searching for a hierarchical tag beginning with 'AA' is ``tags:"=.AA"``. This template constructs a search URL for that expression::
ar: حيث `query` هو أي تعبير بحث صالح في calibre. يجب عليك ترميز سداسي عشري لأي استعلام يحتوي على مسافات أو أحرف خاصة، مما يعني عمومًا جميعها. على سبيل المثال، تعبير البحث في calibre للبحث عن علامة هرمية تبدأ بـ 'AA' هو ``tags:"=.AA"``. ينشئ هذا القالب عنوان URL للبحث عن هذا التعبير::

en: The resulting URL is::
ar: عنوان URL الناتج هو::

en: Here is an example of the same URL built using the :ref:``ff_make_url_extended`` function instead of :ref:`ff_strcat`::
ar: إليك مثال على نفس عنوان URL تم إنشاؤه باستخدام دالة :ref:``ff_make_url_extended`` بدلاً من :ref:`ff_strcat`::

en: Open a book details window on a book in some library. The syntax for this URL is::
ar: فتح نافذة تفاصيل كتاب لكتاب في مكتبة ما. صيغة عنوان URL هذا هي::

en: An example template is::
ar: مثال على قالب هو::

en: which produces the URL::
ar: الذي ينتج عنوان URL::

en: Open the notes associated with an author/series/etc. The syntax of the URL is::
ar: فتح الملاحظات المرتبطة بمؤلف/سلسلة/إلخ. صيغة عنوان URL هي::

en: ``Field_Name`` is the lookup name of the field. If the field is a custom column then replace the ``#`` character with an underscore (``_``). ``Item_Id`` is the internal numeric ID of the value in the field. There isn't a template function that returns the ``Item_Id``, so templates will normally use the second form, ``Hex_Encoded_Item_Name``. Here is a sample template that opens the note for the person ``Boy-Żeleński, Tadeusz`` in the field ``#authtest``::
ar: ``Field_Name`` هو اسم البحث للحقل. إذا كان الحقل عمودًا مخصصًا، فاستبدل الحرف ``#`` بشرطة سفلية (``_``). ``Item_Id`` هو المعرف الرقمي الداخلي للقيمة في الحقل. لا توجد دالة قالب تعيد ``Item_Id``، لذا ستستخدم القوالب عادةً الشكل الثاني، ``Hex_Encoded_Item_Name``. إليك قالب مثال يفتح الملاحظة للشخص ``Boy-Żeleński, Tadeusz`` في الحقل ``#authtest``::

en: Stored templates
ar: القوالب المخزنة

en: Both :ref:`General Program Mode <general_mode>` and :ref:`Python Template Mode <python_mode>` support saving templates and calling those templates from another template, much like calling stored functions. You save templates using :guilabel:`Preferences->Advanced->Template functions`. More information is provided in that dialog. You call a template the same way you call a function, passing positional arguments if desired. An argument can be any expression. Examples of calling a template, assuming the stored template is named ``foo``:
ar: يدعم كل من :ref:`وضع البرنامج العام <general_mode>` و :ref:`وضع قالب بايثون <python_mode>` حفظ القوالب واستدعاء تلك القوالب من قالب آخر، تمامًا مثل استدعاء الدوال المخزنة. يمكنك حفظ القوالب باستخدام :guilabel:`التفضيلات->متقدم->دوال القوالب`. يتم توفير المزيد من المعلومات في هذا الحوار. يمكنك استدعاء قالب بنفس الطريقة التي تستدعي بها دالة، مع تمرير الوسائط الموضعية إذا رغبت في ذلك. يمكن أن يكون الوسيط أي تعبير. أمثلة على استدعاء قالب، بافتراض أن القالب المخزن يسمى ``foo``:

en: ``foo()`` -- call the template passing no arguments.
ar: ``foo()`` -- استدعاء القالب دون تمرير أي وسائط.

en: ``foo(a, b)`` call the template passing the values of the two variables ``a`` and ``b``.
ar: ``foo(a, b)`` استدعاء القالب مع تمرير قيم المتغيرين ``a`` و ``b``.

en: ``foo(if field('series') then field('series_index') else 0 fi)`` -- if the book has a ``series`` then pass the ``series_index``, otherwise pass the value ``0``.
ar: ``foo(if field('series') then field('series_index') else 0 fi)`` -- إذا كان الكتاب يحتوي على ``سلسلة``، فمرر ``series_index``، وإلا فمرر القيمة ``0``.

en: In GPM you retrieve the arguments passed in the call to the stored template using the ``arguments`` function. It both declares and initializes local variables, effectively parameters. The variables are positional; they get the value of the parameter given in the call in the same position. If the corresponding parameter is not provided in the call then ``arguments`` assigns that variable the provided default value. If there is no default value then the variable is set to the empty string. For example, the following ``arguments`` function declares 2 variables, ``key``, ``alternate``::
ar: في GPM، تسترد الوسائط التي تم تمريرها في استدعاء القالب المخزن باستخدام دالة ``arguments``. إنها تعلن وتهيئ المتغيرات المحلية، وهي في الواقع معلمات. المتغيرات موضعية؛ تحصل على قيمة المعلمة المعطاة في الاستدعاء في نفس الموضع. إذا لم يتم توفير المعلمة المقابلة في الاستدعاء، فإن ``arguments`` تعين هذا المتغير القيمة الافتراضية المقدمة. إذا لم تكن هناك قيمة افتراضية، فإن المتغير يتم تعيينه إلى سلسلة فارغة. على سبيل المثال، دالة ``arguments`` التالية تعلن متغيرين، ``key``، ``alternate``::

en: Examples, again assuming the stored template is named ``foo``:
ar: أمثلة، بافتراض مرة أخرى أن القالب المخزن يسمى ``foo``:

en: ``foo('#myseries')`` -- argument ``key`` is assigned the value ``'myseries'`` and the argument ``alternate`` is assigned the default value ``'series'``.
ar: ``foo('#myseries')`` -- يتم تعيين الوسيط ``key`` للقيمة ``'myseries'`` ويتم تعيين الوسيط ``alternate`` للقيمة الافتراضية ``'series'``.

en: ``foo('series', '#genre')`` the variable ``key`` is assigned the value ``'series'`` and the variable ``alternate`` is assigned the value ``'#genre'``.
ar: ``foo('series', '#genre')`` يتم تعيين المتغير ``key`` للقيمة ``'series'`` ويتم تعيين المتغير ``alternate`` للقيمة ``'#genre'``.

en: ``foo()`` -- the variable ``key`` is assigned the empty string and the variable ``alternate`` is assigned the value ``'series'``.
ar: ``foo()`` -- يتم تعيين المتغير ``key`` للسلسلة الفارغة ويتم تعيين المتغير ``alternate`` للقيمة ``'series'``.

en: In PTM the arguments are passed in the ``arguments`` parameter, which is a list of strings. There isn't any way to specify default values. You must check the length of the ``arguments`` list to be sure that the number of arguments is what you expect.
ar: في PTM، يتم تمرير الوسائط في المعامل ``arguments``، وهو قائمة من السلاسل. لا توجد أي طريقة لتحديد قيم افتراضية. يجب عليك التحقق من طول قائمة ``arguments`` للتأكد من أن عدد الوسائط هو ما تتوقعه.

en: An easy way to test stored templates is using the ``Template tester`` dialog. For ease of access give it a keyboard shortcut in :guilabel:`Preferences->Advanced->Keyboard shortcuts->Template tester`. Giving the ``Stored templates`` dialog a shortcut will help switching more rapidly between the tester and editing the stored template's source code.
ar: طريقة سهلة لاختبار القوالب المخزنة هي استخدام مربع حوار ``اختبار القوالب``. لسهولة الوصول، امنحه اختصار لوحة مفاتيح في :guilabel:`التفضيلات->متقدم->اختصارات لوحة المفاتيح->اختبار القوالب`. إعطاء مربع حوار ``القوالب المخزنة`` اختصارًا سيساعد في التبديل بسرعة أكبر بين المختبر وتحرير الكود المصدري للقالب المخزن.

en: Providing additional information to templates
ar: توفير معلومات إضافية للقوالب

en: A developer can choose to pass additional information to the template processor, such as application-specific book metadata or information about what the processor is being asked to do. A template can access this information and use it during the evaluation.
ar: يمكن للمطور اختيار تمرير معلومات إضافية إلى معالج القوالب، مثل البيانات الوصفية الخاصة بالكتب لتطبيق معين أو معلومات حول ما يُطلب من المعالج القيام به. يمكن للقالب الوصول إلى هذه المعلومات واستخدامها أثناء التقييم.

en: **Developer: how to pass additional information**
ar: **المطور: كيفية تمرير معلومات إضافية**

en: The additional information is a Python dictionary containing pairs ``variable_name: variable_value`` where the values must be strings. The template can access the dictionary, creating template local variables named ``variable_name`` containing the value ``variable_value``. The user cannot change the name so it is best to use names that won't collide with other template local variables, for example by prefixing the name with an underscore.
ar: المعلومات الإضافية هي قاموس بايثون يحتوي على أزواج ``variable_name: variable_value`` حيث يجب أن تكون القيم سلاسل. يمكن للقالب الوصول إلى القاموس، وإنشاء متغيرات محلية للقالب تسمى ``variable_name`` تحتوي على القيمة ``variable_value``. لا يمكن للمستخدم تغيير الاسم لذا من الأفضل استخدام أسماء لن تتعارض مع متغيرات محلية أخرى للقالب، على سبيل المثال عن طريق إضافة بادئة للاسم بشرطة سفلية.

en: This dictionary is passed to the template processor (the ``formatter``) using the named parameter ``global_vars=your_dict``. The full method signature is::
ar: يتم تمرير هذا القاموس إلى معالج القوالب (``formatter``) باستخدام المعامل المسمى ``global_vars=your_dict``. توقيع الدالة الكامل هو::

en: **Template writer: how to access the additional information**
ar: **كاتب القالب: كيفية الوصول إلى المعلومات الإضافية**

en: You access the additional information (the ``globals`` dictionary) in a template using the template function::
ar: يمكنك الوصول إلى المعلومات الإضافية (قاموس ``globals``) في قالب باستخدام دالة القالب::

en: where ``id`` is any legal variable name. This function checks whether the additional information provided by the developer contains the name. If it does then the function assigns the provided value to a template local variable with that name. If the name is not in the additional information and if an ``expression`` is provided, the ``expression`` is evaluated and the result is assigned to the local variable. If neither a value nor an expression is provided, the function assigns the empty string (``''``) to the local variable.
ar: حيث ``id`` هو أي اسم متغير قانوني. تتحقق هذه الدالة مما إذا كانت المعلومات الإضافية المقدمة من المطور تحتوي على الاسم. إذا كانت تحتوي عليه، فإن الدالة تعين القيمة المقدمة لمتغير محلي للقالب بهذا الاسم. إذا لم يكن الاسم موجودًا في المعلومات الإضافية وإذا تم توفير ``expression``، يتم تقييم ``expression`` و يتم تعيين النتيجة للمتغير المحلي. إذا لم يتم توفير قيمة ولا تعبير، فإن الدالة تعين السلسلة الفارغة (``''``) لـ المتغير المحلي.

en: A template can set a value in the ``globals`` dictionary using the template function::
ar: يمكن للقالب تعيين قيمة في قاموس ``globals`` باستخدام دالة القالب::

en: This function sets the ``globals`` dictionary key:value pair ``id:value`` where ``value`` is the value of the template local variable ``id``. If that local variable doesn't exist then ``value`` is set to the result of evaluating ``expression``.
ar: تقوم هذه الدالة بتعيين زوج المفتاح:القيمة ``id:value`` في قاموس ``globals`` حيث ``value`` هي قيمة المتغير المحلي للقالب ``id``. إذا لم يكن هذا المتغير المحلي موجودًا، فسيتم تعيين ``value`` إلى نتيجة تقييم ``expression``.

en: Notes on the difference between modes
ar: ملاحظات حول الفرق بين الأوضاع

en: The three program modes, :ref:`Single Function Mode <single_mode>` (SFM), :ref:`Template Program Mode <template_mode>` (`TPM`), and :ref:`General Program Mode <general_mode>` (`GPM`), work differently. SFM is intended to be 'simple' so it hides a lot of programming language bits.
ar: تعمل أوضاع البرمجة الثلاثة، :ref:`وضع الدالة الواحدة <single_mode>` (SFM)، :ref:`وضع برنامج القالب <template_mode>` (`TPM`)، و :ref:`وضع البرنامج العام <general_mode>` (`GPM`)، بشكل مختلف. يهدف SFM إلى أن يكون 'بسيطًا' لذا فإنه يخفي الكثير من أجزاء لغة البرمجة.

en: Differences:
ar: الفروقات:

en: In SFM the value of the column is always passed as an 'invisible' first argument to a function included in the template.
ar: في SFM، يتم دائمًا تمرير قيمة العمود كوسيط أول 'غير مرئي' لدالة مضمنة في القالب.

en: SFM doesn't support the difference between variables and strings; all values are strings.
ar: لا يدعم SFM الفرق بين المتغيرات والسلاسل؛ جميع القيم هي سلاسل.

en: The following SFM template returns either the series name or the string "no series"::
ar: يعيد قالب SFM التالي إما اسم السلسلة أو السلسلة النصية "لا توجد سلسلة"::

en: The equivalent template in `TPM` is ::
ar: القالب المكافئ في `TPM` هو::

en: The equivalent template in `GPM` is::
ar: القالب المكافئ في `GPM` هو::

en: The first argument to ``ifempty`` is the value of the field ``series``. The second argument is the string ``no series``. In SFM the first argument, the value of the field, is automatically passed (the invisible argument).
ar: الوسيط الأول لدالة ``ifempty`` هو قيمة الحقل ``series``. الوسيط الثاني هو السلسلة النصية ``no series``. في SFM، يتم تمرير الوسيط الأول، وهو قيمة الحقل، تلقائيًا (الوسيط غير المرئي).

en: Several template functions, for example ``booksize()`` and ``current_library_name()``, take no arguments. Because of the 'invisible argument' you cannot use these functions in SFM.
ar: العديد من دوال القوالب، على سبيل المثال ``booksize()`` و ``current_library_name()``، لا تأخذ أي وسائط. بسبب 'الوسيط غير المرئي'، لا يمكنك استخدام هذه الدوال في SFM.

en: Nested functions, where a function calls another function to compute an argument, cannot be used in SFM. For example this template, intended to return the first 5 characters of the series value uppercased, won't work in SFM::
ar: لا يمكن استخدام الدوال المتداخلة، حيث تستدعي دالة دالة أخرى لحساب وسيط، في SFM. على سبيل المثال، هذا القالب، الذي يهدف إلى إرجاع أول 5 أحرف من قيمة السلسلة بأحرف كبيرة، لن يعمل في SFM::

en: `TPM` and `GPM` support nested functions. The above template in `TPM` would be::
ar: يدعم `TPM` و `GPM` الدوال المتداخلة. القالب أعلاه في `TPM` سيكون::

en: In `GPM` it would be::
ar: في `GPM` سيكون::

en: As noted in the above :ref:`Template Program Mode <template_mode>` section, using ``{`` and ``}`` characters in `TPM` string literals can lead to errors or unexpected results because they confuse the template processor. It tries to treat them as template boundaries, not characters. In some but not all cases you can replace a ``{`` with ``[[`` and a ``}`` with `]]`. Generally, if your program contains ``{`` and ``}`` characters then you should use `General Program Mode`.
ar: كما هو مذكور في قسم :ref:`وضع برنامج القالب <template_mode>` أعلاه، يمكن أن يؤدي استخدام الأحرف ``{`` و ``}`` في سلاسل `TPM` الحرفية إلى أخطاء أو نتائج غير متوقعة لأنها تربك معالج القوالب. فهو يحاول التعامل معها كحدود للقالب، وليس كأحرف. في بعض الحالات وليس كلها، يمكنك استبدال ``{`` بـ ``[[`` و ``}`` بـ ``]]``. بشكل عام، إذا كان برنامجك يحتوي على أحرف ``{`` و ``}``، فيجب عليك استخدام `وضع البرنامج العام`.

en: User-defined Python template functions
ar: دوال قالب بايثون المعرفة من قبل المستخدم

en: You can add your own Python functions to the template processor. Such functions can be used in any of the three template programming modes. The functions are added by going to :guilabel:`Preferences -> Advanced -> Template functions`. Instructions are shown in that dialog. Note that you can use `Python Templates` for a similar purpose. As calling user-defined functions is faster than calling a Python template, user-defined functions might be more efficient depending on the complexity of what the function or template does.
ar: يمكنك إضافة دوال بايثون الخاصة بك إلى معالج القوالب. يمكن استخدام هذه الدوال في أي من أوضاع برمجة القوالب الثلاثة. يتم إضافة الدوال بالانتقال إلى :guilabel:`التفضيلات -> متقدم -> دوال القوالب`. تظهر التعليمات في هذا الحوار. لاحظ أنه يمكنك استخدام `قوالب بايثون` لغرض مماثل. نظرًا لأن استدعاء الدوال المعرفة من قبل المستخدم أسرع من استدعاء قالب بايثون، فقد تكون الدوال المعرفة من قبل المستخدم أكثر كفاءة اعتمادًا على تعقيد ما تفعله الدالة أو القالب.

en: Special notes for using templates in different contexts
ar: ملاحظات خاصة لاستخدام القوالب في سياقات مختلفة

en: In the GUI (:guilabel:`Columns made from other columns` and :guilabel:`Template searches`):
ar: في واجهة المستخدم الرسومية (:guilabel:`الأعمدة المصنوعة من أعمدة أخرى` و :guilabel:`عمليات البحث بالقالب`):

en: GPM templates work as before.
ar: تعمل قوالب GPM كما كانت من قبل.

en: Python templates have full access to the calibre database.
ar: تتمتع قوالب بايثون بوصول كامل إلى قاعدة بيانات calibre.

en: In icon rules:
ar: في قواعد الأيقونات:

en: icon rule templates have no book data so field-based functions such as :ref:`ff_format_date_field`, :ref:`ff_list_count_field`, and :ref:`ff_check_yes_no` won't work.
ar: لا تحتوي قوالب قواعد الأيقونات على بيانات كتاب، لذا فإن الدوال المستندة إلى الحقول مثل :ref:`ff_format_date_field`، :ref:`ff_list_count_field`، و :ref:`ff_check_yes_no` لن تعمل.

en: In the Content server:
ar: في خادم المحتوى:

en: Templates have access to the new API but not the old API (LibraryDatabase).
ar: تتمتع القوالب بالوصول إلى واجهة برمجة التطبيقات الجديدة ولكن ليس إلى واجهة برمجة التطبيقات القديمة (LibraryDatabase).

en: Because of the above, the following formatter functions are not guaranteed to work in GPM templates (composite columns, icon rules, etc) and should be avoided if you use the content server:
ar: بسبب ما سبق، لا يُضمن عمل دوال التنسيق التالية في قوالب GPM (الأعمدة المركبة، قواعد الأيقونات، إلخ) ويجب تجنبها إذا كنت تستخدم خادم المحتوى:

en: Special notes for save/send templates
ar: ملاحظات خاصة لقوالب الحفظ/الإرسال

en: Special processing is applied when a template is used in a :guilabel:`Save to disk` or :guilabel:`Send to device` template. The values of the fields are cleaned, replacing characters that are special to file systems with underscores, including slashes. This means that field text cannot be used to create folders. However, slashes are not changed in prefix or suffix strings, so slashes in these strings will cause folders to be created. Because of this, you can create variable-depth folder structure.
ar: يتم تطبيق معالجة خاصة عند استخدام قالب في قالب :guilabel:`حفظ إلى القرص` أو :guilabel:`إرسال إلى الجهاز`. يتم تنظيف قيم الحقول، واستبدال الأحرف الخاصة بأنظمة الملفات بشرطات سفلية، بما في ذلك الشرطات المائلة. هذا يعني أنه لا يمكن استخدام نص الحقل لإنشاء مجلدات. ومع ذلك، لا تتغير الشرطات المائلة في سلاسل البادئة أو اللاحقة، لذا ستؤدي الشرطات المائلة في هذه السلاسل إلى إنشاء مجلدات. بسبب هذا، يمكنك إنشاء هيكل مجلدات بعمق متغير.

en: For example, assume we want the folder structure `series/series_index - title`, with the caveat that if series does not exist, then the title should be in the top folder. The template to do this is::
ar: على سبيل المثال، افترض أننا نريد هيكل المجلد `سلسلة/فهرس_السلسلة - عنوان`، مع ملاحظة أنه إذا لم تكن السلسلة موجودة، فيجب أن يكون العنوان في المجلد العلوي. القالب للقيام بذلك هو::

en: The slash and the hyphen appear only if series is not empty.
ar: تظهر الشرطة المائلة والواصلة فقط إذا لم تكن السلسلة فارغة.

en: The lookup function lets us do even fancier processing. For example, assume that if a book has a series, then we want the folder structure `series/series index - title.fmt`. If the book does not have a series then we want the folder structure `genre/author_sort/title.fmt`. If the book has no genre then we want to use 'Unknown'. We want two completely different paths, depending on the value of series.
ar: تتيح لنا دالة البحث القيام بمعالجة أكثر تعقيدًا. على سبيل المثال، افترض أنه إذا كان الكتاب يحتوي على سلسلة، فإننا نريد هيكل المجلد `سلسلة/فهرس السلسلة - عنوان.fmt`. إذا لم يكن للكتاب سلسلة، فإننا نريد هيكل المجلد `نوع/ترتيب_المؤلف/عنوان.fmt`. إذا لم يكن للكتاب نوع، فإننا نريد استخدام 'غير معروف'. نريد مسارين مختلفين تمامًا، اعتمادًا على قيمة السلسلة.

en: To accomplish this, we:
ar: لتحقيق ذلك، نقوم بـ:

en: Create a composite field (give it lookup name #aa) containing ``{series}/{series_index} - {title}``. If the series is not empty, then this template will produce `series/series_index - title`.
ar: إنشاء حقل مركب (إعطائه اسم بحث #aa) يحتوي على ``{series}/{series_index} - {title}``. إذا لم تكن السلسلة فارغة، فإن هذا القالب سينتج `سلسلة/فهرس_السلسلة - عنوان`.

en: Create a composite field (give it lookup name #bb) containing ``{#genre:ifempty(Unknown)}/{author_sort}/{title}``. This template produces `genre/author_sort/title`, where an empty genre is replaced with `Unknown`.
ar: إنشاء حقل مركب (إعطائه اسم بحث #bb) يحتوي على ``{#genre:ifempty(Unknown)}/{author_sort}/{title}``. ينتج هذا القالب `نوع/ترتيب_المؤلف/عنوان`، حيث يتم استبدال النوع الفارغ بـ `غير معروف`.

en: Set the save template to ``{series:lookup(.,#aa,#bb)}``. This template chooses composite field ``#aa`` if series is not empty and composite field ``#bb`` if series is empty. We therefore have two completely different save paths, depending on whether or not `series` is empty.
ar: تعيين قالب الحفظ إلى ``{series:lookup(.,#aa,#bb)}``. يختار هذا القالب الحقل المركب ``#aa`` إذا لم تكن السلسلة فارغة، والحقل المركب ``#bb`` إذا كانت السلسلة فارغة. لذلك لدينا مساران حفظ مختلفان تمامًا، اعتمادًا على ما إذا كانت `السلسلة` فارغة أم لا.

en: Tips
ar: نصائح

en: Use the Template Tester to test templates. Add the tester to the context menu for books in the library and/or give it a keyboard shortcut.
ar: استخدم "اختبار القوالب" لاختبار القوالب. أضف المختبر إلى قائمة السياق للكتب في المكتبة و/أو امنحه اختصار لوحة مفاتيح.

en: Templates can use other templates by referencing composite columns built with the desired template. Alternatively, you can use Stored Templates.
ar: يمكن للقوالب استخدام قوالب أخرى عن طريق الإشارة إلى أعمدة مركبة تم إنشاؤها باستخدام القالب المطلوب. بدلاً من ذلك، يمكنك استخدام القوالب المخزنة.

en: In a plugboard, you can set a field to empty (or whatever is equivalent to empty) by using the special template ``{}``. This template will always evaluate to an empty string.
ar: في لوحة التوصيل، يمكنك تعيين حقل إلى فارغ (أو ما يعادله) باستخدام القالب الخاص ``{}``. سيُقيّم هذا القالب دائمًا إلى سلسلة فارغة.

en: The technique described above to show numbers even if they have a zero value works with the standard field series_index.
ar: التقنية الموصوفة أعلاه لعرض الأرقام حتى لو كانت قيمتها صفرًا تعمل مع حقل series_index القياسي.

en: Template function reference
ar: مرجع دالة القالب
