نام (NAME)

bt_macros - دسترسی به جدول ماکروهای btparse و دستکاری آن

خلاصه دستور (SYNOPSIS)

void bt_add_macro_value (AST *  assignment,
                         btshort options);
void bt_add_macro_text (char * macro,
                        char * text,
                        char * filename,
                        int    line);
void bt_delete_macro (char * macro);
void bt_delete_all_macros (void);
int bt_macro_length (char *macro);
char * bt_macro_text (char * macro,
                      char * filename,
                      int line);

توضیحات (DESCRIPTION)

btparse یک جدول واحد از تمامی ماکروهای (کوته‌نوشت‌های) دیده‌شده هنگام تجزیه مدخل‌های BibTeX نگهداری می‌کند. این جدول هر زمان که با یک مدخل «تعریف ماکرو» (@string) مواجه شود به‌روزرسانی شده و هر زمان که ماکرویی در یک مدخل به کار رود و نیاز به بسط داشته باشد، به آن ارجاع داده می‌شود. (ماکروها لزوماً در ورودی بسط داده نمی‌شوند، اگرچه این حالت پیش‌فرض است. به bt_postprocess مراجعه کنید.) تعاریف ماکروها تنها زمانی پاک می‌شوند که تابع پاک‌سازی سراسری btparse، یعنی bt_cleanup()، فراخوانی شود. بنابراین، مگر اینکه صراحتاً bt_delete_macro() یا bt_delete_all_macros() را فراخوانی کنید، تعاریف ماکرو تا زمانی که از کتابخانه استفاده می‌کنید --- معمولاً طول عمر فرایند شما --- باقی می‌مانند.

توابع (FUNCTIONS)

می‌توانید از توابع زیر برای افزودن ماکروها، حذف آن‌ها، و پرس‌وجوی مقادیرشان استفاده کنید --- و در نتیجه، در حین اجرا در عملکرد عادی btparse مداخله نمایید.

bt_add_macro_text ()

void bt_add_macro_text (char * macro,
                        char * text,
                        char * filename,
                        int    line);

یک ماکروی جدید تعریف می‌کند، یا ماکروی قدیمی را مجدداً تعریف می‌نماید. "macro" نام ماکرو است، و "text" متنی است که ماکرو باید به آن بسط یابد. "filename" و "line" صرفاً برای ایجاد هرگونه هشدار درباره تعریف ماکرو به کار می‌روند؛ اگر کاربردی ندارند، مقدار "NULL" را برای "filename" و 0 را برای "line" مشخص کنید. تنها هشداری از این دست زمانی رخ می‌دهد که یک ماکروی قدیمی را مجدداً تعریف کنید: مقدار آن بازنویسی می‌شود و bt_add_macro_text() هشداری مبنی بر این موضوع صادر می‌کند.

برای نمونه، هنگام تجزیه این مدخل تعریف ماکرو:

@string{fubar = "Fouled Up Beyond All Recognition"}

کتابخانه (به‌ویژه کد پس‌پردازشی که پس از تجزیه موفق یک مدخل فراخوانی می‌شود) در نهایت این کار را انجام می‌دهد:

bt_add_macro_text ("fubar", "Fouled Up Beyond All Recognition",
                   filename, line);

این امر به نوبه خود باعث می‌شود که هر زمان کد پس‌پردازش ماکروی "fubar" را در مدخل‌های بعدی ببیند، آن را به درستی بسط دهد.

bt_add_macro_value ()

void bt_add_macro_value (AST *  assignment,
                         btshort options);

این تابع عمدتاً برای استفاده داخلی کتابخانه است، اما اگر زمانی تکه‌ای از AST در دست داشتید که نمایانگر یک تعریف ماکرو است و می‌خواستید خودتان ماکرو را تنظیم کنید (به‌جای اینکه اجازه دهید کد پس‌پردازش کتابخانه این کار را برایتان انجام دهد)، برای شما در دسترس است. "assignment" باید یک گره AST باشد همان‌طور که توسط bt_next_field() برگردانده می‌شود. برخلاف بیشتر توابع دیگر btparse که یک آرگومان "options" می‌پذیرند، "options" در اینجا مشخص می‌کند که مقدار موجود در "assignment" چگونه پس‌پردازش شده است. این امر به این دلیل لازم است که مقادیر ماکرو باید به شیوه‌ای ویژه پردازش شوند تا در بسط‌های آینده معتبر باشند؛ اگر این مقدار به آن شیوه پردازش نشده باشد، bt_add_macro_value() آن را برایتان انجام خواهد داد. اگر نمی‌دانید مقدار چگونه پس‌پردازش شده است، کافی است مقدار 0 را برای "options" ارائه دهید --- این کار تضمین می‌کند مقداری متفاوت از «شیوه درست» برای ماکروها توصیف شود، بنابراین پس‌پردازش به‌درستی انجام خواهد شد.

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

@string{and = " and "}
@string{jim_n_bob = "James Smith" # and # "Bob Jones"}

آنگاه مقداری که برای "jim_n_bob" ذخیره می‌شود آشکارا باید رشتهٔ "James Smith and Bob Jones" باشد. برای اطمینان از این موضوع، btparse باید مقدار "and" را متفاوت از بیشتر رشته‌های BibTeX پردازش کند: به‌ویژه، فاصله‌های خالی پیش از ذخیره شدن رشته ادغام نمی‌شوند. بدین ترتیب، مقدار صحیح یعنی " and " درون مقدار "jim_n_bob" درج می‌شود. بنابراین، تمام مقادیر ماکرو پیش از ذخیره شدن، زیرماکروهایشان بسط داده شده و رشته‌هایشان به هم متصل می‌شوند، اما فاصله‌های خالی تا زمانی که ماکرو در یک مدخل معمولی به کار نرود، ادغام نمی‌شوند.

این تابع bt_add_macro_text() را فراخوانی می‌کند، بنابراین همان هشدار درباره بازتعریف ماکروهای قدیمی اعمال می‌شود --- هشداری صادر شده و مقدار قدیمی از بین می‌رود.

bt_delete_macro ()

void bt_delete_macro (char * macro);

یک ماکرو را از جدول ماکروها حذف می‌کند. اگر "macro" تعریف نشده باشد، هیچ عملی انجام نمی‌گیرد.

bt_delete_all_macros ()

void bt_delete_all_macros (void);

تمام ماکروها را از جدول ماکروها حذف می‌کند.

bt_macro_length ()

int bt_macro_length (char *macro);

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

bt_macro_text ()

char * bt_macro_text (char * macro,
                      char * filename,
                      int line);

متن بسط‌یافته یک ماکرو را برمی‌گرداند. اگر ماکرو تعریف نشده باشد، هشداری صادر کرده و "NULL" برمی‌گرداند. "filename" و "line" برای ایجاد این هشدار استفاده می‌شوند؛ اگر کاربردی ندارند (یعنی ماکرو را در نتیجه یافتن آن در فایلی بسط نمی‌دهید)، برای "filename" مقدار "NULL" و برای "line" مقدار 0 را مشخص کنید.

همچنین ببینید (SEE ALSO)

btparse

نویسنده (AUTHOR)

Greg Ward <gward@python.net>