GLOBAL(1) General Commands Manual GLOBAL(1)

global - چاپ مکان نمادهای مشخص‌شده

global [-adEFGilMnNqrstTvx][-S dir][-e] pattern
global -c[dFiIMoOPqrsTv] prefix
global -f[adlnqrstvx][-L file-list][-S dir] files
global -g[aEGilMnoOqtvVx][-L file-list][-S dir][-e] pattern [files]
global -I[ailMnqtvx][-S dir][-e] pattern
global -P[aEGilMnoOqtvVx][-S dir][-e] pattern
global -p[qrv]
global -u[qv]

دستور Global مکان نمادهای داده‌شده را در فایل‌های مبدأ C،‏ Yacc،‏ Java،‏ PHP و اسمبلی پیدا کرده و نام مسیر، شماره خط و محتوای خطِ مربوط به آن مکان‌ها را چاپ می‌کند. Global نه تنها تعاریف، بلکه مراجع و سایر نمادها را نیز می‌تواند بیابد.

Global می‌تواند یک درخت مبدأ (یعنی دایرکتوری‌ای که شامل زیردایرکتوری‌ها و فایل‌های مبدأ است) را به عنوان یک پروژه در نظر بگیرد. پیش از به‌کارگیری این دستور، باید gtags(1) را در دایرکتوری ریشه پروژه‌ای که قصد بررسی آن را دارید اجرا کنید تا فایل‌های برچسب ایجاد شوند. سپس می‌توانید از دستور global در هر کجای پروژه استفاده کنید. نیازی نیست مشخص کنید فایل برچسب کجاست؛ در عوض، global خودش مکان آن را پیدا می‌کند.

شما می‌توانید یک عبارت باقاعده برای pattern مشخص کنید. Global دو نگارش مختلف از نحو عبارات باقاعده را درک می‌کند: پایه (basic) و تعمیم‌یافته (extended که پیش‌فرض است).

دستورهای زیر در دسترس هستند:

<بدون دستور> pattern
عدم تعیین دستور به معنای دستور جستجوی برچسب است. برچسب‌هایی را که با pattern مطابقت دارند چاپ می‌کند. به‌طور پیش‌فرض، برچسب‌های تعریف چاپ می‌شوند.
چاپ نمادهایی که با prefix آغاز می‌شوند. اگر prefix داده نشود، همه نمادها را چاپ می‌کند. اگر limit داده شود، حداکثر تا تعداد خطوط مشخص‌شده در limit چاپ می‌کند.
چاپ همه برچسب‌های موجود در files. این دستور مستلزم گزینه -x است.
چاپ همه خطوطی که با pattern مطابقت دارند. اگر files مشخص شده باشد، این دستور در آن فایل‌ها جستجو می‌کند.
چاپ پیام راهنما.
چاپ تمام خطوطی که با pattern مطابقت دارند. این تابع از idutils(1) به عنوان موتور جستجو استفاده می‌کند. برای استفاده از این دستور، باید idutils(1) را روی سیستم خود نصب کرده و gtags(1) را با گزینه -I اجرا کنید.
چاپ نام مسیرهایی که با pattern مطابقت دارند. اگر الگویی داده نشود، تمام مسیرهای موجود در پروژه را چاپ می‌کند.
چاپ مکان ´GTAGS´.
چاپ مکان name، که می‌تواند یکی از این موارد باشد: ´root´، ´dbpath´ یا ´conf´. ´root´ به معنی دایرکتوری ریشه پروژه است. ´dbpath´ به معنی دایرکتوری‌ای است که پایگاه‌های داده برچسب در آن قرار دارند. ´conf´ به معنی فایل پیکربندی است.
به‌روزرسانی افزایشی فایل‌های برچسب. این دستور به صورت درونی gtags(1) را فرامی‌خواند. برخلاف gtags(1)، می‌توانید این دستور را در هر کجای پروژه اجرا کنید.
نمایش شماره نگارش.

گزینه‌های زیر در دسترس هستند:

چاپ نام مسیرهای مطلق. به‌طور پیش‌فرض، نام مسیرهای نسبی چاپ می‌شوند.
استفاده از رنگ برای برجسته‌سازی الگو در خط؛ when می‌تواند یکی از این موارد باشد: never، always یا auto (پیش‌فرض). رنگ پیش‌فرض، متن قرمز پررنگ روی پس‌زمینه فعلی است؛ متغیر محیطی GREP_COLORS (در حال حاضر تنها mt و ms مؤثر هستند) یا GREP_COLOR آن را تعیین می‌کند. این گزینه برای دستورهای زیر مؤثر است: <بدون دستور>، -f، -g، -I، -P.
تغییر دایرکتوری پیش از انجام تمام کارها از جمله تحلیل پارامترها.
چاپ مکان‌های تعاریف.
استفاده از pattern به عنوان الگو؛ برای محافظت از الگوهایی که با ´-´ آغاز می‌شوند کاربرد دارد.
تفسیر pattern به عنوان یک عبارت باقاعده تعمیم‌یافته (extended). این حالت پیش‌فرض است.
تبدیل نویسه‌های مسیرِ موجود در chars به نماد ´%´، همراه با نمایش شانزده‌شانزدهی دو رقمی آن نویسه. فاصله (blank) به ´%20´ تبدیل خواهد شد.
پایان دادن به جستجو بدون پیمایش تمام فایل‌های برچسب فهرست‌شده در GTAGSLIBPATH هنگامی که برچسب‌ها در یک فایل برچسب پیدا شوند. این حالت پیش‌فرض است.
تعیین نوع برچسب بر اساس context. نحو آن باید به صورت ´lineno:path´ باشد. اگر سیاق (context) تعریفی از الگو باشد آنگاه از -r استفاده می‌شود، در غیر این صورت اگر حداقل یک تعریف از الگو وجود داشته باشد از -d استفاده می‌شود، وگرنه از -s استفاده خواهد شد. اگر این گزینه مشخص شود، گزینه‌های -d، -r و -s روی خط فرمان نادیده گرفته می‌شوند. استفاده از عبارت باقاعده برای pattern مجاز نیست. این گزینه برای استفاده در محیط‌های تعاملی مانند ویرایشگرها و محیط‌های یکپارچه توسعه نرم‌افزار (IDE) در نظر گرفته شده است.
تفسیر pattern به عنوان یک عبارت باقاعده پایه (basic). پیش‌فرض، عبارت باقاعده تعمیم‌یافته است.
تنظیم متغیر محیطی GTAGSCONF روی file.
تنظیم متغیر محیطی GTAGSLABEL روی label.
نادیده گرفتن تمایز حروف کوچک و بزرگ در الگو.
دریافت فایل‌ها از file علاوه بر آرگومان‌ها. آرگومان file می‌تواند روی '-' تنظیم شود تا فهرستی از فایل‌ها را از ورودی استاندارد بپذیرد. نام فایل‌ها باید با خط جدید از یکدیگر جدا شوند.
تنها چاپ برچسب‌هایی که زیر دایرکتوری فعلی قرار دارند.
انجام جستجوی دقیق نویسه‌ای (literal) به جای جستجوی عبارت باقاعده. این گزینه با دستور جستجوی برچسب، دستور -g، دستور -P و دستور -I کار می‌کند.
جستجو به بزرگی و کوچکی حروف حساس باشد. این حالت پیش‌فرض است.
مشخص کردن چگونگی تطابق تکمیل نام مسیر، که در آن part یکی از این موارد است: ´first´، ´last´ یا ´all´ (پیش‌فرض). این گزینه تنها با دستور -c در ترکیب با -P معتبر است.
غیرفعال کردن فیلتر مرتب‌سازی و فیلتر تبدیل مسیر.
استفاده از روش مرتب‌سازی بر اساس نزدیکی (مرتب‌سازی بر مبنای نزدیک‌ترین از start) برای خروجی. به‌طور پیش‌فرض، از روش مرتب‌سازی الفبایی استفاده می‌شود. این گزینه برای دستور جستجوی برچسب، دستور -P و دستور -g مؤثر است. به عنوان یک استثنا، دستور -g زمانی که فایل‌ها با آرگومان مشخص شده باشند این گزینه را نادیده می‌گیرد. میزان نزدیکی بر اساس این تعریف می‌شود که برای رسیدن به هدف باید از چند دایرکتوری والد بالا رفت. نتیجه مرتب‌سازی بر اساس نزدیکی، الحاق موارد زیر ([0]-[n]) به همین ترتیب است. مقدار پیش‌فرض start دایرکتوری فعلی است. 
[0] اگر شروع یک فایل باشد، خروجی جستجوی محلی در آن فایل.
[1] خروجی جستجوی محلی در دایرکتوری شروع به جز [0].
[2] خروجی جستجوی محلی در دایرکتوری والد به جز [0]-[1].
[3] خروجی جستجوی محلی در دایرکتوری والدِ والد به جز [0]-[2].
... (تکرار تا دایرکتوری ریشه پروژه)
[n] خروجی جستجوی محلی در دایرکتوری ریشه پروژه به جز [0]-[n-1].
در هر دایرکتوری، آن‌ها بر اساس ترتیب الفبایی مرتب می‌شوند.
تنها در نظر گرفتن فایل‌های متنی غیر از کد مبدأ، مانند ´README´. این گزینه تنها با دستور -g یا -P معتبر است. این گزینه بر گزینه -o اولویت دارد..TP -o, --other علاوه بر فایل‌های کد مبدأ، فایل‌های متنی دیگر (مانند ´README´) را نیز پردازش می‌کند. این گزینه تنها با دستورهای -g یا -P معتبر است.
نام‌های مسیر را با استفاده از format چاپ می‌کند که می‌تواند یکی از موارد زیر باشد: ´relative´، ´absolute´، ´shorter´، ´abslib´ یا ´through´. ´relative´ به معنای مسیر نسبی است. ´absolute´ به معنای مسیر مطلق است. ´shorter´ به معنای مسیر کوتاه‌تر بین مسیر نسبی و مطلق است. ´abslib´ به معنای مسیر مطلق برای کتابخانه‌ها (GTAGSLIBPATH) و مسیر نسبی برای باقی موارد است. ´through´ به معنای مسیر نسبی از دایرکتوری ریشه پروژه است (قالب داخلی GPATH). وقتی از این شیوه استفاده شود، GTAGSLIBPATH نادیده گرفته می‌شود. پیش‌فرض ´relative´ است. گزینه --path-style اولویت بالاتری نسبت به گزینه -a دارد.
هر رکورد را به جای خط جدید، با یک نویسه نال (null) در انتها چاپ می‌کند.
حالت بی‌صدا.
برچسب‌های مرجع را چاپ می‌کند. مرجع به معنای ارجاع به نمادی است که دارای تعریف باشد. همراه با گزینه -p، دایرکتوری ریشه پروژه را چاپ می‌کند.
خروجی را با استفاده از format چاپ می‌کند که می‌تواند یکی از موارد زیر باشد: ´path´ (پیش‌فرض)، ´ctags´، ´ctags-x´، ´grep´ یا ´cscope´. گزینه‌های --result=ctags و --result=ctags-x به ترتیب معادل گزینه‌های -t و -x هستند. گزینه --result اولویت بالاتری نسبت به گزینه‌های -t و -x دارد.
فایل‌های برچسب را با استفاده از gtags(1) همراه با گزینه --single-update به‌روزرسانی می‌کند. فرض بر این است که file اضافه، به‌روزرسانی یا حذف شده است و هیچ تغییری در فایل‌های دیگر وجود ندارد. این گزینه مستلزم گزینه -u است.
برچسب‌های نمادهای دیگر را چاپ می‌کند. نماد دیگر به معنای ارجاع به نمادی است که هیچ تعریفی ندارد.
فقط برچسب‌هایی را که زیر دایرکتوری dir قرار دارند چاپ می‌کند. مشابه گزینه -l است، اما نیازی به تغییر دایرکتوری ندارید.
تمام فایل‌های برچسب فهرست‌شده در GTAGSLIBPATH را بررسی می‌کند. به‌طور پیش‌فرض، جستجو با یافتن اولین برچسب متوقف می‌شود. در صورت مشخص شدن هر یک از گزینه‌های -s، -r یا -l، این گزینه نادیده گرفته می‌شود.
استفاده از قالب استاندارد ctags.
منطق تطابق را معکوس می‌کند تا خطوط غیرمنطبق انتخاب شوند. این گزینه تنها با دستورهای -g یا -P معتبر است.
حالت پرگو (مشروح).
استفاده از قالب استاندارد cxref در ctags (با -x).

$ ls -F
Makefile      src/    lib/
$ gtags
$ ls G*
GPATH   GRTAGS  GTAGS
$ global main
src/main.c
$ (cd src; global main)
main.c
$ global -x main
main              10 src/main.c  main (argc, argv) {
$ global -f src/main.c
main              10 src/main.c  main (argc, argv) {
func1             55 src/main.c  func1() {
func2             72 src/main.c  func2() {
func3            120 src/main.c  func3() {
$ global -x '^[sg]et'
set_num           20 lib/util.c  set_num(values) {
get_num           30 lib/util.c  get_num() {
$ global -rx set_num
set_num          113 src/op.c            set_num(32);
set_num          225 src/opop.c               if (set_num(0) > 0) {
$ global strlen
$ (cd /usr/src/sys; gtags)
$ export GTAGSLIBPATH=/usr/src/sys
$ global -a strlen
/usr/src/sys/libkern/strlen.c
$ (cd /usr/src/lib; gtags)
$ GTAGSLIBPATH=/usr/src/lib:/usr/src/sys
$ global -a strlen
/usr/src/lib/libc/string/strlen.c

´GTAGS´
فایل برچسب برای تعاریف.
´GRTAGS´
فایل برچسب برای ارجاعات.
´GPATH´
فایل برچسب برای فایل‌های منبع.
´GTAGSROOT´
اگر متغیر محیطی GTAGSROOT تنظیم نشده باشد و فایل ´GTAGSROOT´ در همان دایرکتوری حاوی ´GTAGS´ وجود داشته باشد، آن‌گاه global مقدار GTAGSROOT را برابر با محتوای این فایل قرار می‌دهد.
´gtags.conf´, ´$HOME/.globalrc´
داده‌های پیکربندی برای GNU Global. gtags.conf(5) را ببینید..SH "محیط (ENVIRONMENT)" متغیرهای محیطی زیر بر اجرای global تأثیر می‌گذارند:
رنگی که برای --color استفاده می‌شود؛ GREP_COLORS اولویت دارد.
رنگ (mt یا ms) برای استفاده با --color؛ به grep(1) مراجعه کنید.
اگر این متغیر مقداردهی شود، گزینهٔ --encode-path=" <TAB>" تعیین می‌شود.
اندازهٔ حافظهٔ موقت (کَش) B-tree. مقدار پیش‌فرض 50000000 (بایت) است.
فایل پیکربندی.
دایرکتوری محل قرارگیری فایل‌های برچسب. این مقدار در صورتی که GTAGSROOT تعریف نشده باشد نادیده گرفته می‌شود. استفاده از این متغیر توصیه نمی‌شود.
اگر این متغیر مقداردهی شود، با هر فایلی که پسوند آن ´.h´ باشد مانند یک فایل منبع C++ رفتار می‌شود.
برچسب پیکربندی. مقدار پیش‌فرض default است.
اگر این متغیر مقداردهی شود، به عنوان مسیر جستجو برای توابع کتابخانه‌ای استفاده می‌شود. اگر نماد داده‌شده در پروژهٔ کنونی پیدا نشود، global در این مسیرها نیز جستجو می‌کند. از آنجا که در بازیابی تنها ´GTAGS´ هدف قرار می‌گیرد، هنگام تعیین -r یا -s این متغیر نادیده گرفته می‌شود.
اگر این متغیر مقداردهی شود، ´$GTAGSLOGGING´ به عنوان مسیر فایل لاگ استفاده می‌شود. مقدار پیش‌فرضی وجود ندارد.
دایرکتوری ریشهٔ پروژه. معمولاً از طریق وجود فایل ´GTAGS´ شناسایی می‌شود. استفاده از این متغیر توصیه نمی‌شود.
اگر این متغیر مقداردهی شود، گزینهٔ -T تعیین می‌گردد.
اگر هر یک از این دو متغیر مقداردهی شود، به عنوان نام objdir به سبک BSD استفاده می‌شود. اولویت با متغیر اول است. مقدار پیش‌فرض ´obj´ است.
اگر هر یک از این دو متغیر مقداردهی شود، به عنوان پیشوند objdir به سبک BSD استفاده می‌شود. اولویت با متغیر اول است. مقدار پیش‌فرض ´/usr/obj´ است.

متغیرهای پیکربندی زیر بر اجرای global تأثیر می‌گذارند:

نادیده گرفتن تمایز حروف کوچک و بزرگ در pattern.

در صورت بروز خطا، global با مقداری غیر از ۰ خارج می‌شود، و در غیر این صورت با ۰.

gtags(1), htags(1), less(1), gtags.conf(5).

سامانه برچسب‌گذاری کد منبع GNU Global
(http://www.gnu.org/software/global).

Shigio YAMAGUCHI، Hideki IWAMOTO و دیگران.

دستور global نخستین بار در FreeBSD 2.2.2 پدیدار شد.

May 2015 GNU Project