| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Several tools come with Semantic which would not be possible without it. In general, these tools will work with any language supported by Semantic.
| 11.1 Speedbar | How to use Semantic speedbar support | |
| 11.2 Imenu support | Special support for Imenu. | |
| 11.3 Semantic Database | Cache your parsed buffers between sessions. | |
| 11.4 Semantic Navigator | The Semantic Navigator | |
| 11.5 Semantic Analyzer | Analyze local context | |
| 11.6 Class Browser | Class hierarchy browser | |
| 11.7 Document generation | Document generation functions | |
| 11.8 Charting Commands | Charting code statistics | |
| 11.9 Minor Modes | Useful minor modes |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
Two additional speedbar modes are described in 11.5.2 Speedbar Analysis, and 11.6 Class Browser.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 "TOKENS")))
|
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:
nil if tokens in a file are to be grouped into buckets.
nil if buckets of tokens are to be turned into submenus.
This option is ignored if semantic-imenu-bucketize-file is nil.
nil if types should have submenus with parts in it.
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.
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.
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:
type has interesting children. In Texinfo, however,
a section has interesting children.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
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.
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
As such, all search functions return a list of the form:
( (DATABASE TOKEN1 TOKEN2 ...) (DATABASE2 TOKEN3 TOKEN4 ...) ...) |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Senator stands for SEmantic NAvigaTOR and was written by David Ponce.
This library defines commands and a minor mode to navigate between semantic language tokens in the current buffer.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following user level commands are provided by Senator.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Completion in senator scans all known definitions in the local file, and uses that information to provide the completion.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
yank.
For programmers, to provide specialized pasting, created an override
function for insert-foreign-token (see See section 6.1 Settings.)
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following default key bindings are provided when semantic minor mode is enabled:
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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:
'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.
'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:
(add-hook 'mode-hook
(lambda ()
(setq senator-step-at-token-ids '(function variable))
(setq senator-step-at-start-end-token-ids '(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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Any comments, suggestions, bug reports or upgrade requests are welcome. Please send them to David Ponce at david@dponce.com
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The semantic analyzer is a library tool that performs context analysis and can derive useful information.
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.
Completions run through the following filters:
:prefix in the CONTEXT.
Context type matching can identify the following:
When called interactively, this function displays the list of possible completions. This is useful for debugging.
| 11.5.1 Smart Completion | Commands for smart completion. | |
| 11.5.2 Speedbar Analysis | Display an analysis in speedbar. |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 11.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.
You can also enter speedbar analyzer mode by selecting "Analyze" from the "Display" menu item on speedbar's menu.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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'.
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:
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The document program uses semantic token streams 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 `semantic.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:
nil, query for a new documentation file.
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.
nil, it is derived from the deffn under POINT.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Some commands to draw charts of statistics generated from parsing:
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
nil if the
minor mode is enabled.
semantic-show-dirty-mode.
If ARG is positive, enable, if it is negative, disable.
If ARG is nil, then toggle.
semantic-show-dirty-token-mode.
nil if the
minor mode is enabled.
nil, then toggle.
nil, then toggle.
nil if the
minor mode is enabled.
nil disable display of working message during parse.
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |