ctags: Difference between revisions

Revision as of 12:03, 16 October 2017

Example of auto-completion menu provided by the PHP omnicomplete extension in ViM

Ctags is a tool that generates a tag file of names found in source files. In Moodle, it can be used to index PHP functions, variables, classes and so on. These tags allow definitions to be quickly and easily located by a text editor such as vim.

In the past, the Moodle source code contained a generated tags file to be used directly. If you use this utility these days, you have to generate (and keep up-to-date) the tags file yourself. Please note that most modern IDEs do not need this to provide the functionality.

Obtaining ctags

There are several implementations of the original ctags available these days. Most Moodle developers who use ctags, found https://ctags.io/ a good one.

Generating a tags file

Example of how the tags file can be generated, tuned for Moodle development:

   # cd /path/to/moodle/dirroot/
   # ctags -R --languages=php --fields=+aimS --php-kinds=cdfint --tag-relative=yes --totals=yes --exclude=tags --exclude="config*.php" \
       --exclude="lang/*" --exclude="install/lang/*" --exclude="vendor" --exclude="node_modules" --exclude="moodledata/*" \
       --exclude="phpunit.xml" --exclude=".git/*" --extra=+q

but there are alternative ways too - such as this one.

Using in ViM

The vim editor provides the support for tags file. If you have the tags file generated in the root of the Moodle code, you will probably want something like this in your vimrc file.

set tags=tags,../tags,../../tags,../../../tags,../../../../tags,../../../../../tags,../../../../../../tags,../../../../../../../tags

Once loaded, you can use the tags file to quickly jump and navigate over the Moodle code base:

Place the cursor over the tag (e.g., function name) and press CTRL+].
Type the command :tag <tagname>
To return to your previous location, press CTRL+t

Please refer to your editor help for details and other options.

Integration with PHP omnicomplete

Ctags also play well the the ViM omnicomplete.

@@ Line 1: / Line 1: @@
-== Moodle 1.9.6 and newer ==
+[[Image:vimomnisearch.png|thumb|Example of auto-completion menu provided by the PHP omnicomplete extension in ViM]]
-As of Moodle 1.9.6 the tags file is no longer included in the Moodle distribution. Instead a file tags.txt is included providing instructions on creating the tag file yourself. The text of this file is as follows:
-<pre>
+'''Ctags''' is a tool that generates a tag file of names found in source files. In Moodle, it can be used to index PHP functions, variables, classes and so on. These tags allow definitions to be quickly and easily located by a text editor such as [[vim]].
-Generating a tags file
-======================
-If you need a tags file so that you can jump around Moodle code
+In the past, the Moodle source code contained a generated tags file to be used directly. If you use this utility these days, you have to generate (and keep up-to-date) the tags file yourself. Please note that most modern IDEs do not need this to provide the functionality.
-easily in your editor (eg vim or emacs), you can generate one:
-Exuberant ctags (default on Linux, can be compiled on other platforms):
+== Obtaining ctags ==
-----------------------------------------------------------------------
-ctags -R --languages=php --exclude="CVS" --php-kinds=f \
+There are several implementations of the original ctags available these days. Most Moodle developers who use ctags, found https://ctags.io/ a good one.
---regex-PHP='/abstract class ([^ ]*)/\1/c/' \
---regex-PHP='/interface ([^ ]*)/\1/c/' \
---regex-PHP='/(public |static |abstract |protected |private )+function ([^ (]*)/\2/f/'
+== Generating a tags file ==
-Downloading the tags file
+Example of how the tags file can be generated, tuned for Moodle development:
-=========================
-If for some reason you can't generate one, you can download a recent one from here:
+    # cd /path/to/moodle/dirroot/
+    # ctags -R --languages=php --fields=+aimS --php-kinds=cdfint --tag-relative=yes --totals=yes --exclude=tags --exclude="config*.php" \
+        --exclude="lang/*" --exclude="install/lang/*" --exclude="vendor" --exclude="node_modules" --exclude="moodledata/*" \
+        --exclude="phpunit.xml" --exclude=".git/*" --extra=+q
-http://download.moodle.org/tags            (for head)
+but there are alternative ways too - such as [https://pastebin.com/V2EPbR4z this one].
-http://download.moodle.org/stable19/tags  (Moodle 1.9.x)
-http://download.moodle.org/stable18/tags  (Moodle 1.8.x)
-</pre>
-== Using tags with Vim ==
+== Using in ViM ==
-In order to use the tags file with the Vim editor (on a Unix style system), you should first add the following line to the file '''.vimrc''' in your home directory:
+The [[vim]] editor provides the support for tags file. If you have the <tt>tags</tt> file generated in the root of the Moodle code, you will probably want something like this in your <tt>vimrc</tt> file.
-    set tags=tags;/
+ set tags=tags,../tags,../../tags,../../../tags,../../../../tags,../../../../../tags,../../../../../../tags,../../../../../../../tags
-If .vimrc does not exist you should create it. This directive will force Vim to search for the tags file in the directory tree in which you are working (it searches up from where you are) so it will work for multiple versions of the code automatically.
+Once loaded, you can use the tags file to quickly jump and navigate over the Moodle code base:
-=== How to jump to a tag with Vim ===
+* Place the cursor over the tag (e.g., function name) and press <tt>CTRL+]</tt>.
+* Type the command <tt>:tag <tagname></tt>
+* To return to your previous location, press <tt>CTRL+t</tt>
-There are a number of things you can do:
+Please refer to your editor help for details and other options.
-* Place the cursor over the tag (e.g., function name) and press '''CTRL+]'''.
+=== Integration with PHP omnicomplete ===
-* Type the command ''':tag <tagname>'''
-* To open in a new editor window type the command ''':stag <tagname>'''
-* To return to your previous location type '''CTRL+t'''
-== Using tags with Emacs ==
+Ctags also play well the the ViM omnicomplete.
-To create the TAGS file add a -e to the command of tags.txt, like this:
-<pre>
-ctags -e -R --languages=php --exclude="CVS" --php-kinds=f \
---regex-PHP='/abstract class ([^ ]*)/\1/c/' \
---regex-PHP='/interface ([^ ]*)/\1/c/' \
---regex-PHP='/(public |static |abstract |protected |private )+function ([^ (]*)/\2/f/'
-</pre>
-For instructions about how to use it look to the emacs wiki page [http://www.emacswiki.org/emacs/EmacsTags EmacsTags]
+* [https://github.com/shawncplus/phpcomplete.vim PHP omnicompletion]
+* [https://pastebin.com/Q4N52z6h Example of configuration]
 ==See also==
-* [http://www.vim.org/tips/tip.php?tip_id=94 Vim tags usage tip]
+* [http://www.emacswiki.org/emacs/EmacsTags EmacsTags]
-* [http://vimdoc.sourceforge.net/htmldoc/usr_29.html#29.1 Vim documentation: Using tags]
-* [http://vimdoc.sourceforge.net/htmldoc/tagsrch.html Vim documentation: Tags and special searches]
 [[Category:Developer tools]]

Documentation