.\" -*- 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_TRAVERSAL 1" .TH BT_TRAVERSAL 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_traversal \- توابع پیمایش و پرس‌وجوی AST در کتابخانه btparse .SH "خلاصه دستور (SYNOPSIS)" .IX Header "SYNOPSIS" .Vb 7 \& AST * bt_next_entry (AST * entry_list, \& AST * prev_entry) \& AST * bt_next_field (AST * entry, AST * prev, char ** name) \& AST * bt_next_value (AST * head, \& AST * prev, \& bt_nodetype_t * nodetype, \& char ** text) \& \& bt_metatype_t bt_entry_metatype (AST * entry) \& char * bt_entry_type (AST * entry) \& char * bt_entry_key (AST * entry) \& char * bt_get_text (AST * node) .Ve .SH "توضیحات (DESCRIPTION)" .IX Header "DESCRIPTION" توابعی که در اینجا شرح داده شده‌اند، همگی برای پیمایش و پرس‌وجوی درخت‌های نحو انتزاعی (ASTها) بازگردانده‌شده توسط توابع ورودیِ شرح‌داده‌شده در bt_input به کار می‌روند. سه تابع «bt_next» (\f(CWbt_next_entry()\fR، \&\f(CWbt_next_field()\fR و \f(CWbt_next_value()\fR) به ترتیب برای پیمایش فهرستی از مدخل‌ها، فهرست فیلدهای درون یک مدخل خاص، و فهرست مقادیر سادهٔ مرتبط با یک فیلد خاص استفاده می‌شوند. سایر توابع صرفاً برای پرس‌وجوی گره‌های مختلف در درخت جهت استخراج اطلاعات مفید موجود در آن‌ها به کار می‌روند. .SS "توابع پیمایش (Traversal functions)" .IX Subsection "Traversal functions" .IP \fBbt_next_entry()\fR 4 .IX Item "bt_next_entry()" .Vb 2 \& AST * bt_next_entry (AST * entry_list, \& AST * prev_entry) .Ve .Sp برای پیمایش لیست پیوندی مدخل‌های بازگردانده‌شده توسط \&\f(CWbt_parse_file()\fR (به bt_input مراجعه کنید) استفاده می‌شود. در فراخوانی نخست، باید مقدار \f(CW\*(C`NULL\*(C'\fR را برای \f(CW\*(C`prev_entry\*(C'\fR ارسال کنید، تا اشاره‌گری به ابتدای لیست بازگردانده شود. در فراخوانی‌های بعدی، مقدار بازگشتی قبلی را به عنوان \f(CW\*(C`prev_entry\*(C'\fR ارسال کنید؛ تابع مدخل بعدی در فهرست را بازمی‌گرداند، یا اگر مدخل دیگری وجود نداشته باشد، \f(CW\*(C`NULL\*(C'\fR برمی‌گرداند. همچنین در صورتی که هر یک از \f(CW\*(C`entry_list\*(C'\fR یا \f(CW\*(C`prev_entry\*(C'\fR نامعتبر باشند، \f(CW\*(C`NULL\*(C'\fR برمی‌گرداند. .Sp به عنوان مثال (صرف‌نظر از مدیریت خطا و اعلان متغیرها): .Sp .Vb 6 \& entries = bt_parse_file (filename, options, &status); \& entry = NULL; \& while (entry = bt_next_entry (entries, entry)) \& { \& /* process entry */ \& } .Ve .IP \fBbt_next_field()\fR 4 .IX Item "bt_next_field()" .Vb 1 \& AST * bt_next_field (AST * entry, AST * prev, char ** name) .Ve .Sp برای پیمایش فهرست فیلدها در یک مدخل عادی یا تعریف ماکرو استفاده می‌شود. (پیش از فراخوانی \f(CWbt_next_field()\fR باید \f(CWbt_entry_metatype()\fR را فراخوانی کنید تا مشخص شود آیا نوع مدخل مناسب است یا خیر.) آرگومان \f(CW\*(C`entry\*(C'\fR باید اشاره‌گری به AST یک مدخل واحد باشد، همان‌طور که توسط \f(CWbt_parse_entry()\fR، \&\f(CWbt_parse_entry_s()\fR، یا \f(CWbt_next_entry()\fR بازگردانده می‌شود. در فراخوانی نخست، برای \f(CW\*(C`prev\*(C'\fR مقدار \f(CW\*(C`NULL\*(C'\fR را ارسال کنید؛ \f(CWbt_next_field()\fR اشاره‌گری به نخستین فیلد در \f(CW\*(C`entry\*(C'\fR بازمی‌گرداند، یا اگر \f(CW\*(C`entry\*(C'\fR فاقد فیلد باشد (برای نمونه اگر یک مدخل comment یا preamble باشد)، مقدار \f(CW\*(C`NULL\*(C'\fR را بازمی‌گرداند. در فراخوانی‌های بعدی، مقدار بازگشتی قبلی را به عنوان \f(CW\*(C`prev\*(C'\fR ارسال کنید؛ \f(CWbt_next_field()\fR تا زمانی که معتبر باشد به بازگرداندن اشاره‌گرها به زیردرخت‌های AST فیلد ادامه می‌دهد. سپس می‌توان این اشاره‌گرها را به \f(CWbt_next_value()\fR یا \f(CWbt_get_text()\fR ارسال کرد تا مقدار فیلد دریافت شود. .Sp برای نمونه، بدنهٔ حلقه در مثال قبلی می‌تواند چنین باشد: .Sp .Vb 5 \& field = NULL; \& while (field = bt_next_field (entry, field, &field_name)) \& { \& /* process field */ \& } .Ve .IP \fBbt_next_value()\fR 4 .IX Item "bt_next_value()" .Vb 4 \& AST * bt_next_value (AST * head, \& AST * prev, \& bt_nodetype_t * nodetype, \& char ** text) .Ve .Sp فهرست مقادیر ساده‌ای را که مقدار یک فیلد منفرد را تشکیل می‌دهند می‌پیماید. (به یاد داشته باشید که یک مقدار ساده، یا یک رشتهٔ درون گیومه است، یا فراخوانی یک ماکرو، یا یک عدد. مقدار مرکب فهرستی از این موارد است که در ورودی اصلی با \f(CW\*(Aq#\*(Aq\fR از یکدیگر جدا شده‌اند. بسته به گزینه‌های پس‌پردازش رشته که هنگام تجزیهٔ داده‌ها استفاده شده است، ماهیت «فهرستی از مقادیر ساده» در داده‌های اصلی ممکن است در AST مورد پیمایش شما حفظ شده باشد، که در این حالت به یک حلقهٔ \f(CWbt_next_value()\fR نیاز خواهید داشت.) .Sp تابع \&\f(CWbt_next_value()\fR بسیار شبیه به \f(CWbt_next_entry()\fR و \f(CWbt_next_field()\fR عمل می‌کند: در فراخوانی نخست، \f(CW\*(C`NULL\*(C'\fR را برای \f(CW\*(C`prev\*(C'\fR مشخص می‌کنید، و در فراخوانی‌های بعدی مقدار بازگشتی قبلی را ارسال می‌نمایید. هنگامی که مقدار سادهٔ دیگری برای بازگرداندن وجود نداشته باشد، مقدار \f(CW\*(C`NULL\*(C'\fR را برمی‌گرداند. همچنین مقادیر \f(CW*nodetype\fR و \f(CW*text\fR را روی اطلاعات متناظر برگرفته از گره مقدار ساده تنظیم می‌کند. \f(CW*nodetype\fR یکی از مقادیر \f(CW\*(C`BTAST_STRING\*(C'\fR، \&\f(CW\*(C`BTAST_MACRO\*(C'\fR یا \f(CW\*(C`BTAST_NUMBER\*(C'\fR خواهد بود؛ \f(CW*text\fR به همان رشته‌ای اشاره خواهد کرد که گره AST اشاره دارد (برای شما کپی نمی‌شود)، بنابراین آن را تغییر ندهید. .Sp برای نمونه، بدنهٔ حلقه در مثال \f(CWbt_next_field()\fR می‌تواند با کد زیر جایگزین شود: .Sp .Vb 10 \& value = NULL; \& while (value = bt_next_field (field, value, &nodetype, &text)) \& { \& switch (nodetype) \& { \& case BTAST_STRING: /* process the string */ \& case BTAST_MACRO: /* process the macro */ \& case BTAST_NUMBER: /* process the number */ \& } \& } .Ve .Sp همچنین بخش «bt_get_text» را ببینید. .SS "توابع پرس‌وجو (Query functions)" .IX Subsection "Query functions" .IP \fBbt_entry_metatype()\fR 4 .IX Item "bt_entry_metatype()" .Vb 1 \& bt_metatype_t bt_entry_metatype (AST * entry) .Ve .Sp نوع‌دادهٔ فراگیر (metatype) یک مدخل را بازمی‌گرداند. (به یاد داشته باشید که \fImetatype\fR یک نوع شمارشی است که مقادیر آن از نوع خاص یک مدخل مشتق می‌شوند؛ برای نمونه، یک مدخل \f(CW@comment\fR دارای نوع \f(CW"comment"\fR و metatype از نوع \f(CW\*(C`BTE_COMMENT\*(C'\fR است. رابطهٔ نوع و نوع‌دادهٔ فراگیر (type\-metatype) به همین ترتیب برای \f(CW\*(C`BTE_PREAMBLE\*(C'\fR نیز آشکار است؛ \f(CW\*(C`BTE_MACRODEF\*(C'\fR متناظر با مدخل‌های \f(CW@string\fR است؛ و \f(CW\*(C`BTE_REGULAR\*(C'\fR متناظر با هر نوع دیگری است.) .Sp اگر \f(CW\*(C`entry\*(C'\fR نامعتبر باشد (یعنی \f(CW\*(C`NULL\*(C'\fR باشد یا اشاره‌گری به AST مدخل نباشد)، \f(CW\*(C`BTE_UNKNOWN\*(C'\fR را بازمی‌گرداند. .IP \fBbt_entry_type()\fR 4 .IX Item "bt_entry_type()" .Vb 1 \& char * bt_entry_type (AST * entry) .Ve .Sp نوع یک مدخل را بازمی‌گرداند. به یاد داشته باشید که نوع، همان نامی است که پس از نویسهٔ \f(CW\*(Aq@\*(Aq\fR در ورودی اصلی ظاهر می‌شود. در صورتی که \f(CW\*(C`entry\*(C'\fR نامعتبر باشد (یعنی \f(CW\*(C`NULL\*(C'\fR باشد یا اشاره‌گری به AST یک مدخل نباشد)، \f(CW\*(C`NULL\*(C'\fR را برمی‌گرداند. .IP \fBbt_entry_key()\fR 4 .IX Item "bt_entry_key()" .Vb 1 \& char * bt_entry_key (AST * entry) .Ve .Sp کلید ارجاع (citation key) یک مدخل عادی را بازمی‌گرداند. (کلید ارجاع، نامی است که پس از نویسهٔ جداکنندهٔ بازکنندهٔ مدخل در یک مدخل عادی ظاهر می‌شود.) در صورتی که \f(CW\*(C`entry\*(C'\fR نامعتبر باشد (یعنی \f(CW\*(C`NULL\*(C'\fR باشد یا اشاره‌گری به AST یک مدخل عادی نباشد)، \f(CW\*(C`NULL\*(C'\fR را بازمی‌گرداند. .IP \fBbt_get_text()\fR 4 .IX Item "bt_get_text()" .Vb 1 \& char * bt_get_text (AST * node) .Ve .Sp تمام عملیات پس‌پردازش رشته (بسط ماکرو، الحاق مقادیر ساده، و فشرده‌سازی فاصله‌های سفید) را برای یک مقدار مرکب انجام می‌دهد و رشتهٔ حاصل را بازمی‌گرداند. این تابع را می‌توان یا روی یک فیلد از یک مدخل عادی یا تعریف ماکرو (همان‌طور که توسط \f(CWbt_next_field()\fR بازگردانده شده)، یا روی یک مدخل comment یا preamble فراخوانی کرد. اگر روی یک گره AST نامعتبر فراخوانی شود، مقدار \f(CW\*(C`NULL\*(C'\fR را برمی‌گرداند. .SH "همچنین ببینید (SEE ALSO)" .IX Header "SEE ALSO" btparse, bt_input, bt_postprocess .SH "نویسنده (AUTHOR)" .IX Header "AUTHOR" Greg Ward