84252
|
1 @c This is part of the Emacs manual.
|
|
2 @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000,
|
|
3 @c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
|
|
4 @c See file emacs.texi for copying conditions.
|
|
5 @node Maintaining, Abbrevs, Building, Top
|
|
6 @chapter Maintaining Large Programs
|
|
7
|
|
8 This chapter describes Emacs features for maintaining large
|
|
9 programs. The version control features (@pxref{Version Control}) are
|
|
10 also particularly useful for this purpose.
|
|
11
|
|
12 @menu
|
|
13 * Change Log:: Maintaining a change history for your program.
|
|
14 * Format of ChangeLog:: What the change log file looks like.
|
|
15 * Tags:: Go direct to any function in your program in one
|
|
16 command. Tags remembers which file it is in.
|
|
17 @ifnottex
|
|
18 * Emerge:: A convenient way of merging two versions of a program.
|
|
19 @end ifnottex
|
|
20 @end menu
|
|
21
|
|
22 @node Change Log
|
|
23 @section Change Logs
|
|
24
|
|
25 A change log file contains a chronological record of when and why you
|
|
26 have changed a program, consisting of a sequence of entries describing
|
|
27 individual changes. Normally it is kept in a file called
|
|
28 @file{ChangeLog} in the same directory as the file you are editing, or
|
|
29 one of its parent directories. A single @file{ChangeLog} file can
|
|
30 record changes for all the files in its directory and all its
|
|
31 subdirectories.
|
|
32
|
|
33 @cindex change log
|
|
34 @kindex C-x 4 a
|
|
35 @findex add-change-log-entry-other-window
|
|
36 The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
|
|
37 file for the file you are editing
|
|
38 (@code{add-change-log-entry-other-window}). If that file is actually
|
|
39 a backup file, it makes an entry appropriate for the file's
|
|
40 parent---that is useful for making log entries for functions that
|
|
41 have been deleted in the current version.
|
|
42
|
|
43 @kbd{C-x 4 a} visits the change log file and creates a new entry
|
|
44 unless the most recent entry is for today's date and your name. It
|
|
45 also creates a new item for the current file. For many languages, it
|
|
46 can even guess the name of the function or other object that was
|
|
47 changed.
|
|
48
|
|
49 @vindex add-log-keep-changes-together
|
|
50 When the variable @code{add-log-keep-changes-together} is
|
|
51 non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file
|
|
52 rather than starting a new item.
|
|
53
|
|
54 @vindex add-log-always-start-new-record
|
|
55 If @code{add-log-always-start-new-record} is non-@code{nil},
|
|
56 @kbd{C-x 4 a} always makes a new entry, even if the last entry
|
|
57 was made by you and on the same date.
|
|
58
|
|
59 @vindex change-log-version-info-enabled
|
|
60 @vindex change-log-version-number-regexp-list
|
|
61 @cindex file version in change log entries
|
|
62 If the value of the variable @code{change-log-version-info-enabled}
|
|
63 is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the
|
|
64 change log entry. It finds the version number by searching the first
|
|
65 ten percent of the file, using regular expressions from the variable
|
|
66 @code{change-log-version-number-regexp-list}.
|
|
67
|
|
68 @cindex Change Log mode
|
|
69 @findex change-log-mode
|
|
70 The change log file is visited in Change Log mode. In this major
|
|
71 mode, each bunch of grouped items counts as one paragraph, and each
|
|
72 entry is considered a page. This facilitates editing the entries.
|
|
73 @kbd{C-j} and auto-fill indent each new line like the previous line;
|
|
74 this is convenient for entering the contents of an entry.
|
|
75
|
|
76 @findex change-log-merge
|
|
77 You can use the command @kbd{M-x change-log-merge} to merge other
|
|
78 log files into a buffer in Change Log Mode, preserving the date
|
|
79 ordering of entries.
|
|
80
|
|
81 Version control systems are another way to keep track of changes in your
|
|
82 program and keep a change log. @xref{Log Buffer}.
|
|
83
|
|
84 @node Format of ChangeLog
|
|
85 @section Format of ChangeLog
|
|
86
|
|
87 A change log entry starts with a header line that contains the current
|
|
88 date, your name, and your email address (taken from the variable
|
|
89 @code{add-log-mailing-address}). Aside from these header lines, every
|
|
90 line in the change log starts with a space or a tab. The bulk of the
|
|
91 entry consists of @dfn{items}, each of which starts with a line starting
|
|
92 with whitespace and a star. Here are two entries, both dated in May
|
|
93 1993, with two items and one item respectively.
|
|
94
|
|
95 @iftex
|
|
96 @medbreak
|
|
97 @end iftex
|
|
98 @smallexample
|
|
99 1993-05-25 Richard Stallman <rms@@gnu.org>
|
|
100
|
|
101 * man.el: Rename symbols `man-*' to `Man-*'.
|
|
102 (manual-entry): Make prompt string clearer.
|
|
103
|
|
104 * simple.el (blink-matching-paren-distance):
|
|
105 Change default to 12,000.
|
|
106
|
|
107 1993-05-24 Richard Stallman <rms@@gnu.org>
|
|
108
|
|
109 * vc.el (minor-mode-map-alist): Don't use it if it's void.
|
|
110 (vc-cancel-version): Doc fix.
|
|
111 @end smallexample
|
|
112
|
|
113 One entry can describe several changes; each change should have its
|
|
114 own item, or its own line in an item. Normally there should be a
|
|
115 blank line between items. When items are related (parts of the same
|
|
116 change, in different places), group them by leaving no blank line
|
|
117 between them.
|
|
118
|
|
119 You should put a copyright notice and permission notice at the
|
|
120 end of the change log file. Here is an example:
|
|
121
|
|
122 @smallexample
|
|
123 Copyright 1997, 1998 Free Software Foundation, Inc.
|
|
124 Copying and distribution of this file, with or without modification, are
|
|
125 permitted provided the copyright notice and this notice are preserved.
|
|
126 @end smallexample
|
|
127
|
|
128 @noindent
|
|
129 Of course, you should substitute the proper years and copyright holder.
|
|
130
|
|
131 @node Tags
|
|
132 @section Tags Tables
|
|
133 @cindex tags table
|
|
134
|
|
135 A @dfn{tags table} is a description of how a multi-file program is
|
|
136 broken up into files. It lists the names of the component files and the
|
|
137 names and positions of the functions (or other named subunits) in each
|
|
138 file. Grouping the related files makes it possible to search or replace
|
|
139 through all the files with one command. Recording the function names
|
|
140 and positions makes possible the @kbd{M-.} command which finds the
|
|
141 definition of a function by looking up which of the files it is in.
|
|
142
|
|
143 Tags tables are stored in files called @dfn{tags table files}. The
|
|
144 conventional name for a tags table file is @file{TAGS}.
|
|
145
|
|
146 Each entry in the tags table records the name of one tag, the name of the
|
|
147 file that the tag is defined in (implicitly), and the position in that
|
|
148 file of the tag's definition. When a file parsed by @code{etags} is
|
|
149 generated from a different source file, like a C file generated from a
|
|
150 Cweb source file, the tags of the parsed file reference the source
|
|
151 file.
|
|
152
|
|
153 Just what names from the described files are recorded in the tags table
|
|
154 depends on the programming language of the described file. They
|
|
155 normally include all file names, functions and subroutines, and may
|
|
156 also include global variables, data types, and anything else
|
|
157 convenient. Each name recorded is called a @dfn{tag}.
|
|
158
|
|
159 @cindex C++ class browser, tags
|
|
160 @cindex tags, C++
|
|
161 @cindex class browser, C++
|
|
162 @cindex Ebrowse
|
|
163 See also the Ebrowse facility, which is tailored for C++.
|
|
164 @xref{Top,, Ebrowse, ebrowse, Ebrowse User's Manual}.
|
|
165
|
|
166 @menu
|
|
167 * Tag Syntax:: Tag syntax for various types of code and text files.
|
|
168 * Create Tags Table:: Creating a tags table with @code{etags}.
|
|
169 * Etags Regexps:: Create arbitrary tags using regular expressions.
|
|
170 * Select Tags Table:: How to visit a tags table.
|
|
171 * Find Tag:: Commands to find the definition of a specific tag.
|
|
172 * Tags Search:: Using a tags table for searching and replacing.
|
|
173 * List Tags:: Listing and finding tags defined in a file.
|
|
174 @end menu
|
|
175
|
|
176 @node Tag Syntax
|
|
177 @subsection Source File Tag Syntax
|
|
178
|
|
179 Here is how tag syntax is defined for the most popular languages:
|
|
180
|
|
181 @itemize @bullet
|
|
182 @item
|
|
183 In C code, any C function or typedef is a tag, and so are definitions of
|
|
184 @code{struct}, @code{union} and @code{enum}.
|
|
185 @code{#define} macro definitions, @code{#undef} and @code{enum}
|
|
186 constants are also
|
|
187 tags, unless you specify @samp{--no-defines} when making the tags table.
|
|
188 Similarly, global variables are tags, unless you specify
|
|
189 @samp{--no-globals}, and so are struct members, unless you specify
|
|
190 @samp{--no-members}. Use of @samp{--no-globals}, @samp{--no-defines}
|
|
191 and @samp{--no-members} can make the tags table file much smaller.
|
|
192
|
|
193 You can tag function declarations and external variables in addition
|
|
194 to function definitions by giving the @samp{--declarations} option to
|
|
195 @code{etags}.
|
|
196
|
|
197 @item
|
|
198 In C++ code, in addition to all the tag constructs of C code, member
|
|
199 functions are also recognized; member variables are also recognized,
|
|
200 unless you use the @samp{--no-members} option. Tags for variables and
|
|
201 functions in classes are named @samp{@var{class}::@var{variable}} and
|
|
202 @samp{@var{class}::@var{function}}. @code{operator} definitions have
|
|
203 tag names like @samp{operator+}.
|
|
204
|
|
205 @item
|
|
206 In Java code, tags include all the constructs recognized in C++, plus
|
|
207 the @code{interface}, @code{extends} and @code{implements} constructs.
|
|
208 Tags for variables and functions in classes are named
|
|
209 @samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
|
|
210
|
|
211 @item
|
|
212 In La@TeX{} text, the argument of any of the commands @code{\chapter},
|
|
213 @code{\section}, @code{\subsection}, @code{\subsubsection},
|
|
214 @code{\eqno}, @code{\label}, @code{\ref}, @code{\cite},
|
|
215 @code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry},
|
|
216 @code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand},
|
|
217 @code{\newenvironment} or @code{\renewenvironment} is a tag.@refill
|
|
218
|
|
219 Other commands can make tags as well, if you specify them in the
|
|
220 environment variable @env{TEXTAGS} before invoking @code{etags}. The
|
|
221 value of this environment variable should be a colon-separated list of
|
|
222 command names. For example,
|
|
223
|
|
224 @example
|
|
225 TEXTAGS="mycommand:myothercommand"
|
|
226 export TEXTAGS
|
|
227 @end example
|
|
228
|
|
229 @noindent
|
|
230 specifies (using Bourne shell syntax) that the commands
|
|
231 @samp{\mycommand} and @samp{\myothercommand} also define tags.
|
|
232
|
|
233 @item
|
|
234 In Lisp code, any function defined with @code{defun}, any variable
|
|
235 defined with @code{defvar} or @code{defconst}, and in general the first
|
|
236 argument of any expression that starts with @samp{(def} in column zero is
|
|
237 a tag.
|
|
238
|
|
239 @item
|
|
240 In Scheme code, tags include anything defined with @code{def} or with a
|
|
241 construct whose name starts with @samp{def}. They also include variables
|
|
242 set with @code{set!} at top level in the file.
|
|
243 @end itemize
|
|
244
|
|
245 Several other languages are also supported:
|
|
246
|
|
247 @itemize @bullet
|
|
248
|
|
249 @item
|
|
250 In Ada code, functions, procedures, packages, tasks and types are
|
|
251 tags. Use the @samp{--packages-only} option to create tags for
|
|
252 packages only.
|
|
253
|
|
254 In Ada, the same name can be used for different kinds of entity
|
|
255 (e.g.@:, for a procedure and for a function). Also, for things like
|
|
256 packages, procedures and functions, there is the spec (i.e.@: the
|
|
257 interface) and the body (i.e.@: the implementation). To make it
|
|
258 easier to pick the definition you want, Ada tag name have suffixes
|
|
259 indicating the type of entity:
|
|
260
|
|
261 @table @samp
|
|
262 @item /b
|
|
263 package body.
|
|
264 @item /f
|
|
265 function.
|
|
266 @item /k
|
|
267 task.
|
|
268 @item /p
|
|
269 procedure.
|
|
270 @item /s
|
|
271 package spec.
|
|
272 @item /t
|
|
273 type.
|
|
274 @end table
|
|
275
|
|
276 Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go
|
|
277 directly to the body of the package @code{bidule}, while @kbd{M-x
|
|
278 find-tag @key{RET} bidule @key{RET}} will just search for any tag
|
|
279 @code{bidule}.
|
|
280
|
|
281 @item
|
|
282 In assembler code, labels appearing at the beginning of a line,
|
|
283 followed by a colon, are tags.
|
|
284
|
|
285 @item
|
|
286 In Bison or Yacc input files, each rule defines as a tag the nonterminal
|
|
287 it constructs. The portions of the file that contain C code are parsed
|
|
288 as C code.
|
|
289
|
|
290 @item
|
|
291 In Cobol code, tags are paragraph names; that is, any word starting in
|
|
292 column 8 and followed by a period.
|
|
293
|
|
294 @item
|
|
295 In Erlang code, the tags are the functions, records and macros defined
|
|
296 in the file.
|
|
297
|
|
298 @item
|
|
299 In Fortran code, functions, subroutines and block data are tags.
|
|
300
|
|
301 @item
|
|
302 In HTML input files, the tags are the @code{title} and the @code{h1},
|
|
303 @code{h2}, @code{h3} headers. Also, tags are @code{name=} in anchors
|
|
304 and all occurrences of @code{id=}.
|
|
305
|
|
306 @item
|
|
307 In Lua input files, all functions are tags.
|
|
308
|
|
309 @item
|
|
310 In makefiles, targets are tags; additionally, variables are tags
|
|
311 unless you specify @samp{--no-globals}.
|
|
312
|
|
313 @item
|
|
314 In Objective C code, tags include Objective C definitions for classes,
|
|
315 class categories, methods and protocols. Tags for variables and
|
|
316 functions in classes are named @samp{@var{class}::@var{variable}} and
|
|
317 @samp{@var{class}::@var{function}}.
|
|
318
|
|
319 @item
|
|
320 In Pascal code, the tags are the functions and procedures defined in
|
|
321 the file.
|
|
322
|
|
323 @item
|
|
324 In Perl code, the tags are the packages, subroutines and variables
|
|
325 defined by the @code{package}, @code{sub}, @code{my} and @code{local}
|
|
326 keywords. Use @samp{--globals} if you want to tag global variables.
|
|
327 Tags for subroutines are named @samp{@var{package}::@var{sub}}. The
|
|
328 name for subroutines defined in the default package is
|
|
329 @samp{main::@var{sub}}.
|
|
330
|
|
331 @item
|
|
332 In PHP code, tags are functions, classes and defines. Vars are tags
|
|
333 too, unless you use the @samp{--no-members} option.
|
|
334
|
|
335 @item
|
|
336 In PostScript code, the tags are the functions.
|
|
337
|
|
338 @item
|
|
339 In Prolog code, tags are predicates and rules at the beginning of
|
|
340 line.
|
|
341
|
|
342 @item
|
|
343 In Python code, @code{def} or @code{class} at the beginning of a line
|
|
344 generate a tag.
|
|
345 @end itemize
|
|
346
|
|
347 You can also generate tags based on regexp matching (@pxref{Etags
|
|
348 Regexps}) to handle other formats and languages.
|
|
349
|
|
350 @node Create Tags Table
|
|
351 @subsection Creating Tags Tables
|
|
352 @cindex @code{etags} program
|
|
353
|
|
354 The @code{etags} program is used to create a tags table file. It knows
|
|
355 the syntax of several languages, as described in
|
|
356 @iftex
|
|
357 the previous section.
|
|
358 @end iftex
|
|
359 @ifnottex
|
|
360 @ref{Tag Syntax}.
|
|
361 @end ifnottex
|
|
362 Here is how to run @code{etags}:
|
|
363
|
|
364 @example
|
|
365 etags @var{inputfiles}@dots{}
|
|
366 @end example
|
|
367
|
|
368 @noindent
|
|
369 The @code{etags} program reads the specified files, and writes a tags
|
|
370 table named @file{TAGS} in the current working directory.
|
|
371
|
|
372 If the specified files don't exist, @code{etags} looks for
|
|
373 compressed versions of them and uncompresses them to read them. Under
|
|
374 MS-DOS, @code{etags} also looks for file names like @file{mycode.cgz}
|
|
375 if it is given @samp{mycode.c} on the command line and @file{mycode.c}
|
|
376 does not exist.
|
|
377
|
|
378 @code{etags} recognizes the language used in an input file based on
|
|
379 its file name and contents. You can specify the language with the
|
|
380 @samp{--language=@var{name}} option, described below.
|
|
381
|
|
382 If the tags table data become outdated due to changes in the files
|
|
383 described in the table, the way to update the tags table is the same
|
|
384 way it was made in the first place. If the tags table fails to record
|
|
385 a tag, or records it for the wrong file, then Emacs cannot possibly
|
|
386 find its definition until you update the tags table. However, if the
|
|
387 position recorded in the tags table becomes a little bit wrong (due to
|
|
388 other editing), the worst consequence is a slight delay in finding the
|
|
389 tag. Even if the stored position is very far wrong, Emacs will still
|
|
390 find the tag, after searching most of the file for it. That delay is
|
|
391 hardly noticeable with today's computers.
|
|
392
|
|
393 Thus, there is no need to update the tags table after each edit.
|
|
394 You should update a tags table when you define new tags that you want
|
|
395 to have listed, or when you move tag definitions from one file to
|
|
396 another, or when changes become substantial.
|
|
397
|
|
398 One tags table can virtually include another. Specify the included
|
|
399 tags file name with the @samp{--include=@var{file}} option when
|
|
400 creating the file that is to include it. The latter file then acts as
|
|
401 if it covered all the source files specified in the included file, as
|
|
402 well as the files it directly contains.
|
|
403
|
|
404 If you specify the source files with relative file names when you run
|
|
405 @code{etags}, the tags file will contain file names relative to the
|
|
406 directory where the tags file was initially written. This way, you can
|
|
407 move an entire directory tree containing both the tags file and the
|
|
408 source files, and the tags file will still refer correctly to the source
|
|
409 files. If the tags file is in @file{/dev}, however, the file names are
|
|
410 made relative to the current working directory. This is useful, for
|
|
411 example, when writing the tags to @file{/dev/stdout}.
|
|
412
|
|
413 When using a relative file name, it should not be a symbolic link
|
|
414 pointing to a tags file in a different directory, because this would
|
|
415 generally render the file names invalid.
|
|
416
|
|
417 If you specify absolute file names as arguments to @code{etags}, then
|
|
418 the tags file will contain absolute file names. This way, the tags file
|
|
419 will still refer to the same files even if you move it, as long as the
|
|
420 source files remain in the same place. Absolute file names start with
|
|
421 @samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.
|
|
422
|
|
423 When you want to make a tags table from a great number of files, you
|
|
424 may have problems listing them on the command line, because some systems
|
|
425 have a limit on its length. The simplest way to circumvent this limit
|
|
426 is to tell @code{etags} to read the file names from its standard input,
|
|
427 by typing a dash in place of the file names, like this:
|
|
428
|
|
429 @smallexample
|
|
430 find . -name "*.[chCH]" -print | etags -
|
|
431 @end smallexample
|
|
432
|
|
433 Use the option @samp{--language=@var{name}} to specify the language
|
|
434 explicitly. You can intermix these options with file names; each one
|
|
435 applies to the file names that follow it. Specify
|
|
436 @samp{--language=auto} to tell @code{etags} to resume guessing the
|
|
437 language from the file names and file contents. Specify
|
|
438 @samp{--language=none} to turn off language-specific processing
|
|
439 entirely; then @code{etags} recognizes tags by regexp matching alone
|
|
440 (@pxref{Etags Regexps}).
|
|
441
|
|
442 The option @samp{--parse-stdin=@var{file}} is mostly useful when
|
|
443 calling @code{etags} from programs. It can be used (only once) in
|
|
444 place of a file name on the command line. @code{Etags} will read from
|
|
445 standard input and mark the produced tags as belonging to the file
|
|
446 @var{file}.
|
|
447
|
|
448 @samp{etags --help} outputs the list of the languages @code{etags}
|
|
449 knows, and the file name rules for guessing the language. It also prints
|
|
450 a list of all the available @code{etags} options, together with a short
|
|
451 explanation. If followed by one or more @samp{--language=@var{lang}}
|
|
452 options, it outputs detailed information about how tags are generated for
|
|
453 @var{lang}.
|
|
454
|
|
455 @node Etags Regexps
|
|
456 @subsection Etags Regexps
|
|
457
|
|
458 The @samp{--regex} option provides a general way of recognizing tags
|
|
459 based on regexp matching. You can freely intermix this option with
|
|
460 file names, and each one applies to the source files that follow it.
|
|
461 If you specify multiple @samp{--regex} options, all of them are used
|
|
462 in parallel. The syntax is:
|
|
463
|
|
464 @smallexample
|
|
465 --regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers}
|
|
466 @end smallexample
|
|
467
|
|
468 The essential part of the option value is @var{tagregexp}, the
|
|
469 regexp for matching tags. It is always used anchored, that is, it
|
|
470 only matches at the beginning of a line. If you want to allow
|
|
471 indented tags, use a regexp that matches initial whitespace; start it
|
|
472 with @samp{[ \t]*}.
|
|
473
|
|
474 In these regular expressions, @samp{\} quotes the next character, and
|
|
475 all the GCC character escape sequences are supported (@samp{\a} for
|
|
476 bell, @samp{\b} for back space, @samp{\d} for delete, @samp{\e} for
|
|
477 escape, @samp{\f} for formfeed, @samp{\n} for newline, @samp{\r} for
|
|
478 carriage return, @samp{\t} for tab, and @samp{\v} for vertical tab).
|
|
479
|
|
480 Ideally, @var{tagregexp} should not match more characters than are
|
|
481 needed to recognize what you want to tag. If the syntax requires you
|
|
482 to write @var{tagregexp} so it matches more characters beyond the tag
|
|
483 itself, you should add a @var{nameregexp}, to pick out just the tag.
|
|
484 This will enable Emacs to find tags more accurately and to do
|
|
485 completion on tag names more reliably. You can find some examples
|
|
486 below.
|
|
487
|
|
488 The @var{modifiers} are a sequence of zero or more characters that
|
|
489 modify the way @code{etags} does the matching. A regexp with no
|
|
490 modifiers is applied sequentially to each line of the input file, in a
|
|
491 case-sensitive way. The modifiers and their meanings are:
|
|
492
|
|
493 @table @samp
|
|
494 @item i
|
|
495 Ignore case when matching this regexp.
|
|
496 @item m
|
|
497 Match this regular expression against the whole file, so that
|
|
498 multi-line matches are possible.
|
|
499 @item s
|
|
500 Match this regular expression against the whole file, and allow
|
|
501 @samp{.} in @var{tagregexp} to match newlines.
|
|
502 @end table
|
|
503
|
|
504 The @samp{-R} option cancels all the regexps defined by preceding
|
|
505 @samp{--regex} options. It too applies to the file names following
|
|
506 it. Here's an example:
|
|
507
|
|
508 @smallexample
|
|
509 etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \
|
|
510 bar.ber -R --lang=lisp los.er
|
|
511 @end smallexample
|
|
512
|
|
513 @noindent
|
|
514 Here @code{etags} chooses the parsing language for @file{voo.doo} and
|
|
515 @file{bar.ber} according to their contents. @code{etags} also uses
|
|
516 @var{reg1} to recognize additional tags in @file{voo.doo}, and both
|
|
517 @var{reg1} and @var{reg2} to recognize additional tags in
|
|
518 @file{bar.ber}. @var{reg1} is checked against each line of
|
|
519 @file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while
|
|
520 @var{reg2} is checked against the whole @file{bar.ber} file,
|
|
521 permitting multi-line matches, in a case-sensitive way. @code{etags}
|
|
522 uses only the Lisp tags rules, with no user-specified regexp matching,
|
|
523 to recognize tags in @file{los.er}.
|
|
524
|
|
525 You can restrict a @samp{--regex} option to match only files of a
|
|
526 given language by using the optional prefix @var{@{language@}}.
|
|
527 (@samp{etags --help} prints the list of languages recognized by
|
|
528 @code{etags}.) This is particularly useful when storing many
|
|
529 predefined regular expressions for @code{etags} in a file. The
|
|
530 following example tags the @code{DEFVAR} macros in the Emacs source
|
|
531 files, for the C language only:
|
|
532
|
|
533 @smallexample
|
|
534 --regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
|
|
535 @end smallexample
|
|
536
|
|
537 @noindent
|
|
538 When you have complex regular expressions, you can store the list of
|
|
539 them in a file. The following option syntax instructs @code{etags} to
|
|
540 read two files of regular expressions. The regular expressions
|
|
541 contained in the second file are matched without regard to case.
|
|
542
|
|
543 @smallexample
|
|
544 --regex=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-file}
|
|
545 @end smallexample
|
|
546
|
|
547 @noindent
|
|
548 A regex file for @code{etags} contains one regular expression per
|
|
549 line. Empty lines, and lines beginning with space or tab are ignored.
|
|
550 When the first character in a line is @samp{@@}, @code{etags} assumes
|
|
551 that the rest of the line is the name of another file of regular
|
|
552 expressions; thus, one such file can include another file. All the
|
|
553 other lines are taken to be regular expressions. If the first
|
|
554 non-whitespace text on the line is @samp{--}, that line is a comment.
|
|
555
|
|
556 For example, we can create a file called @samp{emacs.tags} with the
|
|
557 following contents:
|
|
558
|
|
559 @smallexample
|
|
560 -- This is for GNU Emacs C source files
|
|
561 @{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
|
|
562 @end smallexample
|
|
563
|
|
564 @noindent
|
|
565 and then use it like this:
|
|
566
|
|
567 @smallexample
|
|
568 etags --regex=@@emacs.tags *.[ch] */*.[ch]
|
|
569 @end smallexample
|
|
570
|
|
571 Here are some more examples. The regexps are quoted to protect them
|
|
572 from shell interpretation.
|
|
573
|
|
574 @itemize @bullet
|
|
575
|
|
576 @item
|
|
577 Tag Octave files:
|
|
578
|
|
579 @smallexample
|
|
580 etags --language=none \
|
|
581 --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
|
|
582 --regex='/###key \(.*\)/\1/' \
|
|
583 --regex='/[ \t]*global[ \t].*/' \
|
|
584 *.m
|
|
585 @end smallexample
|
|
586
|
|
587 @noindent
|
|
588 Note that tags are not generated for scripts, so that you have to add
|
|
589 a line by yourself of the form @samp{###key @var{scriptname}} if you
|
|
590 want to jump to it.
|
|
591
|
|
592 @item
|
|
593 Tag Tcl files:
|
|
594
|
|
595 @smallexample
|
|
596 etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
|
|
597 @end smallexample
|
|
598
|
|
599 @item
|
|
600 Tag VHDL files:
|
|
601
|
|
602 @smallexample
|
|
603 etags --language=none \
|
|
604 --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
|
|
605 --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
|
|
606 \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
|
|
607 @end smallexample
|
|
608 @end itemize
|
|
609
|
|
610 @node Select Tags Table
|
|
611 @subsection Selecting a Tags Table
|
|
612
|
|
613 @vindex tags-file-name
|
|
614 @findex visit-tags-table
|
|
615 Emacs has at any time one @dfn{selected} tags table, and all the
|
|
616 commands for working with tags tables use the selected one. To select
|
|
617 a tags table, type @kbd{M-x visit-tags-table}, which reads the tags
|
|
618 table file name as an argument, with @file{TAGS} in the default
|
|
619 directory as the default.
|
|
620
|
|
621 Emacs does not actually read in the tags table contents until you
|
|
622 try to use them; all @code{visit-tags-table} does is store the file
|
|
623 name in the variable @code{tags-file-name}, and setting the variable
|
|
624 yourself is just as good. The variable's initial value is @code{nil};
|
|
625 that value tells all the commands for working with tags tables that
|
|
626 they must ask for a tags table file name to use.
|
|
627
|
|
628 Using @code{visit-tags-table} when a tags table is already loaded
|
|
629 gives you a choice: you can add the new tags table to the current list
|
|
630 of tags tables, or start a new list. The tags commands use all the tags
|
|
631 tables in the current list. If you start a new list, the new tags table
|
|
632 is used @emph{instead} of others. If you add the new table to the
|
|
633 current list, it is used @emph{as well as} the others.
|
|
634
|
|
635 @vindex tags-table-list
|
|
636 You can specify a precise list of tags tables by setting the variable
|
|
637 @code{tags-table-list} to a list of strings, like this:
|
|
638
|
|
639 @c keep this on two lines for formatting in smallbook
|
|
640 @example
|
|
641 @group
|
|
642 (setq tags-table-list
|
|
643 '("~/emacs" "/usr/local/lib/emacs/src"))
|
|
644 @end group
|
|
645 @end example
|
|
646
|
|
647 @noindent
|
|
648 This tells the tags commands to look at the @file{TAGS} files in your
|
|
649 @file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}
|
|
650 directory. The order depends on which file you are in and which tags
|
|
651 table mentions that file, as explained above.
|
|
652
|
|
653 Do not set both @code{tags-file-name} and @code{tags-table-list}.
|
|
654
|
|
655 @node Find Tag
|
|
656 @subsection Finding a Tag
|
|
657
|
|
658 The most important thing that a tags table enables you to do is to find
|
|
659 the definition of a specific tag.
|
|
660
|
|
661 @table @kbd
|
|
662 @item M-.@: @var{tag} @key{RET}
|
|
663 Find first definition of @var{tag} (@code{find-tag}).
|
|
664 @item C-u M-.
|
|
665 Find next alternate definition of last tag specified.
|
|
666 @item C-u - M-.
|
|
667 Go back to previous tag found.
|
|
668 @item C-M-. @var{pattern} @key{RET}
|
|
669 Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}).
|
|
670 @item C-u C-M-.
|
|
671 Find the next tag whose name matches the last pattern used.
|
|
672 @item C-x 4 .@: @var{tag} @key{RET}
|
|
673 Find first definition of @var{tag}, but display it in another window
|
|
674 (@code{find-tag-other-window}).
|
|
675 @item C-x 5 .@: @var{tag} @key{RET}
|
|
676 Find first definition of @var{tag}, and create a new frame to select the
|
|
677 buffer (@code{find-tag-other-frame}).
|
|
678 @item M-*
|
|
679 Pop back to where you previously invoked @kbd{M-.} and friends.
|
|
680 @end table
|
|
681
|
|
682 @kindex M-.
|
|
683 @findex find-tag
|
|
684 @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of
|
|
685 a specified tag. It searches through the tags table for that tag, as a
|
|
686 string, and then uses the tags table info to determine the file that the
|
|
687 definition is in and the approximate character position in the file of
|
|
688 the definition. Then @code{find-tag} visits that file, moves point to
|
|
689 the approximate character position, and searches ever-increasing
|
|
690 distances away to find the tag definition.
|
|
691
|
|
692 If an empty argument is given (just type @key{RET}), the balanced
|
|
693 expression in the buffer before or around point is used as the
|
|
694 @var{tag} argument. @xref{Expressions}.
|
|
695
|
|
696 You don't need to give @kbd{M-.} the full name of the tag; a part
|
|
697 will do. This is because @kbd{M-.} finds tags in the table which
|
|
698 contain @var{tag} as a substring. However, it prefers an exact match
|
|
699 to a substring match. To find other tags that match the same
|
|
700 substring, give @code{find-tag} a numeric argument, as in @kbd{C-u
|
|
701 M-.}; this does not read a tag name, but continues searching the tags
|
|
702 table's text for another tag containing the same substring last used.
|
|
703 If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier
|
|
704 alternative to @kbd{C-u M-.}.
|
|
705
|
|
706 @kindex C-x 4 .
|
|
707 @findex find-tag-other-window
|
|
708 @kindex C-x 5 .
|
|
709 @findex find-tag-other-frame
|
|
710 Like most commands that can switch buffers, @code{find-tag} has a
|
|
711 variant that displays the new buffer in another window, and one that
|
|
712 makes a new frame for it. The former is @w{@kbd{C-x 4 .}}, which invokes
|
|
713 the command @code{find-tag-other-window}. The latter is @w{@kbd{C-x 5 .}},
|
|
714 which invokes @code{find-tag-other-frame}.
|
|
715
|
|
716 To move back to places you've found tags recently, use @kbd{C-u -
|
|
717 M-.}; more generally, @kbd{M-.} with a negative numeric argument. This
|
|
718 command can take you to another buffer. @w{@kbd{C-x 4 .}} with a negative
|
|
719 argument finds the previous tag location in another window.
|
|
720
|
|
721 @kindex M-*
|
|
722 @findex pop-tag-mark
|
|
723 @vindex find-tag-marker-ring-length
|
|
724 As well as going back to places you've found tags recently, you can go
|
|
725 back to places @emph{from where} you found them. Use @kbd{M-*}, which
|
|
726 invokes the command @code{pop-tag-mark}, for this. Typically you would
|
|
727 find and study the definition of something with @kbd{M-.} and then
|
|
728 return to where you were with @kbd{M-*}.
|
|
729
|
|
730 Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to
|
|
731 a depth determined by the variable @code{find-tag-marker-ring-length}.
|
|
732
|
|
733 @findex find-tag-regexp
|
|
734 @kindex C-M-.
|
|
735 The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that
|
|
736 match a specified regular expression. It is just like @kbd{M-.} except
|
|
737 that it does regexp matching instead of substring matching.
|
|
738
|
|
739 @node Tags Search
|
|
740 @subsection Searching and Replacing with Tags Tables
|
|
741 @cindex search and replace in multiple files
|
|
742 @cindex multiple-file search and replace
|
|
743
|
|
744 The commands in this section visit and search all the files listed
|
|
745 in the selected tags table, one by one. For these commands, the tags
|
|
746 table serves only to specify a sequence of files to search. These
|
|
747 commands scan the list of tags tables starting with the first tags
|
|
748 table (if any) that describes the current file, proceed from there to
|
|
749 the end of the list, and then scan from the beginning of the list
|
|
750 until they have covered all the tables in the list.
|
|
751
|
|
752 @table @kbd
|
|
753 @item M-x tags-search @key{RET} @var{regexp} @key{RET}
|
|
754 Search for @var{regexp} through the files in the selected tags
|
|
755 table.
|
|
756 @item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
|
|
757 Perform a @code{query-replace-regexp} on each file in the selected tags table.
|
|
758 @item M-,
|
|
759 Restart one of the commands above, from the current location of point
|
|
760 (@code{tags-loop-continue}).
|
|
761 @end table
|
|
762
|
|
763 @findex tags-search
|
|
764 @kbd{M-x tags-search} reads a regexp using the minibuffer, then
|
|
765 searches for matches in all the files in the selected tags table, one
|
|
766 file at a time. It displays the name of the file being searched so you
|
|
767 can follow its progress. As soon as it finds an occurrence,
|
|
768 @code{tags-search} returns.
|
|
769
|
|
770 @kindex M-,
|
|
771 @findex tags-loop-continue
|
|
772 Having found one match, you probably want to find all the rest. To find
|
|
773 one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
|
|
774 @code{tags-search}. This searches the rest of the current buffer, followed
|
|
775 by the remaining files of the tags table.@refill
|
|
776
|
|
777 @findex tags-query-replace
|
|
778 @kbd{M-x tags-query-replace} performs a single
|
|
779 @code{query-replace-regexp} through all the files in the tags table. It
|
|
780 reads a regexp to search for and a string to replace with, just like
|
|
781 ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x
|
|
782 tags-search}, but repeatedly, processing matches according to your
|
|
783 input. @xref{Replace}, for more information on query replace.
|
|
784
|
|
785 @vindex tags-case-fold-search
|
|
786 @cindex case-sensitivity and tags search
|
|
787 You can control the case-sensitivity of tags search commands by
|
|
788 customizing the value of the variable @code{tags-case-fold-search}. The
|
|
789 default is to use the same setting as the value of
|
|
790 @code{case-fold-search} (@pxref{Search Case}).
|
|
791
|
|
792 It is possible to get through all the files in the tags table with a
|
|
793 single invocation of @kbd{M-x tags-query-replace}. But often it is
|
|
794 useful to exit temporarily, which you can do with any input event that
|
|
795 has no special query replace meaning. You can resume the query replace
|
|
796 subsequently by typing @kbd{M-,}; this command resumes the last tags
|
|
797 search or replace command that you did.
|
|
798
|
|
799 The commands in this section carry out much broader searches than the
|
|
800 @code{find-tag} family. The @code{find-tag} commands search only for
|
|
801 definitions of tags that match your substring or regexp. The commands
|
|
802 @code{tags-search} and @code{tags-query-replace} find every occurrence
|
|
803 of the regexp, as ordinary search commands and replace commands do in
|
|
804 the current buffer.
|
|
805
|
|
806 These commands create buffers only temporarily for the files that they
|
|
807 have to search (those which are not already visited in Emacs buffers).
|
|
808 Buffers in which no match is found are quickly killed; the others
|
|
809 continue to exist.
|
|
810
|
|
811 It may have struck you that @code{tags-search} is a lot like
|
|
812 @code{grep}. You can also run @code{grep} itself as an inferior of
|
|
813 Emacs and have Emacs show you the matching lines one by one.
|
|
814 @xref{Grep Searching}.
|
|
815
|
|
816 @node List Tags
|
|
817 @subsection Tags Table Inquiries
|
|
818
|
|
819 @table @kbd
|
|
820 @item M-x list-tags @key{RET} @var{file} @key{RET}
|
|
821 Display a list of the tags defined in the program file @var{file}.
|
|
822 @item M-x tags-apropos @key{RET} @var{regexp} @key{RET}
|
|
823 Display a list of all tags matching @var{regexp}.
|
|
824 @end table
|
|
825
|
|
826 @findex list-tags
|
|
827 @kbd{M-x list-tags} reads the name of one of the files described by
|
|
828 the selected tags table, and displays a list of all the tags defined in
|
|
829 that file. The ``file name'' argument is really just a string to
|
|
830 compare against the file names recorded in the tags table; it is read as
|
|
831 a string rather than as a file name. Therefore, completion and
|
|
832 defaulting are not available, and you must enter the file name the same
|
|
833 way it appears in the tags table. Do not include a directory as part of
|
|
834 the file name unless the file name recorded in the tags table includes a
|
|
835 directory.
|
|
836
|
|
837 @findex tags-apropos
|
|
838 @vindex tags-apropos-verbose
|
|
839 @kbd{M-x tags-apropos} is like @code{apropos} for tags
|
|
840 (@pxref{Apropos}). It finds all the tags in the selected tags table
|
|
841 whose entries match @var{regexp}, and displays them. If the variable
|
|
842 @code{tags-apropos-verbose} is non-@code{nil}, it displays the names
|
|
843 of the tags files together with the tag names.
|
|
844
|
|
845 @vindex tags-tag-face
|
|
846 @vindex tags-apropos-additional-actions
|
|
847 You can customize the appearance of the output by setting the
|
|
848 variable @code{tags-tag-face} to a face. You can display additional
|
|
849 output with @kbd{M-x tags-apropos} by customizing the variable
|
|
850 @code{tags-apropos-additional-actions}---see its documentation for
|
|
851 details.
|
|
852
|
|
853 You can also use the collection of tag names to complete a symbol
|
|
854 name in the buffer. @xref{Symbol Completion}.
|
|
855
|
|
856 @ifnottex
|
|
857 @include emerge-xtra.texi
|
|
858 @end ifnottex
|
|
859
|
|
860 @ignore
|
|
861 arch-tag: b9d83dfb-82ea-4ff6-bab5-05a3617091fb
|
|
862 @end ignore
|