Commit | Line | Data |
---|---|---|
3149927d CY |
1 | @c This file is included by semantic.texi |
2 | ||
9360256a GM |
3 | @c Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2007, 2009, |
4 | @c 2010 Free Software Foundation, Inc. | |
3149927d CY |
5 | |
6 | @c Permission is granted to copy, distribute and/or modify this | |
7 | @c document under the terms of the GNU Free Documentation License, | |
8 | @c Version 1.3 or any later version published by the Free Software | |
9 | @c Foundation; with no Invariant Sections, no Front-Cover Texts, and | |
10 | @c no Back-Cover Texts. A copy of the license is included in the | |
11 | @c section entitled ``GNU Free Documentation License''. | |
12 | ||
13 | You can begin using @semantic{} by enabling Semantic mode, a global | |
8e687433 CY |
14 | minor mode: type @kbd{M-x semantic-mode}, or open the @samp{Tools} |
15 | menu and click on the menu item named @samp{Source Code Parsers | |
16 | (Semantic)}. @xref{Semantic mode}. | |
3149927d CY |
17 | |
18 | When Semantic mode is turned on, Emacs automatically parses each file | |
8e687433 CY |
19 | you visit. You can then use @semantic{} user commands in those |
20 | buffers (@pxref{Semantic mode user commands}). You can also choose to | |
21 | enable a number of ``helper'' minor modes for saving tags, displaying | |
22 | tag information, and so forth. | |
3149927d CY |
23 | |
24 | To enable Semantic mode each time you start Emacs, add the line | |
25 | @code{(semantic-mode 1)} to your initialization file. @xref{Init | |
26 | File,,,emacs,Emacs manual}. | |
27 | ||
28 | @menu | |
8e687433 CY |
29 | * Semantic mode:: Global minor mode for @semantic{}. |
30 | * SemanticDB:: Caching parsed buffers between sessions. | |
31 | * Idle Scheduler:: @semantic{} actions that occur when idle. | |
32 | * Analyzer:: Semantic tools for analyzing code. | |
33 | * Speedbar:: Using @semantic{} with the Speedbar. | |
34 | * SymRef:: Interface to symbol reference tools. | |
35 | * MRU Bookmarks:: Managing tag ``bookmarks''. | |
36 | * Sticky Func Mode:: Showing declarations in the header line. | |
37 | * Highlight Func Mode:: Highlight the current function declaration. | |
38 | * Tag Decoration Mode:: Minor mode to decorate tags. | |
3149927d CY |
39 | @end menu |
40 | ||
41 | @node Semantic mode | |
42 | @section Semantic mode | |
43 | @cindex Semantic mode | |
44 | ||
45 | Semantic mode is a global minor mode for @semantic{} as a whole. When | |
46 | enabled, each file you visit is automatically parsed, provided its | |
47 | major mode is specified in the variable | |
8e687433 CY |
48 | @code{semantic-new-buffer-setup-functions} (the default value of this |
49 | variable sets up parsing for all the parsers included with Emacs, but | |
50 | you may add to it if you install additional parsers). | |
3149927d CY |
51 | |
52 | In each parser-enabled buffer, a number of @semantic{} commands are | |
53 | available for navigating, querying, and editing source code. | |
54 | @xref{Semantic mode user commands}. Enabling Semantic mode also | |
55 | installs a @samp{Development} menu on the menu-bar, with many of these | |
56 | commands. | |
57 | ||
be479117 | 58 | In addition, enabling Semantic mode turns on certain auxiliary global |
8e687433 CY |
59 | minor modes. The variable @code{semantic-default-submodes} determines |
60 | which auxiliary modes are enabled; the defaults are SemanticDB mode | |
61 | (@pxref{SemanticDB}) and Global Semantic Idle Scheduler mode | |
62 | (@pxref{Idle Scheduler}). You can also toggle the auxiliary minor | |
63 | modes separately, using their mode functions (e.g. @kbd{M-x | |
64 | semanticdb-minor-mode}), or via the @samp{Development} menu. The | |
65 | various auxiliary minor modes are described in the following sections. | |
3149927d CY |
66 | |
67 | @defvar semantic-new-buffer-setup-functions | |
68 | The value of this variable is an alist of functions to call for | |
69 | setting up @semantic{} parsing in the buffer. Each element has the | |
70 | form @code{(@var{mode} . @var{fn})}, where @var{mode} is a value of | |
71 | @code{major-mode} for the buffer and @var{fn} is the corresponding | |
72 | function for setting up the parser. @var{fn} is called, with no | |
73 | arguments, after the major mode is initialized (and after the mode | |
74 | hooks have been run). | |
75 | ||
76 | The default value enables @semantic{} for all supported major modes | |
77 | (i.e., C, C++, Scheme, Javascript, Java, HTML, SRecode, and Make), but | |
78 | you can remove modes from this list if you don't want to use | |
79 | @semantic{} with them. | |
80 | @end defvar | |
81 | ||
82 | @defvar semantic-default-submodes | |
83 | The value of this variable is a list of symbols, specifying the | |
be479117 | 84 | auxiliary minor modes to enable when enabling Semantic mode. The |
3149927d CY |
85 | valid mode symbols are: |
86 | ||
87 | @itemize | |
8e687433 CY |
88 | @item @code{global-semantic-idle-scheduler-mode} (@pxref{Idle Scheduler}). |
89 | @item @code{global-semanticdb-minor-mode} (@pxref{SemanticDB}). | |
90 | @item @code{global-semantic-idle-summary-mode} (@pxref{Idle Summary Mode}). | |
91 | @item @code{global-semantic-idle-completions-mode} (@pxref{Idle Completions Mode}). | |
92 | @item @code{global-semantic-highlight-func-mode} (@pxref{Highlight Func Mode}). | |
93 | @item @code{global-semantic-decoration-mode} (@pxref{Tag Decoration Mode}). | |
94 | @item @code{global-semantic-stickyfunc-mode} (@pxref{Sticky Func Mode}). | |
95 | @item @code{global-semantic-mru-bookmark-mode} (@pxref{MRU Bookmarks}). | |
3149927d CY |
96 | @end itemize |
97 | @end defvar | |
98 | ||
99 | @menu | |
100 | * Semantic mode user commands:: | |
101 | @end menu | |
102 | ||
103 | @node Semantic mode user commands | |
104 | @subsection Semantic mode user commands | |
105 | ||
106 | Semantic mode provides a number of commands for navigating, querying, | |
107 | and editing source code in a language-aware manner. These commands | |
108 | generally act on @dfn{tags}, which are the source-code units deemed | |
109 | ``important'' by the present programming language (e.g. functions in | |
110 | the C programming language). | |
111 | ||
112 | These commands may be used in any buffer that has been parsed by | |
113 | @semantic{}. Several of them prompt for a tag name using the | |
114 | minibuffer; here, the @kbd{TAB} key can be used to complete tag names. | |
115 | Others act on the @dfn{current tag}, meaning the tag at (or around) | |
116 | point. | |
117 | ||
118 | @table @kbd | |
fd1cefda | 119 | @item C-c , j |
3149927d CY |
120 | Prompt for a tag defined in the current file, and move point to it |
121 | (@code{semantic-complete-jump-local}). | |
122 | ||
fd1cefda | 123 | @item C-c , J |
3149927d CY |
124 | Prompt for a tag defined in any file that Emacs has parsed, and move |
125 | point to it (@code{semantic-complete-jump}). | |
126 | ||
fd1cefda | 127 | @item C-c , l |
3149927d CY |
128 | Display a list of the possible completions of the current tag |
129 | (@code{semantic-analyze-possible-completions}). | |
130 | ||
fd1cefda | 131 | @item C-c , g |
3149927d | 132 | Prompt for a tag, and display a list of tags that call it |
8e687433 CY |
133 | (@code{semantic-symref-symbol}). This relies on the presence of an |
134 | external symbol reference tool. @xref{SymRef}. | |
3149927d | 135 | |
fd1cefda | 136 | @item C-c , G |
3149927d | 137 | Display a list of tags that call the current tag |
8e687433 CY |
138 | (@code{semantic-symref}). This relies on the presence of an external |
139 | symbol reference tool. @xref{SymRef}. | |
3149927d | 140 | |
fd1cefda | 141 | @item C-c , p |
3149927d CY |
142 | Move point to the previous tag (@code{senator-previous-tag}). |
143 | ||
fd1cefda | 144 | @item C-c , n |
3149927d CY |
145 | Move point to the next tag (@code{senator-next-tag}). |
146 | ||
fd1cefda | 147 | @item C-c , u |
3149927d CY |
148 | Move point ``up'' one reference (@code{senator-go-to-up-reference}). |
149 | The meaning of ``up'' is language-dependent; in C++, for instance, | |
150 | this means moving to the parent of the current tag. | |
151 | ||
fd1cefda CY |
152 | @item C-c, @key{SPC} |
153 | Display a list of possible completions for the symbol at point | |
154 | (@code{semantic-complete-analyze-inline}). This also activates a | |
155 | special set of keybindings for choosing a completion: @key{RET} | |
156 | accepts the current completion, @kbd{M-n} and @kbd{M-p} cycle through | |
157 | possible completions, @key{TAB} completes as far as possible and then | |
158 | cycles, and @kbd{C-g} or any other key aborts the completion. | |
159 | @xref{Smart Completion}. | |
3149927d | 160 | |
fd1cefda | 161 | @item C-c , C-w |
3149927d CY |
162 | Kill the current tag (@code{senator-kill-tag}). This removes the text |
163 | for that tag, placing it in the kill ring. You can retrieve the text | |
164 | with @kbd{C-y}. This also places the tag in the @dfn{tag ring}, so | |
165 | that you can yank it with @kbd{\C-c,\C-y}, below. | |
166 | ||
fd1cefda | 167 | @item C-c , M-w |
3149927d CY |
168 | Copy the current tag into the kill ring as well as the tag ring |
169 | (@code{senator-copy-tag}). | |
170 | ||
fd1cefda | 171 | @item C-c , C-y |
3149927d CY |
172 | Yank a tag from the tag ring (@code{senator-yank-tag}). |
173 | ||
fd1cefda | 174 | @item C-c , r |
3149927d CY |
175 | Copy the current tag into a register |
176 | (@code{senator-copy-tag-to-register}). With an optional argument, | |
177 | kill it as well. This allows you to insert or jump to that tag with | |
178 | the usual register commands. @xref{Registers,,,emacs,Emacs manual}. | |
179 | ||
fd1cefda | 180 | @item \C-c , @kbd{up} |
3149927d CY |
181 | Transpose the current tag with the previous one |
182 | (@code{senator-transpose-tags-up}). | |
183 | ||
fd1cefda | 184 | @item C-c , @kbd{down} |
3149927d CY |
185 | Transpose the current tag with the next one |
186 | (@code{senator-transpose-tags-down}). | |
187 | @end table | |
188 | ||
189 | @node SemanticDB | |
190 | @section Semantic Database | |
191 | @cindex SemanticDB | |
192 | ||
193 | The Semantic Database (SemanticDB) caches the results of parsing | |
194 | source code files. This data can be saved to disk when you exit | |
195 | Emacs, and reloaded automatically when you subsequently revisit the | |
196 | same source code files. This saves time by eliminating the need to | |
197 | re-parse unmodified files. | |
198 | ||
199 | SemanticDB also provides an @acronym{API} that programs can use to | |
200 | acquire information about source code tags. This information can be | |
201 | accessed without loading the original the source files into memory. | |
202 | It can also be used to create alternate ``back-ends'' for storing tag | |
203 | information in alternative on-disk formats. | |
204 | ||
205 | By default, SemanticDB is enabled together with Semantic mode. To | |
206 | disable it, remove it from @code{semantic-default-submodes} | |
207 | (@pxref{Semantic mode}). You can also enable or disable SemanticDB | |
208 | with @kbd{M-x global-semanticdb-minor-mode}. | |
209 | ||
210 | @deffn Command global-semanticdb-minor-mode | |
211 | Toggle SemanticDB mode. When enabled, any source code parsed by | |
212 | @semantic{} is cached in a database. | |
213 | @end deffn | |
214 | ||
215 | SemanticDB offers a large number of customizable options, which are | |
216 | described in the following subsections. | |
217 | ||
218 | @menu | |
219 | * Semanticdb Tag Storage:: | |
220 | * Semanticdb Search Configuration:: | |
221 | * Changing Backends:: | |
3149927d CY |
222 | * Create System Databases:: |
223 | @end menu | |
224 | ||
225 | @node Semanticdb Tag Storage | |
226 | @subsection Semanticdb Tag Storage | |
227 | ||
228 | Each time you exit Emacs, any data cached by SemanticDB is saved in | |
229 | the directory @file{.emacs.d/semanticdb/}, located in your home | |
230 | directory. Within this directory, the cache data is written into a | |
231 | set of files according to a SemanticDB-specific filename convention. | |
232 | If the SemanticDB directory does not exist, Emacs first asks if you | |
233 | want to create it. | |
234 | ||
235 | You can change the name of the SemanticDB directory by customizing the | |
236 | variable @code{semanticdb-default-save-directory}. | |
237 | ||
3149927d CY |
238 | @deffn Option semanticdb-default-save-directory |
239 | The name of the directory where SemanticDB cache files are saved. If | |
240 | the value is @code{nil}, SemanticDB saves its data into a single file, | |
241 | in the current directory, whose filename is given by | |
242 | @code{semanticdb-default-file-name}. | |
243 | @end deffn | |
244 | ||
3149927d CY |
245 | @deffn Option semanticdb-default-file-name |
246 | The name of a cache file in which to save SemanticDB, when | |
247 | @code{semanticdb-default-save-directory} is @code{nil}. | |
248 | @end deffn | |
249 | ||
250 | You can force SemanticDB to save the data from only certain files, or | |
251 | suppress saving altogether, by customizing | |
252 | @code{semanticdb-persistent-path}: | |
253 | ||
3149927d CY |
254 | @deffn Option semanticdb-persistent-path |
255 | List of valid paths for SemanticDB to cache. Each element should be a | |
256 | directory name (a string); then the parse data from any file in that | |
257 | directory is saved. | |
258 | ||
259 | As a special exception, the value of this variable can be a list | |
260 | containing a single symbol: @code{never}, @code{always}, or | |
261 | @code{project}. The symbol @code{never} disables saving anywhere; | |
262 | @code{always} enables saving everywhere; and @code{project} enables | |
263 | saving directory based on the variable | |
264 | @code{semanticdb-project-predicate-functions}. | |
265 | ||
266 | The default value is @code{(always)}. | |
267 | @end deffn | |
268 | ||
3149927d CY |
269 | @defvar semanticdb-project-predicate-functions |
270 | The value of this variable is a list of predicates for indicating that | |
271 | a directory belongs to a project. This list is used when the value of | |
272 | @code{semanticdb-persistent-path} is @code{(project)}. If the list is | |
273 | empty, all paths are considered valid. | |
274 | ||
275 | Project management packages, such as EDE (@pxref{Top,,,ede,EDE | |
276 | manual}), may add their own predicates with @dfn{add-hook} to this | |
277 | variable. This allows SemanticDB to save tag caches in directories | |
278 | controlled by them. | |
279 | @end defvar | |
280 | ||
3149927d CY |
281 | @deffn Option semanticdb-save-database-hooks |
282 | Abnormal hook run after a database is saved. Each function is called | |
283 | with one argument, the object representing the database recently | |
284 | written. | |
285 | @end deffn | |
286 | ||
287 | @node Semanticdb Search Configuration | |
288 | @subsection Semanticdb Search Configuration | |
289 | ||
290 | When another part of @semantic{} (or another Emacs package using | |
bd6f6833 CY |
291 | @semantic{}) queries the SemanticDB library for a source code tag, the |
292 | search need not be limited to tags defined within the current file. | |
293 | It can include tags defined elsewhere, such as @dfn{header files} | |
294 | referenced by the current file (e.g., via the C/C++ @code{#include} | |
295 | directive). While performing the search, the SemanticDB library may | |
296 | even automatically visit other files and parse them, if necessary. | |
297 | ||
298 | The variable @code{semanticdb-find-default-throttle} determines how | |
299 | aggressively SemanticDB searches for source code tags. @xref{Search | |
300 | Throttle}. | |
301 | ||
302 | The details of SemanticDB searches can vary from language to | |
303 | language. In C/C++ code, for example, SemanticDB distinguishes | |
304 | between @dfn{project header files} and @dfn{system header files}, | |
305 | based on whether the @code{#include} directive uses the @code{""} or | |
306 | @code{<>} filename delimiter. SemanticDB looks for system header in | |
307 | the @dfn{system include path} (@pxref{Include paths}). | |
3149927d CY |
308 | |
309 | @menu | |
8e687433 CY |
310 | * Search Throttle:: Controlling how semanticdb searches occur. |
311 | * Semanticdb Roots:: Specifying the root of different projects. | |
312 | * Include paths:: Specifying the directories to search. | |
3149927d CY |
313 | * Semanticdb search debugging commands:: |
314 | @end menu | |
315 | ||
bd6f6833 CY |
316 | @node Search Throttle |
317 | @subsubsection SemanticDB Search Throttle | |
318 | ||
319 | The SemanticDB @dfn{search throttle} determines how aggressive | |
320 | SemanticDB searches are. It is controlled by the variable | |
321 | @code{semanticdb-find-default-throttle}. The default value of this | |
322 | variable aims for maximum accuracy, at the expense of search time. | |
323 | ||
324 | Other parts of the @semantic{} package, particularly the different | |
325 | language parsers, may change the value of | |
326 | @code{semanticdb-find-default-throttle}. You can override its value, | |
327 | for a given major mode, like this: | |
328 | ||
329 | @example | |
330 | (setq-mode-local c-mode | |
9360256a GM |
331 | semanticdb-find-default-throttle |
332 | '(project unloaded system recursive)) | |
bd6f6833 CY |
333 | @end example |
334 | ||
bd6f6833 CY |
335 | @defvar semanticdb-find-default-throttle |
336 | The default throttle for @code{semanticdb-find} routines. | |
337 | The throttle controls how detailed the list of database | |
338 | tables is for a symbol lookup. The value is a list with | |
339 | the following keys: | |
340 | ||
341 | @table @code | |
342 | @item file | |
343 | The file the search is being performed from. This option is here for | |
344 | completeness only, and is assumed to always be on. | |
345 | @item local | |
346 | Tables from the same local directory are included. This includes | |
347 | files directly referenced by a file name which might be in a different | |
348 | directory. | |
349 | @item project | |
350 | Tables from the same local project are included If @code{project} is | |
351 | specified, then @code{local} is assumed. | |
352 | @item unloaded | |
353 | If a table is not in memory, load it. If it is not cached on disk | |
354 | either, get the source, parse it, and create the table. | |
355 | @item system | |
356 | Tables from system databases. These are specifically tables | |
357 | from system header files, or language equivalent. | |
358 | @item recursive | |
359 | For include based searches, includes tables referenced by included | |
360 | files. | |
361 | @item omniscience | |
362 | Included system databases which are omniscience, or somehow know | |
363 | everything. Omniscience databases are found in | |
364 | @code{semanticdb-project-system-databases}. The Emacs Lisp system | |
365 | @var{db} is an omniscience database. | |
366 | @end table | |
367 | @end defvar | |
368 | ||
3149927d CY |
369 | @node Semanticdb Roots |
370 | @subsubsection SemanticDB project roots | |
371 | ||
bd6f6833 CY |
372 | The @code{project} setting in the SemanticDB search throttle |
373 | (@pxref{Search Throttle}) tells SemanticDB to search within the | |
374 | current single code project. For @semantic{}'s point of view, | |
375 | @dfn{projects} are determined by their top-level directories, or | |
376 | @dfn{project roots}; every subdirectory of a project root is | |
377 | considered part of the same project. | |
378 | ||
379 | If you use EDE for project management, it will set the project roots | |
380 | automatically. @xref{Top,,,ede,EDE manual}. You can also specify | |
381 | them yourself. | |
3149927d | 382 | |
3149927d CY |
383 | @deffn Option semanticdb-project-roots |
384 | The value of this variable is a list of directories (strings) that are | |
bd6f6833 CY |
385 | project roots. All subdirectories of a project root are considered |
386 | part of the same project. This variable can be overriden by | |
387 | @code{semanticdb-project-root-functions}. | |
3149927d CY |
388 | @end deffn |
389 | ||
3149927d CY |
390 | @defvar semanticdb-project-root-functions |
391 | The value of this variable is a list of functions to determine a given | |
392 | directory's project root. These functions are called, one at a time, | |
393 | with one argument (the directory name), and must return either | |
394 | @code{nil}, a string (the project root), or a list of strings | |
395 | (multiple project roots, for complex systems). The first | |
396 | non-@code{nil} return value, if any, is taken to be the project root, | |
397 | overriding @code{semanticdb-project-roots}. | |
398 | @end defvar | |
399 | ||
3149927d CY |
400 | @node Include paths |
401 | @subsubsection Include Paths | |
402 | ||
403 | System include paths are standard locations to find source code tags, | |
404 | such as the @dfn{header files} in @file{/usr/include} and its | |
bd6f6833 CY |
405 | subdirectories on Unix-like operating systems. |
406 | ||
407 | You can add and remove system include paths using the following | |
408 | commands: | |
3149927d | 409 | |
3149927d | 410 | @deffn Command semantic-add-system-include dir &optional mode |
bd6f6833 CY |
411 | Prompts for a directory, @var{dir}, and add it as a system include |
412 | path for the current major mode. When called non-interactively, the | |
413 | major mode can be specified with the @var{mode} argument. | |
3149927d CY |
414 | @end deffn |
415 | ||
3149927d | 416 | @deffn Command semantic-remove-system-include dir &optional mode |
bd6f6833 CY |
417 | Prompt for a directory, @var{dir}, and remove it from the system |
418 | include path for the current major mode (or @var{mode}). | |
3149927d CY |
419 | @end deffn |
420 | ||
3149927d CY |
421 | @deffn Command semantic-customize-system-include-path &optional mode |
422 | Customize the system include path for the current major mode (or | |
be479117 | 423 | @var{mode}). |
3149927d CY |
424 | @end deffn |
425 | ||
3149927d CY |
426 | @defun semanticdb-implied-include-tags |
427 | Include tags implied for all files of a given mode. You can set this | |
428 | variable with @code{defvar-mode-local} for a particular mode so that | |
429 | any symbols that exist for all files for that mode are included. | |
430 | @end defun | |
431 | ||
432 | @c @xref{Search Optimization}, for more information on include paths. | |
433 | ||
3149927d CY |
434 | @node Semanticdb search debugging commands |
435 | @subsubsection Semanticdb search debugging commands | |
436 | ||
bd6f6833 CY |
437 | You can use @kbd{M-x semanticdb-dump-all-table-summary} to see the |
438 | list of databases that will be searched from a given buffer. You can | |
439 | follow up with @kbd{M-x semanticdb-find-test-translate-path} to then | |
440 | make sure specific tables from the path are discovered correctly. | |
3149927d | 441 | Alternately, you can get a list of include files @semantic{} |
bd6f6833 CY |
442 | encountered, but could not find on disk using @kbd{M-x |
443 | semanticdb-find-adebug-lost-includes}. | |
3149927d CY |
444 | |
445 | @deffn Command semanticdb-dump-all-table-summary | |
3149927d CY |
446 | Dump a list of all databases in Emacs memory. |
447 | @end deffn | |
448 | ||
fd1cefda CY |
449 | @deffn Command semanticdb-find-test-translate-path &optional arg |
450 | Call and output results of @dfn{semanticdb-find-translate-path}. In | |
451 | the displayed buffer, you can type @key{SPC} to expand items. With | |
452 | @var{arg} non-@code{nil}, specify a @var{brutish} translation. | |
3149927d CY |
453 | @end deffn |
454 | ||
455 | @deffn Command semanticdb-find-adebug-lost-includes | |
3149927d CY |
456 | Translate the current path, then display the lost includes. |
457 | Examines the variable @code{semanticdb-find-lost-includes}. | |
458 | @end deffn | |
459 | ||
460 | Lastly, you can test an explicit search term using this command: | |
461 | ||
462 | @deffn Command semantic-adebug-searchdb regex | |
3149927d CY |
463 | Search the semanticdb for @var{regex} for the current buffer. |
464 | Display the results as a debug list. | |
465 | @end deffn | |
466 | ||
467 | @node Changing Backends | |
468 | @subsection Changing Backends | |
469 | ||
470 | If you want to use some other form of backend, you can use this | |
471 | variable to choose which back end class to use for your general tag | |
472 | storage. | |
473 | ||
474 | The default is to save databases in flat files. Alternatively, you | |
475 | could write a new database backend that stores tags into a database, | |
476 | or other storage system. | |
477 | ||
bd6f6833 CY |
478 | @defvar semanticdb-new-database-class |
479 | The default type of database created for new files. This can be | |
480 | changed on a per file basis, so that some directories are saved using | |
481 | one mechanism, and some directories via a different mechanism. | |
3149927d CY |
482 | @end defvar |
483 | ||
3149927d CY |
484 | @node Create System Databases |
485 | @subsection Create System Databases | |
486 | ||
487 | If your supported language stores the system libraries in readily | |
488 | available parsable source code, you can pre-generate database files | |
489 | for them once, which will be used over and over for tools such as | |
490 | summary-mode, or the analyzer. | |
491 | ||
492 | @deffn Command semanticdb-create-ebrowse-database dir | |
3149927d CY |
493 | Create an @var{ebrowse} database for directory @var{dir}. |
494 | The database file is stored in ~/.semanticdb, or whichever directory | |
495 | is specified by @code{semanticdb-default-system-save-directory}. | |
496 | @end deffn | |
497 | ||
3149927d CY |
498 | @node Idle Scheduler |
499 | @section Idle Scheduler | |
500 | @cindex Idle Scheduler | |
501 | ||
8e687433 | 502 | The @dfn{Semantic Idle Scheduler} is a part of @semantic{} that |
bd6f6833 | 503 | performs various operations while Emacs is waiting for user input |
8e687433 CY |
504 | (idle time). Its primary job is to perform buffer parsing during idle |
505 | time. You can also use the Idle Scheduler to display function | |
506 | prototypes (@pxref{Idle Summary Mode}) or symbol completions | |
507 | (@pxref{Idle Completions Mode}). | |
3149927d | 508 | |
bd6f6833 CY |
509 | @deffn Command global-semantic-idle-scheduler-mode &optional arg |
510 | This command toggles Semantic Idle Scheduler mode in every | |
511 | @semantic{}-enabled buffer. This minor mode ensures that the buffer | |
512 | is automatically reparsed whenever Emacs is idle. If there is | |
513 | additional idle time, it runs jobs scheduled by other parts of | |
514 | @semantic{}, such as Semantic Idle Summary mode (@pxref{Idle Summary | |
515 | Mode}) and Semantic Idle Completions mode (@pxref{Idle Completions | |
516 | Mode}). | |
3149927d CY |
517 | @end deffn |
518 | ||
bd6f6833 CY |
519 | @deffn Option semantic-idle-scheduler-idle-time |
520 | The value of this variable is the amount of idle time, in seconds, | |
521 | before the Semantic idle scheduler activates. The default is 1. | |
3149927d CY |
522 | @end deffn |
523 | ||
bd6f6833 CY |
524 | @deffn Option semantic-idle-scheduler-verbose-flag |
525 | If this variable is non-@code{nil}, the idle scheduler prints verbose | |
526 | messages while running, which are useful for debugging. | |
3149927d CY |
527 | @end deffn |
528 | ||
3149927d | 529 | @menu |
8e687433 CY |
530 | * Reparsing Options:: Reparsing the current buffer in idle time. |
531 | * Idle Working Options:: Options for extra work done at idle time. | |
532 | * Debugging Idle Time Issues:: How to produce good bug reports. | |
533 | * Idle Summary Mode:: Display prototype of symbol under cursor. | |
534 | * Idle Completions Mode:: Smart completion pop-up help. | |
3149927d CY |
535 | @end menu |
536 | ||
537 | @node Reparsing Options | |
538 | @subsection Reparsing Options | |
539 | ||
bd6f6833 CY |
540 | When activated during idle time, the Semantic idle scheduler |
541 | automatically reparses all buffers that need it. Any arriving user | |
542 | input cancels this, returning Emacs to its normal editing behavior. | |
3149927d | 543 | |
bd6f6833 CY |
544 | @deffn Option semantic-idle-scheduler-max-buffer-size |
545 | Maximum size in bytes of buffers automatically reparsed. If this | |
546 | value is less than or equal to @var{0}, buffers are automatically | |
3149927d CY |
547 | reparsed regardless of their size. |
548 | @end deffn | |
549 | ||
bd6f6833 CY |
550 | @deffn Option semantic-idle-scheduler-no-working-message |
551 | If non-@code{nil}, disable display of working messages whie reparsing. | |
3149927d CY |
552 | @end deffn |
553 | ||
bd6f6833 CY |
554 | @deffn Option semantic-idle-scheduler-working-in-modeline-flag |
555 | If non-@code{nil}, show working messages in the mode line. Normally, | |
556 | re-parsing shows messages in the minibuffer; this moves the parse | |
557 | message to the modeline instead. | |
3149927d CY |
558 | @end deffn |
559 | ||
bd6f6833 CY |
560 | @defvar semantic-before-idle-scheduler-reparse-hook |
561 | This normal hook is run just before the idle scheduler begins | |
562 | reparsing. If any hook function throws an error, the value of this | |
563 | variable is reset to @code{nil}. This hook is not protected from | |
564 | lexical errors. | |
3149927d CY |
565 | @end defvar |
566 | ||
bd6f6833 CY |
567 | @defvar semantic-after-idle-scheduler-reparse-hook |
568 | ||
569 | This normal hook is run after the idle scheduler finishes reparsing. | |
570 | If any hook throws an error, this variable is reset to @code{nil}. | |
3149927d CY |
571 | This hook is not protected from lexical errors. |
572 | @end defvar | |
573 | ||
574 | @node Idle Working Options | |
575 | @subsection Idle Working Options | |
576 | ||
673286f5 CY |
577 | In addition to reparsing buffers, the Semantic idle scheduler performs |
578 | additional operations, including the following: | |
3149927d | 579 | |
673286f5 CY |
580 | @itemize |
581 | @item | |
582 | Creating the include path caches required for symbol lookup. | |
583 | @item | |
584 | Create data type caches. | |
585 | @item | |
586 | Saving SemanticDB caches to disk. | |
587 | @item | |
588 | Speculatively parsing the files in the same directory as the current | |
589 | buffer. | |
590 | @end itemize | |
591 | ||
592 | Because this extra work is quite time-consuming, it is only carried | |
593 | out after a longer idle delay. The following features control how the | |
594 | idle work is performed. | |
3149927d | 595 | |
673286f5 CY |
596 | @deffn Option semantic-idle-scheduler-work-idle-time |
597 | The value of this variable is the amount of idle time, in seconds, | |
598 | before commencing idle work. The default is 60. | |
3149927d CY |
599 | @end deffn |
600 | ||
673286f5 CY |
601 | @deffn Option semantic-idle-work-parse-neighboring-files-flag |
602 | If the value of this variable is non-@code{nil}, the Semantic idle | |
603 | scheduler uses idle work time to parse files in the same directory as | |
604 | the current buffer. This improves the accuracy of tag searches and | |
605 | saves time when visiting those files later, at the cost of doing a lot | |
606 | of parsing. The default is @code{t}. | |
3149927d CY |
607 | @end deffn |
608 | ||
609 | @node Debugging Idle Time Issues | |
610 | @subsection Debugging Idle Time Issues | |
611 | ||
673286f5 CY |
612 | If you see an error signalled during idle time, it could be an |
613 | indication of a more serious issue elsewhere. It is not enough to | |
614 | enable @code{debug-on-error}, because the idle scheduler inhibits the | |
615 | debugger. Instead, use the following commands to debug the error: | |
3149927d CY |
616 | |
617 | @deffn Command semantic-debug-idle-function | |
3149927d CY |
618 | Run the Semantic idle function with debugging turned on. |
619 | @end deffn | |
620 | ||
621 | @deffn Command semantic-debug-idle-work-function | |
3149927d CY |
622 | Run the Semantic idle work function with debugging turned on. |
623 | @end deffn | |
624 | ||
3149927d CY |
625 | @node Idle Summary Mode |
626 | @subsection Idle Summary Mode | |
627 | ||
673286f5 CY |
628 | Semantic Idle Summary mode is a minor mode that displays a short |
629 | summary of the symbol at point, such as its function prototype, in the | |
630 | echo area. Its functionality is similar to what ElDoc mode provides | |
631 | for Emacs Lisp (@pxref{Lisp Doc,,,emacs,Emacs manual}). | |
3149927d | 632 | |
673286f5 CY |
633 | @deffn global-semantic-idle-summary-mode &optional arg |
634 | This command toggles Semantic Idle Summary mode in all | |
635 | @semantic{}-enabled buffers. You can also toggle it via the | |
636 | @samp{Show Tag Summaries} menu item in the @samp{Development} menu. | |
3149927d CY |
637 | @end deffn |
638 | ||
673286f5 CY |
639 | When Semantic Idle Summary mode is active, a summary of the tag at |
640 | point is displayed in the echo area. This display takes place during | |
641 | the idle time, as given by @code{semantic-idle-scheduler-idle-time} | |
642 | (@pxref{Idle Scheduler}). | |
643 | ||
644 | You can override the method for getting the current tag to display by | |
645 | setting @code{idle-summary-current-symbol-info}. | |
3149927d | 646 | |
673286f5 CY |
647 | @deffn Option semantic-idle-summary-function |
648 | The value of this variable should be a function to call to display tag | |
649 | information during idle time. See the variable | |
650 | @code{semantic-format-tag-functions} for a list of useful functions. | |
3149927d CY |
651 | @end deffn |
652 | ||
673286f5 CY |
653 | @defvar semantic-idle-summary-out-of-context-faces |
654 | The value of this variable is a list of font-lock faces indicating | |
655 | useless summary contexts. These are generally faces used to highlight | |
656 | comments or strings. Semantic Idle Summary mode does not display its | |
657 | usual summary if the text at point has one of these faces. | |
3149927d CY |
658 | @end defvar |
659 | ||
660 | @node Idle Completions Mode | |
661 | @subsection Idle Completions Mode | |
662 | ||
673286f5 CY |
663 | Semantic Idle Completions mode is a minor mode for performing |
664 | @dfn{code completions} during idle time. The completions are | |
665 | displayed inline, with keybindings that allow you to cycle through | |
666 | different alternatives. | |
3149927d | 667 | |
fd1cefda CY |
668 | Semantic Idle Completions mode performs completion based on the |
669 | Semantic Analyzer (@pxref{Analyzer}). | |
3149927d | 670 | |
673286f5 CY |
671 | @deffn global-semantic-idle-completions-mode &optional arg |
672 | This command toggles Semantic Idle Completions mode in every | |
673 | @semantic{}-enabled buffer. You can also toggle it via the @samp{Show | |
674 | Tag Completions} menu item in the @samp{Development} menu. | |
3149927d CY |
675 | @end deffn |
676 | ||
673286f5 CY |
677 | If the tag at point has at least one completion, Semantic Idle |
678 | Completions mode displays that completion inline---i.e., as part of | |
679 | the buffer text (you can change the display method by customizing | |
680 | @code{semantic-complete-inline-analyzer-idle-displayor-class}, as | |
681 | described below). The completed part is highlighted, to indicate that | |
682 | it is not yet properly inserted into the buffer. The echo area shows | |
683 | the completion, and whether there are other possible completions, like | |
684 | this: | |
3149927d | 685 | |
673286f5 CY |
686 | @example |
687 | besselj [1 of 6 matches] | |
688 | @end example | |
689 | ||
690 | @noindent | |
691 | While the completion is being displayed, the following keybindings | |
692 | take effect: | |
693 | ||
694 | @table @kbd | |
695 | @item @key{RET} | |
696 | @itemx C-m | |
697 | Accept the current completion (@code{semantic-complete-inline-done}), | |
698 | placing it in the buffer and moving point to the end of the completed | |
699 | tag. | |
700 | @item M-n | |
701 | Select the next possible completion | |
702 | (@code{semantic-complete-inline-down}). The new completion is shown | |
703 | inline, replacing the old completion. | |
704 | @item M-p | |
705 | Select the previous possible completion | |
706 | (@code{semantic-complete-inline-up}). | |
707 | @item @key{TAB} | |
708 | @item C-i | |
709 | Accept as much of the completion as possible. If no additional | |
710 | completion can be accepted without ambiguity, select the next possible | |
711 | completion (@code{semantic-complete-inline-TAB}). | |
712 | @item C-g | |
713 | Quit without completing (@code{semantic-complete-inline-quit}). | |
714 | @end table | |
715 | ||
716 | @noindent | |
717 | You can also exit inline completion by issuing any other Emacs | |
718 | command. The completion text then disappears from the buffer. | |
3149927d | 719 | |
673286f5 CY |
720 | @deffn Command semantic-complete-analyze-inline-idle |
721 | This is the command for performing inline code completion. It is | |
722 | called by Semantic Idle Completions mode during idle time, but you can | |
723 | also call it yourself. It returns immediately, leaving the buffer in | |
724 | a state for inline completion. | |
3149927d CY |
725 | @end deffn |
726 | ||
673286f5 CY |
727 | @deffn Option semantic-complete-inline-analyzer-idle-displayor-class |
728 | The value of this variable determines how | |
729 | @code{semantic-complete-analyze-inline-idle} shows its completions. | |
730 | Possible values include: | |
3149927d | 731 | |
673286f5 CY |
732 | @table @code |
733 | @item semantic-displayor-ghost | |
734 | Display completions ``inline'' with the buffer text, as described | |
735 | above. This is the default value. | |
736 | ||
737 | @item semantic-displayor-tooltip | |
738 | Display completions in a tooltip. | |
739 | ||
740 | @item semantic-displayor-traditional | |
741 | Display completions in a separate window. | |
742 | @end table | |
3149927d | 743 | @end deffn |
fd1cefda CY |
744 | |
745 | @node Analyzer | |
746 | @section Analyzer | |
747 | @cindex Analyzer | |
748 | ||
749 | The Semantic Analyzer is a library for performing context analysis on | |
750 | source code. It provides user commands for displaying, completing, | |
751 | and navigating through source code. | |
752 | ||
753 | @menu | |
754 | * Smart Completion:: Performing code completion. | |
755 | * Smart Summary:: Displaying help on a symbol. | |
756 | * Smart Jump:: Jumping to the definition of a tag. | |
757 | * Analyzer Debug:: Debugging problems with the analyzer. | |
758 | @end menu | |
759 | ||
760 | @node Smart Completion | |
761 | @subsection Smart Completion | |
762 | ||
763 | The Semantic Analyzer can be used to perform code completion in a | |
8e687433 CY |
764 | manner that takes the local context into account. (In addition to the |
765 | user commands in this section, Semantic Idle Completions mode also | |
766 | uses the Semantic Analyzer. @xref{Idle Completions Mode}.) | |
fd1cefda CY |
767 | |
768 | @deffn Command semantic-analyze-possible-completions context | |
769 | This is the most basic command for Semantic Analyzer-based completion. | |
8e687433 CY |
770 | Called interactively, it displays a list of the possible completions |
771 | for the symbol at point. | |
fd1cefda CY |
772 | |
773 | When called from a Lisp program, | |
774 | @code{semantic-analyze-possible-completions} does not display a | |
775 | completions list. The argument @var{context} should be either a | |
776 | buffer position, or a context object. The return value is a list of | |
777 | @semantic{} tag objects that complete the symbol for @var{context}, | |
778 | based on the following criteria: | |
779 | ||
780 | @itemize | |
781 | @item Elements currently in scope. | |
782 | @item Constants currently in scope. | |
783 | @item Elements matching the context's @code{:prefix}. | |
784 | @item Type of the completion matching the type of the context. | |
785 | @end itemize | |
786 | ||
787 | Most of the other commands documented in this section call | |
788 | @code{semantic-analyze-possible-completions} internally. | |
789 | @end deffn | |
790 | ||
fd1cefda CY |
791 | @deffn Command semantic-complete-analyze-inline |
792 | This command is bound to @kbd{C-c , @key{SPC}} when Semantic mode is | |
793 | enabled (@pxref{Semantic mode user commands}). It displays a list of | |
794 | possible completions for the symbol at point, and activates a special | |
795 | set of keybindings for choosing a completion. | |
796 | ||
797 | You can type @key{RET} to accept the current completion, @kbd{M-n} and | |
798 | @kbd{M-p} to cycle through the possible completions, @key{TAB} to | |
799 | complete as far as possible and then cycle through completions, and | |
800 | either @kbd{C-g} or any other key to abort the completion. | |
801 | ||
802 | This command is similar to the completion performed by Semantic Idle | |
803 | Completions mode. The main difference is that it is called | |
804 | explicitly, whereas Semantic Idle Completions mode completes during | |
805 | idle time (@pxref{Idle Completions Mode}). | |
806 | @end deffn | |
807 | ||
fd1cefda CY |
808 | @deffn Option semantic-complete-inline-analyzer-idle-displayor-class |
809 | The value of this variable determines how | |
810 | @code{semantic-complete-analyze-inline} shows its completions. | |
811 | Possible values include: | |
812 | ||
813 | @table @code | |
814 | @item semantic-displayor-traditional | |
815 | Display completions in a separate window. This is the default value. | |
816 | ||
817 | @item semantic-displayor-ghost | |
818 | Display completions ``inline'' with the buffer text, similar to the | |
819 | default behavior of Semantic Idle Completions mode (@pxref{Idle | |
820 | Completions Mode}). | |
821 | ||
822 | @item semantic-displayor-tooltip | |
823 | Display completions in a tooltip. | |
824 | @end table | |
825 | @end deffn | |
826 | ||
827 | In addition to @code{semantic-complete-analyze-inline}, you can use | |
828 | the simpler command @code{semantic-ia-complete-symbol point}. This | |
829 | behaves like the usual @kbd{M-@key{TAB}} (@code{complete-symbol}) | |
830 | command (@pxref{Symbol Completion,,,emacs,Emacs manual}), except it | |
8e687433 | 831 | uses the Semantic Analyzer. |
fd1cefda | 832 | |
fd1cefda CY |
833 | @deffn Command semantic-ia-complete-symbol point |
834 | Complete the current symbol at @var{point}. | |
835 | @end deffn | |
836 | ||
837 | @node Smart Summary | |
838 | @subsection Smart Summary | |
839 | ||
8e687433 | 840 | You can use the following commands to obtain information about the |
fd1cefda CY |
841 | code at point: |
842 | ||
fd1cefda CY |
843 | @deffn Command semantic-ia-show-summary pos |
844 | Display a summary for the symbol at @var{pos}. Called interactively, | |
845 | @var{pos} defaults to point. | |
846 | @end deffn | |
847 | ||
fd1cefda CY |
848 | @deffn Command semantic-ia-show-doc pos |
849 | Display the code-level documentation for the symbol at @var{pos}. | |
850 | Called interactively, @var{pos} defaults to point. | |
851 | @end deffn | |
852 | ||
fd1cefda CY |
853 | @deffn Command semantic-ia-describe-class typename |
854 | Prompt for the name of a data type, @var{typename}, and display its | |
855 | components. For instance, if the type in question is a class, this | |
856 | displays the methods and member variables. | |
857 | @end deffn | |
858 | ||
859 | You can also use Semantic Idle Summary mode to show information about | |
860 | the current symbol in the echo area during idle time. @xref{Idle | |
861 | Summary Mode}. | |
862 | ||
863 | @node Smart Jump | |
864 | @subsection Smart Jump | |
865 | ||
866 | The Semantic Analyzer can be used to jump directly to the definition | |
8e687433 | 867 | for a code symbol. |
fd1cefda | 868 | |
fd1cefda CY |
869 | @deffn Command semantic-ia-fast-jump pos |
870 | Jump to the definition for the symbol at @var{pos}. Called | |
871 | interactively, @var{pos} defaults to point. | |
872 | @end deffn | |
873 | ||
fd1cefda CY |
874 | @defun semantic-ia-fast-mouse-jump event |
875 | Jump to the definition for the symbol at the position of the mouse | |
876 | event @var{event}. This command is meant to be bound to a mouse | |
877 | command, like this: | |
878 | ||
879 | @example | |
880 | (global-set-key '[(S-mouse-1)] semantic-ia-fast-mouse-jump) | |
881 | @end example | |
882 | @end defun | |
883 | ||
8e687433 CY |
884 | These commands are often more accurate than than the @code{find-tag} |
885 | command (@pxref{Tags,,,emacs,Emacs manual}), because the Semantic | |
886 | Analyzer is context-sensitive. | |
887 | ||
fd1cefda CY |
888 | You can also use @kbd{C-c , j} (@code{semantic-complete-jump-local}) |
889 | and @kbd{C-c , J} (@code{semantic-complete-jump}) to navigate tags. | |
890 | @xref{Semantic mode user commands}. Those commands do not make use of | |
891 | the Semantic Analyzer. | |
892 | ||
893 | @node Analyzer Debug | |
894 | @subsection Debugging the Semantic Analyzer | |
895 | ||
8e687433 CY |
896 | If the Semantic Analyzer does not analyze your code properly, you can |
897 | take steps to identify and solve the problem. This section was | |
898 | written with C/C++ in mind, but should be relevant for any typed | |
899 | language. | |
fd1cefda CY |
900 | |
901 | @subsubsection Step 1: Check the context | |
902 | ||
8e687433 CY |
903 | To check the current context, type @kbd{M-x |
904 | semantic-analyze-current-context}. | |
fd1cefda CY |
905 | |
906 | @deffn Command semantic-analyze-current-context pos | |
907 | Analyze the context at @var{pos}. This function is used by most of | |
908 | the other Semantic Analyzer commands to obtain the context of the code | |
909 | at a given buffer position. The return value is an EIEIO object | |
910 | describing the context at @var{pos} (@pxref{Top,,,eieio,EIEIO | |
911 | manual}). | |
912 | ||
913 | When called interactively, this displays a @samp{*Semantic Context | |
8e687433 | 914 | Analysis*} buffer containing a summary of the context at point. |
fd1cefda CY |
915 | @end deffn |
916 | ||
8e687433 | 917 | @noindent |
fd1cefda CY |
918 | The Prefix section of the @samp{*Semantic Context Analysis*} buffer |
919 | lists the tags based on the text at point. If it shows only a simple | |
920 | string, the Semantic was unable to identify what the data type was. | |
921 | ||
922 | The first item in the list of the prefix is the first lookup failure | |
923 | in the chain, and that is the item to focus debugging effort on. For | |
924 | example: | |
925 | ||
926 | @example | |
927 | Context Type: #<semantic-analyze-context context> | |
928 | Bounds: (182 . 185) | |
929 | Prefix: Foo* bar | |
930 | int bbb (const char* y) | |
931 | Prefix Types: class Foo @{@} | |
932 | -------- | |
933 | -> Local Vars: int argc | |
934 | char** argv | |
935 | @end example | |
936 | ||
937 | In this example you can see that the prefix has two fully found tags. | |
938 | In the following example, the symbol ``bbb'' is incomplete, and could | |
939 | not be found: | |
940 | ||
941 | @example | |
942 | Context Type: #<semantic-analyze-context context> | |
943 | Bounds: (182 . 184) | |
944 | Prefix: Foo* bar | |
945 | "bb" | |
946 | Prefix Classes: 'function | |
947 | 'variable | |
948 | Prefix Types: class Foo @{@} | |
949 | -------- | |
950 | -> Local Vars: int argc | |
951 | char** argv | |
952 | @end example | |
953 | ||
954 | @subsubsection Step 2 : Check your include path | |
955 | ||
8e687433 CY |
956 | Once you know the missing symbol, check your include path. The header |
957 | or include file containing the needed definition may not be in the | |
958 | list of headers @semantic{} is searching through. To get a basic | |
959 | list, you can use @kbd{M-x semanticdb-find-test-translate-path}. | |
960 | @xref{Semanticdb search debugging commands}. | |
fd1cefda | 961 | |
8e687433 CY |
962 | If items should be loaded but aren't, or if you see some tables that |
963 | have no tags in them, then you you may have an incorrectly-set search | |
964 | throttle (@pxref{Search Throttle}). For example, | |
fd1cefda CY |
965 | |
966 | @example | |
967 | *#<semanticdb-table main.cpp (4 tags DIRTY)> | |
968 | *#<semanticdb-table foo.hh (0 tags DIRTY)> | |
969 | @end example | |
970 | ||
971 | Here, @semantic{} found @file{foo.hh}, but there are 0 tags. This may | |
8e687433 CY |
972 | be because you had set the throttle to avoid reading and parsing files |
973 | that Emacs has not visited. To fix this, visit the file and let | |
974 | @semantic{} parse it. | |
975 | ||
976 | For C++, check also that the @samp{#include} statements for your | |
977 | project-level files use quotes, not angle brackets; angle brackets are | |
978 | for system files. | |
fd1cefda CY |
979 | |
980 | @subsubsection Step 3: Check the local scope | |
981 | ||
982 | If your data type is somehow abbreviated based on scope, such as from | |
983 | a @code{using} statement, you should make sure that the symbol you | |
984 | want is in the local scope. Examine the scope with @kbd{M-x | |
985 | semantic-calculate-scope}. The scope structure is displayed in ADEBUG | |
986 | mode, so use @kbd{SPC} to expand different elements and looking for | |
987 | your symbol. | |
988 | ||
989 | If your symbol should be in the scope, but you cannot find it, then | |
990 | you may have found a language support bug in the local-variable | |
991 | parser, or using statement parser. | |
992 | ||
993 | Calling @kbd{M-x bovinte} should force a reset on the scope in case | |
994 | there is merely some bad state. | |
995 | ||
996 | @example | |
997 | ] Name: Cache | |
998 | ] Class: #'semantic-scope-cache | |
999 | ] :table #<semanticdb-table testsubclass.cpp (13 tags DIRTY)> | |
1000 | ] tag createMoose : class moose | |
1001 | ] scopetypes 'nil | |
1002 | ] parents #<TAG LIST: 1 entries> | |
1003 | ] scope #<TAG LIST: 22 entries> | |
1004 | ] fullscope #<TAG LIST: 23 entries> | |
1005 | ] localvar #<TAG LIST: 6 entries> | |
1006 | @end example | |
1007 | ||
1008 | In the above sample output, the @code{tag} slot specifies where within | |
1009 | you source this scope is relevant. @code{Parents} should contain any | |
1010 | in scope parents, such as the class a method belongs to. | |
1011 | @code{Localvar} should contain your local variables. @code{Scope} | |
1012 | should contain datatypes in scope due to a @code{using} statement or | |
1013 | the like. | |
1014 | ||
1015 | @subsubsection Step 4: Check the typecache | |
1016 | ||
1017 | For complex typed languages like C++, @semantic{} creates a typecache, | |
1018 | or an optimized search table with all the various data types in it. | |
1019 | Elements in the typecache do not obey local scope. It only contains | |
1020 | fully qualified names. You can examine the typecache with | |
1021 | @kbd{M-x semanticdb-typecache-dump}. | |
1022 | ||
1023 | If your data types are not in the typecache, there may be some parsing | |
1024 | error or other bug. Calling @kbd{M-x bovinte} should force a reset on | |
1025 | the typecache in case there is merely some bad state. | |
1026 | ||
1027 | @example | |
1028 | ]#<semanticdb-typecache /home/zappo/cedet/semantic/tests/testsubclass.cpp> | |
1029 | ] Name: /home/zappo/cedet/semantic/tests/testsubclass.cpp | |
1030 | ] Class: #'semanticdb-typecache | |
1031 | ] filestream 'nil | |
1032 | ] includestream #<TAG LIST: 84 entries> | |
1033 | ] stream 'nil | |
1034 | ] dependants 'nil | |
1035 | @end example | |
1036 | ||
1037 | In the above example, the output of @kbd{M-x semanticdb-typecache-dump} | |
1038 | was expanded one level. The @code{filestream} slot should contain | |
1039 | datatypes in the current file. The @code{includestream} should | |
1040 | contain all the datatypes in all included header files. | |
1041 | ||
1042 | The @code{dependants} slot will specify other files that depend on | |
1043 | this one. | |
1044 | ||
8e687433 | 1045 | @subsubsection Step 5: Check the parser |
fd1cefda CY |
1046 | |
1047 | Go to the location where your unfound tag should be. You can call | |
1048 | @kbd{M-x bovinate}, and see a dump of the raw tag structure. To see a | |
1049 | navigable tree, use @kbd{M-x semantic-adebug-bovinate} instead. You | |
1050 | can then look to make sure your tag has been properly parsed. | |
1051 | ||
1052 | If it has not, then you may have found a parser bug. To get a feel | |
1053 | how @semantic{} treats your file, type @kbd{M-x | |
1054 | global-semantic-show-unmatched-syntax-mode}. This causes any syntax | |
1055 | it cannot parse to be underlined in red. | |
1056 | ||
1057 | If your type is not parsable, it could be for a couple of reasons: | |
1058 | ||
1059 | @enumerate | |
1060 | @item | |
1061 | If there is a MACRO keyword used in the definition of the type, you | |
1062 | may need to update the @code{semantic-lex-c-preprocessor-symbol-map} | |
1063 | to account for it. | |
1064 | ||
1065 | @item | |
1066 | Or perhaps the parser needs to be fixed. | |
1067 | @end enumerate | |
964f5b2b | 1068 | |
8e687433 CY |
1069 | @node Speedbar |
1070 | @section Speedbar | |
1071 | @cindex speedbar | |
1072 | ||
1073 | You can integrate @semantic{} with the Speedbar. | |
1074 | @xref{Speedbar,,,emacs,Emacs manual}. To do this, add the following | |
1075 | line to your init file: | |
1076 | ||
1077 | @example | |
1078 | (add-hook 'speedbar-load-hook (lambda () (require 'semantic/sb))) | |
1079 | @end example | |
1080 | ||
1081 | @noindent | |
1082 | Or, alternatively: | |
1083 | ||
1084 | @example | |
1085 | (require 'semantic/sb) | |
1086 | @end example | |
1087 | ||
1088 | Once installed, the Speedbar will use @semantic{} to find and display | |
1089 | tags. Tags from @semantic{} are displayed with more details than | |
1090 | ordinary Speedbar tags, such as function arguments and return type. | |
1091 | ||
1092 | In addition, you can use the Speedbar to show the output of the | |
1093 | Semantic Analyzer (@pxref{Analyzer}). To do this, go to the | |
1094 | @samp{Display} menu item on the Speedbar menu and select | |
1095 | @samp{Analyze}; or type @kbd{M-x semantic-speedbar-analysis}. | |
1096 | ||
1097 | @deffn Command semantic-speedbar-analysis | |
1098 | Start the Speedbar in Semantic Analysis mode. | |
1099 | @end deffn | |
1100 | ||
1101 | In Semantic Analysis mode, the Speedbar displays information about the | |
1102 | local context, such as the current function, local arguments and | |
1103 | variables, and details on the prefix (the current symbol). Each entry | |
1104 | has an @samp{<i>} button; clicking on this shows a summary of what | |
1105 | @semantic{} knows about that variable or type. The Speedbar also | |
1106 | displays a list of possible completions at point. | |
1107 | ||
1108 | @node SymRef | |
1109 | @section Symbol References | |
1110 | @cindex symref | |
1111 | ||
1112 | @semantic{} can interface with external @dfn{symbol reference tools}, | |
1113 | such as GNU Global and GNU Idutils. These tools provide information | |
1114 | about where different tags or symbols appear. | |
1115 | ||
1116 | By default, @semantic{} tries to look for the best external symbol | |
1117 | reference tool that can be used. The supported tools are GNU Global, | |
1118 | GNU Idutils, CScope, and Grep (the fallback method). For best | |
1119 | results, use GNU Global. However, @semantic{} does not manage your | |
1120 | GNU Global tables for you; you must manage them yourself. | |
1121 | ||
1122 | @defvar semantic-symref-tool | |
1123 | The value of this variable is a symbol that determines the external | |
1124 | symbol reference tool to use. The default value, @code{detect}, says | |
1125 | to look for the best available tool. Other possible values are | |
1126 | @code{global}, @code{idutils}, @code{cscope}, and @code{grep}. Note | |
1127 | that @code{grep} is much slower than the others. | |
1128 | @end defvar | |
1129 | ||
1130 | The commands to display symbol references are @kbd{C-c , g} | |
1131 | (@code{semantic-symref-symbol} and @kbd{C-c , G} | |
1132 | (@code{semantic-symref}). These keybindings are available whenever | |
1133 | Semantic mode is enabled (@pxref{Semantic mode user commands}). | |
1134 | ||
1135 | @deffn Command semantic-symref-symbol sym | |
1136 | This command (normally bound to @kbd{C-c , g}) prompts for a symbol | |
1137 | name, and uses an external reference tool to find references to that | |
1138 | tag. | |
1139 | @end deffn | |
1140 | ||
1141 | @deffn Command semantic-symref | |
1142 | This command (normally bound to @kbd{C-c , G}) uses an external | |
1143 | reference tool to find references to the current tag. | |
1144 | @end deffn | |
1145 | ||
1146 | Both @code{semantic-symref-symbol} and @code{semantic-symref} display | |
1147 | a list of symbol references in a separate buffer. The entries are | |
1148 | organized by file, and by function name. Typing @key{RET} on the | |
1149 | @samp{[+]} next to each function name ``expands'' that entry, listing | |
1150 | all references to the target symbol occurring within that function. | |
1151 | Typing @kbd{RET} on a reference line jumps to that reference. | |
1152 | ||
1153 | @node MRU Bookmarks | |
1154 | @section MRU Bookmarks mode | |
1155 | @cindex semantic-mru-bookmark-mode | |
1156 | ||
1157 | Semantic MRU Bookmarks mode is a minor mode that keeps track of the | |
1158 | tags you have edited, allowing you to quickly return to them later | |
1159 | (MRU stands for ``Most Recently Used''). | |
1160 | ||
1161 | @deffn Command global-semantic-mru-bookmark-mode &optional arg | |
1162 | Toggle Semantic MRU Bookmarks mode globally. The minor mode can be | |
1163 | turned on only if the current buffer was set up for parsing. With | |
1164 | argument @var{arg}, turn the minor mode if @var{arg} is positive, and | |
1165 | off otherwise. | |
1166 | @end deffn | |
1167 | ||
1168 | Semantic MRU Bookmarks mode takes note of each tag you edit. | |
1169 | Afterwards, you can type @kbd{C-x B} | |
1170 | (@code{semantic-mrub-switch-tags}) to return to a tag. This command | |
1171 | prompts for a tag name, completing with the names of edited tags; at | |
1172 | the prompt, you can use @kbd{M-p} and @kbd{M-n} to cycle through tags | |
1173 | in order of last modification time. | |
1174 | ||
1175 | @node Sticky Func Mode | |
1176 | @section Sticky Function mode | |
1177 | ||
1178 | Semantic Sticky Function minor mode displays a header line that shows | |
1179 | the declaration line of the function or tag on the topmost line in the | |
1180 | text area. This allows you to keep that declaration line in view at | |
1181 | all times, even if it is scrolls off the ``top'' of the screen. | |
1182 | ||
1183 | In addition, clicking @kbd{Mouse-1} on the header line opens a context | |
1184 | menu that contains menu items for copying, killing, or narrowing to | |
1185 | that tag. | |
1186 | ||
1187 | @deffn Command global-semantic-stickyfunc-mode &optional arg | |
1188 | Toggle Semantic Sticky Function mode in all Semantic-enabled buffers. | |
1189 | With an optional argument @var{arg}, enable if @var{arg} is positive, | |
1190 | and disable otherwise. | |
1191 | @end deffn | |
1192 | ||
1193 | @defvar semantic-stickyfunc-sticky-classes | |
1194 | The value of this variable is a list of tag classes that Semantic | |
1195 | Sticky Function mode makes ``sticky''. The default is | |
1196 | @code{'(function type)}, meaning function declarations and type | |
1197 | declarations. Other possible tag classes are @code{variable}, | |
1198 | @code{include}, and @code{package}. | |
1199 | @end defvar | |
1200 | ||
1201 | @node Highlight Func Mode | |
1202 | @section Highlight Func Mode | |
1203 | @cindex semantic-highlight-func-mode | |
1204 | ||
1205 | Semantic Highlight Function minor mode highlights the declaration line | |
1206 | of the current function or tag (that is to say, the first line that | |
1207 | describes the rest of the construct). | |
1208 | ||
1209 | In addition, clicking @kbd{Mouse-3} on the highlighted declaration | |
1210 | line opens a context menu that contains menu items for copying, | |
1211 | killing, or narrowing to that tag. | |
1212 | ||
1213 | The tag classes highlighted by Semantic Highlight Function mode are | |
1214 | the same ones given by @code{semantic-stickyfunc-sticky-classes}. | |
1215 | @xref{Sticky Func Mode}. | |
1216 | ||
1217 | @defun global-semantic-highlight-func-mode &optional arg | |
1218 | Toggle Semantic Highlight Function mode in all Semantic-enabled | |
1219 | buffers. With an optional argument @var{arg}, enable if @var{arg} is | |
1220 | positive, and disable otherwise. | |
1221 | @end defun | |
1222 | ||
1223 | @deffn Face semantic-highlight-func-current-tag-face | |
1224 | This face is used to highlight declaration lines in Semantic Highlight | |
1225 | Func mode. | |
1226 | @end deffn | |
1227 | ||
1228 | @node Tag Decoration Mode | |
1229 | @section Tag Decoration Mode | |
1230 | @cindex semantic-decoration-mode | |
1231 | ||
1232 | Semantic Tag Decoration mode ``decorates'' each tag based on certain | |
1233 | arbitrary features of that tag. Decorations are specified using the | |
1234 | variable @code{semantic-decoration-styles}. | |
1235 | ||
1236 | @deffn Command global-semantic-decoration-mode &optional arg | |
1237 | Toggle Semantic Tag Decoration mode in all Semantic-enabled buffers. | |
1238 | With an optional argument @var{arg}, enable if @var{arg} is positive, | |
1239 | and disable otherwise. | |
1240 | @end deffn | |
1241 | ||
1242 | @defvar semantic-decoration-styles | |
1243 | The value of this variable is a list of decoration styles for Semantic | |
1244 | Tag Decoration mode. Each element in this list should have the form | |
1245 | @code{(@var{name} . @var{flag})}, where @var{name} is a style name (a | |
1246 | symbol) and @var{flag} is non-@code{nil} if the style is enabled. | |
1247 | ||
1248 | The following styles are available: | |
1249 | ||
1250 | @table @code | |
1251 | @item semantic-tag-boundary | |
1252 | Place an overline in front of each long tag (excluding prototypes). | |
1253 | ||
1254 | @item semantic-decoration-on-private-members | |
1255 | Highlight class members that are designated as private. | |
1256 | ||
1257 | @item semantic-decoration-on-protected-members | |
1258 | Highlight class members that are designated as protected. | |
1259 | ||
1260 | @item semantic-decoration-on-includes | |
1261 | Highlight class members that are includes. Clicking on the | |
1262 | highlighted include statements opens a context menu for configuring | |
1263 | @semantic{} includes. | |
1264 | @end table | |
1265 | @end defvar | |
1266 | ||
1267 | To enable or disable specific decorations, use this function: | |
1268 | ||
1269 | @deffn Command semantic-toggle-decoration-style name &optional arg | |
1270 | Prompt for a decoration style, @var{name}, and turn it on or off. | |
1271 | With prefix argument @var{arg}, turn on if positive, otherwise off. | |
1272 | Return non-@code{nil} if the decoration style is enabled. | |
1273 | @end deffn | |
1274 | ||
1275 | @deffn Face semantic-tag-boundary-face | |
1276 | Face for long tags in the @code{semantic-tag-boundary} decoration | |
1277 | style. | |
1278 | @end deffn | |
1279 | ||
1280 | @deffn Face semantic-decoration-on-private-members-face | |
1281 | Face for privately-scoped tags in the | |
1282 | @code{semantic-decoration-on-private-members} decoration style. | |
1283 | @end deffn | |
1284 | ||
1285 | @deffn Face semantic-decoration-on-protected-members-face | |
1286 | Face for protected tags in the | |
1287 | @code{semantic-decoration-on-protected-members} decoration style. | |
1288 | @end deffn | |
1289 | ||
1290 | @deffn Face semantic-decoration-on-includes | |
1291 | Face for includes that are not in some other state, in the | |
1292 | @code{semantic-decoration-on-includes} decoration style. | |
1293 | @end deffn | |
1294 | ||
1295 | @deffn Face semantic-decoration-on-unknown-includes | |
1296 | Face for includes that cannot be found, in the | |
1297 | @code{semantic-decoration-on-includes} decoration style. | |
1298 | @end deffn | |
1299 | ||
1300 | @deffn Face semantic-decoration-on-unparsed-includes | |
1301 | Face for includes that have not yet been parsed, in the | |
1302 | @code{semantic-decoration-on-includes} decoration style. | |
1303 | @end deffn | |
1304 | ||
1305 | @subsection Creating New Decoration Modes | |
1306 | ||
1307 | You can create new types of decorations using the following function: | |
1308 | ||
1309 | @defun define-semantic-decoration-style name doc &rest flags | |
1310 | Define a new decoration style with @var{name}. | |
1311 | @var{doc} is a documentation string describing the decoration style @var{name}. | |
1312 | It is appended to auto-generated doc strings. | |
1313 | An Optional list of @var{flags} can also be specified. Flags are: | |
1314 | @code{:enabled} <value> - specify the default enabled value for @var{name}. | |
1315 | ||
1316 | ||
1317 | This defines two new overload functions respectively called @code{NAME-p} | |
1318 | and @code{NAME-highlight}, for which you must provide a default | |
1319 | implementation in respectively the functions @code{NAME-p-default} and | |
1320 | @code{NAME-highlight-default}. Those functions are passed a tag. @code{NAME-p} | |
1321 | must return non-@code{nil} to indicate that the tag should be decorated by | |
1322 | @code{NAME-highlight}. | |
1323 | ||
1324 | To put primary decorations on a tag @code{NAME-highlight}, use | |
1325 | functions like @dfn{semantic-set-tag-face}, | |
1326 | @dfn{semantic-set-tag-intangible}, etc., found in the | |
1327 | semantic-decorate library. | |
1328 | ||
1329 | To add other kind of decorations on a tag, @code{NAME-highlight} must use | |
1330 | @dfn{semantic-decorate-tag}, and other functions of the semantic | |
1331 | decoration @var{api} found in this library. | |
1332 | @end defun | |
1333 | ||
964f5b2b MB |
1334 | @ignore |
1335 | arch-tag: 760dca58-7119-484e-8237-866cbaf36f79 | |
1336 | @end ignore |