Initial Commit

[packages] / xemacs-packages / semantic / doc / 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.