تعیین‌کننده‌های رویداد (Event Designators)

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

!

آغاز جایگزینی تاریخچه، مگر زمانی که پس از آن یک نویسه blank، خط جدید، = یا ( بیاید.

!n

ارجاع به خط فرمان n.

!-n

ارجاع به دستور فعلی منهای n.

!!

ارجاع به دستور قبلی. این مترادفی برای `!-1' است.

!string

ارجاع به جدیدترین دستور پیش از موقعیت فعلی در فهرست تاریخچه که با string آغاز می‌شود.

!?string[?]

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

^string1^string2^

جایگزینی سریع. تکرار آخرین دستور، با جایگزین کردن string1 با string2. معادل با ``!!:s^string1^string2^'' (بخش اصلاح‌کننده‌ها در زیر را ببینید).

!#

کل خط فرمان تایپ‌شده تا این لحظه.

تعیین‌کننده‌های کلمه (Word Designators)

تعیین‌کننده‌های کلمه برای انتخاب کلمات مورد نظر از رویداد استفاده می‌شوند. نویسه : مشخصه رویداد را از تعیین‌کننده کلمه جدا می‌سازد. اگر تعیین‌کننده کلمه با یکی از نویسه‌های ^، $، *، -، یا % آغاز شود، این دونقطه می‌تواند حذف گردد. کلمات از ابتدای خط شماره‌گذاری می‌شوند، و کلمه نخست با 0 (صفر) مشخص می‌شود. کلمات با تک‌فاصله جدا شده و در خط فعلی درج می‌گردند.

0 (zero)

کلمه صفرم. برای شل، این کلمه دستور است.

n

کلمه n-ام.

^

نخستین آرگومان؛ یعنی کلمه 1.

$

آخرین کلمه. این معمولاً آخرین آرگومان است، اما اگر تنها یک کلمه در خط وجود داشته باشد، به کلمه صفرم گسترش می‌یابد.

%

نخستین کلمه تطبیق‌یافته توسط جدیدترین جستجوی `?string?'، در صورتی که رشته جستجو با نویسه‌ای که بخشی از یک کلمه است آغاز شود.

x-y

محدوده‌ای از کلمات؛ `-y' مخفف `0-y' است.

*

همه کلمات به جز کلمه صفرم. این مترادفی برای `1-$' است. استفاده از * در صورتی که تنها یک کلمه در رویداد وجود داشته باشد خطا نیست؛ در این حالت رشته خالی بازگردانده می‌شود.

x*

مخفف x-$ است.

x-

همانند x* مخفف x-$ است، اما کلمه پایانی را حذف می‌کند. اگر x وجود نداشته باشد، به طور پیش‌فرض 0 است.

اگر تعیین‌کننده کلمه بدون مشخصه رویداد ارائه شود، دستور قبلی به عنوان رویداد استفاده می‌گردد.

اصلاح‌کننده‌ها (Modifiers)

پس از تعیین‌کننده کلمه اختیاری، ممکن است دنباله‌ای از یک یا چند مورد از اصلاح‌کننده‌های زیر بیاید که پیش از هر یک `:` قرار می‌گیرد. این‌ها کلمه یا کلمات انتخاب‌شده از رویداد تاریخچه را اصلاح یا ویرایش می‌کنند.

h

حذف بخش انتهایی نام فایل، به جا گذاشتن تنها سر (head).

t

حذف تمامی بخش‌های آغازین نام فایل، به جا گذاشتن دم (tail).

r

حذف پسوند انتهایی به قالب .xxx، به جا گذاشتن نام پایه (basename).

e

حذف همه چیز به جز پسوند انتهایی.

p

چاپ دستور جدید بدون اجرای آن.

q

نقل‌قول کردن کلمات جایگزین‌شده، جهت گریز از جایگزینی‌های بعدی.

x

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

s/old/new/

جایگزین کردن new به جای نخستین رخداد old در خط رویداد. هر نویسه‌ای می‌تواند به عنوان جداکننده به جای / استفاده شود. اگر جداکننده پایانی آخرین نویسه خط رویداد باشد، اختیاری است. جداکننده در old و new می‌تواند با یک ممیز وارونه نقل‌قول شود. اگر & در new ظاهر شود، با old جایگزین می‌شود. یک ممیز وارونه علامت & را نقل خواهد کرد. اگر old تهی باشد، روی آخرین old جایگزین‌شده، یا اگر قبلاً هیچ جایگزینی تاریخچه‌ای رخ نداده باشد، روی آخرین string در جستجوی !?string[?] تنظیم می‌شود. اگر new تهی باشد، هر old منطبق حذف می‌گردد.

&

تکرار جایگزینی قبلی.

g

اعمال تغییرات روی کل خط رویداد. این همراه با `:s' (برای مثال، `:gs/old/new/') یا `:&' به کار می‌رود. در صورت استفاده با `:s'، هر نویسه‌ای می‌تواند به جای / به عنوان جداکننده به کار رود، و اگر جداکننده پایانی آخرین نویسه خط رویداد باشد اختیاری است. نویسه a می‌تواند به عنوان مترادفی برای g استفاده شود.

G

اعمال اصلاح‌کننده `s' یا `&' بعدی، یک‌بار روی هر کلمه در خط رویداد.

مقدمه‌ای بر تاریخچه (Introduction to History)

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

کاربری که برنامه‌های نوشته‌شده با کتابخانه History را به کار می‌برد از مزیت یک رابط کاربری یکپارچه با مجموعه‌ای از دستورهای شناخته‌شده جهت دستکاری متن خطوط پیشین و استفاده از آن متن در دستورات جدید بهره‌مند می‌شود. دستورهای پایه‌ای دستکاری تاریخچه با جایگزینی تاریخچه ارائه‌شده توسط bash یکسان هستند.

برنامه‌نویس همچنین می‌تواند از کتابخانه readline استفاده کند، که به طور پیش‌فرض شامل برخی امکانات دستکاری تاریخچه است و مزیت افزوده ویرایش خط فرمان را دارد.

پیش از اعلان هر تابعی که از هر قابلیتی از کتابخانه History در کدهای دیگر استفاده می‌کند، توسعه‌دهنده برنامه باید فایل <readline/history.h> را در هر فایلی که از ویژگی‌های کتابخانه History استفاده می‌کند بگنجاند. این فایل اعلان‌های extern را برای تمام توابع و متغیرهای عمومی کتابخانه فراهم کرده و تمامی ساختارهای داده عمومی را اعلان می‌کند.

ذخیره‌سازی تاریخچه (History Storage)

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

typedef void * histdata_t;

typedef struct _hist_entry {
  char *line;
  char *timestamp;
  histdata_t data;
} HIST_ENTRY;

بنابراین خود فهرست تاریخچه ممکن است به این صورت اعلان شود:

HIST_ENTRY ** the_history_list;

وضعیت کتابخانه History در یک ساختار واحد کپسوله‌سازی می‌شود:

/*
 * ساختاری برای جابه‌جایی وضعیت فعلی تاریخچه.
 */
typedef struct _hist_state {
  HIST_ENTRY **entries; /* اشاره‌گر به خود مدخل‌ها. */
  int offset;           /* اشاره‌گر مکان درون این آرایه. */
  int length;           /* تعداد عناصر درون این آرایه. */
  int size;             /* تعداد خانه‌های اختصاص‌یافته به این آرایه. */
  int flags;
} HISTORY_STATE;

اگر عضو flags شامل HS_STIFLED باشد، تاریخچه محدود (stifled) شده است.

مقداردهی اولیه تاریخچه و مدیریت وضعیت (Initializing History and State Management)

این بخش توابع مورد استفاده برای مقداردهی اولیه و مدیریت وضعیت کتابخانه History را در زمان استفاده از توابع تاریخچه در برنامه شرح می‌دهد.

void using_history (void)
آغاز نشستی که در آن ممکن است از توابع تاریخچه استفاده شود. این تابع متغیرهای تعاملی را مقداردهی اولیه می‌کند.

HISTORY_STATE * history_get_history_state (void)
بازگرداندن ساختاری که وضعیت فعلی تاریخچه ورودی را شرح می‌دهد.

void history_set_history_state (HISTORY_STATE *state)
تنظیم وضعیت فهرست تاریخچه بر اساس state.

مدیریت فهرست تاریخچه (History List Management)

این توابع مدخل‌های منفرد در فهرست تاریخچه را مدیریت می‌کنند، یا پارامترهای حاکم بر خود فهرست را تعیین می‌نمایند.

void add_history (const char *string)
قرار دادن string در انتهای فهرست تاریخچه. فیلد داده مرتبط (در صورت وجود) روی NULL تنظیم می‌شود. اگر حداکثر تعداد مدخل‌های تاریخچه با استفاده از stifle_history() تنظیم شده باشد، و تعداد جدید مدخل‌های تاریخچه از آن حداکثر فراتر رود، قدیمی‌ترین مدخل تاریخچه حذف می‌شود.

void add_history_time (const char *string)
تغییر برچسب زمانی مرتبط با تازه‌ترین مدخل تاریخچه به string.

HIST_ENTRY * remove_history (int which)
حذف مدخل تاریخچه در آفست which از تاریخچه. عنصر حذف‌شده بازگردانده می‌شود تا بتوانید خط، داده و ساختار دربرگیرنده را آزاد کنید.

histdata_t free_history_entry (HIST_ENTRY *histent)
آزاد کردن مدخل تاریخچه histent و هرگونه داده خصوصی کتابخانه تاریخچه مرتبط با آن. داده‌های ویژه برنامه را بازمی‌گرداند تا فراخواننده بتواند آنها را مدیریت و آزاد کند.

HIST_ENTRY * replace_history_entry (int which, const char *line, histdata_t data)
تنظیم line و data برای مدخل تاریخچه در آفست which. این تابع مدخل قدیمی را بازمی‌گرداند تا فراخواننده بتواند داده‌های ویژه برنامه را مدیریت کند. در صورت نامعتبر بودن which، یک اشاره‌گر NULL بازگردانده می‌شود.

void clear_history (void)
پاک کردن فهرست تاریخچه از طریق حذف تمامی مدخل‌ها.

void stifle_history (int max)
محدود کردن فهرست تاریخچه، با نگه‌داری تنها max مدخل پایانی. فهرست تاریخچه در هر زمان تنها شامل حداکثر max مدخل خواهد بود.

int unstifle_history (void)
متوقف کردن محدودسازی تاریخچه. این تابع حداکثر تعداد قبلی تعیین‌شده برای مدخل‌های تاریخچه را بازمی‌گرداند (همان‌طور که توسط stifle_history() تعیین شده بود). مقدار در صورتی که تاریخچه محدود شده بود مثبت، و در غیر این صورت منفی است.

int history_is_stifled (void)
در صورتی که تاریخچه محدود شده باشد مقداری غیرصفر، و در غیر این صورت صفر بازمی‌گرداند.

اطلاعات درباره فهرست تاریخچه (Information About the History List)

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

HIST_ENTRY ** history_list (void)
بازگرداندن یک آرایه پایان‌یافته با NULL از HIST_ENTRY * که نشان‌دهنده تاریخچه ورودی فعلی است. عنصر 0 این فهرست ابتدای زمان است. اگر هیچ تاریخچه‌ای وجود نداشته باشد، NULL بازمی‌گرداند.

int where_history (void)
آفست عنصر فعلی تاریخچه را بازمی‌گرداند.

HIST_ENTRY * current_history (void)
بازگرداندن مدخل تاریخچه در موقعیت فعلی، همان‌طور که توسط where_history() تعیین می‌شود. اگر مدخلی در آنجا وجود نداشته باشد، یک اشاره‌گر NULL بازمی‌گرداند.

HIST_ENTRY * history_get (int offset)
بازگرداندن مدخل تاریخچه در موقعیت offset. دامنه مقادیر معتبر offset از history_base آغاز شده و در history_length - 1 پایان می‌یابد. اگر مدخلی در آنجا نباشد، یا اگر offset خارج از دامنه معتبر باشد، یک اشاره‌گر NULL بازمی‌گرداند.

time_t history_get_time (HIST_ENTRY *)
بازگرداندن برچسب زمانی مرتبط با مدخل تاریخچه‌ای که به عنوان آرگومان ارسال شده است.

int history_total_bytes (void)
بازگرداندن تعداد بایت‌هایی که مدخل‌های اصلی تاریخچه مصرف می‌کنند. این تابع مجموع طول تمامی خطوط موجود در تاریخچه را بازمی‌گرداند.

حرکت در فهرست تاریخچه (Moving Around the History List)

این توابع امکان تنظیم یا تغییر نمایه فعلی در فهرست تاریخچه را فراهم می‌سازند.

int history_set_pos (int pos)
تنظیم آفست فعلی تاریخچه روی pos، که یک نمایه مطلق در فهرست است. در صورت موفقیت 1، و اگر pos کمتر از صفر یا بزرگ‌تر از تعداد مدخل‌های تاریخچه باشد 0 بازمی‌گرداند.

HIST_ENTRY * previous_history (void)
عقب بردن آفست فعلی تاریخچه به مدخل قبلی، و بازگرداندن اشاره‌گری به آن مدخل. اگر مدخل قبلی وجود نداشته باشد، یک اشاره‌گر NULL بازمی‌گرداند.

HIST_ENTRY * next_history (void)
اگر آفست فعلی تاریخچه به یک مدخل معتبر تاریخچه اشاره کند، آفست فعلی تاریخچه را افزایش می‌دهد. اگر آفست افزایش‌یافته به یک مدخل معتبر تاریخچه اشاره داشته باشد، اشاره‌گری به آن مدخل بازمی‌گرداند؛ در غیر این صورت، یک اشاره‌گر NULL بازمی‌گرداند.

جستجو در فهرست تاریخچه (Searching the History List)

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

int history_search (const char *string, int direction)
جستجوی تاریخچه برای string، با شروع از آفست فعلی تاریخچه. اگر direction کمتر از 0 باشد، جستجو در میان مدخل‌های پیشین انجام می‌شود؛ در غیر این صورت در میان مدخل‌های پسین صورت می‌گیرد. اگر string یافت شود، نمایه فعلی تاریخچه روی آن مدخل تنظیم می‌شود و مقدار بازگردانده‌شده آفست در خط آن مدخل است که string در آن پیدا شد. در غیر این صورت، چیزی تغییر نمی‌کند و -1 بازگردانده می‌شود.

int history_search_prefix (const char *string, int direction)
جستجوی تاریخچه برای string، با شروع از آفست فعلی تاریخچه. جستجو لنگردار است: خطوط منطبق باید با string آغاز شوند. اگر direction کمتر از 0 باشد، جستجو در میان مدخل‌های قبلی انجام می‌شود؛ در غیر این صورت در میان مدخل‌های بعدی. اگر string پیدا شود، نمایه فعلی تاریخچه روی آن مدخل تنظیم شده و مقدار بازگشتی 0 است. در غیر این صورت، چیزی تغییر نمی‌کند و -1 بازگردانده می‌شود.

int history_search_pos (const char *string, int direction, int pos)
جستجو برای string در فهرست تاریخچه، با شروع از pos، که نمایه‌ای مطلق در فهرست است. اگر direction منفی باشد، جستجو رو به عقب از pos پیش می‌رود؛ در غیر این صورت رو به جلو. نمایه مطلق عنصر تاریخچه‌ای که string در آن یافت شد را بازمی‌گرداند، یا در غیر این صورت -1 بازمی‌گرداند.

مدیریت فایل تاریخچه (Managing the History File)

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

int read_history (const char *filename)
افزودن محتویات filename به فهرست تاریخچه، خط‌به‌خط. اگر filename برابر NULL باشد، از ~/.history خوانده می‌شود. در صورت موفقیت 0، یا در صورت عدم موفقیت errno را بازمی‌گرداند.

int read_history_range (const char *filename, int from, int to)
خواندن محدوده‌ای از خطوط از filename و افزودن آنها به فهرست تاریخچه. خواندن از خط from شروع شده و در to پایان می‌یابد. اگر from صفر باشد، از ابتدا آغاز می‌شود. اگر to کمتر از from باشد، تا انتهای فایل خوانده می‌شود. اگر filename برابر NULL باشد، از ~/.history خوانده می‌شود. در صورت موفقیت 0، و در صورت عدم موفقیت errno بازمی‌گرداند.

int write_history (const char *filename)
نوشتن تاریخچه فعلی در filename، با رونویسی روی filename در صورت لزوم. اگر filename برابر NULL باشد، فهرست تاریخچه در ~/.history نوشته می‌شود. در صورت موفقیت 0، یا در صورت بروز خطای خواندن یا نوشتن errno را بازمی‌گرداند.

int append_history (int nelements, const char *filename)
الحاق آخرین nelements عنصر از فهرست تاریخچه به filename. اگر filename برابر NULL باشد، به ~/.history الحاق می‌شود. در صورت موفقیت 0، یا در صورت بروز خطای خواندن یا نوشتن errno را بازمی‌گرداند.

int history_truncate_file (const char *filename, int nlines)
کوتاه کردن فایل تاریخچه filename، به جا گذاشتن تنها nlines خط پایانی. اگر filename برابر NULL باشد، ~/.history کوتاه می‌شود. در صورت موفقیت 0، یا در صورت شکست errno بازمی‌گرداند.

گسترش تاریخچه (History Expansion)

این توابع گسترش تاریخچه را پیاده‌سازی می‌کنند.

int history_expand (char *string, char **output)
گسترش string و قرار دادن نتیجه در output، که اشاره‌گری به یک رشته است. مقادیر بازگشتی:

char * get_history_event (const char *string, int *cindex, int qchar)
بازگرداندن متن رویداد تاریخچه‌ای که از string + *cindex آغاز می‌شود. مقدار *cindex تغییر می‌یابد تا به بعد از مشخص‌کننده رویداد اشاره کند. در هنگام ورود به تابع، cindex به نمایه‌ای درون string اشاره دارد که مشخصه رویداد تاریخچه از آنجا آغاز می‌گردد. آرگومان qchar نویسه‌ای است که علاوه بر نویسه‌های پایانی «معمولی»، مجاز به پایان دادن به مشخصه رویداد است.

char ** history_tokenize (const char *string)
بازگرداندن آرایه‌ای از نشانه‌ها (tokens) که از string تجزیه شده‌اند، همان‌گونه که شل عمل می‌کند. نشانه‌ها بر اساس نویسه‌های موجود در متغیر history_word_delimiters تفکیک می‌شوند و قواعد نقل‌قول شل رعایت می‌گردد.

char * history_arg_extract (int first, int last, const char *string)
استخراج بخشی از رشته متشکل از آرگومان‌های first تا last موجود در string. آرگومان‌ها با استفاده از history_tokenize() تفکیک می‌شوند.

متغیرهای تاریخچه (History Variables)

این بخش متغیرهای قابل مشاهده از خارج را که توسط کتابخانه GNU History صادر شده‌اند توصیف می‌کند.

int history_base
آفست منطقی نخستین مدخل در فهرست تاریخچه.

int history_length
تعداد مدخل‌هایی که در حال حاضر در فهرست تاریخچه ذخیره شده‌اند.

int history_max_entries
حداکثر تعداد مدخل‌های تاریخچه. این مقدار باید با استفاده از stifle_history() تغییر یابد.

int history_write_timestamps
اگر غیرصفر باشد، برچسب‌های زمانی در فایل تاریخچه نوشته می‌شوند تا بتوان آنها را میان نشست‌ها حفظ کرد. مقدار پیش‌فرض 0 است، به این معنی که برچسب‌های زمانی ذخیره نمی‌شوند. قالب فعلی برچسب زمانی از مقدار history_comment_char برای تحدید مدخل‌های برچسب زمانی در فایل تاریخچه استفاده می‌کند. اگر این متغیر مقداری نداشته باشد (حالت پیش‌فرض)، برچسب‌های زمانی نوشته نخواهند شد.

char history_expansion_char
نویسه‌ای که یک رویداد تاریخچه را معرفی می‌کند. مقدار پیش‌فرض ! است. تنظیم آن روی 0 گسترش تاریخچه را غیرفعال می‌سازد.

char history_subst_char
نویسه‌ای که اگر در ابتدای یک خط یافت شود جایگزینی کلمه را فراخوانی می‌کند. مقدار پیش‌فرض ^ است.

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

char * history_word_delimiters
نویسه‌هایی که نشانه‌ها را برای history_tokenize() جدا می‌سازند. مقدار پیش‌فرض " \t\n()<>;&|" است.

char * history_no_expand_chars
فهرست نویسه‌هایی که اگر بلافاصله پس از history_expansion_char ظاهر شوند، مانع گسترش تاریخچه می‌گردند. مقدار پیش‌فرض فاصله (space)، تب (tab)، خط جدید (newline)، \r و = است.

char * history_search_delimiter_chars
فهرست نویسه‌های اضافی که علاوه بر فاصله، تب، : و ? در حالت جستجوی زیررشته، می‌توانند رشته جستجوی تاریخچه را محدود کنند. مقدار پیش‌فرض تهی است.

int history_quotes_inhibit_expansion
اگر غیرصفر باشد، کلمات داخل نقل‌قول دوگانه برای نویسه گسترش تاریخچه یا نویسه توضیح تاریخچه پویش نمی‌شوند. مقدار پیش‌فرض 0 است.

rl_linebuf_func_t * history_inhibit_expansion_function
این متغیر باید روی آدرس تابعی تنظیم شود که دو آرگومان دریافت می‌کند: یک char * (string) و یک نمایه int در آن رشته (i). این تابع اگر گسترش تاریخچه با شروع از string[i] نباید انجام شود باید مقداری غیرصفر بازگرداند؛ و اگر گسترش باید صورت گیرد 0 بازگرداند. این برای استفاده توسط برنامه‌هایی نظیر bash در نظر گرفته شده است که از نویسه گسترش تاریخچه برای اهداف اضافی بهره می‌برند. به طور پیش‌فرض، این متغیر روی NULL تنظیم است.