tput(1)

الاسم
tput - يشرع طرفية، أو يختبر قدراتها، أو يستعلم من قاعدة بيانات terminfo

موجز
tput [-v] [-T terminal-type] {cap-code [parameter ...]} ...

tput [-v] [-T terminal-type] [-x] clear

tput [-v] [-T terminal-type] init

tput [-v] [-T terminal-type] reset

tput [-v] [-T terminal-type] longname

tput [-v] -S

tput [-v] -V

الوصف
يستخدم tput مكتبة وقاعدة بيانات terminfo لجعل القدرات والمعلومات الخاصة بالطرفية متاحة لـ الصدفة، أو لتشريع الطرفية أو إعادة ضبطها، أو للإبلاغ عن وصف لنوع الطرفية الحالية (أو المحددة). تُوصَل قدرات الطرفية عبر cap-code.

يناقش terminfo(5) قدرات الطرفية باستفاضة ويعرض قائمة كاملة بـ cap-codes المعيارية. ويعرض user_caps(5) قدرات أخرى واسعة الاستخدام لكنها غير معيارية.

عند استرجاع قيم القدرات، تعتمد النتيجة على نوع القدرة.

منطقي
    يضبط tput حالة خروجه إلى 0 إذا كانت الطرفية تملك cap-code، وإلى 1 إذا كانت لا تملكه.

numeric
    يكتب tput القيمة العشرية لـ cap-code في مجرى الخرج القياسي إذا كانت معرفة (و -1 إذا لم تكن) متبوعة بسطر جديد.

سلسلة نصية
    يكتب tput قيمة cap-code في مجرى الخرج القياسي إذا كانت معرفة، دون سطر جديد في النهاية.

قبل استخدام القيمة المعادة في الخرج القياسي، ينبغي للتطبيق اختبار حالة خروج tput للتأكد من أنها 0؛ انظر قسم “حالة الخروج” أدناه.

  المعاملات
عمومًا، المعامل هو cap-code، وهو رمز قدرة من قاعدة بيانات الطرفية، أو معامل لها. يتعرف tput بشكل خاص على ثلاثة معاملات أخرى: init، و reset، و longname. رغم أنها تشبه رموز القدرات، إلا أنها في الواقع تُعامل معاملة خاصة؛ ونسميها “أشباه القدرات”.

cap-code
    يشير إلى قدرة من قاعدة بيانات الطرفية.

    إذا كان cap-code من نوع سلسلة نصية ويأخذ معاملات، يفسر tput الوسائط التي تلي cap-code كمعاملات، حتى العدد (الثابت) الذي تطلبه القدرة.

    معظم المعاملات عددية. لا تتطلب سوى قليل من قدرات الطرفية معاملات نصية؛ يستخدم tput جدولاً لتقرير أيها يمرر كنصوص. عادةً ما يستخدم tput الدالة tparm(3NCURSES) لإجراء الاستبدال. إذا لم تُعطَ أي معاملات للقدرة، يكتب tput النص دون إجراء الاستبدال.

init
    يشرع الطرفية. إذا كانت قاعدة بيانات الطرفية موجودة وكان هناك مدخل لنوع طرفية المستخدم، يحدث الآتي.

    (1) يسترجع tput إعدادات وضع الطرفية. ويختبر بالتتابع واصفات الملفات المقابلة لـ
        مجرى الخطأ القياسي، مجرى الخرج القياسي، مجرى الدخل القياسي، و /dev/tty

        للحصول على إعدادات الطرفية. وبعد استرجاعها، يتذكر tput أي واصف سيستخدم للتحديثات اللاحقة.

    (2) إذا لم يمكن الحصول على أبعاد الطرفية من نظام التشغيل، ولكن البيئة أو مدخل قاعدة بيانات نوع الطرفية يصفانها، يحدّث tput تصور نظام التشغيل عنها.

    (3) يحدّث tput أوضاع الطرفية.
        يُشغل تمديد علامات الجدولة أو يوقف حسب المواصفات في المدخل، و إذا لم تمدد علامات الجدولة، تُضبط علامات الجدولة القياسية (كل 8 مسافات).

    (4) إذا كانت قدرات التشريع، المفصلة في القسم الفرعي “علامات الجدولة والتشريع” من terminfo(5)، موجودة، يكتبها tput في مجرى الخرج القياسي.

    (5) يفرغ tput مجرى الخرج القياسي.

    إذا افتقر مدخل ما إلى المعلومات اللازمة لنشاط مما سبق، يُتخطى هذا النشاط صمتًا.

reset
    يُعيد تشريع الطرفية. تختلف إعادة الضبط عن التشريع بطريقتين.

    (1) يضبط tput أوضاع الطرفية إلى حالة “سليمة”،
        مُفعلاً الوضع المعياري (“cooked”) ووضع الصدى (echo)، ومعطلاً وضعي cbreak و raw، ومفعلاً ترجمة السطر الجديد، و وضابطاً أي محارف دخل خاصة إلى قيمها المبدئية.

    (2) إذا عُرفت أي قدرات إعادة ضبط لنوع الطرفية، يكتبها tput في مجرى الخرج. وإلا، يستخدم tput أي قدرات تشريع معرفة. تُفصل قدرات إعادة الضبط في القسم الفرعي “علامات الجدولة والتشريع” من terminfo(5).

longname
    يبدأ مدخل terminfo باسم واحد أو أكثر يمكن للتطبيق عبرها الإشارة إلى المدخل، قبل قائمة قدرات الطرفية. تُفصل الأسماء بمحارف “|”. يطلق X/Open Curses على الاسم الأخير اسم “الاسم الطويل”، ويشير إلى أنه قد يتضمن فراغات.

    يُحذر tic إذا لم يتضمن الاسم الأخير فراغات، لاستيعاب مدخلات terminfo القديمة التي كانت تعامل الاسم الطويل كميزة اختيارية. غالبًا ما يُشار إلى الاسم الطويل كحقل الوصف.

    إذا كانت قاعدة بيانات الطرفية موجودة وكان هناك مدخل لنوع طرفية المستخدم، يُبلغ tput عن وصفه في مجرى الخرج القياسي، دون سطر جديد في النهاية. انظر terminfo(5).

ملاحظة: إعادة توجيه خرج “tput init” أو “tput reset” إلى ملف ستلتقط جزءًا فقط من أفعالهما. لا تتأثر التغييرات في أوضاع الطرفية بإعادة توجيه واصف الملف، بما أن أوضاع الطرفية تُعدل عبر ioctl(2).

  الأسماء المستعارة
إذا استُدعي tput عبر وصلة بأي من الأسماء clear، أو init، أو reset، فإنه يعمل كما لو شُغل بمعامل (شبه) القدرة المقابل. على سبيل المثال، تنفيذ وصلة باسم reset تشير إلى tput له نفس تأثير “tput reset”.

قُدمت هذه الميزة في ncurses 5.2 عام 2000. وهي نادرة الاستخدام.

clear
    هو برنامج منفصل، وهو أصغر حجماً وأكثر تنفيذاً.

init
    له نفس اسم برنامج آخر واسع الانتشار.

reset
    توفرها أداة tset(1) (أيضًا عبر وصلة تسمى reset).

  حجم الطرفية
بالإضافة إلى القدرات الزائفة (مثل init)، يعامل tput cap-codes الخاصة بـ lines و cols معاملة خاصة: فقد يستدعي setupterm(3NCURSES) للحصول على حجم الطرفية. أولاً، يحاول tput الحصول على هذه القدرات من قاعدة بيانات الطرفية. يفشل هذا عادةً في محاكيات الطرفية، التي تفتقر إلى حجم نافذة ثابت وبالتالي تغفل هذه القدرات. ثم يسأل نظام التشغيل عن حجم الطرفية، وهو ما ينجح عادةً، ما لم يكن الاتصال عبر خط تسلسلي لا يدعم “NAWS”: المفاوضات حول حجم النافذة. أخيرًا، يفحص متغيرات البيئة LINES و COLUMNS، والتي قد تتخطى حجم الطرفية.

إذا أعطي الخيار -T، يتجاهل tput متغيرات البيئة عبر استدعاء use_tioctl(TRUE)، معتمداً على نظام التشغيل (أو في النهاية، قاعدة بيانات الطرفية).

الخيارات

-S  يسترجع أكثر من قدرة في كل استدعاء لـ tput. يجب تمرير القدرات إلى tput من مجرى الدخل القياسي بدلاً من سطر الأوامر (انظر قسم “أمثلة” أدناه). يُسمح بـ cap-code واحد فقط لكل سطر. يغير الخيار -S معاني حالتي الخروج 0 و 1 (انظر قسم “حالة الخروج” أدناه).

    تستخدم بعض القدرات معاملات نصية بدلاً من العددية. يوظف tput جدولاً مدمجاً ووجود المعاملات في مدخلاته لتقرير كيفية تفسيرها، وما إذا كان سيستخدم tparm(3NCURSES).

-T type
    يشير إلى type (نوع) الطرفية. عادةً ما يكون هذا الخيار غير ضروري، لأن القيمة المبدئية تؤخذ من متغير البيئة TERM. وإذا حُدد، تُتجاهل أيضًا متغيرات البيئة LINES و COLUMNS.

-v  يجعل tput يعمل بإسهاب، مبلغاً عن التحذيرات.

-V  يبلغ عن إصدار ncurses المرتبط بـ tput، ويخرج بحالة نجاح.

-x  يمنع “tput clear” من محاولة مسح ذاكرة التمرير الخلفي.

حالة الخروج
عادةً، ينبغي تفسير حالات خروج tput كما يلي.

الحالة | المعنى عند عدم تحديد -S
0 | قدرة منطقية أو نصية موجودة
1 | قدرة منطقية أو عددية غائبة
2 | خطأ في الاستخدام أو لم يُحدّد نوع الطرفية
3 | نوع طرفية غير معروف
4 | رمز قدرة غير معروف
>4 | خطأ في النظام (4 + errno)

تتغير معاني بعض الحالات عند استخدام الخيار -S.

الحالة | المعنى عند تحديد -S
0 | فُسِّرت جميع المعاملات
1 | unused
4 | لم تُفسَّر بعض المعاملات

البيئة
يقرأ tput ما يصل إلى ثلاثة متغيرات بيئة إذا لم يُحدّد الخيار -T.

COLUMNS
    يحدد عرض الشاشة بالأحرف.

LINES
    يحدد ارتفاع الشاشة بالأحرف.

TERM
    يشير إلى نوع الطرفية. كل نوع طرفية متميز عن غيره، رغم تشابه الكثير منها.

الملفات

/usr/share/tabset
    قاعدة بيانات تهيئة علامات الجدولة

/etc/terminfo
    قاعدة بيانات أوصاف الطرفية المجمّعة

القابلية للنقل
بمرور الوقت، اختلف tput الخاص بـ ncurses عن ذلك الخاص بـ System V في جانبين مهمين، أحدهما أصبح تاريخيًا الآن. “tput cap-code” يكتب إلى المخرجات القياسية، والتي لا يُشترط أن تكون جهاز طرفية. ومع ذلك، فإن المعاملات التي تتحكم في أوضاع الطرفية قد لا تستخدم المخرجات القياسية.

    تستخدم معاملات init و reset في tput الخاص بـ System V منطق tset من 4.1cBSD، للتحكم في أوضاع الطرفية. حيث يتحقق من نفس واصفات الملفات (و /dev/tty) للارتباط بجهاز طرفية كما يفعل ncurses الآن، وإذا لم يوجد أي منها، يفترض في النهاية وجود طرفية بسرعة 1200 باود. وعند تحديث أوضاع الطرفية، فإنه يتجاهل الأخطاء.

    حتى ncurses 6.1 (راجع قسم “التاريخ” أدناه)، لم يكن tput يعدل أوضاع الطرفية. أما الآن فيستخدم آلية مشابهة لـ System V، باستخدام وظائف مشتركة مع tset (ومبنية في الأصل على tset الخاص بـ 4.4BSD). إذا لم يتمكن من فتح طرفية (على سبيل المثال، عند تشغيله بواسطة cron(1))، فإن tput يخرج بحالة خطأ. يفترض tput الخاص بـ System V أن نوع معامل cap-code عددي إذا كانت جميع أحرف قيمته أرقامًا عشرية؛ وإذا لم تكن كذلك، فإنه يعامل cap-code كقدرة نصية (سلسلة).

    تستخدم معظم التنفيدات التي توفر دعماً لمعاملات cap-code الدالة tparm(3NCURSES) لتوسيع معاملاتها. تتوقع تلك الدالة خليطاً من المعاملات العددية والنصية، مما يتطلب من tput معرفة أي نوع يجب استخدامه.

    يستخدم tput في ncurses جدولاً لتحديد أنواع المعلمات لمعاملات cap-code القياسية، ووظيفة داخلية لتحليل معاملات cap-code غير القياسية.

    رغم كونه أكثر موثوقية من أداة System V، إلا أن هذا التحليل يتسبب في مشكلة في القابلية للنقل. فقد اقتبس مطور OpenBSD الوظيفة المكتبية الداخلية من ncurses لنقل tput المبني على termcap الخاص بـ NetBSD إلى terminfo، وعدله ليفسر رموز قدرات (cap-codes) ومعلمات متعددة في سطر الأوامر. يجب ألا تعتمد التطبيقات القابلة للنقل على هذه الميزة؛ إذ يوفرها ncurses لدعم التطبيقات المكتوبة خصيصًا لـ OpenBSD.

يقبل تطبيق ncurses لـ tput، على عكس غيره، كلاً من رموز termcap و terminfo إذا كان دعم termcap مجمّعًا داخله. ومع ذلك، في هذه الحالة، يوجد لبس في رمزين بين termcap و terminfo؛ حيث يفترض ncurses أنه رمز terminfo. يعني رمز القدرة dl القدرة delete_line في termcap ولكن يعني parm_delete_line في terminfo. يستخدم termcap الرمز DL للقدرة parm_delete_line. بينما يستخدم terminfo الرمز dl1 للقدرة delete_line. يعني رمز القدرة ed القدرة exit_delete_mode في termcap ولكن يعني clr_eos في terminfo. يستخدم termcap الرمز cd للقدرة clr_eos. بينما يستخدم terminfo الرمز rmdc للقدرة exit_delete_mode.

لم تكن المعاملات longname، والخيار -S، وميزات استبدال المعلمات المستخدمة في مثال cup أدناه مدعومة في AT&T/USL curses قبل إصدار SVr4 (1989). لاحقًا، أضاف إصدار 4.3BSD-Reno (1990) دعمًا لـ longname، وفي عام 1994، أضاف NetBSD دعمًا لميزات استبدال المعلمات.

تُوثّق مواصفات IEEE Std 1003.1/The Open Group Base Specifications Issue 7 (POSIX.1-2008) المعاملات clear و init و reset فقط. وتبرز بعض الملاحظات المثيرة للاهتمام من هذا الاختيار. يدعم ncurses المعامل clear كما يفعل مع أي رمز قدرة قياسي آخر. أما الآخران (init و longname) فلا يقابلان أي قدرات طرفية. يدعم tput في الأنظمة المبنية على SVr4 مثل Solaris و IRIX64 و HP-UX، بالإضافة إلى أنظمة أخرى مثل AIX و Tru64، معاملات رموز القدرات القياسية أيضًا. تتعرف بعض المنصات مثل FreeBSD على رموز termcap بدلاً من رموز قدرات terminfo في أوامر tput الخاصة بها. ومنذ عام 2010، أصبح tput في NetBSD يستخدم رموز terminfo. قبل ذلك، كان (مثل FreeBSD) يتعرف على رموز termcap.

    بدءًا من عام 2021، أصبح FreeBSD يستخدم tput الخاص بـ ncurses، المهيأ لكل من terminfo (يُختبر أولاً) و termcap (كخيار احتياطي).

بما أن جميع أنظمة يونكس المعتمدة (على ما يبدو) تدعم المجموعة الكاملة لرموز القدرات، فقد لا يكون سبب توثيق القليل منها فقط واضحًا. تُوثّق مواصفات X/Open Curses Issue 7 الأداة tput بشكل مختلف، مع تضمين cap-code والميزات الأخرى المستخدمة في هذا التطبيق. بمعنى آخر، هناك معياران لـ tput: معيار POSIX (مجموعة جزئية) ومعيار X/Open Curses (التطبيق الكامل). يوثق POSIX مجموعة جزئية لتجنب تعقيد تضمين X/Open Curses وقاعدة بيانات قدرات الطرفية. رغم أنه من الممكن بالتأكيد كتابة برنامج tput دون استخدام curses، إلا أنه لا يوجد نظام يحتوي على تطبيق curses يوفر أداة tput لا تدعم أيضًا رموز القدرات (cap-codes) القياسية.

يعد إصدار X/Open Curses Issue 7 (2009) هو النسخة الأولى التي توثق الأدوات. ومع ذلك، فإن هذا الجزء من X/Open Curses لا يتبع الممارسة الحالية (أي سلوك curses في System V). إنه يعين حالة الخروج 4 لـ “معامل غير صالح”، والتي قد يكون لها نفس معنى “قدرة مجهولة”. على سبيل المثال، يستخدم الكود المصدري لـ Solaris xcurses مصطلح “غير صالح” في هذه الحالة. إنه يعين حالة الخروج 255 لمتغير عددي غير محدد في قاعدة بيانات terminfo. ومن المرجح أن يكون هذا خطأ في التوثيق، حيث خُلِطَ بين القيمة “-1” التي تُكتب في المخرجات القياسية للإشارة إلى قدرة عددية غائبة أو ملغاة وحالة الخروج (غير الموقعة).

تستخدم تطبيقات System V المختلفة (AIX، HP-UX، Solaris) نفس حالات الخروج التي يستخدمها ncurses.

يوثق NetBSD curses حالات خروج لا تتوافق مع ncurses ولا مع X/Open Curses.

التاريخ
كتب بيل جوي أمر tput أثناء تطوير 4BSD في أكتوبر 1980. كانت هذه النسخة الأولية تمسح الشاشة فقط، ولم تُطرح مع التوزيعات الرسمية.

طور System V أمر tput مختلفًا. وفر الإصدار SVr2 (1984) أداة tput بدائية تتحقق من المعامل مقابل كل اسم قدرة وتعيد القيمة المقابلة. لم يستخدم هذا الإصدار من tput الدالة tparm(3NCURSES) للقدرات ذات المعاملات. استبدل SVr3 (1987) ذلك ببرنامج أكثر شمولاً، حيث دمج دعمه لمعاملات init و reset (أكثر من نصف البرنامج) ميزة reset الخاصة بـ tset في BSD التي كتبها إريك ألمان. أضاف SVr4 (1989) تهيئة الألوان باستخدام قدرات orig_colors (oc) و orig_pair (op) في منطق init الخاص به.

أعاد كيث بوستيك هيكلة tput في BSD لإصداره في 4.3BSD-Reno (1990)، مما جعله يتبع واجهة tput في System V من خلال قبول بعض المعلمات المسماة بأسماء قدرات (زائفة) لـ terminfo هي: clear، و init، و longname، و reset. ومع ذلك، ونظرًا لأن المتاح لديه كان termcap فقط، فقد قَبِل رموز termcap للقدرات الأخرى. كما أن tput الخاص بـ BSD الذي عدله بوستيك لم يعدل أوضاع الطرفية كما كان يفعل tset السابق في BSD. وفي الوقت نفسه، أضاف بوستيك سكربت صدفة يسمى “clear” يستخدم tput لمسح الشاشة. وأصبحت هذه هي النسخة “الحديثة' لـ tput في BSD.

يكمن أصل tput في ncurses خارج كل من System V و BSD، في حزمة mytinfo لروس ريدج، والتي نُشرت في comp.sources.unix في ديسمبر 1992. استخدم برنامج ريدج قدرات الطرفية بشكل أكثر تطورًا من برنامج BSD. استخدم إريك رايموند برنامج tput ذاك (وأجزاء أخرى من mytinfo) في ncurses في يونيو 1995. ومع دمجه للأجزاء المتعلقة بقدرات الطرفية دون تغيير تقريبًا، إلا أن رايموند أدخل تحسينات على طريقة التعامل مع معلمات سطر الأوامر.

قبل إصدار ncurses 6.1 (2018)، كانت أداتا tset و tput مختلفتين. كانت أداة tset أكثر فعالية في إعادة ضبط أوضاع الطرفية وأحرف الإدخال الخاصة. من ناحية أخرى، كانت مجموعة قدرات الطرفية في tset لإعادة ضبط الطرفية أكثر محدودية؛ حيث كانت تمتلك فقط ما يعادل reset_1string (rs1) و reset_2string (rs2) و reset_file (rf)، ولم تمتلك ميزات تحديث علامات الجدولة والهوامش الموجودة في tput.

يعد برنامج reset تقليديًا اسمًا مستعارًا لـ tset نظرًا لقدرته على إعادة ضبط أوضاع الطرفية وأحرف الإدخال الخاصة.

اعتبارًا من ncurses 6.1، أصبحت ميزات “إعادة الضبط' في البرنامجين هي نفسها (غالبًا). ويتبقى اختلافان طفيفان. عند إجراء إعادة ضبط، يتحقق برنامج tset مما إذا كان الجهاز يبدو كطرفية وهمية (مثل تلك التي يستخدمها برنامج محاكي طرفية)، وإذا لم يكن كذلك، فإنه ينتظر ثانية واحدة تحسبًا لكونه يتواصل مع طرفية مادية (عتاد). يكتب البرنامجان سلاسل تهيئة الطرفية إلى تدفقات مختلفة؛ وهي: الخطأ القياسي لـ tset والمخرجات القياسية لـ tput.

أمثلة

tput init
    تهيئ الطرفية وفقًا لنوع الطرفية في متغير البيئة TERM. إذا كان النظام لا يهيئ الطرفية بشكل موثوق عند تسجيل الدخول، فيمكن تضمين هذا الأمر في $HOME/.profile بعد تصدير متغير البيئة TERM.

tput -T5620 reset
    تُعيد ضبط طرفية AT&T 5620، متجاوزة نوع الطرفية في متغير البيئة TERM.

tput cnorm
    تضبط المؤشر على الرؤية العادية.

tput home
    تنقل المؤشر إلى السطر 0، العمود 0: الركن الأيسر العلوي من الشاشة، والمعروف عادةً باسم موضع المؤشر “الرئيس' (home).

tput clear
    تمسح الشاشة: تكتب قيمة قدرة clear_screen إلى تدفق المخرجات القياسية.

tput cols
    تُبلغ عن عدد الأعمدة التي يستخدمها نوع الطرفية الحالي.

tput -Tadm3a cols
    تُبلغ عن عدد الأعمدة التي تستخدمها طرفية ADM-3A.

strong=`tput smso` normal=`tput rmso`
    تضبط متغيرات الصدفة على قيم القدرات: strong و normal، لبدء وإنهاء وضع البروز (stand-out) للطرفية، على التوالي. يمكن استخدام هذه المتغيرات لعرض محث الأوامر.

        printf "${strong}Username:${normal} "

tput hc
    تشير عبر حالة الخروج عما إذا كانت الطرفية جهاز نسخ مطبوع (hard copy).

tput cup 23 4
    تنقل المؤشر إلى السطر 23، العمود 4.

tput cup
    تُبلغ عن قيمة قدرة cursor_address (cup) (المستخدمة لتحريك المؤشر)، دون استبدال أي معلمات.

tput longname
    تُبلغ عن وصف قاعدة بيانات terminfo لنوع الطرفية المحدد في متغير البيئة TERM.

tput -S
    تعالج قدرات متعددة. يمكن استخدام الخيار -S بشكل مفيد مع “مستند هنا' (here document) في الصدفة.

        $ tput -S <<!
        > clear
        > cup 10 10
        > bold
        > !

    ما سبق يمسح الشاشة، وينقل المؤشر إلى الموضع (10, 10) ويفعل الوضع العريض (سطوع إضافي).

tput clear cup 10 10 bold
    تؤدي نفس الإجراءات المذكورة في مثال “tput -S” السابق.

انظر أيضًا
clear(1)،‏ stty(1)،‏ tabs(1)،‏ tset(1)،‏ termcap(3NCURSES)،‏ terminfo(5)،‏ user_caps(5)

ترجمة
تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي <zayed.alsaidi@gmail.com>

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: kde-l10n-ar@kde.org.