19Jun93 Notes on CTAGS Barry Goldstein
1. This is an upgrade to the Brief version of the UNIX/VI tagging system. I
took off from earlier versions by Yellow Pig XVII, The Shaman, Paul
Verket, Michael Denio, Morris Maynard, Edward Diener, and Sky Schulz. In
particular, I carved up the code found in CTAGS5.ZIP.
CTAGS.C: Source code for the program that prepares the tag files.
CTAGS.COM: That code compiled (Microsoft C6.0a), and linked using setargv
and an improved version of wild.c (so wild card specs like
*e.[ch] will work).
WILDS.OBJ: Small model object for the improved wild card command line
file spec expander.
CTAGS.CB: Source code for the Brief macro that uses the tag files.
CTAGS.CM: That code compiled (Brief for DOS, Version 3.1; macros will
work with OS/2 as well).
GOTO.CB, GOTO.CM: Source code for the macro I assign to Alt-g, to allow
quick access to tags, line numbers, next or previous function
BAG_UTIL.CB, BAG_UTIL.CB: Contains the macro for grabbing a token at or
near the cursor position (GetIdentifier) and some others.
3. To incorporate these into your Brief setup, in your initials macro, add
the following lines:
(autoload "ctags" "ctag" "tag")
(autoload "goto" "goto")
(assign_to_key "" "goto")
(autoload "util" "GetIdentifier")
4. The tagging macros search for tag files (named CTAGS.TAG) in the
the current directory
the directory containing the file in the current edit buffer (if
directories on the path specified by a CTAGS environment variable,
5. Run ctags.com against your source files, in each directory of concern,
re-directing its output to ctags.tag. Run ctags without any arguments
for a usage message; essentially you want something like
ctags *.c *.h >ctags.tag
Flags (see usage) can be interspersed with file specs and apply to
following files. The default is to tag every kind of thing it knows
about. Flags on the command line are indicated by either "-" or "/".
Flags can be combined and the sense of the flags is reversed by a "!".
E.g.: -!seu will turn off structure, enum, and union tagging.
6. Please see the headers of the C and CB files for details of past history,
features, and possible future features.
7. New features:
It now tags functions, #defines, typedefs, structs, unions, enums, and
enum constants; except for functions, command line arguments allow for
not tagging any of these constructs.
It now tags any of these things (in so far as they are legal) WITHIN
code bound by braces, so it will find #defines within a structure
definition, or structs within a function body, and such like.
8. The finite state machine parser is pretty simple minded, but it will work
with all but really idiosyncratic styles of coding. I've toyed with the
idea of re-doing the whole thing using lex/yacc, but have not gotten
quite that obsessed with it. The syntax spec would have to combine parts
of the C pre-processor scan with the compiler scan itself.
9. One possible line of development is to process #if stuff, at least with
symbols defined on the command line (/DDEBUG, e.g.), if not with #defines
within the program. #if, #if[n]def, #if [!]defined, #else, #elif, #endif,
is as far as I'm willing to go, with simple, atomic operands (such as
#ifdef FOO). Anything further would re-invent the pre-processor, and see
item 7 above.
10. The goto macro extends the standard goto_line usually assigned to Alt-g.
It takes a string argument and parses it so:
if null (you just hit Enter), it calls ctag which picks up the token
at the cursor and searches for the tag
if "+" or "-", it searches down or up for the nearest thing that
looks like a function header (same search used in improved
versions of the routines.cb macro)
if numeric, it calls goto_line
if anything else, it calls tag to search for the argument.
Hitting Esc punts.
11. The GetIdentifier macro is a little more generous with what it takes for
a valid token than the C and CB compilers. But then again, ctags isn't
meant to replace LINT or the compiler.
12. I can be reached via Compuserve (73467,1357), though I only check there
weekly. E-mail at [email protected] or via any BBS (Brief
conference) that might be echoed to the Channel 1 BBS in Cambridge, MA
13. You may do whatever you want with these programs. No promises. No
charge. Comments are welcome.
14. Found a bug: a structure definition without a body
struct foo xxx;
screws up scan. Has to quit and not tag such things if it finds a
variable name before the opening brace. Same problem (or worse for enum
or union defined without a body.
15. Fixed another bug, that missed struct, union, enum definitions after
some other "word" (such as static, or _far, _FAR_, etc.).
--------------------------- end of ctags.doc file ---------------------------