This is semantic-appdev.info, produced by makeinfo version 4.3 from app-dev-guide.texi. This manual documents Application Development with Semantic. Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2007 Eric M. Ludlam Copyright (C) 2001, 2002, 2003, 2004 David Ponce Copyright (C) 2002, 2003 Richard Y. Kim Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being list their titles, with the Front-Cover Texts being list, and with the Back-Cover Texts being list. A copy of the license is included in the section entitled "GNU Free Documentation License". INFO-DIR-SECTION Emacs START-INFO-DIR-ENTRY * Semantic Application Writer's guide: (semantic-appdev). END-INFO-DIR-ENTRY This file documents Application Development with Semantic. _Infrastructure for parser based text analysis in Emacs_ Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004 Eric M. Ludlam, David Ponce, and Richard Y. Kim  File: semantic-appdev.info, Node: Top, Next: Semantic Tags, Up: (dir) Semantic Application Development Manual *************************************** A semantic application takes the semantic tags generated by semantic parsers then provides useful services to the user. For a list of such applications, *note (semantic-user)the Semantic User's Guide::. An application developer needs to know * when to invoke the parser to generate or regenerate the tag lists. * how to access the tag lists. * how to access information about each tag. This chapter describes semantic fuctions and concepts an application developer needs to know to perform all of the tasks just listed. * Menu: * Semantic Tags:: * Searching Tag Tables:: Searching tag tables. * Tags at Point:: Finding tags at point. * Tag Decoration:: Decorating tags * Tag Sorting:: Reorganizing streams. * Tag Completion:: Completing read functions. * Override Methods:: Language dependent functions covering conversion to text strings, language dependent queries and local context information * Parser Features:: Application available parser features. * Semantic Database:: Persistant storage of tags. * Idle Scheduling:: Scheduling jobs in idle time. * Example Programs:: Simple programming examples. * Current Context:: Local context analysis. * App Debugger:: Application Debugger * GNU Free Documentation License:: * Index::  File: semantic-appdev.info, Node: Semantic Tags, Next: Searching Tag Tables, Prev: Top, Up: Top Semantic Tags ************* The end result of a semantic parser is a list of tags per each buffer. This chapter discusses the tag data structure and the API provided by semantic to query, process, and modify tags. The tags list for a buffer can be obtained by calling `semantic-fetch-tags' which returns a parse tree of tags that represent the program structure. * Menu: * Tag Basics:: * Tag Query:: * Tag Hooks:: * Tag Overlay:: * Misc Tag Functions:: * Tag Internals::  File: semantic-appdev.info, Node: Tag Basics, Next: Tag Query, Up: Semantic Tags Tag Basics ========== Currently each tag is a list with up to five elements: (NAME CLASS ATTRIBUTES PROPERTIES OVERLAY) Application developers should not rely on this list structure. Instead they should rely on the provided API documented in this chapter. The list structure is explained here primarily to help those reading the semantic source code. * NAME is a required component for all tags, i.e., every tag must have this component. It is also guaranteed to be a string. This string represents the name of the tag, usually a named definition which the language will use elsewhere as a reference to the syntactic element found. * CLASS is the other required component for all tags. It is a symbol representing the class of the tag. Valid CLASSes can be anything, as long is it is an Emacs Lisp symbol. However following are some of the well-known symbols: `type', `function', `variable', `include', `package', `code'. * ATTRIBUTES is a property list that keep information related to the tag parsed from the buffer. The symbol names in the property list can be anything, though there is a useful set of predefined attributes. It is best to use the API functions to access the well-known properties. *Note Tag Query::. * PROPERTIES is generated by the semantic parser harness, and need not be provided by a language author. Properties are used to store transient data on a tag unrelated to the source of the original tag, such as hook functions, dynamic overlays, or other data needed by programs. The semantic incremental parser will attempt to maintain properties when reparsing the source of a tag. * OVERLAY represents positional information for this tag. It is automatically generated by the semantic parser harness, and need not be provided by the language author. Depending on the overlay in a program can be dangerous because sometimes the overlay is replaced with an integer pair [ START END ] when the buffer the tag belongs to is not in memory. This happens when a using has activated the Semantic Database *note (lang-support-guide)semanticdb::. - Function: semantic-tag-name tag Return the name of TAG. For functions, variables, classes, typedefs, etc., this is the identifier that is being defined. For tags without an obvious associated name, this may be the statement type, e.g., this may return `print' for python's print statement. *Compatibility*: `semantic-tag-name' introduced in semantic version 2.0 supercedes `semantic-token-name' which is now obsolete. - Function: semantic-tag-class tag Return the class of TAG. That is, the symbol `'variable', `'function', `'type', or other. There is no limit to the symbols that may represent the class of a tag. Each parser generates tags with classes defined by it. For functional languages, typical tag classes are: `type' Data types, named map for a memory block. `function' A function or method, or named execution location. `variable' A variable, or named storage for data. `include' Statement that represents a file from which more tags can be found. `package' Statement that declairs this file's package name. `code' Code that has not name or binding to any other symbol, such as in a script. *Compatibility*: `semantic-tag-class' introduced in semantic version 2.0 supercedes `semantic-token-token' which is now obsolete. Several functions that deal with ATTRIBUTES component are given in *Note Tag Attributes Internals: Tag Attributes Internals. However functions listed in *Note Tag Query: Tag Query should provide most needs of the application developer. Similarly functions that deal with PROPERTIES component are given in *Note Tag Properties Internals: Tag Properties Internals. The application developer should not need to use any of these. Finally *Note Tag Overlay: Tag Overlay lists functions dealing with the OVERLAY component.  File: semantic-appdev.info, Node: Tag Query, Next: Tag Hooks, Prev: Tag Basics, Up: Semantic Tags Tag Query ========= This section lists functions that answers simple questions regarding a given tag. Tag Predicates -------------- - Function: semantic-tag-p tag Return non-`nil' if TAG is most likely a semantic tag. *Compatibility*: `semantic-tag-p' introduced in semantic version 2.0 supercedes `semantic-token-p' which is now obsolete. - Function: semantic-equivalent-tag-p tag1 tag2 Compare TAG1 and TAG2 and return non-`nil' if they are equivalent. Use "eq" to test of two tags are the same. Use this function if tags are being copied and regrouped to test for if two tags represent the same thing, but may be constructed of different cons cells. *Compatibility*: `semantic-equivalent-tag-p' introduced in semantic version 2.0 supercedes `semantic-equivalent-tokens-p' which is now obsolete. - Function: semantic-tag-of-class-p tag class Return non-`nil' if class of TAG is CLASS. - Function: semantic-tag-faux-p tag Return non-`nil' if TAG is a FAUX tag. FAUX tags are created to represent a construct that is not known to exist in the code. - Function: semantic-tag-type-compound-p tag Return non-`nil' the type of TAG is compound. Compound implies a structure or similar data type. Returns the list of tag members if it is compound. Documentation ------------- - Function: semantic-tag-docstring tag &optional buffer Return the documentation of TAG. That is the value defined by the `:documentation' attribute. Optional argument BUFFER indicates where to get the text from. If not provided, then only the POSITION can be provided. *Compatibility*: `semantic-tag-docstring' introduced in semantic version 2.0 supercedes `semantic-token-docstring' which is now obsolete. Common Flags ------------ - Function: semantic-tag-variable-constant-p tag Return non-`nil' if the variable that TAG describes is a constant. That is the value of the attribute `:constant-flag'. *Compatibility*: `semantic-tag-variable-constant-p' introduced in semantic version 2.0 supercedes `semantic-token-variable-const' which is now obsolete. - Function: semantic-tag-function-destructor-p tag Return non-`nil' if TAG describes a destructor function. That is the value of the `:destructor-flag' attribute. *Compatibility*: `semantic-tag-function-destructor-p' introduced in semantic version 2.0 supercedes `semantic-token-function-destructor' which is now obsolete. - Function: semantic-tag-function-throws tag Return the exceptions the function that TAG describes can throw. That is the value of the `:throws' attribute. *Compatibility*: `semantic-tag-function-throws' introduced in semantic version 2.0 supercedes `semantic-token-function-throws' which is now obsolete. - Function: semantic-tag-modifiers tag Return the value of the `:typemodifiers' attribute of TAG. *Compatibility*: `semantic-tag-modifiers' introduced in semantic version 2.0 supercedes `semantic-token-type-modifiers' which is now obsolete. *Compatibility*: `semantic-tag-modifiers' introduced in semantic version 2.0 supercedes `semantic-token-variable-modifiers' which is now obsolete. *Compatibility*: `semantic-tag-modifiers' introduced in semantic version 2.0 supercedes `semantic-token-function-modifiers' which is now obsolete. Functions --------- - Function: semantic-tag-function-arguments tag Return the arguments of the function that TAG describes. That is the value of the `:arguments' attribute. *Compatibility*: `semantic-tag-function-arguments' introduced in semantic version 2.0 supercedes `semantic-token-function-args' which is now obsolete. Variables --------- - Function: semantic-tag-variable-default tag Return the default value of the variable that TAG describes. That is the value of the attribute `:default-value'. *Compatibility*: `semantic-tag-variable-default' introduced in semantic version 2.0 supercedes `semantic-token-variable-default' which is now obsolete. Data Types ---------- - Function: semantic-tag-type tag Return the value of the `:type' attribute of TAG. *Compatibility*: `semantic-tag-type' introduced in semantic version 2.0 supercedes `semantic-token-type' which is now obsolete. - Function: semantic-tag-of-type-p tag type Compare TAG's type against TYPE. Non `nil' if equivalent. TYPE can be a string, or a tag of class `'type'. Inheritance and Hierarchy ------------------------- - Function: semantic-tag-named-parent tag Return the parent of TAG. That is the value of the `:parent' attribute. If a definition can occur outside an actual parent structure, but refers to that parent by name, then the `:parent' attribute should be used. - Function: semantic-tag-function-parent tag Return the parent of the function that TAG describes. That is the value of the `:parent' attribute. A function has a parent if it is a method of a class, and if the function does not appear in body of it's parent class. *Compatibility*: `semantic-tag-function-parent' introduced in semantic version 2.0 supercedes `semantic-token-function-parent' which is now obsolete. - Function: semantic-tag-type-superclasses tag Return the list of superclasses of the type that TAG describes. *Compatibility*: `semantic-tag-type-superclasses' introduced in semantic version 2.0 supercedes `semantic-token-type-parent-superclass' which is now obsolete. *Compatibility*: `semantic-tag-type-superclasses' introduced in semantic version 2.0 supercedes `semantic-token-type-parent' which is now obsolete. - Function: semantic-tag-type-interfaces tag Return the list of interfaces of the type that TAG describes. *Compatibility*: `semantic-tag-type-interfaces' introduced in semantic version 2.0 supercedes `semantic-token-type-parent-implement' which is now obsolete. *Compatibility*: `semantic-tag-type-interfaces' introduced in semantic version 2.0 supercedes `semantic-token-type-parent' which is now obsolete. - Function: semantic-tag-type-members tag Return the members of the type that TAG describes. That is the value of the `:members' attribute. *Compatibility*: `semantic-tag-type-members' introduced in semantic version 2.0 supercedes `semantic-token-type-parts' which is now obsolete. Includes -------- - Function: semantic-tag-include-system-p tag Return non-`nil' if the include that TAG describes is a system include. That is the value of the attribute `:system-flag'. *Compatibility*: `semantic-tag-include-system-p' introduced in semantic version 2.0 supercedes `semantic-token-include-system' which is now obsolete. - Function: semantic-tag-include-filename tag Return a filename representation of TAG. The default action is to return the "semantic-tag-name". Some languages do not use full filenames in their include statements. Override this method to translate the code represenation into a filename. (A relative filename if necessary.) See "semantic-dependency-tag-file" to expand an include tag to a full file name. This function can be overloaded (see "define-mode-local-override" for details). Code ---- - Function: semantic-tag-code-detail tag Return detail information from code that TAG describes. That is the value of the attribute `:detail'. Tag Children ------------ - Function: semantic-tag-components tag Return a list of components for TAG. A Component is a part of TAG which itself may be a TAG. Examples include the elements of a structure in a tag of class `type, or the list of arguments to a tag of class `'function'. This function can be overloaded (see "define-mode-local-override" for details). - Function: semantic-tag-components-default tag Return a list of components for TAG. Perform the described task in "semantic-tag-components". - Function: semantic-tag-children-compatibility tag &optional positiononly Return children of TAG. If POSITIONONLY is `nil', use "semantic-tag-components". If POSITIONONLY is non-`nil', use "semantic-tag-components-with-overlays". DO NOT use this fcn in new code. Use one of the above instead. *Compatibility*: `semantic-tag-children-compatibility' introduced in semantic version 2.0 supercedes `semantic-nonterminal-children' which is now obsolete. Location --------  File: semantic-appdev.info, Node: Tag Overlay, Next: Misc Tag Functions, Prev: Tag Hooks, Up: Semantic Tags Tag Overlay =========== The functions in this answer questions regarding the overly such as the buffer in which the tags is located, the start and/or end position of the tag, and the overlay itself which spans the tags. - Function: semantic-tag-start tag Return the start location of TAG. *Compatibility*: `semantic-tag-start' introduced in semantic version 2.0 supercedes `semantic-token-start' which is now obsolete. - Function: semantic-tag-end tag Return the end location of TAG. *Compatibility*: `semantic-tag-end' introduced in semantic version 2.0 supercedes `semantic-token-end' which is now obsolete. - Function: semantic-tag-bounds tag Return the location (START END) of data TAG describes. *Compatibility*: `semantic-tag-bounds' introduced in semantic version 2.0 supercedes `semantic-token-extent' which is now obsolete. - Function: semantic-tag-buffer tag Return the buffer TAG resides in. If TAG has an originating file, read that file into a (maybe new) buffer, and return it. Return `nil' if there is no buffer for this tag. *Compatibility*: `semantic-tag-buffer' introduced in semantic version 2.0 supercedes `semantic-token-buffer' which is now obsolete. - Function: semantic-tag-file-name tag Return the name of the file from which TAG originated. Return `nil' if that information can't be obtained. If TAG is from a loaded buffer, then that buffer's filename is used. If TAG is unlinked, but has a `:filename' property, then that is used. - Function: semantic-tag-overlay tag Return the OVERLAY part of TAG. That is, an overlay or an unloaded buffer representation. This function can also return an array of the form [ START END ]. This occurs for tags that are not currently linked into a buffer. *Compatibility*: `semantic-tag-overlay' introduced in semantic version 2.0 supercedes `semantic-token-overlay' which is now obsolete. - Function: semantic-tag-with-position-p tag Return non-`nil' if TAG has positional information. *Compatibility*: `semantic-tag-with-position-p' introduced in semantic version 2.0 supercedes `semantic-token-with-position-p' which is now obsolete. - Function: semantic-tag-components-with-overlays tag Return the list of top level components belonging to TAG. Children are any sub-tags which contain overlays. Default behavior is to get "semantic-tag-components" in addition to the components of an anonymous types (if applicable.) *Language authors, please note:* If a mode defines a language tag that has tags in it with overlays you should still return them with this function. Ignoring this step will prevent several features from working correctly. This function can be overloaded (see "define-mode-local-override" for details). - Function: semantic-tag-components-with-overlays-default tag Return the list of top level components belonging to TAG. Children are any sub-tags which contain overlays. The default action collects regular components of TAG, in addition to any components beloning to an anonymous type.  File: semantic-appdev.info, Node: Tag Hooks, Next: Tag Overlay, Prev: Tag Query, Up: Semantic Tags Tag Hooks ========= Individual tags can have hooks associated with them. Hooks are saved as properties, but can cause specific tags to have special behaviors after a hook is added. You can manipulate tag hooks with these functions: - Function: semantic-tag-add-hook tag hook function &optional append Onto TAG, add to the value of HOOK the function FUNCTION. FUNCTION is added (if necessary) at the beginning of the hook list unless the optional argument APPEND is non-`nil', in which case FUNCTION is added at the end. HOOK should be a symbol, and FUNCTION may be any valid function. See also the function "add-hook". - Function: semantic-tag-remove-hook tag hook function Onto TAG, remove from the value of HOOK the function FUNCTION. HOOK should be a symbol, and FUNCTION may be any valid function. If FUNCTION isn't the value of HOOK, or, if FUNCTION doesn't appear in the list of hooks to run in HOOK, then nothing is done. See also the function "remove-hook". For a developer, if you have an application for which you want to support a special kind of hook on a per tag basis, you can use this to run those hooks. - Function: semantic-tag-run-hooks tag hook &rest args Run for TAG all expressions saved on the property HOOK. Each hook expression must take at least one argument, the TAG. For any given situation, additional ARGS may be passed. Semantic supports two TAG specific hooks at this time: `link-hook' This hook is run whenever a tag is linked into a buffer. This occurs just after parsing, and whenever a tag is loaded into memory. This hook also executes after a datase save, when all tags are first unlinked from the current buffer before the save. `unlink-hook' This hook is run whenever a tag is unlinked from a buffer. This ocucrs during a database save, or when a tag is modified by the incremental parser. `unlink-copy-hook' This hook is run whenever a tag is copied. This occurs in the function `semantic-tag-copy'. Use this hook to remove properties from the tag that link it to a buffer, as this tag should no longer have direct buffer links.  File: semantic-appdev.info, Node: Misc Tag Functions, Next: Tag Internals, Prev: Tag Overlay, Up: Semantic Tags Misc Tag Functions ================== - Command: semantic-narrow-to-tag &optional tag Narrow to the region specified by the bounds of TAG. See "semantic-tag-bounds". *Compatibility*: `semantic-narrow-to-tag' introduced in semantic version 2.0 supercedes `semantic-narrow-to-token' which is now obsolete. - Function: semantic-with-buffer-narrowed-to-current-tag &rest body Execute BODY with the buffer narrowed to the current tag. *Compatibility*: `semantic-with-buffer-narrowed-to-current-tag' introduced in semantic version 2.0 supercedes `semantic-with-buffer-narrowed-to-current-token' which is now obsolete. - Function: semantic-with-buffer-narrowed-to-tag tag &rest body Narrow to TAG, and execute BODY. *Compatibility*: `semantic-with-buffer-narrowed-to-tag' introduced in semantic version 2.0 supercedes `semantic-with-buffer-narrowed-to-token' which is now obsolete.  File: semantic-appdev.info, Node: Tag Internals, Prev: Misc Tag Functions, Up: Semantic Tags Tag Internals ============= * Menu: * Tag Attributes Internals:: * Tag Properties Internals:: * Tag Overlay Internals:: * Creating Tags:: * Misc Tag Internals::  File: semantic-appdev.info, Node: Tag Attributes Internals, Next: Tag Properties Internals, Up: Tag Internals Tag Attributes Internals ------------------------ - Function: semantic-tag-attributes tag Return the list of public attributes of TAG. That is a property list: (ATTRIBUTE-1 VALUE-1 ATTRIBUTE-2 VALUE-2...). *Compatibility*: `semantic-tag-attributes' introduced in semantic version 2.0 supercedes `semantic-token-extra-specs' which is now obsolete. *Compatibility*: `semantic-tag-attributes' introduced in semantic version 2.0 supercedes `semantic-token-function-extra-specs' which is now obsolete. *Compatibility*: `semantic-tag-attributes' introduced in semantic version 2.0 supercedes `semantic-token-variable-extra-specs' which is now obsolete. *Compatibility*: `semantic-tag-attributes' introduced in semantic version 2.0 supercedes `semantic-token-type-extra-specs' which is now obsolete. - Function: semantic-tag-get-attribute tag attribute From TAG, return the value of ATTRIBUTE. ATTRIBUTE is a symbol whose specification value to get. Return the value found, or `nil' if ATTRIBUTE is not one of the attributes of TAG. *Compatibility*: `semantic-tag-get-attribute' introduced in semantic version 2.0 supercedes `semantic-token-extra-spec' which is now obsolete. *Compatibility*: `semantic-tag-get-attribute' introduced in semantic version 2.0 supercedes `semantic-token-function-extra-spec' which is now obsolete. *Compatibility*: `semantic-tag-get-attribute' introduced in semantic version 2.0 supercedes `semantic-token-variable-extra-spec' which is now obsolete. - Function: semantic-tag-put-attribute tag attribute value Change value in TAG of ATTRIBUTE to VALUE. If ATTRIBUTE already exists, its value is set to VALUE, otherwise the new ATTRIBUTE VALUE pair is added. Return TAG. Use this function in a parser when not all attributes are known at the same time. *Compatibility*: `semantic-tag-put-attribute' introduced in semantic version 2.0 supercedes `semantic-token-add-extra-spec' which is now obsolete. - Function: semantic-tag-put-attribute-no-side-effect tag attribute value Change value in TAG of ATTRIBUTE to VALUE without side effects. All cons cells in the attribute list are replicated so that there are no side effects if TAG is in shared lists. If ATTRIBUTE already exists, its value is set to VALUE, otherwise the new ATTRIBUTE VALUE pair is added. Return TAG.  File: semantic-appdev.info, Node: Tag Properties Internals, Next: Tag Overlay Internals, Prev: Tag Attributes Internals, Up: Tag Internals Tag Properties Internals ------------------------ - Function: semantic-tag-properties tag Return the list of private properties of TAG. That is a property list: (PROPERTY-1 VALUE-1 PROPERTY-2 VALUE-2...). *Compatibility*: `semantic-tag-properties' introduced in semantic version 2.0 supercedes `semantic-token-properties' which is now obsolete. - Function: semantic-tag-put-property tag property value Change value in TAG of PROPERTY to VALUE. If PROPERTY already exists, its value is set to VALUE, otherwise the new PROPERTY VALUE pair is added. Return TAG. That function is for internal use only. *Compatibility*: `semantic--tag-put-property' introduced in semantic version 2.0 supercedes `semantic-token-put' which is now obsolete. - Function: semantic-tag-get-property tag property From TAG, extract the value of PROPERTY. Return the value found, or `nil' if PROPERTY is not one of the properties of TAG. That function is for internal use only. *Compatibility*: `semantic--tag-get-property' introduced in semantic version 2.0 supercedes `semantic-token-get' which is now obsolete. - Function: semantic-tag-put-property-no-side-effect tag property value Change value in TAG of PROPERTY to VALUE without side effects. All cons cells in the property list are replicated so that there are no side effects if TAG is in shared lists. If PROPERTY already exists, its value is set to VALUE, otherwise the new PROPERTY VALUE pair is added. Return TAG. That function is for internal use only. *Compatibility*: `semantic--tag-put-property-no-side-effect' introduced in semantic version 2.0 supercedes `semantic-token-put-no-side-effect' which is now obsolete. - Function: semantic-tag-make-plist args Create a property list with ARGS. Args is a property list of the form (KEY1 VALUE1 ... KEYN VALUEN). Where KEY is a symbol, and VALUE is the value for that symbol. The return value will be a new property list, with these KEY/VALUE pairs eliminated: - KEY associated to `nil' VALUE. - KEY associated to an empty string VALUE. - KEY associated to a zero VALUE. *Compatibility*: `semantic-tag-make-plist' introduced in semantic version 2.0 supercedes `semantic-tag-make-assoc-list' which is now obsolete.  File: semantic-appdev.info, Node: Tag Overlay Internals, Next: Creating Tags, Prev: Tag Properties Internals, Up: Tag Internals Tag Overlay Internals --------------------- Many of the overlay related functions were already documented in *Note Tag Overlay: Tag Overlay. - Function: semantic-tag-set-bounds tag start end In TAG, set the START and END location of data it describes.  File: semantic-appdev.info, Node: Creating Tags, Next: Misc Tag Internals, Prev: Tag Overlay Internals, Up: Tag Internals Creating Tags ------------- - Function: semantic-tag name class &rest attributes Create a generic semantic tag. NAME is a string representing the name of this tag. CLASS is the symbol that represents the class of tag this is, such as `'variable', or `'function'. ATTRIBUTES is a list of additional attributes belonging to this tag. *Compatibility*: `semantic-tag' introduced in semantic version 2.0 supercedes `semantic-token' which is now obsolete. - Function: semantic-tag-new-variable name type default-value &rest attributes Create a semantic tag of class `'variable'. NAME is the name of this variable. TYPE is a string or semantic tag representing the type of this variable. DEFAULT-VALUE is a string representing the default value of this variable. ATTRIBUTES is a list of additional attributes belonging to this tag. *Compatibility*: `semantic-tag-new-variable' introduced in semantic version 2.0 supercedes `semantic-token-new-variable' which is now obsolete. - Function: semantic-tag-new-function name type arg-list &rest attributes Create a semantic tag of class `'function'. NAME is the name of this function. TYPE is a string or semantic tag representing the type of this function. ARG-LIST is a list of strings or semantic tags representing the arguments of this function. ATTRIBUTES is a list of additional attributes belonging to this tag. *Compatibility*: `semantic-tag-new-function' introduced in semantic version 2.0 supercedes `semantic-token-new-function' which is now obsolete. - Function: semantic-tag-new-type name type members parents &rest attributes Create a semantic tag of class `'type'. NAME is the name of this type. TYPE is a string or semantic tag representing the type of this type. MEMBERS is a list of strings or semantic tags representing the elements that make up this type if it is a composite type. PARENTS is a cons cell. (EXPLICIT-PARENTS . INTERFACE-PARENTS) EXPLICIT-PARENTS can be a single string (Just one parent) or a list of parents (in a multiple inheritance situation). It can also be `nil'. INTERFACE-PARENTS is a list of strings representing the names of all INTERFACES, or abstract classes inherited from. It can also be `nil'. This slot can be interesting because the form: ( `nil' "string") is a valid parent where there is no explicit parent, and only an interface. ATTRIBUTES is a list of additional attributes belonging to this tag. *Compatibility*: `semantic-tag-new-type' introduced in semantic version 2.0 supercedes `semantic-token-new-type' which is now obsolete. - Function: semantic-tag-new-include name system-flag &rest attributes Create a semantic tag of class `'include'. NAME is the name of this include. SYSTEM-FLAG represents that we were able to identify this include as belonging to the system, as opposed to belonging to the local project. ATTRIBUTES is a list of additional attributes belonging to this tag. *Compatibility*: `semantic-tag-new-include' introduced in semantic version 2.0 supercedes `semantic-token-new-include' which is now obsolete. - Function: semantic-tag-new-package name detail &rest attributes Create a semantic tag of class `'package'. NAME is the name of this package. DETAIL is extra information about this package, such as a location where it can be found. ATTRIBUTES is a list of additional attributes belonging to this tag. *Compatibility*: `semantic-tag-new-package' introduced in semantic version 2.0 supercedes `semantic-token-new-package' which is now obsolete. - Function: semantic-tag-new-code name detail &rest attributes Create a semantic tag of class `'code'. NAME is a name for this code. DETAIL is extra information about the code. ATTRIBUTES is a list of additional attributes belonging to this tag. - Function: semantic-tag-clone tag &optional name Clone TAG, creating a new TAG. If optional argument NAME is not `nil' it specifies a new name for the cloned tag. *Compatibility*: `semantic-tag-clone' introduced in semantic version 2.0 supercedes `semantic-clone-tag' which is now obsolete. - Function: semantic-tag-copy tag &optional name keep-file Return a copy of TAG unlinked from the originating buffer. If optional argument NAME is non-`nil' it specifies a new name for the copied tag. If optional argument KEEP-FILE is non-`nil', and TAG was linked to a buffer, the originating buffer file name is kept in the `:filename' property of the copied tag. This runs the tag hook `unlink-copy-hook`.  File: semantic-appdev.info, Node: Misc Tag Internals, Prev: Creating Tags, Up: Tag Internals Misc Tag Internals ------------------ - Function: semantic-tag-run-hooks tag hook &rest args Run for TAG all expressions saved on the property HOOK. Each hook expression must take at least one argument, the TAG. For any given situation, additional ARGS may be passed. - Function: semantic-tag-unlink-from-buffer tag Convert TAG from using an overlay to using an overlay proxy. This function is for internal use only. This runs the tag hook `unlink-hook'. *Note Tag Hooks:: - Function: semantic-tag-link-to-buffer tag Convert TAG from using an overlay proxy to using an overlay. This function is for internal use only. This runs the tag hook `link-hook'. *Note Tag Hooks:: - Function: semantic-tag-unlink-list-from-buffer tags Convert TAGS from using an overlay to using an overlay proxy. This function is for internal use only. - Function: semantic-tag-link-list-to-buffer tags Convert TAGS from using an overlay proxy to using an overlay. This function is for internal use only. - Function: semantic-tag-unlink-cache-from-buffer Convert all tags in the current cache to use overlay proxys. This function is for internal use only. - Function: semantic-tag-link-cache-to-buffer Convert all tags in the current cache to use overlays. This function is for internal use only. - Function: semantic-tag-expanded-p tag Return non-`nil' if TAG is expanded. This function is for internal use only. See also the function `semantic--expand-tag'. - Function: semantic-tag-expand tag Convert TAG from a raw state to a cooked state, and expand it. Returns a list of cooked tags. The parser returns raw tags with positional data START END at the end of the tag data structure (a list for now). We convert it from that to a cooked state that uses an overlay proxy, that is, a vector [START END]. The raw tag is changed with side effects and maybe expanded in several derived tags when the variable `semantic-tag-expand-function' is set. This function is for internal use only.  File: semantic-appdev.info, Node: Searching Tag Tables, Next: Tags at Point, Prev: Semantic Tags, Up: Top Searching Tag Tables ******************** These functions take some key, and returns information found in a tag table. Some will return one tag (the first matching item found.) Others will return a list of all items matching a given criterion. Most of these functions work regardless of a buffer being in memory or not. Any specialty search routine that claims to use a function that is an overload method will need to execute in a buffer of the same mode as the tags being searched. * Menu: * Breadth Search:: Searching only one level of tags. * Deep Search:: Deep searches into types or argument lists. * Specialty Search:: Specialty Searches. * Custom Search:: Write custom search routines.  File: semantic-appdev.info, Node: Breadth Search, Next: Deep Search, Up: Searching Tag Tables Breadth Search ============== Searching the breadth of a list of tags means that only one level of the tags will be searched. If one of the tags is a datatype with additional members, those members are not searched. - Function: semantic-find-first-tag-by-name name &optional table Find the first tag with NAME in TABLE. NAME is a string. TABLE is a semantic tags table. See "semantic-something-to-tag-table". This routine uses "assoc" to quickly find the first matching entry. - Function: semantic-find-tags-by-name name &optional table Find all tags with NAME in TABLE. NAME is a string. TABLE is a tag table. See "semantic-something-to-tag-table". - Function: semantic-find-tags-for-completion prefix &optional table Find all tags whos name begins with PREFIX in TABLE. PREFIX is a string. TABLE is a tag table. See "semantic-something-to-tag-table". While it would be nice to use "try-completion" or "all-completions", those functions do not return the tags, only a string. Uses "compare-strings" for fast comparison. - Function: semantic-find-tags-by-name-regexp regexp &optional table Find all tags with name matching REGEXP in TABLE. REGEXP is a string containing a regular expression, TABLE is a tag table. See "semantic-something-to-tag-table". Consider using "semantic-find-tags-for-completion" if you are attempting to do completions. - Function: semantic-find-tags-by-class class &optional table Find all tags of class CLASS in TABLE. CLASS is a symbol representing the class of the token, such as `'variable', of 'function.. TABLE is a tag table. See "semantic-something-to-tag-table". - Function: semantic-find-tags-by-type type &optional table Find all tags of with a type TYPE in TABLE. TYPE is a string or tag representing a data type as defined in the language the tags were parsed from, such as "int", or perhaps a tag whose name is that of a struct or class. TABLE is a tag table. See "semantic-something-to-tag-table". - Function: semantic-find-tags-included &optional table Find all tags in TABLE that are of the `'include' class. TABLE is a tag table. See "semantic-something-to-tag-table".  File: semantic-appdev.info, Node: Deep Search, Next: Specialty Search, Prev: Breadth Search, Up: Searching Tag Tables Deep Search =========== - Function: semantic-brute-find-first-tag-by-name name streamorbuffer &optional search-parts search-include Find a tag NAME within STREAMORBUFFER. NAME is a string. If SEARCH-PARTS is non-`nil', search children of tags. If SEARCH-INCLUDE is non-`nil', search include files. Use "semantic-find-first-tag-by-name" instead. *Compatibility*: `semantic-brute-find-first-tag-by-name' introduced in semantic version 2.0 supercedes `semantic-find-nonterminal-by-name' which is now obsolete. - Function: semantic-brute-find-tag-by-property property value streamorbuffer &optional search-parts search-includes Find all tags with PROPERTY equal to VALUE in STREAMORBUFFER. Optional argument SEARCH-PARTS and SEARCH-INCLUDES are passed to "semantic-brute-find-tag-by-function". *Compatibility*: `semantic-brute-find-tag-by-property' introduced in semantic version 2.0 supercedes `semantic-find-nonterminal-by-property' which is now obsolete. - Function: semantic-brute-find-tag-by-attribute attr streamorbuffer &optional search-parts search-includes Find all tags with a given ATTR in STREAMORBUFFER. ATTR is a symbol key into the attributes list. Optional argument SEARCH-PARTS and SEARCH-INCLUDES are passed to "semantic-brute-find-tag-by-function". *Compatibility*: `semantic-brute-find-tag-by-attribute' introduced in semantic version 2.0 supercedes `semantic-find-nonterminal-by-extra-spec' which is now obsolete. - Function: semantic-brute-find-tag-by-attribute-value attr value streamorbuffer &optional search-parts search-includes Find all tags with a given ATTR equal to VALUE in STREAMORBUFFER. ATTR is a symbol key into the attributes list. VALUE is the value that ATTR should match. Optional argument SEARCH-PARTS and SEARCH-INCLUDES are passed to "semantic-brute-find-tag-by-function". *Compatibility*: `semantic-brute-find-tag-by-attribute-value' introduced in semantic version 2.0 supercedes `semantic-find-nonterminal-by-extra-spec-value' which is now obsolete. - Function: semantic-brute-find-tag-by-position position streamorbuffer &optional nomedian Find a nonterminal covering POSITION within STREAMORBUFFER. POSITION is a number, or marker. If NOMEDIAN is non-`nil', don't do the median calculation, and return nil. *Compatibility*: `semantic-brute-find-tag-by-position' introduced in semantic version 2.0 supercedes `semantic-find-nonterminal-by-position' which is now obsolete. - Function: semantic-brute-find-innermost-tag-by-position position streamorbuffer &optional nomedian Find a list of tags covering POSITION within STREAMORBUFFER. POSITION is a number, or marker. If NOMEDIAN is non-`nil', don't do the median calculation, and return nil. This function will find the topmost item, and recurse until no more details are available of findable. *Compatibility*: `semantic-brute-find-innermost-tag-by-position' introduced in semantic version 2.0 supercedes `semantic-find-innermost-nonterminal-by-position' which is now obsolete. - Function: semantic-brute-find-tag-by-class class streamorbuffer &optional search-parts search-includes Find all tags with a class CLASS within STREAMORBUFFER. CLASS is a symbol representing the class of the tags to find. See "semantic-tag-class". Optional argument SEARCH-PARTS and SEARCH-INCLUDES are passed to "semantic-brute-find-tag-by-function". Use `semantic-find-tag-by-class' instead. *Compatibility*: `semantic-brute-find-tag-by-class' introduced in semantic version 2.0 supercedes `semantic-find-nonterminal-by-token' which is now obsolete. - Function: semantic-brute-find-tag-standard streamorbuffer &optional search-parts search-includes Find all tags in STREAMORBUFFER which define simple class types. See "semantic-tag-class". Optional argument SEARCH-PARTS and SEARCH-INCLUDES are passed to "semantic-brute-find-tag-by-function". *Compatibility*: `semantic-brute-find-tag-standard' introduced in semantic version 2.0 supercedes `semantic-find-nonterminal-standard' which is now obsolete. - Function: semantic-brute-find-tag-by-type type streamorbuffer &optional search-parts search-includes Find all tags with type TYPE within STREAMORBUFFER. TYPE is a string which is the name of the type of the tags returned. See "semantic-tag-type". Optional argument SEARCH-PARTS and SEARCH-INCLUDES are passed to "semantic-brute-find-tag-by-function". *Compatibility*: `semantic-brute-find-tag-by-type' introduced in semantic version 2.0 supercedes `semantic-find-nonterminal-by-type' which is now obsolete. - Function: semantic-brute-find-tag-by-function function streamorbuffer &optional search-parts search-includes Find all tags for which FUNCTION's value is non-`nil' within STREAMORBUFFER. FUNCTION must return non-`nil' if an element of STREAM will be included in the new list. If optional argument SEARCH-PARTS is non-`nil', all sub-parts of tags are searched. The overloadable function `semantic-tag-componenets' is used for the searching child lists. If SEARCH-PARTS is the symbol `'positiononly', then only children that have positional information are searched. If SEARCH-INCLUDES is non-`nil', then all include files are also searched for matches. This parameter hasn't be active for a while and is obsolete. *Compatibility*: `semantic-brute-find-tag-by-function' introduced in semantic version 2.0 supercedes `semantic-find-nonterminal-by-function' which is now obsolete. - Function: semantic-brute-find-first-tag-by-function function streamorbuffer &optional search-parts search-includes Find the first nonterminal which FUNCTION match within STREAMORBUFFER. FUNCTION must return non-`nil' if an element of STREAM will be included in the new list. The following parameters were never implemented. If optional argument SEARCH-PARTS, all sub-parts of tags are searched. The overloadable function "semantic-tag-components" is used for searching. If SEARCH-INCLUDES is non-`nil', then all include files are also searched for matches. *Compatibility*: `semantic-brute-find-first-tag-by-function' introduced in semantic version 2.0 supercedes `semantic-find-nonterminal-by-function-first-match' which is now obsolete.  File: semantic-appdev.info, Node: Specialty Search, Next: Custom Search, Prev: Deep Search, Up: Searching Tag Tables Specialty Search ================ There are some specialty searches needed by some semantic tools that could prove useful. These specialty searches often do not match against some single attribute as most breadth searches do. - Function: semantic-find-tags-of-compound-type &optional table Find all tags which are a compound type in TABLE. Compound types are structures, or other data type which is not of a primitive nature, such as int or double. Used in completion. - Function: semantic-find-tags-by-scope-protection scopeprotection parent &optional table Find all tags accessable by SCOPEPROTECTION. SCOPEPROTECTION is a symbol which can be returned by the method "semantic-tag-protection". A hard-coded order is used to determine a match. PARENT is a tag representing the PARENT slot needed for "semantic-tag-protection". TABLE is a list of tags (a subset of PARENT members) to scan. If TABLE is `nil', the type members of PARENT are used. See "semantic-tag-protected-p" for details on which tags are returned. - Function: semantic-find-tags-external-children-of-type type &optional table Find all tags in whose parent is TYPE in TABLE. These tags are defined outside the scope of the original TYPE declaration. TABLE is a tag table. See "semantic-something-to-tag-table".  File: semantic-appdev.info, Node: Custom Search, Prev: Specialty Search, Up: Searching Tag Tables Custom Search ============= The searching framework for semantic for tag tables has two basic root methods. One is a function and the other is a macro. The functional version is needed if some sort of macro conflict arrises. The macro version is useful because it eliminates a level of function call, and is faster. - Function: semantic-find-tags-by-function predicate &optional table Find tags for which PREDICATE is non-`nil' in TABLE. PREDICATE is a lambda expression which accepts on TAG. TABLE is a semantic tags table. See "semantic-something-to-tag-table". - Function: semantic-find-tags-by-macro form &optional table Find tags for which FORM is non-`nil' in TABLE. TABLE is a semantic tags table. See "semantic-something-to-tag-table".