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.