.TH "ZSHMODULES" "1" "July 12, 2026" "zsh 5\&.9\&.2"
.SH "نام (NAME)"
zshmodules \- ماژول‌های بارگذاری‌پذیر پوسته زد (zsh)
.\" Yodl file: Zsh/modules.yo
.SH "توضیحات (DESCRIPTION)"
برخی از بخش‌های اختیاری zsh به صورت ماژول‌هایی جدا از هسته
پوسته قرار دارند\&. هر یک از این ماژول‌ها را می‌توان در زمان ساخت به
پوسته پیوند داد،
یا در صورتی که پیکربندی نصب از این قابلیت پشتیبانی کند،
در حین اجرای پوسته به صورت پویا متصل کرد\&.
ماژول‌ها در زمان اجرا با استفاده از دستور \fBzmodload\fP پیوند داده می‌شوند،
راهنمای \fIzshbuiltins\fP(1) را ببینید\&.
.PP
ماژول‌هایی که همراه با توزیع zsh عرضه می‌شوند عبارتند از:
.PP
.\" Yodl file: Zsh/modlist.yo
.PD 0
.TP
.PD
\fBzsh/attr\fP
دستورات توکار برای دستکاری صفات گسترش‌یافته (xattr)\&.
.TP
\fBzsh/cap\fP
دستورات توکار برای کار با مجموعه‌های قابلیت‌های (دسترسی‌های) POSIX\&.1e (POSIX\&.6)\&.
.TP
\fBzsh/clone\fP
یک دستور توکار که می‌تواند یک نمونه شبیه‌سازی‌شده از پوسته در حال اجرا را به ترمینال دیگری متصل کند\&.
.TP
\fBzsh/compctl\fP
دستور توکار \fBcompctl\fP برای کنترل کامل‌سازی\&.
.TP
\fBzsh/complete\fP
کد پایه و اصلی کامل‌سازی\&.
.TP
\fBzsh/complist\fP
افزونه‌های فهرست کردن گزینه‌های کامل‌سازی\&.
.TP
\fBzsh/computil\fP
ماژولی حاوی دستورات توکار کمکی مورد نیاز سیستم کامل‌سازی مبتنی بر توابع پوسته\&.
.TP
\fBzsh/curses\fP
دستورات مدیریت پنجره curses
.TP
\fBzsh/datetime\fP
تعدادی دستور و پارامتر مربوط به تاریخ و زمان\&.
.TP
\fBzsh/db/gdbm\fP
دستورات توکار برای مدیریت پارامترهای آرایه انجمنی متصل به پایگاه‌های داده GDBM\&.
.TP
\fBzsh/deltochar\fP
یک تابع ZLE که معادل عملکرد \fBzap\-to\-char\fP در ویرایشگر EMACS است\&.
.TP
\fBzsh/example\fP
یک نمونه از نحوه نوشتن ماژول\&.
.TP
\fBzsh/files\fP
برخی دستورات پایه برای دستکاری فایل به صورت دستور توکار\&.
.TP
\fBzsh/langinfo\fP
رابط دسترسی به اطلاعات محلی‌سازی (locale)\&.
.TP
\fBzsh/mapfile\fP
دسترسی به فایل‌های خارجی از طریق یک آرایه انجمنی ویژه\&.
.TP
\fBzsh/mathfunc\fP
توابع علمی استاندارد برای استفاده در ارزیابی‌های ریاضی\&.
.TP
\fBzsh/nearcolor\fP
نگاشت رنگ‌ها به نزدیک‌ترین رنگ در پالت رنگ موجود\&.
.TP
\fBzsh/newuser\fP
آماده‌سازی شرایط برای نصب فایل‌های پیکربندی کاربران جدید\&.
.TP
\fBzsh/parameter\fP
دسترسی به جدول‌های درهم‌سازی درونی از طریق آرایه‌های انجمنی ویژه\&.
.TP
\fBzsh/pcre\fP
رابط اتصال به کتابخانه عبارات منظم PCRE\&.
.TP
\fBzsh/param/private\fP
دستورات توکار برای مدیریت پارامترهای با حوزه خصوصی در بستر توابع\&.
.TP
\fBzsh/regex\fP
رابط اتصال به کتابخانه عبارات منظم POSIX\&.
.TP
\fBzsh/sched\fP
یک دستور توکار که امکان اجرای زمان‌بندی‌شده دستورها را در پوسته فراهم می‌کند\&.
.TP
\fBzsh/net/socket\fP
کار با سوکت‌های دامنه یونیکس
.TP
\fBzsh/stat\fP
رابط یک دستور توکار برای فراخوانی سیستمی \fBstat\fP\&.
.TP
\fBzsh/system\fP
یک رابط توکار برای دسترسی به ویژگی‌های سطح پایین گوناگون سیستم\&.
.TP
\fBzsh/net/tcp\fP
کار با سوکت‌های TCP
.TP
\fBzsh/termcap\fP
رابط کار با پایگاه‌داده termcap\&.
.TP
\fBzsh/terminfo\fP
رابط کار با پایگاه‌داده terminfo\&.
.TP
\fBzsh/watch\fP
گزارش رویدادهای ورود و خروج کاربران از سیستم\&.
.TP
\fBzsh/zftp\fP
یک کلاینت توکار FTP\&.
.TP
\fBzsh/zle\fP
ویرایشگر خط فرمان Zsh، شامل دستورات توکار \fBbindkey\fP و \fBvared\fP\&.
.TP
\fBzsh/zleparameter\fP
دسترسی به بخش‌های درونی ویرایشگر خط Zsh از طریق پارامترها\&.
.TP
\fBzsh/zprof\fP
ماژولی برای پروفایل‌سازی و تحلیل کارایی توابع پوسته\&.
.TP
\fBzsh/zpty\fP
یک دستور توکار برای راه‌اندازی یک دستور در یک شبه‌ترمینال\&.
.TP
\fBzsh/zselect\fP
مسدود کردن اجرا و بازگشت هنگام آماده شدن توصیف‌کننده‌های فایل\&.
.TP
\fBzsh/zutil\fP
تعدادی دستور توکار کمکی، برای نمونه ابزار پشتیبانی از پیکربندی از طریق سبک‌ها (styles)\&.
.\" Yodl file: Zsh/modmenu.yo
.SH "ماژول ZSH/ATTR (THE ZSH/ATTR MODULE)"
.\" Yodl file: Zsh/mod_attr.yo

ماژول \fBzsh/attr\fP برای دستکاری و مدیریت صفات گسترش‌یافته به کار می‌رود\&.
گزینه \fB\-h\fP باعث می‌شود تمام دستورها به جای اهداف پیوندها، روی پیوندهای نمادین
اعمال شوند\&.
دستورات توکار موجود در این ماژول عبارتند از:
.PP
.PD 0
.TP
.PD
\fBzgetattr\fP [ \fB\-h\fP ] \fIfilename\fP \fIattribute\fP [ \fIparameter\fP ]
صفت گسترش‌یافته \fIattribute\fP را از \fIfilename\fP مشخص‌شده دریافت می‌کند\&. در صورتی
که آرگومان اختیاری \fIparameter\fP داده شود، صفت در آن پارامتر مقداردهی می‌شود و
در خروجی استاندارد چاپ نخواهد شد\&.
.TP
\fBzsetattr\fP [ \fB\-h\fP ] \fIfilename\fP \fIattribute\fP \fIvalue\fP
صفت گسترش‌یافته \fIattribute\fP را روی \fIfilename\fP مشخص‌شده به مقدار \fIvalue\fP
تنظیم می‌کند\&.
.TP
\fBzdelattr\fP [ \fB\-h\fP ] \fIfilename\fP \fIattribute\fP
صفت گسترش‌یافته \fIattribute\fP را از \fIfilename\fP مشخص‌شده حذف می‌کند\&.
.TP
\fBzlistattr\fP [ \fB\-h\fP ] \fIfilename\fP [ \fIparameter\fP ]
فهرست صفات گسترش‌یافته تنظیم‌شده فعلی روی \fIfilename\fP مشخص‌شده را نمایش می‌دهد\&. در صورتی
که آرگومان اختیاری \fIparameter\fP داده شود، فهرست صفات در آن پارامتر ذخیره شده و به جای آن
در خروجی استاندارد چاپ نخواهد شد\&.
.PP
دستورات \fBzgetattr\fP و \fBzlistattr\fP حافظه را به صورت پویا تخصیص می‌دهند\&. اگر صفت یا
فهرست صفات در فاصله بین تخصیص حافظه و فراخوانی دریافت آن‌ها افزایش یابد، مقدار 2 را بازمی‌گردانند\&.
در سایر خطاها، مقدار 1 بازگردانده می‌شود\&. این سازوکار به تابع فراخوان امکان می‌دهد
این وضعیت را بررسی کرده و دوباره تلاش کند\&.
.SH "ماژول ZSH/CAP (THE ZSH/CAP MODULE)"
.\" Yodl file: Zsh/mod_cap.yo

ماژول \fBzsh/cap\fP برای دستکاری مجموعه‌های قابلیت‌های POSIX\&.1e (POSIX\&.6) به کار می‌رود\&.
چنانچه سیستم‌عامل از این رابط پشتیبانی نکند، دستورات توکار تعریف‌شده توسط این ماژول هیچ کاری انجام نمی‌دهند\&.
دستورات توکار این ماژول عبارتند از:
.PP
.PD 0
.TP
.PD
\fBcap\fP [ \fIcapabilities\fP ]
مجموعه قابلیت‌های پردازش پوسته را به \fIcapabilities\fP مشخص‌شده تغییر می‌دهد،
در غیر این صورت قابلیت‌های جاری پوسته را نمایش می‌دهد\&.
.TP
\fBgetcap\fP \fIfilename\fP \&.\&.\&.
این یک پیاده‌سازی درونی (توکار) از ابزار استاندارد POSIX است\&. مجموعه‌های
قابلیت را روی هر \fIfilename\fP مشخص‌شده نمایش می‌دهد\&.
.TP
\fBsetcap\fP \fIcapabilities\fP \fIfilename\fP \&.\&.\&.
این یک پیاده‌سازی درونی از ابزار استاندارد POSIX است\&. مجموعه‌های قابلیت را
روی هر \fIfilename\fP مشخص‌شده به \fIcapabilities\fP داده‌شده تنظیم می‌کند\&.
.SH "ماژول ZSH/CLONE (THE ZSH/CLONE MODULE)"
.\" Yodl file: Zsh/mod_clone.yo

ماژول \fBzsh/clone\fP یک دستور توکار در دسترس قرار می‌دهد:
.PP
.PD 0
.TP
.PD
\fBclone\fP \fItty\fP
یک نمونه منشعب‌شده (forked) از پوسته فعلی ایجاد می‌کند که به \fItty\fP مشخص‌شده
متصل است\&. در پوسته جدید، پارامترهای ویژه \fBPID\fP، \fBPPID\fP و \fBTTY\fP به شکل
مناسب تغییر می‌کنند\&. مقدار \fB$!\fP در پوسته جدید برابر صفر، و در پوسته اصلی
برابر با PID پوسته جدید تنظیم می‌شود\&.
.RS
.PP
وضعیت خروجی این دستور توکار در هر دو پوسته در صورت موفقیت برابر صفر،
و در صورت بروز خطا غیر صفر است\&.
.PP
مقصد \fBclone\fP باید یک ترمینال بلااستفاده باشد، مانند یک کنسول مجازی بدون استفاده
یا یک ترمینال مجازی که توسط دستور زیر ایجاد شده است:
.PP
.RS
.nf
\fBxterm \-e sh \-c \&'trap : INT QUIT TSTP; tty;
        while :; do sleep 100000000; done\&'\fP
.fi
.RE
.PP
توضیحاتی درباره این خط فرمان طولانی xterm لازم است: هنگام شبیه‌سازی روی یک
شبه‌ترمینال، نشست دیگری («نشست» در مفهوم گروه نشست یونیکس یا SID) پیش‌تر مالکیت ترمینال
را در اختیار دارد\&. بنابراین zsh شبیه‌سازی‌شده نمی‌تواند شبه‌ترمینال را به عنوان
tty کنترل‌کننده تصاحب کند\&. این موضوع متضمن دو نکته است:
.PP
.PD 0
.TP
.PD
\(bu
سیگنال‌های کنترل شغل (job control) به گروه پردازش sh\-started\-by\-xterm ارسال خواهند شد
(به همین دلیل سیگنال‌های INT، QUIT و TSTP را با trap غیرفعال می‌کنیم؛ در غیر این صورت
حلقه while ممکن است متوقف یا کشته شود)
.TP
\(bu
در پوسته شبیه‌سازی‌شده کنترل شغل غیرفعال خواهد بود و کلیدهای کنترل شغل
(شامل control\-C، control\-\e و control\-Z) کار نخواهند کرد\&.
.PP
این موضوع در زمان شبیه‌سازی روی یک vc \fIاستفاده‌نشده\fP صدق نمی‌کند\&.
.PP
شبیه‌سازی روی ترمینالِ در حال استفاده (و آماده‌نشده) باعث می‌شود دو پردازش
به طور همزمان از یک ترمینال بخوانند و بایت‌های ورودی به صورت تصادفی به هر یک از
دو پردازش برسد\&.
.PP
دستور \fBclone\fP بیشتر به عنوان یک جایگزین توکار پوسته برای openvt مفید است\&.
.RE
.SH "ماژول ZSH/COMPCTL (THE ZSH/COMPCTL MODULE)"
.\" Yodl file: Zsh/mod_compctl.yo

ماژول \fBzsh/compctl\fP دو دستور توکار را فراهم می‌کند\&. دستور \fBcompctl\fP،
روش قدیمی و منسوخ‌شده برای کنترل کامل‌سازی‌ها در ZLE است\&. به
\fIzshcompctl\fP(1) مراجعه کنید\&.
دستور توکار دیگر، \fBcompcall\fP، می‌تواند در ویجت‌های کامل‌سازی تعریف‌شده توسط کاربر
به کار رود، راهنمای \fIzshcompwid\fP(1) را ببینید\&.
.SH "ماژول ZSH/COMPLETE (THE ZSH/COMPLETE MODULE)"
.\" Yodl file: Zsh/mod_complete.yo

ماژول \fBzsh/complete\fP چندین دستور توکار در دسترس قرار می‌دهد که می‌توانند
در ویجت‌های کامل‌سازی تعریف‌شده توسط کاربر استفاده شوند، راهنمای
\fIzshcompwid\fP(1) را ببینید\&.
.SH "ماژول ZSH/COMPLIST (THE ZSH/COMPLIST MODULE)"
.\" Yodl file: Zsh/mod_complist.yo

ماژول \fBzsh/complist\fP سه قابلیت تکمیلی برای فهرست‌های کامل‌سازی ارائه می‌دهد:
امکان برجسته‌سازی و رنگ‌آمیزی موارد تطبیق‌یافته در فهرست، امکان
پیمایش (اسکرول) در فهرست‌های طولانی، و سبک متفاوتی از کامل‌سازی منویی\&.
.PP
.SS "فهرست‌های رنگی کامل‌سازی (Colored completion listings)"
هر زمان که یکی از پارامترهای \fBZLS_COLORS\fP یا \fBZLS_COLOURS\fP تنظیم شده باشد
و ماژول \fBzsh/complist\fP در پوسته بارگذاری یا پیوند داده شده باشد،
فهرست‌های کامل‌سازی رنگی خواهند شد\&. توجه داشته باشید که در صورت عدم پیوند درونی،
\fBcomplist\fP به طور خودکار بارگذاری نمی‌شود: در سیستم‌های دارای قابلیت
بارگذاری پویا، اجرای دستور `\fBzmodload zsh/complist\fP\&' الزامی است\&.
.PP
پارامترهای \fBZLS_COLORS\fP و \fBZLS_COLOURS\fP نحوه برجسته‌سازی تطابق‌ها را
مشخص می‌کنند\&. برای فعال‌سازی برجسته‌سازی، یک مقدار خالی کافی است که در
این حالت تمام مقادیر پیش‌فرض ارائه‌شده در زیر به کار خواهند رفت\&. قالب
مقدار این پارامترها مشابه قالب به‌کاررفته در نسخه GNU دستور
\fBls\fP است: فهرستی جداشده با دونقطه (\fB:\fP) از مشخصه‌ها به صورت
`\fIname\fP\fB=\fP\fIvalue\fP\&'\&. مقدار \fIname\fP می‌تواند یکی از رشته‌های زیر باشد
که بیشتر آن‌ها انواع فایل را برای تعیین \fIvalue\fP مشخص می‌کنند\&.
این رشته‌ها و مقادیر پیش‌فرض آن‌ها عبارتند از:
.PP
.PD 0
.TP
.PD
\fBno 0\fP
برای متن معمولی (یعنی هنگام نمایش مواردی غیر از یک فایل تطبیق‌یافته)
.TP
\fBfi 0\fP
برای فایل‌های عادی (regular files)
.TP
\fBdi 32\fP
برای دایرکتوری‌ها
.TP
\fBln 36\fP
برای پیوندهای نمادین (symbolic links)\&. اگر این فیلد مقدار ویژه \fBtarget\fP را داشته باشد،
پیوندهای نمادین مرجع‌گشایی شده و از فایل هدف برای تعیین قالب نمایش استفاده می‌شود\&.
.TP
\fBpi 31\fP
برای لوله‌های نام‌گذاری‌شده (FIFOs)
.TP
\fBso 33\fP
برای سوکت‌ها
.TP
\fBbd 44;37\fP
برای دستگاه‌های بلوکی (block devices)
.TP
\fBcd 44;37\fP
برای دستگاه‌های کاراکتری (character devices)
.TP
\fBor\fP \fInone\fP
برای پیوند نمادین شکسته یا اشاره‌کننده به فایل ناموجود (پیش‌فرض، مقدار تعریف‌شده برای \fBln\fP است)
.TP
\fBmi\fP \fInone\fP
برای یک فایل ناموجود (پیش‌فرض، مقدار تعریف‌شده برای \fBfi\fP است)؛ این کد در حال حاضر استفاده نمی‌شود
.TP
\fBsu 37;41\fP
برای فایل‌های دارای بیت setuid
.TP
\fBsg 30;43\fP
برای فایل‌های دارای بیت setgid
.TP
\fBtw 30;42\fP
برای دایرکتوری‌های قابل نوشتن همگانی دارای بیت چسبان (sticky bit)
.TP
\fBow 34;43\fP
برای دایرکتوری‌های قابل نوشتن همگانی بدون بیت چسبان
.TP
\fBsa\fP \fInone\fP
برای فایل‌های دارای نام مستعار پسوند (suffix alias)؛ این مورد فقط پس از بررسی پسوندهای خاص آزموده می‌شود، همان‌طور که در زیر شرح داده شده است
.TP
\fBst 37;44\fP
برای دایرکتوری‌های دارای بیت چسبان که برای عموم قابل نوشتن نیستند
.TP
\fBex 35\fP
برای فایل‌های اجرایی
.TP
\fBlc \ee[\fP
برای کد سمت چپ (به توضیحات زیر مراجعه کنید)
.TP
\fBrc m\fP
برای کد سمت راست
.TP
\fBtc 0\fP
برای نویسه نشان‌دهنده نوع فایل که پس از نام فایل چاپ می‌شود، در صورتی که گزینه \fBLIST_TYPES\fP تنظیم شده باشد
.TP
\fBsp 0\fP
برای فاصله‌هایی که پس از موارد تطبیق‌یافته جهت تراز کردن ستون بعدی چاپ می‌شوند
.TP
\fBec\fP \fInone\fP
برای کد پایانی
.PP
به جز این رشته‌ها، \fIname\fP می‌تواند یک علامت ستاره (`\fB*\fP\&') و
به دنبال آن هر رشته دلخواهی باشد\&. مقدار \fIvalue\fP ارائه‌شده برای چنین
رشته‌ای برای تمام فایل‌هایی که نامشان با آن رشته خاتمه می‌یابد استفاده خواهد شد\&.
همچنین \fIname\fP می‌تواند یک علامت مساوی (`\fB=\fP\&') همراه با یک
الگو باشد؛ برای ارزیابی این الگو گزینه \fBEXTENDED_GLOB\fP فعال خواهد شد\&. مقدار
\fIvalue\fP ارائه‌شده برای این الگو برای تمام موارد تطبیق‌یافته‌ای (نه فقط نام فایل‌ها)
که رشته نمایشی آن‌ها با الگو مطابقت داشته باشد استفاده می‌شود\&. تعاریف دارای علامت
مساوی اولیه نسبت به مقادیر تعریف‌شده برای انواع فایل اولویت دارند، و این مقادیر
نیز به نوبه خود نسبت به مشخصه‌های دارای علامت ستاره (پسوند فایل‌ها) ارجحیت دارند\&.
.PP
قالب دارای مساوی اولیه همچنین امکان رنگ‌آمیزی متمایز بخش‌های گوناگون یک رشته
نمایشی را فراهم می‌کند\&. برای این کار، الگو باید از پرچم الگوبرداری `\fB(#b)\fP\&'
و جفت‌پرانتزهایی در اطراف بخش‌هایی از رشته که قرار است با رنگ دیگری نمایش داده شوند
استفاده کند\&. در این حالت، \fIvalue\fP می‌تواند شامل چند کد رنگی جداشده با علامت مساوی
باشد\&. اولین کد برای تمام بخش‌هایی به کار می‌رود که کد صریحی برایشان تعیین نشده است
و کدهای بعدی برای بخش‌های منطبق با زیرالگوهای داخل پرانتز اعمال می‌شوند\&. به عنوان
مثال، مشخصه `\fB=(#b)(?)*(?)=0=3=7\fP\&' برای تمام مواردی که حداقل دو نویسه طول دارند
استفاده می‌شود و کد `\fB3\fP\&' را برای نویسه نخست، `\fB7\fP' را برای نویسه پایانی
و `\fB0\fP\&' را برای سایر بخش‌ها به کار می‌برد\&.
.PP
هر سه حالت \fIname\fP می‌توانند با یک الگو درون پرانتز آغاز شوند\&. در صورت درج چنین الگویی،
مقدار \fIvalue\fP فقط برای مواردی به کار خواهد رفت که در گروه‌های منطبق با الگوی درون
پرانتز قرار داشته باشند\&. برای مثال، `\fB(g*)m*=43\fP\&' تمام موارد تطبیق‌یافته‌ای را
که با `\fBm\fP\&' شروع می‌شوند در گروه‌هایی که نامشان با `\fBg\fP\&' آغاز می‌شود با کد
رنگ `\fB43\fP' برجسته می‌کند\&. در مورد کدهای `\fBlc\fP'، `\fBrc\fP\&' و `\fBec\fP'، الگوی
گروه نادیده گرفته می‌شود\&.
.PP
توجه داشته باشید که تمام الگوها به ترتیب حضور در مقدار پارامتر ارزیابی می‌شوند
تا اولین الگوی منطبق تعیین و استفاده شود\&. الگوها می‌توانند با موارد کامل‌سازی، توضیحات
(احتمالاً همراه با فاصله‌های الحاق‌شده جهت تراز) یا خطوطی متشکل از مورد کامل‌سازی و به دنبال
آن توضیح تطبیق داده شوند\&. برای یکپارچگی رنگ‌آمیزی ممکن است نیاز باشد از چند الگو
یا الگویی همراه با ارجاع به عقب (backreferences) استفاده شود\&.
.PP
هنگام چاپ یک مورد، کد ابتدا مقدار \fBlc\fP، سپس مقدار نوع فایل یا آخرین مشخصه منطبق
دارای `\fB*\fP\&'، سپس مقدار \fBrc\fP، خود رشته نمایشی مورد تطبیق، و در نهایت مقدار \fBec\fP
(در صورت تعریف) یا مقادیر \fBlc\fP، \fBno\fP و \fBrc\fP (اگر \fBec\fP تعریف نشده باشد) را چاپ می‌کند\&.
.PP
مقادیر پیش‌فرض با استاندارد ISO 6429 (ANSI) سازگار هستند و می‌توانند در ترمینال‌های
سازگار با vt100 مانند \fBxterm\fP استفاده شوند\&. در ترمینال‌های تک‌رنگ، مقادیر پیش‌فرض
تأثیر بصری نخواهند داشت\&. تابع \fBcolors\fP موجود در بسته‌های الحاقی (contribution)
را می‌توان برای دریافت آرایه‌های انجمنی حاوی کدهای ترمینال‌های ANSI به کار برد (بخش
`Other Functions\&' را در \fIzshcontrib\fP(1) ببینید)\&. برای نمونه پس از بارگذاری \fBcolors\fP،
می‌توان از `\fB$color[red]\fP\&' برای دریافت کد رنگ پیش‌زمینه قرمز و از
`\fB$color[bg\-green]\fP\&' برای کد رنگ پس‌زمینه سبز استفاده کرد\&.
.PP
اگر از سیستم کامل‌سازی فراخوانی‌شده توسط compinit استفاده شود، این پارامترها نباید
مستقیماً مقداردهی شوند زیرا خود سیستم آن‌ها را مدیریت می‌کند\&. در عوض، باید از
سبک \fBlist\-colors\fP استفاده شود (بخش `Completion System Configuration\&' را
در \fIzshcompsys\fP(1) ببینید)\&.
.PP
.SS "پیمایش در فهرست‌های کامل‌سازی (Scrolling in completion listings)"
برای فعال‌سازی قابلیت پیمایش (اسکرول) در فهرست کامل‌سازی، پارامتر \fBLISTPROMPT\fP
باید تنظیم شود\&. مقدار آن به عنوان اعلان (prompt) به کار می‌رود؛ اگر یک رشته خالی باشد،
یک اعلان پیش‌فرض نمایش خواهد یافت\&. این مقدار می‌تواند شامل کاراکترهای اسکیپ به فرم
`\fB%x\fP\&' باشد\&. این پارامتر از دنباله‌های اسکیپ `\fB%B\fP\&'، `\fB%b\fP'، `\fB%S\fP'،
`\fB%s\fP'، `\fB%U\fP'، `\fB%u\fP'، `\fB%F\fP'، `\fB%f\fP\&'، `\fB%K\fP'، `\fB%k\fP' و
`\fB%{\fP\fI\&.\&.\&.\fP\fB%}\fP\&' که در اعلان‌های پوسته نیز کاربرد دارند، و همچنین سه جفت دنباله اضافی
پشتیبانی می‌کند: `\fB%l\fP\&' یا `\fB%L\fP' با شماره آخرین خط نمایش‌داده‌شده و تعداد کل
خطوط به صورت `\fInumber\fP\fB/\fP\fItotal\fP\&' جایگزین می‌شود؛ `\fB%m\fP' یا `\fB%M\fP' با
شماره آخرین مورد نمایش‌یافته و تعداد کل موارد جایگزین می‌گردد؛ و `\fB%p\fP\&' یا `\fB%P\fP'
به ترتیب با `\fBTop\fP'، `\fBBottom\fP' یا موقعیت خط اول نمایش‌یافته برحسب درصد کل
خطوط جایگزین خواهد شد\&. در هر یک از این حالات، نسخه با حروف بزرگ با یک رشته با عرض
ثابت که از سمت راست با فاصله پر شده جایگزین می‌شود، در حالی که نسخه با حروف کوچک پر نمی‌شود\&.
.PP
اگر پارامتر \fBLISTPROMPT\fP تنظیم شده باشد، کد کامل‌سازی برای نمایش فهرست سؤالی نمی‌پرسد\&.
در عوض بلافاصله شروع به نمایش فهرست کرده، پس از پر شدن صفحه اول متوقف می‌شود، اعلان را در پایین
صفحه نمایش می‌دهد و پس از جابه‌جایی موقت به نقشه کلید \fBlistscroll\fP، منتظر فشرده شدن یک کلید می‌ماند\&.
برخی از توابع zle هنگام پیمایش فهرست‌ها معنای ویژه‌ای دارند:
.PP
.PD 0
.TP
.PD
\fBsend\-break\fP
نمایش فهرست را متوقف کرده و کلید فشرده‌شده را نادیده می‌گیرد
.TP
.PD 0
\fBaccept\-line\fP, \fBdown\-history\fP, \fBdown\-line\-or\-history\fP
.TP
.PD
\fBdown\-line\-or\-search\fP, \fBvi\-down\-line\-or\-history\fP
فهرست را یک خط به جلو می‌پیماید
.TP
.PD 0
\fBcomplete\-word\fP, \fBmenu\-complete\fP, \fBexpand\-or\-complete\fP
.TP
.PD
\fBexpand\-or\-complete\-prefix\fP, \fBmenu\-complete\-or\-expand\fP
فهرست را به اندازه یک صفحه کامل به جلو می‌پیماید
.TP
.PD
\fBaccept\-search\fP
نمایش فهرست را متوقف می‌کند اما اقدام دیگری انجام نمی‌دهد
.PP
هر نویسه دیگری نمایش فهرست را متوقف کرده و کلید مربوطه بلافاصله طبق معمول پردازش می‌شود\&.
هر کلیدی که در نقشه کلید \fBlistscroll\fP مقید نشده باشد یا به \fBundefined\-key\fP مقید شده
باشد، در نقشه کلید فعال فعلی جستجو و اجرا می‌گردد\&.
.PP
همانند پارامترهای \fBZLS_COLORS\fP و \fBZLS_COLOURS\fP، پارامتر \fBLISTPROMPT\fP نیز
هنگام استفاده از سیستم کامل‌سازی مبتنی بر توابع پوسته نباید مستقیماً تنظیم شود\&. در عوض،
باید سبک \fBlist\-prompt\fP به کار رود\&.
.PP
.SS "انتخاب منو (Menu selection)"
ماژول \fBzsh/complist\fP سبک دیگری برای انتخاب موارد از یک فهرست ارائه می‌دهد که انتخاب منو (menu selection)
نامیده می‌شود؛ این قابلیت زمانی قابل استفاده است که پوسته به گونه‌ای تنظیم شده باشد که پس از نمایش
فهرست کامل‌سازی به آخرین اعلان بازگردد (گزینه \fBALWAYS_LAST_PROMPT\fP را در
\fIzshoptions\fP(1) ببینید)\&.
.PP
انتخاب منو را می‌توان مستقیماً توسط ویجت \fBmenu\-select\fP تعریف‌شده در این ماژول فراخوانی کرد\&.
این یک ویجت استاندارد ZLE است که می‌توان آن را طبق روال معمول شرح‌داده‌شده در
\fIzshzle\fP(1) به یک کلید مقید کرد\&.
.PP
به عنوان روش دیگر، می‌توان پارامتر \fBMENUSELECT\fP را به یک عدد صحیح تنظیم کرد که حداقل
تعداد موارد تطبیق‌یافته لازم برای فعال‌سازی خودکار انتخاب منو را تعیین می‌کند\&. این روش دوم
نیازمند آن است که کامل‌سازی منویی آغاز شده باشد، چه مستقیماً از طریق یک ویجت نظیر \fBmenu\-complete\fP
و چه به دلیل تنظیم بودن یکی از گزینه‌های \fBMENU_COMPLETE\fP یا \fBAUTO_MENU\fP\&. اگر
\fBMENUSELECT\fP تنظیم شده باشد اما مقدار آن 0، 1 یا خالی باشد، انتخاب منو همواره در طول یک
کامل‌سازی منویی دارای ابهام آغاز خواهد شد\&.
.PP
هنگام استفاده از سیستم کامل‌سازی مبتنی بر توابع پوسته، پارامتر \fBMENUSELECT\fP نباید استفاده
شود (مشابه پارامترهای \fBZLS_COLORS\fP و \fBZLS_COLOURS\fP که پیش‌تر توضیح داده شد)\&. در عوض،
باید از سبک \fBmenu\fP همراه با کلیدواژه \fBselect=\fP\fI\&.\&.\&.\fP استفاده گردد\&.
.PP
پس از آغاز انتخاب منو، موارد تطبیق‌یافته فهرست می‌شوند\&. اگر تعداد موارد بیش از ظرفیت صفحه
باشد، فقط صفحه اول نمایش داده می‌شود\&. مواردی که باید در خط فرمان درج شوند را می‌توان از این
فهرست برگزید\&. در فهرست، یکی از موارد با استفاده از مقدار مشخص‌شده برای \fBma\fP در پارامترهای
\fBZLS_COLORS\fP یا \fBZLS_COLOURS\fP برجسته می‌شود\&. مقدار پیش‌فرض آن `\fB7\fP\&' است که باعث
می‌شود مورد انتخاب‌شده با حالت برجسته (standout mode) در ترمینال‌های سازگار با vt100 نمایش یابد\&. اگر
هیچ‌یک از پارامترهای \fBZLS_COLORS\fP یا \fBZLS_COLOURS\fP تنظیم نشده باشند، از همان دنباله
کنترلی ترمینال که برای اسکیپ `\fB%S\fP\&' در اعلان‌ها به کار می‌رود استفاده خواهد شد\&.
.PP
اگر تعداد موارد بیشتر از گنجایش صفحه باشد و پارامتر \fBMENUPROMPT\fP تنظیم شده باشد، مقدار آن در
زیر موارد نمایش داده می‌شود\&. این پارامتر از دنباله‌های اسکیپ مشابه با \fBLISTPROMPT\fP پشتیبانی
می‌کند، با این تفاوت که شماره مورد یا خط نشان‌داده‌شده مربوط به موقعیت نشانگر خواهد بود\&. اگر مقدار
آن یک رشته خالی باشد، یک اعلان پیش‌فرض به کار خواهد رفت\&.
.PP
پارامتر \fBMENUSCROLL\fP می‌تواند برای تعیین چگونگی پیمایش فهرست استفاده شود\&. اگر این پارامتر
تنظیم نشده باشد، پیمایش به صورت خط‌به‌خط انجام می‌گیرد؛ اگر مقدار آن برابر `\fB0\fP\&' (صفر) باشد،
فهرست به اندازه نیمی از تعداد خطوط صفحه پیمایش می‌شود\&. اگر مقدار آن مثبت باشد، بیانگر تعداد
خطوط پیمایش است و اگر منفی باشد، فهرست به اندازه تعداد خطوط صفحه منهای قدر مطلق آن مقدار پیمایش می‌گردد\&.
.PP
همانند پارامترهای \fBZLS_COLORS\fP، \fBZLS_COLOURS\fP و \fBLISTPROMPT\fP، پارامترهای
\fBMENUPROMPT\fP و \fBMENUSCROLL\fP نیز نباید هنگام استفاده از سیستم کامل‌سازی مبتنی بر توابع پوسته
مستقیماً تنظیم شوند\&. در عوض، باید سبک‌های \fBselect\-prompt\fP و \fBselect\-scroll\fP به کار روند\&.
.PP
کد کامل‌سازی گاهی اوقات تصمیم می‌گیرد همه موارد تطبیق‌یافته را در فهرست نمایش ندهد\&. این موارد پنهان
یا مواردی هستند که تابع کامل‌سازی افزوده‌کننده آن‌ها صریحاً درخواست کرده در فهرست ظاهر نشوند (با استفاده
از گزینه \fB\-n\fP دستور توکار \fBcompadd\fP)، یا مواردی هستند که یک رشته موجود در فهرست را تکرار می‌کنند
(زیرا تنها در مواردی مانند پیشوندها یا پسوندهایی تفاوت دارند که نمایش داده نمی‌شوند)\&. با این حال در
فهرست مورد استفاده برای انتخاب منو، حتی این موارد نیز نمایش داده می‌شوند تا امکان انتخاب آن‌ها وجود داشته
باشد\&. برای برجسته‌سازی چنین مواردی، قابلیت‌های \fBhi\fP و \fBdu\fP در پارامترهای \fBZLS_COLORS\fP و
\fBZLS_COLOURS\fP به ترتیب برای موارد پنهان نوع اول و دوم پشتیبانی می‌شوند\&.
.PP
انتخاب موارد با جابه‌جا کردن نشانگر با استفاده از توابع حرکتی zle صورت می‌گیرد\&. هنگامی که همه موارد
به طور همزمان در صفحه جا نمی‌شوند، فهرست هنگام عبور از خط بالایی یا پایینی به بالا و پایین پیمایش
می‌شود\&. توابع zle زیر در هنگام انتخاب منو معنای ویژه‌ای دارند\&. توجه داشته باشید که موارد زیر
همواره عمل یکسانی را در نقشه انتخاب منو انجام می‌دهند و نمی‌توان آن‌ها را با ویجت‌های تعریف‌شده توسط
کاربر جایگزین کرد، و مجموعه این توابع نیز قابل گسترش نیست:
.PP
.PD 0
.TP
.PD
\fBaccept\-line\fP, \fBaccept\-search\fP
مورد تطبیق‌یافته فعلی را می‌پذیرد و از انتخاب منو خارج می‌شود (اما باعث تأیید و اجرای خط فرمان نمی‌شود)
.TP
\fBsend\-break\fP
از انتخاب منو خارج شده و محتوای قبلی خط فرمان را بازمی‌گرداند
.TP
\fBredisplay\fP, \fBclear\-screen\fP
عملکرد عادی خود را بدون خروج از انتخاب منو اجرا می‌کنند
.TP
\fBaccept\-and\-hold\fP, \fBaccept\-and\-menu\-complete\fP
مورد درج‌شده فعلی را پذیرفته و انتخاب را ادامه می‌دهند تا امکان انتخاب مورد بعدی برای درج در خط فرمان فراهم باشد
.TP
\fBaccept\-and\-infer\-next\-history\fP
مورد فعلی را می‌پذیرد و سپس مجدداً کامل‌سازی را همراه با انتخاب منو امتحان می‌کند؛ در مورد فایل‌ها این ویژگی
امکان می‌دهد یک دایرکتوری را انتخاب کرده و بلافاصله تلاش برای کامل‌سازی فایل‌های درون آن آغاز شود؛ اگر
موردی یافت نشد پیامی نمایش داده می‌شود و می‌توان با \fBundo\fP به کامل‌سازی در سطح قبلی بازگشت؛ هر کلید دیگری
از انتخاب منو خارج می‌شود (از جمله سایر توابع zle که در حالت عادی در طول انتخاب منو رفتار ویژه‌ای دارند)
.TP
\fBundo\fP
موارد درج‌شده در طول انتخاب منو توسط یکی از سه تابع قبلی را حذف می‌کند
.TP
.PD 0
\fBdown\-history\fP, \fBdown\-line\-or\-history\fP
.TP
.PD
\fBvi\-down\-line\-or\-history\fP, \fBdown\-line\-or\-search\fP
نشانگر را یک خط به پایین حرکت می‌دهد
.TP
.PD 0
\fBup\-history\fP, \fBup\-line\-or\-history\fP
.TP
.PD
\fBvi\-up\-line\-or\-history\fP, \fBup\-line\-or\-search\fP
نشانگر را یک خط به بالا حرکت می‌دهد
.TP
\fBforward\-char\fP, \fBvi\-forward\-char\fP
نشانگر را یک ستون به راست حرکت می‌دهد
.TP
\fBbackward\-char\fP, \fBvi\-backward\-char\fP
نشانگر را یک ستون به چپ حرکت می‌دهد
.TP
.PD 0
\fBforward\-word\fP, \fBvi\-forward\-word\fP
.TP
.PD
\fBvi\-forward\-word\-end\fP, \fBemacs\-forward\-word\fP
نشانگر را یک صفحه کامل به پایین حرکت می‌دهد
.TP
\fBbackward\-word\fP, \fBvi\-backward\-word\fP, \fBemacs\-backward\-word\fP
نشانگر را یک صفحه کامل به بالا حرکت می‌دهد
.TP
\fBvi\-forward\-blank\-word\fP, \fBvi\-forward\-blank\-word\-end\fP
نشانگر را به خط اول گروه بعدی موارد حرکت می‌دهد
.TP
\fBvi\-backward\-blank\-word\fP
نشانگر را به آخرین خط گروه قبلی موارد حرکت می‌دهد
.TP
\fBbeginning\-of\-history\fP
نشانگر را به خط اول منتقل می‌کند
.TP
\fBend\-of\-history\fP
نشانگر را به آخرین خط منتقل می‌کند
.TP
.PD 0
\fBbeginning\-of\-buffer\-or\-history\fP, \fBbeginning\-of\-line\fP
.TP
.PD
\fBbeginning\-of\-line\-hist\fP, \fBvi\-beginning\-of\-line\fP
نشانگر را به چپ‌ترین ستون منتقل می‌کند
.TP
.PD 0
\fBend\-of\-buffer\-or\-history\fP, \fBend\-of\-line\fP
.TP
.PD
\fBend\-of\-line\-hist\fP, \fBvi\-end\-of\-line\fP
نشانگر را به راست‌ترین ستون منتقل می‌کند
.TP
.PD 0
\fBcomplete\-word\fP, \fBmenu\-complete\fP, \fBexpand\-or\-complete\fP
.TP
.PD
\fBexpand\-or\-complete\-prefix\fP, \fBmenu\-expand\-or\-complete\fP
نشانگر را به مورد بعدی منتقل می‌کند
.TP
\fBreverse\-menu\-complete\fP
نشانگر را به مورد قبلی منتقل می‌کند
.TP
\fBvi\-insert\fP
حالت را بین عادی و تعاملی تغییر می‌دهد؛ در حالت تعاملی کلیدهای مقید به \fBself\-insert\fP و
\fBself\-insert\-unmeta\fP مانند حالت ویرایش عادی نویسه را در خط فرمان درج می‌کنند اما بدون آنکه
از انتخاب منو خارج شوند؛ پس از هر نویسه کامل‌سازی مجدداً آزموده می‌شود و فهرست تغییر می‌کند تا تنها
شامل موارد تطبیق جدید باشد؛ ویجت‌های کامل‌سازی طولانی‌ترین رشته بدون ابهام را در خط فرمان درج می‌کنند
و \fBundo\fP و \fBbackward\-delete\-char\fP به مجموعه موارد قبلی بازمی‌گردند
.TP
.PD 0
\fBhistory\-incremental\-search\-forward\fP
.TP
.PD
\fBhistory\-incremental\-search\-backward\fP
جستجوی افزایشی را در فهرست کامل‌سازی‌های نمایش‌یافته آغاز می‌کند؛ در این حالت، \fBaccept\-line\fP
فقط از جستجوی افزایشی خارج شده و به حالت انتخاب منوی عادی بازمی‌گردد
.PP
تمام توابع حرکتی در لبه‌ها دچار چرخش (wrap around) می‌شوند؛ هر تابع zle دیگری که در فهرست بالا نیامده
است باعث خروج از انتخاب منو و اجرای آن تابع می‌شود\&. با قرار دادن یک `\fB\&.\fP\&' در ابتدای نام ویجت
می‌توان ویجت‌های موجود در فهرست فوق را نیز وادار به همین رفتار کرد\&. برای نمونه، ویجت `\fB\&.accept\-line\fP'
باعث خروج از انتخاب منو و پذیرش کل خط فرمان می‌شود\&.
.PP
در طول این انتخاب، ویجت از نقشه کلید \fBmenuselect\fP استفاده می‌کند\&. هر کلیدی که در این نقشه کلید
تعریف نشده باشد یا به \fBundefined\-key\fP مقید شده باشد، در نقشه کلید فعال فعلی جستجو می‌شود\&. این
سازوکار به منظور اطمینان از این است که کلیدهای اصلی مورد استفاده در طول انتخاب (به‌ویژه کلیدهای جهت‌نما،
return و TAB) پیش‌فرض‌های معقولی داشته باشند\&. با این حال، کلیدهای موجود در نقشه کلید \fBmenuselect\fP
را می‌توان مستقیماً با استفاده از دستور توکار \fBbindkey\fP تغییر داد (راهنمای
\fIzshmodules\fP(1) را ببینید)\&. برای مثال برای اینکه کلید return بدون پذیرش مورد انتخاب‌شده فعلی از انتخاب
منو خارج شود، می‌توان پس از بارگذاری ماژول \fBzsh/complist\fP دستور زیر را فراخوانی کرد:
.PP
.RS
.nf
\fBbindkey \-M menuselect \&'^M' send\-break\fP
.fi
.RE
.PP
.SH "ماژول ZSH/COMPUTIL (THE ZSH/COMPUTIL MODULE)"
.\" Yodl file: Zsh/mod_computil.yo

ماژول \fBzsh/computil\fP چندین دستور توکار اضافه می‌کند که توسط برخی از
توابع کامل‌سازی در سیستم کامل‌سازی مبتنی بر توابع پوسته استفاده می‌شوند (راهنمای
\fIzshcompsys\fP(1)
را ببینید)\&. به استثنای \fBcompquote\fP، این دستورات توکار بسیار تخصصی
هستند و بنابراین هنگام نوشتن توابع کامل‌سازی اختصاصی چندان کاربرد عمومی
ندارند\&. به طور خلاصه، این دستورات توکار عبارتند از:
.PP
.PD 0
.TP
.PD
\fBcomparguments\fP
این دستور توسط تابع \fB_arguments\fP برای تجزیه آرگومان‌ها و خط فرمان
استفاده می‌شود\&. همانند \fBcompdescribe\fP، این دستور نیز گزینه \fB\-i\fP برای
انجام تجزیه و مقداردهی اولیه برخی وضعیت‌های درونی، و گزینه‌های گوناگونی برای دسترسی
به اطلاعات وضعیت جهت تصمیم‌گیری در مورد آنچه باید کامل شود دارد\&.
.TP
\fBcompdescribe\fP
توسط تابع \fB_describe\fP برای ساخت رشته‌های نمایشی موارد تطبیق‌یافته و دریافت رشته‌هایی
که باید به همراه گزینه‌هایشان به عنوان تطابق اضافه شوند استفاده می‌شود\&. در نخستین فراخوانی
باید یکی از گزینه‌های \fB\-i\fP یا \fB\-I\fP به عنوان آرگومان اول ارائه شود\&. در حالت اول،
رشته‌های نمایشی بدون توضیحات تولید می‌شوند؛ در حالت دوم، رشته‌ای که برای جدا کردن موارد
تطبیق از توضیحاتشان به کار می‌رود باید به عنوان آرگومان دوم داده شود و توضیحات (در صورت وجود)
نمایش داده خواهند شد\&. سایر آرگومان‌ها مشابه آرگومان‌های تعریفی خود \fB_describe\fP هستند\&.
.RS
.PP
هنگامی که \fBcompdescribe\fP با یکی از گزینه‌های \fB\-i\fP یا \fB\-I\fP فراخوانی شد،
می‌توان آن را مکرراً با گزینه \fB\-g\fP و نام چهار پارامتر به عنوان آرگومان‌های آن فراخوانی کرد\&.
این کار در میان مجموعه‌های مختلف موارد پیمایش کرده و مقدار \fBcompstate[list]\fP را در اولین
اسکالر، گزینه‌های مربوط به \fBcompadd\fP را در آرایه دوم، موارد تطبیق را در آرایه سوم، و
رشته‌های نمایشی در فهرست کامل‌سازی را در آرایه چهارم ذخیره می‌کند\&. سپس می‌توان این آرایه‌ها را
مستقیماً به \fBcompadd\fP داد تا موارد را در کد کامل‌سازی ثبت کند\&.
.RE
.TP
\fBcompfiles\fP
توسط تابع \fB_path_files\fP برای بهینه‌سازی تولید بازگشتی و پیچیده نام فایل‌ها (globbing)
استفاده می‌شود\&. این دستور سه کار انجام می‌دهد: با گزینه‌های \fB\-p\fP و \fB\-P\fP الگوهای
تطبیق مسیر (glob) را با در نظر گرفتن مسیرهای پیش‌تر پردازش‌شده می‌سازد و تلاش می‌کند الگوها
را با توجه به پیشوند و پسوند خط و مشخصه تطابق جاری بهینه کند\&. گزینه \fB\-i\fP بررسی‌های دایرکتوری
را برای سبک \fBignore\-parents\fP انجام می‌دهد و گزینه \fB\-r\fP بررسی می‌کند که آیا یک مؤلفه
از برخی موارد تطبیق با رشته روی خط برابر است یا خیر و در صورت برابری، تمام موارد دیگر را حذف می‌کند\&.
.TP
\fBcompgroups\fP
توسط تابع \fB_tags\fP برای پیاده‌سازی عملکردهای درونی سبک \fBgroup\-order\fP به کار می‌رود\&.
این دستور تنها نام گروه‌های کامل‌سازی را به عنوان آرگومان می‌پذیرد و گروه‌ها را برای آن ایجاد
می‌کند (شامل هر شش نوع: مرتب‌شده و مرتب‌نشده، هر دو بدون حذف موارد تکراری، با حذف تمام موارد تکراری،
و با حذف موارد تکراری متوالی)\&.
.TP
\fBcompquote\fP [ \fB\-p\fP ] \fInames\fP \&.\&.\&.
ممکن است دلایلی برای نوشتن توابع کامل‌سازی وجود داشته باشد که نیاز دارند موارد تطبیق را با
گزینه \fB\-Q\fP به \fBcompadd\fP اضافه کنند و نقل‌قول‌گذاری (کوتیشن) را خودشان انجام دهند\&. به جای
تفسیر نویسه نخست کلید \fBall_quotes\fP از آرایه انجمنی ویژه \fBcompstate\fP و استفاده از
پرچم \fBq\fP برای بسط پارامترها، می‌توان از این دستور توکار استفاده کرد\&. آرگومان‌ها نام
پارامترهای اسکالر یا آرایه‌ای هستند و مقادیر این پارامترها بر اساس نیاز درونی‌ترین سطح
نقل‌قول، کوت می‌شوند\&. اگر گزینه \fB\-p\fP داده شود، نقل‌قول‌گذاری به گونه‌ای انجام می‌شود که گویی
پیشوندی پیش از مقادیر پارامترها وجود دارد، به طوری که علامت مساوی ابتدایی کوت نخواهد شد\&.
.RS
.PP
وضعیت خروجی در صورت بروز خطا غیر صفر و در غیر این صورت صفر است\&.
.RE
.TP
.PD 0
\fBcomptags\fP
.TP
.PD
\fBcomptry\fP
این دستورات بخش‌های درونی سازوکار برچسب‌ها (tags) را پیاده‌سازی می‌کنند\&.
.TP
\fBcompvalues\fP
مشابه \fBcomparguments\fP، اما برای تابع \fB_values\fP\&.
.SH "ماژول ZSH/CURSES (THE ZSH/CURSES MODULE)"
.\" Yodl file: Zsh/mod_curses.yo

ماژول \fBzsh/curses\fP یک دستور توکار و چندین پارامتر را در دسترس قرار می‌دهد\&.
.PP
.SS "دستورات توکار (Builtin)"
.PP
.PD 0
.TP
.PD 0
\fBzcurses\fP \fBinit\fP
.TP
.PD 0
\fBzcurses\fP \fBend\fP
.TP
.PD 0
\fBzcurses\fP \fBaddwin\fP \fItargetwin\fP \fInlines\fP \fIncols\fP \fIbegin_y\fP \fIbegin_x\fP [ \fIparentwin\fP ]
.TP
.PD 0
\fBzcurses\fP \fBdelwin\fP \fItargetwin\fP
.TP
.PD 0
\fBzcurses\fP \fBrefresh\fP [ \fItargetwin\fP \&.\&.\&. ]
.TP
.PD 0
\fBzcurses\fP \fBtouch\fP \fItargetwin\fP \&.\&.\&.
.TP
.PD 0
\fBzcurses\fP \fBmove\fP \fItargetwin\fP \fInew_y\fP \fInew_x\fP
.TP
.PD 0
\fBzcurses\fP \fBclear\fP \fItargetwin\fP [ \fBredraw\fP | \fBeol\fP | \fBbot\fP ]
.TP
.PD 0
\fBzcurses\fP \fBposition\fP \fItargetwin\fP \fIarray\fP
.TP
.PD 0
\fBzcurses\fP \fBchar\fP \fItargetwin\fP \fIcharacter\fP
.TP
.PD 0
\fBzcurses\fP \fBstring\fP \fItargetwin\fP \fIstring\fP
.TP
.PD 0
\fBzcurses\fP \fBborder\fP \fItargetwin\fP \fIborder\fP
.TP
.PD 0
\fBzcurses\fP \fBattr\fP \fItargetwin\fP [ [\fB+\fP|\fB\-\fP]\fIattribute\fP | \fIfg_col\fP\fB/\fP\fIbg_col\fP ] [\&.\&.\&.]
.TP
.PD 0
\fBzcurses\fP \fBbg\fP \fItargetwin\fP [ [\fB+\fP|\fB\-\fP]\fIattribute\fP | \fIfg_col\fP\fB/\fP\fIbg_col\fP | \fB@\fP\fIchar\fP ] [\&.\&.\&.]
.TP
.PD 0
\fBzcurses\fP \fBscroll\fP \fItargetwin\fP [ \fBon\fP | \fBoff\fP | [\fB+\fP|\fB\-\fP]\fIlines\fP ]
.TP
.PD 0
\fBzcurses\fP \fBinput\fP \fItargetwin\fP [ \fIparam\fP [ \fIkparam\fP [ \fImparam\fP ] ] ]
.TP
.PD 0
\fBzcurses\fP \fBmouse\fP [ \fBdelay\fP \fInum\fP | [\fB+\fP|\fB\-\fP]\fBmotion\fP ]
.TP
.PD 0
\fBzcurses\fP \fBtimeout\fP \fItargetwin\fP \fIintval\fP
.TP
.PD 0
\fBzcurses\fP \fBquerychar\fP \fItargetwin\fP [ \fIparam\fP ]
.TP
.PD
\fBzcurses\fP \fBresize\fP \fIheight\fP \fIwidth\fP [ \fBendwin\fP | \fBnosave\fP | \fBendwin_nosave\fP ]
مدیریت و کار با پنجره‌های curses\&. تمام موارد استفاده از این دستور باید با
`\fBzcurses init\fP\&' برای مقداردهی اولیه curses آغاز شده، و با `\fBzcurses end\fP\&'
خاتمه یابد؛ عدم درج `\fBzcurses end\fP' می‌تواند ترمینال را در وضعیتی نامطلوب باقی بگذارد\&.
.RS
.PP
زیردستور \fBaddwin\fP پنجره‌ای با \fInlines\fP سطر و \fIncols\fP ستون ایجاد می‌کند\&.
گوشه سمت چپ بالای آن در سطر \fIbegin_y\fP و ستون \fIbegin_x\fP صفحه نمایش قرار خواهد گرفت\&.
\fItargetwin\fP یک رشته است که به نام پنجره‌ای اشاره می‌کند که در حال حاضر اختصاص نیافته است\&.
به ویژه به قرارداد curses توجه داشته باشید که مقادیر عمودی پیش از مقادیر افقی ذکر می‌شوند\&.
.PP
اگر به \fBaddwin\fP یک پنجره موجود به عنوان آخرین آرگومان داده شود، پنجره جدید به صورت
زیرپنجره‌ای از \fIparentwin\fP ایجاد می‌شود\&. این حالت با پنجره معمولی جدید تفاوت دارد زیرا حافظه
محتوای پنجره با حافظه والد به اشتراک گذاشته می‌شود\&. زیرپنجره‌ها باید پیش از والدشان حذف شوند\&.
توجه داشته باشید که مختصات زیرپنجره‌ها برخلاف سایر پنجره‌ها نسبت به صفحه اصلی سنجیده می‌شود و نه والد\&.
.PP
از زیردستور \fBdelwin\fP برای حذف پنجره ایجادشده با \fBaddwin\fP استفاده کنید\&. توجه داشته
باشید که \fBend\fP پنجره‌ها را به طور ضمنی حذف \fIنمی‌کند\fP، و \fBdelwin\fP نیز تصویر روی صفحه پنجره
را پاک نمی‌کند\&.
.PP
پنجره متناظر با کل صفحه نمایش قابل مشاهده \fBstdscr\fP نامیده می‌شود؛ این پنجره پس از
`\fBzcurses init\fP\&' همواره وجود دارد و نمی‌توان آن را با \fBdelwin\fP حذف کرد\&.
.PP
زیردستور \fBrefresh\fP پنجره \fItargetwin\fP را بازنشانی و تازه‌سازی می‌کند؛ این کار برای اینکه
تغییرات معلق (مانند کاراکترهایی که با \fBchar\fP برای خروجی آماده کرده‌اید) روی صفحه قابل مشاهده
شوند الزامی است\&. فراخوانی \fBrefresh\fP بدون آرگومان باعث پاک شدن و بازرسم کل صفحه می‌شود\&.
اگر چندین پنجره داده شود، صفحه نمایش در پایان کار یک بار به‌روزرسانی خواهد شد\&.
.PP
زیردستور \fBtouch\fP پنجره‌های \fItargetwin\fP فهرست‌شده را به عنوان تغییریافته علامت‌گذاری می‌کند\&.
این کار پیش از \fBrefresh\fP پنجره‌ها در صورتی که پنجره‌ای که جلوی پنجره دیگری (که ممکن است \fBstdscr\fP باشد)
بوده حذف شود، ضروری است\&.
.PP
زیردستور \fBmove\fP موقعیت مکان‌نما را در \fItargetwin\fP به مختصات جدید \fInew_y\fP و
\fInew_x\fP منتقل می‌کند\&. توجه داشته باشید که زیردستور \fBstring\fP (برخلاف زیردستور \fBchar\fP)
مکان‌نما را به اندازه نویسه‌های اضافه‌شده به جلو می‌برد\&.
.PP
زیردستور \fBclear\fP محتوای \fItargetwin\fP را پاک می‌کند\&. می‌توان یکی (و نه بیش از یکی) از سه
گزینه را تعیین کرد: با گزینه \fBredraw\fP، علاوه بر پاک شدن، در \fBrefresh\fP بعدی \fItargetwin\fP
صفحه پاک شده و مجدداً رسم می‌شود\&. با گزینه \fBeol\fP، پنجره \fItargetwin\fP فقط تا انتهای خط فعلی
مکان‌نما پاک می‌شود\&. با گزینه \fBbot\fP، پنجره \fItargetwin\fP تا انتهای پنجره پاک می‌شود، یعنی
همه چیز در سمت راست و پایین مکان‌نما پاک خواهد شد\&.
.PP
زیردستور \fBposition\fP موقعیت‌های مختلف مربوط به \fItargetwin\fP را در آرایه‌ای به نام
\fIarray\fP می‌نویسد\&. این مقادیر به ترتیب عبارتند از:
.PD 0
.TP
\-
مختصات y و x مکان‌نما نسبت به گوشه بالا سمت چپ \fItargetwin\fP
.TP
\-
مختصات y و x گوشه بالا سمت چپ \fItargetwin\fP روی صفحه نمایش
.TP
\-
اندازه \fItargetwin\fP در ابعاد y و x\&.
.PD
.PP
چاپ نویسه‌ها و رشته‌ها به ترتیب با دستورات \fBchar\fP و \fBstring\fP انجام می‌شود\&.
.PP
برای رسم کادر در اطراف پنجره \fItargetwin\fP، از \fBborder\fP استفاده کنید\&. توجه داشته باشید
که کادر پس از آن رفتار خاصی ندارد: به بیان دیگر، کادر صرفاً مجموعه‌ای از نویسه‌های چاپ‌شده در
لبه‌های پنجره است؛ بنابراین ممکن است بازنویسی شود، با اسکرول از پنجره خارج گردد و غیره\&.
.PP
زیردستور \fBattr\fP صفات پنجره \fItargetwin\fP یا جفت رنگ پیش‌زمینه/پس‌زمینه را برای خروجی‌های
متوالی بعدی نویسه‌ها تنظیم می‌کند\&. هر \fIattribute\fP ارائه‌شده روی خط می‌تواند با یک \fB+\fP برای
فعال‌سازی یا یک \fB\-\fP برای غیرفعال‌سازی همراه باشد؛ در صورت عدم درج، \fB+\fP فرض می‌شود\&.
صفات پشتیبانی‌شده عبارتند از \fBblink\fP، \fBbold\fP، \fBdim\fP، \fBreverse\fP، \fBstandout\fP
و \fBunderline\fP\&.
.PP
هر صفت \fIfg_col\fP\fB/\fP\fIbg_col\fP (به صورت «رنگ پیش‌زمینه روی رنگ پس‌زمینه») رنگ پیش‌زمینه
و پس‌زمینه را برای چاپ نویسه‌ها تعیین می‌کند\&. رنگ \fBdefault\fP گاهی در دسترس است (به‌ویژه
اگر کتابخانه ncurses باشد)، که بیانگر رنگ پیش‌زمینه یا پس‌زمینه‌ای است که ترمینال با آن آغاز شده است\&.
جفت رنگ \fBdefault/default\fP همیشه در دسترس است\&. برای استفاده از رنگ‌هایی بیش از 8 رنگ نام‌گذاری‌شده
(قرمز، سبز و...) جفت‌های \fIfg_col\fP\fB/\fP\fIbg_col\fP را بسازید که در آن‌ها \fIfg_col\fP و
\fIbg_col\fP اعداد صحیح ده‌دهی باشند، مثلاً \fB128/200\fP\&. اگر ترمینال از ۲۵۶ رنگ پشتیبانی کند،
حداکثر مقدار رنگ ۲۵۴ است\&.
.PP
دستور \fBbg\fP رنگ و سایر صفات تمام نویسه‌های موجود در پنجره را بازنویسی می‌کند\&. کاربرد معمول آن
تنظیم پس‌زمینه در ابتدا است، اما صفات هر نویسه‌ای را در زمان فراخوانی بازنویسی خواهد کرد\&. علاوه
بر آرگومان‌های مجاز در \fBattr\fP، یک آرگومان به صورت \fB@\fP\fIchar\fP نویسه‌ای را تعیین می‌کند که
در نواحی خالی پنجره نمایش داده شود\&. به دلیل محدودیت‌های curses این نویسه نمی‌تواند چندبایتی باشد
(تنها استفاده از نویسه‌های ASCII توصیه می‌شود)\&. از آنجا که صفات ارائه‌شده جایگزین پس‌زمینه موجود می‌شوند،
خاموش کردن صفات در آرگومان‌ها اثری ندارد، هرچند خطایی نیز ایجاد نمی‌کند\&.
.PP
زیردستور \fBscroll\fP را می‌توان با \fBon\fP یا \fBoff\fP برای فعال یا غیرفعال کردن پیمایش پنجره
هنگامی که مکان‌نما بر اثر تایپ یا خروجی به زیر پنجره حرکت می‌کند استفاده کرد\&. همچنین می‌توان آن را
با یک عدد صحیح مثبت یا منفی به کار برد تا پنجره به تعداد خطوط مشخص‌شده به سمت بالا یا پایین پیمایش شود
بدون آنکه موقعیت فعلی مکان‌نما تغییر کند (بنابراین به نظر می‌رسد مکان‌نما نسبت به پنجره در جهت مخالف
حرکت کرده است)\&. در حالت دوم اگر پیمایش \fBoff\fP باشد، موقتاً \fBon\fP می‌شود تا پیمایش پنجره انجام پذیرد\&.
.PP
زیردستور \fBinput\fP یک نویسه منفرد را از پنجره می‌خواند بدون آنکه آن را پژواک دهد\&. اگر \fIparam\fP
داده شود، نویسه به پارامتر \fIparam\fP اختصاص می‌یابد، در غیر این صورت در پارامتر \fBREPLY\fP ذخیره می‌شود\&.
.PP
اگر هر دو پارامتر \fIparam\fP و \fIkparam\fP داده شوند، کلید در حالت «keypad» خوانده می‌شود\&. در این
حالت کلیدهای ویژه مانند کلیدهای تابعی (F-keys) و کلیدهای جهت‌نما، نام کلید را در پارامتر \fIkparam\fP
بازمی‌گردانند\&. نام کلیدها همان ماکروهای تعریف‌شده در \fBcurses\&.h\fP یا \fBncurses\&.h\fP با حذف
پیشوند `\fBKEY_\fP\&' هستند؛ همچنین توضیحات پارامتر \fBzcurses_keycodes\fP در زیر را ببینید\&. سایر
کلیدها طبق روال پیشین مقداری در \fIparam\fP قرار می‌دهند\&. در صورت بازگشت موفقیت‌آمیز، تنها یکی از
\fIparam\fP یا \fIkparam\fP حاوی رشته غیرخالی خواهد بود و دیگری به رشته خالی تنظیم می‌شود\&.
.PP
اگر \fImparam\fP نیز داده شود، \fBinput\fP تلاش می‌کند ورودی ماوس را مدیریت کند\&. این قابلیت تنها با
کتابخانه ncurses در دسترس است؛ پشتیبانی از ماوس را می‌توان با بررسی وضعیت خروج `\fBzcurses mouse\fP\&'
بدون آرگومان سنجید\&. اگر یکی از دکمه‌های ماوس کلیک شود (یا دوبارکلیک، سه‌بارکلیک، یا فشرده و رها شود
با تاخیر قابل تنظیم نسبت به کلیک)، مقدار \fIkparam\fP برابر رشته \fBMOUSE\fP تنظیم می‌شود و \fImparam\fP
برابر آرایه‌ای شامل عناصر زیر خواهد شد:
.PD 0
.TP
\-
یک شناسه برای تفکیک دستگاه‌های ورودی مختلف؛ این مورد به ندرت مفید است\&.
.TP
\-
مختصات x، y و z کلیک ماوس نسبت به کل صفحه، به صورت سه عنصر با همان ترتیب (یعنی برخلاف معمول، مختصات y
پس از مختصات x قرار دارد)\&. مختصات z فقط برای تعداد اندکی از دستگاه‌های ورودی غیرمعمول در دسترس است
و در سایر موارد صفر خواهد بود\&.
.TP
\-
هر رویدادی که به عنوان آیتم جداگانه رخ داده است؛ معمولاً تنها یک مورد خواهد بود\&. یک رویداد شامل
\fBPRESSED\fP، \fBRELEASED\fP، \fBCLICKED\fP، \fBDOUBLE_CLICKED\fP یا \fBTRIPLE_CLICKED\fP
است که بلافاصله (در همان عنصر) شماره دکمه به دنبال آن می‌آید\&.
.TP
\-
اگر کلید shift فشرده شده بود، رشته \fBSHIFT\fP\&.
.TP
\-
اگر کلید control فشرده شده بود، رشته \fBCTRL\fP\&.
.TP
\-
اگر کلید alt فشرده شده بود، رشته \fBALT\fP\&.
.PD
.PP
همه رویدادهای ماوس ممکن است به پنجره ترمینال ارسال نشوند؛ اغلب شبیه‌سازهای ترمینال برخی رویدادهای ماوس را
خود مدیریت می‌کنند\&. توجه داشته باشید راهنمای ncurses متذکر شده که استفاده از ورودی هم با مدیریت ماوس و هم
بدون آن ممکن است باعث ظاهر و ناپدید شدن مکان‌نمای ماوس گردد\&.
.PP
زیردستور \fBmouse\fP برای پیکربندی رفتار ماوس به کار می‌رود\&. آرگومان پنجره وجود ندارد؛ گزینه‌های
ماوس سراسری هستند\&. اجرای `\fBzcurses mouse\fP\&' بدون آرگومان در صورت امکان مدیریت ماوس وضعیت 0 و
در غیر این صورت وضعیت 1 را بازمی‌گرداند\&. در غیر این صورت، آرگومان‌های ممکن (که می‌توان آن‌ها را در
یک خط فرمان ترکیب کرد) به شرح زیر هستند:
\fBdelay\fP \fInum\fP حداکثر تاخیر را برحسب میلی‌ثانیه بین رویدادهای فشردن و رها کردن تعیین می‌کند تا
به عنوان کلیک تلقی شود؛ مقدار 0 تفکیک کلیک را غیرفعال می‌کند و پیش‌فرض یک‌ششم ثانیه است\&. \fBmotion\fP
همراه با یک `\fB+\fP\&' اختیاری (پیش‌فرض) یا `\fB\-\fP\&' گزارش حرکت ماوس را علاوه بر کلیک‌ها، فشردن‌ها
و رها کردن‌ها (که همواره گزارش می‌شوند) فعال یا غیرفعال می‌کند\&. با این حال به نظر می‌رسد گزارش حرکت
ماوس در حال حاضر پیاده‌سازی نشده است\&.
.PP
زیردستور \fBtimeout\fP مقدار زمان‌انتظار (timeout) را برای ورودی از \fItargetwin\fP تعیین می‌کند\&. اگر
\fIintval\fP منفی باشد، `\fBzcurses input\fP\&' برای همیشه منتظر تایپ نویسه می‌ماند؛ این حالت پیش‌فرض است\&.
اگر \fIintval\fP صفر باشد، `\fBzcurses input\fP\&' بلافاصله بازمی‌گردد؛ اگر ورودی پیش‌تایپ‌شده وجود داشته باشد
بازگردانده می‌شود، وگرنه ورودی دریافت نشده و وضعیت 1 برمی‌گردد\&. اگر \fIintval\fP مثبت باشد،
`\fBzcurses input\fP\&' به مدت \fIintval\fP میلی‌ثانیه منتظر ورودی می‌ماند و اگر در پایان این بازه
ورودی وجود نداشته باشد، وضعیت 1 را بازمی‌گرداند\&.
.PP
زیردستور \fBquerychar\fP نویسه موجود در موقعیت فعلی مکان‌نما را بررسی می‌کند\&. مقادیر بازگشتی در صورت
ارائه در آرایه‌ای به نام \fIparam\fP و در غیر این صورت در آرایه \fBreply\fP ذخیره می‌شوند\&. اولین مقدار
نویسه است (که در صورت پشتیبانی سیستم ممکن است چندبایتی باشد)؛ مقدار دوم جفت‌رنگ با نگارش متداول
\fIfg_col\fP\fB/\fP\fIbg_col\fP است، یا در صورت عدم پشتیبانی از رنگ \fB0\fP خواهد بود\&. هر صفت دیگری به
جز رنگ که بر نویسه اعمال شده باشد (همان‌طور که با زیردستور \fBattr\fP تنظیم می‌شود)، به عنوان عناصر بیشتر
ظاهر خواهند شد\&.
.PP
زیردستور \fBresize\fP اندازه \fBstdscr\fP و تمام پنجره‌ها را به ابعاد داده‌شده تغییر می‌دهد (پنجره‌هایی که
از ابعاد جدید بیرون بزنند کوچک‌تر می‌شوند)\&. ممکن است افزونه زیربنایی curses (فراخوانی \fBresize_term\fP)
در دسترس نباشد\&. برای بررسی می‌توان از صفر برای \fIheight\fP و \fIwidth\fP استفاده کرد\&. اگر نتیجه
زیردستور \fB0\fP باشد فراخوانی resize_term در دسترس است (در غیر این صورت \fB2\fP)\&. آزمایش‌ها نشان می‌دهند
که تغییر اندازه را معمولاً می‌توان با فراخوانی \fBzcurses end\fP و \fBzcurses refresh\fP انجام داد\&.
زیردستور \fBresize\fP برای انعطاف‌پذیری بیشتر ارائه شده است\&. پیکربندی‌های چندگانه سیستم بررسی شده‌اند
و \fBzcurses end\fP و \fBzcurses refresh\fP همچنان برای وضعیت صحیح ترمینال پس از تغییر اندازه مورد نیاز هستند\&.
برای فراخوانی آن‌ها همراه با \fBresize\fP، از آرگومان \fIendwin\fP استفاده کنید\&. استفاده از آرگومان
\fInosave\fP باعث می‌شود وضعیت جدید ترمینال به صورت درونی توسط \fBzcurses\fP ذخیره نشود\&. این مورد نیز
برای انعطاف‌پذیری فراهم شده و در حالت عادی نیازی به آن نیست\&.
.RE
.PP
.SS "پارامترها (Parameters)"
.PP
.PD 0
.TP
.PD
\fBZCURSES_COLORS\fP
عدد صحیح فقط‌خواندنی\&. حداکثر تعداد رنگ‌هایی که ترمینال پشتیبانی می‌کند\&. این مقدار توسط کتابخانه curses
مقداردهی اولیه می‌شود و تا پیش از نخستین اجرای \fBzcurses init\fP در دسترس نیست\&.
.TP
\fBZCURSES_COLOR_PAIRS\fP
عدد صحیح فقط‌خواندنی\&. حداکثر تعداد جفت‌رنگ‌های \fIfg_col\fP\fB/\fP\fIbg_col\fP که می‌توان در دستورات
`\fBzcurses attr\fP\&' تعریف کرد؛ توجه داشته باشید این محدودیت شامل تمام جفت‌رنگ‌های استفاده‌شده می‌شود،
چه در حال حاضر فعال باشند و چه نباشند\&. این مقدار توسط کتابخانه curses مقداردهی می‌شود و تا پیش از نخستین
اجرای \fBzcurses init\fP در دسترس نخواهد بود\&.
.TP
\fBzcurses_attrs\fP
آرایه فقط‌خواندنی\&. صفات پشتیبانی‌شده توسط \fBzsh/curses\fP؛ به محض بارگذاری ماژول در دسترس است\&.
.TP
\fBzcurses_colors\fP
آرایه فقط‌خواندنی\&. رنگ‌های پشتیبانی‌شده توسط \fBzsh/curses\fP؛ به محض بارگذاری ماژول در دسترس است\&.
.TP
\fBzcurses_keycodes\fP
آرایه فقط‌خواندنی\&. مقادیری که ممکن است در دومین پارامتر ارائه‌شده به `\fBzcurses input\fP\&' بازگردانده
شوند، به ترتیبی که به صورت درونی توسط curses تعریف شده‌اند\&. همه کلیدهای تابعی ذکر نشده‌اند و فقط
\fBF0\fP آمده است؛ curses فضایی برای کلیدهای \fBF0\fP تا \fBF63\fP رزرو می‌کند\&.
.TP
\fBzcurses_windows\fP
آرایه فقط‌خواندنی\&. فهرست پنجره‌های فعلی، یعنی تمام پنجره‌هایی که با `\fBzcurses addwin\fP\&' ایجاد
شده و با `\fBzcurses delwin\fP\&' حذف نشده‌اند\&.
.SH "ماژول ZSH/DATETIME (THE ZSH/DATETIME MODULE)"
.\" Yodl file: Zsh/mod_datetime.yo

ماژول \fBzsh/datetime\fP یک دستور توکار در دسترس قرار می‌دهد:
.PP
.PD 0
.TP
.PD 0
\fBstrftime\fP [ \fB\-s\fP \fIscalar\fP | \fB\-n\fP ] \fIformat\fP [ \fIepochtime\fP [ \fInanoseconds\fP ] ]
.TP
.PD
\fBstrftime\fP \fB\-r\fP [ \fB\-q\fP ] [ \fB\-s\fP \fIscalar\fP | \fB\-n\fP ] \fIformat\fP \fItimestring\fP
تاریخ را در قالب \fIformat\fP مشخص‌شده چاپ می‌کند\&. بدون \fIepochtime\fP، تاریخ/زمان فعلی سیستم به کار
می‌رود؛ به صورت اختیاری می‌توان از \fIepochtime\fP برای مشخص کردن تعداد ثانیه‌های سپری‌شده از زمان مبدأ (epoch)
استفاده کرد، و از \fInanoseconds\fP نیز می‌توان برای تعیین تعداد نانوثانیه‌های پس از ثانیه بهره برد
(در غیر این صورت این عدد 0 فرض می‌شود)\&.
برای جزئیات راهنمای \fIstrftime\fP(3) را ببینید\&. افزونه‌های zsh شرح‌داده‌شده در بخش EXPANSION OF PROMPT SEQUENCES
در \fIzshmisc\fP(1) نیز در دسترس هستند\&.
.RS
.PP
.PD 0
.TP
.PD
\fB\-n\fP
از چاپ خط جدید پس از رشته قالب‌بندی‌شده جلوگیری می‌کند\&.
.TP
\fB\-q\fP
اجرا در حالت بی‌صدا؛ از چاپ تمام پیام‌های خطای شرح‌داده‌شده در زیر جلوگیری می‌کند\&. خطاهای مربوط به
مقادیر نامعتبر \fIepochtime\fP همواره چاپ می‌شوند\&.
.TP
\fB\-r\fP
با گزینه \fB\-r\fP (معکوس)، از \fIformat\fP برای تجزیه رشته ورودی \fItimestring\fP استفاده کرده و
تعداد ثانیه‌های سپری‌شده از زمان مبدأ را که در آن زمان رخ داده چاپ می‌کند\&. این تجزیه توسط تابع
سیستمی \fBstrptime\fP پیاده‌سازی شده است؛ راهنمای \fIstrptime\fP(3) را ببینید\&. این بدان معناست که
افزونه‌های قالب zsh در دسترس نیستند، اما برای جستجوی معکوس نیز نیازی به آن‌ها نیست\&.
.RS
.PP
در بیشتر پیاده‌سازی‌های \fBstrftime\fP هرگونه منطقه زمانی موجود در \fItimestring\fP نادیده گرفته شده
و از منطقه زمانی محلی اعلان‌شده توسط متغیر محیطی \fBTZ\fP استفاده می‌شود؛ سایر پارامترها در صورت
عدم حضور روی صفر تنظیم می‌شوند\&.
.PP
اگر \fItimestring\fP با \fIformat\fP مطابقت نداشته باشد، دستور وضعیت 1 را بازگردانده و پیام خطا چاپ
می‌کند\&. اگر \fItimestring\fP با \fIformat\fP تطابق داشته باشد اما همه نویسه‌های \fItimestring\fP استفاده
نشده باشند، تبدیل با موفقیت انجام می‌شود اما پیام خطایی نیز چاپ خواهد شد\&.
.PP
اگر هیچ‌یک از توابع سیستمی \fBstrptime\fP یا \fBmktime\fP در دسترس نباشند، وضعیت 2 بازگردانده شده و یک
پیام خطا چاپ می‌شود\&.
.RE
.TP
\fB\-s\fP \fIscalar\fP
رشته تاریخ (یا زمان مبدأ برحسب ثانیه در صورت درج \fB\-r\fP) را به جای چاپ کردن، به متغیر \fIscalar\fP
اختصاص می‌دهد\&.
.PP
توجه داشته باشید که بسته به نوع داده زمانی صحیح اعلان‌شده در سیستم، \fBstrftime\fP ممکن است برای
زمان‌های مبدأ بزرگ‌تر از 2147483647 (که متناظر با 2038\-01\-19 03:14:07 +0000 است) نتایج نادرستی تولید کند\&.
.RE
.PP
ماژول \fBzsh/datetime\fP چندین پارامتر در دسترس قرار می‌دهد؛ همگی فقط‌خواندنی هستند:
.PP
.PD 0
.TP
.PD
\fBEPOCHREALTIME\fP
یک مقدار ممیز شناور که بیانگر تعداد ثانیه‌های سپری‌شده از مبدأ زمانی است\&. دقت فرضی در صورت در دسترس بودن
فراخوانی \fBclock_gettime\fP در حد نانوثانیه و در غیر این صورت میکروثانیه است، اما در عمل دامنه دقت مضاعف
ممیز شناور و تاخیرهای زمان‌بندی پوسته ممکن است اثرات قابل توجهی داشته باشند\&.
.TP
\fBEPOCHSECONDS\fP
یک مقدار عدد صحیح که بیانگر تعداد ثانیه‌های سپری‌شده از زمان مبدأ است\&.
.TP
\fBepochtime\fP
یک مقدار آرایه‌ای که حاوی تعداد ثانیه‌های سپری‌شده از زمان مبدأ در عنصر اول و باقیمانده زمان پس از مبدأ
برحسب نانوثانیه در عنصر دوم است\&. برای اطمینان از همگام بودن دو عنصر، این آرایه باید پیش از استفاده از
مقادیر آن کپی شده یا به صورت یک جایگزینی یکپارچه مرجع داده شود\&. الگوی زیر می‌تواند به کار رود:
.RS
.PP
.RS
.nf
\fBfor secs nsecs in $epochtime; do
  \&.\&.\&.
done\fP
.fi
.RE
.PP
.RE
.SH "ماژول ZSH/DB/GDBM (THE ZSH/DB/GDBM MODULE)"
.\" Yodl file: Zsh/mod_db_gdbm.yo

ماژول \fBzsh/db/gdbm\fP برای ایجاد آرایه‌های انجمنی «وابسته» (tied) استفاده می‌شود که به
عنوان رابط فایل‌های پایگاه‌داده عمل می‌کنند\&. در صورتی که رابط GDBM در دسترس نباشد،
دستورات توکار تعریف‌شده توسط این ماژول خطا گزارش می‌دهند\&. این ماژول همچنین به عنوان یک نمونه
اولیه جهت ایجاد رابط‌های پایگاه‌داده دیگر طراحی شده است، بنابراین ممکن است دستور توکار \fBztie\fP
در آینده به یک ماژول عمومی‌تر منتقل شود\&.
.PP
دستورات توکار این ماژول عبارتند از:
.PP
.PD 0
.TP
.PD
\fBztie \-d db/gdbm \-f\fP \fIfilename\fP [ \fB\-r\fP ] \fIarrayname\fP
پایگاه‌داده GDBM مشخص‌شده توسط \fIfilename\fP را باز کرده و در صورت موفقیت، آرایه انجمنی
\fIarrayname\fP متصل به آن فایل را ایجاد می‌کند\&. برای ایجاد یک آرایه وابسته محلی، ابتدا
باید پارامتر اعلان شود، بنابراین دستوراتی مشابه زیر در حوزه یک تابع اجرا خواهند شد:
.RS
.PP
.RS
.nf
\fBlocal \-A sampledb
ztie \-d db/gdbm \-f sample\&.gdbm sampledb\fP
.fi
.RE
.PP
گزینه \fB\-r\fP فایل پایگاه‌داده را صرفاً برای خواندن باز می‌کند و پارامتری با صفت فقط‌خواندنی
ایجاد می‌نماید\&. بدون این گزینه، اجرای `\fBztie\fP\&' روی فایلی که کاربر مجوز نوشتن روی آن را ندارد
خطا خواهد داد\&. در صورت قابل نوشتن بودن، پایگاه‌داده به صورت همگام باز می‌شود تا فیلدهای تغییریافته
در \fIarrayname\fP بلافاصله در \fIfilename\fP نوشته شوند\&.
.PP
تغییر در مجوزهای فایل \fIfilename\fP پس از باز شدن آن، وضعیت \fIarrayname\fP را تغییر نمی‌دهد،
اما `\fBtypeset \-r\fP \fIarrayname\fP\&' طبق انتظار کار خواهد کرد\&.
.RE
.TP
\fBzuntie\fP [ \fB\-u\fP ] \fIarrayname\fP \&.\&.\&.
پایگاه‌داده GDBM متصل به هر \fIarrayname\fP را می‌بندد و سپس پارامتر را لغو مقداردهی (unset) می‌کند\&.
گزینه \fB\-u\fP لغو مقداردهی پارامترهایی را که با `\fBztie \-r\fP\&' فقط‌خواندنی شده‌اند تحمیل می‌کند\&.
.RS
.PP
این کار در صورتی که پارامتر به طور صریح لغو مقداردهی شود یا دامنه محلی (تابع) آن به پایان برسد،
به طور خودکار رخ می‌دهد\&. توجه داشته باشید که یک پارامتر فقط‌خواندنی را نمی‌توان به طور صریح
لغو مقداردهی کرد، بنابراین تنها راه برای حذف یک پارامتر سراسری ایجادشده با `\fBztie \-r\fP\&'
استفاده از `\fBzuntie \-u\fP' است\&.
.RE
.TP
\fBzgdbmpath\fP \fIparametername\fP
مسیر فایل پایگاه‌داده اختصاص‌یافته به \fIparametername\fP را در متغیر اسکالر \fBREPLY\fP
قرار می‌دهد\&.
.TP
\fBzgdbm_tied\fP
آرایه‌ای حاوی نام تمام پارامترهای متصل‌شده (tied)\&.
.PP
فیلدهای یک آرایه انجمنی متصل به GDBM نه کش می‌شوند و نه به روش دیگری در حافظه نگهداری می‌شوند؛
آن‌ها در هر بار ارجاع، از پایگاه‌داده خوانده شده یا در آن نوشته می‌شوند\&. بنابراین به عنوان مثال،
مقادیر موجود در یک آرایه فقط‌خواندنی ممکن است توسط نویسنده دیگری روی همان فایل پایگاه‌داده تغییر کند\&.
.SH "ماژول ZSH/DELTOCHAR (THE ZSH/DELTOCHAR MODULE)"
.\" Yodl file: Zsh/mod_deltochar.yo

ماژول \fBzsh/deltochar\fP دو تابع ZLE را در دسترس قرار می‌دهد:
.PP
.PD 0
.TP
.PD
\fBdelete\-to\-char\fP
یک نویسه را از صفحه‌کلید می‌خواند، و از موقعیت مکان‌نما تا وقوع بعدی (یا با شمارش تکرار \fIn\fP،
وقوع \fIn\fPام) آن نویسه (شامل خود نویسه) را حذف می‌کند\&. شمارش تکرار منفی به معنای حذف به سمت عقب است\&.
.TP
\fBzap\-to\-char\fP
این تابع مشابه \fBdelete\-to\-char\fP عمل می‌کند، با این تفاوت که وقوع پایانی خود آن نویسه حذف نمی‌شود\&.
.SH "ماژول ZSH/EXAMPLE (THE ZSH/EXAMPLE MODULE)"
.\" Yodl file: Zsh/mod_example.yo

ماژول \fBzsh/example\fP یک دستور توکار در دسترس قرار می‌دهد:
.PP
.PD 0
.TP
.PD
\fBexample\fP [ \fB\-flags\fP ] [ \fIargs\fP \&.\&.\&. ]
پرچم‌ها و آرگومان‌هایی را که با آن فراخوانی شده است نمایش می‌دهد\&.
.PP
هدف این ماژول این است که به عنوان نمونه‌ای از نحوه نگارش یک ماژول عمل کند\&.
.SH "ماژول ZSH/FILES (THE ZSH/FILES MODULE)"
.\" Yodl file: Zsh/mod_files.yo

ماژول \fBzsh/files\fP برخی از دستورات متداول برای دستکاری و مدیریت فایل‌ها را به عنوان
دستورات توکار فراهم می‌کند؛ این دستورات احتمالاً در بسیاری از شرایط عادی مورد نیاز نیستند اما
می‌توانند در موقعیت‌های بازیابی اضطراری با منابع محدود مفید باشند\&. این دستورات همه ویژگی‌های
الزام‌شده توسط کمیته‌های استاندارد مربوطه را پیاده‌سازی نمی‌کنند\&.
.PP
برای تمام دستورات، نسخه‌ای با پیشوند \fBzf_\fP نیز موجود بوده و به طور خودکار بارگذاری می‌شود\&.
استفاده از قابلیت ویژگی‌های zmodload امکان می‌دهد فقط نام‌های مورد نظرتان را بارگذاری کنید\&.
توجه داشته باشید که می‌توان تنها دستورات توکار با نام‌های مختص zsh را با دستور زیر بارگذاری کرد:
.PP
.RS
.nf
\fBzmodload \-m \-F zsh/files b:zf_\e*\fP
.fi
.RE
.PP
دستوراتی که به طور پیش‌فرض بارگذاری می‌شوند عبارتند از:
.PP
.PD 0
.TP
.PD
\fBchgrp\fP [ \fB\-hRs\fP ] \fIgroup\fP \fIfilename\fP \&.\&.\&.
گروه فایل‌های مشخص‌شده را تغییر می‌دهد\&. این معادل \fBchown\fP با آرگومان \fIuser\-spec\fP به صورت
`\fB:\fP\fIgroup\fP\&' است\&.
.TP
\fBchmod\fP [ \fB\-Rs\fP ] \fImode\fP \fIfilename\fP \&.\&.\&.
حالت دسترسی فایل‌های مشخص‌شده را تغییر می‌دهد\&.
.RS
.PP
مقدار \fImode\fP مشخص‌شده باید در مبنای هشت (اکتال) باشد\&.
.PP
گزینه \fB\-R\fP باعث می‌شود \fBchmod\fP به صورت بازگشتی وارد دایرکتوری‌ها شده، و پس از تغییر
حالت دسترسی خود دایرکتوری، حالت دسترسی تمام فایل‌های درون آن را تغییر دهد\&.
.PP
گزینه \fB\-s\fP یک افزونه zsh برای عملکردهای \fBchmod\fP است\&. این گزینه رفتار محتاطانه (paranoid)
را فعال می‌کند که هدف آن جلوگیری از مشکلات امنیتی ناشی از فریب خوردن \fBchmod\fP برای تأثیر گذاشتن بر
فایل‌هایی غیر از موارد مورد نظر است\&. این دستور از دنبال کردن پیوندهای نمادین خودداری می‌کند،
به طوری که مثلاً دستور ``\fBchmod 600 /tmp/foo/passwd\fP\&'' نتواند تصادفاً مجوزهای \fB/etc/passwd\fP
را تغییر دهد اگر \fB/tmp/foo\fP پیوندی به \fB/etc\fP باشد\&. همچنین پس از خروج از دایرکتوری‌ها موقعیت
خود را بررسی می‌کند تا یک chmod بازگشتی در درختی عمیق از دایرکتوری‌ها نتواند در نتیجه جابه‌جا شدن دایرکتوری‌ها
به سمت بالای درخت، به تغییر بازگشتی مجوزهای \fB/usr\fP منجر شود\&.
.RE
.TP
\fBchown\fP [ \fB\-hRs\fP ] \fIuser\-spec\fP \fIfilename\fP \&.\&.\&.
مالکیت و گروه فایل‌های مشخص‌شده را تغییر می‌دهد\&.
.RS
.PP
مشخصه \fIuser\-spec\fP می‌تواند به چهار شکل باشد:
.PP
.PD 0
.TP
\fIuser\fP
مالک را به \fIuser\fP تغییر می‌دهد؛ گروه را تغییر نمی‌دهد
.TP
\fIuser\fP\fB::\fP
مالک را به \fIuser\fP تغییر می‌دهد؛ گروه را تغییر نمی‌دهد
.TP
\fIuser\fP\fB:\fP
مالک را به \fIuser\fP تغییر می‌دهد؛ گروه را به گروه اصلی \fIuser\fP تغییر می‌دهد
.TP
\fIuser\fP\fB:\fP\fIgroup\fP
مالک را به \fIuser\fP و گروه را به \fIgroup\fP تغییر می‌دهد
.TP
\fB:\fP\fIgroup\fP
مالک را تغییر نمی‌دهد؛ گروه را به \fIgroup\fP تغییر می‌دهد
.PD
.PP
در هر حالت، `\fB:\fP\&' می‌تواند به جای آن `\fB\&.\fP' باشد\&. قاعده این است که اگر `\fB:\fP\&'
وجود داشته باشد جداکننده `\fB:\fP' است، در غیر این صورت اگر `\fB\&.\fP\&' وجود داشته باشد جداکننده
`\fB\&.\fP' است، وگرنه جداکننده‌ای وجود ندارد\&.
.PP
هر یک از \fIuser\fP و \fIgroup\fP می‌توانند نام کاربری (یا نام گروه) یا شناسه عددی ده‌دهی کاربر (شناسه گروه)
باشند\&. تفسیر به عنوان نام در صورتی که یک نام کاربری (یا نام گروه) کاملاً عددی وجود داشته باشد، اولویت دارد\&.
.PP
اگر هدف یک پیوند نمادین باشد، گزینه \fB\-h\fP باعث می‌شود \fBchown\fP مالکیت خود پیوند را به جای هدف آن
تنظیم کند\&.
.PP
گزینه \fB\-R\fP باعث می‌شود \fBchown\fP به صورت بازگشتی وارد دایرکتوری‌ها شود و مالکیت تمام فایل‌های
درون دایرکتوری را پس از تغییر مالکیت خود دایرکتوری تغییر دهد\&.
.PP
گزینه \fB\-s\fP یک افزونه zsh برای قابلیت‌های \fBchown\fP است\&. این گزینه رفتار محتاطانه را برای
جلوگیری از مشکلات امنیتی فعال می‌کند تا از فریب خوردن \fBchown\fP برای اثرگذاری بر فایل‌هایی غیر از موارد
مورد نظر جلوگیری شود\&. این گزینه از دنبال کردن پیوندهای نمادین خودداری می‌کند، به طوری که دستور
``\fBchown luser /tmp/foo/passwd\fP\&'' نتواند تصادفاً مالکیت \fB/etc/passwd\fP را تغییر دهد اگر
\fB/tmp/foo\fP پیوندی به \fB/etc\fP باشد\&. همچنین پس از خروج از دایرکتوری‌ها بررسی می‌کند کجاست، تا تغییر
مالکیت بازگشتی یک درخت عمیق نتواند در اثر جابه‌جا شدن دایرکتوری‌ها منجر به تغییر بازگشتی مالکیت \fB/usr\fP شود\&.
.RE
.TP
.PD 0
\fBln\fP [ \fB\-dfhins\fP ] \fIfilename\fP \fIdest\fP
.TP
.PD
\fBln\fP [ \fB\-dfhins\fP ] \fIfilename\fP \&.\&.\&. \fIdir\fP
پیوندهای سخت (یا با \fB\-s\fP، نمادین) ایجاد می‌کند\&. در حالت اول، مقصد مشخص‌شده \fIdest\fP به عنوان پیوندی
به \fIfilename\fP داده‌شده ایجاد می‌شود\&. در حالت دوم، هر یک از \fIfilename\fPها به نوبت در نظر گرفته
شده و به مسیری در دایرکتوری \fIdir\fP مشخص‌شده که آخرین مؤلفه نام آن یکسان است پیوند داده می‌شوند\&.
.RS
.PP
به طور معمول، \fBln\fP برای ایجاد پیوندهای سخت به دایرکتوری‌ها تلاش نخواهد کرد\&. این بررسی را می‌توان
با گزینه \fB\-d\fP لغو کرد\&. معمولاً تنها کاربر ارشد (ریشه) می‌تواند در ایجاد پیوندهای سخت به دایرکتوری‌ها
موفق شود\&. این محدودیت در هر حال شامل پیوندهای نمادین نمی‌شود\&.
.PP
به طور پیش‌فرض، فایل‌های موجود را نمی‌توان با پیوندها جایگزین کرد\&. گزینه \fB\-i\fP باعث پرسش از کاربر
در مورد جایگزینی فایل‌های موجود می‌شود\&. گزینه \fB\-f\fP باعث می‌شود فایل‌های موجود بدون پرسش و در سکوت
حذف شوند\&. گزینه \fB\-f\fP اولویت دارد\&.
.PP
گزینه‌های \fB\-h\fP و \fB\-n\fP یکسان هستند و هر دو برای سازگاری وجود دارند؛ هر کدام نشان می‌دهند که
اگر هدف یک پیوند نمادین است، نباید مرجع‌گشایی شود\&. معمولاً این گزینه در ترکیب با \fB\-sf\fP استفاده می‌شود
تا در صورتی که پیوند موجود به یک دایرکتوری اشاره می‌کند، به جای دنبال شدن، حذف گردد\&. اگر این گزینه
با چند نام فایل استفاده شود و هدف پیوندی نمادین به یک دایرکتوری باشد، نتیجه خطا خواهد بود\&.
.RE
.TP
\fBmkdir\fP [ \fB\-p\fP ] [ \fB\-m\fP \fImode\fP ] \fIdir\fP \&.\&.\&.
دایرکتوری ایجاد می‌کند\&. با گزینه \fB\-p\fP، دایرکتوری‌های والد ناموجود در صورت نیاز ابتدا ایجاد می‌شوند،
و اگر دایرکتوری از قبل وجود داشته باشد خطایی اعلام نمی‌شود\&.
از گزینه \fB\-m\fP می‌توان برای تعیین (در مبنای هشت) مجموعه‌ای از مجوزهای فایل برای دایرکتوری‌های ایجادشده
استفاده کرد، در غیر این صورت حالت 777 که با \fBumask\fP فعلی تعدیل شده به کار می‌رود (راهنمای \fIumask\fP(2) را ببینید)\&.
.TP
.PD 0
\fBmv\fP [ \fB\-fi\fP ] \fIfilename\fP \fIdest\fP
.TP
.PD
\fBmv\fP [ \fB\-fi\fP ] \fIfilename\fP \&.\&.\&. \fIdir\fP
فایل‌ها را منتقل می‌کند\&. در حالت اول، \fIfilename\fP مشخص‌شده به مقصد \fIdest\fP داده‌شده منتقل می‌شود\&.
در حالت دوم، هر یک از \fIfilename\fPها به نوبت در نظر گرفته شده و به مسیری در دایرکتوری \fIdir\fP مشخص‌شده
که آخرین جزء نام آن یکسان است منتقل می‌شوند\&.
.RS
.PP
به طور پیش‌فرض، پیش از جایگزینی فایلی که کاربر دسترسی نوشتن به آن را ندارد از او سوال پرسیده می‌شود، اما
فایل‌های قابل نوشتن بدون اعلان حذف می‌شوند\&. گزینه \fB\-i\fP باعث می‌شود درباره جایگزینی هر فایل موجودی از
کاربر سوال شود\&. گزینه \fB\-f\fP باعث می‌شود هر فایل موجود بدون سوال حذف گردد\&. گزینه \fB\-f\fP ارجحیت دارد\&.
.PP
توجه داشته باشید که این دستور \fBmv\fP فایل‌ها را میان دستگاه‌های مختلف (دیسک‌ها یا پارتیشن‌های گوناگون) منتقل
نمی‌کند\&. نسخه‌های پیشین \fBmv\fP هنگامی که تغییر نام واقعی ناممکن بود، به کپی و سپس حذف فایل‌ها متوسل می‌شدند؛
اگر این رفتار مورد نظر است، از \fBcp\fP و \fBrm\fP به صورت دستی استفاده کنید\&. این موضوع ممکن است در نسخه‌های
آینده تغییر کند\&.
.RE
.TP
\fBrm\fP [ \fB\-dfiRrs\fP ] \fIfilename\fP \&.\&.\&.
فایل‌ها و دایرکتوری‌های مشخص‌شده را حذف می‌کند\&.
.RS
.PP
به طور معمول، \fBrm\fP دایرکتوری‌ها را حذف نمی‌کند (مگر با گزینه‌های \fB\-R\fP یا \fB\-r\fP)\&. گزینه \fB\-d\fP
باعث می‌شود \fBrm\fP تلاش کند دایرکتوری‌ها را با \fBunlink\fP حذف کند (راهنمای \fIunlink\fP(2) را ببینید)، همان
روشی که برای فایل‌ها به کار می‌رود\&. معمولاً تنها کاربر ارشد می‌تواند دایرکتوری‌ها را با این روش حذف کند\&.
گزینه \fB\-d\fP نسبت به \fB\-R\fP و \fB\-r\fP اولویت دارد\&.
.PP
به طور پیش‌فرض، پیش از حذف فایلی که کاربر اجازه نوشتن روی آن را ندارد سوال پرسیده می‌شود، اما فایل‌های قابل
نوشتن بدون اعلان حذف می‌گردند\&. گزینه \fB\-i\fP باعث پرسش پیش از حذف هر فایلی می‌شود\&. گزینه \fB\-f\fP
باعث حذف فایل‌ها در سکوت، بدون پرسش و بدون نمایش نشانه‌های خطا می‌گردد\&. \fB\-f\fP ارجحیت دارد\&.
.PP
گزینه‌های \fB\-R\fP و \fB\-r\fP باعث می‌شوند \fBrm\fP به صورت بازگشتی وارد دایرکتوری‌ها شده، و تمام فایل‌های
درون دایرکتوری را پیش از حذف خود دایرکتوری با فراخوانی سیستمی \fBrmdir\fP حذف کند (راهنمای \fIrmdir\fP(2) را ببینید)\&.
.PP
گزینه \fB\-s\fP یک افزونه zsh برای عملکردهای \fBrm\fP است\&. این گزینه رفتار محتاطانه را برای جلوگیری از
مشکلات امنیتی رایج فعال می‌کند تا از فریب خوردن \fBrm\fP اجراشده توسط ریشه برای حذف فایل‌هایی غیر از موارد
مورد نظر ممانعت به عمل آید\&. این گزینه از دنبال کردن پیوندهای نمادین خودداری می‌کند، بنابراین مثلاً دستور
``\fBrm /tmp/foo/passwd\fP\&'' نمی‌تواند تصادفاً \fB/etc/passwd\fP را حذف کند اگر \fB/tmp/foo\fP پیوندی به
\fB/etc\fP باشد\&. همچنین پس از خروج از دایرکتوری‌ها بررسی می‌کند کجاست، تا حذف بازگشتی یک درخت عمیق نتواند در
نتیجه جابه‌جا شدن دایرکتوری‌ها به حذف بازگشتی \fB/usr\fP منتهی شود\&.
.RE
.TP
\fBrmdir\fP \fIdir\fP \&.\&.\&.
دایرکتوری‌های خالی مشخص‌شده را حذف می‌کند\&.
.TP
\fBsync\fP
فراخوانی سیستمی هم‌نام خود را فرا می‌خواند (راهنمای \fIsync\fP(2) را ببینید)، که بافرهای تغییریافته (dirty) را
روی دیسک تخلیه می‌کند\&. این دستور ممکن است پیش از پایان کامل عملیات ورودی/خروجی بازگردد\&.
.SH "ماژول ZSH/LANGINFO (THE ZSH/LANGINFO MODULE)"
.\" Yodl file: Zsh/mod_langinfo.yo

ماژول \fBzsh/langinfo\fP یک پارامتر را در دسترس قرار می‌دهد:
.PP
.PD 0
.TP
.PD
\fBlanginfo\fP
یک آرایه انجمنی که عناصر langinfo را به مقادیر آن‌ها نگاشت می‌کند\&.
.RS
.PP
پیاده‌سازی سیستم شما ممکن است از تعدادی از کلیدهای زیر پشتیبانی کند:
.PP
\fBCODESET\fP,
\fBD_T_FMT\fP,
\fBD_FMT\fP,
\fBT_FMT\fP,
\fBRADIXCHAR\fP,
\fBTHOUSEP\fP,
\fBYESEXPR\fP,
\fBNOEXPR\fP,
\fBCRNCYSTR\fP,
\fBABDAY_{1\&.\&.7}\fP,
\fBDAY_{1\&.\&.7}\fP,
\fBABMON_{1\&.\&.12}\fP,
\fBMON_{1\&.\&.12}\fP,
\fBT_FMT_AMPM\fP,
\fBAM_STR\fP,
\fBPM_STR\fP,
\fBERA\fP,
\fBERA_D_FMT\fP,
\fBERA_D_T_FMT\fP,
\fBERA_T_FMT\fP,
\fBALT_DIGITS\fP
.PP
.RE
.SH "ماژول ZSH/MAPFILE (THE ZSH/MAPFILE MODULE)"
.\" Yodl file: Zsh/mod_mapfile.yo

ماژول \fBzsh/mapfile\fP یک پارامتر آرایه انجمنی ویژه با همین نام فراهم می‌کند\&.
.PP
.PD 0
.TP
.PD
\fBmapfile\fP
این آرایه انجمنی نام فایل‌ها را به عنوان کلید می‌پذیرد؛ مقدار حاصل محتوای فایل خواهد بود\&.
این مقدار دقیقاً مشابه هر متن دیگری که از یک پارامتر می‌آید پردازش می‌شود\&. همچنین می‌توان به
این مقدار تخصیص داد، که در این صورت فایل مربوطه نوشته می‌شود (خواه از ابتدا وجود داشته باشد یا خیر)؛
یا یک عنصر را می‌توان لغو مقداردهی (unset) کرد، که فایل مربوطه را حذف خواهد کرد\&. برای نمونه،
دستور `\fBvared \&'mapfile[myfile]'\fP' طبق انتظار کار کرده و فایل `\fBmyfile\fP\&' را ویرایش می‌کند\&.
.RS
.PP
هنگامی که به کل آرایه دسترسی پیدا شود، کلیدها نام فایل‌های موجود در دایرکتوری جاری بوده و مقادیر
آن‌ها خالی است (برای صرفه‌جویی در بار سنگین حافظه)\&. بنابراین \fB${(k)mapfile}\fP همان اثری را دارد که
عملگر انطباق مسیر \fB*(D)\fP دارد، زیرا فایل‌های با نقطه آغازین رفتار خاصی ندارند\&. در عباراتی نظیر
\fBrm ${(k)mapfile}\fP باید دقت زیادی شود، زیرا تمام فایل‌های دایرکتوری جاری را بدون بررسی معمول
`\fBrm *\fP\&' حذف خواهد کرد\&.
.PP
پارامتر \fBmapfile\fP را می‌توان فقط‌خواندنی کرد؛ در این حالت، فایل‌های ارجاع‌شده را نمی‌توان بازنویسی یا حذف کرد\&.
.PP
یک فایل را می‌توان به راحتی با قالب
`\fIarray\fP\fB=("${(f@)mapfile[\fP\fIfilename\fP\fB]}")\fP\&'
به صورت یک خط در هر عنصر درون یک آرایه خواند\&. نقل‌قول دوتایی و `\fB@\fP\&' برای جلوگیری از حذف خطوط خالی
ضروری هستند\&. توجه داشته باشید که اگر فایل با یک خط جدید به پایان برسد، پوسته روی خط جدید نهایی تفکیک
انجام داده و یک فیلد خالی اضافی تولید می‌کند؛ این رفتار را می‌توان با استفاده از عبارت
`\fIarray\fP\fB=("${(f@)${mapfile[\fP\fIfilename\fP\fB]%$\&'\en'}}")\fP'
مهار کرد\&.
.RE
.PP
.SS "محدودیت‌ها (Limitations)"
.PP
اگرچه خواندن و نوشتن فایل مربوطه با کارایی بالا انجام می‌شود، مدیریت حافظه درونی zsh ممکن است پیچیدگی‌های
خاص خود را داشته باشد؛ با این حال، \fBmapfile\fP معمولاً بسیار کارآمدتر از هر روش مبتنی بر حلقه است\&.
به ویژه توجه داشته باشید که هنگام دسترسی، تمام محتوای فایل همیشه به صورت فیزیکی در حافظه قرار خواهد گرفت
(احتمالاً چندین بار، به دلیل عملیات استاندارد جایگزینی پارامتر)\&. به ویژه، این بدان معناست که مدیریت فایل‌های
به اندازه کافی بزرگ (بزرگ‌تر از فضای swap سیستم، یا بزرگ‌تر از دامنه نوع داده اشاره‌گر) با خطا مواجه خواهد شد\&.
.PP
هیچ خطایی برای فایل‌های ناموجود، غیرقابل خواندن یا غیرقابل نوشتن چاپ یا پرچم‌گذاری نمی‌شود، زیرا سازوکار
پارامتر در سلسله‌مراتب اجرای پوسته در سطح بسیار پایینی قرار دارد که پیاده‌سازی این کار را دشوار می‌کند\&.
.PP
متأسفانه سازوکار بارگذاری ماژول‌ها هنوز به کاربر اجازه نمی‌دهد نام پارامتر پوسته‌ای را که قرار است این
رفتار ویژه را داشته باشد تعیین کند\&.
.SH "ماژول ZSH/MATHFUNC (THE ZSH/MATHFUNC MODULE)"
.\" Yodl file: Zsh/mod_mathfunc.yo

ماژول \fBzsh/mathfunc\fP توابع ریاضی استاندارد را برای استفاده در هنگام ارزیابی فرمول‌های ریاضی
فراهم می‌کند\&. ساختار دستوری با قراردادهای معمول C و FORTRAN مطابقت دارد، برای نمونه:
.PP
.RS
.nf
\fB(( f = sin(0\&.3) ))\fP
.fi
.RE
.PP
سینوس 0.3 را به پارامتر f اختصاص می‌دهد\&.
.PP
بیشتر توابع آرگومان‌های ممیز شناور می‌پذیرند و یک مقدار ممیز شناور بازمی‌گردانند\&. با این حال، هرگونه
تبدیل لازم از یا به نوع عدد صحیح به طور خودکار توسط پوسته انجام می‌شود\&. به جز \fBatan\fP با آرگومان دوم
و توابع \fBabs\fP، \fBint\fP و \fBfloat\fP، تمام توابع همان‌طور که در صفحه راهنمای تابع C متناظر ذکر شده
رفتار می‌کنند، مگر اینکه هر آرگومانی خارج از دامنه مجاز برای تابع مربوطه توسط پوسته شناسایی شده و خطا
گزارش گردد\&.
.PP
توابع زیر یک آرگومان ممیز شناور منفرد دریافت می‌کنند: \fBacos\fP، \fBacosh\fP، \fBasin\fP، \fBasinh\fP،
\fBatan\fP، \fBatanh\fP، \fBcbrt\fP، \fBceil\fP، \fBcos\fP، \fBcosh\fP، \fBerf\fP، \fBerfc\fP، \fBexp\fP،
\fBexpm1\fP، \fBfabs\fP، \fBfloor\fP، \fBgamma\fP، \fBj0\fP، \fBj1\fP، \fBlgamma\fP، \fBlog\fP، \fBlog10\fP،
\fBlog1p\fP، \fBlog2\fP، \fBlogb\fP، \fBsin\fP، \fBsinh\fP، \fBsqrt\fP، \fBtan\fP، \fBtanh\fP، \fBy0\fP،
\fBy1\fP\&. تابع \fBatan\fP می‌تواند به صورت اختیاری آرگومان دوم نیز بپذیرد، که در این حالت مانند تابع C به
نام \fBatan2\fP رفتار می‌کند\&. تابع \fBilogb\fP یک آرگومان ممیز شناور منفرد می‌گیرد، اما یک عدد صحیح بازمی‌گرداند\&.
.PP
تابع \fBsigngam\fP هیچ آرگومانی نمی‌پذیرد و یک عدد صحیح برمی‌گرداند، که همان متغیر C با همین نام است که در
\fIgamma\fP(3) شرح داده شده است\&. توجه داشته باشید که بنابراین تنها بلافاصله پس از فراخوانی \fBgamma\fP یا
\fBlgamma\fP کاربرد دارد\&. همچنین توجه داشته باشید که `\fBsigngam()\fP\&' و `\fBsigngam\fP' عبارات متمایزی هستند\&.
.PP
توابع \fBmin\fP، \fBmax\fP و \fBsum\fP در این ماژول تعریف نشده‌اند بلکه در تابع قابل بارگذاری خودکار \fBzmathfunc\fP
قرار دارند که در بخش `Mathematical Functions\&' در \fIzshcontrib\fP(1) شرح داده شده است\&.
.PP
توابع زیر دو آرگومان ممیز شناور می‌پذیرند: \fBcopysign\fP، \fBfmod\fP، \fBhypot\fP، \fBnextafter\fP\&.
.PP
توابع زیر یک آرگومان اول صحیح و یک آرگومان دوم ممیز شناور می‌پذیرند: \fBjn\fP، \fByn\fP\&.
.PP
توابع زیر یک آرگومان اول ممیز شناور و یک آرگومان دوم صحیح می‌پذیرند: \fBldexp\fP، \fBscalb\fP\&.
.PP
تابع \fBabs\fP نوع آرگومان منفرد خود را تبدیل نمی‌کند؛ قدر مطلق یک عدد ممیز شناور یا یک عدد صحیح را
بازمی‌گرداند\&. توابع \fBfloat\fP و \fBint\fP به ترتیب آرگومان‌های خود را به مقدار ممیز شناور یا عدد صحیح
(با قطع اعشار) تبدیل می‌کنند\&.
.PP
توجه داشته باشید که تابع \fBpow\fP در C در ارزیابی ریاضی عادی به عنوان عملگر `\fB**\fP\&' در دسترس است
و در اینجا ارائه نشده است\&.
.PP
تابع \fBrand48\fP در صورتی در دسترس است که کتابخانه ریاضی سیستم شما تابع \fBerand48(3)\fP را داشته باشد\&.
این تابع یک عدد شبه‌تصادفی ممیز شناور بین 0 و 1 برمی‌گرداند\&. این تابع یک آرگومان رشته‌ای اختیاری می‌پذیرد\&.
.PP
اگر آرگومان وجود نداشته باشد، هسته عدد تصادفی (seed) با سه بار فراخوانی تابع \fBrand(3)\fP مقداردهی اولیه
می‌شود \-\-\- این کار همان اعداد تصادفی سه مقدار بعدی \fB$RANDOM\fP را تولید می‌کند\&.
.PP
اگر آرگومان ارائه شود، بیانگر نام یک پارامتر اسکالر است که هسته عدد تصادفی جاری در آن ذخیره خواهد شد\&.
در اولین فراخوانی، مقدار باید شامل حداقل دوازده رقم هگزادسیمال باشد (بقیه رشته نادیده گرفته می‌شود)، یا اینکه
هسته به همان شیوه فراخوانی \fBrand48\fP بدون آرگومان مقداردهی خواهد شد\&. فراخوانی‌های بعدی \fBrand48\fP(\fIparam\fP)
سپس هسته را در پارامتر \fIparam\fP به عنوان رشته‌ای از دوازده رقم هگزادسیمال بدون پیشوند مبنا نگهداری می‌کنند\&.
دنباله‌های اعداد تصادفی برای پارامترهای مختلف کاملاً مستقل هستند، و همچنین از دنباله مورد استفاده در
فراخوانی‌های \fBrand48\fP بدون آرگومان مستقل می‌باشند\&.
.PP
برای نمونه دستورات زیر را در نظر بگیرید:
.PP
.RS
.nf
\fBprint $(( rand48(seed) ))
print $(( rand48() ))
print $(( rand48(seed) ))\fP
.fi
.RE
.PP
با فرض اینکه \fB$seed\fP وجود نداشته باشد، با اولین فراخوانی مقداردهی اولیه می‌شود\&. در فراخوانی دوم، هسته
پیش‌فرض مقداردهی می‌شود؛ با این حال توجه داشته باشید که به دلیل ویژگی‌های \fBrand()\fP همبستگی میان
هسته‌های مورد استفاده برای این دو مقداردهی اولیه وجود دارد، بنابراین برای استفاده‌های امن‌تر باید هسته
۱۲ بایتی اختصاصی خود را تولید کنید\&. فراخوانی سوم به همان دنباله اعداد تصادفی مورد استفاده در فراخوانی
نخست بازمی‌گردد، بدون آنکه تحت تأثیر \fBrand48()\fP میانی قرار گرفته باشد\&.
.SH "ماژول ZSH/NEARCOLOR (THE ZSH/NEARCOLOR MODULE)"
.\" Yodl file: Zsh/mod_nearcolor.yo

ماژول \fBzsh/nearcolor\fP رنگ‌های مشخص‌شده با سه‌تایی‌های هگزادسیمال را با نزدیک‌ترین رنگ در پالت‌های
۸۸ یا ۲۵۶ رنگی که به طور گسترده توسط شبیه‌سازهای ترمینال استفاده می‌شوند جایگزین می‌کند\&. به طور پیش‌فرض،
هنگامی که رنگ‌ها با سه‌تایی‌های هگزادسیمال مشخص می‌شوند کدهای فرار رنگ واقعی (true colour) ۲۴ بیتی تولید
می‌شوند\&. این کدها توسط همه ترمینال‌ها پشتیبانی نمی‌شوند\&. هدف این ماژول آسان‌تر کردن تعریف اولویت‌های رنگی
در قالبی است که بتواند در طیف وسیعی از شبیه‌سازهای ترمینال کار کند\&.
.PP
به جز رنگ پیش‌فرض، استاندارد ANSI برای کدهای اسکیپ ترمینال هشت رنگ فراهم می‌کند\&. صفت روشن (bright) این
تعداد را به شانزده می‌رساند\&. این رنگ‌های پایه به دلیل پشتیبانی گسترده معمولاً در برنامه‌های ترمینال به کار
می‌روند\&. پالت‌های گسترش‌یافته ۸۸ و ۲۵۶ رنگ نیز متداول هستند و در حالی که شانزده رنگ اول تا حدی میان ترمینال‌ها
و پیکربندی‌های مختلف تفاوت دارند، این پالت‌ها مجموعه‌ای به طور کلی یکنواخت و قابل پیش‌بینی از رنگ‌ها اضافه می‌کنند\&.
.PP
برای استفاده از ماژول \fBzsh/nearcolor\fP، تنها کافی است آن را بارگذاری کنید\&. پس از آن، هر زمان رنگی با
سه‌تایی هگزادسیمال تعیین شود، با تک‌تک رنگ‌های موجود مقایسه شده و نزدیک‌ترین رنگ انتخاب خواهد شد\&. شانزده
رنگ نخست به دلیل غیرقابل پیش‌بینی بودن هرگز در این فرایند تطبیق داده نمی‌شوند\&.
.PP
تشخیص قابل اعتماد پشتیبانی از رنگ واقعی (true colour) در شبیه‌ساز ترمینال امکان‌پذیر نیست\&. بنابراین توصیه
می‌شود در بارگذاری ماژول \fBzsh/nearcolor\fP گزینشی عمل کنید\&. برای نمونه، دستور زیر متغیر محیطی
\fBCOLORTERM\fP را بررسی می‌کند:
.PP
.RS
.nf
\fB[[ $COLORTERM = *(24bit|truecolor)* ]] || zmodload zsh/nearcolor\fP
.fi
.RE
.PP
توجه داشته باشید که برخی از ترمینال‌ها کدهای اسکیپ true color را می‌پذیرند اما آن‌ها را به صورت درونی به یک
پالت محدودتر نگاشت می‌کنند، به شیوه‌ای مشابه ماژول \fBzsh/nearcolor\fP\&.
.SH "ماژول ZSH/NEWUSER (THE ZSH/NEWUSER MODULE)"
.\" Yodl file: Zsh/mod_newuser.yo

ماژول \fBzsh/newuser\fP در هنگام راه‌اندازی سیستم در صورتی که در دسترس باشد، گزینه \fBRCS\fP فعال باشد
و گزینه \fBPRIVILEGED\fP فعال نباشد (هر سه به طور پیش‌فرض برقرارند) بارگذاری می‌شود\&. این کار بلافاصله
پس از اجرای دستورات موجود در فایل سراسری \fBzshenv\fP (معمولاً \fB/etc/zsh/zshenv\fP)، در صورت وجود، انجام
می‌گیرد\&. اگر ماژول در دسترس نباشد، در سکوت توسط پوسته نادیده گرفته می‌شود؛ در صورت عدم نیاز، ماژول را
می‌توان با خیال راحت توسط مدیر سیستم از \fB$MODULE_PATH\fP حذف کرد\&.
.PP
پس از بارگذاری، ماژول بررسی می‌کند که آیا هیچ‌یک از فایل‌های راه‌اندازی \fB\&.zshenv\fP، \fB\&.zprofile\fP،
\fB\&.zshrc\fP یا \fB\&.zlogin\fP در دایرکتوری ارائه‌شده توسط متغیر محیطی \fBZDOTDIR\fP، یا دایرکتوری خانگی
کاربر در صورت عدم تنظیم آن وجود دارند یا خیر\&. اگر پوسته در حالت شبیه‌سازی باشد (یعنی به عنوان پوسته‌ای
غیر از zsh فراخوانی شده باشد)، این بررسی انجام نشده و پردازش ماژول متوقف می‌شود\&.
.PP
اگر هیچ‌یک از فایل‌های راه‌اندازی یافت نشوند، ماژول سپس فایل \fBnewuser\fP را ابتدا در یک دایرکتوری در سطح
سیستم (معمولاً دایرکتوری والد دایرکتوری \fBsite\-functions\fP) جستجو می‌کند، و اگر پیدا نشد ماژول در یک
دایرکتوری مختص نسخه (معمولاً والد دایرکتوری \fBfunctions\fP حاوی توابع مختص نسخه) به جستجو می‌پردازد\&.
(این دایرکتوری‌ها را می‌توان هنگام ساخت zsh با استفاده از فلگ‌های \fB\-\-enable\-site\-scriptdir=\fP\fIdir\fP
و \fB\-\-enable\-scriptdir=\fP\fIdir\fP در دستور \fBconfigure\fP پیکربندی کرد؛ پیش‌فرض‌ها به ترتیب
\fIprefix\fP\fB/share/zsh\fP و \fIprefix\fP\fB/share/zsh/$ZSH_VERSION\fP هستند که در آن \fIprefix\fP
پیش‌فرض \fB/usr/local\fP است\&.)
.PP
اگر فایل \fBnewuser\fP یافت شود، به همان شیوه یک فایل راه‌اندازی سورس (source) می‌شود\&. انتظار می‌رود این
فایل حاوی کدهایی برای نصب فایل‌های راه‌اندازی برای کاربر باشد، با این حال هر کد معتبر پوسته اجرا خواهد شد\&.
.PP
سپس ماژول \fBzsh/newuser\fP بدون قید و شرط از حافظه تخلیه (unload) می‌شود\&.
.PP
توجه داشته باشید که می‌توان با افزودن کد به \fB/etc/zsh/zshenv\fP دقیقاً به همان اثر ماژول \fBzsh/newuser\fP
دست یافت\&. این ماژول صرفاً به منظور امکان‌پذیر ساختن تمهیدات لازم برای کاربران جدید توسط پوسته بدون نیاز
به مداخله نگه‌دارندگان بسته‌ها و مدیران سیستم وجود دارد\&.
.PP
اسکریپت ارائه‌شده همراه با این ماژول تابع پوسته \fBzsh\-newuser\-install\fP را فراخوانی می‌کند\&. این تابع
می‌تواند حتی در صورت غیرفعال بودن ماژول \fBzsh/newuser\fP مستقیماً توسط کاربر فراخوانی شود\&. با این حال توجه
داشته باشید که در صورت عدم نصب ماژول، این تابع نیز نصب نخواهد شد\&. این تابع در بخش `User Configuration Functions\&'
در \fIzshcontrib\fP(1) مستند شده است\&.
.SH "ماژول ZSH/PARAMETER (THE ZSH/PARAMETER MODULE)"
.\" Yodl file: Zsh/mod_parameter.yo

ماژول \fBzsh/parameter\fP با تعریف برخی پارامترهای ویژه، امکان دسترسی به برخی از
جدول‌های درهم‌سازی (hash tables) درونی مورد استفاده پوسته را فراهم می‌کند\&.
.PP
.PD 0
.TP
.PD
\fBoptions\fP
کلیدهای این آرایه انجمنی، نام گزینه‌هایی است که می‌توان آن‌ها را با استفاده از دستورات توکار
\fBsetopt\fP و \fBunsetopt\fP تنظیم یا لغو کرد\&. مقدار هر کلید در صورتی که گزینه در حال حاضر
فعال باشد رشته \fBon\fP، و در صورت غیرفعال بودن رشته \fBoff\fP است\&.
تنظیم یک کلید روی یکی از این رشته‌ها به ترتیب معادل فعال‌سازی یا غیرفعال‌سازی آن گزینه است\&.
لغو مقداردهی (unset) یک کلید در این آرایه همانند تنظیم آن روی مقدار \fBoff\fP خواهد بود\&.
.TP
\fBcommands\fP
این آرایه امکان دسترسی به جدول درهم‌سازی دستورها را فراهم می‌کند\&. کلیدها نام دستورهای خارجی
هستند، و مقادیر، مسیرهای فایل‌هایی می‌باشند که هنگام فراخوانی دستور اجرا خواهند شد\&. تنظیم یک
کلید در این آرایه، یک مدخل جدید در این جدول ایجاد می‌کند، دقیقاً مانند دستور توکار \fBhash\fP\&.
لغو مقداردهی یک کلید مانند `\fBunset "commands[foo]"\fP\&' مدخل مربوط به آن کلید را از جدول
درهم‌سازی دستورات حذف می‌کند\&.
.TP
\fBfunctions\fP
این آرایه انجمنی نام توابع فعال را به تعاریف بدنه آن‌ها نگاشت می‌کند\&. تنظیم یک کلید در آن،
مانند تعریف تابعی با نام داده‌شده توسط کلید و بدنه داده‌شده توسط مقدار است\&. لغو مقداردهی یک
کلید، تعریف تابع با آن نام را حذف می‌کند\&.
.TP
\fBdis_functions\fP
مشابه \fBfunctions\fP، اما برای توابع غیرفعال‌شده\&.
.TP
\fBfunctions_source\fP
این آرایه انجمنی فقط‌خواندنی، نام توابع فعال را به نام فایلی که حاوی سورس آن تابع است نگاشت می‌کند\&.
.RS
.PP
برای تابع بارگذاری‌شونده خودکاری (autoloaded) که پیش‌تر بارگذاری شده، یا با یک مسیر مطلق برای
بارگذاری خودکار علامت‌گذاری شده، یا مسیر آن با `\fBfunctions \-r\fP\&' تفکیک شده است، این مقدار
همان فایل یافت‌شده برای بارگذاری خودکار است که به یک مسیر مطلق تبدیل شده است\&.
.PP
برای تابعی که درون بدنه یک اسکریپت یا فایل سورس‌شده تعریف شده باشد، این مقدار نام همان فایل است\&.
در این حالت، مقدار دقیقاً همان مسیری است که در اصل برای آن فایل استفاده شده بود و ممکن است یک مسیر نسبی باشد\&.
.PP
برای هر تابع دیگری، از جمله هر تابعی که در اعلان تعاملی تعریف شده باشد یا یک تابع autoload که هنوز
مسیر آن تفکیک نشده است، مقدار یک رشته خالی خواهد بود\&. با این حال، تا زمانی که تابع حضور دارد مدخل
درهم‌سازی به صورت تعریف‌شده گزارش می‌شود: کلیدهای این جدول مشابه کلیدهای \fB$functions\fP هستند\&.
.RE
.TP
\fBdis_functions_source\fP
مشابه \fBfunctions_source\fP، اما برای توابع غیرفعال‌شده\&.
.TP
\fBbuiltins\fP
این آرایه انجمنی اطلاعاتی درباره دستورات توکار در حال حاضر فعال ارائه می‌دهد\&. کلیدها نام دستورات
توکار هستند و مقادیر در صورتی که دستور توکار هنگام فراخوانی به طور خودکار از یک ماژول بارگذاری شود
`\fBundefined\fP\&' و برای دستورات توکاری که از قبل بارگذاری شده‌اند `\fBdefined\fP\&' است\&.
.TP
\fBdis_builtins\fP
مشابه \fBbuiltins\fP، اما برای دستورات توکار غیرفعال‌شده\&.
.TP
\fBreswords\fP
این آرایه حاوی کلمات کلیدی رزروشده فعال است\&.
.TP
\fBdis_reswords\fP
مشابه \fBreswords\fP، اما برای کلمات کلیدی رزروشده غیرفعال\&.
.TP
\fBpatchars\fP
این آرایه حاوی نویسه‌های الگوی تطابق (pattern characters) فعال است\&.
.TP
\fBdis_patchars\fP
مشابه \fBpatchars\fP، اما برای نویسه‌های الگوی غیرفعال\&.
.TP
\fBaliases\fP
این آرایه نام نام‌های مستعار (alias) معمولی فعال را به عبارت بسط‌یافته آن‌ها نگاشت می‌کند\&.
.TP
\fBdis_aliases\fP
مشابه \fBaliases\fP، اما برای نام‌های مستعار معمولی غیرفعال\&.
.TP
\fBgaliases\fP
مشابه \fBaliases\fP، اما برای نام‌های مستعار سراسری (global aliases)\&.
.TP
\fBdis_galiases\fP
مشابه \fBgaliases\fP، اما برای نام‌های مستعار سراسری غیرفعال\&.
.TP
\fBsaliases\fP
مشابه \fBraliases\fP، اما برای نام‌های مستعار پسوندی (suffix aliases)\&.
.TP
\fBdis_saliases\fP
مشابه \fBsaliases\fP، اما برای نام‌های مستعار پسوندی غیرفعال\&.
.TP
\fBparameters\fP
کلیدهای این آرایه انجمنی نام پارامترهایی هستند که در حال حاضر تعریف شده‌اند\&. مقادیر، رشته‌هایی در
توصیف نوع پارامتر هستند، در همان قالبی که توسط پرچم پارامتر \fBt\fP استفاده می‌شود؛ راهنمای
\fIzshexpn\fP(1)
را ببینید\&.
تنظیم یا لغو مقداردهی کلیدها در این آرایه امکان‌پذیر نیست\&.
.TP
\fBmodules\fP
آرایه انجمنی حاوی اطلاعاتی پیرامون ماژول‌ها\&. کلیدها نام ماژول‌های بارگذاری‌شده، ثبت‌شده برای
بارگذاری خودکار، یا نام مستعار داده‌شده هستند\&. مقدار نشان می‌دهد که ماژول در چه وضعیتی قرار دارد
و یکی از رشته‌های `\fBloaded\fP\&'، `\fBautoloaded\fP' یا `\fBalias:\fP\fIname\fP' است،
که در آن \fIname\fP نامی است که ماژول به آن ارجاع داده شده است\&.
.RS
.PP
تنظیم یا لغو مقداردهی کلیدها در این آرایه امکان‌پذیر نیست\&.
.RE
.TP
\fBdirstack\fP
یک آرایه معمولی حاوی عناصر پشته دایرکتوری‌ها (directory stack)\&. توجه داشته باشید که خروجی
دستور توکار \fBdirs\fP شامل یک دایرکتوری بیشتر، یعنی دایرکتوری کاری فعلی است\&.
.TP
\fBhistory\fP
این آرایه انجمنی شماره رویدادهای تاریخچه را به خطوط کامل تاریخچه نگاشت می‌کند\&. اگرچه به عنوان
یک آرایه انجمنی ارائه شده است، اما آرایه تمام مقادیر (\fB${history[@]}\fP) تضمین می‌شود که به
ترتیب از جدیدترین به قدیمی‌ترین رویداد تاریخچه، یعنی با کاهش شماره رویداد تاریخچه، بازگردانده شود\&.
.TP
\fBhistorywords\fP
یک آرایه ویژه حاوی کلمات ذخیره‌شده در تاریخچه\&. این کلمات نیز به ترتیب از جدیدترین به قدیمی‌ترین ظاهر می‌شوند\&.
.TP
\fBjobdirs\fP
این آرایه انجمنی شماره شغل‌ها (jobs) را به دایرکتوری‌هایی که شغل از آن‌ها آغاز شده است نگاشت می‌کند
(که ممکن است دایرکتوری جاری شغل نباشد)\&.
.RS
.PP
کلیدهای آرایه انجمنی معمولاً شماره‌های معتبر شغل‌ها هستند، و این‌ها همان مقادیری هستند که برای نمونه با
\fB${(k)jobdirs}\fP خروجی داده می‌شوند\&. هنگام جستجوی یک مقدار می‌توان از ارجاعات غیرعددی شغل نیز
استفاده کرد؛ برای مثال، \fB${jobdirs[%+]}\fP به شغل جاری اشاره دارد\&.
.PP
برای آگاهی از نحوه ارائه اطلاعات شغل در یک زیرپوسته، به توضیحات دستور توکار \fBjobs\fP مراجعه کنید\&.
.RE
.TP
\fBjobtexts\fP
این آرایه انجمنی شماره شغل‌ها را به متن خطوط فرمانی که برای شروع آن شغل‌ها استفاده شده نگاشت می‌کند\&.
.RS
.PP
مدیریت کلیدهای این آرایه انجمنی همانند توضیحات ارائه‌شده برای \fBjobdirs\fP در بالا است\&.
.PP
برای چگونگی ارائه اطلاعات شغل در زیرپوسته، به دستور توکار \fBjobs\fP مراجعه کنید\&.
.RE
.TP
\fBjobstates\fP
این آرایه انجمنی اطلاعاتی درباره وضعیت شغل‌های شناخته‌شده فعلی ارائه می‌دهد\&. کلیدها شماره شغل‌ها
و مقادیر رشته‌هایی به صورت
`\fIjob\-state\fP\fB:\fP\fImark\fP\fB:\fP\fIpid\fP\fB=\fP\fIstate\fP\&.\&.\&.\&'
هستند\&. بخش \fIjob\-state\fP وضعیت کل شغل را نشان می‌دهد که یکی از مقادیر
`\fBrunning\fP\&'، `\fBsuspended\fP' یا `\fBdone\fP' است\&. علامت \fImark\fP برای شغل جاری برابر
`\fB+\fP\&'، برای شغل قبلی برابر `\fB\-\fP' و در غیر این صورت خالی است\&. به دنبال آن یک عبارت
`\fB:\fP\fIpid\fP\fB=\fP\fIstate\fP\&' برای هر پردازش در آن شغل می‌آید\&. شناسه‌های \fIpid\fP همان
شناسه‌های پردازش هستند و \fIstate\fP وضعیت آن پردازش را شرح می‌دهد\&.
.RS
.PP
مدیریت کلیدهای این آرایه انجمنی مشابه توضیحات \fBjobdirs\fP در بالا است\&.
.PP
برای نحوه ارائه اطلاعات شغل در یک زیرپوسته، دستور توکار \fBjobs\fP را ببینید\&.
.RE
.TP
\fBnameddirs\fP
این آرایه انجمنی نام دایرکتوری‌های نام‌گذاری‌شده را به مسیرهایی که معرف آن‌ها هستند نگاشت می‌کند\&.
.TP
\fBuserdirs\fP
این آرایه انجمنی نام‌های کاربری را به مسیرهای دایرکتوری‌های خانگی آن‌ها نگاشت می‌کند\&.
.TP
\fBusergroups\fP
این آرایه انجمنی نام گروه‌های سیستمی را که کاربر جاری عضو آن‌ها است به شناسه‌های عددی گروه متناظر
نگاشت می‌کند\&. محتوای آن مشابه گروه‌های نمایش‌داده‌شده توسط دستور \fBid\fP است\&.
.TP
\fBfuncfiletrace\fP
این آرایه حاوی شماره سطرهای مطلق و نام فایل‌های متناظری است که در آن تابع جاری، فایل سورس‌شده، یا
(اگر \fBEVAL_LINENO\fP تنظیم باشد) دستور \fBeval\fP فراخوانی شده است\&. طول این آرایه با
\fBfuncsourcetrace\fP و \fBfunctrace\fP یکسان است، اما با \fBfuncsourcetrace\fP از این نظر تفاوت دارد
که سطر و فایل، نقطه فراخوانی هستند و نه نقطه تعریف، و با \fBfunctrace\fP نیز از این جهت تفاوت دارد که
تمام مقادیر، شماره سطرهای مطلق درون فایل‌ها هستند و نه نسبت به ابتدای یک تابع\&.
.TP
\fBfuncsourcetrace\fP
این آرایه شامل نام فایل‌ها و شماره سطرهایی است که توابع، فایل‌های سورس‌شده و (در صورت تنظیم \fBEVAL_LINENO\fP)
دستورات \fBeval\fP در حال اجرای فعلی در آنجا تعریف شده‌اند\&. شماره سطر همان سطری است که در آن
`\fBfunction\fP \fIname\fP\&' یا `\fIname\fP \fB()\fP\&' آغاز شده است\&. در مورد توابع autoload،
شماره سطر برابر صفر گزارش می‌شود\&. قالب هر عنصر به صورت \fIfilename\fP\fB:\fP\fIlineno\fP است\&.
.RS
.PP
برای توابعی که از یک فایل با قالب بومی zsh بارگذاری شده‌اند و فقط بدنه تابع در فایل قرار دارد، یا برای
فایل‌هایی که با دستورات توکار \fBsource\fP یا `\fB\&.\fP\&' اجرا شده‌اند، اطلاعات ردگیری به صورت
\fIfilename\fP\fB:\fP\fI0\fP نمایش داده می‌شود، زیرا کل فایل همان تعریف است\&. نام فایل سورس هنگام
بارگذاری تابع یا تفکیک مسیر آن، به یک مسیر مطلق تبدیل می‌گردد\&.
.PP
بیشتر کاربران در عوض به اطلاعات موجود در آرایه \fBfuncfiletrace\fP علاقه‌مند خواهند بود\&.
.RE
.TP
\fBfuncstack\fP
این آرایه حاوی نام توابع، فایل‌های سورس‌شده و (در صورت تنظیم بودن \fBEVAL_LINENO\fP) دستورات \fBeval\fP
در حال اجرای جاری است\&. اولین عنصر نام تابعی است که از این پارامتر استفاده می‌کند\&.
.RS
.PP
آرایه استاندارد پوسته \fBzsh_eval_context\fP می‌تواند برای تعیین نوع ساختار پوسته‌ای در حال اجرا در هر عمق
به کار رود: توجه داشته باشید که این آرایه به ترتیب معکوس است و جدیدترین مورد در انتهای آن قرار دارد، و همچنین
دارای جزئیات بیشتری است، به عنوان مثال مدخلی برای \fBtoplevel\fP دارد که کد اصلی پوسته در حال اجرا به صورت
تعاملی یا از طریق اسکریپت است و در \fB$funcstack\fP حضور ندارد\&.
.RE
.TP
\fBfunctrace\fP
این آرایه شامل نام‌ها و شماره خطوط فراخوان‌های متناظر با توابع در حال اجرای جاری است\&.
قالب هر عنصر به صورت \fIname\fP\fB:\fP\fIlineno\fP می‌باشد\&. فراخوان‌ها برای فایل‌های سورس‌شده نیز
نمایش داده می‌شوند؛ فراخوان نقطه‌ای است که دستور \fBsource\fP یا `\fB\&.\fP\&' در آن اجرا شده است\&.
.SH "ماژول ZSH/PCRE (THE ZSH/PCRE MODULE)"
.\" Yodl file: Zsh/mod_pcre.yo

ماژول \fBzsh/pcre\fP برخی دستورات را به عنوان دستور توکار در دسترس قرار می‌دهد:
.PP
.PD 0
.TP
.PD
\fBpcre_compile\fP [ \fB\-aimxs\fP ] \fIPCRE\fP
یک عبارت منظم سازگار با پرل (PCRE) را کامپایل می‌کند\&.
.RS
.PP
گزینه \fB\-a\fP الگو را مهارشده (anchored) می‌کند\&.
گزینه \fB\-i\fP الگو را حساس به بزرگ و کوچکی حروف نمی‌کند (case\-insensitive)\&.
گزینه \fB\-m\fP الگو را چندخطی کامپایل می‌کند؛ یعنی \fB^\fP و \fB$\fP با خطوط جدید درون الگو مطابقت خواهند داشت\&.
گزینه \fB\-x\fP یک الگوی گسترش‌یافته کامپایل می‌کند که در آن فاصله‌های خالی و یادداشت‌های \fB#\fP نادیده گرفته می‌شوند\&.
گزینه \fB\-s\fP باعث می‌شود متاکاراکتر نقطه با تمام نویسه‌ها، از جمله نویسه‌های نشان‌دهنده خط جدید مطابقت پیدا کند\&.
.RE
.TP
\fBpcre_study\fP
عبارت PCRE از پیش کامپایل‌شده را مورد تحلیل قرار می‌دهد که ممکن است به تطابق سریع‌تر بینجامد\&.
.TP
\fBpcre_match\fP [ \fB\-v\fP \fIvar\fP ] [ \fB\-a\fP \fIarr\fP ] [ \fB\-n\fP \fIoffset\fP ] [ \fB\-b\fP ] \fIstring\fP
در صورتی که \fBstring\fP با PCRE پیش‌تر کامپایل‌شده مطابقت داشته باشد، با موفقیت بازمی‌گردد\&.
.RS
.PP
در صورت تطابق موفق، اگر عبارت زیررشته‌هایی را درون پرانتز جذب کند، \fBpcre_match\fP آرایه
\fBmatch\fP را برابر با آن زیررشته‌ها قرار می‌دهد، مگر اینکه گزینه \fB\-a\fP داده شده باشد که در این
صورت آرایه \fIarr\fP را تنظیم می‌کند\&. به طور مشابه، متغیر \fBMATCH\fP روی کل بخش تطبیق‌یافته رشته
تنظیم می‌شود، مگر اینکه گزینه \fB\-v\fP داده شده باشد که در آن حالت متغیر \fIvar\fP مقداردهی می‌گردد\&.
در صورت عدم تطابق موفق هیچ متغیری تغییر نمی‌کند\&.
گزینه \fB\-n\fP جستجو برای تطابق را از موقعیت بایتی \fIoffset\fP در \fIstring\fP آغاز می‌کند\&. اگر
گزینه \fB\-b\fP داده شود، متغیر \fBZPCRE_OP\fP روی رشته‌ای شامل یک جفت آفست تنظیم می‌شود که بیانگر
موقعیت‌های آفست بایتی کل بخش تطبیق‌یافته درون \fIstring\fP است\&. به عنوان مثال، اگر \fBZPCRE_OP\fP روی
"32 45" تنظیم شود نشان می‌دهد بخش تطبیق‌یافته از آفست بایتی 32 آغاز شده و در آفست بایتی 44 پایان یافته است\&.
در اینجا، موقعیت آفست بایتی 45 موقعیت بلافاصله پس از بخش تطبیق‌یافته است\&. به یاد داشته باشید که موقعیت
بایتی در زمان وجود نویسه‌های UTF\-8 لزوماً با موقعیت نویسه‌ای یکسان نیست\&.
در نتیجه، موقعیت‌های آفست بایتی تنها در بستر استفاده از آن‌ها برای جستجوهای بعدی روی \fIstring\fP با
استفاده از موقعیت آفست به عنوان آرگومان گزینه \fB\-n\fP قابل اتکا هستند\&. این قابلیت عمدتاً برای پیاده‌سازی
عملکرد «یافتن تمام تطابق‌های غیرهم‌پوشان» به کار می‌رود\&.
.PP
نمونه‌ای ساده از «یافتن تمام تطابق‌های غیرهم‌پوشان»:
.PP
.RS
.nf
\fBstring="The following zip codes: 78884 90210 99513"
pcre_compile \-m "\ed{5}"
accum=()
pcre_match \-b \-\- $string
while [[ $? \-eq 0 ]] do
    b=($=ZPCRE_OP)
    accum+=$MATCH
    pcre_match \-b \-n $b[2] \-\- $string
done
print \-l $accum\fP
.fi
.RE
.RE
.PP
ماژول \fBzsh/pcre\fP شرط آزمون زیر را در دسترس قرار می‌دهد:
.PP
.PD 0
.TP
.PD
\fIexpr\fP \fB\-pcre\-match\fP \fIpcre\fP
یک رشته را با یک عبارت منظم سازگار با پرل تطبیق می‌دهد\&.
.RS
.PP
برای نمونه:
.PP
.RS
.nf
\fB[[ "$text" \-pcre\-match ^d+$ ]] &&
print text variable contains only "d\&'s"\&.\fP
.fi
.RE
.PP
اگر گزینه \fBREMATCH_PCRE\fP تنظیم شده باشد، عملگر \fB=~\fP معادل \fB\-pcre\-match\fP خواهد بود،
و گزینه \fBNO_CASE_MATCH\fP می‌تواند استفاده شود\&. توجه داشته باشید که \fBNO_CASE_MATCH\fP هرگز
بر دستور توکار \fBpcre_match\fP اعمال نمی‌شود، و در عوض باید از سوییچ \fB\-i\fP در \fBpcre_compile\fP
استفاده کرد\&.
.RE
.SH "ماژول ZSH/PARAM/PRIVATE (THE ZSH/PARAM/PRIVATE MODULE)"
.\" Yodl file: Zsh/mod_private.yo

ماژول \fBzsh/param/private\fP برای ایجاد پارامترهایی استفاده می‌شود که حوزه (scope) آن‌ها محدود به
بدنه تابع فعلی است، و \fIنه\fP به سایر توابعی که توسط تابع جاری فراخوانی می‌شوند\&.
.PP
این ماژول یک دستور توکار autoload منفرد ارائه می‌دهد:
.PD 0
.TP
.PD
\fBprivate\fP [ {\fB+\fP|\fB\-\fP}\fBAHUahlmrtux\fP ] [ {\fB+\fP|\fB\-\fP}\fBEFLRZi\fP [ \fIn\fP ] ] [ \fIname\fP[\fB=\fP\fIvalue\fP] \&.\&.\&. ]
دستور توکار \fBprivate\fP همه گزینه‌ها و آرگومان‌های مشابه \fBlocal\fP (\fIzshbuiltins\fP(1)) را می‌پذیرد
به استثنای گزینه `\fB\-\fP\fBT\fP\&'\&. پارامترهای متصل‌شده (tied) را نمی‌توان خصوصی کرد\&.
.RS
.PP
گزینه `\fB\-\fP\fBp\fP\&' در حال حاضر هیچ عملی انجام نمی‌دهد (no\-op) زیرا وضعیت پارامترهای خصوصی را
نمی‌توان به شکل قابل اعتمادی دوباره بارگذاری کرد\&. این مورد در چاپ پارامترهای خصوصی با `\fBtypeset \-p\fP\&'
نیز صدق می‌کند\&.
.PP
اگر در بالاترین سطح (خارج از دامنه تابع) استفاده شود، \fBprivate\fP یک پارامتر معمولی ایجاد می‌کند دقیقاً
به همان روش \fBdeclare\fP یا \fBtypeset\fP\&. اگر گزینه \fBWARN_CREATE_GLOBAL\fP تنظیم شده باشد
(\fIzshoptions\fP(1))، هشداری در این خصوص چاپ می‌شود\&. هنگام استفاده در حوزه یک تابع، \fBprivate\fP
یک پارامتر محلی مشابه پارامتر اعلان‌شده با \fBlocal\fP ایجاد می‌کند، با این تفاوت که دارای ویژگی‌های
ویژه ذکرشده در زیر است\&.
.PP
پارامترهای ویژه‌ای که وضعیت درونی پوسته را آشکار یا دستکاری می‌کنند، نظیر \fBARGC\fP، \fBargv\fP،
\fBCOLUMNS\fP، \fBLINES\fP، \fBUID\fP، \fBEUID\fP، \fBIFS\fP، \fBPROMPT\fP، \fBRANDOM\fP،
\fBSECONDS\fP و غیره را نمی‌توان خصوصی ساخت مگر آنکه از گزینه `\fB\-\fP\fBh\fP\&' برای پنهان کردن معنای
ویژه پارامتر استفاده شود\&. این موضوع ممکن است در آینده تغییر کند\&.
.RE
.PP
همانند سایر دستورات معادل \fBtypeset\fP، دستور \fBprivate\fP هم یک دستور توکار و هم یک کلمه کلیدی
رزروشده است، بنابراین آرایه‌ها را می‌توان با ساختار دستوری فهرست کلمات داخل پرانتز
\fIname\fP\fB=(\fP\fIvalue\fP\&.\&.\&.\fB)\fP مقداردهی کرد\&. با این حال کلمه رزروشده `\fBprivate\fP\&'
تا پیش از بارگذاری \fBzsh/param/private\fP در دسترس نیست، بنابراین باید در ترتیب اجرا و تجزیه برای تعاریف
توابعی که از \fBprivate\fP استفاده می‌کنند دقت شود\&. برای جبران این موضوع، ماژول همچنین گزینه `\fB\-P\fP\&'
را به دستور توکار `\fBlocal\fP' برای اعلان پارامترهای خصوصی اضافه می‌کند\&.
.PP
برای نمونه، در صورتی که \fBzsh/param/private\fP هنوز هنگام تعریف `\fBbad_declaration\fP\&' بارگذاری نشده
باشد، این ساختار با شکست روبرو می‌شود:
.RS
.PP
.RS
.nf
\fBbad_declaration() {
  zmodload zsh/param/private
  private array=( one two three )
}\fP
.fi
.RE
.RE
.PP
این ساختار کار می‌کند زیرا \fBlocal\fP از قبل یک کلمه کلیدی است، و ماژول پیش از اجرای عبارت بارگذاری می‌شود:
.RS
.PP
.RS
.nf
\fBgood_declaration() {
  zmodload zsh/param/private
  local \-P array=( one two three )
}\fP
.fi
.RE
.RE
.PP
کد زیر در اسکریپت‌ها قابل استفاده است اما ممکن است با \fBautoload\fP دچار مشکل شود:
.RS
.PP
.RS
.nf
\fBzmodload zsh/param/private
iffy_declaration() {
  private array=( one two three )
}\fP
.fi
.RE
.RE
.PP
دستور توکار \fBprivate\fP همواره می‌تواند برای تخصیص‌های اسکالر و برای اعلان‌های بدون تخصیص مقدار استفاده شود\&.
.PP
پارامترهای اعلان‌شده با \fBprivate\fP ویژگی‌های زیر را دارا هستند:
.PD 0
.TP
.PD
\(bu
درون بدنه تابعی که پارامتر در آن اعلان شده است، همانند یک متغیر local رفتار می‌کند، مگر در موارد ذکرشده
در بالا برای پارامترهای وابسته یا ویژه\&.
.TP
\(bu
نوع پارامتری که خصوصی اعلان شده است را نمی‌توان در دامنه‌ای که در آن اعلان شده تغییر داد، حتی اگر پارامتر
لغو مقداردهی شود\&. بنابراین یک آرایه را نمی‌توان به یک متغیر اسکالر خصوصی تخصیص داد و غیره\&.
.TP
\(bu
درون هر تابع دیگری که توسط تابع اعلان‌کننده فراخوانی شود، پارامتر خصوصی پارامترهای دیگر با همان نام را
پنهان \fIنمی‌کند\fP؛ بنابراین برای نمونه یک پارامتر سراسری با همان نام قابل مشاهده بوده و می‌تواند مقداردهی
یا لغو شود\&. این مورد شامل فراخوانی توابع ناشناس نیز می‌شود، هرچند ممکن است این رفتار در آینده تغییر کند\&.
با این حال، نام خصوصی را نمی‌توان در خارج از دامنه محلی در صورتی که قبلاً اعلان نشده باشد ایجاد کرد\&.
.TP
\(bu
یک پارامتر خصوصی صادرشده (exported) در محیط دامنه‌های درونی باقی می‌ماند اما برای پوسته جاری در آن
دامنه‌ها لغوشده به نظر می‌رسد\&. به طور کلی باید از صدور پارامترهای خصوصی خودداری شود\&.
.PP
توجه داشته باشید که این ویژگی با حوزه ایستا (static scope) تعریف‌شده در زبان‌های کامپایلری مشتق از C
تفاوت دارد، زیرا یک فراخوانی جدید به همان تابع دامنه‌ای جدید ایجاد می‌کند، یعنی پارامتر همچنان با پشته
فراخوانی مرتبط است و نه با تعریف تابع\&. همچنین با `\fBtypeset \-S\fP\&' در ksh تفاوت دارد زیرا نحو مورد
استفاده برای تعریف تابع ارتباطی با رعایت شدن حوزه پارامتر ندارد\&.
.SH "ماژول ZSH/REGEX (THE ZSH/REGEX MODULE)"
.\" Yodl file: Zsh/mod_regex.yo

ماژول \fBzsh/regex\fP شرط آزمون زیر را در دسترس قرار می‌دهد:
.PP
.PD 0
.TP
.PD
\fIexpr\fP \fB\-regex\-match\fP \fIregex\fP
یک رشته را با یک عبارت منظم گسترش‌یافته POSIX تطبیق می‌دهد\&.
در صورت تطابق موفقیت‌آمیز، بخش تطبیق‌یافته رشته معمولاً در متغیر \fBMATCH\fP قرار می‌گیرد\&. اگر هرگونه
پرانتز جذبی در عبارت منظم وجود داشته باشد، متغیر آرایه‌ای \fBmatch\fP حاوی آن‌ها خواهد بود\&.
اگر تطابق موفق نباشد، متغیرها تغییر نخواهند کرد\&.
.RS
.PP
برای نمونه:
.PP
.RS
.nf
\fB[[ alphabetical \-regex\-match ^a([^a]+)a([^a]+)a ]] &&
print \-l $MATCH X $match\fP
.fi
.RE
.PP
اگر گزینه \fBREMATCH_PCRE\fP تنظیم نشده باشد، عملگر \fB=~\fP در صورت نیاز این ماژول را به طور خودکار
بارگذاری کرده و عملگر \fB\-regex\-match\fP را فراخوانی می‌کند\&.
.PP
اگر \fBBASH_REMATCH\fP تنظیم شده باشد، آرایه \fBBASH_REMATCH\fP به جای \fBMATCH\fP و \fBmatch\fP
تنظیم خواهد شد\&.
.PP
توجه داشته باشید که منطق ماژول \fBzsh/regex\fP به سیستم میزبان متکی است\&. اگر یک \fIregex\fP با ساختار
غیر استاندارد داده شود، همان جفت \fIexpr\fP و \fIregex\fP می‌تواند نتایج متفاوتی در پلتفرم‌های مختلف ایجاد کند\&.
.PP
برای مثال هیچ ساختاری برای تطابق مرز کلمه در استاندارد عبارات منظم گسترش‌یافته POSIX تعریف نشده است\&.
GNU \fBlibc\fP و BSD \fBlibc\fP هر دو چنین ساختارهایی را به عنوان افزونه ارائه می‌دهند (به ترتیب \fB\eb\fP
و \fB[[:<:]]\fP/\fB[[:>:]]\fP)، اما هیچ‌یک از این ساختارها در هر دوی این پیاده‌سازی‌ها پشتیبانی نمی‌شود\&.
.PP
برای ساختارهای پشتیبانی‌شده به صورت محلی در سیستم خود، به صفحات راهنمای \fIregcomp\fP(3) و
\fIre_format\fP(7) مراجعه فرمایید\&.
.RE
.SH "ماژول ZSH/SCHED (THE ZSH/SCHED MODULE)"
.\" Yodl file: Zsh/mod_sched.yo

ماژول \fBzsh/sched\fP یک دستور توکار و یک پارامتر را در دسترس قرار می‌دهد\&.
.PP
.PD 0
.TP
.PD 0
\fBsched\fP [\fB\-o\fP] [\fB+\fP]\fIhh\fP\fB:\fP\fImm\fP[\fB:\fP\fIss\fP] \fIcommand\fP \&.\&.\&.
.TP
.PD 0
\fBsched\fP [\fB\-o\fP] [\fB+\fP]\fIseconds\fP \fIcommand\fP \&.\&.\&.
.TP
.PD
\fBsched\fP [ \fB\-\fP\fIitem\fP ]
یک مدخل در فهرست زمان‌بندی‌شده دستورها برای اجرا ایجاد می‌کند\&.
زمان را می‌توان به صورت زمان مطلق یا نسبی، و یا به صورت ساعت، دقیقه و (اختیاری) ثانیه جداشده با دونقطه،
یا صرفاً برحسب ثانیه تعیین کرد\&.
یک عدد مطلق از ثانیه‌ها نشان‌دهنده زمان سپری‌شده از مبدأ زمانی (1970/01/01 00:00) است؛ این ویژگی در
ترکیب با قابلیت‌های ماژول \fBzsh/datetime\fP مفید است؛ مدخل ماژول zsh/datetime را در \fIzshmodules\fP(1)
ببینید\&.
.RS
.PP
بدون آرگومان، فهرست دستورهای زمان‌بندی‌شده را چاپ می‌کند\&. اگر دستور زمان‌بندی‌شده دارای پرچم \fB\-o\fP
باشد، این مورد در ابتدای دستور نشان داده می‌شود\&.
.PP
با آرگومان `\fB\-\fP\fIitem\fP\&'، آیتم مشخص‌شده را از فهرست حذف می‌کند\&. شماره‌گذاری فهرست پیوسته است
و مدخل‌ها بر حسب ترتیب زمانی مرتب شده‌اند، بنابراین با اضافه یا حذف شدن مدخل‌ها شماره‌گذاری ممکن است تغییر کند\&.
.PP
دستورها یا بلافاصله پیش از یک اعلان یا در زمانی که ویرایشگر خط پوسته منتظر ورودی است اجرا می‌شوند\&.
در حالت دوم، تولید خروجی بدون ایجاد اختلال در خط در حال ویرایش اهمیت دارد\&. ارائه گزینه \fB\-o\fP باعث
می‌شود پوسته پیش از رویداد خط فرمان را پاک کرده و پس از آن مجدداً رسم کند\&. این گزینه باید برای هر رویداد
زمان‌بندی‌شده‌ای که خروجی قابل مشاهده در ترمینال تولید می‌کند استفاده شود؛ برای نمونه در خروجی‌هایی که
نوار عنوان شبیه‌ساز ترمینال را به‌روزرسانی می‌کنند نیازی به آن نیست\&.
.PP
برای اعمال تغییرات در بافر ویرایشگر هنگام اجرای رویداد، از دستور `\fBzle\fP\&' بدون آرگومان برای آزمایش
فعال بودن ویرایشگر استفاده کنید، و اگر فعال بود، از `\fBzle \fP\fIwidget\fP\&' برای دسترسی به ویرایشگر
از طریق \fIwidget\fP نام‌گذاری‌شده بهره ببرید\&.
.PP
دستور توکار \fBsched\fP در حالتی که پوسته در وضعیت شبیه‌سازی پوسته دیگری آغاز به کار کند به طور پیش‌فرض
در دسترس نیست\&. می‌توان آن را با دستور `\fBzmodload \-F zsh/sched b:sched\fP\&' در دسترس قرار داد\&.
.RE
.PP
.PD 0
.TP
.PD
\fBzsh_scheduled_events\fP
یک آرایه فقط‌خواندنی متناظر با رویدادهای زمان‌بندی‌شده توسط دستور توکار \fBsched\fP\&. اندیس‌های آرایه
متناظر با شماره‌هایی است که هنگام اجرای \fBsched\fP بدون آرگومان نمایش داده می‌شوند (به شرطی که گزینه
\fBKSH_ARRAYS\fP تنظیم نشده باشد)\&. مقدار آرایه شامل زمان زمان‌بندی‌شده برحسب ثانیه از مبدأ زمانی
(برای امکانات استفاده از این عدد، بخش `The zsh/datetime Module\&' را ببینید)، به دنبال آن یک دونقطه،
به دنبال آن هرگونه گزینه (که ممکن است خالی باشد اما در غیر این صورت با `\fB\-\fP\&' همراه خواهد بود)،
به دنبال آن یک دونقطه، و سپس دستور مورد نظر برای اجرا است\&.
.RS
.PP
از دستور توکار \fBsched\fP باید برای دستکاری و مدیریت این رویدادها استفاده شود\&. توجه داشته باشید که این
کار تأثیر فوری بر محتوای آرایه خواهد داشت، بنابراین اندیس‌ها ممکن است نامعتبر شوند\&.
.RE
.SH "ماژول ZSH/NET/SOCKET (THE ZSH/NET/SOCKET MODULE)"
.\" Yodl file: Zsh/mod_socket.yo

ماژول \fBzsh/net/socket\fP یک دستور توکار در دسترس قرار می‌دهد:
.PP
.PD 0
.TP
.PD
\fBzsocket\fP [ \fB\-altv\fP ] [ \fB\-d\fP \fIfd\fP ] [ \fIargs\fP ]
دستور \fBzsocket\fP به صورت یک دستور توکار پیاده‌سازی شده است تا امکان استفاده کامل از ویرایش
خط فرمان پوسته، ورودی/خروجی فایل، و سازوکارهای کنترل شغل را فراهم کند\&.
.PP
.SS "اتصال‌های خروجی (Outbound Connections)"
.PP
.PD 0
.TP
.PD
\fBzsocket\fP [ \fB\-v\fP ] [ \fB\-d\fP \fIfd\fP ] \fIfilename\fP
یک اتصال جدید در دامنه یونیکس به \fIfilename\fP باز می‌کند\&.
پارامتر پوسته‌ای \fBREPLY\fP روی توصیف‌کننده فایل مرتبط با آن اتصال تنظیم خواهد شد\&.
در حال حاضر، تنها اتصال‌های جریانی (stream connections) پشتیبانی می‌شوند\&.
.RS
.PP
اگر \fB\-d\fP تعیین شود، آرگومان آن به عنوان توصیف‌کننده فایل هدف برای اتصال در نظر گرفته می‌شود\&.
.PP
برای دریافت خروجی با جزئیات بیشتر، از \fB\-v\fP استفاده کنید\&.
.PP
هنگامی که دیگر نیازی به توصیف‌کننده‌های فایل نباشد، می‌توان آن‌ها را با نحو معمول پوسته بست، به عنوان مثال:
.PP
.RS
.nf
\fBexec {REPLY}>&\-\fP
.fi
.RE
.RE
.PP
.SS "اتصال‌های ورودی (Inbound Connections)"
.PP
.PD 0
.TP
.PD
\fBzsocket\fP \fB\-l\fP [ \fB\-v\fP ] [ \fB\-d\fP \fIfd\fP ] \fIfilename\fP
دستور \fBzsocket \-l\fP یک سوکت شنونده روی \fIfilename\fP باز می‌کند\&.
پارامتر پوسته‌ای \fBREPLY\fP روی توصیف‌کننده فایل متناظر با آن شنونده تنظیم خواهد شد\&.
این توصیف‌کننده فایل در زیرپوسته‌ها و فایل‌های اجرایی خارجی منشعب‌شده باز می‌ماند\&.
.RS
.PP
اگر \fB\-d\fP تعیین شود، آرگومان آن به عنوان توصیف‌کننده فایل هدف برای اتصال لحاظ می‌گردد\&.
.PP
جهت دریافت خروجی با جزئیات بیشتر، از \fB\-v\fP استفاده کنید\&.
.RE
.TP
\fBzsocket\fP \fB\-a\fP [ \fB\-tv\fP ] [ \fB\-d\fP \fItargetfd\fP ] \fIlistenfd\fP
دستور \fBzsocket \-a\fP یک اتصال ورودی به سوکت مرتبط با \fIlistenfd\fP را می‌پذیرد\&.
پارامتر پوسته‌ای \fBREPLY\fP روی توصیف‌کننده فایل مرتبط با اتصال ورودی تنظیم خواهد شد\&.
این توصیف‌کننده فایل در زیرپوسته‌ها و برنامه‌های اجرایی خارجی منشعب باز می‌ماند\&.
.RS
.PP
اگر \fB\-d\fP مشخص شود، آرگومان آن به عنوان توصیف‌کننده فایل مقصد برای اتصال تلقی خواهد شد\&.
.PP
اگر \fB\-t\fP مشخص شده باشد، در صورتی که هیچ اتصال ورودی در انتظار نباشد، \fBzsocket\fP
بلافاصله بازمی‌گردد\&. در غیر این صورت منتظر یک اتصال خواهد ماند\&.
.PP
برای دریافت خروجی با جزئیات بیشتر، از \fB\-v\fP استفاده کنید\&.
.RE
.SH "ماژول ZSH/STAT (THE ZSH/STAT MODULE)"
.\" Yodl file: Zsh/mod_stat.yo

ماژول \fBzsh/stat\fP یک دستور توکار را تحت دو نام ممکن در دسترس قرار می‌دهد:
.PP
.PD 0
.TP
.PD 0
\fBzstat \fP[ \fB\-gnNolLtTrs\fP ] [ \fB\-f\fP \fIfd\fP ] [ \fB\-H\fP \fIhash\fP ] [ \fB\-A\fP \fIarray\fP ] [ \fB\-F\fP \fIfmt\fP ]
.TP
.PD 0
\fB      \fP[ \fB+\fP\fIelement\fP ] [ \fIfile\fP \&.\&.\&. ]
.TP
.PD
\fBstat\fP \fI\&.\&.\&.\fP
این دستور به عنوان یک رابط برای فراخوانی سیستمی \fBstat\fP عمل می‌کند (راهنمای \fIstat\fP(2) را ببینید)\&.
همین دستور با دو نام ارائه شده است؛ از آنجا که نام \fBstat\fP اغلب توسط یک دستور خارجی استفاده می‌شود،
توصیه می‌شود تنها از صورت \fBzstat\fP این دستور استفاده شود\&. این کار را می‌توان با بارگذاری ماژول با
دستور `\fBzmodload \-F zsh/stat b:zstat\fP\&' هماهنگ کرد\&.
.RS
.PP
اگر فراخوانی \fBstat\fP با شکست مواجه شود، پیام خطای سیستمی مناسب چاپ شده و وضعیت 1 بازگردانده می‌شود\&.
فیلدهای ساختار \fBstruct stat\fP اطلاعاتی درباره فایل‌های ارائه‌شده به عنوان آرگومان به دستور فراهم
می‌کنند\&. علاوه بر فیلدهای موجود در فراخوانی \fBstat\fP، یک عنصر اضافی به نام `\fBlink\fP\&' نیز فراهم شده است\&.
این عناصر عبارتند از:
.PP
.PD 0
.TP
.PD
\fBdevice\fP
شماره دستگاهی که فایل روی آن قرار دارد\&.
.TP
\fBinode\fP
شماره منحصربه‌فرد فایل روی این دستگاه (شماره `\fIinode\fP\&')\&.
.TP
\fBmode\fP
حالت دسترسی فایل؛ یعنی نوع فایل و مجوزهای دسترسی آن\&. با گزینه \fB\-s\fP، این مقدار به صورت
رشته‌ای متناظر با ستون اول نمایش دستور \fBls \-l\fP بازگردانده می‌شود\&.
.TP
\fBnlink\fP
تعداد پیوندهای سخت به فایل\&.
.TP
\fBuid\fP
شناسه کاربری مالک فایل\&. با گزینه \fB\-s\fP، این مقدار به صورت نام کاربری نمایش داده می‌شود\&.
.TP
\fBgid\fP
شناسه گروه فایل\&. با گزینه \fB\-s\fP، به صورت نام گروه نمایش داده می‌شود\&.
.TP
\fBrdev\fP
شماره دستگاه خام\&. این مقدار فقط برای دستگاه‌های خاص مفید است\&.
.TP
\fBsize\fP
اندازه فایل برحسب بایت\&.
.TP
.PD 0
\fBatime\fP
.TP
.PD 0
\fBmtime\fP
.TP
.PD
\fBctime\fP
به ترتیب زمان‌های آخرین دسترسی، آخرین تغییر محتوا، و آخرین تغییر اینود فایل، به صورت تعداد ثانیه‌های
سپری‌شده از نیمه‌شب اول ژانویه ۱۹۷۰ برحسب گرینویچ (GMT)\&. با گزینه \fB\-s\fP، این زمان‌ها به عنوان
رشته‌هایی برای منطقه زمانی محلی چاپ می‌شوند؛ قالب نمایش را می‌توان با گزینه \fB\-F\fP تغییر داد، و با
گزینه \fB\-g\fP زمان‌ها بر مبنای GMT خواهند بود\&.
.TP
\fBblksize\fP
تعداد بایت‌های موجود در یک بلوک تخصیص روی دستگاهی که فایل در آن مستقر است\&.
.TP
\fBblock\fP
تعداد بلوک‌های دیسک مورد استفاده فایل\&.
.TP
\fBlink\fP
اگر فایل یک پیوند باشد و گزینه \fB\-L\fP اعمال شده باشد، این فیلد شامل نام فایلی است که به آن پیوند داده
شده است، در غیر این صورت خالی خواهد بود\&. توجه داشته باشید که در صورت انتخاب این عنصر
(``\fBzstat +link\fP\&'')، گزینه \fB\-L\fP به طور خودکار فعال می‌شود\&.
.PP
یک عنصر خاص را می‌توان با درج نام آن همراه با یک علامت `\fB+\fP\&' در فهرست گزینه‌ها انتخاب کرد؛ تنها
یک عنصر مجاز است\&. نام عنصر را می‌توان به هر مجموعه منحصربه‌فردی از نویسه‌های ابتدایی آن خلاصه کرد\&.
در غیر این صورت، تمام عناصر برای تمام فایل‌ها نمایش داده خواهند شد\&.
.PP
گزینه‌ها:
.PP
.PD 0
.TP
.PD
\fB\-A\fP \fIarray\fP
به جای نمایش نتایج در خروجی استاندارد، آن‌ها را به یک \fIarray\fP تخصیص می‌دهد، به این صورت که برای
هر فایل به ترتیب یک عنصر از \fBstruct stat\fP در هر عنصر آرایه قرار می‌گیرد\&. در این حالت نه نام عنصر
و نه نام فایل‌ها در \fIarray\fP ظاهر نمی‌شوند، مگر اینکه به ترتیب گزینه‌های \fB\-t\fP یا \fB\-n\fP داده
شده باشند\&. اگر \fB\-t\fP داده شود، نام عنصر به عنوان پیشوند به عنصر مربوطه آرایه اضافه می‌شود؛ اگر
\fB\-n\fP داده شود، نام فایل به عنوان یک عنصر جداگانه در آرایه قبل از بقیه عناصر قرار می‌گیرد\&.
سایر گزینه‌های قالب‌بندی رعایت می‌شوند\&.
.TP
\fB\-H\fP \fIhash\fP
مشابه \fB\-A\fP، اما مقادیر را به یک جدول درهم‌سازی (آرایه انجمنی) \fIhash\fP تخصیص می‌دهد\&. کلیدها همان
عناصر ذکرشده در بالا هستند\&. اگر گزینه \fB\-n\fP ارائه شود، نام فایل با کلید \fBname\fP در جدول درهم‌سازی گنجانده می‌شود\&.
.TP
\fB\-f\fP \fIfd\fP
از فایل متصل به توصیف‌کننده فایل \fIfd\fP به جای فایل‌های نام‌گذاری‌شده استفاده می‌کند؛ در این حالت
فهرستی از نام فایل‌ها مجاز نیست\&.
.TP
\fB\-F\fP \fIfmt\fP
یک رشته قالب \fBstrftime\fP (راهنمای \fIstrftime\fP(3) را ببینید) برای قالب‌بندی عناصر زمانی فراهم
می‌کند\&. رشته قالب از تمام افزونه‌های zsh شرح‌داده‌شده در بخش EXPANSION OF PROMPT SEQUENCES در
\fIzshmisc\fP(1) پشتیبانی می‌کند\&. به ویژه، \fB\-F %s\&.%N\fP می‌تواند برای نمایش زمان با دقت نانوثانیه
در صورت پشتیبانی سیستم به کار رود\&. گزینه \fB\-s\fP به طور ضمنی فعال می‌شود\&.
.TP
\fB\-g\fP
عناصر زمانی را در منطقه زمانی گرینویچ (GMT) نشان می‌دهد\&. گزینه \fB\-s\fP به صورت ضمنی اعمال می‌شود\&.
.TP
\fB\-l\fP
نام عناصر نوع را (بسته به مورد در خروجی استاندارد یا یک آرایه) فهرست کرده و بلافاصله بازمی‌گردد؛
آرگومان‌ها و گزینه‌هایی غیر از \fB\-A\fP نادیده گرفته می‌شوند\&.
.TP
\fB\-L\fP
به جای فراخوانی سیستمی \fBstat\fP، فراخوانی \fBlstat\fP (راهنمای \fIlstat\fP(2) را ببینید) را انجام
می‌دهد\&. در این حالت اگر فایل یک پیوند باشد، اطلاعات مربوط به خود پیوند به جای فایل مقصد بازگردانده
می‌شود\&. این گزینه برای مفید واقع شدن عنصر \fBlink\fP الزامی است\&. بسیار مهم است توجه داشته باشید که
این رفتار دقیقاً برعکس رفتار دستور \fIls\fP(1) و غیره است\&.
.TP
\fB\-n\fP
همواره نام فایل‌ها را نمایش می‌دهد\&. معمولاً نام‌ها تنها زمانی نشان داده می‌شوند که خروجی به خروجی
استاندارد فرستاده شود و بیش از یک فایل در فهرست وجود داشته باشد\&.
.TP
\fB\-N\fP
هرگز نام فایل‌ها را نمایش نمی‌دهد\&.
.TP
\fB\-o\fP
اگر حالت دسترسی خام فایل چاپ شود، آن را در مبنای هشت (اکتال) نشان می‌دهد که برای خوانش انسانی بسیار
مفیدتر از مبنای ده پیش‌فرض است\&. در این حالت یک صفر در ابتدا چاپ خواهد شد\&. توجه داشته باشید که این
گزینه بر نمایش داده شدن حالت دسترسی خام یا قالب‌بندی‌شده تأثیری ندارد (که توسط گزینه‌های \fB\-r\fP و
\fB\-s\fP کنترل می‌شود)، و همچنین تأثیری بر نمایش یا عدم نمایش کلی حالت فایل ندارد\&.
.TP
\fB\-r\fP
داده‌های خام (قالب پیش‌فرض) را در کنار داده‌های رشته‌ای (قالب \fB\-s\fP) چاپ می‌کند؛ داده‌های رشته‌ای
درون پرانتز پس از داده‌های خام ظاهر می‌شوند\&.
.TP
\fB\-s\fP
عناصر \fBmode\fP، \fBuid\fP، \fBgid\fP و سه عنصر زمانی را به جای عدد به صورت رشته چاپ می‌کند\&. در هر
مورد، قالب مشابه خروجی \fBls \-l\fP است\&.
.TP
\fB\-t\fP
همواره نام نوع فیلدها را برای عناصر \fBstruct stat\fP نشان می‌دهد\&. معمولاً این نام‌ها تنها زمانی چاپ
می‌شوند که خروجی در خروجی استاندارد باشد و هیچ عنصر منفردی انتخاب نشده باشد\&.
.TP
\fB\-T\fP
هرگز نام نوع عناصر \fBstruct stat\fP را نمایش نمی‌دهد\&.
.RE
.SH "ماژول ZSH/SYSTEM (THE ZSH/SYSTEM MODULE)"
.\" Yodl file: Zsh/mod_system.yo

ماژول \fBzsh/system\fP دستورات توکار و پارامترهای گوناگونی را در دسترس قرار می‌دهد\&.
.PP
.SS "دستورات توکار (Builtins)"
.PP
.PD 0
.TP
.PD
\fBsyserror\fP [ \fB\-e\fP \fIerrvar\fP ] [ \fB\-p\fP \fIprefix\fP ] [ \fIerrno\fP | \fIerrname\fP ]
این دستور پیام خطای مرتبط با \fIerrno\fP (یک شماره خطای سیستمی) را همراه با یک خط جدید در خروجی خطای
استاندارد چاپ می‌کند\&.
.RS
.PP
به جای شماره خطا، می‌توان از یک نام \fIerrname\fP مانند \fBENOENT\fP استفاده کرد\&. مجموعه این نام‌ها
همان محتوای آرایه \fBerrnos\fP است، به توضیحات زیر مراجعه کنید\&.
.PP
اگر رشته \fIprefix\fP ارائه شود، بدون هیچ فاصله واسطی در ابتدای پیام خطا چاپ می‌شود\&.
.PP
اگر \fIerrvar\fP داده شود، کل پیام بدون خط جدید به پارامتری با نام \fIerrvar\fP اختصاص داده شده و چیزی
چاپ نخواهد شد\&.
.PP
وضعیت خروجی 0 نشان می‌دهد پیام با موفقیت چاپ شده است (اگرچه در صورتی که شماره خطا خارج از دامنه سیستم
باشد ممکن است مفید نباشد)، وضعیت خروجی 1 نشان‌دهنده خطا در پارامترهاست، و وضعیت خروجی 2 نشان می‌دهد
نام خطا شناخته نشده است (در این حالت پیامی چاپ نمی‌شود)\&.
.RE
.TP
.PD 0
\fBsysopen\fP [ \fB\-arw\fP ] [ \fB\-m\fP \fIpermissions\fP ] [ \fB\-o\fP \fIoptions\fP ]
.TP
.PD
\fB        \fP\fB\-u\fP \fIfd\fP \fIfile\fP
این دستور یک فایل را باز می‌کند\&. پرچم‌های \fB\-r\fP، \fB\-w\fP و \fB\-a\fP به ترتیب نشان می‌دهند
که فایل باید برای خواندن، نوشتن و الحاق باز شود\&. گزینه \fB\-m\fP امکان تعیین مجوزهای اولیه هنگام
ایجاد فایل را در قالب مبنای هشت فراهم می‌کند\&. توصیف‌کننده فایل با \fB\-u\fP مشخص می‌شود\&. می‌توان
یک توصیف‌کننده فایل صریح در محدوده 0 تا 9 تعیین کرد یا نام متغیری را ارائه داد که شماره توصیف‌کننده
فایل به آن اختصاص یابد\&.
.RS
.PP
گزینه \fB\-o\fP امکان می‌دهد گزینه‌های گوناگون مختص سیستم به صورت فهرستی جداشده با کاما تعیین شوند\&.
فهرست زیر گزینه‌های ممکن را نشان می‌دهد\&. توجه داشته باشید که بسته به سیستم، برخی ممکن است در دسترس نباشند:
.PD 0
.TP
.PD
\fBcloexec\fP
فایل را علامت‌گذاری می‌کند تا هنگام اجرای سایر برنامه‌ها بسته شود (در غیر این صورت توصیف‌کننده فایل در
زیرپوسته‌ها و برنامه‌های اجرایی خارجی منشعب باز می‌ماند)
.TP
.PD 0
\fBcreate\fP
.TP
.PD
\fBcreat\fP
در صورت عدم وجود فایل، آن را ایجاد می‌کند
.TP
\fBexcl\fP
فایل را ایجاد می‌کند و در صورت وجود قبلی آن، خطا می‌دهد
.TP
\fBnoatime\fP
از به‌روزرسانی زمان دسترسی (atime) فایل جلوگیری می‌کند
.TP
\fBnofollow\fP
در صورتی که \fIfile\fP یک پیوند نمادین باشد با شکست مواجه می‌شود
.TP
\fBnonblock\fP
فایل در حالت غیرمسدودکننده (nonblocking) باز می‌شود
.TP
\fBsync\fP
درخواست می‌کند که عملیات نوشتن تا زمانی که داده‌ها به صورت فیزیکی نوشته نشده‌اند منتظر بماند
.TP
.PD 0
\fBtruncate\fP
.TP
.PD
\fBtrunc\fP
فایل را به اندازه 0 کوتاه (truncate) می‌کند
.PP
برای بستن فایل، از یکی از دستورات زیر استفاده کنید:
.PP
.RS
.nf
\fBexec {\fP\fIfd\fP\fB}<&\-\fP
\fBexec {\fP\fIfd\fP\fB}>&\-\fP
.fi
.RE
.RE
.TP
.PD 0
\fBsysread \fP[ \fB\-c\fP \fIcountvar\fP ] [ \fB\-i\fP \fIinfd\fP ] [ \fB\-o\fP \fIoutfd\fP ]
.TP
.PD
\fB        \fP[ \fB\-s\fP \fIbufsize\fP ] [ \fB\-t\fP \fItimeout\fP ] [ \fIparam\fP ]
یک عملیات خواندن سیستمی منفرد را از توصیف‌کننده فایل \fIinfd\fP (یا صفر در صورت عدم تعیین) انجام می‌دهد\&.
نتیجه خواندن در \fIparam\fP یا در \fBREPLY\fP در صورت عدم تعیین ذخیره می‌شود\&. اگر \fIcountvar\fP داده
شود، تعداد بایت‌های خوانده‌شده به پارامتری با نام \fIcountvar\fP اختصاص می‌یابد\&.
.RS
.PP
حداکثر تعداد بایت‌های خوانده‌شده \fIbufsize\fP یا در صورت عدم تعیین 8192 است؛ با این حال به محض اینکه هر
تعدادی از بایت‌ها با موفقیت خوانده شد، دستور بلافاصله بازمی‌گردد\&.
.PP
اگر \fItimeout\fP داده شود، زمان‌انتظار را برحسب ثانیه تعیین می‌کند، که می‌تواند صفر باشد تا توصیف‌کننده
فایل را نمونه‌برداری (poll) کند\&. این کار در صورت امکان با فراخوانی سیستمی \fBpoll\fP و در غیر این صورت با
فراخوانی سیستمی \fBselect\fP مدیریت می‌شود\&.
.PP
اگر \fIoutfd\fP داده شود، تلاشی صورت می‌گیرد تا تمام بایت‌های تازه خوانده‌شده در توصیف‌کننده فایل
\fIoutfd\fP نوشته شوند\&. اگر این عملیات به دلیل یک خطای سیستمی غیر از \fBEINTR\fP یا به دلیل خطای درونی
zsh در طول وقفه با شکست مواجه شود، بایت‌های خوانده‌شده اما نوشته‌نشده در پارامتری با نام \fIparam\fP
در صورت ارائه ذخیره می‌شوند (در این حالت پیش‌فرضی به کار نمی‌رود)، و تعداد بایت‌های خوانده‌شده اما
نوشته‌نشده در پارامتری با نام \fIcountvar\fP در صورت تعیین ذخیره می‌گردد\&. اگر موفقیت‌آمیز بود،
\fIcountvar\fP مانند همیشه حاوی تعداد کامل بایت‌های انتقال‌یافته است و \fIparam\fP تنظیم نمی‌شود\&.
.PP
خطای \fBEINTR\fP (فراخوانی سیستمی متوقف‌شده با وقفه) به صورت درونی مدیریت می‌شود تا وقفه‌های پوسته برای
فراخوان شفاف باشند\&. هر خطای دیگری باعث بازگشت دستور می‌گردد\&.
.PP
وضعیت‌های بازگشتی ممکن عبارتند از:
.PD 0
.TP
.PD
0
حداقل یک بایت داده با موفقیت خوانده شده و در صورت لزوم نوشته شده است\&.
.TP
1
خطایی در پارامترهای ارائه‌شده به دستور رخ داده است\&. این تنها خطایی است که برای آن پیامی در خروجی خطای
استاندارد چاپ می‌شود\&.
.TP
2
خطایی در هنگام خواندن، یا در حین بررسی توصیف‌کننده فایل ورودی برای زمان‌انتظار رخ داده است\&.
پارامتر \fBERRNO\fP نوع خطا را نشان می‌دهد\&.
.TP
3
داده‌ها با موفقیت خوانده شدند، اما در هنگام نوشتن آن‌ها در \fIoutfd\fP خطایی رخ داد\&.
پارامتر \fBERRNO\fP خطا را گزارش می‌کند\&.
.TP
4
تلاش برای خواندن با پایان زمان‌انتظار مواجه شد\&. توجه داشته باشید این حالت \fBERRNO\fP را تنظیم نمی‌کند
زیرا یک خطای سیستمی نیست\&.
.TP
5
هیچ خطای سیستمی رخ نداد، اما صفر بایت خوانده شد\&. این حالت معمولاً نشان‌دهنده پایان فایل (EOF) است\&.
پارامترها بر اساس قواعد معمول تنظیم می‌شوند؛ هیچ تلاشی برای نوشتن در \fIoutfd\fP انجام نمی‌گیرد\&.
.RE
.TP
\fBsysseek\fP [ \fB\-u\fP \fIfd\fP ] [ \fB\-w\fP \fBstart\fP|\fBend\fP|\fBcurrent\fP ] \fIoffset\fP
موقعیت فعلی فایل را که خواندن‌ها و نوشتن‌های بعدی در آن رخ خواهند داد به آفست بایتی مشخص‌شده تنظیم می‌کند\&.
مقدار \fIoffset\fP به عنوان یک عبارت ریاضی ارزیابی می‌شود\&. گزینه \fB\-u\fP امکان تعیین توصیف‌کننده فایل
را فراهم می‌کند\&. به طور پیش‌فرض آفست نسبت به ابتدای فایل سنجیده می‌شود، اما با گزینه \fB\-w\fP می‌توان
مشخص کرد که آفست نسبت به موقعیت فعلی یا انتهای فایل سنجیده شود\&.
.TP
\fBsyswrite\fP [ \fB\-c\fP \fIcountvar\fP ] [ \fB\-o\fP \fIoutfd\fP ] \fIdata\fP
داده‌ها (یک رشته بایت منفرد) را با استفاده از فراخوانی سیستمی \fBwrite\fP در توصیف‌کننده فایل \fIoutfd\fP
(یا 1 در صورت عدم تعیین) می‌نویسد\&. در صورتی که عملیات اول تمام داده‌ها را ننویسد، ممکن است چندین
عملیات نوشتن متوالی انجام شود\&.
.RS
.PP
اگر \fIcountvar\fP داده شود، تعداد بایت‌های نوشته‌شده در پارامتری با نام \fIcountvar\fP ذخیره می‌شود؛
در صورت بروز خطا این عدد ممکن است برابر با طول کل \fIdata\fP نباشد\&.
.PP
خطای \fBEINTR\fP (فراخوانی سیستمی قطع‌شده با وقفه) با تلاش مجدد به صورت درونی مدیریت می‌شود؛ در غیر این
صورت خطا باعث بازگشت دستور خواهد شد\&. برای نمونه اگر توصیف‌کننده فایل برای خروجی غیرمسدودکننده تنظیم شده
باشد، خطای \fBEAGAIN\fP (در برخی سیستم‌ها \fBEWOULDBLOCK\fP) ممکن است منجر به بازگشت زودهنگام دستور شود\&.
.PP
وضعیت خروجی می‌تواند 0 برای موفقیت، 1 برای خطا در پارامترهای دستور، یا 2 برای خطا در هنگام نوشتن باشد؛
در حالت اخیر پیامی چاپ نمی‌شود، اما پارامتر \fBERRNO\fP خطای رخ‌داده را بازتاب می‌دهد\&.
.RE
.TP
.PD 0
\fBzsystem flock\fP [ \fB\-t\fP \fItimeout\fP ] [ \fB\-i\fP \fIinterval\fP ] [ \fB\-f\fP \fIvar\fP ] [\fB\-er\fP] \fIfile\fP
.TP
.PD
\fBzsystem flock \-u\fP \fIfd_expr\fP
زیردستور \fBflock\fP از دستور توکار \fBzsystem\fP، قفل‌گذاری مشورتی فایل (advisory file locking از طریق
فراخوانی سیستمی \fIfcntl\fP(2)) را روی کل محتوای فایل مشخص‌شده انجام می‌دهد\&. این شکل از قفل‌گذاری نیازمند
همکاری پردازش‌هایی است که به فایل دسترسی دارند؛ بارزترین کاربرد آن میان دو نمونه از خود پوسته است\&.
.RS
.PP
در حالت اول، \fIfile\fP نام‌گذاری‌شده که باید از قبل وجود داشته باشد، با باز کردن یک توصیف‌کننده فایل به
آن و اعمال قفل روی آن توصیف‌کننده، قفل می‌شود\&. قفل زمانی پایان می‌یابد که پردازش پوسته‌ای که قفل را
ایجاد کرده خاتمه یابد؛ بنابراین اغلب مناسب است قفل‌های فایل درون زیرپوسته‌ها ایجاد شوند، زیرا قفل با خروج
زیرپوسته به طور خودکار آزاد می‌شود\&. توجه داشته باشید که استفاده از دستور توکار \fBprint\fP با گزینه
\fB\-u\fP به عنوان یک اثر جانبی قفل را آزاد خواهد کرد، و تغییرمسیر به فایل در پوسته‌ای که قفل را در اختیار
دارد نیز همین اثر را دارد\&. برای حل این مشکل از زیرپوسته استفاده کنید، مثلاً `\fB(print message) >> \fP\fIfile\fP\&'\&.
در صورت موفقیت در قفل وضعیت 0 و در غیر این صورت وضعیت 1 بازگردانده می‌شود\&.
.PP
در حالت دوم، توصیف‌کننده فایل ارائه‌شده توسط عبارت حسابی \fIfd_expr\fP بسته شده و قفل آزاد می‌گردد\&.
توصیف‌کننده فایل را می‌توان با استفاده از فرم `\fB\-f\fP \fIvar\fP\&' در حین قفل‌گذاری به دست آورد؛
در صورت قفل موفقیت‌آمیز، متغیر پوسته‌ای \fIvar\fP روی توصیف‌کننده فایل مورد استفاده برای قفل‌گذاری تنظیم می‌شود\&.
اگر توصیف‌کننده فایل با هر روش دیگری بسته شود، مثلاً با `\fBexec {\fP\fIvar\fP\fB}>&\-\fP\&' قفل آزاد
خواهد شد؛ با این حال، صورتی که در اینجا شرح داده شد بررسی ایمنی انجام می‌دهد که توصیف‌کننده فایل برای
قفل فایل در حال استفاده باشد\&.
.PP
به طور پیش‌فرض، پوسته برای همیشه منتظر موفقیت در قفل‌گذاری می‌ماند\&. گزینه \fB\-t\fP \fItimeout\fP یک
زمان‌انتظار برای قفل برحسب ثانیه تعیین می‌کند؛ ثانیه‌های کسری مجاز هستند\&. در طول این مدت، پوسته تلاش
می‌کند هر \fIinterval\fP ثانیه (در صورت ارائه گزینه \fB\-i\fP \fIinterval\fP) یا در غیر این صورت هر یک
ثانیه فایل را قفل کند\&. (این \fIinterval\fP پیش از آخرین تلاش در صورت نیاز کوتاه‌تر می‌شود تا پوسته
تنها تا سقف \fItimeout\fP منتظر بماند و نه بیشتر)\&. اگر تلاش با پایان زمان‌انتظار مواجه شود، وضعیت 2
بازگردانده می‌شود\&.
.PP
(توجه: \fItimeout\fP به 2^30\-1 ثانیه (حدود ۳۴ سال) و \fIinterval\fP به 0.999 * LONG_MAX میکروثانیه
(حدود ۳۵ دقیقه در سیستم‌های ۳۲ بیتی) محدود است\&.)
.PP
اگر گزینه \fB\-e\fP داده شود، توصیف‌کننده فایل برای قفل در زمانی که پوسته از \fBexec\fP برای راه‌اندازی
یک پردازش جدید استفاده می‌کند حفظ می‌شود؛ در غیر این صورت در آن نقطه بسته شده و قفل آزاد می‌گردد\&.
.PP
اگر گزینه \fB\-r\fP داده شود، قفل صرفاً برای خواندن است، در غیر این صورت برای خواندن و نوشتن خواهد بود\&.
توصیف‌کننده فایل بر همین اساس باز می‌شود\&.
.RE
.TP
\fBzsystem supports\fP \fIsubcommand\fP
زیردستور \fBsupports\fP از دستور توکار \fBzsystem\fP بررسی می‌کند که آیا یک زیردستور معین پشتیبانی
می‌شود یا خیر\&. در این صورت وضعیت 0 و در غیر این صورت وضعیت 1 را بازمی‌گرداند\&. این دستور در سکوت عمل
می‌کند مگر اینکه خطای نگارشی (یعنی تعداد نادرست آرگومان‌ها) وجود داشته باشد، که در این حالت وضعیت 255
بازگردانده می‌شود\&. وضعیت 1 می‌تواند بیانگر یکی از دو مورد باشد: \fIsubcommand\fP شناخته‌شده است اما توسط
سیستم‌عامل جاری پشتیبانی نمی‌شود، یا \fIsubcommand\fP ناشناخته است (احتمالاً به دلیل نسخه قدیمی‌تر پوسته
پیش از پیاده‌سازی آن)\&.
.PP
.SS "توابع ریاضی (Math Functions)"
.PP
.PD 0
.TP
.PD
\fBsystell(\fIfd\fP)\fP
تابع ریاضی systell موقعیت فعلی فایل را برای توصیف‌کننده فایل ارسال‌شده به عنوان آرگومان بازمی‌گرداند\&.
.PP
.SS "پارامترها (Parameters)"
.PP
.PD 0
.TP
.PD
\fBerrnos\fP
یک آرایه فقط‌خواندنی از نام خطاهای تعریف‌شده در سیستم\&. این‌ها معمولاً ماکروهایی در C هستند که با گنجاندن
فایل سرایند سیستمی \fBerrno\&.h\fP تعریف می‌شوند\&. اندیس هر نام (با فرض اینکه گزینه \fBKSH_ARRAYS\fP
تنظیم نشده باشد) متناظر با شماره خطا است\&. به شماره‌های خطای \fInum\fP پیش از آخرین خطای شناخته‌شده که
نامی ندارند، نام \fBE\fP\fInum\fP در آرایه اختصاص داده می‌شود\&.
.RS
.PP
توجه داشته باشید که نام‌های مستعار برای خطاها مدیریت نمی‌شوند؛ تنها نام استاندارد و رسمی به کار می‌رود\&.
.RE
.TP
\fBsysparams\fP
یک آرایه انجمنی فقط‌خواندنی\&. کلیدها عبارتند از:
.RS
.PP
.PD 0
.TP
.PD
\fBpid\fP
شناسه پردازش (PID) پردازش جاری را حتی در زیرپوسته‌ها بازمی‌گرداند\&. مقایسه کنید با \fB$$\fP، که شناسه
پردازش پردازش اصلی پوسته را بازمی‌گرداند\&.
.TP
\fBppid\fP
شناسه پردازش جاری والد پردازش فعلی را حتی در زیرپوسته‌ها بازمی‌گرداند\&. مقایسه کنید با \fB$PPID\fP،
که شناسه پردازش والد اولیه پردازش اصلی پوسته را بازمی‌گرداند\&.
.TP
\fBprocsubstpid\fP
شناسه پردازش آخرین پردازش راه‌اندازی‌شده برای جایگزینی پردازش بازمی‌گرداند، یعنی بسط‌های
\fB<(\fP\fI\&.\&.\&.\fP\fB)\fP و \fB>(\fP\fI\&.\&.\&.\fP\fB)\fP\&.
.RE
.SH "ماژول ZSH/NET/TCP (THE ZSH/NET/TCP MODULE)"
.\" Yodl file: Zsh/mod_tcp.yo

ماژول \fBzsh/net/tcp\fP یک دستور توکار در دسترس قرار می‌دهد:
.PP
.PD 0
.TP
.PD
\fBztcp\fP [ \fB\-acflLtv\fP ] [ \fB\-d\fP \fIfd\fP ] [ \fIargs\fP ]
دستور \fBztcp\fP به صورت یک دستور توکار پیاده‌سازی شده است تا امکان استفاده کامل از ویرایش
خط فرمان پوسته، ورودی/خروجی فایل، و سازوکارهای کنترل شغل را فراهم کند\&.
.RS
.PP
اگر \fBztcp\fP بدون هیچ گزینه‌ای اجرا شود، محتوای جدول نشست‌های (session table) خود را
نمایش می‌دهد\&.
.PP
اگر تنها با گزینه \fB\-L\fP اجرا شود، محتوای جدول نشست‌ها را در قالبی مناسب برای تجزیه خودکار
خروجی می‌دهد\&. در صورتی که این گزینه همراه با دستوری برای باز کردن یا بستن یک نشست داده شود،
نادیده گرفته خواهد شد\&. خروجی شامل مجموعه‌ای از خطوط است (یکی به ازای هر نشست) که هر کدام
حاوی عناصر زیر بوده و با فاصله از یکدیگر جدا شده‌اند:
.PP
.PD 0
.TP
.PD
توصیف‌کننده فایل (File descriptor)
توصیف‌کننده فایل در حال استفاده برای اتصال\&. برای اتصال‌های عادی ورودی (\fBI\fP) و
خروجی (\fBO\fP)، این توصیف‌کننده می‌تواند با سازوکارهای معمول پوسته خوانده و نوشته شود\&. با
این حال، تنها باید با `\fBztcp \-c\fP\&' بسته شود\&.
.TP
نوع اتصال (Connection type)
حرفی که نحوه ایجاد نشست را نشان می‌دهد:
.RS
.PP
.PD 0
.TP
.PD
\fBZ\fP
نشستی که با دستور \fBzftp\fP ایجاد شده است\&.
.TP
\fBL\fP
اتصالی که برای گوش فرا دادن (listening) با `\fBztcp \-l\fP\&' باز شده است\&.
.TP
\fBI\fP
یک اتصال ورودی که با `\fBztcp \-a\fP\&' پذیرفته شده است\&.
.TP
\fBO\fP
یک اتصال خروجی که با `\fBztcp\fP \fIhost\fP \fI\&.\&.\&.\fP\&' ایجاد شده است\&.
.PP
.RE
.TP
میزبان محلی (The local host)
معمولاً روی یک آدرس IP سراسر صفر تنظیم می‌شود زیرا آدرس لوکال‌هاست اهمیتی ندارد\&.
.TP
پورت محلی (The local port)
احتمالاً صفر خواهد بود مگر آنکه اتصال برای گوش دادن باشد\&.
.TP
میزبان دوردست (The remote host)
نام دامنه کاملاً واجد شرایط (FQDN) طرف مقابل در صورت در دسترس بودن، وگرنه یک آدرس IP است\&. برای
نشستی که جهت شنود باز شده است، یک آدرس IP کاملاً صفر خواهد بود\&.
.TP
پورت دوردست (The remote port)
برای اتصالی که جهت شنود باز شده باشد برابر صفر است\&.
.RE
.PP
.SS "اتصال‌های خروجی (Outbound Connections)"
.PP
.PD 0
.TP
.PD
\fBztcp\fP [ \fB\-v\fP ] [ \fB\-d\fP \fIfd\fP ] \fIhost\fP [ \fIport\fP ]
یک اتصال TCP جدید به \fIhost\fP باز می‌کند\&. اگر \fIport\fP ذکر نشود، پیش‌فرض پورت 23 خواهد
بود\&. اتصال به جدول نشست‌ها اضافه شده و پارامتر پوسته‌ای \fBREPLY\fP روی توصیف‌کننده فایل
مرتبط با آن اتصال تنظیم می‌شود\&.
.RS
.PP
اگر \fB\-d\fP تعیین شود، آرگومان آن به عنوان توصیف‌کننده فایل مقصد برای اتصال در نظر گرفته می‌شود\&.
.PP
برای دریافت خروجی با جزئیات بیشتر، از \fB\-v\fP استفاده کنید\&.
.RE
.PP
.SS "اتصال‌های ورودی (Inbound Connections)"
.PP
.PD 0
.TP
.PD
\fBztcp\fP \fB\-l\fP [ \fB\-v\fP ] [ \fB\-d\fP \fIfd\fP ] \fIport\fP
دستور \fBztcp \-l\fP یک سوکت شنونده روی پورت TCP به شماره \fIport\fP باز می‌کند\&. این سوکت به
جدول نشست‌ها افزوده شده و پارامتر پوسته‌ای \fBREPLY\fP روی توصیف‌کننده فایل مرتبط با آن شنونده
تنظیم خواهد شد\&.
.RS
.PP
اگر \fB\-d\fP تعیین شود، آرگومان آن به عنوان توصیف‌کننده فایل هدف برای اتصال تلقی می‌گردد\&.
.PP
برای خروجی مفصل‌تر، از \fB\-v\fP استفاده کنید\&.
.RE
.TP
\fBztcp\fP \fB\-a\fP [ \fB\-tv\fP ] [ \fB\-d\fP \fItargetfd\fP ] \fIlistenfd\fP
دستور \fBztcp \-a\fP یک اتصال ورودی به پورت مرتبط با \fIlistenfd\fP را می‌پذیرد\&.
اتصال به جدول نشست‌ها اضافه شده و پارامتر پوسته‌ای \fBREPLY\fP روی توصیف‌کننده فایل متناظر
با اتصال ورودی تنظیم می‌شود\&.
.RS
.PP
اگر \fB\-d\fP مشخص شود، آرگومان آن به عنوان توصیف‌کننده فایل هدف برای اتصال لحاظ خواهد شد\&.
.PP
اگر \fB\-t\fP مشخص شده باشد، در صورتی که اتصال ورودی در انتظار نباشد، \fBztcp\fP بلافاصله
بازمی‌گردد\&. در غیر این صورت منتظر یک اتصال خواهد ماند\&.
.PP
برای دریافت خروجی با جزئیات بیشتر، از \fB\-v\fP استفاده کنید\&.
.RE
.PP
.SS "بستن اتصال‌ها (Closing Connections)"
.PP
.PD 0
.TP
.PD 0
\fBztcp\fP \fB\-cf\fP [ \fB\-v\fP ] [ \fIfd\fP ]
.TP
.PD
\fBztcp\fP \fB\-c\fP [ \fB\-v\fP ] [ \fIfd\fP ]
دستور \fBztcp \-c\fP سوکت مرتبط با \fIfd\fP را می‌بندد\&. سوکت از جدول نشست‌ها حذف خواهد شد\&. اگر
\fIfd\fP تعیین نشود، \fBztcp\fP تمام سوکت‌های موجود در جدول نشست‌ها را می‌بندد\&.
.RS
.PP
به طور معمول، سوکت‌های ثبت‌شده توسط zftp (راهنمای
\fIzshmodules\fP(1)
را ببینید) را نمی‌توان به این شیوه بست\&. برای اجبار به بستن چنین سوکتی، از \fB\-f\fP استفاده کنید\&.
.PP
برای دریافت خروجی با جزئیات بیشتر، از \fB\-v\fP استفاده کنید\&.
.RE
.PP
.SS "مثال (Example)"
نحوه برقراری یک اتصال TCP میان دو نمونه از zsh در زیر آمده است\&. باید یک پورت استفاده‌نشده را انتخاب
کنیم؛ در اینجا از پورت تصادفی ۵۱۲۳ استفاده می‌کنیم\&.
.PP
روی \fBhost1\fP:
.RS
.nf
\fBzmodload zsh/net/tcp
ztcp \-l 5123
listenfd=$REPLY
ztcp \-a $listenfd
fd=$REPLY\fP
.fi
.RE
دستور یکی مانده به آخر تا زمان برقراری یک اتصال ورودی متوقف (مسدود) می‌ماند\&.
.PP
اکنون اتصالی از سمت \fBhost2\fP (که البته می‌تواند همان رایانه باشد) برقرار کنید:
.RS
.nf
\fBzmodload zsh/net/tcp
ztcp host1 5123
fd=$REPLY\fP
.fi
.RE
.PP
اکنون در هر میزبان، \fB$fd\fP حاوی یک توصیف‌کننده فایل برای گفت‌وگو با طرف مقابل است\&. به عنوان مثال،
روی \fBhost1\fP:
.RS
.nf
\fBprint This is a message >&$fd\fP
.fi
.RE
و روی \fBhost2\fP:
.RS
.nf
\fBread \-r line <&$fd; print \-r \- $line\fP
.fi
.RE
عبارت `\fBThis is a message\fP\&' را چاپ می‌کند\&.
.PP
برای پاک‌سازی نشست‌ها، روی \fBhost1\fP:
.RS
.nf
\fBztcp \-c $listenfd
ztcp \-c $fd\fP
.fi
.RE
و روی \fBhost2\fP:
.RS
.nf
\fBztcp \-c $fd\fP
.fi
.RE
.SH "ماژول ZSH/TERMCAP (THE ZSH/TERMCAP MODULE)"
.\" Yodl file: Zsh/mod_termcap.yo

ماژول \fBzsh/termcap\fP یک دستور توکار در دسترس قرار می‌دهد:
.PP
.PD 0
.TP
.PD
\fBechotc\fP \fIcap\fP [ \fIarg\fP \&.\&.\&. ]
مقدار termcap متناظر با قابلیت \fIcap\fP را همراه با آرگومان‌های اختیاری خروجی می‌دهد\&.
.PP
ماژول \fBzsh/termcap\fP یک پارامتر را در دسترس قرار می‌دهد:
.PP
.PD 0
.TP
.PD
\fBtermcap\fP
یک آرایه انجمنی که کدهای قابلیت‌های termcap را به مقادیر آن‌ها نگاشت می‌کند\&.
.SH "ماژول ZSH/TERMINFO (THE ZSH/TERMINFO MODULE)"
.\" Yodl file: Zsh/mod_terminfo.yo

ماژول \fBzsh/terminfo\fP یک دستور توکار در دسترس قرار می‌دهد:
.PP
.PD 0
.TP
.PD
\fBechoti\fP \fIcap\fP [ \fIarg\fP ]
مقدار terminfo متناظر با قابلیت \fIcap\fP را، که در صورت کاربرد با \fIarg\fP مقداردهی شده، خروجی می‌دهد\&.
.PP
ماژول \fBzsh/terminfo\fP یک پارامتر را در دسترس قرار می‌دهد:
.PP
.PD 0
.TP
.PD
\fBterminfo\fP
یک آرایه انجمنی که نام قابلیت‌های terminfo را به مقادیر آن‌ها نگاشت می‌کند\&.
.SH "ماژول ZSH/WATCH (THE ZSH/WATCH MODULE)"
.\" Yodl file: Zsh/mod_watch.yo

ماژول \fBzsh/watch\fP می‌تواند برای گزارش ورود یا خروج کاربران خاص به کار رود\&. این قابلیت از
طریق پارامترهای زیر کنترل می‌شود:
.PP
.PD 0
.TP
.PD
\fBLOGCHECK\fP
بازه زمانی برحسب ثانیه میان بررسی‌های مربوط به فعالیت ورود/خروج با استفاده از پارامتر \fBwatch\fP\&.
.TP
\fBwatch\fP <S> <Z> (\fBWATCH\fP <S>)
یک آرایه (فهرست جداشده با دونقطه) از رویدادهای ورود/خروج که باید گزارش شوند\&.
.RS
.PP
اگر حاوی کلمه منفرد `\fBall\fP\&' باشد، تمام رویدادهای ورود/خروج گزارش می‌شوند\&. اگر حاوی کلمه منفرد
`\fBnotme\fP\&' باشد، تمام رویدادها مانند `\fBall\fP\&' به استثنای \fB$USERNAME\fP گزارش خواهند شد\&.
.PP
یک مدخل در این فهرست می‌تواند شامل یک نام کاربری، یک `\fB@\fP\&' و به دنبال آن نام میزبان راه دور،
و یک `\fB%\fP\&' و به دنبال آن یک خط ترمینال (tty) باشد\&. هر یک از این‌ها می‌تواند یک الگو باشد
(هنگام تخصیص به \fBwatch\fP حتماً آن را کوت کنید تا بلافاصله دست به تولید نام فایل نزند)؛ تنظیمات
گزینه \fBEXTENDED_GLOB\fP رعایت می‌شود\&. هر کدام یا همه این مؤلفه‌ها می‌توانند در یک مدخل حضور
داشته باشند؛ اگر یک رویداد ورود/خروج با همه آن‌ها مطابقت داشته باشد، گزارش خواهد شد\&.
.PP
برای نمونه با تنظیم گزینه \fBEXTENDED_GLOB\fP، دستور زیر:
.PP
.RS
.nf
\fBwatch=(\&'^(pws|barts)')\fP
.fi
.RE
.PP
باعث گزارش فعالیت‌های مربوط به هر کاربری غیر از \fBpws\fP یا \fBbarts\fP می‌شود\&.
.RE
.TP
\fBWATCHFMT\fP
قالب گزارش‌های ورود/خروج در صورت تنظیم بودن پارامتر \fBwatch\fP\&. پیش‌فرض
`\fB%n has %a %l from %m\fP\&' است\&.
دنباله‌های فرار زیر را می‌شناسد:
.RS
.PP
.PD 0
.TP
.PD
\fB%n\fP
نام کاربری که وارد یا خارج شده است\&.
.TP
\fB%a\fP
عمل مشاهده‌شده، یعنی "logged on" یا "logged off"\&.
.TP
\fB%l\fP
خطی (tty) که کاربر روی آن لاگین کرده است\&.
.TP
\fB%M\fP
نام کامل میزبان راه دور\&.
.TP
\fB%m\fP
نام میزبان تا اولین `\fB\&.\fP\&'\&. اگر فقط آدرس IP در دسترس باشد یا فیلد utmp حاوی نام صفحه نمایش
X\-windows باشد، کل نام چاپ می‌شود\&.
.RS
.PP
\fINOTE:\fP
دنباله‌های `\fB%m\fP\&' و `\fB%M\fP' تنها در صورتی کار خواهند کرد که فیلد نام میزبان در utmp رایانه شما
وجود داشته باشد\&. در غیر این صورت به عنوان رشته‌های معمولی با آن‌ها رفتار می‌شود\&.
.RE
.TP
\fB%F{\fP\fIcolor\fP\fB}\fP (\fB%f\fP)
آغاز (پایان) استفاده از رنگ پیش‌زمینه متفاوت\&.
.TP
\fB%K{\fP\fIcolor\fP\fB}\fP (\fB%k\fP)
آغاز (پایان) استفاده از رنگ پس‌زمینه متفاوت\&.
.TP
\fB%S\fP (\fB%s\fP)
آغاز (پایان) حالت برجسته (standout)\&.
.TP
\fB%U\fP (\fB%u\fP)
آغاز (پایان) حالت زیرخط‌دار (underline)\&.
.TP
\fB%B\fP (\fB%b\fP)
آغاز (پایان) حالت پررنگ (bold)\&.
.TP
.PD 0
\fB%t\fP
.TP
.PD
\fB%@\fP
زمان در قالب ۱۲ ساعته همراه با am/pm\&.
.TP
\fB%T\fP
زمان در قالب ۲۴ ساعته\&.
.TP
\fB%w\fP
تاریخ در قالب `\fIday\fP\fB\-\fP\fIdd\fP\&'\&.
.TP
\fB%W\fP
تاریخ در قالب `\fImm\fP\fB/\fP\fIdd\fP\fB/\fP\fIyy\fP\&'\&.
.TP
\fB%D\fP
تاریخ در قالب `\fIyy\fP\fB\-\fP\fImm\fP\fB\-\fP\fIdd\fP\&'\&.
.TP
\fB%D{\fP\fIstring\fP\fB}\fP
تاریخ قالب‌بندی‌شده به صورت \fIstring\fP با استفاده از تابع \fBstrftime\fP، همراه با افزونه‌های zsh
همان‌طور که در EXPANSION OF PROMPT SEQUENCES در \fIzshmisc\fP(1) شرح داده شده است\&.
.TP
\fB%(\fP\fIx\fP\fB:\fP\fItrue\-text\fP\fB:\fP\fIfalse\-text\fP\fB)\fP
یک عبارت سه‌گانه (ternary) را مشخص می‌کند\&. نویسه پس از \fIx\fP دلخواه است؛ از همان نویسه برای جدا کردن
متن برای نتیجه «درست» از نتیجه «نادرست» استفاده می‌شود\&. هم جداکننده و هم پرانتز راست را می‌توان با
یک بک‌اسلش اسکیپ کرد\&. عبارات سه‌گانه را می‌توان تو در تو قرار داد\&.
.RS
.PP
نویسه آزمون \fIx\fP می‌تواند یکی از `\fBl\fP\&'، `\fBn\fP'، `\fBm\fP' یا `\fBM\fP\&' باشد، که
در صورت بازگرداندن مقداری غیرخالی توسط دنباله فرار متناظر، نتیجه «درست» را نشان می‌دهند؛ یا می‌تواند
`\fBa\fP\&' باشد، که در صورت ورود کاربر تحت نظر نتیجه «درست»، و در صورت خروج او «نادرست» را نشان می‌دهد\&.
نویسه‌های دیگر نه درست و نه نادرست ارزیابی می‌شوند؛ کل عبارت در این حالت حذف خواهد شد\&.
.PP
اگر نتیجه «درست» باشد، \fItrue\-text\fP بر اساس قواعد فوق قالب‌بندی شده و چاپ می‌شود، و از
\fIfalse\-text\fP صرف‌نظر می‌گردد\&. اگر «نادرست» باشد، از \fItrue\-text\fP صرف‌نظر شده و
\fIfalse\-text\fP قالب‌بندی و چاپ می‌شود\&. هر یک یا هر دوی شاخه‌ها می‌توانند خالی باشند، اما هر دو
جداکننده باید در هر حال حضور داشته باشند\&.
.RE
.RE
.PP
علاوه بر این، ماژول \fBzsh/watch\fP یک دستور توکار در دسترس قرار می‌دهد:
.PP
.PD 0
.TP
.PD
\fBlog\fP
تمام کاربرانی را که در حال حاضر وارد سیستم شده‌اند و تحت تأثیر تنظیمات فعلی پارامتر \fBwatch\fP قرار
دارند فهرست می‌کند\&.
.SH "ماژول ZSH/ZFTP (THE ZSH/ZFTP MODULE)"
.\" Yodl file: Zsh/mod_zftp.yo

ماژول \fBzsh/zftp\fP یک دستور توکار را در دسترس قرار می‌دهد:
.PP
.PD 0
.TP
.PD
\fBzftp\fP \fIsubcommand\fP [ \fIargs\fP ]
ماژول \fBzsh/zftp\fP یک کلاینت برای پروتکل انتقال فایل (FTP) است\&. این ماژول به صورت یک دستور توکار
پیاده‌سازی شده است تا امکان استفاده کامل از ویرایش خط فرمان پوسته، ورودی/خروجی فایل و سازوکارهای
کنترل شغل فراهم شود\&. اغلب کاربران از طریق توابع پوسته که رابط قدرتمندتری ارائه می‌دهند به آن دسترسی
دارند؛ مجموعه‌ای از این توابع همراه با توزیع \fBzsh\fP ارائه شده و در
\fIzshzftpsys\fP(1)
شرح داده شده است\&. با این حال، دستور \fBzftp\fP به خودی خود کاملاً قابل استفاده است\&.
.RS
.PP
تمام دستورها از نام دستور \fBzftp\fP و به دنبال آن نام یک زیردستور تشکیل شده‌اند\&. این زیردستورها در زیر
فهرست شده‌اند\&. وضعیت بازگشتی هر زیردستور منعکس‌کننده موفقیت یا شکست عملیات از راه دور است\&. برای اطلاعات
بیشتر در مورد نحوه چاپ پاسخ‌های سرور، به توضیحات متغیر \fBZFTP_VERBOSE\fP مراجعه کنید\&.
.RE
.PP
.SS "زیردستورها (Subcommands)"
.PP
.PD 0
.TP
.PD
\fBopen\fP \fIhost\fP[\fB:\fP\fIport\fP] [ \fIuser\fP [ \fIpassword\fP [ \fIaccount\fP ] ] ]
یک نشست جدید FTP به \fIhost\fP باز می‌کند، که می‌تواند نام یک میزبان متصل به TCP/IP یا یک شماره IP با
نگارش نقطه‌دار استاندارد باشد\&. اگر آرگومان به صورت \fIhost\fP\fB:\fP\fIport\fP باشد، اتصالی به پورت TCP
مشخص‌شده با \fIport\fP به جای پورت استاندارد FTP (یعنی ۲۱) باز می‌شود\&. این می‌تواند نام یک سرویس TCP یا
یک عدد باشد: برای اطلاعات بیشتر توضیحات \fBZFTP_PORT\fP در زیر را ببینید\&.
.RS
.PP
اگر از آدرس‌های IPv6 در قالب دونقطه استفاده می‌شود، برای تمایز آن از \fIport\fP باید \fIhost\fP را درون
کروشه‌های کوت‌شده قرار داد، برای مثال \fB\&'[fe80::203:baff:fe02:8b56]'\fP\&. برای هماهنگی و یکدستی، این
نحو برای تمام قالب‌های \fIhost\fP مجاز است\&.
.PP
باقیمانده آرگومان‌ها به زیردستور \fBlogin\fP منتقل می‌شوند\&. توجه داشته باشید که اگر آرگومانی فراتر از
\fIhost\fP ارائه نشود، \fBopen\fP به صورت خودکار \fBlogin\fP را فراخوانی \fIنخواهد کرد\fP\&. اگر هیچ
آرگومانی ارائه نشود، \fBopen\fP از پارامترهای تنظیم‌شده با زیردستور \fBparams\fP استفاده خواهد کرد\&.
.PP
پس از یک اتصال باز موفقیت‌آمیز، متغیرهای پوسته‌ای \fBZFTP_HOST\fP، \fBZFTP_PORT\fP، \fBZFTP_IP\fP و
\fBZFTP_SYSTEM\fP در دسترس خواهند بود؛ بخش `Variables\&' در زیر را ببینید\&.
.RE
.TP
.PD 0
\fBlogin\fP [ \fIname\fP [ \fIpassword\fP [ \fIaccount\fP ] ] ]
.TP
.PD
\fBuser\fP [ \fIname\fP [ \fIpassword\fP [ \fIaccount\fP ] ] ]
کاربر با نام \fIname\fP را با پارامترهای \fIpassword\fP و \fIaccount\fP لاگین می‌کند\&.
هر یک از این پارامترها را می‌توان حذف کرد، و در صورت نیاز از ورودی استاندارد خوانده خواهند شد (\fIname\fP
همواره مورد نیاز است)\&. اگر ورودی استاندارد یک ترمینال باشد، اعلانی برای هر کدام در خروجی خطای استاندارد
چاپ می‌شود و \fIpassword\fP پژواک نخواهد شد\&. اگر هر یک از پارامترها استفاده نشوند، یک پیام هشدار چاپ می‌شود\&.
.RS
.PP
پس از ورود موفق، متغیرهای پوسته‌ای \fBZFTP_USER\fP، \fBZFTP_ACCOUNT\fP و \fBZFTP_PWD\fP در دسترس
خواهند بود؛ بخش `Variables\&' در زیر را ببینید\&.
.PP
این دستور می‌تواند زمانی که کاربری پیش‌تر لاگین کرده است مجدداً صادر شود، که در این حالت سرور ابتدا برای یک
کاربر جدید مقداردهی اولیه خواهد شد\&.
.RE
.TP
.PD 0
\fBparams\fP [ \fIhost\fP [ \fIuser\fP [ \fIpassword\fP [ \fIaccount\fP ] ] ] ]
.TP
.PD
\fBparams\fP \fB\-\fP
پارامترهای داده‌شده را برای یک دستور \fBopen\fP بعدی بدون آرگومان ذخیره می‌کند\&. تنها پارامترهایی که روی
خط فرمان داده شده‌اند به خاطر سپرده خواهند شد\&. اگر هیچ آرگومانی داده نشود، پارامترهای در حال حاضر
تنظیم‌شده چاپ می‌شوند، هرچند گذرواژه به صورت خطی از ستاره‌ها نمایش داده خواهد شد؛ وضعیت بازگشتی در صورت
عدم تنظیم هیچ پارامتری یک، و در غیر این صورت صفر است\&.
.RS
.PP
هر یک از پارامترها را می‌توان به صورت یک `\fB?\fP\&' مشخص کرد، که برای محافظت در برابر بسط پوسته ممکن
است نیاز به کوت کردن داشته باشد\&. در این حالت، پارامتر مربوطه از stdin مشابه زیردستور \fBlogin\fP
خوانده می‌شود، از جمله مدیریت ویژه \fIpassword\fP\&. اگر به دنبال `\fB?\fP\&' رشته‌ای بیاید، از آن به جای
پیام پیش‌فرض به عنوان اعلان برای خواندن پارامتر استفاده می‌شود (هرگونه نشانه‌گذاری و فاصله خالی لازم باید
در انتهای اعلان گنجانده شود)\&. تنها نویسه اول پارامتر را می‌توان با یک `\fB\e\fP\&' کوت کرد؛ بنابراین
یک آرگومان \fB"\e\e$word"\fP تضمین می‌کند که رشته حاصل از پارامتر پوسته \fB$word\fP چه با `\fB?\fP\&'
شروع شود یا نه، به صورت تحت‌اللفظی پردازش خواهد شد\&.
.PP
اگر به جای آن یک `\fB\-\fP\&' منفرد داده شود، پارامترهای موجود (در صورت وجود) حذف می‌شوند\&. در آن حالت،
فراخوانی \fBopen\fP بدون هیچ آرگومانی باعث خطا خواهد شد\&.
.PP
فهرست پارامترها پس از یک \fBclose\fP حذف نمی‌شود، با این حال در صورت تخلیه (unload) ماژول \fBzsh/zftp\fP
حذف خواهد شد\&.
.PP
برای نمونه:
.PP
.RS
.nf
\fBzftp params ftp\&.elsewhere\&.xx juser \&'?Password for juser: '\fP
.fi
.RE
.PP
میزبان \fBftp\&.elsewhere\&.xx\fP و کاربر \fBjuser\fP را ذخیره کرده و سپس با اعلان داده‌شده از کاربر
رمز عبور متناظر را درخواست می‌کند\&.
.RE
.TP
\fBtest\fP
اتصال را بررسی می‌کند؛ اگر سرور گزارش داده باشد که اتصال را بسته است (شاید به دلیل پایان زمان‌انتظار)،
وضعیت 2 بازمی‌گرداند؛ اگر در هر حال هیچ اتصالی باز نبوده باشد، وضعیت 1 برمی‌گرداند؛ در غیر این صورت
وضعیت 0 را بازمی‌گرداند\&. زیردستور \fBtest\fP به جز پیام‌های چاپ‌شده توسط سازوکار \fB$ZFTP_VERBOSE\fP،
یا پیام‌های خطا در صورت بسته شدن اتصال، در سکوت اجرا می‌شود\&. این آزمایش هیچ بار ترافیک شبکه‌ای به همراه ندارد\&.
.RS
.PP
این آزمون تنها در سیستم‌هایی که دارای فراخوانی‌های سیستمی \fBselect(2)\fP یا \fBpoll(2)\fP هستند پشتیبانی
می‌شود؛ در غیر این صورت پیام `\fBnot supported on this system\fP\&' چاپ می‌شود\&.
.PP
زیردستور \fBtest\fP به صورت خودکار در آغاز هر زیردستور دیگری برای نشست فعلی در زمان باز بودن اتصال فراخوانی خواهد شد\&.
.RE
.TP
\fBcd\fP \fIdirectory\fP
دایرکتوری راه دور را به \fIdirectory\fP تغییر می‌دهد\&. همچنین متغیر پوسته‌ای \fBZFTP_PWD\fP را تغییر می‌دهد\&.
.TP
\fBcdup\fP
دایرکتوری راه دور را به یک سطح بالاتر در درخت دایرکتوری تغییر می‌دهد\&. توجه داشته باشید که دستور
\fBcd \&.\&.\fP روی سیستم‌های غیر یونیکس نیز به درستی کار خواهد کرد\&.
.TP
\fBdir\fP [ \fIarg\fP \&.\&.\&. ]
یک فهرست (مفصل و باجزئیات) از دایرکتوری راه دور ارائه می‌دهد\&. آرگومان‌های \fIarg\fP مستقیماً به سرور
ارسال می‌شوند\&. رفتار دستور وابسته به پیاده‌سازی است، اما یک سرور یونیکس معمولاً آرگومان‌های \fIarg\fP را
به عنوان آرگومان‌های دستور \fBls\fP تفسیر می‌کند و بدون هیچ آرگومانی نتیجه `\fBls \-l\fP\&' را برمی‌گرداند\&.
فهرست دایرکتوری در خروجی استاندارد نمایش داده می‌شود\&.
.TP
\fBls\fP [ \fIarg\fP \&.\&.\&. ]
فهرستی (خلاصه) از دایرکتوری راه دور ارائه می‌دهد\&. بدون \fIarg\fP، فهرستی خام از فایل‌های دایرکتوری را
به صورت یک فایل در هر خط تولید می‌کند\&. در غیر این صورت، بسته به تغییرات جزئی پیاده‌سازی سرور، رفتاری
مشابه با \fBdir\fP دارد\&.
.TP
\fBtype\fP [ \fItype\fP ]
نوع انتقال داده را به \fItype\fP تغییر می‌دهد، یا در صورت عدم حضور \fItype\fP نوع فعلی را چاپ می‌کند\&.
مقادیر مجاز عبارتند از `\fBA\fP\&' (ASCII)، `\fBI\fP\&' (Image، یعنی باینری) یا `\fBB\fP' (مترادفی برای `\fBI\fP')\&.
.RS
.PP
پیش‌فرض FTP برای انتقال، ASCII است\&. با این حال اگر \fBzftp\fP تشخیص دهد که میزبان راه دور یک ماشین یونیکس
با بایت‌های ۸ بیتی است، هنگام \fBopen\fP به طور خودکار به استفاده از باینری تغییر وضعیت می‌دهد\&. این مورد
می‌تواند بعداً لغو شود\&.
.PP
نوع انتقال تنها زمانی به میزبان راه دور فرستاده می‌شود که اتصال داده برقرار گردد؛ این دستور بار ترافیک شبکه ندارد\&.
.RE
.TP
\fBascii\fP
معادل \fBtype A\fP\&.
.TP
\fBbinary\fP
معادل \fBtype I\fP\&.
.TP
\fBmode\fP [ \fBS\fP | \fBB\fP ]
نوع حالت انتقال را به جریانی (\fBS\fP) یا بلوکی (\fBB\fP) تنظیم می‌کند\&. حالت جریانی (Stream) پیش‌فرض
است؛ حالت بلوکی (Block) پشتیبانی گسترده‌ای ندارد\&.
.TP
.PD 0
\fBremote\fP \fIfile\fP \&.\&.\&.
.TP
.PD
\fBlocal\fP [ \fIfile\fP \&.\&.\&. ]
اندازه و آخرین زمان تغییر فایل‌های راه دور یا محلی را چاپ می‌کند\&. اگر بیش از یک مورد در فهرست وجود
داشته باشد، ابتدا نام فایل چاپ می‌شود\&. عدد اول اندازه فایل، و عدد دوم آخرین زمان تغییر فایل در قالب
\fBCCYYMMDDhhmmSS\fP متشکل از سال، ماه، روز، ساعت، دقیقه و ثانیه در GMT است\&. توجه داشته باشید که این
قالب، از جمله طول آن، تضمین‌شده است به طوری که رشته‌های زمانی را می‌توان مستقیماً با عملگرهای \fB<\fP و
\fB>\fP از دستور توکار \fB[[\fP مقایسه کرد، حتی اگر طولانی‌تر از آن باشند که به صورت عدد صحیح نمایش یابند\&.
.RS
.PP
همه سرورها از دستورات مربوط به بازیابی این اطلاعات پشتیبانی نمی‌کنند\&. در آن حالت، دستور \fBremote\fP
چیزی چاپ نمی‌کند و وضعیت 2 را بازمی‌گرداند، در مقایسه با وضعیت 1 برای فایلی که یافت نشده است\&.
.PP
دستور \fBlocal\fP (اما نه \fBremote\fP) می‌تواند بدون آرگومان استفاده شود، که در این حالت اطلاعات از
بررسی توصیف‌کننده فایل صفر حاصل می‌شود\&. این همان فایلی است که توسط یک دستور \fBput\fP بدون تغییرمسیر
بیشتر دیده می‌شود\&.
.RE
.TP
\fBget\fP \fIfile\fP \&.\&.\&.
تمام فایل‌های \fIfile\fP را از سرور دریافت کرده، آن‌ها را الحاق نموده و به خروجی استاندارد ارسال می‌کند\&.
.TP
\fBput\fP \fIfile\fP \&.\&.\&.
به ازای هر \fIfile\fP، فایلی را از ورودی استاندارد خوانده و آن را با نام داده‌شده به میزبان راه دور ارسال می‌کند\&.
.TP
\fBappend\fP \fIfile\fP \&.\&.\&.
مشابه \fBput\fP، اما اگر \fIfile\fP راه دور از قبل وجود داشته باشد، داده‌ها به جای بازنویسی، به انتهای آن
الحاق می‌شوند\&.
.TP
.PD 0
\fBgetat\fP \fIfile\fP \fIpoint\fP
.TP
.PD 0
\fBputat\fP \fIfile\fP \fIpoint\fP
.TP
.PD
\fBappendat\fP \fIfile\fP \fIpoint\fP
نسخه‌هایی از \fBget\fP، \fBput\fP و \fBappend\fP که انتقال را از \fIpoint\fP داده‌شده در فایل راه دور
آغاز می‌کنند\&. این ویژگی برای افزودن به یک فایل محلی ناقص مفید است\&. با این حال توجه داشته باشید که
این قابلیت به طور سراسری توسط سرورها پشتیبانی نمی‌شود (و کاملاً مطابق رفتار تعیین‌شده در استاندارد نیست)\&.
.TP
\fBdelete\fP \fIfile\fP \&.\&.\&.
فهرست فایل‌ها را در سرور حذف می‌کند\&.
.TP
\fBmkdir\fP \fIdirectory\fP
یک دایرکتوری جدید \fIdirectory\fP در سرور ایجاد می‌کند\&.
.TP
\fBrmdir\fP \fIdirectory\fP
دایرکتوری \fIdirectory\fP را در سرور حذف می‌کند\&.
.TP
\fBrename\fP \fIold\-name\fP \fInew\-name\fP
نام فایل \fIold\-name\fP را به \fInew\-name\fP در سرور تغییر می‌دهد\&.
.TP
\fBsite\fP \fIarg\fP \&.\&.\&.
دستوری مختص میزبان را به سرور ارسال می‌کند\&. احتمالاً تنها در صورتی که سرور استفاده از آن را دستور دهد
به آن نیاز خواهید داشت\&.
.TP
\fBquote\fP \fIarg\fP \&.\&.\&.
دنباله دستورات خام FTP را به سرور می‌فرستد\&. پیش از این کار باید با مجموعه دستورات FTP همان‌طور که در
RFC959 تعریف شده است آشنا باشید\&. دستورات مفید ممکن است شامل \fBSTAT\fP و \fBHELP\fP باشند\&. همچنین به
سازوکار بازگرداندن پیام‌ها همان‌طور که برای متغیر \fBZFTP_VERBOSE\fP در زیر شرح داده شده توجه داشته باشید،
به ویژه اینکه تمام پیام‌های حاصل از اتصال کنترل به خروجی خطای استاندارد فرستاده می‌شوند\&.
.TP
.PD 0
\fBclose\fP
.TP
.PD
\fBquit\fP
اتصال داده جاری را می‌بندد\&. این کار پارامترهای پوسته‌ای \fBZFTP_HOST\fP، \fBZFTP_PORT\fP،
\fBZFTP_IP\fP، \fBZFTP_SYSTEM\fP، \fBZFTP_USER\fP، \fBZFTP_ACCOUNT\fP، \fBZFTP_PWD\fP،
\fBZFTP_TYPE\fP و \fBZFTP_MODE\fP را لغو مقداردهی (unset) می‌کند\&.
.TP
\fBsession\fP [ \fIsessname\fP ]
امکان استفاده همزمان از چندین نشست FTP را فراهم می‌سازد\&. نام نشست یک رشته دلخواه از نویسه‌هاست؛
نشست پیش‌فرض `\fBdefault\fP\&' نام دارد\&. اگر این دستور بدون آرگومان فراخوانی شود، تمام نشست‌های فعلی را
فهرست می‌کند؛ با یک آرگومان، به نشست موجود با نام \fIsessname\fP تغییر وضعیت می‌دهد، یا یک نشست جدید با آن
نام ایجاد می‌کند\&.
.RS
.PP
هر نشست وضعیت اتصال، مجموعه پارامترهای پوسته‌ای مختص اتصال (همان مجموعه‌ای که با بسته شدن اتصال لغو
می‌شوند، همان‌طور که در توضیحات \fBclose\fP آمده است)، و هرگونه پارامتر کاربری تعیین‌شده با زیردستور
\fBparams\fP را به خاطر می‌سپارد\&. تغییر وضعیت به یک نشست قبلی آن مقادیر را بازیابی می‌کند؛ جابه‌جایی
به یک نشست جدید آن‌ها را به همان شیوه‌ای مقداردهی اولیه می‌کند که گویی \fBzftp\fP به تازگی بارگذاری شده
است\&. نام نشست فعلی توسط پارامتر \fBZFTP_SESSION\fP مشخص می‌شود\&.
.RE
.TP
\fBrmsession\fP [ \fIsessname\fP ]
یک نشست را حذف می‌کند؛ اگر نامی داده نشود، نشست فعلی حذف می‌شود\&. اگر نشست جاری حذف شود، قدیمی‌ترین
نشست موجود به عنوان نشست جاری جدید تعیین می‌گردد، در غیر این صورت نشست فعلی تغییری نمی‌کند\&. اگر نشستی
که حذف می‌شود تنها نشست موجود باشد، یک نشست جدید به نام `\fBdefault\fP\&' ایجاد شده و به عنوان نشست جاری
تعیین می‌گردد؛ توجه داشته باشید که این یک نشست جدید است حتی اگر نشستی که حذف می‌شود نیز `\fBdefault\fP\&'
نام داشته باشد\&. توصیه می‌شود در حالی که دستورهای پس‌زمینه که از \fBzftp\fP استفاده می‌کنند هنوز فعال هستند،
نشست‌ها حذف نشوند\&.
.PP
.SS "پارامترها (Parameters)"
پارامترهای پوسته‌ای زیر توسط \fBzftp\fP استفاده می‌شوند\&. در حال حاضر هیچ‌کدام از آن‌ها خاص نیستند\&.
.PP
.PD 0
.TP
.PD
\fBZFTP_TMOUT\fP
عدد صحیح\&. مدت زمان برحسب ثانیه برای انتظار جهت تکمیل یک عملیات شبکه پیش از بازگرداندن خطا\&. اگر هنگام
بارگذاری ماژول این متغیر تنظیم نشده باشد، مقدار پیش‌فرض ۶۰ به آن داده خواهد شد\&. مقدار صفر زمان‌انتظار
را غیرفعال می‌کند\&. اگر زمان‌انتظار در اتصال کنترل رخ دهد، بسته خواهد شد\&. در صورت وقوع مکرر، از مقدار
بزرگ‌تری استفاده کنید\&.
.TP
\fBZFTP_IP\fP
فقط‌خواندنی\&. آدرس IP اتصال فعلی با قالب نقطه‌دار\&.
.TP
\fBZFTP_HOST\fP
فقط‌خواندنی\&. نام میزبان سرور راه دور فعلی\&. اگر میزبان با شماره IP باز شده باشد، \fBZFTP_HOST\fP به جای
آن حاوی شماره IP است؛ این کار بار ناشی از جستجوی نام را حذف می‌کند، زیرا شماره‌های IP بیشتر زمانی به کار
می‌روند که نیم‌سرور در دسترس نباشد\&.
.TP
\fBZFTP_PORT\fP
فقط‌خواندنی\&. شماره پورت TCP راه دور که اتصال به آن باز است (حتی اگر پورت در اصل به عنوان یک سرویس
نام‌گذاری‌شده مشخص شده باشد)\&. معمولاً این مقدار پورت استاندارد FTP، یعنی ۲۱ است\&.
.RS
.PP
در حالت غیرمحتمل که سیستم شما فاقد توابع تبدیل مناسب باشد، این مقدار در ترتیب بایتی شبکه ظاهر می‌شود\&. اگر
سیستم شما little\-endian باشد، پورت شامل دو بایت جابه‌جاشده است و پورت استاندارد به صورت 5376 گزارش خواهد
شد\&. در آن حالت، پورت‌های عددی ارسال‌شده به \fBzftp open\fP نیز باید در این قالب باشند\&.
.RE
.TP
\fBZFTP_SYSTEM\fP
فقط‌خواندنی\&. رشته نوع سیستم بازگردانده‌شده توسط سرور در پاسخ به درخواست FTP \fBSYST\fP\&. جالب‌ترین حالت
رشته‌ای است که با \fB"UNIX Type: L8"\fP آغاز می‌شود، که حداکثر سازگاری را با یک میزبان یونیکس محلی تضمین می‌کند\&.
.TP
\fBZFTP_TYPE\fP
فقط‌خواندنی\&. نوع مورد استفاده برای انتقال داده، یا `\fBA\fP\&' یا `\fBI\fP\&'\&. برای تغییر این مورد از
زیردستور \fBtype\fP استفاده کنید\&.
.TP
\fBZFTP_USER\fP
فقط‌خواندنی\&. نام کاربری که در حال حاضر لاگین کرده است (در صورت وجود)\&.
.TP
\fBZFTP_ACCOUNT\fP
فقط‌خواندنی\&. نام حساب کاربری جاری (در صورت وجود)\&. بیشتر سرورها نیازی به نام حساب ندارند\&.
.TP
\fBZFTP_PWD\fP
فقط‌خواندنی\&. دایرکتوری فعلی روی سرور\&.
.TP
\fBZFTP_CODE\fP
فقط‌خواندنی\&. کد سه‌رقمی آخرین پاسخ FTP از سرور به عنوان یک رشته\&. این مقدار همچنان پس از بسته شدن اتصال
قابل خواندن است و هنگام تغییر نشست جاری تغییر نمی‌کند\&.
.TP
\fBZFTP_REPLY\fP
فقط‌خواندنی\&. آخرین خط از آخرین پاسخ ارسال‌شده توسط سرور\&. این مقدار همچنان پس از بسته شدن اتصال قابل
خواندن است و هنگام تغییر نشست فعلی تغییر نمی‌کند\&.
.TP
\fBZFTP_SESSION\fP
فقط‌خواندنی\&. نام نشست FTP جاری؛ توضیحات زیردستور \fBsession\fP را ببینید\&.
.TP
\fBZFTP_PREFS\fP
رشته‌ای از اولویت‌ها برای تغییر جنبه‌های رفتار \fBzftp\fP\&. هر اولویت یک نویسه منفرد است\&. موارد زیر
تعریف شده‌اند:
.RS
.PP
.PD 0
.TP
.PD
\fBP\fP
حالت غیرفعال (Passive): تلاش می‌کند سرور راه دور را وادار به آغاز انتقال داده‌ها کند\&. این حالت کمی
کارآمدتر از حالت sendport است\&. اگر حرف \fBS\fP بعداً در رشته بیاید، در صورتی که حالت passive در دسترس
نباشد، \fBzftp\fP از حالت sendport استفاده خواهد کرد\&.
.TP
\fBS\fP
ارسال پورت (Sendport): انتقال‌ها را با دستور FTP \fBPORT\fP آغاز می‌کند\&. اگر این نویسه قبل از هر
\fBP\fP در رشته بیاید، هرگز تلاشی برای حالت passive نخواهد شد\&.
.TP
\fBD\fP
حالت ساده (Dumb): تنها از حداقل ممکن دستورات FTP استفاده می‌کند\&. این حالت از تنظیم متغیرهای
\fBZFTP_SYSTEM\fP و \fBZFTP_PWD\fP جلوگیری کرده و به این معنا خواهد بود که تمام اتصالات به صورت پیش‌فرض
به نوع ASCII هستند\&. همچنین اگر سرور اندازه را ارسال نکند ممکن است از تنظیم \fBZFTP_SIZE\fP در طول انتقال
جلوگیری کند (بسیاری از سرورها آن را می‌فرستند)\&.
.PP
اگر \fBZFTP_PREFS\fP در هنگام بارگذاری \fBzftp\fP تنظیم نشده باشد، مقدار پیش‌فرض آن روی `\fBPS\fP\&'
تنظیم خواهد شد، یعنی در صورت امکان از حالت غیرفعال استفاده شود، در غیر این صورت به حالت sendport برگردد\&.
.RE
.TP
\fBZFTP_VERBOSE\fP
رشته‌ای از ارقام بین 0 تا 5 (شامل هر دو)، که مشخص می‌کند کدام پاسخ‌ها از سوی سرور باید چاپ شوند\&. تمام
پاسخ‌ها به خروجی خطای استاندارد فرستاده می‌شوند\&. اگر هر یک از اعداد ۱ تا ۵ در رشته ظاهر شوند، پاسخ‌های
خام از سرور با کدهای پاسخی که با آن رقم شروع می‌شوند در خروجی خطای استاندارد چاپ خواهند شد\&. اولین رقم از
کد پاسخ سه‌رقمی طبق RFC959 به شرح زیر تعریف شده است:
.RS
.PP
.PD 0
.TP
.PD
1\&.
یک پاسخ مقدماتی مثبت (positive preliminary reply)\&.
.TP
2\&.
یک پاسخ تکمیل مثبت (positive completion reply)\&.
.TP
3\&.
یک پاسخ میانی مثبت (positive intermediate reply)\&.
.TP
4\&.
یک پاسخ تکمیل منفی گذرا (transient negative completion reply)\&.
.TP
5\&.
یک پاسخ تکمیل منفی دائمی (permanent negative completion reply)\&.
.PP
باید اشاره کرد که به دلایل نامعلوم، پاسخ «سرویس در دسترس نیست» که باعث پایان اجباری یک اتصال می‌شود، به عنوان
421 یعنی «منفی گذرا» طبقه‌بندی شده است، که تفسیری جالب از کلمه «گذرا» محسوب می‌شود\&.
.PP
کد 0 خاص است: نشان می‌دهد که تمام خطوط به جز آخرین خط از پاسخ‌های چندخطی خوانده‌شده از سرور در قالبی
پردازش‌شده در خروجی خطای استاندارد چاپ خواهند شد\&. طبق عرف، سرورها از این سازوکار برای ارسال اطلاعاتی
جهت خواندن کاربر استفاده می‌کنند\&. کد پاسخ مناسب در صورتی که با همان پاسخ مطابقت داشته باشد اولویت دارد\&.
.PP
اگر \fBZFTP_VERBOSE\fP هنگام بارگذاری \fBzftp\fP تنظیم نشده باشد، روی مقدار پیش‌فرض \fB450\fP تنظیم
خواهد شد، یعنی پیام‌های مخصوص کاربر و تمام خطاها چاپ می‌شوند\&. یک رشته تهی معتبر است و مشخص می‌کند
که هیچ پیامی نباید چاپ شود\&.
.RE
.PP
.SS "توابع (Functions)"
.PP
.PD 0
.TP
.PD
\fBzftp_chpwd\fP
اگر این تابع توسط کاربر تعریف شود، هر بار که دایرکتوری در سرور تغییر کند فراخوانی می‌شود، از جمله هنگامی
که کاربری وارد شده، یا اتصالی بسته شده باشد\&. در حالت آخر، مقدار \fB$ZFTP_PWD\fP لغو مقداردهی خواهد شد؛
در غیر این صورت دایرکتوری جدید را منعکس می‌کند\&.
.TP
\fBzftp_progress\fP
اگر این تابع توسط کاربر تعریف شود، در حین عملیات \fBget\fP، \fBput\fP یا \fBappend\fP هر بار که داده‌های
کافی از میزبان دریافت شود فراخوانی خواهد شد\&. در حین یک عملیات \fBget\fP داده‌ها به خروجی استاندارد فرستاده
می‌شوند، بنابراین حیاتی است که این تابع در خروجی خطای استاندارد یا مستقیماً در ترمینال بنویسد، و \fIنه\fP
در خروجی استاندارد\&.
.RS
.PP
هنگامی که این تابع در حین یک انتقال در جریان فراخوانی می‌شود، پارامترهای پوسته‌ای اضافی زیر تنظیم می‌گردند:
.PP
.PD 0
.TP
.PD
\fBZFTP_FILE\fP
نام فایل راه دور که به یا از آن انتقال داده می‌شود\&.
.TP
\fBZFTP_TRANSFER\fP
حرف \fBG\fP برای یک عملیات \fBget\fP و حرف \fBP\fP برای یک عملیات \fBput\fP\&.
.TP
\fBZFTP_SIZE\fP
اندازه کل فایل کاملی که منتقل می‌شود: همان مقدار اول ارائه‌شده توسط زیردستورات \fBremote\fP و \fBlocal\fP
برای یک فایل معین\&. اگر سرور نتواند این مقدار را برای فایل راه دوری که دریافت می‌شود ارائه دهد، تنظیم
نخواهد شد\&. اگر ورودی از یک لوله (pipe) باشد مقدار ممکن است نادرست بوده و صرفاً با یک بافر پر لوله مطابقت داشته باشد\&.
.TP
\fBZFTP_COUNT\fP
میزان داده‌هایی که تا کنون منتقل شده است؛ عددی بین صفر و \fB$ZFTP_SIZE\fP، در صورتی که تنظیم شده باشد\&.
این عدد همواره در دسترس است\&.
.PP
تابع در ابتدا با تنظیم مناسب \fBZFTP_TRANSFER\fP و تنظیم \fBZFTP_COUNT\fP روی صفر فراخوانی می‌شود\&. پس
از پایان انتقال، تابع یک بار دیگر با \fBZFTP_TRANSFER\fP تنظیم‌شده روی \fBGF\fP یا \fBPF\fP فراخوانی
خواهد شد، در صورتی که بخواهد پاک‌سازی انجام دهد\&. در غیر این صورت هرگز دو بار با همان مقدار \fBZFTP_COUNT\fP
فراخوانی نمی‌شود\&.
.PP
گاهی اوقات نشانگر پیشرفت ممکن است اختلال ایجاد کند\&. این بر عهده کاربر است که تصمیم بگیرد تابع باید
تعریف شود یا خیر و در صورت لزوم از \fBunfunction\fP استفاده کند\&.
.RE
.PP
.SS "مشکلات (Problems)"
.PP
اتصال نمی‌تواند در سمت چپ یک لوله (pipe) باز شود زیرا این کار در یک زیرپوسته اتفاق می‌افتد و اطلاعات فایل
در پوسته اصلی به‌روزرسانی نمی‌شود\&. در مورد تغییرات نوع یا حالت، یا بستن اتصال در یک زیرپوسته، اطلاعات
بازگردانده می‌شوند اما متغیرها تا فراخوانی بعدی به \fBzftp\fP به‌روزرسانی نخواهند شد\&. سایر تغییرات وضعیت
در زیرپوسته‌ها در تغییرات متغیرها منعکس نمی‌شوند (اما در غیر این صورت بی‌ضرر هستند)\&.
.PP
حذف نشست‌ها در حالی که دستور \fBzftp\fP در پس‌زمینه فعال است می‌تواند اثرات غیرمنتظره‌ای داشته باشد، حتی
اگر از نشستی که حذف می‌شود استفاده نکند\&. این به دلیل آن است که تمام زیرپردازش‌های پوسته اطلاعات وضعیت
تمام اتصالات را به اشتراک می‌گذارند، و حذف یک نشست ترتیب آن اطلاعات را تغییر می‌دهد\&.
.PP
در برخی سیستم‌عامل‌ها، اتصال کنترل پس از فراخوانی fork() معتبر نیست، بنابراین عملیات در زیرپوسته‌ها، در
سمت چپ یک خط لوله، یا در پس‌زمینه امکان‌پذیر نیست، در حالی که باید این‌گونه باشد\&. این موضوع احتمالاً
یک باگ در سیستم‌عامل است\&.
.SH "ماژول ZSH/ZLE (THE ZSH/ZLE MODULE)"
.\" Yodl file: Zsh/mod_zle.yo

ماژول \fBzsh/zle\fP شامل ویرایشگر خط فرمان Zsh است\&. راهنمای
\fIzshzle\fP(1)
را ببینید\&.
.SH "ماژول ZSH/ZLEPARAMETER (THE ZSH/ZLEPARAMETER MODULE)"
.\" Yodl file: Zsh/mod_zleparameter.yo

ماژول \fBzsh/zleparameter\fP دو پارامتر ویژه تعریف می‌کند که می‌توانند برای دسترسی به
اطلاعات درونی ویرایشگر خط Zsh به کار روند (راهنمای
\fIzshzle\fP(1)
را ببینید)\&.
.PP
.PD 0
.TP
.PD
\fBkeymaps\fP
این آرایه شامل نام نقشه‌های کلید (keymaps) در حال حاضر تعریف‌شده است\&.
.TP
\fBwidgets\fP
این آرایه انجمنی شامل یک مدخل به ازای هر ویجت است\&. نام ویجت کلید آن است و مقدار آن
اطلاعاتی درباره ویجت ارائه می‌دهد\&. این مقدار یا
رشته `\fBbuiltin\fP\&' برای ویجت‌های توکار است،
یا رشته‌ای به صورت `\fBuser:\fP\fIname\fP\&' برای ویجت‌های تعریف‌شده توسط کاربر است
که در آن \fIname\fP نام تابع پوسته پیاده‌سازی‌کننده ویجت است،
یا رشته‌ای به صورت `\fBcompletion:\fP\fItype\fP\fB:\fP\fIname\fP\&'
برای ویجت‌های کامل‌سازی است،
و یا مقداری تهی است در صورتی که ویجت هنوز به طور کامل تعریف نشده باشد\&.
در حالت یکی مانده به آخر، \fItype\fP نام ویجت توکاری است که ویجت کامل‌سازی رفتار آن را
تقلید می‌کند و \fIname\fP نام تابع پوسته‌ای است که ویجت کامل‌سازی را پیاده‌سازی می‌نماید\&.
.SH "ماژول ZSH/ZPROF (THE ZSH/ZPROF MODULE)"
.\" Yodl file: Zsh/mod_zprof.yo

پس از بارگذاری، ماژول \fBzsh/zprof\fP باعث می‌شود توابع پوسته مورد پروفایل‌سازی (تحلیل کارایی)
قرار گیرند\&. نتایج پروفایل‌سازی را می‌توان با دستور توکار \fBzprof\fP که توسط این ماژول ارائه
می‌شود به دست آورد\&. هیچ راهی برای غیرفعال کردن پروفایل‌سازی به جز تخلیه (unload) این ماژول وجود ندارد\&.
.PP
.PD 0
.TP
.PD
\fBzprof\fP [ \fB\-c\fP ]
بدون گزینه \fB\-c\fP، دستور \fBzprof\fP نتایج پروفایل‌سازی را در خروجی استاندارد فهرست می‌کند\&.
قالب آن قابل مقایسه با دستوراتی مانند \fBgprof\fP است\&.
.RS
.PP
در بالا خلاصه‌ای شامل تمام توابعی که حداقل یک بار فراخوانی شده‌اند قرار دارد\&. این خلاصه بر
حسب مدت زمان صرف‌شده در هر یک به صورت نزولی مرتب شده است\&. خطوط شامل شماره ترتیبی تابع هستند،
که در سایر بخش‌های فهرست در پسوندهایی به صورت `\fB[\fP\fInum\fP\fB]\fP\&' استفاده می‌شود، و
سپس تعداد فراخوانی‌های انجام‌شده از آن تابع می‌آید\&. سه ستون بعدی زمان صرف‌شده در تابع و
نوادگان آن را برحسب میلی‌ثانیه، میانگین زمان صرف‌شده در تابع و نوادگان آن به ازای هر فراخوانی
برحسب میلی‌ثانیه، و درصد زمان صرف‌شده در تمام توابع پوسته مورد استفاده در این تابع و نوادگان
آن را نشان می‌دهند\&. سه ستون پس از آن همین اطلاعات را ارائه می‌دهند، اما تنها زمان صرف‌شده
در خود تابع را محاسبه می‌کنند\&. ستون پایانی نام تابع را نشان می‌دهد\&.
.PP
پس از بخش خلاصه، اطلاعات تفصیلی درباره هر تابعی که فراخوانی شده فهرست می‌شود، که به ترتیب
نزولی مقدار زمان صرف‌شده در هر تابع و نوادگان آن مرتب شده است\&. هر یک از این مدخل‌ها شامل
توضیحاتی برای توابعی است که تابع مورد نظر را فراخوانی کرده‌اند، خود تابع، و توابعی که از درون
آن فراخوانی شده‌اند\&. توضیحات مربوط به خود تابع همان قالب بخش خلاصه را دارد (و همان اطلاعات
را نشان می‌دهد)\&. خطوط دیگر شماره تابع را در ابتدا نشان نمی‌دهند و نام تابع آن‌ها دارای تورفتگی
است تا تشخیص خط نشان‌دهنده تابع شرح‌داده‌شده در این بخش از خطوط اطراف آسان‌تر شود\&.
.PP
اطلاعات نشان داده‌شده در این حالت تقریباً مشابه بخش خلاصه است، اما تنها به سلسله‌مراتب فراخوانی
در حال نمایش اشاره دارد\&. برای نمونه برای یک تابع فراخوان، ستون نشان‌دهنده کل زمان اجرا، زمان
صرف‌شده در تابع مورد نظر و نوادگان آن را تنها برای دفعاتی که از آن تابع فراخوان خاص فراخوانی
شده فهرست می‌کند\&. به طور مشابه برای یک تابع فراخوانی‌شده، این ستون کل زمان صرف‌شده در تابع
فراخوانی‌شده و نوادگان آن را تنها برای دفعاتی که از تابع مورد نظر فراخوانی شده فهرست می‌نماید\&.
.PP
همچنین در این حالت، ستون نشان‌دهنده تعداد فراخوانی‌های یک تابع، یک اسلش و سپس تعداد کل دفعات
فراخوانی تابع صدازده‌شده را نشان می‌دهد\&.
.PP
تا زمانی که ماژول \fBzsh/zprof\fP بارگذاری شده باشد، پروفایل‌سازی انجام خواهد شد و فراخوانی‌های
مکرر دستور توکار \fBzprof\fP زمان‌ها و تعداد فراخوانی‌ها را از زمان بارگذاری ماژول نشان خواهند داد\&.
با گزینه \fB\-c\fP، دستور توکار \fBzprof\fP شمارنده‌های درونی خود را بازنشانی کرده و فهرستی نمایش نخواهد داد\&.
.RE
.SH "ماژول ZSH/ZPTY (THE ZSH/ZPTY MODULE)"
.\" Yodl file: Zsh/mod_zpty.yo

ماژول \fBzsh/zpty\fP یک دستور توکار ارائه می‌دهد:
.PP
.PD 0
.TP
.PD
\fBzpty\fP [ \fB\-e\fP ] [ \fB\-b\fP ] \fIname\fP [ \fIarg\fP \&.\&.\&. ]
آرگومان‌های پس از \fIname\fP با قرار دادن فاصله میان آن‌ها الحاق شده، سپس به عنوان یک دستور
اجرا می‌شوند، درست مانند اینکه به دستور توکار \fBeval\fP ارسال شده باشند\&. دستور تحت یک
شبه‌ترمینال (pseudo\-terminal) تازه اختصاص‌یافته اجرا می‌شود؛ این ویژگی برای اجرای غیرتعاملی
دستوراتی که انتظار یک محیط تعاملی را دارند مفید است\&. مقدار \fIname\fP جزئی از دستور نیست، اما
برای ارجاع به این دستور در فراخوانی‌های بعدی \fBzpty\fP استفاده می‌شود\&.
.RS
.PP
با گزینه \fB\-e\fP، شبه‌ترمینال به گونه‌ای تنظیم می‌شود که نویسه‌های ورودی پژواک (echo) داده شوند\&.
.PP
با گزینه \fB\-b\fP، ورودی و خروجی شبه‌ترمینال در حالت غیرمسدودکننده (non\-blocking) قرار می‌گیرد\&.
.PP
پارامتر پوسته‌ای \fBREPLY\fP روی توصیف‌کننده فایل اختصاص‌یافته به سمت اصلی (master) شبه‌ترمینال
تنظیم می‌شود\&. این امکان می‌دهد ترمینال با گرداننده‌های توصیف‌کننده ZLE مانیتور شود (راهنمای
\fIzshzle\fP(1)
را ببینید) یا با \fBsysread\fP و \fBsyswrite\fP مدیریت گردد (بخش THE ZSH/SYSTEM MODULE در
\fIzshmodules\fP(1)
را ببینید)\&. \fIهشدار\fP: استفاده از \fBsysread\fP و \fBsyswrite\fP توصیه \fIنمی‌شود\fP؛ از
\fBzpty \-r\fP و \fBzpty \-w\fP استفاده کنید مگر اینکه دقیقاً بدانید چه کار می‌کنید\&.
.RE
.TP
\fBzpty\fP \fB\-d\fP [ \fIname\fP \&.\&.\&. ]
گزینه \fB\-d\fP برای حذف دستوراتی که پیش‌تر راه‌اندازی شده‌اند با ارائه فهرستی از \fIname\fPهای
آن‌ها استفاده می‌شود\&. اگر هیچ \fIname\fPای داده نشود، تمام دستورها حذف خواهند شد\&. حذف یک
دستور باعث ارسال سیگنال HUP به پردازش متناظر می‌شود\&. استفاده از این حالت در یک زیرپوسته ایده
مناسبی نیست، زیرا دستور را خواهد کشت اما پوسته والد را درباره وضعیت سردرگم باقی می‌گذارد و
ممکن است تلاش کند پردازش دیگری را که شناسه پردازش را مجدداً استفاده کرده بکشد\&.
.TP
\fBzpty\fP \fB\-w\fP [ \fB\-n\fP ] \fIname\fP [ \fIstring\fP \&.\&.\&. ]
گزینه \fB\-w\fP می‌تواند برای ارسال رشته‌های \fIstring\fP داده‌شده به عنوان ورودی به دستور
\fIname\fP (جداشده با فاصله) استفاده شود\&. اگر گزینه \fB\-n\fP داده \fIنشود\fP، یک خط جدید در
انتها اضافه می‌شود\&.
.RS
.PP
اگر هیچ \fIstring\fPای ارائه نشود، ورودی استاندارد در شبه‌ترمینال کپی می‌شود؛ این عملیات در صورت
غیرمسدودکننده بودن شبه‌ترمینال ممکن است پیش از کپی کل ورودی متوقف شود\&. ورودی دقیق همواره کپی
می‌شود: گزینه \fB\-n\fP اعمال نخواهد شد\&.
.PP
توجه داشته باشید که دستور تحت شبه‌ترمینال این ورودی را به گونه‌ای می‌بیند که گویی تایپ شده است،
بنابراین هنگام ارسال نویسه‌های کنترلی ویژه درایور tty نظیر پاک کردن کلمه، کشتن خط و پایان فایل
(EOF) احتیاط کنید\&.
.RE
.TP
\fBzpty\fP \fB\-r\fP [ \fB\-mt\fP ] \fIname\fP [ \fIparam\fP [ \fIpattern\fP ] ]
گزینه \fB\-r\fP می‌تواند برای خواندن خروجی دستور \fIname\fP استفاده شود\&.
تنها با آرگومان \fIname\fP، خروجی خوانده‌شده در خروجی استاندارد کپی می‌شود\&. مگر اینکه شبه‌ترمینال
غیرمسدودکننده باشد، کپی کردن تا زمان خروج دستور تحت شبه‌ترمینال ادامه می‌یابد؛ در حالت غیرمسدودکننده،
تنها مقداری از خروجی که بلافاصله در دسترس است کپی می‌شود\&. وضعیت بازگشتی در صورت کپی هر مقداری از
خروجی صفر است\&.
.RS
.PP
هنگامی که یک آرگومان \fIparam\fP نیز داده شود، حداکثر یک خط خوانده شده و در پارامتر با نام
\fIparam\fP ذخیره می‌شود\&. در صورت غیرمسدودکننده بودن شبه‌ترمینال ممکن است کمتر از یک خط کامل
خوانده شود\&. وضعیت بازگشتی در صورت ذخیره حداقل یک نویسه در \fIparam\fP صفر است\&.
.PP
اگر یک \fIpattern\fP نیز ارائه شود، خروجی تا زمانی خوانده می‌شود که کل رشته خوانده‌شده با
\fIpattern\fP مطابقت پیدا کند، حتی در حالت غیرمسدودکننده\&. وضعیت بازگشتی در صورتی که رشته
خوانده‌شده با الگو مطابقت داشته باشد، یا اگر دستور خاتمه یافته باشد اما حداقل یک نویسه همچنان قابل
خواندن باشد، صفر خواهد بود\&. اگر گزینه \fB\-m\fP حضور داشته باشد، وضعیت بازگشتی تنها در صورت تطابق
با الگو صفر است\&. تا زمان نگارش این مستند، حداکثر یک مگابایت خروجی می‌تواند از این طریق خوانده شود؛
اگر یک مگابایت کامل بدون تطابق با الگو خوانده شود، وضعیت بازگشتی غیر صفر خواهد بود\&.
.PP
در تمام حالات، اگر چیزی قابل خواندن نباشد وضعیت بازگشتی غیر صفر است، و اگر این موضوع به دلیل پایان یافتن
دستور باشد مقدار آن \fB2\fP خواهد بود\&.
.PP
اگر گزینه \fB\-r\fP با گزینه \fB\-t\fP ترکیب شود، \fBzpty\fP پیش از تلاش برای خواندن، در دسترس بودن
خروجی را بررسی می‌کند\&. اگر خروجی در دسترس نباشد، \fBzpty\fP بلافاصله وضعیت \fB1\fP را بازمی‌گرداند\&.
هنگام استفاده همراه با یک \fIpattern\fP، رفتار در زمان شکست در نمونه‌برداری مشابه زمانی است که دستور
خاتمه یافته باشد: اگر حداقل یک نویسه همچنان قابل خواندن باشد مقدار بازگشتی صفر است حتی اگر الگو با
شکست در تطابق مواجه شده باشد\&.
.RE
.TP
\fBzpty\fP \fB\-t\fP \fIname\fP
گزینه \fB\-t\fP بدون گزینه \fB\-r\fP می‌تواند برای آزمایش در حال اجرا بودن دستور \fIname\fP به کار رود\&.
در صورت در حال اجرا بودن دستور وضعیت صفر و در غیر این صورت مقداری غیر صفر بازمی‌گرداند\&. توجه داشته
باشید که این گزینه نشان‌دهنده در دسترس بودن یا نبودن خروجی برای خواندن نیست\&.
.TP
\fBzpty\fP [ \fB\-L\fP ]
آخرین صورت، بدون هیچ آرگومانی، برای فهرست کردن دستورات در حال حاضر تعریف‌شده استفاده می‌شود\&. اگر
گزینه \fB\-L\fP داده شود، این کار در قالب فراخوانی‌هایی به دستور توکار \fBzpty\fP انجام خواهد گرفت\&.
.SH "ماژول ZSH/ZSELECT (THE ZSH/ZSELECT MODULE)"
.\" Yodl file: Zsh/mod_zselect.yo

ماژول \fBzsh/zselect\fP یک دستور توکار در دسترس قرار می‌دهد:
.PP
.PD 0
.TP
.PD
\fBzselect\fP [ \fB\-rwe\fP ] [ \fB\-t\fP \fItimeout\fP ] [ \fB\-a\fP \fIarray\fP ] [ \fB\-A\fP \fIassoc\fP ] [ \fIfd\fP \&.\&.\&. ]
دستور توکار \fBzselect\fP رابطی برای فراخوانی سیستمی `select\&' است که اجرا را تا زمان آماده شدن
یک توصیف‌کننده فایل برای خواندن یا نوشتن، یا وقوع یک وضعیت خطا، با یک زمان‌انتظار اختیاری مسدود
می‌کند\&. اگر این قابلیت در سیستم شما موجود نباشد، دستور پیام خطایی چاپ کرده و وضعیت 2 را برمی‌گرداند
(خطاهای عادی وضعیت 1 برمی‌گردانند)\&. برای اطلاعات بیشتر، مستندات سیستم خود را برای \fIselect\fP(2)
ببینید\&. توجه داشته باشید که ارتباطی با دستور توکار پوسته با همین نام وجود ندارد\&.
.RS
.PP
آرگومان‌ها و گزینه‌ها می‌توانند با هر ترتیبی درهم آمیخته شوند\&. آرگومان‌های غیرگزینه‌ای توصیف‌کننده‌های
فایل هستند که باید اعداد صحیح ده‌دهی باشند\&. به طور پیش‌فرض، توصیف‌کننده‌های فایل برای خواندن بررسی
می‌شوند، یعنی \fBzselect\fP زمانی بازمی‌گردد که داده‌ها برای خواندن از توصیف‌کننده فایل آماده باشند، یا
به بیان دقیق‌تر، هنگامی که عملیات خواندن از توصیف‌کننده فایل مسدود نشود\&. پس از \fB\-r\fP، \fB\-w\fP و
\fB\-e\fP، توصیف‌کننده‌های فایل داده‌شده برای شرایط خواندن، نوشتن یا خطا بررسی می‌شوند\&. این گزینه‌ها و
فهرست دلخواهی از توصیف‌کننده‌های فایل می‌توانند با هر ترتیبی داده شوند\&.
.PP
(وجود یک «وضعیت خطا» در مستندات بسیاری از پیاده‌سازی‌های فراخوانی سیستمی select به خوبی تعریف نشده است\&.
طبق نسخه‌های اخیر استاندارد POSIX، این در واقع یک وضعیت «استثنا» (exception) است که تنها نمونه استاندارد
آن داده‌های خارج از باند دریافت‌شده روی یک سوکت است\&. بنابراین بعید است کاربران zsh گزینه \fB\-e\fP را
مفید بیابند\&.)
.PP
گزینه `\fB\-t\fP \fItimeout\fP\&' زمان‌انتظار را برحسب صدم ثانیه تعیین می‌کند\&. این مقدار می‌تواند صفر
باشد که در این حالت توصیف‌کننده‌های فایل صرفاً نمونه‌برداری شده و \fBzselect\fP بلافاصله بازمی‌گردد\&.
امکان فراخوانی zselect بدون هیچ توصیف‌کننده فایلی و با یک زمان‌انتظار غیر صفر برای استفاده به عنوان
جایگزینی دقیق‌تر برای `sleep\&' وجود دارد؛ با این حال توجه داشته باشید وضعیت بازگشتی برای یک timeout
همواره 1 است\&.
.PP
گزینه `\fB\-a\fP \fIarray\fP\&' مشخص می‌کند که \fIarray\fP باید برای نشان دادن توصیف‌کننده(های) فایل
آماده تنظیم شود\&. اگر این گزینه ارائه نشود، آرایه \fBreply\fP برای این منظور استفاده خواهد شد\&. آرایه
شامل رشته‌ای مشابه با آرگومان‌های \fBzselect\fP خواهد بود\&. برای نمونه:
.PP
.RS
.nf
\fBzselect \-t 0 \-r 0 \-w 1\fP
.fi
.RE
.PP
ممکن است بلافاصله با وضعیت 0 و در حالی که \fB$reply\fP شامل `\fB\-r 0 \-w 1\fP\&' است بازگردد تا نشان دهد
هر دو توصیف‌کننده فایل برای عملیات‌های درخواستی آماده هستند\&.
.PP
گزینه `\fB\-A\fP \fIassoc\fP\&' مشخص می‌کند که آرایه انجمنی \fIassoc\fP باید برای نشان دادن توصیف‌کننده(های)
فایل آماده مقداردهی شود\&. این گزینه بر گزینه \fB\-a\fP تقدم دارد و \fBreply\fP نیز تغییر نخواهد کرد\&.
کلیدهای \fBassoc\fP همان توصیف‌کننده‌های فایل هستند، و مقادیر متناظر هر یک از نویسه‌های `\fBrwe\fP\&'
برای نشان دادن وضعیت مربوطه می‌باشند\&.
.PP
در صورتی که برخی از توصیف‌کننده‌های فایل برای خواندن آماده باشند، دستور وضعیت 0 را بازمی‌گرداند\&. اگر
عملیات با پایان زمان‌انتظار مواجه شد، یا زمان‌انتظار صفر داده شد و هیچ توصیف‌کننده‌ای آماده نبود، یا خطایی
رخ داد، وضعیت 1 را برمی‌گرداند و آرایه تنظیم نخواهد شد (و به هیچ وجه تغییر نمی‌کند)\&. اگر خطایی در عملیات
select رخ داده باشد پیام خطای مناسب چاپ می‌شود\&.
.RE
.SH "ماژول ZSH/ZUTIL (THE ZSH/ZUTIL MODULE)"
.\" Yodl file: Zsh/mod_zutil.yo

ماژول \fBzsh/zutil\fP تنها تعدادی دستور توکار اضافه می‌کند:
.PP
.PD 0
.TP
.PD 0
\fBzstyle\fP [ \fB\-L\fP [ \fImetapattern\fP [ \fIstyle\fP ] ] ]
.TP
.PD 0
\fBzstyle\fP [ \fB\-e\fP | \fB\-\fP | \fB\-\fP\fB\-\fP ] \fIpattern\fP \fIstyle\fP \fIstring\fP \&.\&.\&.
.TP
.PD 0
\fBzstyle \-d\fP [ \fIpattern\fP [ \fIstyle\fP \&.\&.\&. ] ]
.TP
.PD 0
\fBzstyle \-g\fP \fIname\fP [ \fIpattern\fP [ \fIstyle\fP ] ]
.TP
.PD 0
\fBzstyle \-\fP{\fBa\fP|\fBb\fP|\fBs\fP} \fIcontext\fP \fIstyle\fP \fIname\fP [ \fIsep\fP ]
.TP
.PD 0
\fBzstyle \-\fP{\fBT\fP|\fBt\fP} \fIcontext\fP \fIstyle\fP [ \fIstring\fP \&.\&.\&. ]
.TP
.PD
\fBzstyle \-m\fP \fIcontext\fP \fIstyle\fP \fIpattern\fP
این دستور توکار برای تعریف و جستجوی سبک‌ها (styles) استفاده می‌شود\&. سبک‌ها جفت‌هایی از نام و
مقدار هستند، که مقادیر آن‌ها از هر تعداد رشته تشکیل می‌شود\&. سبک‌ها همراه با الگوها ذخیره می‌شوند و
جستجو با ارائه یک رشته به نام `\fIcontext\fP\&' (زمینه) انجام می‌گیرد که با الگوها مطابقت داده می‌شود\&.
تعریف ذخیره‌شده برای خاص‌ترین الگویی که مطابقت داشته باشد بازگردانده خواهد شد\&.
.RS
.PP
یک الگو زمانی خاص‌تر از الگوی دیگر در نظر گرفته می‌شود که مؤلفه‌های بیشتری (زیررشته‌های جداشده با
دونقطه) داشته باشد یا الگوهای مربوط به مؤلفه‌های آن خاص‌تر باشند، به این صورت که رشته‌های ساده
خاص‌تر از الگوها و الگوهای پیچیده خاص‌تر از الگوی `\fB*\fP\&' تلقی می‌شوند\&. یک `\fB*\fP' در الگو با صفر یا
چند نویسه در زمینه مطابقت دارد؛ دونقطه‌ها در این زمینه رفتار خاصی ندارند\&. اگر دو الگو به یک اندازه خاص
باشند، برابری به نفع الگویی که اول تعریف شده است شکسته می‌شود\&.
.PP
\fIمثال\fP
.PP
برای نمونه، یک پلاگین فرضی به نام `\fBweather\fP\&' ممکن است در مستندات خود بیان کند که به جستجوی
سبک \fBpreferred\-precipitation\fP در زمینه
`\fB:weather:\fP\fIcontinent\fP\fB:\fP\fIday\-of\-the\-week\fP\fB:\fP\fIphase\-of\-the\-moon\fP\&'
می‌پردازد\&. بر این اساس، شما ممکن است مقادیر زیر را در فایل \fBzshrc\fP خود تنظیم کنید:
.PP
.RS
.nf
\fBzstyle \&':weather:europe:*' preferred\-precipitation rain
zstyle \&':weather:*:Sunday:*' preferred\-precipitation snow\fP
.fi
.RE
.PP
سپس پلاگین در پشت صحنه دستوری مانند دستور زیر را اجرا می‌کند:
.PP
.RS
.nf
\fBzstyle \-s ":weather:${continent}:${day_of_week}:${moon_phase}" preferred\-precipitation REPLY\fP
.fi
.RE
.PP
تا ترجیح شما را در متغیر اسکالر \fB$REPLY\fP بازیابی کند\&. در روزهای یکشنبه مقدار \fB$REPLY\fP برابر
`\fBsnow\fP\&' خواهد بود؛ در اروپا برابر `\fBrain\fP\&' خواهد بود؛ و در روزهای یکشنبه در اروپا دوباره
برابر `\fBsnow\fP' تنظیم می‌شود، زیرا هر دو الگوی `\fB:weather:europe:*\fP\&' و `\fB:weather:*:Sunday:*\fP'
با آرگومان \fIcontext\fP در دستور \fBzstyle \-s\fP مطابقت دارند، دارای درجه ویژگی یکسانی هستند، و الگوی دوم
خاص‌تر است (زیرا مؤلفه‌های جداشده با دونقطه بیشتری دارد)\&.
.PP
\fIنحوه استفاده\fP
.PP
حالت‌هایی که روی الگوها عمل می‌کنند به شرح زیر هستند:
.PP
.PD 0
.TP
.PD
\fBzstyle\fP [ \fB\-L\fP [ \fImetapattern\fP [ \fIstyle\fP ] ] ]
بدون آرگومان، تعاریف سبک را فهرست می‌کند\&. سبک‌ها به ترتیب الفبایی و الگوها به ترتیبی که
\fBzstyle\fP آن‌ها را می‌آزماید نشان داده می‌شوند\&.
.RS
.PP
اگر گزینه \fB\-L\fP داده شود، فهرست کردن در قالب فراخوانی‌هایی به \fBzstyle\fP انجام می‌شود\&. اولین
آرگومان اختیاری، \fImetapattern\fP، الگویی است که با رشته ارائه‌شده به عنوان \fIpattern\fP در هنگام
تعریف سبک مطابقت داده خواهد شد\&. توجه: این بدان معناست که برای نمونه دستور
`\fBzstyle \-L ":completion:*"\fP\&' با هر الگوی ارائه‌شده‌ای که با `\fB:completion:\fP\&' آغاز شود
تطبیق می‌یابد، نه فقط با \fB":completion:*"\fP: برای تطبیق دقیق با آن، از \fB\&':completion:\e*'\fP
استفاده کنید\&. آرگومان دوم اختیاری، خروجی را به یک \fIstyle\fP مشخص محدود می‌کند (نه یک الگو)\&.
گزینه \fB\-L\fP با هیچ گزینه دیگری سازگار نیست\&.
.RE
.TP
\fBzstyle\fP [ \fB\-\fP | \fB\-\fP\fB\-\fP | \fB\-e\fP ] \fIpattern\fP \fIstyle\fP \fIstring\fP \&.\&.\&.
سبک \fIstyle\fP داده‌شده را برای الگوی \fIpattern\fP با رشته‌های \fIstring\fP به عنوان مقدار تعریف
می‌کند\&. اگر گزینه \fB\-e\fP داده شود، رشته‌های \fIstring\fP (با فاصله) الحاق می‌شوند و رشته حاصل
هنگام جستجوی سبک (به همان روشی که توسط دستور توکار \fBeval\fP انجام می‌گیرد) ارزیابی خواهد شد\&.
در این حالت پارامتر `\fBreply\fP\&' باید برای تعیین رشته‌های بازگردانده‌شده پس از ارزیابی مقداردهی
شود\&. پیش از ارزیابی مقدار، \fBreply\fP لغو مقداردهی می‌شود، و اگر پس از ارزیابی همچنان لغو شده
باقی بماند، با سبک به گونه‌ای رفتار می‌شود که گویی تنظیم نشده است\&.
.TP
\fBzstyle \-d\fP [ \fIpattern\fP [ \fIstyle\fP \&.\&.\&. ] ]
تعاریف سبک را حذف می‌کند\&. بدون آرگومان تمام تعاریف حذف می‌شوند؛ با یک \fIpattern\fP تمام تعاریف مربوط
به آن الگو حذف می‌شوند و اگر هرگونه \fIstyle\fP داده شود، تنها آن سبک‌ها برای آن \fIpattern\fP حذف خواهند شد\&.
.TP
\fBzstyle \-g\fP \fIname\fP [ \fIpattern\fP [ \fIstyle\fP ] ]
تعریف یک سبک را بازیابی می‌کند\&. مقدار \fIname\fP به عنوان نام آرایه‌ای که نتایج در آن ذخیره می‌شوند
به کار می‌رود\&. بدون آرگومان‌های بیشتر، تمام الگوهای تعریف‌شده بازگردانده می‌شوند\&. با یک \fIpattern\fP،
سبک‌های تعریف‌شده برای آن الگو بازگردانده می‌شوند و با هر دو آرگومان \fIpattern\fP و \fIstyle\fP،
رشته‌های مقدار آن ترکیب بازگردانده خواهد شد\&.
.PP
حالت‌های دیگر می‌توانند برای جستجو یا آزمایش سبک‌ها برای یک زمینه معین استفاده شوند:
.PP
.PD 0
.TP
.PD
\fBzstyle \-s\fP \fIcontext\fP \fIstyle\fP \fIname\fP [ \fIsep\fP ]
پارامتر \fIname\fP روی مقدار سبک به صورت تفسیرشده به عنوان یک رشته تنظیم می‌شود\&. اگر مقدار شامل چندین
رشته باشد، آن‌ها با فاصله (یا با رشته \fIsep\fP در صورت ارائه) در میانشان الحاق می‌شوند\&.
.RS
.PP
در صورت تنظیم بودن سبک وضعیت \fB0\fP و در غیر این صورت \fB1\fP را بازمی‌گرداند\&.
.RE
.TP
\fBzstyle \-b\fP \fIcontext\fP \fIstyle\fP \fIname\fP
مقدار به صورت یک بولی (boolean) در \fIname\fP ذخیره می‌شود، یعنی در صورتی که مقدار تنها شامل یک رشته باشد
و آن رشته برابر یکی از مقادیر `\fByes\fP\&'، `\fBtrue\fP'، `\fBon\fP' یا `\fB1\fP' باشد، رشته `\fByes\fP\&'
ذخیره خواهد شد\&. اگر مقدار هر رشته دیگری باشد یا بیش از یک رشته داشته باشد، پارامتر روی `\fBno\fP\&' تنظیم می‌شود\&.
.RS
.PP
در صورتی که \fIname\fP روی `\fByes\fP\&' تنظیم شده باشد وضعیت \fB0\fP و در غیر این صورت \fB1\fP را بازمی‌گرداند\&.
.RE
.TP
\fBzstyle \-a\fP \fIcontext\fP \fIstyle\fP \fIname\fP
مقدار به صورت یک آرایه در \fIname\fP ذخیره می‌شود\&. اگر \fIname\fP به عنوان یک آرایه انجمنی اعلان شده
باشد، رشته‌های اول، سوم و غیره به عنوان کلیدها و سایر رشته‌ها به عنوان مقادیر استفاده می‌شوند\&.
.RS
.PP
در صورت تنظیم بودن سبک وضعیت \fB0\fP و در غیر این صورت \fB1\fP بازگردانده می‌شود\&.
.RE
.TP
.PD 0
\fBzstyle \-t\fP \fIcontext\fP \fIstyle\fP [ \fIstring\fP \&.\&.\&. ]
.TP
.PD
\fBzstyle \-T\fP \fIcontext\fP \fIstyle\fP [ \fIstring\fP \&.\&.\&. ]
مقدار یک سبک را آزمایش می‌کند، یعنی گزینه \fB\-t\fP تنها یک وضعیت بازمی‌گرداند (\fB$?\fP را تنظیم می‌کند)\&.
بدون هیچ \fIstring\fPای، در صورتی که سبک برای حداقل یک الگوی منطبق تعریف شده باشد، تنها یک رشته در مقدار
خود داشته باشد و آن رشته برابر با یکی از `\fBtrue\fP\&'، `\fByes\fP'، `\fBon\fP' یا `\fB1\fP\&' باشد،
وضعیت خروجی صفر است\&. اگر رشته‌های \fIstring\fP داده شوند، وضعیت خروجی تنها در صورتی صفر است که حداقل
یکی از \fIstring\fPها برابر با حداقل یکی از رشته‌های موجود در مقدار باشد\&. اگر سبک تعریف شده باشد اما
تطبیق نیابد، وضعیت خروجی \fB1\fP است\&. اگر سبک تعریف نشده باشد، وضعیت \fB2\fP خواهد بود\&.
.RS
.PP
گزینه \fB\-T\fP مقادیر سبک را مشابه \fB\-t\fP آزمایش می‌کند، اما در صورتی که سبک برای هیچ الگوی منطبقی
تعریف نشده باشد وضعیت صفر (به جای \fB2\fP) بازمی‌گرداند\&.
.RE
.TP
\fBzstyle \-m\fP \fIcontext\fP \fIstyle\fP \fIpattern\fP
یک مقدار را تطبیق می‌دهد\&. اگر الگوی \fIpattern\fP با حداقل یکی از رشته‌های موجود در مقدار تطابق داشته
باشد، وضعیت خروجی صفر را بازمی‌گرداند\&.
.RE
.TP
.PD 0
\fBzformat \-f\fP \fIparam\fP \fIformat\fP \fIspec\fP \&.\&.\&.
.TP
.PD 0
\fBzformat \-F\fP \fIparam\fP \fIformat\fP \fIspec\fP \&.\&.\&.
.TP
.PD
\fBzformat \-a\fP \fIarray\fP \fIsep\fP \fIspec\fP \&.\&.\&.
این دستور توکار اشکال گوناگونی از قالب‌بندی را ارائه می‌دهد\&. حالت اول با گزینه \fB\-f\fP انتخاب می‌شود\&.
در این حالت رشته \fIformat\fP با جایگزین کردن دنباله‌هایی که با علامت درصد شروع می‌شوند با رشته‌های حاصل از
\fIspec\fPها اصلاح خواهد شد\&. هر \fIspec\fP باید به صورت `\fIchar\fP\fB:\fP\fIstring\fP\&' باشد که
باعث می‌شود هر بار وقوع دنباله `\fB%\fP\fIchar\fP\&' در \fIformat\fP با \fIstring\fP جایگزین شود\&.
دنباله `\fB%\fP\&' همچنین می‌تواند حاوی مشخصه‌های اختیاری حداقل و حداکثر عرض فیلد میان `\fB%\fP\&' و
`\fIchar\fP\&' به صورت `\fB%\fP\fImin\fP\fB\&.\fP\fImax\fP\fBc\fP' باشد، یعنی حداقل عرض فیلد ابتدا
می‌آید و اگر حداکثر عرض فیلد استفاده شود، باید یک نقطه پیش از آن قرار گیرد\&. تعیین حداقل عرض فیلد باعث
می‌شود در صورتی که \fIstring\fP کوتاه‌تر از عرض درخواستی باشد، نتیجه از سمت راست با فاصله‌های خالی پر شود\&.
پر کردن از سمت چپ را می‌توان با تعیین حداقل عرض فیلد منفی به دست آورد\&. اگر حداکثر عرض فیلد مشخص شود،
\fIstring\fP پس از آن تعداد نویسه قطع (truncate) خواهد شد\&. پس از پردازش تمام دنباله‌های `\fB%\fP\&' برای
\fIspec\fPهای داده‌شده، رشته حاصل در پارامتر \fIparam\fP ذخیره می‌شود\&. دنباله `\fB%%\fP\&' می‌تواند برای
تولید یک علامت \fB%\fP واقعی استفاده شود\&.
.RS
.PP
دنباله‌های اسکیپ با علامت \fB%\fP همچنین عبارات سه‌گانه را به همان قالبی که در اعلان‌ها به کار می‌رود
می‌فهمند\&. علامت \fB%\fP با یک `\fB(\fP\&' و سپس یک نویسه مشخص‌کننده قالب معمولی همان‌طور که در بالا شرح
داده شد دنبال می‌شود\&. مجموعه‌ای از ارقام می‌توانند قبل یا بعد از `\fB(\fP\&' قرار گیرند؛ این ارقام یک
شماره آزمون را مشخص می‌کنند که پیش‌فرض آن صفر است\&. اعداد منفی نیز مجاز هستند\&. یک نویسه جداکننده دلخواه
به دنبال مشخص‌کننده قالب می‌آید، که پس از آن بخشی از متن «درست»، دوباره نویسه جداکننده، بخشی از متن
«نادرست»، و یک پرانتز بسته قرار می‌گیرد\&. عبارت کامل (بدون ارقام) بنابراین شبیه به
`\fB%(\fP\fIX\fP\fB\&.\fP\fItext1\fP\fB\&.\fP\fItext2\fP\fB)\fP\&'
خواهد بود، با این تفاوت که نویسه `\fB\&.\fP\&' دلخواه است\&. مقدار ارائه‌شده برای مشخص‌کننده قالب در
عبارات \fIchar\fP\fB:\fP\fIstring\fP به عنوان یک عبارت ریاضی ارزیابی شده و با شماره آزمون مقایسه
می‌شود\&. اگر یکسان باشند، \fItext1\fP خروجی داده می‌شود، وگرنه \fItext2\fP خروجی خواهد بود\&. یک پرانتز
را می‌توان در \fItext2\fP به صورت \fB%)\fP اسکیپ کرد\&. هر یک از \fItext1\fP یا \fItext2\fP می‌توانند
حاوی دنباله‌های فرار \fB%\fP تو در تو باشند\&.
.PP
برای مثال:
.PP
.RS
.nf
\fBzformat \-f REPLY "The answer is \&'%3(c\&.yes\&.no)'\&." c:3\fP
.fi
.RE
.PP
عبارت "The answer is \&'yes'\&." را در \fBREPLY\fP چاپ می‌کند زیرا مقدار برای مشخص‌کننده قالب \fBc\fP
برابر 3 است، که با آرگومان رقمی عبارت سه‌گانه مطابقت دارد\&.
.PP
با گزینه \fB\-F\fP به جای \fB\-f\fP، عبارات سه‌گانه بر اساس اینکه آیا مشخص‌کننده قالب حاضر و غیرخالی
است یا خیر، میان متن «درست» یا «نادرست» انتخاب می‌کنند\&. یک شماره آزمون بیانگر حداقل عرض برای مقدار
ارائه‌شده در مشخص‌کننده قالب است\&. اعداد منفی این قاعده را معکوس می‌کنند، بنابراین آزمون بررسی می‌کند که
آیا مقدار از حداکثر عرض فراتر می‌رود یا خیر\&.
.PP
حالتی که از گزینه \fB\-a\fP استفاده می‌کند، می‌تواند برای تراز کردن رشته‌ها به کار رود\&. در اینجا
\fIspec\fPها به صورت `\fIleft\fP\fB:\fP\fIright\fP\&' هستند که در آن `\fIleft\fP' و `\fIright\fP'
رشته‌های دلخواهی می‌باشند\&. این رشته‌ها با جایگزین کردن دونقطه‌ها با رشته \fIsep\fP و پر کردن رشته‌های
\fIleft\fP با فاصله‌های خالی از سمت راست اصلاح می‌شوند به طوری که رشته‌های \fIsep\fP در نتیجه (و بنابراین
رشته‌های \fIright\fP پس از آن‌ها) همگی در صورتی که رشته‌ها زیر یکدیگر چاپ شوند تراز گردند\&. تمام رشته‌های
بدون دونقطه بدون تغییر باقی می‌مانند و تمام رشته‌های دارای یک رشته \fIright\fP خالی، دونقطه انتهایی آن‌ها
حذف خواهد شد\&. در هر دو حالت، طول رشته‌ها برای تعیین چگونگی تراز شدن سایر رشته‌ها استفاده نمی‌شود\&.
یک دونقطه در رشته \fIleft\fP را می‌توان با یک بک‌اسلش اسکیپ کرد\&. رشته‌های حاصل در \fIarray\fP ذخیره می‌شوند\&.
.RE
.TP
\fBzregexparse\fP
این دستور برخی عملکردهای درونی تابع \fB_regex_arguments\fP را پیاده‌سازی می‌کند\&.
.TP
\fBzparseopts\fP [ \fB\-D\fP \fB\-E\fP \fB\-F\fP \fB\-K\fP \fB\-M\fP ] [ \fB\-a\fP \fIarray\fP ] [ \fB\-A\fP \fIassoc\fP ] [ \fB\-\fP ] \fIspec\fP \&.\&.\&.
این دستور توکار تجزیه گزینه‌ها را در پارامترهای مکانی (یعنی مجموعه آرگومان‌های ارائه‌شده توسط \fB$*\fP)
ساده می‌کند\&. هر \fIspec\fP یک گزینه را شرح می‌دهد و باید به صورت `\fIopt\fP[\fB=\fP\fIarray\fP]\&'
باشد\&. اگر گزینه‌ای که توسط \fIopt\fP توصیف شده است در پارامترهای مکانی یافت شود، در آرایه \fIarray\fP
مشخص‌شده با گزینه \fB\-a\fP کپی می‌شود؛ اگر عبارت اختیاری `\fB=\fP\fIarray\fP\&' داده شده باشد، در عوض در
آن آرایه کپی می‌شود، که باید به عنوان یک آرایه معمولی اعلان شده باشد و هرگز نباید یک آرایه انجمنی باشد\&.
.RS
.PP
توجه داشته باشید که ارائه هر \fIspec\fP بدون یک `\fB=\fP\fIarray\fP\&' خطا محسوب می‌شود مگر اینکه یکی از
گزینه‌های \fB\-a\fP یا \fB\-A\fP استفاده شده باشد\&.
.PP
مگر در حالتی که گزینه \fB\-E\fP داده شده باشد، تجزیه در اولین رشته‌ای که توسط یکی از \fIspec\fPها توصیف
نشده باشد متوقف می‌شود\&. حتی با \fB\-E\fP، تجزیه همواره در یک پارامتر مکانی برابر با `\fB\-\fP\&' یا
`\fB\-\fP\fB\-\fP\&' متوقف خواهد شد\&. همچنین گزینه \fB\-F\fP را ببینید\&.
.PP
توضیحات \fIopt\fP باید یکی از موارد زیر باشد\&. هر یک از نویسه‌های ویژه می‌توانند در نام گزینه ظاهر شوند
به شرطی که یک بک‌اسلش در پیش از آن‌ها قرار گیرد\&.
.PP
.PD 0
.TP
.PD 0
\fIname\fP
.TP
.PD
\fIname\fP\fB+\fP
مقدار \fIname\fP همان نام گزینه بدون علامت `\fB\-\fP\&' ابتدایی است\&. برای مشخص کردن یک گزینه طولانی
به سبک GNU، یکی از دو علامت `\fB\-\fP\&' آغازین باید در \fIname\fP گنجانده شود؛ برای مثال، یک گزینه
`\fB\-\fP\fB\-file\fP\&' با \fIname\fP به صورت `\fB\-file\fP\&' نشان داده می‌شود\&.
.RS
.PP
اگر یک `\fB+\fP\&' پس از \fIname\fP ظاهر شود، هر بار که گزینه در پارامترهای مکانی یافت شود به \fIarray\fP
الحاق می‌گردد؛ بدون `\fB+\fP\&' تنها \fIآخرین\fP وقوع گزینه حفظ می‌شود\&.
.PP
اگر یکی از این قالب‌ها استفاده شود، گزینه هیچ آرگومانی نمی‌پذیرد، بنابراین در صورتی که پارامتر مکانی بعدی
با `\fB\-\fP\&' آغاز نشود، تجزیه متوقف می‌شود (مگر اینکه گزینه \fB\-E\fP استفاده شود)\&.
.RE
.TP
.PD 0
\fIname\fP\fB:\fP
.TP
.PD 0
\fIname\fP\fB:\-\fP
.TP
.PD
\fIname\fP\fB::\fP
اگر یک یا دو دونقطه داده شود، گزینه یک آرگومان می‌پذیرد؛ با یک دونقطه، آرگومان اجباری است و با دو دونقطه
اختیاری خواهد بود\&. آرگومان پس از خود گزینه به \fIarray\fP الحاق می‌شود\&.
.RS
.PP
یک آرگومان اختیاری در همان عنصر آرایه که نام گزینه قرار دارد گذاشته می‌شود (توجه داشته باشید این امر رشته‌های
خالی را به عنوان آرگومان غیرقابل تمایز می‌سازد)\&. یک آرگومان اجباری به عنوان یک عنصر جداگانه اضافه می‌شود
مگر اینکه از حالت `\fB:\-\fP\&' استفاده شود، که در این حالت آرگومان در همان عنصر قرار می‌گیرد\&.
.PP
یک `\fB+\fP\&' همان‌طور که در بالا توضیح داده شد می‌تواند میان \fIname\fP و نخستین دونقطه قرار گیرد\&.
.RE
.PP
در تمام حالات، آرگومان‌های گزینه باید یا بلافاصله پس از گزینه در همان پارامتر مکانی یا در پارامتر بعدی
ظاهر شوند\&. حتی یک آرگومان اختیاری می‌تواند در پارامتر بعدی ظاهر شود، مگر اینکه با یک `\fB\-\fP\&' شروع
شده باشد\&. هیچ رفتار ویژه‌ای برای `\fB=\fP\&' همانند تجزیه‌کننده‌های آرگومان به سبک GNU وجود ندارد؛
با فرض \fIspec\fP به صورت `\fB\-foo:\fP\&'، پارامتر مکانی `\fB\-\fP\fB\-foo=bar\fP' به عنوان
`\fB\-\fP\fB\-foo\fP\&' با یک آرگومان `\fB=bar\fP' تجزیه می‌شود\&.
.PP
هنگامی که نام دو گزینه که آرگومانی نمی‌پذیرند هم‌پوشانی داشته باشد، طولانی‌ترین گزینه برنده است، به طوری که
تجزیه برای \fIspec\fPهای `\fB\-foo \-foobar\fP\&' (برای مثال) بدون ابهام است\&. با این حال با توجه به نحوه
مدیریت پیش‌گفته برای آرگومان‌های گزینه‌ها، زمانی که حداقل یکی از \fIspec\fPهای هم‌پوشان آرگومانی بپذیرد
(مانند `\fB\-foo: \-foobar\fP\&') ممکن است ابهام رخ دهد\&. در این حالت، آخرین \fIspec\fP منطبق برنده خواهد بود\&.
.PP
گزینه‌های خود دستور \fBzparseopts\fP را نمی‌توان با هم ترکیب کرد (stack کرد) زیرا برای مثال عبارت
`\fB\-DEK\fP\&' از یک \fIspec\fP برای گزینه طولانی به سبک GNU یعنی `\fB\-\fP\fB\-DEK\fP\&' غیرقابل تفکیک
است\&. گزینه‌های خود \fBzparseopts\fP عبارتند از:
.PP
.PD 0
.TP
.PD
\fB\-a\fP \fIarray\fP
همان‌طور که در بالا شرح داده شد، آرایه پیش‌فرضی را که گزینه‌های شناخته‌شده باید در آن ذخیره شوند تعیین می‌کند\&.
.TP
\fB\-A\fP \fIassoc\fP
در صورت ارائه، گزینه‌ها و مقادیر آن‌ها همچنین در یک آرایه انجمنی قرار داده می‌شوند که نام گزینه‌ها به
عنوان کلید و آرگومان‌ها (در صورت وجود) به عنوان مقادیر آن خواهد بود\&.
.TP
\fB\-D\fP
در صورت ارائه این گزینه، تمام گزینه‌های یافت‌شده از پارامترهای مکانی پوسته فراخوان یا تابع پوسته، تا
(اما نه شامل) هر موردی که توسط \fIspec\fPها توصیف نشده باشد حذف می‌شوند\&. اگر نخستین پارامتر این‌چنینی
`\fB\-\fP\&' یا `\fB\-\fP\fB\-\fP\&' باشد، آن نیز حذف خواهد شد\&. این شبیه به استفاده از دستور توکار
\fBshift\fP است\&.
.TP
\fB\-E\fP
قواعد تجزیه را تغییر می‌دهد تا در اولین رشته‌ای که توسط یکی از \fIspec\fPها توصیف نشده است متوقف \fIنشود\fP\&.
می‌توان از آن برای آزمایش وجود یا (در صورت استفاده همراه با \fB\-D\fP) استخراج گزینه‌ها و آرگومان‌های آن‌ها،
با نادیده گرفتن تمام گزینه‌ها و آرگومان‌های دیگری که ممکن است در پارامترهای مکانی باشند، استفاده کرد\&.
همان‌طور که در بالا اشاره شد، تجزیه همچنان در اولین `\fB\-\fP\&' یا `\fB\-\fP\fB\-\fP' توصیف‌نشده توسط یک
\fIspec\fP متوقف می‌شود، اما در صورت استفاده همراه با \fB\-D\fP حذف نخواهد شد\&.
.TP
\fB\-F\fP
در صورت ارائه این گزینه، \fBzparseopts\fP بلافاصله در نخستین پارامتر گزینه‌مانندی که توسط یکی از
\fIspec\fPها توصیف نشده باشد متوقف می‌شود، یک پیام خطا چاپ کرده، و وضعیت 1 را بازمی‌گرداند\&. حذف
(\fB\-D\fP) و استخراج (\fB\-E\fP) انجام نمی‌شوند، و آرایه‌های گزینه به‌روزرسانی نخواهند شد\&. این گزینه
یک اعتبارسنجی اولیه برای گزینه‌های ارائه‌شده فراهم می‌کند\&.
.RS
.PP
توجه داشته باشید که حضور گزینه‌ای بدون آرگومان الزامی آن در پارامترهای مکانی، همواره تجزیه را متوقف کرده
و خطایی را همان‌طور که در بالا شرح داده شد برمی‌گرداند، صرف‌نظر از اینکه این گزینه استفاده شده باشد یا خیر\&.
.RE
.TP
\fB\-K\fP
با این گزینه، آرایه‌های مشخص‌شده با گزینه \fB\-a\fP و با قالب‌های `\fB=\fP\fIarray\fP\&' هنگامی که
هیچ‌یک از \fIspec\fPهای مربوط به آن‌ها استفاده نشوند دست‌نخورده باقی می‌مانند\&. در غیر این صورت کل
آرایه هنگام استفاده از هر یک از \fIspec\fPها جایگزین می‌شود\&. عناصر منفرد آرایه‌های انجمنی مشخص‌شده با
گزینه \fB\-A\fP توسط \fB\-K\fP حفظ می‌شوند\&. این امکان می‌دهد پیش از فراخوانی \fBzparseopts\fP مقادیر
پیش‌فرضی به آرایه‌ها اختصاص داده شود\&.
.TP
\fB\-M\fP
قواعد انتساب را برای پیاده‌سازی نگاشتی میان نام‌های معادل گزینه‌ها تغییر می‌دهد\&. اگر هر \fIspec\fPای از
قالب `\fB=\fP\fIarray\fP\&' استفاده کند، رشته \fIarray\fP به عنوان نام یک \fIspec\fP دیگر تفسیر می‌شود،
که برای انتخاب محل ذخیره مقادیر به کار می‌رود\&. اگر هیچ \fIspec\fP دیگری یافت نشود، مقادیر طبق معمول ذخیره
می‌شوند\&. این گزینه تنها شیوه ذخیره مقادیر را تغییر می‌دهد و نه شیوه تجزیه \fB$*\fP را، بنابراین نتایج در
صورت استفاده ناهماهنگ از مشخص‌کننده `\fIname\fP\fB+\fP\&' ممکن است غیرقابل پیش‌بینی باشد\&.
.PP
برای نمونه:
.PP
.RS
.nf
\fBset \-\- \-a \-bx \-c y \-cz baz \-cend
zparseopts a=foo b:=bar c+:=bar\fP
.fi
.RE
.PP
تأثیری به صورت زیر خواهد داشت:
.PP
.RS
.nf
\fBfoo=(\-a)
bar=(\-b x \-c y \-c z)\fP
.fi
.RE
.PP
آرگومان‌ها از `\fBbaz\fP\&' به بعد استفاده نخواهند شد\&.
.PP
به عنوان مثالی برای گزینه \fB\-E\fP، دستور زیر را در نظر بگیرید:
.PP
.RS
.nf
\fBset \-\- \-a x \-b y \-c z arg1 arg2
zparseopts \-E \-D b:=bar\fP
.fi
.RE
.PP
تأثیری به صورت زیر دارد:
.PP
.RS
.nf
\fBbar=(\-b y)
set \-\- \-a x \-c z arg1 arg2\fP
.fi
.RE
.PP
یعنی گزینه \fB\-b\fP و آرگومان‌های آن از پارامترهای مکانی برداشته شده و در آرایه \fBbar\fP قرار می‌گیرند\&.
.PP
گزینه \fB\-M\fP می‌تواند به صورت زیر استفاده شود:
.PP
.RS
.nf
\fBset \-\- \-a \-bx \-c y \-cz baz \-cend
zparseopts \-A bar \-M a=foo b+: c:=b\fP
.fi
.RE
.PP
تا اثری به صورت زیر داشته باشد:
.PP
.RS
.nf
\fBfoo=(\-a)
bar=(\-a \&'' \-b xyz)\fP
.fi
.RE
.RE