GETOPT(1)

الاسم
getopt - تحليل خيارات الأوامر (محسن)

موجز

getopt اسم_الخيار ‎معاملات

getopt [خيارات] [--] اسم_الخيار ‎معاملات

getopt [خيارات] -o|--options ‎اسم_الخيار [‎خيارات] [--] ‎معاملات

الوصف

يُستخدم getopt لتفكيك (تحليل) الخيارات في أسطر الأوامر لتسهيل تحليلها بواسطة إجراءات الصدفة، وللتحقق من صحة الخيارات. ويستخدم روتين GNU getopt(3) للقيام بذلك.

المعاملات التي يُستدعى بها getopt يمكن تقسيمها إلى جزأين: خيارات تعدل الطريقة التي سيقوم بها getopt بالتحليل (options و اسم_الخيار في قسم موجز الاستخدام )، والمعاملات التي سيجري تحليلها (معاملات في قسم موجز الاستخدام). يبدأ الجزء الثاني عند أول معامل ليس خياراً ولا وسيطاً لخيار، أو بعد أول ظهور للرمز '--'. إذا لم يوجد خيار '-o' أو '--options' في الجزء الأول، يُستخدم المعامل الأول من الجزء الثاني كسلسلة خيارات قصيرة.

إذا ضُبط متغير البيئة GETOPT_COMPATIBLE، أو إذا كان المعامل الأول ليس خياراً (لا يبدأ بـ '-'، وهو التنسيق الأول في موجز الاستخدام)، فسيولد getopt مخرجات متوافقة مع إصدارات getopt(1) الأخرى. وسيقوم رغم ذلك بتبديل ترتيب المعاملات والتعرف على الوسائط الاختيارية (انظر قسم التوافقية لمزيد من المعلومات).

إن التطبيقات التقليدية لـ getopt(1) غير قادرة على التعامل مع المسافات البيضاء والمحارف الخاصة الأخرى (الخاصة بالصدفة) في الوسائط والمعاملات التي ليست خيارات. ولحل هذه المشكلة، يمكن لهذا التطبيق توليد مخرجات مقتبسة يجب تفسيرها مرة أخرى بواسطة الصدفة (عادةً باستخدام أمر eval). وهذا يؤدي إلى الحفاظ على تلك المحارف، ولكن يجب استدعاء getopt بطريقة لم تعد متوافقة مع الإصدارات الأخرى (التنسيق الثاني أو الثالث في موجز الاستخدام). ولتحديد ما إذا كان هذا الإصدار المحسن من getopt(1) مثبتاً، يمكن استخدام خيار اختبار خاص (-T).

الخيارات

-a، --alternative
    السماح للخيارات الطويلة بالبدء بشرطة واحدة '-'.

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

-n، --name اسم_البرنامج
    الاسم الذي ستستخدمه روتينات getopt(3) عند الإبلاغ عن الأخطاء. لاحظ أن أخطاء getopt(1) لا يزال يُبلغ عنها على أنها آتية من getopt.

-o، --options _الخيارات-القصيرة _
    الخيارات القصيرة (ذات المحرف الواحد) المراد التعرف عليها. إذا لم يتم العثور على هذا الخيار، يُستخدم المعامل الأول من getopt الذي لا يبدأ بـ '-' (وليس وسيطاً لخيار) كسلسلة خيارات قصيرة. كل محرف خيار قصير في shortopts قد يتبعه {colon} واحد للإشارة إلى أن له وسيطاً مطلوباً، و{colon}{colon} للإشارة إلى أن له وسيطاً اختيارياً. قد يكون المحرف الأول من shortopts هو '+' أو '-' للتأثير على طريقة تحليل الخيارات وتوليد المخرجات (انظر قسم أوضاع الفحص للتفاصيل).

-q، --quiet
    تعطيل الإبلاغ عن الأخطاء بواسطة getopt(3).

-Q، --quiet-output
    عدم توليد مخرجات عادية. لا يزال يُبلغ عن الأخطاء بواسطة getopt(3)، ما لم تستخدم أيضاً الخيار -q.

-s، --shell الصدفة
    يضبط اصطلاحات الاقتباس لتلك الخاصة بـ صدفة. إذا لم يُعطَ الخيار -s، تُستخدم اصطلاحات BASH. المعطيات الصالحة حاليًا هي 'sh' و'bash' و'csh' و'tcsh'.

-T، --test
    اختبار ما إذا كان getopt(1) هو هذا الإصدار المحسن أو إصدار قديم. لا يولد هذا أي مخرجات، ويضبط حالة الخطأ على 4. التطبيقات الأخرى من getopt(1)، وهذا الإصدار في حال ضبط متغير البيئة GETOPT_COMPATIBLE، ستعيد '--' وحالة الخطأ 0.

-u، --unquoted
    لا تقتبس المخرجات. لاحظ أن المسافات البيضاء والمحارف الخاصة (المعتمدة على الصدفة) يمكن أن تسبب فوضى في هذا الوضع (كما تفعل مع تطبيقات getopt(1) الأخرى).

-U، --unknown
    ترك الخيارات المجهولة كما هي وكتم رسائل الخطأ من getopt(3). ونظراً لعدم وجود طريقة لمعرفة ما إذا كان الخيار المجهول يتطلب معطى أم لا، فإن أي معطى ليس خياراً يأتي بعد الخيار المجهول بعد مسافة بيضاء، سيُعتبر معطى للخيار، وبالتالي سيُترك المعطى دون تغيير ويُطبع بجانب الخيار المجهول المقابل له. ولمنع السلوك غير المتوقع، ينبغي تحديد الخيارات القصيرة بشكل فردي.

-h، --help
    اعرض نص المساعدة ثم اخرج.

-V، --version
    اعرض الإصدار واخرج.

التحليل

يحدد هذا القسم تنسيق الجزء الثاني من معلمات getopt (المعلمات معاملات في قسم SYNOPSIS). يصف القسم التالي (OUTPUT) المخرجات الناتجة. هذه المعلمات هي عادةً المعلمات التي استُدعيت بها دالة الصدفة. يجب الحرص على أن كل معلمة استُدعيت بها دالة الصدفة تقابل تمامًا معلمة واحدة في قائمة معلمات getopt (راجع الأمثلة *). يُجرى كل التحليل بواسطة روتينات GNU *getopt(3).

تُحلل المعلمات من اليسار إلى اليمين. تُصنف كل معلمة كخيار قصير، أو خيار طويل، أو معطى لخيار، أو معلمة ليست خيارًا.

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

يمكن تحديد عدة خيارات قصيرة بعد '-' واحد، طالما أن جميعها (باستثناء الأخير ربما) لا تملك معطيات مطلوبة أو اختيارية.

يبدأ الخيار الطويل عادةً بـ '--' متبوعًا باسم الخيار الطويل. إذا كان للخيار معطى مطلوب، فيمكن كتابته مباشرة بعد اسم الخيار الطويل، مفصولاً بـ '='، أو كالمعطى التالي (أي يفصل بينهما مسافة بيضاء في سطر الأوامر). إذا كان للخيار معطى اختياري، فيجب كتابته مباشرة بعد اسم الخيار الطويل، مفصولاً بـ '='، في حال وجوده (إذا أضفت '=' ولم تضف شيئًا خلفه، يُفسر كما لو لم يكن هناك معطى؛ هذا خطأ برمجى طفيف، راجع قسم العيوب BUGS). يمكن اختصار الخيارات الطويلة، طالما أن الاختصار ليس غامضًا.

كل معلمة لا تبدأ بـ '-'، وليست معطى مطلوبًا لخيار سابق، هي معلمة ليست خيارًا. كل معلمة بعد معلمة '--' تُفسر دائمًا على أنها معلمة ليست خيارًا. إذا ضُبط متغير البيئة POSIXLY_CORRECT، أو إذا بدأت سلسلة خيارات القصير بـ '+'، تُفسر جميع المعلمات المتبقية كمعلمات ليست خيارات بمجرد العثور على أول معلمة ليست خيارًا.

الخرج

تولّد المخرجات لكل عنصر موصوف في القسم السابق. يتم الإخراج بنفس الترتيب الذي حددت به العناصر في المدخلات، باستثناء المعلمات التي ليست خيارات. يمكن أن يكون الإخراج في وضع متوافق (غير مقتبس)، أو بطريقة تحافظ على المسافات البيضاء والمحارف الخاصة الأخرى داخل المعطيات والمعلمات التي ليست خيارات (راجع قسم الاقتباس QUOTING). عندما تُعالج المخرجات في سكريبت الصدفة، ستظهر وكأنها مكونة من عناصر متميزة يمكن معالجتها واحدًا تلو الآخر (باستخدام أمر shift في معظم لغات الصدفة). هذا غير مثالي في الوضع غير المقتبس، حيث يمكن تقسيم العناصر في أماكن غير متوقعة إذا كانت تحتوي على مسافات بيضاء أو محارف خاصة.

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

بالنسبة للخيار القصير، يُولّد '-' واحد ومحرف الخيار كمعلمة واحدة. إذا كان للخيار معطى، فستكون المعلمة التالية هي المعطى. إذا كان الخيار يأخذ معطى اختياريًا، ولكن لم يُعثر على أي منها، فستُولّد المعلمة التالية ولكنها ستكون فارغة في وضع الاقتباس، ولكن لن تُولّد معلمة ثانية في الوضع غير المقتبس (المتوافق). لاحظ أن العديد من تطبيقات getopt(1) الأخرى لا تدعم المعطيات الاختيارية.

إذا حُددت خيارات قصيرة متعددة بعد علامة '-' واحدة، فسيظهر كل منها في المخرجات كمعلمة منفصلة.

بالنسبة للخيار الطويل، تُولّد '--' واسم الخيار الكامل كمعلمة واحدة. ويُنفذ هذا بغض النظر عما إذا كان الخيار قد اختُصر أو حُدد بعلامة '-' واحدة في المدخلات. وتُعامل المعطيات كما تُعامل في الخيارات القصيرة.

عادةً، لا تُولّد مخرجات للمعالم التي لا تُعد خيارات حتى تُولّد جميع الخيارات ومعطياتها. ثم تُولّد '--' كمعلمة واحدة، وبعدها المعالم التي ليست خيارات بالترتيب الذي وُجدت به، كل منها كمعلمة منفصلة. وفقط إذا كان المحرف الأول من سلسلة الخيارات القصيرة هو '-'، تُولّد مخرجات المعالم التي ليست خيارات في المكان الذي وُجدت فيه في المدخلات (هذا ليس متاحًا إذا استُخدم التنسيق الأول لفقرة SYNOPSIS؛ وفي هذه الحالة تُتجاهل جميع حالات ظهور '-' و '+' السابقة).

الاقتباس

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

لا يُفعل الاقتباس إذا ضُبط متغير البيئة GETOPT_COMPATIBLE، أو إذا استُخدم الصيغة الأولى من SYNOPSIS، أو إذا وُجد الخيار '-u'.

تستخدم الصدفات المختلفة اتفاقيات اقتباس مختلفة. يمكنك استخدام الخيار '-s' لاختيار الصدفة التي تستخدمها. الصدفات التالية متاحة حاليًا: 'sh' و 'bash' و 'csh' و 'tcsh'. في الواقع، يُميز بين 'نكهتين' فقط: اتفاقيات اقتباس تشبه sh واتفاقيات اقتباس تشبه csh. ومن المحتمل أنه إذا كنت تستخدم لغة سكريبت صدفة أخرى، فإنه لا يزال بالإمكان استخدام إحدى هاتين النكهتين.

أوضاع الفحص

قد يكون المحرف الأول من سلسلة الخيارات القصيرة هو '-' أو '+' للإشارة إلى وضع مسح خاص. وإذا استُخدمت صيغة الاستدعاء الأولى في SYNOPSIS فإنها تُتجاهل؛ ومع ذلك، لا يزال يُفحص متغير البيئة POSIXLY_CORRECT.

إذا كان المحرف الأول هو '+'، أو إذا ضُبط متغير البيئة POSIXLY_CORRECT، فإن التحليل يتوقف بمجرد العثور على أول معلمة ليست خيارًا (أي معلمة لا تبدأ بـ '-') ولا تُعد معطى لخيار. وتُفسر جميع المعالم المتبقية على أنها معالم ليست خيارات.

إذا كان المحرف الأول هو '-'، تُخرج المعالم التي ليست خيارات في المكان الذي وُجدت فيه؛ أما في التشغيل العادي، فتُجمع جميعًا في نهاية المخرجات بعد توليد المعلمة '--'. لاحظ أن معلمة '--' هذه لا تزال تُولد، ولكنها ستكون دائمًا المعلمة الأخيرة في هذا الوضع.

التوافقية

كُتب هذا الإصدار من getopt(1) ليكون متوافقًا قدر الإمكان مع الإصدارات الأخرى. وعادةً يمكنك استبدالها بهذا الإصدار دون أي تعديلات، ومع الحصول على بعض المزايا.

إذا لم يكن المحرف الأول من المعلمة الأولى لـ getopt هو '-'، يدخل getopt في وضع التوافق. حيث سيُفسر معلمته الأولى على أنها سلسلة الخيارات القصيرة، وستُحلل جميع المعطيات الأخرى. وسيستمر في إجراء تبديل المعالم (أي تُخرج جميع المعالم التي ليست خيارات في النهاية)، ما لم يُضبط متغير البيئة POSIXLY_CORRECT، وفي هذه الحالة، سيسبق getopt سلسلة الخيارات القصيرة بـ '+' آليًا.

يُجبر متغير البيئة GETOPT_COMPATIBLE الأداة getopt على الدخول في وضع التوافق. ويوفر ضبط كل من متغير البيئة هذا و POSIXLY_CORRECT توافقًا بنسبة 100% للبرامج 'الصعبة'. ومع ذلك، فعادةً لا توجد حاجة لأي منهما.

في وضع التوافق، تُتجاهل محارف '-' و '+' البادئة في سلسلة الخيارات القصيرة.

الشفرات الراجعة

يعيد getopt رمز الخطأ 0 للتحليل الناجح، و 1 إذا أعاد getopt(3) أخطاءً، و 2 إذا لم يفهم معالمه الخاصة، و 3 في حال حدوث خطأ داخلي مثل نفاد الذاكرة، و 4 إذا استُدعي مع الخيار -T.

أمثلة

تُوفر سكريبتات أمثلة لـ (ba)sh و (t)csh مع توزيعة getopt(1)، وتُثبت في دليل /usr/share/doc/util-linux.

البيئة

POSIXLY_CORRECT
    يُفحص متغير البيئة هذا بواسطة روتينات getopt(3). فإذا كان مضبوطًا، يتوقف التحليل بمجرد العثور على معلمة لا تُعد خيارًا أو معطى لخيار. وتُفسر جميع المعالم المتبقية أيضًا على أنها معالم ليست خيارات، بغض النظر عما إذا كانت تبدأ بـ '-'.

GETOPT_COMPATIBLE
    يُجبر getopt على استخدام صيغة الاستدعاء الأولى كما هي محددة في الموجز.

العلل

يمكن لـ getopt(3) تحليل الخيارات الطويلة ذات الوسائط الاختيارية التي تُعطى وسيطاً اختيارياً فارغاً (لكنه لا يستطيع القيام بذلك للخيارات القصيرة). تعامل الأداة getopt(1) هذه الوسائط الاختيارية الفارغة وكأنها غير موجودة.

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

المؤلف

انظر أيضاً

bash(1)، tcsh(1)، getopt(3)

التبليغ عن الأخطاء

لتقارير العِلل، استخدم

التوفر

الأمر getopt جزء من حزمة util-linux التي يمكن تنزيلها من