开发工具CLI【免费下载链接】ctagsA maintained ctags implementation项目地址https://gitcode.com/gh_mirrors/ct/ctags点击查看免费下载本文以 Universal Ctags 的标签文件tags file格式为核心系统讲解它与传统 Exuberant Ctags 格式的关键差异与新增能力如何开启引用标签reference tags追踪对象被引用的位置、如何使用roles字段描述标签的引用方式、如何通过 pseudo-tags 向客户端程序通告 kinds 与分隔符等元信息以及解析器如何定义专属的 fields、extras 和参数。读完本文你将掌握--extrasr、--fieldsr、--_xformat、--pseudo-tags、--fields-LANG、--extras-LANG、--param-LANG等一组进阶选项的完整用法并能理解它们背后的实现机制可对照 main/field.c、main/ptag.c、main/xtag.c 等源码与 Tmain 下的测试用例验证。一、概述从定义到引用从通用到专属传统 ctags 只收集语言对象被定义DEFINED的位置信息。Universal Ctags 在此基础上扩展出了三条主线引用标签reference tags额外收集对象被引用REFERENCED的位置并用roles字段记录引用方式Pseudo-tags向读取 tags 文件的客户端程序输出机器可读的元信息如 kind 描述、作用域分隔符、输出模式等解析器专属parser specific扩展允许每个解析器定义自己的 fields、extras 与参数通过--fields-LANG、--extras-LANG、--param-LANG精确控制。关于输出格式的整体框架u-ctags、e-ctags、etags、xref、json 五种格式的选择可参考 docs/output-format.rst本文聚焦于标签文件tags file内部格式层面的变化。二、Fkind 的保留你不能自定义的 file kind在编写自己的.ctags配置或 optlib 解析器时不能使用Ffilekind——Universal Ctags 保留它用于为每个输入文件本身生成一个 file 标签--extrasf时输出。这与 Exuberant Ctags 的兼容性约束有关详见ctags-incompatibilities(7)手册页位于 docs/man 目录。如果强行把F用作自定义 kind会与系统保留的 file kind 语义冲突导致行为不可预期。三、引用标签Reference Tags追踪对象被引用的位置3.1 背景与启用方式引用标签特性最初由 shigio 在 Universal Ctags 的 #569 号 issue 中为 GNU GLOBAL 提出。默认情况下 ctags 只输出定义标签启用 extra-tagrreference后引用位置也会被收集并输出。extra 的定义可以在 main/xtag.c 中找到{ false, r, reference, Include reference tags},即r的默认状态是关闭false需显式开启。3.2 传统输出 vs 引用输出以文档中的reftag.c为例#include stdio.h #include foo.h #define TYPE point struct TYPE { int x, y; }; TYPE p; #undef TYPE传统输出只有定义标签$ ctags -o - reftag.c TYPE reftag.c /^#define TYPE /; d file: TYPE reftag.c /^struct TYPE { int x, y; };$/; s file: p reftag.c /^TYPE p;$/; v typeref:typename:TYPE x reftag.c /^struct TYPE { int x, y; };$/; m struct:TYPE typeref:typename:int file: y reftag.c /^struct TYPE { int x, y; };$/; m struct:TYPE typeref:typename:int file:先确认rextra 的存在与状态$ ctags --list-extras | grep ^r r Include reference tags off启用引用标签后的输出$ ctags -o - --extrasr reftag.c TYPE reftag.c /^#define TYPE /; d file: TYPE reftag.c /^#undef TYPE$/; d file: TYPE reftag.c /^struct TYPE { int x, y; };$/; s file: foo.h reftag.c /^#include foo.h/; h p reftag.c /^TYPE p;$/; v typeref:typename:TYPE stdio.h reftag.c /^#include stdio.h/; h x reftag.c /^struct TYPE { int x, y; };$/; m struct:TYPE typeref:typename:int file: y reftag.c /^struct TYPE { int x, y; };$/; m struct:TYPE typeref:typename:int file:对比可见#undef TYPE和两个#includefoo.h、stdio.h是新增的引用标签条目。3.3roles字段记录标签如何被引用roles是 Universal Ctags 新引入的字段用于记录一个标签被引用的方式定义标签的 roles 值为def。该字段在 main/field.c 中注册为 letterr、nameroles[FIELD_ROLES - FIELDS_UCTAGS_START] { .letter r, .name roles, .description Roles, .enabled false, ...而def这个角色名定义在 main/entry.h#define ROLE_DEFINITION_NAME def用--fieldsr开启 roles 字段的输出$ ctags -o - --extrasr --fieldsr reftag.c TYPE reftag.c /^#define TYPE /; d file: TYPE reftag.c /^#undef TYPE$/; d file: roles:undef TYPE reftag.c /^struct TYPE { int x, y; };$/; s file: roles:def foo.h reftag.c /^#include foo.h/; h roles:local p reftag.c /^TYPE p;$/; v typeref:typename:TYPE roles:def stdio.h reftag.c /^#include stdio.h/; h roles:system x reftag.c /^struct TYPE { int x, y; };$/; m struct:TYPE typeref:typename:int file: roles:def y reftag.c /^struct TYPE { int x, y; };$/; m struct:TYPE typeref:typename:int file: roles:def可以看到角色语义非常直观#undef TYPE的角色是undef#include foo.h的角色是local#include stdio.h的角色是system而所有定义标签的角色都是def。3.4 用%R在 xref 输出中区分定义与引用RReference tag marker字段是专门为 GNU GLOBAL 的需求设计的定义标签标记为D引用标签标记为R。该字段只能与--_xformat一起使用自定义 xref 输出格式详见 docs/output-xref.rst$ ctags -x --_xformat%R %-16N %4n %-16F %C --extrasr reftag.c D TYPE 3 reftag.c #define TYPE point D TYPE 4 reftag.c struct TYPE { int x, y; }; D p 5 reftag.c TYPE p; D x 4 reftag.c struct TYPE { int x, y; }; D y 4 reftag.c struct TYPE { int x, y; }; R TYPE 6 reftag.c #undef TYPE R foo.h 2 reftag.c #include foo.h R stdio.h 1 reftag.c #include stdio.h注意--_xformat是提取引用标签的唯一途径tags 输出本身不带D/R标记。3.5 列出所有可用角色--list-roles虽然引用标签的采集框架已经实现但目前只有少数解析器使用它。用--list-roles可以列出所有解析器定义的角色$ ctags --list-roles #LANGUAGE KIND(L/N) NAME ENABLED DESCRIPTION SystemdUnit u/unit Requires on referred in Requires key SystemdUnit u/unit Wants on referred in Wants key SystemdUnit u/unit After on referred in After key SystemdUnit u/unit Before on referred in Before key SystemdUnit u/unit RequiredBy on referred in RequiredBy key SystemdUnit u/unit WantedBy on referred in WantedBy key Yaml a/anchor alias on alias DTD e/element attOwner on attributes owner Automake c/condition branched on used for branching Cobol S/sourcefile copied on copied in source file Maven2 g/groupId dependency on dependency DTD p/parameterEntity elementName on element names DTD p/parameterEntity condition on conditions LdScript s/symbol entrypoint on entry points LdScript i/inputSection discarded on discarded when linking ...各列含义第一列解析器parser名称第二列kind 的字母/名称KIND(L/N)第三列角色名称第四列角色是否启用ENABLED第五列角色描述。角色的启用/禁用通过--roles-LANG.KIND选项控制其命令行语法在 main/options.c 中有完整声明--roles-(LANG|all).(kind|*)[|-][roles|*]同时--list-roles也支持按语言过滤例如--list-rolesC.{header}d见 main/options.c。如果你想在 optlib 解析器中为某个 kind 自定义角色以采集引用标签可以使用 regex 的{role}标志详见 docs/optlib.rst 中关于捕获引用标签的章节。四、Pseudo-tags面向客户端程序的元信息输出Pseudo-tags 是面向 ctags 客户端程序如编辑器插件、GNU GLOBAL的元信息条目以!_TAG_...开头的行出现在 tags 文件头部。其概念详见ctags-client-tools(7)手册页。所有 pseudo-tag 的描述表定义在 main/ptag.c其中每个条目都标注了是否默认启用true/false以及所属类别PTAGF_COMMON/PTAGF_PARSER。4.1TAG_KIND_DESCRIPTION枚举 kind 的字母、名称与描述这是新增的 pseudo-tag默认不输出只有显式指定--pseudo-tagsTAG_KIND_DESCRIPTION才输出。它用于枚举某个语言的 kind字母、名称和描述。输出格式!_TAG_KIND_SEPARATOR!{parser} {letter},{name} /{description}/其中{description}中的反斜杠和斜杠会以反斜杠转义。在 main/ptag.c 中它的注册信息是{ true, TAG_KIND_DESCRIPTION, the letters, names and descriptions of enabled kinds in the language, ptagMakeKindDescriptions, PTAGF_PARSER },注意这里true表示该 pseudo-tag 的定义是内置的但实际输出仍需--pseudo-tagsTAG_KIND_DESCRIPTION显式开启。4.2TAG_KIND_SEPARATOR描述语言内部的 kind 分隔符这也是新增的 pseudo-tag默认不输出需--pseudo-tagsTAG_KIND_SEPARATOR显式开启。它用于描述一个语言中两个 kind 之间放置的分隔符——当--extrasq开启时fully qualified tags如Foo.func会包含这些分隔符分隔符同样用于作用域scope信息。输出格式有两种!_TAG_KIND_SEPARATOR!{parser} {sep} /{upper}{lower}/或根分隔符无 upper!_TAG_KIND_SEPARATOR!{parser} {sep} /{lower}/字段含义{parser}语言名称例如 PHP{lower}下层 kind 的字母{upper}上层 kind 的字母{sep}放置在上层项与下层项之间的分隔符。不带{upper}的格式用于表示根分隔符root separator——即当一个项没有上层作用域时用作其前缀的分隔符。{upper}为*时表示通配该{sep}可与任意上层项搭配。{sep}中的每个反斜杠字符都会被额外转义一个反斜杠。示例输出针对 PHP 输入$ ctags -o - --extrasp --pseudo-tags --pseudo-tagsTAG_KIND_SEPARATOR input.php !_TAG_KIND_SEPARATOR!PHP :: /*c/ ... !_TAG_KIND_SEPARATOR!PHP \\ /c/ ... !_TAG_KIND_SEPARATOR!PHP \\ /nc/ ...逐行解读第一行::用于将某物与 class kind 的项组合第二行class 项位于顶层无上层项时使用\\第三行namespace 项上层与 class 项下层组合时使用\\。当存在多个候选分隔符时ctags 会优先使用更具体的行第三行/nc/的优先级高于第一行/*c/。该 pseudo-tag 的注册见 main/ptag.c测试用例可参考 Tmain/ptag-kind-sep.d/run.sh。4.3TAG_OUTPUT_FILESEP文件名中的分隔符该 pseudo-tag 表示文件名中使用的分隔符斜杠slash或反斜杠backslash。在 Unix 类环境下恒为slash在 Windows 上默认也是slash但当指定--output-formate-tags或--use-slash-as-filename-separatorno时变为backslash。其实现函数ptagMakeCtagsOutputFilesep注册于 main/ptag.c。4.4TAG_OUTPUT_MODE输出模式通告该 pseudo-tag 表示输出模式是u-ctags还是e-ctags由--output-format选项控制对应 main/ptag.c。关于 u-ctags 与 e-ctags 两种模式的兼容性与各自弱点的讨论参见 docs/output-format.rst。五、长输入行的 pattern 截断当输入行过长时tags 文件中的 pattern 字段会被截断截断长度由--pattern-length-limitN选项控制详见ctags(1)手册页。对应地Universal Ctags 会通过TAG_PATTERN_LENGTH_LIMITpseudo-tag 通告该限制值见 main/ptag.c。六、解析器专属字段Parser Specific Fields6.1 动机从通用字段到语言专属字段一个标签的基本信息是名称name、输入文件名input file和定位模式pattern此外还会附加language:、signature:等可选字段。在 Exuberant Ctags 中字段对所有语言通用Universal Ctags 扩展了这一概念——解析器可以定义自己的专属字段。该扩展由 pragmaware 在 #857 号 issue 中提出。用于列出和启停字段的选项也随之扩展。在--list-fields的输出中字段的属主会打印在LANGUAGE列$ ctags --list-fields #LETTER NAME ENABLED LANGUAGE XFMT DESCRIPTION ... - end off C TRUE end lines of various constructs - properties off C TRUE properties (static, inline, mutable,...) - end off C TRUE end lines of various constructs - template off C TRUE template parameters - captures off C TRUE lambda capture list - properties off C TRUE properties (static, virtual, inline, mutable,...) - sectionMarker off reStructuredText TRUE character used for declaring section - version off Maven2 TRUE version of artifact例如sectionMarker字段的属主是 reStructuredText 解析器而end字段同时被 C 和 C 两个解析器拥有。6.2 按语言过滤列表--list-fieldsLANGUAGE--list-fields接受一个可选参数LANGUAGE指定后只打印该解析器的字段$ ctags --list-fieldsMaven2 #LETTER NAME ENABLED LANGUAGE XFMT DESCRIPTION - version off Maven2 TRUE version of artifact6.3 启停解析器专属字段--fields-LANG解析器专属字段只有长名称、没有字母因此必须用名称配合--fields-LANG启停。例如开启 reStructuredText 解析器的sectionMarker字段$ ctags --fields-reStructuredText{sectionMarker} ...6.4 通配符批量启停与版本兼容通配符*也可以用于启停解析器专属字段开启 C 解析器的所有字段$ ctags --fields-C* ...*还可以用于指定语言为所有拥有end字段的语言开启它$ ctags --fields-*{end} ...用通配符指定语言的好处是避免 Universal Ctags 自身版本间的不兼容SELF INCOMPATIBILITY在开发过程中某个解析器专属字段可能因对其他语言也有意义而被提升promote为通用字段这种提升会破坏--fields-LANG的命令行兼容性而LANG位置使用通配符可以规避这种影响。值得强调的是引入解析器专属字段不会改变 tags 文件格式仍然沿用fieldname:value的写法字段属主名永远不会作为前缀出现——标签的language:字段会标识其属主。七、解析器专属 Extras7.1 概念与启停语法如 Exuberant Ctags 手册所述--extras选项控制是否包含某些额外的标签条目Universal Ctags 保留该选项并扩展为允许解析器定义自己的 extra 标志用--extras-LANG[|-]{...}控制。--list-extras的输出中同样有LANGUAGE列NONE表示该 extra 是语言无关的通用仍用--extras控制$ ctags --list-extras #LETTER NAME ENABLED LANGUAGE DESCRIPTION F fileScope TRUE NONE Include tags ... f inputFile FALSE NONE Include an entry ... p pseudo FALSE NONE Include pseudo tags q qualified FALSE NONE Include an extra ... r reference FALSE NONE Include reference tags g guest FALSE NONE Include tags ... - whitespaceSwapped TRUE Robot Include tags swapping ...这些通用 extra 的具体定义可在 main/xtag.c 中查看包括fileScope、inputFile、pseudo、qualified、reference、guest、subparser、anonymous、nulltag等。7.2 实战Robot 解析器的whitespaceSwapped以whitespaceSwapped为例它的语言是Robot默认启用但可以用--extras-Robot-{whitespaceSwapped}关闭$ cat input.robot *** Keywords *** its ok to be correct Python_keyword_2 $ ctags -o - input.robot its ok to be correct input.robot /^its ok to be correct$/; k its_ok_to_be_correct input.robot /^its ok to be correct$/; k $ ctags -o - --extras-Robot-{whitespaceSwapped} input.robot its ok to be correct input.robot /^its ok to be correct$/; k关闭后its_ok_to_be_correct不再出现在输出中。也就是说这个名称是在 extra 标志启用时由its ok to be correct派生出来的把空格替换为下划线。7.3 讨论什么是额外标签条目本节偏向解析器开发者正式文档中标注为应移入开发者文档。目前业界对extra 标签条目没有明确统一的定义。Universal Ctags 内部有两个想法ideas而非 definitions因为现有解析器并未全部遵循想法一如果一个标签条目的名称原样出现在输入文件中它就不是 extra。要控制这类条目的输出应该用经典的--kind-LANG[|-]...而不是--extras。--extrasq控制的 fully qualified tags 是这一想法最好的例证$ cat input.py class Foo: def func (self): pass $ ctags -o - --extrasq --fieldsE input.py Foo input.py /^class Foo:$/; c Foo.func input.py /^ def func (self):$/; m class:Foo extra:qualified func input.py /^ def func (self):$/; m class:FooFoo和func都原样出现在input.py中因此不是 extra而Foo.func在输入文件中并不以原样出现它是 ctags 生成的 qualified extra 标签条目extra:qualified字段标明来源。Robot 解析器的whitespaceSwapped也符合这一想法。不过作者也坦承并非所有解析器都遵循比如 C 中operator原样在input.cc中但 ctags 输出的却是带空格的operator $ cat input.cc class A { A operator (int); }; $ ctags --kinds-all* --fields -o - input.cc A input.cc /^class A$/ operator input.cc /^ A operator (int);$/注意关键字operator与运算符之间的空格——这是想法一的一个例外。想法二如果一个标签的包含与否无法用--kind-LANG[|-]...很好地控制那么它可能适合作为 extra。以 C 语言函数为例$ cat input.c static int foo (void) { return 0; } int bar (void) { return 1; } $ ctags --sortno -o - --extrasF input.c foo input.c /^static int foo (void)$/; f typeref:typename:int file: bar input.c /^int bar (void)$/; f typeref:typename:int $ ctags -o - --extras-F input.c foo input.c /^static int foo (void)$/; f typeref:typename:intfoo只有在Fextra 开启时才输出。foo和bar都是函数它们的包含与否本可由 C 语言的fkind--kind-C[|-]f控制static修饰符与隐式extern修饰符之间的差异则由Fextra 标志处理。概括来说kind 概念用于处理语言对象的种类函数、变量、宏、类型等extra 概念用于处理其他方面如 static/extern 这类作用域属性。但解析器开发者也可以另辟蹊径——例如为解析器准备staticFunction与exportedFunction两个 kind 来替代引入专属 extra。因此想法二只是指导原则具体采用哪种方式由解析器开发者根据目标语言自行权衡。最后提醒如果--extras控制的是包含与否那么当你要控制的不是包含问题而是更细的细节时--param-LANG可以作为最后的兜底手段。八、解析器专属参数Parser Specific Parameters为了控制解析器的细节行为Universal Ctags 引入--param-LANG。--kinds-LANG、--fields-LANG、--extras-LANG都可以定制指定解析器的行为而--param-LANG用于处理这些选项kinds、fields、extras无法很好覆盖的解析器方面。每个解析器定义一组参数每个参数有名称并接受一个参数值。设置参数的记法--param-LANG.namearg示例--param-CPreProcessor.if0true这里if0是 CPreProcessor 解析器的一个参数名true是其取值——含义是是否检查#if 0分支内的代码。所有可用参数用--list-params列出$ ctags --list-params #PARSER NAME DESCRIPTION CPreProcessor if0 examine code within #if 0 branch (true or [false]) CPreProcessor ignore a token to be specially handled截至文档编写时只有 CPreProcessor 解析器定义了参数括号中的[false]表示该参数的默认值。九、实践建议与小结追踪引用关系对支持角色的语言用--extrasr --fieldsr输出引用标签及角色需要区分定义/引用时配合--_xformat使用%R。元信息通告需要让编辑器、LSP 或 GLOBAL 类工具理解 tags 文件结构时按需开启TAG_KIND_DESCRIPTION、TAG_KIND_SEPARATOR等 pseudo-tags而不是依赖默认输出。按语言定制解析器专属的 fields、extras、params 是通用选项 语言限定的组合拳优先用--fields-LANG、--extras-LANG、--param-LANG需要跨版本稳定时在LANG位置使用通配符*。验证手段上述所有行为都可以在仓库的测试用例中找到实证例如 Tmain/ptag-kind-sep.d/run.shTAG_KIND_SEPARATOR 输出、Tmain/multi-roles.d/run.shroles 启停与 CTagsSelfTest 语言的引用标签、Tmain/list-roles.d/run.sh 与 Tmain/roledef.d/run.sh角色定义与列出等源码层面的注册表分别在 main/field.c、main/xtag.c 与 main/ptag.c。理解并善用这些扩展你可以让 Universal Ctags 的 tags 输出从单纯的符号索引升级为带有引用关系、语言结构与元数据语义的结构化索引为上层工具提供更丰富的分析基础。赞分享开发工具CLI【免费下载链接】ctagsA maintained ctags implementation项目地址https://gitcode.com/gh_mirrors/ct/ctags点击查看免费下载相关推荐Universal Ctags 完全指南ctags.1 手册精解——从命令行选项到标签文件格式Universal Ctags 完全指南ctags.1 手册精解——从命令行选项到标签文件格式 导读 本文是对 Universal Ctags 官方手册 do开发工具CLIUniversal Ctags 的 SystemTap 脚本标签解析ctags-lang-systemtap(7) 手册深度解读Universal Ctags 的 SystemTap 脚本标签解析ctags lang systemtap 7 手册深度解读 本文围绕 Universal开发工具CLIUniversal Ctags 对 Fortran 源码的标签生成指南ctags-lang-fortran 手册与 linkName 额外标签解析Universal Ctags 对 Fortran 源码的标签生成指南ctags lang fortran 手册与 linkName 额外标签解析 本指南以开发工具CLI上一篇awesome-writing完全指南让开发者写出更友好的技术文档的终极资源下一篇释放3GB存储空间DriverStore Explorer的智能驱动管理解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考