FISH-COMPLETIONS(1) fish-shell FISH-COMPLETIONS(1)

fish-completions - نحوه عملکرد و نوشتن تکمیل خودکار دستورات در پوسته fish

برای تعیین یک تکمیل خودکار، از دستور complete استفاده کنید. دستور complete نام دستوری را که می‌خواهید برای آن تکمیل مشخص کنید به عنوان پارامتر دریافت می‌کند. به عنوان مثال، برای افزودن یک تکمیل برای برنامه myprog (یا myprog.exe در Cygwin/MSYS2 <#completions-cygwin>)، دستور تکمیل را با complete -c myprog ... آغاز کنید.

برای شرح کامل سوییچ‌های گوناگون پذیرفته‌شده توسط دستور complete، مستندات دستور توکار complete <> را مشاهده کنید یا در پوسته fish دستور complete --help را اجرا کنید.

برای ارائه فهرستی از تکمیل‌های ممکن برای myprog، از سوییچ -a استفاده کنید. اگر myprog آرگومان‌های start و stop را می‌پذیرد، این موضوع را می‌توان به صورت complete -c myprog -a 'start stop' تعیین کرد. آرگومان سوییچ -a همواره یک رشته واحد است. در زمان تکمیل، این رشته بر اساس فاصله‌ها و تب‌ها تفکیک (توکنایز) می‌شود و گسترش متغیرها، جایگزینی دستور و سایر اشکال بسط پارامتر اعمال خواهد شد:

# اگر myprog بتواند خروجی‌های معتبر را با زیردستور list-outputs فهرست کند:
complete -c myprog -l output -a '(myprog list-outputs)'

پوسته fish دارای نحو ویژه‌ای برای پشتیبانی از تعیین سوییچ‌های پذیرفته‌شده توسط یک دستور است. سوییچ‌های -s، -l و -o به‌ترتیب برای تعیین یک سوییچ کوتاه (تک‌کاراکتری، مانند -l)، یک سوییچ بلند به سبک گنو (مانند --color) و یک سوییچ بلند به سبک قدیمی (با یک علامت -، مانند -shuffle) استفاده می‌شوند. اگر دستور 'myprog' گزینه‌ای دارد که می‌تواند به صورت -o یا --output نوشته شود، یعنی:

complete -c myprog -s o -l output

اگر این گزینه یک آرگومان اختیاری می‌پذیرد، می‌توانید --argument یا -a را نیز اضافه کرده و آرگومان‌های ممکن را به آن اختصاص دهید:

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

این دستور آرگومان‌های "yes" و "no" را برای موارد زیر پیشنهاد می‌دهد:

> myprog -o<TAB>
> myprog --output=<TAB>

به‌طور پیش‌فرض، آرگومان‌های گزینه‌ها اختیاری هستند، بنابراین گزینه‌ها تنها در حالتی که مستقیماً به آن چسبیده‌اند پیشنهاد می‌شوند و در این حالت ارائه نخواهند شد:

> myprog -o <TAB>

معمولاً گزینه‌ها به یک پارامتر نیاز دارند، بنابراین می‌توانید از --require-parameter یا -r استفاده کنید:

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

که در این حالت‌ها گزینه‌های yes/no را پیشنهاد می‌دهد:

> myprog -o<TAB>
> myprog --output=<TAB>
> myprog -o <TAB>
> myprog --output <TAB>

پوسته fish همچنین علاوه بر آرگومان‌هایی که مشخص کرده‌اید، به‌طور پیش‌فرض فایل‌ها را نیز پیشنهاد می‌دهد. شما می‌توانید تکمیل فایل را برای یک گزینه خاص غیرفعال کنید:

complete -c myprog -s o -l output --no-files -ra "yes no"

یا با یک شرط خاص:

complete -c myprog -f --condition '__fish_seen_subcommand_from somesubcommand'

یا می‌توانید تکمیل فایل را به‌طور سراسری برای کل دستور غیرفعال کنید:

complete -c myprog -f

اگر تکمیل فایل را به‌طور سراسری غیرفعال کرده‌اید، می‌توانید آن را فقط برای یک شرط یا گزینه خاص با استفاده از گزینه --force-files یا -F دوباره فعال کنید:

# غیرفعال کردن فایل‌ها به‌طور پیش‌فرض
complete -c myprog -f
# اما فعال‌سازی دوباره آن‌ها برای --config-file
complete -c myprog -l config-file --force-files -r

به عنوان یک مثال جامع‌تر، در اینجا بخشی از تکمیل‌های دستور timedatectl در systemd همراه با توضیحات آورده شده است:

# تمام زیردستورهایی که timedatectl می‌شناسد - این مورد برای مراحل بعدی مفید است.
set -l commands status set-time set-timezone list-timezones set-local-rtc set-ntp
# غیرفعال کردن تکمیل فایل برای کل دستور
# زیرا در هیچ بخشی فایلی دریافت نمی‌کند
# توجه داشته باشید که این کار با استفاده از "-F" قابل بازگشت است.
#
# همچنین در صورتی که بخواهید کنترل بیشتری بر نوع فایل‌های پیشنهادی داشته باشید
# (مثلاً فقط دایرکتوری‌ها، یا فقط فایل‌هایی با پسوند ".mp3")، تکمیل فایل باید غیرفعال شود.
complete -c timedatectl -f
# این خط زیردستورهای
# -"status"،
# -"set-timezone"،
# -"set-time"
# -"list-timezones"
# را در صورتی که تاکنون زیردستوری وارد نشده باشد، پیشنهاد می‌دهد.
#
# گزینه `-n`/`--condition` اسکریپتی را در قالب رشته دریافت و آن را اجرا می‌کند.
# اگر مقدار درستی (true) برگرداند، تکمیل پیشنهاد داده می‌شود.
# در اینجا شرط، تابع کمکی `__fish_seen_subcommand_from` است.
# این تابع اگر هر یک از دستورات داده‌شده در خط فرمان استفاده شده باشد (بر اساس یک روش تقریبی ساده)، مقدار درستی برمی‌گرداند.
# برای کاربردهای پیچیده‌تر، می‌توانید تابع خود را بنویسید.
# برای نمونه، تکمیل‌های git را ببینید.
#
complete -c timedatectl -n "not __fish_seen_subcommand_from $commands" \
    -a "status set-time set-timezone list-timezones"
# اگر زیردستور "set-timezone" استفاده شده باشد،
# خروجی `timedatectl list-timezones` را به عنوان تکمیل پیشنهاد می‌دهد.
# هر خط از خروجی به عنوان یک نامزد جداگانه استفاده می‌شود،
# و هر چیزی پس از تب به عنوان توضیحات در نظر گرفته می‌شود.
# تبدیل خروجی دستور به این شکل با استفاده از `string` اغلب بسیار مفید است.
complete -c timedatectl -n "__fish_seen_subcommand_from set-timezone" \
    -a "(timedatectl list-timezones)"
# نامزدهای تکمیل را می‌توان از طریق `-d` نیز توصیف کرد،
# که اگر توضیحات ثابت باشد، بسیار مفید است.
# سعی کنید این توضیحات را کوتاه نگه دارید، زیرا باعث می‌شود کاربر موارد بیشتری را به طور همزمان ببیند.
complete -c timedatectl -n "not __fish_seen_subcommand_from $commands" \
    -a "set-local-rtc" -d "Maintain RTC in local time"
# همچنین می‌توانیم با استفاده از شرایط، گزینه‌ها را به زیردستورهای خاصی محدود کنیم.
complete -c timedatectl -n "__fish_seen_subcommand_from set-local-rtc" \
    -l adjust-system-clock -d 'Synchronize system clock from the RTC'
# این‌ها گزینه‌های ساده‌ای هستند که در همه‌جا می‌توانند استفاده شوند.
complete -c timedatectl -s h -l help -d 'Print a short help text and exit'
complete -c timedatectl -l version -d 'Print a short version string and exit'
complete -c timedatectl -l no-pager -d 'Do not pipe output into a pager'

برای مشاهده نمونه‌هایی از نحوه نوشتن تکمیل‌های خود، مسیر share/completions را در درخت کد مبدا fish-shell بررسی کنید.

پوسته fish همراه با توابع متعددی ارائه می‌شود که هنگام نوشتن تکمیل‌های ویژه یک دستور می‌توانند مفید باشند. نام اکثر این توابع با رشته __fish_ آغاز می‌شود. این‌گونه توابع درونی fish هستند و نام یا رابط آن‌ها ممکن است در نسخه‌های آینده fish تغییر کند. چند نمونه از این توابع در اینجا شرح داده شده‌اند.

توابعی که با رشته __fish_print_ آغاز می‌شوند فهرستی از رشته‌ها را که با خط جدید از هم جدا شده‌اند چاپ می‌کنند. برای مثال، __fish_print_filesystems فهرستی از تمامی سیستم‌فایل‌های شناخته‌شده را چاپ می‌کند. توابعی که با __fish_complete_ شروع می‌شوند فهرستی از تکمیل‌ها را به همراه توضیحات با خط جدید چاپ می‌کنند. توضیحات با کاراکتر تب از تکمیل جدا می‌شوند.

  • __fish_complete_directories STRING DESCRIPTION تکمیل مسیر را روی STRING انجام می‌دهد و فقط دایرکتوری‌ها را مجاز دانسته و توضیحات DESCRIPTION را به آن‌ها اختصاص می‌دهد.
  • __fish_complete_path STRING DESCRIPTION تکمیل مسیر را روی STRING انجام می‌دهد و توضیحات DESCRIPTION را به آن‌ها اختصاص می‌دهد.
  • __fish_complete_groups فهرستی از تمام گروه‌های کاربری را همراه با اعضای هر گروه به عنوان توضیحات چاپ می‌کند.
  • __fish_complete_pids فهرستی از شناسه تمام فرآیندها (PID) را همراه با نام دستور به عنوان توضیحات چاپ می‌کند.
  • __fish_complete_suffix SUFFIX تکمیل فایل را انجام می‌دهد اما فایل‌هایی را که به SUFFIX ختم می‌شوند در ابتدا مرتب می‌کند. این تابع در ترکیب با complete --keep-order مفید است.
  • __fish_complete_users فهرستی از تمام کاربران را همراه با نام کاملشان به عنوان توضیحات چاپ می‌کند.
  • __fish_print_filesystems فهرستی از تمامی سیستم‌فایل‌های شناخته‌شده را چاپ می‌کند. در حال حاضر، این یک فهرست ایستا است و به اینکه سیستم‌عامل میزبان چه سیستم‌فایل‌هایی را عملاً پشتیبانی می‌کند وابسته نیست.
  • __fish_print_hostnames فهرستی از تمام نام‌های میزبان (hostname) شناخته‌شده را چاپ می‌کند. این تابع فایل fstab را برای سرورهای nfs و ssh را برای میزبان‌های شناخته‌شده جستجو کرده و فایل /etc/hosts را بررسی می‌کند.
  • __fish_print_interfaces فهرستی از تمام رابط‌های شبکه شناخته‌شده را چاپ می‌کند.

تکمیل‌ها را می‌توان در خط فرمان یا در یک فایل پیکربندی تعریف کرد، اما آن‌ها همچنین می‌توانند به صورت خودکار بارگذاری شوند. پوسته fish به‌طور خودکار در تمام دایرکتوری‌های موجود در متغیر فهرستی $fish_complete_path جستجو می‌کند و هر تکمیلی که تعریف شده باشد در زمان نیاز به‌صورت خودکار بارگذاری می‌شود. نام فایل تکمیل باید متشکل از نام دستور مورد نظر برای تکمیل و پسوند .fish باشد.

به‌طور پیش‌فرض، fish برای یافتن تکمیل‌ها مسیرهای زیر را جستجو می‌کند و از اولین فایل در دسترس که پیدا کند بهره می‌برد:

  • یک دایرکتوری برای کاربران نهایی جهت نگهداری تکمیل‌های اختصاصی خود، معمولاً در ~/.config/fish/completions (کنترل‌شده توسط متغیر محیطی XDG_CONFIG_HOME)؛
  • یک دایرکتوری برای مدیران سیستم جهت نصب تکمیل‌ها برای همه کاربران سیستم، معمولاً در /etc/fish/completions؛
  • یک دایرکتوری تعیین‌شده توسط کاربر برای تکمیل‌های ارائه‌دهندگان شخص ثالث، معمولاً در ~/.local/share/fish/vendor_completions.d (کنترل‌شده توسط متغیر محیطی XDG_DATA_HOME)؛
  • یک دایرکتوری برای ارائه‌دهندگان نرم‌افزارهای شخص ثالث جهت ارائه تکمیل‌های نرم‌افزار خود، معمولاً در /usr/share/fish/vendor_completions.d؛
  • تکمیل‌های ارائه‌شده همراه با fish که درون برنامه fish ذخیره شده‌اند و با دستور status list-files قابل مشاهده هستند؛ و
  • تکمیل‌هایی که به‌طور خودکار از صفحات راهنمای سیستم‌عامل تولید می‌شوند و معمولاً در ~/.cache/fish/generated_completions ذخیره می‌گردند (کنترل‌شده توسط متغیر محیطی XDG_CACHE_HOME).

این مسیرها توسط پارامترهایی که در زمان ساخت، نصب یا اجرا تنظیم می‌شوند کنترل می‌گردند و ممکن است با مقادیر پیش‌فرض فهرست‌شده در بالا تفاوت داشته باشند.

این گستردگی جستجو ممکن است گیج‌کننده باشد. اگر مطمئن نیستید، تکمیل‌های شما احتمالاً به ~/.config/fish/completions تعلق دارند.

اگر تکمیل‌های جدیدی برای یک دستور رایج یونیکس نوشته‌اید، لطفاً با ارسال آن طبق دستورالعمل‌های بخش راهنمایی و توسعه بیشتر <#more-help>، کار خود را به اشتراک بگذارید.

اگر در حال توسعه برنامه دیگری هستید و مایلید تکمیل‌ها را به همراه برنامه خود عرضه کنید، آن‌ها را در دایرکتوری تکمیل‌های «فروشنده» (vendor) نصب نمایید. از آنجا که این مسیر ممکن است در سیستم‌های مختلف متفاوت باشد، باید از چارچوب pkgconfig برای یافتن این مسیر با استفاده از خروجی دستور pkg-config --variable completionsdir fish استفاده شود.

توسعه‌دهندگان fish-shell

توسعه‌دهندگان fish-shell

September 7, 2026 4.9