.\" Man page generated from reStructuredText .\" by the Docutils 0.22.2 manpage writer. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "ctags" "1" "" "6.2.1" "Universal Ctags" .SH "نام (NAME)" ctags \- تولید فایل‌های برچسب (tag) برای کد منبع .SH "خلاصه دستور (SYNOPSIS)" .nf \fBctags\fP [] [] \fBetags\fP [] [] .fi .sp .SH "توضیحات (DESCRIPTION)" .sp برنامه‌های \fIctags\fP و \fIetags\fP (گزینه \fB\-e\fP را ببینید) (که از این پس در اینجا، به جز موارد تمایز، در مجموع با عنوان ctags نامیده می‌شوند) یک فایل نمایه (یا \(dqtag\(dq) برای انواع گوناگونی از \fIاشیاء زبان\fP موجود در \fIفایل(های) منبع\fP تولید می‌کنند\&. این فایل برچسب امکان می‌دهد این موارد به سرعت و آسانی توسط یک ویرایشگر متنی یا سایر ابزارها (\fIابزارهای کلاینت\fP) مکان‌یابی شوند\&. یک \fIبرچسب\fP (tag) نمایانگر یک شیء زبانی است که مدخلی در نمایه برای آن در دسترس است (یا از نگاه دیگر، مدخل نمایه‌ای است که برای آن شیء ایجاد شده است)\&. .sp همچنین، ctags می‌تواند یک فایل ارجاع متقابل (cross reference) تولید کند که اطلاعات مربوط به اشیاء زبانی مختلف موجود در مجموعه‌ای از فایل‌های منبع را در قالبی خوانا برای انسان فهرست می‌کند\&. .sp فایل‌های نمایه برچسب توسط ویرایشگرهای متعددی پشتیبانی می‌شوند، که به کاربر امکان می‌دهند شیء مرتبط با یک نام ظاهر شده در یک فایل منبع را مکان‌یابی کرده و به فایل و خطی که آن نام را تعریف می‌کند بپرد\&. برای چگونگی استفاده از دستور ctags و فایل‌های نمایه برچسب در ویرایشگر، راهنمای ویرایشگر مورد علاقه خود را ببینید\&. .sp ابزار ctags قادر به تولید \fIانواع\fP (kinds) متفاوتی از برچسب‌ها برای هر یک از \fIزبان‌های\fP مختلف بسیار است\&. برای فهرست کاملی از زبان‌های پشتیبانی‌شده، نام‌هایی که با آن‌ها شناخته می‌شوند، و انواع برچسب‌هایی که برای هر کدام تولید می‌شود، گزینه‌های \fB\-\-list\-languages\fP و \fB\-\-list\-kinds\-full\fP را ببینید\&. .sp این صفحه راهنما \fIUniversal Ctags\fP را شرح می‌دهد، پیاده‌سازی‌ای از ctags که از \fIExuberant Ctags\fP مشتق شده است\&. تغییرات ناسازگار عمده میان Universal Ctags و Exuberant Ctags در ctags\-incompatibilities(7) برشمرده شده‌اند\&. .sp یکی از مزایای Exuberant Ctags این است که به کاربر اجازه می‌دهد تجزیه‌کننده (parser) جدیدی را از خط فرمان تعریف کند\&. گسترش این قابلیت یکی از ویژگی‌های عمده Universal Ctags است\&. سند ctags\-optlib(7) چگونگی گسترش این قابلیت را شرح می‌دهد\&. .sp قابلیت‌های آزمایشی به‌تازگی معرفی‌شده در اینجا توضیح داده نشده‌اند\&. اگر به چنین ویژگی‌هایی و سازوکارهای داخلی ctags علاقه‌مند هستید، از \% دیدن کنید\&. .SH "رابط خط فرمان (COMMAND LINE INTERFACE)" .sp با وجود انبوه گزینه‌های موجود، پیش‌فرض‌ها به گونه‌ای تنظیم شده‌اند که ctags اغلب بدون هیچ گزینه‌ای اجرا می‌شود (مانند \(dq\fBctags *\fP\(dq یا \(dq\fBctags \-R\fP\(dq)، که یک فایل برچسب در شاخه فعلی برای تمام فایل‌های منبع شناخته‌شده ایجاد خواهد کرد\&. گزینه‌های شرح‌داده‌شده در زیر صرفاً برای ایجاد امکان سفارشی‌سازی بر اساس نیازهای ویژه ارائه شده‌اند\&. .sp توجه داشته باشید که فاصله‌های جداکننده گزینه‌های تک‌حرفی از پارامترهایشان اختیاری هستند\&. .sp همچنین توجه داشته باشید که پارامترهای بولی گزینه‌های طولانی (گزینه‌هایی که با \fB\-\-\fP شروع می‌شوند و پارامتر \fB[=(yes|no)]\fP می‌گیرند) می‌توانند حذف شوند، که در این صورت مقدار \fB=yes\fP لحاظ می‌شود (مثلاً \fB\-\-sort\fP معادل \fB\-\-sort=yes\fP است)\&. علاوه بر این توجه داشته باشید که مقادیر \fB=1\fP، \fB=on\fP و \fB=true\fP به عنوان مترادف‌های \fB=yes\fP، و مقادیر \fB=0\fP، \fB=off\fP و \fB=false\fP به عنوان مترادف‌های \fB=no\fP در نظر گرفته می‌شوند\&. .sp برخی گزینه‌ها نادیده گرفته می‌شوند یا تنها هنگام اجرا در حالت etags (گزینه \fB\-e\fP را ببینید) مفید هستند\&. به این گونه گزینه‌ها اشاره خواهد شد\&. .sp طبق قرارداد استاندارد POSIX، مقدار \fI\fP باید پیش از \fI\fP بیاید\&. .sp گزینه‌هایی که نام زبان‌ها را می‌پذیرند، آن نام‌ها را با حروف بزرگ یا کوچک دریافت می‌کنند\&. برای فهرستی کامل از نام زبان‌های توکار، گزینه \fB\-\-list\-languages\fP را ببینید\&. .SS "حروف و نام‌ها (Letters and names)" .sp برخی گزینه‌ها پرچم‌های تک‌حرفی را به عنوان پارامتر می‌پذیرند (مانند گزینه \fB\-\-kinds\-\fP)\&. تعیین صرفاً حروف به کاربر کمک می‌کند یک خط فرمان پیچیده را سریعاً ایجاد کند\&. با این حال، یک خط فرمان شامل توالی پرچم‌های تک‌حرفی به سختی قابل درک خواهد بود\&. .sp ابزار Universal Ctags علاوه بر پرچم‌های تک‌حرفی، پرچم‌های نام‌کامل را نیز می‌پذیرد\&. پرچم‌های نام‌کامل و تک‌حرفی را می‌توان با احاطه کردن هر نام‌کامل با آکولاد، در یک پارامتر گزینه ترکیب کرد\&. بدین ترتیب، برای مثال، سه نگارش زیر برای گزینه \fB\-\-kinds\-C\fP معنای یکسانی دارند: .INDENT 0.0 .INDENT 3.5 .sp .EX \-\-kinds\-C=+pLl \-\-kinds\-C=+{prototype}{label}{local} \-\-kinds\-C=+{prototype}L{local} .EE .UNINDENT .UNINDENT .sp توجه داشته باشید که آکولادها ممکن است در پوسته (shell) شما نویسه‌های متا باشند\&. در چنین حالتی از نقل‌قول تکی استفاده کنید\&. .sp گزینه‌های \fB\-\-list\-...\fP پرچم‌های تک‌حرفی و پرچم‌های نام‌کامل مرتبط با آن‌ها را نمایش می‌دهند\&. .SS "گزینه‌های فهرست‌گیری (List options)" .sp ابزار Universal Ctags گزینه‌های \fB\-\-list\-...\fP متعددی را معرفی می‌کند که داده‌های درونی Universal Ctags را فراهم می‌سازند (\(dqListing Options\(dq را ببینید)\&. هم کاربران و هم ابزارهای کلاینت می‌توانند از این داده‌ها استفاده کنند\&. گزینه‌های \fB\-\-with\-list\-header\fP و \fB\-\-machinable\fP خروجی اکثر گزینه‌های \fB\-\-list\-...\fP را تنظیم می‌کنند\&. .sp تنظیمات پیش‌فرض (\fB\-\-with\-list\-header=yes\fP و \fB\-\-machinable=no\fP) برای استفاده تعاملی از طریق ترمینال است\&. سرآیندی که معنای ستون‌ها را توضیح می‌دهد به سادگی به خروجی افزوده می‌شود و هر ستون در تمامی خطوط تراز می‌گردد\&. خط سرآیند با یک نویسه هش (\(aq\fB#\fP\(aq) آغاز می‌شود\&. .sp برای اسکریپت‌نویسی در یک ابزار کلاینت، گزینه‌های \fB\-\-with\-list\-header=no\fP و \fB\-\-machinable=yes\fP ممکن است مفید باشند\&. سرآیند به خروجی اضافه نمی‌شود و هر ستون با نویسه‌های تب جدا می‌شود\&. .sp توجه داشته باشید که ترتیب ستون‌ها در نگارش‌های آینده تغییر خواهد کرد\&. با این وجود، برچسب‌ها در سرآیند تغییر نخواهند کرد\&. بنابراین یک ابزار کلاینت با پایش سرآیند می‌تواند نمایه ستون مورد نظر را بیابد\&. .\" options that should be explained and revised here .\" ``--list-features`` (done) .\" ``--machinable`` (done) .\" ``--with-list-header`` (done) . .SH "گزینه‌ها (OPTIONS)" .sp دستور ctags گزینه‌های بیشتری نسبت به موارد فهرست‌شده در اینجا دارد. گزینه‌هایی که با یک نویسه زیرخط (underscore) آغاز می‌شوند، مانند \fB\-\-_echo=\fP، در اینجا فهرست نشده‌اند. آن‌ها آزمایشی بوده یا برای اهداف اشکال‌زدایی هستند. .sp شیوه‌نگارش: \fB\fP برای یک رشته متغیر \fBfoo\fP، \fB[ ... ]\fP برای موارد اختیاری، \fB|\fP برای انتخاب، و \fB( ... )\fP برای گروه‌بندی به کار می‌رود. برای نمونه \fB\-\-foo[=(yes|no)]\fP به معنای \fB\-\-foo\fP، \fB\-\-foo=yes\fP، یا \fB\-\-foo=no\fP است\&. .SS "گزینه‌های فایل ورودی/خروجی (Input/Output File Options)" .INDENT 0.0 .TP .B \fB\-\-exclude=\fP الگوی \fI\fP را به فهرست فایل‌ها و شاخه‌های مستثنی‌شده می‌افزاید. این گزینه را می‌توان به تعداد دلخواه مشخص کرد. برای هر نام فایلی که توسط ctags بررسی می‌شود، هر الگوی مشخص‌شده با استفاده از این گزینه هم با مسیر کامل (مانند \fBsome/path/base.ext\fP) و هم با نام پایه (مانند \fBbase.ext\fP) فایل مقایسه خواهد شد؛ بنابراین این امکان فراهم می‌شود که الگوها بدون در نظر گرفتن مسیر با یک نام فایل معین تطبیق یابند، یا تنها با یک مسیر مشخص تطابق داشته باشند. .sp اگر پشتیبانی مناسب در کتابخانه زمان اجرای کامپایلر C شما موجود باشد، الگو می‌تواند حاوی نویسه‌های عام شل (shell wildcards) متداول در یونیکس (و نه عبارات باقاعده / regular expressions) باشد (حتماً پارامتر گزینه را در گیومه قرار دهید تا نویسه‌های عام پیش از ارسال به ctags توسط شل بسط داده نشوند؛ همچنین توجه داشته باشید که نویسه‌های عام می‌توانند با نویسه اسلش، \(aq\fB/\fP\(aq، نیز تطبیق یابند). می‌توانید با بررسی خروجی گزینه \fB\-\-list\-features\fP بررسی کنید که آیا نویسه‌های عام شل در پلتفرم شما در دسترس هستند یا خیر، که در این صورت \fBwildcards\fP در فهرست ویژگی‌های کامپایل‌شده درج خواهد بود؛ در غیر این صورت، الگو با استفاده از مقایسه متنی ساده با نام فایل‌ها تطبیق داده می‌شود. .sp اگر \fI\fP با نویسه \(aq\fB@\fP\(aq آغاز شود، بقیه رشته به عنوان نام فایلی تفسیر می‌شود که باید الگوهای استثنا از آن خوانده شوند، در هر سطر یک الگو. اگر الگو خالی باشد، فهرست الگوهای مستثنی‌شده پاک می‌شود. .sp توجه داشته باشید که هنگام شروع برنامه، فهرست پیش‌فرض استثناها شامل نام‌های فایل‌های پنهان و سیستمی متداول، الگوهایی برای فایل‌های باینری، و شاخه‌هایی است که عموماً مطلوب نیست هنگام پردازش گزینه \fB\-\-recurse\fP به درون آن‌ها وارد شد. برای مشاهده فهرست الگوهای استثنای توکار، از \fB\-\-list\-excludes\fP استفاده کنید\&. .sp همچنین به توضیحات گزینه \fB\-\-exclude\-exception=\fP مراجعه کنید. .TP .B \fB\-\-exclude\-exception=\fP الگوی \fI\fP را به فهرست فایل‌ها و شاخه‌های مشمول (مستثنی‌نشده) اضافه می‌کند. این الگو بر فایل‌ها و شاخه‌هایی اثر می‌گذارد که توسط الگوی مشخص‌شده با گزینه \fB\-\-exclude=\fP مستثنی شده‌اند. .sp برای نمونه، اگر می‌خواهید ctags همه فایل‌های زیر شاخه \fBfoo\fP را به جز \fBfoo/main.c\fP نادیده بگیرد، از این خط فرمان استفاده کنید: \fB\-\-exclude=foo/* \-\-exclude\-exception=foo/main.c\fP\&. .TP .B \fB\-\-filter[=(yes|no)]\fP باعث می‌شود ctags مانند یک فیلتر رفتار کند؛ به این صورت که نام فایل‌های منبع را از ورودی استاندارد می‌خواند و برچسب‌های آن‌ها را به صورت فایل‌به‌فایل در خروجی استاندارد چاپ می‌کند. اگر \fB\-\-sort\fP فعال باشد، برچسب‌ها تنها در محدوده همان فایل منبعی که در آن تعریف شده‌اند مرتب می‌شوند. نام‌های فایل از ورودی استاندارد در حالت ورودی سطر‌محور خوانده می‌شوند (به یادداشت مربوط به گزینه \fB\-L\fP مراجعه کنید) و تنها پس از نام‌های فایل فهرست‌شده در خط فرمان یا از هر فایل ارائه‌شده با استفاده از گزینه \fB\-L\fP پردازش می‌شوند. هنگامی که این گزینه فعال باشد، گزینه‌های \fB\-f\fP، \fB\-o\fP و \fB\-\-totals\fP نادیده گرفته می‌شوند. این گزینه کاملاً تخصصی و کم‌کاربرد است و به طور پیش‌فرض غیرفعال است. .TP .B \fB\-\-filter\-terminator=\fP رشته \fI\fP را مشخص می‌کند تا در هنگام فعال بودن گزینه \fB\-\-filter\fP، پس از برچسب‌های مربوط به هر نام فایل تجزیه‌شده، در خروجی استاندارد چاپ شود. این امر می‌تواند به برنامه‌ای که خروجی ctags را می‌خواند اجازه دهد تشخیص دهد چه زمانی خروجی هر فایل به پایان رسیده است. .sp توجه داشته باشید که اگر نام فایل خوانده‌شده یک شاخه باشد و \fB\-\-recurse\fP فعال باشد، این رشته تنها یک بار در انتهای تمام برچسب‌های یافته‌شده در پیمایش آن شاخه چاپ خواهد شد. این رشته همواره با نویسه خط جدید پایانی خود از آخرین خط برچسب فایل جدا خواهد شد. .sp این گزینه کاملاً تخصصی و کم‌کاربرد است و به طور پیش‌فرض خالی است. .TP .B \fB\-\-links[=(yes|no)]\fP مشخص می‌کند که آیا پیوندهای نمادین (در صورت پشتیبانی) باید دنبال شوند یا خیر. در صورت غیرفعال بودن، پیوندهای نمادین نادیده گرفته می‌شوند. این گزینه به طور پیش‌فرض روشن است. .TP .B \fB\-\-maxdepth=\fP عمق بازگشت در شاخه‌ها که با گزینه \fB\-\-recurse\fP (\fB\-R\fP) فعال شده است را محدود می‌کند. .TP .B \fB\-\-recurse[=(yes|no)]\fP به صورت بازگشتی وارد شاخه‌های موجود در فهرست فایل‌های ارائه‌شده می‌شود. .sp اگر فهرست فایل‌های ارائه‌شده خالی باشد و هیچ فهرست فایلی با گزینه \fB\-L\fP مشخص نشده باشد، شاخه فعلی (یعنی \(aq\fB\&.\fP\(aq) فرض می‌شود. پیوندهای نمادین به طور پیش‌فرض دنبال می‌شوند (گزینه \fB\-\-links\fP را ببینید). اگر این رفتارها را نمی‌پسندید، یا فایل‌ها را صریحاً مشخص کنید یا خروجی \fBfind(1)\fP را به \(dq\fBctags \-L \-\fP\(dq لوله‌کشی (pipe) کنید. همچنین گزینه‌های \fB\-\-exclude\fP و \fB\-\-maxdepth\fP را برای محدود کردن بازگشت ببینید. .sp نکته: این گزینه در حال حاضر روی همه پلتفرم‌ها پشتیبانی نمی‌شود. اگر خروجی گزینه \fB\-\-help\fP شامل این گزینه باشد، در دسترس خواهد بود. .UNINDENT .\" TODO(code): --list-features option should support this. . .INDENT 0.0 .TP .B \fB\-R\fP معادل \fB\-\-recurse\fP است\&. .TP .B \fB\-L \fP فهرستی از نام‌های فایل را که باید برچسب‌ها برای آن‌ها تولید شوند از \fI\fP می‌خواند. .sp اگر فایل به صورت \(aq\fB\-\fP\(aq مشخص شود، نام‌های فایل از ورودی استاندارد خوانده می‌شوند. نام‌های فایلی که با استفاده از این گزینه خوانده می‌شوند، پس از نام‌های فایل موجود در خط فرمان پردازش می‌گردند. گزینه‌ها نیز در این ورودی پذیرفته می‌شوند. اگر این گزینه بیش از یک بار مشخص شود، تنها آخرین مورد اعمال خواهد شد. .sp نکته: فایل در حالت سطر‌محور خوانده می‌شود، جایی که خط جدید تنها جداکننده است و فاصله‌های خالی غیرپایانی مهم تلقی می‌شوند، تا بتوان نام‌های فایل حاوی فاصله را نیز مشخص کرد (با این حال، فاصله‌های خالی پایانی از سطرها حذف می‌شوند)؛ این امر می‌تواند بر نحوه تجزیه گزینه‌ها در صورت گنجانده شدن در ورودی اثر بگذارد. .TP .B \fB\-\-append[=(yes|no)]\fP مشخص می‌کند که آیا برچسب‌های تولیدشده از فایل‌های معین باید به برچسب‌های موجود در فایل برچسب اضافه شوند یا جایگزین آن‌ها گردند. این گزینه به طور پیش‌فرض \fBno\fP است. .TP .B \fB\-a\fP معادل \fB\-\-append\fP است\&. .TP .B \fB\-f \fP از نام مشخص‌شده توسط \fI\fP برای فایل برچسب استفاده می‌کند (پیش‌فرض \(dq\fBtags\fP\(dq است، یا هنگام اجرا در حالت etags مقدار آن \(dq\fBTAGS\fP\(dq می‌باشد). اگر \fI\fP به صورت \(aq\fB\-\fP\(aq مشخص شود، برچسب‌ها به جای آن در خروجی استاندارد نوشته می‌شوند. .sp دستور ctags اگر tagfile از قبل وجود داشته باشد و خط نخست آن حاوی چیزی به جز یک خط برچسب معتبر باشد، سرسختانه از دریافت دستورات سر باز می‌زند. این کار در صورتی که اشتباهاً عبارت \(dq\fBctags \-f *.c\fP\(dq را تایپ کنید جان شما را نجات خواهد داد، چرا که در غیر این صورت نخستین فایل C شما با برچسب‌های تولیدشده از بقیه فایل‌ها بازنویسی می‌شد! این ابزار همچنین از پذیرفتن نام فایل چندنویسه‌ای که با یک نویسه \(aq\fB\-\fP\(aq (خط تیره) آغاز شود امتناع می‌ورزد، چرا که این مورد به احتمال زیاد بدان معناست که نام فایل برچسب را جا انداخته‌اید و این گزینه سعی کرده گزینه بعدی را به عنوان نام فایل در نظر بگیرد. اگر واقعاً می‌خواهید نام فایل برچسب خروجی خود را \fB\-ugly\fP بگذارید، آن را به صورت \(dq\fB\-f ./\-ugly\fP\(dq مشخص کنید. .sp این گزینه باید پیش از نخستین نام فایل درج شود. اگر این گزینه بیش از یک بار مشخص شود، تنها آخرین مورد اعمال خواهد شد. .TP .B \fB\-o \fP معادل \(dq\fB\-f tagfile\fP\(dq است. .UNINDENT .SS گزینه‌های قالب خروجی (Output Format Options) .INDENT 0.0 .TP .B \fB\-\-format=(1|2)\fP قالب پرونده برچسب خروجی را تغییر می‌دهد. در حال حاضر تنها مقادیر معتبر برای سطح، 1 یا 2 هستند. سطح 1 قالب پرونده برچسب اصلی را مشخص می‌کند و سطح 2 یک قالب توسعه‌یافته جدید شامل فیلدهای گسترش را تعیین می‌کند (اما به گونه‌ای که سازگاری با گذشته با پیاده‌سازی‌های اصلی \fBvi(1)\fP حفظ شود). سطح پیش‌فرض 2 است. [در حالت etags نادیده گرفته می‌شود] .TP .B \fB\-\-output\-format=(u\-ctags|e\-ctags|etags|xref|json)\fP قالب خروجی را مشخص می‌کند. پیش‌فرض \fBu\-ctags\fP است\&. برای \fBu\-ctags\fP و \fBe\-ctags\fP به tags(5) مراجعه کنید\&. شبه‌برچسب \fBTAG_OUTPUT_MODE\fP انتخاب مورد نظر، \fBu\-ctags\fP یا \fBe\-ctags\fP را مشخص می‌کند\&. برای اطلاعات بیشتر درباره این شبه‌برچسب، ctags\-client\-tools(7) را ببینید\&. .sp برای \fBetags\fP گزینه \fB\-e\fP، و برای \fBxref\fP گزینه \fB\-x\fP را ببینید\&. قالب \fBjson\fP تنها در صورتی در دسترس است که برنامه اجرایی ctags با \fBlibjansson\fP ساخته شده باشد\&. برای اطلاعات بیشتر درباره قالب \fBjson\fP، ctags\-json\-output(5) را ببینید\&. .sp همچنین به \fB\-\-list\-output\-formats\fP مراجعه کنید\&. .TP .B \fB\-e\fP مشابه \fB\-\-output\-format=etags\fP است\&. حالت etags را فعال می‌کند، که یک پرونده برچسب برای استفاده با ویرایشگر Emacs ایجاد خواهد کرد. همچنین، اگر ctags با نامی فراخوانی شود که حاوی رشته \(dqetags\(dq باشد (خواه با تغییر نام، یا ایجاد پیوند به فایل اجرایی)، حالت etags فعال خواهد شد. .TP .B \fB\-x\fP مشابه \fB\-\-output\-format=xref\fP است\&. به جای تولید پرونده برچسب، یک پرونده ارجاع متقابل (xref) جدولی و خوانا برای انسان را در خروجی استاندارد چاپ می‌کند. اطلاعات موجود در خروجی شامل: نام برچسب؛ نوع برچسب؛ شماره سطر، نام پرونده، و سطر منبع (با فشرده‌سازی فاصله‌های خالی اضافی) از پرونده‌ای است که برچسب را تعریف می‌کند. هیچ پرونده برچسبی نوشته نمی‌شود و تمام گزینه‌هایی که بر خروجی پرونده برچسب تأثیر می‌گذارند نادیده گرفته خواهند شد. .sp کاربردهای نمونه برای این قابلیت عبارتند از تولید فهرستی از تمام توابع موجود در یک پرونده منبع (مانند \(dq\fBctags \-x \-\-kinds\-c=f file\fP\(dq)، یا تولید فهرستی از تمام متغیرهای سراسری با دید بیرونی موجود در یک پرونده منبع (مانند \(dq\fBctags \-x \-\-kinds\-c=v \-\-extras=\-F file\fP\(dq). .TP .B \fB\-\-sort=(yes|no|foldcase)\fP مشخص می‌کند که آیا پرونده برچسب باید بر اساس نام برچسب مرتب شود یا خیر (پیش‌فرض \fByes\fP است). توجه داشته باشید که \fBvi(1)\fP اصلی به برچسب‌های مرتب‌شده نیاز داشت. مقدار \fBfoldcase\fP مرتب‌سازی بدون حساسیت به حروف کوچک و بزرگ (case\-folded) را مشخص می‌کند. جستجوهای دودویی سریع در پرونده‌های برچسب مرتب‌شده با case\-folding نیازمند پشتیبانی ویژه از سوی ابزارهای استفاده‌کننده از پرونده‌های برچسب است، مانند آنچه در کتابخانه readtags در ctags یا نسخه 6.2 یا بالاتر Vim (با استفاده از \(dq\fBset ignorecase\fP\(dq) یافت می‌شود. [در حالت etags نادیده گرفته می‌شود] .TP .B \fB\-u\fP معادل \fB\-\-sort=no\fP است (یعنی \(dqمرتب‌نشده\(dq یا unsorted). .TP .B \fB\-\-etags\-include=\fP ارجاعی به \fI\fP را در پرونده برچسب می‌گنجاند. این گزینه می‌تواند به تعداد دلخواه تکرار شود. این قابلیت از امکان Emacs برای استفاده از پرونده برچسبی که سایر پرونده‌های برچسب را در بر می‌گیرد (\fIincludes\fP)، پشتیبانی می‌کند. [تنها در حالت etags در دسترس است] .TP .B \fB\-\-input\-encoding=\fP کدگذاری (\fI\fP) پرونده‌های ورودی را مشخص می‌کند. در صورت تعیین این گزینه، Universal Ctags ورودی را از این کدگذاری به کدگذاری مشخص‌شده با \fB\-\-output\-encoding=encoding\fP تبدیل می‌کند\&. .TP .B \fB\-\-input\-encoding\-=\fP یک \fI\fP ورودی خاص را برای زبان \fI\fP مشخص می‌کند\&. این مقدار بر مقدار پیش‌فرض سراسری که با \fB\-\-input\-encoding\fP داده شده برتری دارد\&. .TP .B \fB\-\-output\-encoding=\fP کدگذاری (\fI\fP) پرونده برچسب‌ها را مشخص می‌کند. ابزار Universal Ctags کدگذاری پرونده‌های ورودی را از کدگذاری مشخص‌شده توسط \fB\-\-input\-encoding=\fP به این کدگذاری تبدیل می‌کند. .sp علاوه بر این، \fI\fP در بالای پرونده برچسب‌ها به عنوان مقدار شبه‌برچسب \fBTAG_FILE_ENCODING\fP درج می‌شود. مقدار پیش‌فرض \fI\fP برابر با \fBUTF\-8\fP است\&. .UNINDENT .SS گزینه‌های انتخاب و نگاشت زبان (Language Selection and Mapping Options) .INDENT 0.0 .TP .B \fB\-\-language\-force=(|auto)\fP به‌طور پیش‌فرض، ctags زبان پرونده منبع را به صورت خودکار انتخاب می‌کند، و پرونده‌هایی را که زبانشان قابل تشخیص نیست نادیده می‌گیرد (به بخش \(dqتعیین زبان پرونده\(dq یا Determining file language مراجعه کنید). این گزینه استفاده از \fIlanguage\fP مشخص‌شده (غیرحساس به بزرگی و کوچکی حروف؛ چه توکار و چه تعریف‌شده توسط کاربر) را برای هر پرونده داده‌شده تحمیل می‌کند، به جای آنکه زبان را بر اساس پسوند پرونده به‌طور خودکار انتخاب کند. .sp علاوه بر این، مقدار ویژه \fBauto\fP نشان می‌دهد که زبان باید به‌طور خودکار انتخاب شود (که عملاً این گزینه را غیرفعال می‌کند). .TP .B \fB\-\-languages=[+|\-](|all)\fP زبان‌هایی را مشخص می‌کند که تولید برچسب برای آن‌ها فعال است، به طوری که \fI\fP شامل فهرستی از نام‌های زبان جداشده با کاما است (غیرحساس به بزرگی و کوچکی حروف؛ چه توکار و چه تعریف‌شده توسط کاربر). .sp اگر زبان نخست در \fI\fP با هیچ‌یک از علامت‌های \(aq\fB+\fP\(aq یا \(aq\fB\-\fP\(aq شروع نشده باشد، فهرست کنونی (تنظیمات جاری زبان‌های فعال/غیرفعال که در درون ctags مدیریت می‌شوند) پیش از افزودن یا حذف زبان‌ها در \fI\fP پاک خواهد شد\&. تا زمانی که به یک \(aq\fB\-\fP\(aq برخورد نشود، هر زبان در \fI\fP به فهرست کنونی اضافه خواهد شد. .sp به محض مواجهه با \(aq\fB+\fP\(aq یا \(aq\fB\-\fP\(aq در \fI\fP، زبان‌های پس از آن به ترتیب به فهرست کنونی افزوده یا از آن حذف می‌شوند. بنابراین جایگزین کردن فهرست کنونی با فهرستی جدید، یا افزودن و کاستن زبان‌ها از فهرست جاری ساده می‌شود. .sp فهرست واقعی پرونده‌هایی که برچسب‌ها برای آن‌ها تولید می‌شوند به نگاشت پسوند زبانِ در حال اجرا وابسته است (به گزینه \fB\-\-langmap\fP مراجعه کنید). توجه داشته باشید که بیشتر زبان‌ها، از جمله زبان‌های تعریف‌شده توسط کاربر، فعال هستند مگر اینکه صراحتاً با استفاده از این گزینه غیرفعال شده باشند. نام‌های زبان گنجانده‌شده در فهرست می‌توانند هر زبان توکار یا زبانی باشند که پیش‌تر با \fB\-\-langdef\fP تعریف شده باشد\&. .sp مقدار پیش‌فرض \fBall\fP است که به عنوان یک آرگومان معتبر نیز پذیرفته می‌شود. برای مشاهده فهرستی از تمام نام‌های زبان (توکار و تعریف‌شده توسط کاربر) به گزینه \fB\-\-list\-languages\fP مراجعه کنید. .sp توجه داشته باشید که گزینه \fB\-\-languages=\fP به شیوه انباشتی عمل می‌کند؛ این گزینه می‌تواند چندین بار با آرگومان‌های متفاوت در یک خط فرمان مشخص شود. .TP .B \fB\-\-alias\-=[+|\-](|default)\fP یک الگوی نام مستعار \fI\fP را به زبان مشخص‌شده با \fI\fP اضافه (\(aq\fB+\fP\(aq) یا حذف (\(aq\fB\-\fP\(aq) می‌کند\&. ابزار ctags در مرحله \(dqتعیین زبان پرونده\(dq به الگوی نام مستعار مراجعه می‌کند. .sp پارامتر \fI\fP یک فهرست نیست. برای افزودن یا حذف چندین الگوی نام مستعار، از این گزینه چندین بار در یک خط فرمان استفاده کنید. .sp برای بازگردانی نام‌های مستعار پیش‌فرض زبان، \fBdefault\fP را مشخص کنید\&. .sp استفاده از \fBall\fP برای \fI\fP در دو حالت زیر معنی دارد: .INDENT 7.0 .TP .B \fB\-\-alias\-all=\fP این کار تنظیمات نام‌های مستعار تمام زبان‌ها را پاک می‌کند. .TP .B \fB\-\-alias\-all=default\fP این کار نام‌های مستعار پیش‌فرض زبان‌ها را برای تمام زبان‌ها بازیابی می‌کند. .UNINDENT .TP .B \fB\-\-guess\-language\-eagerly\fP محتوای پرونده را برای حدس اکتشافی تجزیه‌کننده مناسب زبان بررسی می‌کند. به \(dqتعیین زبان پرونده\(dq مراجعه کنید. .TP .B \fB\-G\fP معادل \fB\-\-guess\-language\-eagerly\fP است\&. .TP .B \fB\-\-langmap=[,[...]]\fP چگونگی نگاشت نام‌های پرونده به زبان‌ها را کنترل می‌کند (به گزینه \fB\-\-list\-maps\fP مراجعه کنید). هر \fI\fP جداشده با کاما شامل نام زبان (خواه زبانی توکار یا تعریف‌شده توسط کاربر)، یک دو‌نقطه، و فهرستی از \fIپسوندهای پرونده\fP و/یا \fIالگوهای نام پرونده\fP است\&. یک پسوند پرونده با قرار دادن یک نقطه پیش از پسوند مشخص می‌شود (مانند \fB\&.c\fP). یک الگوی نام پرونده با محصور کردن الگو در پرانتز مشخص می‌شود (مانند \fB([Mm]akefile)\fP). .sp اگر پشتیبانی مناسب در کتابخانه زمان اجرای کامپایلر C شما در دسترس باشد، الگوی نام پرونده می‌تواند شامل نویسه‌های عام معمول پوسته (wildcards) رایج در یونیکس باشد (حتماً پارامتر گزینه را نقل‌قول کنید تا از بسط نویسه‌های عام توسط پوسته پیش از ارسال به ctags محافظت شود). می‌توانید با بررسی خروجی گزینه \fB\-\-list\-features\fP مشخص کنید که آیا نویسه‌های عام پوسته در پلتفرم شما در دسترس هستند یا خیر، که در این صورت \fBwildcards\fP در فهرست ویژگی‌های کامپایل‌شده گنجانده خواهد شد؛ در غیر این صورت، الگوهای نام پرونده با استفاده از مقایسه متنی ساده با نام پرونده‌ها تطبیق داده می‌شوند. .sp هنگام نگاشت یک پسوند پرونده با گزینه \fB\-\-langmap\fP، ابتدا نگاشت آن از هر زبان دیگری برداشته می‌شود. (گزینه \fB\-\-map\-\fP کنترل دقیق‌تری فراهم می‌کند.) .sp اگر نویسه نخست در یک \fI\fP علامت مثبت (\(aq\fB+\fP\(aq) باشد، پسوندها و الگوهای نام پرونده در آن نگاشت به نگاشت کنونی آن زبان اضافه خواهند شد؛ در غیر این صورت، نگاشت جایگزین نگاشت کنونی خواهد شد. برای نمونه، برای تعیین اینکه تنها پرونده‌هایی با پسوندهای \fB\&.c\fP و \fB\&.x\fP به عنوان پرونده‌های زبان C در نظر گرفته شوند، از \fB\-\-langmap=c:.c.x\fP استفاده کنید؛ برای اضافه کردن پرونده‌های دارای پسوند \fB\&.j\fP به عنوان پرونده‌های زبان Java، عبارت \fB\-\-langmap=c:.c.x,java:+.j\fP را مشخص کنید\&. برای نگاشت makefileها (مانند پرونده‌هایی با نام \fBMakefile\fP، \fBmakefile\fP، یا پرونده‌های با پسوند \fB\&.mak\fP) به زبانی به نام \fBmake\fP، عبارت \fB\-\-langmap=make:([Mm]akefile).mak\fP را مشخص کنید\&. برای نگاشت پرونده‌های بدون پسوند، نقطه‌ای را مشخص کنید که پس از آن نویسه‌ای غیر از نقطه نیامده باشد (مانند \(aq\fB\&.\fP\(aq، \fB\&..x\fP، \fB\&.x.\fP). .sp برای پاک کردن نگاشت یک زبان خاص (و در نتیجه جلوگیری از تولید خودکار برچسب‌ها برای آن زبان)، یک فهرست پسوند خالی مشخص کنید (مانند \fB\-\-langmap=fortran:\fP). برای بازگرداندن نگاشت‌های پیش‌فرض زبان برای یک زبان خاص، کلیدواژه \fBdefault\fP را برای نگاشت ارائه دهید. برای بازیابی نگاشت‌های پیش‌فرض زبان برای تمام زبان‌ها، \fB\-\-langmap=default\fP را مشخص کنید\&. .sp توجه داشته باشید که هنگام استنتاج زبان یک پرونده، الگوهای نام پرونده پیش از پسوندهای پرونده بررسی می‌شوند. این ترتیب در Universal Ctags با Exuberant Ctags متفاوت است. برای پیش‌زمینه این تغییر ناسازگار، ctags\-incompatibilities(7) را ببینید. .TP .B \fB\-\-map\-=[+|\-]|\fP این گزینه روشی را برای کنترل نگاشت(های) نام‌های پرونده به زبان‌ها به شیوه‌ای دقیق‌تر از گزینه \fB\-\-langmap\fP فراهم می‌کند. .sp در ctags، بیش از یک زبان می‌تواند به یک \fI\fP (الگو)ی نام پرونده یا \fI\fP (پسوند) پرونده نگاشت شود (\fIنگاشت N:1\fP). در مقابل، گزینه \fB\-\-langmap\fP تنها \fIنگاشت 1:1\fP را مدیریت می‌کند، یعنی تنها یک زبان به یک \fI\fP نام پرونده یا \fI\fP پرونده نگاشت می‌شود\&. یک نگاشت معمول N:1 در زبان‌های C++ و ObjectiveC دیده می‌شود؛ هر دو زبان دارای نگاشتی به \fB\&.h\fP به عنوان پسوند پرونده هستند. .sp پسوند پرونده با قرار دادن یک نقطه پیش از پسوند مشخص می‌شود (مانند \fB\&.c\fP). الگوی نام پرونده با قرار دادن الگو درون پرانتز مشخص می‌شود (مانند \fB([Mm]akefile)\fP). علامت مثبت پیشوندی (\(aq\fB+\fP\(aq) برای افزودن، و منفی (\(aq\fB\-\fP\(aq) برای حذف است. نبود پیشوند به معنای جایگزینی نگاشت \fI\fP است\&. .sp برخلاف \fB\-\-langmap\fP، پارامتر \fI\fP (یا \fI\fP) یک فهرست نیست. گزینه \fB\-\-map\-\fP یک پسوند (یا الگو) را دریافت می‌کند. با این حال، می‌توان این گزینه را با آرگومان‌های متفاوت چندین بار در یک خط فرمان مشخص کرد. .UNINDENT .SS گزینه‌های محتویات پرونده برچسب‌ها (Tags File Contents Options) .sp درباره فیلدها، گونه‌ها (kinds)، نقش‌ها (roles) و موارد اضافی (extras) به بخش \(dqمدخل‌های برچسب (TAG ENTRIES)\(dq مراجعه کنید. .INDENT 0.0 .TP .B \fB\-\-excmd=(number|pattern|mix|combine)\fP نوع دستور \fBEX\fP مورد استفاده برای یافتن محل برچسب‌ها در پرونده مبدأ را تعیین می‌کند. [در حالت etags نادیده گرفته می‌شود] .sp مقادیر معتبر برای نوع (یا کل کلمه یا حرف اول آن پذیرفته می‌شود) عبارتند از: .INDENT 7.0 .TP .B \fBnumber\fP تنها از شماره خطوط در پرونده برچسب برای مکان‌یابی برچسب‌ها استفاده می‌کند. این حالت دارای چهار مزیت است: .INDENT 7.0 .IP 1. 3 اندازه پرونده برچسب حاصل را به طور چشمگیری کاهش می‌دهد. .IP 2. 3 عدم موفقیت در یافتن برچسب‌ها را به دلیل تغییر سطری که برچسب را تعریف می‌کند و در نتیجه شکست در تطبیق الگو، حذف می‌کند (توجه داشته باشید که برخی ویرایشگرها مانند \fBvim\fP قادرند در بسیاری از چنین مواردی بازیابی را انجام دهند). .IP 3. 3 یافتن سطرهای مبدأ تطبیق‌یافته یکسان اما نادرست را حذف می‌کند (به \(dqایرادها (BUGS)\(dq مراجعه کنید). .IP 4. 3 مدخل‌های جداگانه‌ای را در پرونده برچسب برای سطرهایی که محتوای یکسان دارند نگه می‌دارد. در حالت الگو (pattern)، مدخل‌های تکراری حذف می‌شوند زیرا الگوهای جستجویی که تولید می‌کنند یکسان هستند و مدخل‌های تکراری را بی‌فایده می‌سازد. .UNINDENT .sp با این حال، این گزینه یک اشکال عمده دارد: تغییرات در پرونده‌های مبدأ می‌تواند باعث شود شماره خطوط ثبت‌شده در پرونده برچسب دیگر با سطرهای موجود در پرونده مبدأ مطابقت نداشته باشند، که باعث می‌شود پرش به برخی برچسب‌ها یک یا چند سطر از تعریف هدف خطا برود. اساساً این گزینه بهترین کاربرد را زمانی دارد که کد مبدأ اعمال‌شده روی آن در معرض تغییر نباشد. انتخاب این نوع گزینه باعث نادیده گرفته شدن گزینه‌های زیر می‌شود: \fB\-B\fP، \fB\-F\fP\&. .sp نوع \fBnumber\fP در قالب‌های خروجی Xref و JSON نادیده گرفته می‌شود. از \fB\-\-_xformat=\(dq...%n\(dq\fP برای قالب خروجی Xref، یا \fB\-\-fields=+n\-P\fP برای قالب خروجی JSON استفاده کنید. .\" NOTE: #2792 . .TP .B \fBpattern\fP تنها از الگوهای جستجو برای همه برچسب‌ها استفاده می‌کند، به جای شماره خطوطی که معمولاً برای تعاریف ماکرو به کار می‌روند. این حالت این مزیت را دارد که در صورت افزودن یا حذف سطرها از زمان ایجاد پرونده برچسب، به شماره خطوط منسوخ‌شده ارجاع نمی‌دهد. .TP .B \fBmixed\fP در این حالت، الگوها عموماً با استثنائاتی استفاده می‌شوند. برای فرترن (Fortran)، از شماره خطوط برای بلوک‌های مشترک (common blocks) استفاده می‌شود زیرا سطرهای مبدأ متناظر آن‌ها عموماً یکسان هستند و جستجوی الگو را برای یافتن همه تطابق‌ها بی‌فایده می‌سازد. .sp ابزار Exuberant Ctags یک استثنای دیگر دارد؛ برای C، از شماره خطوط برای برچسب‌های تعریف ماکرو استفاده می‌شود. Universal Ctags این استثنا را برای C ندارد. .sp این قالب پیش‌فرض تولیدشده توسط ctags اصلی بود و بنابراین به عنوان پیش‌فرض برای این گزینه حفظ شده است. .TP .B \fBcombine\fP شماره سطر و الگو را با قرار دادن یک نقطه‌ویرگول در میان آن‌ها به یکدیگر متصل می‌کند. .UNINDENT .TP .B \fB\-n\fP معادل با \fB\-\-excmd=number\fP\&. .TP .B \fB\-N\fP معادل با \fB\-\-excmd=pattern\fP\&. .TP .B \fB\-\-extras=[+|\-][|*]\fP مشخص می‌کند که آیا مدخل‌های برچسب اضافی برای انواع خاصی از اطلاعات گنجانده شوند یا خیر. همچنین برای دانستن اینکه موارد اضافی چه هستند، زیربخش \(dqموارد اضافی (Extras)\(dq را ببینید. .sp پارامتر \fI\fP مجموعه‌ای از پرچم‌های تک‌حرفی (و/یا پرچم‌های با نام طولانی) است که هر یک نمایانگر یک نوع مدخل برچسب اضافی برای گنجاندن در پرونده برچسب هستند. اگر پرچم‌ها با یکی از نویسه‌های \(aq\fB+\fP\(aq یا \(aq\fB\-\fP\(aq آغاز شوند، اثر هر پرچم به پرچم‌های فعال فعلی افزوده شده یا از آن‌ها کاسته می‌شود؛ در غیر این صورت، پرچم‌ها جایگزین تنظیمات فعلی می‌شوند. در صورت ارائه \(aq\fB*\fP\(aq، همه مدخل‌ها گنجانده می‌شوند. .sp این گزینه \fB\-\-extras=\fP برای کنترل موارد اضافی مشترک در همه زبان‌ها (یا موارد اضافی مستقل از زبان) است. ابزار Universal Ctags همچنین از موارد اضافی ویژه‌زبان پشتیبانی می‌کند. (برای این مفهوم به \(dqفیلدها و موارد اضافی ویژه‌زبان (Language\-specific fields and extras)\(dq مراجعه کنید). برای کنترل آن‌ها از گزینه \fB\-\-extras\-=\fP استفاده کنید. .TP .B \fB\-\-extras\-(|all)=[+|\-][|*]\fP مشخص می‌کند که آیا مدخل‌های برچسب اضافی برای انواع خاصی از اطلاعات برای زبان \fI\fP گنجانده شوند یا خیر. Universal Ctags موارد اضافی ویژه‌زبان را معرفی می‌کند. برای این مفهوم به \(dqفیلدها و موارد اضافی ویژه‌زبان (Language\-specific fields and extras)\(dq مراجعه کنید. این گزینه برای کنترل آن‌هاست. .sp مقدار \fBall\fP را به عنوان \fI\fP مشخص کنید تا پارامتر \fI\fP به همه زبان‌ها اعمال شود؛ با مشخص کردن \(aq\fB*\fP\(aq به عنوان پرچم‌های پارامتر، همه موارد اضافی فعال می‌شوند. اگر هیچ چیز به عنوان پرچم‌های پارامتر مشخص نشود (\fB\-\-extras\-all=\fP)، همه موارد اضافی غیرفعال می‌شوند. این دو ترکیب برای آزمایش مفید هستند. .sp برای موارد اضافی زبان خاص \fI\fP، خروجی گزینه \fB\-\-list\-extras=\fP را بررسی کنید. .TP .B \fB\-\-fields=[+|\-][|*]\fP مشخص می‌کند که کدام فیلدهای مستقل از زبان باید در مدخل‌های برچسب گنجانده شوند. فیلدهای مستقل از زبان فیلدهای الحاقی هستند که در همه زبان‌ها مشترک‌اند. برای جزئیات فیلدهای الحاقی، به بخش \(dqقالب پرونده برچسب (TAG FILE FORMAT)\(dq و زیربخش \(dqفیلدهای الحاقی (Extension fields)\(dq مراجعه کنید. .sp پارامتر \fI\fP مجموعه‌ای از پرچم‌های تک‌حرفی یا نام‌های طولانی است که هر یک نمایانگر نوعی از فیلد الحاقی برای گنجاندن هستند. هر پرچم یا گروهی از پرچم‌ها ممکن است با \(aq\fB+\fP\(aq برای افزودن به مجموعه پیش‌فرض، یا \(aq\fB\-\fP\(aq برای مستثنی کردن از آن، پیشوندگذاری شود. در صورت عدم وجود هرگونه علامت \(aq\fB+\fP\(aq یا \(aq\fB\-\fP\(aq در پیشوند، تنها فیلدهایی که صریحاً در flags فهرست شده‌اند در خروجی گنجانده خواهند شد (یعنی بازنویسی مجموعه پیش‌فرض). اگر \(aq\fB*\fP\(aq داده شود، همه فیلدها گنجانده می‌شوند. .sp در صورتی که گزینه \fB\-\-format=1\fP (قالب قدیمی پرونده برچسب) مشخص شده باشد، این گزینه نادیده گرفته می‌شود. .sp برای کنترل فیلدهای ویژه‌زبان از گزینه \fB\-\-fields\-=\fP استفاده کنید. .TP .B \fB\-\-fields\-(|all)=[+|\-][|*]\fP مشخص می‌کند که کدام فیلدهای ویژه‌زبان باید در مدخل‌های برچسب گنجانده شوند. ابزار Universal Ctags از فیلدهای ویژه‌زبان پشتیبانی می‌کند. (برای این مفهوم به \(dqفیلدها و موارد اضافی ویژه‌زبان (Language\-specific fields and extras)\(dq مراجعه کنید). .sp مقدار \fBall\fP را به عنوان \fI\fP مشخص کنید تا پارامتر \fI\fP به همه زبان‌ها اعمال شود؛ با مشخص کردن \(aq\fB*\fP\(aq به عنوان پرچم‌های پارامتر، همه فیلدها فعال می‌شوند. اگر هیچ چیز به عنوان پارامتر \fI\fP مشخص نشود (یعنی \fB\-\-fields\-all=\fP)، همه فیلدها غیرفعال می‌شوند. این دو ترکیب برای آزمایش مفید هستند. .sp درباره \fI\fP به توضیحات \fB\-\-fields=[+|\-][|*]\fP مراجعه کنید. .sp برای کنترل فیلدهای مستقل از زبان از گزینه \fB\-\-fields=\fP استفاده کنید. .TP .B \fB\-\-kinds\-(|all)=[+|\-](|*)\fP فهرستی از گونه‌های (\fI\fP) برچسب‌های ویژه‌زبان (یا گونه‌ها) را برای گنجاندن در پرونده خروجی برای یک زبان خاص مشخص می‌کند، که در آن \fI\fP به حروف کوچک و بزرگ حساس نیست و یکی از نام‌های داخلی زبان‌هاست (برای فهرست کامل گزینه \fB\-\-list\-languages\fP را ببینید). .sp پارامتر \fI\fP گروهی از پرچم‌های تک‌حرفی یا نام‌های طولانی است که گونه‌های برچسب‌ها را (مختص به آن زبان) برای گنجاندن یا حذف از خروجی تعیین می‌کند. مجموعه‌های خاصی از پرچم‌های شناخته‌شده برای هر زبان، معانی و مقادیر پیش‌فرض آن‌ها می‌تواند با استفاده از گزینه \fB\-\-list\-kinds\-full\fP فهرست شود. .sp هر حرف یا گروهی از حروف می‌تواند با \(aq\fB+\fP\(aq برای افزودن به، یا \(aq\fB\-\fP\(aq برای حذف از مجموعه پیش‌فرض، پیشوندگذاری شود. در صورت عدم وجود هرگونه علامت \(aq\fB+\fP\(aq یا \(aq\fB\-\fP\(aq در پیشوند، تنها آن گونه‌هایی که صریحاً در kinds فهرست شده‌اند در خروجی گنجانده خواهند شد (یعنی بازنویسی پیش‌فرض برای زبان مشخص‌شده). .sp برای گنجاندن همه گونه‌های پیاده‌سازی‌شده در \fI\fP در خروجی، \(aq\fB*\fP\(aq را به عنوان پارامتر مشخص کنید. همچنین اگر \fBall\fP به عنوان \fI\fP داده شود، مشخص کردن پارامتر \fBkinds\fP بر همه زبان‌های تعریف‌شده در ctags تأثیر می‌گذارد. دادن \fBall\fP تنها زمانی معنا دارد که \(aq\fB*\fP\(aq یا \(aq\fBF\fP\(aq به عنوان پارامتر \fBkinds\fP داده شود\&. .sp به عنوان نمونه برای زبان C، به منظور افزودن پیش‌نمونه‌ها (prototypes) و اعلان متغیرهای خارجی به مجموعه پیش‌فرض گونه‌های برچسب، اما مستثنی کردن ماکروها، از \fB\-\-kinds\-c=+px\-d\fP استفاده کنید؛ برای گنجاندن تنها برچسب‌های مربوط به توابع، از \fB\-\-kinds\-c=f\fP استفاده کنید\&. .sp برخی از گونه‌های زبان‌های C و C++ همگام‌سازی شده‌اند؛ فعال‌سازی (یا غیرفعال‌سازی) یک گونه در یک زبان، گونه‌ای را که دارای همان تک‌حرف و نام طولانی در زبان دیگر است فعال می‌کند. همچنین به توضیحات ستون \fBMASTER\fP در \fB\-\-list\-kinds\-full\fP مراجعه کنید\&. .UNINDENT .\" COMMENT: .\" ``--param-.name=argument`` is moved to "Language Specific Options" . .INDENT 0.0 .TP .B \fB\-\-pattern\-length\-limit=\fP الگوهای مدخل‌های برچسب را پس از \fI\fP نویسه کوتاه می‌کند. با تنظیم روی 0 غیرفعال می‌شود (پیش‌فرض 96 است). .sp یک پرونده منبع ورودی با خطوط طولانی و چندین تطابق برچسب در هر خط می‌تواند در صورت نامحدود بودن طول الگو، پرونده برچسب‌های بیش از حد بزرگی تولید کند. برای نمونه، اجرای ctags روی یک پرونده منبع فشرده‌شده (minified) جاوااسکریپت معمولاً چنین رفتاری را نشان می‌دهد. .sp کوتاه‌سازی به منظور جلوگیری از نوشتن توالی بایت‌های نامعتبر از پرونده‌های ورودی معتبر، از بریدن در میانه یک نقطه کد UTF\-8 چندبایتی خودداری می‌کند. این سازوکار در بدترین حالت که یک نقطه کد ۴ بایتی درست پیش از حد نصاب آغاز می‌شود، اجازه تا ۳ بایت اضافه فراتر از حد تنظیم‌شده را می‌دهد. لطفاً توجه داشته باشید که این سازوکار نسبتاً ساده و سریع است، و اگرچه در برابر هر ورودی مقاومت دارد، اما برای عملکرد درست نیازمند یک ورودی معتبر است؛ تضمین نمی‌شود هنگام کار با ورودی UTF\-8 با بخش‌های نامعتبر طبق انتظار کاربر عمل کند. این موضوع همچنین ورودی‌های غیر UTF\-8 را نیز تا حدی تحت تأثیر قرار می‌دهد، در صورتی که توالی بایت در طول محل کوتاه‌سازی شبیه یک توالی چندبایتی UTF\-8 باشد. با این حال این حالت باید نادر باشد، و در بدترین وضعیت منجر به گنجاندن تا ۳ بایت اضافی بیش از حد نصاب خواهد شد. .TP .B \fB\-\-pseudo\-tags=[+|\-](|*)\fP تولید شبه‌برچسبی با نام \fI\fP را فعال/غیرفعال می‌کند\&. اگر \(aq\fB*\fP\(aq داده شود، تولید همه شبه‌برچسب‌ها را فعال/غیرفعال می‌کند. .TP .B \fB\-\-put\-field\-prefix\fP عبارت \fBUCTAGS\fP را به عنوان پیشوند برای نام فیلدهایی که به تازگی در Universal Ctags معرفی شده‌اند قرار می‌دهد. .sp برخی فیلدها به تازگی در Universal Ctags معرفی شده‌اند و در آینده موارد بیشتری معرفی خواهند شد. سایر تولیدکنندگان برچسب نیز ممکن است فیلدهای اختصاصی خود را معرفی کنند. .sp در چنین شرایطی، نگرانی درباره تداخل نام‌های فیلد وجود دارد؛ ترکیب پرونده‌های برچسب تولیدشده توسط چندین تولیدکننده برچسب از جمله Universal Ctags دشوار است. این گزینه راهکاری برای چنین وضعیتی فراهم می‌کند. .INDENT 7.0 .INDENT 3.5 .sp .EX $ ctags \-\-fields=\(aq{line}{end}\(aq \-o \- hello.c main hello.c /^main(int argc, char **argv)$/;\(dq f line:3 end:6 $ ctags \-\-put\-field\-prefix \-\-fields=\(aq{line}{end}\(aq \-o \- hello.c main hello.c /^main(int argc, char **argv)$/;\(dq f line:3 UCTAGSend:6 .EE .UNINDENT .UNINDENT .sp در مثال بالا، پیشوند به فیلد \fBend\fP که به تازگی در Universal Ctags معرفی شده، اضافه شده است. .TP .B \fB\-\-roles\-(|all).(|*)=[+|\-][|*]\fP فهرستی از نقش‌های وابسته به گونهٔ برچسب‌ها را برای گنجاندن در پرونده خروجی برای زبانی خاص مشخص می‌کند. \fI\fP گونه‌ای را مشخص می‌کند که \fI\fP در آن تعریف شده‌اند. \fI\fP زبانی را مشخص می‌کند که گونه در آن تعریف شده است. هر نقش در \fI\fP باید درون آکولاد محصور شود (برای نمونه \fB{system}\fP برای نقشی به نام \(dqsystem\(dq). .sp همانند گزینه \fB\-\-kinds\-\fP، نویسه \(aq\fB+\fP\(aq برای افزودن نقش به فهرست، و \(aq\fB\-\fP\(aq برای حذف از فهرست است. \(aq\fB*\fP\(aq برای گنجاندن تمام نقش‌های آن گونه در فهرست است. گزینه بدون آرگومان فهرست را خالی می‌کند. .sp هم پرچم تک‌نویسه‌ای و هم پرچم نام کامل محصور در آکولاد برای مشخص کردن یک گونه قابل قبول هستند (مانند \fB\-\-roles\-C.h=+{system}{local}\fP یا \fB\-\-roles\-C.{header}=+{system}{local}\fP). از \(aq\fB*\fP\(aq می‌توان برای \fI\fP تنها به منظور افزودن/حذف تمام نقش‌های همه گونه‌ها در یک زبان به/از فهرست استفاده کرد (مانند \fB\-\-roles\-C.*=*\fP یا \fB\-\-roles\-C.*=\fP). .sp از \fBall\fP می‌توان برای \fI\fP تنها جهت افزودن/حذف تمام نقش‌های همه گونه‌ها در تمام زبان‌ها به/از فهرست استفاده کرد (مانند \fB\-\-roles\-all.*=*\fP یا \fB\-\-roles\-all.*=\fP). .TP .B \fB\-\-tag\-relative=(yes|no|always|never)\fP نحوه ثبت مسیرهای پرونده را در پرونده برچسب مشخص می‌کند. مقدار پیش‌فرض هنگام اجرا در حالت etags (گزینه \fB\-e\fP را ببینید) برابر \fByes\fP، و در غیر این صورت \fBno\fP است. .INDENT 7.0 .TP .B \fByes\fP مشخص می‌کند مسیرهای پرونده ثبت‌شده در پرونده برچسب باید \fIنسبت به پوشه حاوی پرونده برچسب\fP باشند، مگر اینکه پرونده‌های ارائه‌شده در خط فرمان با مسیرهای مطلق مشخص شده باشند. .TP .B \fBno\fP مشخص می‌کند مسیرهای پرونده ثبت‌شده در پرونده برچسب باید \fIنسبت به پوشه جاری\fP باشند، مگر اینکه پرونده‌های ارائه‌شده در خط فرمان با مسیرهای مطلق مشخص شده باشند. .TP .B \fBalways\fP مشخص می‌کند مسیرهای پرونده ثبت‌شده باید نسبی باشند، حتی اگر نام پرونده‌های منبع با مسیرهای مطلق داده شده باشند. .TP .B \fBnever\fP مشخص می‌کند مسیرهای پرونده ثبت‌شده باید مطلق باشند، حتی اگر نام پرونده‌های منبع با مسیرهای نسبی داده شده باشند. .UNINDENT .TP .B \fB\-\-use\-slash\-as\-filename\-separator[=(yes|no)]\fP هنگام چاپ فیلد \fBinput:\fP از نویسه اسلش (\(aq\fB/\fP\(aq) به جای نویسه بک‌اسلش (\(aq\fB\e\fP\(aq) به عنوان جداکننده نام پرونده استفاده می‌کند. مقدار پیش‌فرض برای قالب خروجی پیش‌فرض \(dqu\-ctags\(dq برابر \fByes\fP، و برای سایر قالب‌ها \fBno\fP است. .sp شبه‌برچسب \fBTAG_OUTPUT_FILESEP\fP برای نشان دادن انتخاب جداکننده نام پرونده با این گزینه است. همچنین ctags\-client\-tools(7) را ببینید. .sp این گزینه تنها روی MS Windows در دسترس است. .TP .B \fB\-B\fP استفاده از الگوهای جستجو به سمت عقب (مانند \fB?pattern?\fP). [در حالت etags نادیده گرفته می‌شود] .TP .B \fB\-F\fP استفاده از الگوهای جستجو به سمت جلو (مانند \fB/pattern/\fP) (پیش‌فرض). [در حالت etags نادیده گرفته می‌شود] .UNINDENT .SS "گزینه‌های پرونده تنظیمات (Option File Options)" .\" TODO: merge some of description in option-file.rst into FILE or a dedicated .\" section . .INDENT 0.0 .TP .B \fB\-\-options=\fP خواندن گزینه‌های اضافی از یک پرونده یا پوشه. .sp ctags ابتدا \fI\fP را در فهرست مسیرهای optlib جستجو می‌کند. اگر ctags نتواند پرونده یا پوشه‌ای را در فهرست بیابد، پرونده یا پوشه را در \fI\fP مشخص‌شده می‌خواند\&. .sp اگر پرونده‌ای مشخص شود، باید شامل یک گزینه در هر خط باشد. اگر پوشه‌ای مشخص شود، پرونده‌های دارای پسوند \fB\&.ctags\fP در آن پوشه به ترتیب الفبایی خوانده می‌شوند. .sp به عنوان یک حالت ویژه، اگر \fB\-\-options=NONE\fP به عنوان نخستین گزینه در خط فرمان مشخص شود، پیش‌بارگذاری غیرفعال می‌شود؛ این گزینه خواندن خودکار هرگونه گزینه پیکربندی از یک پرونده را غیرفعال خواهد کرد (\(dqFILES\(dq را ببینید). .TP .B \fB\-\-options\-maybe=\fP مشابه \fB\-\-options\fP است اما در صورت عدم وجود پرونده (یا پوشه) مشخص‌شده با \fI\fP، خطایی ایجاد نمی‌کند. .TP .B \fB\-\-optlib\-dir=[+]\fP افزودن یک \fI\fP مربوط به optlib به فهرست مسیرهای optlib یا بازنشانی آن. برای عناصر پیش‌فرض در فهرست مسیرهای optlib به \(dqDefault optlib path list\(dq مراجعه کنید. .UNINDENT .SS "گزینه‌های optlib (optlib Options)" .sp برای جزئیات هر گزینه به ctags\-optlib(7) مراجعه کنید\&. .INDENT 0.0 .TP .B \fB\-\-kinddef\-=,,\fP تعریف یک نوع (kind) برای \fI\fP\&. این گزینه را با \fB\-\-kinds\-\fP اشتباه نگیرید\&. .TP .B \fB\-\-langdef=\fP یک زبان جدید تعریف‌شده توسط کاربر به نام \fI\fP را تعریف می‌کند تا با عبارت‌های منظم تجزیه شود\&. .TP .B \fB\-\-mline\-regex\-=////[]\fP تعریف عبارت منظم چندخطی برای یافتن برچسب‌ها در زبانی مشخص\&. .TP .B \fB\-\-regex\-=////[]\fP تعریف عبارت منظم تک‌خطی برای یافتن برچسب‌ها در زبانی مشخص\&. .UNINDENT .SS "گزینه‌های ویژه زبان (Language Specific Options)" .INDENT 0.0 .TP .B \fB\-\-if0[=(yes|no)]\fP ترجیحی را مشخص می‌کند مبنی بر اینکه آیا کدهای درون یک شاخه \(dq\fB#if 0\fP\(dq از شرط پیش‌پردازنده برای برچسب‌های غیرماکرو بررسی شوند یا خیر (برچسب‌های ماکرو همواره لحاظ می‌شوند)\&. از آنجا که هدف از این ساختار غیرفعال کردن کد است، مقدار پیش‌فرض این گزینه \fBno\fP (غیرفعال) است\&. .sp توجه داشته باشید که این گزینه صرفاً یک ترجیح را نشان می‌دهد و نادیده گرفتن کدهای درون یک شاخه \(dq\fB#if 0\fP\(dq را تضمین نمی‌کند، چرا که الگوریتم جایگزین (fall\-back) که هنگام پیچیده بودن شروط پیش‌پردازنده برای تولید برچسب‌ها به کار می‌رود، تمام شاخه‌های یک شرط را دنبال می‌کند\&. .TP .B \fB\-\-line\-directives[=(yes|no)]\fP مشخص می‌کند که آیا دستورهای \fB#line\fP باید شناسایی شوند یا خیر\&. این دستورها در خروجی یک پیش‌پردازنده حضور دارند و حاوی شماره خط، و احتمالاً نام فایلِ فایل(های) منبع اصلی هستند که خروجی پیش‌پردازنده از آن‌ها تولید شده است\&. این گزینه به‌طور پیش‌فرض غیرفعال است\&. .sp در صورت فعال بودن، این گزینه باعث می‌شود ctags ورودی‌های برچسب را به جای مکان‌های واقعی آن‌ها در خروجی پیش‌پردازنده، با نام فایل‌ها و شماره خط‌های مکان آن‌ها در فایل(های) منبع اصلی نشانه‌گذاری و تولید کند\&. نام فایل‌های واقعی قرار گرفته در فایل برچسب، همان بخش‌های ابتدایی مسیر فایل خروجی پیش‌پردازنده را خواهند داشت، زیرا فرض می‌شود که فایل‌های منبع اصلی نسبت به فایل خروجی پیش‌پردازنده قرار دارند (مگر اینکه، البته، دستور \fB#line\fP یک مسیر مطلق را مشخص کرده باشد)\&. .sp نکته: این گزینه عموماً تنها زمانی مفید است که همراه با گزینه \fB\-\-excmd=number\fP (\fB\-n\fP) استفاده شود\&. همچنین اگر پسوند فایل خروجی پیش‌پردازنده برای ctags ناشناخته باشد، ممکن است لازم باشد از گزینه \fB\-\-langmap\fP یا \fB\-\-language\-force\fP استفاده کنید\&. .TP .B \fB\-D =\fP یک \fI\fP پیش‌پردازنده C را تعریف می‌کند\&. این گزینه رفتار گزینه متناظر در gcc را شبیه‌سازی می‌کند\&. همه انواع ماکروها، از جمله آن‌هایی که دارای پارامتر و آرگومان‌های متغیر هستند، پشتیبانی می‌شوند\&. تبدیل به رشته (stringification)، چسباندن توکن‌ها (token pasting) و بسط بازگشتی ماکرو نیز پشتیبانی می‌شوند\&. این گزینه عملکرد ارائه‌شده توسط گزینه \fB\-I\fP را گسترش می‌دهد\&. .TP .B \fB\-h (|default)\fP یک \fI\fP از پسوندهای فایل، جداشده با نقطه، را مشخص می‌کند که باید به عنوان فایل‌های include (یا سرآیند) تفسیر شوند\&. برای مشخص کردن فایل‌های فاقد پسوند، از نقطه‌ای استفاده کنید که به دنبال آن نویسه‌ای غیر از نقطه نیامده باشد (مانند \(aq\fB\&.\fP\(aq، \fB\&..x\fP، \fB\&.x.\fP)\&. .sp این گزینه صرفاً بر نحوه تفسیر حوزه دید (scoping) انواع خاصی از برچسب‌ها اثر می‌گذارد (یعنی اینکه آیا به عنوان برچسب سراسری دیده می‌شوند یا تنها درون فایلی که در آن تعریف شده‌اند قابل مشاهده هستند)؛ این گزینه پسوند را به هیچ زبان خاصی نگاشت نمی‌کند\&. هر برچسبی که در فایلی غیر از فایل‌های include قرار داشته باشد و نتوان آن را از فایلی دیگر مشاهده کرد (مانند پیوند داده شدن به آن)، دارای حوزه دید محدود به فایل (مانند static) در نظر گرفته می‌شود\&. هیچ نوع برچسبی که در یک فایل include ظاهر شود، دارای حوزه دید محدود به فایل در نظر گرفته نخواهد شد\&. .sp اگر اولین نویسه در فهرست \(aq\fB+\fP\(aq باشد، پسوندهای موجود در فهرست به فهرست کنونی اضافه خواهند شد؛ در غیر این صورت، این فهرست جایگزین فهرست کنونی می‌شود\&. همچنین پرچم \fBfileScope\fP/\fBF\fP از گزینه \fB\-\-extras\fP را ببینید\&. .sp فهرست پیش‌فرض \fB\&.h.H.hh.hpp.hxx.h++.inc.def\fP است\&. برای بازگردانی فهرست پیش‌فرض، \(dq\fB\-h default\fP\(dq را مشخص کنید\&. .sp توجه داشته باشید که اگر پسوندی که به این گزینه داده می‌شود قبلاً به زبانی خاص نگاشت نشده باشد (به بخش \(dqDetermining file language\(dq در بالا مراجعه کنید)، باید از گزینه \fB\-\-map\-\fP، \fB\-\-langmap\fP یا \fB\-\-language\-force\fP نیز استفاده کنید\&. .TP .B \fB\-I \fP یک \fI\fP از شناسه‌هایی را مشخص می‌کند که هنگام تجزیه فایل‌های منبع C و C++ باید به‌طور ویژه پردازش شوند\&. این گزینه به‌طور خاص برای رسیدگی به موارد ویژه‌ای که ناشی از استفاده از ماکروهای پیش‌پردازنده هستند در نظر گرفته شده است\&. هنگامی که شناسه‌های فهرست‌شده شناسه‌های ساده باشند، در طول تجزیه فایل‌های منبع نادیده گرفته می‌شوند\&. .sp اگر شناسه با یک نویسه \(aq\fB+\fP\(aq پسوندگذاری شود (مانند \(dq\fB\-I FOO+\fP\(dq)، ابزار ctags همچنین هر فهرست آرگومانی محصور در پرانتز را که بلافاصله پس از شناسه در فایل‌های منبع آمده باشد نادیده خواهد گرفت\&. به مثال \(dq\fB\-I MODULE_VERSION+\fP\(dq در زیر مراجعه کنید\&. .sp اگر دو شناسه با نویسه \(aq\fB=\fP\(aq از هم جدا شده باشند (مانند \fB\-I FOO=BAR\fP)، شناسه اول برای اهداف تجزیه با شناسه دوم جایگزین می‌شود\&. فهرست شناسه‌ها می‌تواند مستقیماً در خط فرمان داده شود یا از یک فایل جداگانه خوانده شود\&. به مثال \(dq\fB\-I CLASS=class\fP\(dq در زیر مراجعه کنید\&. .sp اگر اولین نویسه \fI\fP برابر \(aq\fB@\fP\(aq، \(aq\fB\&.\fP\(aq یا یک جداکننده مسیر (\(aq\fB/\fP\(aq یا \(aq\fB\e\fP\(aq) باشد، یا دو نویسه اول نام یک درایو را مشخص کنند (مانند \fBC:\fP)، پارامتر \fI\fP به عنوان نام فایلی تفسیر خواهد شد که فهرستی از شناسه‌ها، هر کدام در یک سطر ورودی، از آن خوانده می‌شود\&. .sp در غیر این صورت، \fI\fP فهرستی از شناسه‌ها (یا جفت‌های شناسه) برای رسیدگی ویژه است که هر کدام با کاما یا فاصله خالی جدا شده‌اند (در این حالت برای نگه داشتن کل فهرست به عنوان یک آرگومان خط فرمان، فهرست باید درون نقل‌قول قرار گیرد)\&. .sp می‌توان چندین گزینه \fB\-I\fP را مشخص کرد\&. برای پاک کردن فهرست شناسه‌های نادیده‌گرفته‌شده، یک خط تیره منفرد (\(aq\fB\-\fP\(aq) برای \fI\fP بدهید\&. .sp این قابلیت زمانی مفید است که ماکروهای پیش‌پردازنده به گونه‌ای استفاده شوند که حضور آن‌ها باعث سردرگمی نحوی شود\&. در واقع، این بهترین روش برای دور زدن تعدادی از مشکلاتی است که به دلیل حضور ماکروهای برهم‌زننده نحو در فایل‌های منبع ایجاد می‌شوند (به \(dqCAVEATS\(dq مراجعه کنید)\&. چند مثال این موضوع را روشن خواهد کرد\&. .INDENT 7.0 .INDENT 3.5 .sp .EX int foo ARGDECL4(void *, ptr, long int, nbytes) .EE .UNINDENT .UNINDENT .sp در مثال بالا، ماکروی \fBARGDECL4\fP به اشتباه به جای نام درست تابع یعنی \fBfoo\fP، به عنوان نام تابع تفسیر می‌شود\&. مشخص کردن \(dq\fB\-I ARGDECL4\fP\(dq منجر به رفتار درست می‌شود\&. .INDENT 7.0 .INDENT 3.5 .sp .EX /* creates an RCS version string in module */ MODULE_VERSION(\(dq$Revision$\(dq) .EE .UNINDENT .UNINDENT .sp در مثال بالا فراخوانی ماکرو بسیار شبیه به یک تعریف تابع به نظر می‌رسد، زیرا نقطه‌ویرگول به دنبال آن نیامده است (در واقع، حتی می‌تواند پس از آن تعریف متغیر سراسری بیاید که بسیار شبیه به اعلان پارامتر تابع به سبک K&R باشد)\&. در حقیقت، این تعریف ظاهری تابع حتی ممکن است باعث نادیده گرفته شدن باقی فایل هنگام تلاش برای تکمیل تعریف شود\&. مشخص کردن \(dq\fB\-I MODULE_VERSION+\fP\(dq از چنین مشکلی جلوگیری می‌کند\&. .INDENT 7.0 .INDENT 3.5 .sp .EX CLASS Example { // your content here }; .EE .UNINDENT .UNINDENT .sp مثال بالا از \fBCLASS\fP به عنوان یک ماکروی پیش‌پردازنده استفاده می‌کند که برای هر پلتفرم به چیزی متفاوت بسط می‌یابد\&. به عنوان مثال، \fBCLASS\fP ممکن است در پلتفرم‌های Win32 به صورت \fBclass __declspec(dllexport)\fP و در UNIX صرفاً به صورت \fBclass\fP تعریف شود\&. در حالت عادی، عدم وجود کلیدواژه C++ یعنی \fBclass\fP باعث می‌شود فایل منبع به نادرستی تجزیه شود\&. رفتار درست را می‌توان با تعیین \(dq\fB\-I CLASS=class\fP\(dq بازیابی کرد\&. .TP .B \fB\-\-param\-.=\fP تنظیم یک پارامتر ویژه \fI\fP، پارامتری که مختص به \fI\fP است\&. .sp پارامترهای موجود را می‌توان با \fB\-\-list\-params\fP فهرست کرد\&. .UNINDENT .SS "گزینه‌های فهرست‌بندی (Listing Options)" .INDENT 0.0 .TP .B \fB\-\-list\-aliases[=(|all)]\fP نام‌های مستعار (aliases) را برای \fI\fP مشخص‌شده یا \fBall\fP (همه) زبان‌ها فهرست می‌کند و سپس خارج می‌شود. در صورت حذف آرگومان گزینه، \fBall\fP به عنوان مقدار پیش‌فرض استفاده می‌شود. نام‌های مستعار هنگام آزمایش اکتشافیِ یک تجزیه‌کننده زبان برای یک فایل منبع استفاده می‌شوند. .TP .B \fB\-\-list\-excludes\fP الگوهای استثناسازی فعلی مورد استفاده برای نادیده گرفتن فایل‌ها را فهرست می‌کند. .TP .B \fB\-\-list\-extras[=(|NONE|all)]\fP موارد اضافی (extras) شناسایی‌شده را برای \fI\fP مشخص‌شده یا \fBall\fP (همه) زبان‌ها فهرست می‌کند. اگر \fBNONE\fP مشخص شود، تنها موارد اضافی مشترک در تمام زبان‌ها را فهرست می‌کند. برای دانستن اینکه موارد اضافی چه هستند به زیربخش \(dqExtras\(dq مراجعه کنید. در صورت حذف آرگومان گزینه، \fBall\fP به عنوان مقدار پیش‌فرض استفاده می‌شود. .sp یک مورد اضافی می‌تواند با \fB\-\-extras=\fP برای موارد اضافی مشترک در تمام زبان‌ها، یا با \fB\-\-extras\-=\fP برای زبان مشخص‌شده فعال یا غیرفعال شود. این گزینه‌ها یک پرچم تک‌حرفی یا پرچم نام‌کامل را به عنوان پارامتر برای مشخص کردن یک مورد اضافی دریافت می‌کنند. .sp معنای ستون‌ها در خروجی به شرح زیر است: .INDENT 7.0 .TP .B LETTER پرچم تک‌حرفی. علامت \(aq\fB\-\fP\(aq به این معنی است که مورد اضافی پرچم تک‌حرفی ندارد. .TP .B NAME پرچم نام‌کامل (long-name). نام‌کامل در فیلد \fBextras\fP استفاده می‌شود. .TP .B ENABLED فعال بودن یا نبودن مورد اضافی. مقدار \fByes\fP یا \fBno\fP می‌گیرد. .TP .B LANGUAGE نام زبان، در صورتی که مورد اضافی متعلق به یک تجزیه‌کننده باشد. مقدار \fBNONE\fP یعنی مورد اضافی میان تجزیه‌کننده‌ها مشترک است. .TP .B DESCRIPTION توضیحات خوانا برای انسان درباره مورد اضافی. .UNINDENT .TP .B \fB\-\-list\-features\fP ویژگی‌های کامپایل‌شده را فهرست می‌کند. .TP .B \fB\-\-list\-fields[=(|NONE|all)]\fP فیلدهای شناخته‌شده را برای \fI\fP مشخص‌شده یا \fBall\fP (همه) زبان‌ها فهرست می‌کند. اگر \fBNONE\fP مشخص شود، تنها فیلدهای مشترک در تمام زبان‌ها را فهرست می‌کند. برای دانستن اینکه فیلدها چه هستند به زیربخش \(dqExtension fields\(dq مراجعه کنید. در صورت حذف آرگومان گزینه، \fBall\fP به عنوان مقدار پیش‌فرض استفاده می‌شود. .sp معنای ستون‌ها به شرح زیر است: .INDENT 7.0 .TP .B LETTER پرچم تک‌حرفی. علامت \(aq\fB\-\fP\(aq به این معنی است که فیلد پرچم تک‌حرفی ندارد. .TP .B NAME نام‌کامل فیلد. .TP .B ENABLED فعال بودن یا نبودن فیلد. مقدار \fByes\fP یا \fBno\fP می‌گیرد. .TP .B LANGUAGE نام زبان، در صورتی که فیلد متعلق به یک تجزیه‌کننده باشد. مقدار \fBNONE\fP به این معنی است که فیلد مستقل از زبان بوده و میان تمام زبان‌ها مشترک است. .TP .B JSTYPE نوع JSON که هنگام مشخص شدن \fB\-\-output\-format=json\fP برای چاپ مقدار فیلد استفاده می‌شود. به ctags\-client\-tools(7) مراجعه کنید. .TP .B FIXED آیا این فیلد در خروجی tags قابل غیرفعال‌سازی است یا خیر. .sp برخی فیلدها همیشه در خروجی tags چاپ می‌شوند. مقدار این ستون برای آن‌ها \fByes\fP است. .sp برخلاف حالت خروجی tag، حالت خروجی JSON اجازه غیرفعال کردن هر فیلدی را می‌دهد. .TP .B OP نحوه دسترسی به این فیلد از طریق کد optscript. این فیلد برای توسعه‌دهندگان Universal Ctags است. .TP .B DESCRIPTION توضیحات خوانا برای انسان درباره فیلد. .UNINDENT .TP .B \fB\-\-list\-kinds[=(|all)]\fP زیرمجموعه‌ای از \fB\-\-list\-kinds\-full\fP است. این گزینه برای سازگاری عقب‌رو با Exuberant Ctags حفظ شده است. .sp این گزینه تنها فیلدهای LETTER و DESCRIPTION و ENABLED از خروجی \fB\-\-list\-kinds\-full\fP را چاپ می‌کند. با این حال، نحوه نمایش ستون ENABLED با گزینه \fB\-\-list\-kinds\-full\fP متفاوت است؛ در صورتی که گونه (kind) غیرفعال باشد \fB[off]\fP پس از توضیحات می‌آید، و در صورت فعال بودن چیزی درج نمی‌شود. بیشتر گونه‌ها به طور پیش‌فرض فعال هستند. .sp نقطه ضعف اساسی این گزینه عدم چاپ نام گونه است. Universal Ctags گزینه \fB\-\-list\-kinds\-full\fP را معرفی کرد زیرا نام‌ها را مهم می‌داند. .sp این گزینه با \fB\-\-machinable\fP یا \fB\-\-with\-list\-header\fP کار نمی‌کند. .TP .B \fB\-\-list\-kinds\-full[=(|all)]\fP گونه‌های برچسب (tag kinds) شناخته‌شده را برای \fI\fP مشخص‌شده یا \fBall\fP (همه) زبان‌ها فهرست کرده و سپس خارج می‌شود. برای یادگیری مفهوم گونه‌ها به زیربخش \(dqKinds\(dq مراجعه کنید. در صورت حذف آرگومان گزینه، \fBall\fP به عنوان مقدار پیش‌فرض استفاده می‌شود. .sp هر گونه از برچسب ثبت‌شده در فایل برچسب، با یک پرچم تک‌حرفی یا پرچم نام‌کامل نشان داده می‌شود. آن‌ها همچنین برای فیلتر کردن برچسب‌های قرارگرفته در خروجی با استفاده از گزینه \fB\-\-kinds\-\fP به کار می‌روند. .sp معنای ستون‌ها به شرح زیر است: .INDENT 7.0 .TP .B LANGUAGE نام زبانی که گونه را دارد. .TP .B LETTER پرچم تک‌حرفی. این مقدار در هر زبان باید یکتا باشد. .TP .B NAME پرچم نام‌کامل گونه. می‌تواند به عنوان جایگزینی برای پرچم تک‌حرفیِ ذکرشده در بالا استفاده شود. در صورت فعال کردن فیلد \fBK\fP با \fB\-\-fields=+K\fP، ابزار ctags در خروجی برچسب‌ها به جای تک‌حرف‌ها از نام‌های کامل استفاده می‌کند. برای فعال/غیرفعال کردن یک گونه با گزینه \fB\-\-kinds\-\fP، به جای تک‌حرف از نام‌کامل احاطه‌شده با آکولاد استفاده می‌شود. برای جزئیات به \(dqLetters and names\(dq مراجعه کنید. این مقدار در هر زبان باید یکتا باشد. .TP .B ENABLED فعال بودن یا نبودن گونه. مقدار \fByes\fP یا \fBno\fP می‌گیرد. .TP .B REFONLY آیا گونه منحصراً برای برچسب‌گذاری ارجاعی است یا خیر. اگر ستون \fByes\fP باشد، گونه برای برچسب‌گذاری ارجاعی است و هرگز برای برچسب‌گذاری تعاریف استفاده نمی‌شود. همچنین به \(dqTAG ENTRIES\(dq مراجعه کنید. .TP .B NROLES تعداد نقش‌هایی که این گونه دارد. همچنین به \(dqRoles\(dq مراجعه کنید. .TP .B MASTER تجزیه‌کننده اصلی (master parser) که فعال‌سازی گونه را کنترل می‌کند. در Universal Ctags یک گونه متعلق به یک زبان (مالک) است؛ فعال یا غیرفعال کردن یک گونه در یک زبان هیچ اثری بر گونه در زبانی دیگر ندارد، حتی اگر هر دو گونه پرچم تک‌حرفی و/یا نام‌کامل یکسانی داشته باشند. به بیان دیگر، فضای نام گونه‌ها بر اساس زبان تفکیک شده است. .sp با این حال، Exuberant Ctags گونه‌های C و ++C را تفکیک نمی‌کند. فعال/غیرفعال کردن kindX در زبان C سبب فعال/غیرفعال شدن گونه‌ای در زبان ++C با همان پرچم نام‌کامل می‌شود. برای شبیه‌سازی این رفتار در Universal Ctags، مفهومی به نام \fImaster parser\fP معرفی شده است. فعال/غیرفعال‌سازی برخی گونه‌ها تحت کنترل زبان اصلی هماهنگ‌سازی می‌شود. .INDENT 7.0 .INDENT 3.5 .sp .EX $ ctags \-\-kinds\-C=+\(aq{local}\(aq \-\-list\-kinds\-full \e | grep \-E \(aq^(#|C\e+\e+ .* local)\(aq #LANGUAGE LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION C++ l local yes no 0 C local variables $ ctags \-\-kinds\-C=\-\(aq{local}\(aq \-\-list\-kinds\-full \e | grep \-E \(aq^(#|C\e+\e+ .* local)\(aq #LANGUAGE LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION C++ l local no no 0 C local variables .EE .UNINDENT .UNINDENT .sp مشاهده می‌کنید که فیلد \fBENABLED\fP برای گونه \fBlocal\fP در زبان ++C تغییر می‌کند گرچه گونه \fBlocal\fP در زبان C فعال/غیرفعال شده است. در صورت جابه‌جا کردن زبان‌ها نیز نتیجه یکسان خواهد بود. .\" TODO: need a reference to "master parser" . .TP .B DESCRIPTION توضیحات خوانا برای انسان درباره گونه. .UNINDENT .TP .B \fB\-\-list\-languages\fP نام زبان‌های قابل فهم برای ctags را فهرست کرده و سپس خارج می‌شود. این نام‌های زبان به بزرگی و کوچکی حروف حساس نیستند و می‌توانند در گزینه‌های متعدد دیگری مانند \fB\-\-language\-force\fP، \fB\-\-languages\fP، \fB\-\-kinds\-\fP، \fB\-\-regex\-\fP و غیره استفاده شوند. .sp هر زبان فهرست‌شده در صورتی که عبارت \fB[disabled]\fP به دنبال آن بیاید غیرفعال است. برای استفاده از تجزیه‌کننده برای چنین زبانی، زبان را به عنوان آرگومانی برای گزینه \fB\-\-languages=+\fP مشخص کنید. .sp گزینه‌های \fB\-\-machinable\fP و \fB\-\-with\-list\-header\fP در صورت تعیین همراه با این گزینه نادیده گرفته می‌شوند. .TP .B \fB\-\-list\-map\-extensions[=(|all)]\fP پسوندهای فایلی را که نام یک فایل را به یک زبان مرتبط می‌کنند، برای \fI\fP مشخص‌شده یا \fBall\fP (همه) زبان‌ها فهرست کرده و سپس خارج می‌شود\&. در صورت حذف آرگومان گزینه، \fBall\fP به عنوان مقدار پیش‌فرض استفاده می‌شود\&. .TP .B \fB\-\-list\-map\-patterns[=(|all)]\fP الگوهای نام فایلی را که نام یک فایل را به یک زبان مرتبط می‌کنند، برای \fI\fP مشخص‌شده یا \fBall\fP (همه) زبان‌ها فهرست کرده و سپس خارج می‌شود\&. در صورت حذف آرگومان گزینه، \fBall\fP به عنوان مقدار پیش‌فرض استفاده می‌شود\&. .TP .B \fB\-\-list\-maps[=(|all)]\fP الگوهای نام فایل و پسوندهای فایلی را که نام یک فایل را به یک زبان مرتبط می‌کنند، برای \fI\fP مشخص‌شده یا \fBall\fP (همه) زبان‌ها فهرست کرده و سپس خارج می‌شود\&. در صورت حذف آرگومان گزینه، \fBall\fP به عنوان مقدار پیش‌فرض استفاده می‌شود\&. .sp برای فهرست کردن پسوندهای فایل یا الگوهای نام فایل به‌صورت جداگانه، از گزینه \fB\-\-list\-map\-extensions\fP یا \fB\-\-list\-map\-patterns\fP استفاده کنید\&. گزینه \fB\-\-langmap\fP و بخش \(dqDetermining file language\(dq (تعیین زبان فایل) در بالا را ببینید\&. .sp این گزینه نه با \fB\-\-machinable\fP و نه با \fB\-\-with\-list\-header\fP کار نمی‌کند\&. .TP .B \fB\-\-list\-mline\-regex\-flags\fP فهرستی از پرچم‌هایی را که می‌توان در تعریف یک تجزیه‌کننده عبارات باقاعده چندخطی استفاده کرد، خروجی می‌دهد\&. سند ctags\-optlib(7) را ببینید\&. .TP .B \fB\-\-list\-output\-formats\fP قالب‌های خروجی قابل استفاده در گزینه \fB\-\-output\-format\fP را فهرست می‌کند\&. .sp ستون \fBNULLTAG\fP نشان می‌دهد که آیا قالب از \fInull tags\fP (برچسب‌های پوچ) پشتیبانی می‌کند یا خیر\&. درباره برچسب‌های پوچ، \fBnulltag\fP/\fBz\fP در بخش \(dqExtras\(dq را ببینید\&. .sp (از نسخه 6.2.0 به بعد) .TP .B \fB\-\-list\-params[=(|all)]\fP پارامترها را برای \fI\fP مشخص‌شده یا \fBall\fP (همه) زبان‌ها فهرست کرده و سپس خارج می‌شود\&. در صورت حذف آرگومان گزینه، \fBall\fP به عنوان مقدار پیش‌فرض استفاده می‌شود\&. .TP .B \fB\-\-list\-pseudo\-tags\fP فهرست شبه‌برچسب‌ها را خروجی می‌دهد\&. .TP .B \fB\-\-list\-regex\-flags\fP پرچم‌هایی را که می‌توان در گزینه \fB\-\-regex\-\fP به کار برد فهرست می‌کند\&. سند ctags\-optlib(7) را ببینید\&. .TP .B \fB\-\-list\-roles[=(|all)[.(|*)]]\fP نقش‌ها را برای \fI\fP مشخص‌شده یا \fBall\fP (همه) زبان‌ها فهرست می‌کند\&. در صورت حذف آرگومان گزینه، \fBall\fP به عنوان مقدار پیش‌فرض استفاده می‌شود\&. .sp اگر پارامتر \fI\fP پس از پارامتر \fI\fP یا \fBall\fP همراه با الحاق \(aq\fB\&.\fP\(aq داده شود، تنها نقش‌های تعریف‌شده در آن انواع (kinds) را فهرست می‌کند\&. هر دو مورد پرچم‌های تک‌حرفی و پرچم‌های نام‌طولانی احاطه‌شده با آکولاد به عنوان پارامتر \fI\fP پذیرفته می‌شوند\&. .sp معنی ستون‌ها به شرح زیر است: .INDENT 7.0 .TP .B LANGUAGE نام زبانی که نقش را دربردارد\&. .TP .B KIND(L/N) پرچم تک‌حرفی و پرچم نام‌طولانی نوعی که این نقش را دارد\&. .TP .B NAME پرچم نام‌طولانی نقش\&. .TP .B ENABLED اینکه نوع فعال است یا خیر\&. مقادیر \fByes\fP یا \fBno\fP می‌پذیرد\&. .TP .B DESCRIPTION توضیحات خوانا برای انسان برای نقش\&. .UNINDENT .TP .B \fB\-\-list\-subparsers[=(|all)]\fP زیرتجزیه‌کننده‌ها را برای یک زبان پایه برای \fI\fP مشخص‌شده یا \fBall\fP (همه) زبان‌ها فهرست کرده و سپس خارج می‌شود\&. در صورت حذف آرگومان گزینه، \fBall\fP به عنوان مقدار پیش‌فرض استفاده می‌شود\&. .TP .B \fB\-\-machinable[=(yes|no)]\fP از نویسه تب به عنوان جداکننده برای خروجی گزینه \fB\-\-list\-\fP استفاده می‌کند\&. این ممکن است برای اسکریپت‌نویسی مناسب باشد\&. برای موارد کاربرد در نظر گرفته‌شده، بخش \(dqList options\(dq را ببینید\&. به‌طور پیش‌فرض غیرفعال است\&. .TP .B \fB\-\-with\-list\-header[=(yes|no)]\fP سرآیندهای توصیف‌کننده ستون‌ها را در خروجی گزینه \fB\-\-list\-\fP چاپ می‌کند\&. همچنین بخش \(dqList options\(dq را ببینید\&. .UNINDENT .SS "گزینه‌های متفرقه (Miscellaneous Options)" .INDENT 0.0 .TP .B \fB\-\-help\fP شرح مفصلی از نحوه استفاده را در خروجی استاندارد چاپ کرده و سپس خارج می‌شود\&. .TP .B \fB\-?\fP معادل \fB\-\-help\fP\&. .TP .B \fB\-\-help\-full\fP شرح مفصلی از نحوه استفاده شامل ویژگی‌های آزمایشی را در خروجی استاندارد چاپ کرده و سپس خارج می‌شود\&. برای اطلاعات درباره جدیدترین ویژگی‌های آزمایشی، از \% دیدن کنید\&. .TP .B \fB\-\-license\fP خلاصه‌ای از مجوز نرم‌افزار را در خروجی استاندارد چاپ کرده و سپس خارج می‌شود\&. .TP .B \fB\-\-print\-language\fP تنها تجزیه‌کننده‌های زبان را برای فایل‌های منبع مشخص‌شده چاپ کرده و سپس خارج می‌شود\&. .TP .B \fB\-\-quiet[=(yes|no)]\fP پیام‌های کمتری می‌نویسد (پیش‌فرض \fBno\fP است)\&. .TP .B \fB\-\-totals[=(yes|no|extra)]\fP آماری درباره فایل‌های منبع خوانده‌شده و فایل برچسب نوشته‌شده در طول اجرای جاری ctags چاپ می‌کند\&. این گزینه به‌طور پیش‌فرض \fBno\fP است\&. .sp مقدار \fBextra\fP آمارهای خاص تجزیه‌کننده را برای تجزیه‌کننده‌هایی که چنین اطلاعاتی جمع‌آوری می‌کنند، چاپ می‌کند\&. .TP .B \fB\-\-verbose[=(yes|no)]\fP حالت پرحرف (verbose) را فعال می‌کند\&. این حالت اطلاعاتی درباره پردازش گزینه‌ها و پیامی کوتاه در توصیف اقدامی که برای هر فایل بررسی‌شده توسط ctags انجام می‌شود چاپ می‌کند\&. به‌طور معمول، ctags آرگومان‌های خط فرمان را تا پس از خواندن گزینه‌ها از فایل‌های پیکربندی (بخش \(dqFILES\(dq در زیر را ببینید) نمی‌خواند\&. با این حال، اگر این گزینه نخستین آرگومان در خط فرمان باشد، پیش از خوانده شدن هر گزینه‌ای از این منابع اثر خواهد کرد\&. مقدار پیش‌فرض \fBno\fP است\&. .TP .B \fB\-V\fP معادل \fB\-\-verbose\fP\&. .TP .B \fB\-\-version[=|NONE]\fP شناسه نسخه ctags را در خروجی استاندارد چاپ کرده و سپس خارج می‌شود\&. تضمین می‌شود که همیشه حاوی رشته \(dqUniversal Ctags\(dq است\&. همچنین توضیحات \fBTAG_PROGRAM_VERSION\fP و \fBTAG_OUTPUT_VERSION\fP در ctags\-client\-tools(7) را ببینید\&. .sp اگر \fBNONE\fP داده شود، شناسه نسخه را به شیوه‌ای ساده‌شده چاپ می‌کند\&. .sp اگر \fI\fP داده شود، شناسه نسخه را برای تجزیه‌کننده \fI\fP چاپ می‌کند\&. همچنین توضیحات \fBTAG_PARSER_VERSION\fP در ctags\-client\-tools(7) را ببینید\&. .UNINDENT .SS "گزینه‌های منسوخ‌شده (Obsoleted Options)" .sp این گزینه‌ها برای سازگاری عقبروی با Exuberant Ctags نگه‌داشته شده‌اند\&. .INDENT 0.0 .TP .B \fB\-w\fP این گزینه برای سازگاری عقبروی با ctags در SVR4 Unix بی‌صدا نادیده گرفته می‌شود\&. .TP .B \fB\-\-file\-scope[=(yes|no)]\fP این گزینه حذف شده است\&. به جای آن از \fB\-\-extras=[+|\-]F\fP یا \fB\-\-extras=[+|\-]{fileScope}\fP استفاده کنید\&. .TP .B \fB\-\-extra=[+|\-][|*]\fP معادل \fB\-\-extras=[+|\-][|*]\fP است که برای هماهنگ‌سازی شیوه نام‌گذاری گزینه با گزینه‌های دیگر مانند \fB\-\-kinds\-=\fP و \fB\-\-fields=\fP معرفی شد\&. .TP .B \fB\-\-\-kinds=[+|\-](|*)\fP این گزینه منسوخ شده است\&. به جای آن از \fB\-\-kinds\-=...\fP استفاده کنید\&. .UNINDENT .SH "جزئیات عملیاتی (OPERATIONAL DETAILS)" .sp هنگامی که ctags هر یک از نام‌های فایل‌های منبع را به نوبت بررسی می‌کند، تلاش می‌نماید با اعمال آزمون‌های شرح‌داده‌شده در بخش \(dqتشخیص زبان فایل\(dq (Determining file language)، زبان فایل را تعیین کند. .sp اگر زبانی شناسایی شود، فایل باز شده و سپس تجزیه‌کننده زبان مربوطه برای پردازش روی فایلِ در حال حاضر باز، فراخوانی می‌شود. تجزیه‌کننده فایل را پیمایش کرده و به‌ازای هر شیء زبانی که برای مدیریت آن نوشته شده است، مدخلی به فایل برچسب می‌افزاید. برای مشاهده جزئیات این مدخل‌ها، به بخش \(dqقالب فایل برچسب\(dq (TAG FILE FORMAT) در ادامه مراجعه کنید. .SS "نکاتی برای تجزیه‌کننده C/C++ (Notes for C/C++ Parser)" .\" TODO: move the following description to parser-cxx.rst. . .sp این پیاده‌سازی ctags برخلاف پیاده‌سازی‌های موروثی، هیچ الزامی برای قالب‌بندی کد C تحمیل نمی‌کند. پیاده‌سازی‌های قدیمی‌تر ctags تمایل داشتند بر مفروضات قالب‌بندی معینی تکیه کنند تا بتوانند دوراهی‌های کدنویسی ناشی از شرط‌های پیش‌پردازنده را حل نمایند. .sp به‌طور کلی، ctags تلاش می‌کند در مورد دستورهای شرطی پیش‌پردازنده هوشمندانه رفتار کند. اگر یک شرط پیش‌پردازنده درون عبارتی دیده شود که برچسبی را تعریف می‌کند، ctags تنها نخستین شاخه آن شرط را دنبال می‌کند (مگر در حالت خاص \fB#if 0\fP، که در آن فقط آخرین شاخه را دنبال می‌کند). دلیل این امر آن است که دنبال نکردن تنها یک شاخه می‌تواند منجر به نحو مبهمی گردد، مانند مثال زیر: .INDENT 0.0 .INDENT 3.5 .sp .EX #ifdef TWO_ALTERNATIVES struct { #else union { #endif short a; long b; } .EE .UNINDENT .UNINDENT .sp نمی‌توان هر دو شاخه را دنبال کرد، زیرا در این صورت آکولادها نامتعادل شده و ctags قادر به درک نحو نخواهد بود. .sp اگر اعمال این روش اکتشافی در تجزیه درست فایل با شکست مواجه شود (که عموماً به دلیل جفت‌شدن‌های پیچیده و ناسازگار در شرط‌ها رخ می‌دهد)، ctags تجزیه فایل را با روش اکتشافی متفاوتی دوباره امتحان می‌کند؛ روشی که شاخه‌های شرطی پیش‌پردازنده را به شکل گزینشی دنبال نمی‌کند، بلکه در صورت بروز هرگونه عدم تعادل آکولادها در پی دنبال کردن یک شاخه شرطی \fB#if\fP، به تکیه بر آکولاد بسته (\(aq\fB}\fP\(aq) در ستون ۱ به عنوان نشانه پایان بلوک بازمی‌گردد. .sp همچنین ctags تلاش خواهد کرد فهرست‌های آرگومان محصور در دو جفت پرانتز را به طور ویژه مدیریت کند تا ساختار شرطی زیر را بپذیرد: .INDENT 0.0 .INDENT 3.5 .sp .EX extern void foo __ARGS((int one, char two)); .EE .UNINDENT .UNINDENT .sp هر نامی که بلافاصله پیش از \(aq\fB((\fP\(aq قرار گیرد به‌طور خودکار نادیده گرفته شده و از نام پیشین استفاده خواهد شد. .sp تعاریف عملگر در ++C به طور ویژه مدیریت می‌شوند. به منظور حفظ سازگاری با تمام انواع عملگرها (سربارگذاری‌شده و تبدیل نوع)، نام عملگر در فایل برچسب همواره با رشته \(dqoperator \(dq پیشونددهی خواهد شد (یعنی حتی اگر تعریف واقعی عملگر به صورت \(dqoperator<<\(dq نوشته شده باشد). .sp پس از ساخت یا الحاق به فایل برچسب، فایل بر پایه نام برچسب مرتب شده و سطرهای برچسبِ یکسان حذف می‌شوند. .SS "تشخیص زبان فایل (Determining file language)" .SS "نگاشت نام فایل (File name mapping)" .sp مگر اینکه گزینه \fB\-\-language\-force\fP تعیین شده باشد، زبان هر فایل منبع به‌طور خودکار بر پایه یک \fIنگاشت\fP از نام‌های فایل به زبان‌ها انتخاب می‌شود. نگاشت‌های فعال برای هر زبان را می‌توان با استفاده از گزینه \fB\-\-list\-maps\fP نمایش داد و با استفاده از گزینه‌های \fB\-\-langmap\fP یا \fB\-\-map\-\fP تغییر داد. .sp اگر نام یک فایل به زبانی نگاشت نشده باشد، ctags تلاش می‌کند با بررسی محتوای فایل، زبان آن را به شیوه اکتشافی حدس بزند. .sp همه فایل‌هایی که فاقد نگاشت نام فایل و فاقد تجزیه‌کننده حدس‌زده‌شده هستند، نادیده گرفته می‌شوند. این قابلیت اجازه می‌دهد ctags را روی تمام فایل‌های موجود در یک شاخه تنها (مانند \(dq\fBctags *\fP\(dq)، یا روی همه فایل‌ها در کل درخت شاخه‌های منبع (مانند \(dq\fBctags \-R\fP\(dq) اجرا کرد، زیرا تنها فایل‌هایی که نامشان به زبان‌ها نگاشت شده باشد پویش خواهند شد. .sp یک پسوند می‌تواند به چند تجزیه‌کننده نگاشت شود. برای نمونه، \fB\&.h\fP به C++، C و ObjectiveC نگاشت شده است. این نگاشت‌ها می‌توانند موجب بروز مشکلاتی شوند. ctags با اعمال روش‌های اکتشافی روی محتوای فایل منبع، سعی می‌کند تجزیه‌کننده مناسب را انتخاب نماید، با این وجود بی‌نقص نیست. در صورت بروز مشکل می‌توان از گزینه‌های \fB\-\-language\-force=\fP، \fB\-\-langmap=[,[...]]\fP، یا \fB\-\-map\-=[+|\-]|\fP استفاده کرد. (برخی از این روش‌های اکتشافی صرف‌نظر از اینکه \fB\-\-guess\-language\-eagerly\fP داده شده باشد یا خیر اعمال می‌شوند.) .\" TODO: all heuristics??? To be confirmed. . .SS "حدس اکتشافی (Heuristically guessing)" .sp اگر ctags نتواند تجزیه‌کننده‌ای را بر پایه نگاشت نام‌های فایل انتخاب کند، آزمون‌های اکتشافی گوناگونی برای تعیین زبان انجام می‌گیرند: .INDENT 0.0 .TP .B آزمون نام فایل الگو (template file name testing) اگر نام فایل دارای پسوند \fB\&.in\fP باشد، ctags نگاشت را روی نام فایل بدون پسوند اعمال می‌کند. برای نمونه، برای فایلی با نام \fBconfig.h.in\fP، نگاشت \fBconfig.h\fP آزموده می‌شود\&. .TP .B آزمون \(dqمفسر\(dq (\(dqinterpreter\(dq testing) سطر نخست فایل بررسی می‌شود تا مشخص گردد آیا فایل یک اسکریپت \fB#!\fP برای زبانی شناخته‌شده هست یا خیر. ctags به دنبال تجزیه‌کننده‌ای با همان نام می‌گردد. .sp اگر ctags چنین تجزیه‌کننده‌ای نیابد، به دنبال آن نام در فهرست‌های نام مستعار می‌گردد. برای نمونه، فرض کنید سطر نخست \fB#!/bin/sh\fP باشد\&. اگرچه ctags یک تجزیه‌کننده \(dqshell\(dq دارد، اما فاقد تجزیه‌کننده \(dqsh\(dq است. با این حال، از آنجا که \fBsh\fP به عنوان نام مستعار \fBshell\fP فهرست شده است، ctags تجزیه‌کننده \(dqshell\(dq را برای فایل برمی‌گزیند. .sp یک استثنا \fBenv\fP است\&. اگر \fBenv\fP مشخص شده باشد (برای نمونه \(dq\fB#!/usr/bin/env python\fP\(dq)، ctags سطرهای بیشتری را می‌خواند تا مشخصات مفسر واقعی را بیابد. .sp برای نمایش فهرست نام‌های مستعار، از گزینه \fB\-\-list\-aliases\fP استفاده کنید. برای افزودن یک مورد به فهرست یا حذف یک مورد از فهرست، به ترتیب از گزینه \fB\-\-alias\-=+\fP یا \fB\-\-alias\-=\-\fP استفاده نمایید. .TP .B آزمون \(dqبرچسب بارگذاری خودکار zsh\(dq (\(dqzsh autoload tag\(dq testing) اگر سطر نخست با \fB#compdef\fP یا \fB#autoload\fP آغاز شود، ctags آن سطر را به منزله \(dqzsh\(dq در نظر می‌گیرد. .TP .B آزمون \(dqحالت emacs در سطر نخست\(dq (\(dqemacs mode at the first line\(dq testing) ویرایشگر Emacs چندین حالت ویرایشی ویژه زبان‌های برنامه‌نویسی دارد. Emacs می‌تواند نشانگری موسوم به modeline را در یک فایل شناسایی کند و از آن نشانگر برای انتخاب حالت بهره ببرد. این آزمون اکتشافی دقیقاً همان کاری را انجام می‌دهد که Emacs انجام می‌دهد. .sp اگر سطر نخست یکی از الگوهای زیر را داشته باشد، ctags با \fBMODE\fP به عنوان نام مفسر رفتار کرده و همان قاعده آزمون \(dqمفسر\(dq را اعمال می‌نماید: .INDENT 7.0 .INDENT 3.5 .sp .EX \-*\- mode: MODE \-*\- .EE .UNINDENT .UNINDENT .sp یا .INDENT 7.0 .INDENT 3.5 .sp .EX \-*\- MODE \-*\- .EE .UNINDENT .UNINDENT .TP .B آزمون \(dqحالت emacs در پایان فایل\(dq (\(dqemacs mode at the EOF\(dq testing) ویرایشگر Emacs نشانگر دیگری را در پایان فایل به عنوان مشخص‌کننده حالت تشخیص می‌دهد. این آزمون اکتشافی نیز مانند Emacs عمل می‌کند. .sp اگر سطرهای انتهای فایل دارای الگوی زیر باشند، ctags با \fBMODE\fP به عنوان نام یک مفسر رفتار کرده و همان قاعده آزمون اکتشافی \(dqمفسر\(dq را اعمال می‌کند: .INDENT 7.0 .INDENT 3.5 .sp .EX Local Variables: \&... mode: MODE \&... End: .EE .UNINDENT .UNINDENT .sp برای یافتن این الگو، ۳۰۰۰ نویسه از انتهای فایل جستجو می‌شود. .TP .B آزمون \(dqmodeline در vim\(dq (\(dqvim modeline\(dq testing) همانند modeline در ویرایشگر Emacs، ویرایشگر Vim نیز مفهوم یکسانی دارد. اگر ۵ سطر نخست یا ۵ سطر پایانی فایل یکی از الگوهای زیر را داشته باشند، ctags با \fBTYPE\fP به عنوان نام مفسر رفتار کرده و همان قاعده آزمون اکتشافی \(dqمفسر\(dq را اعمال می‌نماید: .INDENT 7.0 .INDENT 3.5 .sp .EX filetype=TYPE .EE .UNINDENT .UNINDENT .sp یا .INDENT 7.0 .INDENT 3.5 .sp .EX ft=TYPE .EE .UNINDENT .UNINDENT .TP .B آزمودن \(dqنشانگر PHP\(dq (\(dqPHP marker\(dq testing) اگر خط نخست با \fB;\(dq .EE .UNINDENT .UNINDENT .sp فیلدها و جداکننده‌های این خطوط به صورت زیر مشخص می‌شوند: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP 1. 3 \fB\fP: نام برچسب .IP 2. 3 \fB\fP: نویسهٔ تب منفرد .IP 3. 3 \fB\fP: نام فایلی که شیء مرتبط با برچسب در آن قرار دارد .IP 4. 3 \fB\fP: نویسهٔ تب منفرد .IP 5. 3 \fB\fP: دستور EX که برای مکان‌یابی برچسب درون فایل استفاده می‌شود؛ عموماً یک الگوی جستجو (یا \fB/pattern/\fP یا \fB?pattern?\fP) یا شمارهٔ خط (گزینهٔ \fB\-\-excmd=\fP را ببینید)\&. .IP 6. 3 \fB;\(dq\fP: مجموعه‌ای از فیلدهای افزونه\&. برای جزئیات بیشتر \(dqExtension fields\(dq را ببینید\&. .sp قالب ۲ فایل برچسب (گزینهٔ \fB\-\-format\fP را ببینید) دستور EX را گسترش می‌دهد تا فیلدهای افزونه را که درون یک توضیح EX بلافاصله متصل‌شده به دستور EX قرار دارند شامل شود، که این امر سازگاری رو به عقب آن را با پیاده‌سازی‌های اصلی \fBvi(1)\fP حفظ می‌کند\&. .UNINDENT .UNINDENT .UNINDENT .sp تعداد اندکی برچسب ویژه، موسوم به \fIبرچسب‌های شبه\fP (pseudo tags)، برای اهداف داخلی درون فایل برچسب نوشته می‌شوند\&. .INDENT 0.0 .INDENT 3.5 .sp .EX !_TAG_FILE_FORMAT 2 /extended format; \-\-format=1 will not append ;\(dq to lines/ !_TAG_FILE_SORTED 1 /0=unsorted, 1=sorted, 2=foldcase/ \&... .EE .UNINDENT .UNINDENT .sp گزینهٔ \fB\-\-pseudo\-tags=[+|\-](|*)\fP صدور برچسب‌های شبه را فعال یا غیرفعال می‌کند\&. .sp برای دیدن فهرست انواع، خروجی \(dq\fBctags \-\-list\-pseudo\-tags\fP\(dq را ببینید\&. همچنین برای جزئیات بیشتر دربارهٔ برچسب‌های شبه به tags(5) و ctags\-client\-tools(7) مراجعه کنید\&. .sp این برچسب‌ها به گونه‌ای مرتب می‌شوند که همیشه به ابتدای فایل منتقل گردند\&. بنابراین، دو نویسهٔ اول این برچسب‌ها به عنوان یک عدد جادویی (magic number) جهت شناسایی فایل برچسب برای تعیین این که آیا به جای یک فایل منبع، یک فایل برچسب معتبر بازنویسی می‌شود، مورد استفاده قرار می‌گیرد\&. .sp توجه داشته باشید که نام هر فایل منبع دقیقاً همان‌طور که در خط فرمان ظاهر شده است در فایل برچسب ثبت خواهد شد\&. بنابراین، اگر مسیری که در خط فرمان مشخص کرده‌اید نسبت به شاخهٔ جاری بوده باشد، در فایل برچسب نیز به همان صورت ثبت خواهد شد\&. با این حال، گزینهٔ \fB\-\-tag\-relative=(yes|no|always|never)\fP را ببینید تا بدانید چگونه این رفتار را می‌توان تغییر داد\&. .SH "مدخل‌های برچسب (TAG ENTRIES)" .sp یک برچسب نمایه‌ای برای یک شیء زبانی است\&. مفهوم برچسب و موارد مرتبط با آن در Exuberant Ctags در Universal Ctags پالایش و گسترش یافته است\&. .sp یک برچسب به \fIبرچسب‌های تعریف\fP (definition tags) یا \fIبرچسب‌های ارجاع\fP (reference tags) دسته‌بندی می‌شود\&. به طور کلی، Exuberant Ctags فقط \fIتعاریف\fP اشیاء زبانی را برچسب‌گذاری می‌کند: مکان‌هایی که در آن‌ها اشیاء زبانی نام‌گذاری‌شدهٔ جدید \fIمعرفی می‌شوند\fP\&. از سوی دیگر، Universal Ctags می‌تواند \fIارجاعات\fP به اشیاء زبانی را نیز برچسب‌گذاری کند: مکان‌هایی که در آن‌ها اشیاء زبانی نام‌گذاری‌شده \fIاستفاده می‌شوند\fP\&. با این حال، پشتیبانی از تولید برچسب‌های ارجاع در نسخهٔ جاری جدید بوده و به بخش‌های خاصی از زبان‌های خاص محدود است\&. .SS "فیلدهای افزونه (Extension fields)" .sp یک برچسب می‌تواند اطلاعات گوناگونی را ثبت کند که \fIفیلدهای افزونه\fP (extension fields) نامیده می‌شوند\&. .sp فیلدهای افزونه جفت‌های کلید-مقداری هستند که با تب جدا شده و همان‌طور که در بالا توضیح داده شد، به عنوان یک نظر/توضیح به انتهای دستور EX پیوست می‌شوند\&. این جفت‌های کلید-مقدار به فرم کلی \fBkey:value\fP ظاهر می‌شوند\&. .sp علاوه بر این، ممکن است اطلاعات مربوط به حوزهٔ (scope) تعریف برچسب نیز در دسترس باشد، به طوری که بخش کلید برابر با نام یک ساختار وابسته به زبان بوده و مقدار آن، نام اعلان‌شده برای آن ساختار در برنامه باشد\&. این مدخل حوزه نشان‌دهندهٔ حوزه‌ای است که برچسب در آن یافت شده است\&. برای مثال، برچسب تولیدشده برای یک عضو ساختار C دارای حوزه‌ای شبیه به \fBstruct:myStruct\fP خواهد بود\&. .sp گزینه‌های \fB\-\-fields=[+|\-][|*]\fP و \fB\-\-fields\-(|all)=[+|\-][|*]\fP مشخص می‌کنند کدام فیلدهای افزونهٔ موجود باید در مدخل‌های برچسب گنجانده شوند\&. .sp برای فهرست فیلدهای افزونه، خروجی \(dq\fBctags \-\-list\-fields\fP\(dq را ببینید\&. فیلدهای اساسی عبارت‌اند از \fBname\fP، \fBinput\fP، \fBpattern\fP، و \fBline\fP\&. معنای فیلدهای اصلی به صورت زیر است (پرچم نام‌بلند/پرچم تک‌حرفی): .INDENT 0.0 .TP .B \fBaccess\fP/\fBa\fP سطح دسترسی و دید این عضو کلاس را مشخص می‌کند، که در آن مقدار وابسته به زبان است\&. .TP .B \fBend\fP/\fBe\fP شماره خطوط پایانی شیء زبانی را مشخص می‌کند\&. .TP .B \fBextras\fP/\fBE\fP اطلاعات نوع برچسب اضافی\&. برای جزئیات بیشتر \(dqExtras\(dq را ببینید\&. .TP .B \fBfile\fP/\fBf\fP نشان می‌دهد که برچسب دارای دید محدود به فایل است\&. این کلید هیچ مقدار متناظری ندارد\&. به طور پیش‌فرض فعال است\&. .TP .B \fBimplementation\fP/\fBm\fP در صورت وجود، نشان‌دهندهٔ یک پیاده‌سازی محدود (انتزاعی در برابر عینی) از یک روال یا کلاس است، که در آن مقدار وابسته به زبان می‌باشد (\fBvirtual\fP یا \fBpure virtual\fP برای ++C؛ \fBabstract\fP برای Java)\&. .TP .B \fBinherits\fP/\fBi\fP در صورت وجود، مقدار آن فهرستی جداشده با ویرگول از کلاس‌هایی است که این کلاس از آن‌ها مشتق شده است (یعنی از آن‌ها ارث‌بری می‌کند)\&. .TP .B \fBinput\fP/\fBF\fP نام فایل منبعی که \fBname\fP در آن تعریف یا به آن ارجاع داده شده است\&. .TP .B \fBk\fP نوع \% برچسب به عنوان تک‌حرف\&. به طور پیش‌فرض فعال است\&. این فیلد نام‌بلند ندارد\&. همچنین پرچم \fBkind\fP/\fBz\fP را ببینید\&. .TP .B \fBK\fP نوع \% برچسب به عنوان نام‌بلند\&. این فیلد نام‌بلند ندارد\&. همچنین پرچم \fBkind\fP/\fBz\fP را ببینید\&. .TP .B \fBkind\fP/\fBz\fP کلید \fBkind:\fP در فیلد kind \% گنجانده شود\&. همچنین پرچم‌های \fBk\fP و \fBK\fP را ببینید\&. .TP .B \fBlanguage\fP/\fBl\fP زبان فایل منبع حاوی برچسب\&. .TP .B \fBline\fP/\fBn\fP شماره خطی که در آن \fBname\fP در \fBinput\fP تعریف یا ارجاع داده شده است\&. .TP .B \fBname\fP/\fBN\fP نام اشیاء زبانی\&. .TP .B \fBnth\fP/\fBo\fP ترتیب در حوزهٔ والد\&. (برای مثال چهارمین پارامتر در تابع)\&. .TP .B \fBpattern\fP/\fBP\fP می‌تواند برای جستجوی \fBname\fP در \fBinput\fP استفاده شود\&. .TP .B \fBroles\fP/\fBr\fP نقش‌های اختصاص‌یافته به برچسب\&. برای جزئیات بیشتر \(dqRoles\(dq را ببینید\&. .TP .B \fBs\fP حوزهٔ تعریف برچسب\&. به طور پیش‌فرض فعال است\&. این فیلد نام‌بلند ندارد\&. همچنین پرچم \fBscope\fP/\fBZ\fP را ببینید\&. .TP .B \fBscope\fP/\fBZ\fP کلید \fBscope:\fP را به ابتدای فیلد حوزه (\fBs\fP) اضافه می‌کند. پرچم \fBs\fP را نیز ببینید. .TP .B \fBscopeKind\fP/\fBp\fP نوع حوزه به صورت نام طولانی (long\-name). .TP .B \fBsignature\fP/\fBS\fP در صورت وجود، مقدار آن نمایشی وابسته به زبان از امضای یک روال (مانند پیش‌نمونه یا فهرست پارامترها) است. امضای یک روال در شکل کامل خود نوع بازگشتی یک روال و فهرست آرگومان‌های صوری آن را مشخص می‌کند. این فیلد افزونه در حال حاضر تنها برای زبان‌های مبتنی بر C پشتیبانی می‌شود و شامل نوع بازگشتی نمی‌باشد. .TP .B \fBtyperef\fP/\fBt\fP نوع و نام یک متغیر، typedef یا نوع بازگشتی یک شیء قابل فراخوانی مانند تابع به عنوان فیلد \fBtyperef:\fP\&. به‌طور پیش‌فرض فعال است. .UNINDENT .SS "انواع (Kinds)" .sp \fBkind\fP فیلدی است که \fIنوعِ\fP شیء زبان مشخص‌شده توسط یک برچسب را نشان می‌دهد. انواع مورد استفاده و تعریف‌شده میان تجزیه‌کننده‌ها بسیار متفاوت هستند. برای نمونه، زبان C مواردی چون \fBmacro\fP، \fBfunction\fP، \fBvariable\fP، \fBtypedef\fP و غیره را تعریف می‌کند. .sp گزینه \fB\-\-kinds\-(|all)=[+|\-](|*)\fP فهرستی از انواع برچسب‌های وابسته به زبان (یا انواع) را برای گنجاندن در فایل خروجی برای زبانی خاص مشخص می‌کند. .sp برای فهرست کامل انواع، خروجی دستور \(dq\fBctags \-\-list\-kinds\-full\fP\(dq را مشاهده کنید. .sp مقدار آن یا یکی از پرچم‌های تک‌حرفی متناظر یا یک پرچم با نام طولانی است. حذف بخش کلید (key) در این فیلد مجاز (و در واقع پیش‌فرض) است. رفتارهای اختیاری با گزینه \fB\-\-fields\fP به شرح زیر کنترل می‌شوند. .INDENT 0.0 .INDENT 3.5 .sp .EX $ ctags \-o \- kinds.c foo kinds.c /^int foo() {$/;\(dq f typeref:typename:int $ ctags \-\-fields=+k \-o \- kinds.c foo kinds.c /^int foo() {$/;\(dq f typeref:typename:int $ ctags \-\-fields=+K \-o \- kinds.c foo kinds.c /^int foo() {$/;\(dq function typeref:typename:int $ ctags \-\-fields=+z \-o \- kinds.c foo kinds.c /^int foo() {$/;\(dq kind:f typeref:typename:int $ ctags \-\-fields=+zK \-o \- kinds.c foo kinds.c /^int foo() {$/;\(dq kind:function typeref:typename:int .EE .UNINDENT .UNINDENT .SS "نقش‌ها (Roles)" .sp مفهوم \fIRole\fP (نقش) مفهومی تازه معرفی‌شده در Universal Ctags است. نقش مفهومی مرتبط با برچسب‌های ارجاعی است و هنوز به‌طور گسترده پیاده‌سازی نشده است. .sp همان‌طور که پیش‌تر در بخش \(dqانواع (Kinds)\(dq شرح داده شد، فیلد \fBkind\fP نشان‌دهنده نوع شیء زبان مشخص‌شده با یک برچسب است، مانند تابع در برابر متغیر. انواع خاصی برای برچسب‌های ارجاعی تعریف شده‌اند، مانند نوع \fBheader\fP در C++ برای فایل‌های سرآیند، یا نوع \fBpackage\fP در Java برای عبارات package. برای چنین انواع ارجاعی، یک فیلد \fBroles\fP می‌تواند برای متمایز ساختن نقشِ نوع ارجاعی اضافه شود. به بیان دیگر، فیلد \fBkind\fP مشخص می‌کند که شیء زبان \fIچه چیزی\fP است، در حالی که فیلد \fBroles\fP مشخص می‌کند شیء زبان ارجاع‌شده \fIچگونه\fP است. نقش‌ها تنها با انواع خاصی استفاده می‌شوند. .sp برای یک برچسب تعریف، این فیلد مقدار \fBdef\fP را می‌گیرد. .sp برای نمونه، در کد زیر \fBBaz\fP به عنوان یک برچسب ارجاعی با نوع \fBpackage\fP و نقش \fBimported\fP برچسب‌گذاری می‌شود. .INDENT 0.0 .INDENT 3.5 .sp .EX package Bar; import Baz; class Foo { // ... } .EE .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .EX $ ctags \-\-fields=+KEr \-uo \- roles.java Bar roles.java /^package Bar;$/;\(dq package roles:def Foo roles.java /^class Foo {$/;\(dq class roles:def $ ctags \-\-fields=+EKr \-\-extras=+r \-uo \- roles.java Bar roles.java /^package Bar;$/;\(dq package roles:def Baz roles.java /^import Baz;$/;\(dq package roles:imported extras:reference Foo roles.java /^class Foo {$/;\(dq class roles:def .EE .UNINDENT .UNINDENT .sp گزینه \fB\-\-roles\-(|all).(|all)=[+|\-][|*]\fP فهرستی از نقش‌های خاص هر نوع برچسب را برای گنجاندن در فایل خروجی برای زبانی مشخص تعیین می‌کند. .sp برای فهرست نقش‌ها خروجی \(dq\fBctags \-\-list\-roles\fP\(dq را بررسی کنید. .SS "موارد اضافی (Extras)" .sp به‌طور کلی، ctags تنها اشیاء زبانی ظاهرشده در فایل‌های منبع را همان‌گونه که هستند برچسب‌گذاری می‌کند. به عبارت دیگر، مقدار یک فیلد \fBname:\fP باید در فایل منبع مرتبط با آن \fBname:\fP یافت شود. برچسبی از نوع \fBextra\fP (\fIextra\fP) برای برچسب‌گذاری یک شیء زبان با نامی پردازش‌شده، یا برچسب‌گذاری چیزی است که با یک شیء زبان مرتبط نیست. یک برچسب اضافی متداول \fBqualified\fP است که یک شیء زبان را با نام واجد شرایط کلاس یا حوزه (scope-qualified) برچسب‌گذاری می‌کند. .sp گزینه \fB\-\-extras\-(|all)=[+|\-][|*]\fP مشخص می‌کند آیا مدخل‌های برچسب اضافی برای انواع خاصی از اطلاعات گنجانده شوند یا خیر. .sp برای فهرست موارد اضافی خروجی \fBctags \-\-list\-extras\fP را بررسی کنید. معنای موارد اضافی اصلی به این شرح است (پرچم نام طولانی/پرچم تک‌حرفی): .INDENT 0.0 .TP .B \fBanonymous\fP/none گنجاندن یک مدخل برای شیء زبانی که نام ندارد، مانند تابع لامبدا. این مورد اضافی فاقد پرچم تک‌حرفی است و به‌طور پیش‌فرض فعال است. .sp این برچسب اضافی به عنوان یک جای‌نگه‌دار برای پر کردن فیلدهای حوزه برای اشیاء زبانیِ تعریف‌شده در یک شیء زبانی فاقد نام مفید است. .INDENT 7.0 .INDENT 3.5 .sp .EX struct { double x, y; } p = { .x = 0.0, .y = 0.0 }; .EE .UNINDENT .UNINDENT .sp \(aq\fBx\fP\(aq و \(aq\fBy\fP\(aq اعضای یک ساختار هستند. هنگام پر کردن فیلدهای حوزه برای آن‌ها، ctags دچار مشکل می‌شود چرا که ساختارِ دربرگیرنده \(aq\fBx\fP\(aq و \(aq\fBy\fP\(aq نامی ندارد. برای حل این مشکل، ctags یک برچسب اضافی ناشناس (anonymous) برای ساختار تولید می‌کند و فیلدهای حوزه را با نام این برچسب اضافی پر می‌نماید. .INDENT 7.0 .INDENT 3.5 .sp .EX $ ctags \-\-fields=\-f \-uo \- input.c __anon9f26d2460108 input.c /^struct {$/;\(dq s x input.c /^ double x, y;$/;\(dq m struct:__anon9f26d2460108 y input.c /^ double x, y;$/;\(dq m struct:__anon9f26d2460108 p input.c /^} p = { .x = 0.0, .y = 0.0 };$/;\(dq v typeref:struct:__anon9f26d2460108 .EE .UNINDENT .UNINDENT .sp خروجی برچسب فوق حاوی \fB__anon9f26d2460108\fP به عنوان برچسب اضافی ناشناس است. فیلد typeref برای \(aq\fBp\fP\(aq نیز از مزیت آن بهره‌مند می‌شود. .TP .B \fBfileScope\fP/\fBF\fP نشان می‌دهد آیا برچسب‌های منحصر به حوزه تک‌فایل (یعنی برچسب‌هایی که بیرون از فایلی که در آن تعریف شده‌اند دیده نمی‌شوند، مانند اشیاء زبانی با اصلاح‌کننده \fBstatic\fP در زبان C) باید در خروجی گنجانده شوند یا خیر. گزینه \fB\-h\fP را نیز ببینید. .sp این برچسب اضافی به‌طور پیش‌فرض فعال است. برای عدم درج برچسب‌های منحصر به حوزه تک‌فایل، گزینه \fB\-\-extras=\-F\fP را اضافه کنید. این گزینه جایگزین گزینه \fB\-\-file\-scope\fP در Exuberant Ctags است. .INDENT 7.0 .INDENT 3.5 .sp .EX static int f() { return 0; } int g() { return 0; } .EE .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .EX $ ctags \-uo \- filescope.c f filescope.c /^static int f() {$/;\(dq f typeref:typename:int file: g filescope.c /^int g() {$/;\(dq f typeref:typename:int $ ctags \-\-extras=\-F \-uo \- filescope.c g filescope.c /^int g() {$/;\(dq f typeref:typename:int .EE .UNINDENT .UNINDENT .TP .B \fBinputFile\fP/\fBf\fP گنجاندن یک مدخل برای نام پایه هر فایل منبع (مانند \fBexample.c\fP) که به خط اول فایل اشاره دارد. این پرچم جایگزین گزینه پنهان \fB\-\-file\-tags\fP در Exuberant Ctags است. .sp اگر فیلد \fBend:\fP فعال باشد، شماره خط پایانی فایل می‌تواند به برچسب پیوست شود. (با این حال، اگر فاقد خط جدید باشد مانند یک فایل خالی، ctags فیلد \fBend:\fP را حذف می‌کند.) .sp به‌طور پیش‌فرض، اگر ctags تجزیه‌کننده‌ای برای فایل منبع نیابد، برچسب اضافی \fBinputFile\fP/\fBf\fP را برای آن ایجاد نمی‌کند. فعال‌سازی تجزیه‌کننده \fBUnknown\fP با \fB\-\-languages=+Unknown\fP، ابزار ctags را وادار می‌کند برچسب‌های اضافی را برای هر فایل منبعی بسازد. .sp حالت etags تجزیه‌کننده \fBUnknown\fP را به شکل ضمنی فعال می‌کند. .TP .B \fBnulltag\fP/\fBz\fP شامل کردن برچسب‌هایی (\fIبرچسب‌های پوچ\fP یا \fInull tags\fP) که رشته‌های خالی را به عنوان نام خود دارند\&. به طور کلی، تلاش برای ایجاد یک برچسب پوچ نشانه‌ای از اشکال تجزیه‌کننده (parser bug) یا ورودی خراب است\&. ctags در مورد چنین تلاشی هشدار می‌دهد یا برچسب پوچ را دور می‌اندازد\&. برای سرکوب هشدارها، از گزینه \fB\-\-quiet\fP استفاده کنید\&. .sp از سوی دیگر، برچسب‌های پوچ در برخی زبان‌ها معتبر هستند\&. کد منبع JavaScript به شکل \fB{\(dq\(dq: val}\fP را در نظر بگیرید؛ رشته خالی به عنوان یک کلید معتبر است\&. اگر یک تجزیه‌کننده عمداً یک برچسب پوچ (یک برچسب پوچ معتبر) ایجاد کند، ctags هشداری نمی‌دهد اما به طور پیش‌فرض آن را کنار می‌گذارد\&. .sp این کنار گذاشتن به این دلیل است که ممکن است برخی قالب‌های خروجی برچسب‌های پوچ را پشتیبانی نکنند یا در نظر نگیرند\&. .sp با مورد اضافی \fBnulltag\fP/\fBz\fP، می‌توانید ctags را مجبور کنید که برچسب‌های پوچ را صادر کند\&. این مورد اضافی تنها در صورتی مؤثر است که قالب خروجی از برچسب‌های پوچ پشتیبانی کند\&. گزینه \fB\-\-list\-output\-formats\fP مشخص می‌کند که کدام قالب‌های خروجی از برچسب‌های پوچ پشتیبانی می‌کنند\&. .sp (از نسخه 6.2.0) .TP .B \fBpseudo\fP/\fBp\fP شامل کردن شبه‌برچسب‌ها (pseudo\-tags)\&. به طور پیش‌فرض فعال است مگر اینکه فایل برچسب در خروجی استاندارد نوشته شود\&. برای جزئیات مربوط به شبه‌برچسب‌ها، ctags\-client\-tools(7) را ببینید\&. .TP .B \fBqualified\fP/\fBq\fP شامل کردن یک مدخل برچسب اضافی با نام واجد شرایط کلاس (class\-qualified) یا فضای نام (namespace\-qualified) به ازای هر برچسبی که عضوی از یک کلاس یا یک فضای نام است\&. .sp این گزینه ممکن است مکان‌یابی آسان‌تر برچسب‌های خاص را در زمانی که چندین رخداد از یک نام برچسب در فایل برچسب وجود دارد امکان‌پذیر کند\&. با این حال، توجه داشته باشید که این کار می‌تواند به طور بالقوه اندازه فایل برچسب را بیش از دو برابر کند\&. .sp شکل واقعی برچسب واجد شرایط به زبانی بستگی دارد که برچسب از آن مشتق شده است (با استفاده از قالبی که طبیعی‌ترین حالت برای نحوه تعیین فراخوانی‌های واجد شرایط در آن زبان است)\&. برای C++‎ و Perl، به شکل \fBclass::member\fP است؛ برای Eiffel و Java، به شکل \fBclass.member\fP است\&. .sp نکته: در PHP از نویسه‌های بک‌اسلش (backslash) به عنوان جداکننده برای ساخت نام واجد شرایط استفاده می‌شود\&. با این حال، در خروجی برچسب‌های Universal Ctags، یک نویسه بک‌اسلش در یک نام با یک نویسه بک‌اسلش دیگر گریز داده می‌شود (escaped)\&. درباره گریز دادن، tags(5) را ببینید\&. .sp مثال زیر برچسب اضافی \fBqualified\fP را نشان می‌دهد\&. .INDENT 7.0 .INDENT 3.5 .sp .EX class point { double x; }; .EE .UNINDENT .UNINDENT .sp برای فایل منبع بالا، ctags به طور پیش‌فرض \fBpoint\fP و \fBx\fP را برچسب‌گذاری می‌کند\&. اگر مورد اضافی \fBqualified\fP از خط فرمان فعال شود (\fB\-\-extras=+q\fP)، آن‌گاه \fBpoint.x\fP نیز برچسب‌گذاری می‌شود حتی با اینکه رشته \(dq\fBpoint.x\fP\(dq در کد منبع وجود ندارد\&. .INDENT 7.0 .INDENT 3.5 .sp .EX $ ctags \-\-fields=+K \-uo \- qualified.java point qualified.java /^class point {$/;\(dq class x qualified.java /^ double x;$/;\(dq field class:point $ ctags \-\-fields=+K \-\-extras=+q \-uo \- qualified.java point qualified.java /^class point {$/;\(dq class x qualified.java /^ double x;$/;\(dq field class:point point.x qualified.java /^ double x;$/;\(dq field class:point .EE .UNINDENT .UNINDENT .TP .B \fBreference\fP/\fBr\fP شامل کردن برچسب‌های مرجع (reference tags)\&. بخش \(dqمدخل‌های برچسب (TAG ENTRIES)\(dq را درباره برچسب‌های مرجع ببینید\&. .sp مثال زیر برچسب اضافی \fBreference\fP را نشان می‌دهد\&. .INDENT 7.0 .INDENT 3.5 .sp .EX #include #include \(dqutils.h\(dq #define X #undef X .EE .UNINDENT .UNINDENT .sp فیلدهای \fBroles:system\fP یا \fBroles:local\fP بسته به اینکه نام فایل گنجانده‌شده با \(aq\fB<\fP\(aq آغاز شود یا نه، اضافه خواهند شد\&. .sp عبارت \(dq\fB#define X\fP\(dq یک برچسب تعریف صادر می‌کند\&. از سوی دیگر \(dq\fB#undef X\fP\(dq یک برچسب مرجع صادر می‌کند\&. .INDENT 7.0 .INDENT 3.5 .sp .EX $ ctags \-\-fields=+EKr \-uo \- inc.c X inc.c /^#define X$/;\(dq macro file: roles:def extras:fileScope $ ctags \-\-fields=+EKr \-\-extras=+r \-uo \- inc.c stdio.h inc.c /^#include /;\(dq header roles:system extras:reference utils.h inc.c /^#include \(dqutils.h\(dq/;\(dq header roles:local extras:reference X inc.c /^#define X$/;\(dq macro file: roles:def extras:fileScope X inc.c /^#undef X$/;\(dq macro file: roles:undef extras:fileScope,reference .EE .UNINDENT .UNINDENT .UNINDENT .SS "فیلدها و موارد اضافی مختص زبان (Language-specific fields and extras)" .sp ابزار Exuberant Ctags دارای مفهوم \fIفیلدها\fP (\fIfields\fP) و \fIموارد اضافی\fP (\fIextras\fP) است\&. آن‌ها بین تجزیه‌کننده‌های زبان‌های مختلف مشترک هستند\&. Universal Ctags این مفهوم را با ارائه فیلدها و موارد اضافی مختص زبان گسترش می‌دهد\&. .\" Note: kinds are language-specific since e-ctags. roles are new to u-ctags. . .\" TODO: move the following "Hot to ..." sections to FAQ man page when available . .SH "نحوه استفاده با VI (HOW TO USE WITH VI)" .sp برنامه \fBvi(1)\fP به‌طور پیش‌فرض انتظار فایلی از برچسب‌ها با نام \fBtags\fP را در دایرکتوری جاری دارد\&. پس از ساخته شدن فایل برچسب، دستورهای زیر قابلیت نمایه‌سازی برچسب را به کار می‌گیرند: .INDENT 0.0 .TP .B \fBvi \-t tag\fP اجرای vi و قرار دادن مکان‌نما در فایل و خطی که \fBtag\fP در آن تعریف شده است\&. .TP .B \fB:ta tag\fP یافتن یک برچسب\&. .TP .B \fBCtrl\-]\fP یافتن برچسب زیر مکان‌نما\&. .TP .B \fBCtrl\-T\fP بازگشت به مکان قبلی پیش از پرش به برچسب (در همه ویرایشگرها پیاده‌سازی نشده است)\&. .UNINDENT .SH "نحوه استفاده با GNU EMACS (HOW TO USE WITH GNU EMACS)" .sp برنامه \fBemacs(1)\fP به‌طور پیش‌فرض انتظار فایلی از برچسب‌ها با نام \fBTAGS\fP را در دایرکتوری جاری دارد\&. پس از ساخته شدن فایل برچسب، دستورهای زیر قابلیت نمایه‌سازی برچسب را به کار می‌گیرند: .INDENT 0.0 .TP .B \fBM\-x visit\-tags\-table FILE \fP انتخاب فایل برچسب، \fBFILE\fP، برای استفاده\&. .TP .B \fBM\-. [TAG] \fP یافتن اولین تعریف TAG\&. برچسب پیش‌فرض همان شناسه زیر مکان‌نما است\&. .TP .B \fBM\-*\fP بازگشت به مکانی که قبلاً در آن \fBM\-.\fP فراخوانی شده بود\&. .TP .B \fBC\-u M\-.\fP یافتن تعریف بعدی برای آخرین برچسب\&. .UNINDENT .sp برای دستورهای بیشتر، مبحث Tags را در سند info برنامه Emacs ببینید\&. .SH "نحوه استفاده با NEDIT (HOW TO USE WITH NEDIT)" .sp برنامه NEdit نسخه 5.1 و بالاتر می‌تواند قالب گسترش‌یافته جدید فایل برچسب را مدیریت کند (گزینه \fB\-\-format\fP را ببینید)\&. .INDENT 0.0 .IP \(bu 2 برای استفاده NEdit از فایل برچسب، گزینه \(dqFile\->Load Tags File\(dq را انتخاب کنید\&. .IP \(bu 2 برای پرش به تعریف یک برچسب، کلمه را مشخص کرده (highlight)، سپس \fBCtrl\-D\fP را فشار دهید\&. .UNINDENT .sp برنامه NEdit 5.1 می‌تواند چندین فایل برچسب را از دایرکتوری‌های مختلف بخواند\&. مقداردهی منبع سامانه X یعنی \fBnedit.tagFile\fP با نام یک فایل برچسب، به NEdit دستور می‌دهد تا آن فایل برچسب را هنگام راه‌اندازی به‌طور خودکار بارگذاری کند\&. .SH "هشدارها (CAVEATS)" .sp از آنجا که ctags نه پیش‌پردازنده است و نه کامپایلر، استفاده از ماکروهای پیش‌پردازنده می‌تواند ctags را بفریبد تا برچسب‌ها را نادیده بگیرد یا برچسب‌های نامناسبی تولید کند\&. اگرچه ctags برای رسیدگی به موارد رایج خاصی طراحی شده است، این موضوع بزرگ‌ترین عامل مشکلات گزارش‌شده است\&. به‌ویژه، استفاده از ساختارهای پیش‌پردازنده‌ای که نحو متنی C را دگرگون می‌کنند می‌تواند ctags را گمراه کند\&. با استفاده از گزینه \fB\-I\fP می‌توانید بسیاری از این مشکلات را برطرف سازید\&. .sp توجه داشته باشید از آنجا که ctags برای مکان‌یابی برچسب‌ها الگو تولید می‌کند (گزینه \fB\-\-excmd\fP را ببینید)، اگر سطر سورس دیگری عیناً مشابه سطر حاوی برچسب باشد، کاملاً ممکن است ویرایشگر شما سطر اشتباهی را بیابد\&. مثال زیر این وضعیت را نشان می‌دهد: .INDENT 0.0 .INDENT 3.5 .sp .EX int variable; /* ... */ void foo(variable) int variable; { /* ... */ } .EE .UNINDENT .UNINDENT .sp بسته به ویرایشگر مورد استفاده و موقعیت فعلی در کد، ممکن است الگوی جستجو پیش از یافتن تعریف واقعی متغیر سراسری، اعلان پارامتر محلی را بیابد؛ چرا که این سطرها (و در نتیجه الگوهای جستجوی آن‌ها) یکسان هستند\&. .sp می‌توان با استفاده از گزینه \fB\-\-excmd=n\fP از این مشکل جلوگیری کرد\&. .SH "تغییرات ناسازگار (INCOMPATIBLE CHANGES)" .sp برای اطلاعات درباره ناسازگاری‌های میان Universal Ctags و Exuberant Ctags، مستند ctags\-incompatibilities(7) را ببینید\&. .sp این بخش ناسازگاری‌های عمده بین نسخه‌های Universal Ctags را شرح می‌دهد\&. .INDENT 0.0 .TP .B یکسان‌سازی حرف گونه (kind Letter) برای گونه‌های \fBunknown\fP برخی تجزیه‌کننده‌ها از حروف گونه متفاوتی برای گونه‌های \fBunknown\fP استفاده می‌کردند\&. EmacsLisp از \fBu\fP استفاده می‌کرد\&. Go از \fBu\fP استفاده می‌کرد\&. Julian از \fBx\fP استفاده می‌کرد\&. Lisp از \fBu\fP استفاده می‌کرد\&. Lua از \fBX\fP استفاده می‌کرد و Python از \fBx\fP استفاده می‌کرد\&. این موارد در طول توسعه نسخه 5.9.x روی \fBY\fP یکسان‌سازی شدند\&. .UNINDENT .SH "ایرادات (BUGS)" .sp برنامه ctags گزینه‌های بیشتری نسبت به \fBls(1)\fP دارد\&. .sp برنامه ctags فرض می‌کند فایل ورودی با گرامر صحیح نوشته شده است\&. در غیر این صورت، خروجی ctags تعریف‌نشده است\&. به عبارت دیگر دارای ویژگی «ورودی نامعتبر، خروجی نامعتبر» (GIGO) است\&. .\" TODO: move the following paragraph to parser-cxx.rst. . .sp هنگام تجزیه تعریف یک تابع عضو C++ (مانند \fBclassName::function\fP)، برنامه ctags نمی‌تواند تشخیص دهد مشخص‌کننده دامنه (scope specifier) نام یک کلاس است یا نام یک namespace و همیشه آن را به عنوان نام کلاس در بخش scope از فیلدهای الحاقی فهرست می‌کند\&. همچنین اگر یک تابع C++ بیرون از اعلان کلاس تعریف شده باشد (که حالت معمول است)، مشخصه دسترسی (یعنی public، protected یا private) و اطلاعات پیاده‌سازی (مانند virtual یا pure virtual) موجود در اعلان تابع، هنگام تولید برچسب برای تعریف تابع مشخص نیستند\&. با این حال این اطلاعات برای پیش‌نمونه‌ها (مانند \fB\-\-kinds\-c++=+p\fP) در دسترس خواهند بود\&. .sp هیچ برچسب واجد شرایطی (qualified tags) برای اشیاء زبانی که در یک کلاس به ارث برده شده‌اند تولید نمی‌شود\&. .SH "متغیرهای محیطی (ENVIRONMENT VARIABLES)" .INDENT 0.0 .TP .B \fBTMPDIR\fP در میزبان‌های شبه‌یونیکس که \fBmkstemp(3)\fP در دسترس است، مقدار این متغیر پوشه‌ای را مشخص می‌کند که فایل‌های موقت در آن قرار می‌گیرند. این متغیر زمانی می‌تواند مفید باشد که اندازه یک فایل موقت بیش از حد بزرگ شود و در پارتیشن حاوی پوشه موقت پیش‌فرض (تعریف‌شده در زمان کامپایل) جای نگیرد. .sp ctags فایل‌های موقت را فقط در صورتی ایجاد می‌کند که (۱) یک فایل برچسب به سبک emacs در حال تولید باشد، (۲) فایل برچسب به خروجی استاندارد ارسال شود، یا (۳) برنامه به گونه‌ای کامپایل شده باشد که از الگوریتم مرتب‌سازی داخلی برای مرتب‌سازی فایل‌های برچسب به جای ابزار \fBsort(1)\fP سیستم‌عامل استفاده کند. اگر از ابزار \fBsort(1)\fP سیستم‌عامل استفاده شود، معمولاً این متغیر را نیز رعایت خواهد کرد. .sp توجه داشته باشید که اگر ctags دارای بیت setuid باشد، مقدار \fBTMPDIR\fP نادیده گرفته خواهد شد. .UNINDENT .SH "فایل‌ها (FILES)" .SS "فایل‌های خروجی (Output files)" .INDENT 0.0 .TP .B \fBtags\fP فایل برچسب پیش‌فرض ایجادشده توسط ctags. .TP .B \fBTAGS\fP فایل برچسب پیش‌فرض ایجادشده توسط etags. .UNINDENT .SS "پیش‌بارگذاری فایل‌های تنظیمات (Preloading option files)" .sp \fB$XDG_CONFIG_HOME/ctags/*.ctags\fP، یا \fB$HOME/.config/ctags/*.ctags\fP اگر \fB$XDG_CONFIG_HOME\fP تعریف نشده باشد .sp \fB$HOME/.ctags.d/*.ctags\fP .sp \fB$HOMEDRIVE$HOMEPATH/ctags.d/*.ctags\fP (فقط در MS Windows) .sp \fB\&.ctags.d/*.ctags\fP .sp \fBctags.d/*.ctags\fP .INDENT 0.0 .INDENT 3.5 اگر هر یک از این فایل‌های پیکربندی وجود داشته باشند، انتظار می‌رود که هر یک شامل مجموعه‌ای از گزینه‌های پیش‌فرض باشند که هنگام شروع ctags به ترتیب فهرست‌شده خوانده می‌شوند، اما قبل از اینکه هرگونه گزینه خط فرمان خوانده شود. این امر تنظیم پیش‌فرض‌های شخصی یا در سطح پروژه را امکان‌پذیر می‌سازد. .sp می‌توان ctags را طوری کامپایل کرد که یک فایل پیکربندی اضافی را قبل از هر یک از موارد نشان‌داده‌شده در بالا بخواند؛ این موضوع در صورتی مشخص می‌شود که خروجی تولیدشده توسط گزینه \fB\-\-version\fP ویژگی \fBcustom\-conf\fP را فهرست کند. .sp گزینه‌های ارائه‌شده در خط فرمان بر گزینه‌های مشخص‌شده در این فایل‌ها اولویت خواهند داشت (override می‌کنند). فقط گزینه‌ها از این فایل‌ها خوانده می‌شوند. .sp توجه داشته باشید که فایل‌های گزینه‌ها در حالت خط‌محور خوانده می‌شوند که در آن فاصله‌ها معنادار هستند (زیرا نقل‌قول پوسته ممکن نیست) اما فاصله‌های ابتدای یک خط نادیده گرفته می‌شوند. هر خط فایل به عنوان یک پارامتر خط فرمان خوانده می‌شود (گویی با نقل‌قول تکی نقل شده است). بنابراین، برای مشخص کردن آرگومان‌های خط فرمان جداگانه از خطوط جدید استفاده کنید. .sp خطی که با \(aq\fB#\fP\(aq آغاز شود به عنوان کامنت در نظر گرفته می‌شود. .sp فایل‌های \fB*.ctags\fP در یک پوشه به ترتیب الفبایی بارگذاری می‌شوند. .UNINDENT .UNINDENT .SS "فهرست مسیر پیش‌فرض optlib (Default optlib path list)" .sp \fB$XDG_CONFIG_HOME/ctags\fP، یا \fB$HOME/.config/ctags\fP اگر \fB$XDG_CONFIG_HOME\fP تعریف نشده باشد .sp \fB$HOME/.ctags.d\fP .sp \fB$HOMEDRIVE$HOMEPATH/ctags.d\fP (فقط در MS Windows) .INDENT 0.0 .INDENT 3.5 این پوشه‌ها به طور پیش‌فرض بخش‌هایی از فهرست مسیر optlib هستند. درباره فهرست مسیر optlib به \(dqOption File Options\(dq مراجعه کنید. .sp اگر مجموعه‌ای از گزینه‌ها را دارید که می‌خواهید به صورت شرطی فعال شوند، پوشه‌ای در مسیر فهرست مسیر optlib بسازید و گزینه‌ها را در فایل‌هایی با پسوند .ctags زیر آن پوشه قرار دهید. \fB\-\-options=\fP برای فعال کردن گزینه‌ها است. .sp به عنوان مثال، فرض کنید گزینه‌هایی دارید که می‌خواهید فقط هنگام برچسب‌گذاری درخت کد منبع هسته لینوکس فعال شوند. در این حالت، پوشه \fB$HOME/.ctags.d/linux\fP را ایجاد کنید، گزینه‌ها را در \fB$HOME/.ctags.d/linux/my.ctags\fP قرار دهید. اگر گزینه‌های زیادی دارید، می‌توانید آن‌ها را در چندین فایل مانند \fB$HOME/.ctags.d/linux/device\-driver.ctags\fP و \fB$HOME/.ctags.d/linux/network\-stack.ctags\fP تقسیم کنید. در هر صورت، می‌توانید گزینه‌ها را در فایل(های) .ctags زیر آن پوشه با افزودن \fB\-\-options=linux\fP به خط فرمان ctags خود فعال کنید. .UNINDENT .UNINDENT .SH "همچنین ببینید (SEE ALSO)" .sp برای تعریف (یا گسترش) یک تجزیه‌کننده در یک فایل پیکربندی، ctags\-optlib(7) را ببینید. .sp برای ساختار و قالب فایل‌های برچسب، tags(5) را ببینید. .sp درباره ناسازگاری‌های شناخته‌شده با Exuberant Ctags، ctags\-incompatibilities(7) را ببینید. .sp اگر به نوشتن ابزاری برای پردازش فایل‌های برچسب علاقه‌مندید، ctags\-client\-tools(7) را ببینید. .sp درباره نکات اختصاصی ورودی پایتون، ctags\-lang\-python(7) را ببینید. .sp درباره یک ابزار کلاینت برای جستجوی دودویی یک نام در فایل برچسب مرتب‌شده، readtags(1) را ببینید. .sp وب‌سایت رسمی Universal Ctags در: \% .sp همچنین \fBex(1)\fP، \fBvi(1)\fP، \fBelvis(1)\fP، یا بهتر از همه، \fBvim(1)\fP، ویرایشگر رسمی ctags. برای اطلاعات بیشتر درباره \fBvim(1)\fP، وب‌سایت Vim را ببینید در: \% .sp درباره قالب فایل \fBTAGS\fP، مخزن گیت emacs را ببینید: \%\&. .SH "نویسنده (AUTHOR)" .sp پروژهٔ Universal Ctags \% .sp Darren Hiebert <\%> \% .SH "انگیزه (MOTIVATION)" .sp \(dqهمواره در اندیشهٔ خدمت به یکایک افراد نوع بشر باشید\&.\(dq .sp \(dqهر تلاش و کوششی که انسان از صمیم قلب مبذول دارد، عبادت است؛ اگر برخاسته از والاترین انگیزه‌ها و ارادهٔ خدمت به بشریت باشد\&.\(dq .sp \-\- برگرفته از آثار بهائی .SH "دست‌اندرکاران و قدردانی (CREDITS)" .sp این نسخه از ctags (Universal Ctags) از مخزنی موسوم به fishman\-ctags که توسط Reza Jelveh (رضا جلوه) آغاز شده بود، مشتق شده است\&. .sp مخزن fishman\-ctags خود از Exuberant Ctags برگرفته شده بود\&. .sp برخی از تجزیه‌کننده‌ها از \fBtagmanager\fP پروژهٔ Geany (\%) گرفته شده‌اند\&. .sp نرم‌افزار Exuberant Ctags در اصل از برنامهٔ ctags نوشتهٔ Steve Kirkendall <\%> که همراه با شبیه‌ساز Elvis vi عرضه می‌شد، مشتق شده و الهام گرفته بود (هرچند عملاً هیچ کدی از نسخهٔ اولیه باقی نمانده است)\&. .sp همچنین قدردانی ویژه شایستهٔ Bram Moolenaar <\%>، نویسندهٔ vim است، که بخش عمده‌ای از وقت و انرژی خود را چه در راه توسعهٔ این ویرایشگر به عنوان خدمتی به دیگران و چه در یاری رساندن به کودکان یتیم اوگاندا صرف کرد\&. .sp بخش با عنوان \(dqHOW TO USE WITH GNU EMACS\(dq بی‌شرمانه از صفحهٔ info برنامهٔ GNU etags به سرقت رفته است\&. .\" End of generated man page.