This is semantic-user.info, produced by makeinfo version 4.3 from
user-guide.texi.

This is the Semantic User's Manual

   Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005 Eric M. Ludlam
Copyright (C) 2001, 2002, 2003, 2004 David Ponce Copyright (C) 2002,
2003 Richard Y. Kim

     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".
   
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Semantic User's guide: (semantic-user).
END-INFO-DIR-ENTRY

   This is the Semantic User's Guide _Infrastructure for parser based
text analysis in Emacs_

   Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004 Eric M. Ludlam,
David Ponce, and Richard Y. Kim


File: semantic-user.info,  Node: Top,  Next: speedbar,  Up: (dir)

Semantic User's Guide
*********************

This chapter describes how to use 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.
* Customizing::
* GNU Free Documentation License::
* Index::


File: semantic-user.info,  Node: speedbar,  Next: ECB,  Prev: Top,  Up: Top

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

Two additional speedbar modes are described in *Note Speedbar
Analysis::, and *Note Class Browser::.


File: semantic-user.info,  Node: ECB,  Next: imenu,  Prev: speedbar,  Up: Top

ECB
***

From the ECB Website: <http://ecb.sourceforge.net>:

     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.


File: semantic-user.info,  Node: imenu,  Next: senator,  Prev: ECB,  Up: Top

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 `.emacs' file:

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

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 found in `semantic-format-tag-functions'.

 - Option: semantic-imenu-bucketize-file
     Non-`nil' if tags in a file are to be grouped into buckets.

 - Option: semantic-imenu-buckets-to-submenu
     Non-`nil' if buckets of tags are to be turned into submenus.  This
     option is ignored if `semantic-imenu-bucketize-file' is nil.

 - Option: semantic-imenu-expand-type-members
     Non-`nil' if types should have submenus with members in them.

 - Option: semantic-imenu-bucketize-type-members
     Non-`nil' if members of a type should be grouped into buckets.
     `nil' means to keep them in the same order.  Overriden 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.
     See "semantic-bucketize" and the FILTER argument for more details
     on this function.

 - 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-tag-classes
     List of expandable tag classes.  Tags of those classes will be
     given submenu with children.  By default, a `type' has interesting
     children.  In Texinfo, however, a `section' has interesting
     children.


File: semantic-user.info,  Node: senator,  Next: Analyzer,  Prev: imenu,  Up: Top

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.

Commands
========

The following user level commands are provided by Senator.

Navigation
----------

 - Function: senator-next-tag
     Navigate to the next Semantic tag.  Return the tag or `nil' if at
     end of buffer.

 - Function: senator-previous-tag
     Navigate to the previous Semantic tag.  Return the tag or `nil' if
     at beginning of buffer.

 - Function: senator-jump
     Jump to the semantic symbol SYM.

     If optional IN-CONTEXT is non-`nil' jump in the local type's
     context (see function "senator-current-type-context").  If optional
     NO-DEFAULT is non-`nil' do not provide a default value.

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

     - `C-u'       IN-CONTEXT.  - `C-u' -     NO-DEFAULT.  - `C-u'
     `C-u'   IN-CONTEXT + NO-DEFAULT.

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.

 - Command: senator-isearch-toggle-semantic-mode
     Toggle semantic searching on or off in isearch mode.  `C-c , i'
     toggle semantic searching.

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

 - Command: re-search-forward regex
 - Command: re-search-backward regex
     Search forward and backward for a token matching the regular
     expression REGEX.

 - Command: word-search-forward word
 - Command: word-search-backward word
     Search forward and backward for a token whose name matches WORD.

Completion
----------

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

 - Command: senator-complete-symbol &optional cycle-once
     Complete the current symbol under point.  If optional argument
     CYCLE-ONCE is non-`nil', only cycle through the list of
     completions once, doing nothing where there are no more matches.

 - 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
     "imenu-mouse-menu" to handle the popup menu.

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.

 - Command: senator-copy-tag
     Take the current tag, and place it in the tag ring.

 - 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 `C-y'.

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

 - Command: senator-copy-tag-to-register register &optional kill-flag
     Copy the current tag into REGISTER.  Optional argument KILL-FLAG
     will delete the text of the tag to the kill ring.

For programmers, to provide specialized pasting, created an override
function for `insert-foreign-tag' (see *note (semantic-langdev)Writing
Parsers::.)

Minor Mode
----------

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

    <C-c , n>
          senator-next-tag

    <C-c , p>
          senator-previous-tag

    <C-c , i>
          senator-isearch-toggle-semantic-mode

    <C-c , j>
          semantic-complete-jump-local

    <C-c , J>
          semantic-complete-jump

    <C-c , TAB>
          senator-complete-symbol

    <C-c , SPC>
          senator-completion-menu-popup

    <C-c , C-y>
          senator-yank-tag

    <C-c , C-w>
          senator-kill-tag

    <C-c , M-w>
          senator-copy-tag

    <C-c , +>
          senator-unfold-tag

    <C-c , ->
          senator-fold-tag

Customization
=============

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

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

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

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

 - Option: senator-step-at-tag-classes
     List of tag classes where to step.  A tag class is a symbol like
     `'variable', `'function', `'type', or other.  If `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.

 - 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 `'variable', `'function', `'type', or other.  If
     `nil', navigation only step at beginning of tags.  If `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.

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

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

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


File: semantic-user.info,  Node: Analyzer,  Next: Class Browser,  Prev: senator,  Up: Top

Analyzer
********

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

 - Command: semantic-analyze-current-context position
     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 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 can derive a completion
list.

 - Command: semantic-analyze-possible-completions context
     Return a list of semantic tags which are possible completions.
     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:
    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, displays the list of possible
          completions in a buffer.

* Menu:

* Smart Completion::
* Speedbar Analysis::


File: semantic-user.info,  Node: Smart Completion,  Next: Speedbar Analysis,  Up: Analyzer

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-symbol point
     Complete the current symbol at POINT.  Completion options are
     calculated with "semantic-analyze-possible-completions".

 - Command: semantic-ia-complete-symbol-menu point
     Complete the current symbol via a menu based at POINT.  Completion
     options are calculated with
     "semantic-analyze-possible-completions".

 - Command: semantic-ia-show-doc point
     Display the code-level documentation for the symbol at POINT.


File: semantic-user.info,  Node: Speedbar Analysis,  Prev: Smart Completion,  Up: Analyzer

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-completions"
*Note 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.


File: semantic-user.info,  Node: Class Browser,  Next: Document,  Prev: Analyzer,  Up: Top

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


File: semantic-user.info,  Node: Document,  Next: Charts,  Prev: Class Browser,  Up: Top

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 `document.el' that comes with semantic:

     (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."
       ...
       )

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 `user-guide.texi' file:

     @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

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-comment tag buffer
     Insert mode-comment documentation about TAG from BUFFER.

 - Command: document-insert-new-file-header header
     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 tag
     Update the documentation for 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.

 - Command: semantic-texi-goto-source &optional tag
     Jump to the source for the definition in the texinfo file TAG.  If
     TAG is `nil', it is derived from the deffn under POINT.


File: semantic-user.info,  Node: Charts,  Next: Idle Scheduler,  Prev: Document,  Up: Top

Charts
******

Some commands to draw charts of statistics generated from parsing:

 - 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 TAGTABLE
     exist with a given class.  See `semantic-symbol->name-assoc-list'
     for tokens which will be charted.  TAGTABLE is passedto
     "semantic-something-to-tag-table".

 - 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
     TAGTABLE exist in each database entry.  TAGTABLE is passedto
     "semantic-something-to-tag-table".

 - 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 CLASS.  Each bar
     represents the complexity of some nonterminal in TAGTABLE.  Only
     the most complex items are charted.  TAGTABLE is passedto
     "semantic-something-to-tag-table".


File: semantic-user.info,  Node: Idle Scheduler,  Next: Minor Modes,  Prev: Charts,  Up: Top

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.

 - Command: global-semantic-idle-scheduler-mode &optional arg
     Toggle global use of option "semantic-idle-scheduler-mode".  The
     idle scheduler with automatically reparse buffers in idle time,
     and then schedule other jobs setup with
     "semantic-idle-scheduler-add".  If ARG is positive, enable, if it
     is negative, disable.  If ARG is `nil', then toggle.

     *Compatibility*: `global-semantic-idle-scheduler-mode' introduced
     in semantic version 2.0 supercedes
     `global-semantic-auto-parse-mode' which is now obsolete.


*Compatibility*: `semantic-idle-scheduler-mode' introduced in semantic
version 2.0 supercedes `semantic-auto-parse-mode' which is now obsolete.

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

 - Option: semantic-idle-scheduler-mode-hook
     Hook run at the end of function "semantic-idle-scheduler-mode".

You can add new functionality to the idle scheduler by reading the
Application Developers Guide *note (semantic-appdev.info)Idle
Scheduling::.

* Menu:

* Reparsing Options::
* Idle Summary Mode::
* Idle Completions Mode::


File: semantic-user.info,  Node: Reparsing Options,  Next: Idle Summary Mode,  Up: Idle Scheduler

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.

Reparse Configuration
---------------------

 - Option: semantic-idle-scheduler-max-buffer-size
     Maximum size in bytes of buffers automatically reparsed.  If this
     value is less than or equal to 0, buffers are automatically
     reparsed regardless of their size.

Reparse Messages
----------------

 - Option: semantic-idle-scheduler-no-working-message
     If non-`nil', disable display of working messages during parse.

 - Option: semantic-idle-scheduler-working-in-modeline-flag
     Non-`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.

Reprasing Hooks
---------------

 - Variable: semantic-before-idle-scheduler-reparse-hooks
     Hooks run before option `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.

 - Variable: semantic-after-idle-scheduler-reparse-hooks
     Hooks run after option `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.


File: semantic-user.info,  Node: Idle Summary Mode,  Next: Idle Completions Mode,  Prev: Reparsing Options,  Up: Idle Scheduler

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.

 - semantic-idle-summary-mode: &optional arg
     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 `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


*Compatibility*: `semantic-idle-summary-mode' introduced in semantic
version 2.0 supercedes `semantic-summary-mode' which is now obsolete.

 - Option: semantic-idle-summary-function
     Function to use when displaying tag information during idle time.
     Some useful functions are found in `semantic-format-tag-functions'.


File: semantic-user.info,  Node: Idle Completions Mode,  Prev: Idle Summary Mode,  Up: Idle Scheduler

Idle Completions Mode
=====================

The definition of completion lists is described in the Analyzer section
*Note 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.

 - semantic-idle-completions-mode: &optional arg
     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
     `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

This mode operates by using the command
`semantic-complete-inline-analyzer'.


File: semantic-user.info,  Node: Minor Modes,  Next: semanticdb,  Prev: Idle Scheduler,  Up: Top

Minor Modes
***********

Semantic comes with a wide range of minor-modes which use various
features of semantic.  These modes vary widly in utility.

There are some core modes that are required for smooth operations.
Some of these are discussed in other chapters, such as *Note Idle
Scheduler::, and *Note semanticdb::

* Menu:

* Code Helpers::        Modes for assisting in authoring code.
* Development Modes::   Modes for assisting in developing/debugging Semantic.


File: semantic-user.info,  Node: Code Helpers,  Next: Development Modes,  Up: Minor Modes

Code Helpers
============

Code Helpers are minor modes that augment basic Emacs behavior in ways
that can assist in programming Semantic supported langauges.

* Menu:

* Sticky Function Mode::
* Tag Decoration Mode::

Senator is another mode which can assist in programming *Note senator::.


File: semantic-user.info,  Node: Development Modes,  Prev: Code Helpers,  Up: Minor Modes

Development Modes
=================

* Menu:

* Highlight Edits Mode::
* Parser State::
* Unmatched Syntax Highlighting::


File: semantic-user.info,  Node: Sticky Function Mode,  Next: Tag Decoration Mode,  Up: Code Helpers

Sticky Function Headers
-----------------------

 - Command: semantic-stickyfunc-mode &optional arg
     Minor mode to show the title of a tag in the header line.
     Enables/disables making the header line of functions sticky.  A
     function (or other tag class specified by
     `semantic-stickyfunc-sticky-classes') has a header line, meaning
     the first line which describes the rest of the construct.  This
     first line is what is displayed in the Emacs 21 header line.

     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.

 - Variable: semantic-stickyfunc-sticky-classes
     List of tag classes which sticky func will display in the header
     line.


File: semantic-user.info,  Node: Tag Decoration Mode,  Prev: Sticky Function Mode,  Up: Code Helpers

Tag Decoration Mode
-------------------

Decoration mode is a harness that allows any parsed tag to be
highlighted based on some arbitrary feature of that tag.  Decoration
mode is actually a full harness for providing any kind of decoration on
a tag based on a prefix function.

 - Command: semantic-decoration-mode &optional arg
     Minor mode for decorating tags.  Decorations are specified in
     `semantic-decoration-styles'.  You can define new decoration
     styles with "define-semantic-decoration-style".  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.

To enable or disable specific decorations, you can use this function:

 - Command: semantic-toggle-decoration-style name &optional arg
     Turn on/off the decoration style with NAME.  Decorations are
     specified in `semantic-decoration-styles'.  With prefix argument
     ARG, turn on if positive, otherwise off.  Return non-`nil' if the
     decoration style is enabled.

You can create new types of decorations using the following function:

 - Function: define-semantic-decoration-style name doc &rest flags
     Define a new decoration style with NAME.  DOC is a documentation
     string describing the decoration style NAME.  It is appended to
     auto-generated doc strings.  An Optional list of FLAGS can also be
     specified.  Flags are:   `:enabled' <value>  - specify the default
     enabled value for NAME.

     This defines two new overload functions respectively called
     `NAME-p' and `NAME-highlight', for which you must provide a default
     implementation in respectively the functions `NAME-p-default' and
     `NAME-highlight-default'.  Those functions are passed a tag.
     `NAME-p' must return non-`nil' to indicate that the tag should be
     decorated by `NAME-highlight'.

     To put primary decorations on a tag `NAME-highlight' must use
     functions like "semantic-set-tag-face",
     "semantic-set-tag-intangible", etc., found in the
     semantic-decorate library.

     To add other kind of decorations on a tag, `NAME-highlight' must
     use "semantic-decorate-tag", and other functions of the semantic
     decoration API found in this library.


File: semantic-user.info,  Node: Highlight Edits Mode,  Next: Parser State,  Up: Development Modes

Highlight Edits Mode
--------------------

Highlight edits mode is useful mostly for debugging the incremental
parser.  As you change text, that effected text is highlighted, and you
can visual predict what actions the incremental parser will need to
make.

 - Command: semantic-highlight-edits-mode &optional arg
     Minor mode for highlighting changes made in a buffer.  Changes are
     tracked by semantic so that the incremental parser can work
     properly.  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.

 - Face: semantic-highlight-edits-face
     Face used to show dirty tokens in `semantic-highlight-edits-mode'.


File: semantic-user.info,  Node: Parser State,  Next: Unmatched Syntax Highlighting,  Prev: Highlight Edits Mode,  Up: Development Modes

Parser State
------------

 - Command: semantic-show-parser-state-mode &optional arg
     Minor mode for displaying parser cache state in the modeline.  The
     cache can be in one of three states.  They are Up to date, Partial
     reprase needed, and Full reparse needed.  The state is indicated
     in the modeline with the following characters:
    `-'
          The cache is up to date.

    `!'
          The cache requires a full update.

    `~'
          The cache needs to be incrementally parsed.

    `%'
          The buffer is not lexically parseable.

    `@'
          Auto-parse in progress (not set here.)  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.


File: semantic-user.info,  Node: Unmatched Syntax Highlighting,  Prev: Parser State,  Up: Development Modes

Unmatched Syntax Highlighting
-----------------------------

 - Command: semantic-show-unmatched-syntax-mode &optional arg
     Minor mode to highlight unmatched syntax tokens.  When a parser
     executes, some elements in the buffer may not match any parser
     rules.  These text characters are considered unmatched syntax.
     Often time, the display of unmatched syntax can expose coding
     problems before the compiler is run.

     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.

     `C-c , `'		"semantic-show-unmatched-syntax-next"

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


File: semantic-user.info,  Node: semanticdb,  Next: Customizing,  Prev: Minor Modes,  Up: Top

Semantic Database
*****************

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 `.emacs' file:

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

If you use `semantic-load.el', or the default CEDET install mechanism,
you do not need to add the above lines in your `.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.

Core Tables
     These core tables for semanticdb are not associated with files, or
     backends.  They define the basic behavior of a database and table.

Persistent Tables
     These databases are what are generally used in semantic to store
     information to disk.

Custom Backends
     These databases and tables are interfaces to some other source of
     tagging informatin, such as the symbols loaded in Emacs Lisp, or
     perhaps symbols in a Java `.class' file.

Semanticdb Configuration
========================

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

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

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.

 - Option: semanticdb-default-file-name
     File name of the semantic tag cache.

 - Option: semanticdb-default-save-directory
     Directory name where semantic cache files are stored.  If this
     value is `nil', files are saved in the current directory.  If the
     value is a valid directory, then it overrides
     `semanticdb-default-file-name' and stores caches in a coded file
     name in this directory.

 - Option: semanticdb-persistent-path
     List of valid paths that semanticdb will cache tags to.  When
     "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.  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 `semanticdb-project-predicate-functions'.

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

     Project Management software (such as EDE and JDE) should add their
     own predicates with "add-hook" to this variable, and semanticdb
     will save tag caches in directories controlled by them.

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

Semanticdb Search Configuration
-------------------------------

 - 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 overriden by
     project management programs via the
     `semanticdb-project-root-functions' variable.

 - Variable: semanticdb-project-root-functions
     List of functions used to determine a given directories project
     root.  Functions in this variable can override
     `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 EDE or JDE.

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.

 - Variable: semanticdb-find-default-throttle
     The default throttle for `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:

    `file'
          The file the search is being performed from.  This option is
          here for completeness only, and is assumed to always be on.

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

    `project'
          Tables from the same local project are included If `project'
          is specified, then `local' is assumed.

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

    `system'
          Tables from system databases.  These are specifically tables
          from system header files, or language equivalent.

    `recursive'
          For include based searches, includes tables referenced by
          included files.

    `omniscience'
          Included system databases which are omniscience, or somehow
          know everything.  Omniscience databases are found in
          `semanticdb-project-system-databases'.  The Emacs Lisp system
          DB is an omniscience database.


To test the throttle varuable, use this command.

 - Command: semanticdb-find-test-translate-path &optional arg
     Call and output results of "semanticdb-find-translate-path" With
     ARG non-`nil', specify a BRUTISH translation.

Semanticdb System Backends
--------------------------

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

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

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

 - Variable: semanticdb-search-system-databases
     Non `nil' if search routines are to include a system database.

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.

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

Script Generated Cache Files
----------------------------

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

     $ semanticdb.sh *.el

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:

 - Command: semanticdb-create-system-database path &optional class
     Create a system database starting at PATH.  PATH should be a top
     level directory for a series of files containing declarations for
     SYSTEM files.  In C, this would be header filaes.  CLASS is the
     class for the database to create.  Only child classes of symbol
     "semanticdb-project-database-system" are accepted.

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


File: semantic-user.info,  Node: Customizing,  Next: GNU Free Documentation License,  Prev: semanticdb,  Up: Top

Customizing
***********

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

