.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Required to disable full justification in groff 1.23.0. .if n .ds AD l .\" ======================================================================== .\" .IX Title "BT_INPUT 1" .TH BT_INPUT 1 2025-07-14 "btparse, version 0.91" btparse .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "نام (NAME)" bt_input \- توابع ورودی و تجزیه در کتابخانه btparse .SH "خلاصه دستور (SYNOPSIS)" .IX Header "SYNOPSIS" .Vb 10 \& 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); .Ve .SH "توضیحات (DESCRIPTION)" .IX Header "DESCRIPTION" توابعی که در اینجا شرح داده شده‌اند برای خواندن و تجزیه داده‌های BibTeX و تبدیل آن‌ها از متن خام به درخت‌های نحو انتزاعی (AST) به کار می‌روند. .IP "bt_set_stringopts ()" 4 .IX Item "bt_set_stringopts ()" .Vb 1 \& void bt_set_stringopts (bt_metatype_t metatype, btshort options); .Ve .Sp گزینه‌های پردازش رشته را برای یک متاتایپ مدخل خاص تنظیم می‌کند. این امر بر پس‌پردازش مدخل که توسط \f(CWbt_parse_entry_s()\fR، \&\f(CWbt_parse_entry()\fR، و \f(CWbt_parse_file()\fR انجام می‌شود اثر می‌گذارد. اگر \f(CWbt_set_stringopts()\fR هرگز فراخوانی نشود، چهار متاتایپ به‌طور پیش‌فرض از مجموعه‌های گزینه‌های رشته زیر استفاده می‌کنند: .Sp .Vb 4 \& BTE_REGULAR BTO_CONVERT | BTO_EXPAND | BTO_PASTE | BTO_COLLAPSE \& BTE_COMMENT 0 \& BTE_PREAMBLE 0 \& BTE_MACRODEF BTO_CONVERT | BTO_EXPAND | BTO_PASTE .Ve .Sp برای مثال، .Sp .Vb 1 \& bt_set_stringopts (BTE_COMMENT, BTO_COLLAPSE); .Ve .Sp باعث می‌شود کتابخانه فاصله‌های سفید را در مقدار حاصل از همه مدخل‌های توضیح (comment) جمع و ادغام کند؛ AST بازگردانده‌شده توسط یکی از توابع \f(CW\*(C`bt_parse_*\*(C'\fR این تغییر را منعکس خواهد کرد. .IP "bt_parse_entry ()" 4 .IX Item "bt_parse_entry ()" .Vb 4 \& AST * bt_parse_entry (FILE * infile, \& char * filename, \& btshort options, \& boolean * status); .Ve .Sp مدخل بعدی BibTeX را در \f(CW\*(C`infile\*(C'\fR پویش و تجزیه می‌کند. شما باید \f(CW\*(C`filename\*(C'\fR را مشخص کنید تا به \fBbtparse\fR در تولید پیام‌های خطای دقیق کمک نماید؛ کتابخانه شماره سطر جاری \f(CW\*(C`infile\*(C'\fR را به‌طور داخلی پیگیری می‌کند، بنابراین نیازی نیست که آن را ارسال کنید. آرگومان \f(CW\*(C`options\*(C'\fR باید یک نگاشت بیتی (bitmap) از گزینه‌های غیرمرتبط با پردازش رشته باشد (در حال حاضر، \f(CW\*(C`BTO_NOSTORE\*(C'\fR برای غیرفعال کردن ذخیره بسط‌های ماکرو تنها گزینه از این دست است). در صورتی که مدخل با موفقیت یا فقط با هشدارهای جزئی تجزیه شود، \f(CW*status\fR برابر با \f(CW\*(C`TRUE\*(C'\fR تنظیم می‌شود و در صورت وجود هرگونه خطای لغوی یا نحوی جدی، برابر با \f(CW\*(C`FALSE\*(C'\fR خواهد بود. اگر \f(CW\*(C`status\*(C'\fR برابر با \f(CW\*(C`NULL\*(C'\fR باشد، وضعیت تجزیه در دسترس شما نخواهد بود. هر دو نوع هشدارهای جزئی و خطاهای جدی در \f(CW\*(C`stderr\*(C'\fR گزارش می‌شوند. .Sp اشاره‌گری به درخت نحو انتزاعی (AST) توصیف‌کننده مدخل تازه تجزیه‌شده بازمی‌گرداند، یا اگر مدخل دیگری در \f(CW\*(C`infile\*(C'\fR یافت نشود، \f(CW\*(C`NULL\*(C'\fR برمی‌گرداند (این وضعیت، \f(CW\*(C`infile\*(C'\fR را در پایان فایل یا end\-of\-file رها می‌کند). سعی نکنید با تشخیص پایان فایل توسط خودتان، رفتار \f(CWbt_parse_entry()\fR را پیش‌بینی کنید؛ باید اجازه دهید خودش پایان فایل را تشخیص دهد تا بتواند برخی داده‌های ایستا را که بین فراخوانی‌ها برای همان فایل حفظ می‌شوند پاک‌سازی کند. .Sp تابع \f(CWbt_parse_entry()\fR دارای دو محدودیت مهم است که باید از آن‌ها مطلع باشید. نخست، باید اجازه دهید \fBbtparse\fR تمام ورودی‌های فایل را مدیریت کند؛ این امر هم به دلایل ظاهری است (تا کتابخانه شماره سطر جاری را برای تولید پیام‌های خطای دقیق بداند) و هم به دلایل بنیادی (کتابخانه باید اجازه داشته باشد پایان فایل را تشخیص دهد تا متغیرهای ایستای خاصی را پاک‌سازی کرده و به شما امکان تجزیه فایلی دیگر را بدهد). دوم، نمی‌توانید تجزیه دو فایل مختلف را به صورت متناوب و هم‌زمان (interleave) انجام دهید؛ اقدام به انجام این کار منجر به یک خطای مهلک می‌شود که برنامه شما را متوقف می‌کند (crash). این امر نتیجه مستقیم حالت ایستایی است که بین فراخوانی‌های \f(CWbt_parse_entry()\fR نگه‌داری می‌شود. .Sp به دلیل دو نوع «شکست» متمایز ممکن برای \f(CWbt_parse_entry()\fR (پایان فایل، که مورد انتظار است اما به معنای توقف پردازش فایل جاری است؛ و خطا در ورودی، که غیرمنتظره است اما به شما اجازه می‌دهد به پردازش همان فایل ادامه دهید)، معمولاً باید آن را به این صورت فراخوانی کنید: .Sp .Vb 7 \& while (entry = bt_parse_entry (file, filename, options, &ok)) \& { \& if (ok) \& { \& /* ... process entry ... */ \& } \& } .Ve .Sp در پایان این حلقه، مقدار \f(CW\*(C`feof (file)\*(C'\fR درست (true) خواهد بود. .IP "bt_parse_entry_s ()" 4 .IX Item "bt_parse_entry_s ()" .Vb 5 \& AST * bt_parse_entry_s (char * entry_text, \& char * filename, \& int line, \& btshort options, \& boolean * status) .Ve .Sp یک مدخل منفرد و کامل BibTeX موجود در یک رشته، یعنی \f(CW\*(C`entry_text\*(C'\fR، را پویش و تجزیه می‌کند. اگر این رشته را از یک فایل خوانده‌اید، باید با مشخص کردن نام فایل در آرگومان \f(CW\*(C`filename\*(C'\fR و شماره سطر ابتدای مدخل در آرگومان \f(CW\*(C`line\*(C'\fR، به \fBbtparse\fR در تولید پیام‌های خطای دقیق کمک کنید؛ در غیر این صورت، \f(CW\*(C`filename\*(C'\fR را روی \f(CW\*(C`NULL\*(C'\fR و \f(CW\*(C`line\*(C'\fR را روی \f(CW1\fR تنظیم نمایید. آرگومان‌های \f(CW\*(C`options\*(C'\fR و \f(CW\*(C`status\*(C'\fR همانند \f(CWbt_parse_entry()\fR هستند. .Sp اشاره‌گری به درخت نحو انتزاعی (AST) توصیف‌کننده مدخل تازه تجزیه‌شده برمی‌گرداند، و اگر هیچ مدخلی در \f(CW\*(C`entry_text\*(C'\fR یافت نشود یا \f(CW\*(C`entry_text\*(C'\fR برابر با \f(CW\*(C`NULL\*(C'\fR باشد، مقدار \f(CW\*(C`NULL\*(C'\fR را بازمی‌گرداند. .Sp باید \f(CWbt_parse_entry_s()\fR را یک بار بیشتر از تعداد کل مدخل‌هایی که مایل به تجزیه آن‌ها هستید فراخوانی کنید؛ در آخرین فراخوانی، \f(CW\*(C`entry_text\*(C'\fR را روی \f(CW\*(C`NULL\*(C'\fR تنظیم کنید تا تابع بداند متنی برای تجزیه باقی نمانده است. این فراخوانی نهایی به آن اجازه می‌دهد تا برخی ساختارهایی را که در فراخوانی نخست تخصیص یافته بودند پاک‌سازی کند. بنابراین، معمولاً از \f(CWbt_parse_entry_s()\fR به این صورت استفاده می‌شود: .Sp .Vb 4 \& 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 */ .Ve .Sp با این فرض که \f(CWget_more_text()\fR اشاره‌گری به متن یک مدخل برای تجزیه برمی‌گرداند، یا اگر متن بیشتری در دسترس نباشد، مقدار \f(CW\*(C`NULL\*(C'\fR را بازمی‌گرداند. .IP "bt_parse_file ()" 4 .IX Item "bt_parse_file ()" .Vb 3 \& AST * bt_parse_file (char * filename, \& btshort options, \& boolean * status) .Ve .Sp یک فایل کامل BibTeX را پویش و تجزیه می‌کند. اگر \f(CW\*(C`filename\*(C'\fR برابر با \f(CW\*(C`NULL\*(C'\fR یا \f(CW"\-"\fR باشد، ورودی استاندارد (\f(CW\*(C`stdin\*(C'\fR) خوانده خواهد شد؛ در غیر این صورت، تلاش می‌کند فایل نام‌برده‌شده را باز کند. اگر این تلاش ناموفق باشد، پیامی خطا در \f(CW\*(C`stderr\*(C'\fR چاپ کرده و \f(CW\*(C`NULL\*(C'\fR برمی‌گرداند. آرگومان‌های \f(CW\*(C`options\*(C'\fR و \f(CW\*(C`status\*(C'\fR همانند \f(CWbt_parse_entry()\fR هستند\-\-\-توجه داشته باشید که اگر \fIهر\fR خطایی در کل فایل وجود داشته باشد، \f(CW*status\fR برابر با \f(CW\*(C`FALSE\*(C'\fR خواهد بود؛ برای بررسی دقیق‌تر و جزءبه‌جزء خطاها، باید از \f(CWbt_parse_entry()\fR استفاده کنید. .Sp اشاره‌گری به یک لیست پیوندی از ASTها که مدخل‌های درون فایل را نشان می‌دهند بازمی‌گرداند، یا اگر مدخلی در فایل یافت نشود، مقدار \f(CW\*(C`NULL\*(C'\fR را برمی‌گرداند. این لیست را می‌توان با \f(CWbt_next_entry()\fR پیمایش کرد و سپس مدخل‌های مجزا را طبق معمول مورد پیمایش قرار داد (به bt_traversal مراجعه کنید). .SH "همچنین ببینید (SEE ALSO)" .IX Header "SEE ALSO" btparse, bt_postprocess, bt_traversal .SH "نویسندگان (AUTHORS)" .IX Header "AUTHORS" Greg Ward