6 The end result of a @semantic{} parser is a list of tags per each buffer.
7 This chapter discusses the tag data structure and the API provided
8 by @semantic{} to query, process, and modify tags.
10 The tags list for a buffer can be obtained by calling
11 @code{semantic-fetch-tags} which returns
12 a parse tree of tags that represent the program structure.
17 Tags are not sorted. Maybe would it be clearer to say that
18 `semantic-fetch-tags returns a parse tree of tags that
19 represent the program structure.
21 From a grammar's developer point of view it could be worth
22 highlighting that the parse tree of tags should be consistent with
25 For example, for the following definition:
29 The parse tree should look like:
36 A bad parse tree is for example:
40 ("y" "x")) <--- Arguments are in the reverse order
49 * Misc Tag Functions::
53 @node Tag Basics, Tag Query, Semantic Tags, Semantic Tags
57 Currently each tag is a list with up to five elements:
59 (@var{name} @var{class} @var{attributes} @var{properties} @var{overlay})
62 Application developers should not rely on this list structure.
63 Instead they should rely on the provided API documented in this chapter.
64 The list structure is explained here primarily to help those reading
65 the @semantic{} source code.
70 @var{name} is a required component for all tags, i.e., every tag
71 must have this component. It is also guaranteed to be a string. This
72 string represents the name of the tag, usually a named definition
73 which the language will use elsewhere as a reference to the syntactic
77 @var{class} is the other required component for all tags.
78 It is a symbol representing the class of the tag.
81 I think it would be better to say the category or class of tag
82 [rather than ``type'']. Type of tag could be confusing. The notion
83 of tag type represents program data type (see the function
86 Valid @var{class}es can be anything, as long is it is an Emacs Lisp
87 symbol. However following are some of the well-known symbols:
88 @code{type}, @code{function}, @code{variable}, @code{include},
89 @code{package}, @code{code}.
92 @var{attributes} is a property list that keep information related
93 to the tag parsed from the buffer.
95 The symbol names in the property list can be anything, though there is
96 a useful set of predefined attributes. It is best to use the API
97 functions to access the well-known properties. @ref{Tag Query}.
101 It could be worth enumerating the commonly used attribute names:
113 We could recommend to use the above names when that makes sense, and
114 more generally to use the Emacs keyword notation (symbol starting with
115 ':') for attribute names.
119 @var{properties} is generated by the semantic parser harness,
120 and need not be provided by a language author.
122 Properties are used to store transient data on a tag unrelated to the
123 source of the original tag, such as hook functions, dynamic overlays,
124 or other data needed by programs.
126 The semantic incremental parser will attempt to maintain properties
127 when reparsing the source of a tag.
130 @var{overlay} represents positional information for this tag. It is
131 automatically generated by the semantic parser harness, and need
132 not be provided by the language author.
133 @c Below is from old semantic manual: unless they provide a
134 @c nonterminal expansion function via
135 @c @code{semantic-tag-expand-function}.
136 Depending on the overlay in a program can be dangerous because
137 sometimes the overlay is replaced with an integer pair
139 [ @var{start} @var{end} ]
141 when the buffer the tag belongs to is not in memory. This happens
142 when a using has activated the Semantic Database
143 @inforef{semanticdb, , lang-support-guide}.
147 @defun semantic-tag-name tag
148 @anchor{semantic-tag-name}
149 Return the name of @var{tag}.
150 For functions, variables, classes, typedefs, etc., this is the identifier
151 that is being defined. For tags without an obvious associated name, this
152 may be the statement type, e.g., this may return @code{print} for python's
154 @obsolete{semantic-token-name,semantic-tag-name}
157 @defun semantic-tag-class tag
158 @anchor{semantic-tag-class}
159 Return the class of @var{tag}.
160 That is, the symbol @code{'variable}, @code{'function}, @code{'type}, or other.
161 There is no limit to the symbols that may represent the class of a tag.
162 Each parser generates tags with classes defined by it.
164 For functional languages, typical tag classes are:
168 Data types, named map for a memory block.
170 A function or method, or named execution location.
172 A variable, or named storage for data.
174 Statement that represents a file from which more tags can be found.
176 Statement that declairs this file's package name.
178 Code that has not name or binding to any other symbol, such as in a script.
181 @obsolete{semantic-token-token,semantic-tag-class}
184 Several functions that deal with @var{attributes} component are given
185 in @ref{Tag Attributes Internals,Tag Attributes Internals}.
186 However functions listed in @ref{Tag Query,Tag Query}
187 should provide most needs of the application developer.
189 Similarly functions that deal with @var{properties} component are given
190 in @ref{Tag Properties Internals,Tag Properties Internals}.
191 The application developer should not need to use any of these.
193 Finally @ref{Tag Overlay,Tag Overlay} lists functions dealing with
194 the @var{overlay} component.
196 @node Tag Query, Tag Overlay, Tag Basics, Semantic Tags
200 This section lists functions that answers simple questions
201 regarding a given tag.
203 @subsection Tag Predicates
205 @defun semantic-tag-p tag
206 @anchor{semantic-tag-p}
207 Return non-@code{nil} if @var{tag} is most likely a semantic tag.
208 @obsolete{semantic-token-p,semantic-tag-p}
211 @defun semantic-equivalent-tag-p tag1 tag2
212 @anchor{semantic-equivalent-tag-p}
213 Compare @var{tag1} and @var{tag2} and return non-@code{nil} if they are equivalent.
214 Use @dfn{eq} to test of two tags are the same. Use this function if tags
215 are being copied and regrouped to test for if two tags represent the
216 same thing, but may be constructed of different cons cells.
217 @obsolete{semantic-equivalent-tokens-p,semantic-equivalent-tag-p}
220 @defun semantic-tag-of-class-p tag class
221 @anchor{semantic-tag-of-class-p}
222 Return non-@code{nil} if class of @var{tag} is @var{class}.
225 @defun semantic-tag-faux-p tag
226 @anchor{semantic-tag-faux-p}
227 Return non-@code{nil} if @var{tag} is a @var{faux} tag.
228 @var{faux} tags are created to represent a construct that is
229 not known to exist in the code.
232 @defun semantic-tag-type-compound-p tag
233 @anchor{semantic-tag-type-compound-p}
234 Return non-@code{nil} the type of @var{tag} is compound.
235 Compound implies a structure or similar data type.
236 Returns the list of tag members if it is compound.
239 @subsection Documentation
241 @defun semantic-tag-docstring tag &optional buffer
242 @anchor{semantic-tag-docstring}
243 Return the documentation of @var{tag}.
244 That is the value defined by the `:documentation' attribute.
245 Optional argument @var{buffer} indicates where to get the text from.
246 If not provided, then only the @var{position} can be provided.
247 @obsolete{semantic-token-docstring,semantic-tag-docstring}
250 @subsection Common Flags
252 @defun semantic-tag-variable-constant-p tag
253 @anchor{semantic-tag-variable-constant-p}
254 Return non-@code{nil} if the variable that @var{tag} describes is a constant.
255 That is the value of the attribute `:constant-flag'.
256 @obsolete{semantic-token-variable-const,semantic-tag-variable-constant-p}
259 @defun semantic-tag-function-destructor-p tag
260 @anchor{semantic-tag-function-destructor-p}
261 Return non-@code{nil} if @var{tag} describes a destructor function.
262 That is the value of the `:destructor-flag' attribute.
263 @obsolete{semantic-token-function-destructor,semantic-tag-function-destructor-p}
266 @defun semantic-tag-function-throws tag
267 @anchor{semantic-tag-function-throws}
268 Return the exceptions the function that @var{tag} describes can throw.
269 That is the value of the `:throws' attribute.
270 @obsolete{semantic-token-function-throws,semantic-tag-function-throws}
273 @defun semantic-tag-modifiers tag
274 @anchor{semantic-tag-modifiers}
275 Return the value of the `:typemodifiers' attribute of @var{tag}.
276 @obsolete{semantic-token-type-modifiers,semantic-tag-modifiers}
277 @obsolete{semantic-token-variable-modifiers,semantic-tag-modifiers}
278 @obsolete{semantic-token-function-modifiers,semantic-tag-modifiers}
281 @subsection Functions
283 @defun semantic-tag-function-arguments tag
284 @anchor{semantic-tag-function-arguments}
285 Return the arguments of the function that @var{tag} describes.
286 That is the value of the `:arguments' attribute.
287 @obsolete{semantic-token-function-args,semantic-tag-function-arguments}
290 @subsection Variables
292 @defun semantic-tag-variable-default tag
293 @anchor{semantic-tag-variable-default}
294 Return the default value of the variable that @var{tag} describes.
295 That is the value of the attribute `:default-value'.
296 @obsolete{semantic-token-variable-default,semantic-tag-variable-default}
299 @subsection Data Types
301 @defun semantic-tag-type tag
302 @anchor{semantic-tag-type}
303 Return the value of the `:type' attribute of @var{tag}.
304 @obsolete{semantic-token-type,semantic-tag-type}
307 @defun semantic-tag-of-type-p tag type
308 @anchor{semantic-tag-of-type-p}
309 Compare TAG's type against @var{type}. Non @code{nil} if equivalent.
310 @var{type} can be a string, or a tag of class @code{'type}.
313 @subsection Inheritance and Hierarchy
315 @defun semantic-tag-named-parent tag
316 @anchor{semantic-tag-named-parent}
317 Return the parent of @var{tag}.
318 That is the value of the `:parent' attribute.
319 If a definition can occur outside an actual parent structure, but
320 refers to that parent by name, then the @code{:parent} attribute should be used.
323 @defun semantic-tag-function-parent tag
324 @anchor{semantic-tag-function-parent}
325 Return the parent of the function that @var{tag} describes.
326 That is the value of the `:parent' attribute.
327 A function has a parent if it is a method of a class, and if the
328 function does not appear in body of it's parent class.
329 @obsolete{semantic-token-function-parent,semantic-tag-function-parent}
332 @defun semantic-tag-type-superclasses tag
333 @anchor{semantic-tag-type-superclasses}
334 Return the list of superclasses of the type that @var{tag} describes.
335 @obsolete{semantic-token-type-parent-superclass,semantic-tag-type-superclasses}
336 @obsolete{semantic-token-type-parent,semantic-tag-type-superclasses}
339 @defun semantic-tag-type-interfaces tag
340 @anchor{semantic-tag-type-interfaces}
341 Return the list of interfaces of the type that @var{tag} describes.
342 @obsolete{semantic-token-type-parent-implement,semantic-tag-type-interfaces}
343 @obsolete{semantic-token-type-parent,semantic-tag-type-interfaces}
346 @defun semantic-tag-type-members tag
347 @anchor{semantic-tag-type-members}
348 Return the members of the type that @var{tag} describes.
349 That is the value of the `:members' attribute.
350 @obsolete{semantic-token-type-parts,semantic-tag-type-members}
355 @defun semantic-tag-include-system-p tag
356 @anchor{semantic-tag-include-system-p}
357 Return non-@code{nil} if the include that @var{tag} describes is a system include.
358 That is the value of the attribute `:system-flag'.
359 @obsolete{semantic-token-include-system,semantic-tag-include-system-p}
362 @defun semantic-tag-include-filename tag
363 @anchor{semantic-tag-include-filename}
364 Return a filename representation of @var{tag}.
365 The default action is to return the @dfn{semantic-tag-name}.
366 Some languages do not use full filenames in their include statements.
367 Override this method to translate the code represenation
368 into a filename. (A relative filename if necessary.)
370 See @dfn{semantic-dependency-tag-file} to expand an include
371 tag to a full file name.
372 This function can be overloaded (see @dfn{define-mode-local-override} for details).
377 @defun semantic-tag-code-detail tag
378 @anchor{semantic-tag-code-detail}
379 Return detail information from code that @var{tag} describes.
380 That is the value of the attribute `:detail'.
383 @subsection Tag Children
385 @defun semantic-tag-components tag
386 @anchor{semantic-tag-components}
387 Return a list of components for @var{tag}.
388 A Component is a part of @var{tag} which itself may be a @var{tag}.
389 Examples include the elements of a structure in a
390 tag of class `type, or the list of arguments to a
391 tag of class @code{'function}.
392 This function can be overloaded (see @dfn{define-mode-local-override} for details).
395 @defun semantic-tag-components-default tag
396 @anchor{semantic-tag-components-default}
397 Return a list of components for @var{tag}.
398 Perform the described task in @dfn{semantic-tag-components}.
401 @defun semantic-tag-children-compatibility tag &optional positiononly
402 @anchor{semantic-tag-children-compatibility}
403 Return children of @var{tag}.
404 If @var{positiononly} is @code{nil}, use @dfn{semantic-tag-components}.
405 If @var{positiononly} is non-@code{nil}, use @dfn{semantic-tag-components-with-overlays}.
406 @var{do} @var{not} use this fcn in new code. Use one of the above instead.
407 @obsolete{semantic-nonterminal-children,semantic-tag-children-compatibility}
412 @node Tag Overlay, Tag Hooks, Tag Query, Semantic Tags
416 The functions in this answer questions regarding the overly such as
417 the buffer in which the tags is located, the start and/or end position
418 of the tag, and the overlay itself which spans the tags.
420 @defun semantic-tag-start tag
421 @anchor{semantic-tag-start}
422 Return the start location of @var{tag}.
423 @obsolete{semantic-token-start,semantic-tag-start}
426 @defun semantic-tag-end tag
427 @anchor{semantic-tag-end}
428 Return the end location of @var{tag}.
429 @obsolete{semantic-token-end,semantic-tag-end}
432 @defun semantic-tag-bounds tag
433 @anchor{semantic-tag-bounds}
434 Return the location (@var{start} @var{end}) of data @var{tag} describes.
435 @obsolete{semantic-token-extent,semantic-tag-bounds}
438 @defun semantic-tag-buffer tag
439 @anchor{semantic-tag-buffer}
440 Return the buffer @var{tag} resides in.
441 If @var{tag} has an originating file, read that file into a (maybe new)
442 buffer, and return it.
443 Return @code{nil} if there is no buffer for this tag.
444 @obsolete{semantic-token-buffer,semantic-tag-buffer}
447 @defun semantic-tag-file-name tag
448 @anchor{semantic-tag-file-name}
449 Return the name of the file from which @var{tag} originated.
450 Return @code{nil} if that information can't be obtained.
451 If @var{tag} is from a loaded buffer, then that buffer's filename is used.
452 If @var{tag} is unlinked, but has a @code{:filename} property, then that is used.
455 @defun semantic-tag-overlay tag
456 @anchor{semantic-tag-overlay}
457 Return the @var{overlay} part of @var{tag}.
458 That is, an overlay or an unloaded buffer representation.
459 This function can also return an array of the form [ @var{start} @var{end} ].
460 This occurs for tags that are not currently linked into a buffer.
461 @obsolete{semantic-token-overlay,semantic-tag-overlay}
464 @defun semantic-tag-with-position-p tag
465 @anchor{semantic-tag-with-position-p}
466 Return non-@code{nil} if @var{tag} has positional information.
467 @obsolete{semantic-token-with-position-p,semantic-tag-with-position-p}
470 @defun semantic-tag-components-with-overlays tag
471 @anchor{semantic-tag-components-with-overlays}
472 Return the list of top level components belonging to @var{tag}.
473 Children are any sub-tags which contain overlays.
475 Default behavior is to get @dfn{semantic-tag-components} in addition
476 to the components of an anonymous types (if applicable.)
479 @item Language authors, please note:
480 If a mode defines a language tag that has tags in it with overlays
481 you should still return them with this function.
482 Ignoring this step will prevent several features from working correctly.
483 This function can be overloaded (see @dfn{define-mode-local-override} for details).
487 @defun semantic-tag-components-with-overlays-default tag
488 @anchor{semantic-tag-components-with-overlays-default}
489 Return the list of top level components belonging to @var{tag}.
490 Children are any sub-tags which contain overlays.
491 The default action collects regular components of @var{tag}, in addition
492 to any components beloning to an anonymous type.
495 @node Tag Hooks, Misc Tag Functions, Tag Overlay, Semantic Tags
499 Individual tags can have hooks associated with them. Hooks are saved
500 as properties, but can cause specific tags to have special behaviors
501 after a hook is added.
503 You can manipulate tag hooks with these functions:
505 @defun semantic-tag-add-hook tag hook function &optional append
506 @anchor{semantic-tag-add-hook}
507 Onto @var{tag}, add to the value of @var{hook} the function @var{function}.
508 @var{function} is added (if necessary) at the beginning of the hook list
509 unless the optional argument @var{append} is non-@code{nil}, in which case
510 @var{function} is added at the end.
511 @var{hook} should be a symbol, and @var{function} may be any valid function.
512 See also the function @dfn{add-hook}.
515 @defun semantic-tag-remove-hook tag hook function
516 @anchor{semantic-tag-remove-hook}
517 Onto @var{tag}, remove from the value of @var{hook} the function @var{function}.
518 @var{hook} should be a symbol, and @var{function} may be any valid function. If
519 @var{function} isn't the value of @var{hook}, or, if @var{function} doesn't appear in
520 the list of hooks to run in @var{hook}, then nothing is done.
521 See also the function @dfn{remove-hook}.
524 For a developer, if you have an application for which you want to
525 support a special kind of hook on a per tag basis, you can use this
528 @defun semantic--tag-run-hooks tag hook &rest args
529 @anchor{semantic--tag-run-hooks}
530 Run for @var{tag} all expressions saved on the property @var{hook}.
531 Each hook expression must take at least one argument, the @var{tag}.
532 For any given situation, additional @var{args} may be passed.
535 Semantic supports two TAG specific hooks at this time:
539 This hook is run whenever a tag is linked into a buffer. This occurs
540 just after parsing, and whenever a tag is loaded into memory. This
541 hook also executes after a datase save, when all tags are first
542 unlinked from the current buffer before the save.
544 This hook is run whenever a tag is unlinked from a buffer. This
545 ocucrs during a database save, or when a tag is modified by the
547 @item unlink-copy-hook
548 This hook is run whenever a tag is copied. This occurs in the
549 function @code{semantic-tag-copy}. Use this hook to remove properties
550 from the tag that link it to a buffer, as this tag should no longer
551 have direct buffer links.
554 @node Misc Tag Functions, Tag Internals, Tag Hooks, Semantic Tags
555 @section Misc Tag Functions
556 @cindex Misc Tag Functions
558 @deffn Command semantic-narrow-to-tag &optional tag
559 @anchor{semantic-narrow-to-tag}
560 Narrow to the region specified by the bounds of @var{tag}.
561 See @dfn{semantic-tag-bounds}.
562 @obsolete{semantic-narrow-to-token,semantic-narrow-to-tag}
565 @defun semantic-with-buffer-narrowed-to-current-tag &rest body
566 @anchor{semantic-with-buffer-narrowed-to-current-tag}
567 Execute @var{body} with the buffer narrowed to the current tag.
568 @obsolete{semantic-with-buffer-narrowed-to-current-token,semantic-with-buffer-narrowed-to-current-tag}
571 @defun semantic-with-buffer-narrowed-to-tag tag &rest body
572 @anchor{semantic-with-buffer-narrowed-to-tag}
573 Narrow to @var{tag}, and execute @var{body}.
574 @obsolete{semantic-with-buffer-narrowed-to-token,semantic-with-buffer-narrowed-to-tag}
577 @node Tag Internals, , Misc Tag Functions, Semantic Tags
578 @section Tag Internals
579 @cindex Tag Internals
582 * Tag Attributes Internals::
583 * Tag Properties Internals::
584 * Tag Overlay Internals::
586 * Misc Tag Internals::
589 @node Tag Attributes Internals, Tag Properties Internals, Tag Internals, Tag Internals
590 @subsection Tag Attributes Internals
593 Attribute Accessor Method | Property Symbol
594 ----------------------------------------------------
595 semantic-tag-variable-constant-p | :constant-flag
596 semantic-tag-function-destructor-p | :destructor-flag
597 semantic-tag-function-parent | :parent
598 semantic-tag-function-throws | :throws
599 semantic-tag-modifiers | :typemodifiers
600 semantic-tag-function-arguments | :arguments
601 semantic-tag-variable-default | :default-value
602 semantic-tag-docstring | :documentation
603 semantic-tag-type-interfaces | :interfaces
604 semantic-tag-type-members | :members
605 semantic-tag-type-superclasses | :superclasses
606 semantic-tag-include-system-p | :system-flag
607 semantic-tag-type | :type
610 @defun semantic-tag-attributes tag
611 @anchor{semantic-tag-attributes}
612 Return the list of public attributes of @var{tag}.
613 That is a property list: (@var{attribute-1} @var{value-1} @var{attribute-2} @var{value-2}@dots{}).
614 @obsolete{semantic-token-extra-specs,semantic-tag-attributes}
615 @obsolete{semantic-token-function-extra-specs,semantic-tag-attributes}
616 @obsolete{semantic-token-variable-extra-specs,semantic-tag-attributes}
617 @obsolete{semantic-token-type-extra-specs,semantic-tag-attributes}
620 @defun semantic-tag-get-attribute tag attribute
621 @anchor{semantic-tag-get-attribute}
622 From @var{tag}, return the value of @var{attribute}.
623 @var{attribute} is a symbol whose specification value to get.
624 Return the value found, or @code{nil} if @var{attribute} is not one of the
625 attributes of @var{tag}.
626 @obsolete{semantic-token-extra-spec,semantic-tag-get-attribute}
627 @obsolete{semantic-token-function-extra-spec,semantic-tag-get-attribute}
628 @obsolete{semantic-token-variable-extra-spec,semantic-tag-get-attribute}
631 @defun semantic-tag-put-attribute tag attribute value
632 @anchor{semantic-tag-put-attribute}
633 Change value in @var{tag} of @var{attribute} to @var{value}.
634 If @var{attribute} already exists, its value is set to @var{value}, otherwise the
635 new @var{attribute} @var{value} pair is added.
637 Use this function in a parser when not all attributes are known at the
639 @obsolete{semantic-token-add-extra-spec,semantic-tag-put-attribute}
642 @defun semantic-tag-put-attribute-no-side-effect tag attribute value
643 @anchor{semantic-tag-put-attribute-no-side-effect}
644 Change value in @var{tag} of @var{attribute} to @var{value} without side effects.
645 All cons cells in the attribute list are replicated so that there
646 are no side effects if @var{tag} is in shared lists.
647 If @var{attribute} already exists, its value is set to @var{value}, otherwise the
648 new @var{attribute} @var{value} pair is added.
652 @node Tag Properties Internals, Tag Overlay Internals, Tag Attributes Internals, Tag Internals
653 @subsection Tag Properties Internals
661 Related functions not yet documented:
662 semantic-brute-find-tag-by-property
663 semantic-tag-add-hook
664 semantic-tag-remove-hook
668 @defun semantic-tag-properties tag
669 @anchor{semantic-tag-properties}
670 Return the list of private properties of @var{tag}.
671 That is a property list: (@var{property-1} @var{value-1} @var{property-2} @var{value-2}@dots{}).
672 @obsolete{semantic-token-properties,semantic-tag-properties}
675 @defun semantic--tag-put-property tag property value
676 @anchor{semantic--tag-put-property}
677 Change value in @var{tag} of @var{property} to @var{value}.
678 If @var{property} already exists, its value is set to @var{value}, otherwise the
679 new @var{property} @var{value} pair is added.
681 That function is for internal use only.
682 @obsolete{semantic-token-put,semantic--tag-put-property}
685 @defun semantic--tag-get-property tag property
686 @anchor{semantic--tag-get-property}
687 From @var{tag}, extract the value of @var{property}.
688 Return the value found, or @code{nil} if @var{property} is not one of the
689 properties of @var{tag}.
690 That function is for internal use only.
691 @obsolete{semantic-token-get,semantic--tag-get-property}
694 @defun semantic--tag-put-property-no-side-effect tag property value
695 @anchor{semantic--tag-put-property-no-side-effect}
696 Change value in @var{tag} of @var{property} to @var{value} without side effects.
697 All cons cells in the property list are replicated so that there
698 are no side effects if @var{tag} is in shared lists.
699 If @var{property} already exists, its value is set to @var{value}, otherwise the
700 new @var{property} @var{value} pair is added.
702 That function is for internal use only.
703 @obsolete{semantic-token-put-no-side-effect,semantic--tag-put-property-no-side-effect}
706 @defun semantic-tag-make-plist args
707 @anchor{semantic-tag-make-plist}
708 Create a property list with @var{args}.
709 Args is a property list of the form (@var{key1} @var{value1} @dots{} @var{keyn} @var{valuen}).
710 Where @var{key} is a symbol, and @var{value} is the value for that symbol.
711 The return value will be a new property list, with these @var{key}/@var{value}
714 - @var{key} associated to @code{nil} @var{value}.
715 - @var{key} associated to an empty string @var{value}.
716 - @var{key} associated to a zero @var{value}.
717 @obsolete{semantic-tag-make-assoc-list,semantic-tag-make-plist}
720 @node Tag Overlay Internals, Creating Tags, Tag Properties Internals, Tag Internals
721 @subsection Tag Overlay Internals
723 Many of the overlay related functions were already documented in
724 @ref{Tag Overlay,Tag Overlay}.
727 Functions not yet documented:
728 semantic--tag-overlay-cdr
729 semantic--tag-set-overlay
732 @defun semantic-tag-set-bounds tag start end
733 @anchor{semantic-tag-set-bounds}
734 In @var{tag}, set the @var{start} and @var{end} location of data it describes.
737 @node Creating Tags, Misc Tag Internals, Tag Overlay Internals, Tag Internals
738 @subsection Creating Tags
740 @defun semantic-tag name class &rest attributes
741 @anchor{semantic-tag}
742 Create a generic semantic tag.
743 @var{name} is a string representing the name of this tag.
744 @var{class} is the symbol that represents the class of tag this is,
745 such as @code{'variable}, or @code{'function}.
746 @var{attributes} is a list of additional attributes belonging to this tag.
747 @obsolete{semantic-token,semantic-tag}
750 @defun semantic-tag-new-variable name type default-value &rest attributes
751 @anchor{semantic-tag-new-variable}
752 Create a semantic tag of class @code{'variable}.
753 @var{name} is the name of this variable.
754 @var{type} is a string or semantic tag representing the type of this variable.
755 @var{default-value} is a string representing the default value of this variable.
756 @var{attributes} is a list of additional attributes belonging to this tag.
757 @obsolete{semantic-token-new-variable,semantic-tag-new-variable}
760 @defun semantic-tag-new-function name type arg-list &rest attributes
761 @anchor{semantic-tag-new-function}
762 Create a semantic tag of class @code{'function}.
763 @var{name} is the name of this function.
764 @var{type} is a string or semantic tag representing the type of this function.
765 @var{arg-list} is a list of strings or semantic tags representing the
766 arguments of this function.
767 @var{attributes} is a list of additional attributes belonging to this tag.
768 @obsolete{semantic-token-new-function,semantic-tag-new-function}
771 @defun semantic-tag-new-type name type members parents &rest attributes
772 @anchor{semantic-tag-new-type}
773 Create a semantic tag of class @code{'type}.
774 @var{name} is the name of this type.
775 @var{type} is a string or semantic tag representing the type of this type.
776 @var{members} is a list of strings or semantic tags representing the
777 elements that make up this type if it is a composite type.
778 @var{parents} is a cons cell. (@var{explicit-parents} . @var{interface-parents})
779 @var{explicit-parents} can be a single string (Just one parent) or a
780 list of parents (in a multiple inheritance situation). It can also
782 @var{interface-parents} is a list of strings representing the names of
783 all @var{interfaces}, or abstract classes inherited from. It can also be
785 This slot can be interesting because the form:
786 ( @code{nil} ``string'')
787 is a valid parent where there is no explicit parent, and only an
789 @var{attributes} is a list of additional attributes belonging to this tag.
790 @obsolete{semantic-token-new-type,semantic-tag-new-type}
793 @defun semantic-tag-new-include name system-flag &rest attributes
794 @anchor{semantic-tag-new-include}
795 Create a semantic tag of class @code{'include}.
796 @var{name} is the name of this include.
797 @var{system-flag} represents that we were able to identify this include as belonging
798 to the system, as opposed to belonging to the local project.
799 @var{attributes} is a list of additional attributes belonging to this tag.
800 @obsolete{semantic-token-new-include,semantic-tag-new-include}
803 @defun semantic-tag-new-package name detail &rest attributes
804 @anchor{semantic-tag-new-package}
805 Create a semantic tag of class @code{'package}.
806 @var{name} is the name of this package.
807 @var{detail} is extra information about this package, such as a location where
809 @var{attributes} is a list of additional attributes belonging to this tag.
810 @obsolete{semantic-token-new-package,semantic-tag-new-package}
813 @defun semantic-tag-new-code name detail &rest attributes
814 @anchor{semantic-tag-new-code}
815 Create a semantic tag of class @code{'code}.
816 @var{name} is a name for this code.
817 @var{detail} is extra information about the code.
818 @var{attributes} is a list of additional attributes belonging to this tag.
821 @defun semantic-tag-clone tag &optional name
822 @anchor{semantic-tag-clone}
823 Clone @var{tag}, creating a new @var{tag}.
824 If optional argument @var{name} is not @code{nil} it specifies a new name for the
826 @obsolete{semantic-clone-tag,semantic-tag-clone}
829 @defun semantic-tag-copy tag &optional name keep-file
830 @anchor{semantic-tag-copy}
831 Return a copy of @var{tag} unlinked from the originating buffer.
832 If optional argument @var{name} is non-@code{nil} it specifies a new name for the
834 If optional argument @var{keep-file} is non-@code{nil}, and @var{tag} was linked to a
835 buffer, the originating buffer file name is kept in the `:filename'
836 property of the copied tag.
837 This runs the tag hook `unlink-copy-hook`.
840 @node Misc Tag Internals, , Creating Tags, Tag Internals
841 @subsection Misc Tag Internals
843 @defun semantic--tag-run-hooks tag hook &rest args
844 Run for @var{tag} all expressions saved on the property @var{hook}.
845 Each hook expression must take at least one argument, the @var{tag}.
846 For any given situation, additional @var{args} may be passed.
849 @defun semantic--tag-unlink-from-buffer tag
850 Convert @var{tag} from using an overlay to using an overlay proxy.
851 This function is for internal use only. This runs the tag hook
852 @code{unlink-hook}. @ref{Tag Hooks}
855 @defun semantic--tag-link-to-buffer tag
856 Convert @var{tag} from using an overlay proxy to using an overlay.
857 This function is for internal use only. This runs the tag hook
858 @code{link-hook}. @ref{Tag Hooks}
861 @defun semantic--tag-unlink-list-from-buffer tags
862 Convert @var{tags} from using an overlay to using an overlay proxy.
863 This function is for internal use only.
866 @defun semantic--tag-link-list-to-buffer tags
867 Convert @var{tags} from using an overlay proxy to using an overlay.
868 This function is for internal use only.
871 @defun semantic--tag-unlink-cache-from-buffer
872 Convert all tags in the current cache to use overlay proxys.
873 This function is for internal use only.
876 @defun semantic--tag-link-cache-to-buffer
877 Convert all tags in the current cache to use overlays.
878 This function is for internal use only.
881 @defun semantic--tag-expanded-p tag
882 Return non-@code{nil} if @var{tag} is expanded.
883 This function is for internal use only.
884 See also the function @code{semantic--expand-tag}.
887 @defun semantic--tag-expand tag
888 Convert @var{tag} from a raw state to a cooked state, and expand it.
889 Returns a list of cooked tags.
891 The parser returns raw tags with positional data @var{start} @var{end} at the
892 end of the tag data structure (a list for now). We convert it from
893 that to a cooked state that uses an overlay proxy, that is, a vector
894 [@var{start} @var{end}].
896 The raw tag is changed with side effects and maybe expanded in
897 several derived tags when the variable @code{semantic-tag-expand-function}
900 This function is for internal use only.
904 @c @node Semantic Functions Called within ECB
905 @c @section Semantic Functions Called within ECB
906 @c @cindex Semantic Functions Called within ECB
908 I was curious as to what semantic functions were called by a real
909 semantic application such as ECB. So I searched ECB and listed all
910 functions that ECB calls that start with ``semantic-''. Then as I
911 document one by one, I deleted them. The functions below are ones
912 that I have not yet gone through. -ryk8/13/03.
915 semantic-adopt-external-members
916 semantic-after-partial-cache-change-hook
917 semantic-after-toplevel-cache-change-hook
919 semantic-c-template-string
920 semantic-clear-toplevel-cache
921 semantic-colorize-text
922 semantic-current-nonterminal
923 semantic-find-dependency
924 semantic-name-nonterminal
925 semantic-nonterminal-children
926 semantic-nonterminal-protection
927 semantic-overlay-live-p
929 semantic-prototype-nonterminal
930 semantic-require-version
931 semantic-token-buffer
933 semantic-token-function-parent
936 semantic-token-overlay
940 semantic-token-type-parent