Guides/Ctags

Overview

Ctag provide a means of jumping to definition of names similar to that provided by Find-in-Files in J IDE. Some background information for ctags in wikipedia.

Some confusing terms

ctags - a program to generate tags, available in Linux and Windows.

tags, Tags - a file in top-level directory that contain index of defintion of names under that directory.

jtags - a Linux shell script to generate tags. Depended on other tools such as awk and sort.

jtags - a J addons in ~addons/general/jtags which provide some helper utilities to call ctags and jtags shell scripts.

Tags_j_ - a J noun contained boxed list of location of tags files referenced by jconsole and gtkide. Read from ~config/base.cfg during booting, default to '~Project/tags';'~install/tags'

How to use (jconsole and gtkide)

The locale 'ctag' will be loaded during booting and provides some public verbs.

cleartags

y is ignored.
Clear internal tags cache so that it will be rebuilt automatically when needed next time.

loadtags y

y either a string or boxed list of strings or empty.
Rebuild internal tags cache using tags file specified in Tag_j_ if y is empty. Otherwise rebuilt using the tags file(s) specified in y.

x tagopen y

y either a string or boxed list of strings.
Open the file containing the definition of y using external editor Editor_j_ or Editor_nox_j_. If there are several occurrences of definition, jump to the x-th (0-based) occurrence, jump to the 0-th when x is elided.

x tagselect y

y either a string or boxed list of strings.
x (default 0) if x=1 then include partial matches.
Return a character matrix for every definition of y.

x ta y

y either a string or boxed list of strings.
x (default 0) if x=1 then include partial matches.
Similar to monad tagopen but prints a list of definitions when there are more than one occurrence. It will then wait for user input to jump to the required occurrence.

NB. try these
ta 'load'
1 ta 'load'

tagcp y

Return boxed list of tags that partially match y

NB. try these
tagcp 'load'
tagcp 'tag';'deb'

How to use (gtkide specific)

x tagtab y

Open the file containing the definition of y in an edit tab. If there are several occurrences of definition, jump to the x-th (0-based) occurrence, jump to the 0-th when x is elided.

x tag y

x (default 0) if x=1 then include partial matches.
Similar to monad tagtab but will open a listbox for choosing when there are more than one occurrence.

editor integration

Place cursor on a name or select a name, then either press Control-] or mouse right click to bring up a popup menu. Choose the choice Find Tag. It will jump to the definition or open a listbox for choosing when there are more than one occurrence.

Prepare to use

install package jtags

This package is not needed if you can already generate tags files outside jconsole or gtkide.

require 'pacman'
'update' jpkg ''
'install' jpkg 'general/jtags'

Or install using the pacman gui interface in gtkide.

edit Tags_j_

Edit the noun Tags in base.cfg to contain all tags files wanted, eg., if your project tree is under /home/john/myproject, then change to

Tag=: '/home/john/myproject/tags';'~Project/tags';'~install/tags'

put the more relevant tags files in the beginning of the list.

generate tags files

require 'jtags'
jtags ''

In gtkide, the above two lines can be run by clicking the menu item Tools|Generate Tags.

Alternatively, manually generate all tags files and then reload internal tags cache either by restarting J or by

loadtags ''

Tags files are snapshots so that it will become obsolete after source files changed. Remember to regenerate tags files again from time to time.

---

Contributed by Bill Lam.