.TH "ZSHCONTRIB" "1" "July 12, 2026" "zsh 5\&.9\&.2"
.SH "نام (NAME)"
zshcontrib \- مشارکت‌های کاربران در zsh
.\" Yodl file: Zsh/contrib.yo
.SH "توضیحات (DESCRIPTION)"
.PP
توزیع سورس‌کد Zsh شامل مواردی است که توسط جامعه کاربران مشارکت شده است\&. این موارد ذاتاً بخشی از پوسته نیستند و ممکن است برخی از آن‌ها در هر نصب zsh در دسترس نباشند\&. مهم‌ترین این موارد در اینجا مستند شده‌اند\&. برای مستندات مربوط به سایر موارد مشارکت‌شده مانند توابع پوسته، به کامنت‌های موجود در فایل‌های منبع توابع مراجعه کنید\&.
.PP
.PP
.SH "ابزارها (UTILITIES)"
.PP
.SS "دسترسی به راهنمای برخط (Accessing On\-Line Help)"
.PP
دنباله کلیدهای \fBESC h\fP معمولاً توسط ZLE برای اجرای ابزارک \fBrun\-help\fP مقید (bind) شده است (به \fIzshzle\fP(1) مراجعه کنید)\&. این کار دستور \fBrun\-help\fP را با کلمه دستوری خط ورودی فعلی به عنوان آرگومان آن فراخوانی می‌کند\&. به‌طور پیش‌فرض، \fBrun\-help\fP یک نام مستعار (alias) برای دستور \fBman\fP است، بنابراین هنگامی که کلمه دستوری یک دستور توکار پوسته یا یک تابع تعریف‌شده توسط کاربر باشد، اغلب با شکست مواجه می‌شود\&. با بازتعریف نام مستعار \fBrun\-help\fP، می‌توان راهنمای برخط ارائه‌شده توسط پوسته را بهبود بخشید\&.
.PP
ابزار \fBhelpfiles\fP، موجود در دایرکتوری \fBUtil\fP توزیع، برنامه‌ای به زبان Perl است که می‌تواند برای پردازش راهنمای zsh جهت تولید یک فایل راهنمای جداگانه برای هر دستور توکار پوسته و همچنین بسیاری از دیگر ویژگی‌های پوسته استفاده شود\&. تابع با قابلیت بارگذاری خودکار (autoloadable) \fBrun\-help\fP، موجود در \fBFunctions/Misc\fP، این فایل‌های راهنما را جستجو کرده و چندین بررسی دیگر را انجام می‌دهد تا کامل‌ترین راهنمای ممکن را برای دستور تولید کند\&.
.PP
فایل‌های راهنما به‌طور پیش‌فرض در زیردایرکتوری از \fB/usr/share/zsh\fP یا \fB/usr/local/share/zsh\fP نصب می‌شوند\&.
.PP
برای ایجاد فایل‌های راهنمای اختصاصی با \fBhelpfiles\fP، دایرکتوری‌ای را که فایل‌های راهنمای هر دستور در آن قرار خواهند گرفت، انتخاب یا ایجاد کنید\&. برای مثال، می‌توانید \fB~/zsh_help\fP را انتخاب کنید\&. اگر توزیع zsh را در دایرکتوری خانگی خود استخراج کرده‌اید، از این دستورات استفاده کنید:
.PP
.RS
.nf
\fBmkdir ~/zsh_help
perl ~/zsh\-5\&.9\&.2/Util/helpfiles ~/zsh_help\fP
.fi
.RE
.PP
پارامتر \fBHELPDIR\fP به \fBrun\-help\fP می‌گوید در کجا به دنبال فایل‌های راهنما بگردد\&. در صورت تنظیم نشدن، از مسیر نصب پیش‌فرض استفاده می‌کند\&. برای استفاده از مجموعه فایل‌های راهنمای خود، این متغیر را در یکی از فایل‌های راه‌اندازی (startup) خود بر روی مسیر مناسب تنظیم کنید:
.PP
.RS
.nf
\fBHELPDIR=~/zsh_help\fP
.fi
.RE
.PP
برای استفاده از تابع \fBrun\-help\fP، باید خطوطی شبیه به موارد زیر را به \fB\&.zshrc\fP یا فایل راه‌اندازی معادل خود اضافه کنید:
.PP
.RS
.nf
\fBunalias run\-help
autoload run\-help\fP
.fi
.RE
.PP
توجه داشته باشید که برای کارکرد `\fBautoload run\-help\fP\&`، فایل \fBrun\-help\fP باید در یکی از دایرکتوری‌های مشخص‌شده در آرایه \fBfpath\fP شما قرار داشته باشد (به \fIzshparam\fP(1) مراجعه کنید)\&. در یک نصب استاندارد zsh باید چنین باشد؛ اگر این‌طور نیست، \fBFunctions/Misc/run\-help\fP را در یک دایرکتوری مناسب کپی کنید\&.
.PP
.SS "کامپایل مجدد توابع (Recompiling Functions)"
.PP
اگر مرتباً توابع zsh خود را ویرایش می‌کنید یا برای پیگیری آخرین تغییرات، نصب zsh خود را به صورت دوره‌ای به‌روزرسانی می‌کنید، ممکن است متوجه شوید که فایل‌های چکیده توابع (function digests) کامپایل‌شده با دستور توکار \fBzcompile\fP نسبت به فایل‌های منبع توابع، اغلب منسوخ و قدیمی می‌شوند\&. این موضوع معمولاً مشکلی ایجاد نمی‌کند، زیرا zsh هنگام بارگذاری یک تابع همیشه به دنبال جدیدترین فایل می‌گردد، اما ممکن است باعث کندتر شدن راه‌اندازی پوسته و بارگذاری توابع شود\&. همچنین اگر یک فایل دایجست صریحاً به عنوان عنصری از \fBfpath\fP استفاده شده باشد، zsh بررسی نخواهد کرد که آیا هیچ‌یک از فایل‌های منبع آن تغییر کرده‌اند یا خیر\&.
.PP
تابع قابل بارگذاری خودکار \fBzrecompile\fP، موجود در \fBFunctions/Misc\fP، می‌تواند برای به‌روز نگه داشتن فایل‌های دایجست توابع استفاده شود\&.
.PP
.PD 0
.TP
.PD 0
\fBzrecompile\fP [ \fB\-qt\fP ] [ \fIname\fP \&.\&.\&. ]
.TP
.PD
\fBzrecompile\fP [ \fB\-qt\fP ] \fB\-p\fP \fIarg\fP \&.\&.\&. [ \fB\-\fP\fB\-\fP \fIarg\fP \&.\&.\&. ]
این ابزار تلاش می‌کند فایل‌های \fB*\&.zwc\fP را پیدا کرده و در صورتی که حداقل یکی از فایل‌های اصلی از فایل کامپایل‌شده جدیدتر باشد، آنها را به‌طور خودکار دوباره کامپایل کند\&. این قابلیت تنها در صورتی عمل می‌کند که نام‌های ذخیره‌شده در فایل‌های کامپایل‌شده، مسیرهای کامل باشند یا نسبت به دایرکتوریِ حاوی فایل \fB\&.zwc\fP نسبی باشند\&.
.RS
.PP
در فرم اول، هر \fIname\fP نام یک فایل کامپایل‌شده یا دایرکتوری شامل فایل‌های \fB*\&.zwc\fP است که باید بررسی شوند\&. اگر هیچ آرگومانی داده نشود، دایرکتوری‌ها و فایل‌های \fB*\&.zwc\fP موجود در \fBfpath\fP استفاده می‌شوند\&.
.PP
هنگامی که \fB\-t\fP داده شود، هیچ کامپایلی انجام نمی‌شود، اما اگر فایل‌هایی وجود داشته باشند که نیاز به کامپایل مجدد دارند، وضعیت خروج صفر (درست) و در غیر این صورت غیرصفر (نادرست) تنظیم می‌شود\&. گزینه \fB\-q\fP خروجی‌های تفصیلی را که اقدامات \fBzrecompile\fP را شرح می‌دهند، بی‌صدا می‌کند\&.
.PP
بدون گزینه \fB\-t\fP، وضعیت خروج در صورتی صفر است که تمام فایل‌های نیازمند کامپایل مجدد با موفقیت کامپایل شوند، و اگر کامپایل حداقل یکی از فایل‌ها با شکست مواجه شود، غیرصفر خواهد بود\&.
.PP
اگر گزینه \fB\-p\fP داده شود، \fIarg\fPها به عنوان یک یا چند مجموعه آرگومان برای \fBzcompile\fP تفسیر می‌شوند که با `\fB\-\fP\fB\-\fP\&` از یکدیگر جدا شده‌اند\&. برای مثال:
.PP
.RS
.nf
\fBzrecompile \-p \e 
           \-R ~/\&.zshrc \-\- \e 
           \-M ~/\&.zcompdump \-\- \e 
           ~/zsh/comp\&.zwc ~/zsh/Completion/*/_*\fP
.fi
.RE
.PP
این دستور در صورتی که \fB~/\&.zshrc\&.zwc\fP وجود نداشته باشد یا از \fB~/\&.zshrc\fP قدیمی‌تر باشد، \fB~/\&.zshrc\fP را به \fB~/\&.zshrc\&.zwc\fP کامپایل می‌کند\&. فایل کامپایل‌شده به جای نگاشت (mapping)، برای خواندن علامت‌گذاری خواهد شد\&. همین عمل برای \fB~/\&.zcompdump\fP و \fB~/\&.zcompdump\&.zwc\fP انجام می‌شود، اما این فایل کامپایل‌شده برای نگاشت نشانه‌گذاری می‌گردد\&. آخرین خط در صورتی که هر یک از فایل‌های منطبق با الگوی ارائه‌شده از آن جدیدتر باشند، فایل \fB~/zsh/comp\&.zwc\fP را مجدداً ایجاد می‌کند\&.
.PP
بدون گزینه \fB\-p\fP، دستور \fBzrecompile\fP فایل‌های دایجست تابعی را که از قبل وجود ندارند ایجاد نمی‌کند، و همچنین توابع جدید را به فایل دایجست اضافه نخواهد کرد\&.
.RE
.PP
حلقه پوسته زیر، نمونه‌ای از روشی برای ایجاد خلاصه‌های توابع برای تمام توابع موجود در \fBfpath\fP شما است، با این فرض که دسترسی نوشتن در آن دایرکتوری‌ها را داشته باشید:
.PP
.RS
.nf
\fBfor ((i=1; i <= $#fpath; ++i)); do
  dir=$fpath[i]
  zwc=${dir:t}\&.zwc
  if [[ $dir == (\&.|\&.\&.) || $dir == (\&.|\&.\&.)/* ]]; then
    continue
  fi
  files=($dir/*(N\-\&.))
  if [[ \-w $dir:h && \-n $files ]]; then
    files=(${${(M)files%/*/*}#/})
    if ( cd $dir:h &&
         zrecompile \-p \-U \-z $zwc $files ); then
      fpath[i]=$fpath[i]\&.zwc
    fi
  fi
done\fP
.fi
.RE
.PP
گزینه‌های \fB\-U\fP و \fB\-z\fP برای توابع موجود در \fBfpath\fP پیش‌فرضِ نصب zsh مناسب هستند؛ ممکن است برای دایرکتوری‌های توابع شخصی خود نیاز به استفاده از گزینه‌های متفاوتی داشته باشید\&.
.PP
هنگامی که دایجست‌ها ایجاد شدند و \fBfpath\fP شما برای ارجاع به آنها تغییر یافت، می‌توانید با اجرای \fBzrecompile\fP بدون هیچ آرگومانی، آنها را به‌روز نگه دارید\&.
.PP.SS "تعریف صفحه‌کلید (Keyboard Definition)"
.PP
تعداد بسیار زیاد ترکیب‌های ممکن از صفحه‌کلیدها، ایستگاه‌های کاری، پایانه‌ها، شبیه‌سازها و سیستم‌های پنجره‌ای، باعث می‌شود zsh نتواند مقیدسازی‌های پیش‌ساخته کلیدها را برای هر وضعیتی در خود داشته باشد\&. ابزار کاربردی \fBzkbd\fP، واقع در \fBFunctions/Misc\fP، می‌تواند به شما کمک کند تا سریعاً برای پیکربندی خود مقیدسازی‌های کلید را بسازید\&.
.PP
ابزار \fBzkbd\fP را یا به عنوان یک تابع خودبارگذاری‌شونده (autoloaded)، یا به شکل یک اسکریپت پوسته اجرا کنید:
.PP
.RS
.nf
\fBzsh \-f ~/zsh\-5\&.9\&.2/Functions/Misc/zkbd\fP
.fi
.RE
.PP
هنگامی که \fBzkbd\fP را اجرا می‌کنید، ابتدا از شما می‌خواهد که نوع پایانه خود را وارد کنید؛ اگر مقدار پیش‌فرضی که پیشنهاد می‌دهد صحیح است، کافی است کلید return را فشار دهید\&. سپس از شما می‌خواهد تعدادی کلید مختلف را بفشارید تا مشخصات صفحه‌کلید و پایانه شما را تشخیص دهد؛ \fBzkbd\fP در صورتی که با موردی غیرعادی برخورد کند به شما هشدار می‌دهد، مانند کلید Delete که نه \fB^H\fP و نه \fB^?\fP را ارسال می‌کند\&.
.PP
کلیدهای فشرده‌شده‌ای که توسط \fBzkbd\fP خوانده می‌شوند، به عنوان تعریفی برای یک آرایه انجمنی به نام \fBkey\fP ثبت شده و در فایلی در زیرپوشه \fB\&.zkbd\fP درون دایرکتوری \fBHOME\fP یا \fBZDOTDIR\fP شما نوشته می‌شوند\&. نام این فایل از پارامترهای \fBTERM\fP، \fBVENDOR\fP و \fBOSTYPE\fP تشکیل می‌شود که با خط تیره (hyphen) به هم متصل شده‌اند\&.
.PP
شما می‌توانید این فایل را با دستورات «\fBsource\fP» یا «\fB\&.\fP» در \fB\&.zshrc\fP یا یک فایل راه‌اندازی دیگر بخوانید، و سپس به پارامتر \fBkey\fP در دستورات bindkey ارجاع دهید، مانند این:
.PP
.RS
.nf
\fBsource ${ZDOTDIR:\-$HOME}/\&.zkbd/$TERM\-$VENDOR\-$OSTYPE
[[ \-n ${key[Left]} ]] && bindkey "${key[Left]}" backward\-char
[[ \-n ${key[Right]} ]] && bindkey "${key[Right]}" forward\-char
# etc\&.\fP
.fi
.RE
.PP
توجه داشته باشید که برای کارکردن «\fBautoload zkbd\fP»، فایل \fBzkdb\fP باید در یکی از دایرکتوری‌های مشخص‌شده در آرایه \fBfpath\fP شما قرار داشته باشد (به \fIzshparam\fP(1) مراجعه کنید)\&. اگر یک نصب استاندارد zsh را دارید، این مورد از پیش برقرار است؛ در غیر این صورت، \fBFunctions/Misc/zkbd\fP را در یک دایرکتوری مناسب کپی کنید\&.
.PP
.SS "تخلیه وضعیت پوسته (Dumping Shell State)"
.PP
گاهی اوقات ممکن است با چیزی مواجه شوید که به نظر یک باگ در پوسته می‌آید، به‌ویژه اگر از نسخه بتا یا یک نسخه توسعه zsh استفاده می‌کنید\&. معمولاً ارسال شرح مشکل به یکی از فهرست‌های پستی zsh کافی است (به \fIzsh\fP(1) مراجعه کنید)، اما گاهی اوقات یکی از توسعه‌دهندگان zsh نیاز خواهد داشت که برای ردیابی مشکل، محیط شما را بازسازی کند\&.
.PP
اسکریپتی به نام \fBreporter\fP، واقع در دایرکتوری \fBUtil\fP توزیع، برای این منظور ارائه شده است\&. (امکان اجرای \fBautoload reporter\fP نیز وجود دارد، اما \fBreporter\fP به طور پیش‌فرض در \fBfpath\fP نصب نشده است\&.) این اسکریپت خروجی تخلیه مفصلی از وضعیت پوسته را در قالب اسکریپت دیگری تولید می‌کند که می‌توان آن را با «\fBzsh \-f\fP» خواند تا آن وضعیت دوباره بازسازی شود\&.
.PP
برای استفاده از \fBreporter\fP، اسکریپت را با دستور «\fB\&.\fP» در پوسته خود بخوانید و خروجی را به یک فایل هدایت کنید:
.PP
.RS
.nf
\fB\&. ~/zsh\-5\&.9\&.2/Util/reporter > zsh\&.report\fP
.fi
.RE
.PP
شما باید فایل \fBzsh\&.report\fP را برای هرگونه اطلاعات حساس مانند گذرواژه‌ها بررسی کرده و قبل از ارسال اسکریپت به توسعه‌دهندگان، آن‌ها را به صورت دستی حذف کنید\&. همچنین، از آنجا که خروجی ممکن است بسیار حجیم باشد، بهتر است منتظر بمانید تا توسعه‌دهندگان این اطلاعات را درخواست کنند و سپس آن را بفرستید\&.
.PP
همچنین می‌توانید از \fBreporter\fP برای تخلیه تنها زیرمجموعه‌ای از وضعیت پوسته استفاده کنید\&. این کار گاهی برای ایجاد فایل‌های راه‌اندازی برای نخستین بار مفید است\&. بیشتر خروجی reporter بسیار مفصل‌تر از آن چیزی است که معمولاً برای یک فایل راه‌اندازی نیاز است، اما وضعیت‌های \fBaliases\fP، \fBoptions\fP و \fBzstyles\fP ممکن است مفید باشند، زیرا فقط تغییرات نسبت به مقادیر پیش‌فرض را شامل می‌شوند\&. وضعیت \fBbindings\fP در صورتی که نگاشت‌های کلید اختصاصی خود را ساخته باشید ممکن است مفید باشد، زیرا \fBreporter\fP دستورات ایجاد نگاشت کلید و همچنین مقیدسازی‌های هر نگاشت کلید را خروجی می‌دهد\&.
.PP
همان‌طور که در مورد ابزارهای خودکار معمول است، اگر با \fBreporter\fP یک فایل راه‌اندازی ایجاد می‌کنید، باید نتایج را برای حذف دستورات غیرضروری ویرایش کنید\&. توجه داشته باشید که در صورت استفاده از سیستم تکمیل جدید، \fIنباید\fP وضعیت \fBfunctions\fP را با \fBreporter\fP در فایل‌های راه‌اندازی خود تخلیه کنید؛ در عوض از تابع \fBcompdump\fP استفاده کنید (به \fIzshcompsys\fP(1) مراجعه کنید)\&.
.PP
.PD 0
.TP
.PD
\fBreporter\fP [ \fIstate\fP \&.\&.\&. ]
زیرمجموعه مشخص‌شده از وضعیت فعلی پوسته را در خروجی استاندارد چاپ می‌کند\&. آرگومان‌های \fIstate\fP می‌توانند یک یا چند مورد از موارد زیر باشند:
.RS
.PP
.PD 0
.TP
\fBall\fP
تمام موارد فهرست‌شده در زیر را در خروجی قرار می‌دهد\&.
.TP
\fBaliases\fP
تعاریف alias را خروجی می‌دهد\&.
.TP
\fBbindings\fP
نگاشت‌های کلید و مقیدسازی‌های ZLE را خروجی می‌دهد\&.
.TP
\fBcompletion\fP
دستورات سبک قدیمی \fBcompctl\fP را خروجی می‌دهد\&. تکمیل جدید توسط \fBfunctions\fP و \fBzstyles\fP پوشش داده می‌شود\&.
.TP
\fBfunctions\fP
بارگذاری‌های خودکار (autoloads) و تعاریف توابع را خروجی می‌دهد\&.
.TP
\fBlimits\fP
دستورات \fBlimit\fP را خروجی می‌دهد\&.
.TP
\fBoptions\fP
دستورات \fBsetopt\fP را خروجی می‌دهد\&.
.TP
\fBstyles\fP
مشابه \fBzstyles\fP\&.
.TP
\fBvariables\fP
مقداردهی پارامترهای پوسته، به علاوه دستورات \fBexport\fP برای متغیرهای محیطی را خروجی می‌دهد\&.
.TP
\fBzstyles\fP
دستورات \fBzstyle\fP را خروجی می‌دهد\&.
.PD
.PP
اگر \fIstate\fP حذف شود، \fBall\fP در نظر گرفته می‌شود\&.
.RE
.PP
به استثنای «\fBall\fP»، هر \fIstate\fP می‌تواند با هر پیشوندی خلاصه شود، حتی یک حرف منفرد؛ بنابراین \fBa\fP همان \fBaliases\fP است، \fBz\fP همان \fBzstyles\fP است، و غیره\&.
.PP.SS "دستکاری توابع قلاب (Manipulating Hook Functions)"
.PP
.PD 0
.TP
.PD
\fBadd\-zsh\-hook\fP [ \fB\-L\fP | \fB\-dD\fP ] [ \fB\-Uzk\fP ] \fIhook\fP \fIfunction\fP
چندین تابع برای پوسته خاص هستند، همان‌طور که در بخش
SPECIAL FUNCTIONS، ببینید \fIzshmisc\fP(1)، شرح داده شده است،
از این جهت که در نقاط مشخصی در طول اجرای پوسته به‌طور خودکار فراخوانی می‌شوند\&.
هر یک دارای یک آرایهٔ مرتبط متشکل از نام توابعی است که باید
در همان نقطه فراخوانی شوند؛ این‌ها اصطلاحاً `hook functions\&' (توابع قلاب) نامیده می‌شوند\&.
تابع پوستهٔ \fBadd\-zsh\-hook\fP روشی ساده برای افزودن یا
حذف توابع از این آرایه فراهم می‌کند\&.
.RS
.PP
آرگومان \fIhook\fP یکی از توابع خاص مورد نظر شامل \fBchpwd\fP، \fBperiodic\fP، \fBprecmd\fP، \fBpreexec\fP،
\fBzshaddhistory\fP، \fBzshexit\fP یا \fBzsh_directory_name\fP است\&.  توجه داشته باشید که \fBzsh_directory_name\fP
به روش متفاوتی نسبت به سایر توابع فراخوانی می‌شود، اما همچنان
می‌تواند به‌عنوان یک قلاب دستکاری شود\&.
.PP
آرگومان \fIfunction\fP نام یک تابع عادی پوسته است\&.  اگر هیچ گزینه‌ای
داده نشود، این تابع به آرایهٔ توابعی که باید در بافت داده‌شده اجرا شوند
اضافه خواهد شد\&.
توابع به ترتیبی که اضافه شده‌اند فراخوانی می‌شوند\&.
.PP
اگر گزینهٔ \fB\-L\fP داده شود، مقادیر فعلی آرایه‌های قلاب
با \fBtypeset\fP فهرست می‌شوند\&.
.PP
اگر گزینهٔ \fB\-d\fP داده شود، تابع \fIfunction\fP از
آرایهٔ توابعی که باید اجرا شوند حذف می‌شود\&.
.PP
اگر گزینهٔ \fB\-D\fP داده شود، با \fIfunction\fP مانند یک الگو رفتار می‌شود
و هر نام تابع مطابقی از آرایهٔ توابعی که باید اجرا شوند
حذف خواهد شد\&.
.PP
گزینه‌های \fB\-U\fP، \fB\-z\fP و \fB\-k\fP به‌عنوان آرگومان برای
\fIfunction\fP به \fBautoload\fP فرستاده می‌شوند\&.  برای توابعی که همراه با zsh ارائه می‌شوند،
گزینه‌های \fB\-Uz\fP مناسب هستند\&.
.RE
.TP
\fBadd\-zle\-hook\-widget\fP [ \fB\-L\fP | \fB\-dD\fP ] [ \fB\-Uzk\fP ] \fIhook\fP \fIwidgetname\fP
چندین نام ابزارک برای ویرایشگر خط خاص هستند، همان‌طور که در بخش
Special Widgets، ببینید \fIzshzle\fP(1)، شرح داده شده است،
از این جهت که در نقاط مشخصی در طول ویرایش به‌طور خودکار فراخوانی می‌شوند\&.
برخلاف قلاب‌های توابع، این‌ها از یک آرایهٔ از پیش تعریف‌شده از نام‌های دیگر
برای فراخوانی در همان نقطه استفاده نمی‌کنند؛ تابع پوستهٔ \fBadd\-zle\-hook\-widget\fP
آرایه‌ای مشابه را نگهداری کرده و شرایطی را فراهم می‌کند تا ابزارک خاص
آن ابزارک‌های اضافی را فراخوانی کند\&.
.RS
.PP
آرگومان \fIhook\fP یکی از موارد \fBisearch\-exit\fP، \fBisearch\-update\fP،
\fBline\-pre\-redraw\fP، \fBline\-init\fP، \fBline\-finish\fP، \fBhistory\-line\-set\fP،
یا \fBkeymap\-select\fP است که متناظر با هر یک از ابزارک‌های خاص
\fBzle\-isearch\-exit\fP و غیره می‌باشند\&.  نام ابزارک‌های خاص نیز
به‌عنوان آرگومان \fIhook\fP پذیرفته می‌شوند\&.
.PP
آرگومان \fIwidgetname\fP نام یک ابزارک ZLE است\&.  اگر هیچ گزینه‌ای داده نشود،
این ابزارک به آرایهٔ ابزارک‌هایی که باید در بافت قلاب داده‌شده فراخوانی شوند اضافه می‌شود\&.
ابزارک‌ها به ترتیبی که افزوده شده‌اند فراخوانی می‌شوند، با
.RS
.nf
\fB\fBzle \fP\fIwidgetname\fP\fB \-Nw \-f "nolast" \-\- "$@"\fP\fP
.fi
.RE
.PP
توجه داشته باشید که این بدان معناست که پارامتر ویژهٔ `\fBWIDGET\fP\&' هنگام
فراخوانی تابع ابزارک، به‌جای ردگیری نام ابزارک قلاب خاص متناظر،
\fIwidgetname\fP را ردگیری می‌کند\&.
.PP
اگر گزینهٔ \fB\-d\fP داده شود، \fIwidgetname\fP از
آرایهٔ ابزارک‌هایی که باید اجرا شوند حذف می‌شود\&.
.PP
اگر گزینهٔ \fB\-D\fP داده شود، با \fIwidgetname\fP مانند یک الگو رفتار می‌شود
و هر نام ابزارک مطابق از آرایه حذف خواهد شد\&.
.PP
اگر \fIwidgetname\fP هنگام افزوده شدن به آرایه نام یک ابزارک موجود نباشد،
فرض می‌شود که یک تابع پوسته نیز با نام \fIwidgetname\fP قرار است
پیاده‌سازی این ابزارک را فراهم کند\&.  بنابراین این نام برای بارگذاری خودکار
نشانه‌گذاری می‌شود، و گزینه‌های \fB\-U\fP، \fB\-z\fP و \fB\-k\fP همانند
\fBadd\-zsh\-hook\fP به‌عنوان آرگومان به \fBautoload\fP فرستاده می‌شوند\&.  ابزارک
همچنین با `\fBzle \-N \fP\fIwidgetname\fP\&' ایجاد می‌شود تا باعث شود
تابع متناظر در نخستین باری که قلاب فراخوانی می‌شود بارگذاری گردد\&.
.PP
آرایه‌های \fIwidgetname\fP در حال حاضر در بافت‌های \fBzstyle\fP
نگهداری می‌شوند، یکی برای هر بافت \fIhook\fP، با سبکی از `\fBwidgets\fP\&'\&.
اگر گزینهٔ \fB\-L\fP داده شود، این مجموعه از سبک‌ها با
`\fBzstyle \-L\fP\&' فهرست می‌شوند\&.  این پیاده‌سازی ممکن است تغییر کند، و ابزارک‌های خاصی
که به این سبک‌ها ارجاع دارند تنها در صورتی ایجاد می‌شوند که \fBadd\-zle\-hook\-widget\fP
برای افزودن حداقل یک ابزارک فراخوانی شده باشد؛ بنابراین اگر از این تابع برای
هر قلابی استفاده شود، تمام قلاب‌ها باید منحصراً از طریق همین تابع مدیریت شوند\&.
.RE
.PP.SH "به‌خاطرسپاری دایرکتوری‌های اخیر (REMEMBERING RECENT DIRECTORIES)"
.PP
تابع \fBcdr\fP به شما امکان می‌دهد دایرکتوری کاری را به یکی از دایرکتوری‌های کاری قبلی از فهرستی که به‌طور خودکار نگهداری می‌شود، تغییر دهید\&. این مفهوم مشابه پشتهٔ دایرکتوری است که توسط توابع توکار \fBpushd\fP، \fBpopd\fP و \fBdirs\fP کنترل می‌شود، اما قابلیت پیکربندی بیشتری دارد و از آنجا که تمام ورودی‌ها را در فایل‌ها ذخیره می‌کند، در بین نشست‌های مختلف و (به‌طور پیش‌فرض) بین شبیه‌سازهای ترمینال در نشست جاری حفظ می‌شود\&. موارد تکراری به‌طور خودکار حذف می‌شوند تا فهرست، آخرین استفاده از هر دایرکتوری را منعکس کند\&.
.PP
توجه داشته باشید که پشتهٔ دایرکتوری \fBpushd\fP در واقع توسط \fBcdr\fP تغییر داده نشده یا استفاده نمی‌شود، مگر اینکه آن را مطابق توضیحات بخش پیکربندی در زیر، برای این کار پیکربندی کرده باشید\&.
.PP
.SS "نصب (Installation)"
.PP
این سازوکار به کمک یک تابع قلاب (hook function) کار می‌کند که هر بار با تغییر دایرکتوری فراخوانی می‌شود\&. برای نصب این سیستم، توابع مورد نیاز را autoload کرده و از تابع \fBadd\-zsh\-hook\fP که در بالا توضیح داده شد استفاده کنید:
.PP
.RS
.nf
\fBautoload \-Uz chpwd_recent_dirs cdr add\-zsh\-hook
add\-zsh\-hook chpwd chpwd_recent_dirs\fP
.fi
.RE
.PP
اکنون هر بار که دایرکتوری را به‌صورت تعاملی تغییر دهید، بدون توجه به اینکه از چه دستوری استفاده می‌کنید، دایرکتوری‌ای که به آن وارد می‌شوید به ترتیب از جدیدترین به قدیمی‌ترین به‌خاطر سپرده خواهد شد\&.
.PP
.SS "استفاده (Use)"
.PP
تمام تعامل مستقیم کاربر از طریق تابع \fBcdr\fP انجام می‌شود\&.
.PP
آرگومان ورودی cdr یک عدد \fIN\fP متناظر با \fIN\fPامین دایرکتوری است که اخیراً به آن وارد شده‌اید\&. عدد 1 دایرکتوری بلافاصله قبلی است؛ دایرکتوری جاری به‌خاطر سپرده می‌شود اما به عنوان مقصد پیشنهاد داده نمی‌شود\&. توجه داشته باشید که اگر چندین پنجره باز داشته باشید، عدد 1 ممکن است به دایرکتوری تغییریافته در پنجره‌ای دیگر اشاره کند؛ شما می‌توانید با استفاده از فایل‌های مجزا به ازای هر ترمینال برای ذخیره دایرکتوری، مطابق آنچه در شیوهٔ \fBrecent\-dirs\-file\fP در زیر توضیح داده شده است، از این مسئله جلوگیری کنید\&.
.PP
اگر شیوهٔ \fBrecent\-dirs\-default\fP توضیح‌داده‌شده در زیر را تنظیم کنید، در صورت ارائه یک آرگومان غیرعددی یا بیش از یک آرگومان، \fBcdr\fP رفتاری مشابه با \fBcd\fP خواهد داشت\&. با هر روشی که دایرکتوری را تغییر دهید، فهرست دایرکتوری‌های اخیر به همان صورت به‌روزرسانی می‌شود\&.
.PP
در صورت حذف آرگومان، مقدار 1 فرض می‌شود\&. این رفتار شبیه به رفتار \fBpushd\fP در جابجایی دو دایرکتوری اخیر روی پشته است\&.
.PP
تکمیل خودکار (completion) برای آرگومان \fBcdr\fP در صورتی که compinit اجرا شده باشد در دسترس است؛ انتخاب منویی پیشنهاد می‌شود، با استفاده از:
.PP
.RS
.nf
\fBzstyle \&':completion:*:*:cdr:*:*' menu selection\fP
.fi
.RE
.PP
تا به شما اجازه دهد بین دایرکتوری‌های اخیر پیمایش کنید؛ ترتیب حفظ می‌شود، بنابراین اولین انتخاب جدیدترین دایرکتوری قبل از دایرکتوری فعلی است\&. شیوهٔ verbose نیز برای اطمینان از نمایش دایرکتوری توصیه می‌شود؛ این سبک به‌طور پیش‌فرض فعال است، بنابراین نیازی به انجام کاری نیست مگر اینکه آن را تغییر داده باشید\&.
.PP
.SS "گزینه‌ها (Options)"
.PP
رفتار \fBcdr\fP ممکن است با گزینه‌های زیر تغییر داده شود\&.
.PP
.PD 0
.TP
.PD
\fB\-l\fP
شماره‌ها و دایرکتوری‌های متناظر را به صورت کوتاه شده (یعنی با اعمال مجدد جایگزینی \fB~\fP)، در هر سطر یکی فهرست می‌کند\&. دایرکتوری‌ها در اینجا درون علامت نقل‌قول قرار نمی‌گیرند (این موضوع تنها زمانی ایجاد اشکال می‌کند که نام یک دایرکتوری شامل نویسهٔ خط جدید باشد)\&. این گزینه توسط سیستم تکمیل خودکار استفاده می‌شود\&.
.TP
\fB\-r\fP
متغیر \fBreply\fP را روی مجموعه دایرکتوری‌های جاری تنظیم می‌کند\&. چیزی چاپ نمی‌شود و دایرکتوری تغییر نمی‌کند\&.
.TP
\fB\-e\fP
به شما امکان می‌دهد فهرست دایرکتوری‌ها را، در هر سطر یکی، ویرایش کنید\&. این فهرست به هر میزانی که مایل باشید قابل ویرایش است؛ هیچ بررسی درستی‌سنجی (sanity check) انجام نمی‌شود\&. تکمیل خودکار در دسترس است\&. نیازی به نقل‌قول‌گذاری نیست (به‌جز خطوط جدید که در هر حال پشتیبانی نمی‌شوند)؛ دایرکتوری‌ها به صورت کامل و غیرمخفف بوده و حاوی مسیر مطلق هستند، یعنی با \fB/\fP شروع می‌شوند\&. معمولاً ورودی اول باید به عنوان دایرکتوری فعلی باقی بماند\&.
.TP
\fB\-p \&'\fP\fIpattern\fP\fB'\fP
تمام مواردی از فهرست دایرکتوری‌ها را که با الگوی glob گسترش‌یافتهٔ مشخص‌شده مطابقت داشته باشند هرس (حذف) می‌کند؛ الگو باید درون علامت نقل‌قول قرار گیرد تا از بسط فوری آن در خط فرمان جلوگیری شود\&. الگو در برابر هر نام فایل کاملاً بسط‌یافته در فهرست مطابقت داده می‌شود؛ کل رشته باید منطبق شود، بنابراین نویسه‌های عام (wildcard) در انتها (مثلاً \fB\&'*removeme*'\fP) برای حذف ورودی‌های دارای یک زیررشتهٔ معین مورد نیاز هستند\&.
.RS
.PP
اگر خروجی به یک ترمینال باشد، تابع فهرست جدید را پس از هرس چاپ کرده و از کاربر تأییدیه می‌خواهد\&. از این مرحله خروجی و دریافت تأییدیه می‌توان با استفاده از \fB\-P\fP به جای \fB\-p\fP صرف‌نظر کرد\&.
.RE
.PP.SS "پیکربندی (Configuration)"
.PP
پیکربندی از طریق سازوکار سبک‌ها (styles) انجام می‌شود که باید از سیستم تکمیل (completion) با آن آشنا باشید؛ در غیر این صورت، توضیحات دستور \fBzstyle\fP را در \fIzshmodules\fP(1) مشاهده کنید\&. بافت (context) برای تنظیم سبک‌ها باید \fB\&':chpwd:*'\fP باشد تا در صورت گسترش معنای بافت در آینده مشکلی پیش نیاید، برای مثال:
.PP
.RS
.nf
\fBzstyle \&':chpwd:*' recent\-dirs\-max 0\fP
.fi
.RE
.PP
مقدار سبک \fBrecent\-dirs\-max\fP را برابر با 0 قرار می‌دهد\&. در عمل، نام سبک به اندازهٔ کافی خاص هست که بافت \&'*' نیز کافی باشد\&.
.PP
یک استثنا \fBrecent\-dirs\-insert\fP است که منحصراً توسط سیستم تکمیل استفاده می‌شود و از این رو بافت معمول سیستم تکمیل را دارد (اگر بافت خاص‌تری نیاز نباشد، \fB\&':completion:*'\fP)، هرچند در عمل باز هم \fB\&'*'\fP باید مناسب باشد\&.
.PP
.PD 0
.TP
.PD
\fBrecent\-dirs\-default\fP
اگر true باشد و دستور در انتظار یک نمایهٔ دایرکتوری اخیر باشد، و بیش از یک آرگومان وجود داشته باشد یا آرگومان یک عدد صحیح نباشد، به "cd" منتقل (fall through) می‌شود\&. این قابلیت به افراد تنبل امکان می‌دهد تنها از یک دستور برای تغییر دایرکتوری استفاده کنند\&. سیستم تکمیل نیز این موضوع را تشخیص می‌دهد؛ برای آگاهی از نحوهٔ کنترل تکمیل هنگام استفاده از این گزینه، recent\-dirs\-insert را ببینید\&.
.TP
\fBrecent\-dirs\-file\fP
فایلی که فهرست دایرکتوری‌ها در آن ذخیره می‌شود\&. مقدار پیش‌فرض \fB${ZDOTDIR:\-$HOME}/\&.chpwd\-recent\-dirs\fP است، یعنی در دایرکتوری خانگی (home) شما قرار دارد، مگر اینکه متغیر \fBZDOTDIR\fP را طوری تنظیم کرده باشید که به جای دیگری اشاره کند\&. نام دایرکتوری‌ها در قالب نقل‌قول‌شدهٔ \fB$\&'\fP\fI\&.\&.\&.\fP\fB'\fP ذخیره می‌شوند، بنابراین هر خط در فایل می‌تواند مستقیماً به عنوان یک آرگومان به پوسته داده شود\&.
.RS
.PP
مقدار این سبک می‌تواند یک آرایه باشد\&. در این حالت، نخستین فایل در فهرست همواره برای ذخیرهٔ دایرکتوری‌ها استفاده خواهد شد، در حالی که سایر فایل‌ها دست‌نخورده باقی می‌مانند\&. هنگام خواندن فهرست دایرکتوری‌های اخیر، اگر تعداد ورودی‌ها در فایل اول کمتر از بیشینهٔ مجاز باشد، محتویات فایل‌های بعدی در آرایه الحاق خواهند شد، به طوری که موارد تکراری از فهرست نمایش داده‌شده حذف می‌شوند\&. محتویات دو فایل با یکدیگر مرتب‌سازی نمی‌شوند، یعنی تمام ورودی‌های فایل اول در ابتدا نمایش داده می‌شوند\&. مقدار ویژهٔ \fB+\fP می‌تواند در فهرست ظاهر شود تا نشان دهد فایل پیش‌فرض باید در آن نقطه خوانده شود\&. این امر امکان پیاده‌سازی مواردی مانند مثال زیر را فراهم می‌کند:
.PP
.RS
.nf
\fBzstyle \&':chpwd:*' recent\-dirs\-file \e 
~/\&.chpwd\-recent\-dirs\-${TTY##*/} +\fP
.fi
.RE
.PP
دایرکتوری‌های اخیر از فایلی شماره‌گذاری‌شده بر اساس ترمینال خوانده می‌شوند\&. اگر تعداد ورودی‌ها کافی نباشد، فهرست با فایل پیش‌فرض تکمیل می‌شود\&.
.PP
امکان استفاده از \fBzstyle \-e\fP برای پیکربندی‌پذیر کردن دایرکتوری در زمان اجرا وجود دارد:
.PP
.RS
.nf
\fBzstyle \-e \&':chpwd:*' recent\-dirs\-file pick\-recent\-dirs\-file
pick\-recent\-dirs\-file() {
  if [[ $PWD = ~/text/writing(|/*) ]]; then
    reply=(~/\&.chpwd\-recent\-dirs\-writing)
  else
    reply=(+)
  fi
}\fP
.fi
.RE
.PP
در این مثال، اگر دایرکتوری جاری \fB~/text/writing\fP یا دایرکتوری زیر آن باشد، از فایلی ویژه برای ذخیرهٔ دایرکتوری‌های اخیر استفاده می‌شود، وگرنه از پیش‌فرض استفاده خواهد شد\&.
.RE
.TP
\fBrecent\-dirs\-insert\fP
توسط سیستم تکمیل استفاده می‌شود\&. اگر \fBrecent\-dirs\-default\fP برابر با true باشد، تنظیم این سبک روی \fBtrue\fP باعث می‌شود که به جای نمایهٔ دایرکتوری، خودِ دایرکتوری واقعی در خط فرمان درج شود؛ این کار اثری مشابه استفاده از نمایهٔ مربوطه دارد، اما تاریخچه (history) را واضح‌تر و ویرایش خط را آسان‌تر می‌کند\&. با این تنظیم، چنانچه بخشی از یک آرگومان پیش‌تر تایپ شده باشد، به جای تکمیل دایرکتوری‌های اخیر، تکمیل معمولی دایرکتوری انجام می‌شود؛ زیرا انتظار می‌رود تکمیل دایرکتوری اخیر با گردش بین ورودی‌ها به صورت منو انجام گیرد\&.
.RS
.PP
اگر مقدار این سبک \fBalways\fP باشد، تنها دایرکتوری‌های اخیر تکمیل خواهند شد؛ در این صورت، هرگاه می‌خواهید دایرکتوری‌های دیگر را تکمیل کنید از دستور \fBcd\fP استفاده نمایید\&.
.PP
اگر مقدار آن \fBfallback\fP باشد، ابتدا دایرکتوری‌های اخیر امتحان می‌شوند، سپس در صورتی که تکمیل دایرکتوری‌های اخیر تطابقی پیدا نکند، تکمیل معمولی دایرکتوری انجام می‌پذیرد\&.
.PP
در نهایت، اگر مقدار آن \fBboth\fP باشد، هر دو مجموعه تکمیل‌ها ارائه می‌شوند؛ سازوکار معمول برچسب‌گذاری (tag) می‌تواند برای تمایز نتایج استفاده شود، به طوری که دایرکتوری‌های اخیر با برچسب \fBrecent\-dirs\fP مشخص می‌شوند\&. توجه داشته باشید که دایرکتوری‌های اخیر درج‌شده در صورت لزوم با نام دایرکتوری خلاصه می‌شوند\&.
.RE
.TP
\fBrecent\-dirs\-max\fP
بیشینهٔ تعداد دایرکتوری‌هایی که باید در فایل ذخیره شوند\&. اگر این مقدار صفر یا منفی باشد، بیشینه‌ای وجود نخواهد داشت\&. مقدار پیش‌فرض 20 است\&. توجه داشته باشید که این تعداد شامل دایرکتوری جاری نیز می‌شود، که ارائه نمی‌گردد، بنابراین بیشترین تعداد دایرکتوری‌هایی که به شما پیشنهاد خواهد شد یکی کمتر از مقدار بیشینه است\&.
.TP
\fBrecent\-dirs\-prune\fP
این سبک یک آرایه است که تعیین می‌کند چه دایرکتوری‌هایی باید (یا نباید) به فهرست موارد اخیر افزوده شوند\&. عناصر این آرایه می‌توانند شامل موارد زیر باشند:
.RS
.PP
.PD 0
.TP
.PD
\fBparent\fP
هرس کردن (حذف) والدها (به طور دقیق‌تر، اجداد) از فهرست اخیر\&. اگر مشخص شود، جابجایی مستقیم به پایین به هر تعداد دایرکتوری باعث می‌شود دایرکتوری جاری رونویسی شود\&. برای مثال، تغییر از ~pws به ~pws/some/other/dir باعث می‌شود ~pws در پشتهٔ دایرکتوری‌های اخیر باقی نماند\&. این فقط برای تغییر مستقیم به دایرکتوری‌های نسل بعدی (فرزندان) اعمال می‌شود؛ دایرکتوری‌های قبلی در فهرست هرس نمی‌شوند\&. به عنوان نمونه، جابجایی از ~pws/yet/another به ~pws/some/other/dir باعث هرس شدن ~pws نمی‌شود\&.
.TP
\fBpattern:\fP\fIpattern\fP
یک الگوی zsh برای دایرکتوری‌هایی که نباید به فهرست اخیر اضافه شوند (در صورتی که از قبل آنجا نباشند) مشخص می‌کند\&. این عنصر را می‌توان برای افزودن الگوهای مختلف تکرار کرد\&. برای مثال، \fB\&'pattern:/tmp(|/*)'\fP مانع از اضافه شدن \fB/tmp\fP یا زیرشاخه‌های آن می‌شود\&. گزینهٔ \fBEXTENDED_GLOB\fP همواره برای این الگوها فعال است\&.
.RE
.TP
\fBrecent\-dirs\-pushd\fP
اگر روی true تنظیم شود، \fBcdr\fP برای تغییر دایرکتوری به جای \fBcd\fP از \fBpushd\fP استفاده خواهد کرد، بنابراین دایرکتوری در پشتهٔ دایرکتوری ذخیره می‌شود\&. از آنجا که پشتهٔ دایرکتوری کاملاً از فهرست فایل‌های ذخیره‌شده توسط سازوکار استفاده‌شده در این فایل مجزاست، دلیل مشخصی برای انجام این کار وجود ندارد\&.
.PP.SS "استفاده با نام‌گذاری پویای دایرکتوری"
.PP
می‌توان با استفاده از نحو نام‌گذاری پویای دایرکتوری و با به‌کارگیری تابع ارائه‌شدهٔ \fBzsh_directory_name_cdr\fP به عنوان یک قلاب (hook)، به دایرکتوری‌های اخیر ارجاع داد:
.PP
.RS
.nf
\fBautoload \-Uz add\-zsh\-hook
add\-zsh\-hook \-Uz zsh_directory_name zsh_directory_name_cdr\fP
.fi
.RE
.PP
پس از انجام این کار، \fB~[1]\fP به تازه‌ترین دایرکتوری به جز $PWD ارجاع خواهد داد، و به همین ترتیب\&. تکمیل خودکار پس از \fB~[\fP\fI\&.\&.\&.\fP نیز کار می‌کند\&.
.PP
.SS "جزئیات مدیریت دایرکتوری"
.PP
این بخش برای افراد کنجکاو یا سردرگم است؛ بیشتر کاربران نیازی به دانستن این اطلاعات نخواهند داشت\&.
.PP
دایرکتوری‌های اخیر بلافاصله در یک فایل ذخیره می‌شوند و بنابراین در میان نشست‌ها حفظ می‌گردند\&. توجه داشته باشید که در حال حاضر هیچ قفل‌گذاری روی فایلی اعمال نمی‌شود: این فهرست بلافاصله هنگام اجرای دستورهای تعاملی و نه در هیچ جای دیگری به‌روزرسانی می‌شود (برخلاف تاریخچه)، و فرض بر این است که شما در هر زمان تنها در یک پنجره دایرکتوری را تغییر می‌دهید\&. این سازوکار در حساب‌های کاربری اشتراکی امن نیست، اما در هر حال زمانی که شخص دیگری بدون اطلاع شما به مجموعه‌ای متفاوت از دایرکتوری‌ها می‌رود، سامانه کاربرد محدودی دارد\&.
.PP
برای ایمن‌تر کردن این فرایند، تنها تغییرات دایرکتوری که از خط فرمان آغاز شده باشند—چه به صورت مستقیم و چه غیرمستقیم از طریق فراخوانی توابع شل (اما نه از طریق زیرشل‌ها (subshells)، evals، traps، توابع تکمیل و مانند آن‌ها)—ذخیره می‌شوند\&. در صورتی که قرار است تغییر دایرکتوری در خط فرمان نامرئی بماند، توابع شل باید از \fBcd \-q\fP یا \fBpushd \-q\fP برای جلوگیری از عوارض جانبی استفاده کنند\&. برای جزئیات بیشتر محتویات تابع \fBchpwd_recent_dirs\fP را ببینید\&.
.PP
.SH "ارجاعات پویای اختصاری به دایرکتوری‌ها (ABBREVIATED DYNAMIC REFERENCES TO DIRECTORIES)"
.PP
سامانهٔ نام‌گذاری پویای دایرکتوری در زیربخش \fIDynamic named directories\fP از بخش \fIFilename Expansion\fP در \fIzshexpn\fP(1) شرح داده شده است\&. در این بخش، ارجاع به \fB~[\fP\fI\&.\&.\&.\fP\fB]\fP توسط تابعی که از طریق سازوکار قلاب‌ها پیدا شده، بسط داده می‌شود\&.
.PP
تابع ارائه‌شدهٔ \fBzsh_directory_name_generic\fP سامانه‌ای را فراهم می‌کند که به کاربر اجازه می‌دهد تنها با مقدار محدودی کد جدید به دایرکتوری‌ها ارجاع دهد\&. این تابع از هر سه رابط استاندارد برای نام‌گذاری دایرکتوری پشتیبانی می‌کند: تبدیل نام به دایرکتوری، تبدیل در جهت معکوس برای یافتن نام کوتاه، و تکمیل خودکار نام‌ها\&.
.PP
ویژگی اصلی این تابع، یک نحو شبه‌مسیر است که اختصارات را در چند سطح جداشده با «:» ترکیب می‌کند\&. به عنوان مثال، ~[g:p:s] ممکن است مشخص‌کنندهٔ موارد زیر باشد:
.PD 0
.TP
.PD
\fBg\fP
دایرکتوری سطح بالایی برای ناحیهٔ git شما\&. این مؤلفهٔ نخست باید مطابقت داشته باشد، در غیر این صورت تابع مقداری برمی‌گرداند که نشان می‌دهد باید یک تابع قلاب نام دایرکتوری دیگر امتحان شود\&.
.TP
\fBp\fP
نام یک پروژه درون ناحیهٔ git شما\&.
.TP
\fBs\fP
ناحیهٔ سورس (source) درون آن پروژه\&.
این به شما امکان می‌دهد تا ارجاعات به سلسله‌مراتب‌های طولانی را به شکلی بسیار فشرده خلاصه کنید، به ویژه اگر این سلسله‌مراتب‌ها در بخش‌های مختلف دیسک مشابه باشند\&.
.PP
مؤلفه‌های نام ممکن است تکمیل خودکار شوند: اگر توصیفی در بالای فهرست تکمیل‌ها نمایش داده شود، شامل مسیری است که مؤلفه‌های قبلی به آن بسط می‌یابند، در حالی که توصیف یک مورد تکمیل منفرد، قطعه‌مسیر اضافه‌شونده توسط آن را نشان می‌دهد\&. هیچ پیکربندی اضافی برای این کار لازم نیست زیرا سیستم تکمیل خودکار از سازوکار نام پویای دایرکتوری آگاه است\&.
.PP
.SS "کاربرد"
.PP
برای استفاده از این تابع، ابتدا یک تابع پوششی (wrapper function) برای مورد خاص خود تعریف کنید\&. ما فرض می‌کنیم که این تابع قرار است به طور خودکار بارگذاری (autoload) شود\&. این تابع می‌تواند هر نامی داشته باشد، اما ما از آن با نام zdn_mywrapper یاد می‌کنیم\&. این تابع پوششی متغیرهای مختلفی را تعریف کرده و سپس این تابع را با همان آرگومان‌هایی که تابع پوششی دریافت کرده، فراخوانی می‌کند\&. این پیکربندی در زیر شرح داده شده است\&.
.PP
سپس ترتیبی دهید که تابع پوششی به عنوان یک قلاب zsh_directory_name اجرا شود:
.PP
.RS
.nf
\fBautoload \-Uz add\-zsh\-hook zsh_directory_name_generic zdn_mywrapper
add\-zsh\-hook \-U zsh_directory_name zdn_mywrapper\fP
.fi
.RE
.PP.SS "پیکربندی (Configuration)"
.PP
تابع پوششی (wrapper function) باید یک آرایهٔ متناظر محلی به نام zdn_top تعریف کند\&.
همچنین این مورد می‌تواند با یک سبک (style) به نام \fBmapping\fP نیز تنظیم شود\&.
زمینه (context) برای این سبک \fB:zdn:\fP\fIwrapper\-name\fP است که در آن
\fIwrapper\-name\fP تابعی است که zsh_directory_name_generic را فراخوانی می‌کند؛
برای مثال:
.PP
.RS
.nf
\fBzstyle :zdn:zdn_mywrapper: mapping zdn_mywrapper_top\fP
.fi
.RE
.PP
کلیدها در این آرایهٔ متناظر، متناظر با بخش اول نام هستند\&.
مقادیر، دایرکتوری‌های منطبق می‌باشند\&.
آن‌ها می‌توانند یک پسوند اختیاری شامل یک اسلش و به دنبال آن یک دو‌نقطه و نام یک متغیر با همان قالب داشته باشند تا مؤلفهٔ بعدی را مشخص کنند\&.
(اسلش پیش از دونقطه برای رفع ابهام در مواردی است که برای مشخص کردن یک درایو در مسیر به دونقطه نیاز است\&.
در غیر این صورت هیچ ساختاری برای گریز (escaping) از این حالت وجود ندارد، بنابراین مؤلفه‌های مسیری که نامشان با دونقطه آغاز می‌شود پشتیبانی نمی‌شوند\&.)
مؤلفهٔ ویژهٔ \fB:default:\fP متغیری را در قالب \fB/:\fP\fIvar\fP تعیین می‌کند
(بخش مسیر نادیده گرفته می‌شود و بنابراین معمولاً خالی است)
که در صورت مشخص نشدن متغیر برای مسیر، برای مؤلفهٔ بعدی استفاده خواهد شد\&.
متغیرهایی که در \fBzdn_top\fP به آن‌ها ارجاع داده می‌شود، قالبی مشابه خود \fBzdn_top\fP دارند، اما شامل مسیرهای نسبی هستند\&.
.PP
برای مثال،
.PP
.RS
.nf
\fBlocal \-A zdn_top=(
  g   ~/git
  ga  ~/alternate/git
  gs  /scratch/$USER/git/:second2
  :default: /:second1
)\fP
.fi
.RE
.PP
این پیکربندی رفتار دایرکتوری مورد ارجاع به صورت \fB~[g:\&.\&.\&.]\fP
یا \fB~[ga:\&.\&.\&.]\fP یا \fB~[gs:\&.\&.\&.]\fP را مشخص می‌کند\&.
مؤلفه‌های بعدی مسیر اختیاری هستند؛ در این حالت \fB~[g]\fP به \fB~/git\fP گسترش می‌یابد، و به همین ترتیب\&.
\fBgs\fP به \fB/scratch/$USER/git\fP گسترش می‌یابد و از آرایهٔ متناظر \fBsecond2\fP برای تطبیق مؤلفهٔ دوم استفاده می‌کند؛
\fBg\fP و \fBga\fP از آرایهٔ متناظر \fBsecond1\fP برای تطبیق مؤلفهٔ دوم استفاده می‌کنند\&.
.PP
هنگام گسترش یک نام به یک دایرکتوری، چنانچه مؤلفهٔ اول \fBg\fP،
\fBga\fP یا \fBgs\fP نباشد، خطا به شمار نمی‌آید؛ تابع صرفاً مقدار 1 را برمی‌گرداند تا امکان بررسی یک تابع قلاب (hook) بعدی وجود داشته باشد\&.
با این حال، تطبیق مؤلفهٔ اول، تابع را متعهد می‌سازد؛ از این رو در صورت عدم تطبیق مؤلفه‌های بعدی، یک خطا چاپ می‌شود
(هرچند این موضوع مانع از اجرای قلاب‌های بعدی نمی‌شود)\&.
.PP
برای مؤلفه‌های پس از بخش اول، یک مسیر نسبی انتظار می‌رود، اما توجه داشته باشید که ممکن است چندین سطح نیز وجود داشته باشد\&.
در اینجا نمونه‌ای از \fBsecond1\fP آورده شده است:
.PP
.RS
.nf
\fBlocal \-A second1=(
  p   myproject
  s   somproject
  os  otherproject/subproject/:third
)\fP
.fi
.RE
.PP
مسیر یافت‌شده از \fBzdn_top\fP با دایرکتوری منطبق گسترش می‌یابد، بنابراین \fB~[g:p]\fP تبدیل به \fB~/git/myproject\fP می‌شود\&.
اسلش میانی به طور خودکار افزوده می‌شود (امکان ندارد یک مؤلفهٔ بعدی نام دایرکتوری از پیش تطبیق‌یافته را دستخوش تغییر کند)\&.
تنها \fBos\fP متغیری را برای مؤلفهٔ سوم مشخص می‌کند، و همچنین هیچ \fB:default:\fP وجود ندارد؛
بنابراین استفاده از نام‌هایی نظیر \fB~[g:p:x]\fP یا \fB~[ga:s:y]\fP خطا محسوب می‌شود، چرا که مکانی برای جستجوی \fBx\fP یا \fBy\fP وجود ندارد\&.
.PP
آرایه‌های متناظر باید درون این تابع قابل مشاهده باشند؛ بنابراین تابع عمومی (generic) از نام متغیرهای داخلی که با \fB_zdn_\fP آغاز می‌شوند استفاده می‌کند تا از هرگونه تداخل نام‌ها جلوگیری شود\&.
توجه داشته باشید که متغیر \fBreply\fP باید به شل بازگردانده شود، در نتیجه نباید در تابع فراخواننده به صورت محلی (local) تعریف شده باشد\&.
.PP
این تابع بررسی نمی‌کند که آیا دایرکتوری‌های حاصل از ترکیب مؤلفه‌ها در عمل وجود دارند یا خیر؛
این امر سیستم را قادر می‌سازد با سیستم‌های فایلی با سوار شدن خودکار (automounted) نیز کار کند\&.
خطای ناشی از دستوری که تلاش می‌کند به یک دایرکتوری ناموجود دسترسی پیدا کند، برای نشان دادن مشکل کفایت خواهد کرد\&.
.PP.SS "مثال کامل (Complete example)"
.PP
در اینجا یک تعریف کامل و ساختگی، اما قابل استفاده و با امکان بارگذاری خودکار (autoloadable) از تابع نمونه‌ای که با کد بالا تعریف شد، آمده است\&. بنابراین \fB~[gs:p:s]\fP به \fB/scratch/$USER/git/myscratchproject/top/srcdir\fP بسط می‌یابد (که در آن \fB$USER\fP نیز بسط داده می‌شود)\&.
.PP
.RS
.nf
\fBlocal \-A zdn_top=(
  g   ~/git
  ga  ~/alternate/git
  gs  /scratch/$USER/git/:second2
  :default: /:second1
)

local \-A second1=(
  p   myproject
  s   somproject
  os  otherproject/subproject/:third
)

local \-A second2=(
  p   myscratchproject
  s   somescratchproject
)

local \-A third=(
  s   top/srcdir
  d   top/documentation
)

# autoload not needed if you did this at initialisation\&.\&.\&.
autoload \-Uz zsh_directory_name_generic
zsh_directory_name_generic "$@\fP
.fi
.RE
.PP
همچنین می‌توان از آرایه‌های انجمنی سراسری با نام‌گذاری مناسب استفاده کرد و سبک (style) را برای بافت تابع پوششی (wrapper) خود به گونه‌ای تنظیم نمود که به آن ارجاع دهد\&. در این صورت کد پیکربندی شما شامل موارد زیر خواهد بود:
.PP
.RS
.nf
\fBtypeset \-A zdn_mywrapper_top=(\&.\&.\&.)
# \&.\&.\&. and so on for other associative arrays \&.\&.\&.
zstyle \&':zdn:zdn_mywrapper:' mapping zdn_mywrapper_top
autoload \-Uz add\-zsh\-hook zsh_directory_name_generic zdn_mywrapper
add\-zsh\-hook \-U zsh_directory_name zdn_mywrapper\fP
.fi
.RE
.PP
و تابع \fBzdn_mywrapper\fP تنها شامل موارد زیر خواهد بود:
.PP
.RS
.nf
\fBzsh_directory_name_generic "$@"\fP
.fi
.RE
.PP
.SH "جمع‌آوری اطلاعات از سیستم‌های کنترل نسخه (GATHERING INFORMATION FROM VERSION CONTROL SYSTEMS)"
.PP
در بسیاری از موارد، بازیابی خودکار اطلاعات از سیستم‌های کنترل نسخه (VCSها)، مانند subversion، CVS یا git، برای نمایش آن به کاربر (به‌ویژه در اعلان یا همان prompt کاربر) بسیار سودمند است؛ برای نمونه تا بتوانید فوراً متوجه شوید در حال حاضر روی کدام شاخه (branch) قرار دارید\&.
.PP
برای انجام این کار، می‌توانید از تابع \fBvcs_info\fP استفاده کنید\&.
.PP
سیستم‌های کنترل نسخه (VCS) زیر پشتیبانی می‌شوند و نام اختصاری ارجاع به آن‌ها در سیستم نیز نشان داده شده است:
.PD 0
.TP
Bazaar (\fBbzr\fP)
\fBhttps://bazaar\&.canonical\&.com\fP
.TP
Codeville (\fBcdv\fP)
\fBhttp://freecode\&.com/projects/codeville\fP
.TP
Concurrent Versioning System (\fBcvs\fP)
\fBhttps://www\&.nongnu\&.org/cvs\fP
.TP
Darcs (\fBdarcs\fP)
\fBhttp://darcs\&.net\fP
.TP
Fossil (\fBfossil\fP)
\fBhttps://fossil\-scm\&.org\fP
.TP
Git (\fBgit\fP)
\fBhttps://git\-scm\&.com\fP
.TP
GNU arch (\fBtla\fP)
\fBhttps://www\&.gnu\&.org/software/gnu\-arch\fP
.TP
Mercurial (\fBhg\fP)
\fBhttps://www\&.mercurial\-scm\&.org\fP
.TP
Monotone (\fBmtn\fP)
\fBhttps://monotone\&.ca\fP
.TP
Perforce (\fBp4\fP)
\fBhttps://www\&.perforce\&.com\fP
.TP
Subversion (\fBsvn\fP)
\fBhttps://subversion\&.apache\&.org\fP
.TP
SVK (\fBsvk\fP)
\fBhttps://svk\&.bestpractical\&.com\fP
.PD
.PP
همچنین از سیستم مدیریت وصله \fBquilt\fP (\fBhttps://savannah\&.nongnu\&.org/projects/quilt\fP) نیز پشتیبانی می‌شود\&. برای جزئیات به بخش \fBQuilt Support\fP در ادامه نگاه کنید\&.
.PP
برای بارگذاری \fBvcs_info\fP:
.PP
.RS
.nf
\fBautoload \-Uz vcs_info\fP
.fi
.RE
.PP
از این تابع می‌توان در هر اعلان (prompt) موجودی استفاده کرد، زیرا نیازی به وجود مدخل‌های خاصی از \fB$psvar\fP ندارد\&.
.PP
.PP.SS "شروع سریع (Quickstart)"
.PP
برای راه‌اندازی سریع این قابلیت (شامل رنگ‌ها)، می‌توانید مراحل زیر را انجام دهید (با فرض اینکه \fBvcs_info\fP را به‌درستی بارگذاری کرده‌اید \- بالا را ببینید):
.PP
.RS
.nf
\fBzstyle \&':vcs_info:*' actionformats \e 
    \&'%F{5}(%f%s%F{5})%F{3}\-%F{5}[%F{2}%b%F{3}|%F{1}%a%F{5}]%f '
zstyle \&':vcs_info:*' formats       \e 
    \&'%F{5}(%f%s%F{5})%F{3}\-%F{5}[%F{2}%b%F{5}]%f '
zstyle \&':vcs_info:(sv[nk]|bzr):*' branchformat '%b%F{1}:%F{3}%r'
precmd () { vcs_info }
PS1=\&'%F{5}[%F{2}%n%F{5}] %F{3}%3~ ${vcs_info_msg_0_}%f%# '\fP
.fi
.RE
.PP
واضح است که دو خط آخر صرفاً برای نمایش هستند\&. شما باید \fBvcs_info\fP را از تابع \fBprecmd\fP خود فراخوانی کنید\&. پس از انجام این کار، به یک \fB\&'${vcs_info_msg_0_}'\fP \fIتک‌نقل‌قول‌شده (single quoted)\fP در اعلان خط فرمان (prompt) خود نیاز خواهید داشت\&.
.PP
برای اینکه بتوانید \fB\&'${vcs_info_msg_0_}'\fP را مستقیماً مانند این نمونه در اعلان خط فرمان خود به کار ببرید، باید گزینهٔ \fBPROMPT_SUBST\fP را فعال کرده باشید\&.
.PP
اکنون ابزار کاربردی \fBvcs_info_printsys\fP را از خط فرمان اجرا کنید:
.PP
.RS
.nf
\fB% vcs_info_printsys
## list of supported version control backends:
## disabled systems are prefixed by a hash sign (#)
bzr
cdv
cvs
darcs
fossil
git
hg
mtn
p4
svk
svn
tla
## flavours (cannot be used in the enable or disable styles; they
## are enabled and disabled with their master [git\-svn \-> git])
## they *can* be used in contexts: \&':vcs_info:git\-svn:*'\&.
git\-p4
git\-svn
hg\-git
hg\-hgsubversion
hg\-hgsvn\fP
.fi
.RE
.PP
ممکن است همهٔ این موارد را نخواهید؛ چرا که اجرای کد برای تشخیص سامانه‌هایی که از آن‌ها استفاده نمی‌کنید بیهوده است\&. بنابراین راهی وجود دارد تا برخی از بک‌اندها را به‌طور کامل غیرفعال کنید:
.PP
.RS
.nf
\fBzstyle \&':vcs_info:*' disable bzr cdv darcs mtn svk tla\fP
.fi
.RE
.PP
همچنین می‌توانید چند مورد را از آن فهرست برگزینید و تنها همان‌ها را فعال کنید:
.PP
.RS
.nf
\fBzstyle \&':vcs_info:*' enable git cvs svn\fP
.fi
.RE
.PP
اگر پس از یکی از این دستورها مجدداً \fBvcs_info_printsys\fP را اجرا کنید، بک‌اندهای فهرست‌شده در سبک \fBdisable\fP (یا بک‌اندهایی که در سبک \fBenable\fP نیستند \- اگر از آن استفاده کرده باشید) را خواهید دید که با علامت هش (#) به عنوان غیرفعال علامت‌گذاری شده‌اند\&. این بدان معناست که از تشخیص این سامانه‌ها \fIبه‌طور کامل\fP صرف‌نظر می‌شود؛ بنابراین هیچ زمانی هدر نمی‌رود\&.
.PP
.SS "پیکربندی (Configuration)"
.PP
قابلیت \fBvcs_info\fP از طریق \fBzstyle\fP قابل پیکربندی است\&.
.PP
ابتدا، زمینه‌ای (context) که در آن کار می‌کنیم:
.RS
.nf
\fB:vcs_info:\fIvcs\-string\fP:\fIuser\-context\fP:\fIrepo\-root\-name\fP\fP
.fi
.RE
.PP
.PD 0
.TP
.PD
\fIvcs\-string\fP
یکی از این موارد است: \fBgit\fP، \fBgit\-svn\fP، \fBgit\-p4\fP، \fBhg\fP، \fBhg\-git\fP،
\fBhg\-hgsubversion\fP، \fBhg\-hgsvn\fP، \fBdarcs\fP، \fBbzr\fP، \fBcdv\fP، \fBmtn\fP،
\fBsvn\fP، \fBcvs\fP، \fBsvk\fP، \fBtla\fP، \fBp4\fP یا \fBfossil\fP\&.
این مورد در حالت Quilt با «\fB\&.quilt\-\fP\fIquilt\-mode\fP»
(برای جزئیات \fBQuilt Support\fP را ببینید)
و در زمان فعال بودن قلاب‌ها (hooks) با «\fB+\fP\fIhook\-name\fP» دنبال می‌شود
(برای جزئیات \fBHooks in vcs_info\fP را ببینید)\&.
.RS
.PP

در حال حاضر، قلاب‌ها در حالت quilt اطلاعات «\fB\&.quilt\-\fP\fIquilt\-mode\fP» را اضافه نمی‌کنند\&.
این وضعیت ممکن است در آینده تغییر کند\&.
.RE
.TP
\fIuser\-context\fP
رشته‌ای با قابلیت پیکربندی آزادانه است که توسط کاربر به عنوان آرگومان نخست به \fBvcs_info\fP ارسال می‌شود (توضیحات آن را در زیر ببینید)\&.
.TP
\fIrepo\-root\-name\fP
نام مخزنی است که می‌خواهید یک سبک (style) با آن تطبیق یابد\&. بنابراین، اگر تنظیمی مخصوص \fB/usr/src/zsh\fP می‌خواهید که یک چک‌اوت CVS است، می‌توانید \fIrepo\-root\-name\fP را روی \fBzsh\fP تنظیم کنید تا اعمال شود\&.
.PP
سه مقدار ویژه برای \fIvcs\-string\fP وجود دارد: اولی \fB\-init\-\fP نام دارد که تا زمانی که تصمیمی مبنی بر انتخاب بک‌اند سامانه کنترل نسخه (VCS) گرفته نشده باشد، معتبر است\&. دومی \fB\-preinit\-\fP است؛ این مقدار \fIپیش از\fP اجرای \fBvcs_info\fP، هنگام مقداردهی اولیه به متغیرهای صادرکنندهٔ داده استفاده می‌شود\&. سومین مقدار ویژه \fBformats\fP است و توسط \fBvcs_info_lastmsg\fP برای جستجوی سبک‌های آن به کار می‌رود\&.
.PP
مقدار اولیهٔ \fIrepo\-root\-name\fP برابر با \fB\-all\-\fP است و به محض مشخص شدن نام واقعی، با آن جایگزین می‌شود\&. از این بخش زمینه تنها برای تعریف سبک‌های \fBformats\fP، \fBactionformats\fP یا \fBbranchformat\fP استفاده کنید؛ چرا که تضمین شده است \fIrepo\-root\-name\fP تنها برای این سبک‌ها به‌درستی مقداردهی می‌شود\&. برای سایر سبک‌ها، تنها از \fB\&'*'\fP استفاده کنید\&.
.PP
دو مقدار از پیش‌تعریف‌شده برای \fIuser\-context\fP وجود دارد:
.PD 0
.TP
\fBdefault\fP
موردی که در صورت مشخص نشدن هیچ مقداری، استفاده می‌شود
.TP
\fBcommand\fP
توسط vcs_info_lastmsg برای جستجوی سبک‌های آن استفاده می‌شود
.PD
.PP
البته می‌توانید از \fB\&':vcs_info:*'\fP برای تطبیق هم‌زمان با تمامی VCSها در تمام زمینه‌های کاربری (user-contexts) استفاده کنید\&.
.PP
در ادامه توضیحی دربارهٔ تمامی سبک‌هایی که جستجو می‌شوند آورده شده است\&.
.PP
.PD 0
.TP
.PD
\fBformats\fP
فهرستی از قالب‌ها است که در صورت استفاده نشدن از actionformats (که اغلب اوقات چنین است) به کار می‌رود\&.
.TP
\fBactionformats\fP
فهرستی از قالب‌ها است که در صورت وقوع یک عملیات ویژه در مخزن فعلی شما استفاده می‌شود؛ مانند یک بازسازی تعاملی (interactive rebase) یا تداخل ادغام (merge conflict)\&.
.TP
\fBbranchformat\fP
برخی بک‌اندها \fB%b\fP را در سبک‌های formats و actionformats بالا، نه تنها با نام شاخه بلکه با شمارهٔ ویرایش (revision number) نیز جایگزین می‌کنند\&. این سبک به شما امکان می‌دهد ظاهر آن رشته را سفارشی‌سازی کنید\&.
.TP
\fBnvcsformats\fP
این «قالب‌ها» زمانی تنظیم می‌شوند که سامانهٔ کنترل نسخه‌ای برای دایرکتوری فعلی تشخیص داده نشود یا \fBvcs_info\fP غیرفعال شده باشد\&. این ویژگی زمانی مفید است که بخواهید \fBvcs_info\fP تولید اعلان خط فرمان (prompt) شما را کاملاً بر عهده بگیرد\&. برای رسیدن به این هدف، کاری مانند \fBPS1=\&'${vcs_info_msg_0_}'\fP را انجام می‌دهید\&.
.TP
\fBhgrevformat\fP
ابزار \fBhg\fP هم از هش و هم از شمارهٔ ویرایش برای ارجاع به یک مجموعه تغییرات (changeset) خاص در مخزن استفاده می‌کند\&. با این سبک می‌توانید رشتهٔ بازبینی را قالب‌بندی کنید (به \fBbranchformat\fP مراجعه کنید) تا شامل یکی از آن‌ها یا هر دو باشد\&. این ویژگی تنها زمانی مفید است که \fBget\-revision\fP برابر با true باشد\&. توجه داشته باشید که شناسهٔ ویرایش ۴۰ نویسه‌ای کامل در دسترس نیست (مگر هنگام استفاده از گزینهٔ \fBuse\-simple\fP)، زیرا اجرای بیش از یک بار hg در هر اعلان خط فرمان بسیار کند است؛ می‌توانید این رفتار را با استفاده از قلاب‌ها سفارشی‌سازی کنید\&.
.TP
\fBmax\-exports\fP
حداکثر تعداد متغیرهای \fBvcs_info_msg_*_\fP را که \fBvcs_info\fP تنظیم خواهد کرد، مشخص می‌کند\&..TP
\fBenable\fP
فهرستی از بک‌اندهایی که می‌خواهید استفاده کنید\&. در زمینهٔ \fB\-init\-\fP بررسی می‌شود\&. اگر این فهرست شامل موردی به نام \fBNONE\fP باشد، از هیچ بک‌اندی استفاده نخواهد شد و \fBvcs_info\fP کاری انجام نمی‌دهد\&. اگر این فهرست شامل \fBALL\fP باشد، \fBvcs_info\fP از همهٔ بک‌اندهای شناخته‌شده استفاده خواهد کرد\&. شیوهٔ \fBdisable\fP تنها در صورتی اثرگذار است که \fBALL\fP در \fBenable\fP قرار داشته باشد\&. مقادیر \fBALL\fP و \fBNONE\fP به بزرگی و کوچکی حروف حساس نیستند\&.
.TP
\fBdisable\fP
فهرستی از سیستم‌های کنترل نسخه‌ای که نمی‌خواهید \fBvcs_info\fP آن‌ها را برای مخازن بررسی کند (این مورد نیز در زمینهٔ \fB\-init\-\fP بررسی می‌شود)\&. تنها زمانی استفاده می‌شود که \fBenable\fP حاوی \fBALL\fP باشد\&.
.TP
\fBdisable\-patterns\fP
فهرستی از الگوها که با \fB$PWD\fP تطبیق داده می‌شوند\&. اگر الگویی مطابقت داشته باشد، \fBvcs_info\fP غیرفعال خواهد شد\&. این شیوه در زمینهٔ \fB:vcs_info:\-init\-:*:\-all\-\fP بررسی می‌شود\&.
.RS
.PP
به‌عنوان مثال، فرض کنید \fB~/\&.zsh\fP دایرکتوری تحت کنترل نسخه است و نمی‌خواهید \fBvcs_info\fP در آن فعال باشد؛ دستور زیر را اجرا کنید:
.RS
.nf
\fBzstyle \&':vcs_info:*' disable\-patterns "${(b)HOME}/\&.zsh(|/*)"\fP
.fi
.RE
.RE
.TP
\fBuse\-quilt\fP
در صورت فعال بودن، کد پشتیبانی از \fBquilt\fP در حالت «addon» فعال می‌شود\&. برای جزئیات به \fBQuilt Support\fP مراجعه کنید\&.
.TP
\fBquilt\-standalone\fP
در صورت فعال بودن، اگر هیچ سیستم کنترل نسخه‌ای در دایرکتوری داده‌شده فعال نباشد، تلاش می‌شود حالت «standalone» تشخیص داده شود\&. برای جزئیات به \fBQuilt Support\fP مراجعه کنید\&.
.TP
\fBquilt\-patch\-dir\fP
رونویسی مقدار متغیر محیطی \fB$QUILT_PATCHES\fP\&. برای جزئیات به \fBQuilt Support\fP مراجعه کنید\&.
.TP
\fBquiltcommand\fP
هنگامی که خود دستور \fBquilt\fP در پشتیبانی quilt فراخوانی می‌شود، مقدار این شیوه به‌عنوان نام دستور استفاده می‌شود\&.
.TP
\fBcheck\-for\-changes\fP
اگر فعال باشد، این شیوه باعث می‌شود دنباله‌های گریز قالب‌بندی \fB%c\fP و \fB%u\fP نشان دهند که آیا دایرکتوری کاری دارای تغییرات ثبت‌نشده (uncommitted) هست یا خیر\&. رشته‌های نمایش‌داده‌شده توسط این گریزها را می‌توان با شیوه‌های \fBstagedstr\fP و \fBunstagedstr\fP کنترل کرد\&. تنها بک‌اندهایی که در حال حاضر از این گزینه پشتیبانی می‌کنند \fBgit\fP، \fBhg\fP و \fBbzr\fP هستند (دو مورد آخر تنها از تغییرات unstaged پشتیبانی می‌کنند)\&.
.RS
.PP
برای ارزیابی این شیوه در بک‌اند \fBhg\fP، باید شیوهٔ \fBget\-revision\fP تنظیم شده و شیوهٔ \fBuse\-simple\fP غیرفعال باشد\&. مورد دوم پیش‌فرض است، اما اولی پیش‌فرض نیست\&.
.PP
در بک‌اند \fBbzr\fP، دریافت‌های سبک (\fIlightweight checkouts\fP) تنها زمانی از این شیوه پیروی می‌کنند که شیوهٔ \fBuse\-server\fP تنظیم شده باشد\&.
.PP
توجه داشته باشید عملیاتی که در صورت فعال بودن این شیوه انجام می‌شود بالقوه پرهزینه هستند (به این معنی که بسته به اندازهٔ مخزن فعلی، ممکن است کُند باشند)\&. بنابراین، به‌طور پیش‌فرض غیرفعال است\&.
.RE
.TP
\fBcheck\-for\-staged\-changes\fP
این شیوه مشابه \fBcheck\-for\-changes\fP است، اما هرگز فایل‌های درخت‌کاری (worktree) را بررسی نمی‌کند، بلکه تنها فراداده‌های موجود در پوشهٔ \fB\&.${vcs}\fP را بررسی می‌کند\&. بنابراین، این شیوه فقط گریز \fB%c\fP را (با \fBstagedstr\fP) مقداردهی می‌کند و گریز \fB%u\fP را تنظیم نمی‌کند\&. این شیوه از \fBcheck\-for\-changes\fP سریع‌تر است\&.
.RS
.PP
در بک‌اند \fBgit\fP، این شیوه تغییرات موجود در نمایه‌ها (index) را بررسی می‌کند\&. بک‌اندهای دیگر در حال حاضر این شیوه را پیاده‌سازی نکرده‌اند\&.
.PP
این شیوه به‌طور پیش‌فرض غیرفعال است\&.
.RE
.TP
\fBstagedstr\fP
اگر تغییرات آماده‌سازی‌شده (staged) در مخزن وجود داشته باشد، این رشته در گریز \fB%c\fP استفاده خواهد شد\&.
.TP
\fBunstagedstr\fP
اگر تغییرات آماده‌سازی‌نشده (unstaged) در مخزن وجود داشته باشد، این رشته در گریز \fB%u\fP استفاده خواهد شد\&.
.TP
\fBcommand\fP
این شیوه باعث می‌شود \fBvcs_info\fP از رشتهٔ ارائه‌شده به‌عنوان دستوری که باید باینری سیستم کنترل نسخه باشد استفاده کند\&. توجه داشته باشید که تنظیم این مورد در '\fB:vcs_info:*\fP' ایدهٔ خوبی نیست\&.
.RS
.PP
اگر مقدار این شیوه خالی باشد (که پیش‌فرض است)، نام باینری مورد استفاده، همان نام بک‌اند در حال استفاده خواهد بود (به‌عنوان مثال در یک مخزن \fBsvn\fP از دستور \fBsvn\fP استفاده می‌شود)\&.
.PP
بخش \fBrepo\-root\-name\fP در زمینه، هنگام جستجوی این شیوه همیشه برابر مقدار پیش‌فرض \fB\-all\-\fP است\&.
.PP
برای نمونه، از این شیوه می‌توان برای استفاده از باینری‌ها در مسیرهای نصب غیرپیش‌فرض بهره برد\&. فرض کنید \fBgit\fP در /usr/bin نصب شده است اما مدیر سیستم نسخه جدیدتری را در /usr/local/bin نصب کرده است\&. به‌جای تغییر ترتیب متغیر \fB$PATH\fP خود، می‌توانید این کار را انجام دهید:
.RS
.nf
\fBzstyle \&':vcs_info:git:*:\-all\-' command /usr/local/bin/git\fP
.fi
.RE
.RE
.TP
\fBuse\-server\fP
این مورد توسط بک‌اند پرفورس (\fBp4\fP) استفاده می‌شود تا تصمیم بگیرد که آیا باید با کارگزار Perforce تماس بگیرد تا متوجه شود که آیا یک دایرکتوری توسط Perforce مدیریت می‌شود یا خیر\&. این تنها روش قابل‌اعتماد برای این کار است، اما در صورت عدم یافتن نام کارگزار خطر ایجاد تاخیر را به همراه دارد\&. اگر نتوان با کارگزار (به‌طور دقیق‌تر، جفت \fIhost\fP\fB:\fP\fIport\fP که کارگزار را مشخص می‌کند) ارتباط برقرار کرد، نام آن در آرایهٔ انجمنی \fBvcs_info_p4_dead_servers\fP قرار می‌گیرد و در طول آن نشست دیگر تماسی با آن برقرار نمی‌شود، مگر اینکه به‌صورت دستی حذف شود\&. اگر این شیوه را تنظیم نکنید، بک‌اند \fBp4\fP تنها در صورتی قابل استفاده خواهد بود که متغیر محیطی \fBP4CONFIG\fP را روی نام یک فایل تنظیم کرده باشید و فایل‌های متناظر در دایرکتوری‌های ریشهٔ هر کلاینت Perforce وجود داشته باشد\&. برای جزئیات بیشتر به توضیحات تابع \fBVCS_INFO_detect_p4\fP مراجعه کنید\&.
.RS
.PP
بک‌اند بازار (\fBbzr\fP) از این مورد برای اجازه دادن به برقراری ارتباط با کارگزار دربارهٔ checkoutهای سبک استفاده می‌کند؛ شیوهٔ \fBcheck\-for\-changes\fP را ببینید\&.
.RE
.TP
\fBuse\-simple\fP
اگر دو روش مختلف برای جمع‌آوری اطلاعات وجود داشته باشد، می‌توانید با تنظیم این شیوه بر روی true، روش ساده‌تر را انتخاب کنید؛ پیش‌فرض استفاده از کد غیرساده است که بالقوه بسیار کندتر است اما ممکن است در تمام موارد ممکن دقیق‌تر باشد\&. این شیوه توسط بک‌اندهای \fBbzr\fP، \fBhg\fP و \fBgit\fP استفاده می‌شود\&. در مورد \fBhg\fP، برنامهٔ خارجی hexdump را برای تجزیهٔ فایل حافظهٔ موقت باینری dirstate فراخوانی می‌کند؛ این روش شمارهٔ بازبینی محلی را بازنمی‌گرداند\&.
.TP
\fBget\-revision\fP
اگر روی true تنظیم شود، vcs_info تلاش بیشتری به خرج می‌دهد تا شمارهٔ بازبینی درخت‌کاری مخزن را بیابد (در حال حاضر برای بک‌اندهای \fBgit\fP و \fBhg\fP که چنین اطلاعاتی همیشه حیاتی نیستند)\&. در \fBgit\fP، مقدار هش کامیت فعلی که checkout شده از طریق بسط \fB%i\fP در دسترس است\&. در \fBhg\fP، شمارهٔ بازبینی محلی و هش سراسری متناظر از طریق \fB%i\fP در دسترس هستند\&.
.TP
\fBget\-mq\fP
اگر روی true تنظیم شود، بک‌اند \fBhg\fP به دنبال دایرکتوری وصلهٔ Mercurial Queue (\fBmq\fP) خواهد گشت\&. اطلاعات از طریق جایگزینی «\fB%m\fP» در دسترس خواهد بود\&.
.TP
\fBget\-bookmarks\fP
اگر روی true تنظیم شود، بک‌اند \fBhg\fP تلاش می‌کند فهرستی از نشانک‌های (bookmarks) فعلی به دست آورد\&. آن‌ها از طریق جایگزینی «\fB%m\fP» در دسترس خواهند بود\&.
.RS
.PP
حالت پیش‌فرض، ایجاد فهرستی جداشده با کاما از تمام نام‌های نشانک‌هایی است که به بازبینی فعلی checkout شده ارجاع می‌دهند\&. اگر نشانکی فعال باشد، یک ستاره به انتهای نام آن اضافه شده و در ابتدای فهرست قرار می‌گیرد\&.
.RE
.TP
\fBuse\-prompt\-escapes\fP
تعیین می‌کند که آیا فرض کنیم رشتهٔ سرهم‌شده از \fBvcs_info\fP شامل دنباله‌های گریز خط فرمان (prompt escapes) است یا خیر\&. (توسط \fBvcs_info_lastmsg\fP استفاده می‌شود\&.)
.TP
\fBdebug\fP
خروجی اشکال‌زدایی را برای ردیابی مشکلات احتمالی فعال می‌کند\&. در حال حاضر این شیوه تنها توسط سامانهٔ قلاب‌های (hooks) دستور \fBvcs_info\fP استفاده می‌شود\&.
.TP
\fBhooks\fP
یک شیوهٔ فهرستی که نام توابع قلاب را تعیین می‌کند\&. برای جزئیات به بخش \fBHooks in vcs_info\fP در ادامه مراجعه کنید\&.
.TP
.PD 0
\fBpatch\-format\fP
.TP
.PD
\fBnopatch\-format\fP
این جفت‌شیوه، اطلاعات وصله را که توسط بسط‌دهندهٔ \fB%m\fP در formats و actionformats برای بک‌اندهای \fBgit\fP و \fBhg\fP استفاده می‌شود، قالب‌بندی می‌کنند\&. این مقدار تابع برخی بسط‌های \fB%\fP است که در زیر شرح داده شده است\&.
مقدار بسط‌یافته در آرایهٔ سراسری \fBbackend_misc\fP به‌صورت \fB${backend_misc[patches]}\fP در دسترس قرار می‌گیرد (همچنین اگر از یک قلاب \fBset\-patch\-format\fP استفاده شود)\&..TP
\fBget\-unapplied\fP
این شیوه بولی (boolean) مشخص می‌کند که آیا یک backend باید برای جمع‌آوری فهرستی از وصله‌های اعمال‌نشده (برای نمونه با وصله‌های Mercurial Queue) تلاش کند یا خیر\&.
.RS
.PP
توسط backendهای \fBquilt\fP، \fBhg\fP و \fBgit\fP استفاده می‌شود\&.
.RE
.PP
مقادیر پیش‌فرض برای این شیوه‌ها در تمامی زمینه‌ها عبارتند از:
.PP
.PD 0
.TP
\fBformats\fP
" (%s)\-[%b]%u%c\-"
.TP
\fBactionformats\fP
" (%s)\-[%b|%a]%u%c\-"
.TP
\fBbranchformat\fP
"%b:%r" (برای bzr، svn، svk و hg)
.TP
\fBnvcsformats\fP
""
.TP
\fBhgrevformat\fP
"%r:%h"
.TP
\fBmax\-exports\fP
2
.TP
\fBenable\fP
ALL
.TP
\fBdisable\fP
(فهرست خالی)
.TP
\fBdisable\-patterns\fP
(فهرست خالی)
.TP
\fBcheck\-for\-changes\fP
false
.TP
\fBcheck\-for\-staged\-changes\fP
false
.TP
\fBstagedstr\fP
(رشته: "S")
.TP
\fBunstagedstr\fP
(رشته: "U")
.TP
\fBcommand\fP
(رشته خالی)
.TP
\fBuse\-server\fP
false
.TP
\fBuse\-simple\fP
false
.TP
\fBget\-revision\fP
false
.TP
\fBget\-mq\fP
true
.TP
\fBget\-bookmarks\fP
false
.TP
\fBuse\-prompt\-escapes\fP
true
.TP
\fBdebug\fP
false
.TP
\fBhooks\fP
(فهرست خالی)
.TP
\fBuse\-quilt\fP
false
.TP
\fBquilt\-standalone\fP
false
.TP
\fBquilt\-patch\-dir\fP
خالی \- استفاده از \fB$QUILT_PATCHES\fP
.TP
\fBquiltcommand\fP
quilt
.TP
\fBpatch\-format\fP
\fIوابسته به backend\fP
.TP
\fBnopatch\-format\fP
\fIوابسته به backend\fP
.TP
\fBget\-unapplied\fP
false
.PD
.PP
در \fBformats\fP و \fBactionformats\fP عادی جایگزینی‌های زیر انجام می‌شوند:
.PP
.PD 0
.TP
\fB%s\fP
سامانه کنترل نسخه (VCS) مورد استفاده (git، hg، svn و غیره)\&.
.TP
\fB%b\fP
اطلاعات مربوط به شاخه جاری\&.
.TP
\fB%a\fP
یک شناسه‌گر که عملیات (action) را توصیف می‌کند\&. فقط در \fBactionformats\fP معنا دارد\&.
.TP
\fB%i\fP
شماره یا شناسه‌گر نگارش (revision) جاری\&. برای \fBhg\fP می‌توان از شیوه \fBhgrevformat\fP برای سفارشی‌سازی خروجی استفاده کرد\&.
.TP
\fB%c\fP
رشته حاصل از شیوه \fBstagedstr\fP در صورتی که تغییرات مرحله‌بندی‌شده (staged) در مخزن وجود داشته باشد\&.
.TP
\fB%u\fP
رشته حاصل از شیوه \fBunstagedstr\fP در صورتی که تغییرات مرحله‌بندی‌نشده (unstaged) در مخزن وجود داشته باشد\&.
.TP
\fB%R\fP
دایرکتوری پایه مخزن\&.
.TP
\fB%r\fP
نام مخزن\&. اگر \fB%R\fP برابر با \fB/foo/bar/repoXY\fP باشد، \fB%r\fP برابر \fBrepoXY\fP است\&.
.TP
\fB%S\fP
یک زیردایرکتوری درون مخزن\&. اگر \fB$PWD\fP برابر \fB/foo/bar/repoXY/beer/tasty\fP باشد، \fB%S\fP برابر \fBbeer/tasty\fP است\&.
.PD
.PD 0
.TP
.PD
\fB%m\fP
یک جایگزینی «متفرقه» (misc)\&. تصمیم‌گیری در مورد اینکه این جایگزین به چه چیزی بسط یابد، بر عهده backend است\&.
.RS
.PP
backendهای \fBhg\fP و \fBgit\fP از این عبارت بسط‌پذیر (expando) برای نمایش اطلاعات وصله استفاده می‌کنند\&.
\fBhg\fP اطلاعات وصله را از افزونه‌های \fBmq\fP استخراج می‌کند؛ \fBgit\fP از عملیات‌های در حال انجام \fBrebase\fP و \fBcherry\-pick\fP و از افزونه \fBstgit\fP استفاده می‌کند\&. شیوه‌های \fBpatch\-format\fP و \fBnopatch\-format\fP رشته تولیدشده را کنترل می‌کنند\&. مورد اول زمانی استفاده می‌شود که حداقل یک وصله از صف وصله‌ها اعمال شده باشد، و مورد دوم در غیر این صورت استفاده می‌شود\&.
.PP
backend برنامه \fBhg\fP اطلاعات نشانک (bookmark) را در این عبارت بسط‌پذیر نمایش می‌دهد (علاوه بر اطلاعات \fBmq\fP)\&. شیوه‌های \fBget\-mq\fP و \fBget\-bookmarks\fP را ببینید\&. هر دوی این شیوه‌ها ممکن است هم‌زمان فعال باشند\&. اگر هر دو فعال باشند، هر دو رشته حاصل به‌وسیله یک نقطه\-ویرگول از هم جدا خواهند شد (که در حال حاضر قابل سفارشی‌سازی نیست)\&.
.PP
backend نوع `standalone\&' ابزار \fBquilt\fP این عبارت بسط‌پذیر را روی همان مقدار عبارت بسط‌پذیر \fB%Q\fP تنظیم می‌کند\&.
.RE
.TP
\fB%Q\fP
اطلاعات سری Quilt\&.
هنگامی که quilt استفاده می‌شود (چه در حالت `addon\&' یا به عنوان یک backend مستقل `standalone')، این عبارت بسط‌پذیر روی رشته \fBpatch\-format\fP سری quilt تنظیم می‌شود\&.
قلاب \fBset\-patch\-format\fP و شیوه \fBnopatch\-format\fP رعایت می‌شوند\&.
.RS
.PP
برای جزئیات بیشتر بخش \fBQuilt Support\fP در زیر را ببینید\&.
.RE
.PP
در \fBbranchformat\fP این جایگزینی‌ها انجام می‌شوند:
.PP
.PD 0
.TP
\fB%b\fP
نام شاخه\&. برای \fBhg\fP، نام شاخه می‌تواند شامل نام یک موضوع (topic) باشد\&..TP
\fB%r\fP
شماره نسخه فعلی یا سبک \fBhgrevformat\fP برای \fBhg\fP\&.
.PD
.PP
در \fBhgrevformat\fP این جایگزینی‌ها انجام می‌شوند:
.PP
.PD 0
.TP
\fB%r\fP
شماره نسخه محلی فعلی\&.
.TP
\fB%h\fP
شناسه نسخه سراسری فعلی\&.
.PD
.PP
در \fBpatch\-format\fP و \fBnopatch\-format\fP این جایگزینی‌ها انجام می‌شوند:
.PP
.PD 0
.TP
\fB%p\fP
نام بالاترین وصله اعمال‌شده؛ ممکن است توسط قلاب \fBapplied\-string\fP بازنویسی شود\&.
.TP
\fB%u\fP
تعداد وصله‌های اعمال‌نشده؛ ممکن است توسط قلاب \fBunapplied\-string\fP بازنویسی شود\&.
.TP
\fB%n\fP
تعداد وصله‌های اعمال‌شده\&.
.TP
\fB%c\fP
تعداد وصله‌های اعمال‌نشده\&.
.TP
\fB%a\fP
تعداد تمام وصله‌ها (\fB%a = %n + %c\fP)\&.
.TP
\fB%g\fP
نام‌های نگه‌بان‌های (guards) فعال \fBmq\fP (موتور پشتیبان \fBhg\fP)\&.
.TP
\fB%G\fP
تعداد نگه‌بان‌های (guards) فعال \fBmq\fP (موتور پشتیبان \fBhg\fP)\&.
.PD
.PP
لازم نیست همه موتورهای پشتیبان سامانه کنترل نسخه (VCS) از تمام جایگزینی‌ها پشتیبانی کنند\&. برای \fBnvcsformats\fP هیچ جایگزینی انجام نمی‌شود و صرفاً یک رشته است\&.
.PP
.SS "موارد عجیب (Oddities)"
.PP
اگر می‌خواهید از بسط اعلان \fB%b\fP (خاموش کردن حالت برجسته/bold) در \fBformats\fP استفاده کنید که خودِ \fB%b\fP را بسط می‌دهد، از \fB%%b\fP استفاده نمایید\&. این کار موجب می‌شود بسط \fBvcs_info\fP مقدار \fB%%b\fP را با \fB%b\fP جایگزین کند تا سازوکار بسط اعلان zsh بتواند آن را مدیریت و پردازش نماید\&. به‌طور مشابه، برای فرستادن \fB%b\fP از \fBbranchformat\fP، از \fB%%%%b\fP استفاده کنید\&. پوزش بابت این زحمت، اما اجتناب از آن به‌سادگی ممکن نبود\&. خوشبختانه با بیشتر بسط‌های اعلان تداخلی وجود ندارد و این عمل تنها برای همین موارد خاص لازم است\&.
.PP
هنگامی که یکی از قلاب‌های \fBgen\-applied\-string\fP، \fBgen\-unapplied\-string\fP و \fBset\-patch\-format\fP تعریف شده باشد، اعمال گریزدهی به \fB%\fP (`\fBfoo=${foo//\&'%'/%%}\fP') روی مقادیر درون‌یابی‌شده جهت استفاده در اعلان، (مشترکاً) بر عهده آن قلاب‌ها خواهد بود؛ زمانی که هیچ‌یک از این قلاب‌ها تعریف نشده باشند، \fBvcs_info\fP گریزدهی را خود به تنهایی انجام می‌دهد\&. بابت این وابستگی پوزش می‌خواهیم، اما وجود آن برای سازگاری عقروعلی (عقب‌رو) الزامی بود\&.
.PP
.SS "پشتیبانی از Quilt (Quilt Support)"
.PP
ابزار \fBQuilt\fP یک سامانه کنترل نسخه نیست، از این رو به عنوان یک موتور پشتیبان پیاده‌سازی نشده است\&. این ابزار می‌تواند به پیگیری مجموعه‌ای از وصله‌ها کمک کند\&. افراد از آن برای نگهداری مجموعه‌ای از تغییرات که می‌خواهند روی بسته‌های نرم‌افزاری اعمال کنند بهره می‌گیرند (که با فرایند ساخت بسته به شکل تنگاتنگی یکپارچه شده است \- پروژه دبیان برای تعداد کثیری از بسته‌ها این کار را انجام می‌دهد)\&. همچنین \fBQuilt\fP می‌تواند به توسعه‌دهندگان به صورت انفرادی کمک کند تا وصله‌های خود را روی سامانه‌های کنترل نسخه واقعی مدیریت و دنبال کنند\&.
.PP
یکپارچه‌سازی \fBvcs_info\fP تلاش می‌کند تا با ارائه دو حالت عملکردی کمی متفاوت، از هر دو روش استفاده از quilt پشتیبانی کند: حالت «addon» و حالت «standalone»\&.
.PP
یکپارچه‌سازی Quilt به طور پیش‌فرض غیرفعال است؛ برای فعال‌سازی آن، سبک \fBuse\-quilt\fP را تنظیم کرده و \fB%Q\fP را به سبک‌های \fBformats\fP یا \fBactionformats\fP خود بیفزایید:
.RS
.nf
\fBzstyle \&':vcs_info:*' use\-quilt true\fP
.fi
.RE
.PP
سبک‌هایی که توسط کد پشتیبانی Quilt بررسی می‌شوند شامل `\fB\&.quilt\-\fP\fIquilt\-mode\fP\&' در بخش \fIvcs\-string\fP بافت هستند، که در آن \fIquilt\-mode\fP یا \fBaddon\fP است یا \fBstandalone\fP\&.
مثال: \fB:vcs_info:git\&.quilt\-addon:default:\fP\fIrepo\-root\-name\fP\&.
.PP
برای فعال شدن حالت «addon»، سامانه \fBvcs_info\fP باید از قبل یک سامانه کنترل نسخه واقعی را که دایرکتوری را کنترل می‌کند شناسایی کرده باشد\&. اگر چنین باشد، باید دایرکتوری حاوی وصله‌های quilt پیدا شود\&. آن دایرکتوری از طریق متغیر محیطی `\fBQUILT_PATCHES\fP\&' قابل پیکربندی است\&. اگر متغیر مذکور وجود داشته باشد از مقدار آن استفاده می‌شود، در غیر این صورت مقدار `\fBpatches\fP\&' در نظر گرفته می‌شود\&. مقدار به‌دست‌آمده از \fB$QUILT_PATCHES\fP را می‌توان با استفاده از سبک `\fBquilt\-patch\-dir\fP\&' بازنویسی کرد\&. (نکته: با استفاده از قلاب \fBpost\-quilt\fP در \fBvcs_info\fP می‌توانید مقدار \fB$QUILT_PATCHES\fP را همیشه درست نگه دارید)\&.
.PP
هنگامی که دایرکتوری مورد نظر پیدا شود، quilt فعال فرض می‌شود\&. برای گردآوری اطلاعات بیشتر، \fBvcs_info\fP به دنبال دایرکتوری‌ای با نام `\&.pc\&' می‌گردد؛ Quilt از این دایرکتوری برای پیگیری وضعیت فعلی خود استفاده می‌کند\&. اگر این دایرکتوری وجود نداشته باشد، می‌دانیم که quilt هیچ تغییری روی دایرکتوری کاری اعمال نکرده است (بدین معنا که هنوز هیچ وصله‌ای اعمال نشده است)\&.
.PP
اگر وصله‌هایی اعمال شده باشند، \fBvcs_info\fP سعی خواهد کرد تا مشخص کند کدام وصله‌ها هستند\&. چنانچه مایلید بدانید کدام وصله‌ها از یک مجموعه هنوز اعمال نشده‌اند، باید سبک \fBget\-unapplied\fP را در بافت مربوطه فعال کنید\&.
.PP
سامانه \fBvcs_info\fP امکان نظارت بسیار دقیقی را بر نحوه نمایش اطلاعات گردآوری‌شده فراهم می‌کند (بخش‌های \fBConfiguration\fP و \fBHooks in vcs_info\fP را ببینید)، که همگی در ادامه مستند شده‌اند\&. توجه داشته باشید سامانه‌های ردیابی وصله دیگری نیز وجود دارند که روی سامانه‌های کنترل نسخه خاصی کار می‌کنند (مانند \fBstgit\fP برای \fBgit\fP، یا \fBmq\fP برای \fBhg\fP)؛ پیکربندی چنین سامانه‌هایی عموماً مانند پشتیبانی از \fBquilt\fP انجام می‌پذیرد\&.
.PP
اگر پشتیبانی \fBquilt\fP در حالت «addon» عمل کند، رشته تولیدشده به عنوان یک جایگزین ساده قالب (دقیقاً \fB%Q\fP) در دسترس خواهد بود که می‌توان از آن در \fBformats\fP و \fBactionformats\fP استفاده کرد؛ برای جزئیات به بخش‌های پایین‌تر رجوع کنید)\&.
.PP
در مقابل، اگر کد پشتیبانی در حالت «standalone» فعالیت کند، \fBvcs_info\fP طوری رفتار خواهد کرد که گویی \fBquilt\fP یک سامانه کنترل نسخه واقعی است\&. این بدان معناست که شناسه سامانه کنترل نسخه (که در غیر این صورت مقداری مانند `svn\&' یا `cvs' بود) روی `\fB\-quilt\-\fP\&' تنظیم خواهد شد\&. این موضوع روی بافت سبک مورداستفاده که این شناسه عنصر دوم آن است اثرگذار خواهد بود\&. سامانه \fBvcs_info\fP مقدار مناسبی را برای دایرکتوری ریشه «مخزن» پر می‌کند و رشته حاوی اطلاعات وضعیت quilt به عنوان جایگزین `misc' (و همچنین \fB%Q\fP به منظور سازگاری با حالت «addon») در دسترس خواهد بود\&.
.PP
آنچه برای بحث باقی می‌ماند چگونگی تشخیص حالت «standalone» است\&. خود این تشخیص شامل مجموعه‌ای از جستجوها برای دایرکتوری‌هاست\&. شما می‌توانید این قابلیت تشخیص را همیشه در هر دایرکتوری‌ای که به صورت دیگر تحت کنترل نسخه نیست فعال داشته باشید\&. اگر می‌دانید تنها درخت‌های محدودی وجود دارند که مایلید \fBvcs_info\fP در آن‌ها به جستجوی Quilt در حالت «standalone» بپردازد تا میزان جستجو در هر بار فراخوانی \fBvcs_info\fP به کمترین حد ممکن برسد، روش‌های متعددی برای این کار وجود دارد:
.PP
اساساً، تشخیص حالت «standalone» توسط سبکی به نام `\fBquilt\-standalone\fP\&' کنترل می‌شود\&. این یک سبک رشته‌ای است و مقدار آن می‌تواند اثرات مختلفی داشته باشد\&. ساده‌ترین مقادیر عبارتند از: `\fBalways\fP\&' جهت اجرای تشخیص در هر بار اجرای \fBvcs_info\fP، و `\fBnever\fP\&' به منظور غیرفعال‌سازی کامل تشخیص\&.
.PP
اگر مقدار \fBquilt\-standalone\fP چیز دیگری باشد، به شیوه متفاوتی تفسیر می‌شود\&. چنانچه مقدار نام یک متغیر اسکالر (scalar) باشد، مقدار آن متغیر ارزیابی شده و دقیقاً به شیوه `always'/`never' مذکور در بالا به کار می‌رود\&.
.PP
اگر مقدار \fBquilt\-standalone\fP یک آرایه باشد، عناصر آن آرایه به عنوان نام دایرکتوری‌هایی تلقی می‌شوند که می‌خواهید تشخیص در ذیل آن‌ها فعال باشد\&.
.PP
اگر \fBquilt\-standalone\fP یک آرایه انجمنی (associative array) باشد، کلیدها به عنوان نام دایرکتوری‌هایی فرض می‌شوند که می‌خواهید تشخیص زیر آن‌ها فعال باشد، اما تنها در حالتی که مقدار متناظر آن رشته `\fBtrue\fP\&' باشد\&.
.PP
در آخر، اگر مقدار \fBquilt\-standalone\fP نام یک تابع باشد، تابع بدون آرگومان فراخوانی می‌گردد و مقدار بازگشتی تعیین می‌کند که آیا تشخیص باید فعال باشد یا خیر\&. مقدار بازگشتی `0\&' به معنای درست (true) بوده و مقدار بازگشتی غیرصفر به صورت نادرست (false) تفسیر می‌گردد\&.
.PP
توجه داشته باشید، اگر هم یک تابع و هم یک متغیر با نام \fBquilt\-standalone\fP موجود باشد، تقدم با تابع خواهد بود\&.
.PP.SS "شرح توابع (API عمومی)"
.PP
.PD 0
.TP
.PD
\fBvcs_info\fP [\fIuser\-context\fP]
تابع اصلی که تمام backendها را اجرا کرده و همهٔ داده‌ها را در
\fB${vcs_info_msg_*_}\fP سرهم می‌کند\&. این تابعی است که اگر می‌خواهید
اطلاعات به‌روز را در اعلان (prompt) خود بگنجانید، باید آن را از
\fBprecmd\fP فراخوانی کنید (به
\fBشرح متغیرها\fP
در زیر نگاه کنید)\&. اگر یک آرگومان داده شود، آن رشته به جای
\fBdefault\fP در فیلد \fIuser\-context\fP از بافت سبک (style context)
استفاده خواهد شد\&.
.TP
\fBvcs_info_hookadd\fP
تعدادی از توابع را به صورت ایستا در یک قلاب (hook) مشخص ثبت می‌کند\&.
قلاب باید به عنوان نخستین آرگومان داده شود؛ آنچه در ادامه می‌آید فهرستی
از نام‌های توابع قلاب برای ثبت در آن قلاب است\&. پیشوند `\fB+vi\-\fP\&' در اینجا
باید حذف شود\&. برای جزئیات به \fBقلاب‌ها در vcs_info\fP در زیر مراجعه کنید\&.
.TP
\fBvcs_info_hookdel\fP
حذف توابع قلاب از یک قلاب مشخص\&. قلاب باید به عنوان نخستین آرگومان
غیرگزینه‌ای داده شود؛ آنچه در ادامه می‌آید فهرستی از نام‌های توابع قلاب
برای لغو ثبت از آن قلاب است\&. اگر `\fB\-a\fP\&' به عنوان نخستین آرگومان
استفاده شود، \fBتمام\fP دفعات وقوع توابع لغو ثبت می‌شوند\&. در غیر این صورت
تنها آخرین مورد حذف می‌شود (اگر تابعی بیش از یک بار در قلاب ثبت شده باشد)\&.
پیشوند `\fB+vi\-\fP\&' در اینجا باید حذف شود\&.
برای جزئیات به \fBقلاب‌ها در vcs_info\fP در زیر مراجعه کنید\&.
.TP
\fBvcs_info_lastmsg\fP
مقادیر کنونی \fB${vcs_info_msg_*_}\fP را در خروجی چاپ می‌کند\&.
مقدار سبک \fBuse\-prompt\-escapes\fP را در
\fB\&':vcs_info:formats:command:\-all\-'\fP لحاظ می‌کند\&. همچنین تنها
مقادیر را به تعداد \fBmax\-exports\fP چاپ می‌کند\&.
.TP
\fBvcs_info_printsys\fP [\fIuser\-context\fP]
فهرستی از تمام سیستم‌های کنترل نسخهٔ پشتیبانی‌شده را چاپ می‌کند\&. برای
آگاهی از بافت‌های ممکن (و اینکه کدام‌یک فعال هستند) یا مقادیر مناسب
برای سبک \fBdisable\fP مفید است\&.
.TP
\fBvcs_info_setsys\fP
فهرست درونی backendهای دردسترس \fBvcs_info\fP را مقداردهی اولیه می‌کند\&.
با این تابع می‌توانید بدون راه‌اندازی مجدد شل، پشتیبانی از VCSهای جدید
را اضافه کنید\&.
.PP
تمام توابع به نام \fBVCS_INFO_*\fP صرفاً برای استفادهٔ داخلی هستند\&.
.PP
.SS "شرح متغیرها"
.PP
.PD 0
.TP
.PD
\fB${vcs_info_msg_\fP\fIN\fP\fB_}\fP (به زیرخط انتهایی توجه کنید)
جایی که \fIN\fP یک عدد صحیح است، مانند \fBvcs_info_msg_0_\fP\&. این متغیرها
محل ذخیرهٔ پیام اطلاعاتی هستند که آخرین فراخوانی \fBvcs_info\fP سرهم کرده
است\&. این‌ها وابستگی شدیدی به سبک‌های \fBformats\fP، \fBactionformats\fP
و \fBnvcsformats\fP شرح‌داده‌شده در بالا دارند\&. این سبک‌ها فهرست هستند\&.
نخستین عضو این فهرست در \fB${vcs_info_msg_0_}\fP، دومی در
\fB${vcs_info_msg_1_}\fP و Nاُمین عضو در \fB${vcs_info_msg_N\-1_}\fP
بسط می‌یابد\&. (به سبک \fBmax\-exports\fP در بالا مراجعه کنید\&.)
.PP
تمام متغیرهای به نام \fBVCS_INFO_*\fP صرفاً برای استفادهٔ داخلی هستند\&.
.PP
.SS "قلاب‌ها در vcs_info"
.PP
قلاب‌ها مکان‌هایی در \fBvcs_info\fP هستند که می‌توانید کد خود را در آن‌ها
اجرا کنید\&. آن کد می‌تواند با کدی که آن را فراخوانی کرده ارتباط برقرار کند
و از این طریق، رفتار سیستم را تغییر دهد\&.
.PP
جهت پیکربندی، قلاب‌ها بافت سبک را تغییر می‌دهند:
.RS
.nf
\fB:vcs_info:\fIvcs\-string\fP+\fIhook\-name\fP:\fIuser\-context\fP:\fIrepo\-root\-name\fP\fP
.fi
.RE
.PP
برای ثبت توابع در یک قلاب، باید آن‌ها را در سبک \fBhooks\fP در بافت
مناسب فهرست کنید\&.
.PP
مثال:
.RS
.nf
\fBzstyle \&':vcs_info:*+foo:*' hooks bar baz\fP
.fi
.RE
.PP
این کار توابع را در قلاب `foo\&' برای تمام backendها ثبت می‌کند\&.
به‌منظور جلوگیری از تداخل فضای نام، نام همهٔ توابع ثبت‌شده با یک
`\fB+vi\-\fP\&' پیشوندگذاری می‌شود، بنابراین توابع واقعی فراخوانی‌شده
برای قلاب `foo' عبارتند از `\fB+vi\-bar\fP\&' و `\fB+vi\-baz\fP'\&.
.PP
اگر مایلید تابعی را صرف‌نظر از بافت کنونی در یک قلاب ثبت کنید، می‌توانید
از تابع \fBvcs_info_hookadd\fP استفاده کنید\&. برای حذف تابعی که به
این شکل اضافه شده است، می‌توان از تابع \fBvcs_info_hookdel\fP استفاده کرد\&.
.PP
اگر چیزی عجیب به نظر می‌رسد، می‌توانید سبک بولی `debug\&' را در بافت
مربوطه فعال کنید و کد فراخوانندهٔ قلاب، آنچه را که تلاش کرده اجرا کند
و اینکه آیا تابع مورد نظر وجود داشته است یا خیر را چاپ خواهد کرد\&.
.PP
هنگامی که بیش از یک تابع را در یک قلاب ثبت می‌کنید، همهٔ توابع یکی پس
از دیگری اجرا می‌شوند تا زمانی که یک تابع مقداری غیرصفر بازگرداند یا تمام
توابع فراخوانی شوند\&. توابع قلاب وابسته به بافت، \fBپیش از\fP توابع ایستا
ثبت‌شده (مواردی که با \fBvcs_info_hookadd\fP اضافه شده‌اند) اجرا می‌شوند\&.
.PP
می‌توانید از طریق یک آرایهٔ انجمنی به نام \fBuser_data\fP داده‌ها را بین
توابع منتقل کنید\&. برای مثال:
.RS
.nf
\fB
+vi\-git\-myfirsthook(){
    user_data[myval]=$myval
}
+vi\-git\-mysecondhook(){
    # do something with ${user_data[myval]}
}\fP
.fi
.RE
.PP
تعدادی متغیر وجود دارند که در بافت‌های قلاب خاص هستند:
.PP
.PD 0
.TP
.PD
\fBret\fP
مقدار بازگشتی که سامانهٔ قلاب‌ها به فراخواننده بازمی‌گرداند\&. مقدار
پیش‌فرض عدد صحیح `صفر\&' است\&. اینکه آیا و چگونه یک مقدار تغییریافتهٔ
\fBret\fP اجرای فراخواننده را تغییر می‌دهد به قلاب مشخص بستگی دارد\&. برای
جزئیات به مستندات قلاب در زیر مراجعه کنید\&.
.TP
\fBhook_com\fP
یک آرایهٔ انجمنی که برای ارتباط دوطرفه بین فراخواننده و توابع قلاب
استفاده می‌شود\&. کلیدهای مورد استفاده به قلاب خاص بستگی دارد\&.
.TP
\fBcontext\fP
بافت فعال قلاب\&. توابعی که مایل به تغییر این متغیر هستند باید ابتدا حوزهٔ
آن را محلی (local) کنند\&.
.TP
\fBvcs\fP
سامانهٔ VCS کنونی پس از تشخیص\&. همان مقادیر مربوط به سبک enable/disable
استفاده می‌شوند\&. در تمام قلاب‌ها به جز \fBstart\-up\fP در دسترس است\&.
.PP
در نهایت، فهرست کامل قلاب‌های در دسترس کنونی:
.PP
.PD 0
.TP
.PD
\fBstart\-up\fP
پس از شروع \fBvcs_info\fP اما پیش از تعیین VCS موجود در این دایرکتوری
فراخوانی می‌شود\&. در صورت نیاز می‌تواند برای غیرفعال کردن موقت
\fBvcs_info\fP به کار رود\&. هنگامی که \fBret\fP روی \fB1\fP تنظیم شود،
\fBvcs_info\fP لغو شده و کاری انجام نمی‌دهد؛ زمانی که روی \fB2\fP تنظیم
شود، \fBvcs_info\fP همه‌چیز را طوری تنظیم می‌کند که گویی هیچ کنترل
نسخه‌ای فعال نیست و خارج می‌شود\&.
.TP
\fBpre\-get\-data\fP
مانند \fBstart\-up\fP اما پس از تشخیص VCS\&.
.TP
\fBgen\-hg\-bookmark\-string\fP
در backend مربوط به Mercurial زمانی که یک رشتهٔ نشانک (bookmark) تولید
می‌شود، فراخوانی می‌گردد؛ سبک‌های \fBget\-revision\fP و \fBget\-bookmarks\fP
باید true باشند\&.
.RS
.PP
این قلاب نام‌های نشانک‌های Mercurial را که \fBvcs_info\fP از `hg\&'
جمع‌آوری کرده، دریافت می‌کند\&.
.PP
اگر نشانکی فعال باشد، کلید \fB${hook_com[hg\-active\-bookmark]}\fP
روی نام آن تنظیم می‌شود\&. در غیر این صورت این کلید تنظیم‌نشده (unset)
خواهد بود\&.
.PP
هنگام تنظیم \fBret\fP به مقداری غیرصفر، رشتهٔ موجود در
\fB${hook_com[hg\-bookmark\-string]}\fP در گریز (escape) مربوط به \fB%m\fP
در \fBformats\fP و \fBactionformats\fP استفاده خواهد شد و در آرایهٔ سراسری
\fBbackend_misc\fP به‌صورت \fB${backend_misc[bookmarks]}\fP در دسترس
خواهد بود\&.
.RE
.TP
\fBgen\-applied\-string\fP
در backendهای \fBgit\fP (همراه با \fBstgit\fP یا در طول rebase یا merge)
و \fBhg\fP (همراه با \fBmq\fP) و در پشتیبانی \fBquilt\fP زمانی که
\fBapplied\-string\fP تولید می‌شود، فراخوانی می‌گردد؛ zstyle مربوط به
\fBuse\-quilt\fP برای \fBquilt\fP باید true باشد (backendهای \fBmq\fP
و \fBstgit\fP به‌طور پیش‌فرض فعال هستند)\&.
.RS.PP
آرگومان‌های ورودی این قلاب، وصله‌های اِعمال‌شده را با ترتیب معکوس شرح می‌دهند،
بدین معنا که نخستین آرگومان، بالاترین وصله است و الی آخر\&.
.PP
هنگامی که پیام‌های گزارش وصله‌ها قابل استخراج باشند، پس از یک فاصله
درون هر آرگومان قرار می‌گیرند؛ بنابراین هر آرگومان به صورت
`\fIpatch\-name\fP \fIfirst line of the log message\fP\&' خواهد بود که در آن \fIpatch\-name\fP
شامل هیچ فاصله خالی (whitespace) نیست\&. پشتیبان \fBmq\fP آرگومان‌ها را به شکل
`\fIpatch name\fP\&' همراه با فاصله‌های احتمالی، اما بدون استخراج پیام گزارش وصله ارسال می‌کند\&.
.PP
هنگام تنظیم \fBret\fP به مقداری غیرصفر، رشته موجود در
\fB${hook_com[applied\-string]}\fP به عنوان \fB%p\fP در سبک‌های
\fBpatch\-format\fP و \fBnopatch\-format\fP در دسترس خواهد بود\&.
این قلاب به همراه \fBset\-patch\-format\fP مسئول گریزدهی (escape کردن)
نویسه‌های \fB%\fP در آن مقدار جهت استفاده در خط فرمان (prompt) است\&.
(بخش \fBOddities\fP را ببینید\&.)
.PP
پشتیبان \fBquilt\fP ورودی‌های \fB${hook_com[quilt\-patches\-dir]}\fP و در صورت مشخص شدن،
\fB${hook_com[quilt\-pc\-dir]}\fP را به این قلاب ارسال می‌کند\&.
.RE
.TP
\fBgen\-unapplied\-string\fP
در پشتیبان‌های \fBgit\fP (با \fBstgit\fP یا هنگام rebase) و \fBhg\fP (با
\fBmq\fP) و در پشتیبانی از \fBquilt\fP هنگامی که \fBunapplied\-string\fP تولید می‌شود،
فراخوانی می‌گردد؛ سبک \fBget\-unapplied\fP باید مقدار true داشته باشد\&.
.RS
.PP
این قلاب نام تمام وصله‌های اِعمال‌نشده را به ترتیبی که \fBvcs_info\fP به دست آورده دریافت می‌کند،
بدین معنا که نخستین آرگومان، وصله بعدی در صف اِعمال است و الی آخر\&.
.PP
قالب هر آرگومان مشابه \fBgen\-applied\-string\fP در بالا است\&.
.PP
هنگام تنظیم \fBret\fP به مقداری غیرصفر، رشته موجود در
\fB${hook_com[unapplied\-string]}\fP به عنوان \fB%u\fP در سبک‌های
\fBpatch\-format\fP و \fBnopatch\-format\fP در دسترس خواهد بود\&.
این قلاب به همراه \fBset\-patch\-format\fP مسئول گریزدهی نویسه‌های
\fB%\fP در آن مقدار جهت استفاده در خط فرمان (prompt) است\&.
(بخش \fBOddities\fP را ببینید\&.)
.PP
پشتیبان \fBquilt\fP ورودی‌های \fB${hook_com[quilt\-patches\-dir]}\fP و در صورت مشخص شدن،
\fB${hook_com[quilt\-pc\-dir]}\fP را به این قلاب ارسال می‌کند\&.
.RE
.TP
\fBgen\-mqguards\-string\fP
در پشتیبان \fBhg\fP هنگام تولید \fBguards\-string\fP فراخوانی می‌شود؛
سبک \fBget\-mq\fP باید true باشد (پیش‌فرض)\&.
.RS
.PP
این قلاب نام‌های همه نگه‌بان‌های (guards) فعال \fBmq\fP را دریافت می‌کند\&.
.PP
هنگام تنظیم \fBret\fP به مقداری غیرصفر، رشته موجود در
\fB${hook_com[guards\-string]}\fP در توالی گریز \fB%g\fP در سبک‌های
\fBpatch\-format\fP و \fBnopatch\-format\fP استفاده خواهد شد\&.
.RE
.TP
\fBno\-vcs\fP
این قلاب هنگامی فراخوانی می‌شود که هیچ سیستم کنترل نگارشی شناسایی نشده باشد\&.
.RS
.PP
پارامتر `\fBhook_com\fP\&' استفاده نمی‌شود\&.
.RE
.TP
\fBpost\-backend\fP
به محض اینکه پشتیبان جمع‌آوری اطلاعات را به پایان برساند فراخوانی می‌شود\&.
.RS
.PP
کلیدهای `\fBhook_com\fP\&' در دسترس، همانند قلاب \fBset\-message\fP هستند\&.
.RE
.TP
\fBpost\-quilt\fP
پس از پایان کار پشتیبانی از \fBquilt\fP فراخوانی می‌شود\&. اطلاعات زیر به عنوان آرگومان
به قلاب منتقل می‌شوند: ۱\&. حالت پشتیبانی quilt (مقدار `addon\&' یا `standalone\&')؛
۲\&. دایرکتوری حاوی مجموعه‌وصله‌ها (patch series)؛ ۳\&. دایرکتوری نگه‌دارنده اطلاعات
وضعیت quilt (دایرکتوری `\&.pc') یا رشته \fB"\-nopc\-"\fP در صورتی که آن دایرکتوری
یافت نشده باشد\&.
.RS
.PP
پارامتر `hook_com\&' استفاده نمی‌شود\&.
.RE
.TP
\fBset\-branch\-format\fP
پیش از تنظیم شدن `\fBbranchformat\fP\&' فراخوانی می‌شود\&. تنها آرگومان ارسالی
به قلاب، قالبی است که در این نقطه پیکربندی شده است\&.
.RS
.PP
کلیدهای مورد بررسی در `\fBhook_com\fP\&'، کلیدهای `\fBbranch\fP' و `\fBrevision\fP' هستند\&.
آن‌ها روی مقادیری که تاکنون توسط \fBvcs_info\fP شناسایی شده تنظیم می‌شوند و هرگونه
تغییری مستقیماً هنگام جایگزینی واقعی اعمال خواهد شد\&.
.PP
اگر \fBret\fP روی مقداری غیرصفر تنظیم شود، رشته موجود در
\fB${hook_com[branch\-replace]}\fP بدون تغییر به عنوان جایگزین
`\fB%b\fP\&' در متغیرهای تنظیم‌شده توسط \fBvcs_info\fP استفاده خواهد شد\&.
.RE
.TP
\fBset\-hgrev\-format\fP
پیش از تنظیم شدن یک `\fBhgrevformat\fP\&' فراخوانی می‌شود\&. تنها آرگومان ارسالی
به قلاب، قالبی است که در این نقطه پیکربندی شده است\&.
.RS
.PP
کلیدهای مورد بررسی در `\fBhook_com\fP\&'، کلیدهای `\fBhash\fP' و `\fBlocalrev\fP' هستند\&.
آن‌ها روی مقادیری که تاکنون توسط \fBvcs_info\fP مشخص شده تنظیم می‌شوند و هرگونه
تغییری مستقیماً هنگام انجام جایگزینی واقعی به کار خواهد رفت\&.
.PP
اگر \fBret\fP روی مقداری غیرصفر تنظیم شود، رشته موجود در
\fB${hook_com[rev\-replace]}\fP بدون تغییر به عنوان جایگزین
`\fB%i\fP\&' در متغیرهای مقداردهی‌شده توسط \fBvcs_info\fP استفاده خواهد شد\&.
.RE
.TP
\fBpre\-addon\-quilt\fP
این قلاب هنگامی استفاده می‌شود که قابلیت quilt در \fBvcs_info\fP در حالت "addon"
(استفاده از quilt بر فراز یک سیستم کنترل نگارش واقعی) فعال باشد\&. این قلاب درست
پیش از انجام هرگونه اقدام مختص quilt فعال می‌شود\&.
.RS
.PP
تنظیم متغیر `\fBret\fP\&' در این قلاب به یک مقدار غیرصفر از اجرای هرگونه اقدام
مختص quilt به طور کامل جلوگیری می‌کند\&.
.RE
.TP
\fBset\-patch\-format\fP
این قلاب برای مهار برخی از بسط‌های احتمالی در سبک‌های \fBpatch\-format\fP و
\fBnopatch\-format\fP همراه با سامانه‌های صف وصله مانند quilt، mqueue و نظایر
آن استفاده می‌شود\&.
.RS
.PP
این قلاب در پشتیبان‌های \fBgit\fP، \fBhg\fP و \fBquilt\fP استفاده می‌شود\&.
.PP
این قلاب امکان مهار بسط‌های \fB%p\fP (\fB${hook_com[applied]}\fP) و \fB%u\fP
(\fB${hook_com[unapplied]}\fP) را در تمامی پشتیبان‌هایی که از این قلاب بهره می‌برند فراهم می‌کند\&.
در پشتیبان mercurial، علاوه بر این موارد، بسط \fB%g\fP (\fB${hook_com[guards]}\fP) نیز
قابل کنترل است\&.
.PP
اگر \fBret\fP به مقداری غیرصفر تنظیم شود، رشته موجود در \fB${hook_com[patch\-replace]}\fP
به‌جای قالب بسط‌یافته از \fBpatch\-format\fP یا \fBnopatch\-format\fP، به صورت دست‌نخورده
استفاده خواهد شد\&.
.PP
این قلاب در کنار قلاب‌های \fBgen\-applied\-string\fP یا
\fBgen\-unapplied\-string\fP (در صورت تعریف شدن)، مسئول گریزدهی
نویسه‌های \fB%\fP در مقدار نهایی \fBpatch\-format\fP جهت استفاده در خط فرمان (prompt) است\&.
(بخش \fBOddities\fP را ببینید\&.)
.PP
پشتیبان \fBquilt\fP ورودی‌های \fB${hook_com[quilt\-patches\-dir]}\fP و در صورت مشخص شدن،
\fB${hook_com[quilt\-pc\-dir]}\fP را به این قلاب ارسال می‌کند\&.
.RE
.TP
\fBset\-message\fP
هر بار پیش از مقداردهی یک پیام `\fBvcs_info_msg_\fP\fIN\fP\fB_\fP\&' فراخوانی می‌شود\&.
این قلاب دو آرگومان می‌پذیرد؛ اولی `\fIN\fP\&' موجود در نام متغیر پیام،
و دومی \fBformats\fP یا \fBactionformats\fP پیکربندی‌شده فعلی است\&.
.RS
.PP
تعدادی کلید `\fBhook_com\fP\&' وجود دارند که در اینجا به کار می‌روند:
`\fBaction\fP\&'، `\fBbranch\fP'، `\fBbase\fP'، `\fBbase\-name\fP'، `\fBsubdir\fP'،
`\fBstaged\fP\&'، `\fBunstaged\fP'، `\fBrevision\fP'، `\fBmisc\fP'، `\fBvcs\fP'
و یک مدخل `\fBmiscN\fP\&' برای هر فیلد داده‌ای مختص به پشتیبان (\fBN\fP
از صفر شروع می‌شود)\&. آن‌ها روی مقادیری که تاکنون توسط \fBvcs_info\fP
شناسایی شده مقداردهی می‌شوند و هرگونه تغییری مستقیماً هنگام انجام
جایگزینی واقعی اعمال خواهد شد\&.
.PP
از آنجا که این قلاب چندین بار فعال می‌شود (یک بار برای هر یک از
\fBformats\fP یا \fBactionformats\fP پیکربندی‌شده)، هر کدام از کلیدهای `\fBhook_com\fP\&'
که در بالا ذکر شد (به استثنای مدخل‌های \fBmiscN\fP) یک همتای `\fB_orig\fP\&'
دارند؛ بنابراین حتی اگر مقداری را مطابق نیاز خود تغییر دهید، همچنان می‌توانید در اجرای
بعدی به مقدار اصلی دسترسی داشته باشید\&. دستکاری مقادیر `\fB_orig\fP\&' احتمالاً
ایده مناسبی نیست\&.
.PP
اگر \fBret\fP به مقداری غیرصفر تنظیم شود، رشته موجود در
\fB${hook_com[message]}\fP بدون تغییر به عنوان پیام توسط
\fBvcs_info\fP استفاده خواهد شد\&.
.RE
.PP
اگر تمام این موارد تا حدودی گیج‌کننده به نظر می‌رسد، به بخش \fBExamples\fP
در زیر و همچنین به فایل \fBMisc/vcs_info\-examples\fP در کد منبع Zsh
نگاهی بیندازید\&. آنها حاوی کدهای توضیحی هستند\&..PP
.SS "مثال‌ها (Examples)"
.PP
به‌هیچ‌وجه از \fBvcs_info\fP استفاده نکنید (حتی اگر در اعلان (prompt) شما قرار دارد):
.RS
.nf
\fBzstyle \&':vcs_info:*' enable NONE\fP
.fi
.RE
.PP
غیرفعال کردن پس‌اندهای مربوط به \fBbzr\fP و \fBsvk\fP:
.RS
.nf
\fBzstyle \&':vcs_info:*' disable bzr svk\fP
.fi
.RE
.PP
غیرفعال کردن همه‌چیز \fIبه‌جز\fP \fBbzr\fP و \fBsvk\fP:
.RS
.nf
\fBzstyle \&':vcs_info:*' enable bzr svk\fP
.fi
.RE
.PP
ارائه قالب‌های ویژه برای \fBgit\fP:
.RS
.nf
\fBzstyle \&':vcs_info:git:*' formats       ' GIT, BABY! [%b]'
zstyle \&':vcs_info:git:*' actionformats ' GIT ACTION! [%b|%a]'\fP
.fi
.RE
.PP
تمام بسط‌های \fB%x\fP در انواع قالب‌ها (\fBformats\fP، \fBactionformats\fP،
\fBbranchformat\fP و غیره) با استفاده از دستور توکار `\fBzformat\fP\&' از
پودمان `\fBzsh/zutil\fP\&' انجام می‌شوند\&. این بدان معناست که هر آنچه
\fBzformat\fP پشتیبانی می‌کند را می‌توانید با این موارد \fB%x\fP انجام دهید\&.
به‌ویژه، اگر می‌خواهید مقداری که بسیار طولانی است دارای عرض ثابت باشد،
مانند یک هش در \fBbranchformat\fP برای mercurial، می‌توانید این کار را
انجام دهید: \fB%12\&.12i\fP\&. این کار هش ۴۰ نویسه‌ای را به ۱۲ نویسه ابتدایی آن
خلاصه می‌کند\&. این ساختار در واقع به صورت
`\fB%\fP\fImin\fP\fB\&.\fP\fImax\fP\fBx\fP\&'\& است\&. امکانات بیشتری نیز وجود دارد\&.
برای جزئیات به بخش `The zsh/zutil Module\&' در \fIzshmodules\fP(1) مراجعه کنید\&.
.PP
استفاده از پس‌اند سریع‌تر \fBbzr\fP
.RS
.nf
\fBzstyle \&':vcs_info:bzr:*' use\-simple true\fP
.fi
.RE
.PP
اگر از \fBuse\-simple\fP استفاده می‌کنید، لطفاً گزارش دهید که آیا کارکرد درست و مورد انتظاری (`the\-right\-thing[tm]\&') دارد یا خیر\&.
.PP
نمایش شماره بازبینی (revision) با رنگ زرد برای \fBbzr\fP و \fBsvn\fP:
.RS
.nf
\fBzstyle \&':vcs_info:(svn|bzr):*' \e 
       branchformat \&'%b%%F{yellow}:%r'\fP
.fi
.RE
.PP
دلیل دو برابر شدن علامت درصد در
بخش \fBOddities\fP توضیح داده شده است\&.
.PP
به‌عنوان روش جایگزین، می‌توان مستقیماً از کدهای رنگی خام استفاده کرد:
.PP
.RS
.nf
\fBzstyle \&':vcs_info:(svn|bzr):*' \e 
       branchformat \&'%b%{'${fg[yellow]}'%}:%r'\fP
.fi
.RE
.PP
به‌طور معمول وقتی یک متغیر درون یک رشته قالب جای‌گذاری (interpolate) می‌شود،
باید با \fB%\fP گریزدهی (escape) شود\&. در این مثال از این کار صرف‌نظر کردیم
زیرا فرض می‌کنیم مقدار \fB${fg[yellow]}\fP شامل هیچ علامت \fB%\fP نیست\&.
.PP
اگر می‌خواهید از رشته ارائه‌شده توسط \fBvcs_info\fP در اعلان‌ها استفاده کنید،
مطمئن شوید که کدهای رنگ را درون \fB%{\fP\fI\&.\&.\&.\fP\fB%}\fP قرار می‌دهید\&.
.PP
در اینجا نحوه چاپ اطلاعات VCS به عنوان یک دستور (نه در اعلان) آمده است:
.RS
.nf
\fBvcsi() { vcs_info interactive; vcs_info_lastmsg }\fP
.fi
.RE
.PP
از این طریق، حتی می‌توانید قالب‌های متفاوتی را برای خروجی از طریق
\fBvcs_info_lastmsg\fP در فضای نام \&'\fB:vcs_info:*:interactive:*\fP' تعریف کنید\&.
.PP
اکنون همان‌طور که وعده داده شد، کدی که از قلاب‌ها (hooks) استفاده می‌کند:
فرض کنید می‌خواهید رشته `svn' را با `subversion' در
جایگزینی \fB%s\fP در \fBformats\fP برای \fBvcs_info\fP جایگزین کنید\&.
.PP
ابتدا، به \fBvcs_info\fP می‌گوییم هنگام پر کردن متغیرهای پیام
با اطلاعات جمع‌آوری‌شده، یک تابع را فراخوانی کند:
.RS
.nf
\fBzstyle \&':vcs_info:*+set\-message:*' hooks svn2subversion\fP
.fi
.RE
.PP
هیچ اتفاقی نمی‌افتد\&. که البته منطقی است، زیرا ما هنوز تابع واقعی را
تعریف نکرده‌ایم\&. برای مشاهده اینکه زیرسیستم قلاب‌ها در تلاش برای انجام چه کاری است،
شیوه (style) `\fBdebug\fP\&' را فعال کنید:
.RS
.nf
\fBzstyle \&':vcs_info:*+*:*' debug true\fP
.fi
.RE
.PP
این کار باید تصویری از آنچه در حال رخ دادن است به شما بدهد\&. به‌طور مشخص، تابعی
که به دنبال آن هستیم `\fB+vi\-svn2subversion\fP\&' است\&. به پیشوند `\fB+vi\-\fP'
توجه کنید\&. بنابراین، همه‌چیز مرتب و دقیقاً مطابق مستندات است\&. وقتی کارتان با
بررسی خروجی اشکال‌زدایی تمام شد، دوباره آن را غیرفعال کنید:
.RS
.nf
\fBzstyle \&':vcs_info:*+*:*' debug false\fP
.fi
.RE
.PP
اکنون، بیایید تابع را تعریف کنیم:
.RS
.nf
\fB
function +vi\-svn2subversion() {
    [[ ${hook_com[vcs_orig]} == svn ]] && hook_com[vcs]=subversion
}\fP
.fi
.RE
.PP
به اندازه کافی ساده است\&. و حتی می‌توانست ساده‌تر باشد، اگر فقط
تابع خود را در یک زمینه (context) با عمومیت کمتر ثبت می‌کردیم\&. اگر این کار را تنها
در زمینه پس‌اند `\fBsvn\fP\&' انجام دهیم، دیگر نیازی به بررسی اینکه کدام
پس‌اند فعال است نخواهیم داشت:
.RS
.nf
\fBzstyle \&':vcs_info:svn+set\-message:*' hooks svn2subversion\fP
.fi
.RE
.RS
.nf
\fB
function +vi\-svn2subversion() {
    hook_com[vcs]=subversion
}\fP
.fi
.RE
.PP
و در نهایت یک مثال کمی مفصل‌تر، که از یک قلاب برای ایجاد
یک رشته نشانک (bookmark) سفارشی برای پس‌اند \fBhg\fP استفاده می‌کند\&.
.PP
مجدداً، با ثبت یک تابع کار را آغاز می‌کنیم:
.RS
.nf
\fBzstyle \&':vcs_info:hg+gen\-hg\-bookmark\-string:*' hooks hgbookmarks\fP
.fi
.RE
.PP
و سپس تابع `\fB+vi\-hgbookmarks\fP\&' را تعریف می‌کنیم:
.RS
.nf
\fB
function +vi\-hgbookmarks() {
    # حالت پیش‌فرض این است که تمام نام‌های نشانک با
    # ویرگول به هم متصل شوند\&. این کار اوضاع را کمی درهم می‌کند\&.
    # تصور کنید نوعی از نشانک‌ها وجود دارد که برای شما
    # خاص است؛ مثلاً به این دلیل که کار *خودتان* است\&.
    # این نشانک‌ها همیشه به این شکل هستند: "sh/*"
    # (برای مثال، به این دلیل که حروف اول نام شما sh است)\&.
    # این کار باعث می‌شود رشته نشانک‌ها تنها از آن
    # نشانک‌ها استفاده کند\&. اگر بیش از یکی وجود داشته باشد،
    # آن‌ها را با استفاده از ویرگول به هم متصل می‌کند\&.
    # نشانک‌های بازگردانده‌شده توسط `hg\&' در پارامترهای
    # موقعیتی تابع در دسترس هستند\&.
    local s="${(Mj:,:)@:#sh/*}"
    # اکنون، ارتباط با کدی که توابع قلاب را فراخوانی
    # می‌کند از طریق درهم‌سازی hook_com[] انجام
    # می‌شود\&. کلیدی که قلاب `gen\-hg\-bookmark\-string\&'
    # بررسی می‌کند `hg\-bookmark\-string\&' است\&. بنابراین:
    hook_com[hg\-bookmark\-string]=$s
    # و برای اعلام اینکه می‌خواهیم از رشته‌ای که تازه تولید
    # کرده‌ایم استفاده شود، متغیر ویژه `ret\&' را روی مقداری
    # غیر از پیش‌فرض صفر تنظیم کنید:
    ret=1
    return 0
}\fP
.fi
.RE.PP
برخی مثال‌های طولانی‌تر و قطعه‌کدهایی که ممکن است مفید باشند در فایل مثال‌ها واقع در Misc/vcs_info\-examples در دایرکتوری سورس Zsh در دسترس هستند\&.
.PP
این بخش راهنمای گام‌به‌گام ما را دربارهٔ \fBvcs_info\fP در zsh به پایان می‌رساند\&.
.PP
.SH "پوسته‌های اعلان (PROMPT THEMES)"
.PP
.SS "نصب (Installation)"
.PP
باید اطمینان حاصل کنید که تمام توابع موجود در دایرکتوری \fBFunctions/Prompts\fP از توزیع سورس در دسترس هستند؛ به جز تابع ویژهٔ `\fBpromptinit\fP'\&، همگی آن‌ها با رشتهٔ `\fBprompt_\fP\&' آغاز می‌شوند\&.
همچنین به توابع `\fBcolors\fP\&' و `\fBadd\-zsh\-hook\fP' از دایرکتوری \fBFunctions/Misc\fP نیاز دارید\&.
تمام این توابع ممکن است از پیش روی سیستم شما نصب شده باشند؛ در غیر این صورت، باید آن‌ها را پیدا کرده و رونوشت بردارید\&. این دایرکتوری باید به عنوان یکی از عناصر آرایهٔ \fBfpath\fP ظاهر شود (اگر نصب شده باشند، از قبل باید به همین صورت باشد)، و حداقل تابع \fBpromptinit\fP باید به صورت خودکار بارگذاری (autoload) شود؛ این تابع باقی توابع را خودکار بارگذاری خواهد کرد\&. در نهایت، برای مقداردهی اولیه و استفاده از سامانه باید تابع \fBpromptinit\fP را فراخوانی کنید\&. کد زیر در فایل \fB\&.zshrc\fP شما این سازوکار را فراهم می‌کند؛ با این فرض که توابع در دایرکتوری \fB~/myfns\fP ذخیره شده باشند:
.PP
.RS
.nf
\fBfpath=(~/myfns $fpath)
autoload \-U promptinit
promptinit\fP
.fi
.RE
.PP
.SS "انتخاب پوسته (Theme Selection)"
.PP
برای انتخاب پوستهٔ مورد نظر خود از دستور \fBprompt\fP استفاده کنید\&. این دستور می‌تواند پس از فراخوانی \fBpromptinit\fP به فایل \fB\&.zshrc\fP شما افزوده شود تا zsh از همان ابتدا با یک پوستهٔ از پیش انتخاب‌شده اجرا گردد\&.
.PP
.PD 0
.TP
.PD 0
\fBprompt\fP [ \fB\-c\fP | \fB\-l\fP ]
.TP
.PD 0
\fBprompt\fP [ \fB\-p\fP | \fB\-h\fP ] [ \fItheme\fP \&.\&.\&. ]
.TP
.PD
\fBprompt\fP [ \fB\-s\fP ] \fItheme\fP [ \fIarg\fP \&.\&.\&. ]
تنظیم یا بررسی پوستهٔ اعلان\&. بدون هیچ گزینه‌ای و همراه با یک آرگومان \fItheme\fP، پوسته‌ای با آن نام به عنوان پوستهٔ کنونی تنظیم می‌شود\&. پوسته‌های در دسترس در زمان اجرا تعیین می‌شوند؛ برای دیدن فهرست آن‌ها از گزینهٔ \fB\-l\fP استفاده کنید\&. پوستهٔ ویژهٔ `\fBrandom\fP\&' یکی از پوسته‌های موجود را به صورت تصادفی انتخاب کرده و اعلان شما را روی آن تنظیم می‌کند\&.
.RS
.PP
در برخی موارد ممکن است \fItheme\fP با یک یا چند آرگومان که پس از نام پوسته مشخص می‌شوند، تغییر یابد\&. برای شرح این آرگومان‌ها به بخش راهنمای هر پوسته مراجعه کنید\&.
.PP
گزینه‌ها عبارتند از:
.PP
.PD 0
.TP
\fB\-c\fP
نمایش پوستهٔ انتخاب‌شدهٔ کنونی و پارامترهای آن، در صورت وجود\&.
.TP
\fB\-l\fP
فهرست کردن تمام پوسته‌های اعلان در دسترس\&.
.TP
\fB\-p\fP
پیش‌نمایش پوستهٔ تعیین‌شده با \fItheme\fP، یا تمام پوسته‌ها در صورتی که هیچ \fItheme\fP مشخص نشده باشد\&.
.TP
\fB\-h\fP
نمایش راهنما برای پوستهٔ تعیین‌شده با \fItheme\fP، یا برای تابع \fBprompt\fP در صورتی که هیچ \fItheme\fP مشخص نشده باشد\&.
.TP
\fB\-s\fP
تنظیم \fItheme\fP به عنوان پوستهٔ کنونی و ذخیرهٔ وضعیت\&.
.PD
.RE
.TP
\fBprompt_\fP\fItheme\fP\fB_setup\fP
هر \fItheme\fP در دسترس دارای یک تابع راه‌اندازی است که توسط تابع \fBprompt\fP برای نصب آن پوسته فراخوانی می‌شود\&. این تابع ممکن است در صورت نیاز توابع دیگری را برای نگهداری اعلان تعریف کند، از جمله توابعی که برای پیش‌نمایش اعلان یا ارائهٔ راهنما برای استفاده از آن به کار می‌روند\&. در حالت عادی نباید تابع راه‌اندازی یک پوسته را به صورت مستقیم فراخوانی کنید\&.
.PP.SS "تم‌های کاربردی (Utility Themes)"
.PP
.PD 0
.TP
.PD
\fBprompt off\fP
تم `\fBoff\fP\&' تمامی متغیرهای اعلان را بدون هیچ جلوهٔ ویژه‌ای روی مقادیر کمینه تنظیم می‌کند\&.
.TP
\fBprompt default\fP
تم `\fBdefault\fP\&' تمامی متغیرهای اعلان را به همان حالتی تنظیم می‌کند که گویی یک zsh تعاملی بدون هیچ فایل راه‌اندازی آغاز شده است\&.
.TP
\fBprompt restore\fP
تم ویژهٔ `\fBrestore\fP\&' تمام تنظیمات تم را پاک کرده و متغیرهای اعلان را به وضعیت آن‌ها پیش از نخستین باری که تابع `\fBprompt\fP\&' اجرا شد بازمی‌گرداند، به شرطی که هر تم پاک‌سازی (cleanup) خود را به‌درستی تعریف کرده باشد (پایین را ببینید)\&.
.RS
.PP
توجه داشته باشید که می‌توانید اثر `\fBprompt off\fP\&' و `\fBprompt default\fP' را با `\fBprompt restore\fP\&' لغو کنید، اما بازیابی دوم اثر اولی را لغو نمی‌کند\&.
.RE
.PP
.SS "نوشتن تم‌ها (Writing Themes)"
.PP
نخستین گام برای افزودن تم اختصاصی خود، انتخاب نامی برای آن و ایجاد فایلی به نام `\fBprompt_\fIname\fP_setup\fP\&' در پوشه‌ای درون \fBfpath\fP شماست، مانند \fB~/myfns\fP در مثال بالا\&. این فایل باید دست‌کم حاوی مقداردهی‌هایی برای متغیرهای اعلانی باشد که تم شما مایل به تغییر آن‌ها است\&. بر طبق رسم معمول، تم‌ها به جای نام‌های طولانی‌تر \fBPROMPT\fP و \fBRPROMPT\fP، از \fBPS1\fP، \fBPS2\fP، \fBRPS1\fP و غیره استفاده می‌کنند\&.
.PP
این فایل به‌عنوان یک تابع در زمینهٔ جاری پوسته به‌طور خودکار بارگذاری (autoload) می‌شود، بنابراین می‌تواند شامل هر دستور لازمی برای سفارشی‌سازی تم شما باشد، از جمله تعریف توابع اضافی\&. برای آسان‌تر کردن برخی وظایف پیچیده، تابع راه‌اندازی (setup) شما می‌تواند هر یک از کارهای زیر را نیز انجام دهد:
.PP
.PD 0
.TP
.PD
مقداردهی \fBprompt_opts\fP
آرایهٔ \fBprompt_opts\fP می‌تواند هر یک از مقادیر \fB"bang"\fP، \fB"cr"\fP، \fB"percent"\fP، \fB"sp"\fP، و/یا \fB"subst"\fP را دریافت کند\&. گزینه‌های setopt متناظر (\fBpromptbang\fP و غیره) فعال شده و سایر گزینه‌های مرتبط با اعلان خاموش می‌شوند\&. در صورتی که تابع شما نیاز داشته باشد، آرایهٔ \fBprompt_opts\fP گزینه‌های setopt را حتی فراتر از حوزهٔ \fBlocaloptions\fP حفظ می‌کند\&.
.TP
تغییر قلاب‌ها (Modify hooks)
استفاده از \fBadd\-zsh\-hook\fP و \fBadd\-zle\-hook\-widget\fP توصیه می‌شود (بخش \fBManipulating Hook Functions\fP در بالا را ببینید)\&.
تمامی قلاب‌هایی که از الگوی نام‌گذاری \fBprompt_\fP\fItheme\fP\fB_\fP\fIhook\fP پیروی می‌کنند، هنگام تغییر یا غیرفعال شدن تم اعلان، به‌طور خودکار حذف می‌شوند\&.
.TP
اعلام پاک‌سازی (Declare cleanup)
اگر تابع شما تغییرات دیگری ایجاد می‌کند که هنگام غیرفعال شدن تم باید خنثی شوند، تابع راه‌اندازی شما می‌تواند این دستور را فراخوانی کند:
.RS
.PP
.RS
.nf
\fBprompt_cleanup \fIcommand\fP\fP
.fi
.RE
.PP
که در آن \fIcommand\fP باید به‌طور مناسبی نقل‌قول (quote) شده باشد\&. اگر تم شما روزی غیرفعال شود یا تم دیگری جایگزین آن گردد، \fIcommand\fP با \fBeval\fP اجرا خواهد شد\&. شما می‌توانید بیش از یک قلاب پاک‌سازی را تعریف کنید\&.
.RE
.TP
تعریف پیش‌نمایش (Define preview)
تعریف یا بارگذاری خودکار یک تابع به نام \fBprompt_\fP\fIname\fP\fB_preview\fP برای نمایش نسخهٔ شبیه‌سازی‌شده‌ای از اعلان شما\&. یک پیش‌نمایش‌گر پیش‌فرض ساده توسط \fBpromptinit\fP برای تم‌هایی که خودشان پیش‌نمایش را تعریف نکرده‌اند تعیین شده است\&. این تابع پیش‌نمایش توسط `\fBprompt \-p\fP\&' فراخوانی می‌شود\&.
.TP
ارائهٔ راهنما (Provide help)
تعریف یا بارگذاری خودکار یک تابع به نام \fBprompt_\fP\fIname\fP\fB_help\fP برای نمایش مستندات یا متن راهنمای تم شما\&.
این تابع راهنما توسط `\fBprompt \-h\fP\&' فراخوانی می‌شود\&.
.PP.SH "توابع ZLE (ZLE FUNCTIONS)"
.PP
.SS "ابزارک‌ها (Widgets)"
.PP
همهٔ این توابع ابزارک‌های ZLE تعریف‌شده توسط کاربر را پیاده‌سازی می‌کنند (ببینید
\fIzshzle\fP(1)) که می‌توانند در شل‌های تعاملی به کلیدها متصل شوند\&. برای استفاده از آن‌ها،
فایل \fB\&.zshrc\fP شما باید شامل خطوطی به این صورت باشد:
.PP
.RS
.nf
\fBautoload \fIfunction\fP
zle \-N \fIfunction\fP\fP
.fi
.RE
.PP
که در ادامهٔ آن دستور مناسب \fBbindkey\fP برای مرتبط کردن تابع با یک توالی کلید قرار می‌گیرد\&. اتصالات کلیدی پیشنهادی در زیر شرح داده شده‌اند\&.
.PP
.PD 0
.TP
.PD
توابع کلمه به سبک bash (bash\-style word functions)
اگر به دنبال توابعی برای پیاده‌سازی پیمایش و ویرایش کلمات به شیوهٔ bash هستید، که در آن فقط نویسه‌های حرفی‌عددی به عنوان نویسه‌های کلمه در نظر گرفته می‌شوند، می‌توانید از توابع شرح‌داده‌شده در بخش بعدی استفاده کنید\&. موارد زیر کافی است:
.RS
.PP
.RS
.nf
\fBautoload \-U select\-word\-style
select\-word\-style bash\fP
.fi
.RE
.PP
.RE
.TP
.PD 0
\fBforward\-word\-match\fP, \fBbackward\-word\-match\fP
.TP
.PD 0
\fBkill\-word\-match\fP, \fBbackward\-kill\-word\-match\fP
.TP
.PD 0
\fBtranspose\-words\-match\fP, \fBcapitalize\-word\-match\fP
.TP
.PD 0
\fBup\-case\-word\-match\fP, \fBdown\-case\-word\-match\fP
.TP
.PD 0
\fBdelete\-whole\-word\-match\fP, \fBselect\-word\-match\fP
.TP
.PD
\fBselect\-word\-style\fP, \fBmatch\-word\-context\fP, \fBmatch\-words\-by\-style\fP
هشت تابع نخست `\fB\-match\fP\&' جایگزین‌های مستقیمی برای ابزارک‌های توکار بدون این پسوند هستند\&. آن‌ها به صورت پیش‌فرض به شیوه‌ای مشابه عمل می‌کنند\&. با این حال، با استفاده از سبک‌ها (styles) و تابع \fBselect\-word\-style\fP، نحوهٔ تطبیق کلمات می‌تواند دگرگون شود\&. تابع \fBselect\-word\-match\fP برای استفاده به عنوان یک شیء متنی (text object) در حالت vi اما با سبک‌های سفارشی کلمه در نظر گرفته شده است\&. برای مقایسه، ابزارک‌های شرح‌داده‌شده در \fIzshzle\fP(1) زیر عنوان Text Objects از تعاریف ثابتی برای کلمات استفاده می‌کنند که با ویرایشگر \fBvim\fP سازگار است\&.
.RS
.PP
ساده‌ترین روش برای پیکربندی توابع، استفاده از \fBselect\-word\-style\fP است که می‌تواند یا به عنوان یک تابع عادی با آرگومان مناسب فراخوانی شود، یا به عنوان یک ابزارک تعریف‌شده توسط کاربر اجرا گردد که نویسهٔ اول سبک کلمهٔ مورد استفاده را درخواست می‌کند\&. نخستین باری که فراخوانی می‌شود، هشت تابع نخست \fB\-match\fP به طور خودکار جایگزین نسخه‌های توکار می‌شوند، بنابراین نیازی به بارگذاری صریح آن‌ها نیست\&.
.PP
سبک‌های کلمهٔ در دسترس به شرح زیر هستند\&. فقط نخستین نویسه بررسی می‌شود\&.
.PP
.PD 0
.TP
.PD
\fBbash\fP
نویسه‌های کلمه فقط نویسه‌های حرفی‌عددی هستند\&.
.TP
\fBnormal\fP
مانند عملکرد عادی شل: نویسه‌های کلمه نویسه‌های حرفی‌عددی به علاوهٔ هر نویسهٔ موجود در رشتهٔ تعیین‌شده توسط پارامتر \fB$WORDCHARS\fP هستند\&.
.TP
\fBshell\fP
کلمات همان آرگومان‌های کامل دستور شل هستند، که احتمالاً شامل رشته‌های نقل‌قول‌شدهٔ کامل، یا هر نشانهٔ (token) ویژهٔ شل می‌شوند\&.
.TP
\fBwhitespace\fP
کلمات هر مجموعه‌ای از نویسه‌ها هستند که با فاصلهٔ سفید (whitespace) از یکدیگر جدا شده‌اند\&.
.TP
\fBdefault\fP
تنظیمات پیش‌فرض را بازیابی می‌کند؛ این حالت معمولاً همانند `\fBnormal\fP\&' است\&.
.PP
همه به جز `\fBdefault\fP\&' می‌توانند با یک نویسهٔ بزرگ (upper case) وارد شوند، که همان اثر را دارد اما تطبیق زیرکلمه (subword matching) در آن فعال است\&. در این حالت، با کلماتی که دارای حروف بزرگ هستند به صورت ویژه‌ای رفتار می‌شود: هر توالی جداگانه از حروف بزرگ، یا یک نویسهٔ بزرگ که به دنبال آن هر تعداد از نویسه‌های دیگر بیاید، یک کلمه در نظر گرفته می‌شود\&. سبک \fBsubword\-range\fP می‌تواند یک محدودهٔ نویسهٔ جایگزین برای پیش‌فرض `\fB[:upper:]\fP\&' ارائه دهد؛ مقدار این سبک به عنوان محتویات یک الگوی `\fB[\fP\fI\&.\&.\&.\fP\fB]\fP\&' در نظر گرفته می‌شود (توجه داشته باشید که قلاب‌های بیرونی نباید داده شوند، فقط قلاب‌های احاطه‌کنندهٔ محدوده‌های نام‌گذاری‌شده مورد نیاز هستند)\&.
.PP
کنترل دقیق‌تر را می‌توان با استفاده از دستور \fBzstyle\fP، همان‌طور که در \fIzshmodules\fP(1) شرح داده شده است، به دست آورد\&. هر سبک در بافتار (context) \fB:zle:\fP\fIwidget\fP جستجو می‌شود که در آن \fIwidget\fP نام ابزارک تعریف‌شده توسط کاربر است، نه نام تابعی که آن را پیاده‌سازی می‌کند؛ بنابراین در مورد تعاریف ارائه‌شده توسط \fBselect\-word\-style\fP، بافتارهای مناسب \fB:zle:forward\-word\fP و غیره هستند\&. خود تابع \fBselect\-word\-style\fP همواره سبک‌هایی را برای بافتار `\fB:zle:*\fP\&' تعریف می‌کند که می‌توان آن‌ها را با الگوهای خاص‌تر (طولانی‌تر) و همچنین بافتارهای صریح بازنویسی کرد\&.
.PP
سبک \fBword\-style\fP قواعد مورد استفاده را مشخص می‌کند\&. این سبک می‌تواند مقادیر زیر را داشته باشد\&.
.PP
.PD 0
.TP
.PD
\fBnormal\fP
استفاده از قواعد استاندارد شل، یعنی نویسه‌های حرفی‌عددی و \fB$WORDCHARS\fP، مگر اینکه توسط سبک‌های \fBword\-chars\fP یا \fBword\-class\fP بازنویسی شود\&.
.TP
\fBspecified\fP
مشابه \fBnormal\fP، اما \fIتنها\fP نویسه‌های مشخص‌شده نویسهٔ کلمه در نظر گرفته می‌شوند، و نه نویسه‌های حرفی‌عددی\&.
.TP
\fBunspecified\fP
نقیض specified\&. نویسه‌های داده‌شده آن‌هایی هستند که بخشی از یک کلمه در نظر گرفته \fIنمی‌شوند\fP\&.
.TP
\fBshell\fP
کلمات با استفاده از قواعد نحوی برای ایجاد آرگومان‌های دستور شل به دست می‌آیند\&. علاوه بر این، نشانه‌های ویژه‌ای که هرگز آرگومان دستور نیستند مانند `\fB()\fP\&' نیز به عنوان کلمه در نظر گرفته می‌شوند\&.
.TP
\fBwhitespace\fP
کلمات رشته‌هایی از نویسه‌ها هستند که با فاصلهٔ سفید از یکدیگر جدا شده‌اند\&.
.PP
سه قاعدهٔ نخست معمولاً از \fB$WORDCHARS\fP استفاده می‌کنند، اما مقدار درون پارامتر می‌تواند با سبک \fBword\-chars\fP بازنویسی شود که دقیقاً به همان روش \fB$WORDCHARS\fP کار می‌کند\&. علاوه بر این، سبک \fBword\-class\fP از نحو ردهٔ نویسه (character class) برای گروه‌بندی نویسه‌ها استفاده می‌کند و در صورت تنظیم هر دو، بر \fBword\-chars\fP اولویت دارد\&. سبک \fBword\-class\fP شامل قلاب‌های احاطه‌کنندهٔ ردهٔ نویسه نمی‌شود؛ برای نمونه، `\fB\-:[:alnum:]\fP\&' یک \fBword\-class\fP معتبر است برای در بر گرفتن تمام نویسه‌های حرفی‌عددی به علاوهٔ نویسه‌های `\fB\-\fP\&' و `\fB:\fP'\&. در گنجاندن `\fB]\fP\&'، `\fB^\fP' و `\fB\-\fP' دقت کنید زیرا این موارد در داخل رده‌های نویسه ویژه هستند\&.
.PP
سبک \fBword\-style\fP همچنین می‌تواند `\fB\-subword\fP\&' را به انتهای مقدار خود ضمیمه داشته باشد تا همان‌طور که در بالا توضیح داده شد، تطبیق زیرکلمه فعال شود\&.
.PP
سبک \fBskip\-chars\fP بیشتر برای \fBtranspose\-words\fP و توابع مشابه سودمند است\&. در صورت تنظیم، این سبک تعداد نویسه‌هایی را مشخص می‌کند که با شروع از موقعیت مکان‌نما، صرف‌نظر از این که در واقع چه هستند، بخشی از کلمه محسوب نشده و مانند فاصله با آن‌ها برخورد می‌شود\&. برای نمونه، اگر
.PP
.RS
.nf
\fBzstyle \&':zle:transpose\-words' skip\-chars 1\fP
.fi
.RE
.PP
تنظیم شده باشد و \fBtranspose\-words\-match\fP در حالی فراخوانی شود که مکان‌نما روی \fIX\fP از \fBfoo\fP\fIX\fP\fBbar\fP قرار دارد (که در آن \fIX\fP می‌تواند هر نویسه‌ای باشد)، عبارت حاصل \fBbar\fP\fIX\fP\fBfoo\fP خواهد بود\&.
.PP
کنترل دقیق‌تر را می‌توان با تنظیم سبک \fBword\-context\fP به آرایه‌ای از جفت‌های ورودی به دست آورد\&. هر جفت ورودی شامل یک \fIpattern\fP (الگو) و یک \fIsubcontext\fP (زیربافتار) است\&. آرگومان شلی که مکان‌نما روی آن قرار دارد به نوبت با هر \fIpattern\fP مطابقت داده می‌شود تا زمانی که یکی مطابقت یابد؛ در صورت تطابق، بافتار با یک دونقطه (colon) و \fIsubcontext\fP متناظر گسترش می‌یابد\&. توجه داشته باشید که این بررسی بر روی کلمهٔ اصلی در خط و بدون حذف نقل‌قول‌ها صورت می‌گیرد\&. میان کلمات مدیریت ویژه‌ای انجام می‌شود: بافتار جاری بررسی می‌گردد و اگر حاوی رشتهٔ \fBbetween\fP باشد، کلمه روی یک فاصلهٔ تکی تنظیم می‌شود؛ در غیر این صورت اگر حاوی رشتهٔ \fBback\fP باشد، کلمهٔ قبل از مکان‌نما در نظر گرفته می‌شود، در غیر این صورت کلمهٔ بعد از مکان‌نما در نظر گرفته خواهد شد\&. چند نمونه در ادامه آورده شده است\&..PP
سبک \fBskip\-whitespace\-first\fP فقط همراه با ویجت \fBforward\-word\fP استفاده می‌شود\&. اگر روی \fBtrue\fP تنظیم شود، آن‌گاه \fBforward\-word\fP از هر نویسهٔ غیرکلمه‌ای، و در ادامه از هر نویسهٔ غیرکلمه‌ایِ پس از آن می‌گذرد: این شبیه به رفتار دیگر ویجت‌های مبتنی بر کلمه و همچنین رفتار ویرایشگرهای دیگر است، اما با رفتار استاندارد zsh تفاوت دارد\&. هنگام استفاده از \fBselect\-word\-style\fP، اگر سبک کلمه \fBbash\fP باشد این ویجت در بافتار \fB:zle:*\fP روی \fBtrue\fP و در غیر این صورت روی \fBfalse\fP تنظیم می‌شود\&. با تنظیم آن در بافتار خاص‌ترِ \fB:zle:forward\-word*\fP می‌توان مقدار آن را لغو (override) کرد\&.
.PP
ایجاد ویجت‌هایی با رفتار خاص از طریق تعریف یک ویجت جدید که با تابع عمومی مناسب پیاده‌سازی شده، و سپس تعیین سبک برای بافتار آن ویجت خاص امکان‌پذیر است\&. برای نمونه، دستورات زیر یک ویجت \fBbackward\-kill\-space\-word\fP را با استفاده از \fBbackward\-kill\-word\-match\fP (ویجت عمومیِ پیاده‌سازی‌کنندهٔ رفتار \fBbackward\-kill\-word\fP) تعریف کرده و تضمین می‌کند که ویجت جدید همواره رفتارِ جداشده با فاصله (space\-delimited) را پیاده‌سازی نماید\&.
.PP
.RS
.nf
\fBzle \-N backward\-kill\-space\-word backward\-kill\-word\-match
zstyle :zle:backward\-kill\-space\-word word\-style space\fP
.fi
.RE
.PP
اکنون می‌توان ویجت \fBbackward\-kill\-space\-word\fP را به یک کلید مقید (bind) کرد\&.
.PP
در ادامه چند مثال دیگر از نحوهٔ استفاده از سبک‌ها آمده است که در واقع از رابط کاربری ساده‌شده در \fBselect\-word\-style\fP برگرفته شده‌اند:
.PP
.RS
.nf
\fBzstyle \&':zle:*' word\-style standard
zstyle \&':zle:*' word\-chars ''\fP
.fi
.RE
.PP
مدیریت کلمه به سبک bash را برای همهٔ ویجت‌ها پیاده‌سازی می‌کند، یعنی فقط نویسه‌های الفبایی‌عددی نویسهٔ کلمه محسوب می‌شوند؛ معادل خالی تنظیم کردن پارامتر \fBWORDCHARS\fP برای بافتار مربوطه\&.
.PP
.RS
.nf
\fBstyle \&':zle:*kill*' word\-style space\fP
.fi
.RE
.PP
برای ویجت‌هایی که واژهٔ «kill» در نامشان وجود دارد، از کلمات جداشده با فاصله استفاده می‌کند\&. در این حالت هیچ‌یک از سبک‌های \fBword\-chars\fP یا \fBword\-class\fP استفاده نمی‌شوند\&.
.PP
در اینجا چند مثال از استفاده از سبک \fBword\-context\fP برای بسط دادن بافتار آمده است\&.
.PP
.RS
.nf
\fBzstyle \&':zle:*' word\-context \e 
       "*/*" filename "[[:space:]]" whitespace
zstyle \&':zle:transpose\-words:whitespace' word\-style shell
zstyle \&':zle:transpose\-words:filename' word\-style normal
zstyle \&':zle:transpose\-words:filename' word\-chars ''\fP
.fi
.RE
.PP
این پیکربندی بسته به اینکه مکان‌نما روی فاصلهٔ خالی میان کلمات باشد یا روی نام یک فایل (در اینجا هر کلمه‌ای که دارای \fB/\fP باشد)، دو شیوهٔ مختلف را برای استفاده از \fBtranspose\-words\fP فراهم می‌کند\&. روی فاصلهٔ خالی، آرگومان‌های کامل آن‌گونه که طبق قوانین استاندارد پوسته تعریف شده‌اند جابه‌جا می‌شوند\&. در یک نام فایل، فقط نویسه‌های الفبایی‌عددی جابه‌جا خواهند شد\&. در جاهای دیگر، کلمات با استفاده از سبک پیش‌فرضِ \fB:zle:transpose\-words\fP جابه‌جا می‌شوند\&.
.PP
تطبیق کلمات و تمامی فرایندهای مدیریت تنظیمات \fBzstyle\fP در واقع توسط تابع \fBmatch\-words\-by\-style\fP پیاده‌سازی شده است\&. این تابع می‌تواند برای ساخت ویجت‌های سفارشیِ جدید توسط کاربر استفاده شود\&. تابع فراخواننده باید پارامتر محلی \fBcurcontext\fP را روی \fB:zle:\fP\fIwidget\fP تنظیم کرده، پارامتر محلی \fBmatched_words\fP را ایجاد نماید و تابع \fBmatch\-words\-by\-style\fP را بدون هیچ آرگومانی فراخوانی کند\&. در هنگام بازگشت، \fBmatched_words\fP به آرایه‌ای با این عناصر مقداردهی می‌شود: (۱) ابتدای خط (۲) کلمهٔ قبل از مکان‌نما (۳) هر نویسهٔ غیرکلمه‌ایِ بین آن کلمه و مکان‌نما (۴) هر نویسهٔ غیرکلمه‌ای در موقعیت مکان‌نما به همراه نویسه‌های غیرکلمه‌ایِ باقی‌مانده پیش از کلمهٔ بعدی، شامل تمام نویسه‌های مشخص‌شده توسط سبک \fBskip\-chars\fP، (۵) کلمهٔ روی مکان‌نما یا پس از آن (۶) هر نویسهٔ غیرکلمه‌ای پس از آن کلمه (۷) باقی‌ماندهٔ خط\&. هر یک از این عناصر می‌تواند یک رشتهٔ خالی باشد؛ تابع فراخواننده باید این موضوع را بررسی کند تا تعیین نماید که آیا قادر به اجرای عملکرد خود هست یا خیر\&.
.PP
اگر متغیر \fBmatched_words\fP توسط فراخوانندهٔ \fBmatch\-words\-by\-style\fP به صورت یک آرایهٔ انجمنی (\fBlocal \-A matched_words\fP) تعریف شده باشد، آن‌گاه مقادیر هفت‌گانهٔ ارائه‌شده در بالا باید به عنوان عناصری با نام‌های \fBstart\fP، \fBword\-before\-cursor\fP، \fBws\-before\-cursor\fP، \fBws\-after\-cursor\fP، \fBword\-after\-cursor\fP، \fBws\-after\-word\fP و \fBend\fP از آن استخراج شوند\&. علاوه بر این، چنانچه مکان‌نما در آغاز یک کلمه یا زیرکلمه باشد، یا روی فاصلهٔ خالی پیش از آن قرار گرفته باشد (این دو حالت با بررسی عنصر \fBws\-after\-cursor\fP قابل تفکیک هستند)، مقدار عنصر \fBis\-word\-start\fP برابر ۱ و در غیر این صورت ۰ خواهد بود\&. این شیوه برای حفظ سازگاری در آینده پیشنهاد می‌شود\&.
.PP
امکان ارسال گزینه‌ها به همراه آرگومان به \fBmatch\-words\-by\-style\fP جهت بازنویسی و لغو استفاده از سبک‌ها وجود دارد\&. این گزینه‌ها عبارتند از:
.PD 0
.TP
\fB\-w\fP
\fIword\-style\fP
.TP
\fB\-s\fP
\fIskip\-chars\fP
.TP
\fB\-c\fP
\fIword\-class\fP
.TP
\fB\-C\fP
\fIword\-chars\fP
.TP
\fB\-r\fP
\fIsubword\-range\fP
.PD
.PP
برای مثال، می‌توان از دستور \fBmatch\-words\-by\-style \-w shell \-c 0\fP برای استخراج آرگومان دستوریِ پیرامون مکان‌نما استفاده کرد\&.
.PP
سبک \fBword\-context\fP توسط تابع \fBmatch\-word\-context\fP پیاده‌سازی شده است\&. معمولاً نیازی نیست که این تابع مستقیماً فراخوانی شود\&.
.RE
.TP
\fBbracketed\-paste\-magic\fP
ویجت \fBbracketed\-paste\fP (به زیربخش «Miscellaneous» در \fIzshzle\fP(1) مراجعه کنید) متن چسبانده‌شده را به جای تفسیر به عنوان ورودی‌های صفحه‌کلید، به صورت لفظی در بافر ویرایشگر درج می‌کند\&. این امر برخی کاربردهای متداول را که در آن‌ها ویجت \fBself\-insert\fP برای اعمال پردازش‌های بیشتر جایگزین شده است غیرفعال می‌سازد\&. یک نمونه از آن، ویجت الحاقی \fBurl\-quote\-magic\fP است که در زیر شرح داده شده است\&.
.RS
.PP
ویجت \fBbracketed\-paste\-magic\fP با این هدف طراحی شده است که \fBbracketed\-paste\fP را با یک پوشش‌دهنده (wrapper) جایگزین کند که این عملیات‌های self\-insert و دیگر اقدامات تعیین‌شده توسط zstyleها را مجدداً فعال می‌سازد\&. از این رو این ویجت با دستور زیر راه‌اندازی می‌شود:

.RS
.nf
\fBautoload \-Uz bracketed\-paste\-magic
zle \-N bracketed\-paste bracketed\-paste\-magic\fP
.fi
.RE
.PP
به جز فعال کردن پردازشِ برخی ویجت‌ها، \fBbracketed\-paste\-magic\fP سعی می‌کند عملکرد \fBbracketed\-paste\fP را تا جای ممکن به شکلی دقیق و وفادارانه بازتولید کند\&.
.PP
سبک‌های zstyle زیر را می‌توان برای کنترل پردازش متن چسبانده‌شده تنظیم کرد\&. همهٔ آن‌ها در بافتار «\fB:bracketed\-paste\-magic\fP» جستجو می‌شوند\&.
.PP
.PD 0
.TP
.PD
\fBactive\-widgets\fP
فهرستی از الگوهای منطبق بر نام‌های ویجت‌هایی است که باید در زمان چسباندن متن فعال شوند\&. تمام دنباله‌های کلید دیگر به صورت \fBself\-insert\-unmeta\fP پردازش می‌شوند\&. مقدار پیش‌فرض «\fBself\-*\fP» است، از این رو هر ویجت سفارشیِ تعریف‌شده با این پیشوند در کنار ویجت توکار \fBself\-insert\fP فعال خواهد بود\&.
.RS
.PP
اگر این سبک تنظیم نشود (به‌طور صریح حذف گردد) یا مقداری خالی به آن اختصاص یابد، هیچ ویجتی فعال نخواهد بود و متنِ چسبانده‌شده به صورت لفظی درج می‌شود\&. اگر مقدار آن شامل «\fBundefined\-key\fP» باشد، هر دنبالهٔ ناشناخته از متن چسبانده‌شده حذف و نادیده گرفته می‌شود\&.
.RE
.TP
\fBinactive\-keys\fP
نقطهٔ مقابل \fBactive\-widgets\fP؛ فهرستی از دنباله‌های کلید است که همواره از \fBself\-insert\-unmeta\fP استفاده می‌کنند، حتی اگر به یک ویجت فعال مقید شده باشند\&. توجه داشته باشید که این مورد فهرستی از دنباله‌های کلید لفظی (عینی) است، نه الگوها\&.
.TP
\fBpaste\-init\fP
فهرستی از نام توابع است که در بافتار ویجت (اما نه به عنوان ویجت) فراخوانی می‌شوند\&. توابع به ترتیب فراخوانی می‌شوند تا زمانی که یکی از آن‌ها وضعیت خروجی غیرصفر برگرداند\&. پارامتر «\fBPASTED\fP» حاوی وضعیت اولیهٔ متن چسبانده‌شده است\&. تمام پارامترهای دیگر ZLE نظیر «\fBBUFFER\fP» مقادیر و اثرات جانبی عادی خود را دارند و تاریخچهٔ کامل در دسترس است؛ بنابراین برای مثال توابع \fBpaste\-init\fP می‌توانند کلماتی را از \fBBUFFER\fP به \fBPASTED\fP انتقال دهند تا آن کلمات برای \fBactive\-widgets\fP قابل مشاهده باشند\&.
.RS.PP
بازگشت مقداری غیرصفر از یک تابع \fBpaste\-init\fP مانع از انجام خود عملیات جای‌گذاری \fIنمی‌شود\fP\&.
.PP
بارگذاری \fBbracketed\-paste\-magic\fP تابع کمکی \fBbackward\-extend\-paste\fP را برای استفاده در \fBpaste\-init\fP تعریف می‌کند\&.
.PP
.RS
.nf
\fBzstyle :bracketed\-paste\-magic paste\-init \e 
       backward\-extend\-paste\fP
.fi
.RE
.PP
هنگامی که یک جای‌گذاری در میانه‌ی یک کلمه درج شود یا متنی را به کلمه‌ای که از پیش روی خط وجود دارد اضافه کند، \fBbackward\-extend\-paste\fP پیشوند را از \fBLBUFFER\fP به \fBPASTED\fP منتقل می‌کند تا \fBactive\-widgets\fP کل کلمه را تا آن نقطه ببینند\&. این قابلیت می‌تواند با \fBurl\-quote\-magic\fP مفید باشد\&.
.RE
.TP
\fBpaste\-finish\fP
فهرست دیگری از نام‌های توابع که به ترتیب فراخوانی می‌شوند تا زمانی که یکی از آن‌ها مقداری غیرصفر بازگرداند\&.
این توابع \fIپس از\fP پردازش متن جای‌گذاری‌شده توسط \fBactive\-widgets\fP، اما \fIپیش از\fP درج آن در `\fBBUFFER\fP\&' فراخوانی می‌شوند\&.
پارامترهای ZLE مقادیر و اثرات جانبی معمول خود را دارند\&.
.RS
.PP
بازگشت مقداری غیرصفر از یک تابع \fBpaste\-finish\fP مانع از انجام خود عملیات جای‌گذاری \fIنمی‌شود\fP\&.
.PP
بارگذاری \fBbracketed\-paste\-magic\fP همچنین تابع کمکی \fBquote\-paste\fP را برای استفاده در \fBpaste\-finish\fP تعریف می‌کند\&.
.PP
.RS
.nf
\fBzstyle :bracketed\-paste\-magic paste\-finish \e 
       quote\-paste
zstyle :bracketed\-paste\-magic:finish quote\-style \e 
       qqq\fP
.fi
.RE
.PP
هنگامی که متن جای‌گذاری‌شده در \fBBUFFER\fP درج می‌شود، مطابق با مقدار \fBquote\-style\fP نقل‌قول‌بندی می‌شود\&. برای غیرفعال کردن اجباری نقل‌قول‌بندی پیشوند عددی توکارِ \fBbracketed\-paste\fP، از دستور زیر استفاده کنید:
.PP
.RS
.nf
\fBzstyle :bracketed\-paste\-magic:finish quote\-style \e 
       none\fP
.fi
.RE
.RE
.PP
\fIمهم:\fP در حین پردازش جای‌گذاری توسط \fBactive\-widgets\fP (پس از \fBpaste\-init\fP و پیش از \fBpaste\-finish\fP)، \fBBUFFER\fP در ابتدا خالی است و تاریخچه محدود می‌گردد، بنابراین حرکات مکان‌نما و موارد مشابه ممکن است به خارج از محتوای جای‌گذاری‌شده نروند\&. متنی که توسط ویجت‌های فعال به \fBBUFFER\fP اختصاص داده می‌شود، پیش از \fBpaste\-finish\fP دوباره درون \fBPASTED\fP کپی می‌شود\&.
.RE
.TP
\fBcopy\-earlier\-word\fP
این ویجت مانند ترکیبی از \fBinsert\-last\-word\fP و \fBcopy\-prev\-shell\-word\fP عمل می‌کند\&. فراخوانی‌های مکرر این ویجت کلمات پیشین را در خط تاریخچه‌ی مربوطه بازیابی می‌کند\&. با یک آرگومان عددی \fIN\fP، کلمه‌ی \fIN\fPام از خط تاریخچه درج می‌شود؛ \fIN\fP می‌تواند منفی باشد تا شمارش از انتهای خط انجام گیرد\&.
.RS
.PP
اگر از \fBinsert\-last\-word\fP برای بازیابی آخرین کلمه‌ی یک خط تاریخچه‌ی قبلی استفاده شده باشد، فراخوانی‌های مکرر آن کلمه را با کلمات پیشین از همان خط جایگزین می‌کند\&.
.PP
در غیر این صورت، ویجت بر روی کلمات خطی که در حال حاضر ویرایش می‌شود اعمال می‌گردد\&. سبک \fBwidget\fP را می‌توان روی نام ویجت دیگری تنظیم کرد که باید برای بازیابی کلمات فراخوانی شود\&. این ویجت باید همان سه آرگومان \fBinsert\-last\-word\fP را بپذیرد\&.
.RE
.TP
\fBcycle\-completion\-positions\fP
پس از درج یک رشته‌ی بدون ابهام در خط فرمان، سامانه‌ی جدید کامل‌سازی مبتنی بر تابع ممکن است چندین نقطه در این رشته را شناسایی کند که نویسه‌ها در آن‌ها جا افتاده‌اند یا دست‌کم با یکی از تطابق‌های ممکن تفاوت دارند\&. سپس مکان‌نما در موقعیتی قرار می‌گیرد که جالب‌ترین موقعیت به شمار می‌رود، یعنی موقعیتی که در آن می‌توان با کمترین میزان تایپ، بین بیشترین تطابق‌های ممکن رفع ابهام کرد\&.
.RS
.PP
این ویجت اجازه می‌دهد که مکان‌نما به آسانی به سایر نقاط مهم جابه‌جا شود\&. می‌توان آن را مکرراً فراخوانی کرد تا میان تمام موقعیت‌های گزارش‌شده توسط سامانه‌ی کامل‌سازی چرخش انجام گیرد\&.
.RE
.TP
\fBdelete\-whole\-word\-match\fP
این تابع دیگری است که مانند توابع \fB\-match\fP که پیش‌تر توضیح داده شد عمل می‌کند، یعنی از سبک‌ها برای تعیین مرزهای کلمه استفاده می‌کند\&. با این حال، جایگزینی برای هیچ تابع موجودی نیست\&.
.RS
.PP
رفتار پایه‌ای آن حذف کلمه‌ی پیرامون مکان‌نما است\&. هیچ پردازشی روی آرگومان عددی وجود ندارد؛ تنها همان تک‌کلمه‌ی اطراف مکان‌نما در نظر گرفته می‌شود\&. اگر ویجت شامل رشته‌ی \fBkill\fP باشد، متن حذف‌شده برای بازگردانی (yank) بعدی در cutbuffer قرار می‌گیرد\&. این رفتار را می‌توان با تعریف \fBkill\-whole\-word\-match\fP به صورت زیر پیاده کرد:
.PP
.RS
.nf
\fBzle \-N kill\-whole\-word\-match delete\-whole\-word\-match\fP
.fi
.RE
.PP
و سپس مقیدسازی ویجت \fBkill\-whole\-word\-match\fP\&.
.RE
.TP
\fBup\-line\-or\-beginning\-search\fP, \fBdown\-line\-or\-beginning\-search\fP
این ویجت‌ها مشابه توابع توکار \fBup\-line\-or\-search\fP و \fBdown\-line\-or\-search\fP هستند: اگر در یک بافر چندخطی باشند به بالا یا پایین در بافر حرکت می‌کنند، در غیر این صورت به دنبال خطی از تاریخچه می‌گردند که با ابتدای خط جاری مطابقت داشته باشد\&. با این حال در این مورد، آن‌ها به جای نخستین کلمه‌ی خط، همانند \fBhistory\-beginning\-search\-backward\fP و \fB\-forward\fP به دنبال خطی می‌گردند که با خط جاری تا موقعیت فعلی مکان‌نما مطابقت داشته باشد\&.
.TP
\fBedit\-command\-line\fP
ویرایش خط فرمان با استفاده از ویرایشگر بصری، همانند \fBksh\fP\&.
.RS
.PP
.RS
.nf
\fBbindkey \-M vicmd v edit\-command\-line\fP
.fi
.RE
.PP
ویرایشگری که باید استفاده شود را نیز می‌توان با استفاده از سبک \fBeditor\fP در بافتار ویجت مشخص کرد\&. این ویرایشگر به عنوان آرایه‌ای از دستور و آرگومان‌ها مشخص می‌شود:
.PP
.RS
.nf
\fBzstyle :zle:edit\-command\-line editor gvim \-f\fP
.fi
.RE
.RE
.TP
\fBexpand\-absolute\-path\fP
گسترش نام فایل زیر مکان‌نما به یک مسیر مطلق، به همراه حل پیوندهای نمادین\&. در صورت امکان، بخش آغازین مسیر به یک دایرکتوری نام‌گذاری‌شده یا ارجاعی به دایرکتوری خانگی کاربر تبدیل می‌شود\&.
.TP
\fBhistory\-search\-end\fP
این تابع ویجت‌های \fBhistory\-beginning\-search\-backward\-end\fP و \fBhistory\-beginning\-search\-forward\-end\fP را پیاده‌سازی می‌کند\&. این دستورها ابتدا با فراخوانی ویجت توکار متناظر (بخش `History Control\&' در \fIzshzle\fP(1) را ببینید) و سپس جابه‌جا کردن مکان‌نما به انتهای خط عمل می‌کنند\&. موقعیت اولیه‌ی مکان‌نما به خاطر سپرده شده و پیش از فراخوانی مجدد ویجت توکار بازگردانی می‌شود، تا همان جستجو برای پیمایش بیشتر در تاریخچه تکرار شود\&.
.RS
.PP
اگرچه تنها یک تابع را \fBautoload\fP می‌کنید، اما دستورهای استفاده از آن کمی متفاوت هستند چرا که دو ویجت را پیاده‌سازی می‌کند\&.
.PP
.RS
.nf
\fBzle \-N history\-beginning\-search\-backward\-end \e 
       history\-search\-end
zle \-N history\-beginning\-search\-forward\-end \e 
       history\-search\-end
bindkey \&'\ee^P' history\-beginning\-search\-backward\-end
bindkey \&'\ee^N' history\-beginning\-search\-forward\-end\fP
.fi
.RE
.RE
.TP
\fBhistory\-beginning\-search\-menu\fP
این تابع شکل دیگری از جستجوی تاریخچه را پیاده‌سازی می‌کند\&. متن پیش از مکان‌نما برای انتخاب خطوط از تاریخچه استفاده می‌شود، همانند \fBhistory\-beginning\-search\-backward\fP با این تفاوت که همه‌ی تطابق‌ها در یک منوی شماره‌دار نمایش داده می‌شوند\&. با فشردن ارقام مربوطه، کل خط تاریخچه درج می‌گردد\&. توجه داشته باشید که صفرهای آغازین حتماً باید تایپ شوند (آن‌ها تنها در صورت لزوم برای رفع ابهام نمایش داده می‌شوند)\&. تمام تاریخچه جستجو می‌شود؛ هیچ تمایزی میان جستجو به سمت جلو یا عقب وجود ندارد\&.
.RS.PP
با یک آرگومان عددی، جستجو به ابتدای خط مقید نمی‌شود؛ رشته تایپ‌شده
توسط کاربر ممکن است در هر کجای خط در تاریخچه ظاهر شود\&.
.PP
اگر نام ویجت شامل `\fB\-end\fP\&' باشد، مکان‌نما به انتهای خط
درج‌شده منتقل می‌شود\&. اگر نام ویجت شامل `\fB\-space\fP\&' باشد، هر فاصله‌ای
در متن تایپ‌شده به عنوان یک نویسه عمومی (wildcard) در نظر گرفته می‌شود و می‌تواند با هر چیزی
تطابق یابد (از این رو وجود یک فاصله در ابتدا معادل دادن یک آرگومان عددی است)\&. هر دو
فرم را می‌توان ترکیب کرد، برای مثال:
.PP
.RS
.nf
\fBzle \-N history\-beginning\-search\-menu\-space\-end \e 
       history\-beginning\-search\-menu\fP
.fi
.RE
.RE
.TP
\fBhistory\-pattern\-search\fP
تابع \fBhistory\-pattern\-search\fP ویجت‌هایی را پیاده‌سازی می‌کند که
الگویی را برای جستجوی تاریخچه به سمت عقب یا جلو درخواست می‌کنند\&. الگو
در قالب معمول zsh است، با این حال نویسه اول می‌تواند
\fB^\fP باشد تا جستجو را به ابتدای خط مقید سازد، و نویسه آخر
می‌تواند \fB$\fP باشد تا جستجو را به انتهای خط مقید کند\&. اگر
جستجو به انتهای خط مقید نشده باشد، مکان‌نما درست پس از الگوی
یافت‌شده قرار می‌گیرد\&.
.RS
.PP
دستورهای ایجاد ویجت‌های قابل انتساب مشابه موارد موجود در مثال
دقیقاً بالا هستند:
.PP
.RS
.nf
\fBautoload \-U history\-pattern\-search
zle \-N history\-pattern\-search\-backward history\-pattern\-search
zle \-N history\-pattern\-search\-forward history\-pattern\-search\fP
.fi
.RE
.RE
.TP
\fBincarg\fP
تایپ کلیدهای این ویجت در حالی که مکان‌نما روی یک عدد صحیح یا در سمت چپ آن
قرار دارد، باعث می‌شود آن عدد صحیح یک واحد افزایش یابد\&. با یک
آرگومان عددی، عدد به میزان مقدار آرگومان افزایش می‌یابد
(و در صورتی که آرگومان عددی منفی باشد، کاهش می‌یابد)\&. پارامتر پوسته
\fBincarg\fP را می‌توان برای تغییر مقدار افزایش پیش‌فرض به مقداری غیر
از یک تنظیم کرد\&.
.RS
.PP
.RS
.nf
\fBbindkey \&'^X+' incarg\fP
.fi
.RE
.RE
.TP
\fBincremental\-complete\-word\fP
این ویژگی امکان تکمیل افزایشی یک کلمه را فراهم می‌کند\&. پس از شروع این
دستور، پس از هر نویسه‌ای که تایپ می‌کنید فهرستی از گزینه‌های تکمیل می‌تواند
نمایش داده شود که می‌توانید آن را با \fB^H\fP یا \fBDEL\fP حذف کنید\&. فشردن return
تکمیل انجام‌شده تا این لحظه را می‌پذیرد و شما را به ویرایش عادی بازمی‌گرداند (یعنی
خط فرمان بلافاصله اجرا \fIنمی‌شود\fP)\&. می‌توانید \fBTAB\fP را برای تکمیل عادی،
\fB^G\fP را برای لغو و بازگشت به وضعیت زمان شروع،
و \fB^D\fP را برای فهرست کردن تطابق‌ها بزنید\&.
.RS
.PP
این ویژگی تنها با سیستم جدید تکمیل مبتنی بر تابع کار می‌کند\&.
.PP
.RS
.nf
\fBbindkey \&'^Xi' incremental\-complete\-word\fP
.fi
.RE
.RE
.TP
\fBinsert\-composed\-char\fP
این تابع به شما اجازه می‌دهد نویسه‌هایی را که روی صفحه‌کلید وجود ندارند
ترکیب کرده و در خط فرمان درج کنید\&. پس از این دستور، دو کلید متناظر با
نویسه‌های ASCII وارد می‌شود (هیچ خط اعلانی وجود ندارد)\&. برای نویسه‌های
اعراب‌دار، این دو کلید عبارتند از یک نویسه پایه و به دنبال آن یک کد برای حرکت،
در حالی که برای سایر نویسه‌های خاص، این دو نویسه با هم یک نماد اختصاری
(mnemonic) را برای نویسه‌ای که باید درج شود تشکیل می‌دهند\&. کدهای
دو\-نویسه‌ای زیرمجموعه‌ای از کدهای ارائه‌شده توسط RFC 1345 هستند (برای مثال
ببینید: \fBhttp://www\&.faqs\&.org/rfcs/rfc1345\&.html\fP)\&.
.RS
.PP
این تابع می‌تواند به صورت اختیاری با حداکثر دو نویسه دنبال شود که
جایگزین یک یا هر دو نویسه خوانده‌شده از صفحه‌کلید می‌شوند؛ اگر هر دو
نویسه ارائه شوند، هیچ ورودی‌ای خوانده نمی‌شود\&. برای مثال،
\fBinsert\-composed\-char a:\fP می‌تواند درون یک ویجت برای درج یک a با
اوملاوت در خط فرمان استفاده شود\&. این روش نسبت به استفاده از نویسه
تحت‌اللفظی این مزیت را دارد که سازگارتر و قابل‌حمل‌تر است\&.
.PP
برای بهترین نتیجه، zsh باید با پشتیبانی از نویسه‌های چندبایتی ساخته شده باشد
(پیکربندی‌شده با \fB\-\-enable\-multibyte\fP)؛ با این حال، این تابع برای
دامنه محدودی از نویسه‌های موجود در مجموعه‌نویسه‌های تک‌بایتی مانند
ISO\-8859\-1 نیز کار می‌کند\&.
.PP
نویسه به نمایش محلی تبدیل شده و در موقعیت مکان‌نما در خط فرمان
درج می‌شود\&. (این تبدیل در داخل پوسته و با استفاده از امکانات فراهم‌شده توسط
کتابخانه C انجام می‌گیرد\&.) با یک آرگومان عددی، نویسه و کد آن در
خط وضعیت پیش‌نمایش داده می‌شوند\&.
.PP
این تابع را می‌توان خارج از zle اجرا کرد که در این صورت نویسه را
(همراه با یک خط جدید) در خروجی استاندارد چاپ می‌کند\&. ورودی همچنان از
فشردن کلیدها خوانده می‌شود\&.
.PP
برای روشی جایگزین جهت درج نویسه‌های Unicode با استفاده از شماره
نویسه شانزده‌شانزدهی (هگزادسیمال) آن‌ها، \fBinsert\-unicode\-char\fP را ببینید\&.
.PP
مجموعه نویسه‌های اعراب‌دار تا نویسه Unicode با کد U+0180 نسبتاً
کامل است، اما مجموعه نویسه‌های خاص کمتر چنین است\&. با این حال، از آن نقطه
به بعد بسیار پراکنده می‌شود\&. افزودن نویسه‌های جدید آسان است؛ تابع
\fBdefine\-composed\-chars\fP را ببینید\&. لطفاً هرگونه مورد جدید را به
\fBzsh\-workers@zsh\&.org\fP ارسال کنید\&.
.PP
کدهای نویسه دوم هنگامی که برای اعراب‌گذاری روی نویسه اول به کار می‌روند
به شرح زیر است\&. توجه داشته باشید که هر نویسه‌ای نمی‌تواند هر حرکتی را بپذیرد\&.
.PD 0
.TP
\fB!\fP
گراو (Grave)\&.
.TP
\fB\&'\fP
اکیوت (Acute)\&.
.TP
\fB>\fP
سیرکومفلکس (Circumflex)\&.
.TP
\fB?\fP
تیلده (Tilde)\&. (این نویسه \fB~\fP نیست زیرا RFC 1345 فرض نمی‌کند
که این نویسه روی صفحه‌کلید موجود باشد\&.)
.TP
\fB\-\fP
ماکرون (Macron)\&. (یک خط افقی بالای نویسه پایه)\&.
.TP
\fB(\fP
برِوْ (Breve)\&. (یک شکل پیاله‌ای کم‌عمق بالای نویسه پایه)\&.
.TP
\fB\&.\fP
نقطه بالای نویسه پایه، یا در مورد \fBi\fP بدون نقطه،
یا در مورد \fBL\fP و \fBl\fP یک نقطه مرکزی\&.
.TP
\fB:\fP
دیه‌رسیس یا اوملاوت (Diaeresis/Umlaut)\&.
.TP
\fBc\fP
سدیل (Cedilla)\&.
.TP
\fB_\fP
زیرخط، با این حال در حال حاضر هیچ نویسه زیرخط‌داری وجود ندارد\&.
.TP
\fB/\fP
خط مورب روی نویسه پایه\&.
.TP
\fB"\fP
اکیوت دوگانه (تنها روی چند حرف پشتیبانی می‌شود)\&.
.TP
\fB;\fP
اوگونک (Ogonek)\&. (یک قلاب کوچک رو به جلو در پایین سمت راست
نویسه)\&.
.TP
\fB<\fP
کارون (Caron)\&. (یک v کوچک بالای حرف)\&.
.TP
\fB0\fP
دایره بالای نویسه پایه\&.
.TP
\fB2\fP
قلاب بالای نویسه پایه\&.
.TP
\fB9\fP
شاخک (Horn) بالای نویسه پایه\&.
.PD
.PP
رایج‌ترین نویسه‌ها از الفباهای عربی، سیریلیک، یونانی و عبری
در دسترس هستند؛ برای توالی‌های مربوطه به RFC 1345 مراجعه کنید\&.
علاوه بر این، مجموعه‌ای از کدهای دوحرفی که در RFC 1345 وجود ندارند برای
نویسه‌های با عرض دوگانه متناظر با نویسه‌های ASCII از \fB!\fP
تا \fB~\fP (0x21 تا 0x7e) با قرار دادن پیشوند \fB^\fP قبل از نویسه در دسترس هستند،
برای مثال \fB^A\fP برای یک \fBA\fP با عرض دوگانه\&..PP
توالی‌های دو نویسه‌ای زیر نیز شناخته‌شده هستند\&.
.PP
.PD 0
.TP
.PD
نویسه‌های ASCII
این نویسه‌ها هم‌اکنون در بیشتر صفحه‌کلیدها موجود هستند:
.PD 0
.TP
\fB<(\fP
قلاب چپ (کروشه باز)
.TP
\fB//\fP
بک‌اسلش (ممیز وارونه)
.TP
\fB)>\fP
قلاب راست (کروشه بسته)
.TP
\fB(!\fP
ابرو چپ (آکولاد باز)
.TP
\fB!!\fP
خط عمودی (نماد پایپ)
.TP
\fB!)\fP
ابرو راست (آکولاد بسته)
.TP
\fB\&'?\fP
تیلده (مدک)
.PD
.TP
حروف ویژه
نویسه‌هایی که در گونه‌های مختلف الفبای لاتین یافت می‌شوند:
.PD 0
.TP
\fBss\fP
استزت (اس تیز یا scharfes S)
.TP
\fBD\-\fP, \fBd\-\fP
اث (Eth)
.TP
\fBTH\fP, \fBth\fP
تورن (Thorn)
.TP
\fBkk\fP
کرا (Kra)
.TP
\fB\&'n\fP
\&'n
.TP
\fBNG\fP, \fBng\fP
Ng
.TP
\fBOI\fP, \fBoi\fP
Oi
.TP
\fByr\fP
yr
.TP
\fBED\fP
اژ (ezh)
.PD
.TP
نمادهای یکای پول
.PD 0
.TP
\fBCt\fP
سنت
.TP
\fBPd\fP
پوند استرلینگ (همچنین لیر و غیره)
.TP
\fBCu\fP
نشان عمومی ارز
.TP
\fBYe\fP
ین
.TP
\fBEu\fP
یورو (توجه: در RFC 1345 موجود نیست)
.PD
.TP
نویسه‌های نشانه‌گذاری
ارجاع‌ها به نقل‌قول‌های «راست» نشان‌دهنده شکل ظاهری آن‌هاست (مانند ۹ به جای ۶)
نه کاربرد دستوری آن‌ها\&. (برای نمونه، نقل‌قول دوگانه پایین «راست»
برای باز کردن نقل‌قول در زبان آلمانی به کار می‌رود\&.)
.PD 0
.TP
\fB!I\fP
علامت تعجب وارونه
.TP
\fBBB\fP
خط عمودی شکسته
.TP
\fBSE\fP
بخش (Section)
.TP
\fBCo\fP
کپی‌رایت (حق نشر)
.TP
\fB\-a\fP
نشانگر ترتیبی مؤنث اسپانیایی
.TP
\fB<<\fP
گیومه چپ
.TP
\fB\-\fP\fB\-\fP
خط پیوند نرم (Soft hyphen)
.TP
\fBRg\fP
نشان تجاری ثبت‌شده
.TP
\fBPI\fP
پیلکرو (نشان پاراگراف)
.TP
\fB\-o\fP
نشانگر ترتیبی مذکر اسپانیایی
.TP
\fB>>\fP
گیومه راست
.TP
\fB?I\fP
علامت سؤال وارونه
.TP
\fB\-1\fP
خط فاصله (Hyphen)
.TP
\fB\-N\fP
خط تیره ان (En dash)
.TP
\fB\-M\fP
خط تیره ام (Em dash)
.TP
\fB\-3\fP
خط افقی (Horizontal bar)
.TP
\fB:3\fP
سه نقطه عمودی
.TP
\fB\&.3\fP
سه نقطه افقی خط وسط
.TP
\fB!2\fP
خط عمودی دوتایی
.TP
\fB=2\fP
خط زیرین دوتایی
.TP
\fB\&'6\fP
علامت نقل‌قول تکی چپ
.TP
\fB\&'9\fP
علامت نقل‌قول تکی راست
.TP
\fB\&.9\fP
نقل‌قول پایین «راست»
.TP
\fB9\&'\fP
نقل‌قول «راست» معکوس
.TP
\fB"6\fP
علامت نقل‌قول دوتایی چپ
.TP
\fB"9\fP
علامت نقل‌قول دوتایی راست
.TP
\fB:9\fP
نقل‌قول دوتایی پایین «راست»
.TP
\fB9"\fP
نقل‌قول دوتایی «راست» معکوس
.TP
\fB/\-\fP
خنجر (Dagger)
.TP
\fB/=\fP
خنجر دوتایی (Double dagger)
.PD
.TP
نمادهای ریاضی.PD 0
.TP
\fBDG\fP
درجه
.TP
\fB\-2\fP, \fB+\-\fP, \fB\-+\fP
علامت \-، علامت +/\-، علامت \-/+
.TP
\fB2S\fP
بالانویس ۲
.TP
\fB3S\fP
بالانویس ۳
.TP
\fB1S\fP
بالانویس ۱
.TP
\fBMy\fP
میکرو
.TP
\fB\&.M\fP
نقطه میانی
.TP
\fB14\fP
یک‌چهارم
.TP
\fB12\fP
یک‌دوم (نیم)
.TP
\fB34\fP
سه‌چهارم
.TP
\fB*X\fP
ضرب
.TP
\fB\-:\fP
تقسیم
.TP
\fB%0\fP
در هزار (پر میل)
.TP
\fBFA\fP, \fBTE\fP, \fB/0\fP
به ازای هر (سور عمومی)، وجود دارد (سور وجودی)، مجموعه تهی
.TP
\fBdP\fP, \fBDE\fP, \fBNB\fP
مشتق جزئی، دلتا (افزایش)، دل (نابَلا)
.TP
\fB(\-\fP, \fB\-)\fP
عضوِ، شاملِ
.TP
\fB*P\fP, \fB+Z\fP
حاصل‌ضرب، مجموع
.TP
\fB*\-\fP, \fBOb\fP, \fBSb\fP
ستاره، حلقه، گلوله (bullet)
.TP
\fBRT\fP, \fB0(\fP, \fB00\fP
علامت رادیکال، متناسب با، بی‌نهایت
.PD
.TP
نمادهای دیگر
.PD 0
.TP
\fBcS\fP, \fBcH\fP, \fBcD\fP, \fBcC\fP
خال‌های ورق: پیک، دل، خشت، گشنیز
.TP
\fBMd\fP, \fBM8\fP, \fBM2\fP, \fBMb\fP, \fBMx\fP, \fBMX\fP
نت‌نویسی موسیقی:
نت سیاه (یک‌چهارم)، نت چنگ (یک‌هشتم)، نت دولاچنگ (یک‌شانزدهم)، علامت پرچم، علامت بکار (طبیعی)، علامت دیز
.TP
\fBFm\fP, \fBMl\fP
مؤنث، مذکر
.PD
.TP
نشانه‌های اکسان (اعراب) به‌تنهایی
.PD 0
.TP
\fB\&'>\fP
اکسان سرکومفلکس / هشتک (مشابه کارِت، \fB^\fP)
.TP
\fB\&'!\fP
اکسان گراو (مشابه بک‌تیک، \fB`\fP)
.TP
\fB\&',\fP
سدیل (Cedilla)
.TP
\fB\&':\fP
دونقطه (اوملاوت)
.TP
\fB\&'m\fP
ماکرون (خط تیره روی حرف)
.TP
\fB\&''\fP
اکسان اگو (Acute)
.PD
.RE
.TP
\fBinsert\-files\fP
این تابع به شما امکان می‌دهد تا یک الگوی فایل را تایپ کرده و نتایج بسط را در هر مرحله مشاهده کنید\&. هنگامی که کلید بازگشت (Return) را فشار می‌دهید، تمام بسط‌ها درون خط فرمان درج می‌شوند\&.
.RS
.PP
.RS
.nf
\fBbindkey \&'^Xf' insert\-files\fP
.fi
.RE
.RE
.TP
\fBinsert\-unicode\-char\fP
هنگامی که برای نخستین بار اجرا می‌شود، کاربر مجموعه‌ای از ارقام هگزادسیمال (شانزده‌شانزدهی) را وارد می‌کند\&. این ورودی با فراخوانی دیگری از \fBinsert\-unicode\-char\fP پایان می‌پذیرد\&. سپس ارقام به نویسه یونیکد متناظر تبدیل می‌شوند\&. برای نمونه، اگر ویجت به \fB^XU\fP مقید شده باشد، توالی نویسه `\fB^XU 4 c ^XU\fP\&' نویسه \fBL\fP (یونیکد U+004c) را درج می‌کند\&.
.RS
.PP
برای روشی جهت درج نویسه‌ها با استفاده از یک شناسه اختصاری (کد حفظی) دو نویسه‌ای، \fBinsert\-composed\-char\fP را ببینید\&.
.RE

.TP
.PD 0
\fBnarrow\-to\-region \fP[ \fB\-p\fP \fIpre\fP ] [ \fB\-P\fP \fIpost\fP ]
.TP
.PD 0
\fB                 \fP[ \fB\-S\fP \fIstatepm\fP | \fB\-R\fP \fIstatepm\fP | [ \fB\-l\fP \fIlbufvar\fP ] [ \fB\-r\fP \fIrbufvar\fP ] ]
.TP
.PD 0
\fB                 \fP[ \fB\-n\fP ] [ \fIstart\fP \fIend\fP ]
.TP
.PD
\fBnarrow\-to\-region\-invisible\fP
بخش قابل ویرایش بافر را به ناحیه بین مکان‌نما و نشان (mark) محدود می‌کند، که می‌تواند به هر ترتیبی باشد\&. این ناحیه نباید خالی باشد\&.
.RS
.PP
\fBnarrow\-to\-region\fP می‌تواند به عنوان یک ویجت استفاده شود یا به صورت یک تابع از یک ویجت تعریف‌شده توسط کاربر فراخوانی گردد؛ به طور پیش‌فرض، متن بیرون از ناحیه قابل ویرایش، مرئی باقی می‌ماند\&. یک \fBrecursive\-edit\fP انجام می‌شود و سپس وضعیت گسترش‌یافته اولیه بازیابی می‌گردد\&. هنگامی که به صورت تابع فراخوانی می‌شود، گزینه‌ها و آرگومان‌های گوناگونی در دسترس هستند\&.
.PP
گزینه‌های \fB\-p\fP \fIpretext\fP و \fB\-P\fP \fIposttext\fP می‌توانند برای جایگزینی متنِ قبل و بعد از ناحیه نمایش در طول مدت اجرای تابع استفاده شوند؛ هر یک یا هر دوی آن‌ها می‌توانند یک رشته خالی باشند\&.
.PP
اگر گزینه \fB\-n\fP نیز داده شود، \fIpretext\fP یا \fIposttext\fP تنها در صورتی درج خواهند شد که به ترتیب متنی قبل یا بعد از ناحیه وجود داشته باشد که نامرئی خواهد شد\&.
.PP
می‌توان دو آرگومان عددی تعیین کرد که به جای موقعیت‌های مکان‌نما و نشان به کار خواهند رفت\&.
.PP
گزینه \fB\-S\fP \fIstatepm\fP برای محدودسازی بر اساس سایر گزینه‌ها ضمن ذخیره وضعیت اولیه در پارامتری با نام \fIstatepm\fP به کار می‌رود، در حالی که گزینه \fB\-R\fP \fIstatepm\fP برای بازیابی وضعیت از آن پارامتر استفاده می‌شود؛ توجه داشته باشید که در هر دو حالت، \fIنام\fP پارامتر لازم است\&. در حالت دوم، سایر گزینه‌ها و آرگومان‌ها بی‌اهمیت هستند\&. هنگامی که از این روش استفاده می‌شود، هیچ \fBrecursive\-edit\fPی انجام نمی‌گیرد؛ ویجت فراخواننده باید این تابع را با گزینه \fB\-S\fP فراخوانی کند، ویرایش مورد نظر خود را روی خط فرمان انجام دهد یا از طریق `\fBzle recursive\-edit\fP\&' کنترل را به کاربر بسپارد، سپس این تابع را با گزینه \fB\-R\fP فراخوانی نماید\&. آرگومان \fIstatepm\fP باید نام مناسبی برای یک پارامتر معمولی باشد، به جز اینکه پارامترهایی که با پیشوند \fB_ntr_\fP آغاز می‌شوند برای استفاده در \fBnarrow\-to\-region\fP رزرو شده‌اند\&. به طور معمول، این پارامتر برای تابع فراخواننده محلی (local) خواهد بود\&.
.PP
گزینه‌های \fB\-l\fP \fIlbufvar\fP و \fB\-r\fP \fIrbufvar\fP می‌توانند برای مشخص کردن پارامترهایی استفاده شوند که ویجت متن حاصل از عملیات را در آن‌ها ذخیره می‌کند\&. پارامتر \fIlbufvar\fP حاوی \fBLBUFFER\fP و \fIrbufvar\fP حاوی \fBRBUFFER\fP خواهد بود\&. هیچ یک از این دو گزینه نمی‌توانند همراه با \fB\-S\fP یا \fB\-R\fP استفاده شوند\&.
.PP
\fBnarrow\-to\-region\-invisible\fP یک ویجت ساده است که \fBnarrow\-to\-region\fP را با آرگومان‌هایی فراخوانی می‌کند که هر متنی خارج از ناحیه را با `\fB\&.\&.\&.\fP\&' جایگزین می‌نماید\&. این ویجت هیچ آرگومانی نمی‌پذیرد\&..PP
صفحه‌نمایش با اجرای هر دستور zle که معمولاً موجب پذیرفته شدن یا لغو شدن خط می‌شود بازیابی می‌گردد (و ابزارک بازمی‌گردد)\&. از این رو، یک دستور اضافی از این دست برای پذیرش یا لغو خط فعلی مورد نیاز است\&.
.PP
وضعیت بازگشتی هر دو ابزارک در صورتی که خط پذیرفته شده باشد صفر، و در غیر این صورت غیرصفر است\&.
.PP
در اینجا نمونه‌ای ساده از ابزارکی که از این ویژگی استفاده می‌کند آمده است\&.
.RS
.nf
\fBlocal state
narrow\-to\-region \-p $\&'Editing restricted region\en' \e 
  \-P \&'' \-S state
zle recursive\-edit
narrow\-to\-region \-R state\fP
.fi
.RE
.RE
.TP
\fBpredict\-on\fP
این مجموعه توابع، تایپ پیش‌بینانه را با استفاده از جستجو در تاریخچه پیاده‌سازی می‌کند\&.
پس از اجرای \fBpredict\-on\fP، تایپ نویسه‌ها باعث می‌شود ویرایشگر در تاریخچه به سمت عقب جستجو کند تا اولین خطی را که با آنچه تا کنون تایپ کرده‌اید آغاز می‌شود بیابد\&. پس از \fBpredict\-off\fP، ویرایش برای خطِ پیداشده به حالت عادی بازمی‌گردد\&.
در واقع، اغلب حتی نیازی به استفاده از \fBpredict\-off\fP ندارید، زیرا اگر خط با موردی در تاریخچه مطابقت نداشته باشد، فشردن یک کلید تکمیل خودکار استاندارد را انجام می‌دهد و در صورت نیافتن هیچ تکمیل خودکاری، نویسه درج می‌شود\&.
با این حال، ویرایش در میانه خط ممکن است پیش‌بینی را دچار سردرگمی کند؛ سبک \fBtoggle\fP را در زیر ببینید\&.
.RS
.PP
با سیستم تکمیل خودکار مبتنی بر تابع (که برای این کار لازم است)، باید بتوانید تقریباً در هر نقطه‌ای کلید \fBTAB\fP را بزنید تا مکان‌نما به موقعیت نویسه «جالب» بعدی برود (معمولاً انتهای کلمه جاری، اما گاهی در میانه‌ی کلمه)\&. و البته به محض اینکه کل خط همان چیزی شد که می‌خواهید، می‌توانید بدون نیاز به انتقال مکان‌نما به انتها، آن را با کلید return بپذیرید\&.
.PP
نخستین باری که \fBpredict\-on\fP استفاده می‌شود، چند تابع ابزارک اضافی می‌سازد:
.PP
.PD 0
.TP
\fBdelete\-backward\-and\-predict\fP
جایگزین ابزارک \fBbackward\-delete\-char\fP می‌شود\&. نیازی نیست خودتان آن را مقید (bind) کنید\&.
.TP
\fBinsert\-and\-predict\fP
تایپ پیش‌بینانه را با جایگزینی ابزارک \fBself\-insert\fP پیاده‌سازی می‌کند\&. نیازی نیست خودتان آن را مقید کنید\&.
.TP
\fBpredict\-off\fP
تایپ پیش‌بینانه را خاموش می‌کند\&.
.PD
.PP
اگرچه تنها تابع \fBpredict\-on\fP را \fBautoload\fP می‌کنید، لازم است یک مقیدسازی کلید برای \fBpredict\-off\fP نیز تعریف کنید\&.
.PP
.RS
.nf
\fBzle \-N predict\-on
zle \-N predict\-off
bindkey \&'^X^Z' predict\-on
bindkey \&'^Z' predict\-off\fP
.fi
.RE
.RE
.TP
\fBread\-from\-minibuffer\fP
این تابع بیشترین کاربرد را زمانی دارد که به عنوان یک تابع از درون یک ابزارک فراخوانی شود، اما به خودی خود نیز به عنوان یک ابزارک به درستی کار خواهد کرد\&. این ابزارک مقداری را در زیر خط فرمان فعلی درخواست می‌کند؛ این مقدار را می‌توان با استفاده از تمامی عملیات استاندارد zle (و نه صرفاً مجموعه محدودی که مثلاً هنگام اجرای \fBexecute\-named\-cmd\fP در دسترس است) وارد کرد\&. سپس مقدار در پارامتر \fB$REPLY\fP به تابع فراخوان بازگردانده شده و بافر ویرایش به وضعیت پیشین خود بازیابی می‌شود\&. اگر خواندن ورودی با یک وقفه صفحه‌کلید (معمولاً \fB^G\fP) لغو شود، تابع وضعیت ۱ را بازمی‌گرداند و \fB$REPLY\fP مقداردهی نمی‌شود\&.
.RS
.PP
اگر یک آرگومان به تابع داده شود، به عنوان اعلان (prompt) در نظر گرفته می‌شود، در غیر این صورت از «\fB? \fP\&» استفاده می‌شود\&. اگر دو آرگومان داده شود، اولی اعلان و دومی مقدار اولیه‌ی \fB$LBUFFER\fP است، و اگر آرگومان سومی داده شود مقدار اولیه‌ی \fB$RBUFFER\fP خواهد بود\&. این کار مقدار پیش‌فرض و جای‌گیری اولیه مکان‌نما را فراهم می‌کند\&. پس از بازگشت، کل بافر مقدار \fB$REPLY\fP خواهد بود\&.
.PP
یک گزینه در دسترس است: «\fB\-k\fP \fInum\fP\&» مشخص می‌کند که به جای کل یک خط، \fInum\fP نویسه خوانده شود\&. ویرایشگر خط در این حالت به صورت بازگشتی فراخوانی نمی‌شود، بنابراین بسته به تنظیمات ترمینال ممکن است ورودی قابل مشاهده نباشد، و فقط کلیدهای ورودی در \fB$REPLY\fP قرار می‌گیرند، نه کل بافر\&. توجه داشته باشید که بر خلاف دستور توکار \fBread\fP، مقدار \fInum\fP باید حتماً داده شود؛ هیچ پیش‌فرضی وجود ندارد\&.
.PP
نام این تابع تا حدی نامتناسب است، زیرا در واقع از minibuffer خود شل استفاده نمی‌شود\&. بنابراین همچنان امکان فراخوانی \fBexecuted\-named\-cmd\fP و توابع مشابه در حین خواندن مقدار وجود دارد\&.
.RE
.TP
\fBreplace\-argument\fP، \fBreplace\-argument\-edit\fP
تابع \fBreplace\-argument\fP می‌تواند برای جایگزینی یک آرگومان خط فرمان در خط فرمان فعلی یا، در صورت خالی بودن خط فرمان فعلی، در آخرین خط فرمان اجرا شده استفاده شود (خط فرمان جدید اجرا نمی‌شود)\&. آرگومان‌ها همان‌گونه که با نحو استاندارد شل تفکیک می‌شوند، در نظر گرفته خواهند شد\&.
.RS
.PP
اگر یک آرگومان عددی داده شود، مشخص‌کننده آرگومانی است که باید جایگزین شود\&. 0 به معنای نام دستور است، همانند بسط تاریخچه\&. یک آرگومان عددی منفی از آخرین کلمه به عقب شمارش می‌کند\&.
.PP
اگر آرگومان عددی داده نشود، آرگومان فعلی جایگزین می‌شود؛ در صورتی که از خط پیشین تاریخچه استفاده شود، این آرگومان همان آخرین آرگومان خواهد بود\&.
.PP
تابع برای یک آرگومان جایگزین اعلان نمایش می‌دهد\&.
.PP
اگر نام ابزارک حاوی رشته‌ی \fBedit\fP باشد، برای مثال به این صورت تعریف شده باشد:
.PP
.RS
.nf
\fBzle \-N replace\-argument\-edit replace\-argument\fP
.fi
.RE
.PP
آنگاه تابع، مقدار فعلی آرگومان را برای ویرایش ارائه می‌دهد، در غیر این صورت بافر ویرایش برای جایگزینی در ابتدا خالی خواهد بود\&.
.RE
.TP
.PD 0
\fBreplace\-string\fP، \fBreplace\-pattern\fP
.TP
.PD
\fBreplace\-string\-again\fP، \fBreplace\-pattern\-again\fP
تابع \fBreplace\-string\fP سه ابزارک را پیاده‌سازی می‌کند\&.
اگر با همان نام تابع تعریف شود، دو رشته را درخواست می‌کند؛ اولین رشته (مبدأ) با رشته دوم در هر کجای بافر ویرایش خط که ظاهر شود، جایگزین خواهد شد\&.
.RS
.PP
اگر نام ابزارک حاوی کلمه‌ی «\fBpattern\fP\&» باشد، برای نمونه با تعریف ابزارک از طریق دستور «\fBzle \-N replace\-pattern replace\-string\fP\&»، آنگاه تطبیق با استفاده از الگوهای zsh انجام می‌شود\&. تمام الگوهای گسترش‌یافته گلوبینگ (extended globbing) در zsh می‌توانند در رشته مبدأ استفاده شوند؛ توجه داشته باشید که بر خلاف تولید نام فایل، الگو نیازی به تطبیق با یک کلمه کامل ندارد و توصیف‌کننده‌های گلوب (glob qualifiers) نیز هیچ اثری ندارند\&. علاوه بر این، رشته جایگزین می‌تواند شامل جایگزینی‌های پارامتر یا فرمان باشد\&. افزون بر این، یک «\fB&\fP\&» در رشته جایگزین با رشته مبدأ تطبیق‌یافته جایگزین خواهد شد، و یک رقم با بک‌اسلش «\fB\e\fP\fIN\fP\&» با \fIN\fPاُمین عبارت داخل پرانتز تطبیق‌یافته جایگزین می‌شود\&. شکل «\fB\e{\fP\fIN\fP\fB}\fP\&» می‌تواند برای محافظت از رقم در برابر ارقام بعدی استفاده شود\&.
.PP
اگر ابزارک به جای آن حاوی کلمه‌ی «\fBregex\fP\&» (یا «\fBregexp\fP») باشد، تطبیق با استفاده از عبارت‌های منظم و با رعایت تنظیمات گزینه \fBRE_MATCH_PCRE\fP انجام می‌شود (توضیحات تابع \fBregexp\-replace\fP را در زیر ببینید)\&. امکانات جایگزینی ویژه شرح‌داده‌شده در بالا برای تطبیق الگو در اینجا نیز در دسترس هستند\&.
.PP
به طور پیش‌فرض، رشته مبدأ یا جایگزین پیشین برای ویرایش ارائه نمی‌شود\&. با این حال، این ویژگی را می‌توان با تنظیم سبک \fBedit\-previous\fP در زمینه \fB:zle:\fP\fIwidget\fP (برای مثال \fB:zle:replace\-string\fP) بر روی \fBtrue\fP فعال کرد\&. علاوه بر این، یک آرگومان عددی مثبت ارائه مقادیر قبلی را اجباری می‌کند، و آرگومان منفی یا صفر مانع از ارائه آن‌ها می‌شود\&.
.PP
تابع \fBreplace\-string\-again\fP می‌تواند برای تکرار جایگزینی قبلی استفاده شود؛ هیچ اعلانی نمایش داده نمی‌شود\&. همانند \fBreplace\-string\fP، اگر نام ابزارک حاوی کلمه‌ی «\fBpattern\fP\&» یا «\fBregex\fP» باشد، تطبیق الگو یا عبارت منظم انجام می‌شود، و در غیر این صورت جایگزینی رشته لفظی (literal) صورت می‌گیرد\&. توجه داشته باشید که متن مبدأ و جایگزین پیشین یکسان هستند، چه از تطبیق الگو، چه عبارت منظم و چه رشته استفاده شده باشد\&.
.PP
علاوه بر این، \fBreplace\-string\fP جایگزینی پیشین را در بالای اعلان نشان می‌دهد، مادامی که در طول نشست جاری موردی وجود داشته باشد؛ اگر رشته مبدأ خالی باشد، آن جایگزینی بدون اینکه ابزارک برای یک رشته جایگزین درخواستی کند تکرار خواهد شد\&.
.PP
برای مثال، با شروع از خط:
.PP
.RS.nf
\fBprint This line contains fan and fond\fP
.fi
.RE
.PP
و فراخوانی \fBreplace\-pattern\fP با رشتهٔ مبدأ
`\fBf(?)n\fP\&' و
رشتهٔ جایگزین `\fBc\e1r\fP\&' خط نه‌چندان مفیدی را تولید می‌کند:
.PP
.RS
.nf
\fBprint This line contains car and cord\fP
.fi
.RE
.PP
دامنهٔ رشتهٔ جایگزین می‌تواند با استفاده از ابزارک
\fBnarrow\-to\-region\-invisible\fP محدود شود\&. یکی از محدودیت‌های نسخهٔ
فعلی این است که \fBundo\fP پیش از باطل‌سازی خود جایگزینی، میان تغییرات
رشته‌های جایگزین و مبدأ دور می‌زند\&.
.RE
.TP
\fBsend\-invisible\fP
این تابع شبیه به read\-from\-minibuffer است، از این جهت که ممکن است به‌صورت یک
تابع از درون یک ابزارک یا به عنوان ابزارکی مستقل فراخوانی شود، و به‌صورت تعاملی
ورودی را از صفحه‌کلید بخواند\&. با این حال، ورودیِ در حال تایپ پنهان شده و
به جای آن رشته‌ای از ستاره‌ها (`\fB*\fP\&') نشان داده می‌شود\&. مقدار در
پارامتر \fB$INVISIBLE\fP ذخیره می‌شود که ارجاعی به آن در موقعیت بازگردانی‌شدهٔ مکان‌نما
در بافر ویرایش درج می‌گردد\&. اگر خواندن با یک وقفهٔ صفحه‌کلید (معمولاً \fB^G\fP) یا
یک خروج دیگر از ویرایش مانند \fBpush\-line\fP لغو شود، \fB$INVISIBLE\fP خالی تنظیم
شده و بافر اصلی بدون تغییر بازگردانده می‌شود\&.
.RS
.PP
اگر یک آرگومان به تابع داده شود، به عنوان اعلان در نظر گرفته می‌شود،
در غیر این صورت از `\fBNon\-echoed text: \fP\&' استفاده می‌شود (مانند emacs)\&.
اگر آرگومان دوم و سومی ارائه شوند، برای شروع و پایان ارجاع به \fB$INVISIBLE\fP که
در بافر درج می‌شود به کار می‌روند\&. پیش‌فرض این است که با \fB${\fP باز شده، سپس
\fBINVISIBLE\fP و با \fB}\fP بسته شود، اما جلوه‌های بسیار دیگری نیز ممکن است\&.
.RE
.TP
\fBsmart\-insert\-last\-word\fP
این تابع می‌تواند جایگزین ابزارک \fBinsert\-last\-word\fP شود، به این صورت:
.RS
.PP
.RS
.nf
\fBzle \-N insert\-last\-word smart\-insert\-last\-word\fP
.fi
.RE
.PP
با یک آرگومان عددی، یا هنگامی که در یک فراخوانی از ابزارکی دیگر آرگومان‌های خط فرمان
به آن پاس داده شود، مانند \fBinsert\-last\-word\fP رفتار می‌کند، با این تفاوت که
وقتی \fBINTERACTIVE_COMMENTS\fP تنظیم شده باشد، کلمات موجود در توضیحات نادیده گرفته می‌شوند\&.
.PP
در غیر این صورت، راست‌ترین کلمهٔ «جالب» از دستور پیشین پیدا شده و درج
می‌شود\&. تعریف پیش‌فرض «جالب» این است که کلمه دست‌کم حاوی یک نویسهٔ الفبایی،
اسلش یا بک‌اسلش باشد\&. این تعریف می‌تواند با استفاده از سبک \fBmatch\fP بازنویسی
شود\&. بافت مورد استفاده برای جستجوی این سبک، نام ابزارک است؛ بنابراین بافت
معمولاً \fB:insert\-last\-word\fP است\&. با این وجود، می‌توانید این تابع را به
ابزارک‌های مختلف مقید کنید تا از الگوهای متفاوتی استفاده کند:
.PP
.RS
.nf
\fBzle \-N insert\-last\-assignment smart\-insert\-last\-word
zstyle :insert\-last\-assignment match \&'[[:alpha:]][][[:alnum:]]#=*'
bindkey \&'\ee=' insert\-last\-assignment\fP
.fi
.RE
.PP
اگر هیچ کلمهٔ جالبی یافت نشود و سبک \fBauto\-previous\fP روی یک مقدار درست
تنظیم شده باشد، جستجو به سمت بالا در تاریخچه ادامه می‌یابد\&. هنگامی که
\fBauto\-previous\fP تنظیم نشده یا نادرست باشد (حالت پیش‌فرض)، ابزارک باید مکرراً
فراخوانی شود تا خطوط پیشین تاریخچه جستجو شوند\&.
.RE
.TP
\fBtranspose\-lines\fP
تنها با یک بافر ویرایش چندخطی کاربرد دارد؛ خطوط در اینجا خطوطِ درون بافر
فعلیِ روی صفحه هستند، نه خطوط تاریخچه\&. تأثیر آن مشابه تابعی با همین نام
در Emacs است\&.
.RS
.PP
خط فعلی را با خط قبلی جابه‌جا می‌کند و مکان‌نما را به ابتدای خط بعدی
می‌برد\&. تکرار این کار (که با ارائهٔ یک آرگومان عددی مثبت امکان‌پذیر است)
تأثیر جابه‌جا کردن خط بالای مکان‌نما به سمت پایین به تعداد معینی خط را دارد\&.
.PP
با یک آرگومان عددی منفی، به دو خط در بالای مکان‌نما نیاز دارد\&. این دو خط
جابه‌جا شده و مکان‌نما به ابتدای خط قبلی منتقل می‌شود\&. استفاده از یک
آرگومان عددی کمتر از \-1 این اثر را دارد که خط بالای مکان‌نما را به اندازهٔ
قرینهٔ آن عدد خط به سمت بالا حرکت می‌دهد\&.
.RE
.TP
\fBurl\-quote\-magic\fP
این ابزارک جایگزین دستور توکار \fBself\-insert\fP می‌شود تا تایپ نشانی‌های URL
به عنوان آرگومان‌های خط فرمان را آسان‌تر کند\&. هم‌زمان با تایپ کردن شما،
نویسهٔ ورودی تحلیل می‌شود و اگر نیازمند نقل‌قول باشد، کلمهٔ فعلی برای
یافتن یک طرحوارهٔ URI بررسی می‌شود\&. اگر موردی یافت شد و کلمهٔ فعلی از
قبل داخل نقل‌قول نبود، یک بک‌اسلش پیش از نویسهٔ ورودی درج می‌گردد\&.
.RS
.PP
سبک‌ها برای مهار رفتار نقل‌قول:
.PP
.PD 0
.TP
.PD
\fBurl\-metas\fP
این سبک در بافت `\fB:url\-quote\-magic:\fP\fIscheme\fP\&' بررسی می‌شود
(که در آن \fIscheme\fP طرحوارهٔ URL فعلی است، مانند "\fBftp\fP")\&. مقدار آن،
رشته‌ای از نویسه‌هایی است که هنگام حضور در URL با آن طرحواره، به عنوان فرانوسه‌های
تطبیق الگو در نظر گرفته می‌شوند\&. پیش‌فرض این است که همهٔ نویسه‌های تطبیق
الگوی گسترش‌یافتهٔ zsh نقل‌قول شوند، به جز \&'\fB<\fP' و \&'\fB>\fP'، اما شامل آکولادها
(مانند گسترش آکولادی)\&. همچنین \fBurl\-seps\fP را ببینید\&.
.TP
\fBurl\-seps\fP
مانند \fBurl\-metas\fP، اما نویسه‌هایی را فهرست می‌کند که باید جداکننده‌های دستور،
تغییرمسیرها، ارجاعات تاریخچه و غیره در نظر گرفته شوند\&. حالت پیش‌فرض، نقل‌قول کردن
مجموعهٔ استاندارد جداکننده‌های شل است، به استثنای مواردی که با نویسه‌های تطبیق الگوی
گسترش‌یافته تداخل دارند، اما شامل \&'\fB<\fP' و \&'\fB>\fP' و اولین نویسهٔ \fB$histchars\fP\&.
.TP
\fBurl\-globbers\fP
این سبک در بافت `\fB:url\-quote\-magic\fP\&' بررسی می‌شود\&. مقادیر، فهرستی از
نام‌های دستوراتی را تشکیل می‌دهند که انتظار می‌رود تطبیق الگوی خودشان را روی رشتهٔ
URL انجام دهند\&. این بدان معناست که آنها برای استفاده از اصلاح‌گر `\fBnoglob\fP\&'
نام‌مستعار شده‌اند\&. هنگامی که اولین کلمه در خط با یکی از این مقادیر مطابقت
داشته باشد \fIو\fP نشانی URL به یک فایل محلی اشاره کند (\fBurl\-local\-schema\fP را ببینید)،
تنها نویسه‌های \fBurl\-seps\fP نقل‌قول می‌شوند؛ نویسه‌های \fBurl\-metas\fP دست‌نخورده
باقی می‌مانند و به آنها اجازه داده می‌شود که بر تجزیهٔ خط فرمان، کامل‌سازی و غیره
تأثیر بگذارند\&. مقادیر پیش‌فرض عبارت است از `\fBnoglob\fP\&' مستقیم به‌علاوهٔ هر دستوری
که به تابع کمکی `\fBurlglobber\fP\&' یا نام‌مستعار آن `\fBgloburl\fP' منتسب شده باشد
(زمانی که پیمانهٔ \fBzsh/parameter\fP در دسترس باشد)\&.
.TP
\fBurl\-local\-schema\fP
این سبک همیشه در بافت `\fB:urlglobber\fP\&' بررسی می‌شود، حتی با اینکه توسط هر دو
ابزارک url\-quote\-magic و urlglobber استفاده می‌شود\&. مقادیر، فهرستی از طرحواره‌های
URI را تشکیل می‌دهند که باید بر اساس نام مسیرهای واقعی محلی‌شان به عنوان اشاره به
فایل‌های محلی در نظر گرفته شوند، بر خلاف فایل‌هایی که نسبت به ریشهٔ اسناد
تعریف‌شده توسط وب‌سرور مشخص می‌شوند\&. مقادیر پیش‌فرض "\fBftp\fP" و "\fBfile\fP" هستند\&.
.TP
\fBurl\-other\-schema\fP
مانند \fBurl\-local\-schema\fP، اما تمام طرحواره‌های دیگر URI را فهرست می‌کند که
\fBurlglobber\fP و \fBurl\-quote\-magic\fP باید روی آن‌ها عمل کنند\&. اگر URI در
خط فرمان دارای طرحواره‌ای نباشد که در این فهرست یا در \fBurl\-local\-schema\fP آمده
باشد، به صورت جادویی نقل‌قول نمی‌شود\&. مقادیر پیش‌فرض "\fBhttp\fP"، "\fBhttps\fP"
و "\fBftp\fP" هستند\&. هنگامی که یک طرحواره هم در اینجا و هم در \fBurl\-local\-schema\fP
حضور داشته باشد، بسته به اینکه نام دستور در \fBurl\-globbers\fP آمده باشد یا خیر، به
شیوه‌ای متفاوت نقل‌قول می‌شود\&.
.PP
بارگذاری \fBurl\-quote\-magic\fP همچنین یک تابع کمکی به نام `\fBurlglobber\fP\&' را
تعریف می‌کند و `\fBgloburl\fP\&' را به `\fBnoglob urlglobber\fP' نام‌مستعار می‌کند\&.
این تابع یک URL محلی را تجزیه کرده، تلاش می‌کند تا بخش فایل محلی مسیر URL را با
الگو تطبیق دهد و سپس نتایج را دوباره در قالب URL بازگرداند\&.
.RE
.TP
\fBvi\-pipe\fP
این تابع یک دستور حرکتی را از صفحه‌کلید خوانده و سپس برای یک دستور خارجی
اعلان نمایش می‌دهد\&. بخشی از بافر که توسط آن حرکت پوشش داده شده است، به دستور
خارجی پایپ شده و سپس با خروجی آن دستور جایگزین می‌شود\&. اگر دستور
حرکتی به vi\-pipe مقید شده باشد، خط فعلی استفاده می‌شود\&.
.RS
.PP
این تابع به عنوان نمونه‌ای برای خواندن یک دستور حرکتی vi از درون یک ابزارک
تعریف‌شده توسط کاربر عمل می‌کند\&.
.RE
.TP
\fBwhich\-command\fP
این تابع یک جایگزین مستقیم برای ابزارک توکار \fBwhich\-command\fP است\&.
این تابع رفتار بهبودیافته‌ای دارد، از این جهت که به درستی تشخیص می‌دهد که آیا
کلمهٔ دستور نیاز به بسط‌یافتن به عنوان یک نام‌مستعار دارد یا خیر؛ در این
صورت، به ردیابی کلمهٔ دستور از نام‌مستعارِ بسط‌یافته ادامه می‌دهد تا به دستوری برسد
که اجرا خواهد شد\&.
.RS
.PP
سبک \fBwhence\fP در بافت \fB:zle:$WIDGET\fP در دسترس است؛ این سبک می‌تواند
به یک آرایه تنظیم شود تا دستور و گزینه‌هایی را مشخص کند که برای بررسی کلمهٔ
دستور یافت‌شده استفاده خواهند شد\&. مقدار پیش‌فرض \fBwhence \-c\fP است\&.
.RE.TP
\fBzcalc\-auto\-insert\fP
این تابع همراه با تابع \fBzcalc\fP که در بخش «Mathematical Functions» شرح داده شده است، مفید است\&.
این تابع باید به کلیدی متصل شود که نشان‌دهنده یک عملگر دودویی مانند `\fB+\fP\&'، `\fB\-\fP'، `\fB*\fP' یا `\fB/\fP' است\&. هنگام اجرا در zcalc، اگر کلید در ابتدای خط یا بلافاصله پس از یک پرانتز باز قرار گیرد، متن \fB"ans "\fP پیش از نمایش خود کلید درج می‌شود\&. این کار امکان استفاده آسان از پاسخ محاسبات قبلی در خط فعلی را فراهم می‌سازد\&. متنی که قرار است پیش از نماد تایپ‌شده درج شود، می‌تواند با تنظیم متغیر \fBZCALC_AUTO_INSERT_PREFIX\fP تغییر یابد\&.
.RS
.PP
بنابراین، برای مثال، فشردن `\fB+12\fP\&' و به‌دنبال آن return، مقدار ۱۲ را به نتیجه قبلی اضافه می‌کند\&.
.PP
اگر zcalc در حالت RPN باشد (گزینه \fB\-r\fP)، تأثیر این اتصال کلید به‌طور خودکار خنثی می‌شود؛ زیرا عملگرها به‌تنهایی در یک خط معنادار هستند\&.
.PP
هنگامی که در zcalc نیستید، کلید صرفاً خود نماد را درج می‌کند\&.
.RE
.PP
.SS "توابع کمکی (Utility Functions)"
.PP
این توابع در ساخت ویجت‌ها کاربرد دارند\&. آن‌ها باید با `\fBautoload \-U\fP \fIfunction\fP\&' بارگذاری شده و مطابق توضیحات، از طریق ویجت‌های تعریف‌شده توسط کاربر فراخوانی شوند\&.
.PP
.PD 0
.TP
.PD
\fBsplit\-shell\-arguments\fP
این تابع خطی را که در حال حاضر ویرایش می‌شود، به آرگومان‌های پوسته و فاصله‌های خالی تفکیک می‌کند\&. نتیجه در آرایه \fBreply\fP ذخیره می‌شود\&. این آرایه شامل تمام بخش‌های خط به ترتیب است؛ از هر فاصله خالی قبل از اولین آرگومان شروع شده و به هر فاصله خالی بعد از آخرین آرگومان ختم می‌شود\&. بنابراین (تا زمانی که گزینه \fBKSH_ARRAYS\fP تنظیم نشده باشد) فاصله‌های خالی در نمایه‌های فرد آرایه و آرگومان‌ها در نمایه‌های زوج قرار می‌گیرند\&. توجه داشته باشید که هیچ نقض یا حذفی در نقل‌قول‌ها (quotes) صورت نمی‌گیرد؛ اتصال تمام عناصر \fBreply\fP به ترتیب، تضمین می‌کند که خط اصلی بازتولید شود\&.
.RS
.PP
پارامتر \fBREPLY\fP روی نمایه کلمه‌ای در \fBreply\fP تنظیم می‌شود که حاوی نویسه پس از مکان‌نما است، که در آن اولین عنصر دارای نمایه ۱ است\&. پارامتر \fBREPLY2\fP روی نمایه نویسه زیر مکان‌نما در آن کلمه تنظیم می‌شود، که در آن اولین نویسه نمایه ۱ دارد\&.
.PP
بنابراین \fBreply\fP، \fBREPLY\fP و \fBREPLY2\fP همگی باید درون تابع دربرگیرنده به‌صورت محلی (local) تعریف شوند\&.
.PP
برای مشاهده مثالی از نحوه فراخوانی این تابع، به تابع \fBmodify\-current\-argument\fP که در زیر شرح داده شده است مراجعه کنید\&.
.RE
.TP
\fBmodify\-current\-argument\fP [ \fIexpr\-using\-\fP\fB$ARG\fP | \fIfunc\fP ]
این تابع روشی ساده فراهم می‌کند تا ویجت‌های تعریف‌شده توسط کاربر بتوانند آرگومان خط فرمانِ زیر مکان‌نما (یا بلافاصله سمت چپ مکان‌نما، در صورتی که مکان‌نما بین آرگومان‌ها باشد) را اصلاح کنند\&.
.RS
.PP
آرگومان می‌تواند عبارتی باشد که هنگام ارزیابی، روی پارامتر پوسته \fBARG\fP عمل می‌کند؛ پارامتری که روی آرگومان خط فرمانِ زیر مکان‌نما تنظیم شده است\&. عبارت باید به‌درستی نقل‌قول (quote) شود تا از ارزیابی زودهنگام آن جلوگیری شود\&.
.PP
در حالت دیگر، اگر آرگومان حاوی رشته \fBARG\fP نباشد، فرض می‌شود که یک تابع پوسته است که آرگومان فعلی خط فرمان به‌عنوان تنها آرگومان به آن ارسال می‌گردد\&. تابع باید متغیر \fBREPLY\fP را روی مقدار جدید برای آرگومان خط فرمان تنظیم کند\&. اگر تابع وضعیت خروج غیرصفر بازگرداند، تابع فراخواننده نیز چنین وضعیتی بازخواهد گرداند\&.
.PP
برای مثال، یک ویجت تعریف‌شده توسط کاربر که حاوی کد زیر است، تمام نویسه‌های موجود در آرگومانِ زیر مکان‌نما را به حروف بزرگ تبدیل می‌کند:
.PP
.RS
.nf
\fBmodify\-current\-argument \&'${(U)ARG}'\fP
.fi
.RE
.PP
کد زیر هرگونه نقل‌قول را از کلمه فعلی حذف می‌کند (چه بک‌اسلش باشد و چه یکی از سبک‌های نقل‌قول)، و آن را در سراسر کلمه با نقل‌قول تکی (single quoting) جایگزین می‌کند:
.PP
.RS
.nf
\fBmodify\-current\-argument \&'${(qq)${(Q)ARG}}'\fP
.fi
.RE
.PP
کد زیر بسط دایرکتوری را روی آرگومان خط فرمان انجام داده و آن را با مسیر مطلق جایگزین می‌کند:
.PP
.RS
.nf
\fBexpand\-dir() {
  REPLY=${~1}
  REPLY=${REPLY:a}
}
modify\-current\-argument expand\-dir\fP
.fi
.RE
.PP
در عمل، تابع \fBexpand\-dir\fP احتمالاً درون ویجتی که \fBmodify\-current\-argument\fP در آن فراخوانی می‌شود، تعریف نخواهد شد\&.
.RE
.PP.SS "سبک‌ها (Styles)"
.PP
رفتار چندین مورد از ابزارک‌های بالا را می‌توان با استفاده از سازوکار \fBzstyle\fP مهار کرد\&. به‌ویژه، ابزارک‌هایی که با سامانهٔ تکمیل تعامل دارند، زمینهٔ خود را به هر تکمیلی که فراخوانی می‌کنند انتقال می‌دهند\&.
.PP
.PD 0
.TP
.PD
\fBbreak\-keys\fP
این سبک توسط ابزارک \fBincremental\-complete\-word\fP استفاده می‌شود\&. مقدار آن باید یک الگو باشد، و تمام کلیدهایی که با این الگو مطابقت دارند باعث می‌شوند ابزارک، بدون داشتن هیچ اثر دیگری از سوی کلید، تکمیل افزایشی را متوقف کند\&. مانند همهٔ سبک‌هایی که مستقیماً توسط \fBincremental\-complete\-word\fP استفاده می‌شوند، این سبک با استفاده از زمینهٔ `\fB:incremental\fP\&' جستجو می‌شود\&.
.TP
\fBcompleter\fP
ابزارک‌های \fBincremental\-complete\-word\fP و \fBinsert\-and\-predict\fP پیش از فراخوانی فرایند تکمیل، نام زمینهٔ سطح بالای خود را برپا می‌سازند\&. این امر امکان تعریف مجموعه‌های مختلفی از توابع تکمیل‌کننده را برای تکمیل عادی و برای این ابزارک‌ها فراهم می‌کند\&. برای نمونه، برای استفاده از تکمیل، تقریب و تصحیح در تکمیل عادی، تکمیل و تصحیح در تکمیل افزایشی و تنها تکمیل در پیش‌بینی، می‌توان این‌گونه استفاده کرد:
.RS
.PP
.RS
.nf
\fBzstyle \&':completion:*' completer \e 
        _complete _correct _approximate
zstyle \&':completion:incremental:*' completer \e 
        _complete _correct
zstyle \&':completion:predict:*' completer \e 
        _complete\fP
.fi
.RE
.PP
محدود کردن تکمیل‌کننده‌های مورداستفاده در پیش‌بینی ایدهٔ خوبی است، چرا که ممکن است حین تایپ کردن شما به‌طور خودکار فراخوانی شوند\&. تکمیل‌کننده‌های \fB_list\fP و \fB_menu\fP هرگز نباید همراه با پیش‌بینی استفاده شوند\&. تکمیل‌کننده‌های \fB_approximate\fP، \fB_correct\fP، \fB_expand\fP و \fB_match\fP را می‌توان استفاده کرد، اما توجه داشته باشید که ممکن است نویسه‌ها را در هر کجای کلمهٔ پشت مکان‌نما تغییر دهند، بنابراین باید به‌دقت مراقب باشید که نتیجه همان چیزی باشد که مد نظر داشتید\&.
.RE
.TP
\fBcursor\fP
ابزارک \fBinsert\-and\-predict\fP از این سبک در زمینهٔ `\fB:predict\fP\&' برای تصمیم‌گیری دربارهٔ محل قرارگیری مکان‌نما پس از اقدام به تکمیل استفاده می‌کند\&. مقادیر عبارت‌اند از:
.RS
.PP
.PD 0
.TP
.PD
\fBcomplete\fP
مکان‌نما در جایی که هنگام پایان تکمیل بود باقی می‌ماند، اما تنها در صورتی که بعد از نویسه‌ای برابر با نویسه‌ای باشد که کاربر به‌تازگی درج کرده است\&. اگر بعد از نویسهٔ دیگری باشد، این مقدار همانند `\fBkey\fP\&' خواهد بود\&.
.TP
\fBkey\fP
مکان‌نما پس از \fIn\fPاُمین رخداد نویسه‌ای که به‌تازگی درج شده رها می‌شود، که در آن \fIn\fP تعداد دفعاتی است که آن نویسه پیش از اقدام به تکمیل در کلمه ظاهر شده بود\&. به‌طور خلاصه، این کار اثر باقی گذاشتن مکان‌نما پس از نویسهٔ به‌تازگی تایپ‌شده را دارد حتی اگر کد تکمیل دریافته باشد که نویسهٔ دیگری در آن موقعیت نیاز به درج ندارد\&.
.PP
هر مقدار دیگری برای این سبک، بدون قید و شرط مکان‌نما را در موقعیتی رها می‌کند که کد تکمیل آن را رها کرده است\&.
.RE
.TP
\fBlist\fP
هنگام استفاده از ابزارک \fBincremental\-complete\-word\fP، این سبک مشخص می‌کند که آیا تطابق‌ها باید با هر بار فشردن کلید فهرست شوند یا خیر (در صورتی که در صفحه جا شوند)\&. از پیشوند زمینهٔ `\fB:completion:incremental\fP\&' استفاده کنید\&.
.RS
.PP
ابزارک \fBinsert\-and\-predict\fP از این سبک برای تصمیم‌گیری دربارهٔ اینکه آیا تکمیل حتی در صورت وجود تنها یک تکمیل ممکن نمایش داده شود یا خیر استفاده می‌کند\&. این کار در صورتی انجام می‌شود که مقدار این سبک رشتهٔ \fBalways\fP باشد\&. در این حالت زمینه `\fB:predict\fP\&' است (\fIنه\fP `\fB:completion:predict\fP')\&.
.RE
.TP
\fBmatch\fP
این سبک توسط \fBsmart\-insert\-last\-word\fP برای ارائهٔ الگویی (با استفاده از نحو کامل \fBEXTENDED_GLOB\fP) که با یک کلمهٔ مورد نظر مطابقت دارد به کار می‌رود\&. زمینه، نام ابزارکی است که \fBsmart\-insert\-last\-word\fP به آن متصل شده است (بالا را ببینید)\&. رفتار پیش‌فرض \fBsmart\-insert\-last\-word\fP معادل است با:
.RS
.PP
.RS
.nf
\fBzstyle :insert\-last\-word match \&'*[[:alpha:]/\e\e]*'\fP
.fi
.RE
.PP
با این حال، ممکن است بخواهید کلماتی را که حاوی فاصله هستند نیز بگنجانید:
.PP
.RS
.nf
\fBzstyle :insert\-last\-word match \&'*[[:alpha:][:space:]/\e\e]*'\fP
.fi
.RE
.PP
یا اعداد را تا زمانی که طول کلمه حداقل دو نویسه باشد بگنجانید:
.PP
.RS
.nf
\fBzstyle :insert\-last\-word match \&'*([[:digit:]]?|[[:alpha:]/\e\e])*'\fP
.fi
.RE
.PP
مثال بالا باعث می‌شود بازهدایت‌هایی مانند "2>" نیز گنجانده شوند\&.
.RE
.TP
\fBprompt\fP
ابزارک \fBincremental\-complete\-word\fP مقدار این سبک را در طول تکمیل افزایشی در خط وضعیت نمایش می‌دهد\&. مقدار رشته‌ای می‌تواند شامل هر یک از زیررشته‌های زیر به شیوهٔ پارامترهای اعلان \fBPS1\fP و دیگر اعلان‌ها باشد:
.RS
.PP
.PD 0
.TP
.PD
\fB%c\fP
با نام تابع تکمیل‌کننده‌ای که تطابق‌ها را تولید کرده است (بدون زیرخط آغازین) جایگزین می‌شود\&.
.TP
\fB%l\fP
هنگامی که سبک \fBlist\fP تنظیم شده باشد، اگر فهرست تطابق‌ها برای جا شدن در صفحه بیش از حد طولانی باشد با `\fB\&.\&.\&.\fP\&' و در غیر این صورت با یک رشتهٔ خالی جایگزین می‌شود\&. اگر سبک \fBlist\fP برابر `false\&' باشد یا تنظیم نشده باشد، `\fB%l\fP' همواره حذف می‌گردد\&.
.TP
\fB%n\fP
با تعداد تطابق‌های تولیدشده جایگزین می‌شود\&.
.TP
\fB%s\fP
به‌ترتیب در صورتی که هیچ تکمیلی مطابق با کلمهٔ روی خط نباشد با `\fB\-no match\-\fP\&'، اگر تطابق‌ها پیشوند مشترکی متفاوت از کلمهٔ روی خط نداشته باشند با `\fB\-no prefix\-\fP'، یا در صورت وجود چنین پیشوند مشترکی با یک رشتهٔ خالی جایگزین می‌شود\&.
.TP
\fB%u\fP
با بخش بدون‌ابهام تمام تطابق‌ها، در صورت وجود و در صورتی که متفاوت از کلمهٔ روی خط باشد، جایگزین می‌شود\&.
.PP
مانند `\fBbreak\-keys\fP\&'، این سبک نیز از زمینهٔ `\fB:incremental\fP' استفاده می‌کند\&.
.RE
.TP
\fBstop\-keys\fP
این سبک توسط ابزارک \fBincremental\-complete\-word\fP استفاده می‌شود\&. با مقدار آن به‌گونه‌ای مشابه با مقدار سبک \fBbreak\-keys\fP رفتار می‌شود (و از همان زمینه استفاده می‌کند: `\fB:incremental\fP\&')\&. با این حال، در این مورد تمام کلیدهایی که با الگوی ارائه‌شده به‌عنوان مقدار آن تطابق دارند، تکمیل افزایشی را متوقف کرده و سپس تابع معمول خود را اجرا می‌کنند\&.
.TP
\fBtoggle\fP
این سبک بولی توسط \fBpredict\-on\fP و ابزارک‌های مرتبط با آن در زمینهٔ `\fB:predict\fP\&' استفاده می‌شود\&. اگر روی یکی از مقادیر استاندارد `true' تنظیم شود، تایپ پیش‌گویانه به‌طور خودکار در وضعیت‌هایی که بعید است مفید باشد خاموش می‌شود، مانند هنگام ویرایش یک میان‌گیر چندخطی یا پس از رفتن به میانهٔ یک خط و سپس حذف یک نویسه\&. حالت پیش‌فرض روشن ماندن پیش‌بینی تا زمان فراخوانی صریح \fBpredict\-off\fP است\&.
.TP
\fBverbose\fP
این سبک بولی توسط \fBpredict\-on\fP و ابزارک‌های مرتبط با آن در زمینهٔ `\fB:predict\fP\&' استفاده می‌شود\&. اگر روی یکی از مقادیر استاندارد `true' تنظیم شود، این ابزارک‌ها هنگام تغییر حالت پیش‌گویی، پیامی زیر اعلان نمایش می‌دهند\&. این سبک در ترکیب با سبک \fBtoggle\fP بیشترین کاربرد را دارد\&. در حالت پیش‌فرض این پیام‌ها نمایش داده نمی‌شوند\&.
.TP
\fBwidget\fP
این سبک مشابه سبک \fBcommand\fP است: برای توابع ابزارکی که از \fBzle\fP برای فراخوانی ابزارک‌های دیگر استفاده می‌کنند، گاهی می‌توان از این سبک برای جایگزینی ابزارکِ فراخوانی‌شده استفاده کرد\&. زمینهٔ این سبک، نام ابزارک فراخواننده است (\fIنه\fP نام تابع فراخواننده، چرا که یک تابع ممکن است به چندین نام ابزارک متصل شده باشد)\&.
.RS.PP
.RS
.nf
\fBzstyle :copy\-earlier\-word widget smart\-insert\-last\-word\fP
.fi
.RE
.PP
برای تعیین اینکه آیا سبک \fBwidget\fP استفاده می‌شود یا خیر، مستندات ویجت یا تابع فراخواننده را بررسی کنید\&.
.RE
.PP
.SH "مدیریت استثناها (EXCEPTION HANDLING)"
.PP
دو تابع برای فعال کردن قابلیت مدیریت استثنا در zsh ارائه شده‌اند، به شکلی که باید برای کاربران سایر زبان‌ها آشنا باشد\&.
.PP
.PD 0
.TP
.PD
\fBthrow\fP \fIexception\fP
تابع \fBthrow\fP استثنای نام‌برده‌شدهٔ \fIexception\fP را پرتاب می‌کند\&. این نام یک رشتهٔ اختیاری است و تنها توسط توابع \fBthrow\fP و \fBcatch\fP استفاده می‌شود\&. با یک استثنا در بیشتر موارد همانند یک خطای شل رفتار می‌شود؛ یعنی یک استثنای مدیریت‌نشده باعث می‌شود شل تمام پردازش‌ها را در یک تابع یا اسکریپت متوقف کرده و در یک شل تعاملی به بالاترین سطح بازگردد\&.
.TP
\fBcatch\fP \fIexception\-pattern\fP
تابع \fBcatch\fP در صورتی که یک استثنا پرتاب شده باشد و الگوی \fIexception\-pattern\fP با نام آن مطابقت داشته باشد، وضعیت صفر را بازمی‌گرداند؛ در غیر این صورت وضعیت ۱ را بازمی‌گرداند\&. \fIexception\-pattern\fP یک الگوی استاندارد شل است که از تنظیمات فعلی گزینهٔ \fBEXTENDED_GLOB\fP پیروی می‌کند\&. همچنین نام مستعار \fBcatch\fP نیز تعریف شده است تا از تطبیق آرگومان تابع با نام فایل‌ها جلوگیری کند؛ بنابراین الگوها می‌توانند بدون نقل‌قول استفاده شوند\&. توجه داشته باشید از آنجا که استثناها تفاوت بنیادینی با سایر خطاهای شل ندارند، می‌توان خطاهای شل را با استفاده از یک رشتهٔ خالی به عنوان نام استثنا دریافت کرد\&. متغیر شل \fBCAUGHT\fP توسط \fBcatch\fP روی نام استثنای دریافت‌شده تنظیم می‌شود\&. پس از دریافت یک استثنا، می‌توان با فراخوانی مجدد تابع \fBthrow\fP آن را دوباره پرتاب کرد\&.
.PP
این توابع طوری طراحی شده‌اند که همراه با ساختار \fBalways\fP شرح‌داده‌شده در \fIzshmisc\fP(1) استفاده شوند\&. این موضوع اهمیت دارد زیرا تنها این ساختار پشتیبانی لازم را برای استثناها فراهم می‌کند\&. یک مثال متداول به شرح زیر است\&:
.PP
.RS
.nf
\fB{
  # "try" block
  # \&.\&.\&. nested code here calls "throw MyExcept"
} always {
  # "always" block
  if catch MyExcept; then
    print "Caught exception MyExcept"
  elif catch \&''; then
    print "Caught a shell error\&.  Propagating\&.\&.\&."
    throw \&''
  fi
  # Other exceptions are not handled but may be caught further
  # up the call stack\&.
}\fP
.fi
.RE
.PP
اگر لازم باشد همهٔ استثناها دریافت شوند، الگوی زیر ممکن است ترجیح داده شود\&:
.PP
.RS
.nf
\fB{
  # \&.\&.\&. nested code here throws an exception
} always {
  if catch *; then
    case $CAUGHT in
      (MyExcept)
      print "Caught my own exception"
      ;;
      (*)
      print "Caught some other exception"
      ;;
    esac
  fi
}\fP
.fi
.RE
.PP
مشابه مدیریت استثنا در سایر زبان‌ها، استثنا می‌تواند توسط کدی در اعماق بلوک `try\&' پرتاب شود\&. با این حال، توجه داشته باشید که این پرتاب باید درون شل جاری انجام شود، نه در یک زیرشل (subshell) که برای خط‌لوله (pipeline)، ساختار پرانتزبندی‌شدهٔ شل جاری، یا نوعی جایگزینی دستور یا فرایند ایجاد شده است\&.
.PP
سیستم در داخل از متغیر شل \fBEXCEPTION\fP برای ذخیرهٔ نام استثنا در فاصلهٔ بین پرتاب و دریافت استفاده می‌کند\&. یکی از معایب این طرح این است که اگر استثنا مدیریت نشود، متغیر \fBEXCEPTION\fP مقداردهی‌شده باقی می‌ماند و در صورت وقوع خطای بعدی در شل، ممکن است به اشتباه به عنوان نام یک استثنا شناخته شود\&. افزودن دستور \fBunset EXCEPTION\fP در ابتدای بیرونی‌ترین لایه از هر کدی که از مدیریت استثنا استفاده می‌کند، این مشکل را برطرف خواهد کرد\&.
.PP.SH "توابع MIME (MIME FUNCTIONS)"
.PP
سه تابع برای مدیریت فایل‌هایی که از روی پسوندشان شناسایی می‌شوند در دسترس هستند؛ برای نمونه برای ارسال فایلی مانند \fBtext\&.ps\fP هنگام اجرا به عنوان یک دستور، به یک نمایش‌دهندهٔ مناسب\&.
.PP
.PD 0
.TP
.PD 0
\fBzsh\-mime\-setup\fP [ \fB\-fv\fP ] [ \fB\-l\fP [ \fIsuffix\fP \&.\&.\&. ] ]
.TP
.PD
\fBzsh\-mime\-handler\fP [ \fB\-l\fP ] \fIcommand argument\fP \&.\&.\&.
این دو تابع از فایل‌های \fB~/\&.mime\&.types\fP و \fB/etc/mime\&.types\fP استفاده می‌کنند که انواع و پسوندها را مرتبط می‌سازند، و همچنین فایل‌های \fB~/\&.mailcap\fP و \fB/etc/mailcap\fP که انواع را به برنامه‌های گردانندهٔ آن‌ها مرتبط می‌کنند\&. این فایل‌ها در بسیاری از سیستم‌ها همراه با پسوندهای چندمنظورهٔ پست الکترونیکی اینترنت (MIME) ارائه می‌شوند\&.
.RS
.PP
برای فعال‌سازی سیستم، تابع \fBzsh\-mime\-setup\fP باید خودبارگذاری (autoload) و اجرا شود\&. این کار اجازه می‌دهد فایل‌های دارای پسوند به عنوان فایل اجرایی در نظر گرفته شوند؛ چنین فایل‌هایی می‌توانند توسط سیستم تکمیل خودکار تابع تکمیل شوند\&. نیازی نیست تابع \fBzsh\-mime\-handler\fP توسط کاربر فراخوانی شود\&.
.PP
این سیستم با تنظیم نام‌های مستعار پسوند با `\fBalias \-s\fP\&' کار می‌کند\&. نام‌های مستعار پسوندی که از پیش توسط کاربر نصب شده‌اند بازنویسی نخواهند شد\&.
.PP
برای پسوندهایی که با حروف کوچک تعریف شده‌اند، حالت‌های حروف بزرگ نیز به طور خودکار مدیریت خواهند شد (برای مثال، اگر مدیریت پسوند \fBpdf\fP تعریف شده باشد، \fBPDF\fP نیز به طور خودکار مدیریت می‌شود)، اما عکس آن برقرار نیست\&.
.PP
فراخوانی‌های مکرر \fBzsh\-mime\-setup\fP نگاشت موجود میان پسوندها و فایل‌های اجرایی را بازنویسی نمی‌کند، مگر اینکه گزینهٔ \fB\-f\fP داده شود\&. با این حال توجه داشته باشید که این کار نام‌های مستعار پسوند موجود را که به گرداننده‌هایی جز \fBzsh\-mime\-handler\fP اختصاص یافته‌اند بازنویسی نمی‌کند\&.
.PP
فراخوانی \fBzsh\-mime\-setup\fP با گزینهٔ \fB\-l\fP نگاشت‌های موجود را بدون تغییر دادن آن‌ها فهرست می‌کند\&. پسوندهایی که باید فهرست شوند (که ممکن است حاوی نویسه‌های الگویی باشند که برای جلوگیری از تفسیر فوری در خط فرمان باید نقل‌قول شوند) می‌توانند به عنوان آرگومان‌های اضافی داده شوند؛ در غیر این صورت، تمام پسوندها فهرست می‌شوند\&.
.PP
فراخوانی \fBzsh\-mime\-setup\fP با گزینهٔ \fB\-v\fP باعث می‌شود خروجی پرگو در طول عملیات راه‌اندازی نمایش داده شود\&.
.PP
این سیستم پرچم‌های \fBmailcap\fP یعنی \fBneedsterminal\fP و \fBcopiousoutput\fP را رعایت می‌کند؛ \fImailcap\fP(4) یا \fImailcap\fP(5) را ببینید (نام صفحهٔ راهنما در پلتفرم‌های مختلف متفاوت است)\&.
.PP
این توابع از سبک‌های زیر استفاده می‌کنند که با دستور توکار \fBzstyle\fP تعریف می‌شوند (به \fIzshmodules\fP(1) مراجعه کنید)\&. آن‌ها باید پیش از اجرای \fBzsh\-mime\-setup\fP تعریف شوند\&. زمینه‌های مورد استفاده همگی با \fB:mime:\fP آغاز می‌شوند و در برخی موارد اجزای دیگری نیز دارند\&. توصیه می‌شود که یک \fB*\fP در انتها (به صورت نقل‌قول‌شده مناسب) به الگوهای سبک الحاق شود تا در صورت گسترش سیستم در آینده مشکلی پیش نیاید\&. چند مثال در زیر آورده شده است\&.
.PP
برای فایل‌هایی که چند پسوند دارند، برای نمونه \fB\&.pdf\&.gz\fP، در جایی که زمینه شامل پسوند است، جستجو با طولانی‌ترین پسوند ممکن آغاز می‌شود تا زمانی که تطابقی برای سبک یافت شود\&. برای مثال، اگر \fB\&.pdf\&.gz\fP تطابقی برای گرداننده ایجاد کند، از آن استفاده خواهد شد؛ در غیر این صورت از گرداننده برای \fB\&.gz\fP استفاده می‌شود\&. توجه داشته باشید که به دلیل شیوهٔ کارکرد نام‌های مستعار پسوند، همواره لازم است که یک گرداننده برای کوتاه‌ترین پسوند ممکن وجود داشته باشد، بنابراین در این مثال \fB\&.pdf\&.gz\fP تنها در صورتی قابل مدیریت است که \fB\&.gz\fP نیز مدیریت شود (اگرچه نه لزوماً به همان روش)\&. از طرف دیگر، اگر به مدیریت مستقل \fB\&.gz\fP نیازی نیست، افزودن سادهٔ دستور
.PP
.RS
.nf
\fBalias \-s gz=zsh\-mime\-handler\fP
.fi
.RE
.PP
به کد مقداردهی اولیه کافی است؛ \fB\&.gz\fP به تنهایی مدیریت نخواهد شد، اما ممکن است در ترکیب با پسوندهای دیگر مدیریت شود\&.
.PP
.PD 0
.TP
.PD
\fBcurrent\-shell\fP
اگر این سبک بولی درست (true) باشد، گردانندهٔ mailcap برای زمینهٔ مورد نظر با استفاده از دستور توکار \fBeval\fP به جای راه‌اندازی یک فرایند جدید \fBsh\fP اجرا می‌شود\&. این روش کارآمدتر است، اما ممکن است در موارد نادری که گردانندهٔ mailcap از نحو دقیق POSIX استفاده می‌کند کار نکند\&.
.TP
\fBdisown\fP
اگر این سبک بولی درست (true) باشد، گرداننده‌های mailcap که در پس‌زمینه راه‌اندازی می‌شوند رها (disown) خواهند شد؛ یعنی مشمول کنترل کار (job control) در پوستهٔ والد نخواهند بود\&. چنین گرداننده‌هایی تقریباً همیشه پنجره‌های خود را ایجاد می‌کنند، بنابراین تنها اثر جانبی مضر احتمالیِ تنظیم این سبک آن است که متوقف کردن (kill) کارها از درون پوسته دشوارتر می‌شود\&.
.TP
\fBexecute\-as\-is\fP
این سبک فهرستی از الگوها را ارائه می‌دهد تا با فایل‌های ارسال‌شده برای اجرا توسط برنامهٔ گرداننده تطبیق داده شوند\&. اگر فایل با الگو تطابق داشته باشد، کل خط فرمان به شکل فعلی خود و بدون هیچ گرداننده‌ای اجرا می‌شود\&. این ویژگی برای فایل‌هایی که ممکن است پسوند داشته باشند اما خودشان فایلی اجرایی باشند مفید است\&. اگر این سبک تنظیم نشده باشد، الگوی \fB*(*) *(/)\fP استفاده می‌شود؛ بنابراین فایل‌های اجرایی مستقیماً اجرا شده و به گرداننده ارسال نمی‌شوند، و گزینهٔ \fBAUTO_CD\fP می‌تواند برای رفتن به دایرکتوری‌هایی استفاده شود که بر حسب اتفاق پسوندهای MIME دارند\&.
.TP
\fBexecute\-never\fP
این سبک در ترکیب با \fBexecute\-as\-is\fP مفید است\&. این سبک به آرایه‌ای از الگوها مربوط به مسیرهای کامل فایل‌هایی تنظیم می‌شود که هرگز نباید به عنوان فایل اجرایی تلقی شوند، حتی اگر فایل ارسال‌شده به گردانندهٔ MIME با \fBexecute\-as\-is\fP مطابقت داشته باشد\&. این ویژگی برای سیستم‌های فایلی که مجوز اجرا را پشتیبانی نمی‌کنند یا شامل فایل‌های اجرایی سیستم‌عامل دیگری هستند کاربرد دارد\&. برای نمونه، اگر \fB/mnt/windows\fP یک نقطهٔ اتصال ویندوز باشد، آنگاه
.RS
.PP
.RS
.nf
\fBzstyle \&':mime:*' execute\-never '/mnt/windows/*'\fP
.fi
.RE
.PP
اطمینان حاصل خواهد کرد که هر فایل موجود در آن ناحیه به عنوان انواع MIME اجرا شود، حتی اگر اجرایی باشد\&. همان‌طور که این مثال نشان می‌دهد، نام کامل فایل با الگو مطابقت داده می‌شود، صرف‌نظر از اینکه فایل چگونه به گرداننده ارسال شده است\&. فایل با استفاده از اصلاح‌گر \fB:P\fP که در زیربخش `Modifiers\&' در \fIzshexpn\fP(1) شرح داده شده به یک مسیر کامل حل می‌شود؛ این بدان معناست که پیوندهای نمادین تا حد امکان حل می‌شوند تا پیوندها به دیگر سیستم‌های فایل عملکرد صحیحی داشته باشند\&.
.RE
.TP
\fBfile\-path\fP
در صورتی استفاده می‌شود که سبک \fBfind\-file\-in\-path\fP برای همان زمینه درست (true) باشد\&. به آرایه‌ای از دایرکتوری‌ها تنظیم می‌شود که برای جستجوی فایلِ مورد نظر برای مدیریت استفاده می‌شوند؛ پیش‌فرض، مسیر دستوری است که با پارامتر ویژهٔ \fBpath\fP مشخص شده است\&. گزینهٔ پوسته \fBPATH_DIRS\fP رعایت می‌شود؛ اگر آن گزینه تنظیم شده باشد، مسیر مناسب جستجو خواهد شد حتی اگر نام فایل برای مدیریت، همان‌طور که در خط فرمان ظاهر می‌شود، حاوی یک `\fB/\fP\&' باشد\&. زمینهٔ کامل \fB:mime:\&.\fP\fIsuffix\fP\fB:\fP است، همان‌طور که برای سبک \fBhandler\fP توضیح داده شده است\&.
.TP
\fBfind\-file\-in\-path\fP
در صورت تنظیم، اجازه می‌دهد فایل‌هایی که نامشان شامل مسیر مطلق نیست در مسیر دستور یا مسیر مشخص‌شده با سبک \fBfile\-path\fP جستجو شوند\&. اگر فایل در مسیر یافت نشود، به صورت محلی جستجو می‌شود (چه دایرکتوری جاری در مسیر باشد یا نباشد)؛ اگر به صورت محلی نیز یافت نشود، گرداننده لغو خواهد شد مگر اینکه سبک \fBhandle\-nonexistent\fP تنظیم شده باشد\&. فایل‌های یافت‌شده در مسیر همان‌طور که برای سبک \fBexecute\-as\-is\fP شرح داده شد آزمایش می‌شوند\&. زمینهٔ کامل \fB:mime:\&.\fP\fIsuffix\fP\fB:\fP است، همان‌طور که برای سبک \fBhandler\fP شرح داده شده است\&.
.TP
\fBflags\fP
پرچم‌های همراه با یک گرداننده را تعریف می‌کند؛ زمینه مانند سبک \fBhandler\fP است، و قالب آن همانند پرچم‌ها در \fBmailcap\fP می‌باشد\&.
.TP
\fBhandle\-nonexistent\fP
به طور پیش‌فرض، آرگومان‌هایی که با فایل‌ها مطابقت ندارند به گردانندهٔ MIME ارسال نمی‌شوند تا از رهگیری دستورهای موجود در مسیر که بر حسب اتفاق پسوند دارند جلوگیری شود\&. این سبک ممکن است به آرایه‌ای از الگوهای glob گسترش‌یافته برای آرگومان‌هایی تنظیم شود که حتی در صورت عدم وجود به گرداننده ارسال خواهند شد\&. اگر صریحاً تنظیم نشده باشد، مقدار پیش‌فرض آن \fB[[:alpha:]]#:/*\fP است که اجازه می‌دهد URLها به گردانندهٔ MIME ارسال شوند، حتی اگر با آن قالب در سیستم فایل وجود نداشته باشند\&. زمینهٔ کامل \fB:mime:\&.\fP\fIsuffix\fP\fB:\fP است، همان‌طور که برای سبک \fBhandler\fP توصیف شده است\&.
.TP
\fBhandler\fP
گرداننده‌ای را برای یک پسوند مشخص می‌کند؛ پسوند بر اساس زمینه به شکل \fB:mime:\&.\fP\fIsuffix\fP\fB:\fP داده می‌شود و قالب گرداننده دقیقاً همان قالب موجود در \fBmailcap\fP است\&. به طور ویژه به `\fB\&.\fP\&' و دونقطهٔ پایانی برای متمایز کردن این استفاده از زمینه دقت کنید\&. این سبک هر گرداننده‌ای را که توسط فایل‌های \fBmailcap\fP مشخص شده باشد بازنویسی می‌کند\&. اگر گرداننده به یک پایانه نیاز داشته باشد، سبک \fBflags\fP باید طوری تنظیم شود که شامل کلمهٔ \fBneedsterminal\fP باشد، یا اگر قرار است خروجی از طریق یک صفحه‌بند (pager) نمایش داده شود (اما نه در صورتی که گرداننده خودش یک صفحه‌بند باشد)، باید شامل \fBcopiousoutput\fP باشد\&.
.TP
\fBmailcap\fP
فهرستی از فایل‌ها در قالب \fB~/\&.mailcap\fP و \fB/etc/mailcap\fP که هنگام راه‌اندازی خوانده می‌شوند و جایگزین فهرست پیش‌فرض شامل آن دو فایل خواهند شد\&. زمینهٔ آن \fB:mime:\fP است\&. یک \fB+\fP در فهرست با فایل‌های پیش‌فرض جایگزین خواهد شد\&..TP
\fBmailcap\-priorities\fP
این سبک برای رفع ابهام میان چندین مدخل mailcap برای یک نوع MIME یکسان به کار می‌رود\&. این سبک از آرایه‌ای از عناصر زیر به ترتیب نزولی اولویت تشکیل شده است؛ در صورتی که مدخل‌های ابتدایی نتوانند مدخل‌های در حال مقایسه را تفکیک کنند، از مدخل‌های بعدی استفاده خواهد شد\&. اگر هیچ‌یک از آزمون‌ها نتواند مدخل‌ها را تعیین تکلیف کند، نخستین مدخل دیده‌شده حفظ می‌شود\&.
.RS
.PP
.PD 0
.TP
.PD
\fBfiles\fP
ترتیب فایل‌های خوانده‌شده (مدخل‌ها در سبک \fBmailcap\fP)\&. فایل‌های اولویت‌دارتر ترجیح داده می‌شوند\&. (توجه داشته باشید که این آزمون ابهام میان مدخل‌های موجود در یک فایل را برطرف نمی‌کند\&.)
.TP
\fBpriority\fP
پرچم اولویت برگرفته از مدخل mailcap\&. این اولویت یک عدد صحیح از 0 تا 9 با مقدار پیش‌فرض 5 است\&.
.TP
\fBflags\fP
آزمون ارائه‌شده توسط گزینهٔ \fBmailcap\-prio\-flags\fP برای تفکیک مدخل‌ها استفاده می‌شود\&.
.TP
\fBplace\fP
مدخل‌های بعدی ارجحیت دارند؛ از آنجا که مدخل‌ها دارای ترتیبی اکید هستند، این آزمون همواره موفق خواهد بود\&.
.PP
توجه داشته باشید که چون این سبک در هنگام مقداردهی اولیه پردازش می‌شود، بافت همواره \fB:mime:\fP است و هیچ تمایزی بر اساس پسوند صورت نمی‌گیرد\&.
.RE
.TP
\fBmailcap\-prio\-flags\fP
این سبک هنگامی به کار می‌رود که کلیدواژهٔ \fBflags\fP در فهرست آزمون‌های مشخص‌شده توسط سبک \fBmailcap\-priorities\fP دیده شود\&.
این سبک باید روی فهرستی از الگوها تنظیم شود که هر یک در برابر پرچم‌های مشخص‌شده در مدخل mailcap (به عبارت دیگر، مجموعه‌های انتساب موجود در برخی مدخل‌های فایل mailcap) سنجیده می‌شوند\&. الگوهای ابتدایی فهرست نسبت به الگوهای انتهایی اولویت دارند، و الگوهای منطبق‌شده بر الگوهای منطبق‌نشده ترجیح داده می‌شوند\&.
.TP
\fBmime\-types\fP
فهرستی از فایل‌ها با قالب \fB~/\&.mime\&.types\fP و \fB/etc/mime\&.types\fP که باید در طول راه‌اندازی خوانده شوند و جایگزین فهرست پیش‌فرض متشکل از این دو فایل گردند\&. بافت \fB:mime:\fP است\&.
علامت \fB+\fP در فهرست با فایل‌های پیش‌فرض جایگزین خواهد شد\&.
.TP
\fBnever\-background\fP
اگر این سبک بولی تنظیم شود، گرداننده برای بافت داده‌شده همواره در پیش‌زمینه اجرا می‌شود، حتی اگر پرچم‌های ارائه‌شده در مدخل mailcap نشان دهند که نیازی به آن نیست (برای نمونه، نیازی به ترمینال ندارد)\&.
.TP
\fBpager\fP
در صورت تنظیم، به جای \fB$PAGER\fP یا \fBmore\fP برای مدیریت پسوندهایی که پرچم \fBcopiousoutput\fP برای آن‌ها فعال است استفاده خواهد شد\&. بافت همانند \fBhandler\fP است، یعنی \fB:mime:\&.\fP\fIsuffix\fP\fB:\fP برای مدیریت فایلی با \fIsuffix\fP مشخص‌شده\&.
.PP
مثال‌ها:
.PP
.RS
.nf
\fBzstyle \&':mime:*' mailcap ~/\&.mailcap /usr/local/etc/mailcap
zstyle \&':mime:\&.txt:' handler less %s
zstyle \&':mime:\&.txt:' flags needsterminal\fP
.fi
.RE
.PP
هنگامی که \fBzsh\-mime\-setup\fP متعاقباً اجرا شود، به دنبال مدخل‌های \fBmailcap\fP در دو فایل ارائه‌شده می‌گردد\&. فایل‌هایی با پسوند \fB\&.txt\fP با اجرای `\fBless\fP \fIfile\&.txt\fP\&' مدیریت خواهند شد\&. پرچم \fBneedsterminal\fP تنظیم شده است تا نشان دهد این برنامه باید به صورت متصل به یک ترمینال اجرا شود\&.
.PP
از آنجا که ارسال یک دستور شامل چندین مرحله است، در صورتی که تلاش برای اجرای یک فایل بر اساس پسوند \fB\&.\fP\fIext\fP تأثیر مورد انتظار را به همراه نداشت، موارد زیر باید بررسی شوند\&.
.PP
دستور `\fBalias \-s\fP \fIext\fP\&' باید `\fBps=zsh\-mime\-handler\fP\&' را نمایش دهد\&. اگر چیز دیگری نشان دهد، به این معنی است که نام مستعار دیگری برای این پسوند از قبل نصب بوده و بازنویسی نشده است\&. اگر چیزی نشان ندهد، هیچ گرداننده‌ای نصب نشده است: این موضوع احتمالاً به این دلیل است که هیچ گرداننده‌ای در ترکیب \fB\&.mime\&.types\fP و \fBmailcap\fP برای فایل‌های \fB\&.ext\fP پیدا نشده است\&. در این حالت، مدیریت مناسب باید به \fB~/\&.mime\&.types\fP و \fBmailcap\fP اضافه شود\&.
.PP
اگر پسوند توسط \fBzsh\-mime\-handler\fP مدیریت می‌شود اما فایل به درستی باز نمی‌شود، یا گردانندهٔ تعریف‌شده برای این نوع نادرست است، یا پرچم‌های مرتبط با آن نامناسب هستند\&. اجرای \fBzsh\-mime\-setup \-l\fP گرداننده و در صورت وجود، پرچم‌ها را نشان خواهد داد\&. یک \fB%s\fP در گرداننده با فایل (در صورت لزوم با نقل‌قول مناسب) جایگزین می‌شود\&. بررسی کنید که برنامهٔ گردانندهٔ فهرست‌شده وجود داشته باشد و بتواند به شیوهٔ نشان داده شده اجرا شود\&. همچنین بررسی کنید که در صورت نیاز به اجرای گرداننده در ترمینال، پرچم‌های \fBneedsterminal\fP یا \fBcopiousoutput\fP تنظیم شده باشند؛ پرچم دوم زمانی استفاده می‌شود که خروجی باید به یک صفحه‌بند (pager) ارسال شود\&. نمونه‌ای از یک مدخل مناسب در \fBmailcap\fP برای چنین برنامه‌ای:
.PP
.RS
.nf
\fBtext/html; /usr/bin/lynx \&'%s'; needsterminal\fP
.fi
.RE
.PP
اجرای `\fBzsh\-mime\-handler \-l\fP \fIcommand line\fP\&' خط فرمانی را که اجرا خواهد شد چاپ می‌کند، ساده‌شده تا اثر هرگونه پرچم حذف شود، و با نقل‌قول مناسب تا خروجی بتواند به عنوان یک خط فرمان کامل zsh اجرا گردد\&. این مورد توسط سامانهٔ تکمیل برای تصمیم‌گیری دربارهٔ نحوهٔ تکمیل پس از فایلی که توسط \fBzsh\-mime\-setup\fP مدیریت می‌شود، به کار می‌رود\&.
.RE
.TP
\fBpick\-web\-browser\fP
این تابع از دو تابع MIME شرح داده شده در بالا مجزاست و می‌تواند مستقیماً به یک پسوند اختصاص یابد:
.RS
.PP
.RS
.nf
\fBautoload \-U pick\-web\-browser
alias \-s html=pick\-web\-browser\fP
.fi
.RE
.PP
این ابزار به عنوان یک پیشانهٔ هوشمند برای هدایت و اجرای مرورگر وب ارائه شده است\&. این مورد می‌تواند به عنوان یک تابع یا یک اسکریپت شل اجرا شود\&. در صورتی که هیچ مرورگری نتواند راه‌اندازی شود، وضعیت خروج 255 بازگردانده می‌شود\&.
.PP
سبک‌های گوناگونی برای سفارشی‌سازی انتخاب مرورگرها در دسترس است:
.PP
.PD 0
.TP
.PD
\fBbrowser\-style\fP
مقدار این سبک آرایه‌ای است که اولویت‌ها را به ترتیب نزولی برای نوع مرورگر مورد استفاده مشخص می‌کند\&. مقادیر عناصر می‌توانند شامل موارد زیر باشند:
.RS
.PP
.PD 0
.TP
.PD
\fBrunning\fP
استفاده از یک مرورگر گرافیکی (GUI) که در صورت در دسترس بودن نمایشگر X Window، هم‌اکنون در حال اجرا است\&. مرورگرهای فهرست‌شده در سبک \fBx\-browsers\fP به ترتیب بررسی می‌شوند تا یکی یافت شود؛ در صورت یافتن، فایل در آن مرورگر نمایش داده خواهد شد، بنابراین ممکن است لازم باشد کاربر بررسی کند که آیا فایل نمایش داده شده است یا خیر\&. اگر مرورگر در حال اجرایی یافت نشود، مرورگری آغاز به کار نخواهد کرد\&. برای مرورگرهایی به جز Firefox، Opera و Konqueror فرض می‌شود که نحو Mozilla را برای باز کردن URL از راه دور درک می‌کنند\&.
.TP
\fBx\fP
راه‌اندازی یک مرورگر گرافیکی جدید در هنگام در دسترس بودن نمایشگر X Window\&. در دسترس بودن یکی از مرورگرهای فهرست‌شده در سبک \fBx\-browsers\fP جستجو شده و نخستین موردی که یافت شود اجرا می‌گردد\&. هیچ بررسی‌ای برای مرورگری که از قبل در حال اجرا باشد انجام نمی‌شود\&.
.TP
\fBtty\fP
راه‌اندازی یک مرورگر مبتنی بر ترمینال\&. در دسترس بودن یکی از مرورگرهای فهرست‌شده در سبک \fBtty\-browsers\fP جستجو شده و نخستین موردی که یافت شود اجرا می‌گردد\&.
.PP
اگر این سبک تنظیم نشده باشد، مقدار پیش‌فرض \fBrunning x tty\fP استفاده می‌شود\&.
.RE
.TP
\fBx\-browsers\fP
آرایه‌ای با اولویت نزولی از مرورگرها برای استفاده در هنگام اجرا تحت سامانهٔ X Window System\&. این آرایه شامل نام دستوری است که مرورگر با آن راه‌اندازی می‌شود\&. این موارد در بافت \fB:mime:\fP جستجو می‌شوند (که ممکن است در آینده گسترش یابد، بنابراین افزودن `\fB*\fP\&' توصیه می‌شود)\&. برای نمونه،
.RS
.PP
.RS
.nf
\fBzstyle \&':mime:*' x\-browsers opera konqueror firefox\fP
.fi
.RE
.PP
مشخص می‌کند که \fBpick\-web\-browser\fP ابتدا باید به دنبال یک نمونهٔ در حال اجرای Opera، Konqueror یا Firefox، به همین ترتیب بگردد، و اگر هیچ‌کدام را پیدا نکرد تلاش کند تا Opera را راه‌اندازی نماید\&. مقدار پیش‌فرض \fBfirefox mozilla netscape opera konqueror\fP است\&.
.RE.TP
\fBtty\-browsers\fP
آرایه‌ای مشابه با \fBx\-browsers\fP، با این تفاوت که مرورگرهایی را مشخص می‌کند که در صورت در دسترس نبودن نمایشگر X Window باید استفاده شوند\&. مقدار پیش‌فرض
\fBelinks links lynx\fP است\&.
.TP
\fBcommand\fP
در صورت تنظیم، این سبک (style) برای انتخاب دستوری استفاده می‌شود که جهت باز کردن یک صفحه برای مرورگر به کار می‌رود\&. بافت (context) برای راه‌اندازی یک مرورگر جدید،
\fB:mime:browser:new:$browser:\fP و برای باز کردن یک URL در مرورگری که از پیش در نمایشگر فعلی X در حال اجرا است،
\fB:mime:browser:running:$browser:\fP می‌باشد؛ که در آن \fB$browser\fP مقداری است که در سبک
\fBx\-browsers\fP یا \fBtty\-browsers\fP تطبیق داده شده است\&. توالی گریز
\fB%b\fP در مقدار این سبک، با مرورگر و \fB%u\fP با URL جایگزین خواهد شد\&. اگر این سبک تنظیم نشده باشد، مقدار پیش‌فرض برای تمام نمونه‌های جدید معادل \fB%b %u\fP است و مقادیر پیش‌فرض برای استفاده از مرورگرهای در حال اجرا معادل مقادیر \fBkfmclient openURL %u\fP برای
Konqueror، \fBfirefox \-new\-tab %u\fP برای Firefox، \fBopera \-newpage %u\fP
برای Opera، و \fB%b \-remote "openUrl(%u)"\fP برای سایر موارد است\&.
.RE
.PP
.SH "توابع ریاضی (MATHEMATICAL FUNCTIONS)"
.PP
.PD 0
.TP
.PD
\fBzcalc\fP [ \fB\-erf\fP ] [ \fIexpression\fP \&.\&.\&. ]
یک ماشین‌حساب نسبتاً قدرتمند بر پایهٔ سازوکار ارزیابی محاسباتی zsh\&. نحو آن مشابه فرمول‌ها در بیشتر زبان‌های برنامه‌نویسی است؛ برای جزئیات،
بخش `Arithmetic Evaluation\&' در \fIzshmisc\fP(1) را ببینید\&.
.RS
.PP
افراد غیربرنامه‌نویس باید توجه داشته باشند که همانند بسیاری از زبان‌های برنامه‌نویسی دیگر، عبارت‌هایی که فقط شامل اعداد صحیح هستند (خواه ثابت‌های بدون `\fB\&.\fP\&'، متغیرهای حاوی چنین ثابت‌هایی به صورت رشته، یا متغیرهایی که به عنوان عدد صحیح اعلان شده‌اند) به‌طور پیش‌فرض با استفاده از محاسبات اعداد صحیح ارزیابی می‌شوند، که روش کار ماشین‌حساب‌های رومیزی معمولی نیست\&. برای اجبار عملیات ممیز شناور، گزینهٔ \fB\-f\fP را ارسال کنید؛
یادداشت‌های بیشتر در زیر را ببینید\&.
.PP
اگر فایل \fB~/\&.zcalcrc\fP وجود داشته باشد، پس از راه‌اندازی تابع و هنگامی که در آستانهٔ پردازش خط فرمان است، درون تابع سورس (source) می‌شود\&. این کار می‌تواند برای مثال جهت تنظیم گزینه‌های پوسته استفاده شود؛ در این مرحله \fBemulate \-L zsh\fP
و \fBsetopt extendedglob\fP فعال هستند\&. در صورت وجود فایل، هرگونه شکست در بارگذاری (source کردن) آن بحرانی (fatal) تلقی می‌شود\&.
همانند سایر فایل‌های مقداردهی اولیه، در صورت تنظیم بودن دایرکتوری \fB$ZDOTDIR\fP، به جای \fB$HOME\fP از آن استفاده می‌شود\&.
.PP
کتابخانهٔ ریاضی \fBzsh/mathfunc\fP در صورت در دسترس بودن بارگذاری خواهد شد؛
بخش `The zsh/mathfunc Module\&' را در \fIzshmodules\fP(1) ببینید\&. توابع ریاضی متناظر با کتابخانه‌های خام سیستم هستند، بنابراین توابع مثلثاتی با استفاده از رادیان ارزیابی می‌شوند و غیره\&.
.PP
هر خط تایپ‌شده به عنوان یک عبارت ارزیابی می‌شود\&. اعلان (prompt) عددی را نشان می‌دهد که متناظر با یک پارامتر مکانی است که نتیجهٔ آن محاسبه در آن ذخیره می‌شود\&. برای مثال، نتیجهٔ محاسبه در خطی که پیش از آن `\fB4> \fP\&' آمده است به صورت \fB$4\fP در دسترس خواهد بود\&. آخرین مقدار محاسبه‌شده به صورت \fBans\fP در دسترس است\&. قابلیت ویرایش کامل خط فرمان، شامل تاریخچهٔ محاسبات پیشین، در دسترس است؛ این تاریخچه در فایل \fB~/\&.zcalc_history\fP ذخیره می‌شود\&. برای خروج، یک خط خالی وارد کنید یا به تنهایی `\fB:q\fP\&' را تایپ کنید (استفاده از `\fBq\fP\&' به دلایل سازگاری تاریخی مجاز است)\&.
.PP
خطی که به یک تک‌بک‌اسلش ختم می‌شود همانند ویرایش خط فرمان رفتار می‌کند: بک‌اسلش حذف شده، تابع ورودی بیشتری درخواست می‌کند (اعلان با `\fB\&.\&.\&.\fP\&' پیشوند می‌شود تا این موضوع را نشان دهد)، و خطوط با یکدیگر ترکیب می‌شوند تا نتیجهٔ نهایی حاصل شود\&. علاوه بر این، اگر ورودی تا آن نقطه حاوی پرانتزهای باز بیشتری نسبت به پرانتزهای بسته باشد، \fBzcalc\fP ورودی بیشتری را درخواست خواهد کرد\&.
.PP
اگر آرگومان‌هایی در زمان راه‌اندازی به \fBzcalc\fP داده شود، از آن‌ها برای پر کردن اولیهٔ اولین پارامترهای مکانی استفاده می‌شود\&. هنگام شروع به کار ماشین‌حساب، یک نشانگر بصری از این موضوع نمایش داده می‌شود\&.
.PP
ثابت‌های \fBPI\fP (3\&.14159\&.\&.\&.) و \fBE\fP (2\&.71828\&.\&.\&.) فراهم شده‌اند\&.
انتساب پارامتر امکان‌پذیر است، اما توجه داشته باشید که تمامی پارامترها در فضای نام سراسری (global namespace) قرار خواهند گرفت، مگر اینکه از دستور ویژهٔ \fB:local\fP استفاده شود\&. این تابع متغیرهای محلی ایجاد می‌کند که نام آن‌ها با
\fB_\fP آغاز می‌شود، بنابراین کاربران باید از انجام این کار خودداری کنند\&. به متغیرهای \fBans\fP (آخرین پاسخ) و \fBstack\fP (پشته در حالت RPN) می‌توان مستقیماً ارجاع داد؛ \fBstack\fP یک آرایه است اما عناصر آن عددی هستند\&. متغیرهای ویژهٔ متعدد دیگری با معانی استاندارد خود به صورت محلی استفاده می‌شوند، برای مثال \fBcompcontext\fP، \fBmatch\fP، \fBmbegin\fP، \fBmend\fP، \fBpsvar\fP\&.
.PP
مبنای خروجی را می‌توان با ارسال گزینهٔ `\fB\-#\fP\fIbase\fP\&' مقداردهی اولیه کرد، برای مثال `\fBzcalc \-#16\fP\&' (بسته به گزینه‌های globbing تنظیم‌شده، ممکن است نیاز به نقل‌قول کردن `\fB#\fP' باشد)\&.
.PP
اگر گزینهٔ `\fB\-e\fP\&' تنظیم شده باشد، تابع به‌صورت غیرتعاملی اجرا می‌شود: با آرگومان‌ها به عنوان عبارت‌هایی رفتار می‌شود که باید ارزیابی شوند، گویی خط به خط به صورت تعاملی وارد شده‌اند\&.
.PP
اگر گزینهٔ `\fB\-f\fP\&' تنظیم شده باشد، با تمام اعداد به عنوان ممیز شناور رفتار می‌شود، بنابراین برای مثال عبارت `\fB3/4\fP\&' به جای 0 به 0\&.75 ارزیابی می‌شود\&. گزینه‌ها باید در کلمات مجزا قرار گیرند\&.
.PP
اگر گزینهٔ `\fB\-r\fP\&' تنظیم شده باشد، حالت RPN (نشانه‌گذاری معکوس لهستانی) فعال می‌شود\&. این حالت ویژگی‌های اضافی گوناگونی دارد:
.PD 0
.TP
.PD
پشته (Stack)
مقادیر ارزیابی‌شده در یک پشته نگهداری می‌شوند؛ این در آرایه‌ای به نام \fBstack\fP قرار دارد که جدیدترین مقدار آن در \fB${stack[1]}\fP است\&.
.TP
عملگرها و توابع (Operators and functions)
اگر خط واردشده با یک عملگر (\fB+\fP، \fB\-\fP، \fB*\fP،
\fB/\fP، \fB**\fP، \fB^\fP، \fB|\fP یا \fB&\fP) یا تابعی ارائه‌شده توسط کتابخانهٔ
\fBzsh/mathfunc\fP مطابقت داشته باشد، عنصر یا عناصر پایینی پشته برداشته (pop) می‌شوند تا به عنوان آرگومان یا آرگومان‌ها استفاده گردند\&. عناصر بالاتر پشته (قدیمی‌ترین‌ها) به عنوان آرگومان‌های پیشین استفاده می‌شوند\&. سپس نتیجه به درون \fB${stack[1]}\fP رانده (push) می‌شود\&.
.TP
عبارت‌ها (Expressions)
سایر عبارت‌ها به صورت عادی ارزیابی شده، چاپ می‌شوند و به عنوان مقادیر عددی به پشته اضافه می‌گردند\&. نحو درون عبارت‌ها در یک خط منفرد، محاسبات استاندارد پوسته است (نه RPN)\&.
.TP
فهرست پشته (Stack listing)
اگر بلافاصله و بدون فاصله بعد از گزینهٔ \fB\-r\fP یک عدد صحیح بیاید، در هر ارزیابی به همان تعداد از عناصر پشته، در صورت وجود، به جای فقط جدیدترین نتیجه چاپ می‌شوند\&. بنابراین، برای مثال،
\fBzcalc \-r4\fP هر بار که نتایج چاپ می‌شوند، \fB$stack[4]\fP تا \fB$stack[1]\fP را نشان می‌دهد\&.
.TP
تکثیر: \fB=\fP
شبه‌عملگر \fB=\fP باعث می‌شود جدیدترین عنصر پشته در پشته تکثیر شود\&.
.TP
\fBpop\fP
شبه‌تابع \fBpop\fP باعث می‌شود جدیدترین عنصر پشته برداشته (pop) شود\&. یک `\fB>\fP\&' به تنهایی نیز همین اثر را دارد\&.
.TP
\fB>\fP\fIident\fP
عبارت \fB>\fP که بدون فاصله یک شناسهٔ پوسته به دنبال آن بیاید، باعث می‌شود جدیدترین عنصر پشته pop شده و به متغیری با آن نام انتساب یابد\&. این متغیر برای تابع \fBzcalc\fP محلی است\&.
.TP
\fB<\fP\fIident\fP
عبارت \fB<\fP که بدون فاصله یک شناسهٔ پوسته به دنبال آن بیاید، باعث می‌شود مقدار متغیری با آن نام به درون پشته push شود\&. \fIident\fP می‌تواند یک عدد صحیح باشد، که در این صورت نتیجهٔ قبلی با آن شماره (همان‌طور که پیش از \fB>\fP در اعلان استاندارد \fBzcalc\fP نشان داده شده) در پشته قرار می‌گیرد\&.
.TP
تبادل: \fBxy\fP
شبه‌تابع \fBxy\fP باعث می‌شود دو عنصر آخر پشته با یکدیگر جابه‌جا شوند\&. `\fB<>\fP\&' نیز همین اثر را دارد\&.
.PP
اعلان (prompt) از طریق پارامتر \fBZCALCPROMPT\fP قابل پیکربندی است که تحت بسط استاندارد اعلان قرار می‌گیرد\&. اندیس ورودی جاری به صورت محلی در اولین عنصر آرایهٔ \fBpsvar\fP ذخیره می‌شود که می‌توان در \fBZCALCPROMPT\fP به عنوان `\fB%1v\fP\&' به آن ارجاع داد\&. اعلان پیش‌فرض
`\fB%1v> \fP\&' است\&.
.PP
متغیر \fBZCALC_ACTIVE\fP درون تابع مقداردهی می‌شود و توسط توابع تو در تو قابل بررسی است؛ این متغیر در صورت فعال بودن حالت RPN دارای مقدار \fBrpn\fP، و در غیر این صورت مقدار 1 خواهد بود\&.
.PP
چند دستور ویژه در دسترس هستند؛ این دستورها با یک دونقطه (:) آغاز می‌شوند\&.
به منظور سازگاری با نسخه‌های پیشین، دونقطه ممکن است برای برخی دستورها نادیده گرفته شود\&. اگر \fBcompinit\fP اجرا شده باشد، قابلیت تکمیل خودکار (completion) در دسترس خواهد بود\&.
.PP
دقت خروجی را می‌توان درون zcalc با دستورهای ویژه‌ای که در بسیاری از ماشین‌حساب‌ها آشنا هستند تعیین کرد\&.
.PD 0
.TP
.PD
\fB:norm\fP
قالب خروجی پیش‌فرض\&. این گزینه متناظر با مشخصهٔ \fB%g\fP در printf است\&. معمولاً شش رقم اعشار را نشان می‌دهد\&.
.TP
\fB:sci\fP \fIdigits\fP
نماد علمی، متناظر با قالب خروجی \fB%g\fP در printf با دقتی که توسط \fIdigits\fP تعیین شده است\&. این گزینه بسته به مقدار خروجی، نماد ممیز ثابت یا نمایی تولید می‌کند\&.
.TP
\fB:fix\fP \fIdigits\fP
نماد ممیز ثابت، متناظر با قالب خروجی \fB%f\fP در printf با دقتی که توسط \fIdigits\fP تعیین شده است\&..TP
\fB:eng\fP \fIdigits\fP
نماد علمی (نمایی)، متناظر با قالب خروجی \fB%E\fP در printf با دقت تعیین‌شده توسط \fIdigits\fP\&.
.TP
\fB:raw\fP
خروجی خام: این حالت پیش‌فرض خروجی ارزیابی‌های ریاضی است\&. ممکن است دقتی بیش از آن‌چه عدد واقعاً دارد را نمایش دهد\&.
.PP
سایر دستورهای ویژه:
.PD 0
.TP
.PD
\fB:!\fP\fIline\&.\&.\&.\fP
اجرای \fIline\&.\&.\&.\fP به عنوان یک خط فرمان عادی شل\&. توجه داشته باشید که این دستور در زمینه (context) تابع اجرا می‌شود، یعنی با متغیرهای محلی\&.
فاصله بعد از \fB:!\fP اختیاری است\&.
.TP
\fB:local\fP \fIarg\fP \&.\&.\&.
اعلان متغیرهای محلی برای تابع\&. سایر متغیرها نیز می‌توانند استفاده شوند، اما از دامنهٔ سراسری (global scope) خوانده شده یا در آن قرار می‌گیرند\&.
.TP
\fB:function\fP \fIname\fP [ \fIbody\fP ]
تعریف یک تابع ریاضی یا (بدون \fIbody\fP) حذف آن\&.
\fB:function\fP می‌تواند به \fB:func\fP یا صرفاً \fB:f\fP خلاصه شود\&.
\fIname\fP می‌تواند حاوی همان نویسه‌های مجاز در نام توابع شل باشد\&.
این تابع با استفاده از \fBzmathfuncdef\fP تعریف می‌شود، به بخش زیر مراجعه کنید\&.
.RS
.PP
توجه داشته باشید که \fBzcalc\fP خودش تمام نقل‌قول‌ها (quoting) را مدیریت می‌کند\&. بنابراین برای مثال:
.PP
.RS
.nf
\fB:f cube $1 * $1 * $1\fP
.fi
.RE
.PP
تابعی را برای مکعب کردن (به توان ۳ رساندن) تک‌آرگومان ورودی تعریف می‌کند\&. توابعی که بدین شکل تعریف شوند، یا در واقع هر تابعی که مستقیماً یا غیرمستقیم با استفاده از \fBfunctions \-M\fP تعریف شده باشد، در حالت RPN تنها با وارد کردن نامشان روی خط قابل اجرا هستند؛ این کار تعداد آرگومان مناسب را از پشته واکشی می‌کند (pop) تا به تابع تحویل دهد، یعنی ۱ مورد در مثال تابع \fBcube\fP\&. اگر آرگومان‌های اختیاری وجود داشته باشد، از این طریق فقط آرگومان‌های اجباری تأمین می‌شوند\&.
.RE
.TP
\fB[#\fP\fIbase\fP\fB]\fP
این یک دستور ویژه نیست، بلکه بخشی از نحو محاسباتی عادی است؛ با این حال، هرگاه این ساختار به‌تنهایی روی یک خط ظاهر شود مبنای (radix) پیش‌فرض خروجی روی \fIbase\fP تنظیم می‌شود\&. برای مثال، از `\fB[#16]\fP\&' برای نمایش خروجی هگزادسیمال همراه با نشانگر مبنا، یا `\fB[##16]\fP\&' برای نمایش مستقیم عدد خام در مبنای داده‌شده استفاده کنید\&. خود مبناها همیشه در مبنای ده‌دهی مشخص می‌شوند\&. عبارت `\fB[#]\fP\&' قالب خروجی عادی را بازمی‌گرداند\&.
توجه داشته باشید که تنظیم مبنای خروجی، خروجی ممیز شناور را غیرفعال می‌کند؛ برای بازگشت به عملکرد عادی از `\fB[#]\fP\&' استفاده کنید\&.
.TP
\fB$\fP\fIvar\fP
مقدار var را به‌صورت مستقیم چاپ می‌کند؛ این عمل تأثیری بر محاسبات ندارد\&.
برای استفاده از مقدار var، علامت `\fB$\fP\&' ابتدایی را حذف کنید\&.
.PP
برای چند نکتهٔ اضافی، توضیحات (کامنت‌های) درون تابع را ببینید\&.
.RE
.TP
.PD 0
\fBmin(\fP\fIarg\fP\fB, \&.\&.\&.)\fP
.TP
.PD 0
\fBmax(\fP\fIarg\fP\fB, \&.\&.\&.)\fP
.TP
.PD 0
\fBsum(\fP\fIarg\fP\fB, \&.\&.\&.)\fP
.TP
.PD
\fBzmathfunc\fP
تابع \fBzmathfunc\fP سه تابع ریاضی \fBmin\fP، \fBmax\fP و \fBsum\fP را تعریف می‌کند\&. توابع \fBmin\fP و \fBmax\fP یک یا چند آرگومان می‌پذیرند\&. تابع \fBsum\fP صفر یا چند آرگومان می‌گیرد\&.
آرگومان‌ها می‌توانند از انواع متفاوتی باشند (صحیح و ممیز شناور)\&.
.RS
.PP
با ماژول \fBzsh/mathfunc\fP که در بخش `The zsh/mathfunc Module\&' از \fIzshmodules\fP(1) شرح داده شده است، اشتباه گرفته نشود\&.
.RE
.TP
\fBzmathfuncdef\fP [ \fImathfunc\fP [ \fIbody\fP ] ]
یک رابط کاربری مناسب برای \fBfunctions \-M\fP\&.
.RS
.PP
با دو آرگومان، یک تابع ریاضی به نام \fImathfunc\fP تعریف می‌کند که در هر شکلی از ارزیابی‌های حسابی قابل استفاده است\&. \fIbody\fP یک عبارت ریاضی برای پیاده‌سازی تابع است\&. این عبارت ممکن است شامل ارجاعاتی به پارامترهای مکانی \fB$1\fP، \fB$2\fP و \&.\&.\&. برای اشاره به پارامترهای اجباری و \fB${1:\-\fP\fIdefvalue\fP\fB}\fP و \&.\&.\&. برای اشاره به پارامترهای اختیاری باشد\&. توجه داشته باشید که این ساختارها باید دقیقاً رعایت شوند تا تابع بتواند تعداد صحیح آرگومان‌ها را محاسبه کند\&. پیاده‌سازی در یک تابع شل به نام \fBzsh_math_func_\fP\fImathfunc\fP نگهداری می‌شود؛ معمولاً نیازی نیست کاربر مستقیماً به تابع شل ارجاع دهد\&. هر تابع موجود با همین نام بی‌صدا جایگزین می‌شود\&.
.PP
با یک آرگومان، تابع ریاضی \fImathfunc\fP و همچنین پیاده‌سازی تابع شل آن را حذف می‌کند\&.
.PP
بدون آرگومان، تمام توابع \fImathfunc\fP را در قالبی مناسب برای بازگرداندن تعاریف فهرست می‌کند\&.
این توابع لزوماً توسط \fBzmathfuncdef\fP تعریف نشده‌اند\&.
.RE
.PP.SH "توابع پیکربندی کاربر (USER CONFIGURATION FUNCTIONS)"
.PP
ماژول \fBzsh/newuser\fP همراه با تابعی برای کمک به پیکربندی
گزینه‌های شل برای کاربران جدید ارائه می‌شود\&. در صورت نصب بودن ماژول، این تابع
می‌تواند به‌صورت دستی نیز اجرا شود\&. این تابع حتی در صورتی که رفتار پیش‌فرض
ماژول، یعنی اجرای تابع برای یک کاربر جدید که بدون فایل‌های راه‌اندازی وارد سیستم می‌شود،
غیرفعال شده باشد نیز در دسترس است\&.
.PP
.PD 0
.TP
.PD
\fBzsh\-newuser\-install\fP [ \fB\-f\fP ]
این تابع گزینه‌های مختلفی را برای سفارشی‌سازی اسکریپت‌های راه‌اندازی
پیش روی کاربر قرار می‌دهد\&. در حال حاضر تنها \fB~/\&.zshrc\fP مدیریت می‌شود\&.
در صورت تنظیم بودن پارامتر \fBZDOTDIR\fP، به‌جای آن از \fB$ZDOTDIR/\&.zshrc\fP
استفاده می‌شود؛ این امر راهکاری را برای کاربر فراهم می‌کند تا فایلی را بدون
دستکاری \fB\&.zshrc\fP موجود پیکربندی کند\&.
.RS
.PP
به‌طور پیش‌فرض، اگر تابع هر یک از فایل‌های \fB\&.zshenv\fP، \fB\&.zprofile\fP،
\fB\&.zshrc\fP یا \fB\&.zlogin\fP را در دایرکتوری مربوطه پیدا کند، بلافاصله
خارج می‌شود\&. برای اجبار تابع به ادامه کار، گزینه \fB\-f\fP الزامی
است\&. توجه داشته باشید که این وضعیت ممکن است حتی در صورتی که خود \fB\&.zshrc\fP
وجود نداشته باشد نیز رخ دهد\&.
.PP
طبق پیکربندی فعلی، اگر کاربر دارای امتیازات ریشه (root) باشد،
تابع بلافاصله خارج خواهد شد؛ این رفتار قابل لغو یا تغییر نیست\&.
.PP
پس از فعال‌سازی، رفتار تابع باید خودتوضیح‌دهنده باشد\&.
منوهایی وجود دارند که به کاربر اجازه می‌دهند مقدار گزینه‌ها و پارامترها
را تغییر دهد\&. پیشنهادها برای بهبود همیشه مورد استقبال است\&.
.PP
هنگام خروج اسکریپت، به کاربر این امکان داده می‌شود که فایل جدید را
ذخیره کند یا خیر؛ تا پیش از این نقطه، تغییرات برگشت‌پذیر هستند\&. با این حال،
اسکریپت دقت دارد که تغییرات فایل را تنها به گروهی محدود کند که با خطوط
`\fB# Lines configured by zsh\-newuser\-install\fP\&' و
`\fB# End of lines configured by zsh\-newuser\-install\fP\&' مشخص شده است\&.
علاوه بر این، نسخه قدیمی \fB\&.zshrc\fP در فایلی با پسوند افزوده شده
\fB\&.zni\fP ذخیره می‌شود\&.
.PP
اگر تابع یک \fB\&.zshrc\fP موجود را ویرایش کند، این بر عهده کاربر است
که مطمئن شود تغییرات اعمال‌شده اثرگذار خواهند بود\&. برای نمونه، اگر کنترل اجرای
برنامه معمولاً در اوایل \fB\&.zshrc\fP موجود خاتمه یابد، این خطوط اجرا نخواهند شد؛
یا ممکن است یک فایل راه‌اندازی پس از آن، گزینه‌ها یا پارامترها را بازنویسی کند،
و مواردی از این دست\&. خود تابع تلاشی برای تشخیص چنین تداخل‌هایی نمی‌کند\&.
.RE
.PP
.SH "سایر توابع (OTHER FUNCTIONS)"
.PP
تعداد زیادی تابع مفید در دایرکتوری \fBFunctions/Misc\fP
از توزیع zsh وجود دارد\&. بیشتر آن‌ها بسیار ساده هستند و در اینجا نیازی به
مستندسازی ندارند، اما چند مورد از آن‌ها شایسته ذکر ویژه هستند\&.
.PP
.SS "توضیحات (Descriptions)"
.PP
.PD 0
.TP
.PD
\fBcolors\fP
این تابع چندین آرایه متناظر (associative array) را برای نگاشت نام‌های رنگ‌ها به
(و از) کدهای هشت‌رنگ استاندارد ترمینال ANSI مقداردهی اولیه می‌کند\&. این‌ها توسط
سیستم تم اعلان (به بالا مراجعه کنید) استفاده می‌شوند\&. به‌ندرت ممکن است به اجرای
\fBcolors\fP بیش از یک بار نیاز پیدا کنید\&.
.RS
.PP
هشت رنگ اصلی عبارتند از: \fBblack\fP، \fBred\fP، \fBgreen\fP، \fByellow\fP،
\fBblue\fP، \fBmagenta\fP، \fBcyan\fP و \fBwhite\fP\&. هر یک از این‌ها کدهایی برای
پیش‌زمینه و پس‌زمینه دارند\&. علاوه بر این، هفت ویژگی شدت وجود دارد:
\fBbold\fP، \fBfaint\fP، \fBstandout\fP، \fBunderline\fP، \fBblink\fP، \fBreverse\fP
و \fBconceal\fP\&. در نهایت، هفت کد برای خنثی‌سازی ویژگی‌ها استفاده می‌شود:
\fBnone\fP (بازنشانی همه ویژگی‌ها به مقادیر پیش‌فرض)، \fBnormal\fP
(نه bold و نه faint)، \fBno\-standout\fP، \fBno\-underline\fP، \fBno\-blink\fP،
\fBno\-reverse\fP و \fBno\-conceal\fP\&.
.PP
برخی از ترمینال‌ها از تمام ترکیب‌های رنگ‌ها و شدت‌ها پشتیبانی نمی‌کنند\&.
.PP
آرایه‌های متناظر عبارتند از:
.PP
.PD 0
.TP
.PD 0
\fBcolor\fP
.TP
.PD
\fBcolour\fP
تمام نام‌های رنگ‌ها را به کدهای عدد صحیح آن‌ها، و کدهای عدد صحیح را به نام‌های
رنگ‌ها نگاشت می‌کنند\&. هشت نام اصلی به کدهای رنگ پیش‌زمینه نگاشت می‌شوند،
همان‌طور که نام‌های دارای پیشوند `\fBfg\-\fP\&'، مانند `\fBfg\-red\fP' عمل می‌کنند\&.
نام‌های دارای پیشوند `\fBbg\-\fP\&'، مانند `\fBbg\-blue\fP'، به کدهای پس‌زمینه اشاره
دارند\&. نگاشت معکوس از کد به رنگ، برای کدهای پیش‌زمینه نام اصلی و برای پس‌زمینه‌ها
قالب \fBbg\-\fP را بازمی‌گرداند\&.
.RS
.PP
اگرچه نامیدن آن‌ها به‌عنوان «رنگ‌ها» دقیق نیست، این آرایه‌ها چهارده ویژگی
دیگر را نیز از نام به کد و از کد به نام نگاشت می‌کنند\&.
.RE
.TP
.PD 0
\fBfg\fP
.TP
.PD 0
\fBfg_bold\fP
.TP
.PD
\fBfg_no_bold\fP
هشت نام رنگ اصلی را به توالی‌های گریز ترمینال ANSI نگاشت می‌کنند که ویژگی‌های متنی
پیش‌زمینه متناظر را تنظیم می‌نمایند\&. توالی‌های \fBfg\fP رنگ را بدون تغییر
هشت ویژگی شدت تغییر می‌دهند\&.
.TP
.PD 0
\fBbg\fP
.TP
.PD 0
\fBbg_bold\fP
.TP
.PD
\fBbg_no_bold\fP
هشت نام رنگ اصلی را به توالی‌های گریز ترمینال ANSI نگاشت می‌کنند که ویژگی‌های
پس‌زمینه متناظر را تنظیم می‌نمایند\&. توالی‌های \fBbg\fP رنگ را بدون تغییر
هشت ویژگی شدت تغییر می‌دهند\&.
.PP
علاوه بر این، پارامترهای اسکالر \fBreset_color\fP و \fBbold_color\fP به‌ترتیب
روی توالی‌های گریز ترمینال ANSI تنظیم می‌شوند که همه ویژگی‌ها را خاموش و
شدت bold را فعال می‌کنند\&.
.RE
.TP
\fBfned\fP [ \fB\-x\fP \fInum\fP ] \fIname\fP
همانند \fBzed \-f\fP\&. این تابع در توزیع zsh ظاهر نمی‌شود، اما می‌توان با ایجاد
پیوند از \fBzed\fP به نام \fBfned\fP در یکی از دایرکتوری‌های موجود در \fBfpath\fP
شما، آن را ایجاد کرد\&.
.TP
\fBhisted\fP [ [ \fIname\fP ] \fIsize\fP ]
همانند \fBzed \-h\fP\&. این تابع در توزیع zsh ظاهر نمی‌شود، اما می‌توان با ایجاد
پیوند از \fBzed\fP به نام \fBhisted\fP در یکی از دایرکتوری‌های موجود در \fBfpath\fP
شما، آن را ایجاد کرد\&.
.TP
\fBis\-at\-least\fP \fIneeded\fP [ \fIpresent\fP ]
یک مقایسه بزرگ‌تر یا مساوی را بین دو رشته دارای قالب شماره نسخه zsh انجام می‌دهد؛
یعنی رشته‌ای از اعداد و متن که بخش‌های آن با نقطه یا خط تیره از هم جدا شده‌اند\&.
اگر رشته \fIpresent\fP ارائه نشود، از \fB$ZSH_VERSION\fP استفاده می‌شود\&. بخش‌ها در
دو رشته از چپ به راست جفت می‌شوند و از بخش‌های غیرعددیِ ابتدایی صرف‌نظر می‌گردد\&.
اگر یک رشته بخش‌های کمتری نسبت به دیگری داشته باشد، بخش‌های ناموجود صفر در نظر گرفته می‌شوند\&.
.RS
.PP
این تابع در فایل‌های راه‌اندازی برای تنظیم گزینه‌ها و سایر وضعیت‌هایی که در
همه نسخه‌های zsh در دسترس نیستند مفید است\&.
.PP
.RS
.nf
\fBis\-at\-least 3\&.1\&.6\-15 && setopt NO_GLOBAL_RCS
is\-at\-least 3\&.1\&.0 && setopt HIST_REDUCE_BLANKS
is\-at\-least 2\&.6\-17 || print "You can\&'t use is\-at\-least here\&."\fP
.fi
.RE
.RE
.TP
\fBnslookup\fP [ \fIarg\fP \&.\&.\&. ]
این تابع پوششی (wrapper) برای دستور \fBnslookup\fP به ماژول \fBzsh/zpty\fP
نیاز دارد (به \fIzshmodules\fP(1) مراجعه کنید)\&. این تابع دقیقاً مانند
\fBnslookup\fP استاندارد رفتار می‌کند، به‌جز اینکه اعلان‌های سفارشی‌پذیر
(شامل یک اعلان در سمت راست) و تکمیل خودکار دستورات nslookup، نام‌های میزبان و غیره
را فراهم می‌آورد (در صورتی که از سیستم تکمیل مبتنی بر تابع استفاده کنید)\&.
سبک‌های تکمیل ممکن است با پیشوند زمینه `\fB:completion:nslookup\fP\&' تنظیم شوند\&.
.RS
.PP
همچنین به سبک‌های \fBpager\fP، \fBprompt\fP و \fBrprompt\fP در ادامه مراجعه کنید\&.
.RE
.TP
\fBregexp\-replace\fP \fIvar\fP \fIregexp\fP \fIreplace\fP
از عبارت‌های باقاعده برای انجام یک عملیات جستجو و جایگزینی سراسری روی
یک متغیر استفاده می‌کند\&. عبارت‌های باقاعده تعمیم‌یافته POSIX (کوتاه‌نوشت ERE)
استفاده می‌شوند، مگر اینکه گزینه \fBRE_MATCH_PCRE\fP تنظیم شده باشد،
که در این صورت از عبارت‌های باقاعده سازگار با Perl استفاده می‌شود
(این امر مستلزم آن است که شل با کتابخانه \fBpcre\fP پیوند خورده باشد)\&.
.RS.PP
\fIvar\fP نام متغیری است که حاوی رشته مورد نظر برای تطبیق است\&.
این متغیر مستقیماً توسط تابع تغییر داده خواهد شد\&. از متغیرهای
\fBMATCH\fP، \fBMBEGIN\fP، \fBMEND\fP، \fBmatch\fP، \fBmbegin\fP و \fBmend\fP
باید خودداری شود چرا که این متغیرها توسط کد عبارات باقاعده (regular expression) استفاده می‌شوند\&.
.PP
\fIregexp\fP عبارت باقاعده‌ای است که رشته باید با آن مطابقت داده شود\&.
.PP
\fIreplace\fP متن جایگزین است\&. این مقدار می‌تواند شامل عبارت‌های پارامتری، دستوری
و حسابی باشد که جایگزین خواهند شد: به‌ویژه، ارجاع به
\fB$MATCH\fP با متنی که توسط الگو مطابقت داده شده است، جایگزین خواهد شد\&.
.PP
وضعیت بازگشتی در صورتی که حداقل یک تطبیق انجام شده باشد 0، وگرنه 1 است\&.
.PP
توجه داشته باشید که در صورت استفاده از POSIX EREها، عملگرهای \fB^\fP یا مرز کلمه (word boundary)
(در صورت پشتیبانی) ممکن است به‌درستی کار نکنند\&.
.RE
.TP
\fBrun\-help\fP \fIcmd\fP
این تابع به‌گونه‌ای طراحی شده است که توسط ویجت ZLE \fBrun\-help\fP،
به‌جای نام مستعار پیش‌فرض فراخوانی شود\&. برای دستورالعمل‌های راه‌اندازی،
به «Accessing On\-Line Help» در بالا مراجعه کنید\&.
.RS
.PP
در ادامه، اگر \fIcmd\fP یک مسیر در فایل‌سیستم باشد، ابتدا به سمت‌راست‌ترین جزء خود (نام فایل) تقلیل می‌یابد\&.
.PP
راهنما ابتدا با جستجوی فایلی به نام \fIcmd\fP در دایرکتوری مشخص‌شده توسط پارامتر
\fBHELPDIR\fP جستجو می‌شود\&. اگر هیچ فایلی پیدا نشد، یک تابع کمکی، نام مستعار،
یا دستوری به نام \fBrun\-help\-\fIcmd\fP\fP جستجو می‌شود\&. در صورت یافتن،
دستیار کمکی همراه با بقیه خط فرمان فعلی (هر آنچه پس از نام دستور \fIcmd\fP آمده است)
به‌عنوان آرگومان‌هایش اجرا می‌شود\&. هنگامی که نه فایل و نه دستیار کمکی یافت نشوند،
دستور خارجی «\fBman\fP \fIcmd\fP» اجرا می‌شود\&.
.PP
یک دستیار کمکی نمونه برای دستور «ssh»:
.PP
.RS
.nf
\fBrun\-help\-ssh() {
    emulate \-LR zsh
    local \-a args
    # Delete the "\-l username" option
    zparseopts \-D \-E \-a args l:
    # Delete other options, leaving: host command
    args=(${@:#\-*})
    if [[ ${#args} \-lt 2 ]]; then
        man ssh
    else
        run\-help $args[2]
    fi
}\fP
.fi
.RE
.PP
تعدادی از این دستیاران در دایرکتوری \fBFunctions/Misc\fP ارائه شده‌اند\&.
این موارد برای این‌که توسط \fBrun\-help\fP پیدا و استفاده شوند، باید به‌صورت خودکار
بارگذاری (autoload) شوند یا به‌عنوان اسکریپت‌های اجرایی در مسیر جستجوی (search path) شما قرار گیرند\&.
.PP
.PD 0
.TP
.PD 0
\fBrun\-help\-btrfs\fP
.TP
.PD 0
\fBrun\-help\-git\fP
.TP
.PD 0
\fBrun\-help\-ip\fP
.TP
.PD 0
\fBrun\-help\-openssl\fP
.TP
.PD 0
\fBrun\-help\-p4\fP
.TP
.PD 0
\fBrun\-help\-sudo\fP
.TP
.PD 0
\fBrun\-help\-svk\fP
.TP
.PD
\fBrun\-help\-svn\fP
توابع کمکی برای دستورهای
\fBbtrfs\fP،
\fBgit\fP،
\fBip\fP،
\fBopenssl\fP،
\fBp4\fP،
\fBsudo\fP،
\fBsvk\fP
و
\fBsvn\fP\&.
.RE
.TP
\fBtetris\fP
زمانی Zsh متهم شده بود که به اندازه Emacs کامل نیست،
چرا که فاقد بازی Tetris بود\&. این تابع برای
رد این تهمت بدخواهانه نوشته شد\&.
.RS
.PP
این تابع باید به‌عنوان یک ویجت ZLE استفاده شود:
.PP
.RS
.nf
\fBautoload \-U tetris
zle \-N tetris
bindkey \fIkeys\fP tetris\fP
.fi
.RE
.PP
برای شروع بازی، ویجت را با فشردن \fIkeys\fP اجرا کنید\&. هر خط فرمانی که در حال
ویرایش آن بودید موقتاً ناپدید می‌شود، و نگاشت کلیدهای شما (keymap) نیز موقتاً با کلیدهای
کنترلی Tetris جایگزین می‌شود\&. وضعیت قبلی ویرایشگر هنگام خروج از بازی (با فشردن «\fBq\fP»)
یا زمانی که ببازید، بازیابی می‌شود\&.
.PP
اگر در میانه بازی خارج شوید، فراخوانی بعدی ویجت \fBtetris\fP از همان‌جایی که بازی را رها کرده بودید
ادامه می‌یابد\&. اگر باخته باشید، یک بازی جدید آغاز خواهد شد\&.
.RE
.TP
\fBtetriscurses\fP
این یک پورت از مورد بالا برای zcurses است\&. مدیریت ورودی اندکی بهبود یافته است
به‌گونه‌ای که جابجایی یک بلوک به طرفین، گام زمانی (timestep) را به‌طور خودکار پیش نمی‌برد،
و گرافیک بازی از نویسه‌های بلوکی یونیکد (unicode block graphics) استفاده می‌کند\&.
.RS
.PP
این نسخه وضعیت بازی را بین دفعات فراخوانی ذخیره نمی‌کند، و به‌عنوان یک ویجت اجرا نمی‌شود،
بلکه اجرای آن به‌صورت زیر است:
.PP
.RS
.nf
\fBautoload \-U tetriscurses
tetriscurses\fP
.fi
.RE
.RE
.TP
\fBzargs\fP [ \fIoption\fP \&.\&.\&. \fB\-\fP\fB\-\fP ] [ \fIinput\fP \&.\&.\&. ] [ \fB\-\fP\fB\-\fP \fIcommand\fP [ \fIarg\fP \&.\&.\&. ] ]
این تابع کاربردی مشابه با GNU xargs دارد\&. به‌جای خواندن خطوط آرگومان‌ها از ورودی
استاندارد، آن‌ها را از خط فرمان می‌گیرد\&. این قابلیت بسیار مفید است زیرا zsh، به‌ویژه
با عملگرهای glob بازگشتی، اغلب می‌تواند برای یک تابع شل خط فرمانی بسازد که
طولانی‌تر از حداکثر طول قابل پذیرش توسط یک دستور خارجی است\&.
.RS
.PP
فهرست \fIoption\fP نشان‌دهنده گزینه‌های خود دستور \fBzargs\fP است که مشابه با
گزینه‌های \fBxargs\fP می‌باشند\&. فهرست \fIinput\fP مجموعه‌ای از رشته‌هاست (اغلب
نام‌های فایل) که آرگومان‌های \fBcommand\fP را تشکیل می‌دهند، مشابه با ورودی
استاندارد در \fBxargs\fP\&. در نهایت، فهرست \fIarg\fP شامل آرگومان‌هایی (معمولاً
گزینه‌ها) است که هر بار با اجرای \fIcommand\fP به آن ارسال می‌شوند\&. فهرست \fIarg\fP
در هر اجرا، مقدم بر عناصر فهرست \fBinput\fP قرار می‌گیرد\&. اگر هیچ دستوری (\fIcommand\fP)
مشخص نشود، نباید هیچ فهرست آرگومانی (\fIarg\fP) نیز ارائه شود، و در آن حالت،
دستور پیش‌فرض «\fBprint\fP» با آرگومان‌های «\fB\-r \-\fP\fB\-\fP» خواهد بود\&.
.PP
به‌عنوان مثال، برای دریافت فهرست تفصیلی \fBls\fP از همه فایل‌های عادی غیرپنهان
در دایرکتوری فعلی یا زیردایرکتوری‌های آن:
.PP
.RS
.nf
\fBautoload \-U zargs
zargs \-\- **/*(\&.) \-\- ls \-ld \-\-\fP
.fi
.RE
.PP
اولین و سومین رخداد «\fB\-\fP\fB\-\fP» به‌ترتیب برای نشانه‌گذاری پایان گزینه‌های \fBzargs\fP
و \fBls\fP استفاده می‌شوند تا در برابر نام فایل‌هایی که با «\fB\-\fP» آغاز می‌شوند محافظت شود،
در حالی که رخداد دوم برای تفکیک فهرست فایل‌ها از دستورِ قابل اجرا («\fBls \-ld \-\-\fP»)
استفاده می‌شود\&.
.PP
همچنین اولین «\fB\-\fP\fB\-\fP» در صورتی که احتمال خالی بودن فهرست وجود داشته باشد نیز لازم خواهد بود،
مانند:
.PP
.RS
.nf
\fBzargs \-r \-\- \&./*\&.back(#qN) \-\- rm \-f\fP
.fi
.RE.PP
در صورتی که رشتهٔ «\fB\-\fP\fB\-\fP» یک \fIinput\fP (ورودی) باشد یا احتمال برود که باشد، می‌توان از گزینهٔ \fB\-e\fP برای تغییر نشانگر پایان ورودی‌ها استفاده کرد\&. توجه داشته باشید که این کار نشانگر پایان گزینه‌ها را تغییر \fIنمی‌دهد\fP\&. برای مثال، جهت استفاده از «\fB\&.\&.\fP» به عنوان نشانگر:
.PP
.RS
.nf
\fBzargs \-e\&.\&. \-\- **/*(\&.) \&.\&. ls \-ld \-\-\fP
.fi
.RE
.PP
این مورد در این مثال انتخاب مناسبی است، چرا که نام هیچ فایل ساده‌ای نمی‌تواند «\fB\&.\&.\fP» باشد، اما بهترین نشانگر پایان به شرایط بستگی دارد\&.
.PP
گزینه‌های \fB\-i\fP، \fB\-I\fP، \fB\-l\fP، \fB\-L\fP و \fB\-n\fP کمی با کاربردشان در \fBxargs\fP تفاوت دارند\&. در \fBzargs\fP هیچ خط ورودی برای شمارش وجود ندارد، بنابراین \fB\-l\fP و \fB\-L\fP در طول فهرست \fIinput\fP می‌شمارند، و \fB\-n\fP تعداد آرگومان‌های ارسالی به هر بار اجرای \fIcommand\fP را، \fIشامل\fP هر فهرست \fIarg\fP، می‌شمارد\&. همچنین، هر زمان که \fB\-i\fP یا \fB\-I\fP استفاده شود، هر \fIinput\fP به صورت جداگانه پردازش می‌شود، درست مانند رفتار «\fB\-L\fP \fB1\fP»\&.
.PP
برای جزئیات سایر گزینه‌های \fBzargs\fP، صفحهٔ راهنمای \fIxargs\fP(1) را ببینید (اما به تفاوت در عملکرد بین \fBzargs\fP و \fBxargs\fP توجه داشته باشید) یا \fBzargs\fP را با گزینهٔ \fB\-\fP\fB\-help\fP اجرا کنید\&.
.RE
.TP
.PD 0
\fBzed\fP [ \fB\-f\fP [ \fB\-x\fP \fInum\fP ] ] \fIname\fP
.TP
.PD 0
\fBzed\fP [ \fB\-h\fP [ \fIname\fP ] \fIsize\fP ]
.TP
.PD
\fBzed \-b\fP
این تابع از ویرایشگر ZLE برای ویرایش یک فایل یا تابع استفاده می‌کند\&.
.RS
.PP
تنها یک آرگومان \fIname\fP مجاز است\&.
اگر گزینهٔ \fB\-f\fP داده شود، نام به عنوان یک تابع در نظر گرفته می‌شود؛ اگر تابع برای بارگذاری خودکار (autoloading) علامت‌گذاری شده باشد، \fBzed\fP آن را در \fBfpath\fP جستجو کرده و بارگذاری می‌کند\&. توجه داشته باشید توابعی که به این شیوه ویرایش می‌شوند در شل فعلی نصب می‌گردند، اما روی فایل autoload بازنویسی \fIنمی‌شوند\fP\&. در این حالت گزینهٔ \fB\-x\fP مشخص می‌کند که نویسه‌های tab ابتدایی که تابع را بر اساس نحو تورفتگی داده‌اند باید به تعداد مشخص‌شده‌ای از فاصله‌ها تبدیل شوند؛ «\fB\-x 2\fP» با قالب‌بندی توابع توزیع‌شده به همراه شل همخوانی دارد\&.
.PP
بدون \fB\-f\fP، مقدار \fIname\fP نام مسیر فایلی است که باید ویرایش شود و نیازی نیست از قبل وجود داشته باشد؛ در صورت نیاز، هنگام نوشتن ایجاد می‌شود\&. همراه با \fB\-h\fP، فرض می‌شود که فایل حاوی رویدادهای تاریخچه (history) است\&.
.PP
هنگامی که هیچ نام فایلی برای \fB\-h\fP ارائه نشود، تاریخچهٔ شل فعلی درجا ویرایش می‌شود\&. پس از خروج موفقیت‌آمیز zed، شماره‌گذاری تاریخچه دوباره انجام می‌شود\&.
.PP
هنگام ویرایش تاریخچه، رویدادهای چندخطی باید در انتهای هر خط قبل از آخرین خط، یک بک‌اسلش داشته باشند\&.
.PP
در حین ویرایش، این تابع نگاشت کلید اصلی را به \fBzed\fP و نگاشت کلید دستور vi را به \fBzed\-vicmd\fP تنظیم می‌کند\&. اگر این نگاشت‌ها در اولین اجرای \fBzed\fP وجود نداشته باشند، از نگاشت‌های کلید موجود \fBmain\fP و \fBvicmd\fP کپی خواهند شد\&. از آن‌ها می‌توان برای تعریف کلیدهای میانبر ویژه‌ای که فقط در zed کاربرد دارند استفاده کرد\&.
.PP
اگر نگاشت کلید را ایجاد کند، \fBzed\fP کلید return را مجدداً برای درج شکستگی خط و «\fB^X^W\fP» را برای پذیرش ویرایش در نگاشت کلید \fBzed\fP مقید می‌کند، و «\fBZZ\fP» را برای پذیرش ویرایش در نگاشت کلید \fBzed\-vicmd\fP اختصاص می‌دهد\&.
.PP
تنها این کلیدهای میانبر را می‌توان با اجرای «\fBzed \-b\fP» نصب کرد\&. این کار برای قرار دادن در یک فایل راه‌انداز مناسب است\&. توجه داشته باشید که در صورت اجرای مجدد، این دستور نگاشت‌های کلید موجود \fBzed\fP و \fBzed\-vicmd\fP را بازنویسی خواهد کرد\&.
.PP
قابلیت تکمیل خودکار در دسترس است، و شیوه‌ها را می‌توان با پیشوند زمینهٔ «\fB:completion:zed:\fP» تنظیم نمود\&.
.PP
ویجت zle با نام \fBzed\-set\-file\-name\fP در دسترس است\&. این ویجت را می‌توان با نام از درون zed با استفاده از «\fB\eex zed\-set\-file\-name\fP» فراخوانی کرد یا پس از اجرای «\fBzed \-b\fP»، می‌توان آن را به کلیدی در هر یک از نگاشت‌های کلید \fBzed\fP یا \fBzed\-vicmd\fP مقید ساخت\&. هنگامی که ویجت فراخوانی می‌شود، نام جدیدی برای فایلی که در حال ویرایش است درخواست می‌کند\&. زمانی که zed خارج می‌شود، فایل با آن نام نوشته خواهد شد و فایل اصلی دست‌نخورده باقی می‌ماند\&. فراخوانی این ویجت از «\fBzed \-f\fP» بی‌تأثیر است\&. زمینهٔ تکمیل خودکار به «\fB:completion:zed\-set\-file\-name:\fP» تغییر می‌یابد\&. هنگام ویرایش تاریخچهٔ فعلی با «\fBzed \-h\fP»، ابتدا تاریخچه به‌روزرسانی شده و سپس فایل نوشته می‌شود، اما تنظیم سراسری \fBHISTFILE\fP دستکاری نمی‌شود\&.
.PP
در زمان اجرای \fBzed\-set\-file\-name\fP، برنامهٔ zed از نگاشت کلید \fBzed\-normal\-keymap\fP استفاده می‌کند که از نگاشت کلید اصلی فعال در زمان راه‌اندازی میانبرهای zed پیوند داده شده است\&. (این کار برای این است که کلید return به صورت عادی عمل کند\&.) در نتیجه اگر نگاشت کلید اصلی تغییر کرده باشد، ویجت متوجه آن نخواهد شد\&. این موضوع برای بیشتر کاربران اهمیتی ندارد\&.
.RE
.TP
.PD 0
\fBzcp\fP [ \fB\-finqQvwW\fP ] \fIsrcpat\fP \fIdest\fP
.TP
.PD
\fBzln\fP [ \fB\-finqQsvwW\fP ] \fIsrcpat\fP \fIdest\fP
به ترتیب مشابه \fBzmv \-C\fP و \fBzmv \-L\fP هستند\&. این توابع در توزیع zsh وجود ندارند، اما می‌توان با پیوند دادن \fBzmv\fP به نام‌های \fBzcp\fP و \fBzln\fP در پوشه‌ای درون \fBfpath\fP، آن‌ها را ایجاد کرد\&.
.TP
\fBzkbd\fP
بخش «تعریف صفحه‌کلید (Keyboard Definition)» در بالا را ببینید\&.

.TP
.PD 0
\fBzmv\fP [ \fB\-finqQsvwW\fP ] [ \fB\-C\fP | \fB\-L\fP | \fB\-M\fP | \-{\fBp\fP|\fBP\fP} \fIprogram\fP ] [ \fB\-o\fP \fIoptstring\fP ]
.TP
.PD
\fB    \fP\fIsrcpat\fP \fIdest\fP 
انتقال (معمولاً تغییر نام) فایل‌های منطبق بر الگوی \fIsrcpat\fP به فایل‌های متناظر با نام‌هایی به فرم ارائه‌شده توسط \fIdest\fP، به طوری که \fIsrcpat\fP شامل پرانتزهایی در بر گیرندهٔ الگوها باشد که به نوبت با \fB$1\fP، \fB$2\fP، \&.\&.\&. در \fIdest\fP جایگزین خواهند شد\&. برای مثال،
.RS
.PP
.RS
.nf
\fBzmv \&'(*)\&.lis' '$1\&.txt'\fP
.fi
.RE
.PP
نام «\fBfoo\&.lis\fP» را به «\fBfoo\&.txt\fP»، «\fBmy\&.old\&.stuff\&.lis\fP» را به «\fBmy\&.old\&.stuff\&.txt\fP» و به همین ترتیب تغییر می‌دهد\&.
.PP
الگو همیشه به عنوان یک الگوی \fBEXTENDED_GLOB\fP در نظر گرفته می‌شود\&. هر فایلی که نام آن در اثر جایگزینی تغییر نکند، به سادگی نادیده گرفته می‌شود\&. هرگونه خطا (جایگزینی به رشته‌ای خالی منجر شود، دو جایگزینی نتیجهٔ یکسانی داشته باشند، مقصد یک فایل عادی موجود باشد و \fB\-f\fP مشخص نشده باشد) باعث متوقف شدن کل تابع بدون انجام هیچ عملیاتی می‌شود\&.
.PP
علاوه بر جایگزینی الگو، می‌توان به متغیر \fB$f\fP در آرگومان دوم (جایگزینی) ارجاع داد\&. این کار امکان استفاده از جانشینی متغیر برای تغییر آرگومان را فراهم می‌کند؛ مثال‌های زیر را مشاهده کنید\&.
.PP
گزینه‌ها:
.PP
.PD 0
.TP
\fB\-f\fP
رونویسی اجباری فایل‌های مقصد\&. در حال حاضر به دلیل پیچیدگی‌ها و تفاوت‌های پیاده‌سازی به دستور \fBmv\fP/\fBcp\fP/\fBln\fP منتقل نمی‌شود (اما برای این منظور می‌توانید از \fB\-o\-f\fP استفاده کنید)\&.
.TP
\fB\-i\fP
تعاملی: نمایش هر خطی که قرار است اجرا شود و پرسش از کاربر مبنی بر اجرای آن\&. «\fBY\fP» یا «\fBy\fP» آن را اجرا خواهد کرد و هر ورودی دیگری از آن رد می‌شود\&. توجه داشته باشید که فقط وارد کردن یک نویسه کافی است\&.
.TP
\fB\-n\fP
عدم اجرا: چاپ رخدادهایی که قرار است اتفاق بیفتد، بدون اجرای واقعی آن‌ها\&.
.TP
\fB\-q\fP
غیرفعال کردن توصیف‌کننده‌های سادهٔ الگو (bare glob qualifiers): اکنون به‌طور پیش‌فرض لحاظ می‌شود، بنابراین اثری ندارد\&.
.TP
\fB\-Q\fP
فعال‌سازی اجباری توصیف‌کننده‌های سادهٔ الگو (bare glob qualifiers)\&. این گزینه را فعال نکنید مگر اینکه واقعاً از توصیف‌کننده‌های glob در یک الگو استفاده کنید\&.
.TP
\fB\-s\fP
نمادین (Symbolic)، که به \fBln\fP فرستاده می‌شود؛ فقط با \fB\-L\fP کار می‌کند\&.
.TP
\fB\-v\fP
حالت پرگو (Verbose): چاپ هر دستور در حین اجرای آن\&.
.TP
\fB\-w\fP
انتخاب بخش‌های نویسه‌بدل (wildcard) از الگو، همان‌طور که در بالا توضیح داده شد، و افزودن ضمنی پرانتزها برای ارجاع به آن‌ها\&.
.TP
\fB\-W\fP
دقیقاً مانند \fB\-w\fP، با این ویژگی اضافه که نویسه‌های بدل در الگوی جایگزینی به ارجاع‌های متوالی \fB${1}\fP \&.\&. \fB${N}\fP تبدیل می‌شوند\&.
.TP
\fB\-C\fP
.TP
\fB\-L\fP.TP
\fB\-M\fP
اجبار به استفاده از \fBcp\fP، \fBln\fP یا \fBmv\fP (به ترتیب)، صرف‌نظر از نام تابع\&.
.TP
\fB\-p\fP \fIprogram\fP
فراخوانی \fIprogram\fP به جای \fBcp\fP، \fBln\fP یا
\fBmv\fP\&. هر کاری که انجام می‌دهد، دست‌کم باید ساختار
`\fIprogram\fP \fB\-\fP\fB\-\fP \fIoldname\fP \fInewname\fP\&'
را درک کند، که در آن \fIoldname\fP و \fInewname\fP نام‌های فایل تولیدشده توسط \fBzmv\fP هستند\&.
\fIprogram\fP به کلمات مجزا تقسیم می‌شود، بنابراین می‌تواند برای مثال نام یک ابزار بایگانی به همراه یک زیرفرمان کپی یا تغییر نام باشد\&.
.TP
\fB\-P\fP \fIprogram\fP
مانند \fB\-p\fP \fIprogram\fP، به جز اینکه
\fIprogram\fP برای نشان دادن پایان گزینه‌ها، \fB\-\fP\fB\-\fP بعدی را نمی‌پذیرد\&. در این حالت، نام‌های فایل باید از قبل در قالبی معقول و مناسب برای برنامهٔ مورد نظر باشند\&.
.TP
\fB\-o\fP \fIoptstring\fP
رشتهٔ \fIoptstring\fP به کلمات تفکیک شده و عینا به دستور فراخوانی‌شدهٔ \fBcp\fP، \fBln\fP یا \fBmv\fP جهت انجام کار تحویل داده می‌شود\&. این رشته احتمالا باید با یک `\fB\-\fP\&' شروع شود\&.
.PD
.PP
مثال‌های بیشتر:
.PP
.RS
.nf
\fBzmv \-v \&'(* *)' '${1// /_}'\fP
.fi
.RE
.PP
برای هر فایل در دایرکتوری جاری که حداقل یک فاصله در نام خود دارد، هر فاصله را با یک زیرخط (underscore) جایگزین کرده و دستورهای اجراشده را نمایش می‌دهد\&.
.PP
.RS
.nf
\fBzmv \-v \&'* *' '${f// /_}'\fP
.fi
.RE
.PP
این دستور دقیقا همان کار را با ارجاع به نام فایل ذخیره‌شده در \fB$f\fP انجام می‌دهد\&.
.PP
برای مثال‌های کامل‌تر و سایر جزئیات پیاده‌سازی، فایل منبع \fBzmv\fP را ببینید، که معمولا در یکی از دایرکتوری‌های مشخص‌شده در \fBfpath\fP شما، یا در \fBFunctions/Misc/zmv\fP در توزیع zsh قرار دارد\&.
.RE
.TP
\fBzrecompile\fP
بخش `Recompiling Functions\&' در بالا را ببینید\&.
.TP
\fBzstyle+\fP \fIcontext\fP \fIstyle\fP \fIvalue\fP [ \fB+\fP \fIsubcontext\fP \fIstyle\fP \fIvalue\fP \&.\&.\&. ]
این دستور تعریف سبک‌ها را با استفاده از یک `\fB+\fP\&' منفرد به عنوان نشانه‌ای ویژه ساده‌تر می‌کند؛ این نشانه به شما امکان می‌دهد یک نام زمینه (context) را به نام زمینهٔ قبلا استفاده‌شده پیوست کنید\&. مانند این:
.RS
.PP
.RS
.nf
\fBzstyle+ \&':foo:bar' \fIstyle1\fP \fIvalue1\fP \e 
       +\&':baz'     \fIstyle2\fP \fIvalue2\fP \e 
       +\&':frob'    \fIstyle3\fP \fIvalue3\fP\fP
.fi
.RE
.PP
این دستور طبق معمول \fIstyle1\fP را با \fIvalue1\fP برای زمینهٔ \fB:foo:bar\fP تعریف می‌کند، اما همچنین \fIstyle2\fP را با \fIvalue2\fP برای زمینهٔ \fB:foo:bar:baz\fP و \fIstyle3\fP را با \fIvalue3\fP برای \fB:foo:bar:frob\fP تعریف می‌نماید\&. هر \fIsubcontext\fP می‌تواند یک رشتهٔ خالی باشد تا همان زمینهٔ اول بدون تغییر مجددا استفاده شود\&.
.RE
.PP
.SS "سبک‌ها (Styles)"
.PP
.PD 0
.TP
.PD
\fBinsert\-tab\fP
تابع \fBzed\fP این سبک را در زمینهٔ `\fB:completion:zed:*\fP\&' \fIتنظیم می‌کند\fP تا در زمان فشرده شدن کلید \fBTAB\fP در ابتدای خط، کامل‌سازی غیرفعال شود\&. شما می‌توانید با تنظیم مقدار دلخواه خود برای این زمینه و سبک، این رفتار را بازنویسی کنید\&.
.TP
\fBpager\fP
تابع \fBnslookup\fP این سبک را در زمینهٔ `\fB:nslookup\fP\&' جستجو می‌کند تا برنامه‌ای را تعیین کند که برای نمایش خروجی‌های جا‌نشدنی در یک صفحهٔ منفرد استفاده می‌شود\&.
.TP
.PD 0
\fBprompt\fP
.TP
.PD
\fBrprompt\fP
تابع \fBnslookup\fP این سبک را در زمینهٔ `\fB:nslookup\fP\&' جستجو می‌کند تا به ترتیب اعلان (prompt) و اعلان سمت راست را تنظیم کند\&. بسط‌های معمول برای پارامترهای \fBPS1\fP و \fBRPS1\fP قابل استفاده هستند (بخش EXPANSION OF PROMPT SEQUENCES در \fIzshmisc\fP(1) را ببینید)\&.