نام (NAME)

bt_input - توابع ورودی و تجزیه در کتابخانه btparse

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

void  bt_set_stringopts (bt_metatype_t metatype, btshort options);
AST * bt_parse_entry_s (char *    entry_text,
                        char *    filename,
                        int       line,
                        btshort    options,
                        boolean * status);
AST * bt_parse_entry   (FILE *    infile,
                        char *    filename,
                        btshort    options,
                        boolean * status);
AST * bt_parse_file    (char *    filename, 
                        btshort    options, 
                        boolean * overall_status);

توضیحات (DESCRIPTION)

توابعی که در اینجا شرح داده شده‌اند برای خواندن و تجزیه داده‌های BibTeX و تبدیل آن‌ها از متن خام به درخت‌های نحو انتزاعی (AST) به کار می‌روند.

bt_set_stringopts ()

void bt_set_stringopts (bt_metatype_t metatype, btshort options);

گزینه‌های پردازش رشته را برای یک متاتایپ مدخل خاص تنظیم می‌کند. این امر بر پس‌پردازش مدخل که توسط bt_parse_entry_s()، bt_parse_entry()، و bt_parse_file() انجام می‌شود اثر می‌گذارد. اگر bt_set_stringopts() هرگز فراخوانی نشود، چهار متاتایپ به‌طور پیش‌فرض از مجموعه‌های گزینه‌های رشته زیر استفاده می‌کنند:

BTE_REGULAR    BTO_CONVERT | BTO_EXPAND | BTO_PASTE | BTO_COLLAPSE
BTE_COMMENT    0
BTE_PREAMBLE   0
BTE_MACRODEF   BTO_CONVERT | BTO_EXPAND | BTO_PASTE

برای مثال،

bt_set_stringopts (BTE_COMMENT, BTO_COLLAPSE);

باعث می‌شود کتابخانه فاصله‌های سفید را در مقدار حاصل از همه مدخل‌های توضیح (comment) جمع و ادغام کند؛ AST بازگردانده‌شده توسط یکی از توابع "bt_parse_*" این تغییر را منعکس خواهد کرد.

bt_parse_entry ()

AST * bt_parse_entry (FILE *    infile,
                      char *    filename,
                      btshort    options,
                      boolean * status);

مدخل بعدی BibTeX را در "infile" پویش و تجزیه می‌کند. شما باید "filename" را مشخص کنید تا به btparse در تولید پیام‌های خطای دقیق کمک نماید؛ کتابخانه شماره سطر جاری "infile" را به‌طور داخلی پیگیری می‌کند، بنابراین نیازی نیست که آن را ارسال کنید. آرگومان "options" باید یک نگاشت بیتی (bitmap) از گزینه‌های غیرمرتبط با پردازش رشته باشد (در حال حاضر، "BTO_NOSTORE" برای غیرفعال کردن ذخیره بسط‌های ماکرو تنها گزینه از این دست است). در صورتی که مدخل با موفقیت یا فقط با هشدارهای جزئی تجزیه شود، *status برابر با "TRUE" تنظیم می‌شود و در صورت وجود هرگونه خطای لغوی یا نحوی جدی، برابر با "FALSE" خواهد بود. اگر "status" برابر با "NULL" باشد، وضعیت تجزیه در دسترس شما نخواهد بود. هر دو نوع هشدارهای جزئی و خطاهای جدی در "stderr" گزارش می‌شوند.

اشاره‌گری به درخت نحو انتزاعی (AST) توصیف‌کننده مدخل تازه تجزیه‌شده بازمی‌گرداند، یا اگر مدخل دیگری در "infile" یافت نشود، "NULL" برمی‌گرداند (این وضعیت، "infile" را در پایان فایل یا end-of-file رها می‌کند). سعی نکنید با تشخیص پایان فایل توسط خودتان، رفتار bt_parse_entry() را پیش‌بینی کنید؛ باید اجازه دهید خودش پایان فایل را تشخیص دهد تا بتواند برخی داده‌های ایستا را که بین فراخوانی‌ها برای همان فایل حفظ می‌شوند پاک‌سازی کند.

تابع bt_parse_entry() دارای دو محدودیت مهم است که باید از آن‌ها مطلع باشید. نخست، باید اجازه دهید btparse تمام ورودی‌های فایل را مدیریت کند؛ این امر هم به دلایل ظاهری است (تا کتابخانه شماره سطر جاری را برای تولید پیام‌های خطای دقیق بداند) و هم به دلایل بنیادی (کتابخانه باید اجازه داشته باشد پایان فایل را تشخیص دهد تا متغیرهای ایستای خاصی را پاک‌سازی کرده و به شما امکان تجزیه فایلی دیگر را بدهد). دوم، نمی‌توانید تجزیه دو فایل مختلف را به صورت متناوب و هم‌زمان (interleave) انجام دهید؛ اقدام به انجام این کار منجر به یک خطای مهلک می‌شود که برنامه شما را متوقف می‌کند (crash). این امر نتیجه مستقیم حالت ایستایی است که بین فراخوانی‌های bt_parse_entry() نگه‌داری می‌شود.

به دلیل دو نوع «شکست» متمایز ممکن برای bt_parse_entry() (پایان فایل، که مورد انتظار است اما به معنای توقف پردازش فایل جاری است؛ و خطا در ورودی، که غیرمنتظره است اما به شما اجازه می‌دهد به پردازش همان فایل ادامه دهید)، معمولاً باید آن را به این صورت فراخوانی کنید:

while (entry = bt_parse_entry (file, filename, options, &ok))
{
   if (ok)
   {
      /* ... process entry ... */
   }
}

در پایان این حلقه، مقدار "feof (file)" درست (true) خواهد بود.

bt_parse_entry_s ()

AST * bt_parse_entry_s (char *    entry_text,
                        char *    filename,
                        int       line,
                        btshort    options,
                        boolean * status)

یک مدخل منفرد و کامل BibTeX موجود در یک رشته، یعنی "entry_text"، را پویش و تجزیه می‌کند. اگر این رشته را از یک فایل خوانده‌اید، باید با مشخص کردن نام فایل در آرگومان "filename" و شماره سطر ابتدای مدخل در آرگومان "line"، به btparse در تولید پیام‌های خطای دقیق کمک کنید؛ در غیر این صورت، "filename" را روی "NULL" و "line" را روی 1 تنظیم نمایید. آرگومان‌های "options" و "status" همانند bt_parse_entry() هستند.

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

باید bt_parse_entry_s() را یک بار بیشتر از تعداد کل مدخل‌هایی که مایل به تجزیه آن‌ها هستید فراخوانی کنید؛ در آخرین فراخوانی، "entry_text" را روی "NULL" تنظیم کنید تا تابع بداند متنی برای تجزیه باقی نمانده است. این فراخوانی نهایی به آن اجازه می‌دهد تا برخی ساختارهایی را که در فراخوانی نخست تخصیص یافته بودند پاک‌سازی کند. بنابراین، معمولاً از bt_parse_entry_s() به این صورت استفاده می‌شود:

char *  entry_text;
btshort  options = 0;
boolean ok;
AST *   entry_ast;
while (entry_text = get_more_text ())
{
   entry_ast = bt_parse_entry_s (entry_text, NULL, 1, options, &ok);
   if (ok)
   {
      /* ... process entry ... */
   }
}
bt_parse_entry_s (NULL, NULL, 1, options, NULL);    /* cleanup */

با این فرض که get_more_text() اشاره‌گری به متن یک مدخل برای تجزیه برمی‌گرداند، یا اگر متن بیشتری در دسترس نباشد، مقدار "NULL" را بازمی‌گرداند.

bt_parse_file ()

AST * bt_parse_file (char *    filename, 
                     btshort    options, 
                     boolean * status)

یک فایل کامل BibTeX را پویش و تجزیه می‌کند. اگر "filename" برابر با "NULL" یا "-" باشد، ورودی استاندارد ("stdin") خوانده خواهد شد؛ در غیر این صورت، تلاش می‌کند فایل نام‌برده‌شده را باز کند. اگر این تلاش ناموفق باشد، پیامی خطا در "stderr" چاپ کرده و "NULL" برمی‌گرداند. آرگومان‌های "options" و "status" همانند bt_parse_entry() هستند---توجه داشته باشید که اگر هر خطایی در کل فایل وجود داشته باشد، *status برابر با "FALSE" خواهد بود؛ برای بررسی دقیق‌تر و جزءبه‌جزء خطاها، باید از bt_parse_entry() استفاده کنید.

اشاره‌گری به یک لیست پیوندی از ASTها که مدخل‌های درون فایل را نشان می‌دهند بازمی‌گرداند، یا اگر مدخلی در فایل یافت نشود، مقدار "NULL" را برمی‌گرداند. این لیست را می‌توان با bt_next_entry() پیمایش کرد و سپس مدخل‌های مجزا را طبق معمول مورد پیمایش قرار داد (به bt_traversal مراجعه کنید).

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

btparse, bt_postprocess, bt_traversal

نویسندگان (AUTHORS)

Greg Ward <gward@python.net>