Commit fd1cefda authored by Chong Yidong's avatar Chong Yidong
Browse files

* semantic.texi (Analyzer Internals): Rename from Analyzer.

* sem-user.texi (Semantic mode user commands): Fix key syntax.
Document semantic-complete-analyze-inline.
(Semanticdb search debugging commands): Minor clarification.
(Analyzer, Smart Completion, Smart Summary, Smart Jump)
(Analyzer Debug) New nodes, adapted from the upstream Semantic user
manual.
parent 26224faf
2009-11-28 Chong Yidong <cyd@stupidchicken.com>
* semantic.texi (Analyzer Internals): Rename from Analyzer.
* sem-user.texi (Semantic mode user commands): Fix key syntax.
Document semantic-complete-analyze-inline.
(Semanticdb search debugging commands): Minor clarification.
(Analyzer, Smart Completion, Smart Summary, Smart Jump)
(Analyzer Debug) New nodes, adapted from the upstream Semantic user
manual.
2009-11-28 Kevin Ryde <user42@zip.com.au>
* cl.texi (Porting Common Lisp): Update EIEIO dead ftp link to a
......
......@@ -28,6 +28,7 @@ File,,,emacs,Emacs manual}.
* Semantic mode:: Global minor mode for @semantic{}.
* SemanticDB:: Caching parsed buffers between sessions.
* Idle Scheduler:: Performing @semantic{} operations when idle.
* Analyzer:: Semantic tools for analyzing code.
@end menu
@node Semantic mode
......@@ -107,64 +108,70 @@ Others act on the @dfn{current tag}, meaning the tag at (or around)
point.
@table @kbd
@item \C-c , j
@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
@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
@item C-c , l
Display a list of the possible completions of the current tag
(@code{semantic-analyze-possible-completions}).
@item \C-c , g
@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
@item C-c , G
Display a list of tags that call the current tag
(@code{semantic-symref}).
@item \C-c , p
@item C-c , p
Move point to the previous tag (@code{senator-previous-tag}).
@item \C-c , n
@item C-c , n
Move point to the next tag (@code{senator-next-tag}).
@item \C-c , u
@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, @key{SPC}
Display a list of possible completions for the symbol at point
(@code{semantic-complete-analyze-inline}). This also activates a
special set of keybindings for choosing a completion: @key{RET}
accepts the current completion, @kbd{M-n} and @kbd{M-p} cycle through
possible completions, @key{TAB} completes as far as possible and then
cycles, and @kbd{C-g} or any other key aborts the completion.
@xref{Smart Completion}.
@item \C-c,\C-w
@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
@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
@item C-c , C-y
Yank a tag from the tag ring (@code{senator-yank-tag}).
@item \C-c,r
@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}
@item \C-c , @kbd{up}
Transpose the current tag with the previous one
(@code{senator-transpose-tags-up}).
@item ?\C-c ?, @kbd{down}
@item C-c , @kbd{down}
Transpose the current tag with the next one
(@code{senator-transpose-tags-down}).
@end table
......@@ -433,7 +440,6 @@ You can use @kbd{M-x semanticdb-dump-all-table-summary} to see the
list of databases that will be searched from a given buffer. You can
follow up with @kbd{M-x semanticdb-find-test-translate-path} 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}.
......@@ -443,10 +449,11 @@ semanticdb-find-adebug-lost-includes}.
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.
@deffn Command semanticdb-find-test-translate-path &optional arg
Call and output results of @dfn{semanticdb-find-translate-path}. In
the displayed buffer, you can type @key{SPC} to expand items. With
@var{arg} non-@code{nil}, specify a @var{brutish} translation.
@end deffn
@deffn Command semanticdb-find-adebug-lost-includes
......@@ -681,8 +688,8 @@ Semantic Idle Completions mode is a minor mode for performing
displayed inline, with keybindings that allow you to cycle through
different alternatives.
@c @xref{Analyzer}, for information about code
@c completion.
Semantic Idle Completions mode performs completion based on the
Semantic Analyzer (@pxref{Analyzer}).
@anchor{global-semantic-idle-completions-mode}
@anchor{semantic-idle-completions-mode}
......@@ -761,3 +768,337 @@ Display completions in a tooltip.
Display completions in a separate window.
@end table
@end deffn
@node Analyzer
@section Analyzer
@cindex Analyzer
The Semantic Analyzer is a library for performing context analysis on
source code. It provides user commands for displaying, completing,
and navigating through source code.
@menu
* Smart Completion:: Performing code completion.
* Smart Summary:: Displaying help on a symbol.
* Smart Jump:: Jumping to the definition of a tag.
* Analyzer Debug:: Debugging problems with the analyzer.
@end menu
@node Smart Completion
@subsection Smart Completion
The Semantic Analyzer can be used to perform code completion in a
manner that takes the local context into account.
In addition to the user commands documented in this section, the
completions performed by Semantic Idle Completions mode also uses the
Semantic Analyzer. @xref{Idle Completions Mode}.
@deffn Command semantic-analyze-possible-completions context
This is the most basic command for Semantic Analyzer-based completion.
Called interactively, it displays in another window a list of the
possible completions for the symbol at point.
When called from a Lisp program,
@code{semantic-analyze-possible-completions} does not display a
completions list. The argument @var{context} should be either a
buffer position, or a context object. The return value is a list of
@semantic{} tag objects that complete the symbol for @var{context},
based on the following criteria:
@itemize
@item Elements currently in scope.
@item Constants currently in scope.
@item Elements matching the context's @code{:prefix}.
@item Type of the completion matching the type of the context.
@end itemize
Most of the other commands documented in this section call
@code{semantic-analyze-possible-completions} internally.
@end deffn
@anchor{semantic-complete-analyze-inline}
@deffn Command semantic-complete-analyze-inline
This command is bound to @kbd{C-c , @key{SPC}} when Semantic mode is
enabled (@pxref{Semantic mode user commands}). It displays a list of
possible completions for the symbol at point, and activates a special
set of keybindings for choosing a completion.
You can type @key{RET} to accept the current completion, @kbd{M-n} and
@kbd{M-p} to cycle through the possible completions, @key{TAB} to
complete as far as possible and then cycle through completions, and
either @kbd{C-g} or any other key to abort the completion.
This command is similar to the completion performed by Semantic Idle
Completions mode. The main difference is that it is called
explicitly, whereas Semantic Idle Completions mode completes during
idle time (@pxref{Idle Completions Mode}).
@end deffn
@anchor{semantic-complete-inline-analyzer-displayor-class}
@deffn Option semantic-complete-inline-analyzer-idle-displayor-class
The value of this variable determines how
@code{semantic-complete-analyze-inline} shows its completions.
Possible values include:
@table @code
@item semantic-displayor-traditional
Display completions in a separate window. This is the default value.
@item semantic-displayor-ghost
Display completions ``inline'' with the buffer text, similar to the
default behavior of Semantic Idle Completions mode (@pxref{Idle
Completions Mode}).
@item semantic-displayor-tooltip
Display completions in a tooltip.
@end table
@end deffn
In addition to @code{semantic-complete-analyze-inline}, you can use
the simpler command @code{semantic-ia-complete-symbol point}. This
behaves like the usual @kbd{M-@key{TAB}} (@code{complete-symbol})
command (@pxref{Symbol Completion,,,emacs,Emacs manual}), except it
uses Semantic Analyzer.
@anchor{semantic-ia-complete-symbol}
@deffn Command semantic-ia-complete-symbol point
Complete the current symbol at @var{point}.
@end deffn
@node Smart Summary
@subsection Smart Summary
You can use the commands in this section to find information about the
code at point:
@anchor{semantic-ia-show-summary}
@deffn Command semantic-ia-show-summary pos
Display a summary for the symbol at @var{pos}. Called interactively,
@var{pos} defaults to point.
@end deffn
@anchor{semantic-ia-show-doc}
@deffn Command semantic-ia-show-doc pos
Display the code-level documentation for the symbol at @var{pos}.
Called interactively, @var{pos} defaults to point.
@end deffn
@anchor{semantic-ia-describe-class}
@deffn Command semantic-ia-describe-class typename
Prompt for the name of a data type, @var{typename}, and display its
components. For instance, if the type in question is a class, this
displays the methods and member variables.
@end deffn
You can also use Semantic Idle Summary mode to show information about
the current symbol in the echo area during idle time. @xref{Idle
Summary Mode}.
@node Smart Jump
@subsection Smart Jump
The Semantic Analyzer can be used to jump directly to the definition
for a code symbol. Because it is based on code analysis, its behavior
is often more accurate than than the @code{find-tag} command
(@pxref{Tags,,,emacs,Emacs manual}).
@anchor{semantic-ia-fast-jump}
@deffn Command semantic-ia-fast-jump pos
Jump to the definition for the symbol at @var{pos}. Called
interactively, @var{pos} defaults to point.
@end deffn
@anchor{semantic-ia-fast-mouse-jump}
@defun semantic-ia-fast-mouse-jump event
Jump to the definition for the symbol at the position of the mouse
event @var{event}. This command is meant to be bound to a mouse
command, like this:
@example
(global-set-key '[(S-mouse-1)] semantic-ia-fast-mouse-jump)
@end example
@end defun
You can also use @kbd{C-c , j} (@code{semantic-complete-jump-local})
and @kbd{C-c , J} (@code{semantic-complete-jump}) to navigate tags.
@xref{Semantic mode user commands}. Those commands do not make use of
the Semantic Analyzer.
@node Analyzer Debug
@subsection Debugging the Semantic Analyzer
In the event that the Semantic Analyzer does not analyze your code
properly, you can take steps to identify and solve the problem. This
section was written with C/C++ in mind, but should be relevant for any
typed language.
@subsubsection Step 1: Check the context
The first thing to do is check the current context. You can do this
with @kbd{M-x semantic-analyze-current-context}.
@deffn Command semantic-analyze-current-context pos
Analyze the context at @var{pos}. This function is used by most of
the other Semantic Analyzer commands to obtain the context of the code
at a given buffer position. The return value is an EIEIO object
describing the context at @var{pos} (@pxref{Top,,,eieio,EIEIO
manual}).
When called interactively, this displays a @samp{*Semantic Context
Analysis*} buffer in a separate window. This buffer contains a
summary of the context at point.
@end deffn
The Prefix section of the @samp{*Semantic Context Analysis*} buffer
lists the tags based on the text at point. If it shows only a simple
string, the Semantic was unable to identify what the data type was.
The first item in the list of the prefix is the first lookup failure
in the chain, and that is the item to focus debugging effort on. For
example:
@example
Context Type: #<semantic-analyze-context context>
Bounds: (182 . 185)
Prefix: Foo* bar
int bbb (const char* y)
Prefix Types: class Foo @{@}
--------
-> Local Vars: int argc
char** argv
@end example
In this example you can see that the prefix has two fully found tags.
In the following example, the symbol ``bbb'' is incomplete, and could
not be found:
@example
Context Type: #<semantic-analyze-context context>
Bounds: (182 . 184)
Prefix: Foo* bar
"bb"
Prefix Classes: 'function
'variable
Prefix Types: class Foo @{@}
--------
-> Local Vars: int argc
char** argv
@end example
@subsubsection Step 2 : Check your include path
Once you know what symbol can't be found, the next thing to check is
your include path. Is the header or include file that has the
definitions you need actually in the list of headers @semantic{} is
searching through? To get a basic list, you can use @kbd{M-x
semanticdb-find-test-translate-path}. @xref{Semanticdb search
debugging commands}.
For C++, check to make sure that your project level include files are
in quotes, and not angle brackets. Items in angle brackets are system
includes.
If items should be loaded but aren't, you may need to update the
search throttle. @xref{Search Throttle}. If you see some tables that
have 0 tags in them, then you you may have an incorrectly set
throttle. For example,
@example
*#<semanticdb-table main.cpp (4 tags DIRTY)>
*#<semanticdb-table foo.hh (0 tags DIRTY)>
@end example
Here, @semantic{} found @file{foo.hh}, but there are 0 tags. This may
be because the throttle was set to not read in and parse files that
Emacs has not yet loaded in. To fix this case, visit the file, and
let @semantic{} parse and save the tags table.
@subsubsection Step 3: Check the local scope
If your data type is somehow abbreviated based on scope, such as from
a @code{using} statement, you should make sure that the symbol you
want is in the local scope. Examine the scope with @kbd{M-x
semantic-calculate-scope}. The scope structure is displayed in ADEBUG
mode, so use @kbd{SPC} to expand different elements and looking for
your symbol.
If your symbol should be in the scope, but you cannot find it, then
you may have found a language support bug in the local-variable
parser, or using statement parser.
Calling @kbd{M-x bovinte} should force a reset on the scope in case
there is merely some bad state.
@example
] Name: Cache
] Class: #'semantic-scope-cache
] :table #<semanticdb-table testsubclass.cpp (13 tags DIRTY)>
] tag createMoose : class moose
] scopetypes 'nil
] parents #<TAG LIST: 1 entries>
] scope #<TAG LIST: 22 entries>
] fullscope #<TAG LIST: 23 entries>
] localvar #<TAG LIST: 6 entries>
@end example
In the above sample output, the @code{tag} slot specifies where within
you source this scope is relevant. @code{Parents} should contain any
in scope parents, such as the class a method belongs to.
@code{Localvar} should contain your local variables. @code{Scope}
should contain datatypes in scope due to a @code{using} statement or
the like.
@subsubsection Step 4: Check the typecache
For complex typed languages like C++, @semantic{} creates a typecache,
or an optimized search table with all the various data types in it.
Elements in the typecache do not obey local scope. It only contains
fully qualified names. You can examine the typecache with
@kbd{M-x semanticdb-typecache-dump}.
If your data types are not in the typecache, there may be some parsing
error or other bug. Calling @kbd{M-x bovinte} should force a reset on
the typecache in case there is merely some bad state.
@example
]#<semanticdb-typecache /home/zappo/cedet/semantic/tests/testsubclass.cpp>
] Name: /home/zappo/cedet/semantic/tests/testsubclass.cpp
] Class: #'semanticdb-typecache
] filestream 'nil
] includestream #<TAG LIST: 84 entries>
] stream 'nil
] dependants 'nil
@end example
In the above example, the output of @kbd{M-x semanticdb-typecache-dump}
was expanded one level. The @code{filestream} slot should contain
datatypes in the current file. The @code{includestream} should
contain all the datatypes in all included header files.
The @code{dependants} slot will specify other files that depend on
this one.
@section Step 5: Check the parser
Go to the location where your unfound tag should be. You can call
@kbd{M-x bovinate}, and see a dump of the raw tag structure. To see a
navigable tree, use @kbd{M-x semantic-adebug-bovinate} instead. You
can then look to make sure your tag has been properly parsed.
If it has not, then you may have found a parser bug. To get a feel
how @semantic{} treats your file, type @kbd{M-x
global-semantic-show-unmatched-syntax-mode}. This causes any syntax
it cannot parse to be underlined in red.
If your type is not parsable, it could be for a couple of reasons:
@enumerate
@item
If there is a MACRO keyword used in the definition of the type, you
may need to update the @code{semantic-lex-c-preprocessor-symbol-map}
to account for it.
@item
Or perhaps the parser needs to be fixed.
@end enumerate
......@@ -240,8 +240,8 @@ 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
* Semanticdb Internals :: Code used in the semantic database
* Analyzer Internals :: Code used in the code analyzer
* Tools :: Code used in user tools
* Tests :: Code used for testing
@end menu
......@@ -349,8 +349,8 @@ Capture documentation comments from near a tag.
@end table
@node Semanticdb internals
@section Semanticdb internals
@node Semanticdb Internals
@section Semanticdb Internals
@acronym{Semanticdb} complexity is certainly an issue. It is a rather
hairy problem to try and solve.
......@@ -400,8 +400,8 @@ need to be flushed. References are in the form of include files.
@end table
@node Analyzer
@section Analyzer
@node Analyzer Internals
@section Analyzer Internals
The @semantic{} analyzer is a complex engine which has been broken
down across several modules. When the @semantic{} analyzer fails,
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment