.TH "ZSHCALSYS" "1" "July 12, 2026" "zsh 5\&.9\&.2"
.SH "نام (NAME)"
zshcalsys \- سیستم تقویم zsh
.\" Yodl file: Zsh/calsys.yo
.SH "توضیحات (DESCRIPTION)"
.PP
این پوسته به همراه مجموعه‌ای از توابع برای جایگزینی و بهبود برنامه سنتی \fBcalendar\fP در یونیکس عرضه شده است؛ برنامه‌ای که رویدادهای قریب‌الوقوع یا آینده را به کاربر هشدار می‌دهد و جزئیات آن‌ها در یک فایل متنی (معمولاً \fBcalendar\fP در دایرکتوری خانگی کاربر) ذخیره می‌شود\&. نسخه‌ای که در اینجا ارائه شده است شامل سازوکاری برای هشدار دادن به کاربر هنگام سررسید یک رویداد است\&.
.PP
علاوه بر این، توابع \fBage\fP، \fBbefore\fP و \fBafter\fP ارائه شده‌اند که می‌توان از آن‌ها در توصیف‌گر تطبیق مسیر (glob qualifier) استفاده کرد؛ آن‌ها امکان انتخاب فایل‌ها را بر اساس زمان تغییراتشان فراهم می‌کنند\&.
.PP
ابتدا قالب فایل \fBcalendar\fP و تاریخ‌های مورد استفاده در آن و در تابع \fBage\fP شرح داده شده و سپس توابعی که می‌توان برای بررسی و تغییر فایل \fBcalendar\fP فراخوانی کرد، توضیح داده می‌شوند\&.
.PP
توابع موجود در اینجا به در دسترس بودن ماژول \fBzsh/datetime\fP وابسته هستند که معمولاً همراه پوسته نصب می‌شود\&. تابع کتابخانه‌ای \fBstrptime()\fP باید در دسترس باشد؛ این تابع در بیشتر سیستم‌عامل‌های امروزی موجود است\&.
.PP
.PP
.SH "قالب‌های فایل و تاریخ (FILE AND DATE FORMATS)"
.PP
.SS "قالب فایل تقویم (Calendar File Format)"
.PP
فایل گاه‌شمار به‌طور پیش‌فرض \fB~/calendar\fP است\&. این مقدار را می‌توان از طریق شیوه (style) \fBcalendar\-file\fP پیکربندی کرد، به بخش STYLES در زیر مراجعه کنید\&. قالب پایه‌ای شامل مجموعه‌ای از خطوط مجزا و بدون تورفتگی است که هر یک شامل مشخصات تاریخ و زمان و به دنبال آن شرح رویداد است\&.
.PP
بهبودهای گوناگونی برای این قالب بر اساس نحو حالت گاه‌شمار Emacs پشتیبانی می‌شود\&. یک خط دارای تورفتگی نشان‌دهنده خط ادامه‌داری است که شرح رویداد را از خط قبلی ادامه می‌دهد (توجه داشته باشید که تاریخ را نمی‌توان به این روش ادامه داد)\&. علامت آمپرسند (\fB&\fP) در ابتدای خط برای سازگاری نادیده گرفته می‌شود\&.
.PP
یک خط دارای تورفتگی که نخستین نویسه غیرفاصله‌ای آن \fB#\fP باشد، همراه با مدخل تقویم نمایش داده نمی‌شود، اما همچنان برای استخراج اطلاعات پویش می‌شود\&. از این ویژگی می‌توان برای پنهان کردن اطلاعاتی استفاده کرد که برای سیستم گاه‌شمار مفید است اما برای کاربر کاربردی ندارد، مانند شناسه یکتای مورد استفاده توسط \fBcalendar_add\fP\&.
.PP
افزونه Emacs مبنی بر اینکه یک تاریخ بدون شرح می‌تواند به چندین رویداد بعدی در زمان‌های مختلف اشاره کند، پشتیبانی نمی‌شود\&.
.PP
مگر اینکه شیوه \fBdone\-file\fP تغییر کرده باشد، هر رویدادی که پردازش شده است به فایلی با همان نام فایل تقویم با پسوند \fB\&.done\fP الصاق می‌شود که بنابراین به‌طور پیش‌فرض \fB~/calendar\&.done\fP خواهد بود\&.
.PP
یک نمونه در زیر نشان داده شده است\&.
.PP
.SS "قالب تاریخ (Date Format)"
.PP
قالب تاریخ و زمان به گونه‌ای طراحی شده است که انعطاف‌پذیری را بدون ایجاد ابهام فراهم کند\&. (کلمات «date» و «time» هر دو در مستندات زیر به کار رفته‌اند؛ مگر در مواردی که صراحتاً ذکر شده باشد، این مفهوم بیانگر رشته‌ای است که می‌تواند شامل مشخصات هر دو، یعنی تاریخ و زمان باشد\&.) توجه داشته باشید که هیچ پشتیبانی از بومی‌سازی وجود ندارد؛ نام‌های ماه‌ها و روزها باید به زبان انگلیسی باشند و نویسه‌های جداکننده ثابت هستند\&. تطبیق نسبت به بزرگی و کوچکی حروف حساس نیست، و تنها سه حرف اول نام‌ها اهمیت دارند، اگرچه به عنوان یک حالت خاص، شکلی که با «month» آغاز شود با «Monday» تطبیق داده نمی‌شود\&. علاوه بر این، منطقه‌های زمانی پشتیبانی نمی‌شوند؛ تمام زمان‌ها محلی فرض می‌شوند\&.
.PP
توصیه می‌شود که کاربران به جای سرک کشیدن به پیچیدگی‌های سیستم، قالب تاریخی را که برایشان طبیعی‌تر است یافته و از همان استفاده کنند\&. این کار از خطاهای غیرمنتظره جلوگیری می‌کند\&. چندین نکته کلیدی باید مورد توجه قرار گیرد\&.
.PP
.PD 0
.TP
.PD
\(bu
به‌ویژه، به ابهام میان \fImonth\fP\fB/\fP\fIday\fP\fB/\fP\fIyear\fP و \fIday\fP\fB/\fP\fImonth\fP\fB/\fP\fIyear\fP هنگامی که ماه عددی است توجه داشته باشید؛ در صورت امکان باید از این قالب‌ها اجتناب کرد\&. جایگزین‌های فراوانی در دسترس هستند\&.
.TP
\(bu
سال باید برای جلوگیری از ابهام به‌طور کامل ذکر شود، و تنها سال‌های بین 1900 تا 2099 (شامل خود آن‌ها) تطبیق داده می‌شوند\&.
.PP
موارد زیر چند نمونه مشخص را نشان می‌دهند؛ کاربرانی که در اینجا قالبی متناسب با سلیقه خود می‌یابند و خود را درگیر پیچیدگی‌های نگارش نمی‌کنند، می‌توانند از شرح کامل صرف‌نظر کنند\&. از آنجا که تاریخ‌ها و زمان‌ها به‌طور جداگانه تطبیق داده می‌شوند (حتی اگر زمان در دل تاریخ قرار گرفته باشد)، هر قالب تاریخی را می‌توان با هر قالبی برای زمان روز ترکیب کرد، به شرطی که جداکننده‌ها واضح باشند (فاصله‌ها، دونقطه‌ها، ویرگول‌ها)\&.
.PP
.RS
.nf
\fB2007/04/03 13:13
2007/04/03:13:13
2007/04/03 1:13 pm
3rd April 2007, 13:13
April 3rd 2007 1:13 p\&.m\&.
Apr 3, 2007 13:13
Tue Apr 03 13:13:00 2007
13:13 2007/apr/3\fP
.fi
.RE
.PP
قواعد دقیق‌تر در ادامه آمده است\&.
.PP
زمان‌ها پیش از تاریخ‌ها تجزیه و استخراج می‌شوند\&. آن‌ها برای جداسازی ساعت و دقیقه باید از دونقطه استفاده کنند، اگرچه در صورت وجود ثانیه، نقطه پیش از آن مجاز است\&. این امر قالب‌های زمان را به موارد زیر محدود می‌کند:
.PP
.PD 0
.TP
.PD
\(bu
\fIHH\fP\fB:\fP\fIMM\fP[\fB:\fP\fISS\fP[\fB\&.\fP\fIFFFFF\fP]] [\fBam\fP|\fBpm\fP|\fBa\&.m\&.\fP|\fBp\&.m\&.\fP]
.TP
\(bu
\fIHH\fP\fB:\fP\fIMM\fP\fB\&.\fP\fISS\fP[\fB\&.\fP\fIFFFFF\fP] [\fBam\fP|\fBpm\fP|\fBa\&.m\&.\fP|\fBp\&.m\&.\fP]
.PP
در اینجا، قلاب‌ها نشان‌دهنده عناصر اختیاری هستند که احتمالاً دارای گزینه‌های جایگزین می‌باشند\&. کسر ثانیه شناسایی می‌شود اما نادیده گرفته خواهد شد\&. برای زمان‌های مطلق (قالب معمولی مورد نیاز فایل \fBcalendar\fP و توابع \fBage\fP، \fBbefore\fP و \fBafter\fP) قید تاریخ اجباری است اما زمان روز اختیاری است؛ زمان بازگردانده‌شده در آغاز تاریخ خواهد بود\&. یک حالت استثنا مجاز است: اگر \fBa\&.m\&.\fP یا \fBp\&.m\&.\fP یا یکی از گونه‌های آن‌ها وجود داشته باشد، ذکر ساعت بدون دقیقه مجاز است، مانند \fB3 p\&.m\&.\fP\&.
.PP
منطقه‌های زمانی پردازش نمی‌شوند، هرچند اگر منطقه‌ای به دنبال مشخصات زمان تطبیق داده شود، حذف خواهد شد تا امکان تجزیه تاریخ پیرامون آن فراهم شود\&. این اتفاق تنها در صورتی رخ می‌دهد که قالب منطقه زمانی بیش از حد غیرمعمول نباشد\&. موارد زیر نمونه‌هایی از شکل‌های قابل فهم هستند:
.PP
.RS
.nf
\fB+0100
GMT
GMT\-7
CET+1CDT\fP
.fi
.RE
.PP
هر بخشی از منطقه زمانی که عددی نیست باید دقیقاً سه حرف بزرگ در نام خود داشته باشد\&.
.PP
تاریخ‌ها دچار ابهام میان \fIDD\fP\fB/\fP\fIMM\fP\fB/\fP\fIYYYY\fP و \fIMM\fP\fB/\fP\fIDD\fP\fB/\fP\fIYYYY\fP هستند\&. توصیه می‌شود در تاریخ‌های کاملاً عددی از این شکل خودداری شود، اما استفاده از اعداد ترتیبی، مانند \fB3rd/04/2007\fP، ابهام را برطرف می‌کند زیرا عدد ترتیبی همواره به عنوان روز ماه تجزیه می‌شود\&. سال‌ها باید چهاررقمی باشند (و دو رقم نخست باید \fB19\fP یا \fB20\fP باشد)؛ \fB03/04/08\fP شناخته نمی‌شود\&. سایر اعداد می‌توانند دارای صفر پیشرو باشند، اما اجباری نیست\&. موارد زیر پشتیبانی می‌شوند:
.PP
.PD 0
.TP
.PD
\(bu
\fIYYYY\fP\fB/\fP\fIMM\fP\fB/\fP\fIDD\fP
.TP
\(bu
\fIYYYY\fP\fB\-\fP\fIMM\fP\fB\-\fP\fIDD\fP
.TP
\(bu
\fIYYYY\fP\fB/\fP\fIMNM\fP\fB/\fP\fIDD\fP
.TP
\(bu
\fIYYYY\fP\fB\-\fP\fIMNM\fP\fB\-\fP\fIDD\fP
.TP
\(bu
\fIDD\fP[\fBth\fP|\fBst\fP|\fBrd\fP] \fIMNM\fP[\fB,\fP] [ \fIYYYY\fP ]
.TP
\(bu
\fIMNM\fP \fIDD\fP[\fBth\fP|\fBst\fP|\fBrd\fP][\fB,\fP] [ \fIYYYY\fP ]
.TP
\(bu
\fIDD\fP[\fBth\fP|\fBst\fP|\fBrd\fP]\fB/\fP\fIMM\fP[\fB,\fP] \fIYYYY\fP
.TP
\(bu
\fIDD\fP[\fBth\fP|\fBst\fP|\fBrd\fP]\fB/\fP\fIMM\fP\fB/\fP\fIYYYY\fP
.TP
\(bu
\fIMM\fP\fB/\fP\fIDD\fP[\fBth\fP|\fBst\fP|\fBrd\fP][\fB,\fP] \fIYYYY\fP
.TP
\(bu
\fIMM\fP\fB/\fP\fIDD\fP[\fBth\fP|\fBst\fP|\fBrd\fP]\fB/\fP\fIYYYY\fP
.PP
در اینجا، \fIMNM\fP حداقل سه حرف اول از نام ماه است که بدون حساسیت به بزرگی و کوچکی حروف تطبیق داده می‌شود\&. باقی‌مانده نام ماه می‌تواند ظاهر شود اما محتوای آن بی‌اهمیت است؛ بنابراین عباراتی چون janissary، febrile، martial، apricot، maybe، junta و غیره بدون مشکل مدیریت می‌شوند\&.
.PP
در جاهایی که سال به صورت اختیاری نشان داده شده است، سال جاری فرض می‌شود\&. تنها دو حالت از این دست وجود دارد، به شکل \fBJun 20\fP یا \fB14 September\fP (تنها دو شکل متداول، به جز «the» در برخی گونه‌های زبان انگلیسی که در حال حاضر پشتیبانی نمی‌شود)\&. البته چنین تاریخ‌هایی در آینده مبهم خواهند شد، بنابراین در حالت ایده‌آل باید از آن‌ها خودداری شود\&..PP
زمان‌ها می‌توانند پس از تاریخ‌ها با یک دونقطه (کولون) بیایند، مانند \fB1965/07/12:09:45\fP؛ این به منظور فراهم کردن قالبی بدون نویسه فاصله‌گذاری (whitespace) است\&. استفاده از ویرگول و فاصله‌گذاری نیز مجاز است، مانند \fB1965/07/12, 09:45\fP\&. در حال حاضر ترتیب این جداکننده‌ها بررسی نمی‌شود، بنابراین قالب‌های غیرمنطقی مانند \fB1965/07/12, : ,09:45\fP نیز تطبیق داده خواهند شد\&. برای سادگی، چنین حالت‌هایی در فهرست بالا نمایش داده نشده‌اند\&. در غیر این صورت، یک زمان تنها در صورتی به عنوان وابسته به تاریخ شناخته می‌شود که میان آن‌ها تنها فاصله‌گذاری باشد، یا اینکه زمان درون تاریخ گنجانده شده باشد\&.
.PP
روزهای هفته معمولاً بررسی (اسکن) نمی‌شوند، اما اگر تنها در آغاز الگوی تاریخ ظاهر شوند نادیده گرفته خواهند شد\&. با این حال، در زمینه‌هایی که تعیین تاریخ‌ها نسبت به امروز کاربرد دارد، می‌توان روزهای هفته را بدون هیچ مشخصه تاریخی دیگری ارائه داد\&. روز فرض می‌شود که یا امروز است یا در طول هفته گذشته\&. به همین ترتیب، کلمات \fByesterday\fP، \fBtoday\fP و \fBtomorrow\fP نیز پردازش می‌شوند\&. تمامی تطبیق‌ها بدون حساسیت به حروف بزرگ و کوچک (case\-insensitive) هستند\&. بنابراین اگر امروز دوشنبه (\fBMonday\fP) باشد، \fBSunday\fP معادل با \fByesterday\fP است، \fBMonday\fP معادل با \fBtoday\fP است، اما \fBTuesday\fP تاریخی مربوط به شش روز پیش را می‌دهد\&. این ویژگی معمولاً در فایل تقویم چندان کاربردی نیست\&. تاریخ‌ها در این قالب می‌توانند با یک مشخصه زمان ترکیب شوند؛ برای نمونه \fBTomorrow, 8 p\&.m\&.\fP\&.
.PP
برای نمونه، قالب استاندارد تاریخ:
.PP
.RS
.nf
\fBFri Aug 18 17:00:48 BST 2006\fP
.fi
.RE
.PP
با تطبیق \fIHH\fP\fB:\fP\fIMM\fP\fB:\fP\fISS\fP و حذف آن به همراه منطقه زمانی تطبیق‌یافته (اما استفاده‌نشده) پردازش می‌شود\&. این کار باقی‌مانده زیر را بر جای می‌گذارد:
.PP
.RS
.nf
\fBFri Aug 18 2006\fP
.fi
.RE
.PP
\fBFri\fP نادیده گرفته شده و مابقی طبق قوانین استاندارد تطبیق داده می‌شود\&.
.PP
.SS "قالب زمان نسبی (Relative Time Format)"
.PP
در جاهای مشخصی زمان‌های نسبی پردازش می‌شوند\&. در اینجا تاریخ مجاز نیست؛ در عوض ترکیبی از دوره‌های مختلف پشتیبانی‌شده به همراه یک زمان اختیاری مجاز است\&. دوره‌ها باید به ترتیب از پرارزش‌ترین به کم‌ارزش‌ترین مرتب شده باشند\&.
.PP
در برخی موارد، زمانی که یک تاریخ لنگر (anchor date) وجود دارد، محاسبات دقیق‌تری امکان‌پذیر است: آفست‌های ماه‌ها یا سال‌ها به جای گرد شدن، روز درستی را برمی‌گزینند، و می‌توان روز خاصی از ماه را مانند `(1st Friday)\&' و غیره انتخاب کرد، همان‌طور که در ادامه با جزئیات بیشتر شرح داده شده است\&.
.PP
لنگرها در موارد زیر در دسترس هستند\&. اگر یک یا دو زمان به تابع \fBcalendar\fP ارسال شود، زمان آغاز به عنوان یک لنگر برای زمان پایان عمل می‌کند، به شرطی که زمان پایان نسبی باشد (حتی اگر زمان آغاز ضمنی باشد)\&. هنگام بررسی فایل‌های تقویم، رویداد زمان‌بندی‌شده‌ای که بررسی می‌شود، زمان هشدار را هنگامی که صراحتاً با کلیدواژه \fBWARN\fP مشخص شده باشد مبنا (لنگر) قرار می‌دهد؛ به همین ترتیب، رویداد زمان‌بندی‌شده یک دوره تکرار را هنگامی که با کلیدواژه \fBRPT\fP مشخص شده باشد لنگر قرار می‌دهد، به‌طوری که مشخصاتی مانند \fBRPT 2 months, 3rd Thursday\fP به درستی پردازش شوند\&. در نهایت، آرگومان \fB\-R\fP برای \fBcalendar_scandate\fP مستقیماً یک لنگر برای محاسبات نسبی فراهم می‌کند\&.
.PP
دوره‌های قابل پردازش، به همراه اختصارات ممکن عبارتند از:
.PP
.PD 0
.TP
.PD
سال‌ها (Years)
\fByears\fP, \fByrs\fP, \fBys\fP, \fByear\fP, \fByr\fP, \fBy\fP, \fByearly\fP\&.
یک سال برابر با 365\&.25 روز است مگر اینکه لنگری وجود داشته باشد\&.
.TP
ماه‌ها (Months)
\fBmonths\fP, \fBmons\fP, \fBmnths\fP, \fBmths\fP, \fBmonth\fP, \fBmon\fP,
\fBmnth\fP, \fBmth\fP, \fBmonthly\fP\&.  توجه داشته باشید که \fBm\fP, \fBms\fP, \fBmn\fP, \fBmns\fP
مبهم هستند و پردازش \fIنمی‌شوند\fP\&.  یک ماه دوره‌ای
۳۰ روزه است نه یک ماه تقویمی، مگر اینکه لنگری وجود داشته باشد\&.
.TP
هفته‌ها (Weeks)
\fBweeks\fP, \fBwks\fP, \fBws\fP, \fBweek\fP, \fBwk\fP, \fBw\fP, \fBweekly\fP
.TP
روزها (Days)
\fBdays\fP, \fBdys\fP, \fBds\fP, \fBday\fP, \fBdy\fP, \fBd\fP, \fBdaily\fP
.TP
ساعت‌ها (Hours)
\fBhours\fP, \fBhrs\fP, \fBhs\fP, \fBhour\fP, \fBhr\fP, \fBh\fP, \fBhourly\fP
.TP
دقیقه‌ها (Minutes)
\fBminutes\fP, \fBmins\fP, \fBminute\fP, \fBmin\fP، اما \fIنه\fP \fBm\fP،
\fBms\fP, \fBmn\fP یا \fBmns\fP
.TP
ثانیه‌ها (Seconds)
\fBseconds\fP, \fBsecs\fP, \fBss\fP, \fBsecond\fP, \fBsec\fP, \fBs\fP
.PP
فاصله‌های میان اعداد اختیاری هستند، اما میان آیتم‌ها الزامی می‌باشند، هرچند می‌توان از ویرگول نیز (با یا بدون فاصله) استفاده کرد\&.
.PP
شکل‌های \fByearly\fP تا \fBhourly\fP امکان حذف عدد را می‌دهند؛ در این حالت فرض می‌شود عدد ۱ است\&. برای نمونه، \fB1 d\fP و \fBdaily\fP معادل یکدیگرند\&. توجه داشته باشید که استفاده از آن شکل‌ها همراه با اسامی جمع گیج‌کننده است؛ \fB2 yearly\fP معادل \fB2 years\fP است، \fIنه\fP دو بار در سال، بنابراین توصیه می‌شود که آن‌ها تنها بدون عدد به کار روند\&.
.PP
هنگامی که زمان لنگر وجود دارد، یک قابلیت افزوده برای مدیریت رویدادهای منظم در قالب «\fIn\fPامین \fIروز مشخص\fP از ماه» وجود دارد\&. چنین مشخصه‌ای باید بلافاصله پس از هر مشخصه سال و ماه، اما پیش از هر زمان از روز بیاید، و باید در قالب \fIn\fP(\fBth\fP|\fBst\fP|\fBrd\fP) \fIday\fP باشد؛ برای نمونه \fB1st Tuesday\fP یا \fB3rd Monday\fP\&. مانند جاهای دیگر، روزها بدون حساسیت به حروف بزرگ و کوچک تطبیق داده می‌شوند، باید به زبان انگلیسی باشند، و تنها سه حرف نخست معنادار است، جز اینکه شکلی که با `month\&' آغاز می‌شود با `Monday' تطبیق نمی‌یابد\&. هیچ تلاشی برای پاک‌سازی (اعتبارسنجی) تاریخ حاصل انجام نمی‌شود؛ تلاش برای گنجاندن رخدادهای بیش از حد در یک ماه، روز را به ماه بعد منتقل خواهد کرد (اما به شیوه‌ای بدیهی، با حفظ روز درست هفته)\&.
.PP
در اینجا چند مثال آورده شده است:
.PP
.RS
.nf
\fB30 years 3 months 4 days 3:42:41
14 days 5 hours
Monthly, 3rd Thursday
4d,10hr\fP
.fi
.RE
.PP.SS "مثال (Example)"
.PP
در اینجا نمونه‌ای از یک فایل تقویم آورده شده است\&. این فایل همان‌گونه که در بالا توصیه شد، از یک قالب تاریخ یکدست استفاده می‌کند\&.
.PP
.RS
.nf
\fBFeb 1, 2006 14:30 Pointless bureaucratic meeting
Mar 27, 2006 11:00 Mutual recrimination and finger pointing
  Bring water pistol and waterproofs
Mar 31, 2006 14:00 Very serious managerial pontification
  # UID 12C7878A9A50
Apr 10, 2006 13:30 Even more pointless blame assignment exercise WARN 30 mins
May 18, 2006 16:00 Regular moaning session RPT monthly, 3rd Thursday\fP
.fi
.RE
.PP
مدخل دوم دارای یک خط ادامه‌دار است\&. مدخل سوم خط ادامه‌ای دارد که هنگام نمایش مدخل نشان داده نخواهد شد، اما شناسهٔ یکتا هنگام به‌روزرسانی رویداد توسط تابع \fBcalendar_add\fP به کار خواهد رفت\&. مدخل چهارم ۳۰ دقیقه پیش از رویداد هشداری ایجاد می‌کند (تا بتوانید خود را به‌خوبی آماده کنید)\&. مدخل پنجم پس از یک ماه در سومین پنج‌شنبه، یعنی ۱۵ ژوئن ۲۰۰۶، در همان ساعت تکرار می‌شود\&.
.PP
.SH "توابع کاربر (USER FUNCTIONS)"
.PP
این بخش توابعی را شرح می‌دهد که برای فراخوانی مستقیم توسط کاربر طراحی شده‌اند\&. بخش نخست توابع مرتبط با تقویم کاربر را توصیف می‌کند؛ بخش دوم استفاده در توصیف‌کننده‌های glob را شرح می‌دهد\&.
.PP
.SS "توابع سامانه تقویم (Calendar system functions)"
.PP
.PD 0

.TP
.PD 0
\fBcalendar \fP[ \fB\-abdDsv\fP ] [ \fB\-C\fP \fIcalfile\fP ] [ \fB\-n\fP \fInum\fP ] [ \fB\-S\fP \fIshowprog\fP ]
.TP
.PD 0
\fB         \fP[ [ \fIstart\fP ] \fIend\fP ]
.TP
.PD 0
\fBcalendar \-r\fP [ \fB\-abdDrsv\fP ] [ \fB\-C\fP \fIcalfile\fP ] [ \fB\-n\fP \fInum\fP ] [ \fB\-S\fP \fIshowprog\fP ]
.TP
.PD
\fB         \fP[ \fIstart\fP ]
نمایش رویدادها در تقویم\&.
.RS
.PP
بدون هیچ آرگومانی، رویدادها را از آغاز امروز تا پایان روز کاریِ بعد از امروز نمایش می‌دهد\&. به بیان دیگر، اگر امروز جمعه، شنبه یا یکشنبه باشد، رویدادها را تا پایان دوشنبهٔ بعد نشان می‌دهد؛ در غیر این صورت، امروز و فردا را نمایش می‌دهد\&.
.PP
اگر \fIend\fP مشخص شود، رویدادها را از آغاز امروز تا زمان و تاریخ داده‌شده نشان می‌دهد، که در قالب توصیف‌شده در بخش پیشین است\&. توجه داشته باشید که اگر این مقدار یک تاریخ باشد، زمان برابر با نیمه‌شب در آغاز آن تاریخ فرض می‌شود، به طوری که در عمل تمام رویدادهای پیش از تاریخ داده‌شده را نمایش می‌دهد\&.
.PP
مقدار \fIend\fP می‌تواند با یک \fB+\fP آغاز شود، که در این صورت باقی مشخصات یک قالب زمان نسبی طبق توضیحات بخش پیشین خواهد بود که بازهٔ زمانی از زمان شروع را برای گنجانده شدن مشخص می‌کند\&.
.PP
اگر \fIstart\fP نیز داده شود، رویدادها را از آن زمان و تاریخ آغاز نمایش می‌دهد\&. کلمهٔ \fBnow\fP می‌تواند برای مشخص کردن زمان فعلی استفاده شود\&.
.PP
برای پیاده‌سازی یک هشدار هنگام سررسید رویدادها، عبارت \fBcalendar \-s\fP را در فایل \fB~/\&.zshrc\fP خود قرار دهید\&.
.PP
گزینه‌ها:
.PP
.PD 0
.TP
.PD
\fB\-a\fP
نمایش تمام موارد در تقویم، بدون در نظر گرفتن \fBstart\fP و \fBend\fP\&.
.TP
\fB\-b\fP
مختصر: خطوط ادامه (یعنی خطوط تورفته پس از خط شامل تاریخ/زمان) نمایش داده نشوند، تنها خط نخست نشان داده شود\&.
.TP
\fB\-B\fP \fIlines\fP
مختصر: نمایش حداکثر \fIlines\fP خط نخست از مدخل تقویم\&. `\fB\-B 1\fP\&' معادل `\fB\-b\fP' است\&.
.TP
\fB\-C\fP \fIcalfile\fP
مشخص کردن صریح یک فایل تقویم به جای مقدار شیوهٔ \fBcalendar\-file\fP یا مقدار پیش‌فرض \fB~/calendar\fP\&.
.TP
\fB\-d\fP
انتقال هرگونه رویداد سپری‌شده از فایل تقویم به فایل «done»، طبق شیوهٔ \fBdone\-file\fP یا پیش‌فرض که همان فایل تقویم با افزودن پسوند \fB\&.done\fP است\&. این گزینه به صورت ضمنی توسط گزینهٔ \fB\-s\fP اعمال می‌شود\&.
.TP
\fB\-D\fP
گزینهٔ \fB\-d\fP را خاموش می‌کند، حتی اگر گزینهٔ \fB\-s\fP نیز وجود داشته باشد\&.
.TP
\fB\-n\fP \fInum\fP, \fB\-\fP\fInum\fP
نمایش حداقل \fInum\fP رویداد، در صورت وجود در فایل تقویم، بدون در نظر گرفتن \fBstart\fP و \fBend\fP\&.
.TP
\fB\-r\fP
نمایش همهٔ موارد باقی‌مانده در تقویم، با نادیده گرفتن زمان پایان (\fIend\fP) داده‌شده\&. زمان آغاز (\fIstart\fP) رعایت می‌شود؛ هر آرگومان داده‌شده به عنوان زمان \fIstart\fP در نظر گرفته می‌شود\&.
.TP
\fB\-s\fP
استفاده از دستور \fBsched\fP پوسته برای زمان‌بندی یک رویداد زمان‌دار که هنگام سررسید رویداد به کاربر هشدار می‌دهد\&. توجه داشته باشید که دستور \fBsched\fP تنها در صورتی اجرا می‌شود که پوسته در یک اعلان تعاملی باشد؛ یک وظیفهٔ پیش‌زمینه مانع از اجرای وظیفهٔ زمان‌بندی‌شده تا زمان پایان آن می‌شود\&.
.RS
.PP
رویداد زمان‌دار معمولاً برنامهٔ \fBcalendar_show\fP را برای نمایش رویداد اجرا می‌کند، همان‌طور که در بخش توابع ابزاری (UTILITY FUNCTIONS) در زیر شرح داده شده است\&.
.PP
به‌طور پیش‌فرض، هشدار رویداد پنج دقیقه پیش از سررسید آن نشان داده می‌شود\&. دورهٔ هشدار را می‌توان با شیوهٔ \fBwarn\-time\fP یا برای یک مدخل تکی در تقویم با گنجاندن \fBWARN\fP \fIreltime\fP در خط نخست مدخل پیکربندی کرد، که در آن \fIreltime\fP یکی از قالب‌های معمول زمان نسبی است\&.
.PP
یک رویداد تکرارشونده را می‌توان با گنجاندن \fBRPT\fP \fIreldate\fP در خط نخست مدخل مشخص کرد\&. پس از نمایش رویداد زمان‌بندی‌شده، در زمانی به اندازهٔ \fIreldate\fP پس از رویداد کنونی دوباره در فایل تقویم وارد خواهد شد\&. توجه داشته باشید که در حال حاضر این تنها استفاده از شمارش تکرار است، به طوری که تا پیش از سپری شدن رویداد قبلی، امکان پرس‌وجو از زمان‌بندی برای رخداد مجدد یک رویداد در تقویم وجود ندارد\&.
.PP
اگر \fBRPT\fP استفاده شود، همچنین می‌توان مشخص کرد که تکرارهای خاصی از یک رویداد باززمان‌بندی یا لغو شوند\&. این کار با کلیدواژهٔ \fBOCCURRENCE\fP انجام می‌شود، که به دنبال آن فاصلهٔ خالی و سپس تاریخ و زمان رخداد در توالی منظم می‌آید، و در ادامه فاصلهٔ خالی و سپس تاریخ و زمان رویداد باززمان‌بندی‌شده یا دقیقاً رشتهٔ \fBCANCELLED\fP قرار می‌گیرد\&. در این حالت، تاریخ و زمان باید دقیقاً در قالب «تاریخ با زمان محلی» استفاده‌شده توسط نوع MIME با شناسهٔ \fBtext/calendar\fP (RFC 2445) باشد: \fI<YYYY><MM><DD>\fP\fBT\fP\fI<hh><mm><ss>\fP (به وجود نویسهٔ عینی \fBT\fP توجه کنید)\&. کلمهٔ اول (تکرار منظم) می‌تواند چیزی غیر از یک تاریخ/زمان معتبر باشد تا نشان دهد رویداد علاوه بر توالی عادی است؛ قراردادی که ظاهر قالب‌بندی را حفظ می‌کند \fBXXXXXXXXTXXXXXX\fP است\&.
.PP
افزون بر این، ثبت تکرار منظم بعدی سودمند است (زیرا در این صورت ممکن است تاریخ نمایش‌داده‌شده برای یک رویدادِ باززمان‌بندی‌شده باشد و بنابراین نتوان از آن برای محاسبهٔ توالی منظم استفاده کرد)\&. این موضوع با \fBRECURRENCE\fP و یک زمان یا تاریخ در همان قالب مشخص می‌شود\&. زمانی که \fBcalendar_add\fP با رویداد تکرارشونده‌ای برخورد کند که فاقد چنین نشانه‌ای است، بر پایهٔ تاریخ/زمان خط عنوان، چنین نشانه‌ای را اضافه می‌کند\&.
.PP
اگر از \fBcalendar_add\fP برای به‌روزرسانی رخدادها استفاده شود، کلیدواژهٔ \fBUID\fP که در آنجا شرح داده شده است باید هم در مدخل موجود و هم در رخداد اضافه‌شده وجود داشته باشد تا توالی‌های رویداد تکرارشونده شناسایی شوند\&.
.PP
برای نمونه،
.PP
.RS
.nf
\fBThu May 6, 2010 11:00 Informal chat RPT 1 week
  # RECURRENCE 20100506T110000
  # OCCURRENCE 20100513T110000 20100513T120000
  # OCCURRENCE 20100520T110000 CANCELLED\fP
.fi
.RE
.PP
رویدادی که در ساعت 11:00 روز ۱۳ مه ۲۰۱۰ رخ می‌دهد، یک ساعت دیرتر باززمان‌بندی می‌شود\&. رویدادی که یک هفته بعد رخ می‌دهد لغو می‌شود\&. رخدادها در یک خط ادامه که با نویسهٔ \fB#\fP آغاز می‌شود مشخص شده‌اند، بنابراین معمولاً به عنوان بخشی از رویداد نمایش داده نمی‌شوند\&. مانند جاهای دیگر، منطقه‌های زمانی در ساعت‌ها لحاظ نمی‌شوند\&. پس از وقوع رویداد بعدی، تاریخ/زمان خط عنوان `\fBThu May 13, 2010 12:00\fP\&' خواهد بود، در حالی که تاریخ/زمان \fBRECURRENCE\fP برابر با `\fB20100513T110000\fP\&' خواهد بود (توجه داشته باشید رویدادهای لغو شده و جابه‌جاشده در \fBRECURRENCE\fP به حساب نمی‌آیند، زیرا مشخص‌کنندهٔ تکرار منظم بعدی است، اما در تاریخ/زمان خط عنوان لحاظ می‌شوند)\&.
.PP
اجرای \fBcalendar \-s\fP برای باززمان‌بندی یک رویداد موجود (برای نمونه در صورتی که فایل تقویم تغییر کرده باشد) ایمن است، و همچنین اجرای آن در چندین نمونه از پوسته مشکلی ندارد، زیرا فایل تقویم هنگام استفاده قفل می‌شود\&.
.PP
به‌طور پیش‌فرض، رویدادهای منقضی‌شده به فایل «done» منتقل می‌شوند؛ گزینهٔ \fB\-d\fP را ببینید\&. برای جلوگیری از این موضوع از \fB\-D\fP استفاده کنید\&.
.RE
.TP
\fB\-S\fP \fIshowprog\fP
مشخص کردن صریح برنامه‌ای برای استفاده در نمایش رویدادها به جای مقدار شیوهٔ \fBshow\-prog\fP یا مقدار پیش‌فرض \fBcalendar_show\fP\&.
.TP
\fB\-v\fP
پرگو (Verbose): نمایش اطلاعات بیشتر دربارهٔ مراحل پردازش\&. این گزینه برای اطمینان از اینکه تابع تاریخ‌های موجود در فایل تقویم را با موفقیت تجزیه کرده است، مفید است\&.
.RE.TP
\fBcalendar_add\fP [ \fB\-BL\fP ] \fIevent\fP \&.\&.\&.
یک تک‌رویداد را در مکان مناسب به تقویم اضافه می‌کند\&.
رویداد می‌تواند همان‌طور که در بخش «Calendar File Format» در بالا توضیح داده شده است،
شامل چندین خط باشد\&.
استفاده از این تابع تضمین می‌کند که فایل تقویم به ترتیب تاریخ
و زمان مرتب شده است\&. همچنین تمهیدات ویژه‌ای را برای قفل کردن
فایل در حین تغییر آن در نظر می‌گیرد\&. تقویم قدیمی در فایلی
با پسوند \fB\&.old\fP باقی می‌ماند\&.
.RS
.PP
گزینه \fB\-B\fP نشان می‌دهد که پشتیبان‌گیری از فایل تقویم توسط فراخواننده
مدیریت می‌شود و نباید توسط \fBcalendar_add\fP انجام گیرد\&. گزینه
\fB\-L\fP نشان می‌دهد که \fBcalendar_add\fP نیازی به قفل کردن فایل تقویم
ندارد زیرا از قبل قفل شده است\&. این گزینه‌ها معمولاً مورد نیاز
کاربران نخواهند بود\&.
.PP
اگر شیوه \fBreformat\-date\fP فعال (true) باشد، تاریخ و زمان ورودی
جدید به قالب استاندارد تاریخ بازنویسی خواهد شد: توضیحات
این شیوه و شیوه \fBdate\-format\fP را ببینید\&.
.PP
این تابع می‌تواند از یک شناسه یکتا ذخیره‌شده با هر رویداد استفاده کند تا اطمینان
حاصل شود که به‌روزرسانی‌های رویدادهای موجود به‌درستی پردازش می‌شوند\&. ورودی
باید شامل کلمه \fBUID\fP، به دنبال آن فاصله خالی (whitespace)، و سپس کلمه‌ای
متشکل از ارقام هگزادسیمال با طول دلخواه باشد (تمام ارقام دارای اهمیت هستند،
از جمله صفرهای ابتدایی)\&. از آنجا که UID مستقیماً برای کاربر مفید نیست،
راحت‌تر است که آن را در یک خط ادامه‌دار تو رفته که با یک \fB#\fP شروع می‌شود
پنهان کنید، به عنوان مثال:
.PP
.RS
.nf
\fBAug 31, 2007 09:30  Celebrate the end of the holidays
  # UID 045B78A0\fP
.fi
.RE
.PP
خط دوم توسط تابع \fBcalendar\fP نمایش داده نخواهد شد\&.
.PP
امکان مشخص کردن کلیدواژه \fBRPT\fP به دنبال \fBCANCELLED\fP
به جای یک زمان نسبی وجود دارد\&. این کار باعث می‌شود هر رویداد یا مجموعه‌ای
از رویدادهای منطبق لغو شود (نیازی نیست رویداد اصلی برای لغو شدن با این روش،
به عنوان تکرارشونده علامت‌گذاری شده باشد)\&. برای تطبیق با یک رویداد موجود
در تقویم، یک \fBUID\fP مورد نیاز است\&.
.PP
\fBcalendar_add\fP تلاش خواهد کرد تکرارها و رخدادهای رویدادهای
تکرارشونده را همان‌طور که برای زمان‌بندی رویدادها توسط \fBcalendar \-s\fP
در بالا توضیح داده شد، مدیریت کند\&. برای زمان‌بندی مجدد یا لغو یک رویداد تکی،
\fBcalendar_add\fP باید با ورودی‌ای فراخوانی شود که شامل \fBUID\fP صحیح باشد
اما کلیدواژه \fBRPT\fP را شامل \fIنشود\fP، چرا که این مورد به این معنی در نظر
گرفته می‌شود که ورودی برای یک سری از رویدادهای تکرارشونده اعمال می‌شود
و در نتیجه تمام اطلاعات موجود را جایگزین می‌کند\&. هر رخدادِ زمان‌بندی‌مجددشده
یا لغوشده باید یک کلیدواژه \fBOCCURRENCE\fP در ورودی ارائه‌شده به
\fBcalendar_add\fP داشته باشد که در فایل تقویم ادغام خواهد شد\&. هرگونه ارجاع
موجود به رخداد جایگزین می‌شود\&. رخدادی که به یک رویداد معتبر موجود اشاره نمی‌کند،
به عنوان یک رخداد یک‌باره به همان ورودی تقویم افزوده می‌شود\&.
.RE
.TP
\fBcalendar_edit\fP
این تابع ویرایشگر کاربر را برای ویرایش فایل تقویم فراخوانی می‌کند\&. اگر
آرگومان‌هایی وجود داشته باشد، به عنوان ویرایشگر مورد استفاده در نظر گرفته می‌شوند
(نام فایل به دستورها الحاق می‌شود)؛ در غیر این صورت، ویرایشگر توسط
متغیر \fBVISUAL\fP (در صورت تنظیم)، وگرنه متغیر \fBEDITOR\fP تعیین می‌شود\&.
.RS
.PP
اگر زمان‌بند تقویم در حال اجرا بود، پس از ویرایش فایل،
\fBcalendar \-s\fP برای به‌روزرسانی آن فراخوانی می‌شود\&.
.PP
این تابع سیستم تقویم را در حین ویرایش قفل می‌کند\&.
بنابراین اگر هرگونه احتمال وقوع یک رویداد تقویم در این میان وجود داشته باشد،
باید برای ویرایش فایل تقویم از آن استفاده شود\&. توجه داشته باشید این امر
می‌تواند منجر به معلق ماندن شل دیگری که توابع تقویم در آن فعال است در انتظار
قفل شود، بنابراین لازم است در اسرع وقت از ویرایشگر خارج شوید\&.
.RE
.TP
\fBcalendar_parse\fP \fIcalendar\-entry\fP
این تابع درونی بخش‌های یک ورودی تقویم را که به عنوان تنها
آرگومان ارسال شده است، تجزیه و تحلیل می‌کند\&. در صورتی که آرگومان
نتواند به عنوان ورودی تقویم تجزیه شود، تابع وضعیت ۱ و در صورت نادرست
بودن تعداد آرگومان‌های ارسالی، وضعیت ۲ را برمی‌گرداند؛ همچنین پارامتر
\fBreply\fP را روی یک آرایه انجمنی خالی تنظیم می‌کند\&. در غیر این صورت،
وضعیت ۰ را برمی‌گرداند و عناصر آرایه انجمنی \fBreply\fP را به شرح زیر
تنظیم می‌نماید:
.RS
.PP
.PD 0
.TP
\fBtime\fP
زمان به عنوان رشته‌ای از ارقام با همان یکای \fB$EPOCHSECONDS\fP\&.
.TP
\fBschedtime\fP
زمان زمان‌بندی‌شده منظم\&. اگر این یک رویداد تکرارشونده باشد و رخداد بعدی
مجدداً زمان‌بندی شده باشد، این مقدار ممکن است با زمان واقعی رویداد (\fBtime\fP)
متفاوت باشد\&. در این حالت \fBtime\fP زمان واقعی و \fBschedtime\fP زمان
تکرار منظم قبل از تغییر را ارائه می‌دهد\&.
.TP
\fBtext1\fP
متن موجود در خط بدون شامل شدن تاریخ و زمان رویداد، اما شامل هرگونه
کلیدواژه و مقادیر \fBWARN\fP یا \fBRPT\fP\&.
.TP
\fBwarntime\fP
هر زمان هشداری که توسط کلیدواژه \fBWARN\fP به عنوان رشته‌ای از ارقام
شامل زمان هشدار با همان یکای \fB$EPOCHSECONDS\fP مشخص شده باشد\&. (توجه
داشته باشید که این یک زمان مطلق است، نه زمان نسبی ارسال‌شده\&.) در صورتی که
هیچ کلیدواژه و مقدار \fBWARN\fP منطبق نشود، تنظیم نمی‌شود\&.
.TP
\fBwarnstr\fP
رشته خام منطبق‌شده پس از کلیدواژه \fBWARN\fP، در غیر این صورت تنظیم نمی‌شود\&.
.TP
\fBrpttime\fP
هر زمان تکراری که توسط کلیدواژه \fBRPT\fP به عنوان رشته‌ای از ارقام
شامل زمان تکرار با همان یکای \fB$EPOCHSECONDS\fP مشخص شده باشد\&. (توجه
داشته باشید که این یک زمان مطلق است\&.) در صورتی که هیچ کلیدواژه و مقدار
\fBRPT\fP منطبق نشود، تنظیم نمی‌شود\&.
.TP
\fBschedrpttime\fP
رخداد زمان‌بندی‌شده بعدی به صورت منظم برای یک رویداد تکرارشونده قبل
از تغییر\&. این ممکن است با \fBrpttime\fP تفاوت داشته باشد، که زمان واقعی
رویدادی است که ممکن است از زمان معمول مجدداً زمان‌بندی شده باشد\&.
.TP
\fBrptstr\fP
رشته خام منطبق‌شده پس از کلیدواژه \fBRPT\fP، در غیر این صورت تنظیم نمی‌شود\&.
.TP
\fBtext2\fP
متن موجود در خط پس از حذف تاریخ و هرگونه کلیدواژه و مقادیر\&.
.RE
.PD
.PP
.TP
\fBcalendar_showdate\fP [ \fB\-r\fP ] [ \fB\-f\fP \fIfmt\fP ] \fIdate\-spec\fP \&.\&.\&.
مقدار \fIdate\-spec\fP داده‌شده تفسیر شده و تاریخ و زمان متناظر
چاپ می‌شود\&. اگر \fIdate\-spec\fP اولیه با یک \fB+\fP یا \fB\-\fP شروع
شود، به صورت نسبی نسبت به زمان فعلی در نظر گرفته می‌شود؛ \fIdate\-spec\fPهای
پس از مورد اول، به صورت نسبی نسبت به تاریخی که تا کنون محاسبه شده در نظر گرفته
می‌شوند و وجود \fB+\fP ابتدایی در آن حالت اختیاری است\&. این امکان را فراهم
می‌سازد تا از سیستم به عنوان یک ماشین‌حساب تاریخ استفاده شود\&. به عنوان مثال،
\fBcalendar_showdate \&'+1 month, 1st Friday\&'\fP تاریخ اولین جمعه ماه بعد
را نشان می‌دهد\&.
.RS
.PP
با گزینه \fB\-r\fP چیزی چاپ نمی‌شود، اما مقدار تاریخ و زمان بر حسب ثانیه
از مبدأ زمان (epoch) در پارامتر \fBREPLY\fP ذخیره می‌شود\&.
.PP
با گزینه \fB\-f\fP \fIfmt\fP قالب تبدیل تاریخ/زمان داده‌شده به \fBstrftime\fP
منتقل می‌شود؛ یادداشت‌های مربوط به شیوه \fBdate\-format\fP را در زیر ببینید\&.
.PP
به منظور جلوگیری از ابهام با مشخصه‌های تاریخ نسبی منفی، گزینه‌ها باید
در کلمات جداگانه قرار گیرند؛ به عبارت دیگر، \fB\-r\fP و \fB\-f\fP
نباید در یک کلمه ترکیب شوند\&.
.RE
.TP
\fBcalendar_sort\fP
فایل تقویم را به ترتیب تاریخ و زمان مرتب می‌کند\&. تقویم قدیمی در فایلی
با پسوند \fB\&.old\fP باقی می‌ماند\&.
.PP.SS "توصیف‌کننده‌های تطبیق الگو (Glob qualifiers)"
.PP
.PD 0
.TP
.PD
\fBage\fP
تابع \fBage\fP می‌تواند به صورت خودکار بارگذاری (autoload) شده و جدا از سامانه تقویم استفاده شود، اگرچه برای قالب‌بندی تاریخ از تابع \fBcalendar_scandate\fP استفاده می‌کند\&. این تابع به دستور توکار \fBzsh/stat\fP نیاز دارد، اما تنها از توکار \fBzstat\fP بهره می‌برد\&.
.RS
.PP
تابع \fBage\fP فایل‌هایی را که دارای زمان ویرایش معینی هستند برای استفاده به عنوان توصیف‌کننده تطبیق الگو (glob qualifier) انتخاب می‌کند\&. قالب تاریخ همان قالبی است که توسط سامانه تقویم پشتیبانی می‌شود و در بخش FILE AND DATE FORMATS در بالا توضیح داده شده است\&.
.PP
این تابع می‌تواند یک یا دو آرگومان دریافت کند، که می‌توان آن‌ها را مستقیماً به عنوان آرگومان، یا به طور جداگانه در قالب متغیرهای پوسته ارائه داد\&.
.PP
.RS
.nf
\fBprint *(e:age 2006/10/04 2006/10/09:)\fP
.fi
.RE
.PP
مثال بالا با تمامی فایل‌هایی که بین آغاز این دو تاریخ ویرایش شده‌اند تطبیق می‌یابد\&. آرگومان دوم همچنین می‌تواند یک زمان نسبی باشد که با یک \fB+\fP شروع می‌شود:
.PP
.RS
.nf
\fBprint *(e:age 2006/10/04 +5d:)\fP
.fi
.RE
.PP
مثال بالا معادل مثال قبلی است\&.
.PP
علاوه بر کاربرد ویژهٔ روزهای هفته، \fBtoday\fP و \fByesterday\fP، می‌توان زمان‌ها را بدون تاریخ نیز مشخص کرد؛ این زمان‌ها به امروز اعمال می‌شوند\&. بدیهی است که چنین کاربردهایی در حوالی نیمه‌شب مشکل‌ساز می‌شوند\&.
.PP
.RS
.nf
\fBprint *(e\-age 12:00 13:30\-)\fP
.fi
.RE
.PP
مثال بالا فایل‌های ویرایش‌شده در امروز بین ساعت ۱۲:۰۰ و ۱۳:۰۰ را نشان می‌دهد\&.
.PP
.RS
.nf
\fBprint *(e:age 2006/10/04:)\fP
.fi
.RE
.PP
مثال بالا با تمامی فایل‌های ویرایش‌شده در آن تاریخ مطابقت دارد\&. اگر آرگومان دوم حذف شود، دقیقاً ۲۴ ساعت پس از آرگومان اول در نظر گرفته می‌شود (حتی اگر آرگومان اول شامل ساعت باشد)\&.
.PP
.RS
.nf
\fBprint *(e\-age 2006/10/04:10:15 2006/10/04:10:45\-)\fP
.fi
.RE
.PP
مثال بالا زمان‌ها را مشخص می‌کند\&. توجه داشته باشید که فاصله خالی (whitespace) درون مشخصات زمان و تاریخ باید نقل‌قول (quote) شود تا اطمینان حاصل شود \fBage\fP آرگومان‌های صحیح را دریافت می‌کند؛ به همین دلیل از دونقطهٔ اضافی برای جداسازی تاریخ و زمان استفاده شده است\&.
.PP
.RS
.nf
\fBAGEREF=2006/10/04:10:15
AGEREF2=2006/10/04:10:45
print *(+age)\fP
.fi
.RE
.PP
این نمونه همان مثال قبلی را با استفاده از شکل دیگری از ارسال آرگومان نشان می‌دهد\&. تاریخ‌ها و زمان‌ها در متغیرهای \fBAGEREF\fP و \fBAGEREF2\fP تا زمان لغو (unset) معتبر می‌مانند، اما در صورت ارسال هر آرگومانی به عنوان آرگومان صریح به \fBage\fP بازنویسی می‌شوند\&. هرگونه آرگومان صریح باعث نادیده گرفته شدن هر دو متغیر می‌شود\&.
.PP
به جای تاریخ و زمان صریح، می‌توان با معرفی نام فایل به همراه یک دونقطه، از زمان ویرایش یک فایل به عنوان تاریخ و زمان برای هر یک از آرگومان‌ها استفاده کرد:
.PP
.RS
.nf
\fBprint *(e\-age :file1\-)\fP
.fi
.RE
.PP
با تمام فایل‌هایی تطبیق می‌یابد که در همان روز (۲۴ ساعت که از نیمه‌شب آغاز می‌شود) مربوط به \fBfile1\fP ایجاد شده‌اند\&.
.PP
.RS
.nf
\fBprint *(e\-age :file1 :file2\-)\fP
.fi
.RE
.PP
با تمام فایل‌هایی که نه زودتر از \fBfile1\fP و نه دیرتر از \fBfile2\fP ویرایش شده‌اند تطبیق می‌یابد؛ دقت در اینجا تا نزدیک‌ترین ثانیه است\&.
.RE
.TP
.PD 0
\fBafter\fP
.TP
.PD
\fBbefore\fP
توابع \fBafter\fP و \fBbefore\fP نسخه‌های ساده‌تری از \fBage\fP هستند که تنها یک آرگومان می‌گیرند\&. این آرگومان مشابه آرگومان \fBage\fP تجزیه می‌شود؛ اگر آرگومانی داده نشود، متغیر \fBAGEREF\fP بررسی می‌شود\&. همان‌طور که از نام این توابع پیداست، یک فایل در صورتی تطبیق می‌یابد که زمان ویرایش آن بعد یا قبل از زمان و تاریخ مشخص‌شده باشد\&. اگر تنها زمان مشخص شده باشد، تاریخ امروز در نظر گرفته می‌شود\&.
.RS
.PP
بنابراین دو مثال زیر معادل یکدیگر هستند:
.RS
.nf
\fBprint *(e\-after 12:00\-)
print *(e\-after today:12:00\-)\fP
.fi
.RE
.RE
.PP.SH "سبک‌ها (STYLES)"
.PP
سازوکار سبک در zsh با استفاده از دستور \fBzstyle\fP در
\fIzshmodules\fP(1)\& شرح داده شده است\&. این همان سازوکاری است
که در سامانهٔ تکمیل (completion) استفاده می‌شود\&.
.PP
تمام سبک‌های زیر در بافتار
\fB:datetime:\fP\fIfunction\fP\fB:\fP، برای نمونه \fB:datetime:calendar:\fP\& بررسی می‌شوند.
.PP
.PD 0
.TP
.PD
\fBcalendar\-file\fP
مکان تقویم اصلی\&. پیش‌فرض \fB~/calendar\fP است\&.
.TP
\fBdate\-format\fP
یک رشتهٔ قالب‌بندی \fBstrftime\fP (به \fIstrftime\fP(3) مراجعه کنید) به‌همراه افزونه‌های zsh
که در صورت تک‌رقمی بودن عدد، ارقام مختلف را بدون صفر یا فاصلهٔ ابتدایی ارائه می‌دهد،
همان‌طور که برای قالب اعلان \fB%D{\fP\fIstring\fP\fB}\fP در
بخش EXPANSION OF PROMPT SEQUENCES در \fIzshmisc\fP(1)\& شرح داده شده است.
.RS
.PP
این سبک برای قالب‌بندی تاریخ‌ها در خروجی \fBcalendar\fP (هم برای پشتیبانی
از گزینهٔ \fB\-v\fP و هم هنگام افزودن مجدد رویدادهای تکرارشونده به فایل تقویم)
و همچنین در \fBcalendar_showdate\fP به عنوان قالب نهایی خروجی استفاده می‌شود\&.
.PP
اگر این سبک تنظیم نشده باشد، مقدار پیش‌فرض مشابه با قالب استاندارد سیستم در
خروجی دستور \fBdate\fP خواهد بود (که با نام «قالب ctime» نیز شناخته می‌شود):
`\fB%a %b %d %H:%M:%S %Z %Y\fP\&'\&.
.RE
.TP
\fBdone\-file\fP
مکان فایلی که رویدادهای گذشته به آن ضمیمه می‌شوند\&.
پیش‌فرض، مکان فایل تقویم با پسوند \fB\&.done\fP است\&.
این سبک می‌تواند روی یک رشتهٔ خالی تنظیم شود که در این صورت فایلی
برای رویدادهای انجام‌شده نگهداری نخواهد شد\&.
.TP
\fBreformat\-date\fP
مقداری بولی که توسط \fBcalendar_add\fP استفاده می‌شود\&. اگر درست (true) باشد،
تاریخ و زمان مدخل‌های جدید اضافه‌شده به تقویم طبق قالب مشخص‌شده
توسط سبک \fBdate\-format\fP یا پیش‌فرض آن بازقالب‌بندی خواهد شد\&. تنها تاریخ و
زمان خود رویداد بازقالب‌بندی می‌شود؛ تاریخ‌ها و زمان‌های فرعی مانند
موارد مربوط به تکرار و زمان‌های هشدار دست‌نخورده باقی می‌مانند\&.
.TP
\fBshow\-prog\fP
برنامه‌ای که توسط \fBcalendar\fP برای نمایش رویدادها اجرا می‌شود\&. زمان
شروع و پایان رویدادهای درخواستی بر حسب ثانیه از مبدا زمان (epoch) به همراه
متن رویداد به آن ارسال خواهد شد\&. توجه داشته باشید که \fBcalendar \-s\fP از
زمان شروع و پایانی برابر با یکدیگر برای هشدار دادن دربارهٔ رویدادهای خاص استفاده می‌کند\&.
.RS
.PP
پیش‌فرض تابع \fBcalendar_show\fP است\&.
.RE
.TP
\fBwarn\-time\fP
مدت‌زمان پیش از رویداد که در آن یک هشدار نمایش داده می‌شود، در صورتی که
سطر اول رویداد شامل متن \fBEVENT\fP \fIreltime\fP نباشد\&.
پیش‌فرض ۵ دقیقه است\&.
.PP
.SH "توابع کمکی (UTILITY FUNCTIONS)"
.PP
.PD 0
.TP
.PD
\fBcalendar_lockfiles\fP
تلاش می‌کند فایل‌های ارائه‌شده در آرگومان را قفل کند\&. برای جلوگیری
از مشکلات قفل‌گذاری فایل‌های شبکه‌ای، این کار به روشی ویژه (ad hoc)
با تلاش برای ایجاد یک پیوند نمادین به فایل با نام
\fIfile\fP\fB\&.lockfile\fP انجام می‌شود\&. هیچ تابع سیستمی دیگری برای قفل کردن
استفاده نمی‌شود، بدین معنی که فایل توسط هر ابزاری که از این سازوکار
استفاده نمی‌کند قابل دسترسی و تغییر است\&. به‌ویژه، کاربر از ویرایش هم‌زمان
فایل تقویم منع نمی‌شود، مگر اینکه از \fBcalendar_edit\fP استفاده شود\&.
.RS
.PP
پیش از انصراف، سه بار برای قفل کردن فایل تلاش می‌شود\&. اگر پیمانهٔ
\fBzsh/zselect\fP در دسترس باشد، فواصل زمانی تلاش‌ها با تأخیر تصادفی (jitter)
همراه می‌شود تا احتمال تلاش مجدد هم‌زمان چند نمونه از تابع فراخواننده کاهش یابد\&.
.PP
فایل‌های قفل‌شده به آرایهٔ \fBlockfiles\fP ضمیمه می‌شوند که باید برای
فراخواننده محلی (local) باشد\&.
.PP
اگر تمام فایل‌ها با موفقیت قفل شوند، وضعیت صفر و در غیر این صورت وضعیت یک برگردانده می‌شود\&.
.PP
این تابع می‌تواند به عنوان یک تابع عمومی قفل‌گذاری فایل استفاده شود، گرچه
تنها در صورتی کار خواهد کرد که فقط از همین سازوکار برای قفل کردن فایل‌ها استفاده شود\&.
.RE
.TP
\fBcalendar_read\fP
این یک پشتیبان (backend) است که توسط توابع مختلف دیگر برای تجزیهٔ
فایل تقویم (که به عنوان تنها آرگومان ارسال می‌شود) به کار می‌رود\&. آرایهٔ
\fBcalendar_entries\fP روی فهرست رویدادهای موجود در فایل تنظیم می‌شود؛ هیچ
هرسی انجام نمی‌شود جز اینکه علامت‌های امپرسند (&) از ابتدای سطر
حذف می‌شوند\&. هر مدخل می‌تواند شامل چند سطر باشد\&.
.TP
\fBcalendar_scandate\fP
این یک تابع عمومی برای تجزیهٔ تاریخ‌ها و زمان‌هاست که می‌تواند
مستقل از سامانهٔ تقویم استفاده شود\&. آرگومان ورودی، مشخصات یک تاریخ یا زمان است
همان‌طور که در بخش FILE AND DATE FORMATS در بالا شرح داده شد\&. پارامتر \fBREPLY\fP
روی تعداد ثانیه‌های سپری‌شده از مبدا زمان (epoch) متناظر با آن تاریخ
یا زمان تنظیم می‌شود\&. به‌طور پیش‌فرض، تاریخ و زمان می‌توانند در هر کجای
آرگومان ارائه‌شده قرار داشته باشند\&.
.RS
.PP
اگر تاریخ و زمان با موفقیت تجزیه شوند وضعیت صفر، وگرنه یک برگردانده می‌شود\&.
.PP
گزینه‌ها:
.PD 0
.TP
.PD
\fB\-a\fP
تاریخ و زمان به ابتدای آرگومان لنگر می‌شوند؛ در صورتی که متنی پیش از
آن‌ها وجود داشته باشد تطبیق داده نخواهند شد\&.
.TP
\fB\-A\fP
تاریخ و زمان به هر دو انتهای ابتدا و پایان آرگومان لنگر می‌شوند؛
در صورت وجود هرگونه متن دیگر در آرگومان تطبیق داده نخواهند شد\&.
.TP
\fB\-d\fP
فعال‌سازی خروجی اشکال‌زدایی اضافی\&.
.TP
\fB\-m\fP
منفی (منها)\&. هنگامی که \fB\-R\fP \fIanchor_time\fP نیز داده شده باشد، زمان نسبی
به سمت عقب از \fIanchor_time\fP محاسبه می‌شود\&.
.TP
\fB\-r\fP
آرگومان ارسال‌شده باید به عنوان یک زمان نسبی تجزیه شود\&.
.TP
\fB\-R\fP \fIanchor_time\fP
آرگومان ارسال‌شده باید به عنوان یک زمان نسبی تجزیه شود\&. این زمان نسبت به
\fIanchor_time\fP (زمانی بر حسب ثانیه از مبدا زمان) محاسبه می‌شود و مقدار
بازگردانده‌شده، زمان مطلقی است که از پیش بردن \fIanchor_time\fP به میزان زمان
نسبی داده‌شده به دست می‌آید\&. این سازوکار اجازه می‌دهد طول ماه‌ها به‌درستی
لحاظ شود\&. اگر روز نهایی در ماه داده‌شده وجود نداشته باشد، آخرین روز ماه
پایانی ارائه می‌شود\&. برای نمونه، اگر زمان مبنا در ۳۱ ژانویه ۲۰۰۷ باشد
و زمان نسبی ۱ ماه باشد، زمان نهایی همان ساعت در ۲۸ فوریه ۲۰۰۷ خواهد بود\&.
.TP
\fB\-s\fP
علاوه بر تنظیم \fBREPLY\fP، مقدار \fBREPLY2\fP را روی باقیماندهٔ آرگومان
پس از حذف تاریخ و زمان تنظیم می‌کند\&. اگر گزینهٔ \fB\-A\fP داده شده باشد،
این مقدار خالی خواهد بود\&.
.TP
\fB\-t\fP
پذیرش زمان بدون مشخص کردن تاریخ\&. تاریخ، امروز فرض می‌شود\&. اگر
ناقوس نیمه‌شب در حال نواختن دوازده باشد (دقیقاً در مرز نیمه‌شب)، رفتار
نامشخص خواهد بود\&.
.RE
.TP
\fBcalendar_show\fP
تابعی که به‌طور پیش‌فرض برای نمایش رویدادها استفاده می‌شود\&. این تابع زمان شروع
و پایان رویدادها (هر دو بر حسب ثانیه‌های epoch) و شرح رویداد را می‌پذیرد\&.
.RS
.PP
رویداد همواره در خروجی استاندارد چاپ می‌شود\&. اگر ویرایشگر خط فرمان فعال
باشد (که معمولاً چنین است)، خط فرمان پس از نمایش خروجی دوباره نشان داده
خواهد شد\&.
.PP
اگر متغیر \fBDISPLAY\fP مقداردهی شده باشد و زمان شروع و پایان یکسان باشند
(که نشان‌دهندهٔ یک رویداد زمان‌بندی‌شده است)، این تابع از دستور \fBxmessage\fP
برای نمایش پنجره‌ای شامل جزئیات رویداد استفاده می‌کند\&.
.RE
.PP.SH "گزارش باگ‌ها (BUGS)"
.PP
از آن‌جا که این سیستم کاملاً بر پایهٔ توابع پوسته بنا شده است (همراه با پشتیبانی اندکی از ماژول \fBzsh/datetime\fP)، سازوکارهای به‌کاررفته به اندازهٔ موارد ارائه‌شده توسط یک ابزار تقویم اختصاصی قابل‌اطمینان و استوار نیستند\&. در نتیجه، کاربر نباید برای هشدارهای حیاتی به پوسته اتکا کند\&.
.PP
تابعی به نام \fBcalendar_delete\fP وجود ندارد\&.
.PP
هیچ پشتیبانی‌ای برای بومی‌سازی تاریخ‌ها و زمان‌ها، یا استفاده از منطقه‌های زمانی وجود ندارد\&.
.PP
دوره‌های نسبی ماه‌ها و سال‌ها متغیر بودن تعداد روزها را در نظر نمی‌گیرند\&.
.PP
تابع \fBcalendar_show\fP در حال حاضر به‌صورت ثابت برای استفاده از \fBxmessage\fP جهت نمایش هشدارها در نمایشگرهای X Window System برنامه‌ریزی شده است\&. این مورد باید قابل‌پیکربندی باشد و در حالت ایده‌آل یکپارچگی بهتری با میزکار داشته باشد\&.
.PP
\fBcalendar_lockfiles\fP در حین انتظار برای دریافت قفل روی یک فایل، پوسته را معلق می‌کند\&. اگر این تابع از یک وظیفهٔ زمان‌بندی‌شده فراخوانی شود، باید در عوض رویدادی را که باعث فراخوانی شده است دوباره زمان‌بندی کند\&.