1 \input texinfo @c -*-texinfo-*-
3 @setfilename semantic-appdev.info
4 @set TITLE Semantic Application Development Manual
5 @set AUTHOR Eric M. Ludlam, David Ponce, and Richard Y. Kim
6 @settitle @value{TITLE}
8 @c *************************************************************************
10 @c *************************************************************************
12 @c Merge all indexes into a single index for now.
13 @c We can always separate them later into two or more as needed.
20 @c @footnotestyle separate
26 This manual documents Application Development with Semantic.
28 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2007 Eric M. Ludlam
29 Copyright @copyright{} 2001, 2002, 2003, 2004 David Ponce
30 Copyright @copyright{} 2002, 2003 Richard Y. Kim
33 Permission is granted to copy, distribute and/or modify this document
34 under the terms of the GNU Free Documentation License, Version 1.1 or
35 any later version published by the Free Software Foundation; with the
36 Invariant Sections being list their titles, with the Front-Cover Texts
37 being list, and with the Back-Cover Texts being list. A copy of the
38 license is included in the section entitled ``GNU Free Documentation
46 * Semantic Application Writer's guide: (semantic-appdev).
54 @c @setchapternewpage odd
55 @c @setchapternewpage off
58 This file documents Application Development with Semantic.
59 @emph{Infrastructure for parser based text analysis in Emacs}
61 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004 @value{AUTHOR}
67 @author by @value{AUTHOR}
68 @vskip 0pt plus 1 fill
69 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004 @value{AUTHOR}
71 @vskip 0pt plus 1 fill
77 @include semanticheader.texi
80 @c *************************************************************************
82 @c *************************************************************************
88 A @semantic{} application takes the semantic tags generated
89 by semantic parsers then provides useful services to the user.
90 For a list of such applications,
91 @inforef{the Semantic User's Guide, , semantic-user}.
93 An application developer needs to know
95 @item when to invoke the parser to generate or regenerate the tag lists.
96 @item how to access the tag lists.
97 @item how to access information about each tag.
100 This chapter describes @semantic{} fuctions and concepts an application
101 developer needs to know to perform all of the tasks just listed.
105 * Searching Tag Tables:: Searching tag tables.
106 * Tags at Point:: Finding tags at point.
107 * Tag Decoration:: Decorating tags
108 * Tag Sorting:: Reorganizing streams.
109 * Tag Completion:: Completing read functions.
110 * Override Methods:: Language dependent functions covering
111 conversion to text strings, language dependent
112 queries and local context information
113 * Parser Features:: Application available parser features.
114 * Semantic Database:: Persistant storage of tags.
115 * Idle Scheduling:: Scheduling jobs in idle time.
116 * Example Programs:: Simple programming examples.
117 * Current Context:: Local context analysis.
118 * App Debugger:: Application Debugger
119 * GNU Free Documentation License::
124 @chapter Semantic Tags
128 @node Searching Tag Tables
129 @chapter Searching Tag Tables
131 These functions take some key, and returns information found in a tag
132 table. Some will return one tag (the first matching item found.)
133 Others will return a list of all items matching a given criterion.
134 Most of these functions work regardless of a buffer being in memory or
137 Any specialty search routine that claims to use a function that is an
138 overload method will need to execute in a buffer of the same mode as
139 the tags being searched.
142 * Breadth Search:: Searching only one level of tags.
143 * Deep Search:: Deep searches into types or argument lists.
144 * Specialty Search:: Specialty Searches.
145 * Custom Search:: Write custom search routines.
149 @section Breadth Search
151 Searching the breadth of a list of tags means that only one level of
152 the tags will be searched. If one of the tags is a datatype with
153 additional members, those members are not searched.
155 @defun semantic-find-first-tag-by-name name &optional table
156 @anchor{semantic-find-first-tag-by-name}
157 Find the first tag with @var{NAME} in @var{TABLE}.
158 @var{NAME} is a string.
159 @var{TABLE} is a semantic tags table. See @dfn{semantic-something-to-tag-table}.
160 This routine uses @dfn{assoc} to quickly find the first matching entry.
163 @defun semantic-find-tags-by-name name &optional table
164 @anchor{semantic-find-tags-by-name}
165 Find all tags with @var{NAME} in @var{TABLE}.
166 @var{NAME} is a string.
167 @var{TABLE} is a tag table. See @dfn{semantic-something-to-tag-table}.
170 @defun semantic-find-tags-for-completion prefix &optional table
171 @anchor{semantic-find-tags-for-completion}
172 Find all tags whos name begins with @var{PREFIX} in @var{TABLE}.
173 @var{PREFIX} is a string.
174 @var{TABLE} is a tag table. See @dfn{semantic-something-to-tag-table}.
175 While it would be nice to use @dfn{try-completion} or @dfn{all-completions},
176 those functions do not return the tags, only a string.
177 Uses @dfn{compare-strings} for fast comparison.
180 @defun semantic-find-tags-by-name-regexp regexp &optional table
181 @anchor{semantic-find-tags-by-name-regexp}
182 Find all tags with name matching @var{REGEXP} in @var{TABLE}.
183 @var{REGEXP} is a string containing a regular expression,
184 @var{TABLE} is a tag table. See @dfn{semantic-something-to-tag-table}.
185 Consider using @dfn{semantic-find-tags-for-completion} if you are
186 attempting to do completions.
189 @defun semantic-find-tags-by-class class &optional table
190 @anchor{semantic-find-tags-by-class}
191 Find all tags of class @var{CLASS} in @var{TABLE}.
192 @var{CLASS} is a symbol representing the class of the token, such as
193 @code{'variable}, of 'function..
194 @var{TABLE} is a tag table. See @dfn{semantic-something-to-tag-table}.
197 @defun semantic-find-tags-by-type type &optional table
198 @anchor{semantic-find-tags-by-type}
199 Find all tags of with a type @var{TYPE} in @var{TABLE}.
200 @var{TYPE} is a string or tag representing a data type as defined in the
201 language the tags were parsed from, such as ``int'', or perhaps
202 a tag whose name is that of a struct or class.
203 @var{TABLE} is a tag table. See @dfn{semantic-something-to-tag-table}.
206 @defun semantic-find-tags-included &optional table
207 @anchor{semantic-find-tags-included}
208 Find all tags in @var{TABLE} that are of the @code{'include} class.
209 @var{TABLE} is a tag table. See @dfn{semantic-something-to-tag-table}.
215 @defun semantic-brute-find-first-tag-by-name name streamorbuffer &optional search-parts search-include
216 Find a tag @var{NAME} within @var{STREAMORBUFFER}. @var{NAME} is a string.
217 If @var{SEARCH-PARTS} is non-@code{nil}, search children of tags.
218 If @var{SEARCH-INCLUDE} is non-@code{nil}, search include files.
220 Use @dfn{semantic-find-first-tag-by-name} instead.
222 @obsolete{semantic-find-nonterminal-by-name,semantic-brute-find-first-tag-by-name}
225 @defun semantic-brute-find-tag-by-property property value streamorbuffer &optional search-parts search-includes
226 Find all tags with @var{PROPERTY} equal to @var{VALUE} in @var{STREAMORBUFFER}.
227 Optional argument @var{SEARCH-PARTS} and @var{SEARCH-INCLUDES} are passed to
228 @dfn{semantic-brute-find-tag-by-function}.
230 @obsolete{semantic-find-nonterminal-by-property,semantic-brute-find-tag-by-property}
233 @defun semantic-brute-find-tag-by-attribute attr streamorbuffer &optional search-parts search-includes
234 Find all tags with a given @var{ATTR} in @var{STREAMORBUFFER}.
235 @var{ATTR} is a symbol key into the attributes list.
236 Optional argument @var{SEARCH-PARTS} and @var{SEARCH-INCLUDES} are passed to
237 @dfn{semantic-brute-find-tag-by-function}.
239 @obsolete{semantic-find-nonterminal-by-extra-spec,semantic-brute-find-tag-by-attribute}
242 @defun semantic-brute-find-tag-by-attribute-value attr value streamorbuffer &optional search-parts search-includes
243 Find all tags with a given @var{ATTR} equal to @var{VALUE} in @var{STREAMORBUFFER}.
244 @var{ATTR} is a symbol key into the attributes list.
245 @var{VALUE} is the value that @var{ATTR} should match.
246 Optional argument @var{SEARCH-PARTS} and @var{SEARCH-INCLUDES} are passed to
247 @dfn{semantic-brute-find-tag-by-function}.
249 @obsolete{semantic-find-nonterminal-by-extra-spec-value,semantic-brute-find-tag-by-attribute-value}
252 @defun semantic-brute-find-tag-by-position position streamorbuffer &optional nomedian
253 Find a nonterminal covering @var{POSITION} within @var{STREAMORBUFFER}.
254 @var{POSITION} is a number, or marker. If @var{NOMEDIAN} is non-@code{nil}, don't do
255 the median calculation, and return nil.
257 @obsolete{semantic-find-nonterminal-by-position,semantic-brute-find-tag-by-position}
260 @defun semantic-brute-find-innermost-tag-by-position position streamorbuffer &optional nomedian
261 Find a list of tags covering @var{POSITION} within @var{STREAMORBUFFER}.
262 @var{POSITION} is a number, or marker. If @var{NOMEDIAN} is non-@code{nil}, don't do
263 the median calculation, and return nil.
264 This function will find the topmost item, and recurse until no more
265 details are available of findable.
267 @obsolete{semantic-find-innermost-nonterminal-by-position,semantic-brute-find-innermost-tag-by-position}
270 @defun semantic-brute-find-tag-by-class class streamorbuffer &optional search-parts search-includes
271 Find all tags with a class @var{CLASS} within @var{STREAMORBUFFER}.
272 @var{CLASS} is a symbol representing the class of the tags to find.
273 See @dfn{semantic-tag-class}.
274 Optional argument @var{SEARCH-PARTS} and @var{SEARCH-INCLUDES} are passed to
275 @dfn{semantic-brute-find-tag-by-function}.
277 Use @code{semantic-find-tag-by-class} instead.
279 @obsolete{semantic-find-nonterminal-by-token,semantic-brute-find-tag-by-class}
282 @defun semantic-brute-find-tag-standard streamorbuffer &optional search-parts search-includes
283 Find all tags in @var{STREAMORBUFFER} which define simple class types.
284 See @dfn{semantic-tag-class}.
285 Optional argument @var{SEARCH-PARTS} and @var{SEARCH-INCLUDES} are passed to
286 @dfn{semantic-brute-find-tag-by-function}.
288 @obsolete{semantic-find-nonterminal-standard,semantic-brute-find-tag-standard}
291 @defun semantic-brute-find-tag-by-type type streamorbuffer &optional search-parts search-includes
292 Find all tags with type @var{TYPE} within @var{STREAMORBUFFER}.
293 @var{TYPE} is a string which is the name of the type of the tags returned.
294 See @dfn{semantic-tag-type}.
295 Optional argument @var{SEARCH-PARTS} and @var{SEARCH-INCLUDES} are passed to
296 @dfn{semantic-brute-find-tag-by-function}.
298 @obsolete{semantic-find-nonterminal-by-type,semantic-brute-find-tag-by-type}
301 @defun semantic-brute-find-tag-by-function function streamorbuffer &optional search-parts search-includes
302 Find all tags for which FUNCTION's value is non-@code{nil} within @var{STREAMORBUFFER}.
303 @var{FUNCTION} must return non-@code{nil} if an element of @var{STREAM} will be included
306 If optional argument @var{SEARCH-PARTS} is non-@code{nil}, all sub-parts of tags
307 are searched. The overloadable function @code{semantic-tag-componenets} is
308 used for the searching child lists. If @var{SEARCH-PARTS} is the symbol
309 @code{'positiononly}, then only children that have positional information are
312 If @var{SEARCH-INCLUDES} is non-@code{nil}, then all include files are also
313 searched for matches. This parameter hasn't be active for a while
316 @obsolete{semantic-find-nonterminal-by-function,semantic-brute-find-tag-by-function}
319 @defun semantic-brute-find-first-tag-by-function function streamorbuffer &optional search-parts search-includes
320 Find the first nonterminal which @var{FUNCTION} match within @var{STREAMORBUFFER}.
321 @var{FUNCTION} must return non-@code{nil} if an element of @var{STREAM} will be included
324 The following parameters were never implemented.
326 If optional argument @var{SEARCH-PARTS}, all sub-parts of tags are searched.
327 The overloadable function @dfn{semantic-tag-components} is used for
329 If @var{SEARCH-INCLUDES} is non-@code{nil}, then all include files are also
330 searched for matches.
332 @obsolete{semantic-find-nonterminal-by-function-first-match,semantic-brute-find-first-tag-by-function}
335 @node Specialty Search
336 @section Specialty Search
338 There are some specialty searches needed by some semantic tools that
339 could prove useful. These specialty searches often do not match
340 against some single attribute as most breadth searches do.
342 @defun semantic-find-tags-of-compound-type &optional table
343 @anchor{semantic-find-tags-of-compound-type}
344 Find all tags which are a compound type in @var{TABLE}.
345 Compound types are structures, or other data type which
346 is not of a primitive nature, such as int or double.
350 @defun semantic-find-tags-by-scope-protection scopeprotection parent &optional table
351 @anchor{semantic-find-tags-by-scope-protection}
352 Find all tags accessable by @var{SCOPEPROTECTION}.
353 @var{SCOPEPROTECTION} is a symbol which can be returned by the method
354 @dfn{semantic-tag-protection}. @var{A} hard-coded order is used to determine a match.
355 @var{PARENT} is a tag representing the @var{PARENT} slot needed for
356 @dfn{semantic-tag-protection}.
357 @var{TABLE} is a list of tags (a subset of @var{PARENT} members) to scan. If @var{TABLE} is @code{nil},
358 the type members of @var{PARENT} are used.
359 See @dfn{semantic-tag-protected-p} for details on which tags are returned.
362 @defun semantic-find-tags-external-children-of-type type &optional table
363 @anchor{semantic-find-tags-external-children-of-type}
364 Find all tags in whose parent is @var{TYPE} in @var{TABLE}.
365 These tags are defined outside the scope of the original @var{TYPE} declaration.
366 @var{TABLE} is a tag table. See @dfn{semantic-something-to-tag-table}.
370 @section Custom Search
372 The searching framework for semantic for tag tables has two basic
373 root methods. One is a function and the other is a macro. The
374 functional version is needed if some sort of macro conflict arrises.
375 The macro version is useful because it eliminates a level of function
378 @defun semantic--find-tags-by-function predicate &optional table
379 @anchor{semantic--find-tags-by-function}
380 Find tags for which @var{PREDICATE} is non-@code{nil} in @var{TABLE}.
381 @var{PREDICATE} is a lambda expression which accepts on @var{TAG}.
382 @var{TABLE} is a semantic tags table. See @dfn{semantic-something-to-tag-table}.
385 @defun semantic--find-tags-by-macro form &optional table
386 @anchor{semantic--find-tags-by-macro}
387 Find tags for which @var{FORM} is non-@code{nil} in @var{TABLE}.
388 @var{TABLE} is a semantic tags table. See @dfn{semantic-something-to-tag-table}.
391 @c @defun semantic-recursive-find-nonterminal-by-name name buffer
392 @c Recursivly find the first occurance of @var{NAME}.
393 @c Start search with @var{BUFFER}. Recurse through all dependencies till
394 @c found. The return item is of the form (@var{BUFFER} @var{TOKEN})
395 @c where @var{BUFFER} is the buffer in which @var{TOKEN} (the token found
396 @c to match @var{NAME}) was found.
398 @c @var{THIS} ISN'T @var{USED} @var{IN} @var{SEMANTIC}. @var{DELETE}
399 @c @var{ME} @var{SOON}.
403 @chapter Tags at Point
405 When you need to get the tag the cursor is on, there is a more
406 efficient mechanism than using
407 @code{semantic-brute-find-tag-by-position}. This mechanism directly
408 queries the overlays the parsing step leaves in the buffer. This
409 provides for very rapid retrieval of what function or variable the
410 cursor is currently in.
413 These functions query the current buffer's overlay system for tags.
415 @defun semantic-find-tag-by-overlay &optional positionormarker buffer
416 Find all tags covering @var{POSITIONORMARKER} by using overlays.
417 If @var{POSITIONORMARKER} is @code{nil}, use the current point.
418 Optional @var{BUFFER} is used if @var{POSITIONORMARKER} is a number, otherwise the current
419 buffer is used. This finds all tags covering the specified position
420 by checking for all overlays covering the current spot. They are then sorted
421 from largest to smallest via the start location.
423 @obsolete{semantic-find-nonterminal-by-overlay,semantic-find-tag-by-overlay}
426 @defun semantic-find-tag-by-overlay-in-region start end &optional buffer
427 Find all tags which exist in whole or in part between @var{START} and @var{END}.
428 Uses overlays to determine positin.
429 Optional @var{BUFFER} argument specifies the buffer to use.
431 @obsolete{semantic-find-nonterminal-by-overlay-in-region,semantic-find-tag-by-overlay-in-region}
434 @defun semantic-find-tag-by-overlay-next &optional start buffer
435 Find the next tag after @var{START} in @var{BUFFER}.
436 If @var{START} is in an overlay, find the tag which starts next,
440 @defun semantic-find-tag-by-overlay-prev &optional start buffer
441 Find the next tag before @var{START} in @var{BUFFER}.
442 If @var{START} is in an overlay, find the tag which starts next,
446 @defun semantic-current-tag
447 Return the current tag in the current buffer.
448 If there are more than one in the same location, return the
449 smallest tag. Return @code{nil} if there is no tag here.
451 @obsolete{semantic-current-nonterminal,semantic-current-tag}
454 @defun semantic-current-tag-parent
455 Return the current tags parent in the current buffer.
456 @var{A} tag's parent would be a containing structure, such as a type
457 containing a field. Return @code{nil} if there is no parent.
459 @obsolete{semantic-current-nonterminal-parent,semantic-current-tag-parent}
463 @chapter Tag Decoration
465 Tags can be decorated in different ways. One way a user can control
466 it is through @code{semantic-decoration-mode}.
467 @inforef{semantic-user,,Tag Decoration Mode}
469 Applications can use the same routines to decorate tags as well.
472 * Tag Highlighting:: Highlighting a tag
473 * Tag Visible Properties:: Invisible, intangible and read only
474 * Tag Secondary Overlays:: Decorating parts of a tag text
475 * Tag Folding:: Visibly Folding up tags
478 @node Tag Highlighting
479 @section Highlighting
481 @defun semantic-highlight-tag tag &optional face
482 @anchor{semantic-highlight-tag}
483 Specify that @var{tag} should be highlighted.
484 Optional @var{face} specifies the face to use.
485 @obsolete{semantic-highlight-token,semantic-highlight-tag}
488 @defun semantic-unhighlight-tag tag
489 @anchor{semantic-unhighlight-tag}
490 Unhighlight @var{tag}, restoring it's previous face.
491 @obsolete{semantic-unhighlight-token,semantic-unhighlight-tag}
494 @defun semantic-momentary-highlight-tag tag &optional face
495 @anchor{semantic-momentary-highlight-tag}
496 Highlight @var{tag}, removing highlighting when the user hits a key.
497 Optional argument @var{face} is the face to use for highlighting.
498 If @var{face} is not specified, then @code{highlight} will be used.
499 @obsolete{semantic-momentary-highlight-token,semantic-momentary-highlight-tag}
502 The highlighting routines do their work by changing the face property
503 of the tag overlay. The raw routine is:
505 @defun semantic-set-tag-face tag face
506 @anchor{semantic-set-tag-face}
507 Specify that @var{tag} should use @var{face} for display.
508 @obsolete{semantic-set-token-face,semantic-set-tag-face}
511 @node Tag Visible Properties
512 @section Changing a tag's visible properties
514 You can give a tag other properties as well, such as making it
515 invisible or intangible. You can control how code is edited
516 programatically through these routines.
518 @defun semantic-set-tag-invisible tag &optional visible
519 @anchor{semantic-set-tag-invisible}
520 Enable the text in @var{tag} to be made invisible.
521 If @var{visible} is non-@code{nil}, make the text visible.
522 @obsolete{semantic-set-token-invisible,semantic-set-tag-invisible}
525 @defun semantic-tag-invisible-p tag
526 @anchor{semantic-tag-invisible-p}
527 Return non-@code{nil} if @var{tag} is invisible.
528 @obsolete{semantic-token-invisible-p,semantic-tag-invisible-p}
531 @defun semantic-set-tag-intangible tag &optional tangible
532 @anchor{semantic-set-tag-intangible}
533 Enable the text in @var{tag} to be made intangible.
534 If @var{tangible} is non-@code{nil}, make the text visible.
535 This function does not have meaning in XEmacs because it seems that
536 the extent 'intangible' property does not exist.
537 @obsolete{semantic-set-token-intangible,semantic-set-tag-intangible}
540 @defun semantic-tag-intangible-p tag
541 @anchor{semantic-tag-intangible-p}
542 Return non-@code{nil} if @var{tag} is intangible.
543 This function does not have meaning in XEmacs because it seems that
544 the extent 'intangible' property does not exist.
545 @obsolete{semantic-token-intangible-p,semantic-tag-intangible-p}
548 @defun semantic-set-tag-read-only tag &optional writable
549 @anchor{semantic-set-tag-read-only}
550 Enable the text in @var{tag} to be made read-only.
551 Optional argument @var{writable} should be non-@code{nil} to make the text writable
552 instead of read-only.
553 @obsolete{semantic-set-token-read-only,semantic-set-tag-read-only}
556 @defun semantic-tag-read-only-p tag
557 @anchor{semantic-tag-read-only-p}
558 Return non-@code{nil} if the current @var{tag} is marked read only.
559 @obsolete{semantic-token-read-only-p,semantic-tag-read-only-p}
562 @node Tag Secondary Overlays
563 @section Secondary Overlays
565 Each tag which is being visited in a buffer has one overlay. This
566 overlay is used to track where the tag is while a user is editing, and
567 can also be used for fast tag identification, and some simple
568 decoration techniques.
570 A secondary overlay associates a new overlay object with a tag which
571 does not cover the entire body of a tag. You can then put visible
572 features on that overlay to decorate portions of a tag. This is how
573 tag boundaries are drawn.
575 @subsection Creation and Deletion
577 @defun semantic-tag-create-secondary-overlay tag &optional link-hook
578 @anchor{semantic-tag-create-secondary-overlay}
579 Create a secondary overlay for @var{tag}.
580 Returns an overlay. The overlay is also saved in @var{tag}.
581 @var{link-hook} is a function called whenever @var{tag} is to be linked into
582 a buffer. It should take @var{tag} and @var{overlay} as arguments.
583 The @var{link-hook} should be used to position and set properties on the
584 generated secondary overlay.
587 @defun semantic-tag-delete-secondary-overlay tag overlay-or-property
588 @anchor{semantic-tag-delete-secondary-overlay}
589 Delete from @var{tag} the secondary overlay @var{overlay-or-property}.
590 If @var{overlay-or-property} is an overlay, delete that overlay.
591 If @var{overlay-or-property} is a symbol, find the overlay with that property.
596 @defun semantic-tag-get-secondary-overlay tag property
597 @anchor{semantic-tag-get-secondary-overlay}
598 Return secondary overlays from @var{tag} with @var{property}.
599 @var{property} is a symbol and all overlays with that symbol are returned..
602 @defun semantic-tag-secondary-overlays tag
603 @anchor{semantic-tag-secondary-overlays}
604 Return a list of secondary overlays active on @var{tag}.
607 @subsection Linking and Unlinking
609 When a tag's file is put in a buffer, that tag is ``linked'' into the
610 buffer. When the buffer is deleted, the tag is ``unlinked''. This
611 process adds and removes the default overlay on the tag. Secondary
612 overlays use @code{semantic-tag-add-hook} and
613 @code{semantic-tag-remove-hook} too apply link and unlink hooks.
615 This allows the secondary overlays to be automatically removed or
616 added by the seconary overlay system whenever a tag's file goes in or
622 Using secondary overlays, a set of tag folding routines are made
623 available. These routines are similar to the tag visible properties.
625 @defun semantic-set-tag-folded tag &optional folded
626 @anchor{semantic-set-tag-folded}
627 Fold @var{tag}, such that only the first line of text is shown.
628 Optional argument @var{folded} should be non-@code{nil} to fold the tag.
629 @code{nil} implies the tag should be fully shown.
632 @defun semantic-tag-folded-p tag
633 @anchor{semantic-tag-folded-p}
634 Non-@code{nil} if @var{tag} is currently folded.
640 Sometimes it is important to reorganize a tag stream into a form that
641 is better for display to a user. It is important to not use functions
642 with side effects that could effect the tag cache.
644 There are some existing utility functions which will reorganize the
647 @defun semantic-unique-tag-table tags
648 @anchor{semantic-unique-tag-table}
649 Scan a list of @var{TAGS}, removing duplicates.
650 This must first sort the tags by position ascending.
651 @var{TAGS} are removed only if they are equivalent, as can happen when
652 multiple tag sources are scanned.
655 @defun semantic-unique-tag-table-by-name tags
656 @anchor{semantic-unique-tag-table-by-name}
657 Scan a list of @var{TAGS}, removing duplicate names.
658 This must first sort the tags by name alphabetically ascending.
661 @defun semantic-bucketize tags &optional parent filter
662 @anchor{semantic-bucketize}
663 Sort @var{tags} into a group of buckets based on tag class.
664 Unknown classes are placed in a Misc bucket.
665 Type bucket names are defined by either @code{semantic-symbol->name-assoc-list}.
666 If @var{parent} is specified, then @var{tags} belong to this @var{parent} in some way.
667 This will use @code{semantic-symbol->name-assoc-list-for-type-parts} to
668 generate bucket names.
669 Optional argument @var{filter} is a filter function to be applied to each bucket.
670 The filter function will take one argument, which is a list of tokens, and
671 may re-organize the list with side-effects.
674 @defvar semantic-bucketize-tag-class
675 @anchor{semantic-bucketize-tag-class}
676 Function used to get a symbol describing the class of a tag.
677 This function must take one argument of a semantic tag.
678 It should return a symbol found in @code{semantic-symbol->name-assoc-list}
679 which @dfn{semantic-bucketize} uses to bin up tokens.
680 To create new bins for an application augment
681 @code{semantic-symbol->name-assoc-list}, and
682 @code{semantic-symbol->name-assoc-list-for-type-parts} in addition
683 to setting this variable (locally in your function).
686 @defun semantic-adopt-external-members tags
687 @anchor{semantic-adopt-external-members}
688 Rebuild @var{tags} so that externally defined members are regrouped.
689 Some languages such as @var{c}++ and @var{clos} permit the declaration of member
690 functions outside the definition of the class. It is easier to study
691 the structure of a program when such methods are grouped together
694 This function uses @dfn{semantic-tag-external-member-p} to
695 determine when a potential child is an externally defined member.
697 Note: Applications which use this function must account for token
698 types which do not have a position, but have children which *do*
701 Applications should use @code{semantic-mark-external-member-function}
702 to modify all tags which are found as externally defined to some
703 type. For example, changing the token type for generating extra
704 buckets with the bucket function.
707 @defvar semantic-orphaned-member-metaparent-type
708 @anchor{semantic-orphaned-member-metaparent-type}
709 In @dfn{semantic-adopt-external-members}, the type of @code{'type} for metaparents.
710 A metaparent is a made-up type semantic token used to hold the child list
711 of orphaned members of a named type.
714 @defvar semantic-mark-external-member-function
715 @anchor{semantic-mark-external-member-function}
716 Function called when an externally defined orphan is found.
717 By default, the token is always marked with the @code{adopted} property.
718 This function should be locally bound by a program that needs
719 to add additional behaviors into the token list.
720 This function is called with two arguments. The first is @var{token} which is
721 a shallow copy of the token to be modified. The second is the @var{parent}
722 which is adopting @var{token}. This function should return @var{token} (or a copy of it)
723 which is then integrated into the revised token list.
727 @chapter Tag Completion
729 Often time, it is useful to ask the user for the name of some tag.
730 This can be as simple as just prompting for a name, but often time,
731 the semantics can be quite complex. If two tags have the same name,
734 Semantic provides a completion engine for prompting for tags by name,
735 and providing fancy ways to display completion lists that allow the
736 user to choose a tag if several have the same name.
738 To use a completion function in your interactive function, you can
739 augment the @dfn{interactive} command like this:
742 (defun my-function (tag)
743 "Do something to TAG."
744 (interactive (list (my-completion-function "Tag: ")))
749 * Tag Completion Convenience Functions:: Provided functions
750 * Custom Tag Completion Functions:: Build your own completion function
751 * Old Tag Completion:: Completion functions from older releases
754 @node Tag Completion Convenience Functions
755 @section Tag Completion Convenience Functions
757 There are some pre written completion functions that can be used in your
760 @defun semantic-complete-read-tag-buffer-deep prompt &optional default-tag initial-input history
761 Ask for a tag by name from the current buffer.
762 Available tags are from the current buffer, at any level.
763 Completion options are presented in a traditional way, with highlighting
764 to resolve same-name collisions.
765 @var{PROMPT} is a string to prompt with.
766 @var{DEFAULT-TAG} is a semantic tag or string to use as the default value.
767 If @var{INITIAL-INPUT} is non-@code{nil}, insert it in the minibuffer initially.
768 @var{HISTORY} is a symbol representing a variable to story the history in.
771 @defun semantic-complete-read-tag-project prompt &optional default-tag initial-input history
772 @anchor{semantic-complete-read-tag-project}
773 Ask for a tag by name from the current project.
774 Available tags are from the current project, at the top level.
775 Completion options are presented in a traditional way, with highlighting
776 to resolve same-name collisions.
777 @var{prompt} is a string to prompt with.
778 @var{default-tag} is a semantic tag or string to use as the default value.
779 If @var{initial-input} is non-@code{nil}, insert it in the minibuffer initially.
780 @var{history} is a symbol representing a variable to store the history in.
783 @defun semantic-complete-read-tag-analyzer prompt &optional context history
784 @anchor{semantic-complete-read-tag-analyzer}
785 Ask for a tag by name based on the current context.
786 The function @dfn{semantic-analyze-current-context} is used to
787 calculate the context. @dfn{semantic-analyze-possible-completions} is used
788 to generate the list of possible completions.
789 @var{prompt} is the first part of the prompt. Additional prompt
790 is added based on the contexts full prefix.
791 @var{context} is the semantic analyzer context to start with.
792 @var{history} is a symbol representing a variable to stor the history in.
793 usually a default-tag and initial-input are available for completion
794 prompts. these are calculated from the @var{context} variable passed in.
797 @defun semantic-complete-inline-analyzer context
798 @anchor{semantic-complete-inline-analyzer}
799 Complete a symbol name by name based on the current context.
800 This is similar to @code{semantic-complete-read-tag-analyze}, except
801 that the completion interaction is in the buffer where the context
803 @var{context} is the semantic analyzer context to start with.
804 See @code{semantic-complete-inline-tag-engine} for details on how
808 @node Custom Tag Completion Functions
809 @section Custom Tag Completion Functions
811 There aren't many built in completion functions, but there are many
812 parts that can be put together into custom completion functions.
814 A completion function is built up of three important parts.
818 Something that selects tags, and provides some list of tags
819 available, such as all functions, or all classes named ``bob''.
820 @item Typing and selecting
821 The prompt where you can type in the name of a tag.
822 @item Displaying possible completion values
823 A mechanism for displaying completion lists.
826 There is one typing and selecting routine that can be used to create
827 your custom completion prompt.
829 @defun semantic-complete-read-tag-engine collector displayor prompt default-tag initial-input history
830 @anchor{semantic-complete-read-tag-engine}
831 Read a semantic tag, and return a tag for the selection.
832 Argument @var{collector} is an object which can be used to to calculate
833 a list of possible hits. See @code{semantic-completion-collector-engine}
834 for details on @var{collector}.
835 Argumeng @var{displayor} is an object used to display a list of possible
836 completions for a given prefix. See@code{semantic-completion-display-engine}
837 for details on @var{displayor}.
838 @var{prompt} is a string to prompt with.
839 @var{default-tag} is a semantic tag or string to use as the default value.
840 If @var{initial-input} is non-@code{nil}, insert it in the minibuffer initially.
841 @var{history} is a symbol representing a variable to story the history in.
844 As you can see, this takes one @dfn{collector}, and one
845 @dfn{displayor}. These are objects created for this prompt at
846 runtime. The completion engine then uses to perform their tasks.
851 (defun semantic-complete-read-tag-buffer-deep (prompt &optional
852 default-tag initial-input history)
853 "Ask for a tag by name from the current buffer.
854 PROMPT is a string to prompt with.
855 DEFAULT-TAG is a semantic tag or string to use as the default value.
856 If INITIAL-INPUT is non-nil, insert it in the minibuffer initially.
857 HISTORY is a symbol representing a variable to story the history in."
858 (semantic-complete-read-tag-engine
859 (semantic-collector-buffer-deep prompt :buffer (current-buffer))
860 (semantic-displayor-traditional-with-focus-highlight "simple")
861 ;;(semantic-displayor-tooltip "simple")
875 @subsection Tag Collectors
877 A tag collector is an object that inherits from
878 @dfn{semantic-collector-abstract}. A new collector is needed for
879 each specialized type of prompt that draws from a different selection
882 You can have a collector that satisfies multiple purposes using slots
883 filled in the initializer for that object.
885 Collectors inherit from some of the following:
887 @deffn Type semantic-collector-abstract
888 @anchor{semantic-collector-abstract}
889 Root class for completion engines.
890 The baseclass provides basic functionality for interacting with
891 a completion displayor object, and tracking the current progress
895 @deffn Type semantic-collector-buffer-abstract
896 @anchor{semantic-collector-buffer-abstract}
897 Root class for per-buffer completion engines.
898 These collectors track themselves on a per-buffer basis.
901 @deffn Type semantic-collector-project-abstract
902 @anchor{semantic-collector-project-abstract}
903 Root class for project wide completion engines.
904 Uses semanticdb for searching all tags in the current project.
907 Available instantiable classes are:
909 @deffn Type semantic-collector-buffer-deep
910 @anchor{semantic-collector-buffer-deep}
911 Completion engine for tags in the current buffer.
912 When searching for a tag, uses semantic deep searche functions.
913 Basics search only in the current buffer.
916 @deffn Type semantic-collector-project
917 @anchor{semantic-collector-project}
918 Completion engine for tags in a project.
921 @deffn Type semantic-collector-project-brutish
922 @anchor{semantic-collector-project-brutish}
923 Completion engine for tags in a project.
926 @deffn Type semantic-collector-analyze-completions
927 @anchor{semantic-collector-analyze-completions}
928 Completion engine that uses the context analyzer to provide options.
929 The only options available for completion are those which can be logically
930 inserted into the current context.
933 NOTE: Add sections for writing new collectors.
935 @c (eieiodoc-class semantic-collector-abstract "cc")
940 @subsection Tag Displayors
942 When a user is interacting with the prompt, and requests completion,
943 those tags are drawn from the collector. If the user asks for a list
944 of completion by hitting a complete key twice, then the list of
945 completions heeds to be displayed in some way.
947 Displayors can be used to manage the display of all tags currently
948 available, AND often needs to be used to @b{focus} one one particular
949 tag of many in a visible way.
951 All displayors inherit from the displayor baseclass that defines the
954 @deffn Type semantic-displayor-abstract
955 @anchor{semantic-displayor-abstract}
956 Manages the display of some number of tags.
957 Provides the basics for a displayor, including interacting with
958 a collector, and tracking tables of completion to display.
961 @deffn Type semantic-displayor-focus-abstract
962 @anchor{semantic-displayor-focus-abstract}
963 A displayor which has the ability to focus in on one tag.
964 Focusing is a way of differentiationg between multiple tags
965 which have the same name.
968 Distinct implementations of displayors include:
970 @deffn Type semantic-displayor-traditional
971 @anchor{semantic-displayor-traditional}
972 Traditional display mechanism for a list of possible completions.
973 Completions are showin in a new buffer and listed with the ability
974 to click on the items to aid in completion.
977 @deffn Type semantic-displayor-traditional-with-focus-highlight
978 @anchor{semantic-displayor-traditional-with-focus-highlight}
979 A traditional displayor which can focus on a tag by showing it.
980 Same as @code{semantic-displayor-traditional}, but with selection between
981 multiple tags with the same name done by 'focusing' on the source
982 location of the different tags to differentiate them.
986 @deffn Type semantic-displayor-tooltip
987 @anchor{semantic-displayor-tooltip}
988 Display mechanism using tooltip for a list of possible completions.
991 NOTE: Add sections for writing new collectors.
993 @c (eieiodoc-class semantic-displayor-abstract "cd")
998 @node Old Tag Completion
999 @section Older Tag Completion functions
1001 These are older completion functions. They may still be useful.
1003 @defun semantic-read-symbol prompt &optional default stream filter
1004 @anchor{semantic-read-symbol}
1005 Read a symbol name from the user for the current buffer.
1006 @var{prompt} is the prompt to use.
1008 @var{default} is the default choice. If no default is given, one is read
1010 @var{stream} is the list of tokens to complete from.
1011 @var{filter} is provides a filter on the types of things to complete.
1012 @var{filter} must be a function to call on each element.
1015 @defun semantic-read-variable prompt &optional default stream
1016 @anchor{semantic-read-variable}
1017 Read a variable name from the user for the current buffer.
1018 @var{prompt} is the prompt to use.
1020 @var{default} is the default choice. If no default is given, one is read
1022 @var{stream} is the list of tokens to complete from.
1025 @defun semantic-read-function prompt &optional default stream
1026 @anchor{semantic-read-function}
1027 Read a function name from the user for the current buffer.
1028 @var{prompt} is the prompt to use.
1030 @var{default} is the default choice. If no default is given, one is read
1032 @var{stream} is the list of tags to complete from.
1035 @defun semantic-read-type prompt &optional default stream
1036 @anchor{semantic-read-type}
1037 Read a type name from the user for the current buffer.
1038 @var{prompt} is the prompt to use.
1040 @var{default} is the default choice. If no default is given, one is read
1042 @var{stream} is the list of tags to complete from.
1045 @node Override Methods
1046 @chapter Override Methods
1048 These functions are called `override methods' because they provide
1049 generic behaviors, which a given language can override. For example,
1050 finding a dependency file in Emacs lisp can be done with the
1051 `locate-library' command (which overrides the default behavior.) In C,
1052 a dependency can be found by searching a generic search path which can
1053 be passed in via a variable.
1055 If you plan to use one of these functions from a buffer that is not
1056 of the same major-mode as the original tag, you can use this form to
1057 make sure the correct action takes place:
1059 @defun semantic-with-mode-bindings mode &rest body
1060 @anchor{semantic-with-mode-bindings}
1061 Evaluate @var{BODY} with the local bindings of @var{MODE}.
1062 The current mode bindings are saved, @var{BODY} is evaluated, and the saved
1063 bindings are restored, even in case of an abnormal exit.
1064 Value is what @var{BODY} returns.
1067 For more on override methods, @inforef{Semantic Overload Mechanism, , lang-support-guide}.
1070 * Format Tag:: Converting Tokens into text strings
1071 * Tag Members:: Tags in tags
1072 * Tag Details:: Arbitrary token detail fetching
1073 * Making New Methods:: How to add your own methods for a tool
1079 Any given tag consists of Meta information which is best viewed in
1080 some textual form. This could be as simple as the tag's name, or as
1081 a prototype to be added to header file in C. Not only are there
1082 several default converters from a Tag into text, but there is also
1083 some convenient variables that can be used with them. Use these
1084 variables to allow options on output forms when displaying tags in
1087 @defvar semantic-format-tag-functions
1088 @anchor{semantic-format-tag-functions}
1089 List of functions which convert a tag to text.
1090 Each function must take the parameters @var{tag} &optional @var{parent} @var{color}.
1091 @var{tag} is the tag to convert.
1092 @var{parent} is a parent tag or name which refers to the structure
1093 or class which contains @var{tag}. @var{parent} is @var{not} a class which a @var{tag}
1094 would claim as a parent.
1095 @var{color} indicates that the generated text should be colored using
1099 @defvar semantic-format-tag-custom-list
1100 @anchor{semantic-format-tag-custom-list}
1101 A List used by customizeable variables to choose a tag to text function.
1102 Use this variable in the @code{:type} field of a customizable variable.
1105 Every tag to text conversion function must take the same parameters,
1106 which are @var{TAG}, the tag to be converted, @var{PARENT}, the
1107 containing parent (like a structure which contains a variable), and
1108 @var{COLOR}, which is a flag specifying that color should be applied
1109 to the returned string.
1111 When creating, or using these strings, particularly with color, use
1112 @dfn{concat} to build up larger strings instead of @dfn{format}. This
1113 will preserve text properties.
1115 @defun semantic-format-tag-name tag &optional parent color
1116 @anchor{semantic-format-tag-name}
1117 Return the name string describing @var{tag}.
1118 The name is the shortest possible representation.
1119 Optional argument @var{parent} is the parent type if @var{tag} is a detail.
1120 Optional argument @var{color} means highlight the prototype with font-lock colors.
1121 This function can be overloaded (see @dfn{define-mode-local-override} for details).
1122 @obsolete{semantic-name-nonterminal,semantic-format-tag-name}
1125 @defun semantic-format-tag-abbreviate tag &optional parent color
1126 @anchor{semantic-format-tag-abbreviate}
1127 Return an abbreviated string describing @var{tag}.
1128 The abbreviation is to be short, with possible symbols indicating
1129 the type of tag, or other information.
1130 Optional argument @var{parent} is the parent type if @var{tag} is a detail.
1131 Optional argument @var{color} means highlight the prototype with font-lock colors.
1132 This function can be overloaded (see @dfn{define-mode-local-override} for details).
1133 @obsolete{semantic-abbreviate-nonterminal,semantic-format-tag-abbreviate}
1136 @defun semantic-format-tag-summarize tag &optional parent color
1137 @anchor{semantic-format-tag-summarize}
1138 Summarize @var{tag} in a reasonable way.
1139 Optional argument @var{parent} is the parent type if @var{tag} is a detail.
1140 Optional argument @var{color} means highlight the prototype with font-lock colors.
1141 This function can be overloaded (see @dfn{define-mode-local-override} for details).
1142 @obsolete{semantic-summerize-nonterminal,semantic-format-tag-summarize}
1145 @defun semantic-format-tag-prototype tag &optional parent color
1146 @anchor{semantic-format-tag-prototype}
1147 Return a prototype for @var{tag}.
1148 This function should be overloaded, though it need not be used.
1149 This is because it can be used to create code by language independent
1151 Optional argument @var{parent} is the parent type if @var{tag} is a detail.
1152 Optional argument @var{color} means highlight the prototype with font-lock colors.
1153 This function can be overloaded (see @dfn{define-mode-local-override} for details).
1154 @obsolete{semantic-prototype-nonterminal,semantic-format-tag-prototype}
1157 @defun semantic-format-tag-concise-prototype tag &optional parent color
1158 @anchor{semantic-format-tag-concise-prototype}
1159 Return a concise prototype for @var{tag}.
1160 Optional argument @var{parent} is the parent type if @var{tag} is a detail.
1161 Optional argument @var{color} means highlight the prototype with font-lock colors.
1162 This function can be overloaded (see @dfn{define-mode-local-override} for details).
1163 @obsolete{semantic-concise-prototype-nonterminal,semantic-format-tag-concise-prototype}
1166 @defun semantic-format-tag-uml-abbreviate tag &optional parent color
1167 @anchor{semantic-format-tag-uml-abbreviate}
1168 Return a @var{uml} style abbreviation for @var{tag}.
1169 Optional argument @var{parent} is the parent type if @var{tag} is a detail.
1170 Optional argument @var{color} means highlight the prototype with font-lock colors.
1171 This function can be overloaded (see @dfn{define-mode-local-override} for details).
1172 @obsolete{semantic-uml-abbreviate-nonterminal,semantic-format-tag-uml-abbreviate}
1175 @defun semantic-format-tag-uml-prototype tag &optional parent color
1176 @anchor{semantic-format-tag-uml-prototype}
1177 Return a @var{uml} style prototype for @var{tag}.
1178 Optional argument @var{parent} is the parent type if @var{tag} is a detail.
1179 Optional argument @var{color} means highlight the prototype with font-lock colors.
1180 This function can be overloaded (see @dfn{define-mode-local-override} for details).
1181 @obsolete{semantic-uml-prototype-nonterminal,semantic-format-tag-uml-prototype}
1184 @defun semantic-format-tag-uml-concise-prototype tag &optional parent color
1185 @anchor{semantic-format-tag-uml-concise-prototype}
1186 Return a @var{uml} style concise prototype for @var{tag}.
1187 Optional argument @var{parent} is the parent type if @var{tag} is a detail.
1188 Optional argument @var{color} means highlight the prototype with font-lock colors.
1189 This function can be overloaded (see @dfn{define-mode-local-override} for details).
1190 @obsolete{semantic-uml-concise-prototype-nonterminal,semantic-format-tag-uml-concise-prototype}
1193 @defun semantic-format-tag-prin1 tag &optional parent color
1194 @anchor{semantic-format-tag-prin1}
1195 Convert @var{tag} to a string that is the print name for @var{tag}.
1196 @var{parent} and @var{color} are ignored.
1197 @obsolete{semantic-prin1-nonterminal,semantic-format-tag-prin1}
1200 An additional utility will return a string for just the data type of
1201 a tag. This function is used in the above routines as well.
1203 @defun semantic-format-tag-type tag color
1204 @anchor{semantic-format-tag-type}
1205 Convert the data type of @var{tag} to a string usable in tag formatting.
1206 It is presumed that @var{type} is a string or semantic tag.
1207 This function can be overloaded (see @dfn{define-mode-local-override} for details).
1211 @section Tag Members
1213 Tags are often in a hierarchical form, meaning that a tag found in
1214 the top-level list may itself contain additional members.
1216 The following overridable functions can fetch those tags.
1218 @defun semantic-tag-components tag
1219 Return a list of components for @var{tag}.
1220 A Component is a part of @var{tag} which itself may be a @var{tag}.
1221 Examples include the elements of a structure in a
1222 tag of class `type, or the list of arguments to a
1223 tag of class @code{'function}.
1224 This function can be overloaded (see @dfn{define-mode-local-override} for details).
1227 @defun semantic-tag-components-with-overlays tag
1228 Return the list of top level components belonging to @var{tag}.
1229 Children are any sub-tags which contain overlays.
1231 Default behavior is to get @dfn{semantic-tag-components} in addition
1232 to the components of an anonymous types (if applicable.)
1234 Note for language authors:
1235 If a mode defines a language tag that has tags in it with overlays
1236 you should still return them with this function.
1237 Ignoring this step will prevent several features from working correctly.
1238 This function can be overloaded (see @dfn{define-mode-local-override} for details).
1241 Some languages can define parts of a tag outside the actual scope of
1242 the parent tag. You can fetch information about them with these
1246 @defun semantic-tag-external-member-p parent tag
1247 @anchor{semantic-tag-external-member-p}
1248 Return non-@code{nil} if @var{parent} is the parent of @var{tag}.
1249 @var{tag} is an external member of @var{parent} when it is somehow tagged
1250 as having @var{parent} as it's parent.
1251 @var{parent} and @var{tag} must both be semantic tags.
1253 The default behavior, if not overridden with
1254 @code{tag-external-member-p} is to match @code{:parent} attribute in
1255 the name of @var{tag}.
1257 If this function is overridden, use
1258 @code{semantic-tag-external-member-children-p-default} to also
1259 include the default behavior, and merely extend your own.
1260 This function can be overloaded (see @dfn{define-mode-local-override} for details).
1261 @obsolete{semantic-nonterminal-external-member-p,semantic-tag-external-member-p}
1264 @defun semantic-tag-external-member-children tag &optional usedb
1265 @anchor{semantic-tag-external-member-children}
1266 Return the list of children which are not *in* @var{tag}.
1267 If optional argument @var{usedb} is non-@code{nil}, then also search files in
1268 the Semantic Database. If @var{usedb} is a list of databases, search those
1271 Children in this case are functions or types which are members of
1272 @var{tag}, such as the parts of a type, but which are not defined inside
1273 the class. @var{c}++ and @var{clos} both permit methods of a class to be defined
1274 outside the bounds of the class' definition.
1276 The default behavior, if not overridden with
1277 @code{tag-external-member-children} is to search using
1278 @dfn{semantic-tag-external-member-p} in all top level definitions
1279 with a parent of @var{tag}.
1281 If this function is overridden, use
1282 @dfn{semantic-tag-external-member-children-default} to also
1283 include the default behavior, and merely extend your own.
1284 This function can be overloaded (see @dfn{define-mode-local-override} for details).
1285 @obsolete{semantic-nonterminal-external-member-children,semantic-tag-external-member-children}
1289 @section Tag Details
1291 These functions help derive information about tags that may not
1292 be obvious for non-traditional languages with their own token types.
1294 @defun semantic-tag-protection tag &optional parent
1295 @anchor{semantic-tag-protection}
1296 Return protection information about @var{tag} with optional @var{parent}.
1297 This function returns on of the following symbols:
1298 @code{nil} - No special protection. Language dependent.
1299 @code{'public} - Anyone can access this @var{tag}.
1300 @code{'private} - Only methods in the local scope can access @var{tag}.
1301 @code{'protected} - Like private for outside scopes, like public for child
1303 Some languages may choose to provide additional return symbols specific
1304 to themselves. Use of this function should allow for this.
1306 The default behavior (if not overridden with @code{tag-protection}
1307 is to return a symbol based on type modifiers.
1308 This function can be overloaded (see @dfn{define-mode-local-override} for details).
1309 It makes the overload @dfn{semantic-nonterminal-protection} obsolete.
1310 @obsolete{semantic-nonterminal-protection,semantic-tag-protection}
1313 @defun semantic-tag-protected-p tag protection &optional parent
1314 @anchor{semantic-tag-protected-p}
1315 Non-@code{nil} if @var{tag} is is protected.
1316 @var{protection} is a symbol which can be returned by the method
1317 @dfn{semantic-tag-protection}.
1318 @var{parent} is the parent data type which contains @var{tag}.
1320 For these PROTECTIONs, true is returned if @var{tag} is:
1327 True if private or @code{nil}.
1329 True if private, protected, or @code{nil}.
1333 @defun semantic-tag-abstract-p tag &optional parent
1334 @anchor{semantic-tag-abstract-p}
1335 Return non @code{nil} if @var{tag} is abstract.
1336 Optional @var{parent} is the parent tag of @var{tag}.
1337 In @var{uml}, abstract methods and classes have special meaning and behavior
1338 in how methods are overridden. In @var{uml}, abstract methods are italicized.
1340 The default behavior (if not overridden with @code{tag-abstract-p}
1341 is to return true if @code{abstract} is in the type modifiers.
1342 This function can be overloaded (see @dfn{define-mode-local-override} for details).
1343 It makes the overload @dfn{semantic-nonterminal-abstract} obsolete.
1344 @obsolete{semantic-nonterminal-abstract,semantic-tag-abstract-p}
1347 @defun semantic-tag-leaf-p tag &optional parent
1348 @anchor{semantic-tag-leaf-p}
1349 Return non @code{nil} if @var{tag} is leaf.
1350 Optional @var{parent} is the parent tag of @var{tag}.
1351 In @var{uml}, leaf methods and classes have special meaning and behavior.
1353 The default behavior (if not overridden with @code{tag-leaf-p}
1354 is to return true if @code{leaf} is in the type modifiers.
1355 This function can be overloaded (see @dfn{define-mode-local-override} for details).
1356 It makes the overload @dfn{semantic-nonterminal-leaf} obsolete.
1357 @obsolete{semantic-tag-leaf,semantic-tag-leaf-p}
1360 @defun semantic-tag-static-p tag &optional parent
1361 @anchor{semantic-tag-static-p}
1362 Return non @code{nil} if @var{tag} is static.
1363 Optional @var{parent} is the parent tag of @var{tag}.
1364 In @var{uml}, static methods and attributes mean that they are allocated
1365 in the parent class, and are not instance specific.
1366 @var{uml} notation specifies that @var{static} entries are underlined.
1367 This function can be overloaded (see @dfn{define-mode-local-override} for details).
1368 @obsolete{semantic-tag-static,semantic-tag-static-p}
1371 @defvar semantic-dependency-include-path
1372 @anchor{semantic-dependency-include-path}
1373 Defines the include path used when searching for files.
1374 This should be a list of directories to search which is specific
1375 to the file being included.
1377 If @dfn{semantic-dependency-tag-file} is overridden for a given
1378 language, this path is most likely ignored.
1380 This function, reguardless of being overriden, caches the located
1381 dependency file location in the tag property @code{dependency-file}.
1382 If you override this function, you do not need to implement your
1383 own cache. Each time the buffer is fully reparsed, the cache
1386 @var{todo}: use ffap.el to locate such items.
1389 @defun semantic-dependency-tag-file &optional tag
1390 @anchor{semantic-dependency-tag-file}
1391 Find the filename represented from @var{tag}.
1392 Depends on @code{semantic-dependency-include-path} for searching. Always searches
1393 @code{.} first, then searches additional paths.
1394 This function can be overloaded (see @dfn{define-mode-local-override} for details).
1395 It makes the overload @dfn{semantic-find-dependency} obsolete.
1396 @obsolete{semantic-find-dependency,semantic-dependency-tag-file}
1399 @defun semantic-prototype-file buffer
1400 @anchor{semantic-prototype-file}
1401 Return a file in which prototypes belonging to @var{buffer} should be placed.
1402 Default behavior (if not overridden) looks for a token specifying the
1403 prototype file, or the existence of an @var{ede} variable indicating which
1404 file prototypes belong in.
1405 This function can be overloaded (see @dfn{define-mode-local-override} for details).
1408 @defun semantic-go-to-tag tag &optional parent
1409 @anchor{semantic-go-to-tag}
1410 Go to the location of @var{tag}.
1411 @var{tag} may be a stripped element, in which case @var{parent} specifies a
1412 parent tag that has position information.
1413 Different behaviors are provided depending on the type of tag.
1414 For example, dependencies (includes) will seek out the file that is
1415 depended on (see @dfn{semantic-dependency-tag-file}.
1416 This function can be overloaded (see @dfn{define-mode-local-override} for details).
1417 It makes the overload @dfn{semantic-find-nonterminal} obsolete.
1418 @obsolete{semantic-find-nonterminal,semantic-go-to-tag}
1421 @defun semantic-texi-find-documentation name &optional type
1422 @anchor{semantic-texi-find-documentation}
1423 Find the function or variable @var{name} of @var{type} in the texinfo source.
1424 @var{name} is a string representing some functional symbol.
1425 @var{type} is a string, such as ``variable`` or ''Command'' used to find
1426 the correct definition in case @var{name} qualifies as several things.
1427 When this function exists, @var{point} is at the definition.
1428 If the doc was not found, an error is thrown.
1429 Note: @var{type} not yet implemented.
1432 @node Making New Methods
1433 @section Making New Methods
1435 To create your own application specific mode local function, you
1436 should use @dfn{define-overload}. This function creates the
1437 framework needed for different mode-authors to customize your
1440 Once a function has been defined as mode-local, you should use
1441 @dfn{define-mode-local-override} to add a mode specific feature.
1443 @defun define-overload name args docstring &rest body
1444 @anchor{define-overload}
1445 Define a new function, as with @dfn{defun} which can be overloaded.
1446 @var{name} is the name of the function to create.
1447 @var{args} are the arguments to the function.
1448 @var{docstring} is a documentation string to describe the function. The
1449 docstring will automatically had details about its overload symbol
1450 appended to the end.
1451 @var{body} is code that would be run when there is no override defined. The
1452 default is to call the function @code{NAME-default} with the appropriate
1455 @var{body} can also include an override form that specifies which part of
1456 @var{body} is specifically overridden. This permits to specify common code
1457 run for both default and overridden implementations.
1458 An override form is one of:
1460 @var{1}. (:override [@var{overbody}])
1461 @var{2}. (:override-with-args @var{overargs} [@var{overbody}])
1463 @var{overbody} is the code that would be run when there is no override
1464 defined. The default is to call the function @code{NAME-default} with the
1465 appropriate arguments deduced from @var{args}.
1466 @var{overargs} is a list of arguments passed to the override and
1467 @code{NAME-default} function, in place of those deduced from @var{args}.
1470 @defun define-mode-local-override name mode args docstring &rest body
1471 @anchor{define-mode-local-override}
1472 Define a mode specific override of the function overload @var{name}.
1473 Has meaning only if @var{name} has been created with @dfn{define-overload}.
1474 @var{mode} is the major mode this override is being defined for.
1475 @var{args} are the function arguments, which should match those of the same
1476 named function created with @dfn{define-overload}.
1477 @var{docstring} is the documentation string.
1478 @var{body} is the implementation of this function.
1479 @obsolete{define-mode-overload-implementation,define-mode-local-override}
1482 @node Parser Features
1483 @chapter Parser Features
1485 If you write a program that uses a tag table in a persistent
1486 display or database, it is necessary to know when tag tables change so
1487 that your displays can be updated. This is especially important as
1488 tags can be replaced, changed, or deleted, and the associated
1489 overlays will then throw errors when you try to use them. Complete
1490 integration with tag changes can be achieved via several hooks.
1492 If you write an application that frequenly accesses the tags tables,
1493 it is important to make sure those tags are up to date, and to make
1494 sure you application does not adversely effect all the other minor
1495 modes that may be running.
1497 The semantic parser has many features and hooks that applications can
1498 use to provide a good user experience.
1501 * Editing Buffers:: Let the parser know you are changing a buffer.
1502 * Parser State:: Knowing if the tag table is out of date
1503 * Parser Hooks:: Knowing when tags change
1504 * Lexical Safety:: Preventing lexical errors from making a mess
1507 @node Editing Buffers
1508 @section Editing Buffers
1510 One interesting way to interact with the parser is to let it know that
1511 changes you are going to make will not require re-parsing.
1513 @defvar semantic-edits-are-safe
1514 When non-@code{nil}, modifications do not require a reparse.
1515 This prevents tokens from being marked dirty, and it
1516 prevents top level edits from causing a cache check.
1517 Use this when writing programs that could cause a full
1518 reparse, but will not change the tag structure, such
1519 as adding or updating top-level comments.
1523 @section Parser State
1525 It is sometimes useful to know what the current parsing state
1526 is. These function can let you know what level of re-parsing may be
1527 needed. Careful choices on when to reparse can make your program much
1530 @defun semantic-parse-tree-needs-update-p
1531 @anchor{semantic-parse-tree-needs-update-p}
1532 Return non-@code{nil} if the current parse tree needs to be updated.
1535 @defun semantic-parse-tree-needs-rebuild-p
1536 @anchor{semantic-parse-tree-needs-rebuild-p}
1537 Return non-@code{nil} if the current parse tree needs to be rebuilt.
1540 @defun semantic-parse-tree-unparseable-p
1541 @anchor{semantic-parse-tree-unparseable-p}
1542 Return non-@code{nil} if the current buffer has been marked unparseable.
1545 @defun semantic-parse-tree-up-to-date-p
1546 @anchor{semantic-parse-tree-up-to-date-p}
1547 Return non-@code{nil} if the current parse tree is up to date.
1551 @section Parser Hooks
1553 If you just want to know when a buffer changes, use this hook.
1555 @defvar semantic-after-toplevel-cache-change-hook
1556 @anchor{semantic-after-toplevel-cache-change-hook}
1557 Hooks run after the buffer tag list has changed.
1558 This list will change when a buffer is reparsed, or when the tag list
1559 in a buffer is cleared. It is *@var{not}* called if the current tag list is
1562 Hook functions must take one argument, which is the new list of tags
1563 associated with this buffer.
1565 For language specific hooks, make sure you define this as a local hook.
1568 If you want tighter interaction with how the user is editing
1569 different tags, you can use this hook instead.
1571 @defvar semantic-after-partial-cache-change-hook
1572 @anchor{semantic-after-partial-cache-change-hook}
1573 Hooks run after the buffer cache has been updated.
1575 This hook will run when the cache has been partially reparsed.
1576 Partial reparses are incurred when a user edits a buffer, and only the
1577 modified sections are rescanned.
1579 Hook functions must take one argument, which is the list of tokens
1580 updated in the current buffer.
1582 For language specific hooks, make sure you define this as a local hook.
1585 It is also useful to clean up any data your application is using when
1586 semantic flushes its tags table.
1588 @defvar semantic-before-toplevel-cache-flush-hook
1589 @anchor{semantic-before-toplevel-cache-flush-hook}
1590 Hooks run before the toplevel nonterminal cache is flushed.
1591 For language specific hooks, make sure you define this as a local
1592 hook. This hook is called before a corresponding
1593 @code{semantic-after-toplevel-cache-change-hook} which is also called
1594 during a flush when the cache is given a new value of @code{nil}.
1597 @node Lexical Safety
1598 @section Lexical Safety
1600 If you application frequenly requests lists of tags upon user request,
1601 it may be important to avoid lexical problems that frequenly occur
1602 when the user has partially written an expression, such as starting a
1603 string, or argument list.
1605 You can protect your code from lexical problems with this macro:
1607 @defun semantic-lex-catch-errors symbol &rest forms
1608 @anchor{semantic-lex-catch-errors}
1609 Using @var{SYMBOL}, execute @var{FORMS} catching lexical errors.
1610 If @var{FORMS} results in a call to the parser that throws a lexical error,
1611 the error will be caught here without the buffer's cache being thrown
1613 If there is an error, the syntax that failed is returned.
1614 If there is no error, then the last value of @var{FORMS} is returned.
1617 It is important to provide a good @var{SYMBOL} so that these macros
1620 If you want your code to run anyway, even if there is a lexical
1621 error, using this macro like this:
1624 (semantic-lex-catch-errors
1625 (semantic-fetch-tags))
1628 will put the parser into the 'unparseable' state, and allow other
1629 routines to request the tag table without incurring additional parser
1632 @node Semantic Database
1633 @chapter Semantic Database
1635 Semanticdb is a database mechanism for storing tags parsed by
1636 @semantic{}. The database operates in the background, saving tags as
1637 they are parsed between sessions. When a file is read in, and there
1638 is a previously created set of tags available for it, sematnicdb will
1639 save time by not parsing the file, and using the cached copy.
1641 In applications, semanticdb can provide access to the sum of all tags
1642 in a project or in the basic system. This database can they be
1643 searched using a set of special routines.
1646 * Semanticdb in Programs:: Basic usage.
1647 * Semanticdb Tag Queries:: Searching for tokens in the databases.
1648 * System Databases:: Special kinds of databases for system tags.
1651 @node Semanticdb in Programs
1652 @section Semanticdb in Programs::
1654 If you write a program using semanticdb, you will probably want to
1655 make sure it is active in your program.
1657 @defun semanticdb-minor-mode-p
1658 @anchor{semanticdb-minor-mode-p}
1659 Return non-@code{nil} if @code{semanticdb-minor-mode} is active.
1662 Since semanticdb is optional, it is best if a program can gracefully
1663 degrade service when semanticdb is not available, or to throw an
1664 error letting the user know it is required to be active.
1666 At the simplest level, you can ask if a given file is in the
1667 database, recieving a tag table. Semanticdb will give you an
1668 accurate set of tags just by asking.
1670 @defun semanticdb-file-stream file
1671 @anchor{semanticdb-file-stream}
1672 Return a list of tags belonging to @var{file}.
1673 If file has database tags available in the database, return them.
1674 If file does not have tags available, then load the file, and create them.
1677 Alternately, you can get at the table object for a file by asking for
1680 @defun semanticdb-file-table-object file &optional dontload
1681 @anchor{semanticdb-file-table-object}
1682 Return a semanticdb table belonging to @var{file}.
1683 If file has database tags available in the database, return it.
1684 If file does not have tags available, and @var{dontload} is @code{nil},
1685 then load the tags for @var{file}, and create a new table object for it.
1686 @var{dontload} does not affect the creation of new database objects.
1689 @node Semanticdb Tag Queries
1690 @section Semanticdb Tag Queries
1692 You can search for tags in the semantic database using the
1693 semanticdb-find API. It is important to note that database search
1694 functions do not return a plain list of tags. This is because some
1695 tags may not be loaded in a buffer, which means that the found tag
1696 would not have an overlay, and no way to determine where it came from.
1698 As such, all search functions return a special Database Results list.
1700 There are several types of searches, divided into groups by
1701 implementation. While it is possible to add new types of searches,
1702 or write custom searches, the built in searches are usually the only
1703 ones available in system backends @ref{System Databases}.
1705 When the term @b{brute} or @b{brutish} is used as a search criteria,
1706 that is distinguishing between an include-path based search, and a
1707 search that scans everything available in a project.
1709 Non-brute force searches assume that all symbols available in a given
1710 buffer are on the search path, or in some file that has been
1711 included, imported, or otherwise indicated in the source file
1712 itself. While not always true for interpreted languages (such as
1713 Emacs Lisp), it is common among declaritive languages.
1715 Sometimes a brute force approach is needed, scanning every file
1716 available to the database. You may want to do this if your
1717 application is collecting data unrelated to a file currently being
1721 * DB Results:: Accessing the results of a search.
1722 * DB Search Paths:: The list of tables to search.
1723 * DB Basic Name Search:: Searches based on name.
1724 * DB Basic Brute Search:: Searches on common tag attributes.
1725 * DB Advanced Search:: Complex searches on associations
1726 * DB Generic Brute Search:: Do It Yourself search criteria
1730 @subsection DB Results
1732 The successful results of a search returns a special list of the
1736 ( (DATABASE TAG1 TAG2 ...) (DATABASE2 TAG3 TAG4 ...) ...)
1739 It should not be necessary to access the results in this way,
1740 however, as there are several routines that can be used to access
1743 To turn a semanticdb search result into a simple tag table, use:
1745 @defun semanticdb-strip-find-results results &optional find-file-match
1746 @anchor{semanticdb-strip-find-results}
1747 Strip a semanticdb search @var{results} to exclude objects.
1748 This makes it appear more like the results of a @code{semantic-find-} call.
1749 Optional @var{find-file-match} loads all files associated with @var{results}
1750 into buffers. This has the side effect of enabling @dfn{semantic-tag-buffer} to
1754 To write a function that accepts a tag table, or a semanticdb search
1755 result, use this to test if it is a semanticdb search result:
1757 @defun semanticdb-find-results-p resultp
1758 @anchor{semanticdb-find-results-p}
1759 Non-@code{nil} if @var{resultp} is in the form of a semanticdb search result.
1760 This query only really tests the first entry in the list that is @var{resultp},
1761 but should be good enough for debugging assertions.
1764 @defun semanticdb-find-result-with-nil-p resultp
1765 @anchor{semanticdb-find-result-with-nil-p}
1766 Non-@code{nil} of @var{resultp} is in the form of a semanticdb search result.
1767 @code{nil} is a valid value where a @var{table} usually is, but only if the @var{tag}
1768 results include overlays.
1769 This query only really tests the first entry in the list that is @var{resultp},
1770 but should be good enough for debugging assertions.
1773 To operate on the search results as though it were a simple tags
1774 table, or plain list, use these routines.
1776 @defun semanticdb-find-result-length result
1777 @anchor{semanticdb-find-result-length}
1778 Number of tags found in @var{result}.
1781 @defun semanticdb-find-result-nth result n
1782 @anchor{semanticdb-find-result-nth}
1783 In @var{result}, return the Nth search result.
1784 This is a @var{0} based search result, with the first match being element @var{0}.
1786 The returned value is a cons cell: (@var{tag} . @var{table}) where @var{tag}
1787 is the tag at the Nth position. @var{table} is the semanticdb table where
1788 the @var{tag} was found. Sometimes @var{table} can be @code{nil}.
1791 @defun semanticdb-find-result-nth-in-buffer result n
1792 @anchor{semanticdb-find-result-nth-in-buffer}
1793 In @var{result}, return the Nth search result.
1794 Like @dfn{semanticdb-find-result-nth}, except that only the @var{tag}
1795 is returned, and the buffer it is found it will be made current.
1796 If the result tag has no position information, the originating buffer
1797 is still made current.
1800 @node DB Search Paths
1801 @subsection DB Search Paths
1803 For searches based on an include path (non-brutish) a path of tables
1804 needs to be generated. Searching a lot of tables is slow, which is
1805 why a brutish search is not always recommended. An include-based
1806 approach can also generate a lot of tables, so you can control how
1807 detailed a search is with a throttle variable.
1809 Ideally, each language mode will have a mode-specific value for
1810 this throttle value. A user can also specify their own values if the
1811 default is not good enough.
1813 @defvar semanticdb-find-default-throttle
1814 @anchor{semanticdb-find-default-throttle}
1815 The default throttle for @code{semanticdb-find} routines.
1816 The throttle controls how detailed the list of database
1817 tables is for a symbol lookup. The value is a list with
1822 The file the search is being performed from. This option is here for
1823 completeness only, and is assumed to always be on.
1825 Tables from the same local directory are included. This includes
1826 files directly referenced by a file name which might be in a different
1829 Tables from the same local project are included If @code{project} is
1830 specified, then @code{local} is assumed.
1832 If a table is not in memory, load it. If it is not cached on disk
1833 either, get the source, parse it, and create the table.
1835 Tables from system databases. These are specifically tables
1836 from system header files, or language equivalent.
1838 For include based searches, includes tables referenced by included
1841 Included system databases which are omniscience, or somehow know
1842 everything. Omniscience databases are found in
1843 @code{semanticdb-project-system-databases}. The Emacs Lisp system
1844 @var{db} is an omniscience database.
1851 You can use the command @code{semanticdb-find-test-translate-path} to
1852 interactively test out how the path translator is working. The path
1853 translation routines are:
1855 @defun semanticdb-find-translate-path path brutish
1856 @anchor{semanticdb-find-translate-path}
1857 Translate @var{path} into a list of semantic tables.
1858 Path translation involves identifying the @var{path} input argument
1859 in one of the following ways:
1860 @code{nil} - Take the current buffer, and use it's include list
1861 buffer - Use that buffer's include list.
1862 filename - Use that file's include list. If the file is not
1863 in a buffer, see of there is a semanticdb table for it. If
1864 not, read that file into a buffer.
1865 tag - Get that tag's buffer of file file. See above.
1866 table - Search that table, and it's include list.
1867 find result - Search the results of a previous find.
1869 In addition, once the base path is found, there is the possibility of
1870 each added table adding yet more tables to the path, so this routine
1871 can return a lengthy list.
1873 If argument @var{brutish} is non-@code{nil}, then instead of using the include
1874 list, use all tables found in the parent project of the table
1875 identified by translating @var{path}. Such searches use brute force to
1876 scan every available table.
1878 The return value is a list of objects of type @dfn{semanticdb-table} or
1879 it's children. In the case of passing in a find result, the result
1880 is returned unchanged.
1882 This routine uses @dfn{semanticdb-find-table-for-include} to translate
1883 specific include tags into a semanticdb table.
1884 This function can be overloaded (see @dfn{define-mode-local-override} for details).
1887 @defun semanticdb-find-table-for-include includetag &optional table
1888 @anchor{semanticdb-find-table-for-include}
1889 For a single @var{includetag} found in @var{table}, find a @dfn{semanticdb-table} object
1890 @var{includetag} is a semantic @var{tag} of class @code{'include}.
1891 @var{table} as defined by @dfn{semantic-something-to-tag-table} to identify
1892 where the tag came from. @var{table} is optional if @var{includetag} has an
1893 overlay of @code{:filename} attribute.
1894 This function can be overloaded (see @dfn{define-mode-local-override} for details).
1897 @node DB Basic Name Search
1898 @subsection DB Basic Name Search
1900 These searches scan a database table collection for tags based on
1901 name. They are divided into normal and deep searches. A deep
1902 search, as with in buffer tag scanning, implies that all entries are
1903 scanned, including those in type declarations.
1907 @defun semanticdb-find-tags-by-name name &optional path find-file-match
1908 @anchor{semanticdb-find-tags-by-name}
1909 Search for all tags matching @var{name} on @var{path}.
1910 See @dfn{semanticdb-find-translate-path} for details on @var{path}.
1911 @var{find-file-match} indicates that any time a match is found, the file
1912 associated with that tag should be loaded into a buffer.
1915 @defun semanticdb-find-tags-by-name-regexp regexp &optional path find-file-match
1916 @anchor{semanticdb-find-tags-by-name-regexp}
1917 Search for all tags matching @var{regexp} on @var{path}.
1918 See @dfn{semanticdb-find-translate-path} for details on @var{path}.
1919 @var{find-file-match} indicates that any time a match is found, the file
1920 associated with that tag should be loaded into a buffer.
1923 @defun semanticdb-find-tags-for-completion prefix &optional path find-file-match
1924 @anchor{semanticdb-find-tags-for-completion}
1925 Search for all tags matching @var{prefix} on @var{path}.
1926 See @dfn{semanticdb-find-translate-path} for details on @var{path}.
1927 @var{find-file-match} indicates that any time a match is found, the file
1928 associated with that tag should be loaded into a buffer.
1931 @defun semanticdb-find-tags-by-class class &optional path find-file-match
1932 @anchor{semanticdb-find-tags-by-class}
1933 Search for all tags of @var{class} on @var{path}.
1934 See @dfn{semanticdb-find-translate-path} for details on @var{path}.
1935 @var{find-file-match} indicates that any time a match is found, the file
1936 associated with that tag should be loaded into a buffer.
1941 @defun semanticdb-deep-find-tags-by-name name &optional path find-file-match
1942 @anchor{semanticdb-deep-find-tags-by-name}
1943 Search for all tags matching @var{name} on @var{path}.
1944 Search also in all components of top level tags founds.
1945 See @dfn{semanticdb-find-translate-path} for details on @var{path}.
1946 @var{find-file-match} indicates that any time a match is found, the file
1947 associated with that tag should be loaded into a buffer.
1950 @defun semanticdb-deep-find-tags-by-name-regexp regexp &optional path find-file-match
1951 @anchor{semanticdb-deep-find-tags-by-name-regexp}
1952 Search for all tags matching @var{regexp} on @var{path}.
1953 Search also in all components of top level tags founds.
1954 See @dfn{semanticdb-find-translate-path} for details on @var{path}.
1955 @var{find-file-match} indicates that any time a match is found, the file
1956 associated with that tag should be loaded into a buffer.
1959 @defun semanticdb-deep-find-tags-for-completion prefix &optional path find-file-match
1960 @anchor{semanticdb-deep-find-tags-for-completion}
1961 Search for all tags matching @var{prefix} on @var{path}.
1962 Search also in all components of top level tags founds.
1963 See @dfn{semanticdb-find-translate-path} for details on @var{path}.
1964 @var{find-file-match} indicates that any time a match is found, the file
1965 associated with that tag should be loaded into a buffer.
1968 @node DB Basic Brute Search
1969 @subsection DB Basic Brute Search
1971 These searches allow searching on specific attributes of tags,
1972 such as name, type, or other attribute.
1974 @defun semanticdb-brute-deep-find-tags-by-name name &optional path find-file-match
1975 @anchor{semanticdb-brute-deep-find-tags-by-name}
1976 Search for all tags matching @var{name} on @var{path}.
1977 See @dfn{semanticdb-find-translate-path} for details on @var{path}.
1978 The argument @var{brutish} will be set so that searching includes all tables
1979 in the current project.
1980 @var{find-file-match} indicates that any time a matchi is found, the file
1981 associated wit that tag should be loaded into a buffer.
1984 @node DB Advanced Search
1985 @subsection DB Advanced Search
1987 These are searches that were needed to accomplish some
1988 specialized tasks as discovered in utilities. Advanced searches
1989 include matching methods defined outside some parent class.
1991 The reason for advanced searches are so that external
1992 repositories such as the Emacs obarray, or java @file{.class} files can
1993 quickly answer these needed questions without dumping the entire
1994 symbol list into Emacs for a regular semanticdb search.
1996 @defun semanticdb-find-tags-external-children-of-type type &optional path find-file-match
1997 @anchor{semanticdb-find-tags-external-children-of-type}
1998 Search for all tags defined outside of @var{type} w/ @var{type} as a parent.
1999 See @dfn{semanticdb-find-translate-path} for details on @var{path}.
2000 @var{find-file-match} indicates that any time a match is found, the file
2001 associated with that tag should be loaded into a buffer.
2004 @node DB Generic Brute Search
2005 @subsection DB Generic Brute Search
2007 The generic search, @dfn{semanticdb-find-nonterminal-by-function}
2008 will call your function with every tag available. (Very slow for
2011 NOTE: There is no such function. Hopefully we can get away without
2012 implementing one, which will make system databases more useful. If
2013 you are really stuck, you can use the following, though I don't
2016 @defun semanticdb-find-tags-collector function &optional path find-file-match brutish
2017 @anchor{semanticdb-find-tags-collector}
2018 Search for all tags returned by @var{function} over @var{path}.
2019 See @dfn{semanticdb-find-translate-path} for details on @var{path}.
2020 @var{find-file-match} indicates that any time a match is found, the file
2021 associated with that tag should be loaded into a buffer.
2022 If optional argument @var{brutish} is non-@code{nil}, then ignore include statements,
2023 and search all tables in this project tree.
2026 @node System Databases
2027 @section System Databases
2029 System Databases are special implementations of the database and
2030 table API which make some external tag source appear as though it
2031 were a normal buffer with semantic parsed tags available.
2033 Search routines for these databases return a special type of table
2034 not associated with a file. It is important to be aware of this
2035 possible return value.
2038 @deffn Type semanticdb-project-database-emacs-lisp
2039 @anchor{semanticdb-project-database-emacs-lisp}
2040 Database representing Emacs core.
2043 This Emacs database is loaded automatically.
2046 @deffn Type semanticdb-project-database-ebrowse
2047 @anchor{semanticdb-project-database-ebrowse}
2048 Semantic Database deriving tags using the @var{ebrowse} tool.
2049 @var{ebrowse} is a C/C++ parser for use with @code{ebrowse} Emacs program.
2052 To create new EBROWSE project databases, use:
2054 @deffn Command semanticdb-create-ebrowse-database dir
2055 @anchor{semanticdb-create-ebrowse-database}
2056 Create an @var{ebrose} database for directory @var{dir}.
2057 The database file is stored in ~/.semanticdb, or whichever directory
2058 is specified by @code{semanticdb-default-system-save-directory}.
2061 @subsection Semantic Parsed System Databases
2063 Another kind of system database is one created by the semantic tools,
2064 but saved in a special way. These databases are created with a
2065 script, or at some other convenient time. They can then be searched
2066 normally. They will appear on the same list of system databases as
2067 back ends that refer to object files indirectly.
2069 A simple way to create one from Emacs is with this function:
2071 @deffn Command semanticdb-create-system-database path &optional class
2072 @anchor{semanticdb-create-system-database}
2073 Create a system database starting at @var{path}.
2074 @var{path} should be a top level directory for a series of files containing
2075 declarations for @var{system} files. In @var{c}, this would be header filaes.
2076 @var{class} is the class for the database to create. Only child classes
2077 of symbol @dfn{semanticdb-project-database-system} are accepted.
2080 @node Idle Scheduling
2081 @chapter Idle Scheduling
2083 The Semantic Idle Scheduler is a minor mode which performs semantic
2084 specific tasks in idle time.
2085 See @inforef{Idle Scheduler, , semantic-user.info}.
2087 It performs the following tasks in order:
2091 Reprarse the current buffer if needed
2093 Reparse other buffers that need it
2095 Execute other scheduled semantic related operations.
2098 Care is take in the idle scheduler to exit immediatly if user input
2099 is detected, improving editing performance.
2101 The reason for grouping these tasks together is so that the automatic
2102 reparsing code executes before other idle services. This allows
2103 lexically broken buffers to be detected so that the other
2104 applications that follow do not accidentally reparse the buffer
2105 leaving unmatched syntax all over.
2107 You can create new minor modes that are automatically scheduled by
2108 the semantic idle scheduler. Create the new minor mode with:
2110 @defun define-semantic-idle-service name doc &rest forms
2111 @anchor{define-semantic-idle-service}
2112 Create a new idle services with @var{NAME}.
2113 @var{DOC} will be a documentation string describing @var{FORMS}.
2114 @var{FORMS} will be called during idle time after the current buffer's
2115 semantic tag information has been updated.
2116 This routines creates the following functions and variables:
2119 @section User Input Handling
2121 When writing an idle service, it is important for tasks that can take
2122 a long time to correctly exit upon user input.
2124 You can test for user input in your idle handler with the following
2127 @defun semantic-throw-on-input from
2128 @anchor{semantic-throw-on-input}
2129 Exit with @dfn{throw} when in @dfn{semantic-exit-on-input} on user input.
2130 @var{FROM} is an indication of where this function is called from as a value
2131 to pass to @dfn{throw}. It is recommended to use the name of the function
2135 If you need to carefully extract from your function, you can wrap
2136 just a section of your function to exit on user input by wrapping it
2139 @defun semantic-exit-on-input symbol &rest forms
2140 @anchor{semantic-exit-on-input}
2141 Using @var{SYMBOL} as an argument to @dfn{throw}, execute @var{FORMS}.
2142 If @var{FORMS} includes a call to @code{semantic-thow-on-input}, then
2143 if a user presses any key during execution, this form macro
2144 will exit with the value passed to @dfn{semantic-throw-on-input}.
2145 If @var{FORMS} completes, then the return value is the same as @dfn{progn}.
2148 Upon catching user input, you can try to detect if there was an exit
2149 from the return argument, and continue throwing with an additional
2150 call to @code{semantic-throw-on-input}.
2152 @node Example Programs
2153 @chapter Programming Examples
2155 *** NOTE *** These examples are for semantic 1.4.
2156 Using the below functions will generate compile time warnings with
2157 advice on what functions to use in semantic 2.0.
2160 Here are some simple examples that use different aspects of the
2161 semantic library APIs. For fully functional example programs with
2162 lots of comments, see the file @file{semantic-examples.el}.
2164 @heading Interactively querying for a token name
2166 If you need a command that asks the user for a token name, you can
2167 get full range completion using the query functions
2168 @ref{Tag Completion}.
2171 (interactive (list (semantic-read-symbol "Symbol: ")))
2174 @heading Finding a symbol in a buffer
2176 If you have the name of a function or variable, and need to find its
2177 location in a buffer, you need a search function. There is a wide
2178 range of searches you can perform @ref{Searching Tag Tables}.
2181 (semantic-find-nonterminal-by-name
2184 t ;; look inside structures and classes for these symbols
2185 nil) ;; do not look inside header files.
2188 @heading Finding a symbol in a project
2190 If you have the name of a function or variable, and need to find its
2191 location somewhere in a project, you need to use the Semantic Database
2192 @inforef{semanticdb, , semanticdb}. There are many search functions similar to the
2193 ones found in @ref{Searching Tag Tables}.
2195 The Semantic Database is interesting in that the return structure is
2198 @heading Locating a token in a buffer
2200 If you have a nonterminal token, or a list of them, you may want to
2201 find their position in a buffer.
2204 (semanticdb-find-nonterminal-by-name
2206 nil ;; Defaults to the current project's database list.
2207 t ;; Search inside types
2208 nil ;; Do not search include files
2209 nil ;; Only search files in the same mode (all C files)
2210 t ;; When a token is found, make sure it is loaded in a buffer.
2214 Of interesting note above, semanticdb can find symbols in files that
2215 are not loaded into an Emacs buffer. These tokens do not have an
2216 associated overlay, and the function @dfn{semantic-token-buffer} will
2219 The last parameter's tells the search function to
2220 @dfn{find-file-noselect} any file in which a matching token was
2221 found. This will allow you to merge all the tokens into a completion
2222 list, or other flat list needed by most functions that use
2225 If you do not ask semanticdb to load those files, you will need to
2226 explicitly request the database object (found in the @code{car} of
2227 each sublist) get the file loaded. It is useful to not auto find all
2228 files if you don't need to jump to that token.
2230 @heading Converting a token into a human readable string.
2232 A tag is a rather unpleasant Lisp structure when trying
2233 to decipher what is going on. As such, there is a wide range of
2234 functions available that can convert a token into a human readable,
2235 and colorful string @ref{Format Tag}.
2237 If you program interfaces with lots of users, you will probably want
2238 to have your program define a configurable variable that will let
2239 users change the visible portion of your program.
2242 (defcustom my-summary-function 'semantic-uml-prototype-nonterminal
2243 "*Function to use when showing info about my tag."
2245 :type semantic-format-tag-custom-list)
2248 Note the special type provided by Semantic.
2250 Next, you can call this function to create a string.
2253 (funcall my-summary-function tag
2259 In this case, @var{tag-parent} is an optional argument. In many
2260 cases, parent is not used by the outputting function. The parent must
2261 be a tag whose @code{semantic-tag-componenets} contains @var{tag}, or
2262 nil for top-level definitions. In particular, C++ needs the parent to
2263 correctly calculate the protection of each method.
2266 @node Current Context
2267 @chapter Deriving the Current Context
2269 This chapter deals with how to derive the current context, and also
2270 how a language maintainer can get the current context API to work
2271 with their language.
2273 By default, the behavior will function in C like languages. This
2274 means languages with parenthetical blocks, and type dereferencing
2275 which uses a similar form.
2279 * Local Variables:: Getting lists of local variables.
2280 * Derived Context:: What goes at a given location?
2281 * Context Analysis:: Analysis information about the local context.
2285 @section Blocks and Navigation
2287 Source code is typically built up of control structures, and blocks of
2288 context, or lexical scope. Semantic terms these lexical scopes as a
2289 ``context''. The following functions can be used to navigate contexts.
2290 Some of them are override functions. Language authors can override
2291 a subset of them to make them work for their language.
2293 @defun semantic-up-context &optional point bounds-type
2294 @anchor{semantic-up-context}
2295 Move point up one context from @var{point}.
2296 Return non-@code{nil} if there are no more context levels.
2297 Overloaded functions using @code{up-context} take no parameters.
2298 @var{bounds-type} is a symbol representing a tag class to restrict
2299 movement to. If this is @code{nil}, @code{'function} is used.
2300 This will find the smallest tag of that class (function, variable,
2301 type, etc) and make sure non-@code{nil} is returned if you cannot
2302 go up past the bounds of that tag.
2303 This function can be overloaded (see @dfn{define-mode-local-override} for details).
2306 @defun semantic-beginning-of-context &optional point
2307 @anchor{semantic-beginning-of-context}
2308 Move @var{point} to the beginning of the current context.
2309 Return non-@code{nil} if there is no upper context.
2310 The default behavior uses @dfn{semantic-up-context}.
2311 This function can be overloaded (see @dfn{define-mode-local-override} for details).
2314 @defun semantic-end-of-context &optional point
2315 @anchor{semantic-end-of-context}
2316 Move @var{point} to the end of the current context.
2317 Return non-@code{nil} if there is no upper context.
2318 Be default, this uses @dfn{semantic-up-context}, and assumes parenthetical
2320 This function can be overloaded (see @dfn{define-mode-local-override} for details).
2323 These next set of functions can be used to navigate across commands.
2325 @defun semantic-end-of-command
2326 @anchor{semantic-end-of-command}
2327 Move to the end of the current command.
2328 Be default, uses @code{semantic-command-separation-character}.
2329 This function can be overloaded (see @dfn{define-mode-local-override} for details).
2332 @defun semantic-beginning-of-command
2333 @anchor{semantic-beginning-of-command}
2334 Move to the beginning of the current command.
2335 Be default, uses @code{semantic-command-separation-character}.
2336 This function can be overloaded (see @dfn{define-mode-local-override} for details).
2339 @node Local Variables
2340 @section Deriving local variables
2342 Within a given context, or block of code, local variables are often
2343 defined. These functions can be used to retrieve lists of locally
2346 @defun semantic-get-local-variables &optional point
2347 @anchor{semantic-get-local-variables}
2348 Get the local variables based on POINT's context.
2349 Local variables are returned in Semantic tag format.
2350 This can be overriden with @code{get-local-variables}.
2351 This function can be overloaded (see @dfn{define-mode-local-override} for details).
2354 @defun semantic-get-local-arguments &optional point
2355 @anchor{semantic-get-local-arguments}
2356 Get arguments (variables) from the current context at @var{point}.
2357 Parameters are available if the point is in a function or method.
2358 Return a list of tags unlinked from the originating buffer.
2359 Arguments are obtained by overriding @code{get-local-arguments}, or by the
2360 default function @dfn{semantic-get-local-arguments-default}. This, must
2361 return a list of tags, or a list of strings that will be converted to
2363 This function can be overloaded (see @dfn{define-mode-local-override} for details).
2366 @defun semantic-get-all-local-variables &optional point
2367 @anchor{semantic-get-all-local-variables}
2368 Get all local variables for this context, and parent contexts.
2369 Local variables are returned in Semantic tag format.
2370 Be default, this gets local variables, and local arguments.
2371 Optional argument @var{point} is the location to start getting the variables from.
2372 This function can be overloaded (see @dfn{define-mode-local-override} for details).
2375 @node Derived Context
2376 @section Deriving the Current Context
2378 While a context has already been used to describe blocks of code,
2379 other context include more local details, such as the symbol the
2380 cursor is on, or the fact we are assigning into some other variable.
2382 These context deriving functions can be overridden to provide language
2383 specific behavior. By default, it assumes a C like language.
2385 @defun semantic-ctxt-current-symbol &optional point
2386 @anchor{semantic-ctxt-current-symbol}
2387 Return the current symbol the cursor is on at @var{point} in a list.
2388 This will include a list of type/field names when applicable.
2389 This function can be overloaded (see @dfn{define-mode-local-override} for details).
2392 @defun semantic-ctxt-current-assignment &optional point
2393 @anchor{semantic-ctxt-current-assignment}
2394 Return the current assignment near the cursor at @var{point}.
2395 Return a list as per @dfn{semantic-ctxt-current-symbol}.
2396 Return @code{nil} if there is nothing relevant.
2397 This function can be overloaded (see @dfn{define-mode-local-override} for details).
2400 @defun semantic-ctxt-current-function &optional point
2401 @anchor{semantic-ctxt-current-function}
2402 Return the current function call the cursor is in at @var{point}.
2403 The function returned is the one accepting the arguments that
2404 the cursor is currently in. It will not return function symbol if the
2405 cursor is on the text representing that function.
2406 This function can be overloaded (see @dfn{define-mode-local-override} for details).
2409 @defun semantic-ctxt-current-argument &optional point
2410 @anchor{semantic-ctxt-current-argument}
2411 Return the index of the argument position the cursor is on at @var{point}.
2412 This function can be overloaded (see @dfn{define-mode-local-override} for details).
2415 @defun semantic-ctxt-current-thing
2416 @anchor{semantic-ctxt-current-thing}
2417 Calculate a thing identified by the current cursor position.
2418 Calls previously defined @code{semantic-ctxt-current-@dots{}} calls until something
2419 gets a match. See @dfn{semantic-ctxt-current-symbol},
2420 @dfn{semantic-ctxt-current-function}, and @dfn{semantic-ctxt-current-assignment}
2421 for details on the return value.
2424 @defun semantic-ctxt-current-class-list &optional point
2425 @anchor{semantic-ctxt-current-class-list}
2426 Return a list of tag classes that are allowed at @var{point}.
2427 If @var{point} is @code{nil}, the current buffer location is used.
2428 For example, in Emacs Lisp, the symbol after a ( is most likely
2429 a function. In a makefile, symbols after a : are rules, and symbols
2430 after a $( are variables.
2431 This function can be overloaded (see @dfn{define-mode-local-override} for details).
2434 @defun semantic-ctxt-scoped-types &optional point
2435 @anchor{semantic-ctxt-scoped-types}
2436 Return a list of type names currently in scope at @var{point}.
2437 The return value can be a mixed list of either strings (names of
2438 types that are in scope) or actual tags (type declared locally
2439 that may or may not have a name.)
2440 This function can be overloaded (see @dfn{define-mode-local-override} for details).
2443 @node Context Analysis
2444 @section Analysis of the current context
2446 The context parsing API is used in a context analysis library. This
2447 library provides high level routines for scanning through token
2448 databases to create lists of token associates. At it's core is a set
2449 of EIEIO classes defining a context. The context contains information
2450 about what was parsed at a given position, such as the strings there,
2451 and they type of assignment. The analysis library then searches the
2452 databases to determine the types and names available.
2454 Two high level functions which can be run interactively are:
2456 @deffn Command semantic-analyze-current-context &optional position
2457 @anchor{semantic-analyze-current-context}
2458 Analyze the current context at optional @var{position}.
2459 If called interactively, display interesting information about @var{position}
2460 in a separate buffer.
2461 Returns an object based on symbol @dfn{semantic-analyze-context}.
2463 This function can be overriden with the symbol @code{analyze-context}.
2464 When overriding this function, your override will be called while
2465 cursor is at @var{position}. In addition, your function will not be called
2466 if a cached copy of the return object is found.
2467 This function can be overloaded (see @dfn{define-mode-local-override} for details).
2471 @deffn Command semantic-analyze-possible-completions context
2472 @anchor{semantic-analyze-possible-completions}
2473 Return a list of semantic tags which are possible completions.
2474 @var{context} is either a position (such as point), or a precalculated
2475 context. Passing in a context is useful if the caller also needs
2476 to access parts of the analysis.
2477 Completions run through the following filters:
2481 Elements currently in scope
2483 Constants currently in scope
2485 Elements match the @code{:prefix} in the @var{context}.
2487 Type of the completion matches the type of the context.
2490 Context type matching can identify the following:
2496 Assignment into a variable of some type.
2498 Argument to a function with type constraints.
2501 When called interactively, displays the list of possible completions
2503 This function can be overloaded (see @dfn{define-mode-local-override} for details).
2507 * Analysis Overview:: A description of how the analyzer works.
2508 * Analysis Objects:: What is in the analysis object.
2509 * Completion Overview:: How completions are calculated.
2512 @node Analysis Overview
2513 @subsection Analysis Overview
2515 The semantic analysis function @dfn{semantic-analye-current-context}
2516 creates an Analysis Object. See @ref{Analysis Objects}. This object
2517 contains many useful pieces of information needed to do any other
2518 kind of intelligent action on the local context.
2520 If you call this function interactively, it will popup a buffer with
2521 a summary of the return value. This is useful when debugging.
2524 +--------+ +----------------+ +----------------------------+
2525 | Buffer |---| Context Parser |---| Local Context Synax Result |
2526 +--------+ +----------------+ +----------------------------+
2528 +--------+ +-----------+ |
2529 | Parser |---| Tag Table |------------+ |
2530 +--------+ +-----------+ | |
2532 +-------------+ +-------------------+
2533 | Semantic DB |-------------------->| Semantic Analyzer |
2534 +-------------+ +-------------------+
2542 @node Analysis Objects
2543 @subsection Analysis Objects
2547 @c First, delete text between this comment and END OF ANALYZE OBJECT text.
2549 @c Execute the below line with C-x C-e
2552 @c (progn (require 'semantic-analyze) (eieiodoc-class semantic-analyze-context "analyze"))
2555 @c END OF ANALZE OBJECT SECTION
2557 @node Completion Overview
2558 @subsection Completion Overview
2562 @chapter Application level Data structure debugger
2564 The data structures that Semantic provides can be complex, and
2565 figuring out why some level of application API performs incorrectly
2568 The semantic Application debugger provides a way to look inside the
2569 various data structures of Semantic in a structures and complete way
2570 to help identify what a problem may be.
2572 @section App Debugger Entry Points
2574 There are a few basic functions that enter into the debugger:
2576 @deffn Command semantic-adebug-bovinate
2577 @anchor{semantic-adebug-bovinate}
2578 The same as @dfn{bovinate}. Display the results in a debug buffer.
2581 @deffn Command semantic-adebug-searchdb regex
2582 @anchor{semantic-adebug-searchdb}
2583 Search the semanticdb for @var{regex} for the current buffer.
2584 Display the results as a debug list.
2587 @deffn Command semantic-adebug-analyze
2588 @anchor{semantic-adebug-analyze}
2589 Perform @dfn{semantic-analyze-current-context}.
2590 Display the results as a debug list.
2593 @section adebug-mode
2595 The semantic debugger mode provides a simple user facing UI for
2596 looking into the data structures.
2598 @deffn Command semantic-adebug-mode
2599 @anchor{semantic-adebug-mode}
2600 Major-mode for the Analyzer debugger.
2605 semantic-adebug-expand-or-contract
2607 semantic-adebug-next-expando
2609 semantic-adebug-prev-expando
2611 semantic-adebug-next
2613 semantic-adebug-prev
2615 semantic-adebug-expand-or-contract-mouse
2620 @section Create new debugger entry commands
2622 Creating a new Application debugger entry point is easy.
2623 First, get a datastructure you need to analyze.
2625 The first function to call is:
2627 @defun semantic-adebug-new-buffer name
2628 @anchor{semantic-adebug-new-buffer}
2629 Create a new adebug buffer with @var{name}.
2632 Next, you need to find the correct function for inserting your
2633 datastructure. All adebug insertion functions are of the form
2634 @code{semantic-adebug-insert-THING}, where @var{thing} is whatever you
2635 object is. Use Emacs help to pick something out.
2638 @node GNU Free Documentation License
2639 @appendix GNU Free Documentation License
2654 @c Following comments are for the benefit of ispell.