11.1 Speedbar

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

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

or you can simply add:

(require 'semantic-sb)

Once installed, speedbar will use semantic to find tokens, 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 `semantic-load.el', you do not need to add the above
lines in your .emacs file.

Also supported is 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 `semantic-load.el', you do not need to add the above
lines in your .emacs file.

You can customize imenu with the following options:

Option:semantic-imenu-summary-function

Function to use when creating items in Imenu.
Some useful functions are:
semantic-abbreviate-nonterminalsemantic-summarize-nonterminalsemantic-prototype-nonterminal

Option:semantic-imenu-bucketize-file

Non-nil if tokens in a file are to be grouped into buckets.

Option:semantic-imenu-buckets-to-submenu

Non-nil if buckets of tokens are to be turned into submenus.
This option is ignored if semantic-imenu-bucketize-file is nil.

Option:semantic-imenu-expand-type-parts

Non-nil if types should have submenus with parts in it.

Option:semantic-imenu-bucketize-type-parts

Non-nil if elements of a type should be placed grouped into buckets.
Nil means to keep them in the same order.
Overridden to nil if semantic-imenu-bucketize-file is nil.

Option:semantic-imenu-sort-bucket-function

Function to use when sorting tags in the buckets of functions.

Option:semantic-imenu-index-directory

Non 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.

Option:semantic-imenu-auto-rebuild-directory-indexes

If non-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.

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

Variable:semantic-imenu-expandable-token

Tokens of this token type will be given submenu with children.
By default, a type has interesting children. In Texinfo, however,
a section has interesting children.

11.3 Semantic Database

Semanticdb is a utility which tracks your parsed files, and saves the
parsed information to files. 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. These functions
will return token information without loading the source file into
memory by checking the disk cache.

To use semanticdb, add the following to your `.emacs' file:

(require 'semanticdb)
(global-semanticdb-minor-mode 1)

If you have a tool which optionally uses the semantic database, it may
be important to track if the database mode is turned on or off.

Option:semanticdb-mode-hooks

Hooks run whenever global-semanticdb-minor-mode is run.
Use semanticdb-minor-mode-p to determine if the mode has been turned
on or off.

Option:semanticdb-persistent-path

List of valid paths that semanticdb will cache tokens to.
When global-semanticdb-minor-mode is active, token lists will
be saved to disk when Emacs exits. Not all directories will have
tokens that should be saved.
The value should be a list of valid paths. 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 never, which will
disable any saving anywhere, always, which enables saving
everywhere, or project, which enables saving in any directory that
passes a list of predicates in semantic-project-predicates.

Option: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 overridden by project management programs
via the semanticdb-project-root-functions variable.

The important difference between these two is that you may put just
"~" in semanticdb-persistent-path, but you may put individual
project directories into semanticdb-project-roots so that
different database lists don't get cross referenced incorrectly.

11.3.1 Searching

You can search for tokens in the database using the following
functions. It is important to note that database search functions do
not return a plain list of tokens. This is because some tokens may
not be loaded in a buffer, which means that the found token would not
have an overlay, and no way to determine where it came from.

Find all occurrences of nonterminals which match FUNCTION.
Search in all DATABASES. If DATABASES is nil, search a range of
associated databases.
When SEARCH-PARTS is non-nil the search will include children of tokens.
When SEARCH-INCLUDES is non-nil, the search will include dependency files.
When DIFF-MODE is non-nil, search databases which are of a different mode.
A Mode is the major-mode that file was in when it was last parsed.
When FIND-FILE-MATCH is non-nil, the make sure any found token's file is
in an Emacs buffer.

Find all occurrences of nonterminals with name matching REGEX in databases.
See semanticdb-find-nonterminal-by-function for details on DATABASES,
SEARCH-PARTS, SEARCH-INCLUDESDIFF-MODE, and FIND-FILE-MATCH.

Find all nonterminals with a PROPERTY equal to VALUE in databases.
See semanticdb-find-nonterminal-by-function for details on DATABASES,
SEARCH-PARTS, SEARCH-INCLUDESDIFF-MODE, and FIND-FILE-MATCH.
Return a list ((DB-TABLE . TOKEN-LIST) ...).

Find all nonterminals with a SPEC in databases.
See semanticdb-find-nonterminal-by-function for details on DATABASES,
SEARCH-PARTS, SEARCH-INCLUDESDIFF-MODE, and FIND-FILE-MATCH.
Return a list ((DB-TABLE . TOKEN-LIST) ...).

Find all nonterminals with a SPEC equal to VALUE in databases.
See semanticdb-find-nonterminal-by-function for details on DATABASES,
SEARCH-PARTS, SEARCH-INCLUDESDIFF-MODE, and FIND-FILE-MATCH.
Return a list ((DB-TABLE . TOKEN-LIST) ...).

Function:semanticdb-file-streamfile

Return a list of tokens belonging to FILE.
If file has database tokens available in the database, return them.
If file does not have tokens available, then load the file, and create them.

11.4.1.4 Copy/Paste

Token Copy/Paste is a high level form of the typical copy yank used by
Emacs. Copying a token 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.

Command:senator-copy-token

Take the current token, and place it in the token ring.

Command:senator-kill-token

Take the current token, place it in the token ring, and kill it.
Killing the token removes the text for that token, and places it into
the kill ring. Retrieve that text with yank.

Command:senator-yank-token

Yank a token from the token ring.
The form the token takes is different depending on where it is being
yanked to.

Command:senator-copy-token-to-registerregister &optional kill-flag

Copy the current token into REGISTER.
Optional argument KILL-FLAG will delete the text of the token to the
kill ring.

For programmers, to provide specialized pasting, created an override
function for insert-foreign-token (see See section 6.1 Settings.)

11.4.2 Customization

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

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

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

Option:senator-step-at-token-ids

List of token identifiers where to step.
Token identifier is symbol 'variable, 'function, 'type, or other. If
nil navigation steps at any token found. This is a buffer local
variable. It can be set in a mode hook to get a specific language
navigation.

Option:senator-step-at-start-end-token-ids

List of token identifiers where to step at start and end.
Token identifier is symbol 'variable, 'function, 'type, or other. If
nil navigation only step at beginning of tokens. If t step at start
and end of any token where it is allowed to step. Also, stepping at
start and end of a token prevent stepping inside its children. This
is a buffer local variable. It can be set in a mode hook to get a
specific language navigation.

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

11.4.3 Contact information for Senator

11.5 Semantic Analyzer

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

Command:semantic-analyze-current-contextposition

Analyze the current context at POSITION.
If called interactively, display interesting information about POSITION
in a separate buffer.
Returns an object based on symbol semantic-analyze-context.

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

Another command that uses the analyzer context derives a completion
list.

Command:semantic-analyze-possible-completionscontext

Return a list of semantic tokens which are possible completions.
CONTEXT is either a position (such as point), or a pre-calculated
context. Passing in a context is useful if the caller also needs
to access parts of the analysis.

Completions run through the following filters:

Elements currently in scope

Constants currently in scope

Elements match the :prefix in the CONTEXT.

Type of the completion matches the type of the context.

Context type matching can identify the following:

No specific type

Assignment into a variable of some type.

Argument to a function with type constraints.

When called interactively, this function displays the list of
possible completions. This is useful for debugging.

11.5.1 Smart Completion

The 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.

Command:semantic-ia-complete-symbolpoint

Complete the current symbol at POINT.
Completion options are calculated with
semantic-analyze-possible-completions.

Command:semantic-ia-complete-symbol-menupoint

Complete the current symbol via a menu based at POINT.
Completion options are calculated with
semantic-analyze-possible-completions.

11.5.2 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
semantic-analyze-possible-completions11.5 Semantic 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.

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.

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

11.6 Class Browser

The semantic class browser is a library that can covert a project
group of files into an EIEIO based structure that contains links
between structures so that the inheritance links between semantic
tokens can be easily navigated.

The core to this library is one function in `semantic-cb.el'.

Function:semantic-cb-new-class-browser

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

Use the Emacs function `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:

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.

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

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 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.

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

Command: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.

Command:document-inline

Document the current function with an inline comment.

Command:document-insert-defun-commentnonterm buffer

Insert mode-comment documentation about NONTERM from BUFFER.

Command:document-insert-new-file-headerheader

Insert a new header file into this buffer. Add reference to HEADER.
Used by prototype if this file doesn't have an introductory comment.

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

Command:semantic-texi-update-doc&optional token

Update the documentation for TOKEN.
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.

Command:semantic-texi-goto-source&optional token

Jump to the source for the definition in the texinfo file TOKEN.
If TOKEN is nil, it is derived from the deffn under POINT.

11.8 Charting Commands

Create a bar chart representing the number of nonterminals for a token.
Each bar represents how many toplevel nonterminal in BUFFER-OR-STREAM
exist with a given token type. See `semantic-symbol->name-assoc-list'
for tokens which will be charted.

Command:semantic-chart-database-size&optional buffer-or-stream

Create a bar chart representing the size of each file in semanticdb.
Each bar represents how many toplevel nonterminals in BUFFER-OR-STREAM
exist in each database entry.

Create a bar chart representing the complexity of some tokens.
Complexity is calculated for tokens with a token of SYMBOL. Each bar
represents the complexity of some nonterminal in BUFFER-OR-STREAM.
Only the most complex items are charted.

11.9 Minor Modes

Command:semantic-show-dirty-mode&optional arg

Minor mode for highlighting dirty tokens.
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.

Command:global-semantic-show-dirty-mode&optional arg

Toggle global use of semantic-show-dirty-mode.
If ARG is positive, enable, if it is negative, disable.
If ARG is nil, then toggle.

Option:semantic-dirty-token-face

Face used to show dirty tokens in semantic-show-dirty-token-mode.

Command:semantic-show-unmatched-syntax-mode&optional arg

Minor mode to highlight unmatched-syntax tokens.
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.

Command:global-semantic-show-unmatched-syntax-mode&optional arg

Toggle global use of semantic-show-unmatched-syntax-mode.
If ARG is positive, enable, if it is negative, disable.
If ARG is nil, then toggle.

Option:semantic-unmatched-syntax-face

Face used to show unmatched-syntax in.
The face is used in semantic-show-unmatched-syntax-mode.

Command:global-semantic-auto-parse-mode&optional arg

Toggle global use of semantic-auto-parse-mode.
If ARG is positive, enable, if it is negative, disable.
If ARG is nil, then toggle.

Command:semantic-auto-parse-mode&optional arg

Minor mode to auto parse buffer following changes.
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.

Option:semantic-auto-parse-no-working-message

Non-nil disable display of working message during parse.

Option:semantic-auto-parse-idle-time

Time in seconds of idle time before auto-reparse.
This time should be short enough to ensure that auto-parse will be
run as soon as Emacs is idle.

Option:semantic-auto-parse-max-buffer-size

Maximum size in bytes of buffers automatically re-parsed.
If this value is less than or equal to 0 buffers are automatically
re-parsed regardless of their size.