نام (NAME)

bt_traversal - توابع پیمایش و پرس‌وجوی AST در کتابخانه btparse

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

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)

توضیحات (DESCRIPTION)

توابعی که در اینجا شرح داده شده‌اند، همگی برای پیمایش و پرس‌وجوی درخت‌های نحو انتزاعی (ASTها) بازگردانده‌شده توسط توابع ورودیِ شرح‌داده‌شده در bt_input به کار می‌روند. سه تابع «bt_next» (bt_next_entry()، bt_next_field() و bt_next_value()) به ترتیب برای پیمایش فهرستی از مدخل‌ها، فهرست فیلدهای درون یک مدخل خاص، و فهرست مقادیر سادهٔ مرتبط با یک فیلد خاص استفاده می‌شوند. سایر توابع صرفاً برای پرس‌وجوی گره‌های مختلف در درخت جهت استخراج اطلاعات مفید موجود در آن‌ها به کار می‌روند.

توابع پیمایش (Traversal functions)

bt_next_entry()

AST * bt_next_entry (AST * entry_list, 
                     AST * prev_entry)

برای پیمایش لیست پیوندی مدخل‌های بازگردانده‌شده توسط bt_parse_file() (به bt_input مراجعه کنید) استفاده می‌شود. در فراخوانی نخست، باید مقدار "NULL" را برای "prev_entry" ارسال کنید، تا اشاره‌گری به ابتدای لیست بازگردانده شود. در فراخوانی‌های بعدی، مقدار بازگشتی قبلی را به عنوان "prev_entry" ارسال کنید؛ تابع مدخل بعدی در فهرست را بازمی‌گرداند، یا اگر مدخل دیگری وجود نداشته باشد، "NULL" برمی‌گرداند. همچنین در صورتی که هر یک از "entry_list" یا "prev_entry" نامعتبر باشند، "NULL" برمی‌گرداند.

به عنوان مثال (صرف‌نظر از مدیریت خطا و اعلان متغیرها):

entries = bt_parse_file (filename, options, &status);
entry = NULL;
while (entry = bt_next_entry (entries, entry))
{
   /* process entry */
}

bt_next_field()

AST * bt_next_field  (AST * entry, AST * prev, char ** name)

برای پیمایش فهرست فیلدها در یک مدخل عادی یا تعریف ماکرو استفاده می‌شود. (پیش از فراخوانی bt_next_field() باید bt_entry_metatype() را فراخوانی کنید تا مشخص شود آیا نوع مدخل مناسب است یا خیر.) آرگومان "entry" باید اشاره‌گری به AST یک مدخل واحد باشد، همان‌طور که توسط bt_parse_entry()، bt_parse_entry_s()، یا bt_next_entry() بازگردانده می‌شود. در فراخوانی نخست، برای "prev" مقدار "NULL" را ارسال کنید؛ bt_next_field() اشاره‌گری به نخستین فیلد در "entry" بازمی‌گرداند، یا اگر "entry" فاقد فیلد باشد (برای نمونه اگر یک مدخل comment یا preamble باشد)، مقدار "NULL" را بازمی‌گرداند. در فراخوانی‌های بعدی، مقدار بازگشتی قبلی را به عنوان "prev" ارسال کنید؛ bt_next_field() تا زمانی که معتبر باشد به بازگرداندن اشاره‌گرها به زیردرخت‌های AST فیلد ادامه می‌دهد. سپس می‌توان این اشاره‌گرها را به bt_next_value() یا bt_get_text() ارسال کرد تا مقدار فیلد دریافت شود.

برای نمونه، بدنهٔ حلقه در مثال قبلی می‌تواند چنین باشد:

field = NULL;
while (field = bt_next_field (entry, field, &field_name))
{
   /* process field */
}

bt_next_value()

AST * bt_next_value (AST * head, 
                     AST * prev,
                     bt_nodetype_t * nodetype,
                     char ** text)

فهرست مقادیر ساده‌ای را که مقدار یک فیلد منفرد را تشکیل می‌دهند می‌پیماید. (به یاد داشته باشید که یک مقدار ساده، یا یک رشتهٔ درون گیومه است، یا فراخوانی یک ماکرو، یا یک عدد. مقدار مرکب فهرستی از این موارد است که در ورودی اصلی با '#' از یکدیگر جدا شده‌اند. بسته به گزینه‌های پس‌پردازش رشته که هنگام تجزیهٔ داده‌ها استفاده شده است، ماهیت «فهرستی از مقادیر ساده» در داده‌های اصلی ممکن است در AST مورد پیمایش شما حفظ شده باشد، که در این حالت به یک حلقهٔ bt_next_value() نیاز خواهید داشت.)

تابع bt_next_value() بسیار شبیه به bt_next_entry() و bt_next_field() عمل می‌کند: در فراخوانی نخست، "NULL" را برای "prev" مشخص می‌کنید، و در فراخوانی‌های بعدی مقدار بازگشتی قبلی را ارسال می‌نمایید. هنگامی که مقدار سادهٔ دیگری برای بازگرداندن وجود نداشته باشد، مقدار "NULL" را برمی‌گرداند. همچنین مقادیر *nodetype و *text را روی اطلاعات متناظر برگرفته از گره مقدار ساده تنظیم می‌کند. *nodetype یکی از مقادیر "BTAST_STRING"، "BTAST_MACRO" یا "BTAST_NUMBER" خواهد بود؛ *text به همان رشته‌ای اشاره خواهد کرد که گره AST اشاره دارد (برای شما کپی نمی‌شود)، بنابراین آن را تغییر ندهید.

برای نمونه، بدنهٔ حلقه در مثال bt_next_field() می‌تواند با کد زیر جایگزین شود:

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 */
   }
}

همچنین بخش «bt_get_text» را ببینید.

توابع پرس‌وجو (Query functions)

bt_entry_metatype()

bt_metatype_t bt_entry_metatype (AST * entry)

نوع‌دادهٔ فراگیر (metatype) یک مدخل را بازمی‌گرداند. (به یاد داشته باشید که metatype یک نوع شمارشی است که مقادیر آن از نوع خاص یک مدخل مشتق می‌شوند؛ برای نمونه، یک مدخل @comment دارای نوع "comment" و metatype از نوع "BTE_COMMENT" است. رابطهٔ نوع و نوع‌دادهٔ فراگیر (type-metatype) به همین ترتیب برای "BTE_PREAMBLE" نیز آشکار است؛ "BTE_MACRODEF" متناظر با مدخل‌های @string است؛ و "BTE_REGULAR" متناظر با هر نوع دیگری است.)

اگر "entry" نامعتبر باشد (یعنی "NULL" باشد یا اشاره‌گری به AST مدخل نباشد)، "BTE_UNKNOWN" را بازمی‌گرداند.

bt_entry_type()

char * bt_entry_type (AST * entry)

نوع یک مدخل را بازمی‌گرداند. به یاد داشته باشید که نوع، همان نامی است که پس از نویسهٔ '@' در ورودی اصلی ظاهر می‌شود. در صورتی که "entry" نامعتبر باشد (یعنی "NULL" باشد یا اشاره‌گری به AST یک مدخل نباشد)، "NULL" را برمی‌گرداند.

bt_entry_key()

char * bt_entry_key (AST * entry)

کلید ارجاع (citation key) یک مدخل عادی را بازمی‌گرداند. (کلید ارجاع، نامی است که پس از نویسهٔ جداکنندهٔ بازکنندهٔ مدخل در یک مدخل عادی ظاهر می‌شود.) در صورتی که "entry" نامعتبر باشد (یعنی "NULL" باشد یا اشاره‌گری به AST یک مدخل عادی نباشد)، "NULL" را بازمی‌گرداند.

bt_get_text()

char * bt_get_text (AST * node)

تمام عملیات پس‌پردازش رشته (بسط ماکرو، الحاق مقادیر ساده، و فشرده‌سازی فاصله‌های سفید) را برای یک مقدار مرکب انجام می‌دهد و رشتهٔ حاصل را بازمی‌گرداند. این تابع را می‌توان یا روی یک فیلد از یک مدخل عادی یا تعریف ماکرو (همان‌طور که توسط bt_next_field() بازگردانده شده)، یا روی یک مدخل comment یا preamble فراخوانی کرد. اگر روی یک گره AST نامعتبر فراخوانی شود، مقدار "NULL" را برمی‌گرداند.

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

btparse, bt_input, bt_postprocess

نویسنده (AUTHOR)

Greg Ward <gward@python.net>