نام (NAME)

etags - ایجاد فایل برچسب برای ویرایشگرهای Emacs و vi

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

etags [-aCDGIQRVh] [-i file] [-l language]
[-o tagfile] [-r regexp] [--parse-stdin=file]
[--append] [--no-defines] [--globals] [--no-globals] [--no-line-directive] [--include=file] [--ignore-indentation] [--language=language] [--members] [--no-members] [--output=tagfile] [--class-qualify] [--regex=regexp] [--no-regex] [--no-fallback-lang] [--fallback-lang] [--no-empty-file-entries] [--empty-file-entries] [--help] [--version] file ...

etags --ctags [-aCdgIQRVh] [-BtTuvwx] [-l language]
[-o tagfile] [-r regexp] [--parse-stdin=file]
[--append] [--backward-search] [--cxref] [--no-defines] [--globals] [--no-globals] [--no-line-directive] [--ignore-indentation] [--language=language] [--members] [--no-members] [--class-qualify] [--output=tagfile] [--regex=regexp] [--update] [--help] [--version] file ...

توضیحات (DESCRIPTION)

برنامه etags برای ایجاد یک فایل جدول برچسب (tag table)، در قالبی قابل فهم برای emacs(1) استفاده می‌شود؛ چنانچه نخستین آرگومان، گزینه منسوخ‌شده --ctags باشد، برنامه در عوض جدول مشابهی در قالبی قابل فهم برای vi(1) ایجاد می‌کند. این برنامه نحو زبان‌های C، Objective C، C++، Java، Fortran، Ada، Cobol، Erlang، Forth، Go، HTML، LaTeX، Emacs Lisp/Common Lisp، Lua، Makefile، Mercury، Pascal، Perl، Ruby، Rust، PHP، PostScript، Python، Prolog، Scheme و بیشتر نحوهای شبیه به اسمبلی را می‌شناسد.

این برنامه فایل‌های مشخص‌شده در خط فرمان را می‌خواند و یک جدول برچسب (پیش‌فرض: TAGS، یا در صورت استفاده از --ctags، فایل tags) در دایرکتوری کاری جاری می‌نویسد. فایل‌هایی که با نام‌های نسبی مشخص شده‌اند، در جدول برچسب با نام‌های فایلی نسبت به دایرکتوری محل استقرار جدول برچسب ثبت می‌شوند. با این حال، اگر جدول برچسب در /dev باشد یا همان خروجی استاندارد باشد، نام فایل‌ها نسبت به دایرکتوری کاری ثبت خواهند شد. فایل‌هایی که با نام‌های مطلق مشخص شده‌اند، با نام‌های مطلق ثبت می‌شوند. فایل‌های تولیدشده از یک فایل منبع – مانند یک فایل C تولیدشده از یک فایل منبع Cweb – با نام فایل منبع ثبت خواهند شد.

فایل‌های فشرده‌شده با استفاده از gzip، bzip2، xz و zstd پشتیبانی می‌شوند.

برنامه‌ها زبان مورد استفاده در یک فایل ورودی را بر اساس نام فایل و محتویات آن تشخیص می‌دهند. از سوییچ --language می‌توان برای اجبار در تجزیه نام‌های فایلی که پس از این سوییچ می‌آیند بر اساس زبان ارائه‌شده استفاده کرد، که بر حدس‌های مبتنی بر پسوند نام فایل اولویت دارد.

گزینه‌ها (OPTIONS)

برخی از گزینه‌ها تنها برای فایل‌های برچسب به سبک vi که با گزینه --ctags تولید می‌شوند معنا دارند؛ در غیر این صورت نادیده گرفته می‌شوند. این برنامه‌ها مخفف‌های بدون ابهام را برای نام‌های طولانی گزینه‌ها می‌پذیرند.

-a, --append

افزودن به انتهای فایل برچسب موجود. (برای فایل‌های برچسب با قالب vi، همچنین --update را ببینید.)

-B, --backward-search

فایل‌های برچسب نوشته‌شده در قالبی که vi انتظار دارد شامل دستورالعمل‌های جستجوی عبارت منظم هستند؛ گزینه -B آن‌ها را با استفاده از جداکننده "?" می‌نویسد تا جستجو در فایل‌ها رو به عقب انجام گیرد. پیش‌فرض، استفاده از جداکننده "/" برای جستجوی رو به جلو در فایل‌ها است. این گزینه تنها در صورت استفاده از --ctags کاربرد دارد.

--declarations

در C و زبان‌های مشتق‌شده از آن، برای اعلانات توابع برچسب ایجاد می‌کند و برای متغیرهای extern نیز برچسب می‌سازد مگر اینکه از --no-globals استفاده شود. در Lisp، برای اعلانات (defvar foo) برچسب می‌سازد. در Mercury، اعلانات خط را با ":-" آغاز می‌کنند و همیشه برچسب‌گذاری می‌شوند. علاوه بر این، این گزینه محمول‌ها یا توابع را در نخستین قواعد بندها، مانند Prolog، برچسب‌گذاری می‌کند.

-D, --no-defines

عدم ایجاد مدخل‌های برچسب برای تعاریف ثابت‌های پیش‌پردازنده C و ثابت‌های enum. در صورتی که فایل‌های هدر زیادی برچسب‌گذاری شوند، این گزینه می‌تواند اندازه فایل برچسب‌ها را بسیار کوچک‌تر کند.

--globals

ایجاد مدخل‌های برچسب برای متغیرهای سراسری در Perl و Makefile. این حالت پیش‌فرض در C و زبان‌های مشتق‌شده از آن است.

--no-globals

عدم برچسب‌گذاری متغیرهای سراسری در C و زبان‌های مشتق‌شده از آن. به‌طور معمول این گزینه اندازه فایل را به میزان یک چهارم کاهش می‌دهد.

--no-line-directive

نادیده گرفتن دستورات پیش‌پردازنده #line در C و زبان‌های مشتق‌شده از آن. حالت پیش‌فرض این است که این دستورات در نظر گرفته شده و برچسب‌ها به‌گونه‌ای ثبت شوند که گویی فایل اسکن‌شده همان فایلی بوده که در دستور #line نام برده شده است. این سوییچ هنگامی سودمند است که فایل اصلی نام‌برده‌شده توسط #line دیگر در دسترس نباشد.

-i file, --include=file

درج یادداشتی در فایل برچسب که مشخص می‌کند هنگام جستجو برای یک برچسب، پس از بررسی فایل جاری باید فایل برچسب‌های file نیز بررسی شود. تنها etags این گزینه را می‌پذیرد.

-I, --ignore-indentation

عدم تکیه بر تورفتگی‌ها به اندازه حالت عادی. در حال حاضر، این بدان معناست که فرض نشود یک آکوالاد بسته در ستون نخست، لزوماً آکوالاد پایانی تعریف تابع یا ساختار در C و C++ است. این گزینه برای کدهایی اهمیت دارد که از قراردادهای کدنویسی گنو مبنی بر قرار دادن آکوالادهای سطح بالا در ستون صفر پیروی نمی‌کنند.

-l language, --language=language

تجزیه فایل‌های بعدی بر اساس زبان ارائه‌شده. بیش از یک مورد از این گزینه‌ها می‌تواند در میان نام‌های فایل قرار گیرد. برای دریافت فهرستی از زبان‌های موجود و پسوندهای پیش‌فرض نام فایل آن‌ها از --help استفاده کنید. برای نمونه، از آنجا که هر دو زبان Mercury و Objective-C پسوند فایل یکسان .m دارند، یک بررسی مبتنی بر محتوا برای تشخیص زبان تلاش می‌کند. اگر این بررسی ناموفق باشد، باید از --language=mercury یا --language=objc استفاده شود. زبان "auto" می‌تواند برای بازگرداندن تشخیص خودکار زبان بر پایه نام فایل استفاده شود. زبان "none" می‌تواند برای غیرفعال کردن کامل تجزیه زبان به کار رود؛ در این صورت تنها تطبیق عبارات منظم انجام خواهد شد (گزینه --regex را ببینید).

--members

ایجاد مدخل‌های برچسب برای متغیرهایی که عضو ساختارهای شبه‌استراکچر در PHP هستند. این حالت پیش‌فرض برای C و زبان‌های مشتق‌شده از آن است.

--no-members

عدم برچسب‌گذاری متغیرهای عضو.

--packages-only

تنها برچسب‌گذاری بسته‌ها در فایل‌های Ada.

--parse-stdin=file

می‌تواند (تنها یک‌بار) به‌جای نام فایل در خط فرمان استفاده شود. etags از ورودی استاندارد می‌خواند و برچسب‌های تولیدشده را به عنوان برچسب‌های متعلق به فایل FILE علامت‌گذاری می‌کند.

-Q, --class-qualify

توصیف نام‌های برچسب با نام کلاس آن‌ها در C++، ObjC، Java و Perl. این گزینه نام‌های برچسب را به شکل class::member برای C++ و Perl، class(category) برای Objective C، و class.member برای Java تولید می‌کند. برای Objective C، همچنین متدهای کلاسی توصیف‌شده با آرگومان‌هایشان را مانند foo:bar:baz:more تولید می‌کند.

-o tagfile, --output=tagfile

نام صریح فایل برای جدول برچسب؛ تنها برای etags، نام فایل - به معنای خروجی استاندارد است؛ بر مقادیر پیش‌فرض TAGS یا tags اولویت دارد. (اما در صورت همراهی با -v یا -x نادیده گرفته می‌شود.)

-r regexp, --regex=regexp

ایجاد برچسب‌ها بر اساس تطبیق عبارت منظم برای فایل‌های پس از این گزینه، افزون بر برچسب‌های ساخته‌شده با تجزیه استاندارد مبتنی بر زبان. می‌تواند آزادانه با نام‌های فایل و گزینه -R ترکیب شود. عبارات منظم حالت تجمعی دارند، یعنی هر یک از این گزینه‌ها به موارد قبلی افزوده خواهد شد. عبارات منظم به یکی از شکل‌های زیر هستند:
[{language}]/tagregexp/[nameregexp/]modifiers
@regexfile

که در آن tagregexp برای تطبیق برچسب استفاده می‌شود. این عبارت نباید با کاراکترهای بیهوده تطبیق یابد. چنانچه تطبیق به‌گونه‌ای باشد که ناگزیر کاراکترهایی بیش از اندازه مورد نیاز توسط tagregexp تطبیق داده شوند، افزودن nameregexp برای محدود کردن دامنه برچسب می‌تواند سودمند باشد. گزینه --ctags عبارات منظم بدون nameregexp را نادیده می‌گیرد. نحو عبارات منظم همانند Emacs است، جز اینکه گریزهای بک‌اسلش همانند GNU grep هستند (که به عنوان نمونه به معنای عدم پشتیبانی از shy groupها است)، و [:ascii:]، [:multibyte:]، [:nonascii:]، [:word:] و [:unibyte:] پشتیبانی نمی‌شوند. توالی‌های گریز کاراکتری زیر پشتیبانی می‌شوند: \a, \b, \d, \e, \f, \n, \r, \t, \v که به‌ترتیب نماینده کاراکترهای اسکی BEL، BS، DEL، ESC، FF، NL، CR، TAB و VT هستند.
بخش modifiers دنباله‌ای از ۰ یا چند کاراکتر از میان موارد زیر است: i، که به معنای نادیده گرفتن بزرگی و کوچکی حروف در تطبیق است؛ m، که بدان معناست که tagregexp به جای خط به خط، با کل محتوای فایل به‌طور یکجا تطبیق داده می‌شود و توالی تطبیق می‌تواند چندین خط را شامل شود؛ و s، که متضمن m بوده و به این معناست که کاراکتر نقطه در tagregexp با کاراکتر خط جدید نیز مطابقت می‌یابد.
جداکننده، که در مثال‌ها / است، می‌تواند هر کاراکتری غیر از فاصله، تب، آکوالادها و @ باشد. اگر کاراکتر جداکننده در درون عبارت منظم مورد نیاز باشد، باید با قرار دادن پیش از آن، اسکیپ شود.
پیشوند اختیاری {language} بدان معناست که برچسب باید تنها برای فایل‌های زبان language ایجاد شده و در غیر این صورت نادیده گرفته شود. این ویژگی به‌ویژه هنگام ذخیره عبارات منظم از پیش تعریف‌شده بسیار در یک فایل مفید است.
در شکل دوم، regexfile نام فایلی است که شامل تعدادی از آرگومان‌های گزینه --regex=، هر کدام در یک خط است. خطوطی که با یک فاصله یا تب آغاز می‌شوند، توضیح (comment) تلقی شده و نادیده گرفته می‌شوند.

در اینجا چند مثال آورده شده است. تمام عبارات منظم نقل‌قول شده‌اند تا از تفسیر آن‌ها توسط شل جلوگیری شود.

برچسب‌گذاری ماکروهای DEFVAR در فایل‌های منبع emacs:
--regex='/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'

برچسب‌گذاری فایل‌های VHDL (این مثال یک خط طولانی منفرد است که به دلایل قالب‌بندی در اینجا شکسته شده است):
--language=none --regex='/[ \t]*\(ARCHITECTURE\|\ CONFIGURATION\) +[^ ]* +OF/' --regex='/[ \t]*\ \(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\( BODY\)?\ \|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'

برچسب‌گذاری فایل‌های Tcl (این مثال پایانی نحوه استفاده از یک tagregexp را نشان می‌دهد):
--lang=none --regex='/proc[ \t]+\([^ \t]+\)/\1/'

یک عبارت منظم می‌تواند با {lang} آغاز شود، که بدین ترتیب تطبیق آن به خطوط فایل‌های زبان مشخص‌شده محدود می‌گردد. برای دریافت فهرستی از زبان‌های شناخته‌شده از etags --help استفاده کنید. این ویژگی به‌ویژه در داخل فایل‌های عبارات منظم (regex files) سودمند است. یک فایل عبارت منظم حاوی یک عبارت منظم در هر خط است. خطوط خالی و خطوطی که با فاصله یا تب آغاز می‌شوند نادیده گرفته می‌شوند. خطوطی که با @ شروع می‌شوند ارجاعاتی به فایل‌های عبارت منظمی هستند که نام آن‌ها پس از علامت @ می‌آید. سایر خطوط به عنوان عبارات منظم مانند موارد پس از --regex در نظر گرفته می‌شوند.
برای نمونه، دستور
etags --regex=@regex.file *.c
عبارات منظم موجود در فایل regex.file را می‌خواند.

-R, --no-regex

عدم انجام تطبیق عبارت منظم بیشتر بر روی فایل‌های بعدی. می‌تواند آزادانه با نام‌های فایل و گزینه --regex ترکیب شود.

--fallback-lang

اگر زبان فایلی قابل تشخیص نباشد، تلاش می‌کند آن را به عنوان Fortran و C/C++ تجزیه کند. این حالت پیش‌فرض است.

--no-fallback-lang

عدم استفاده از Fortran و C/C++ به عنوان جایگزین برای فایل‌هایی که زبان آن‌ها قابل تشخیص نیست.

--empty-file-entries

تولید مدخل‌های فایل برای فایل‌های بدون برچسب. این حالت پیش‌فرض است.

--no-empty-file-entries

عدم ایجاد مدخل‌های فایل در خروجی برای فایل‌های بدون برچسب.

-u, --update

به‌روزرسانی مدخل‌های برچسب برای فایل‌های مشخص‌شده در خط فرمان، بدون تغییر در مدخل‌های برچسب سایر فایل‌ها. در حال حاضر، این قابلیت با حذف مدخل‌های موجود برای فایل‌های ارائه‌شده و سپس بازنویسی مدخل‌های جدید در انتهای فایل برچسب‌ها پیاده‌سازی شده است. معمولاً ساخت مجدد کل فایل برچسب‌ها سریع‌تر از استفاده از این گزینه است. این گزینه تنها در صورت استفاده از --ctags کاربرد دارد.

-v, --vgrind

به‌جای تولید یک فایل برچسب، نمایه (در قالب vgrind) را در خروجی استاندارد می‌نویسد. این گزینه تنها در صورت استفاده از --ctags کاربرد دارد.

-x, --cxref

به‌جای تولید یک فایل برچسب، ارجاع متقابل (در قالب cxref) را در خروجی استاندارد می‌نویسد. این گزینه تنها در صورت استفاده از --ctags کاربرد دارد.

-h, -H, --help

چاپ اطلاعات راهنمای استفاده. در صورت همراهی با یک یا چند مورد از --language=LANG اطلاعات تفصیلی درباره چگونگی ایجاد برچسب‌ها برای زبان LANG چاپ می‌شود.

-V, --version

چاپ نسخه جاری برنامه (مشابه نسخه emacs که etags همراه با آن منتشر شده است).

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

مدخل "emacs" در info؛ GNU Emacs Manual، اثر ریچارد استالمن (Richard Stallman).
cxref(1), emacs(1), vgrind(1), vi(1).

کپی‌رایت و تکثیر (COPYING)

حق نشر ۱۹۹۲، ۱۹۹۹، ۲۰۰۱–۲۰۲۶ بنیاد نرم‌افزارهای آزاد (Free Software Foundation, Inc.)

اجازه ساخت و توزیع نسخه‌های عین متن این سند به شرطی داده می‌شود که اعلان حق نشر و این اعلان اجازه در تمام نسخه‌ها حفظ شوند.

اجازه کپی و توزیع نسخه‌های اصلاح‌شده این سند تحت شرایط کپی عین متن داده می‌شود، مشروط بر آنکه کل اثر اشتقاقی حاصل تحت شرایط اعلان اجازه‌ای یکسان با این اعلان توزیع شود.

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