نام (NAME)

gtags-cscope - پیمایش تعاملی درخت کد منبع با استفاده از GNU GLOBAL

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

gtags-cscope [-abCdehilLvV][-F file ][-012345678 pattern][-p n]

توضیحات (DESCRIPTION)

دستور gtags-cscope ابزاری تعاملی و مبتنی بر نمایشگر متنی است که به کاربر امکان می‌دهد برای یافتن بخش‌ها و عناصر مشخصی از کد منبع، در میان فایل‌ها به جستجو و پیمایش بپردازد.

دستور gtags-cscope در اولین باری که روی فایل‌های منبع برنامه‌ای اجرا می‌شود، پایگاه داده ارجاعات متقابل نمادها (cross-reference) را می‌سازد. در اجراهای بعدی، gtags-cscope پایگاه داده ارجاعات متقابل را تنها زمانی بازسازی می‌کند که یکی از فایل‌های منبع تغییر کرده باشد یا فهرست فایل‌های منبع دگرگون شده باشد. هنگام بازسازی، پایگاه داده به‌صورت تدریجی (incremental) به‌روزرسانی می‌شود که این امر سرعت بازسازی را نسبت به ساخت اولیه بسیار بالاتر می‌برد.

ابزار gtags-cscope صرفاً از رابط کاربری cscope استفاده می‌کند؛ اما در باطن و هسته پردازشی، خود سامانه Global است.

گزینه‌ها (OPTIONS)

برخی از شناسه‌های خط فرمان تنها می‌توانند به‌صورت تک‌آرگومان در اجرای gtags-cscope به کار روند. این گزینه‌ها صرفاً اطلاعاتی را چاپ کرده و بلافاصله خارج می‌شوند:

-h: نمایش راهنمای جامع نحوه استفاده از دستور.
-V: چاپ شماره نسخه gtags-cscope.
--help: همانند -h.
--version: همانند -V.

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

-a: چاپ مسیرهای کامل و مطلق (absolute path).
-b: صرفاً ساخت پایگاه داده ارجاعات متقابل (بدون ورود به رابط تعاملی).
-C: نادیده گرفتن بزرگی و کوچکی حروف در هنگام جستجو.
-d: عدم به‌روزرسانی پایگاه داده ارجاعات متقابل.
-e: عدم نمایش اعلان کلید ´^e´ بین فایل‌ها.
-F file: خواندن خطوط ارجاع نمادها از file. (فایل ارجاع نمادها با عملگرهای > و >> ساخته می‌شود و همچنین می‌توان با دستور < که در بخش «ارسال درخواست‌های بعدی» در ادامه توضیح داده شده، آن را خواند.)
-i: نادیده گرفتن سیگنال SIGINT در حالت خط‌محور.
-L: انجام یک جستجوی تکی با خروجی خط‌محور هنگام استفاده با گزینه -num pattern.
-l: استفاده از رابط خط‌محور (line-oriented). این گزینه مستلزم اعمال گزینه -d است.
-[0-9] pattern: پرش به فیلد ورودی شماره num (شمارش از ۰) و جستجوی pattern.
-p n: نمایش n بخش انتهایی از مسیر فایل به جای مقدار پیش‌فرض (۱). استفاده از مقدار ´0´ نام فایل را به طور کامل مخفی می‌کند.
-v: نمایش خروجی با جزئیات بیشتر در حالت خط‌محور.

درخواست جستجوی اولیه (Requesting the initial search)

پس از آماده شدن ارجاعات متقابل، gtags-cscope منوی زیر را نمایش می‌دهد:

Find this symbol:
Find this global definition:
Find functions called by this function (N/A):
Find references of this function:
Find this text string:
Change this text string:
Find this egrep pattern:
Find this file:
Find files #including this file:
Find assignments to this symbol:

کلیدهای <Up> یا <Down> را برای حرکت به فیلد ورودی مورد نظر فشار دهید، متن مورد جستجو را تایپ کرده و سپس کلید <Return> را بفشارید.

ارسال درخواست‌های بعدی (Issuing subsequent requests)

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

0-9a-zA-Z: ویرایش فایل ارجاع داده شده در شماره خط مورد نظر.
<Space>: نمایش دسته بعدی از خطوط منطبق.
<Tab>: جابه‌جایی بین منو و فهرست خطوط منطبق.
<Up>: حرکت به گزینه قبلی منو (اگر مکان‌نما در منو باشد) یا حرکت به خط منطبق قبلی (اگر مکان‌نما در فهرست خطوط باشد).
<Down>: حرکت به گزینه بعدی منو (اگر مکان‌نما در منو باشد) یا حرکت به خط منطبق بعدی (اگر مکان‌نما در فهرست خطوط باشد).
+: نمایش دسته بعدی از خطوط منطبق.
-: نمایش دسته قبلی از خطوط منطبق.
^e: ویرایش فایل‌های نمایش‌داده‌شده به ترتیب.
>: نوشتن فهرست خطوط نمایش‌داده‌شده در یک فایل.
>>: الحاق فهرست خطوط نمایش‌داده‌شده به انتهای یک فایل.
<: خواندن خطوط از فایلی که در قالب ارجاع نمادها قرار دارد (ساخته شده با ´>´ یا ´>>´)، مشابه با گزینه -F.
^: فیلتر کردن تمام خطوط از طریق یک دستور شل و نمایش خطوط حاصل به جای خطوط قبلی.
|: ارسال (pipe) تمام خطوط به یک دستور شل و نمایش آن‌ها بدون اعمال تغییر.
^g: خواندن خطوط از نتیجه اجرای global(1).

در هر زمان می‌توان از دستورات تک‌حرفی زیر نیز استفاده کرد:

<Return>: رفتن به فیلد ورودی بعدی.
^n: رفتن به فیلد ورودی بعدی.
^p: رفتن به فیلد ورودی قبلی.
^y: جستجو با آخرین متن تایپ‌شده.
^b: حرکت به فیلد ورودی قبلی و الگوی جستجو.
^f: حرکت به فیلد ورودی بعدی و الگوی جستجو.
^c: تغییر وضعیت نادیده‌گرفتن/حساسیت به بزرگی و کوچکی حروف هنگام جستجو (هنگام نادیده‌گرفتن، جستجوی ´FILE´ با ´File´ و ´file´ نیز مطابقت خواهد داشت).
^r: بازسازی پایگاه داده ارجاعات متقابل.
!: شروع یک شل تعاملی (تایپ ´^d´ برای بازگشت به gtags-cscope).
^l: رندر و بازترسیم مجدد صفحه نمایش.
?: نمایش اطلاعات راهنما درباره دستورات gtags-cscope.
^d: خروج از gtags-cscope.

نکته: اگر نویسه اول متنی که می‌خواهید جستجو کنید با یکی از دستورات بالا هم‌خوانی دارد، ابتدا یک علامت اسلش وارونه (´\´) تایپ کنید تا اسکیپ شود.

جایگزینی متن جدید به جای متن قدیمی:

پس از تایپ متنی که قرار است تغییر کند، gtags-cscope متن جدید را درخواست می‌کند و سپس خطوط حاوی متن قدیمی را نمایش می‌دهد. خطوطی را که می‌خواهید تغییر کنند با دستورات تک‌حرفی زیر انتخاب کنید:

0-9a-zA-Z: علامت‌گذاری یا لغو علامت‌گذاری خط مورد نظر برای تغییر.
*: علامت‌گذاری یا لغو علامت‌گذاری تمام خطوط نمایش‌داده‌شده برای تغییر.
<Space>: نمایش دسته بعدی از خطوط.
+: نمایش دسته بعدی از خطوط.
-: نمایش دسته قبلی از خطوط.
^a: علامت‌گذاری یا لغو علامت‌گذاری تمامی خطوط جهت تغییر.
^d: اعمال تغییرات روی خطوط علامت‌گذاری‌شده و خروج.
<Esc>: خروج بدون تغییر دادن خطوط علامت‌گذاری‌شده.
!: شروع یک شل تعاملی (تایپ ´^d´ برای بازگشت به gtags-cscope).
^l: رندر مجدد صفحه نمایش.
?: نمایش اطلاعات راهنما درباره دستورات gtags-cscope.
کلیدهای ویژه (Special keys): اگر ترمینال شما دارای کلیدهای جهتی است که در vi کار می‌کنند، می‌توانید از آن‌ها برای حرکت بین فیلدهای ورودی استفاده کنید. کلید جهت‌نمای بالا برای حرکت به فیلد ورودی قبلی به جای فشردن متوالی کلید <Tab> بسیار کاربردی است. اگر کلیدهای <CLEAR>، <NEXT> یا <PREV> را دارید، آن‌ها به ترتیب مشابه دستورات ´^l´، ´+´ و ´-´ عمل خواهند کرد.

رابط خط‌محور (Line-Oriented interface)

گزینه -l به شما امکان می‌دهد از gtags-cscope در جاهایی استفاده کنید که رابط مبتنی بر صفحه نمایشگر کاربردی ندارد؛ برای نمونه، فراخوانی از درون یک برنامه مبتنی بر صفحه دیگر.

دستور gtags-cscope هنگامی که آماده دریافت یک خط ورودی باشد اعلان ´>>´ را نمایش می‌دهد. خط ورودی با شماره فیلد (شمارش از ۰) آغاز شده و بلافاصله الگوی جستجو به دنبال آن می‌آید. برای مثال، عبارت ´1main´ تعریف تابع ´main´ را پیدا می‌کند.

اگر صرفاً یک جستجوی تکی می‌خواهید، به جای گزینه -l از گزینه‌های -L و -num pattern استفاده کنید؛ در این حالت اعلان ´>>´ نمایش داده نخواهد شد.

برای حالت -l، دستور gtags-cscope تعداد خطوط ارجاع را چاپ می‌کند:
cscope: 2 lines

به ازای هر ارجاع پیدا شده، gtags-cscope یک خط شامل نام فایل، نام تابع، شماره خط و متن خط را چاپ می‌کند که با فاصله از هم جدا شده‌اند. برای مثال:
main.c main 161 main(argc, argv)

توجه داشته باشید که بر خلاف رابط مبتنی بر صفحه نمایش، برای نمایش یک ارجاع تکی ویرایشگر فراخوانی نمی‌شود.

می‌توانید از دستور ´c´ برای تغییر وضعیت نادیده‌گرفتن/حساسیت به بزرگی و کوچکی حروف در جستجو استفاده کنید (در حالت نادیده‌گرفتن، جستجوی ´FILE´ با ´File´ و ´file´ نیز تطابق می‌یابد).

می‌توانید از دستور ´r´ برای بازسازی پایگاه داده استفاده کنید.

دستور gtags-cscope هنگامی که به انتهای فایل (EOF) برسد، یا زمانی که اولین نویسه خط ورودی ´^d´ یا ´q´ باشد، خارج می‌شود.

محیط (ENVIRONMENT)

متغیرهای محیطی زیر از cscope به ارث رسیده‌اند:

CSCOPE_EDITOR: متغیرهای EDITOR و VIEWER را لغو و جایگزین می‌کند. اگر مایلید در cscope از ویرایشگری متفاوت با آنچه در EDITOR/VIEWER مشخص شده استفاده کنید، از این متغیر بهره بگیرید.
CSCOPE_LINEFLAG: قالب فلگ شماره خط برای ویرایشگر شما. به‌طور پیش‌فرض، cscope ویرایشگر شما را با دستوری معادل ´editor +N file´ فراخوانی می‌کند که در آن N شماره خطی است که ویرایشگر باید به آن بپرد. این قالب هم توسط emacs و هم vi پشتیبانی می‌شود. اگر ویرایشگر شما به قالب متفاوتی نیاز دارد، آن را در این متغیر مشخص کنید و از ´%s´ به عنوان جای‌نگهدار شماره خط بهره ببرید. برای مثال، اگر ویرایشگر شما باید به‌صورت ´editor -#103 file´ فراخوانی شود تا به خط ۱۰۳ برود، این متغیر را روی ´-#%s´ تنظیم کنید.
CSCOPE_LINEFLAG_AFTER_FILE: اگر ویرایشگر شما نیازمند دریافت گزینه شماره خط پس از نام فایل است، این متغیر را روی ´yes´ تنظیم کنید. در ادامه مثال بالا در CSCOPE_LINEFLAG: اگر ویرایشگر شما به دستور ´editor file -#number´ نیاز دارد، این متغیر محیطی را تنظیم کنید. کاربران اکثر ویرایشگرهای استاندارد (vi، emacs) نیازی به تنظیم این متغیر ندارند.
EDITOR: ویرایشگر ترجیحی که پیش‌فرض آن vi است.
HOME: دایرکتوری خانگی که به طور خودکار هنگام ورود به سیستم تنظیم می‌شود.
SHELL: شل ترجیحی که پیش‌فرض آن sh است.
TERM: نوع ترمینال که باید یک ترمینال مبتنی بر صفحه نمایش باشد.
TERMINFO: مسیر کامل دایرکتوری اطلاعات ترمینال. اگر ترمینال شما در دایرکتوری استاندارد terminfo قرار ندارد، صفحات راهنمای curses و terminfo را برای نحوه ایجاد توصیف ترمینال اختصاصی خود ببینید.
TMPDIR: دایرکتوری فایل‌های موقت که پیش‌فرض آن ´/tmp´ است.
VIEWER: برنامه ترجیحی برای نمایش فایل‌ها (مانند less) که اولویت بالاتری نسبت به EDITOR دارد (توضیحات بالا را ببینید).

متغیرهای محیطی زیر از سامانه Global به ارث رسیده‌اند:

GTAGSCONF: فایل پیکربندی.
GTAGSGLOBAL: اگر این متغیر تنظیم شود، مقدار ´GTAGSGLOBAL$´ به عنوان نام برنامه global(1) استفاده می‌شود. مقدار پیش‌فرض global است.
GTAGSGTAGS: اگر این متغیر تنظیم شود، مقدار ´GTAGSGTAGS$´ به عنوان نام برنامه gtags(1) استفاده می‌شود. مقدار پیش‌فرض gtags است.
GTAGSDBPATH: دایرکتوری حاوی فایل‌های تگ. در صورت تعریف نشدن GTAGSROOT، این مقدار نادیده گرفته می‌شود.
GTAGSLABEL: برچسب پیکربندی. مقدار پیش‌فرض ´default´ است.
GTAGSLIBPATH: اگر این متغیر تنظیم شود، به عنوان مسیر جستجوی توابع کتابخانه‌ای استفاده می‌شود. اگر تگ مشخص‌شده در پروژه پیدا نشود، global در این مسیرها نیز جستجو خواهد کرد. از آنجا که در بازیابی تنها فایل ´GTAGS´ هدف قرار می‌گیرد، هنگام مشخص شدن گزینه‌های -r یا -s این متغیر نادیده گرفته می‌شود.
GTAGSROOT: دایرکتوری ریشه پروژه.
MAKEOBJDIR: اگر این متغیر تنظیم شود، مقدار ´MAKEOBJDIR$´ به عنوان نام دایرکتوری objdir به سبک BSD استفاده می‌شود. مقدار پیش‌فرض ´obj´ است.
MAKEOBJDIRPREFIX: اگر این متغیر تنظیم شود، مقدار ´MAKEOBJDIRPREFIX$´ به عنوان پیشوند دایرکتوری objdir به سبک BSD استفاده می‌شود. مقدار پیش‌فرض ´/usr/obj´ است.

فایل‌ها (FILES)

´GTAGS´: فایل تگ برای تعاریف.
´GRTAGS´: فایل تگ برای ارجاعات.
´GPATH´: فایل تگ برای فایل‌های منبع.
´GTAGSROOT´: اگر متغیر محیطی GTAGSROOT تنظیم نشده باشد و فایل ´GTAGSROOT´ در همان دایرکتوری حاوی ´GTAGS´ موجود باشد، global مقدار GTAGSROOT را برابر با محتوای این فایل قرار می‌دهد.
´gtags.conf´, ´$HOME/.globalrc´: داده‌های پیکربندی GNU Global. به gtags.conf(5) مراجعه کنید.

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

gtags(1), global(1), htags(1).

سامانه تگ کد منبع GNU Global
(http://www.gnu.org/software/global).

اشکالات (BUG)

فیلد تابع در خروجی تقریباً همیشه به‌صورت <unknown> نمایش داده می‌شود، زیرا Global آن را تشخیص نمی‌دهد.

قابلیت ´Find functions called by this function´ پیاده‌سازی نشده است.

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

Joe Steffen (نویسنده اصلی) و دیگران.

تاریخچه (HISTORY)

ابزار Cscope در اصل در اوایل دهه ۱۹۸۰ در آزمایشگاه‌های بل (Bell Labs) توسعه یافت و در آوریل ۲۰۰۰ به عنوان نرم‌افزار آزاد تحت مجوز BSD منتشر شد. Gtags-cscope انشعابی از cscope است تا از Global به عنوان موتور پشتیبان استفاده کند. رابط خط‌محور آن در اصل در سال ۲۰۰۶ نوشته شد و در سال ۲۰۱۱ با استفاده از خود cscope مجدداً بازنویسی و پیاده‌سازی شد.