.\" -*- 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_SPLIT_NAMES 1" .TH BT_SPLIT_NAMES 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_split_names \- تفکیک نام‌ها و فهرست‌های نام در BibTeX .SH "خلاصه دستور (SYNOPSIS)" .IX Header "SYNOPSIS" .Vb 11 \& bt_stringlist * bt_split_list (char * string, \& char * delim, \& char * filename, \& int line, \& char * description); \& void bt_free_list (bt_stringlist *list); \& bt_name * bt_split_name (char * name, \& char * filename, \& int line, \& int name_num); \& void bt_free_name (bt_name * name); .Ve.SH "توضیحات (DESCRIPTION)" .IX Header "DESCRIPTION" هنگامی که پرونده‌های BibTeX برای هدف اصلی خود\-\-\-مدخل‌های کتاب‌شناختی که انتشارات علمی را توصیف می‌کنند\-\-\-استفاده می‌شوند، پردازش فهرست‌هایی از نام‌ها (بیشتر نویسندگان و ویراستاران) اهمیت می‌یابد. اگرچه چنین پردازش نامی خارج از حوزهٔ پایگاه‌دادهٔ چندمنظورهٔ بیشتر بخش‌های کتابخانهٔ \fBbtparse\fR است، این توابع تفکیک به عنوان سازشی با واقعیت ارائه شده‌اند: بیشتر پرونده‌های دادهٔ BibTeX از قراردادهای BibTeX برای نام‌های نویسندگان استفاده می‌کنند، و کتابخانه‌ای که آن داده‌ها را پردازش می‌کند باید توانایی پردازش نام‌ها را نیز داشته باشد. .PP پردازش نام در دو مرحله صورت می‌گیرد: نخست، تقسیم یک فهرست از نام‌ها به رشته‌های مجزا؛ دوم، تقسیم هر نام به «بخش‌ها» (first، von، last، و jr). مرحلهٔ اول در واقع کاملاً عمومی است: می‌توانید یک جداکننده (مانند \f(CW\*(Aqand\*(Aq\fR، که برای فهرست‌های نام به کار می‌رود) را برگزینید و از آن برای تقسیم هر رشته‌ای به زیررشته‌ها بهره ببرید. سپس می‌توان \f(CWbt_split_list()\fR را برای شکستن رشتهٔ اصلی و استخراج زیررشته‌ها فراخوانی کرد. با این حال، \&\f(CWbt_split_name()\fR کاملاً مختص به نام‌های چهاربخشی نویسندگان است که با استفاده از قراردادهای BibTeX نوشته شده‌اند. (این قراردادها به طور غیررسمی در هر مستندات BibTeX شرح داده شده‌اند؛ توصیفی که در اینجا خواهید یافت رسمی‌تر و الگوریتمی‌تر\-\-\-و در نتیجه درکش دشوارتر است.) .PP برای اطلاعات دربارهٔ تبدیل دوبارهٔ نام‌های تفکیک‌شده به رشته‌ها به روش‌های گوناگون، bt_format_names را ببینید. .SH "توابع (FUNCTIONS)" .IX Header "FUNCTIONS" .IP \fBbt_split_list()\fR 4 .IX Item "bt_split_list()" .Vb 5 \& bt_stringlist * bt_split_list (char * string, \& char * delim, \& char * filename, \& int line, \& char * description) .Ve .Sp رشتهٔ \f(CW\*(C`string\*(C'\fR را به زیررشته‌هایی که با \f(CW\*(C`delim\*(C'\fR (یک رشتهٔ ثابت) از هم جدا شده‌اند تفکیک می‌کند. این تفکیک بر پایهٔ قواعدی انجام می‌گیرد که BibTeX برای تفکیک فهرست نام‌ها استفاده می‌کند، به‌ویژه: .RS 4 .IP \(bu 4 جداکننده‌ها در ابتدا یا انتهای رشته نادیده گرفته می‌شوند .IP \(bu 4 جداکننده‌ها باید با فاصلهٔ خالی (whitespace) احاطه شده باشند .IP \(bu 4 تطابق جداکننده‌ها بدون حساسیت به بزرگی و کوچکی حروف است .IP \(bu 4 جداکننده‌ها در عمق غیرصفر آکولادها نادیده گرفته می‌شوند .RE .RS 4 .Sp برای نمونه، اگر جداکننده \f(CW"and"\fR باشد، آنگاه رشتهٔ .Sp .Vb 1 \& Candy and Apples AnD {Green Eggs and Ham} .Ve .Sp به سه زیررشته تفکیک می‌شود: \f(CW"Candy"\fR، \f(CW"Apples"\fR، و \&\f(CW"{Green Eggs and Ham}"\fR. .Sp اگر جداکننده‌های اضافی در دو انتهای رشته باشند\-\-\-برای نمونه، یک \f(CW"and"\fR در ابتدای رشته\-\-\-در این صورت در اولین/آخرین رشته لحاظ می‌شوند؛ در حال حاضر هیچ هشداری چاپ نمی‌شود، اما ممکن است این رفتار تغییر کند. جداکننده‌های متوالی (\f(CW"and and"\fR) به صدور هشدار و افزوده شدن یک رشتهٔ NULL به فهرست زیررشته‌ها منجر می‌شوند. برای نمونه، رشتهٔ .Sp .Vb 1 \& and Joe Q. Blow and and Smith, Jr., John .Ve .Sp به سه زیررشته تفکیک خواهد شد: \f(CW"and Joe Q. Blow"\fR، \f(CW\*(C`NULL\*(C'\fR، و \&\f(CW"Smith, Jr., John"\fR. .Sp (اگر این قواعد تا اندازه‌ای عجیب به نظر می‌رسند، مرا سرزنش نکنید: من فقط رفتار مشاهده‌شده در BibTeX را پیاده‌سازی کرده‌ام و پیام‌های هشداری را برای یکی از خطاهای واضح‌تر و آسان‌تر برای شناسایی افزوده‌ام.) .Sp زیررشته‌ها در قالب یک ساختار \f(CW\*(C`bt_stringlist\*(C'\fR بازگردانده می‌شوند: .Sp .Vb 6 \& typedef struct \& { \& char * string; \& int num_items; \& char ** items; \& } bt_stringlist; .Ve .Sp در حال حاضر هیچ رابط تمیز و ساده‌ای برای این ساختار وجود ندارد: فقط باید خودتان درون آن به جستجو بپردازید. فیلدها عبارتند از: .ie n .IP """string""" 4 .el .IP \f(CWstring\fR 4 .IX Item "string" یک رونوشت از پارامتر \f(CW\*(C`string\*(C'\fR که به \f(CWbt_split_list()\fR ارسال شده است، اما با نویسه‌های NUL که جایگزین فاصلهٔ پس از هر زیررشته شده‌اند. (این امر ایمن است، زیرا جداکننده‌ها باید با فاصله‌های خالی احاطه شده باشند، یعنی پس از هر زیررشته یک فاصلهٔ خالی وجود دارد که بخشی از زیررشته نیست.) احتمالاً نباید با \f(CW\*(C`string\*(C'\fR دست‌کاری انجام دهید؛ این فیلد فقط به این دلیل وجود دارد تا \f(CWbt_free_list()\fR چیزی برای \f(CWfree()\fR کردن در اختیار داشته باشد. .ie n .IP """num_items""" 4 .el .IP \f(CWnum_items\fR 4 .IX Item "num_items" تعداد زیررشته‌های یافت‌شده در رشتهٔ ارسال‌شده به \&\f(CWbt_split_list()\fR. .ie n .IP """items""" 4 .el .IP \f(CWitems\fR 4 .IX Item "items" آرایه‌ای از اشاره‌گرهای \f(CW\*(C`num_items\*(C'\fR به درون \f(CW\*(C`string\*(C'\fR. برای نمونه، \&\f(CW\*(C`items[1]\*(C'\fR به زیررشتهٔ دوم اشاره دارد. از آنجا که \f(CW\*(C`string\*(C'\fR با نویسه‌های NUL تغییر یافته است، رفتار با \f(CW\*(C`items[i]\*(C'\fR به عنوان یک رشتهٔ عادی C ایمن است. .Sp پارامترهای \&\f(CW\*(C`filename\*(C'\fR، \f(CW\*(C`line\*(C'\fR، و \f(CW\*(C`description\*(C'\fR همگی برای تولید پیام‌های هشدار استفاده می‌شوند. \f(CW\*(C`filename\*(C'\fR و \f(CW\*(C`line\*(C'\fR صرفاً نشان می‌دهند که رشته از کجا آمده است، و \f(CW\*(C`description\*(C'\fR شرحی کوتاه (یک کلمه‌ای) از زیررشته‌ها است. برای نمونه، اگر فهرستی از نام‌ها را تفکیک می‌کنید، مقدار \f(CW"name"\fR را برای \f(CW\*(C`description\*(C'\fR وارد کنید\-\-\-به این ترتیب، هشدارها به جای «substring x» به «name X» اشاره خواهند کرد. .RE .RS 4 .RE .IP \fBbt_free_list()\fR 4 .IX Item "bt_free_list()" .Vb 1 \& void bt_free_list (bt_stringlist *list) .Ve .Sp یک ساختار \f(CW\*(C`bt_stringlist\*(C'\fR بازگردانده‌شده توسط \f(CWbt_split_list()\fR را آزاد می‌کند. یعنی، رونوشت رشته‌ای را که به \&\f(CWbt_split_list()\fR داده بودید آزاد کرده، و سپس خود ساختار را آزاد می‌نماید. .IP \fBbt_split_name()\fR 4 .IX Item "bt_split_name()" .Vb 4 \& bt_name * bt_split_name (char * name, \& char * filename, \& int line, \& int name_num) .Ve .Sp یک نام نویسنده با سبک BibTeX را به چهار بخش تفکیک می‌کند: first، von، last، و jr. این تابع می‌تواند تقریباً تمام نام‌ها به سبک زبان‌های عمدهٔ اروپای غربی را پردازش کند، اما نه به‌طور کامل. (افسوس!) .Sp تفکیک یک نام نخست با تقسیم آن به نشانه‌ها (tokens) انجام می‌گیرد؛ نشانه‌ها با فاصلهٔ خالی یا کاما در سطح آکولاد صفر از یکدیگر جدا می‌شوند. بنابراین نام .Sp .Vb 1 \& van der Graaf, Horace Q. .Ve .Sp پنج نشانه دارد، در حالی که نام .Sp .Vb 1 \& {Foo, Bar, and Sons} .Ve .Sp تنها شامل یک نشانه است. .Sp نحوهٔ تقسیم نشانه‌ها به بخش‌ها به ساختار و قالب نام بستگی دارد. اگر نام فاقد هرگونه کاما در سطح آکولاد صفر باشد (مانند مثال دوم)، آنگاه فرض می‌شود که در یکی از دو قالب «first last» یا «first von last» است. اگر هیچ نشانه‌ای وجود نداشته باشد که با حرف کوچک آغاز شود، آنگاه قالب «first last» فرض می‌شود: نشانهٔ پایانی نام خانوادگی (last) است، و تمام نشانه‌های دیگر نام کوچک (first) را تشکیل می‌دهند. در غیر این صورت، نخستین توالی پیوسته از نشانه‌ها که با حروف کوچک شروع می‌شوند به عنوان بخش \`von\*(Aq در نظر گرفته می‌شود؛ اگر این توالی شامل نشانهٔ پایانی باشد، آنگاه هشداری چاپ شده و نشانهٔ پایانی به اجبار بخش \`last\*(Aq تعیین می‌شود. .Sp اگر نام دارای یک کاما باشد، فرض می‌شود که در قالب «von last, first» است. توالی آغازین از نشانه‌ها با حروف ابتدایی کوچک، در صورت وجود، بخش \`von\*(Aq را می‌سازد؛ نشانه‌های میان \`von\*(Aq و کاما بخش \`last\*(Aq را تشکیل می‌دهند؛ نشانه‌های پس از کاما بخش \`first\*(Aq را می‌سازند. باز هم، اگر هیچ نشانه‌ای پس از توالی آغازین نشانه‌های با حروف کوچک وجود نداشته باشد، هشداری چاپ می‌شود و نشانه‌ای که بلافاصله پیش از کاما قرار دارد به عنوان بخش \`last\*(Aq در نظر گرفته می‌شود. .Sp اگر نام دارای بیش از دو کاما باشد، هشداری چاپ شده و با نام چنان رفتار می‌شود که گویی تنها دو کامای نخست وجود داشته‌اند. .Sp در نهایت، اگر نام دارای دو کاما باشد، فرض می‌شود در قالب «von last, jr, first» است. (این تنها روش برای نمایش نامی است که بخش \`jr\*(Aq دارد.) تجزیهٔ نام همانند نام دارای یک کاما است، با این تفاوت که نشانه‌های میان دو کاما به عنوان بخش \`jr\*(Aq در نظر گرفته می‌شوند. .Sp تنها موردی که قراردادهای نام BibTeX به‌درستی از عهدهٔ آن برنمی‌آیند، نامی دارای بخش \*(Aqjr\*(Aq است که با کاما از نام خانوادگی جدا نشده باشد؛ برای نمونه: .Sp.Vb 2 \& Henry Ford Jr. \& George Herbert Walker Bush III .Ve .Sp هر دوی این موارد هم توسط BibTeX و هم \&\fBbt_split_name()\fR به‌صورت نادرست تفسیر خواهند شد: نشانهٔ \f(CW"Jr."\fR یا \f(CW"III"\fR به عنوان نام خانوادگی در نظر گرفته می‌شود، و سایر نشانه‌ها به عنوان یک نام کوچک دو یا چهاربخشی قلمداد می‌شوند. راهکار دور زدن مشکل این است که \*(Aqjr\*(Aq را در نام خانوادگی بگنجانید: .Sp .Vb 2 \& Henry {Ford Jr.} \& George Herbert Walker {Bush III} .Ve .Sp اما این کار استخراج نام خانوادگی به تنهایی را غیرممکن می‌سازد، برای مثال جهت تولید ارجاع‌های سبک «نویسنده\-سال» ("author\-year"). این نقص طراحی ممکن است در نسخه‌های آیندهٔ \fBbtparse\fR برطرف شود. .Sp نام تفکیک‌شده به عنوان یک ساختار \f(CW\*(C`bt_name\*(C'\fR بازگردانده می‌شود: .Sp .Vb 6 \& typedef struct \& { \& bt_stringlist * tokens; \& char ** parts[BT_MAX_NAMEPARTS]; \& int part_len[BT_MAX_NAMEPARTS]; \& } bt_name; .Ve .Sp باز هم، هیچ رابط مناسبی برای این ساختار وجود ندارد؛ شما صرفاً باید به فیلدها به‌صورت جداگانه دسترسی داشته باشید. آن‌ها عبارتند از: .RS 4 .ie n .IP """tokens""" 4 .el .IP \f(CWtokens\fR 4 .IX Item "tokens" نام، تفکیک‌شده به یک فهرست تخت از نشانه‌ها. برای شرح ساختار \&\f(CW\*(C`bt_stringlist\*(C'\fR به موارد بالا مراجعه کنید. .ie n .IP """parts""" 4 .el .IP \f(CWparts\fR 4 .IX Item "parts" آرایه‌ای از آرایه‌هایی از اشاره‌گرها به فهرست نشانه‌ها. بُعد اصلی این ساختار، «بخش نام» است؛ شما باید این بُعد را با استفاده از شمارشگر \&\f(CW\*(C`bt_namepart\*(C'\fR اندیس‌گذاری کنید. برای نمونه، \f(CW\*(C`parts[BTN_LAST]\*(C'\fR آرایه‌ای از اشاره‌گرها به نشانه‌های تشکیل‌دهندهٔ نام خانوادگی است؛ \&\f(CW\*(C`parts[BTN_LAST][1]\*(C'\fR یک \f(CW\*(C`char *\*(C'\fR است: دومین نشانه از بخش \*(Aqlast\*(Aq؛ و \f(CW\*(C`parts[BTN_LAST][1][0]\*(C'\fR اولین نویسه از دومین نشانه از بخش \*(Aqlast\*(Aq است. .ie n .IP """part_len""" 4 .el .IP \f(CWpart_len\fR 4 .IX Item "part_len" طول هر بخش، بر حسب نشانه. برای نمونه، می‌توانید روی تمام نشانه‌ها در بخش \*(Aqfirst\*(Aq به صورت زیر پیمایش کنید (با این فرض که \f(CW\*(C`name\*(C'\fR یک \&\f(CW\*(C`bt_name *\*(C'\fR بازگردانده‌شده توسط \f(CWbt_split_name()\fR باشد): .Sp .Vb 5 \& for (i = 0; i < name\->part_len[BTN_FIRST]; i++) \& { \& printf ("token %d of first name: %s\en", \& i, name\->parts[BTN_FIRST][i]); \& } .Ve .RE .RS 4 .RE .IP \fBbt_free_name()\fR 4 .IX Item "bt_free_name()" .Vb 1 \& void bt_free_name (bt_name * name) .Ve .Sp ساختار \f(CW\*(C`bt_name\*(C'\fR ایجادشده توسط \f(CWbt_split_name()\fR (شامل ساختار \f(CW\*(C`bt_stringlist\*(C'\fR درون \f(CW\*(C`bt_name\*(C'\fR) را آزاد می‌کند. .SH "همچنین ببینید (SEE ALSO)" .IX Header "SEE ALSO" btparse, bt_format_names .SH "نویسنده (AUTHOR)" .IX Header "AUTHOR" Greg Ward