ZSHCOMPWID(1)

General Commands Manual

ZSHCOMPWID(1)

نام (NAME)

zshcompwid - ویجت‌های تکمیل zsh

توضیحات (DESCRIPTION)

سازوکار تکمیل برنامه‌پذیر پوسته را می‌توان به دو روش دستکاری کرد؛ در اینجا ویژگی‌های سطح پایینی که از سازوکار جدیدترِ مبتنی بر تابع پشتیبانی می‌کنند، تعریف شده‌اند. مجموعهٔ کاملی از توابع پوسته بر پایهٔ این ویژگی‌ها در zshcompsys(1) شرح داده شده است، و کاربرانی که علاقه‌ای به افزودن به این سیستم (یا احتمالاً نوشتن سیستم اختصاصی خود -- به مدخل لغت‌نامه برای `hubris' مراجعه کنید) ندارند، باید از این بخش صرف‌نظر کنند. سیستم قدیمی‌ترِ مبتنی بر دستور توکار compctl در zshcompctl(1) توصیف شده است.

ویجت‌های تکمیل توسط گزینهٔ -C برای دستور توکار zle که توسط ماژول zsh/zle ارائه می‌شود تعریف می‌گردند (به zshzle(1) مراجعه کنید). برای نمونه،

zle -C complete expand-or-complete completer

ویجتی به نام `complete' را تعریف می‌کند. آرگومان دوم نام یکی از ویجت‌های توکاری است که تکمیل‌ها را مدیریت می‌کنند: complete-word، expand-or-complete، expand-or-complete-prefix، menu-complete، menu-expand-or-complete، reverse-menu-complete، list-choices، یا delete-char-or-list. توجه داشته باشید که این سازوکار حتی در صورتی که کلید اتصال ویجت مربوطه مجدداً مقید شده باشد نیز کار خواهد کرد.

هنگامی که این ویجت تازه‌تعریف‌شده با استفاده از دستور توکار bindkey تعریف‌شده در ماژول zsh/zle به یک کلید متصل شود (به zshzle(1) مراجعه کنید)، فشردن آن کلید، تابع پوستهٔ `completer' را فراخوانی خواهد کرد. این تابع وظیفه دارد با استفاده از دستورهای توکار شرح‌داده‌شده در ادامه، تطابق‌های تکمیل را تولید کند. همانند سایر ویجت‌های ZLE، این تابع با ورودی استاندارد بسته فراخوانی می‌شود.

به‌محض بازگشت تابع، کد تکمیل مجدداً کنترل را به دست می‌گیرد و با تطابق‌ها همانند ویجت توکارِ مشخص‌شده رفتار می‌کند، که در این حالت expand-or-complete است.

پارامترهای ویژهٔ تکمیل (COMPLETION SPECIAL PARAMETERS)

پارامترهای ZLE_REMOVE_SUFFIX_CHARS و ZLE_SPACE_SUFFIX_CHARS توسط سازوکار تکمیل استفاده می‌شوند، اما ویژه نیستند. به بخش Parameters Used By The Shell در zshparam(1) مراجعه کنید.

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

CURRENT: شمارهٔ کلمهٔ جاری است؛ یعنی کلمه‌ای در آرایهٔ words که مکان‌نما هم‌اکنون روی آن قرار دارد. توجه داشته باشید که این مقدار تنها در صورتی درست است که گزینهٔ ksharrays تنظیم نشده باشد.
IPREFIX: در ابتدا روی یک رشتهٔ خالی تنظیم می‌شود. این پارامتر مانند PREFIX عمل می‌کند؛ حاوی رشته‌ای است که پیش از رشتهٔ موجود در PREFIX می‌آید و بخشی از فهرست تطابق‌ها در نظر گرفته نمی‌شود. به‌طور معمول، رشته‌ای از ابتدای PREFIX به انتهای IPREFIX منتقل می‌شود، برای نمونه:

IPREFIX=${PREFIX%%\=*}=
PREFIX=${PREFIX#*=}

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

ISUFFIX: مانند IPREFIX، اما برای پسوندی است که نباید بخشی از تطابق‌ها در نظر گرفته شود؛ توجه داشته باشید که رشتهٔ ISUFFIX پس از رشتهٔ SUFFIX می‌آید.
PREFIX: در ابتدا روی بخشی از کلمهٔ جاری از ابتدای کلمه تا موقعیت مکان‌نما تنظیم می‌شود؛ ممکن است برای ارائهٔ یک پیشوند مشترک برای همهٔ تطابق‌ها تغییر داده شود.
QIPREFIX: این پارامتر فقط‌خواندنی است و شامل رشتهٔ نقل‌قول‌شده تا کلمهٔ در حال تکمیل است. برای نمونه هنگام تکمیل `"foo'، این پارامتر حاوی گیومه دوتایی (double quote) است. اگر از گزینهٔ -q در compset استفاده شود (پایین‌تر را ببینید)، و رشتهٔ اصلی `"foo bar' بوده و مکان‌نما روی `bar' باشد، این پارامتر شامل `"foo ' خواهد بود.
QISUFFIX: مانند QIPREFIX، اما حاوی پسوند است.
SUFFIX: در ابتدا روی بخشی از کلمهٔ جاری از موقعیت مکان‌نما تا انتها تنظیم می‌شود؛ ممکن است برای ارائهٔ یک پسوند مشترک برای همهٔ تطابق‌ها تغییر داده شود. بیشترین کاربرد آن زمانی است که گزینهٔ COMPLETE_IN_WORD تنظیم شده باشد، زیرا در غیر این صورت کل کلمه در خط فرمان به‌عنوان یک پیشوند در نظر گرفته می‌شود.
compstate: یک آرایهٔ انجمنی با کلیدها و مقادیر گوناگون است که کد تکمیل از آن برای تبادل اطلاعات با ویجت تکمیل استفاده می‌کند. کلیدها عبارتند از:

all_quotes: گزینهٔ -q از دستور توکار compset (پایین‌تر را ببینید) اجازه می‌دهد یک رشتهٔ نقل‌قول‌شده به کلمات جداگانه شکسته شود؛ اگر مکان‌نما روی یکی از آن کلمات باشد، آن کلمه تکمیل خواهد شد و احتمالاً `compset -q' را به‌صورت بازگشتی فراخوانی می‌کند. با این کلید می‌توان نوع رشته‌های نقل‌قول‌شده‌ای را که در حال حاضر به این روش به بخش‌هایی تقسیم شده‌اند بررسی کرد. مقدار آن شامل یک نویسه به ازای هر سطح نقل‌قول است. این نویسه‌ها عبارتند از یک نقل‌قول تکی یا نقل‌قول دوتایی برای رشته‌های نقل‌قول‌شده با این نویسه‌ها، یک علامت دلار برای رشته‌های نقل‌قول‌شده با $'...' و یک بک‌اسلش برای رشته‌هایی که با نویسهٔ نقل‌قول شروع نمی‌شوند. اولین نویسه در مقدار همیشه متناظر با درونی‌ترین سطح نقل‌قول است.
context: توسط کد تکمیل روی بافت کلی (context) که تکمیل در آن انجام می‌شود تنظیم خواهد شد. مقادیر ممکن عبارتند از:

array_value: هنگام تکمیل درون مقدار یک انتساب پارامتر آرایه‌ای؛ در این حالت آرایهٔ words شامل کلمات داخل پرانتز است.
brace_parameter: هنگام تکمیل نام یک پارامتر در یک بسط پارامتر که با ${ آغاز می‌شود. این بافت همچنین هنگام تکمیل پرچم‌های پارامتر پس از ${( تنظیم خواهد شد؛ آرگومان کامل خط فرمان ارائه می‌شود و گرداننده باید مقدار در حال تکمیل را بررسی کند تا از این موضوع اطمینان یابد.
assign_parameter: هنگام تکمیل نام یک پارامتر در یک انتساب پارامتر.
command: هنگام تکمیل برای یک دستور عادی (چه در موقعیت دستور و چه برای آرگومانی از دستور).
condition: هنگام تکمیل درون عبارت شرطی `[[...]]'؛ در این حالت آرایهٔ words فقط شامل کلمات درون عبارت شرطی است.
math: هنگام تکمیل در یک محیط ریاضی مانند ساختار `((...))'.
parameter: هنگام تکمیل نام یک پارامتر در بسط پارامتری که با $ شروع می‌شود ولی با ${ شروع نمی‌شود.
redirect: هنگام تکمیل پس از یک عملگر تغییر مسیر.
subscript: هنگام تکمیل درون یک اندیس پارامتر.
value: هنگام تکمیل مقدار یک انتساب پارامتر.

exact: رفتار را هنگام تنظیم گزینهٔ REC_EXACT کنترل می‌کند. اگر یک تطابق دقیق پذیرفته شود روی accept تنظیم خواهد شد، و در غیر این صورت تنظیم‌نشده خواهد ماند.

اگر زمانی که حداقل یک تطابق برابر با رشتهٔ موجود در خط تولید شده بود تنظیم شده باشد، آن تطابق پذیرفته می‌شود.

exact_string: رشتهٔ مربوط به یک تطابق دقیق در صورت یافت شدن، و در غیر این صورت تنظیم‌نشده..TP ignored تعداد کامل‌سازی‌هایی که نادیده گرفته شدند زیرا با یکی از الگوهای ارائه‌شده با گزینهٔ -F به دستور توکار compadd مطابقت داشتند.
insert: نحوهٔ درج شدن یک تطابق در خط فرمان را کنترل می‌کند. هنگام ورود به تابع ابزارک، اگر مقداردهی نشده باشد، خط فرمان نباید تغییر کند؛ اگر روی unambiguous تنظیم شده باشد، هرگونه پیشوند مشترک بین تمام تطابق‌ها درج خواهد شد؛ اگر روی automenu-unambiguous تنظیم شود، پیشوند مشترک درج شده و فراخوانی بعدی کد کامل‌سازی ممکن است کامل‌سازی منویی را آغاز کند (به دلیل تنظیم بودن گزینهٔ AUTO_MENU)؛ اگر روی menu یا automenu تنظیم شود، کامل‌سازی منویی برای تطابق‌های تولیدشدهٔ فعلی آغاز خواهد شد (در حالت دوم، این اتفاق به دلیل تنظیم بودن گزینهٔ AUTO_MENU رخ می‌دهد). همچنین این مقدار می‌تواند حاوی رشتهٔ `tab' باشد، در صورتی که کد کامل‌سازی در حالت عادی واقعاً عمل کامل‌سازی را انجام ندهد و صرفاً نویسهٔ TAB را درج کند.

هنگام خروج می‌توان آن را روی هر یک از مقادیر بالا (که تنظیم آن روی رشتهٔ خالی همانند لغو مقداردهی آن است) یا روی یک عدد تنظیم کرد، که در این صورت تطابقی که شماره‌اش مشخص شده است در خط فرمان درج خواهد شد. اعداد منفی از آخرین تطابق رو به عقب شمارش می‌شوند (به‌طوری که `-1' آخرین تطابق را انتخاب می‌کند) و مقادیر خارج از محدوده دور می‌زنند، به‌گونه‌ای که مقدار صفر آخرین تطابق و مقداری به اندازهٔ یک واحد بیشتر از بیشینه، اولین تطابق را انتخاب می‌کند. مگر این‌که مقدار این کلید با یک فاصله پایان یابد، تطابق مانند کامل‌سازی منویی درج می‌شود، یعنی بدون افزودن خودکار فاصله به انتهای آن.

هر دو مقدار menu و automenu می‌توانند شمارهٔ تطابق مورد نظر برای درج را پس از دونقطه مشخص کنند. برای مثال، `menu:2' به این معناست که کامل‌سازی منویی، با شروع از دومین تطابق آغاز شود.

توجه داشته باشید مقداری که شامل زیررشتهٔ `tab' باشد، باعث می‌شود تطابق‌های تولیدشده نادیده گرفته شوند و فقط TAB درج شود.

در نهایت، می‌تواند روی all نیز تنظیم شود، که باعث می‌شود تمام تطابق‌های تولیدشده در خط درج شوند.

insert_positions: هنگامی که سامانهٔ کامل‌سازی یک رشتهٔ بدون ابهام را در خط درج می‌کند، ممکن است چندین موقعیت وجود داشته باشد که در آن‌ها نویسه‌هایی جا افتاده باشند یا نویسهٔ درج‌شده با دست‌کم یکی از تطابق‌ها تفاوت داشته باشد. مقدار این کلید شامل فهرستی جداشده با دونقطه از تمام این موقعیت‌ها به عنوان اندیس‌هایی در خط فرمان است.
last_prompt: اگر این مقدار به ازای هر تطابق اضافه‌شده روی یک رشتهٔ غیرخالی تنظیم شود، کد کامل‌سازی پس از نمایش فهرست کامل‌سازی‌ها، مکان‌نما را به اعلان قبلی بازمی‌گرداند. در ابتدا، این کلید با توجه به گزینهٔ ALWAYS_LAST_PROMPT تنظیم یا لغو می‌شود.
list: این کلید مشخص می‌کند که آیا فهرست تطابق‌ها نمایش داده شود یا چگونه نمایش داده شود. اگر مقداردهی نشده یا خالی باشد، هرگز فهرست نخواهند شد؛ اگر مقدار آن با list شروع شود، همیشه فهرست می‌شوند؛ اگر با autolist یا ambiguous شروع شود، زمانی فهرست می‌شوند که گزینه‌های AUTO_LIST یا LIST_AMBIGUOUS به طور معمول باعث نمایش آن‌ها شوند.

اگر زیررشتهٔ force در این مقدار بیاید، باعث می‌شود فهرست حتی در صورت وجود تنها یک تطابق نمایش داده شود. در حالت عادی، فهرست فقط در صورت وجود حداقل دو تطابق نمایش داده می‌شود.

اگر گزینهٔ LIST_PACKED تنظیم شده باشد، این مقدار حاوی زیررشتهٔ packed خواهد بود. اگر این زیررشته برای تمام تطابق‌های اضافه‌شده به یک گروه داده شود، آن گروه رفتار LIST_PACKED را نشان خواهد داد. همین رفتار برای گزینهٔ LIST_ROWS_FIRST با زیررشتهٔ rows انجام می‌شود.

در نهایت، اگر مقدار حاوی رشتهٔ explanations باشد، فقط رشته‌های توضیحی (در صورت وجود) فهرست خواهند شد، و اگر حاوی messages باشد، فقط پیام‌ها (اضافه‌شده با گزینهٔ -x از compadd) فهرست می‌شوند. اگر حاوی هر دو رشتهٔ explanations و messages باشد، هر دو نوع رشته‌های توضیحی فهرست خواهند شد. این کلید هنگام ورود به یک ابزارک کامل‌سازی به درستی تنظیم می‌شود و می‌تواند در آنجا تغییر کند.

list_lines: تعداد خطوطی را که برای نمایش فهرست کاملِ کامل‌سازی‌ها نیاز است مشخص می‌کند. توجه داشته باشید که برای محاسبهٔ تعداد کل خطوط جهت نمایش، باید تعداد خطوط مورد نیاز برای خط فرمان را به این مقدار اضافه کنید، که به عنوان مقدار پارامتر ویژهٔ BUFFERLINES در دسترس است.
list_max: در ابتدا روی مقدار پارامتر LISTMAX تنظیم می‌شود. می‌تواند روی هر مقدار دیگری نیز تنظیم گردد؛ هنگام خروج ابزارک، این مقدار به همان شیوهٔ مقدار LISTMAX استفاده خواهد شد.
nmatches: تعداد تطابق‌هایی که تاکنون توسط کد کامل‌سازی اضافه شده است.
old_insert: هنگام ورود به ابزارک، روی شمارهٔ تطابقی از یک فهرست قدیمی کامل‌سازی‌ها که هم‌اکنون در خط فرمان درج شده است، تنظیم خواهد شد. اگر هیچ تطابقی درج نشده باشد، این کلید مقداردهی نشده است.

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

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

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

parameter: نام پارامتر هنگام کامل‌سازی درون یک زیرنویس (subscript) یا در مقدار یک انتساب پارامتر.
pattern_insert: در حالت عادی روی menu تنظیم است، که مشخص می‌کند هر زمان مجموعه‌ای از تطابق‌ها با استفاده از pattern_match (به زیر نگاه کنید) تولید شد، کامل‌سازی منویی استفاده خواهد شد. اگر توسط کاربر روی هر رشتهٔ غیرخالی دیگری تنظیم شود و کامل‌سازی منویی توسط سایر تنظیمات گزینه‌ها انتخاب نشده باشد، کد به جای آن، مانند کامل‌سازی عادی، هرگونه پیشوند مشترک برای تطابق‌های تولیدشده را درج می‌کند.
pattern_match: رفتار ارائه‌شده توسط گزینهٔ GLOB_COMPLETE را به صورت محلی کنترل می‌کند. در ابتدا فقط و فقط اگر این گزینه تنظیم شده باشد، روی `*' تنظیم می‌شود. ابزارک کامل‌سازی می‌تواند آن را روی این مقدار، یک رشتهٔ خالی (که همان اثر لغو مقداردهی را دارد)، یا هر رشتهٔ غیرخالی دیگری تنظیم کند. اگر غیرخالی باشد، فرانویسه‌های (metacharacters) خارج از نقل‌قول در خط فرمان به عنوان الگو در نظر گرفته می‌شوند؛ اگر `*' باشد، علاوه بر این یک نویسهٔ عام `*' در موقعیت مکان‌نما فرض می‌شود؛ اگر خالی باشد یا مقداردهی نشده باشد، با فرانویسه‌ها به صورت نویسهٔ تحت‌اللفظی رفتار خواهد شد.

توجه داشته باشید که اگر این کلید روی یک رشتهٔ غیرخالی تنظیم شده باشد، مشخصات تطابق ارائه‌شده به دستور توکار compadd استفاده نمی‌شوند.

quote: هنگام کامل‌سازی درون نقل‌قول‌ها، این کلید حاوی نویسهٔ نقل‌قول است (یعنی تک‌نقل‌قول، جفت‌نقل‌قول، یا بَک‌تیک). در غیر این صورت مقداردهی نشده است.
quoting: هنگام کامل‌سازی درون تک‌نقل‌قول، روی رشتهٔ single تنظیم می‌شود؛ درون جفت‌نقل‌قول، روی رشتهٔ double؛ و درون بَک‌تیک، روی رشتهٔ backtick. در غیر این صورت مقداردهی نشده است.
redirect: عملگر تغییر مسیر هنگام کامل‌سازی در موقعیت تغییر مسیر، یعنی یکی از <، > و غیره.
restore: پیش از ورود به یک تابع روی auto تنظیم می‌شود، که پارامترهای ویژهٔ ذکرشده در بالا (words، CURRENT، PREFIX، IPREFIX، SUFFIX و ISUFFIX) را وادار می‌کند هنگام خروج تابع به مقادیر قبلی خود بازگردانده شوند. اگر تابعی مقدار آن را لغو کند یا آن را روی هر رشتهٔ دیگری تنظیم نماید، آن‌ها بازگردانده نخواهند شد.
to_end: شرایطی را مشخص می‌کند که در آن‌ها هنگام درج یک تطابق، مکان‌نما به انتهای رشته منتقل می‌شود. هنگام ورود به یک تابع ابزارک، در صورتی که این اتفاق هنگام درج یک تطابق منفردِ بدون ابهام رخ دهد، ممکن است single باشد، یا اگر هر زمان که تطابقی درج شد رخ دهد (برای مثال، توسط کامل‌سازی منویی؛ احتمالاً این اثر گزینهٔ ALWAYS_TO_END است)، ممکن است match باشد.

هنگام خروج، ممکن است مانند بالا روی single تنظیم شود. همچنین می‌تواند روی always یا روی رشتهٔ خالی تنظیم شده یا مقداردهی نشده باشد؛ در این حالت‌ها مکان‌نما به ترتیب همواره یا هرگز به انتهای رشته منتقل می‌شود. هر رشتهٔ دیگری به عنوان match در نظر گرفته می‌شود.

unambiguous: این کلید فقط‌خواندنی است و همیشه روی پیشوند مشترک (بدون ابهام) که کد کامل‌سازی برای تمام تطابق‌های اضافه‌شده تا این لحظه تولید کرده است تنظیم خواهد شد.
unambiguous_cursor: موقعیتی را نشان می‌دهد که اگر پیشوند مشترک موجود در کلید unambiguous درج می‌شد، مکان‌نما نسبت به مقدار آن کلید در آنجا قرار می‌گرفت. مکان‌نما قبل از نویسه‌ای قرار می‌گیرد که اندیس آن توسط این کلید مشخص شده است.
unambiguous_positions: حاوی تمام موقعیت‌هایی است که در آن‌ها نویسه‌ها در رشتهٔ بدون ابهام جا افتاده‌اند، یا نویسهٔ درج‌شده با دست‌کم یکی از تطابق‌ها تفاوت دارد. این موقعیت‌ها به عنوان اندیس‌هایی در رشته‌ای که مقدار کلید unambiguous مشخص کرده است، ارائه می‌شوند..TP vared اگر هنگام ویرایش یک سطر با استفاده از دستور توکار vared کامل‌سازی فراخوانی شود، مقدار این کلید روی نام پارامتری تنظیم می‌شود که به‌عنوان آرگومان به vared داده شده است. این کلید تنها در زمانی که یک دستور vared فعال باشد، تنظیم می‌شود.

words: این آرایه شامل واژه‌های موجود در سطر فرمانی است که در حال حاضر ویرایش می‌شود.

دستورهای توکار کامل‌سازی (COMPLETION BUILTIN COMMANDS)

compadd [ -akqQfenUl12C ] [ -F array ]
[-P prefix ] [ -S suffix ]
[-p hidden-prefix ] [ -s hidden-suffix ]
[-i ignored-prefix ] [ -I ignored-suffix ]
[-W file-prefix ] [ -d array ]
[-J group-name ] [ -X explanation ] [ -x message ]
[-V group-name ] [ -o [ order ] ]
[-r remove-chars ] [ -R remove-func ]
[-D array ] [ -O array ] [ -A array ]
[-E number ]
[-M match-spec ] [ -- ] [ completions ... ]

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

کد کامل‌سازی هر تطابق را به ترتیب به هفت فیلد تقسیم می‌کند:

<ipre><apre><hpre><body><hsuf><asuf><isuf>

فیلد نخست یک پیشوند نادیده‌گرفته‌شده از سطر فرمان است؛ یعنی محتوای پارامتر IPREFIX به همراه رشته‌ای که با گزینهٔ -i مشخص شده است. با گزینهٔ -U، تنها رشتهٔ دریافتی از گزینهٔ -i استفاده می‌شود. فیلد <apre> یک رشته پیشوند اختیاری است که با گزینهٔ -P داده می‌شود. فیلد <hpre> رشته‌ای است که بخشی از تطابق در نظر گرفته می‌شود اما نباید هنگام فهرست کردن کامل‌سازی‌ها نمایش داده شود، و با گزینهٔ -p مشخص می‌گردد؛ برای نمونه، توابعی که تولید نام فایل را انجام می‌دهند می‌توانند پیشوند مسیر مشترک را به این روش تعیین کنند. فیلد <body> بخشی از تطابق است که باید در فهرست تطابق‌های نمایش‌داده‌شده به کاربر ظاهر شود. پسوندهای <hsuf>، <asuf> و <isuf> متناظر با پیشوندهای <hpre>، <apre> و <ipre> هستند و به ترتیب با گزینه‌های -s، -S و -I تعیین می‌شوند.

پرچم‌های پشتیبانی‌شده عبارتند از:

-P prefix: رشته‌ای را مشخص می‌کند که باید پیش از هر تطابق درج شود. رشتهٔ ارائه‌شده بخشی از تطابق محسوب نمی‌شود و هنگام درج رشته، هیچ‌یک از نویسه‌های ویژهٔ پوسته (metacharacters) در آن نقل‌قول نخواهند شد.
-S suffix: مشابه -P، اما رشته‌ای را مشخص می‌کند که باید پس از هر تطابق درج شود.
-p hidden-prefix: رشته‌ای را مشخص می‌کند که باید پیش از هر تطابق درج شود اما نباید در فهرست تطابق‌ها ظاهر گردد. مگر در حالتی که گزینهٔ -U داده شده باشد، این رشته باید به‌صورت بخشی از رشته در سطر فرمان تطبیق داده شود.
-s hidden-suffix: مشابه «-p»، اما رشته‌ای را برای درج پس از هر تطابق مشخص می‌کند.
-i ignored-prefix: رشته‌ای را مشخص می‌کند تا دقیقاً پیش از هر رشتهٔ ارائه‌شده با گزینهٔ «-P» درج شود. بدون «-P»، این رشته پیش از رشتهٔ ارائه‌شده با «-p» یا مستقیماً پیش از هر تطابق درج می‌شود.
-I ignored-suffix: مشابه -i، اما یک پسوند نادیده‌گرفته‌شده را مشخص می‌کند.
-a: با این پرچم، completions به‌عنوان نام آرایه‌ها در نظر گرفته می‌شوند و کامل‌سازی‌های واقعی مقادیر آن‌ها خواهند بود. در صورتی که تنها به برخی از عناصر آرایه‌ها نیاز باشد، completions می‌توانند شامل اندیس‌ها (subscripts) نیز باشند، مانند «foo[2,-1]».
-k: با این پرچم، completions به‌عنوان نام آرایه‌های انجمنی در نظر گرفته می‌شوند و کامل‌سازی‌های واقعی کلیدهای آن‌ها هستند. همانند -a، این words نیز می‌توانند شامل اندیس‌ها باشند، مانند «foo[(R)*bar*]».
-d array: رشته‌های نمایشی را به ازای هر کامل‌سازی اضافه می‌کند. آرایهٔ array باید به ازای هر completion ارائه‌شده، شامل یک عنصر باشد. کد کامل‌سازی سپس به‌جای نخستین completion، عنصر اول را نمایش می‌دهد و به همین ترتیب ادامه می‌یابد. آرایهٔ array می‌تواند به‌عنوان نام یک پارامتر آرایه یا مستقیماً به‌صورت فهرستی از واژه‌ها با فاصله‌گذاری درون پرانتز داده شود.

اگر تعداد رشته‌های نمایشی کمتر از completions باشد، کامل‌سازی‌های باقی‌مانده بدون تغییر نمایش داده می‌شوند و اگر تعداد رشته‌های نمایشی بیشتر از completions باشد، رشته‌های نمایشی اضافی بدون هشدار نادیده گرفته خواهند شد.

-l: این گزینه تنها در صورت استفادهٔ هم‌زمان با گزینهٔ -d تأثیرگذار است. در صورت تعیین آن، رشته‌های نمایشی در هر سطر یکی فهرست می‌شوند، نه این‌که در ستون‌ها چیده شوند.
-o [ order ]: ترتیب مرتب‌سازی تطابق‌ها را واپایش می‌کند. مقدار order فهرستی جداشده با کاما شامل مقادیر ممکن زیر است. این مقادیر را می‌توان به دو یا سه نویسهٔ آغازین آن‌ها مخفف کرد. توجه داشته باشید که ترتیب، بخشی از فضای نام گروه را تشکیل می‌دهد؛ بنابراین تطابق‌هایی با ترتیب‌های متفاوت در یک گروه قرار نخواهند گرفت.

match: در صورت مشخص شدن، ترتیب خروجی بر اساس رشته‌های تطابق تعیین می‌شود؛ در غیر این صورت بر اساس رشته‌های نمایشی (یعنی رشته‌های ارائه‌شده توسط گزینهٔ -d) تعیین می‌گردد. اگر «-o» مشخص شود اما آرگومان order حذف گردد، این مقدار پیش‌فرض خواهد بود.
nosort: مشخص می‌کند که completions از پیش مرتب شده‌اند و باید ترتیب آن‌ها حفظ شود. این مقدار تنها به‌تنهایی معنادار است و نمی‌توان آن را با هیچ مقدار دیگری ترکیب کرد.
numeric: اگر تطابق‌ها شامل اعداد باشند، آن‌ها را به‌جای روش الفبایی (lexicographical)، به‌صورت عددی مرتب می‌کند.
reverse: با معکوس کردن ترتیب مرتب‌سازی، تطابق‌ها را وارونه می‌چیند.

-J group-name: نام گروهی را مشخص می‌کند که تطابق‌ها باید در آن ذخیره شوند.
-V group-name: مشابه -J اما یک گروه نامرتب را مشخص می‌کند. این گزینه هم‌ارز ترکیب -J و -o nosort است.
-1: در صورت ارائه همراه با گزینهٔ -V، باعث می‌شود تنها موارد تکراری متوالی در گروه حذف شوند. در صورت ترکیب با گزینهٔ -J، هیچ اثر قابل مشاهده‌ای ندارد. توجه داشته باشید که گروه‌های دارای این پرچم و گروه‌های بدون آن در فضاهای نام متفاوتی هستند.
-2: در صورت ارائه همراه با گزینهٔ -J یا -V، باعث می‌شود همهٔ موارد تکراری حفظ شوند. مجدداً، گروه‌های دارای این پرچم و بدون آن در فضاهای نام متفاوتی قرار دارند.
-X explanation: رشتهٔ explanation همراه با فهرست تطابق‌ها و بالای گروهی که در حال حاضر انتخاب شده است، چاپ می‌شود.

درون explanation، می‌توان از دنباله‌های زیر برای مشخص کردن ویژگی‌های خروجی استفاده کرد، همان‌طور که در بخش EXPANSION OF PROMPT SEQUENCES در zshmisc(1) توصیف شده است: «%B»، «%S»، «%U»، «%F»، «%K» و همتایان حروف کوچک آن‌ها، و همچنین «%{...%}». «%F»، «%K» و «%{...%}» آرگومان‌ها را به همان شکل گسترش اعلان (prompt expansion) می‌پذیرند. (توجه داشته باشید که دنبالهٔ «%G» در دسترس نیست؛ در عوض باید از یک آرگومان برای «%{» استفاده شود.) دنبالهٔ «%%» یک «%» لفظی تولید می‌کند..PP این توالی‌ها اغلب توسط کاربران هنگام سفارشی‌سازی سبک format به کار می‌روند (نگاه کنید به zshcompsys(1))، اما هنگام نوشتن توابع تکمیل نیز باید مد نظر قرار گیرند، چرا که ارسال توصیف‌هایی با نویسه‌های فرارنیافتهٔ «%» به توابع کمکی مانند _arguments و _message ممکن است نتایج غیرمنتظره‌ای ایجاد کند. اگر قرار است متنی دلخواه در یک توصیف ارسال شود، می‌توان آن را با عبارتی مانند ${my_str//\%/%%} گریز داد.

-x message: مانند -X، اما message حتی در صورت نبود هیچ تطابقی در گروه چاپ خواهد شد.
-q: پسوند ارائه‌شده با -S به‌طور خودکار حذف خواهد شد اگر نویسهٔ بعدی تایپ‌شده یک فاصله باشد یا چیزی درج نکند، یا اگر پسوند تنها از یک نویسه تشکیل شده باشد و نویسهٔ بعدی تایپ‌شده همان نویسه باشد.
-r remove-chars: این شکل همه‌کاره‌تری از گزینهٔ -q است. پسوند ارائه‌شده با -S یا ممیزی که به‌طور خودکار پس از تکمیل دایرکتوری‌ها افزوده می‌شود، در صورتی که نویسهٔ بعدی تایپ‌شده یکی از نویسه‌های ارائه‌شده در remove-chars را درج کند، به‌طور خودکار حذف خواهد شد. این رشته به عنوان یک ردهٔ نویسه‌ای تجزیه می‌شود و توالی‌های بک‌اسلشِ مورد استفاده در دستور print را تشخیص می‌دهد. برای نمونه، «-r "a-z\t"» در صورتی که نویسهٔ بعدی تایپ‌شده یک نویسهٔ کوچک یا TAB را درج کند پسوند را حذف می‌کند، و «-r "^0-9"» در صورتی که نویسهٔ بعدی تایپ‌شده هر چیزی به‌جز یک رقم باشد، پسوند را حذف می‌نماید. یک توالی بک‌اسلش اضافی نیز در این رشته قابل فهم است: «\-» نمایانگر تمام نویسه‌هایی است که هیچ چیزی درج نمی‌کنند. بنابراین «-S "=" -q» با «-S "=" -r "= \t\n\-"» یکسان است.

این گزینه ممکن است بدون گزینهٔ -S نیز استفاده شود؛ در این صورت با تایپ یکی از نویسه‌های موجود در فهرست، هر فاصلهٔ به‌طور خودکار اضافه‌شده حذف خواهد شد.

-R remove-func: این شکل دیگری از گزینهٔ -r است. هنگامی که یک تطابق پذیرفته شد و یک پسوند درج گردید، تابع remove-func پس از فشرده‌شدن و تایپ نویسهٔ بعدی فراخوانی خواهد شد. طول پسوند به عنوان یک آرگومان به آن فرستاده می‌شود و این تابع می‌تواند از پارامترهای ویژهٔ موجود در ویجت‌های معمولی (غیرتکمیلی) zle (نگاه کنید به zshzle(1)) برای تحلیل و تغییر خط فرمان استفاده کند.
-f: اگر این پرچم داده شود، همهٔ تطابق‌های ساخته‌شده از completions به عنوان نام فایل علامت‌گذاری می‌شوند. نیازی نیست که آن‌ها حتماً نام فایل‌های واقعی باشند، اما اگر باشند، و گزینهٔ LIST_TYPES تنظیم شده باشد، نویسه‌های توصیف‌کنندهٔ نوع فایل‌ها در فهرست‌های تکمیل نمایش داده خواهند شد. این کار همچنین باعث می‌شود هنگام تکمیل نام یک دایرکتوری، افزودن یک ممیز اجباری گردد.
-e: از این پرچم می‌توان برای اعلام به کد تکمیل استفاده کرد که تطابق‌های افزوده‌شده، نام پارامتر برای یک گسترش پارامتر هستند. این کار باعث می‌شود گزینه‌های AUTO_PARAM_SLASH و AUTO_PARAM_KEYS برای این تطابق‌ها اعمال شوند.
-W file-prefix: این رشته یک نام مسیر است که به همراه هر پیشوند مشخص‌شده توسط گزینهٔ -p، به ابتدای هر تطابق اضافه می‌شود تا نام کامل فایل را برای آزمایش شکل دهد. بنابراین تنها در صورت ترکیب با پرچم -f سودمند است، چرا که در غیر این صورت آزمایش‌ها انجام نخواهند شد.
-F array: آرایه‌ای حاوی الگوها را مشخص می‌کند. مواردی از completions که با یکی از این الگوها مطابقت داشته باشند نادیده گرفته می‌شوند، یعنی به عنوان تطابق در نظر گرفته نمی‌شوند.

این array می‌تواند نام یک پارامتر آرایه‌ای یا فهرستی از الگوهای لفظی محصور در پرانتز و درون نقل‌قول باشد، مانند «-F "(*?.o *?.h)"». اگر نام یک آرایه داده شود، عناصر آن آرایه به عنوان الگوها در نظر گرفته می‌شوند.

-Q: این پرچم به کد تکمیل دستور می‌دهد که هنگام درج تطابق‌ها در خط فرمان، هیچ‌کدام از نویسه‌های خاص (metacharacters) موجود در آن‌ها را درون نقل‌قول قرار ندهد.
-M match-spec: این گزینه مشخصات محلی تطابق را مطابق آنچه در زیر در بخش «Completion Matching Control» شرح داده شده است، تعیین می‌کند. این گزینه ممکن است بیش از یک بار مشخص شود. در این صورت، تمام match-specهای ارائه‌شده با فاصله‌هایی در میانشان به هم متصل می‌شوند تا رشتهٔ مشخصات مورد استفاده را تشکیل دهند. توجه داشته باشید که آن‌ها تنها در صورتی استفاده خواهند شد که گزینهٔ -U داده نشده باشد.
-n: مشخص می‌کند که completions دارای تطابق به مجموعهٔ تطابق‌ها اضافه شوند، اما برای کاربر فهرست نشوند.
-U: اگر این پرچم داده شود، تمام completions به مجموعهٔ تطابق‌ها اضافه می‌شوند و هیچ تطابق‌یابی توسط کد تکمیل انجام نخواهد شد. معمولاً این گزینه در توابعی به کار می‌رود که تطابق‌یابی را خودشان انجام می‌دهند.
-O array: اگر این گزینه داده شود، completions به مجموعهٔ تطابق‌ها اضافه نمی‌شوند. در عوض، تطابق‌یابی طبق معمول انجام می‌گیرد و تمام مواردی از completions که مطابقت دارند، در پارامتر آرایه‌ای که نام آن در array آمده است ذخیره خواهند شد.
-A array: مانند گزینهٔ -O است، با این تفاوت که به‌جای ذخیرهٔ مواردی از completions که مطابقت دارند در array، رشته‌های تولیدشدهٔ داخلی توسط کد تکمیل ذخیره می‌شوند. برای نمونه، با یک مشخصهٔ تطابق «-M "L:|no="»، کلمهٔ فعلی «nof» و completions برابر «foo»، این گزینه رشتهٔ «nofoo» را در آرایه ذخیره می‌کند، در حالی که گزینهٔ -O همان «foo» ارائه‌شدهٔ اولیه را ذخیره خواهد کرد.
-D array: همانند -O، موارد completions به مجموعهٔ تطابق‌ها اضافه نمی‌شوند. در عوض، هر زمان که nاُمین completion مطابقت نداشته باشد، nاُمین عنصر از array حذف می‌شود. عناصری که completion متناظر آن‌ها مطابقت دارد حفظ می‌شوند. این گزینه می‌تواند بیش از یک بار برای حذف عناصر از چندین آرایه استفاده شود.
-C: این گزینه یک تطابق ویژه اضافه می‌کند که هنگام درج در خط فرمان، به تمام تطابق‌های دیگر گسترش می‌یابد، حتی مواردی که پس از به‌کارگیری این گزینه افزوده می‌شوند. همراه با گزینهٔ -d می‌توان رشته‌ای را که باید برای این تطابق ویژه در فهرست نمایش داده شود مشخص کرد. اگر رشته‌ای تعیین نشود، به صورت رشته‌ای حاوی متن‌هایی که برای سایر تطابق‌ها درج می‌شد، بریده‌شده متناسب با عرض صفحه نمایش داده خواهد شد.
-E number: این گزینه پس از افزوده شدن completions منطبق، به تعداد number تطابق خالی اضافه می‌کند. یک تطابق خالی فضایی را در فهرست‌های تکمیل اشغال می‌کند اما هرگز در خط درج نخواهد شد و با تکمیل منویی یا گزینش منویی نیز قابل انتخاب نیست. این امر تطابق‌های خالی را تنها برای قالب‌بندی فهرست‌های تکمیل و نمایش رشته‌های توضیحی در فهرست‌های تکمیل سودمند می‌سازد (چرا که با استفاده از گزینهٔ -d می‌توان رشته‌های نمایشی را به تطابق‌های خالی اختصاص داد). و از آنجا که در غیر این صورت همهٔ رشته‌های خالی به‌جز یکی حذف می‌شدند، این گزینه مستلزم گزینه‌های -V و -2 خواهد بود (حتی اگر گزینهٔ صریح -J داده شده باشد). توجه به این نکته می‌تواند مهم باشد چرا که بر فضای نامی که تطابق‌ها در آن افزوده می‌شوند تأثیر می‌گذارد.
-
--: این پرچم به فهرست پرچم‌ها و گزینه‌ها پایان می‌دهد. تمام آرگومان‌های پس از آن به عنوان completions در نظر گرفته خواهند شد، حتی اگر با خط تیره آغاز شوند.

به‌جز پرچم -M، اگر هر یک از این پرچم‌ها بیش از یک بار داده شود، نخستین پرچم (و آرگومان آن) استفاده خواهد شد.

compset -p number
compset -P [ number ] pattern
compset -s number
compset -S [ number ] pattern
compset -n begin [ end ]
compset -N beg-pat [ end-pat ]
compset -q: این دستور اصلاح پارامترهای ویژه را ساده می‌کند، در حالی که وضعیت بازگشتی آن امکان اجرای آزمایش‌ها روی آن‌ها را فراهم می‌سازد.

گزینه‌ها عبارتند از:

-p number: اگر طول مقدار پارامتر PREFIX حداقل به اندازهٔ number نویسه باشد، number نویسهٔ نخست از آن حذف شده و به محتوای پارامتر IPREFIX الحاق می‌شود.
-P [ number ] pattern: اگر مقدار پارامتر PREFIX با هر چیزی آغاز شود که با pattern مطابقت دارد، بخش مطابقت‌یافته از PREFIX حذف شده و به IPREFIX الحاق می‌گردد. بدون number اختیاری، طولانی‌ترین تطبیق در نظر گرفته می‌شود، اما اگر number مشخص شده باشد، همه چیز تا numberامین تطبیق منتقل می‌شود. اگر number منفی باشد، numberامین طولانی‌ترین تطبیق منتقل خواهد شد. برای مثال، اگر PREFIX حاوی رشتهٔ `a=b=c' باشد، آن‌گاه compset -P '*\=' رشتهٔ `a=b=' را به پارامتر IPREFIX منتقل می‌کند، اما compset -P 1 '*\=' فقط رشتهٔ `a=' را منتقل خواهد کرد.

-s number: مانند -p، اما آخرین number نویسه را از مقدار SUFFIX به ابتدای مقدار ISUFFIX منتقل می‌کند.
-S [ number ] pattern: مانند -P، اما بخش پایانی SUFFIX را تطبیق می‌دهد و بخش تطبیق‌یافته را به ابتدای مقدار ISUFFIX منتقل می‌کند.
-n begin [ end ]: اگر موقعیت کلمهٔ جاری همان‌طور که توسط پارامتر CURRENT مشخص شده بزرگ‌تر یا مساوی با begin باشد، همه چیز تا کلمهٔ beginام از آرایهٔ words حذف شده و از مقدار پارامتر CURRENT به اندازهٔ begin کاسته می‌شود.

اگر آرگومان اختیاری end داده شده باشد، تغییر فقط در صورتی انجام می‌شود که موقعیت کلمهٔ جاری کوچک‌تر یا مساوی با end نیز باشد. در این حالت، کلمات از موقعیت end به بعد نیز از آرایهٔ words حذف می‌شوند.

هر دو مقدار begin و end می‌توانند منفی باشند تا شمارش به‌صورت معکوس از آخرین عنصر آرایهٔ words انجام شود.

-N beg-pat [ end-pat ]: اگر یکی از عناصر آرایهٔ words پیش از عنصری که نمایه‌اش توسط مقدار پارامتر CURRENT تعیین شده با الگوی beg-pat مطابقت کند، تمام عناصر تا عنصر تطبیق‌یافته و خود آن از آرایهٔ words حذف می‌شوند و مقدار CURRENT تغییر می‌یابد تا به همان کلمه در آرایهٔ تغییریافته اشاره کند.

اگر الگوی اختیاری end-pat نیز داده شده باشد، و عنصری در آرایهٔ words وجود داشته باشد که با این الگو مطابقت کند، پارامترها تنها در صورتی تغییر می‌یابند که نمایهٔ این کلمه بزرگ‌تر از نمایهٔ ارائه‌شده توسط پارامتر CURRENT باشد (به‌طوری که کلمهٔ منطبق باید بعد از مکان‌نما باشد). در این حالت، کلمات شروع‌شده از کلمهٔ منطبق با end-pat نیز از آرایهٔ words حذف می‌شوند. اگر words شامل هیچ کلمه‌ای منطبق با end-pat نباشد، آزمایش و تغییر به‌گونه‌ای انجام می‌شود که گویی مشخص نشده است.

-q: کلمه‌ای که در حال حاضر تکمیل می‌شود، بر اساس فاصله‌ها و با رعایت قراردادهای معمول نقل‌قول پوسته به کلمات جداگانه تقسیم می‌شود. کلمات حاصل در آرایهٔ words ذخیره می‌شوند، و CURRENT، PREFIX، SUFFIX، QIPREFIX و QISUFFIX تغییر می‌یابند تا بخشی از کلمه را که تکمیل شده منعکس کنند.

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

if compset -P '*\='; then ...

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

compcall [ -TD ]: این دستور امکان استفاده از تکمیل‌های تعریف‌شده با دستور توکار compctl را از درون ویجت‌های تکمیل فراهم می‌کند. فهرست تطابق‌ها به گونه‌ای تولید خواهد شد که گویی یکی از توابع غیرویجتی تکمیل (complete-word و غیره) فراخوانی شده است، با این تفاوت که تنها compctlهای ارائه‌شده برای دستورهای خاص استفاده می‌شوند. برای وادار کردن کد به آزمایش تکمیل‌های تعریف‌شده با گزینهٔ -T از compctl و/یا تکمیل پیش‌فرض (خواه توسط compctl -D تعریف شده باشد یا پیش‌فرض توکار) در جایگاه‌های مناسب، پرچم‌های -T و/یا -D می‌توانند به compcall داده شوند.

از وضعیت بازگشتی می‌توان برای آزمایش اینکه آیا تعریف منطبقی برای compctl یافت شد یا خیر استفاده کرد. در صورتی که یک compctl پیدا شده باشد غیرصفر و در غیر این صورت صفر است.

توجه داشته باشید که این دستور توکار توسط ماژول zsh/compctl تعریف می‌شود.

کدهای شرطی تکمیل (COMPLETION CONDITION CODES)

کدهای شرطی اضافی زیر برای استفاده در ساختار [[ ... ]] در ویجت‌های تکمیل در دسترس هستند. این‌ها روی پارامترهای ویژه عمل می‌کنند. تمام این آزمایش‌ها می‌توانند توسط دستور توکار compset نیز انجام شوند، اما در مورد کدهای شرطی، محتوای پارامترهای ویژه تغییر نمی‌کند.

-prefix [ number ] pattern: درست است اگر آزمایش برای گزینهٔ -P از compset موفقیت‌آمیز باشد.
-suffix [ number ] pattern: درست است اگر آزمایش برای گزینهٔ -S از compset موفقیت‌آمیز باشد.
-after beg-pat: درست است اگر آزمایش گزینهٔ -N تنها با ارائهٔ beg-pat موفقیت‌آمیز باشد.
-between beg-pat end-pat: درست است اگر آزمایش برای گزینهٔ -N با هر دو الگو موفقیت‌آمیز باشد.

کنترل تطبیق تکمیل (COMPLETION MATCHING CONTROL)

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

الگوی تطبیق پیش‌فرض از کلمهٔ جاری به یکی از روش‌های زیر تولید می‌شود:

•: الحاق یک `*' (تطبیق با هر تعداد نویسه در یک تکمیل) یا،
•: اگر گزینهٔ پوستهٔ COMPLETE_IN_WORD تنظیم شده باشد، درج یک `*' در موقعیت مکان‌نما.

این الگوی محدود را می‌توان با ارسال یک مشخصهٔ تطبیق به دستور توکار compadd از طریق گزینهٔ -M آن، به‌صورت انتخابی گسترش داد (به `دستورهای توکار تکمیل' در بالا مراجعه کنید). یک مشخصهٔ تطبیق از یک یا چند تطبیق‌دهنده تشکیل شده است که با فاصله از هم جدا شده‌اند. تطبیق‌دهنده‌ها در یک مشخصهٔ تطبیق یکی پس از دیگری، از چپ به راست اعمال می‌شوند. پس از اعمال تمام تطبیق‌دهنده‌ها، تکمیل‌ها با الگوی تطبیق نهایی مقایسه شده و موارد غیرمنطبق کنار گذاشته می‌شوند.

•: توجه داشته باشید که اگر کلمهٔ جاری حاوی یک الگوی glob باشد و گزینهٔ پوستهٔ GLOB_COMPLETE تنظیم شده باشد، یا اگر کلید pattern_match از آرایهٔ انجمنی ویژهٔ compstate روی یک مقدار غیرخالی تنظیم شده باشد، گزینهٔ -M نادیده گرفته می‌شود (به `پارامترهای ویژهٔ تکمیل' در بالا مراجعه کنید).
•: کاربران سامانهٔ تکمیل (به zshcompsys(1) مراجعه کنید) به‌طور کلی نباید مستقیماً از گزینهٔ -M استفاده کنند، بلکه بهتر است از سبک‌های matcher-list و matcher استفاده نمایند (به زیربخش Standard Styles در مستندات COMPLETION SYSTEM CONFIGURATION در zshcompsys(1) مراجعه کنید).

هر تطبیق‌دهنده شامل موارد زیر است:

•: یک حرف حساس به حروف کوچک و بزرگ
•: یک `:'
•: یک یا چند الگو که با خطوط عمودی (`|') از هم جدا شده‌اند
•: یک علامت مساوی (`=')، و
•: الگویی دیگر.

الگوهای قبل از `=' برای تطبیق زیررشته‌های کلمهٔ جاری استفاده می‌شوند. برای هر زیررشتهٔ منطبق‌شده، بخش متناظر از الگوی تطبیق با الگوی پس از `=' از طریق یک OR منطقی گسترش می‌یابد.

هر الگو در یک تطبیق‌دهنده شامل یکی از موارد زیر است:

•: رشتهٔ خالی یا
•: دنباله‌ای از

•: نویسه‌های صریح (که ممکن است با یک `\' نقل‌قول شوند)،.TP • علامت‌های سؤال (`?')،
•: عبارت‌های قلاب (`[...]'؛ زیربخش Glob Operators را در مستندات GLOB OPERATORS در zshexpn(1) ببینید)، و/یا
•: عبارت‌های آکولاد (زیر را ببینید).

سایر الگوهای شل مجاز نیستند.

یک عبارت آکولاد، مانند یک عبارت قلاب، از فهرستی از موارد زیر تشکیل می‌شود:

•: نویسه‌های لفظی،
•: بازه‌ها (`0-9')، و/یا
•: رده‌های نویسه (`[:name:]').

با این حال، تفاوت‌های آن‌ها با یکدیگر به شرح زیر است:

•: یک عبارت آکولاد با یک جفت آکولاد (`{...}') محصور می‌شود.
•: عبارت‌های آکولاد از نقیض پشتیبانی نمی‌کنند. یعنی یک `!' یا `^' در آغاز معنای خاصی ندارد و به عنوان یک نویسه لفظی تفسیر خواهد شد.
•: هنگامی که یک نویسه در کلمه جاری با الگوی nام در یک عبارت آکولاد تطابق یابد، بخش متناظر الگوی تطبیق تنها با الگوی nام عبارت آکولاد در سمت دیگر `=' (در صورت وجود) بسط می‌یابد؛ اگر هیچ عبارت آکولادی در سمت دیگر نباشد، آن‌گاه این الگو رشته خالی خواهد بود. با این حال، اگر هر یک از عبارت‌های آکولاد عناصر بیشتری نسبت به دیگری داشته باشد، ورودی‌های اضافی نادیده گرفته می‌شوند. هنگام مقایسه اندیس‌ها، هر نویسه لفظی یا رده نویسه به عنوان یک عنصر شمارش می‌شود، اما در مقابل هر بازه به فهرست کاملی از نویسه‌های لفظی که بازنمایی می‌کند گسترش می‌یابد. علاوه بر این، اگر در هر دو طرف `='، الگوی nام `[:upper:]' یا `[:lower:]' باشد، این موارد نیز مانند بازه‌ها گسترش می‌یابند.

توجه داشته باشید که اگرچه سامانه تطبیق هنوز نویسه‌های چندبایتی را پشتیبانی نمی‌کند، احتمالاً این قابلیت در آینده افزوده خواهد شد. از این رو، استفاده از `[:upper:]' و `[:lower:]' به جای `A-Z' و `a-z' توصیه می‌شود.

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

مگر در مواردی که خلاف آن ذکر شده باشد، تمام مثال‌های ذکرشده فرض می‌کنند که COMPLETE_IN_WORD تنظیم نشده است (همان‌طور که به‌طور پیش‌فرض چنین است).

m:word-pat=match-pat
M:word-pat=match-pat

به ازای هر زیررشته از کلمه جاری که با word-pat مطابقت دارد، بخش متناظر الگوی تطبیق را بسط دهید تا علاوه بر آن با match-pat نیز تطابق یابد.

مثال‌ها:

m:{[:lower:]}={[:upper:]} امکان می‌دهد هر نویسه کوچک در کلمه جاری به خودش یا همتای بزرگش تکمیل شود. بنابراین، تکمیل‌های `foo'، `FOO' و `Foo' همگی تطابق‌هایی برای کلمه `fo' در نظر گرفته می‌شوند.

M:_= هر زیرخط (underscore) از کلمه جاری را در همان موقعیت نسبی، که بر اساس تطبیق زیررشته‌های اطراف آن تعیین می‌شود، در هر تطابق درج می‌کند. بنابراین، با فرض تکمیل `foo'، کلمه `f_o' به تطابق `f_oo' تکمیل خواهد شد، هرچند که این مورد اصلاً به عنوان یک تکمیل وجود نداشته است.

b:word-pat=match-pat
B:word-pat=match-pat
e:word-pat=match-pat
E:word-pat=match-pat

به ازای هر زیررشته متوالی در ابتدا (b:eginning) یا انتها (e:nd) کلمه جاری که با word-pat تطابق دارد، بخش متناظر الگوی تطبیق را بسط دهید تا علاوه بر آن با match-pat نیز مطابقت کند.

مثال‌ها:

`b:-=+' امکان می‌دهد هر تعداد علامت منفی در آغاز کلمه جاری به یک علامت منفی یا مثبت تکمیل شود.

`B:0=' تمام صفرهای ابتدای کلمه جاری را به ابتدای هر تطابق اضافه می‌کند.

l:|word-pat=match-pat
L:|word-pat=match-pat
r:word-pat|=match-pat
R:word-pat|=match-pat

اگر زیررشته‌ای در لبه چپ (l:eft) یا راست (r:ight) کلمه جاری وجود دارد که با word-pat تطابق می‌کند، بخش متناظر الگوی تطبیق را بسط دهید تا علاوه بر آن با match-pat نیز مطابقت داشته باشد.

برای هر یک از تطبیق‌دهنده‌های l:، L:، r: و R: (شامل موارد زیر)، الگوی match-pat می‌تواند یک `*' نیز باشد. این کار با هر تعداد نویسه در یک تکمیل تطابق می‌یابد.

مثال‌ها:

`r:|=*' یک `*' به انتهای الگوی تطبیق می‌افزاید، حتی زمانی که COMPLETE_IN_WORD تنظیم شده باشد و مکان‌نما در انتهای کلمه جاری نباشد.

اگر کلمه جاری با یک علامت منفی آغاز شود، `L:|-=' آن را به ابتدای هر تطابق می‌افزاید.

l:anchor|word-pat=match-pat
L:anchor|word-pat=match-pat
r:word-pat|anchor=match-pat
R:word-pat|anchor=match-pat

به ازای هر زیررشته از کلمه جاری که با word-pat تطابق دارد و در سمت چپ (l:eft) یا راست (r:ight) آن زیررشته دیگری منطبق با anchor قرار دارد، بخش متناظر الگوی تطبیق را بسط دهید تا علاوه بر آن با match-pat نیز مطابقت یابد.

توجه داشته باشید که این تطبیق‌دهنده‌ها (و موارد زیر) فقط آنچه را که توسط word-pat مطابقت داده شده تغییر می‌دهند؛ آن‌ها رفتار تطبیق آنچه توسط anchor (یا coanchor؛ تطبیق‌دهنده‌های زیر را ببینید) مطابقت یافته را تغییر نمی‌دهند. بنابراین، مگر اینکه بخش متناظر آن در الگوی تطبیق تغییر یافته باشد، لنگر (anchor) در کلمه جاری باید دقیقاً و عیناً در هر تکمیل مطابقت داشته باشد، درست مانند هر زیررشته دیگری از کلمه جاری.

اگر یک تطبیق‌دهنده دست‌کم شامل یک لنگر باشد (که شامل تطبیق‌دهنده‌های دارای دو لنگر در زیر نیز می‌شود)، آن‌گاه match-pat می‌تواند `*' یا `**' نیز باشد. `*' می‌تواند با هر بخشی از تکمیل که شامل هیچ زیررشته‌ای منطبق با anchor نباشد تطابق یابد، در حالی که `**' می‌تواند بدون هیچ قیدی با هر بخشی از یک تکمیل مطابقت کند. (توجه داشته باشید که این با رفتار `*' در حالت‌های بدون لنگر `l:' و `r:' و همچنین با `*' و `**' در عبارت‌های glob تفاوت دارد.).PP

مثال‌ها:

`r:|.=*' باعث می‌شود تکمیل `comp.sources.unix' با کلمه `..u' مطابقت پیدا کند -- اما نه با کلمه `.u'.

با فرض تکمیل `--foo'، تطبیق‌دهنده `L:--|no-=' کلمه `--no-' را به تطابق `--no-foo' کامل خواهد کرد.

l:anchor||coanchor=match-pat
L:anchor||coanchor=match-pat
r:coanchor||anchor=match-pat
R:coanchor||anchor=match-pat

به‌ازای هر دو زیررشته متوالی از کلمه جاری که به ترتیب مشخص‌شده با anchor و coanchor مطابقت دارند، الگوی match-pat را بین بخش‌های متناظر آن‌ها در الگوی تطابق درج می‌کند.

توجه داشته باشید که برخلاف anchor، الگوی coanchor آنچه را که `*' می‌تواند با آن تطابق یابد تغییر نمی‌دهد.

مثال‌ها:

`r:?||[[:upper:]]=*' کلمه جاری `fB' را به `fooBar' تکمیل خواهد کرد، اما آن را به `fooHooBar' تکمیل نمی‌کند (زیرا `*' در اینجا نمی‌تواند با چیزی که شامل تطابقی برای `[[:upper:]] باشد مطابقت کند)، و همچنین `B' را به `fooBar' تکمیل نخواهد کرد (زیرا هیچ نویسه‌ای در کلمه جاری برای تطابق با coanchor وجود ندارد).

با فرض کلمه جاری `pass.n' و تکمیل `pass.byname'، تطبیق‌دهنده `L:.||[[:alpha:]]=by' تطابق `pass.name' را تولید خواهد کرد.

x:

این تطبیق‌دهنده و تمام تطبیق‌دهنده‌های سمت راست آن را نادیده می‌گیرد.

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

مثال ویجت تکمیل (COMPLETION WIDGET EXAMPLE)

نخستین گام، تعریف ویجت است:

zle -C complete complete-word complete-files

سپس می‌توان این ویجت را با استفاده از دستور توکار bindkey به یک کلید متصل کرد:

bindkey '^X\t' complete

پس از آن، با فشردن control-X و TAB، تابع پوسته complete-files فراخوانی خواهد شد. این تابع سپس باید تطابق‌ها را تولید کند، مانند:

complete-files () { compadd - * }

این تابع، فایل‌های موجود در دایرکتوری جاری را که با کلمه جاری مطابقت دارند تکمیل خواهد کرد.

July 12, 2026

zsh 5.9.2