user-guide.texi

input texinfo @c -*-texinfo-*- @c %**start of header @setfilename semantic-user.info @set TITLE Semantic User's Guide @set AUTHOR Eric M. Ludlam, David Ponce, and Richard Y. Kim @settitle @value{TITLE}

@c ************************************************************************* @c @ Header @c *************************************************************************

@c Merge all indexes into a single index for now. @c We can always separate them later into two or more as needed. @syncodeindex vr cp @syncodeindex fn cp @syncodeindex ky cp @syncodeindex pg cp @syncodeindex tp cp

@c @footnotestyle separate @c @paragraphindent 2 @c @@smallbook @c %**end of header

@copying This is the Semantic User's Manual

Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Eric M. Ludlam Copyright @copyright{} 2001, 2002, 2003, 2004 David Ponce Copyright @copyright{} 2002, 2003 Richard Y. Kim

@quotation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being list their titles, with the Front-Cover Texts being list, and with the Back-Cover Texts being list. A copy of the license is included in the section entitled ``GNU Free Documentation License''. @end quotation @end copying

@ifinfo @dircategory Emacs @direntry * Semantic User's guide: (semantic-user). @end direntry @end ifinfo

@iftex @finalout @end iftex

@c @setchapternewpage odd @c @setchapternewpage off

@ifinfo This is the Semantic User's Guide @emph{Infrastructure for parser based text analysis in Emacs}

Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004 @value{AUTHOR} @end ifinfo

@titlepage @sp 10 @title @value{TITLE} @author by @value{AUTHOR} @vskip 0pt plus 1 fill Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004 @value{AUTHOR} @page @vskip 0pt plus 1 fill @insertcopying @end titlepage @page

@c MACRO inclusion @include semanticheader.texi

@c ************************************************************************* @c @ Document @c ************************************************************************* @contents

@node top @top @value{TITLE}

This chapter describes how to use @b{applications} enabled by semantic. Many of these come with semantic, but others are distributed apart from semantic.

@menu * speedbar:: How to use Semantic speedbar support * ECB:: Emacs Code Browser * imenu:: Special support for Imenu. * senator:: The Semantic Navigator * Analyzer:: Analyze local context * Class Browser:: Class hierarchy browser * Document:: Document generation functions * Charts:: Charting code statistics * Idle Scheduler:: The idle Scheduler and related modes * Minor Modes:: Useful minor modes * semanticdb:: Cache your parsed buffers between sessions. * Speed Debug:: How to debug speed issues. * Customizing:: * GNU Free Documentation License:: * Index:: @end menu

@node speedbar @chapter speedbar @cindex speedbar

Speedbar supports the display of tags through the Semantic parser. To use this utility, add a line like this to your @file{.emacs} file:

@example (add-hook 'speedbar-load-hook (lambda () (require 'semantic-sb))) @end example

or you can simply add:

@example (require 'semantic-sb) @end example

Once installed, speedbar will use semantic to find tags, and will display them appropriately. Tags from semantic will have additional details which can be seen, such as return type, or arguments to functions.

If you use @file{semantic-load.el}, you do not need to add the above lines in your @file{.emacs} file.

Two additional speedbar modes are described in @ref{Speedbar Analysis}, and @ref{Class Browser}.

@node ECB @chapter ECB @cindex ECB

From the ECB Website: @url{http://ecb.sourceforge.net}:

@example ECB is a source code browser for Emacs. It is a global minor-mode which displays a couple of windows that can be used to browse directories, files and file-contents like methods and variables. @end example

@node imenu @chapter imenu @cindex imenu

There is special support for creating Imenu entries using semantic. This is a highly customizable tool which can create specialized menu systems for navigating your source file.

By default, each language that wants special imenu support will set itself up for it. To setup imenu for your buffers, use this command in your @file{.emacs} file:

@example (add-hook 'semantic-init-hooks (lambda ()
(imenu-add-to-menubar "TAGS"))) @end example

Also supported is @dfn{which-func-mode}. This usually uses imenu tags to show the current function. The semantic support for this function uses overlays, which is much faster.

If you use @file{semantic-load.el}, you do not need to add the above lines in your @file{.emacs} file.

You can customize imenu with the following options:

@deffn Option semantic-imenu-summary-function Function to use when creating items in Imenu. Some useful functions are found in @code{semantic-format-tag-functions}. @end deffn

@deffn Option semantic-imenu-bucketize-file Non-@code{nil} if tags in a file are to be grouped into buckets. @end deffn

@deffn Option semantic-imenu-buckets-to-submenu Non-@code{nil} if buckets of tags are to be turned into submenus. This option is ignored if @code{semantic-imenu-bucketize-file} is nil. @end deffn

@deffn Option semantic-imenu-expand-type-members Non-@code{nil} if types should have submenus with members in them. @end deffn

@deffn Option semantic-imenu-bucketize-type-members Non-@code{nil} if members of a type should be grouped into buckets. @code{nil} means to keep them in the same order. Overriden to @code{nil} if @code{semantic-imenu-bucketize-file} is nil. @end deffn

@deffn Option semantic-imenu-sort-bucket-function Function to use when sorting tags in the buckets of functions. See @dfn{semantic-bucketize} and the @var{FILTER} argument for more details on this function. @end deffn

@deffn Option semantic-imenu-index-directory Non @code{nil} to index the entire directory for tags. Doesn't actually parse the entire directory, but displays tags for all files currently listed in the current Semantic database. This variable has no meaning if semanticdb is not active. @end deffn

@deffn Option semantic-imenu-auto-rebuild-directory-indexes If non-@code{nil} automatically rebuild directory index imenus. That is when a directory index imenu is updated, automatically rebuild other buffer local ones based on the same semanticdb. @end deffn

When adding support to a language, this variable may need to be set:

@defvar semantic-imenu-expandable-tag-classes @anchor{semantic-imenu-expandable-tag-classes} List of expandable tag classes. Tags of those classes will be given submenu with children. By default, a @code{type} has interesting children. In Texinfo, however, a @code{section} has interesting children. @end defvar

@node senator @chapter senator @cindex senator

Senator stands for SEmantic NAvigaTOR and was written by David Ponce.

This library defines commands and a minor mode to navigate and manage semantic language tags in the current buffer.

@section Commands

The following user level commands are provided by Senator.

@subsection Navigation

@defun senator-next-tag Navigate to the next Semantic tag. Return the tag or @code{nil} if at end of buffer. @end defun

@defun senator-previous-tag Navigate to the previous Semantic tag. Return the tag or @code{nil} if at beginning of buffer. @end defun

@defun senator-jump Jump to the semantic symbol @var{SYM}.

If optional @var{IN-CONTEXT} is non-@code{nil} jump in the local type's context (see function @dfn{senator-current-type-context}). If optional @var{NO-DEFAULT} is non-@code{nil} do not provide a default value.

When called interactively you can combine the @var{IN-CONTEXT} and @var{NO-DEFAULT} switches like this:

- @kbd{C-u} @var{IN-CONTEXT}. - @kbd{C-u} - @var{NO-DEFAULT}. - @kbd{C-u} @kbd{C-u} @var{IN-CONTEXT} + @var{NO-DEFAULT}. @end defun

@subsection Searching

Searching using senator mode restricts the search only to the definition text, such as the name of the functions or variables in a given buffer.

@deffn Command senator-isearch-toggle-semantic-mode Toggle semantic searching on or off in isearch mode. @kbd{C-c , i} toggle semantic searching. @end deffn

@deffn Command senator-search-forward what &optional bound noerror count @deffnx Command senator-search-backward what &optional bound noerror count Search semantic tags forward or backward from point for string @var{WHAT}. Set point to the end of the occurrence found, and return point. See @dfn{search-forward} for details and the meaning of @var{BOUND} @var{NOERROR} and @var{COUNT}. @var{COUNT} is just ignored in the current implementation. @end deffn

@deffn Command re-search-forward regex @deffnx Command re-search-backward regex Search forward and backward for a token matching the regular expression @var{regex}. @end deffn

@deffn Command word-search-forward word @deffnx Command word-search-backward word Search forward and backward for a token whose name matches @var{word}. @end deffn

@subsection Completion

Completion in senator scans all known definitions in the local file, and uses that information to provide the completion.

@deffn Command senator-complete-symbol &optional cycle-once Complete the current symbol under point. If optional argument @var{CYCLE-ONCE} is non-@code{nil}, only cycle through the list of completions once, doing nothing where there are no more matches. @end deffn

@deffn Command senator-completion-menu-popup Popup a completion menu for the symbol at point. The popup menu displays all of the possible completions for the symbol it was invoked on. To automatically split large menus this function use @dfn{imenu--mouse-menu} to handle the popup menu. @end deffn

@subsection Copy/Paste

Token Copy/Paste is a high level form of the typical copy yank used by Emacs. Copying a tag saves the meta-information related to the function or item the cursor is currently in. When that information is yanked into a new buffer, the form of the text created is based on the current status of the programming buffer.

For example, pasting a function into a different file results in a function call template to be inserted. In a Texinfo file, a @@deffn is created with documentation for that function or command.

@deffn Command senator-copy-tag Take the current tag, and place it in the tag ring. @end deffn

@deffn Command senator-kill-tag Take the current tag, place it in the tag ring, and kill it. Killing the tag removes the text for that tag, and places it into the kill ring. Retrieve that text with @kbd{C-y}. @end deffn

@deffn Command senator-yank-tag Yank a tag from the tag ring. The form the tag takes is differnet depending on where it is being yanked to. @end deffn

@deffn Command senator-copy-tag-to-register register &optional kill-flag Copy the current tag into @var{REGISTER}. Optional argument @var{KILL-FLAG} will delete the text of the tag to the kill ring. @end deffn

For programmers, to provide specialized pasting, created an override function for @code{insert-foreign-tag} (see @inforef{Writing Parsers, , semantic-langdev}.)

@subsection Minor Mode

@deffn Command senator-minor-mode Toggle the SEmantic NAvigaTOR key bindings in the current buffer.

The following default key bindings are provided when semantic minor mode is enabled:

@table @key @item C-c , n senator-next-tag @item C-c , p senator-previous-tag @item C-c , i senator-isearch-toggle-semantic-mode @item C-c , j semantic-complete-jump-local @item C-c , J semantic-complete-jump @item C-c , TAB senator-complete-symbol @item C-c , SPC senator-completion-menu-popup @item C-c , C-y senator-yank-tag @item C-c , C-w senator-kill-tag @item C-c , M-w senator-copy-tag @item C-c , + senator-unfold-tag @item C-c , - senator-fold-tag @end table @end deffn

@section Customization

To enable the Senator keymap in all modes that support semantic parsing, use this:

@example (add-hook 'semantic-init-hooks 'senator-minor-mode) @end example

If you use @file{semantic-load.el}, you do not need to add the above lines in your @file{.emacs} file.

To customize navigation around different types of tokens, use the following variables:

@deffn Option senator-step-at-tag-classes List of tag classes where to step. A tag class is a symbol like @code{'variable}, @code{'function}, @code{'type}, or other. If @code{nil} navigation steps at any tag found. This is a buffer local variable. It can be set in a mode hook to get a specific langage navigation. @end deffn

@deffn Option senator-step-at-start-end-tag-classes List of tag classes where to step at start and end. A tag class is a symbol like @code{'variable}, @code{'function}, @code{'type}, or other. If @code{nil}, navigation only step at beginning of tags. If @code{t}, step at start and end of any tag where it is allowed to step. Also, stepping at start and end of a tag prevent stepping inside its components. This is a buffer local variable. It can be set in a mode hook to get a specific langage navigation. @end deffn

To have a mode specific customization, do something like this in a hook:

@example (add-hook 'mode-hook
(lambda ()
(setq senator-step-at-tag-classes '(function variable))
(setq senator-step-at-start-end-tag-classes '(function))
)) @end example

This will cause navigation and search commands to stop only between functions and variables, and to step at start and end of functions only.

@node Analyzer @chapter Analyzer @cindex Analyzer

The semantic analyzer is a library tool that performs context analysis and can derive useful information.

@deffn Command semantic-analyze-current-context position Analyze the current context at @var{POSITION}. If called interactively, display interesting information about @var{POSITION} in a separate buffer. Returns an object based on symbol @dfn{semantic-analyze-context}. @end deffn

While this can be used as a command, it is mostly useful while debugging the analyzer, or tools using the return value. Use the Emacs command @dfn{describe-class} to learn more about using @code{semantic-analyze-context}.

Another command that uses the analyzer context can derive a completion list.

@deffn Command semantic-analyze-possible-completions context Return a list of semantic tags which are possible completions. @var{CONTEXT} is either a position (such as point), or a precalculated context. Passing in a context is useful if the caller also needs to access parts of the analysis. Completions run through the following filters: @table @asis @item Elements currently in scope @item Constants currently in scope @item Elements match the @code{:prefix} in the @var{CONTEXT}. @item Type of the completion matches the type of the context. Context type matching can identify the following: @item No specific type @item Assignment into a variable of some type. @item Argument to a function with type constraints. When called interactively, displays the list of possible completions in a buffer. @end table @end deffn

@menu * Smart Completion:: Functions you can bind to keys for completion * Smart Idle Completion:: Automatic completion popups * Speedbar Analysis:: Speedbar provided completion @end menu

@node Smart Completion @section Smart Completion

The file @file{semantic-ia.el} contains two commands for performing smart completion using the analysis library. Analysis to calculate these completions are done through the analyzer and completion mechanism. These functions just provide commands that can be bound to key bindings.

@deffn Command semantic-ia-complete-symbol point @anchor{semantic-ia-complete-symbol} Complete the current symbol at @var{point}. Completion options are calculated with @dfn{semantic-analyze-possible-completions}. @end deffn

@deffn Command semantic-ia-complete-symbol-menu point @anchor{semantic-ia-complete-symbol-menu} Complete the current symbol via a menu based at @var{point}. Completion options are calculated with @dfn{semantic-analyze-possible-completions}. @end deffn

@deffn Command semantic-ia-complete-tip point @anchor{semantic-ia-complete-tip} Pop up a tooltip for completion at @var{point}. @end deffn

@deffn Command semantic-ia-show-summary point @anchor{semantic-ia-show-summary} Display a summary for the symbol under @var{point}. @end deffn

@deffn Command semantic-ia-show-doc point @anchor{semantic-ia-show-doc} Display the code-level documentation for the symbol at @var{point}. @end deffn

@node Smart Idle Completion @section Smart Idle Completion

You can get smart completions or summary information to automatically popup without explicity pressing a key or running a function.

This is accomplished through the Idle Scheduler and related features. See @ref{Idle Scheduler} for more on the Scheduler.

Summaries are provided with @code{semantic-idle-summary-mode}. See @ref{Idle Summary Mode}.

Completions are provided with @code{semantic-idle-completions-mode}. See @ref{Idle Completions Mode}.

@node Speedbar Analysis @section Speedbar Analysis

The Analyzer output can be used through a speedbar interface. This interface lists details about the analysis, such as the current function, local arguments and variables, details on the prefix (the symbol the cursor is on), and a list of all possible completions. Completions are specified in @dfn{semantic-analyze-possible-completions} @ref{Analyzer}.

Each entry can be jumped to by clicking on the name. For strongly typed languages, this means you will jump to the definition of the variable, slot, or type definition.

In addition each entry has an <i> button. Clicking on this will display a summary of everything that is known about the variable or type displayed on that line.

If you click on the name of a variable in the ``Completions'' menu, then the text that was recently analyzed will be replaced with the name of the token that was clicked on in speedbar.

@deffn Command semantic-speedbar-analysis Start Speedbar in semantic analysis mode. The analyzer displays information about the current context, plus a smart list of possible completions. @end deffn

You can also enter speedbar analyzer mode by selecting ``Analyze'' from the ``Display'' menu item on speedbar's menu.

@node Class Browser @chapter Class Browser @cindex Class Browser

The semantic class browser is a library that can covert a project file group into an object structure that contains links between structures so that the inheritance links between semantic tags can be easily navigated.

The core to this library is one function in @file{semantic-cb.el}.

@defun semantic-cb-new-class-browser Create an object representing this project's organization. The object returned is of type @dfn{semantic-cb-project}, which contains the slot `:types', a list of all top-level types. Each element is a class of type @dfn{semantic-cb-token}, or @dfn{semantic-cb-type}. @end defun

Use the Emacs function @dfn{describe-class} to learn more about these classes.

You can access the class inheritance structure through a speedbar interface. You can choose the ``Class Browser'' option from Speedbar's ``Display'' menu item, or use the following command:

@deffn Command semantic-cb-speedbar-mode Bring speedbar up, and put it into Class Browser mode. This will use the Class Browser logic applied to the current Semantic project database to build the available relations. The structure of the class hierarchy can then be navigated using traditional speedbar interactions. @end deffn

@node Document @chapter Document @cindex Document

The document program uses semantic tag tables to aid in the creation of texinfo documentation. For example, the following is a code fragment from @file{document.el} that comes with semantic:

@lisp (defun document (&optional resetfile)
"Document the function or variable the cursor is in. Optional argument RESETFILE is provided w/ universal argument. When non-nil, query for a new documentation file."
...
) @end lisp

While visiting @file{document.el}, put the cursor somewhere within the function shown above. Then type @kbd{M-x document}. After asking for the texinfo file name, which in this case is @file{semantic.texi}, this will update the texinfo documentation of the @code{document} function in that file. The result is that the following texinfo text will be either created or updated in @file{user-guide.texi} file:

@example @@deffn Command document &optional resetfile Document the function or variable the cursor is in. Optional argument @@var@{RESETFILE@} is provided w/ universal argument. When non-@@code@{nil@}, query for a new documentation file. @@end deffn @end example

Note that the function name, arguments and documentation string is put in the right place. Within the doc-string, the function arguments are marked with the @@var command and the @code{nil} code fragment is marked with @@code command. This example provides just a glimpse of what is possible with the syntactic information provided by semantic. @refill

The main entry point for the documentation generator are the following commands:

@deffn Command document &optional resetfile Document the function or variable the cursor is in. Optional argument @var{RESETFILE} is provided w/ universal argument. When non-@code{nil}, query for a new documentation file. @end deffn

@deffn Command document-inline Document the current function with an inline comment. @end deffn

@deffn Command document-insert-defun-comment tag buffer Insert mode-comment documentation about @var{TAG} from @var{BUFFER}. @end deffn

@deffn Command document-insert-new-file-header header Insert a new header file into this buffer. Add reference to @var{HEADER}. Used by @code{prototype} if this file doesn't have an introductory comment. @end deffn

In addition to these base documentation commands, the texinfo semantic parser includes a two convenience functions when working directly with texinfo files.

@deffn Command semantic-texi-update-doc &optional tag Update the documentation for @var{TAG}. If the current buffer is a texinfo file, then find the source doc, and update it. If the current buffer is a source file, then get the documentation for this item, find the existing doc in the associated manual, and update that. @end deffn

@deffn Command semantic-texi-goto-source &optional tag Jump to the source for the definition in the texinfo file @var{TAG}. If @var{TAG} is @code{nil}, it is derived from the deffn under @var{POINT}. @end deffn

@node Charts @chapter Charts @cindex Charts

Some commands to draw charts of statistics generated from parsing:

@deffn Command semantic-chart-tags-by-class &optional tagtable Create a bar chart representing the number of tags for a given tag class. Each bar represents how many toplevel tags in @var{TAGTABLE} exist with a given class. See @code{semantic-symbol->name-assoc-list} for tokens which will be charted. @var{TAGTABLE} is passedto @dfn{semantic-something-to-tag-table}. @end deffn

@deffn Command semantic-chart-database-size &optional tagtable Create a bar chart representing the size of each file in semanticdb. Each bar represents how many toplevel nonterminals in @var{TAGTABLE} exist in each database entry. @var{TAGTABLE} is passedto @dfn{semantic-something-to-tag-table}. @end deffn

@deffn Command semantic-chart-tag-complexity &optional class tagtable Create a bar chart representing the complexity of some tokens. Complexity is calculated for tokens with a tag of @var{CLASS}. Each bar represents the complexity of some nonterminal in @var{TAGTABLE}. Only the most complex items are charted. @var{TAGTABLE} is passedto @dfn{semantic-something-to-tag-table}. @end deffn

@node Idle Scheduler @chapter Idle Scheduler @cindex Idle Scheduler

The Idle Scheduler in Semantic 2.0 replaces what was once Auto-Parse mode. The Idle Scheduler now performs multiple duties.

The primary job is to schedule buffer parsing in idle time. The first buffer whose cache is checked is the current buffer. After this, all other buffers are checked.

Once that has been accomplished, sheduled idle processes that use the semantic tag tables are run.

@deffn Command global-semantic-idle-scheduler-mode &optional arg @anchor{global-semantic-idle-scheduler-mode} Toggle global use of option @dfn{semantic-idle-scheduler-mode}. The idle scheduler with automatically reparse buffers in idle time, and then schedule other jobs setup with @dfn{semantic-idle-scheduler-add}. If @var{ARG} is positive, enable, if it is negative, disable. If @var{ARG} is @code{nil}, then toggle. @obsolete{global-semantic-auto-parse-mode,global-semantic-idle-scheduler-mode} @end deffn

@obsolete{semantic-auto-parse-mode, semantic-idle-scheduler-mode}

@deffn Option semantic-idle-scheduler-idle-time @anchor{semantic-idle-scheduler-idle-time} Time in seconds of idle before scheduling events. This time should be short enough to ensure that idle-scheduler will be run as soon as Emacs is idle. @end deffn

@deffn Option semantic-idle-scheduler-mode-hook @anchor{semantic-idle-scheduler-mode-hook} Hook run at the end of function @dfn{semantic-idle-scheduler-mode}. @end deffn

You can add new functionality to the idle scheduler by reading the Application Developers Guide @inforef{Idle Scheduling, , semantic-appdev.info}.

@menu * Reparsing Options:: * Idle Summary Mode:: * Idle Completions Mode:: @end menu

@node Reparsing Options @section Reparsing Options

The Idle Scheduler will automatically reparse all buffers that need it. User input at any time will cancel the operations and return to normal editing.

@subsection Reparse Configuration

@deffn Option semantic-idle-scheduler-max-buffer-size @anchor{semantic-idle-scheduler-max-buffer-size} Maximum size in bytes of buffers automatically reparsed. If this value is less than or equal to @var{0}, buffers are automatically reparsed regardless of their size. @end deffn

@subsection Reparse Messages

@deffn Option semantic-idle-scheduler-no-working-message @anchor{semantic-idle-scheduler-no-working-message} If non-@code{nil}, disable display of working messages during parse. @end deffn

@deffn Option semantic-idle-scheduler-working-in-modeline-flag @anchor{semantic-idle-scheduler-working-in-modeline-flag} Non-@code{nil} means show working messages in the mode line. Typically, parsing will show messages in the minibuffer. This will move the parse message into the modeline. @end deffn

@subsection Reprasing Hooks

@defvar semantic-before-idle-scheduler-reparse-hooks @anchor{semantic-before-idle-scheduler-reparse-hooks} Hooks run before option @code{semantic-idle-scheduler} begins parsing. If any hook throws an error, this variable is reset to nil. This hook is not protected from lexical errors. @end defvar

@defvar semantic-after-idle-scheduler-reparse-hooks @anchor{semantic-after-idle-scheduler-reparse-hooks} Hooks run after option @code{semantic-idle-scheduler} has parsed. If any hook throws an error, this variable is reset to nil. This hook is not protected from lexical errors. @end defvar

@node Idle Summary Mode @section Idle Summary Mode

A summary describes a tag in a useful way. These can be displayed for the lexical token under the cursor in idle time using this mode.

@deffn semantic-idle-summary-mode &optional arg @anchor{semantic-idle-summary-mode} Display a tag summary of the lexical token under the cursor. This means for getting the current tag to display information can be overriden with @code{idle-summary-current-symbol-info}. This is a minor mode which performs actions during idle time. With prefix argument ARG, turn on if positive, otherwise off. The minor mode can be turned on only if semantic feature is available and the current buffer was set up for parsing. Return non-nil if the minor mode is enabled @end deffn

@obsolete{semantic-summary-mode, semantic-idle-summary-mode}

@deffn Option semantic-idle-summary-function @anchor{semantic-idle-summary-function} Function to use when displaying tag information during idle time. Some useful functions are found in @code{semantic-format-tag-functions}. @end deffn

@node Idle Completions Mode @section Idle Completions Mode

The definition of completion lists is described in the Analyzer section @ref{Analyzer}.

The Idle Completions mode will calculate the list of possible completions in idle time, and display them in a popup list, and also highlight the symbol that needs completion.

@deffn semantic-idle-completions-mode &optional arg @anchor{semantic-idle-completions-mode} Display a tooltip with a list of possible completions near the cursor. There is no convenience for performing a completion replacement. For that you should bind @code{semantic-ia-complete-symbol}. This is a minor mode which performs actions during idle time. With prefix argument ARG, turn on if positive, otherwise off. The minor mode can be turned on only if semantic feature is available and the current buffer was set up for parsing. Return non-nil if the minor mode is enabled @end deffn

This mode operates by using the command @code{semantic-complete-inline-analyzer}.

@node Minor Modes @chapter Minor Modes @cindex Minor Modes

@include minor-modes.texi

@node semanticdb @chapter Semantic Database @cindex semanticdb

Semanticdb is a utility which tracks your parsed files, and saves the parsed information to disk. When you reload your source files, semanticdb automatically associates the file with the cached copy, saving time by not re-parsing your buffer.

Semanticdb also provides an API for programs to use to look up information about a tag. These functions can return tag information without loading the source file into memory.

Lastly, the semanticdb interface allows programmers to create alternate back ends. Such a back end could allow access to tag information in binary files, not normally accessable to @semantic{}. A back end could also be written to store tag information in an alternate form of persistent storage.

To use semanticdb, add the following to your @file{.emacs} file:

@example (require 'semanticdb) (global-semanticdb-minor-mode 1) @end example

If you use @file{semantic-load.el}, or the default CEDET install mechanism, you do not need to add the above lines in your @file{.emacs} file.

The Semantic Database has several user level configuration options that controls it's use. From the user perspective, it appears to be one large application. Internally it is divided into sections.

@table @asis @item Core Tables These core tables for semanticdb are not associated with files, or backends. They define the basic behavior of a database and table. @item Persistent Tables These databases are what are generally used in semantic to store information to disk. @item Custom Backends These databases and tables are interfaces to some other source of tagging information, such as the symbols loaded in Emacs Lisp, or perhaps symbols in a Java @file{.class} file. @end table

You can execute hooks when semanticdb is activated using its mode hook.

@deffn Option semanticdb-mode-hooks @anchor{semanticdb-mode-hooks} Hooks run whenever @dfn{global-semanticdb-minor-mode} is run. Use @dfn{semanticdb-minor-mode-p} to determine if the mode has been turned on or off. @end deffn

@menu * Semanticdb Tag Storage:: * Semanticdb Search Configuration:: * Semanticdb System Backends:: * Changing Backends:: * Script Generated Cache Files:: * Create System Databases:: @end menu

@node Semanticdb Tag Storage @section Semanticdb Tag Storage

Once you have tables of tags parsed from your files, the default action is to save them when Emacs exits. You can control the file name and directories where the caches are stored.

@deffn Option semanticdb-default-file-name @anchor{semanticdb-default-file-name} File name of the semantic tag cache. @end deffn

@deffn Option semanticdb-default-save-directory @anchor{semanticdb-default-save-directory} Directory name where semantic cache files are stored. If this value is @code{nil}, files are saved in the current directory. If the value is a valid directory, then it overrides @code{semanticdb-default-file-name} and stores caches in a coded file name in this directory. @end deffn

@deffn Option semanticdb-persistent-path @anchor{semanticdb-persistent-path} List of valid paths that semanticdb will cache tags to. When @dfn{global-semanticdb-minor-mode} is active, tag lists will be saved to disk when Emacs exits. Not all directories will have tags that should be saved. The value should be a list of valid paths. @var{a} path can be a string, indicating a directory in which to save a variable. An element in the list can also be a symbol. Valid symbols are @code{never}, which will disable any saving anywhere, @code{always}, which enables saving everywhere, or @code{project}, which enables saving in any directory that passes a list of predicates in @code{semanticdb-project-predicate-functions}. @end deffn

@defvar semanticdb-project-predicate-functions @anchor{semanticdb-project-predicate-functions} List of predicates to try that indicate a directory belongs to a project. This list is used when @code{semanticdb-persistent-path} contains the value @code{'project}. If the predicate list is @code{nil}, then presume all paths are valid.

Project Management software (such as @var{ede} and @var{jde}) should add their own predicates with @dfn{add-hook} to this variable, and semanticdb will save tag caches in directories controlled by them. @end defvar

@deffn Option semanticdb-save-database-hooks @anchor{semanticdb-save-database-hooks} Hooks run after a database is saved. Each function is called with one argument, the object representing the database recently written. @end deffn

@node Semanticdb Search Configuration @section Semanticdb Search Configuration

When different tools such as smart completion or tag jumping needs to find a tag, those routines call semanticdb search routines. Some time usually needs to be spent making sure semanticdb can find the files your tags are in.

The search path should include:

@enumerate @item The current file @item a table for each #include file @item if 'recursive is in the throttle, then all include files included in include files. @end enumerate

Include files or equivalent are found in:

@enumerate @item current directory @item directories specified by your project. (such as EDE, or the @code{semanticdb-project-roots} variable.) @item system directories @end enumerate

In C code, semantic tries to distinguish between project and system headers based on @code{""} or @code{<>} delimiters. Each language can distinguish using it's own rules.

The system directory is set up via the variable @code{semantic-dependency-system-include-path}. The path is also modified by some system database create routines, such as @code{semanticdb-create-ebrowse-database}. @xref{Include paths}.

You can use the command:

@example M-x semantic-add-system-include RET /some/path @end example

to add more paths interactively into the current mode's path. This will allow semantic to find more files w/out using system databases.

@menu * Semanticdb Roots:: Specifying the root of different projects * Include paths:: Add/Remove directories to include search paths * Search Throttle:: Controlling how semanticdb searches occur * Semanticdb search debugging commands:: @end menu

@node Semanticdb Roots @subsection SemanticDB project roots

Project roots specify where different code projects start. Searching for files usually stops within a single project, so specifying these roots is important if you want semantic to find tags in other related directories.

@deffn Option semanticdb-project-roots @anchor{semanticdb-project-roots} List of directories, where each directory is the root of some project. All subdirectories of a root project are considered a part of one project. Values in this string can be overriden by project management programs via the @code{semanticdb-project-root-functions} variable. @end deffn

@defvar semanticdb-project-root-functions @anchor{semanticdb-project-root-functions} List of functions used to determine a given directories project root. Functions in this variable can override @code{semanticdb-project-roots}. Functions set in the variable are given one argument (a directory) and must return a string, (the root directory) or a list of strings (multiple root directories in a more complex system). This variable should be used by project management programs like @var{ede} or @var{jde}. @end defvar

@node Include paths @subsection Include Paths

You can add and remove system include paths based on major mode using the following commands:

@deffn Command semantic-add-system-include dir &optional mode @anchor{semantic-add-system-include} Add a system include @var{dir} to path for @var{mode}. Modifies a mode-local version of @code{semantic-dependency-system-include-path}. @end deffn

@deffn Command semantic-remove-system-include dir &optional mode @anchor{semantic-remove-system-include} Add a system include @var{dir} to path for @var{mode}. Modifies a mode-local version of @code{semantic-dependency-system-include-path}. @end deffn

@node Search Throttle @subsection SemanticDB Search Throttle

The semanticdb find throttle is a configuration variable that may often be configured by a language support author. If you need to customize this for yourself, you may need to override the mode values in a mode support hook.

@defvar semanticdb-find-default-throttle @anchor{semanticdb-find-default-throttle} The default throttle for @code{semanticdb-find} routines. The throttle controls how detailed the list of database tables is for a symbol lookup. The value is a list with the following keys:

@table @code @item file The file the search is being performed from. This option is here for completeness only, and is assumed to always be on. @item local Tables from the same local directory are included. This includes files directly referenced by a file name which might be in a different directory. @item project Tables from the same local project are included If @code{project} is specified, then @code{local} is assumed. @item unloaded If a table is not in memory, load it. If it is not cached on disk either, get the source, parse it, and create the table. @item system Tables from system databases. These are specifically tables from system header files, or language equivalent. @item recursive For include based searches, includes tables referenced by included files. @item omniscience Included system databases which are omniscience, or somehow know everything. Omniscience databases are found in @code{semanticdb-project-system-databases}. The Emacs Lisp system @var{db} is an omniscience database. @end table

@end defvar

To set the throttle, use a command like this:

@example (setq-mode-local c-mode semanticdb-find-default-throttle '(project unloaded system recursive)) @end example

@node Semanticdb search debugging commands @subsection Semanticdb search debugging commands

You can use @kbd{M-x semanticdb-dump-all-table-summary RET} to see the list of databases that will be searched from a given buffer. It should include DBs for the directories you expect. You can follow up with @kbd{M-x semanticdb-find-test-translate-path RET} to then make sure specific tables from the path are discovered correctly.

@deffn Command semanticdb-dump-all-table-summary @anchor{semanticdb-dump-all-table-summary} Dump a list of all databases in Emacs memory. @end deffn

@deffn Command semanticdb-find-test-translate-path &optional arg @anchor{semanticdb-find-test-translate-path} Call and output results of @dfn{semanticdb-find-translate-path} With @var{arg} non-@code{nil}, specify a @var{brutish} translation. @end deffn

Lastly, you can test an explicit search term using this command:

@deffn Command semantic-adebug-searchdb regex @anchor{semantic-adebug-searchdb} Search the semanticdb for @var{regex} for the current buffer. Display the results as a debug list. @end deffn

@node Semanticdb System Backends @section Semanticdb System Backends

@defvar semanticdb-project-system-databases @anchor{semanticdb-project-system-databases} List of databases containing system library information. Mode authors can create their own system databases which know detailed information about the system libraries for querying purposes. Put those into this variable as a buffer-local, or mode-local value. @end defvar

These system databases are a part of the `omniscience' throttle value.

While these are enabled with @code{semanticdb-find-default-throttle}, a secondary flag is needed for internal controls that prevent recursive duplication.

@defvar semanticdb-search-system-databases @anchor{semanticdb-search-system-databases} Non @code{nil} if search routines are to include a system database. @end defvar

@node Changing Backends @section Changing Backends

If you want to use some other form of backend, you can use this variable to choose which back end class to use for your general tag storage.

@defvar semanticdb-new-database-class @anchor{semanticdb-new-database-class} The default type of database created for new files. This can be changed on a per file basis, so that some directories are saved using one mechanism, and some directories via a different mechanism. @end defvar

@node Script Generated Cache Files @section Script Generated Cache Files

You can create new semantic databases with the @file{semanticdb.sh} script file. Give this script the directory you want parsed, and it will create a cache file for you.

@example $ semanticdb.sh *.el @end example

@node Create System Databases @section Create System Databases

If your supported langauge stores the system libraries in readilly available parsable source code, you can pre-generate database files for them once, which will be used over and over for tools such as summary-mode, or the analyzer.

Use the following command to create new system databases:

@deffn Command semanticdb-create-system-database path &optional class @anchor{semanticdb-create-system-database} Create a system database starting at @var{path}. @var{path} should be a top level directory for a series of files containing declarations for @var{system} files. In @var{c}, this would be header filaes. @var{class} is the class for the database to create. Only child classes of symbol @dfn{semanticdb-project-database-system} are accepted. @end deffn

@deffn Command semanticdb-create-ebrowse-database dir @anchor{semanticdb-create-ebrowse-database} Create an @var{ebrose} database for directory @var{dir}. The database file is stored in ~/.semanticdb, or whichever directory is specified by @code{semanticdb-default-system-save-directory}. @end deffn

The CLASS requested here is a bit of archana representing the class name for the language the entry is for. Use completion @kbd{SPC} to see the ones available. The name of the language should be part of the class name.

@node Speed Debug @chapter Debugging Speed Problems

If aspects of semantic cause your Emacs to slow down or block editing, there are several things that may be happening. The most time consuming aspect of semantic is usually the parsing of files for tag information, and this action can be triggered from many possible sources.

A simple way to determine where the problem lies is to use the command @kbd{M-x debug-on-quit RET} and then just hit @kbd{C-g} next time it gets 'stuck' somewhere. It will give you a stack and one of the many semantic mode functions will likely show up in that stack trace.

From a simple standpoint, your next action might be to use the the Senator menu under @kbd{Modes} and just toggle suspected modes on and off.

@section Interruptibility

One of the goals with the semantic based minor modes and auto parse is that it should be interruptible. Thus, a keyboard action should interrupt any active parsing or mode activity. In practice, I've found this doesn't always work and I've been a bit stymied as to why.

You can test the interruptibility framework by running @kbd{M-x semantic-test-throw-on-input RET} and seeing that you can press any key to break out of the loop.

@section Incremental parsing

The incremental parser used by semantic will reparse only small sections of a file you have edited, which eliminates the need to reparse entire files. This speeds up minor modes that need the local buffer to be up to date, such as speedbar or ECB.

If the incremental parsing is not always working for you (meaning it will parse the whole file frequently while you edit) then perhaps you need to customize @code{semantic-edits-verbose-flag} to enable some friendly debug output. Additionally using @code{semantic-load-enable-semantic-debugging-helpers} to help identify possible problem areas by enabling highlight edits mode and show parser state mode @inforef{Incremental Parser Debugging, ,semantic-langdev.info}

@section Symbol lookup

There are many minor modes that have special behaviors tied into the current parser state, with the most complex modes being the summary and completion modes. These modes can initiate parsing not only in the current buffer, but in other buffers that are referred to in the current source by some form of include statement.

If they turn out not to be useful in the language mode you are operating in, then it may be best to disable them.

Alternately, you can control how these major modes, and other modes like them parse alternate files by adjusting @code{semanticdb-find-default-throttle}. You can read more in @inforef{ DB Search Paths, , semantic-appdev.info}.

@node Customizing @chapter Customizing @cindex customizing

Customizations can be divided into two categories. * M-x customize * Low level hooks.

@node GNU Free Documentation License @appendix GNU Free Documentation License

@include fdl.texi

@node Index @unnumbered Index @printindex cp

@iftex @contents @summarycontents @end iftex

@bye

@c Following comments are for the benefit of ispell.