# Universal Ctags Hacking Guide

Version:

  Draft

Authors:

  Universal Ctags developers

Web Page:

  https://ctags.io/

Universal Ctags (abbreviated as u-ctags) is a maintained implementation of `ctags`. `ctags` generates an index (or tag) file of language objects found in source files for programming languages. This index makes it easy for text editors and other tools to locate the indexed items.

Exuberant Ctags (e-ctags) maintained by Darren Hiebert, the ancestor of Universal Ctags, improved traditional ctags with multi-language support, the ability for the user to define new languages searched by regular expressions (called optlib in Universal Ctags), and the ability to generate emacs-style TAGS files. But the activity of the project unfortunately stalled.

Universal Ctags has the objective of continuing the development of Exuberant Ctags. Reza Jelveh <reza.jelveh@gmail.com> initially created a personal fork of Exuberant Ctags on GitHub. As interest and participation grew, it was decided to move development to a dedicated project as Universal Ctags. The goal of this project is to maintain a common/unified working space where people interested in making ctags better can work together.

Some of the major features of Universal Ctags are:

- greater number of supported languages

- better language support

    - new extended C/C++ language parser, etc.

- fully extended optlib (a feature to define a new language parser from a command line)

- interactive mode (experimental)

The primary documents of Universal Ctags are man pages. Users should first consult the ctags(1), and other man pages if necessary.

This guide, which also includes the man pages, is primarily for developers and provides additional information to the man pages, including experimental features.

This is a draft document. Proofreading and pull-requests are welcome!

- Building ctags
  - Building with configure (*nix including GNU/Linux)
  - Building/hacking/using on MS-Windows
  - Building on Mac OS
- Man pages
  - ctags(1)
  - ctags-json-output(5)
  - tags(5)
  - ctags-optlib(7)
  - ctags-client-tools(7)
  - ctags-incompatibilities(7)
  - ctags-faq(7)
  - ctags-lang-asm(7)
  - ctags-lang-autoit(7)
  - ctags-lang-automake(7)
  - ctags-lang-c(7)
  - ctags-lang-c++(7)
  - ctags-lang-clojure(7)
  - ctags-lang-cuda(7)
  - ctags-lang-elm(7)
  - ctags-lang-emacslisp(7)
  - ctags-lang-fortran(7)
  - ctags-lang-gdscript(7)
  - ctags-lang-i18nrubygem(7)
  - ctags-lang-iPythonCell(7)
  - ctags-lang-inko(7)
  - ctags-lang-javascript(7)
  - ctags-lang-julia(7)
  - ctags-lang-kconfig(7)
  - ctags-lang-ldscript(7)
  - ctags-lang-lex(7)
  - ctags-lang-lisp(7)
  - ctags-lang-make(7)
  - ctags-lang-markdown(7)
  - ctags-lang-meson(7)
  - ctags-lang-powershell(7)
  - ctags-lang-python(7)
  - ctags-lang-r(7)
  - ctags-lang-rmarkdown(7)
  - ctags-lang-scheme(7)
  - ctags-lang-scss(7)
  - ctags-lang-sql(7)
  - ctags-lang-systemtap(7)
  - ctags-lang-tcl(7)
  - ctags-lang-terraform(7)
  - ctags-lang-verilog(7)
  - ctags-lang-vim(7)
  - readtags(1)
- Parsers
  - Asm parser
  - CMake parser
  - The new C/C++ parser
  - The new GDScript parser
  - The new HTML parser
  - puppetManifest parser
  - The new Python parser
  - The new Tcl parser
  - The V parser
  - The Vim parser
  - XSLT parser
- Option files
  - Order of loading option files
  - `--options=PATHNAME` option
  - Tips for writing an option file
  - Difference from Exuberant Ctags
- Output formats
  - Changes to the tags file format
  - Xref output
- Running multiple parsers on an input file
  - Guest parser: Applying a parser to specified areas of input file
  - Subparser: Tagging definitions of higher (upper) level language
- Interactive mode
  - generate-tags
  - sandbox submode
- NEWS
  - version ?.?.?
  - version 6.2.0
  - version 6.1.0
  - version 6.0.0
- Extending ctags with Regex parser (optlib)
  - Language definition flags
  - Regular expression (regex) engine
  - Perl-compatible regular expressions (PCRE2) engine
  - Regex option argument flags
  - Overriding the letter for file kind
  - Generating fully qualified tags automatically from scope information
  - Multi-line pattern match
  - Advanced pattern matching with multiple regex tables
  - Scheduling a guest parser with `_guest` regex flag
  - Defining a subparser
  - Making tags of foreign languages
  - Translating an option file into C source code (optlib2c)
- Optscript, a programming language for extending optlib parsers
  - Preparation for learning
  - Syntax extension
  - The `optscript` command
  - Optscript in ctags
  - Recipes
  - Difference between Optscript and PostScript
- Extending ctags with a parser written in C
  - Writing a parser in C
  - Input text stream
  - Output tag stream
  - tokenInfo API
  - Multiple parsers
  - PackCC compiler-compiler
  - Null tags
  - Automatic parser guessing (TBW)
  - Managing regular expression parsers (TBW)
  - Ghost kind in regex parser (TBW)
- Testing ctags
  - Tmain: a facility for testing main part
  - Tinst: installation test
  - Fussy syntax checking
  - Finding performance bottleneck
  - Checking coverage
  - Running cppcheck
- Testing a parser
  - Units test facility
  - Reviewing the result of Units test
  - Semi-fuzz(Fuzz) testing
  - Noise testing
  - Chop and slap testing
  - Input validation for Units
  - Testing examples in language specific man pages
- Testing readtags
- Request for extending a parser (or Reporting a bug of parser)
  - Before reporting
  - The content of report
  - An example of good report
- Contributions
  - Basic rules
  - Before You Start
  - Developing a parser
  - Testing
  - Writing Documents
  - Committing and submitting a pull request
  - Rules for reviewing a pull request
- How to release a new version
- Relationship between other projects
  - Other tagging engines
  - Software using ctags
  - Other interesting ctags repositories
  - Tracking other projects
- Who we are