.\" Man page generated from reStructuredText .\" by the Docutils 0.23 manpage writer. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "FISH-COMPLETIONS" "1" "Sep 07, 2026" "4.9" "fish-shell" .SH "نام (NAME)" fish\-completions \- نحوه عملکرد و نوشتن تکمیل خودکار دستورات در پوسته fish .SH "توضیحات (DESCRIPTION)" .sp برای تعیین یک تکمیل خودکار، از دستور \fBcomplete\fP استفاده کنید. دستور \fBcomplete\fP نام دستوری را که می‌خواهید برای آن تکمیل مشخص کنید به عنوان پارامتر دریافت می‌کند. به عنوان مثال، برای افزودن یک تکمیل برای برنامه \fBmyprog\fP (یا \fBmyprog.exe\fP در Cygwin/MSYS2 \%<#\:completions-cygwin>)، دستور تکمیل را با \fBcomplete \-c myprog ...\fP آغاز کنید. .sp برای شرح کامل سوییچ‌های گوناگون پذیرفته‌شده توسط دستور \fBcomplete\fP، مستندات دستور توکار complete \%<> را مشاهده کنید یا در پوسته \fBfish\fP دستور \fBcomplete \-\-help\fP را اجرا کنید. .sp برای ارائه فهرستی از تکمیل‌های ممکن برای myprog، از سوییچ \fB\-a\fP استفاده کنید. اگر \fBmyprog\fP آرگومان‌های start و stop را می‌پذیرد، این موضوع را می‌توان به صورت \fBcomplete \-c myprog \-a \(aqstart stop\(aq\fP\& تعیین کرد. آرگومان سوییچ \fB\-a\fP همواره یک رشته واحد است. در زمان تکمیل، این رشته بر اساس فاصله‌ها و تب‌ها تفکیک (توکنایز) می‌شود و گسترش متغیرها، جایگزینی دستور و سایر اشکال بسط پارامتر اعمال خواهد شد: .INDENT 0.0 .INDENT 3.5 .sp .EX # اگر myprog بتواند خروجی‌های معتبر را با زیردستور list\-outputs فهرست کند: complete \-c myprog \-l output \-a \(aq(myprog list\-outputs)\(aq .EE .UNINDENT .UNINDENT .sp پوسته \fBfish\fP دارای نحو ویژه‌ای برای پشتیبانی از تعیین سوییچ‌های پذیرفته‌شده توسط یک دستور است. سوییچ‌های \fB\-s\fP، \fB\-l\fP و \fB\-o\fP به‌ترتیب برای تعیین یک سوییچ کوتاه (تک‌کاراکتری، مانند \fB\-l\fP)، یک سوییچ بلند به سبک گنو (مانند \fB\-\-color\fP) و یک سوییچ بلند به سبک قدیمی (با یک علامت \fB\-\fP، مانند \fB\-shuffle\fP) استفاده می‌شوند. اگر دستور \(aqmyprog\(aq گزینه‌ای دارد که می‌تواند به صورت \fB\-o\fP یا \fB\-\-output\fP نوشته شود، یعنی: .INDENT 0.0 .INDENT 3.5 .sp .EX complete \-c myprog \-s o \-l output .EE .UNINDENT .UNINDENT .sp اگر این گزینه یک آرگومان اختیاری می‌پذیرد، می‌توانید \fB\-\-argument\fP یا \fB\-a\fP را نیز اضافه کرده و آرگومان‌های ممکن را به آن اختصاص دهید: .INDENT 0.0 .INDENT 3.5 .sp .EX complete \-c myprog \-s o \-l output \-a \(dqyes no\(dq .EE .UNINDENT .UNINDENT .sp این دستور آرگومان‌های \(dqyes\(dq و \(dqno\(dq را برای موارد زیر پیشنهاد می‌دهد: .INDENT 0.0 .INDENT 3.5 .sp .EX > myprog \-o > myprog \-\-output= .EE .UNINDENT .UNINDENT .sp به‌طور پیش‌فرض، آرگومان‌های گزینه‌ها \fIاختیاری\fP هستند، بنابراین گزینه‌ها تنها در حالتی که مستقیماً به آن چسبیده‌اند پیشنهاد می‌شوند و در این حالت ارائه نخواهند شد: .INDENT 0.0 .INDENT 3.5 .sp .EX > myprog \-o .EE .UNINDENT .UNINDENT .sp معمولاً گزینه‌ها به یک پارامتر \fIنیاز دارند\fP، بنابراین می‌توانید از \fB\-\-require\-parameter\fP یا \fB\-r\fP استفاده کنید: .INDENT 0.0 .INDENT 3.5 .sp .EX complete \-c myprog \-s o \-l output \-ra \(dqyes no\(dq .EE .UNINDENT .UNINDENT .sp که در این حالت‌ها گزینه‌های yes/no را پیشنهاد می‌دهد: .INDENT 0.0 .INDENT 3.5 .sp .EX > myprog \-o > myprog \-\-output= > myprog \-o > myprog \-\-output .EE .UNINDENT .UNINDENT .sp پوسته fish همچنین علاوه بر آرگومان‌هایی که مشخص کرده‌اید، به‌طور پیش‌فرض فایل‌ها را نیز پیشنهاد می‌دهد. شما می‌توانید تکمیل فایل را برای یک گزینه خاص غیرفعال کنید: .INDENT 0.0 .INDENT 3.5 .sp .EX complete \-c myprog \-s o \-l output \-\-no\-files \-ra \(dqyes no\(dq .EE .UNINDENT .UNINDENT .sp یا با یک شرط خاص: .INDENT 0.0 .INDENT 3.5 .sp .EX complete \-c myprog \-f \-\-condition \(aq__fish_seen_subcommand_from somesubcommand\(aq .EE .UNINDENT .UNINDENT .sp یا می‌توانید تکمیل فایل را به‌طور سراسری برای کل دستور غیرفعال کنید: .INDENT 0.0 .INDENT 3.5 .sp .EX complete \-c myprog \-f .EE .UNINDENT .UNINDENT .sp اگر تکمیل فایل را به‌طور سراسری غیرفعال کرده‌اید، می‌توانید آن را فقط برای یک شرط یا گزینه خاص با استفاده از گزینه \fB\-\-force\-files\fP یا \fB\-F\fP دوباره فعال کنید: .INDENT 0.0 .INDENT 3.5 .sp .EX # غیرفعال کردن فایل‌ها به‌طور پیش‌فرض complete \-c myprog \-f # اما فعال‌سازی دوباره آن‌ها برای \-\-config\-file complete \-c myprog \-l config\-file \-\-force\-files \-r .EE .UNINDENT .UNINDENT .sp به عنوان یک مثال جامع‌تر، در اینجا بخشی از تکمیل‌های دستور \fBtimedatectl\fP در systemd همراه با توضیحات آورده شده است: .INDENT 0.0 .INDENT 3.5 .sp .EX # تمام زیردستورهایی که timedatectl می‌شناسد \- این مورد برای مراحل بعدی مفید است. set \-l commands status set\-time set\-timezone list\-timezones set\-local\-rtc set\-ntp # غیرفعال کردن تکمیل فایل برای کل دستور # زیرا در هیچ بخشی فایلی دریافت نمی‌کند # توجه داشته باشید که این کار با استفاده از \(dq\-F\(dq قابل بازگشت است. # # همچنین در صورتی که بخواهید کنترل بیشتری بر نوع فایل‌های پیشنهادی داشته باشید # (مثلاً فقط دایرکتوری‌ها، یا فقط فایل‌هایی با پسوند \(dq.mp3\(dq)، تکمیل فایل باید غیرفعال شود. complete \-c timedatectl \-f # این خط زیردستورهای # \-\(dqstatus\(dq، # \-\(dqset\-timezone\(dq، # \-\(dqset\-time\(dq # \-\(dqlist\-timezones\(dq # را در صورتی که تاکنون زیردستوری وارد نشده باشد، پیشنهاد می‌دهد. # # گزینه \(ga\-n\(ga/\(ga\-\-condition\(ga اسکریپتی را در قالب رشته دریافت و آن را اجرا می‌کند. # اگر مقدار درستی (true) برگرداند، تکمیل پیشنهاد داده می‌شود. # در اینجا شرط، تابع کمکی \(ga__fish_seen_subcommand_from\(ga است. # این تابع اگر هر یک از دستورات داده‌شده در خط فرمان استفاده شده باشد (بر اساس یک روش تقریبی ساده)، مقدار درستی برمی‌گرداند. # برای کاربردهای پیچیده‌تر، می‌توانید تابع خود را بنویسید. # برای نمونه، تکمیل‌های git را ببینید. # complete \-c timedatectl \-n \(dqnot __fish_seen_subcommand_from $commands\(dq \e \-a \(dqstatus set\-time set\-timezone list\-timezones\(dq # اگر زیردستور \(dqset\-timezone\(dq استفاده شده باشد، # خروجی \(gatimedatectl list\-timezones\(ga را به عنوان تکمیل پیشنهاد می‌دهد. # هر خط از خروجی به عنوان یک نامزد جداگانه استفاده می‌شود، # و هر چیزی پس از تب به عنوان توضیحات در نظر گرفته می‌شود. # تبدیل خروجی دستور به این شکل با استفاده از \(gastring\(ga اغلب بسیار مفید است. complete \-c timedatectl \-n \(dq__fish_seen_subcommand_from set\-timezone\(dq \e \-a \(dq(timedatectl list\-timezones)\(dq # نامزدهای تکمیل را می‌توان از طریق \(ga\-d\(ga نیز توصیف کرد، # که اگر توضیحات ثابت باشد، بسیار مفید است. # سعی کنید این توضیحات را کوتاه نگه دارید، زیرا باعث می‌شود کاربر موارد بیشتری را به طور همزمان ببیند. complete \-c timedatectl \-n \(dqnot __fish_seen_subcommand_from $commands\(dq \e \-a \(dqset\-local\-rtc\(dq \-d \(dqMaintain RTC in local time\(dq # همچنین می‌توانیم با استفاده از شرایط، گزینه‌ها را به زیردستورهای خاصی محدود کنیم. complete \-c timedatectl \-n \(dq__fish_seen_subcommand_from set\-local\-rtc\(dq \e \-l adjust\-system\-clock \-d \(aqSynchronize system clock from the RTC\(aq # این‌ها گزینه‌های ساده‌ای هستند که در همه‌جا می‌توانند استفاده شوند. complete \-c timedatectl \-s h \-l help \-d \(aqPrint a short help text and exit\(aq complete \-c timedatectl \-l version \-d \(aqPrint a short version string and exit\(aq complete \-c timedatectl \-l no\-pager \-d \(aqDo not pipe output into a pager\(aq .EE .UNINDENT .UNINDENT .sp برای مشاهده نمونه‌هایی از نحوه نوشتن تکمیل‌های خود، مسیر \fBshare/completions\fP را در درخت کد مبدا fish\-shell بررسی کنید. .SH "توابع کاربردی برای نوشتن تکمیل‌ها (USEFUL FUNCTIONS FOR WRITING COMPLETIONS)" .sp پوسته \fBfish\fP همراه با توابع متعددی ارائه می‌شود که هنگام نوشتن تکمیل‌های ویژه یک دستور می‌توانند مفید باشند. نام اکثر این توابع با رشته \fB__fish_\fP\& آغاز می‌شود. این‌گونه توابع درونی \fBfish\fP هستند و نام یا رابط آن‌ها ممکن است در نسخه‌های آینده fish تغییر کند. چند نمونه از این توابع در اینجا شرح داده شده‌اند. .sp توابعی که با رشته \fB__fish_print_\fP آغاز می‌شوند فهرستی از رشته‌ها را که با خط جدید از هم جدا شده‌اند چاپ می‌کنند. برای مثال، \fB__fish_print_filesystems\fP فهرستی از تمامی سیستم‌فایل‌های شناخته‌شده را چاپ می‌کند. توابعی که با \fB__fish_complete_\fP شروع می‌شوند فهرستی از تکمیل‌ها را به همراه توضیحات با خط جدید چاپ می‌کنند. توضیحات با کاراکتر تب از تکمیل جدا می‌شوند. .INDENT 0.0 .IP \(bu 2 \fB__fish_complete_directories STRING DESCRIPTION\fP تکمیل مسیر را روی STRING انجام می‌دهد و فقط دایرکتوری‌ها را مجاز دانسته و توضیحات DESCRIPTION را به آن‌ها اختصاص می‌دهد. .IP \(bu 2 \fB__fish_complete_path STRING DESCRIPTION\fP تکمیل مسیر را روی STRING انجام می‌دهد و توضیحات DESCRIPTION را به آن‌ها اختصاص می‌دهد. .IP \(bu 2 \fB__fish_complete_groups\fP فهرستی از تمام گروه‌های کاربری را همراه با اعضای هر گروه به عنوان توضیحات چاپ می‌کند. .IP \(bu 2 \fB__fish_complete_pids\fP فهرستی از شناسه تمام فرآیندها (PID) را همراه با نام دستور به عنوان توضیحات چاپ می‌کند. .IP \(bu 2 \fB__fish_complete_suffix SUFFIX\fP تکمیل فایل را انجام می‌دهد اما فایل‌هایی را که به SUFFIX ختم می‌شوند در ابتدا مرتب می‌کند. این تابع در ترکیب با \fBcomplete \-\-keep\-order\fP\& مفید است. .IP \(bu 2 \fB__fish_complete_users\fP فهرستی از تمام کاربران را همراه با نام کاملشان به عنوان توضیحات چاپ می‌کند. .IP \(bu 2 \fB__fish_print_filesystems\fP فهرستی از تمامی سیستم‌فایل‌های شناخته‌شده را چاپ می‌کند. در حال حاضر، این یک فهرست ایستا است و به اینکه سیستم‌عامل میزبان چه سیستم‌فایل‌هایی را عملاً پشتیبانی می‌کند وابسته نیست. .IP \(bu 2 \fB__fish_print_hostnames\fP فهرستی از تمام نام‌های میزبان (hostname) شناخته‌شده را چاپ می‌کند. این تابع فایل fstab را برای سرورهای nfs و ssh را برای میزبان‌های شناخته‌شده جستجو کرده و فایل \fB/etc/hosts\fP را بررسی می‌کند. .IP \(bu 2 \fB__fish_print_interfaces\fP فهرستی از تمام رابط‌های شبکه شناخته‌شده را چاپ می‌کند. .UNINDENT .SH "محل قرار دادن فایل‌های تکمیل (WHERE TO PUT COMPLETIONS)" .sp تکمیل‌ها را می‌توان در خط فرمان یا در یک فایل پیکربندی تعریف کرد، اما آن‌ها همچنین می‌توانند به صورت خودکار بارگذاری شوند. پوسته fish به‌طور خودکار در تمام دایرکتوری‌های موجود در متغیر فهرستی \fB$fish_complete_path\fP جستجو می‌کند و هر تکمیلی که تعریف شده باشد در زمان نیاز به‌صورت خودکار بارگذاری می‌شود. نام فایل تکمیل باید متشکل از نام دستور مورد نظر برای تکمیل و پسوند \fB\&.fish\fP باشد. .sp به‌طور پیش‌فرض، fish برای یافتن تکمیل‌ها مسیرهای زیر را جستجو می‌کند و از اولین فایل در دسترس که پیدا کند بهره می‌برد: .INDENT 0.0 .IP \(bu 2 یک دایرکتوری برای کاربران نهایی جهت نگهداری تکمیل‌های اختصاصی خود، معمولاً در \fB~/.config/fish/completions\fP (کنترل‌شده توسط متغیر محیطی \fBXDG_CONFIG_HOME\fP)؛ .IP \(bu 2 یک دایرکتوری برای مدیران سیستم جهت نصب تکمیل‌ها برای همه کاربران سیستم، معمولاً در \fB/etc/fish/completions\fP؛ .IP \(bu 2 یک دایرکتوری تعیین‌شده توسط کاربر برای تکمیل‌های ارائه‌دهندگان شخص ثالث، معمولاً در \fB~/.local/share/fish/vendor_completions.d\fP (کنترل‌شده توسط متغیر محیطی \fBXDG_DATA_HOME\fP)؛ .IP \(bu 2 یک دایرکتوری برای ارائه‌دهندگان نرم‌افزارهای شخص ثالث جهت ارائه تکمیل‌های نرم‌افزار خود، معمولاً در \fB/usr/share/fish/vendor_completions.d\fP؛ .IP \(bu 2 تکمیل‌های ارائه‌شده همراه با fish که درون برنامه fish ذخیره شده‌اند و با دستور \fBstatus list\-files\fP قابل مشاهده هستند؛ و .IP \(bu 2 تکمیل‌هایی که به‌طور خودکار از صفحات راهنمای سیستم‌عامل تولید می‌شوند و معمولاً در \fB~/.cache/fish/generated_completions\fP ذخیره می‌گردند (کنترل‌شده توسط متغیر محیطی \fBXDG_CACHE_HOME\fP). .UNINDENT .sp این مسیرها توسط پارامترهایی که در زمان ساخت، نصب یا اجرا تنظیم می‌شوند کنترل می‌گردند و ممکن است با مقادیر پیش‌فرض فهرست‌شده در بالا تفاوت داشته باشند. .sp این گستردگی جستجو ممکن است گیج‌کننده باشد. اگر مطمئن نیستید، تکمیل‌های شما احتمالاً به \fB~/.config/fish/completions\fP\& تعلق دارند. .sp اگر تکمیل‌های جدیدی برای یک دستور رایج یونیکس نوشته‌اید، لطفاً با ارسال آن طبق دستورالعمل‌های بخش راهنمایی و توسعه بیشتر \%<#\:more-help>\&، کار خود را به اشتراک بگذارید. .sp اگر در حال توسعه برنامه دیگری هستید و مایلید تکمیل‌ها را به همراه برنامه خود عرضه کنید، آن‌ها را در دایرکتوری تکمیل‌های «فروشنده» (vendor) نصب نمایید. از آنجا که این مسیر ممکن است در سیستم‌های مختلف متفاوت باشد، باید از چارچوب \fBpkgconfig\fP برای یافتن این مسیر با استفاده از خروجی دستور \fBpkg\-config \-\-variable completionsdir fish\fP\& استفاده شود. .SH "نویسنده (AUTHOR)" توسعه‌دهندگان fish-shell .SH "حق نشر (COPYRIGHT)" توسعه‌دهندگان fish-shell .\" End of generated man page.