نقاط ورودی پس‌پردازش (Post-processing entry points)

برای درک دلیل ارائه چهار نقطه ورود، توضیح نمونه AST ارائه‌شده در بالا کمک خواهد کرد. نخست اینکه کل مدخل با گره "(entry,"Article")" نمایش داده می‌شود؛ این گره کلید مدخل و تمام جفت‌های فیلد/مقدار را به عنوان فرزندان خود دارد. گره‌های مدخل توسط توابع bt_parse_entry() و bt_parse_entry_s() (به bt_input مراجعه کنید) و همچنین bt_next_entry() (که فهرستی از مدخل‌های برگشتی از bt_parse_file() را می‌پیماید - به bt_traversal مراجعه کنید) بازگردانده می‌شوند. کل مدخل‌ها را می‌توان با تابع bt_postprocess_entry() پس‌پردازش کرد.

همچنین ممکن است نیاز داشته باشید یک فیلد منفرد یا فقط مقدار مرتبط با آن را پس‌پردازش کنید (تفاوت در این است که پردازش فیلد علاوه بر مقدار فیلد می‌تواند نام فیلد را نیز تغییر دهد - مثلاً تبدیل آن به حروف کوچک). گره "(field,"AuThOr")" در بالا نمونه‌ای از یک زیردرخت فیلد است، و گره "(string,"Bob Jones")" نخستین گره در فهرست مقادیر ساده است که مقدار آن فیلد را نشان می‌دهد (به یاد داشته باشید که مقدار یک فیلد به‌طور کلی فهرستی از مقادیر ساده است). گره‌های فیلد توسط bt_next_field() و گره‌های مقدار توسط bt_next_value() بازگردانده می‌شوند. اولی را می‌توان برای پس‌پردازش به bt_postprocess_field() و دومی را به bt_postprocess_value() ارسال کرد.

در نهایت، ممکن است رشته‌های منفرد از منابعی غیر از AST کتابخانه btparse وارد برنامه شما شوند. به همین دلیل، تابع bt_postprocess_string() برای پس‌پردازش رشته‌های دلخواه در دسترس قرار دارد.

گزینه‌های پس‌پردازش (Post-processing options)

تمامی توابع پس‌پردازش دارای پارامتر "options" هستند که می‌توانید از آن برای تنظیم دقیق فرایند پس‌پردازش استفاده کنید (این پارامتر دقیقاً مانند گزینه‌های پردازش رشته بر اساس متاتایپ است که پیش از تجزیه مدخل‌ها تنظیم می‌کنید؛ به bt_set_stringopts() در bt_input مراجعه کنید). همانند سایر بخش‌های کتابخانه، "options" یک نگاشت بیتی (bitmap) است که از طریق ترکیب بیتی (OR منطقی) ثابت‌های از پیش تعریف‌شده مختلف ساخته می‌شود. این ثابت‌ها و اثرات آن‌ها در بخش "String processing option macros" از مستندات btparse شرح داده شده‌اند.

bt_postprocess_string ()

void bt_postprocess_string (char * s,
                            btshort options)

یک رشته منفرد "s" را پس‌پردازش می‌کند که درجا تغییر می‌یابد. تنها گزینه پس‌پردازش که برای رشته‌های منفرد معنادار است، فشرده‌سازی فاصله‌های خالی مطابق قوانین BibTeX است؛ بنابراین، اگر عبارت "options & BTO_COLLAPSE" نادرست (false) باشد، این تابع هیچ اثری نخواهد داشت (هرچند در هر حال یک پیمایش کامل روی رشته انجام می‌دهد که برای توسعه‌های آینده در نظر گرفته شده است).

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

bt_postprocess_value ()

char * bt_postprocess_value (AST *   value,
                             btshort  options,
                             boolean replace);

یک مقدار فیلد منفرد را پس‌پردازش می‌کند که سرلیستِ فهرستی از مقادیر ساده بازگردانده‌شده توسط bt_next_value() است. تمام گزینه‌های مربوط به پردازش رشته در اینجا وارد عمل می‌شوند: تبدیل اعداد به رشته ("BTO_CONVERT")، گسترش ماکروها ("BTO_EXPAND")، فشرده‌سازی فاصله‌های خالی ("BTO_COLLAPSE") و چسباندن رشته‌ها به یکدیگر ("BTO_PASTE"). از آنجا که چسباندن زیررشته‌ها به یکدیگر بدون گسترش ماکروها و تبدیل اعداد بی‌معنی خواهد بود، تلاش برای انجام چنین کاری یک خطای مهلک (fatal error) محسوب می‌شود.

اگر "replace" درست (true) باشد، فهرست با سرلیست "value" با فهرستی که مقدار پردازش‌شده را نشان می‌دهد جایگزین خواهد شد. یعنی اگر چسباندن رشته‌ها فعال باشد ("options & BTO_PASTE" درست باشد)، این فهرست به یک گره منفرد کاهش می‌یابد که حاوی رشته یکتای حاصل از پیوند همه زیررشته‌ها است. اگر چسباندن رشته‌ها فعال نباشد، هر گره در فهرست دست‌نخورده باقی می‌ماند اما متن آن با متن پردازش‌شده جایگزین می‌شود.

اگر "replace" نادرست (false) باشد، یک رشته جدید در لحظه ساخته شده و توسط تابع بازگردانده می‌شود. توجه داشته باشید که اگر در این حالت چسباندن فعال نباشد، فقط آخرین رشته موجود در فهرست را دریافت خواهید کرد (هرچند پس‌پردازش مقدار بدون چسباندن، مگر در حالتی که آن را با مقدار جدید جایگزین کنید، چندان معنادار نیست).

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

عملیاتی را در نظر بگیرید که می‌توان روی مقدار فیلد "author" در مثال بالا انجام داد، که ترکیبی از یک رشته، یک ماکرو و یک رشته دیگر است. فرض کنید ماکروی "and" به " and " بسط می‌یابد، و متغیر "value" به زیردرخت AST برای این مقدار اشاره می‌کند. زیردرخت AST اصلی متناظر با این مقدار عبارت است از:

(string,"Bob   Jones")
(macro,"and")
(string,"Jim Smith ")

برای پردازش کامل این مقدار به‌صورت درجا (in-place)، این تابع را به شکل زیر فراخوانی می‌کنید:

bt_postprocess_value (value, BTO_FULL, TRUE);

این فراخوانی مقدار را به یک فهرست تک‌عضوی تبدیل می‌کند:

(string,"Bob Jones and Jim Smith")

و رشته کاملاً پردازش‌شده "Bob Jones and Jim Smith" را بازمی‌گرداند. توجه داشته باشید که ماکروی "and" بسط یافته، میان دو رشته لفظی قرار گرفته، همه‌چیز به هم چسبانده شده و در نهایت فاصله‌های خالی فشرده شده‌اند (فشرده‌سازی فاصله‌های خالی پیش از اتصال رشته‌ها کار اشتباهی خواهد بود).

(به‌طور ضمنی، "BTO_FULL" صرفاً ماکرویی برای ترکیب تمام گزینه‌های ممکن پردازش رشته است، در حال حاضر شامل:

BTO_CONVERT | BTO_EXPAND | BTO_PASTE | BTO_COLLAPSE

دو ماکروی میان‌بر مشابه دیگر نیز وجود دارند: "BTO_MACRO" برای اعمال پردازش ویژه روی مقادیر ماکرو، که دقیقاً همانند "BTO_FULL" است با این تفاوت که "BTO_COLLAPSE" در آن وجود ندارد؛ و "BTO_MINIMAL" که به معنای عدم انجام هرگونه پردازش رشته است).

فرض کنید ترجیح می‌دهید ماهیت فهرستی مقدار را حفظ کنید، در حالی که ماکروها بسط داده شوند و هر عددی به رشته تبدیل شود (این تبدیل ساده است: صرفاً نوع گره را از "BTAST_NUMBER" به "BTAST_STRING" تغییر می‌دهد. مقادیر عددی همواره به صورت رشته‌ای از ارقام ذخیره می‌شوند، دقیقاً همان‌طور که در فایل آمده‌اند). این کار با فراخوانی زیر انجام می‌شود:

bt_postprocess_value
   (value, BTO_CONVERT|BTO_EXPAND|BTO_COLLAPSE,TRUE);

که فهرست را به این صورت تغییر می‌دهد:

(string,"Bob Jones")
(string,"and")
(string,"Jim Smith")

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

bt_postprocess_field ()

char * bt_postprocess_field (AST *   field,
                             btshort  options,
                             boolean replace);

این تابع چیزی بیش از یک رابط فرانت‌اند برای bt_postprocess_value() نیست؛ تنها تفاوت این است که یک گره AST از نوع "فیلد" (مانند "(field,"AuThOr")" در مثال بالا) به آن ارسال می‌کنید، و اینکه علاوه بر مقدار فیلد، نام فیلد را نیز دگرگون می‌سازد. به‌ویژه اینکه نام فیلد به حروف کوچک تبدیل می‌شود؛ این رفتار (در حال حاضر) اختیاری نیست.

رشته بازگردانده‌شده توسط bt_postprocess_value() را برمی‌گرداند.

bt_postprocess_entry ()

void bt_postprocess_entry (AST *  entry,
                           btshort options);

تمام مقادیر موجود در یک مدخل را پس‌پردازش می‌کند. اگر "entry" به AST یک مدخل "معمولی" (regular) یا "تعریف ماکرو" (macro definition) اشاره کند، مقادیر دقیقاً همان چیزی خواهند بود که انتظار دارید: هر آنچه در سمت راست یک فیلد یا "انتساب" ماکرو قرار دارد. همچنین می‌توانید مدخل‌های کامنت (comment) و پیش‌دیباچه (preamble) را نیز پس‌پردازش کنید. مدخل‌های کامنت اساساً یک رشته بزرگ هستند، بنابراین تنها فشرده‌سازی فاصله‌های خالی برای آن‌ها معنا دارد. مدخل‌های دیباچه ممکن است چندین رشته متصل به هم داشته باشند، بنابراین تمام گزینه‌های پردازش رشته روی آن‌ها اعمال می‌شوند (و هیچ مانعی برای استفاده از ماکروها در یک دیباچه وجود ندارد).