Fish 2.7



fish

Documentation

المقدمة

هذا هو توثيق fish ، الصدفة التفاعلية الودية. fish هو قذيفة commandline المستخدم ودية تهدف في الغالب للاستخدام التفاعلي. shell هو برنامج يستخدم لتنفيذ برامج أخرى. للحصول على أحدث المعلومات حول fish ، يرجى زيارة صفحة fish الرئيسية .

نظرة عامة حول التركيب

وتستخدم قذائف مثل الأسماك من خلال منحهم الأوامر. كل أمر fish يتبع نفس البنية البسيطة.

يتم تنفيذ الأمر عن طريق كتابة اسم الأمر متبوعًا بأي وسيطات.

مثال:

echo hello world

هذا يستدعي الأمر echo . echo هو الأمر الذي سيكتب حججها إلى الشاشة. في المثال أعلاه ، سيكون الناتج "hello world". يتم كل شيء في الأسماك مع الأوامر. هناك أوامر لتنفيذ مجموعة من الأوامر عدة مرات ، أوامر لتعيين متغيرات ، أوامر لمعالجة مجموعة من الأوامر كأمر واحد ، وما إلى ذلك. وكل أمر يتبع نفس البنية البسيطة.

إذا كنت ترغب في معرفة المزيد عن أمر الارتداد المستخدم أعلاه ، اقرأ الصفحة اليدوية لأمر echo بالكتابة: man echo

man هو أمر لعرض صفحة دليل على موضوع معين. يأخذ الأمر man اسم الصفحة اليدوية لعرضها كوسيطة. توجد صفحات يدوية لكل أمر تقريبًا في معظم أجهزة الكمبيوتر. توجد أيضًا صفحات يدوية للعديد من الأشياء الأخرى ، مثل مكتبات النظام والملفات الهامة.

يمكن استخدام كل برنامج على جهاز الكمبيوتر الخاص بك كقيادة في fish . إذا كان ملف البرنامج موجودًا في أحد الدلائل في PATH ، يكفي كتابة اسم البرنامج لاستخدامه. بخلاف ذلك ، يجب استخدام اسم الملف بالكامل ، بما في ذلك الدليل (مثل /home/me/code/checkers/checkers ../checkers /home/me/code/checkers/checkers ../checkers أو ../checkers ).

فيما يلي قائمة ببعض الأوامر المفيدة:

  • cd ، قم بتغيير الدليل الحالي
  • ls ، قائمة الملفات والدلائل
  • man ، عرض صفحة دليل على الشاشة
  • mv ، ونقل (إعادة تسمية) الملفات
  • cp ، نسخ الملفات
  • open الملفات المفتوحة مع التطبيق الافتراضي المرتبط بكل نوع filetype
  • less ، قائمة محتويات الملفات

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

يعد التبديل نوعًا خاصًا جدًا من الحجة. تبدأ المحولات دائمًا بواحدة أو أكثر من "واصلات" وتغيير طريقة عمل الأمر. على سبيل المثال ، يسرد الأمر ' ls ' عادة جميع الملفات والدلائل الموجودة في دليل العمل الحالي ، ولكن باستخدام رمز التبديل ' -l ' ، يتم تغيير سلوك ' ls ' ليس لعرض اسم الملف فقط ، ولكن أيضًا حجمه والأذونات والمالك وتعديل وقت كل ملف.

تختلف مفاتيح التبديل بين الأوامر ويتم توثيقها في الصفحة اليدوية لكل أمر. تكون بعض مفاتيح التبديل شائعة لمعظم الأوامر ، على سبيل المثال " --help " ستعرض عادة نص -i ، " -i " ستقوم في كثير من الأحيان بتشغيل المطالبة التفاعلية قبل اتخاذ الإجراء ، بينما " -f " ستقوم بإيقاف تشغيلها.

يقتبس

في بعض الأحيان ، تظهر بعض الميزات مثل توسيع المعلمة وتجاوز الأحرف . عندما يحدث ذلك ، يمكن للمستخدم كتابة معلمة ضمن علامات اقتباس ، إما ' (اقتباس منفرد) أو " (اقتباس مزدوج). هناك فرق واحد مهم بين السلاسل المفردة والمعلنة المزدوجة: عند استخدام سلسلة مقتبسة مزدوجة ، فإن التوسع المتغير لا يزال يحدث وبخلاف ذلك ، لن يحدث أي نوع آخر من التوسع (بما في ذلك توسيع الدعامة وتوسيع المعلمة) ، وقد تحتوي المعلمة على مسافات ، ويتم تجاهل تسلسلات الهروب ، حيث يكون الهروب المائل للخلف المائل الوحيد المقبول ضمن علامات الاقتباس الفردية هو \' الرمز "و" \\ ، الذي يهرب من رمز الخط المائل العكسي.التقطيع المائل للخلف المائل الوحيد الذي يتم قبوله ضمن علامات اقتباس مزدوجة هو \" ، والتي تخرج من علامة اقتباس مزدوجة ، \$ ، والتي تفلت من حرف دولار ، \ متبوعًا بخط جديد ، يحذف الخط المائل العكسي والخط الخلفي newline ، وأخيرًا \\ ، الذي يهرب من رمز الخط المائل العكسي. الاقتباسات الفردية ليس لها معنى خاص ضمن علامات الاقتباس المزدوجة والعكس صحيح.

مثال:

rm "cumbersome filename.txt"

سوف إزالة الملف "filename.txt مرهقة" ، في حين

rm cumbersome filename.txt

سيزيل الملفين "مرهقين" و "filename.txt".

الهروب من الشخصيات

بعض الحروف لا يمكن كتابتها مباشرة على سطر الأوامر. لهذه الشخصيات ، يتم توفير تسلسل الهروب ما يسمى. هؤلاء هم:

  • " \a " يمثل حرف التنبيه
  • " \b " يمثل الحرف Backspace
  • " \e " يمثل حرف الهروب
  • تمثل " \f " رمز خلاصة النموذج
  • " \n " يمثل حرفًا في السطر الجديد
  • " \r 'تمثل حرف إرجاع الحرف
  • يمثل \t 'حرف علامة التبويب
  • " \v " يمثل حرف الجدولة الرأسي
  • " \ " يهرب من حرف الفضاء
  • يهرب " \$ " من حرف الدولار
  • يهرب ' \\ ' من حرف الخط المائل العكسي (Backslash)
  • " \* " يهرب من شخصية النجمة
  • " \? "يهرب من حرف علامة الاستفهام
  • " \~ " يهرب من حرف التلدة
  • يهرب ' \% ' من الحرف النسبة المئوية
  • يهرب " \# " من حرف التجزئة
  • ' \( ' يهرب من حرف القوس الأيسر
  • يهرب ' \) "من حرف القوس الأيمن
  • " \{ " تنفصل عن حرف قوس المجعد الأيسر
  • يهرب الحرف \} " \} " من حرف قوس المجعد الأيمن
  • " \[ يهرب من حرف القوس الأيسر
  • " \] " 'يهرب من حرف القوس الصحيح
  • يخرج \< "أقل من الحرف
  • ' \> ' يهرب أكثر من الحرف
  • " \^ " يهرب من حرف circumflex
  • " \& " يهرب من حرف علامة الضم
  • " \| "يهرب من شريط شريط عمودي
  • " "يهرب حرف الفاصلة المنقوطة
  • " \" 'يهرب من حرف الاقتباس
  • يهرب الحرف الفاصلة
  • يمثل " \x xx " حيث xx رقمًا سداسيًا عشريًا ascii بالقيمة المحددة. على سبيل المثال ، \x9 هو حرف علامة التبويب.
  • ' \X xx ' ، حيث يمثل xx رقمًا سداسيًا عشريًا ، يمثل بايتًا من البيانات ذات القيمة المحددة. إذا كنت تستخدم ترميز متعدد البايت ، فيمكن استخدامه لإدخال سلاسل غير صالحة. استخدم هذا فقط إذا كنت تعرف ما تقوم به.
  • " \ ooo " ، حيث ooo هو رقم ثماني ، يمثل الحرف ascii بالقيمة المحددة. على سبيل المثال ، \011 هو حرف علامة التبويب.
  • ' \u xxxx ' ، حيث يمثل xxxx رقمًا سداسيًا عشريًا ، يمثل حرف Unicode 16 بت بالقيمة المحددة. على سبيل المثال ، \u9 هو حرف علامة التبويب.
  • ' \U xxxxxxxx ' ، حيث xxxxxxxx هو رقم سداسي عشري ، يمثل حرف Unicode 32 بت بالقيمة المحددة. على سبيل المثال ، \U9 هو حرف علامة التبويب.
  • " \c x " ، حيث تمثل x حرفًا من الحروف الأبجدية ، تمثل تسلسل التحكم الناتج عن الضغط على مفتاح التحكم والحرف المحدد. على سبيل المثال ، \ci هو حرف الجدولة

الإدخال / الإخراج (IO) إعادة توجيه

تستخدم معظم البرامج ثلاثة دفق الإدخال / الإخراج (IO) ، يتم تمثيل كل منها برقم يسمى واصف ملف (FD). هؤلاء هم:

  • الإدخال القياسي ، FD 0 ، للقراءة ، افتراضيات القراءة من لوحة المفاتيح.
  • الإخراج القياسي ، FD 1 ، للكتابة ، الإعداد الافتراضي للكتابة على الشاشة.
  • الخطأ المعياري ، FD 2 ، لكتابة الأخطاء والتحذيرات ، الافتراضيات للكتابة على الشاشة.

السبب في توفير اثنين من واصفات ملف الإخراج هو السماح لفصل الأخطاء والتحذيرات من إخراج البرنامج العادي.

يمكن توجيه أي واصف ملف إلى إخراج مختلف عن الافتراضي من خلال آلية بسيطة تسمى إعادة توجيه.

مثال على إعادة توجيه الملف هو echo hello > output.txt ، الذي يوجه إخراج أمر echo إلى ملف output.txt.

  • لقراءة الإدخال القياسي من ملف ، اكتب <SOURCE_FILE
  • لكتابة إخراج قياسي إلى ملف ، اكتب >DESTINATION
  • لكتابة خطأ قياسي إلى ملف ، اكتب ^DESTINATION
  • لإلحاق الإخراج القياسي إلى ملف ، اكتب >>DESTINATION_FILE
  • لإلحاق الخطأ القياسي بملف ، اكتب ^^DESTINATION_FILE
  • لعدم استبدال ("clobber") بملف موجود ، اكتب "> DESTINATION" أو "^ DESTINATION"

يمكن أن يكون DESTINATION واحدًا مما يلي:

  • اسم الملف. سيتم كتابة الإخراج إلى الملف المحدد.
  • علامة العطف ( & ) متبوعة برقم واصف ملف آخر. ستتم كتابة الإخراج إلى واصف الملف بدلاً من ذلك.
  • علامة العطف متبوعة بعلامة السالب ( &- ). سيتم إغلاق واصف الملف.

مثال:

لإعادة توجيه كل من الإخراج القياسي والخطأ القياسي إلى الملف 'all_output.txt' ، يمكنك كتابة echo Hello > all_output.txt ^&1 .

يمكن إعادة توجيه أي واصف ملف بطريقة عشوائية عن طريق إدخال إعادة التوجيه مع واصف الملف.

  • لإعادة توجيه إدخال FD N ، اكتب N<DESTINATION
  • لإعادة توجيه إخراج FD N ، اكتب N>DESTINATION
  • لإلحاق ناتج FD N إلى ملف ، اكتب N>>DESTINATION_FILE

مثال: echo Hello 2>output.stderr و echo Hello ^output.stderr ، وكتابة الخطأ القياسي (واصف الملف 2) للبرنامج الهدف إلى output.stderr .

الأنابيب

يمكن للمستخدم ربط عدة أوامر معا في ما يسمى خط أنابيب. وهذا يعني أنه سيتم قراءة الإخراج القياسي لأمر واحد كمدخل قياسي في الأمر التالي. يتم ذلك عن طريق فصل الأوامر حسب حرف الأنبوبة ' | ". فمثلا

cat foo.txt | head

سوف يقوم باستدعاء برنامج cat بالمعلمة 'foo.txt' ، والتي ستقوم بطباعة محتويات الملف 'foo.txt'. ثم يتم تصفية محتويات foo.txt من خلال "رأس" البرنامج ، والذي سينتقل على الأسطر العشرة الأولى من الملف إلى الشاشة. لمزيد من المعلومات حول كيفية دمج الأوامر من خلال المواسير ، اقرأ الصفحات اليدوية للأوامر التي تريد استخدامها باستخدام الأمر man . إذا كنت ترغب في معرفة المزيد عن برنامج cat ، اكتب man cat .

توصيل أنابيب عادة واصف الملف 1 (الإخراج القياسي) من العملية الأولى إلى واصف الملف 0 (الإدخال القياسي) من العملية الثانية. من الممكن استخدام واصف ملف إخراج مختلف عن طريق إضافة رقم FD المطلوب ثم إخراج رمز إعادة التوجيه إلى الأنبوب. فمثلا:

make fish 2>| less

سوف يحاول بناء برنامج الأسماك ، وسيتم عرض أي أخطاء باستخدام أقل النداء.

وظائف الخلفية

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

مثال:

emacs &

سيبدأ محرر نص emacs في الخلفية.

السيطرة على الوظيفة

تسمح لك معظم البرامج بتعليق تنفيذ البرنامج وعودة التحكم في fish عن طريق الضغط على Control - Z (يشار إليه أيضًا بـ ^Z ). بمجرد العودة إلى سطر أوامر fish ، يمكنك بدء برامج أخرى وفعل أي شيء تريده. إذا أردت بعد ذلك يمكنك العودة إلى الأمر المعلق باستخدام الأمر fg (الأمامي).

إذا أردت بدلاً من ذلك وضع مهمة معلقة في الخلفية ، فاستخدم الأمر bg .

للحصول على قائمة بجميع الوظائف التي تم تشغيلها حاليًا ، استخدم الأمر jobs .

المهام

وظائف هي برامج مكتوبة في بناء الجملة السمكية. يقوموا بجمع واحد أو أكثر من الأوامر وحججهم باستخدام اسم واحد. يمكن استخدامه أيضًا لبدء أمر محدد مع وسيطات إضافية.

على سبيل المثال ، ما يلي هو تعريف الدالة الذي يستدعي الأمر ls مع الوسيطة ' -l ' لطباعة قائمة مفصلة بمحتويات الدليل الحالي:

function ll
    ls -l $argv
end

يخبر السطر الأول الأسماك أنه يجب تحديد دالة باسم ll . لاستخدامها ، ما عليك سوى كتابة ll على سطر الأوامر. يخبر السطر الثاني الأسماك أنه يجب استدعاء الأمر ls -l $argv عند استدعاء ll . ' $argv ' هو متغير صفيف ، والذي يحتوي دائمًا على كل الوسائط المرسلة إلى الدالة. في المثال أعلاه ، يتم تمرير هذه ببساطة إلى الأمر ls . لمزيد من المعلومات حول الوظائف ، راجع الوثائق الخاصة function .

تحديد الأسماء المستعارة

أحد الاستخدامات الأكثر شيوعًا للوظائف هو تغيير سلوك أمر موجود بالفعل قليلاً. على سبيل المثال ، قد يرغب المرء في إعادة تعريف الأمر ls لعرض الألوان. إن مفتاح تشغيل الألوان على أنظمة جنو هو " --color=auto ". قد يبدو الاسم المستعار أو المجمّع حول ls مثل هذا:

function ls
    command ls --color=auto $argv
end

هناك بعض الأشياء المهمة التي يجب ملاحظتها حول الأسماء المستعارة:

  • احرص دائمًا على إضافة متغير $argv إلى قائمة المعلمات إلى الأمر الملتف. يجعل هذا من أنه إذا حدد المستخدم أي معلمات إضافية للدالة ، فسيتم تمريرها إلى الأمر الأساسي.
  • إذا كان الاسم المستعار له نفس الاسم كأمر مستعار ، فمن الضروري بدء اتصال البرنامج command أجل إخبار الأسماك أن الدالة لا يجب أن تستدعي نفسها ، بل بالأحرى أمر بنفس الاسم. سيؤدي الفشل في القيام بذلك إلى حدوث أخطاء عودية لا نهائية.
  • لا يتم تطبيق Autoloading على الأسماء المستعارة. لأنه ، من خلال التعريف ، يتم إنشاء الدالة في الوقت الذي يتم فيه تنفيذ الأمر المستعار. لا يمكنك autoload الأسماء المستعارة.

لإنشاء وظيفة من هذا النموذج بسهولة ، يمكنك استخدام الأمر alias .

وظائف autoloading

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

تبحث الأسماك تلقائيًا من خلال أي أدلة في متغير الصفيف $fish_function_path ، ويتم تحميل أي وظائف محددة تلقائيًا عند الحاجة. يجب أن يكون لملف تعريف الدالة اسم ملف يتكون من اسم الوظيفة بالإضافة إلى اللاحقة " .fish ".

افتراضيًا ، يبحث Fish في ما يلي عن الوظائف ، باستخدام أول ملف متوفر يعثر عليه:

  • دليل للمستخدمين النهائيين للحفاظ على وظائفهم الخاصة ، عادة ~/.config/fish/functions (يتم التحكم في متغير بيئة XDG_CONFIG_HOME ).
  • دليل لمسؤولي الأنظمة لتثبيت وظائف لكل المستخدمين على النظام ، عادةً /etc/fish/functions .
  • دليل لموردي البرامج التابعين لجهات خارجية لشحن وظائفهم الخاصة /usr/share/fish/vendor_functions.d ، عادةً ما يكون /usr/share/fish/vendor_functions.d .
  • الوظائف التي يتم شحنها مع الأسماك ، وعادة ما يتم تركيبها في /usr/share/fish/functions .

يتم التحكم في هذه المسارات بواسطة معلمات تم تعيينها عند الإنشاء أو التثبيت أو وقت التشغيل ، وقد تختلف عن الإعدادات الافتراضية المذكورة أعلاه.

قد يكون هذا البحث على نطاق واسع مربكًا. إذا كنت غير متأكد ، فقد تنتمي ~/.config/fish/functions .

من المهم جداً أن تحتوي ملفات تعريف الدالة فقط على تعريف الوظيفة المحددة ولا شيء آخر. خلاف ذلك ، من الممكن أن يتطلب autoloading ملفات دالة أن يتم بالفعل تحميل الدالة ، مما ينشئ تبعية دائرية.

لن يعمل Autoloading أيضًا مع معالجات الأحداث ، نظرًا لأن الأسماك لا يمكنها معرفة أنه من المفترض أن يتم تنفيذ إحدى الوظائف عند وقوع الحدث عند عدم تحميله للوظيفة. راجع قسم معالجات الأحداث لمزيد من المعلومات.

لا يتم تطبيق Autoloading على الوظائف التي تم إنشاؤها بواسطة الأمر alias . لوظائف بسيطة بما فيه الكفاية التي تفضل استخدام الأمر alias لتعريفها ستحتاج إلى وضع هذه الأوامر في البرنامج النصي الخاص بك ~/.config/fish/config.fish أو بعض تشغيل البرنامج النصي الأخرى عند بدء shell.

إذا كنت تقوم بتطوير برنامج آخر ، فقد ترغب في تثبيت الوظائف المتاحة لجميع مستخدمي قشرة السمك على النظام. يمكن تثبيتها إلى دليل الدالات "المورد". نظرًا لأن هذا المسار قد يختلف من نظام إلى آخر ، فيجب استخدام إطار pkgconfig لاكتشاف هذا المسار من خلال إخراج pkg-config --variable functionsdir fish .

تنفيذ الشرطي من التعليمات البرمجية والتحكم في التدفق

هناك أربعة أنواع من السمك تسمح لك بتنفيذ الأوامر فقط إذا تم استيفاء معيار معين. هذه الموديلات هي if ، switch ، and و or .

يتم استخدام الأمر switch لتنفيذ أحد كتل الأوامر التي من المحتمل أن تعتمد على قيمة سلسلة. انظر الوثائق switch لمزيد من المعلومات.

تستخدم الشروط الشرطية الأخرى حالة الخروج لأمر ما لتحديد ما إذا كان يجب تنفيذ أمر أو كتلة أوامر. راجع الوثائق لمعرفة if ، and و or لمزيد من المعلومات.

بعض الكلمات الشائعة

هذا هو شرح قصير لبعض الكلمات شائعة الاستخدام في الأسماك.

  • وسيطة معلمة تعطى للأمر
  • بنيت أمر يتم تنفيذه في القشرة. المولدات هي الأوامر التي ترتبط ارتباطًا وثيقًا بالصدفة بحيث يستحيل تنفيذها كأوامر خارجية.
  • أمر برنامج يمكن تشغيل shell.
  • تعمل كتلة من الأوامر التي يمكن أن يطلق عليها كما لو كانت أمر واحد. باستخدام الدالات ، من الممكن تجميع عدة أوامر أصغر في أمر واحد أكثر تقدمًا.
  • العمل على خط أنابيب أو القيادة
  • خط أنابيب مجموعة من الأوامر وتربطها معا بحيث الإخراج من أمر واحد هو إدخال الأمر التالي
  • إعادة توجيه عملية تقوم بتغيير أحد تدفقات الإدخال / الإخراج المرتبطة بالمهمة
  • تبديل إشارة خاصة يتم إرسالها كوسيطة لأمر يؤدي إلى تغيير سلوك الأمر. يبدأ التبديل دائمًا دائمًا بشيطة واحدة أو وحدتين.

مساعدة

fish لديه نظام مساعدة واسع النطاق. استخدم أمر help للحصول على مساعدة حول موضوع أو أمر معين. على سبيل المثال ، يعرض help syntax تعليمات الكتابة قسم البنية في هذه الوثائق.

fish أيضا لديه صفحات رجل لأوامره. على سبيل المثال ، سيعرض المستخدم man set الوثائق set كصفحة رجل.

ويمكن أيضا الحصول على مساعدة على مدمج محدد مع المعلمة -h . على سبيل المثال ، للحصول على مساعدة حول fg builtin ، اكتب fg -h أو help fg .

اقتراحات تلقائية

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

لقبول الإيحاء الذاتي (استبدال محتويات سطر الأوامر) ، اضغط على السهم الأيمن أو Control - F. لقبول الكلمة المقترحة الأولى ، اضغط على Alt - أو Alt - F. إذا لم يكن الإيحاء الذاتي هو ما تريده ، فقط قم بتجاهله: لن يتم تنفيذه ما لم تقبله.

تعتبر الاقتراحات التلقائية طريقة فعالة لاستدعاء الأوامر التي يتم إدخالها بشكل متكرر بسرعة عن طريق كتابة الأحرف القليلة الأولى. وهي أيضًا تقنية فعالة للتنقل عبر التسلسلات الهرمية للدليل.

اكتمال علامة التبويب

يعتبر إكمال علامة التبويب واحدًا من أكثر ميزات حفظ الوقت في أي غلاف حديث. من خلال النقر على مفتاح علامة التبويب ، يطلب المستخدم من fish تخمين باقي الأمر أو المعلمة التي يكتبها المستخدم حاليًا. إذا لم تجد fish سوى إنجاز واحد ممكن ، فستقوم fish بكتابتها. إذا كان هناك أكثر من إتمام ، فإن fish سيكتب أطول بادئة تشترك فيها جميع الإكتمالات. إذا اختلفت الإكمالات في الحرف الأول ، فستتم طباعة قائمة بكل الإكمالات الممكنة. تتميز القائمة بأوصاف الإكمالات ، وإذا كانت القائمة لا تناسب الشاشة ، فيمكن التمرير عليها باستخدام مفاتيح الأسهم ، أو مفاتيح الصفحة لأعلى / أسفل الصفحة ، أو مفتاح علامة التبويب أو شريط المسافة. بمجرد إدخال القائمة ، سيؤدي الضغط على أي مفتاح آخر إلى بدء البحث. إذا لم يتم إدخال القائمة ، فسيؤدي الضغط على أي مفتاح آخر إلى الخروج من القائمة وإدخال المفتاح المضغوط في سطر الأوامر.

هذه هي إضافات علامات الأغراض العامة التي توفرها fish :

  • إنجاز الأوامر (المداخل ، الوظائف والبرامج العادية).
  • الانتهاء من أسماء متغير قذيفة.
  • الانتهاء من أسماء المستخدمين لتوسيع تيلدا.
  • الانتهاء من أسماء الملفات ، حتى على سلاسل أحرف البدل مثل " * " ، " ** " و " ? ".
  • الانتهاء من معرف المهمة واسم المهمة وأسماء عملية لتوسيع العملية .

توفر fish عددًا كبيرًا من الإكمالات المحددة للبرنامج. معظم هذه الإكمالات هي خيارات بسيطة مثل الخيار -l لـ ls ، لكن بعضها أكثر تقدمًا. هذا الأخير يشمل:

  • برامج man وما whatis تظهر كل صفحات دليل مثبتة whatis .
  • يستخدم برنامج make جميع الأهداف في Makefile في الدليل الحالي كمكملات.
  • يستخدم الأمر mount جميع نقاط التحميل المحددة في fstab كإكمال.
  • يستخدم الأمر ssh كافة المضيفات المخزنة في ملف known_hosts كمكملات. (راجع وثائق ssh لمزيد من المعلومات)
  • يستخدم الأمر su جميع المستخدمين على النظام كإكمال.
  • تستخدم أوامر apt-get و rpm و yum جميع الحزم المثبتة كإكمالات.

كتابة الإكمالات الخاصة بك

تحديد الإكمالات الخاصة بك ليست صعبة. لتحديد اكتمال ، استخدم الأمر complete . يأخذ complete كمعلمة اسم الأمر لتحديد اكتمال ل. على سبيل المثال ، لإضافة استكمال لبرنامج myprog ، يمكن للمرء أن يبدأ أمر إكمال مع complete -c myprog ...

لتوفير قائمة من الإكمالات المحتملة للماجبر ، استخدم -a التبديل -a . إذا قبلت myprog بدء الحجج وإيقافها ، فيمكن تحديد ذلك كـ complete -c myprog -a 'start stop' . دائمًا ما تكون الوسيطة -a سلسلة واحدة. في وقت الانتهاء ، سيتم وضعه على مسافات وعلامات تبويب ، وسيتم التوسع المتغير ، واستبدال الأمر وغيرها من أشكال توسيع المعلمات.

fish لديها بناء جملة خاصة لدعم تحديد مفاتيح مقبولة من قبل الأمر. يتم استخدام مفاتيح التبديل -l و -o لتحديد مفتاح تبديل قصير (حرف واحد ، مثل -l ) ، ومفتاح تبديل طويل نمط gnu (مثل " --color ") ومفتاح طويل الطراز طويل (مثل " -shuffle " ، على التوالي. إذا كان للأمر "myprog" خيار "-o" والذي يمكن كتابته أيضًا كـ " --output " ، والذي يمكن أن يأخذ قيمة إضافية إما بـ "yes" أو "no" ، يمكن تحديد ذلك بالكتابة:

complete -c myprog -s o -l output -a "yes no"

توجد أيضًا مفاتيح تبديل خاصة لتحديد أن المفتاح يتطلب وسيطة ، لتعطيل إكمال اسم الملف ، لإنشاء عمليات الإكمال التي لا تتوفر إلا في بعض المجموعات ، إلخ. للحصول على وصف كامل للمفاتيح المتنوعة المقبولة بواسطة الأمر complete ، راجع الوثائق للكامل البناء ، أو الكتابة complete --help داخل قذيفة fish .

للحصول على أمثلة حول كيفية كتابة الإكمالات المعقدة الخاصة بك ، قم بدراسة الإكمالات في /usr/share/fish/completions . (يعتمد المسار الدقيق على بادئة التثبيت التي اخترتها وقد تكون مختلفة قليلاً)

وظائف مفيدة لكتابة الإكمالات

سفن fish مع العديد من الوظائف التي تكون مفيدة جدا عند كتابة الإكمالات المحددة للقيادة. يبدأ معظم اسم هذه الدالات بالسلسلة ' __fish_ '. هذه الوظائف داخلية fish ويمكن أن يتغير اسمها وواجهةها في الإصدارات السمكية المستقبلية. ومع ذلك ، قد يكون بعضها مفيدًا جدًا عند كتابة الإكمالات. بعض هذه الوظائف موصوفة هنا. كن على علم أنه يمكن إزالتها أو تغييرها في الإصدارات المستقبلية من الأسماك.

دالات تبدأ مع السلسلة __fish_print_ طباعة قائمة جديدة مفصولة __fish_print_ . على سبيل المثال ، تقوم __fish_print_filesystems بطباعة قائمة بجميع أنظمة الملفات المعروفة. تبدأ دالات تبدأ بـ __fish_complete_ بقائمة منفصلة مفصولة عن الإكمالات بالأوصاف. يتم فصل الوصف عن الاكتمال بحرف جدولة.

  • __fish_complete_directories STRING DESCRIPTION ينفذ إكمال المسار على STRING ، مما يسمح فقط __fish_complete_directories STRING DESCRIPTION ، ومنحها الوصف DESCRIPTION.
  • __fish_complete_path STRING DESCRIPTION ينفذ عملية إكمال المسار على STRING ، مما يمنحها الوصف DESCRIPTION.
  • __fish_complete_groups تطبع قائمة بجميع مجموعات المستخدمين مع أعضاء المجموعات __fish_complete_groups .
  • تطبع __fish_complete_pids قائمة بكل معرفات العمليات باستخدام اسم الأمر __fish_complete_pids .
  • __fish_complete_suffix SUFFIX تقوم __fish_complete_suffix SUFFIX بإكمال الملف مما يسمح فقط بالملفات المنتهية بـ SUFFIX ، مع وصف اختياري.
  • يطبع __fish_complete_users قائمة بجميع المستخدمين باسمهم الكامل بوصفهم.
  • __fish_print_filesystems بطباعة قائمة بجميع أنظمة الملفات المعروفة. حالياً ، هذه قائمة ثابتة ، ولا تعتمد على أنظمة الملفات التي يفهمها نظام التشغيل المضيف بالفعل.
  • يطبع __fish_print_hostnames قائمة بجميع أسماء المضيف المعروفة. تقوم هذه الوظائف بالبحث عن fstab لملقمات nfs ، ssh للمضيفات المعروفة والتحقق من الملف /etc/hosts .
  • __fish_print_interfaces بطباعة قائمة بجميع واجهات الشبكة المعروفة.
  • __fish_print_packages بطباعة قائمة بجميع الحزم المثبتة. تتعامل هذه الوظيفة حاليًا مع حزم Debian و rpm و Gentoo.

أين تضع الإكمالات

يمكن تعريف الإكمالات على سطر الأوامر أو في ملف التكوين ، ولكن يمكن أيضًا تحميلها تلقائيًا. تقوم الأسماك بالبحث تلقائيًا من خلال أية أدلة في متغير الصفيف $fish_complete_path ، ويتم تلقائيًا تحميل أية $fish_complete_path محددة عند الحاجة. يجب أن يكون لملف الإكمال اسم ملف يتكون من اسم الأمر المراد استكماله واللاحقة " .fish ".

افتراضيًا ، يبحث Fish في ما يلي عن الإكمالات ، باستخدام أول ملف متوفر يعثر عليه:

  • دليل للمستخدمين النهائيين للاحتفاظ XDG_CONFIG_HOME الخاصة بهم ، عادة ~/.config/fish/completions (يتم التحكم في متغير بيئة XDG_CONFIG_HOME ) ؛
  • دليل لمسؤولي الأنظمة لتثبيت الإكمالات لكافة المستخدمين على النظام ، عادةً /etc/fish/completions ؛
  • دليل لموردي البرامج التابعين لجهات خارجية لشحن المكملات الخاصة بهم /usr/share/fish/vendor_completions.d ، عادةً ما يكون /usr/share/fish/vendor_completions.d ؛
  • الإكمالات التي يتم شحنها مع الأسماك ، وعادة ما يتم تركيبها في /usr/share/fish/completions ؛ و
  • يتم إنشاء عمليات الإكمال تلقائيًا من دليل نظام التشغيل ، وعادة ما يتم تخزينها في ~/.local/share/fish/generated_completions .

يتم التحكم في هذه المسارات بواسطة معلمات تم تعيينها عند الإنشاء أو التثبيت أو وقت التشغيل ، وقد تختلف عن الإعدادات الافتراضية المذكورة أعلاه.

قد يكون هذا البحث على نطاق واسع مربكًا. إذا كنت غير متأكد ، فمن المحتمل أن تكون الإكمالات الخاصة بك تنتمي إلى ~/.config/fish/completions .

إذا كنت قد كتبت إكمالات جديدة لأمر Unix شائع ، فالرجاء التفكير في مشاركة عملك عن طريق إرساله عبر التعليمات في مزيد من المساعدة والتطوير .

إذا كنت تقوم بتطوير برنامج آخر وترغب في شحن الإكمالات مع البرنامج الخاص بك ، فقم بتثبيتها في دليل إكمال "المورد". نظرًا لأن هذا المسار قد يختلف من نظام إلى آخر ، فيجب استخدام إطار pkgconfig لاكتشاف هذا المسار بإخراج pkg-config --variable completionsdir fish .

توسيع المعلمة (Globbing)

عندما يتم إعطاء وسيطة لبرنامج في سطر الأوامر ، فإنه يخضع لعملية توسيع المعلمة قبل إرسالها إلى الأمر. يُعد توسيع المعلمة آلية قوية تسمح لك بتوسيع المعلمة بطرق مختلفة ، بما في ذلك إجراء مطابقة أحرف البدل على الملفات ، وإدراج قيمة متغير shell في المعلمة أو حتى استخدام إخراج أمر آخر كقائمة معلمات.

البدل

إذا كانت النجمة ( * ) أو علامة الاستفهام ( ? ) موجودة في المعلمة ، fish مطابقة المعلمة المعطاة لأية ملفات بطريقة:

  • ? يمكن أن يتطابق مع أي حرف واحد باستثناء "/".
  • * يمكن أن تتطابق مع أي سلسلة أحرف لا تحتوي على "/". وهذا يشمل مطابقة سلسلة فارغة.
  • ** يطابق أي سلسلة من الأحرف. وهذا يشمل مطابقة سلسلة فارغة. قد تتضمن السلسلة المطابقة الحرف / ؛ وهذا يعني أنه يتكرر في الدلائل الفرعية. لاحظ أن زيادة حرف البدل هذا مع السلاسل الأخرى لن يتطابق مع الملفات الموجودة في دليل العمل الحالي ( $PWD ) إذا قمت بفصل السلاسل باستخدام شرطة مائلة ("/"). هذا على عكس قذائف أخرى مثل zsh. على سبيل المثال ، **\/*.fish سوف تتطابق **\/*.fish في zsh مع ملفات الأسماك في الأشخاص ذوي الإعاقة ولكن في الأسماك ستطابق هذه الملفات في دليل فرعي فقط. في الأسماك يجب عليك أن تكتب ***.fish لتتطابق مع الملفات في الأشخاص ذوي الإعاقة بالإضافة إلى الدلائل الفرعية.

توفر قذائف أخرى ، مثل zsh ، بناء جملة glob rich لتقييد الملفات المتطابقة بواسطة globs. على سبيل المثال ، **(.) ، لمطابقة الملفات العادية فقط. يفضل السمك إرجاء مثل هذه الميزات إلى البرامج ، مثل find ، بدلاً من إعادة اختراع العجلة. وبالتالي ، إذا كنت ترغب في الحد من توسع حرف البدل إلى الملفات العادية فقط ، فإن أسلوب السمك هو تحديد واستخدام وظيفة. فمثلا،

function ff --description 'Like ** but only returns plain files.'
    # This also ignores .git directories.
    find . \( -name .git -type d -prune \) -o -type f | \ 
        sed -n -e '/^\.\/\.git$/n' -e 's/^\.\///p'
end

عندئذٍ ستستخدمها بدلاً من ** like this ، my_prog (ff) ، لتمرير الملفات العادية فقط في أو أقل من PWD إلى my_prog .

يتم فرز تطابقات أحرف البدل حالة غير حساس. عند فرز التطابقات التي تحتوي على أرقام ، يتم اعتبار الأرقام المتتالية عنصرًا واحدًا ، بحيث يتم ترتيب السلاسل '1' '5' و '12' بالترتيب المحدد.

لا يتم اعتبار أسماء الملفات التي تبدأ بنقطة عند wildcarding ما لم يتم إعطاء نقطة بشكل محدد كأول حرف من اسم الملف.

أمثلة:

  • يتطابق a* مع أي ملفات تبدأ بـ "a" في الدليل الحالي.
  • ??? يطابق أي ملف في الدليل الحالي الذي يتكون اسمه من ثلاثة أحرف بالضبط.
  • ** يطابق أي ملفات أو أدلة في الدليل الحالي وكافة الأدلة الفرعية الخاصة به.

لاحظ أنه بالنسبة لمعظم الأوامر ، إذا فشل أي حرف بدل في التوسيع ، فلن يتم تنفيذ الأمر ، يتم تعيين $status إلى غير صفري ، ويتم طباعة تحذير. هذا السلوك متناسق مع إعداد shopt -s failglob في bash. هناك بالضبط 3 استثناءات ، تحديدا ، count و. يسمح لهم بتوسيع shopt -s nullglob إلى صفر الحجج ، كما هو الحال مع shopt -s nullglob في باش.

أمثلة:

ls *.foo
# Lists the .foo files, or warns if there aren't any.

set foos *.foo
if count $foos >/dev/null
    ls $foos
end
# Lists the .foo files, if any.

استبدال القيادة

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

حالة الخروج لاستبدال الأمر الأخير متاحة في متغير الحالة .

يمكن استخدام جزء فقط من الإخراج ، راجع توسيع نطاق الفهرس للحصول على التفاصيل.

أمثلة:

echo (basename image.jpg .jpg).png
# Outputs 'image.png'.

for i in *.jpg; convert $i (basename $i .jpg).png; end
# Convert all JPEG files in the current directory to the
# PNG format using the 'convert' program.

begin; set -l IFS; set data (cat data.txt); end
# Set the `data` variable to the contents of 'data.txt'
# without splitting it into an array.

توسيع الأوتار

سيتم توسيع قائمة أحرف مفصولة بفواصل داخل الأقواس المتعرجة بحيث يصبح كل عنصر في القائمة معلمة جديدة.

أمثلة:

echo input.{c,h,txt}
# Outputs 'input.c input.h input.txt'

mv *.{c,h} src/
# Moves all files with the suffix '.c' or '.h' to the subdirectory src.

توسيع متغير

يتم توسيع علامة الدولار متبوعاً سلسلة من الأحرف إلى قيمة متغير shell بنفس الاسم. للحصول على مقدمة لمفهوم متغيرات shell ، اقرأ قسم متغيرات Shell .

توسيع المتغيرات غير معرفة والغير فارغة.

لفصل اسم متغير من النص ، قم بتضمين المتغير داخل علامات اقتباس مزدوجة أو أقواس.

أمثلة:

echo $HOME
# Prints the home directory of the current user.

echo $nonexistentvariable
# Prints no output.

echo The plural of $WORD is "$WORD"s
# Prints "The plural of cat is cats" when $WORD is set to cat.
echo The plural of $WORD is {$WORD}s
# ditto

لاحظ أنه بدون الأقواس أو الأقواس ، ستحاول الأسماك توسيع متغير يسمى $WORDs ، والذي قد لا يكون موجودًا.

يعمل بناء الجملة الأخير {$WORD} باستغلال توسعة الدعامة ؛ يجب أن تؤخذ الرعاية مع متغيرات صفيف صفر عنصر ومتغيرات غير محددة ، حيث يتم توسيع هذه كمنتج الديكارتية ، لذلك القضاء على السلسلة.

التوسع المتغير هو النوع الوحيد للتوسع الذي يتم إجراؤه على السلاسل المزدوجة المقتبسة. There is, however, an important difference in how variables are expanded when quoted and when unquoted. An unquoted variable expansion will result in a variable number of arguments. For example, if the variable $foo has zero elements or is undefined, the argument $foo will expand to zero elements. If the variable $foo is an array of five elements, the argument $foo will expand to five elements. When quoted, like "$foo" , a variable expansion will always result in exactly one argument. Undefined variables will expand to the empty string, and array variables will be concatenated using the space character.

There is one further notable feature of fish variable expansion. Consider the following code snippet:

set foo a b c
set a 10; set b 20; set c 30
for i in (seq (count $$foo))
    echo $$foo[$i]
end

# Output is:
# 10
# 20
# 30

The above code demonstrates how to use multiple ' $ ' symbols to expand the value of a variable as a variable name. One can think of the $ symbol as a variable dereference operator. When using this feature together with array brackets, the brackets will always match the innermost $ dereference. Thus, $$foo[5] will always mean the fifth element of the foo variable should be dereferenced, not the fifth element of the doubly dereferenced variable foo . The latter can instead be expressed as $$foo[1][5] .

Cartesian Products

Lists adjacent to other lists or strings are expanded as cartesian products:

أمثلة:

> echo {good,bad}" apples"
good apples bad apples

> set -l a x y z
> set -l b 1 2 3

> echo $a$b
x1 y1 z1 x2 y2 z2 x3 y3 z3

> echo $a"-"$b
x-1 y-1 z-1 x-2 y-2 z-2 x-3 y-3 z-3

> echo {x,y,z}$b
x1 y1 z1 x2 y2 z2 x3 y3 z3

> echo {$b}word
1word 2word 3word

Be careful when you try to use braces to separate variable names from text. The dangers noted in the last example above can be avoided by wrapping the variable in double quotes instead of braces ( echo "$b"word ).

Index range expansion

Both command substitution and shell variable expansion support accessing only specific items by providing a set of indices in square brackets. It's often needed to access a sequence of elements. To do this, use the range operator ' .. ' for this. A range ' a..b ', where range limits 'a' and 'b' are integer numbers, is expanded into a sequence of indices ' a a+1 a+2 ... b ' or ' a a-1 a-2 ... b ' depending on which of 'a' or 'b' is higher. The negative range limits are calculated from the end of the array or command substitution. Note that invalid indexes for either end are silently clamped to one or the size of the array as appropriate.

Some examples:

# Limit the command substitution output
echo (seq 10)[2..5]
# Uses elements from 2 to 5
# Output is: 2 3 4 5

# Use overlapping ranges:
echo (seq 10)[2..5 1..3]
# Takes elements from 2 to 5 and then elements from 1 to 3
# Output is: 2 3 4 5 1 2 3

# Reverse output
echo (seq 10)[-1..1]
# Uses elements from the last output line to
# the first one in reverse direction
# Output is: 10 9 8 7 6 5 4 3 2 1

The same works when setting or expanding variables:

# Reverse path variable
set PATH $PATH[-1..1]
# or
set PATH[-1..1] $PATH

# Use only n last items of the PATH
set n -3
echo $PATH[$n..-1]

Note that variables can be used as indices for expansion of variables, but not command substitution.

Home directory expansion

The ~ (tilde) character at the beginning of a parameter, followed by a username, is expanded into the home directory of the specified user. A lone ~ , or a ~ followed by a slash, is expanded into the home directory of the process owner.

Process expansion

The % (percent) character at the beginning of a parameter followed by a string is expanded into a process ID (PID). The following expansions are performed:

  • If the string is the entire word self , the shell's PID is the result.
  • Otherwise, if the string is the entire word last , the last job's PID is the result.
  • Otherwise, if the string is the ID of a job, the result is the process group ID of the job.
  • Otherwise, if any child processes match the specified string, their PIDs are the result of the expansion.
  • Otherwise, if any processes owned by the user match the specified string, their PIDs are the result of the expansion.
  • If none of these matches apply, an error is produced.

This form of expansion is useful for commands like kill and fg, which take process IDs as arguments.

مثال:

fg %ema will search for a process whose command line begins with the letters 'ema', such as emacs, and if found, put it in the foreground.

kill -s SIGINT %3 will send the SIGINT signal to the job with job ID 3.

Combining different expansions

All of the above expansions can be combined. If several expansions result in more than one parameter, all possible combinations are created.

When combining multiple parameter expansions, expansions are performed in the following order:

  • Command substitutions
  • Variable expansions
  • Bracket expansion
  • Pid expansion
  • Wildcard expansion

Expansions are performed from right to left, nested bracket expansions are performed from the inside and out.

مثال:

If the current directory contains the files 'foo' and 'bar', the command echo a(ls){1,2,3} will output 'abar1 abar2 abar3 afoo1 afoo2 afoo3'.

Shell variable and function names

The names given to shell objects such as variables and function names are known as "identifiers". Each type of identifier has rules that define the valid sequence of characters which compose the identifier.

A variable name cannot be empty. It can contain only letters, digits, and underscores. It may begin and end with any of those characters.

A function name cannot be empty. It may not begin with a hyphen ("-") and may not contain a slash ("/"). All other characters, including a space, are valid.

A bind mode name (eg, bind -m abc ... ) is restricted to the rules for valid variable names.

Shell variables

Shell variables are named pieces of data, which can be created, deleted and their values changed and used by the user. Variables may optionally be "exported", so that a copy of the variable is available to any subprocesses the shell creates. An exported variable is referred to as an "environment variable".

To set a variable value, use the set . A variable name can not be empty and can contain only letters, digits, and underscores. It may begin and end with any of those characters.

مثال:

To set the variable smurf_color to the value blue , use the command set smurf_color blue .

After a variable has been set, you can use the value of a variable in the shell through variable expansion .

مثال:

To use the value of the variable smurf_color , write $ (dollar symbol) followed by the name of the variable, like echo Smurfs are usually $smurf_color , which would print the result 'Smurfs are usually blue'.

Variable scope

There are three kinds of variables in fish: universal, global and local variables. Universal variables are shared between all fish sessions a user is running on one computer. Global variables are specific to the current fish session, but are not associated with any specific block scope, and will never be erased unless the user explicitly requests it using set -e . Local variables are specific to the current fish session, and associated with a specific block of commands, and is automatically erased when a specific block goes out of scope. A block of commands is a series of commands that begins with one of the commands for , while , if , function , begin or switch , and ends with the command end . The user can specify that a variable should have either global or local scope using the -g/--global or -l/--local switches.

Variables can be explicitly set to be universal with the -U or --universal switch, global with the -g or --global switch, or local with the -l or --local switch. The scoping rules when creating or updating a variable are:

  1. If a variable is explicitly set to either universal, global or local, that setting will be honored. If a variable of the same name exists in a different scope, that variable will not be changed.
  2. If a variable is not explicitly set to be either universal, global or local, but has been previously defined, the variable scope is not changed.
  3. If a variable is not explicitly set to be either universal, global or local and has never before been defined, the variable will be local to the currently executing function. Note that this is different from using the -l or --local flag. If one of those flags is used, the variable will be local to the most inner currently executing block, while without these the variable will be local to the function. If no function is executing, the variable will be global.

There may be many variables with the same name, but different scopes. When using a variable, the variable scope will be searched from the inside out, ie a local variable will be used rather than a global variable with the same name, a global variable will be used rather than a universal variable with the same name.

مثال:

The following code will not output anything:

begin
    # This is a nice local scope where all variables will die
    set -l pirate 'There be treasure in them thar hills'
end

echo $pirate
# This will not output anything, since the pirate was local

More on universal variables

Universal variables are variables that are shared between all the users' fish sessions on the computer. Fish stores many of its configuration options as universal variables. This means that in order to change fish settings, all you have to do is change the variable value once, and it will be automatically updated for all sessions, and preserved across computer reboots and login/logout.

To see universal variables in action, start two fish sessions side by side, and issue the following command in one of them set fish_color_cwd blue . Since fish_color_cwd is a universal variable, the color of the current working directory listing in the prompt will instantly change to blue on both terminals.

Universal variables are stored in the file .config/fish/fishd.MACHINE_ID , where MACHINE_ID is typically your MAC address. Do not edit this file directly, as your edits may be overwritten. Edit them through fish scripts or by using fish interactively instead.

Do not append to universal variables in config.fish , because these variables will then get longer with each new shell instance. Instead, simply set them once at the command line.

Variable scope for functions

When calling a function, all current local variables temporarily disappear. This shadowing of the local scope is needed since the variable namespace would become cluttered, making it very easy to accidentally overwrite variables from another function.

فمثلا:

function shiver
    set phrase 'Shiver me timbers'
end

function avast
    set phrase 'Avast, mateys'
    # Calling the shiver function here can not
    # change any variables in the local scope
    shiver
    echo $phrase
end
avast

# Outputs "Avast, mateys"

Exporting variables

Variables in fish can be exported. This means the variable will be inherited by any commands started by fish. It is convention that exported variables are in uppercase and unexported variables are in lowercase.

Variables can be explicitly set to be exported with the -x or --export switch, or not exported with the -u or --unexport switch. The exporting rules when creating or updating a variable are identical to the scoping rules for variables:

  1. If a variable is explicitly set to either be exported or not exported, that setting will be honored.
  2. If a variable is not explicitly set to be exported or not exported, but has been previously defined, the previous exporting rule for the variable is kept.
  3. If a variable is not explicitly set to be either exported or not exported and has never before been defined, the variable will not be exported.

المصفوفات

fish can store a list of multiple strings inside of a variable. To access one element of an array, use the index of the element inside of square brackets, like this:

echo $PATH[3]

Note that array indices start at 1 in fish , not 0, as is more common in other languages. This is because many common Unix tools like seq are more suited to such use. An invalid index is silently ignored resulting in no value being substituted (not an empty string).

If you do not use any brackets, all the elements of the array will be written as separate items. This means you can easily iterate over an array using this syntax:

for i in $PATH; echo $i is in the path; end

To create a variable smurf , containing the items blue and small , simply write:

set smurf blue small

It is also possible to set or erase individual elements of an array:

# Set smurf to be an array with the elements 'blue' and 'small'
set smurf blue small

# Change the second element of smurf to 'evil'
set smurf[2] evil

# Erase the first element
set -e smurf[1]

# Output 'evil'
echo $smurf

If you specify a negative index when expanding or assigning to an array variable, the index will be calculated from the end of the array. For example, the index -1 means the last index of an array.

A range of indices can be specified, see index range expansion for details.

All arrays are one-dimensional and cannot contain other arrays, although it is possible to fake nested arrays using the dereferencing rules of variable expansion .

fish automatically creates arrays from the variables PATH , CDPATH and MANPATH when it is started. (Previous versions created arrays from all colon-delimited environment variables.)

Special variables

The user can change the settings of fish by changing the values of certain variables.

  • A large number of variable starting with the prefixes fish_color and fish_pager_color. See Variables for changing highlighting colors for more information.
  • fish_escape_delay_ms overrides the default timeout of 300ms (default key bindings) or 10ms (vi key bindings) after seeing an escape character before giving up on matching a key binding. See the documentation for the bind builtin command. This delay facilitates using escape as a meta key.
  • fish_greeting , the greeting message printed on startup.
  • fish_history , the current history session name. If set, all subsequent commands within an interactive fish session will be logged to a separate file identified by the value of the variable. If unset, or set to default , the default session name "fish" is used. If set to an empty string, history is not saved to disk (but is still available within the interactive session).
  • fish_user_paths , an array of directories that are prepended to PATH . This can be a universal variable.
  • umask , the current file creation mask. The preferred way to change the umask variable is through the umask function . An attempt to set umask to an invalid value will always fail.
  • BROWSER , the user's preferred web browser. If this variable is set, fish will use the specified browser instead of the system default browser to display the fish documentation.
  • CDPATH , an array of directories in which to search for the new directory for the cd builtin.
  • LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES , LC_MONETARY , LC_NUMERIC and LC_TIME set the language option for the shell and subprograms. See the section Locale variables for more information.
  • PATH , an array of directories in which to search for commands

fish also sends additional information to the user through the values of certain environment variables. The user cannot change the values of most of these variables.

  • _ , the name of the currently running command.
  • argv , an array of arguments to the shell or function. argv is only defined when inside a function call, or if fish was invoked with a list of arguments, like fish myscript.fish foo bar . This variable can be changed by the user.
  • history , an array containing the last commands that were entered.
  • HOME , the user's home directory. This variable can be changed by the user.
  • IFS , the internal field separator that is used for word splitting with the read builtin . Setting this to the empty string will also disable line splitting in command substitution . This variable can be changed by the user.
  • PWD , the current working directory.
  • status , the exit status of the last foreground job to exit. If the job was terminated through a signal, the exit status will be 128 plus the signal number.
  • USER , the current username. This variable can be changed by the user.
  • CMD_DURATION , the runtime of the last command in milliseconds.
  • FISH_VERSION , the version of the currently running fish
  • SHLVL , the level of nesting of shells
  • COLUMNS and LINES , the current size of the terminal in height and width. These values are only used by fish if the operating system does not report the size of the terminal. Both variables must be set in that case otherwise a default of 80x24 will be used. They are updated when the window size changes.

The names of these variables are mostly derived from the csh family of shells and differ from the ones used by Bourne style shells such as bash.

Variables whose name are in uppercase are exported to the commands started by fish, while those in lowercase are not exported. This rule is not enforced by fish, but it is good coding practice to use casing to distinguish between exported and unexported variables. fish also uses several variables internally. Such variables are prefixed with the string __FISH or __fish. These should never be used by the user. Changing their value may break fish.

The status variable

Whenever a process exits, an exit status is returned to the program that started it (usually the shell). This exit status is an integer number, which tells the calling application how the execution of the command went. In general, a zero exit status means that the command executed without problem, but a non-zero exit status means there was some form of problem.

Fish stores the exit status of the last process in the last job to exit in the status variable.

If fish encounters a problem while executing a command, the status variable may also be set to a specific value:

  • 0 is generally the exit status of fish commands if they successfully performed the requested operation.
  • 1 is generally the exit status of fish commands if they failed to perform the requested operation.
  • 121 is generally the exit status of fish commands if they were supplied with invalid arguments.
  • 123 means that the command was not executed because the command name contained invalid characters.
  • 124 means that the command was not executed because none of the wildcards in the command produced any matches.
  • 125 means that while an executable with the specified name was located, the operating system could not actually execute the command.
  • 126 means that while a file with the specified name was located, it was not executable.
  • 127 means that no function, builtin or command with the given name could be located.

If a process exits through a signal, the exit status will be 128 plus the number of the signal.

Variables for changing highlighting colors

The colors used by fish for syntax highlighting can be configured by changing the values of a various variables. The value of these variables can be one of the colors accepted by the set_color command. The --bold or -b switches accepted by set_color are also accepted.

The following variables are available to change the highlighting colors in fish:

  • fish_color_normal , the default color
  • fish_color_command , the color for commands
  • fish_color_quote , the color for quoted blocks of text
  • fish_color_redirection , the color for IO redirections
  • fish_color_end , the color for process separators like ';' and '&'
  • fish_color_error , the color used to highlight potential errors
  • fish_color_param , the color for regular command parameters
  • fish_color_comment , the color used for code comments
  • fish_color_match , the color used to highlight matching parenthesis
  • fish_color_search_match , the color used to highlight history search matches
  • fish_color_operator , the color for parameter expansion operators like '*' and '~'
  • fish_color_escape , the color used to highlight character escapes like '\n' and '\x70'
  • fish_color_cwd , the color used for the current working directory in the default prompt
  • fish_color_autosuggestion , the color used for autosuggestions
  • fish_color_user , the color used to print the current username in some of fish default prompts
  • fish_color_host , the color used to print the current host system in some of fish default prompts
  • fish_color_cancel , the color for the '^C' indicator on a canceled command

Additionally, the following variables are available to change the highlighting in the completion pager:

  • fish_pager_color_prefix , the color of the prefix string, ie the string that is to be completed
  • fish_pager_color_completion , the color of the completion itself
  • fish_pager_color_description , the color of the completion description
  • fish_pager_color_progress , the color of the progress bar at the bottom left corner
  • fish_pager_color_secondary , the background color of the every second completion

مثال:

To make errors highlighted and red, use:

set fish_color_error red --bold

Locale variables

The most common way to set the locale to use a command like 'set -x LANG en_GB.utf8', which sets the current locale to be the English language, as used in Great Britain, using the UTF-8 character set. For a list of available locales, use 'locale -a'.

LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES , LC_MONETARY , LC_NUMERIC and LC_TIME set the language option for the shell and subprograms. These variables work as follows: LC_ALL forces all the aspects of the locale to the specified value. If LC_ALL is set, all other locale variables will be ignored. The other LC_ variables set the specified aspect of the locale information. LANG is a fallback value, it will be used if none of the LC_ variables are specified.

Builtin commands

Many other shells have a large library of builtin commands. Most of these commands are also available as standalone commands, but have been implemented in the shell anyway. To avoid code duplication, and to avoid the confusion of subtly differing versions of the same command, fish generally only implements builtins for actions which cannot be performed by a regular command.

For a list of all builtins, functions and commands shipped with fish, see the table of contents . The documentation is also available by using the --help switch of the command.

Command line editor

The fish editor features copy and paste, a searchable history and many editor functions that can be bound to special keyboard shortcuts.

Similar to bash, fish has Emacs and Vi editing modes. The default editing mode is Emacs. You can switch to Vi mode with fish_vi_key_bindings and switch back with fish_default_key_bindings . You can also make your own key bindings by creating a function and setting $fish_key_bindings to its name. فمثلا:

function hybrid_bindings --description "Vi-style bindings that inherit emacs-style bindings in all modes"
    for mode in default insert visual
        fish_default_key_bindings -M $mode
    end
    fish_vi_key_bindings --no-erase
end
set -g fish_key_bindings hybrid_bindings

Shared bindings

Some bindings are shared between emacs- and vi-mode because they aren't text editing bindings or because what Vi/Vim does for a particular key doesn't make sense for a shell.

  • Tab completes the current token. Shift - Tab completes the current token and starts the pager's search mode.
  • Alt - and Alt - move the cursor one word left or right, or moves forward/backward in the directory history if the command line is empty. If the cursor is already at the end of the line, and an autosuggestion is available, Alt - (or Alt - F ) accepts the first word in the suggestion.
  • and (or Control - P and Control - N for emacs aficionados) search the command history for the previous/next command containing the string that was specified on the commandline before the search was started. If the commandline was empty when the search started, all commands match. See the history section for more information on history searching.
  • Alt - and Alt - search the command history for the previous/next token containing the token under the cursor before the search was started. If the commandline was not on a token when the search started, all tokens match. See the history section for more information on history searching.
  • Control - C cancels the entire line.
  • Control - D delete one character to the right of the cursor. If the command line is empty, Control - D will exit fish.
  • Control - U moves contents from the beginning of line to the cursor to the killring .
  • Control - L clears and repaints the screen.
  • Control - W moves the previous path component (everything up to the previous "/") to the killring .
  • Control - X copies the current buffer to the system's clipboard, Control - V inserts the clipboard contents.
  • Alt - d moves the next word to the killring .
  • Alt - h (or F1 ) shows the manual page for the current command, if one exists.
  • Alt - l lists the contents of the current directory, unless the cursor is over a directory argument, in which case the contents of that directory will be listed.
  • Alt - p adds the string ' | less; ' to the end of the job under the cursor. The result is that the output of the command will be paged.
  • Alt - w prints a short description of the command under the cursor.
  • Alt - e edit the current command line in an external editor. The editor is chosen from the first available of the $VISUAL or $EDITOR variables.
  • Alt - v Same as Alt - e .

Emacs mode commands

  • Home or Control - A moves the cursor to the beginning of the line.
  • End or Control - E moves to the end of line. If the cursor is already at the end of the line, and an autosuggestion is available, End or Control - E accepts the autosuggestion.
  • (or Control - B ) and (or Control - F ) move the cursor left or right by one character. If the cursor is already at the end of the line, and an autosuggestion is available, the key and the Control - F combination accept the suggestion.
  • Delete and Backspace removes one character forwards or backwards respectively.
  • Control - K moves contents from the cursor to the end of line to the killring .
  • Alt - c capitalizes the current word.
  • Alt - u makes the current word uppercase.
  • Control - t transposes the last two characters
  • Alt - t transposes the last two words

You can change these key bindings using the bind builtin command.

Vi mode commands

Vi mode allows for the use of Vi-like commands at the prompt. Initially, insert mode is active. Escape enters command mode . The commands available in command, insert and visual mode are described below. Vi mode shares some bindings with Emacs mode .

It is also possible to add all emacs-mode bindings to vi-mode by using something like

function fish_user_key_bindings
    # Execute this once per mode that emacs bindings should be used in
    fish_default_key_bindings -M insert
    # Without an argument, fish_vi_key_bindings will default to
    # resetting all bindings.
    # The argument specifies the initial mode (insert, "default" or visual).
    fish_vi_key_bindings insert
end

When in vi-mode, the fish_mode_prompt function will display a mode indicator to the left of the prompt. The fish_vi_cursor function will be used to change the cursor's shape depending on the mode in supported terminals. To disable this feature, override it with an empty function. To display the mode elsewhere (like in your right prompt), use the output of the fish_default_mode_prompt function.

Command mode

Command mode is also known as normal mode.

  • h moves the cursor left.
  • l moves the cursor right.
  • i enters insert mode at the current cursor position.
  • v enters visual mode at the current cursor position.
  • a enters insert mode after the current cursor position.
  • Shift - A enters insert mode at the end of the line.
  • 0 (zero) moves the cursor to beginning of line (remaining in command mode).
  • d d deletes the current line and moves it to the killring .
  • Shift - D deletes text after the current cursor position and moves it to the killring .
  • p pastes text from the killring .
  • u search history backwards.
  • [ and ] search the command history for the previous/next token containing the token under the cursor before the search was started. See the history section for more information on history searching.
  • Backspace moves the cursor left.

Insert mode

  • Escape enters command mode .
  • Backspace removes one character to the left.

Visual mode

  • and extend the selection backward/forward by one character.
  • b and w extend the selection backward/forward by one word.
  • d and x move the selection to the killring and enter command mode .
  • Escape and Control - C enter command mode .

Copy and paste (Kill Ring)

fish uses an Emacs style kill ring for copy and paste functionality. Use Control - K to cut from the current cursor position to the end of the line. The string that is cut (aka killed) is inserted into a linked list of kills, called the kill ring. To paste the latest value from the kill ring use Control - Y . After pasting, use Alt - Y to rotate to the previous kill.

Copy and paste from outside are also supported, both via the Control - X / Control - V bindings and via the terminal's paste function, for which fish enables "Bracketed Paste Mode". When pasting inside single quotes, pasted single quotes and backslashes are automatically escaped so that the result can be used as a single token simply by closing the quote after.

After a command has been entered, it is inserted at the end of a history list. Any duplicate history items are automatically removed. By pressing the up and down keys, the user can search forwards and backwards in the history. If the current command line is not empty when starting a history search, only the commands containing the string entered into the command line are shown.

By pressing Alt - and Alt - , a history search is also performed, but instead of searching for a complete commandline, each commandline is broken into separate elements just like it would be before execution, and the history is searched for an element matching that under the cursor.

History searches can be aborted by pressing the escape key.

Prefixing the commandline with a space will prevent the entire line from being stored in the history.

The command history is stored in the file ~/.local/share/fish/fish_history (or $XDG_DATA_HOME/fish/fish_history if that variable is set) by default. However, you can set the fish_history environment variable to change the name of the history session (resulting in a <session>_history file); both before starting the shell and while the shell is running.

أمثلة:

To search for previous entries containing the word 'make', type make in the console and press the up key.

If the commandline reads cd m , place the cursor over the m character and press Alt - to search for previously typed words containing 'm'.

Multiline editing

The fish commandline editor can be used to work on commands that are several lines long. There are three ways to make a command span more than a single line:

  • Pressing the Enter key while a block of commands is unclosed, such as when one or more block commands such as for , begin or if do not have a corresponding end command.
  • Pressing Alt - Enter instead of pressing the Enter key.
  • By inserting a backslash ( \ ) character before pressing the Enter key, escaping the newline.

The fish commandline editor works exactly the same in single line mode and in multiline mode. To move between lines use the left and right arrow keys and other such keyboard shortcuts.

Running multiple programs

Normally when fish starts a program, this program will be put in the foreground, meaning it will take control of the terminal and fish will be stopped until the program finishes. Sometimes this is not desirable. For example, you may wish to start an application with a graphical user interface from the terminal, and then be able to continue using the shell. In such cases, there are several ways in which the user can change fish's behavior.

  1. By ending a command with the & (ampersand) symbol, the user tells fish to put the specified command into the background. A background process will be run simultaneous with fish . fish will retain control of the terminal, so the program will not be able to read from the keyboard.
  2. By pressing Control - Z , the user stops a currently running foreground program and returns control to fish . Some programs do not support this feature, or remap it to another key. GNU Emacs uses Control - X z to stop running.
  3. By using the fg and bg builtin commands, the user can send any currently running job into the foreground or background.

Note that functions cannot be started in the background. Functions that are stopped and then restarted in the background using the bg command will not execute correctly.

Initialization files

On startup, Fish evaluates a number of configuration files, which can be used to control the behavior of the shell. The location of these configuration variables is controlled by a number of environment variables, and their default or usual location is given below.

Configuration files are evaluated in the following order:

  • Configuration shipped with fish, which should not be edited, in $__fish_datadir/config.fish (usually /usr/share/fish/config.fish ).
  • System-wide configuration files, where administrators can include initialization that should be run for all users on the system - similar to /etc/profile for POSIX-style shells - in $__fish_sysconfdir (usually /etc/fish/config.fish );
  • Configuration snippets in files ending in .fish , in the directories:

    • $XDG_CONFIG_HOME/fish/conf.d (by default, ~/.config/fish/conf.d/ )
    • $__fish_sysconfdir/conf.d (by default, /etc/fish/conf.d )
    • /usr/share/fish/vendor_conf.d (set at compile time; by default, $__fish_datadir/conf.d )

    If there are multiple files with the same name in these directories, only the first will be executed. They are executed in order of their filename, sorted (like globs) in a natural order (ie "01" sorts before "2").

  • User initialization, usually in ~/.config/fish/config.fish (controlled by the XDG_CONFIG_HOME environment variable).

These paths are controlled by parameters set at build, install, or run time, and may vary from the defaults listed above.

This wide search may be confusing. If you are unsure where to put your own customisations, use ~/.config/fish/config.fish .

Note that ~/.config/fish/config.fish is sourced after the snippets. This is so users can copy snippets and override some of their behavior.

These files are all executed on the startup of every shell. If you want to run a command only on starting an interactive shell, use the exit status of the command status --is-interactive to determine if the shell is interactive. If you want to run a command only when using a login shell, use status --is-login instead. This will speed up the starting of non-interactive or non-login shells.

If you are developing another program, you may wish to install configuration which is run for all users of the fish shell on a system. This is discouraged; if not carefully written, they may have side-effects or slow the startup of the shell. Additionally, users of other shells will not benefit from the Fish-specific configuration. However, if they are absolutely required, you may install them to the "vendor" configuration directory. As this path may vary from system to system, the pkgconfig framework should be used to discover this path with the output of pkg-config --variable confdir fish .

أمثلة:

If you want to add the directory ~/linux/bin to your PATH variable when using a login shell, add the following to your ~/.config/fish/config.fish file:

if status --is-login
    set -x PATH $PATH ~/linux/bin
end

If you want to run a set of commands when fish exits, use an event handler that is triggered by the exit of the shell:

function on_exit --on-process %self
    echo fish is now exiting
end

Other features

تسليط الضوء على تركيب

fish interprets the command line as it is typed and uses syntax highlighting to provide feedback to the user. The most important feedback is the detection of potential errors. By default, errors are marked red.

Detected errors include:

  • Non existing commands.
  • Reading from or appending to a non existing file.
  • Incorrect use of output redirects
  • Mismatched parenthesis

When the cursor is over a parenthesis or a quote, fish also highlights its matching quote or parenthesis.

To customize the syntax highlighting, you can set the environment variables listed in the Variables for changing highlighting colors section.

Programmable title

When using most virtual terminals, it is possible to set the message displayed in the titlebar of the terminal window. This can be done automatically in fish by defining the fish_title function. The fish_title function is executed before and after a new command is executed or put into the foreground and the output is used as a titlebar message. The $_ environment variable will always contain the name of the job to be put into the foreground (Or 'fish' if control is returning to the shell) when the fish_prompt function is called. The first argument to fish_title will contain the most recently executed foreground command as a string, starting with fish 2.2.

Examples: The default fish title is

function fish_title
    echo $_ ' '
    pwd
end

To show the last command in the title:

function fish_title
    echo $argv[1]
end

Programmable prompt

When fish waits for input, it will display a prompt by evaluating the fish_prompt and fish_right_prompt functions. The output of the former is displayed on the left and the latter's output on the right side of the terminal. The output of fish_mode_prompt will be prepended on the left, though the default function only does this when in vi-mode .

Configurable greeting

If a function named fish_greeting exists, it will be run when entering interactive mode. Otherwise, if an environment variable named fish_greeting exists, it will be printed.

Event handlers

When defining a new function in fish, it is possible to make it into an event handler, ie a function that is automatically run when a specific event takes place. Events that can trigger a handler currently are:

  • When a signal is delivered
  • When a process or job exits
  • When the value of a variable is updated
  • When the prompt is about to be shown
  • When a command lookup fails

مثال:

To specify a signal handler for the WINCH signal, write:

function --on-signal WINCH my_signal_handler
    echo Got WINCH signal!
end

Please note that event handlers only become active when a function is loaded, which means you might need to otherwise source or execute a function instead of relying on autoloading . One approach is to put it into your config.fish .

For more information on how to define new event handlers, see the documentation for the function command.

Debugging fish scripts

Fish includes a built in debugging facility. The debugger allows you to stop execution of a script at an arbitrary point. When this happens you are presented with an interactive prompt. At this prompt you can execute any fish command (there are no debug commands as such). For example, you can check or change the value of any variables using printf and set . As another example, you can run status print-stack-trace to see how this breakpoint was reached. To resume normal execution of the script, simply type exit or [ctrl-D].

To start a debug session simply run the builtin command breakpoint at the point in a function or script where you wish to gain control. Also, the default action of the TRAP signal is to call this builtin. So a running script can be debugged by sending it the TRAP signal with the kill command. Once in the debugger, it is easy to insert new breakpoints by using the funced function to edit the definition of a function.

Note: At the moment the debug prompt is identical to your normal fish prompt. This can make it hard to recognize that you've entered a debug session. Issue 1310 is open to improve this.

Common issues with fish

If you install fish in your home directory, fish will not work correctly for any other user than yourself. This is because fish needs its initialization files to function properly. To solve this problem, either copy the initialization files to each fish users home directory, or install them in /etc .

Further help and development

If you have a question not answered by this documentation, there are several avenues for help:

  1. The official mailing list at [email protected]
  2. The Internet Relay Chat channel, #fish on irc.oftc.net
  3. The project GitHub page

If you have an improvement for fish, you can submit it via the mailing list or the GitHub page.

原文