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