ZSHCOMPCTL(1) General Commands Manual ZSHCOMPCTL(1)

zshcompctl - کنترل و تکمیل خودکار برنامه‌ریزی‌پذیر در zsh

این نسخه از zsh دارای دو روش برای انجام تکمیل کلمات در خط فرمان است. کاربران جدید پوسته ممکن است ترجیح دهند از سیستم جدیدتر و قدرتمندتر مبتنی بر توابع پوسته استفاده کنند؛ این سیستم در zshcompsys(1) توضیح داده شده است، و مکانیزم‌های پایه‌ای پوسته که از آن پشتیبانی می‌کنند در zshcompwid(1) شرح داده شده‌اند. این مدخل راهنما دستور قدیمی‌تر compctl را تشریح می‌کند.

[ + options [ -x ... -- ] ... [+] ] [ command ... ]

رفتار تکمیل ویرایشگر را بر اساس مجموعه گزینه‌های ارائه شده در options کنترل می‌کند. دستورات مختلف ویرایش، به‌ویژه expand-or-complete-word (که معمولاً به کلید tab متصل است)، تلاش می‌کنند کلمه تایپ‌شده توسط کاربر را تکمیل کنند، در حالی که سایر دستورات، به‌ویژه delete-char-or-list (که معمولاً در حالت ویرایش EMACS به ^D متصل است)، گزینه‌های ممکن را فهرست می‌کنند؛ compctl مشخص می‌کند که این گزینه‌های ممکن چه مواردی باشند. آنها برای نمونه می‌توانند نام فایل‌ها (رایج‌ترین حالت و بنابراین پیش‌فرض)، متغیرهای پوسته، یا کلماتی از یک فهرست تعیین‌شده توسط کاربر باشند.

تکمیل آرگومان‌های یک دستور ممکن است برای هر دستور متفاوت باشد یا از مقدار پیش‌فرض استفاده کند. همچنین رفتار هنگام تکمیل خود کلمه دستور را می‌توان به طور جداگانه مشخص کرد. این موارد متناظر با فلگ‌ها و آرگومان‌های زیر هستند که همگی (به‌جز -L) می‌توانند با هر ترکیبی از گزینه‌های options که در ادامه در بخش «فلگ‌های گزینه‌ها» توضیح داده شده‌اند، ترکیب شوند:

command ...
تکمیل را برای دستورات نام‌برده کنترل می‌کند که باید در انتهای خط فرمان فهرست شوند. اگر تکمیل برای دستوری با نام مسیری شامل اسلش انجام شود و هیچ تعریفی برای تکمیل آن یافت نشود، جستجو با آخرین جزء مسیر دوباره تکرار می‌شود. اگر دستور با یک = شروع شود، تکمیل با نام مسیر دستور امتحان می‌شود.

هر یک از رشته‌های command می‌توانند الگوهایی به همان شکلی باشند که معمولاً برای تطبیق نام فایل‌ها استفاده می‌شود. این الگوها باید برای محافظت در برابر بسط فوری در کوتیشن قرار گیرند؛ به عنوان مثال رشته دستوری 'foo*' ترتیبی می‌دهد که کلمات هر دستوری که با foo شروع می‌شود تکمیل گردند. هنگامی که تکمیل فراخوانی می‌شود، تمام تکمیل‌های مبتنی بر الگو به ترتیب معکوس تعریفشان بررسی می‌شوند تا زمانی که یکی مطابقت یابد. به طور پیش‌فرض، تکمیل سپس به صورت عادی ادامه می‌یابد، یعنی پوسته تلاش می‌کند مطابقت‌های بیشتری برای دستور خاص موجود در خط فرمان تولید کند؛ با قرار دادن -tn در فلگ‌های تکمیل الگو می‌توان این رفتار را بازنویسی و متوقف کرد.

توجه داشته باشید که نام‌های مستعار پیش از تعیین نام دستور بسط می‌یابند، مگر اینکه گزینه COMPLETE_ALIASES تنظیم شده باشد. دستورات را نمی‌توان با فلگ‌های -C، -D یا -T ترکیب کرد.

تکمیل را هنگامی که خود کلمه دستور در حال تکمیل است کنترل می‌کند. اگر هیچ دستور compctl -C صادر نشده باشد، نام هر دستور اجرایی (چه در مسیر path باشد و چه مختص پوسته، مانند نام‌های مستعار یا توابع) تکمیل می‌شود.
رفتار پیش‌فرض تکمیل را برای آرگومان‌های دستوراتی که هیچ رفتار خاصی به آنها اختصاص داده نشده کنترل می‌کند. اگر هیچ دستور compctl -D صادر نشده باشد، نام فایل‌ها تکمیل می‌شوند.
فلگ‌های تکمیلی را ارائه می‌دهد که باید پیش از هر پردازش دیگری استفاده شوند، حتی پیش از پردازش compctlهای تعریف‌شده برای دستورات خاص. این ویژگی به‌ویژه هنگام ترکیب با تکمیل گسترش‌یافته (فلگ -x، بخش «تکمیل گسترش‌یافته» در زیر را ببینید) مفید است. با استفاده از این فلگ می‌توانید رفتار پیش‌فرضی را تعریف کنید که بدون استثنا بر تمام دستورات اعمال شود، یا می‌توانید رفتار استاندارد را برای تمامی دستورات تغییر دهید. برای مثال، اگر دسترسی شما به پایگاه داده کاربران بیش از حد کند است و/یا شامل کاربران بسیار زیادی است (به طوری که تکمیل پس از `~' بیش از حد کند و غیرقابل استفاده می‌شود)، می‌توانید از دستور زیر استفاده کنید:
compctl -T -x 's[~] C[0,[^/]#]' -k friends -S/ -tn

تا رشته‌های موجود در آرایه friends پس از `~' تکمیل شوند. آرگومان C[...] لازم است تا این شکل از تکمیل ~ پس از اتمام نام دایرکتوری امتحان نشود.

رفتار تکمیل موجود را به شکلی مناسب برای قرار دادن در اسکریپت راه‌اندازی فهرست می‌کند؛ رفتار فعلی تغییری نمی‌کند. هر ترکیبی از فرم‌های بالا، یا فلگ -M (که باید پس از فلگ -L بیاید) را می‌توان مشخص کرد، در غیر این صورت تمامی تکمیل‌های تعریف‌شده فهرست می‌شوند. هر فلگ دیگری که ارائه شود نادیده گرفته می‌شود.
اگر هیچ آرگومانی داده نشود، compctl تمامی تکمیل‌های تعریف‌شده را به صورت مختصر فهرست می‌کند؛ همراه با فهرستی از options، تمامی تکمیل‌هایی که آن فلگ‌ها برایشان تنظیم شده است (بدون احتساب تکمیل گسترش‌یافته) فهرست می‌شوند.

اگر فلگ + به تنهایی بیاید و بلافاصله پس از آن فهرست command قرار گیرد، رفتار تکمیل برای تمام دستورات موجود در این فهرست به حالت پیش‌فرض بازنشانی می‌شود. به عبارت دیگر، تکمیل در ادامه از گزینه‌های مشخص‌شده توسط فلگ -D استفاده خواهد کرد.

فرمی که در آن -M به عنوان نخستین و تنها گزینه آمده باشد، مشخصات تطبیق سراسری را تعریف می‌کند (نگاه کنید به zshcompwid). مشخصات تطبیق داده‌شده برای هر تلاش تکمیل استفاده خواهند شد (فقط هنگام استفاده از compctl، نه در سیستم جدید تکمیل) و به ترتیبی که تعریف شده‌اند بررسی می‌شوند تا زمانی که یکی حداقل یک تطابق ایجاد کند. برای مثال:

compctl -M '' 'm:{a-zA-Z}={A-Za-z}'

این دستور ابتدا تکمیل را بدون هیچ مشخصه تطبیق سراسری (رشته خالی) امتحان می‌کند و اگر تطابقی حاصل نشد، تکمیل غیرحساس به بزرگی و کوچکی حروف را امتحان خواهد کرد.

[ -fcFBdeaRGovNAIOPZEnbjrzu/12 ]
[ -k array ] [ -g globstring ] [ -s subststring ]
[ -K function ]
[ -Q ] [ -P prefix ] [ -S suffix ]
[ -W file-prefix ] [ -H num pattern ]
[ -q ] [ -X explanation ] [ -Y explanation ]
[ -y func-or-var ] [ -l cmd ] [ -h cmd ] [ -U ]
[ -t continue ] [ -J name ] [ -V name ]
[ -M match-spec ]

گزینه‌های options باقی‌مانده، نوع آرگومان‌های دستور را که در حین تکمیل باید جستجو شوند مشخص می‌کنند. هر ترکیبی از این فلگ‌ها را می‌توان مشخص کرد؛ نتیجه یک فهرست مرتب‌شده از تمامی گزینه‌های ممکن است. گزینه‌ها به شرح زیر هستند.

این فلگ‌ها فهرست‌های تکمیلی تولید می‌کنند که توسط خود پوسته ساخته می‌شوند:

-f
نام فایل‌ها و مسیرهای سیستم فایل.
-/
صرفاً مسیرهای سیستم فایل (دایرکتوری‌ها).
نام دستورات، شامل نام‌های مستعار، توابع پوسته، دستورات داخلی و کلمات کلیدی رزروشده.
نام توابع.
نام دستورات داخلی (builtins).
نام دستورات خارجی.
کلمات کلیدی رزروشده.
نام‌های مستعار.
نام‌های مستعار عادی (غیرسراسری).
نام‌های مستعار سراسری.
این گزینه می‌تواند با -F، -B، -w، -a، -R و -G ترکیب شود تا نام توابع، دستورات داخلی، کلمات رزروشده یا نام‌های مستعار غیرفعال‌شده به دست آید.
این گزینه (برای نمایش دستورات فعال) به صورت پیش‌فرض فعال است، اما ممکن است با -d ترکیب شود؛ -de در ترکیب با -F، -B، -w، -a، -R و -G نام توابع، دستورات داخلی، کلمات رزروشده یا نام‌های مستعار را صرف‌نظر از غیرفعال بودن یا نبودن آنها تکمیل می‌کند.
نام گزینه‌های پوسته (نگاه کنید به zshoptions(1)).
نام هر متغیر تعریف‌شده در پوسته.
نام پارامترهای اسکالر (غیرآرایه‌ای).
نام آرایه‌ها.
نام متغیرهای عددی صحیح.
نام متغیرهای فقط‌خواندنی.
نام پارامترهای مورد استفاده توسط پوسته (شامل پارامترهای ویژه).
نام پارامترهای ویژه پوسته.
نام متغیرهای محیطی.
دایرکتوری‌های نام‌گذاری‌شده.
نام کلیدهای مقیدشده (bindings).
نام کارها (jobs): اولین کلمه از خط فرمان رهبر کار. این گزینه همراه با دستور داخلی kill مفید است.
نام کارهای در حال اجرا.
نام کارهای تعلیق‌شده.
نام‌های کاربری.

این فلگ‌ها دارای آرگومان‌های ارائه‌شده توسط کاربر هستند تا نحوه تشکیل فهرست تکمیل‌ها را تعیین کنند:

-k array
نام‌هایی که از عناصر $array گرفته می‌شوند (توجه داشته باشید که `$' در خط فرمان ظاهر نمی‌شود). همچنین، خود آرگومان array می‌تواند مجموعه‌ای از مقادیر جداشده با فاصله یا کاما درون پرانتز باشد که در آن هر جداکننده‌ای را می‌توان با بک‌اسلش اسکیپ کرد؛ در این حالت آرگومان باید درون کوتیشن قرار گیرد. برای مثال:
compctl -k "(cputime filesize datasize stacksize
		       coredumpsize resident descriptors)" limit
رشته globstring با استفاده از الگویابی نام فایل بسط می‌یابد؛ باید درون کوتیشن قرار گیرد تا از بسط فوری محافظت شود. نام فایل‌های حاصل به عنوان گزینه‌های ممکن تکمیل در نظر گرفته می‌شوند. برای دایرکتوری‌ها به جای `*/' از `*(/)' استفاده کنید. پارامتر ویژه fignore بر فایل‌های حاصل اعمال نمی‌شود. می‌توان بیش از یک الگو را به صورت جداشده با فاصله ارائه کرد. (توجه داشته باشید که بسط کروشه بخشی از الگویابی globbing نیست. از نحو `(either|or)' برای تطبیق گزینه‌های انتخابی استفاده کنید.)
رشته subststring به کلمات تفکیک می‌شود و سپس این کلمات با استفاده از تمام مکانیزم‌های بسط پوسته بسط می‌یابند (نگاه کنید به zshexpn(1)). کلمات حاصل به عنوان گزینه‌های ممکن تکمیل در نظر گرفته می‌شوند. پارامتر ویژه fignore بر فایل‌های حاصل اعمال نمی‌شود. توجه داشته باشید که -g برای نام فایل‌ها سریع‌تر است.
تابع داده‌شده را برای دریافت تکمیل‌ها فرامی‌خواند. مگر اینکه نام تابع با زیرخط شروع شود، دو آرگومان به تابع ارسال می‌شود: پیشوند و پسوند کلمه‌ای که تکمیل روی آن انجام می‌شود؛ به عبارت دیگر نویسه‌های قبل از موقعیت مکان‌نما، و نویسه‌های از موقعیت مکان‌نما به بعد. کل خط فرمان را می‌توان با فلگ‌های -c و -l دستور داخلی read دریافت کرد. تابع باید متغیر reply را با آرایه‌ای حاوی گزینه‌های تکمیل (یک تکمیل در هر عنصر) تنظیم کند؛ توجه داشته باشید که reply نباید به صورت محلی در تابع تعریف شود. از درون چنین تابعی خط فرمان با فلگ‌های -c و -l دستور داخلی read قابل دسترسی است. برای مثال:
function whoson { reply=(`users`); }
compctl -K whoson talk

فقط کاربران واردشده به سیستم را بعد از `talk' تکمیل می‌کند. توجه داشته باشید که `whoson' باید یک آرایه برگرداند، بنابراین `reply=`users`' نادرست خواهد بود.

گزینه‌های ممکن تکمیل از num خط آخر تاریخچه گرفته می‌شوند. فقط کلماتی که با pattern مطابقت داشته باشند انتخاب می‌شوند. اگر num صفر یا منفی باشد کل تاریخچه جستجو می‌شود و اگر pattern یک رشته خالی باشد تمام کلمات انتخاب می‌شوند (مانند `*'). یک کاربرد متداول عبارت است از:
compctl -D -f + -H 0 ''

که باعث می‌شود در صورت عدم تطابق نام فایل، تکمیل در فهرست تاریخچه به دنبال کلمه بگردد.

این فلگ‌ها مستقیماً انواع نام‌های مورد نظر برای تکمیل را مشخص نمی‌کنند، بلکه گزینه‌هایی را که این کار را انجام می‌دهند دستکاری می‌کنند:

-Q
به پوسته دستور می‌دهد که نویسه‌های فرامعنایی (metacharacters) را در تکمیل‌های ممکن درون کوتیشن قرار ندهد. به طور معمول نتایج یک تکمیل همراه با قرار دادن نویسه‌های فرامعنایی در کوتیشن در خط فرمان درج می‌شوند تا به عنوان نویسه‌های عادی تفسیر شوند. این رفتار برای نام فایل‌ها و رشته‌های معمولی مناسب است. با این حال، برای کاربردهای ویژه، مانند درج یک عبارت با بک‌تیک از آرایه تکمیل (-k) به گونه‌ای که عبارت تا زمان اجرای کامل خط ارزیابی نشود، باید از این گزینه استفاده شود.
پیشوند prefix دقیقاً قبل از رشته تکمیل‌شده درج می‌شود؛ هر بخش اولیه‌ای که از قبل تایپ شده باشد تکمیل می‌شود و کل prefix برای مقاصد تکمیل نادیده گرفته می‌شود. برای مثال:
compctl -j -P "%" kill

یک `%' بعد از دستور kill درج می‌کند و سپس نام‌های کارها را تکمیل می‌نماید.

هنگامی که تکمیلی پیدا می‌شود، پسوند suffix بعد از رشته تکمیل‌شده درج می‌شود. در حالت تکمیل منویی، پسوند بلافاصله درج می‌گردد، اما همچنان می‌توان با فشردن مکرر همان کلید در فهرست تکمیل‌ها پیمایش کرد.
همراه با دایرکتوری file-prefix: برای تکمیل دستور، فایل، دایرکتوری و الگوهای جستجوی نام فایل (گزینه‌های -c، -f، -/، -g)، پیشوند فایل به صورت ضمنی در ابتدای نام تکمیل اضافه می‌شود. برای مثال:
compctl -/ -W ~/Mail maildirs

هر زیردایرکتوری را در هر عمقی در زیر دایرکتوری ~/Mail تکمیل می‌کند، هرچند که آن پیشوند در خط فرمان ظاهر نمی‌شود. همچنین file-prefix می‌تواند به شکلی باشد که توسط فلگ -k پذیرفته می‌شود، یعنی نام یک آرایه یا یک فهرست صریح درون پرانتز. در این حالت تمام دایرکتوری‌های موجود در فهرست برای تکمیل‌های ممکن جستجو خواهند شد.

اگر همراه با پسوندی که توسط گزینه -S مشخص شده استفاده شود، باعث می‌شود در صورتی که نویسه بعدی تایپ‌شده فاصله باشد یا چیزی درج نکند، یا اگر پسوند تنها از یک نویسه تشکیل شده باشد و نویسه بعدی تایپ‌شده همان نویسه باشد، پسوند حذف شود؛ این همان قاعده‌ای است که برای گزینه AUTO_REMOVE_SLASH استفاده می‌شود. این گزینه برای جداکننده‌های فهرست (مانند کاما، دونقطه و غیره) بیشترین کاربرد را دارد.
این گزینه محدوده کلمات خط فرمان را که به عنوان آرگومان در نظر گرفته می‌شوند محدود می‌کند. اگر با یکی از الگوهای تکمیل گسترش‌یافته `p[...]'، `r[...]' یا `R[...]' (بخش «تکمیل گسترش‌یافته» در زیر را ببینید) ترکیب شود، محدوده به دامنه آرگومان‌های مشخص‌شده در براکت‌ها محدود می‌شود. سپس تکمیل به گونه‌ای انجام می‌گیرد که گویی این موارد به عنوان آرگومان به دستور cmd ارائه‌شده به این گزینه داده شده‌اند. اگر رشته cmd خالی باشد، اولین کلمه در محدوده به عنوان نام دستور در نظر گرفته شده و تکمیل نام دستور روی اولین کلمه محدوده انجام می‌شود. برای مثال:
compctl -x 'r[-exec,;]' -l '' -- find

آرگومان‌های بین `-exec' و `;' بعدی (یا انتهای خط فرمان در صورت عدم وجود چنین رشته‌ای) را به گونه‌ای تکمیل می‌کند که گویی یک خط فرمان جداگانه هستند.

به طور معمول zsh رشته‌های داخل کوتیشن را به عنوان یک کل واحد تکمیل می‌کند. با این گزینه، می‌توان تکمیل را به صورت جداگانه روی بخش‌های مختلف چنین رشته‌هایی انجام داد. این گزینه شبیه به گزینه -l عمل می‌کند اما کد تکمیل را وادار می‌سازد روی بخش‌هایی از کلمه جاری که با فاصله جدا شده‌اند کار کند. این بخش‌ها به گونه‌ای تکمیل می‌شوند که گویی آرگومان‌های دستور داده‌شده در cmd هستند. اگر cmd رشته خالی باشد، بخش اول همانند -l به عنوان نام دستور تکمیل می‌شود.
از کل فهرست تکمیل‌های ممکن استفاده می‌کند، خواه واقعاً با کلمه موجود در خط فرمان مطابقت داشته باشند یا خیر. کلمه‌ای که تا این لحظه تایپ شده حذف خواهد شد. این گزینه بیشترین کاربرد را با تابعی دارد (ارائه‌شده با گزینه -K) که می‌تواند اجزای کلمه ارسال‌شده به آن را (یا از طریق فلگ‌های -c و -l دستور داخلی read) بررسی کند و از معیارهای خود برای تصمیم‌گیری در مورد موارد منطبق بهره گیرد. اگر هیچ تکمیلی وجود نداشته باشد، کلمه اصلی حفظ می‌شود. از آنجا که تکمیل‌های ممکن تولیدشده به ندرت پیشوندها و پسوندهای مشترک جالب توجهی دارند، در صورتی که AUTO_MENU تنظیم شده باشد و این فلگ استفاده شود، تکمیل منویی فوراً آغاز می‌گردد.
فهرست ارائه‌شده توسط func-or-var هر زمان که به فهرست کردن نیاز باشد به جای فهرست تکمیل‌ها نمایش داده می‌شود؛ تکمیل‌های واقعی که باید درج شوند تغییری نمی‌کنند. این مقدار به دو روش قابل ارائه است. ابتدا، اگر func-or-var با یک $ شروع شود، متغیری را تعریف می‌کند، یا اگر با پرانتز باز شروع شود یک آرایه صریح را مشخص می‌کند که حاوی فهرست است. ممکن است متغیر قبلاً با فراخوانی یک تابع با استفاده از گزینه -K مقداردهی شده باشد. در غیر این صورت، حاوی نام تابعی است که برای ایجاد این فهرست اجرا خواهد شد. تمام تکمیل‌های منطبق، از جمله پیشوندها و پسوندهای کاملاً بسط‌یافته، به عنوان فهرست آرگومان به تابع تحویل داده می‌شوند و تابع باید آرایه reply را با نتیجه تنظیم کند. در هر دو حالت، فهرست نمایشی تنها پس از ایجاد فهرست کاملی از موارد منطبق واکشی خواهد شد.

توجه داشته باشید که فهرست بازگردانده‌شده الزامی ندارد که حتی از نظر تعداد با مجموعه اصلی مطابقت‌ها همخوانی داشته باشد، و می‌تواند به جای آرایه به صورت یک اسکالر ارسال شود. در این حالت هیچ قالب‌بندی خاصی روی نویسه‌ها در خروجی اعمال نمی‌شود؛ به ویژه نویسه‌های خط جدید به صورت لغوی چاپ می‌شوند و در صورت وجود آنها خروجی ستونی غیرفعال می‌گردد.

هنگام تلاش برای تکمیل روی مجموعه جاری گزینه‌ها، متن explanation را چاپ می‌کند. عبارت `%n' در این رشته با تعداد مطابقت‌هایی که برای این رشته توضیحی اضافه شده‌اند جایگزین می‌شود. این توضیح تنها در صورتی ظاهر می‌شود که تکمیل امتحان شده باشد و تطابق یکتایی وجود نداشته باشد، یا هنگام فهرست کردن تکمیل‌ها. رشته‌های توضیحی همراه با مطابقت‌های گروه مشخص‌شده در کنار گزینه -X (با استفاده از گزینه -J یا -V) فهرست خواهند شد. اگر رشته توضیحی یکسانی به چند گزینه -X داده شود، این رشته تنها یک بار (برای هر گروه) ظاهر می‌شود و تعداد مطابقت‌های نمایش‌داده‌شده برای `%n' مجموع تمام مطابقت‌ها برای هر یک از این کاربردها خواهد بود. در هر صورت، رشته توضیحی تنها در صورتی نمایش داده می‌شود که حداقل یک تطابق برای آن رشته اضافه شده باشد.

توالی‌های %B، %b، %S، %s، %U و %u ویژگی‌های خروجی (بولد، برجسته و زیرخط) را مشخص می‌کنند، %F، %f، %K و %k رنگ‌های پیش‌زمینه و پس‌زمینه را تعیین می‌کنند، و %{...%} می‌تواند برای گنجاندن توالی‌های اسکیپ تحت‌اللفظی همانند اعلان‌ها به کار رود.

همانند -X است، به جز اینکه explanation ابتدا طبق قواعد معمول رشته‌ها در دابل‌کوتیشن بسط می‌یابد. این بسط پس از فراخوانی هرگونه تابع برای گزینه‌های -K یا -y انجام می‌شود که به آنها امکان مقداردهی متغیرها را می‌دهد.
رشته continue شامل نویسه‌ای است که مشخص می‌کند کدام مجموعه از فلگ‌های تکمیل باید در مرحله بعد استفاده شوند. کاربردهای آن عبارت است از:

(i) همراه با -T، یا هنگام بررسی فهرستی از تکمیل‌های مبتنی بر الگو، در حالتی که compctl پس از یافتن مطابقت‌ها معمولاً به پردازش عادی ادامه می‌دهد؛ با `-tn' می‌توان از این ادامه کار جلوگیری کرد.

(ii) همراه با فهرستی از گزینه‌های جایگزین جداشده با +، زمانی که compctl به طور معمول پس از تولید مطابقت توسط یکی از گزینه‌ها متوقف می‌شود. می‌توان آن را با افزودن `-t+' به فلگ‌های گزینه جایگزینِ قبل از `+' وادار کرد تا مجموعه بعدی تکمیل‌ها را بررسی کند.

(iii) در یک فهرست تکمیل گسترش‌یافته (در زیر ببینید)، جایی که compctl معمولاً تا زمان برقراری یک مجموعه از شرایط ادامه داده و سپس فقط از فلگ‌های بلافاصله پس از آن استفاده می‌کند. با `-t-'، دستور compctl به امتحان تکمیل‌های گسترش‌یافته پس از `-' بعدی ادامه می‌دهد؛ با `-tx' تکمیل را با فلگ‌های پیش‌فرض، به عبارت دیگر فلگ‌های قبل از `-x' امتحان خواهد کرد.

نام گروهی را مشخص می‌کند که مطابقت‌ها باید در آن قرار گیرند. گروه‌ها به طور جداگانه فهرست و مرتب می‌شوند؛ به همین ترتیب، تکمیل منویی گزینه‌های منطبق در گروه‌ها را به ترتیبی که گروه‌ها تعریف شده‌اند ارائه می‌دهد. اگر نام گروهی صراحتاً داده نشود، مطابقت‌ها در گروهی به نام default ذخیره می‌شوند. اولین باری که با یک نام گروه برخورد می‌شود، گروهی با آن نام ایجاد می‌گردد. پس از آن تمام مطابقت‌های دارای همان نام گروه در آن ذخیره می‌شوند.

این گزینه می‌تواند همراه با تکمیل‌های جایگزین غیرانحصاری مفید باشد. برای مثال در:

compctl -f -J files -t+ + -v -J variables foo

هم فایل‌ها و هم متغیرها گزینه‌های ممکن تکمیل هستند، چرا که -t+ باعث می‌شود هر دو مجموعه جایگزین‌های قبل و بعد از + به صورت همزمان در نظر گرفته شوند. با این حال به دلیل گزینه‌های -J، تمامی فایل‌ها پیش از تمام متغیرها فهرست می‌شوند.

مانند -J است، اما مطابقت‌های درون گروه در فهرست‌ها و در تکمیل منویی مرتب نخواهند شد. این گروه‌های مرتب‌نشده در فضای نام متفاوتی نسبت به گروه‌های مرتب‌شده قرار دارند، بنابراین گروه‌های تعریف‌شده به عنوان -J files و -V files متمایز هستند.
-1
اگر همراه با گزینه -V داده شود، باعث می‌شود تنها موارد تکراری متوالی در گروه حذف شوند. توجه داشته باشید که گروه‌های دارای این فلگ و فاقد آن در فضاهای نام متفاوتی قرار دارند.
-2
اگر همراه با گزینه -J یا -V داده شود، باعث می‌شود تمام موارد تکراری حفظ شوند. مجدداً، گروه‌های دارای این فلگ و فاقد آن در فضاهای نام متفاوتی هستند.
مشخصات کنترل تطبیق اضافی را تعریف می‌کند که تنها هنگام بررسی کلمات برای فهرست فلگ‌هایی که این فلگ در آن ظاهر می‌شود باید استفاده گردند. قالب رشته match-spec در zshcompwid توضیح داده شده است.

فرمی که شامل `+' است، گزینه‌های جایگزین را مشخص می‌کند. تکمیل ابتدا با گزینه‌های پیش از نخستین `+' امتحان می‌شود. اگر این کار تطابقی ایجاد نکرد، تکمیل با فلگ‌های پس از `+' امتحان می‌شود و به همین ترتیب ادامه می‌یابد. اگر پس از آخرین `+' فلگی وجود نداشته باشد و تا آن نقطه تطابقی پیدا نشده باشد، تکمیل پیش‌فرض امتحان می‌شود. اگر فهرست فلگ‌ها شامل یک -t همراه با نویسه + باشد، فهرست بعدی فلگ‌ها استفاده می‌شود حتی اگر فهرست فعلی تطابق‌هایی تولید کرده باشد.

گزینه‌های دیگری نیز در دسترس هستند که تکمیل را به بخشی از خط فرمان محدود می‌کنند؛ این قابلیت تحت عنوان «تکمیل گسترش‌یافته» شناخته می‌شود.

[ command ... ]
[ + options [ -x ... -- ] ... [+] ] [ command ... ]

فرمی که شامل `-x' است، تکمیل گسترش‌یافته را برای دستورات داده‌شده مشخص می‌کند؛ همان‌گونه که نشان داده شده، می‌توان آن را با تکمیل جایگزین با استفاده از `+' ترکیب کرد. هر pattern به نوبت بررسی می‌شود؛ هنگامی که تطابقی یافت شود، گزینه‌های options متناظر، همان‌طور که در بخش «فلگ‌های گزینه‌ها» در بالا شرح داده شد، برای تولید گزینه‌های ممکن تکمیل استفاده می‌شوند. اگر هیچ pattern مطابقت نداشته باشد، گزینه‌های options ارائه‌شده قبل از -x به کار می‌روند.

توجه داشته باشید که هر الگو باید به عنوان یک آرگومان منفرد ارائه شود و برای جلوگیری از بسط نویسه‌های فرامعنایی توسط پوسته، باید در کوتیشن قرار گیرد.

یک pattern از زیرالگوهایی ساخته می‌شود که با کاما از هم جدا شده‌اند؛ اگر حداقل یکی از این زیرالگوها مطابقت داشته باشد، الگو مطابقت می‌یابد (عملگر «یا»). این زیرالگوها نیز به نوبه خود از زیرالگوهای دیگری تشکیل شده‌اند که با نویسه‌های فاصله از هم جدا شده و در صورتی مطابقت می‌یابند که تمام زیرالگوها مطابقت داشته باشند (عملگر «و»). عنصری از زیرالگوها به شکل `c[...][...]' است، که در آن جفت‌براکت‌ها می‌توانند هر چند بار که لازم است تکرار شوند، و در صورتی تطابق برقرار است که هر یک از مجموعه‌های براکت‌ها مطابقت داشته باشد (یک «یا»). مثال زیر این موضوع را روشن‌تر می‌سازد.

عناصر می‌توانند هر یک از موارد زیر باشند:

s[string]...
در صورتی برقرار است که کلمه جاری در خط فرمان با یکی از رشته‌های ارائه‌شده درون براکت‌ها آغاز شود. این string حذف نمی‌شود و بخشی از تکمیل نیست.
مانند s[string] است به جز اینکه string بخشی از تکمیل خواهد بود.
در صورتی برقرار است که شماره کلمه جاری بین یکی از جفت‌های from و to (شامل هر دو) باشد. کاما و to اختیاری هستند؛ مقدار to به صورت پیش‌فرض برابر با from است. اعداد می‌توانند منفی باشند: -n به nـمین کلمه از انتهای خط اشاره دارد.
در صورتی برقرار است که رشته string با کلمه‌ای که به اندازه offset از موقعیت کلمه جاری فاصله دارد مطابقت داشته باشد. معمولاً offset منفی خواهد بود.
مانند c است اما از تطبیق الگو به جای رشته استفاده می‌کند.
در صورتی برقرار است که کلمه واقع در موقعیت index برابر با رشته متناظر string باشد. توجه داشته باشید که شمارش کلمات پس از هرگونه بسط نام‌های مستعار انجام می‌گیرد.
مانند w است اما از تطبیق الگو استفاده می‌کند.
در صورتی برقرار است که کلمه جاری حاوی string باشد. هر چیزی تا indexـمین رخداد این رشته (شامل خود آن) به عنوان بخشی از تکمیل در نظر گرفته نمی‌شود، اما باقی‌مانده آن بخش تکمیل خواهد بود. index می‌تواند برای شمارش از انتها منفی باشد: در بیشتر موارد index برابر ۱ یا -۱ خواهد بود. برای مثال:
compctl -s '`users`' -x 'n[1,@]' -k hosts -- talk

معمولاً نام‌های کاربری را تکمیل می‌کند، اما اگر یک @ پس از نام وارد کنید، نام‌های موجود در آرایه hosts (با این فرض که حاوی نام‌های میزبان باشد، هرچند باید خودتان این آرایه را ایجاد کنید) تکمیل خواهند شد. سایر دستورات مانند rcp را نیز می‌توان به روش مشابه مدیریت کرد.

مانند n است به جز اینکه رشته به عنوان یک رده نویسه‌ای در نظر گرفته می‌شود. هر چیزی تا indexـمین رخداد هر یک از نویسه‌های موجود در string به عنوان بخشی از تکمیل به شمار نخواهد رفت.
در صورتی برقرار است که تعداد کل کلمات بین min و max (شامل هر دو) قرار گیرد.
در صورتی برقرار است که مکان‌نما بعد از کلمه‌ای با پیشوند str1 قرار داشته باشد. اگر کلمه‌ای با پیشوند str2 نیز در خط فرمان بعد از کلمه منطبق با str1 وجود داشته باشد، تنها در صورتی تطابق برقرار است که مکان‌نما قبل از این کلمه باشد. اگر کاما و str2 حذف شوند، در صورتی که مکان‌نما بعد از کلمه‌ای با پیشوند str1 باشد مطابقت می‌یابد.
مانند r است اما به جای آن از تطبیق الگو استفاده می‌کند.
در صورتی برقرار است که کلمه‌ای که در حال حاضر تکمیل می‌شود در تک‌کوتیشن قرار داشته باشد و str با حرف `s' آغاز شود، یا اگر تکمیل در دابل‌کوتیشن انجام شود و str با حرف `d' شروع شود، یا اگر تکمیل در بک‌تیک انجام شود و str با حرف `b' آغاز گردد.

compctl -u -x 's[+] c[-1,-f],s[-f+]' \
  -g '~/Mail/*(:t)' - 's[-f],c[-1,-f]' -f -- mail

این دستور به صورت زیر تفسیر می‌شود:

اگر دستور جاری mail باشد، آنگاه

اگر ((کلمه جاری با + شروع شود و کلمه قبلی -f باشد)
یا (کلمه جاری با -f+ شروع شود))، آنگاه بخش غیردایرکتوری
(اصلاح‌کننده الگویابی `:t') فایل‌های موجود در دایرکتوری
~/Mail را تکمیل کن؛ در غیر این صورت
اگر کلمه جاری با -f شروع شود یا کلمه قبلی -f باشد، آنگاه
هر فایلی را تکمیل کن؛ در غیر این صورت
نام‌های کاربری را تکمیل کن.
July 12, 2026 zsh 5.9.2