# HG changeset patch # User Chong Yidong # Date 1258410349 0 # Node ID 014672c3a25fb45cae6fe8912ead8b39189b63b7 # Parent 2f9ecf376c7a5f7a87ca1861042988f31a9b487c * Makefile.in: Build the Semantic manual. * semantic.texi, sem-user.texi: New files, adapted from the Semantic repository. diff -r 2f9ecf376c7a -r 014672c3a25f doc/misc/ChangeLog --- a/doc/misc/ChangeLog Mon Nov 16 20:36:06 2009 +0000 +++ b/doc/misc/ChangeLog Mon Nov 16 22:25:49 2009 +0000 @@ -1,3 +1,10 @@ +2009-11-16 Chong Yidong + + * Makefile.in: Build the Semantic manual. + + * semantic.texi, sem-user.texi: New files, adapted from the Semantic + repository. + 2009-11-16 Michael Albinus * dbus.texi (Receiving Method Calls): New defun diff -r 2f9ecf376c7a -r 014672c3a25f doc/misc/Makefile.in --- a/doc/misc/Makefile.in Mon Nov 16 20:36:06 2009 +0000 +++ b/doc/misc/Makefile.in Mon Nov 16 22:25:49 2009 +0000 @@ -74,6 +74,7 @@ $(infodir)/reftex \ $(infodir)/sasl \ $(infodir)/sc \ + $(infodir)/semantic \ $(infodir)/ses \ $(infodir)/sieve \ $(infodir)/smtpmail \ @@ -122,6 +123,7 @@ remember.dvi \ sasl.dvi \ sc.dvi \ + semantic.dvi \ ses.dvi \ sieve.dvi \ smtpmail.dvi \ @@ -383,6 +385,12 @@ sc.dvi: sc.texi $(ENVADD) $(TEXI2DVI) ${srcdir}/sc.texi +semantic : $(infodir)/semantic +$(infodir)/semantic: semantic.texi sem-user.texi + cd $(srcdir); $(MAKEINFO) semantic.texi +semantic.dvi: semantic.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/semantic.texi + ses : $(infodir)/ses $(infodir)/ses: ses.texi cd $(srcdir); $(MAKEINFO) ses.texi diff -r 2f9ecf376c7a -r 014672c3a25f doc/misc/ede.texi --- a/doc/misc/ede.texi Mon Nov 16 20:36:06 2009 +0000 +++ b/doc/misc/ede.texi Mon Nov 16 22:25:49 2009 +0000 @@ -132,9 +132,9 @@ @node EDE Mode, Creating a project, EDE Project Concepts, top @chapter @ede{} Mode -@ede{} is implemented as a minor-mode, which augments other modes such as C -mode, and Texinfo mode. You can turn @ede{} on for all buffers by running -the command @code{global-ede-mode}, or by putting this in your +@ede{} is implemented as a minor-mode, which augments other modes such +as C mode, and Texinfo mode. You can enable @ede{} for all buffers by +running the command @code{global-ede-mode}, or by putting this in your @file{~/.emacs} file: @example diff -r 2f9ecf376c7a -r 014672c3a25f doc/misc/sem-user.texi --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/misc/sem-user.texi Mon Nov 16 22:25:49 2009 +0000 @@ -0,0 +1,787 @@ +@c This file is included by semantic.texi + +@c Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2007 +@c Free Software Foundation, Inc. + +@c Permission is granted to copy, distribute and/or modify this +@c document under the terms of the GNU Free Documentation License, +@c Version 1.3 or any later version published by the Free Software +@c Foundation; with no Invariant Sections, no Front-Cover Texts, and +@c no Back-Cover Texts. A copy of the license is included in the +@c section entitled ``GNU Free Documentation License''. + +You can begin using @semantic{} by enabling Semantic mode, a global +minor mode: type @kbd{M-x semantic-mode}, or click on the @samp{Source +Code Parsers (Semantic)} menu item in the @samp{Tools} menu. + +When Semantic mode is turned on, Emacs automatically parses each file +you visit. This allows you to use @semantic{} user commands in those +buffers. It also enables a number of ``helper'' minor modes for +saving tags, displaying tag information, and so forth. @xref{Semantic +mode}. + +To enable Semantic mode each time you start Emacs, add the line +@code{(semantic-mode 1)} to your initialization file. @xref{Init +File,,,emacs,Emacs manual}. + +@menu +* Semantic mode:: Global minor mode for @semantic{}. +* SemanticDB:: Caching parsed buffers between sessions. +* Idle Scheduler:: Performing @semantic{} operations when idle. +@end menu + +@node Semantic mode +@section Semantic mode +@cindex Semantic mode + +Semantic mode is a global minor mode for @semantic{} as a whole. When +enabled, each file you visit is automatically parsed, provided its +major mode is specified in the variable +@code{semantic-new-buffer-setup-functions} (the default is to parse +every buffer @semantic{} knows how to parse). + +In each parser-enabled buffer, a number of @semantic{} commands are +available for navigating, querying, and editing source code. +@xref{Semantic mode user commands}. Enabling Semantic mode also +installs a @samp{Development} menu on the menu-bar, with many of these +commands. + +In addition, enabling Semantic mode turns on certain auxilliary global +minor modes, as specified by the variable +@code{semantic-default-submodes}. The default auxilliary modes are +SemanticDB mode (@pxref{SemanticDB}) and Global Semantic Idle +Scheduler mode. You can also toggle the auxilliary minor modes +separately, using their mode functions (e.g. @kbd{M-x +semanticdb-minor-mode}), or via the @samp{Development} menu. These +auxilliary minor modes are described in the following sections. + +@defvar semantic-new-buffer-setup-functions +The value of this variable is an alist of functions to call for +setting up @semantic{} parsing in the buffer. Each element has the +form @code{(@var{mode} . @var{fn})}, where @var{mode} is a value of +@code{major-mode} for the buffer and @var{fn} is the corresponding +function for setting up the parser. @var{fn} is called, with no +arguments, after the major mode is initialized (and after the mode +hooks have been run). + +The default value enables @semantic{} for all supported major modes +(i.e., C, C++, Scheme, Javascript, Java, HTML, SRecode, and Make), but +you can remove modes from this list if you don't want to use +@semantic{} with them. +@end defvar + +@defvar semantic-default-submodes +The value of this variable is a list of symbols, specifying the +auxilliary minor modes to enable when enabling Semantic mode. The +valid mode symbols are: + +@itemize +@item @code{semantic-idle-scheduler-mode} (@pxref{Idle Scheduler}). +@item @code{semanticdb-minor-mode} (@pxref{SemanticDB}). +@item @code{semantic-idle-summary-mode} (@pxref{Idle Summary Mode}). +@item @code{semantic-idle-completions-mode} (@pxref{Idle Completions Mode}). +@item @code{semantic-highlight-func-mode} +@item @code{semantic-decoration-mode} +@item @code{semantic-stickyfunc-mode} +@item @code{semantic-mru-bookmark-mode} +@end itemize +@end defvar + +@menu +* Semantic mode user commands:: +@end menu + +@node Semantic mode user commands +@subsection Semantic mode user commands + +Semantic mode provides a number of commands for navigating, querying, +and editing source code in a language-aware manner. These commands +generally act on @dfn{tags}, which are the source-code units deemed +``important'' by the present programming language (e.g. functions in +the C programming language). + +These commands may be used in any buffer that has been parsed by +@semantic{}. Several of them prompt for a tag name using the +minibuffer; here, the @kbd{TAB} key can be used to complete tag names. +Others act on the @dfn{current tag}, meaning the tag at (or around) +point. + +@table @kbd +@item \C-c , j +Prompt for a tag defined in the current file, and move point to it +(@code{semantic-complete-jump-local}). + +@item \C-c , J +Prompt for a tag defined in any file that Emacs has parsed, and move +point to it (@code{semantic-complete-jump}). + +@item \C-c , l +Display a list of the possible completions of the current tag +(@code{semantic-analyze-possible-completions}). + +@item \C-c , g +Prompt for a tag, and display a list of tags that call it +(@code{semantic-symref-symbol}). + +@item \C-c , G +Display a list of tags that call the current tag +(@code{semantic-symref}). + +@item \C-c , p +Move point to the previous tag (@code{senator-previous-tag}). + +@item \C-c , n +Move point to the next tag (@code{senator-next-tag}). + +@item \C-c , u +Move point ``up'' one reference (@code{senator-go-to-up-reference}). +The meaning of ``up'' is language-dependent; in C++, for instance, +this means moving to the parent of the current tag. + +@item \C-c, @key{SPC} +(@code{semantic-complete-analyze-inline}) + +@item \C-c,\C-w +Kill the current tag (@code{senator-kill-tag}). This removes the text +for that tag, placing it in the kill ring. You can retrieve the text +with @kbd{C-y}. This also places the tag in the @dfn{tag ring}, so +that you can yank it with @kbd{\C-c,\C-y}, below. + +@item \C-c,\M-w +Copy the current tag into the kill ring as well as the tag ring +(@code{senator-copy-tag}). + +@item \C-c,\C-y +Yank a tag from the tag ring (@code{senator-yank-tag}). + +@item \C-c,r +Copy the current tag into a register +(@code{senator-copy-tag-to-register}). With an optional argument, +kill it as well. This allows you to insert or jump to that tag with +the usual register commands. @xref{Registers,,,emacs,Emacs manual}. + +@item ?\C-c , @kbd{up} +Transpose the current tag with the previous one +(@code{senator-transpose-tags-up}). + +@item ?\C-c ?, @kbd{down} +Transpose the current tag with the next one +(@code{senator-transpose-tags-down}). +@end table + +@node SemanticDB +@section Semantic Database +@cindex SemanticDB + +The Semantic Database (SemanticDB) caches the results of parsing +source code files. This data can be saved to disk when you exit +Emacs, and reloaded automatically when you subsequently revisit the +same source code files. This saves time by eliminating the need to +re-parse unmodified files. + +SemanticDB also provides an @acronym{API} that programs can use to +acquire information about source code tags. This information can be +accessed without loading the original the source files into memory. +It can also be used to create alternate ``back-ends'' for storing tag +information in alternative on-disk formats. + +By default, SemanticDB is enabled together with Semantic mode. To +disable it, remove it from @code{semantic-default-submodes} +(@pxref{Semantic mode}). You can also enable or disable SemanticDB +with @kbd{M-x global-semanticdb-minor-mode}. + +@deffn Command global-semanticdb-minor-mode +Toggle SemanticDB mode. When enabled, any source code parsed by +@semantic{} is cached in a database. +@end deffn + +SemanticDB offers a large number of customizable options, which are +described in the following subsections. + +@menu +* Semanticdb Tag Storage:: +* Semanticdb Search Configuration:: +* Changing Backends:: +* Script Generated Cache Files:: +* Create System Databases:: +@end menu + +@node Semanticdb Tag Storage +@subsection Semanticdb Tag Storage + +Each time you exit Emacs, any data cached by SemanticDB is saved in +the directory @file{.emacs.d/semanticdb/}, located in your home +directory. Within this directory, the cache data is written into a +set of files according to a SemanticDB-specific filename convention. +If the SemanticDB directory does not exist, Emacs first asks if you +want to create it. + +You can change the name of the SemanticDB directory by customizing the +variable @code{semanticdb-default-save-directory}. + +@anchor{semanticdb-default-save-directory} +@deffn Option semanticdb-default-save-directory +The name of the directory where SemanticDB cache files are saved. If +the value is @code{nil}, SemanticDB saves its data into a single file, +in the current directory, whose filename is given by +@code{semanticdb-default-file-name}. +@end deffn + +@anchor{semanticdb-default-file-name} +@deffn Option semanticdb-default-file-name +The name of a cache file in which to save SemanticDB, when +@code{semanticdb-default-save-directory} is @code{nil}. +@end deffn + +You can force SemanticDB to save the data from only certain files, or +suppress saving altogether, by customizing +@code{semanticdb-persistent-path}: + +@anchor{semanticdb-persistent-path} +@deffn Option semanticdb-persistent-path +List of valid paths for SemanticDB to cache. Each element should be a +directory name (a string); then the parse data from any file in that +directory is saved. + +As a special exception, the value of this variable can be a list +containing a single symbol: @code{never}, @code{always}, or +@code{project}. The symbol @code{never} disables saving anywhere; +@code{always} enables saving everywhere; and @code{project} enables +saving directory based on the variable +@code{semanticdb-project-predicate-functions}. + +The default value is @code{(always)}. +@end deffn + +@anchor{semanticdb-project-predicate-functions} +@defvar semanticdb-project-predicate-functions +The value of this variable is a list of predicates for indicating that +a directory belongs to a project. This list is used when the value of +@code{semanticdb-persistent-path} is @code{(project)}. If the list is +empty, all paths are considered valid. + +Project management packages, such as EDE (@pxref{Top,,,ede,EDE +manual}), may add their own predicates with @dfn{add-hook} to this +variable. This allows SemanticDB to save tag caches in directories +controlled by them. +@end defvar + +@anchor{semanticdb-save-database-hooks} +@deffn Option semanticdb-save-database-hooks +Abnormal hook run after a database is saved. Each function is called +with one argument, the object representing the database recently +written. +@end deffn + +@node Semanticdb Search Configuration +@subsection Semanticdb Search Configuration + + When another part of @semantic{} (or another Emacs package using +@semantic{}) searches for a tag within SemanticDB, the SemanticDB +library may perform a search in the locations of the database: + +@enumerate +@item +The entries defined by the current file. +@item +The entries defined by the @dfn{include files} of the current file. +@item +The entries defined by the include files included from the include +files (and so on, recursively). +@end enumerate + +In C and C++, for instance, include files are defined with the +@samp{#include} preprocessor directive (SemanticDB tries to +distinguish between project and system headers, based on the @code{""} +and @code{<>} filename delimiters). Include directives are matched to +filenames in the SemanticDB cache using the following criteria: + +@enumerate +@item +Whether the file is in the same directory as the current file +@item +Whether the file is in the same project, as defined by EDE +(@pxref{Top,,,ede,EDE manual}) or the @code{semanticdb-project-roots} +variable (@pxref{Semanticdb Roots}). +@item +Whether the file is in the @dfn{system include path} (@pxref{Include +paths}). +@end enumerate + +@menu +* Semanticdb Roots:: Specifying the root of different projects +* Include paths:: Add/Remove directories to include search paths +* Search Throttle:: Controlling how semanticdb searches occur +* Semanticdb search debugging commands:: +@end menu + +@node Semanticdb Roots +@subsubsection SemanticDB project roots + +Project roots are the ``top-level'' directories for a single code +project. With the exception of system directories, SemanticDB +searches are usually limited to the current single code project. +Therefore, it is helpful to specify the project root if you want +@semantic{} tag searches to work correctly. + +@anchor{semanticdb-project-roots} +@deffn Option semanticdb-project-roots +The value of this variable is a list of directories (strings) that are +project root. All subdirectories of a project root are considered +part of the same project. This variable can be overriden by project +management programs via @code{semanticdb-project-root-functions}. +@end deffn + +@anchor{semanticdb-project-root-functions} +@defvar semanticdb-project-root-functions +The value of this variable is a list of functions to determine a given +directory's project root. These functions are called, one at a time, +with one argument (the directory name), and must return either +@code{nil}, a string (the project root), or a list of strings +(multiple project roots, for complex systems). The first +non-@code{nil} return value, if any, is taken to be the project root, +overriding @code{semanticdb-project-roots}. +@end defvar + +If you use EDE for project management, it will set +@code{semanticdb-project-root-functions} automatically. +@xref{Top,,,ede,EDE manual}. + +@node Include paths +@subsubsection Include Paths + +System include paths are standard locations to find source code tags, +such as the @dfn{header files} in @file{/usr/include} and its +subdirectories on Unix-like operating systems. You can add and remove +system include paths using the following commands: + +@anchor{semantic-add-system-include} +@deffn Command semantic-add-system-include dir &optional mode +This command prompts for a directory, @var{dir}, and adds it as a +system include path for the current major mode. When called +non-interactively, the major mode can be specified with the @var{mode} +argument. +@end deffn + +@anchor{semantic-remove-system-include} +@deffn Command semantic-remove-system-include dir &optional mode +This command prompt for a directory, @var{dir}, and removes it from +the system include path for the current major mode (or @var{mode}). +@end deffn + +@anchor{semantic-customize-system-include-path} +@deffn Command semantic-customize-system-include-path &optional mode +Customize the system include path for the current major mode (or +@code{mode}). +@end deffn + +@anchor{semanticdb-implied-include-tags} +@defun semanticdb-implied-include-tags +Include tags implied for all files of a given mode. You can set this +variable with @code{defvar-mode-local} for a particular mode so that +any symbols that exist for all files for that mode are included. +@end defun + +@c @xref{Search Optimization}, for more information on include paths. + +@node Search Throttle +@subsubsection SemanticDB Search Throttle + +The SemanticDB search throttle is a variable that may be configured by +a language support author. If you need to customize this for +yourself, you may need to override the mode values in a mode support +hook. + +@defvar semanticdb-find-default-throttle +@anchor{semanticdb-find-default-throttle} +The default throttle for @code{semanticdb-find} routines. +The throttle controls how detailed the list of database +tables is for a symbol lookup. The value is a list with +the following keys: + +@table @code +@item file +The file the search is being performed from. This option is here for +completeness only, and is assumed to always be on. +@item local +Tables from the same local directory are included. This includes +files directly referenced by a file name which might be in a different +directory. +@item project +Tables from the same local project are included If @code{project} is +specified, then @code{local} is assumed. +@item unloaded +If a table is not in memory, load it. If it is not cached on disk +either, get the source, parse it, and create the table. +@item system +Tables from system databases. These are specifically tables +from system header files, or language equivalent. +@item recursive +For include based searches, includes tables referenced by included +files. +@item omniscience +Included system databases which are omniscience, or somehow know +everything. Omniscience databases are found in +@code{semanticdb-project-system-databases}. The Emacs Lisp system +@var{db} is an omniscience database. +@end table + +@end defvar + +To set the throttle, use a command like this: + +@example +(setq-mode-local c-mode + semanticdb-find-default-throttle + '(project unloaded system recursive)) +@end example + +The default value of the throttle is for maximum accuracy at the +expense of time taken to perform a particular look-up. The throttle +is tweaked by @code{semantic-idle-summary-mode} to remove 'unloaded, +thus removing poor speed at unexpected times. + +@node Semanticdb search debugging commands +@subsubsection Semanticdb search debugging commands + +You can use @kbd{M-x semanticdb-dump-all-table-summary RET} to see the +list of databases that will be searched from a given buffer. It +should include DBs for the directories you expect. You can follow up +with @kbd{M-x semanticdb-find-test-translate-path RET} to then make +sure specific tables from the path are discovered correctly. + +Alternately, you can get a list of include files @semantic{} +encountered, but could not find on disk using +@kbd{M-x semanticdb-find-adebug-lost-includes RET}. + +Once you have used the below functions to debug the problem, you may +need to reconfigure how @semantic{} finds include files. +See @ref{Semanticdb Search Configuration}. If the search config is +ok, you may need to configure the search throttle. See @ref{Search Throttle}. + +@deffn Command semanticdb-dump-all-table-summary +@anchor{semanticdb-dump-all-table-summary} +Dump a list of all databases in Emacs memory. +@end deffn + +@deffn Command semanticdb-find-test-translate-path &optional arg +@anchor{semanticdb-find-test-translate-path} +Call and output results of @dfn{semanticdb-find-translate-path} +With @var{arg} non-@code{nil}, specify a @var{brutish} translation. +@end deffn + +@deffn Command semanticdb-find-adebug-lost-includes +@anchor{semanticdb-find-adebug-lost-includes} +Translate the current path, then display the lost includes. +Examines the variable @code{semanticdb-find-lost-includes}. +@end deffn + +Lastly, you can test an explicit search term using this command: + +@deffn Command semantic-adebug-searchdb regex +@anchor{semantic-adebug-searchdb} +Search the semanticdb for @var{regex} for the current buffer. +Display the results as a debug list. +@end deffn + +@node Changing Backends +@subsection 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. + +The default is to save databases in flat files. Alternatively, you +could write a new database backend that stores tags into a database, +or other storage system. + +@defvar semanticdb-new-database-class +@anchor{semanticdb-new-database-class} +The default type of database created for new files. +This can be changed on a per file basis, so that some directories +are saved using one mechanism, and some directories via a different +mechanism. +@end defvar + +@node Script Generated Cache Files +@subsection Script Generated Cache Files + +You can create new semantic databases with the @file{semanticdb.sh} +script file. Give this script the directory you want parsed, and it +will create a cache file for you. + +@example +$ semanticdb.sh *.el +@end example + +To use these generated tables, you would likely need to restart Emacs. + +@node Create System Databases +@subsection Create System Databases + +If your supported language stores the system libraries in readily +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. + +@deffn Command semanticdb-create-ebrowse-database dir +@anchor{semanticdb-create-ebrowse-database} +Create an @var{ebrowse} database for directory @var{dir}. +The database file is stored in ~/.semanticdb, or whichever directory +is specified by @code{semanticdb-default-system-save-directory}. +@end deffn + + +@node Idle Scheduler +@section Idle Scheduler +@cindex Idle Scheduler + +The Idle Scheduler in @semantic{} 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, scheduled idle processes that use the +semantic tag tables are run. + +@deffn Command global-semantic-idle-scheduler-mode &optional arg +@anchor{global-semantic-idle-scheduler-mode} +Toggle global use of option @dfn{semantic-idle-scheduler-mode}. +The idle scheduler with automatically reparse buffers in idle time, +and then schedule other jobs setup with @dfn{semantic-idle-scheduler-add}. +If @var{ARG} is positive, enable, if it is negative, disable. +If @var{ARG} is @code{nil}, then toggle. +@obsolete{global-semantic-auto-parse-mode,global-semantic-idle-scheduler-mode} +@end deffn + +@obsolete{semantic-auto-parse-mode, semantic-idle-scheduler-mode} + +@deffn Option semantic-idle-scheduler-idle-time +@anchor{semantic-idle-scheduler-idle-time} +Time in seconds of idle before scheduling events. +This time should be short enough to ensure that idle-scheduler will be +run as soon as Emacs is idle. +@end deffn + +@deffn Option semantic-idle-scheduler-mode-hook +@anchor{semantic-idle-scheduler-mode-hook} +Hook run at the end of function @dfn{semantic-idle-scheduler-mode}. +@end deffn + +@deffn Option semantic-idle-scheduler-verbose-flag +@anchor{semantic-idle-scheduler-verbose-flag} +Non-@code{nil} means that the idle scheduler should provide debug messages. +Use this setting to debug idle activities. +@end deffn + +You can add new functionality to the idle scheduler by reading the +Application Developers Guide +@inforef{Idle Scheduling, , semantic-appdev.info}. + +@menu +* Reparsing Options:: Reparsing the current buffer in idle time +* Idle Working Options:: Options for extra work done at idle time +* Debugging Idle Time Issues:: How to produce good bug reports. +* Idle Summary Mode:: Display prototype of symbol under cursor +* Idle Completions Mode:: Smart completion pop-up help. +@end menu + +@node Reparsing Options +@subsection 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. + +@deffn Option semantic-idle-scheduler-max-buffer-size +@anchor{semantic-idle-scheduler-max-buffer-size} +Maximum size in bytes of buffers automatically reparsed. +If this value is less than or equal to @var{0}, buffers are automatically +reparsed regardless of their size. +@end deffn + +@deffn Option semantic-idle-scheduler-no-working-message +@anchor{semantic-idle-scheduler-no-working-message} +If non-@code{nil}, disable display of working messages during parse. +@end deffn + +@deffn Option semantic-idle-scheduler-working-in-modeline-flag +@anchor{semantic-idle-scheduler-working-in-modeline-flag} +Non-@code{nil} means show working messages in the mode line. +Typically, parsing will show messages in the minibuffer. +This will move the parse message into the modeline. +@end deffn + +@defvar semantic-before-idle-scheduler-reparse-hooks +@anchor{semantic-before-idle-scheduler-reparse-hooks} +Hooks run before option @code{semantic-idle-scheduler} begins parsing. +If any hook throws an error, this variable is reset to nil. +This hook is not protected from lexical errors. +@end defvar + +@defvar semantic-after-idle-scheduler-reparse-hooks +@anchor{semantic-after-idle-scheduler-reparse-hooks} +Hooks run after option @code{semantic-idle-scheduler} has parsed. +If any hook throws an error, this variable is reset to nil. +This hook is not protected from lexical errors. +@end defvar + +@node Idle Working Options +@subsection Idle Working Options + +Similiar to the reparsing that occurs at short intervals in idle +time, there is extra work that can be controlled to occur in idle time +also. + +Idle work occurs after a longer delay, and can be very time +consuming. The work done includes: + +@table @asis +@item Create Include Path Caches +Create the optimized search caches needed for symbol lookup. +@item Create Type Cache +Create the datatype caches needed for intellisense features. +@item Save Databases +All file-based @semantic{} databases are saved to disk. +@item Parse neighboring files +All files in the same directory as the current buffer are +speculatively parsed. +@end table + +These features can be controlled with the following variables: + +@deffn Option semantic-idle-scheduler-work-idle-time +@anchor{semantic-idle-scheduler-work-idle-time} +Time in seconds of idle before scheduling big work. +This time should be long enough that once any big work is started, it is +unlikely the user would be ready to type again right away. +@end deffn + +@deffn Option semantic-idle-work-parse-neighboring-files-flag +@anchor{semantic-idle-work-parse-neighboring-files-flag} +Non-@code{nil} means to parse files in the same dir as the current buffer. +Disable to prevent lots of excessive parsing in idle time. +@end deffn + +@node Debugging Idle Time Issues +@subsection Debugging Idle Time Issues + +If you see errors produced in idle time, it could be an indication of a +more serious issue elsewhere. It is not enough to enable +@code{debug-on-error}, as the idle timer tries to keep errors under +wraps. + +Instead, there are two commands you can use whenever you see an idle +error. + +@deffn Command semantic-debug-idle-function +@anchor{semantic-debug-idle-function} +Run the Semantic idle function with debugging turned on. +@end deffn + +@deffn Command semantic-debug-idle-work-function +@anchor{semantic-debug-idle-work-function} +Run the Semantic idle work function with debugging turned on. +@end deffn + +Once you identify the general location of the idle error, you can send +the stack trace to the mailing list, or perhaps find a more focused +way to reproduce the issue. + +@node Idle Summary Mode +@subsection Idle Summary Mode + +Similar to the Emacs Lisp facility eldoc, +@code{semantic-idle-summary-mode} will display the prototype, or other +helpful doc about the symbol currently under point. + + +@deffn semantic-idle-summary-mode &optional arg +@anchor{semantic-idle-summary-mode} +Display a tag summary of the lexical token under the cursor. +This means for getting the current tag to display information can +be overriden with @code{idle-summary-current-symbol-info}. +This is a minor mode which performs actions during idle time. +With prefix argument ARG, turn on if positive, otherwise off. The +minor mode can be turned on only if semantic feature is available and +the current buffer was set up for parsing. Return non-nil if the +minor mode is enabled +@end deffn + +@obsolete{semantic-summary-mode, semantic-idle-summary-mode} + +@deffn Option semantic-idle-summary-function +@anchor{semantic-idle-summary-function} +Function to use when displaying tag information during idle time. +Some useful functions are found in @code{semantic-format-tag-functions}. +@end deffn + +@defvar semantic-idle-summary-out-of-context-faces +@anchor{semantic-idle-summary-out-of-context-faces} +List of font-lock faces that indicate a useless summary context. +Those are generally faces used to highlight comments or strings. + +It might be useful to override this variable to add comment faces +specific to a major mode. For example, in jde mode: + +@example +(defvar-mode-local jde-mode semantic-idle-summary-out-of-context-faces + (append (default-value 'semantic-idle-summary-out-of-context-faces) + '(jde-java-font-lock-doc-tag-face + jde-java-font-lock-link-face + jde-java-font-lock-bold-face + jde-java-font-lock-underline-face + jde-java-font-lock-pre-face + jde-java-font-lock-code-face))) +@end example + +@end defvar + +@node Idle Completions Mode +@subsection Idle Completions Mode + +The definition of smart completion is described in the Analyzer +section @ref{Analyzer}. + +The Idle Completions mode will calculate the list of possible +completions in idle time, and display them in a popup list, or other +inline completion mechanism. + +@deffn semantic-idle-completions-mode &optional arg +@anchor{semantic-idle-completions-mode} +Display a tooltip with a list of possible completions near the cursor. +There is no convenience for performing a completion replacement. For +that you should bind @code{semantic-ia-complete-symbol}. +This is a minor mode which performs actions during idle time. +With prefix argument ARG, turn on if positive, otherwise off. The +minor mode can be turned on only if semantic feature is available and +the current buffer was set up for parsing. Return non-nil if the +minor mode is enabled +@end deffn + +This mode operates by using the command +@code{semantic-complete-inline-analyzer}. + +Idle completion uses the completion function +@code{semantic-complete-analyze-inline-idle}. Changing the behavior of +the idle completion popups should be done through those utilities. + +@deffn Command semantic-complete-analyze-inline-idle +@anchor{semantic-complete-analyze-inline-idle} +Perform prompt completion to do in buffer completion. +@dfn{semantic-analyze-possible-completions} is used to determine the +possible values. +The function returns immediately, leaving the buffer in a mode that +will perform the completion. +Configure @code{semantic-complete-inline-analyzer-idle-displayor-class} +to change how completion options are displayed. +@end deffn + +@deffn Option semantic-complete-inline-analyzer-idle-displayor-class +@anchor{semantic-complete-inline-analyzer-idle-displayor-class} +Class for displayor to use with inline completion at idle time. + +Customize this variable to get a list of options, such as popup +tooltips, ghosting text, or traditional completion tools. +@end deffn diff -r 2f9ecf376c7a -r 014672c3a25f doc/misc/semantic.texi --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/misc/semantic.texi Mon Nov 16 22:25:49 2009 +0000 @@ -0,0 +1,638 @@ +\input texinfo +@setfilename ../../info/semantic +@set TITLE Semantic Manual +@set AUTHOR Eric M. Ludlam and David Ponce +@settitle @value{TITLE} + +@c ************************************************************************* +@c @ Header +@c ************************************************************************* + +@c Merge all indexes into a single index for now. +@c We can always separate them later into two or more as needed. +@syncodeindex vr cp +@syncodeindex fn cp +@syncodeindex ky cp +@syncodeindex pg cp +@syncodeindex tp cp + +@c @footnotestyle separate +@c @paragraphindent 2 +@c @@smallbook +@c %**end of header + +@copying +This manual documents the Semantic library and utilities. + +Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2007, +2009 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. A copy of the license +is included in the section entitled ``GNU Free Documentation License.'' + +(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and +modify this GNU manual. Buying copies from the FSF supports it in +developing GNU and promoting software freedom.'' +@end quotation +@end copying + +@ifinfo +@format +START-INFO-DIR-ENTRY +* Semantic: (semantic). Source code parser library and utilities. +END-INFO-DIR-ENTRY +@end format +@end ifinfo + +@titlepage +@center @titlefont{Semantic} +@sp 4 +@center by @value{AUTHOR} +@end titlepage +@page + +@macro semantic{} +@i{Semantic} +@end macro + +@macro keyword{kw} +@anchor{\kw\} +@b{\kw\} +@end macro + +@macro obsolete{old,new} +@sp 1 +@strong{Compatibility}: +@code{\new\} introduced in @semantic{} version 2.0 supercedes +@code{\old\} which is now obsolete. +@end macro + +@c ************************************************************************* +@c @ Document +@c ************************************************************************* +@contents + +@node top +@top @value{TITLE} + +@semantic{} is a suite of Emacs libraries and utilities for parsing +source code. At its core is a lexical analyzer and two parser +generators (@code{bovinator} and @code{wisent}) written in Emacs Lisp. +@semantic{} provides a variety of tools for making use of the parser +output, including user commands for code navigation and completion, as +well as enhancements for imenu, speedbar, whichfunc, eldoc, +hippie-expand, and several other parts of Emacs. + +To send bug reports, or participate in discussions about semantic, +use the mailing list cedet-semantic@@sourceforge.net via the URL: +@url{http://lists.sourceforge.net/lists/listinfo/cedet-semantic} + +@ifnottex +@insertcopying +@end ifnottex + +@menu +* Introduction:: +* Using Semantic:: +* Semantic Internals:: +* Glossary:: +* GNU Free Documentation License:: +* Index:: +@end menu + +@node Introduction +@chapter Introduction + +This chapter gives an overview of @semantic{} and its goals. + +Ordinarily, Emacs uses regular expressions (and syntax tables) to +analyze source code for purposes such as syntax highlighting. This +approach, though simple and efficient, has its limitations: roughly +speaking, it only ``guesses'' the meaning of each piece of source code +in the context of the programming language, instead of rigorously +``understanding'' it. + +@semantic{} provides a new infrastructure to analyze source code using +@dfn{parsers} instead of regular expressions. It contains two +built-in parser generators (an @acronym{LL} generator named +@code{Bovine} and an @acronym{LALR} generator named @code{Wisent}, +both written in Emacs Lisp), and parsers for several common +programming languages. It can also make use of @dfn{external +parsers}---programs such as GNU Global and GNU IDUtils. + +@semantic{} provides a uniform, language-independent @acronym{API} for +accessing the parser output. This output can be used by other Emacs +Lisp programs to implement ``syntax-aware'' behavior. @semantic{} +itself includes several such utilities, including user-level Emacs +commands for navigating, searching, and completing source code. + +The following diagram illustrates the structure of the @semantic{} +package: + +@table @strong +@item Please Note: +The words in all-capital are those that @semantic{} itself provides. +Others are current or future languages or applications that are not +distributed along with @semantic{}. +@end table + +@example + Applications + and + Utilities + ------- + / \ + +---------------+ +--------+ +--------+ + C --->| C PARSER |--->| | | | + +---------------+ | | | | + +---------------+ | COMMON | | COMMON |<--- SPEEDBAR + Java --->| JAVA PARSER |--->| PARSE | | | + +---------------+ | TREE | | PARSE |<--- SEMANTICDB + +---------------+ | FORMAT | | API |<--- ecb + Scheme --->| SCHEME PARSER |--->| | | | + +---------------+ | | | | + +---------------+ | | | | + Texinfo --->| TEXI. PARSER |--->| | | | + +---------------+ | | | | + + ... ... ... ... + + +---------------+ | | | |<--- app. 1 + Lang. A --->| A Parser |--->| | | | + +---------------+ | | | |<--- app. 2 + +---------------+ | | | | + Lang. B --->| B Parser |--->| | | |<--- app. 3 + +---------------+ | | | | + + ... ... ... ... ... + + +---------------+ | | | | + Lang. Y --->| Y Parser |--->| | | |<--- app. ? + +---------------+ | | | | + +---------------+ | | | |<--- app. ? + Lang. Z --->| Z Parser |--->| | | | + +---------------+ +--------+ +--------+ +@end example + +@menu +* Semantic Components:: +@end menu + +@node Semantic Components +@section Semantic Components + +In this section, we provide a more detailed description of the major +components of @semantic{}, and how they interact with one another. + +The first step in parsing a source code file is to break it up into +its fundamental components. This step is called lexical analysis: + +@example + syntax table, keywords list, and options + | + | + v + input file ----> Lexer ----> token stream +@end example + +@noindent +The output of the lexical analyzer is a list of tokens that make up +the file. The next step is the actual parsing, shown below: + +@example + parser tables + | + v + token stream ---> Parser ----> parse tree +@end example + +@noindent +The end result, the parse tree, is @semantic{}'s internal +representation of the language grammar. @semantic{} provides an +@acronym{API} for Emacs Lisp programs to access the parse tree. + +Parsing large files can take several seconds or more. By default, +@semantic{} automatically caches parse trees by saving them in your +@file{.emacs.d} directory. When you revisit a previously-parsed file, +the parse tree is automatically reloaded from this cache, to save +time. @xref{SemanticDB}. + +@node Using Semantic +@chapter Using Semantic + +@include sem-user.texi + +@node Semantic Internals +@chapter Semantic Internals + +This chapter provides an overview of the internals of @semantic{}. +This information would not be needed by neither application developers +nor grammar developers. + +It would be useful mostly for the hackers who would like to learn +more about how @semantic{} works. + +@menu +* Parser code :: Code used for the parsers +* Tag handling :: Code used for manipulating tags +* Semanticdb internals :: Code used in the semantic database +* Analyzer :: Code used in the code analyzer +* Tools :: Code used in user tools. +* Tests :: Code used for testing. +@end menu + +@node Parser code +@section Parser code + +@semantic{} parsing code is spread across a range of files. + +@table @file +@item semantic.el +The core infrastructure sets up buffers for parsing, and has all the +core parsing routines. Most parsing routines are overloadable, so the +actual implementation may be somewhere else. + +@item semantic-edit.el +Incremental reparse based on user edits. + +@item semantic-grammar.el +@itemx semantic-grammar.wy +Parser for the different grammar languages, and a major mode for +editing grammars in Emacs. + +@item semantic-lex.el +Infrastructure for implementing lexical analyzers. Provides macros +for creating individual analyzers for specific features, and a way to +combine them together. + +@item semantic-lex-spp.el +Infrastructure for a lexical symbolic preprocessor. This was written +to implement the C preprocessor, but could be used for other lexical +preprocessors. + +@item bovine/bovine-grammar.el +@itemx bovine/bovine-grammar-macros.el +@itemx bovine/semantic-bovine.el +The ``bovine'' grammar. This is the first grammar mode written for +@semantic{} and is useful for simple creating simple parsers. + +@item wisent/wisent.el +@itemx wisent/bison-wisent.el +@itemx wisent/semantic-wisent.el +@itemx wisent/semantic-debug-grammar.el +A port of bison to Emacs. This infrastructure lets you create LALR +based parsers for @semantic{}. + +@item semantic-ast.el +Manage Abstract Syntax Trees for parsers. + +@item semantic-debug.el +Infrastructure for debugging grammars. + +@item semantic-util.el +Various utilities for manipulating tags, such as describing the tag +under point, adding labels, and the all important +@code{semantic-something-to-tag-table}. + +@end table + +@node Tag handling +@section Tag handling + +A tag represents an individual item found in a buffer, such as a +function or variable. Tag handling is handled in several source +files. + +@table @file +@item semantic-tag.el +Basic tag creation, queries, cloning, binding, and unbinding. + +@item semantic-tag-write.el +Write a tag or tag list to a stream. These routines are used by +@file{semanticdb-file.el} when saving a list of tags. + +@item semantic-tag-file.el +Files associated with tags. Goto-tag, file for include, and file for +a prototype. + +@item semantic-tag-ls.el +Language dependant features of a tag, such as parent calculation, slot +protection, and other states like abstract, virtual, static, and leaf. + +@item semantic-dep.el +Include file handling. Contains the include path concepts, and +routines for looking up file names in the include path. + +@item semantic-format.el +Convert a tag into a nicely formatted and colored string. Use +@code{semantic-test-all-format-tag-functions} to test different output +options. + +@item semantic-find.el +Find tags matching different conditions in a tag table. +These routines are used by @file{semanticdb-find.el} once the database +has been converted into a simpler tag table. + +@item semantic-sort.el +Sorting lists of tags in different ways. Includes sorting a plain +list of tags forward or backward. Includes binning tags based on +attributes (bucketize), and tag adoption for multiple references to +the same thing. + +@item semantic-doc.el +Capture documentation comments from near a tag. + +@end table + +@node Semanticdb internals +@section Semanticdb internals + +@acronym{Semanticdb} complexity is certainly an issue. It is a rather +hairy problem to try and solve. + +@table @file +@item semanticdb.el +Defines a @dfn{database} and a @dfn{table} base class. You can +instantiate these classes, and use them, but they are not persistent. + +This file also provides support for @code{semanticdb-minor-mode}, +which automatically associates files with tables in databases so that +tags are @emph{saved} while a buffer is not in memory. + +The database and tables both also provide applicate cache information, +and cache flushing system. The semanticdb search routines use caches +to save datastructures that are complex to calculate. + +Lastly, it provides the concept of @dfn{project root}. It is a system +by which a file can be associated with the root of a project, so if +you have a tree of directories and source files, it can find the root, +and allow a tag-search to span all available databases in that +directory hierarchy. + +@item semanticdb-file.el +Provides a subclass of the basic table so that it can be saved to +disk. Implements all the code needed to unbind/rebind tags to a +buffer and writing them to a file. + +@item semanticdb-el.el +Implements a special kind of @dfn{system} database that uses Emacs +internals to perform queries. + +@item semanticdb-ebrowse.el +Implements a system database that uses Ebrowse to parse files into a +table that can be queried for tag names. Successful tag hits during a +find causes @semantic{} to pick up and parse the reference files to +get the full details. + +@item semanticdb-find.el +Infrastructure for searching groups @semantic{} databases, and dealing +with the search results format. + +@item semanticdb-ref.el +Tracks crossreferences. Cross references are needed when buffer is +reparsed, and must alert other tables that any dependant caches may +need to be flushed. References are in the form of include files. + +@end table + +@node Analyzer +@section Analyzer + +The @semantic{} analyzer is a complex engine which has been broken +down across several modules. When the @semantic{} analyzer fails, +start with @code{semantic-analyze-debug-assist}, then dive into some +of these files. + +@table @file +@item semantic-analyze.el +The core analyzer for defining the @dfn{current context}. The +current context is an object that contains references to aspects of +the local context including the current prefix, and a tag list +defining what the prefix means. + +@item semantic-analyze-complete.el +Provides @code{semantic-analyze-possible-completions}. + +@item semantic-analyze-debug.el +The analyzer debugger. Useful when attempting to get everything +configured. + +@item semantic-analyze-fcn.el +Various support functions needed by the analyzer. + +@item semantic-ctxt.el +Local context parser. Contains overloadable functions used to move +around through different scopes, get local variables, and collect the +current prefix used when doing completion. + +@item semantic-scope.el +Calculate @dfn{scope} for a location in a buffer. The scope includes +local variables, and tag lists in scope for various reasons, such as +C++ using statements. + +@item semanticdb-typecache.el +The typecache is part of @code{semanticdb}, but is used primarilly by +the analyzer to look up datatypes and complex names. The typecache is +bound across source files and builds a master lookup table for data +type names. + +@item semantic-ia.el +Interactive Analyzer functions. Simple routines that do completion or +lookups based on the results from the Analyzer. These routines are +meant as examples for application writers, but are quite useful as +they are. + +@item semantic-ia-sb.el +Speedbar support for the analyzer, displaying context info, and +completion lists. + +@end table + +@node Tools +@section Tools + +These files contain various tools a user can use. + +@table @file +@item semantic-idle.el +Idle scheduler for @semantic{}. Manages reparsing buffers after +edits, and large work tasks in idle time. Includes modes for showing +summary help and pop-up completion. + +@item senator.el +The @semantic{} navigator. Provides many ways to move through a +buffer based on the active tag table. + +@item semantic-decorate.el +A minor mode for decorating tags based on details from the parser. +Includes overlines for functions, or coloring class fields based on +protection. + +@item semantic-decorate-include.el +A decoration mode for include files, which assists users in setting up +parsing for their includes. + +@item semantic-complete.el +Advanced completion prompts for reading tag names in the minibuffer, or +inline in a buffer. + +@item semantic-imenu.el +Imenu support for using @semantic{} tags in imenu. + +@item semantic-mru-bookmark.el +Automatic bookmarking based on tags. Jump to locations you've been +before based on tag name. + +@item semantic-sb.el +Support for @semantic{} tag usage in Speedbar. + +@item semantic-util-modes.el +A bunch of small minor-modes that exposes aspects of the semantic +parser state. Includes @code{semantic-stickyfunc-mode}. + +@item document.el +@itemx document-vars.el +Create an update comments for tags. + +@item semantic-adebug.el +Extensions of @file{data-debug.el} for @semantic{}. + +@item semantic-chart.el +Draw some charts from stats generated from parsing. + + +@item semantic-elp.el +Profiler for helping to optimize the @semantic{} analyzer. + + +@end table + +@node Tests +@section Tests + +@table @file + +@item semantic-utest.el +Basic testing of parsing and incremental parsing for most supported +languages. + +@item semantic-ia-utest.el +Test the semantic analyzer's ability to provide smart completions. + +@item semantic-utest-c.el +Tests for the C parser's lexical pre-processor. + +@item semantic-regtest.el +Regression tests from the older Semantic 1.x API. + +@end table + +@node Glossary +@appendix Glossary + +@table @keyword +@item BNF +In semantic 1.4, a BNF file represented ``Bovine Normal Form'', the +grammar file used for the 1.4 parser generator. This was a play on +Backus-Naur Form which proved too confusing. + +@item bovinate +A verb representing what happens when a bovine parser parses a file. + +@item bovine lambda +In a bovine, or LL parser, the bovine lambda is a function to execute +when a specific set of match rules has succeeded in matching text from +the buffer. + +@item bovine parser +A parser using the bovine parser generator. It is an LL parser +suitible for small simple languages. + +@item context + +@item LALR + +@item lexer +A program which converts text into a stream of tokens by analyzing +them lexically. Lexers will commonly create strings, symbols, +keywords and punctuation, and strip whitespaces and comments. + +@item LL + +@item nonterminal +A nonterminal symbol or simply a nonterminal stands for a class of +syntactically equivalent groupings. A nonterminal symbol name is used +in writing grammar rules. + +@item overloadable +Some functions are defined via @code{define-overload}. +These can be overloaded via .... + +@item parser +A program that converts @b{tokens} to @b{tags}. + +@item tag +A tag is a representation of some entity in a language file, such as a +function, variable, or include statement. In semantic, the word tag is +used the same way it is used for the etags or ctags tools. + +A tag is usually bound to a buffer region via overlay, or it just +specifies character locations in a file. + +@item token +A single atomic item returned from a lexer. It represents some set +of characters found in a buffer. + +@item token stream +The output of the lexer as well as the input to the parser. + +@item wisent parser +A parser using the wisent parser generator. It is a port of bison to +Emacs Lisp. It is an LALR parser suitable for complex languages. +@end table + + +@node GNU Free Documentation License +@appendix GNU Free Documentation License +@include doclicense.texi + +@node Index +@unnumbered Index +@printindex cp + +@iftex +@contents +@summarycontents +@end iftex + +@bye + +@c Following comments are for the benefit of ispell. + +@c LocalWords: alist API APIs arg argc args argv asis assoc autoload Wisent +@c LocalWords: backquote bnf bovinate bovinates LALR +@c LocalWords: bovinating bovination bovinator bucketize +@c LocalWords: cb cdr charquote checkcache cindex CLOS +@c LocalWords: concat concocting const constantness ctxt Decl defcustom +@c LocalWords: deffn deffnx defun defvar destructor's dfn diff dir +@c LocalWords: doc docstring EDE EIEIO elisp emacsman emph enum +@c LocalWords: eq Exp EXPANDFULL expresssion fn foo func funcall +@c LocalWords: ia ids iff ifinfo imenu imenus init int isearch itemx java kbd +@c LocalWords: keymap keywordtable lang languagemode lexer lexing Ludlam +@c LocalWords: menubar metaparent metaparents min minibuffer Misc mode's +@c LocalWords: multitable NAvigaTOR noindent nomedian nonterm noselect +@c LocalWords: nosnarf obarray OLE OO outputfile paren parsetable POINT's +@c LocalWords: popup positionalonly positiononly positionormarker pre +@c LocalWords: printf printindex Programmatically pt punctuations quotemode +@c LocalWords: ref regex regexp Regexps reparse resetfile samp sb +@c LocalWords: scopestart SEmantic semanticdb setfilename setq +@c LocalWords: settitle setupfunction sexp sp SPC speedbar speedbar's +@c LocalWords: streamorbuffer struct subalist submenu submenus +@c LocalWords: subsubsection sw sym texi texinfo titlefont titlepage +@c LocalWords: tok TOKEN's toplevel typemodifiers uml unset untar +@c LocalWords: uref usedb var vskip xref yak