نام (NAME)

bt_format_names - قالب‌بندی و بازترکیب نام‌ها برای خروجی یکدست در کتابخانه btparse

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

bt_name_format * bt_create_name_format (char * parts,
                                        boolean abbrev_first);
void bt_free_name_format (bt_name_format * format);
void bt_set_format_text (bt_name_format * format,
                         bt_namepart part,
                         char * pre_part,
                         char * post_part,
                         char * pre_token,
                         char * post_token);
void bt_set_format_options (bt_name_format * format,
                            bt_namepart part,
                            boolean abbrev,
                            bt_joinmethod join_tokens,
                            bt_joinmethod join_part);
char * bt_format_name (bt_name * name, bt_name_format * format);

توضیحات (DESCRIPTION)

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

«قالب نام» در قالب ساختار "bt_name_format" کپسوله‌سازی شده است که با تابع bt_create_name_format() ساخته می‌شود. این تابع شامل منطقی هوشمندانه است که باعث می‌شود در بیشتر موارد تنها فراخوانی همین تابع کافی باشد و نیازی به سفارشی‌سازی بیشتر قالب نداشته باشید. با این حال اگر نیاز به سفارشی‌سازی داشته باشید، توابع bt_set_format_text() و bt_set_format_options() این قابلیت را فراهم می‌کنند.

این قالب موارد زیر را کنترل می‌کند:

کدام بخش‌های نام چاپ شوند و به چه ترتیبی (مثلاً "first von last jr" یا "von last jr first")
متنی که قبل و بعد از هر بخش قرار می‌گیرد (مثلاً اگر نام کوچک پس از نام خانوادگی بیاید، معمولاً قبل از بخش `first` به یک کاما نیاز دارید: "Smith, John" به‌جای "Smith John")
متنی که قبل و بعد از هر توکن قرار می‌گیرد (مثلاً اگر نام کوچک مخفف شده باشد، ممکن است بعد از هر توکن یک نقطه بخواهید: "J. R. Smith" به‌جای "J R Smith")
روشی که برای پیوند دادن توکن‌های مربوط به یک بخش به یکدیگر استفاده می‌شود
روشی که برای پیوند دادن هر بخش به بخش بعدی استفاده می‌شود

تمام این موارد به‌جز فهرست بخش‌های مورد نظر برای قالب‌بندی، در آرایه‌هایی نگهداری می‌شوند که اندیس آن‌ها بخش‌های نام است؛ برای مثال، این ساختار دارای فیلدی به‌شکل زیر است:

char * post_token[BT_MAX_NAMEPARTS]

و مقدار "post_token[BTN_FIRST]" (که "BTN_FIRST" از نوع شمارشی "bt_namepart" است) رشته‌ای است که پس از هر توکن در نام کوچک اضافه می‌شود---برای نمونه، اگر نام کوچک به روش مرسوم مخفف شود، مقدار آن "." خواهد بود.

نوع شمارشی دیگری به نام "bt_joinmethod" روش‌های موجود برای پیوند دادن توکن‌ها به یکدیگر را مشخص می‌کند. توجه داشته باشید که دو دسته روش پیوند در قالب نام وجود دارد: پیوند بین توکن‌های درون یک بخش واحد، و پیوند بین توکن‌های دو بخش متفاوت. دسته نخست به شما امکان می‌دهد برای نمونه "J R Smith" (نام کوچک مخفف بدون متن پس‌توکن ولی با توکن‌های جدا شده با فاصله) را به "JR Smith" (همان حالت، اما با توکن‌های چسبیده به هم در نام کوچک) تبدیل کنید. دسته دوم عمدتاً برای اطمینان از این استفاده می‌شود که بخش‌های "von" و "last" با یک نیم‌فاصله نشکن (tie) به هم پیوند داده شوند: "de~Roche" به‌جای "de Roche".

روش‌های پیوند توکن‌ها عبارتند از:

BTJ_MAYTIE: درج یک نیم‌فاصله اختیاری (discretionary tie) بین توکن‌ها؛ یعنی بسته به زمینه، یک فاصله معمولی یا یک فاصله نشکن (tie) درج می‌شود. (فاصله نشکن که در TeX با "~" شناخته می‌شود، فعلاً به‌صورت پیش‌فرض هاردکد شده است.)
سپس این قالب توسط تابع bt_format_name() بر روی یک نام خاص اعمال می‌شود و یک رشته جدید برمی‌گرداند.
BTJ_SPACE: همیشه یک فاصله بین توکن‌ها درج می‌کند.
BTJ_FORCETIE: همیشه یک فاصله نشکن ("~") بین توکن‌ها درج می‌کند.
BTJ_NOTHING: هیچ چیزی بین توکن‌ها درج نمی‌کند---توکن‌ها مستقیماً به هم می‌چسبند.

پیوند دادن توکن‌ها و در نتیجه تصمیم‌گیری درباره درج فاصله نشکن اختیاری، در دو موقعیت انجام می‌شود: درون یک بخش و بین دو بخش. طبیعتاً این قاعده تنها زمانی اعمال می‌شود که مقدار "BTJ_MAYTIE" به‌عنوان روش پیوند انتخاب شده باشد؛ مقادیر "BTJ_SPACE" و "BTJ_FORCETIE" همواره به ترتیب فاصله یا نیم‌فاصله نشکن درج می‌کنند، و "BTJ_NOTHING" همیشه هیچ کاراکتری بین توکن‌ها اضافه نمی‌کند. در درون یک بخش، در صورتی که توکن اول کمتر از سه نویسه طول داشته باشد بعد از آن، و همچنین قبل از توکن آخر فاصله نشکن اضافه می‌شود. در میان دو بخش، فاصله نشکن تنها زمانی اضافه می‌شود که بخش قبلی از یک توکن منفرد با طول کمتر از سه نویسه تشکیل شده باشد. در تمامی موارد دیگر، فاصله معمولی درج می‌شود. (این پیاده‌سازی دقیقاً از رفتار BibTeX پیروی می‌کند.)

توابع (FUNCTIONS)

bt_create_name_format()

bt_name_format * bt_create_name_format (char * parts,
                                        boolean abbrev_first)

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

پارامتر "parts" مشخص می‌کند که چه بخش‌هایی در نام قالب‌بندی‌شده گنجانده شوند و ترتیب قرارگیری آن‌ها چگونه باشد. "parts" باید رشته‌ای شامل حداکثر چهار نویسه باشد که هر یک نشان‌دهنده یکی از چهار بخش نام است: برای نمونه، "vljf" به معنای قالب‌بندی هر چهار بخش به ترتیب "von last jr first" است. استفاده از نویسه‌هایی خارج از مجموعه "fvlj" مجاز نیست و هیچ نویسه‌ای نباید تکرار شود. پارامتر "abbrev_first" تعیین می‌کند که آیا بخش `first` مخفف شود یا خیر (یعنی فقط حرف اول هر توکن چاپ شود).

علاوه بر تنظیم فهرست بخش‌ها و فلگ مخفف‌سازی نام کوچک، تابع bt_create_name_format() کل ساختار قالب را به‌گونه‌ای مقداردهی اولیه می‌کند که نیاز به سفارشی‌سازی‌های بعدی به حداقل برسد:

«روش پیوند توکن‌ها»---آنچه بین توکن‌های یک بخش درج می‌شود---برای تمام بخش‌ها روی "BTJ_MAYTIE" (فاصله نشکن اختیاری) تنظیم می‌شود.
«روش پیوند بخش‌ها»---آنچه پس از آخرین توکن یک بخش خاص (با فرض وجود بخش‌های بعدی) درج می‌شود---برای بخش‌های `first`، `last` و `jr` روی "BTJ_SPACE" تنظیم می‌شود. اگر بخش `von` وجود داشته باشد و بلافاصله قبل از بخش `last` قرار گیرد (که تقریباً همیشه همین‌طور است)، از "BTJ_MAYTIE" برای اتصال `von` به `last` استفاده می‌شود؛ در غیر این صورت، برای `von` نیز از "BTJ_SPACE" به‌عنوان روش پیوند بین‌بخشی استفاده خواهد شد.
فلگ مخفف‌سازی برای بخش‌های `von`، `last` و `jr` برابر با "FALSE" قرار داده می‌شود؛ برای بخش `first`، این فلگ برابر با مقداری تنظیم می‌شود که در آرگومان "abbrev_first" ارسال کرده‌اید.
در ابتدا، تمام متون احاطه‌کننده (متن پیش‌بخش، پس‌بخش، پیش‌توکن و پس‌توکن) برای تمامی بخش‌ها رشته خالی تنظیم می‌شوند. سپس بسته به فلگ "abbrev_first" و ترتیب توکن‌ها چند تغییر اعمال می‌شود: نخست، اگر "abbrev_first" برابر با "TRUE" باشد، متن پس‌توکن برای نام کوچک روی "." تنظیم می‌شود---این کار "J R Smith" را به "J. R. Smith" تبدیل می‌کند که معمولاً شکل مطلوب است. (اگر نقطه‌ها را نمی‌خواهید، باید خودتان متن پس‌توکن را با bt_set_format_text() تنظیم کنید.)
سپس، اگر `jr` وجود داشته باشد و بلافاصله پس از `last` قرار گیرد (تقریباً همیشه چنین است)، متن پیش‌بخش برای `jr` برابر با ", " تنظیم شده و روش پیوند بین‌بخشی برای `last` روی "BTJ_NOTHING" قرار می‌گیرد. این تنظیم باعث می‌شود عبارت "John Smith Jr" (که در آن فاصله پس از "Smith" ناشی از قالب‌بندی نام خانوادگی با روش پیوند بین‌بخشی "BTJ_SPACE" بوده) به "John Smith, Jr" تبدیل شود (که در آن ", " اکنون به "Jr" وابسته است---به این ترتیب اگر بخش `jr` وجود نداشته باشد، ", " نیز چاپ نخواهد شد).

در نهایت، اگر `first` وجود داشته باشد و بلافاصله پس از `jr` یا `last` بیاید (که در قالب‌های «نام خانوادگی در ابتدا» معمولاً چنین است)، همین منطق اعمال می‌شود: متن پیش‌بخش برای `first` روی ", " تنظیم شده و روش پیوند بخش برای بخش قبلی (خواه `jr` باشد یا `last`) روی "BTJ_NOTHING" قرار می‌گیرد.

اگرچه تمامی این قواعد تا حدی پیچیده به نظر می‌رسند، اما باعث می‌شوند که معمولاً از انجام هرگونه سفارشی‌سازی دستی قالب نام بی‌نیاز شوید. این موضوع به‌ویژه زمانی صادق است که تنها به ترتیب‌های "fvlj" و "vljf" نیاز داشته باشید، فقط بخواهید نام کوچک را مخفف کنید، بعد از توکن‌های مخفف نقطه بگذارید، فاصله‌های نشکن در جای مناسب قرار گیرند و کاماها مطابق عرف درج شوند.

اگر به قالبی غیرمعمول نیاز دارید---برای مثال توکن‌های مخففِ چسبیده به هم بدون علامت‌گذاری نگارشی، یا مخفف کردن نام خانوادگی---باید قالب نام را با استفاده از توابع bt_set_format_text() و bt_set_format_options() سفارشی‌سازی کنید.

bt_free_name_format()

void bt_free_name_format (bt_name_format * format)

حافظه اختصاص‌یافته به قالب نام ایجادشده توسط bt_create_name_format() را آزاد می‌کند.

bt_set_format_text()

void bt_set_format_text (bt_name_format * format,
                         bt_namepart part,
                         char * pre_part,
                         char * post_part,
                         char * pre_token,
                         char * post_token)

به شما امکان می‌دهد بخشی از متون احاطه‌کننده یا تمامی آن‌ها را برای یک بخش منفرد از نام سفارشی‌سازی کنید. برای هر بخشی از متن که مایل به تغییر آن نیستید، مقدار "NULL" ارسال کنید.

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

format = bt_create_name_format ("fvlj", TRUE);
bt_set_format_text (format,
                    BTN_FIRST,       /* name-part to customize */
                    NULL, NULL,      /* pre- and post- part text */
                    NULL, "");       /* empty string for post-token */

بدون فراخوانی bt_set_format_text()، متغیر "format" نام‌ها را به‌صورت "J. R. Smith" قالب‌بندی می‌کرد. پس از تنظیم متن پس‌توکن برای نام کوچک روی ""، این نام به "J R Smith" تبدیل می‌شود.

bt_set_format_options()

void bt_set_format_options (bt_name_format * format,
                            bt_namepart part,
                            boolean abbrev,
                            bt_joinmethod join_tokens,
                            bt_joinmethod join_part)

امکان سفارشی‌سازی بیشتر قالب نام را فراهم می‌کند: می‌توانید فلگ مخفف‌سازی و دو روش پیوند توکن را تنظیم کنید. متأسفانه سازوکاری برای بدون تغییر گذاشتن یک مقدار وجود ندارد؛ باید همه گزینه‌ها را با bt_set_format_options() مقداردهی کنید.

به‌عنوان مثال، فرض کنید حذف نقطه‌ها از توکن‌های مخفف در نام کوچک کافی نیست و واقعاً می‌خواهید با چسباندن توکن‌های مخفف به یکدیگر فضا را ذخیره کنید: "JR Smith" به‌جای "J R Smith". با فرض اینکه دو فراخوانی مثال قبلی انجام شده باشند، دستورات زیر کار را تکمیل می‌کنند:

bt_set_format_options (format, BTN_FIRST,
                       TRUE,         /* keep same value for abbrev flag */
                       BTJ_NOTHING,  /* jam tokens together */
                       BTJ_SPACE);   /* space after final token of part */

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

bt_format_name()

char * bt_format_name (bt_name * name, bt_name_format * format)

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

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

btparse, bt_split_names

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

Greg Ward <gward@python.net>