هذا إطار عمل لكتابة نصوص bash التي تقبل الخيارات و/أو الوسائط. حدد الخيارات والوسائط التي يقبلها البرنامج النصي الخاص بك باستخدام بناء جملة تعريفي بسيط ودع bash-args :
لقد تم تصميمه ليكون سهل الاستخدام، وبعيدًا عن الطريق، ولتوفير تجربة مستخدم مصقولة.
يهدف إلى أن يكون محمولاً، حيث يمرر جناح الاختبار جميع الإصدارات الرئيسية من bash >= 3.2.
لاستخدام bash-args في نصوصك البرمجية، ما عليك سوى الحصول على الملف init.sh
فيما يلي مثال للبرنامج النصي eval-command.sh :
#! /usr/bin/env bash
# Summary : My first bash script using bash-args.
#
# Description : This takes a command as argument, and runs it.
#
# Argument : command
#
# Options :
#
# % dry-run
# desc="Don't execute, just print."
# short="n" type="flag" variable="dry_run" value=1 default=0
#
# % directory
# desc="The directory in which to run the command." argument=directory
# short="d" type="option" variable="directory" default="$(pwd)"
#
. path/to/bash-args/init.sh
# After sourcing the script, you can use the $directory and the $dry_run
# variables to get the values of the options typed (or not) in the command line.
# The other arguments are available as standard bash arguments $1, $2, etc.
command= " cd $directory && $1 "
if [[ $dry_run -eq 1 ]] ; then
echo " $command "
else
eval " $command "
fiدعنا نحاول تشغيل هذا الأمر مع الخيارات:
$ eval-command.sh --dry-run --directory /home 'echo hello'
cd /home && echo hello
يمكنك استخدام الخيارات القصيرة، ويمكن تجميعها:
$ eval-command.sh -nd /home 'echo hello'
cd /home && echo hello
إكمال علامة تبويب الإعداد بأمر بسيط:
$ eval $(eval-command.sh _register_completion)
يتم توفير صفحة المساعدة:
$ eval-command.sh --help
My first bash script using bash-args.
Usage : eval-command.sh [OPTIONS] [COMMAND]
This takes a command as argument, and runs it.
Options :
--help | -h
Show this help.
--dry-run | -n
Don't execute, just print.
--directory | -d [DIRECTORY]
The directory in which to run the command.
يمكن لـ Bash-args أيضًا إدارة الأوامر الفرعية:
main-script.sh help subcmd1 أو main-script.sh subcmd1 --help . لتحقيق ذلك، قم باستدعاء الدالة cmd_run في نهاية البرنامج النصي الرئيسي، وحدد الأوامر الفرعية عن طريق إضافة نصوص shell إلى الدليل cmd/ . يجب أن يبدو هيكل مشروعك كما يلي:
main-script.sh
cmd/
- subcmd1.sh
- subcmd2.sh
لتوثيق الأوامر الفرعية وتحديد خياراتها ووسائطها، اكتب بيانات التعريف في كتل التعليق الأولى لكل أمر فرعي، تمامًا كما هو الحال في البرنامج النصي الرئيسي.
الخيارات المحددة في البرنامج النصي الرئيسي متاحة لجميع الأوامر الفرعية، بينما الخيارات المحددة في أمر فرعي متاحة فقط لهذا الأمر الفرعي المحدد.
تتبع البيانات الوصفية للبرنامج النصي بناء جملة بسيط للغاية: في كتلة التعليق الأولى، يحدد كل سطر يبدأ بكلمة متبوعة بفاصلة منقوطة حقلاً جديدًا، وكل شيء يتبع الفاصلة المنقوطة يحدد قيمته. يتم إلحاق الأسطر التالية، حتى بداية الحقل التالي، بالقيمة.
فيما يلي الحقول المستخدمة بواسطة bash-args .
--version الذي يطبع اسمه وإصداره.يتم تعريف الخيارات في البيانات التعريفية للخيارات ، كما هو الحال في المثال النصي:
# Options :
#
# % dry-run
# desc="Don't execute, just print."
# short="n" type="flag" variable="dry_run" value=1 default=0
#
# % directory
# desc="The directory in which to run the command." argument=directory
# short="d" type="option" variable="directory" default="$(pwd)"
# يبدأ الخيار بـ % متبوعًا باسمه. يجب أن تحتوي أسماء الخيارات على أحرف أبجدية رقمية فقط، _ أو - .
تحدد الأسطر التالية معلمات الخيار. عند تشغيل البرنامج النصي، يتم تقييمه فعليًا كرمز bash. المتغيرات المحددة هي معلمات الخيار. هذا يعني أن قواعد الاقتباس العامة للسلاسل تنطبق، وأنه يمكنك تحديد الخيارات ديناميكيًا، كما هو الحال في المثال أعلاه، حيث يتم تعيين المعلمة default لخيار directory على $(pwd) .
يجب أن يحدد الخيار على الأقل type والمعلمة variable :
type إما flag أو option . الأعلام لا تقبل الحجج، الخيارات تفعل ذلك.variable هو اسم المتغير الذي ستتوفر بموجبه قيمة وسيطة الخيار في البرنامج النصي الخاص بك.قد يحدد أحد الخيارات هذه المعلمات الأخرى:
desc هو وصف للخيار المستخدم في صفحات المساعدة.short هو حرف واحد، يستخدم للخيار القصير.argument هي نوع الوسيطة. راجع أنواع الوسيطاتdefault هو القيمة التي يأخذها الخيار عندما لا يكون الخيار محددًا في الأمر الذي يكتبه المستخدم.value هي القيمة التي يأخذها الخيار عند تحديد الخيار، ولكن بدون وسيطة. يتم ضمان تعريف المتغيرات المحددة بواسطة الخيارات في البرنامج النصي الخاص بك: إذا لم تتمكن bash-args من العثور على قيمة لخيار ما، فسيتم الخروج مع حدوث خطأ. هذا يعني أنه إذا لم تحدد الخيار default ، فإن تشغيل البرنامج النصي الرئيسي بدون هذا الخيار سيؤدي إلى ظهور خطأ.
بمعنى آخر، إذا كنت لا تريد أن يكون هناك خيار مطلوب، فحدد معلمة default في تعريفه.
تعمل معلمة value بطريقة مماثلة. إذا لم تحدده، فإن الخيار، عند استخدامه، يتطلب وسيطة. إذا قمت بذلك، يمكن استخدام الخيار بدون وسيطة.
تعمل خيارات العلامة بنفس الطريقة، وبما أنها لا تأخذ وسيطات، فيجب عليك تحديد المعلمات default ومعلمات value الخاصة بها.
يمكن لـ Bash-args التعامل مع الإكمال التلقائي للبرنامج النصي الخاص بك باستخدام واجهة برمجة تطبيقات Bash للإكمال. لتنشيط الإكمال التلقائي للأمر، قم بتشغيل الأمر التالي:
eval $( my-command.sh _register_completion ) سيقترح إكمال علامة التبويب بعد ذلك الخيارات المحددة إذا كانت الكلمة عند النقطة تبدأ بـ - ، ويقترح أوامر فرعية ووسائط بخلاف ذلك.
لإخبار bash-args بما يجب اقتراحه كوسيطة، يمكنك تحديد نوع وسيطة في البيانات Argument للبرنامج النصي (أو الأمر الفرعي)، أو في معلمة argument لأحد الخيارات.
فيما يلي أنواع الوسائط المضمنة:
لإنشاء نوع وسيطة جديد وإعداده للإكمال التلقائي، قم بتعريف وظيفة تسمى _complete_my_arg_type . يجب أن تكون هذه الوظيفة متاحة للبرنامج النصي init.sh ، لذا يجب تعريفها قبل ملف . init.sh خط . init.sh
من المفترض أن تقوم وظائف الإكمال بإضافة اقتراحاتها إلى مجموعة COMP_REPLIES العامة. يحصلون على الكلمة الحالية عند النقطة كمعلمة للراحة، ولكن يمكنك أيضًا استخدام المتغيرات العامة COMP_LINE و COMP_POINT ، تمامًا كما هو الحال في جميع البرامج النصية لإكمال bash.
إليك كيفية تحديد نوع وسيطة الملف :
_complete_file () {
# $1 is the word being typed that we want to complete.
for file in " ${1-} " * ; do
# add each file to the completion candidates.
COMP_REPLIES+=( " $file " )
done
}
