.\" .\" MAN PAGE COMMENTS to .\" .\" Chet Ramey .\" Information Network Services .\" Case Western Reserve University .\" chet.ramey@case.edu .\" .\" Last Change: Fri Jul 17 09:43:01 EDT 2020 .\" .TH HISTORY 3 "2020 July 17" "GNU History 8.1" .\" .\" File Name macro. This used to be `.PN', for Path Name, .\" but Sun doesn't seem to like that very much. .\" .de FN \fI\|\\$1\|\fP .. .ds lp \fR\|(\fP .ds rp \fR\|)\fP .\" FnN return-value fun-name N arguments .de Fn1 \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3\fP\\*(rp .br .. .de Fn2 .if t \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3,\|\\$4\fP\\*(rp .if n \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3, \\$4\fP\\*(rp .br .. .de Fn3 .if t \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3,\|\\$4,\|\\$5\fP\|\\*(rp .if n \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3, \\$4, \\$5\fP\\*(rp .br .. .de Vb \fI\\$1\fP \fB\\$2\fP .br .. .SH "نام (NAME)" history \- کتابخانه تاریخچه گنو (GNU History Library) .SH "حق نشر (COPYRIGHT)" .if t The GNU History Library is Copyright \(co 1989-2020 by the Free Software Foundation, Inc. .if n The GNU History Library is Copyright (C) 1989-2020 by the Free Software Foundation, Inc. .SH "توضیحات (DESCRIPTION)" بسیاری از برنامه‌ها ورودی را خط‌به‌خط از کاربر می‌خوانند. کتابخانه GNU History قادر است این خطوط را پیگیری کند، داده‌های دلخواه را به هر خط مرتبط سازد، و از اطلاعات خطوط پیشین در ایجاد خطوط جدید استفاده نماید. .PP .SH "گسترش تاریخچه (HISTORY EXPANSION)" کتابخانه تاریخچه از ویژگی گسترش تاریخچه پشتیبانی می‌کند که مشابه گسترش تاریخچه در .B bash است. این بخش ویژگی‌های نحوی موجود را توصیف می‌کند. .PP گسترش‌های تاریخچه کلمات را از فهرست تاریخچه وارد جریان ورودی می‌کنند؛ این امر تکرار دستورها، درج آرگومان‌های یک دستور قبلی در خط ورودی فعلی، یا رفع سریع خطاهای دستورات پیشین را آسان می‌سازد. .PP گسترش تاریخچه معمولاً بلافاصله پس از خوانده شدن یک خط کامل انجام می‌شود. این عمل در دو مرحله صورت می‌گیرد. مرحله نخست مشخص کردن این است که کدام خط از فهرست تاریخچه در هنگام جایگزینی استفاده شود. مرحله دوم انتخاب بخش‌هایی از آن خط برای درج در خط فعلی است. خط انتخاب‌شده از تاریخچه «رویداد» (\fIevent\fP) نامیده می‌شود، و بخش‌هایی از آن خط که مورد اقدام قرار می‌گیرند «کلمات» (\fIwords\fP) هستند. «اصلاح‌کننده‌ها» (\fImodifiers\fP) گوناگونی برای دستکاری کلمات انتخاب‌شده در دسترس است. خط به همان شیوه‌ای که .B bash هنگام خواندن ورودی عمل می‌کند به کلمات شکسته می‌شود، به‌طوری که چند کلمه که در حالت عادی جدا می‌بودند، در صورت محصور شدن در نقل‌قول به عنوان یک کلمه در نظر گرفته می‌شوند (توضیحات .B history_tokenize() در زیر را ببینید). گسترش‌های تاریخچه با ظاهر شدن نویسه گسترش تاریخچه معرفی می‌شوند، که به طور پیش‌فرض \^\fB!\fP\^ است. تنها ممیز وارونه (\^\fB\e\fP\^) و نقل‌قول تکی می‌توانند نویسه گسترش تاریخچه را نقل (quote) کنند. .SS "تعیین‌کننده‌های رویداد (Event Designators)" یک تعیین‌کننده رویداد، ارجاعی به یک مدخل خط فرمان در فهرست تاریخچه است. رویدادها نسبت به موقعیت فعلی در فهرست تاریخچه سنجیده می‌شوند، مگر اینکه ارجاع مطلق باشد. .PP .PD 0 .TP .B ! آغاز جایگزینی تاریخچه، مگر زمانی که پس از آن یک نویسه .BR blank ، خط جدید، = یا ( بیاید. .TP .B !\fIn\fR ارجاع به خط فرمان .IR n . .TP .B !\-\fIn\fR ارجاع به دستور فعلی منهای .IR n . .TP .B !! ارجاع به دستور قبلی. این مترادفی برای `!\-1' است. .TP .B !\fIstring\fR ارجاع به جدیدترین دستور پیش از موقعیت فعلی در فهرست تاریخچه که با .I string آغاز می‌شود. .TP .B !?\fIstring\fR\fB[?]\fR ارجاع به جدیدترین دستور پیش از موقعیت فعلی در فهرست تاریخچه که حاوی .I string است. نویسه \fB?\fP پایانی می‌تواند حذف شود اگر بلافاصله پس از .I string یک خط جدید بیاید. اگر \fIstring\fP مشخص نشود، رشته حاصل از جدیدترین جستجو استفاده می‌شود؛ در صورتی که هیچ رشته جستجوی قبلی وجود نداشته باشد، این یک خطا است. .TP .B \d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u جایگزینی سریع. تکرار آخرین دستور، با جایگزین کردن .I string1 با .IR string2 . معادل با ``!!:s\d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u'' (بخش \fBاصلاح‌کننده‌ها\fP در زیر را ببینید). .TP .B !# کل خط فرمان تایپ‌شده تا این لحظه. .PD .SS "تعیین‌کننده‌های کلمه (Word Designators)" تعیین‌کننده‌های کلمه برای انتخاب کلمات مورد نظر از رویداد استفاده می‌شوند. نویسه .B : مشخصه رویداد را از تعیین‌کننده کلمه جدا می‌سازد. اگر تعیین‌کننده کلمه با یکی از نویسه‌های .BR ^ ، .BR $ ، .BR * ، .BR \- ، یا .B % آغاز شود، این دونقطه می‌تواند حذف گردد. کلمات از ابتدای خط شماره‌گذاری می‌شوند، و کلمه نخست با 0 (صفر) مشخص می‌شود. کلمات با تک‌فاصله جدا شده و در خط فعلی درج می‌گردند. .PP .PD 0 .TP .B 0 (zero) کلمه صفرم. برای شل، این کلمه دستور است. .TP .I n کلمه .IR n -ام. .TP .B ^ نخستین آرگومان؛ یعنی کلمه 1. .TP .B $ آخرین کلمه. این معمولاً آخرین آرگومان است، اما اگر تنها یک کلمه در خط وجود داشته باشد، به کلمه صفرم گسترش می‌یابد. .TP .B % نخستین کلمه تطبیق‌یافته توسط جدیدترین جستجوی `?\fIstring\fR?'، در صورتی که رشته جستجو با نویسه‌ای که بخشی از یک کلمه است آغاز شود. .TP .I x\fB\-\fPy محدوده‌ای از کلمات؛ `\-\fIy\fR' مخفف `0\-\fIy\fR' است. .TP .B * همه کلمات به جز کلمه صفرم. این مترادفی برای `\fI1\-$\fP' است. استفاده از .B * در صورتی که تنها یک کلمه در رویداد وجود داشته باشد خطا نیست؛ در این حالت رشته خالی بازگردانده می‌شود. .TP .B x* مخفف \fIx\-$\fP است. .TP .B x\- همانند \fBx*\fP مخفف \fIx\-$\fP است، اما کلمه پایانی را حذف می‌کند. اگر \fBx\fP وجود نداشته باشد، به طور پیش‌فرض 0 است. .PD .PP اگر تعیین‌کننده کلمه بدون مشخصه رویداد ارائه شود، دستور قبلی به عنوان رویداد استفاده می‌گردد. .SS "اصلاح‌کننده‌ها (Modifiers)" پس از تعیین‌کننده کلمه اختیاری، ممکن است دنباله‌ای از یک یا چند مورد از اصلاح‌کننده‌های زیر بیاید که پیش از هر یک `:` قرار می‌گیرد. این‌ها کلمه یا کلمات انتخاب‌شده از رویداد تاریخچه را اصلاح یا ویرایش می‌کنند. .PP .PD 0 .PP .TP .B h حذف بخش انتهایی نام فایل، به جا گذاشتن تنها سر (head). .TP .B t حذف تمامی بخش‌های آغازین نام فایل، به جا گذاشتن دم (tail). .TP .B r حذف پسوند انتهایی به قالب \fI.xxx\fP، به جا گذاشتن نام پایه (basename). .TP .B e حذف همه چیز به جز پسوند انتهایی. .TP .B p چاپ دستور جدید بدون اجرای آن. .TP .B q نقل‌قول کردن کلمات جایگزین‌شده، جهت گریز از جایگزینی‌های بعدی. .TP .B x نقل‌قول کردن کلمات جایگزین‌شده همانند .BR q ، اما شکستن به کلمات در محل .B فاصله‌ها (blanks) و خطوط جدید. اصلاح‌کننده‌های \fBq\fP و \fBx\fP مانعة‌الجمع هستند؛ آخرین اصلاح‌کننده ارائه‌شده استفاده می‌شود. .TP .B s/\fIold\fP/\fInew\fP/ جایگزین کردن .I new به جای نخستین رخداد .I old در خط رویداد. هر نویسه‌ای می‌تواند به عنوان جداکننده به جای / استفاده شود. اگر جداکننده پایانی آخرین نویسه خط رویداد باشد، اختیاری است. جداکننده در .I old و .I new می‌تواند با یک ممیز وارونه نقل‌قول شود. اگر & در .I new ظاهر شود، با .I old جایگزین می‌شود. یک ممیز وارونه علامت & را نقل خواهد کرد. اگر .I old تهی باشد، روی آخرین .I old جایگزین‌شده، یا اگر قبلاً هیچ جایگزینی تاریخچه‌ای رخ نداده باشد، روی آخرین .I string در جستجوی .B !?\fIstring\fR\fB[?]\fR تنظیم می‌شود. اگر .I new تهی باشد، هر .I old منطبق حذف می‌گردد. .TP .B & تکرار جایگزینی قبلی. .TP .B g اعمال تغییرات روی کل خط رویداد. این همراه با `\fB:s\fP' (برای مثال، `\fB:gs/\fIold\fP/\fInew\fP/\fR') یا `\fB:&\fP' به کار می‌رود. در صورت استفاده با `\fB:s\fP'، هر نویسه‌ای می‌تواند به جای / به عنوان جداکننده به کار رود، و اگر جداکننده پایانی آخرین نویسه خط رویداد باشد اختیاری است. نویسه \fBa\fP می‌تواند به عنوان مترادفی برای \fBg\fP استفاده شود. .TP .B G اعمال اصلاح‌کننده `\fBs\fP' یا `\fB&\fP' بعدی، یک‌بار روی هر کلمه در خط رویداد. .PD .SH "برنامه‌نویسی با توابع تاریخچه (PROGRAMMING WITH HISTORY FUNCTIONS)" این بخش نحوه استفاده از کتابخانه History را در سایر برنامه‌ها توصیف می‌کند. .SS "مقدمه‌ای بر تاریخچه (Introduction to History)" برنامه‌نویسی که از کتابخانه History استفاده می‌کند توابعی برای به خاطر سپردن خطوط در فهرست تاریخچه، مرتبط ساختن داده‌های دلخواه با یک خط، حذف خطوط از فهرست، جستجو در فهرست برای خطی حاوی یک رشته متنی دلخواه، و ارجاع مستقیم به هر خط در فهرست در اختیار دارد. علاوه بر این، یک تابع گسترش تاریخچه (\fIexpansion\fP) موجود است که رابط کاربری یکپارچه‌ای را میان برنامه‌های مختلف فراهم می‌سازد. .PP کاربری که برنامه‌های نوشته‌شده با کتابخانه History را به کار می‌برد از مزیت یک رابط کاربری یکپارچه با مجموعه‌ای از دستورهای شناخته‌شده جهت دستکاری متن خطوط پیشین و استفاده از آن متن در دستورات جدید بهره‌مند می‌شود. دستورهای پایه‌ای دستکاری تاریخچه با جایگزینی تاریخچه ارائه‌شده توسط .B bash یکسان هستند. .PP برنامه‌نویس همچنین می‌تواند از کتابخانه readline استفاده کند، که به طور پیش‌فرض شامل برخی امکانات دستکاری تاریخچه است و مزیت افزوده ویرایش خط فرمان را دارد. .PP پیش از اعلان هر تابعی که از هر قابلیتی از کتابخانه History در کدهای دیگر استفاده می‌کند، توسعه‌دهنده برنامه باید فایل .FN را در هر فایلی که از ویژگی‌های کتابخانه History استفاده می‌کند بگنجاند. این فایل اعلان‌های extern را برای تمام توابع و متغیرهای عمومی کتابخانه فراهم کرده و تمامی ساختارهای داده عمومی را اعلان می‌کند. .SS "ذخیره‌سازی تاریخچه (History Storage)" فهرست تاریخچه آرایه‌ای از مدخل‌های تاریخچه است. یک مدخل تاریخچه به صورت زیر اعلان می‌شود: .PP .Vb "typedef void *" histdata_t; .PP .nf typedef struct _hist_entry { char *line; char *timestamp; histdata_t data; } HIST_ENTRY; .fi .PP بنابراین خود فهرست تاریخچه ممکن است به این صورت اعلان شود: .PP .Vb "HIST_ENTRY **" the_history_list; .PP وضعیت کتابخانه History در یک ساختار واحد کپسوله‌سازی می‌شود: .PP .nf /* * ساختاری برای جابه‌جایی وضعیت فعلی تاریخچه. */ typedef struct _hist_state { HIST_ENTRY **entries; /* اشاره‌گر به خود مدخل‌ها. */ int offset; /* اشاره‌گر مکان درون این آرایه. */ int length; /* تعداد عناصر درون این آرایه. */ int size; /* تعداد خانه‌های اختصاص‌یافته به این آرایه. */ int flags; } HISTORY_STATE; .fi .PP اگر عضو flags شامل \fBHS_STIFLED\fP باشد، تاریخچه محدود (stifled) شده است. .SH "توابع تاریخچه (History Functions)" این بخش توالی فراخوانی را برای توابع گوناگون صادرشده توسط کتابخانه GNU History شرح می‌دهد. .SS "مقداردهی اولیه تاریخچه و مدیریت وضعیت (Initializing History and State Management)" این بخش توابع مورد استفاده برای مقداردهی اولیه و مدیریت وضعیت کتابخانه History را در زمان استفاده از توابع تاریخچه در برنامه شرح می‌دهد. .Fn1 void using_history void آغاز نشستی که در آن ممکن است از توابع تاریخچه استفاده شود. این تابع متغیرهای تعاملی را مقداردهی اولیه می‌کند. .Fn1 "HISTORY_STATE *" history_get_history_state void بازگرداندن ساختاری که وضعیت فعلی تاریخچه ورودی را شرح می‌دهد. .Fn1 void history_set_history_state "HISTORY_STATE *state" تنظیم وضعیت فهرست تاریخچه بر اساس \fIstate\fP. .SS "مدیریت فهرست تاریخچه (History List Management)" این توابع مدخل‌های منفرد در فهرست تاریخچه را مدیریت می‌کنند، یا پارامترهای حاکم بر خود فهرست را تعیین می‌نمایند. .Fn1 void add_history "const char *string" قرار دادن \fIstring\fP در انتهای فهرست تاریخچه. فیلد داده مرتبط (در صورت وجود) روی \fBNULL\fP تنظیم می‌شود. اگر حداکثر تعداد مدخل‌های تاریخچه با استفاده از \fBstifle_history()\fP تنظیم شده باشد، و تعداد جدید مدخل‌های تاریخچه از آن حداکثر فراتر رود، قدیمی‌ترین مدخل تاریخچه حذف می‌شود. .Fn1 void add_history_time "const char *string" تغییر برچسب زمانی مرتبط با تازه‌ترین مدخل تاریخچه به \fIstring\fP. .Fn1 "HIST_ENTRY *" remove_history "int which" حذف مدخل تاریخچه در آفست \fIwhich\fP از تاریخچه. عنصر حذف‌شده بازگردانده می‌شود تا بتوانید خط، داده و ساختار دربرگیرنده را آزاد کنید. .Fn1 "histdata_t" free_history_entry "HIST_ENTRY *histent" آزاد کردن مدخل تاریخچه \fIhistent\fP و هرگونه داده خصوصی کتابخانه تاریخچه مرتبط با آن. داده‌های ویژه برنامه را بازمی‌گرداند تا فراخواننده بتواند آنها را مدیریت و آزاد کند. .Fn3 "HIST_ENTRY *" replace_history_entry "int which" "const char *line" "histdata_t data" تنظیم \fIline\fP و \fIdata\fP برای مدخل تاریخچه در آفست \fIwhich\fP. این تابع مدخل قدیمی را بازمی‌گرداند تا فراخواننده بتواند داده‌های ویژه برنامه را مدیریت کند. در صورت نامعتبر بودن \fIwhich\fP، یک اشاره‌گر \fBNULL\fP بازگردانده می‌شود. .Fn1 void clear_history "void" پاک کردن فهرست تاریخچه از طریق حذف تمامی مدخل‌ها. .Fn1 void stifle_history "int max" محدود کردن فهرست تاریخچه، با نگه‌داری تنها \fImax\fP مدخل پایانی. فهرست تاریخچه در هر زمان تنها شامل حداکثر \fImax\fP مدخل خواهد بود. .Fn1 int unstifle_history "void" متوقف کردن محدودسازی تاریخچه. این تابع حداکثر تعداد قبلی تعیین‌شده برای مدخل‌های تاریخچه را بازمی‌گرداند (همان‌طور که توسط \fBstifle_history()\fP تعیین شده بود). مقدار در صورتی که تاریخچه محدود شده بود مثبت، و در غیر این صورت منفی است. .Fn1 int history_is_stifled "void" در صورتی که تاریخچه محدود شده باشد مقداری غیرصفر، و در غیر این صورت صفر بازمی‌گرداند. .SS "اطلاعات درباره فهرست تاریخچه (Information About the History List)" این توابع اطلاعاتی را درباره کل فهرست تاریخچه یا مدخل‌های منفرد فهرست بازمی‌گردانند. .Fn1 "HIST_ENTRY **" history_list "void" بازگرداندن یک آرایه پایان‌یافته با \fBNULL\fP از \fIHIST_ENTRY *\fP که نشان‌دهنده تاریخچه ورودی فعلی است. عنصر 0 این فهرست ابتدای زمان است. اگر هیچ تاریخچه‌ای وجود نداشته باشد، \fBNULL\fP بازمی‌گرداند. .Fn1 int where_history "void" آفست عنصر فعلی تاریخچه را بازمی‌گرداند. .Fn1 "HIST_ENTRY *" current_history "void" بازگرداندن مدخل تاریخچه در موقعیت فعلی، همان‌طور که توسط \fBwhere_history()\fP تعیین می‌شود. اگر مدخلی در آنجا وجود نداشته باشد، یک اشاره‌گر \fBNULL\fP بازمی‌گرداند. .Fn1 "HIST_ENTRY *" history_get "int offset" بازگرداندن مدخل تاریخچه در موقعیت \fIoffset\fP. دامنه مقادیر معتبر \fIoffset\fP از \fBhistory_base\fP آغاز شده و در \fBhistory_length\fP \- 1 پایان می‌یابد. اگر مدخلی در آنجا نباشد، یا اگر \fIoffset\fP خارج از دامنه معتبر باشد، یک اشاره‌گر \fBNULL\fP بازمی‌گرداند. .Fn1 "time_t" history_get_time "HIST_ENTRY *" بازگرداندن برچسب زمانی مرتبط با مدخل تاریخچه‌ای که به عنوان آرگومان ارسال شده است. .Fn1 int history_total_bytes "void" بازگرداندن تعداد بایت‌هایی که مدخل‌های اصلی تاریخچه مصرف می‌کنند. این تابع مجموع طول تمامی خطوط موجود در تاریخچه را بازمی‌گرداند. .SS "حرکت در فهرست تاریخچه (Moving Around the History List)" این توابع امکان تنظیم یا تغییر نمایه فعلی در فهرست تاریخچه را فراهم می‌سازند. .Fn1 int history_set_pos "int pos" تنظیم آفست فعلی تاریخچه روی \fIpos\fP، که یک نمایه مطلق در فهرست است. در صورت موفقیت 1، و اگر \fIpos\fP کمتر از صفر یا بزرگ‌تر از تعداد مدخل‌های تاریخچه باشد 0 بازمی‌گرداند. .Fn1 "HIST_ENTRY *" previous_history "void" عقب بردن آفست فعلی تاریخچه به مدخل قبلی، و بازگرداندن اشاره‌گری به آن مدخل. اگر مدخل قبلی وجود نداشته باشد، یک اشاره‌گر \fBNULL\fP بازمی‌گرداند. .Fn1 "HIST_ENTRY *" next_history "void" اگر آفست فعلی تاریخچه به یک مدخل معتبر تاریخچه اشاره کند، آفست فعلی تاریخچه را افزایش می‌دهد. اگر آفست افزایش‌یافته به یک مدخل معتبر تاریخچه اشاره داشته باشد، اشاره‌گری به آن مدخل بازمی‌گرداند؛ در غیر این صورت، یک اشاره‌گر \fBNULL\fP بازمی‌گرداند. .SS "جستجو در فهرست تاریخچه (Searching the History List)" این توابع امکان جستجو در فهرست تاریخچه برای مدخل‌های حاوی یک رشته مشخص را فراهم می‌کنند. جستجو می‌تواند هم رو به جلو و هم رو به عقب از موقعیت فعلی تاریخچه انجام شود. جستجو می‌تواند لنگردار (\fIanchored\fP) باشد، به این معنی که رشته باید در ابتدای مدخل تاریخچه تطبیق یابد. .Fn2 int history_search "const char *string" "int direction" جستجوی تاریخچه برای \fIstring\fP، با شروع از آفست فعلی تاریخچه. اگر \fIdirection\fP کمتر از 0 باشد، جستجو در میان مدخل‌های پیشین انجام می‌شود؛ در غیر این صورت در میان مدخل‌های پسین صورت می‌گیرد. اگر \fIstring\fP یافت شود، نمایه فعلی تاریخچه روی آن مدخل تنظیم می‌شود و مقدار بازگردانده‌شده آفست در خط آن مدخل است که \fIstring\fP در آن پیدا شد. در غیر این صورت، چیزی تغییر نمی‌کند و -1 بازگردانده می‌شود. .Fn2 int history_search_prefix "const char *string" "int direction" جستجوی تاریخچه برای \fIstring\fP، با شروع از آفست فعلی تاریخچه. جستجو لنگردار است: خطوط منطبق باید با \fIstring\fP آغاز شوند. اگر \fIdirection\fP کمتر از 0 باشد، جستجو در میان مدخل‌های قبلی انجام می‌شود؛ در غیر این صورت در میان مدخل‌های بعدی. اگر \fIstring\fP پیدا شود، نمایه فعلی تاریخچه روی آن مدخل تنظیم شده و مقدار بازگشتی 0 است. در غیر این صورت، چیزی تغییر نمی‌کند و -1 بازگردانده می‌شود. .Fn3 int history_search_pos "const char *string" "int direction" "int pos" جستجو برای \fIstring\fP در فهرست تاریخچه، با شروع از \fIpos\fP، که نمایه‌ای مطلق در فهرست است. اگر \fIdirection\fP منفی باشد، جستجو رو به عقب از \fIpos\fP پیش می‌رود؛ در غیر این صورت رو به جلو. نمایه مطلق عنصر تاریخچه‌ای که \fIstring\fP در آن یافت شد را بازمی‌گرداند، یا در غیر این صورت -1 بازمی‌گرداند. .SS "مدیریت فایل تاریخچه (Managing the History File)" کتابخانه History می‌تواند تاریخچه را از یک فایل بخواند و در آن بنویسد. این بخش توابع مدیریت فایل تاریخچه را مستند می‌کند. .Fn1 int read_history "const char *filename" افزودن محتویات \fIfilename\fP به فهرست تاریخچه، خط‌به‌خط. اگر \fIfilename\fP برابر \fBNULL\fP باشد، از \fI~/.history\fP خوانده می‌شود. در صورت موفقیت 0، یا در صورت عدم موفقیت \fBerrno\fP را بازمی‌گرداند. .Fn3 int read_history_range "const char *filename" "int from" "int to" خواندن محدوده‌ای از خطوط از \fIfilename\fP و افزودن آنها به فهرست تاریخچه. خواندن از خط \fIfrom\fP شروع شده و در \fIto\fP پایان می‌یابد. اگر \fIfrom\fP صفر باشد، از ابتدا آغاز می‌شود. اگر \fIto\fP کمتر از \fIfrom\fP باشد، تا انتهای فایل خوانده می‌شود. اگر \fIfilename\fP برابر \fBNULL\fP باشد، از \fI~/.history\fP خوانده می‌شود. در صورت موفقیت 0، و در صورت عدم موفقیت \fBerrno\fP بازمی‌گرداند. .Fn1 int write_history "const char *filename" نوشتن تاریخچه فعلی در \fIfilename\fP، با رونویسی روی \fIfilename\fP در صورت لزوم. اگر \fIfilename\fP برابر \fBNULL\fP باشد، فهرست تاریخچه در \fI~/.history\fP نوشته می‌شود. در صورت موفقیت 0، یا در صورت بروز خطای خواندن یا نوشتن \fBerrno\fP را بازمی‌گرداند. .Fn2 int append_history "int nelements" "const char *filename" الحاق آخرین \fInelements\fP عنصر از فهرست تاریخچه به \fIfilename\fP. اگر \fIfilename\fP برابر \fBNULL\fP باشد، به \fI~/.history\fP الحاق می‌شود. در صورت موفقیت 0، یا در صورت بروز خطای خواندن یا نوشتن \fBerrno\fP را بازمی‌گرداند. .Fn2 int history_truncate_file "const char *filename" "int nlines" کوتاه کردن فایل تاریخچه \fIfilename\fP، به جا گذاشتن تنها \fInlines\fP خط پایانی. اگر \fIfilename\fP برابر \fBNULL\fP باشد، \fI~/.history\fP کوتاه می‌شود. در صورت موفقیت 0، یا در صورت شکست \fBerrno\fP بازمی‌گرداند. .SS "گسترش تاریخچه (History Expansion)" این توابع گسترش تاریخچه را پیاده‌سازی می‌کنند. .Fn2 int history_expand "char *string" "char **output" گسترش \fIstring\fP و قرار دادن نتیجه در \fIoutput\fP، که اشاره‌گری به یک رشته است. مقادیر بازگشتی: .RS .PD 0 .TP 0 اگر هیچ گسترشی صورت نگرفته باشد (یا اگر تنها تغییر در متن، حذف نویسه‌های گریز پیش از نویسه گسترش تاریخچه باشد)؛ .TP 1 اگر گسترش صورت گرفته باشد؛ .TP -1 اگر خطایی در گسترش رخ داده باشد؛ .TP 2 اگر خط بازگردانده‌شده باید نمایش داده شود ولی اجرا نشود، همانند اصلاح‌کننده \fB:p\fP. .PD .RE اگر خطایی در گسترش رخ دهد، \fIoutput\fP حاوی پیام خطای توصیفی خواهد بود. .Fn3 "char *" get_history_event "const char *string" "int *cindex" "int qchar" بازگرداندن متن رویداد تاریخچه‌ای که از \fIstring\fP + \fI*cindex\fP آغاز می‌شود. مقدار \fI*cindex\fP تغییر می‌یابد تا به بعد از مشخص‌کننده رویداد اشاره کند. در هنگام ورود به تابع، \fIcindex\fP به نمایه‌ای درون \fIstring\fP اشاره دارد که مشخصه رویداد تاریخچه از آنجا آغاز می‌گردد. آرگومان \fIqchar\fP نویسه‌ای است که علاوه بر نویسه‌های پایانی «معمولی»، مجاز به پایان دادن به مشخصه رویداد است. .Fn1 "char **" history_tokenize "const char *string" بازگرداندن آرایه‌ای از نشانه‌ها (tokens) که از \fIstring\fP تجزیه شده‌اند، همان‌گونه که شل عمل می‌کند. نشانه‌ها بر اساس نویسه‌های موجود در متغیر \fBhistory_word_delimiters\fP تفکیک می‌شوند و قواعد نقل‌قول شل رعایت می‌گردد. .Fn3 "char *" history_arg_extract "int first" "int last" "const char *string" استخراج بخشی از رشته متشکل از آرگومان‌های \fIfirst\fP تا \fIlast\fP موجود در \fIstring\fP. آرگومان‌ها با استفاده از \fBhistory_tokenize()\fP تفکیک می‌شوند. .SS "متغیرهای تاریخچه (History Variables)" این بخش متغیرهای قابل مشاهده از خارج را که توسط کتابخانه GNU History صادر شده‌اند توصیف می‌کند. .Vb int history_base آفست منطقی نخستین مدخل در فهرست تاریخچه. .Vb int history_length تعداد مدخل‌هایی که در حال حاضر در فهرست تاریخچه ذخیره شده‌اند. .Vb int history_max_entries حداکثر تعداد مدخل‌های تاریخچه. این مقدار باید با استفاده از \fBstifle_history()\fP تغییر یابد. .Vb int history_write_timestamps اگر غیرصفر باشد، برچسب‌های زمانی در فایل تاریخچه نوشته می‌شوند تا بتوان آنها را میان نشست‌ها حفظ کرد. مقدار پیش‌فرض 0 است، به این معنی که برچسب‌های زمانی ذخیره نمی‌شوند. قالب فعلی برچسب زمانی از مقدار \fIhistory_comment_char\fP برای تحدید مدخل‌های برچسب زمانی در فایل تاریخچه استفاده می‌کند. اگر این متغیر مقداری نداشته باشد (حالت پیش‌فرض)، برچسب‌های زمانی نوشته نخواهند شد. .Vb char history_expansion_char نویسه‌ای که یک رویداد تاریخچه را معرفی می‌کند. مقدار پیش‌فرض \fB!\fP است. تنظیم آن روی 0 گسترش تاریخچه را غیرفعال می‌سازد. .Vb char history_subst_char نویسه‌ای که اگر در ابتدای یک خط یافت شود جایگزینی کلمه را فراخوانی می‌کند. مقدار پیش‌فرض \fB^\fP است. .Vb char history_comment_char در حین نشانه‌گذاری، اگر این نویسه به عنوان نخستین نویسه یک کلمه دیده شود، آن نویسه و تمامی نویسه‌های بعدی تا خط جدید نادیده گرفته می‌شوند، که مانع از گسترش تاریخچه برای باقی خط می‌گردد. این ویژگی به طور پیش‌فرض غیرفعال است. .Vb "char *" history_word_delimiters نویسه‌هایی که نشانه‌ها را برای \fBhistory_tokenize()\fP جدا می‌سازند. مقدار پیش‌فرض \fB"\ \et\en()<>;&|"\fP است. .Vb "char *" history_no_expand_chars فهرست نویسه‌هایی که اگر بلافاصله پس از \fBhistory_expansion_char\fP ظاهر شوند، مانع گسترش تاریخچه می‌گردند. مقدار پیش‌فرض فاصله (space)، تب (tab)، خط جدید (newline)، \fB\er\fP و \fB=\fP است. .Vb "char *" history_search_delimiter_chars فهرست نویسه‌های اضافی که علاوه بر فاصله، تب، \fI:\fP و \fI?\fP در حالت جستجوی زیررشته، می‌توانند رشته جستجوی تاریخچه را محدود کنند. مقدار پیش‌فرض تهی است. .Vb int history_quotes_inhibit_expansion اگر غیرصفر باشد، کلمات داخل نقل‌قول دوگانه برای نویسه گسترش تاریخچه یا نویسه توضیح تاریخچه پویش نمی‌شوند. مقدار پیش‌فرض 0 است. .Vb "rl_linebuf_func_t *" history_inhibit_expansion_function این متغیر باید روی آدرس تابعی تنظیم شود که دو آرگومان دریافت می‌کند: یک \fBchar *\fP (\fIstring\fP) و یک نمایه \fBint\fP در آن رشته (\fIi\fP). این تابع اگر گسترش تاریخچه با شروع از \fIstring[i]\fP نباید انجام شود باید مقداری غیرصفر بازگرداند؛ و اگر گسترش باید صورت گیرد 0 بازگرداند. این برای استفاده توسط برنامه‌هایی نظیر \fBbash\fP در نظر گرفته شده است که از نویسه گسترش تاریخچه برای اهداف اضافی بهره می‌برند. به طور پیش‌فرض، این متغیر روی \fBNULL\fP تنظیم است. .SH "فایل‌ها (FILES)" .PD 0 .TP .FN ~/.history نام فایل پیش‌فرض برای خواندن و نوشتن تاریخچه ذخیره‌شده .PD .SH "همچنین ببینید (SEE ALSO)" .PD 0 .TP \fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey .TP \fIThe Gnu History Library\fP, Brian Fox and Chet Ramey .TP \fIbash\fP(1) .TP \fIreadline\fP(3) .PD .SH "نویسنده (AUTHOR)" Brian Fox, Free Software Foundation .br bfox@gnu.org .PP Chet Ramey, Case Western Reserve University .br chet.ramey@case.edu .SH "گزارش باگ‌ها (REPORTING BUGS)" اگر اشکالی در کتابخانه .B history یافتید، باید آن را گزارش کنید. اما ابتدا مطمئن شوید که واقعاً یک اشکال است، و در جدیدترین نسخه از کتابخانه .B history که در اختیار دارید رخ می‌دهد. .PP هنگامی که اطمینان یافتید که اشکال واقعاً وجود دارد، گزارش اشکال را به \fIbug\-readline\fP@\fIgnu.org\fP ارسال کنید. اگر راه‌حلی برای رفع آن دارید، از ارسال آن نیز استقبال می‌شود! پیشنهادها و گزارش‌های اشکال «مفهومی» ممکن است به \fIbug\-readline\fP@\fIgnu.org\fP ارسال شوند یا در گروه خبری یوزنت .B gnu.bash.bug منتشر گردند. .PP نظرات و گزارش‌های اشکال مربوط به این صفحه راهنما باید به .IR chet.ramey@case.edu ارسال شوند.