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, 2006, 2007 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. * Speed Debug:: How to debug speed issues. * 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: : 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: senator-next-tag senator-previous-tag senator-isearch-toggle-semantic-mode semantic-complete-jump-local semantic-complete-jump senator-complete-symbol senator-completion-menu-popup senator-yank-tag senator-kill-tag senator-copy-tag senator-unfold-tag 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:: Functions you can bind to keys for completion * Smart Idle Completion:: Automatic completion popups * Speedbar Analysis:: Speedbar provided completion  File: semantic-user.info, Node: Smart Completion, Next: Smart Idle Completion, 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-complete-tip point Pop up a tooltip for completion at POINT. - Command: semantic-ia-show-summary point Display a summary for the symbol under POINT. - Command: semantic-ia-show-doc point Display the code-level documentation for the symbol at POINT.  File: semantic-user.info, Node: Smart Idle Completion, Next: Speedbar Analysis, Prev: Smart Completion, Up: Analyzer 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 *Note Idle Scheduler:: for more on the Scheduler. Summaries are provided with `semantic-idle-summary-mode'. See *Note Idle Summary Mode::. Completions are provided with `semantic-idle-completions-mode'. See *Note Idle Completions Mode::.  File: semantic-user.info, Node: Speedbar Analysis, Prev: Smart Idle 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 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:: * MRU Bookmarks 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, Next: MRU Bookmarks 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' - 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: MRU Bookmarks Mode, Prev: Tag Decoration Mode, Up: Code Helpers MRU Bookmarks Mode ------------------ MRU stands for Most Recently Used. Semantic MRU Bookmarks track the tags you edit and maintain a ring of things you've been working on. You can then switch back to tags you've worked on recently by name. - Command: semantic-mru-bookmark-mode &optional arg Minor mode for tracking tag-based bookmarks automatically. Tag based bookmarks a tracked based on editing and viewing habits and can then be navigated via the MRU bookmark keymap. 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. Once this mode is enbled, any edit, or mark setting will add the current tag to your MRU bookmark ring. `C-x B' This keysequence is like `switch-to-buffer', but uses a capital `B' instead of lower case. This lets you type in a tag name, or use `M-p' and `M-n' to cycle through the bookmark list in MRU order.  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: Speed Debug, 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 information, such as the symbols loaded in Emacs Lisp, or perhaps symbols in a Java `.class' file. 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. * Menu: * Semanticdb Tag Storage:: * Semanticdb Search Configuration:: * Semanticdb System Backends:: * Changing Backends:: * Script Generated Cache Files:: * Create System Databases::  File: semantic-user.info, Node: Semanticdb Tag Storage, Next: Semanticdb Search Configuration, Up: semanticdb 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.  File: semantic-user.info, Node: Semanticdb Search Configuration, Next: Semanticdb System Backends, Prev: Semanticdb Tag Storage, Up: semanticdb 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: 1. The current file 2. a table for each #include file 3. if 'recursive is in the throttle, then all include files included in include files. Include files or equivalent are found in: 1. current directory 2. directories specified by your project. (such as EDE, or the `semanticdb-project-roots' variable.) 3. system directories In C code, semantic tries to distinguish between project and system headers based on `""' or `<>' delimiters. Each language can distinguish using it's own rules. The system directory is set up via the variable `semantic-dependency-system-include-path'. The path is also modified by some system database create routines, such as `semanticdb-create-ebrowse-database'. *Note Include paths::. You can use the command: M-x semantic-add-system-include RET /some/path 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::  File: semantic-user.info, Node: Semanticdb Roots, Next: Include paths, Up: Semanticdb Search Configuration 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. - 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.  File: semantic-user.info, Node: Include paths, Next: Search Throttle, Prev: Semanticdb Roots, Up: Semanticdb Search Configuration Include Paths ------------- You can add and remove system include paths based on major mode using the following commands: - Command: semantic-add-system-include dir &optional mode Add a system include DIR to path for MODE. Modifies a mode-local version of `semantic-dependency-system-include-path'. - Command: semantic-remove-system-include dir &optional mode Add a system include DIR to path for MODE. Modifies a mode-local version of `semantic-dependency-system-include-path'.  File: semantic-user.info, Node: Search Throttle, Next: Semanticdb search debugging commands, Prev: Include paths, Up: Semanticdb Search Configuration 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. - 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 set the throttle, use a command like this: (setq-mode-local c-mode semanticdb-find-default-throttle '(project unloaded system recursive))  File: semantic-user.info, Node: Semanticdb search debugging commands, Prev: Search Throttle, Up: Semanticdb Search Configuration Semanticdb search debugging commands ------------------------------------ You can use `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 `M-x semanticdb-find-test-translate-path RET' to then make sure specific tables from the path are discovered correctly. - Command: semanticdb-dump-all-table-summary Dump a list of all databases in Emacs memory. - 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. Lastly, you can test an explicit search term using this command: - Command: semantic-adebug-searchdb regex Search the semanticdb for REGEX for the current buffer. Display the results as a debug list.  File: semantic-user.info, Node: Semanticdb System Backends, Next: Changing Backends, Prev: Semanticdb Search Configuration, Up: semanticdb 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.  File: semantic-user.info, Node: Changing Backends, Next: Script Generated Cache Files, Prev: Semanticdb System Backends, Up: semanticdb 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.  File: semantic-user.info, Node: Script Generated Cache Files, Next: Create System Databases, Prev: Changing Backends, Up: semanticdb 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  File: semantic-user.info, Node: Create System Databases, Prev: Script Generated Cache Files, Up: semanticdb 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. - Command: semanticdb-create-ebrowse-database dir Create an EBROSE database for directory DIR. The database file is stored in ~/.semanticdb, or whichever directory is specified by `semanticdb-default-system-save-directory'. 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.