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 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 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::
* 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 CLASSs 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.

   * PROPERTIES is generated by the semantic parser harness, and need
     not be provided by a language author.

   * 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, i.e., a string.  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.

     *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.

 - 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-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.

 - 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 token' which is now obsolete.

 - 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-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.

 - 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.

 - 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
     token' 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' which
     is now obsolete.

     *Compatibility*: `semantic-tag-type-interfaces' introduced in
     semantic version 2.0 supercedes
     `semantic-token-type-parent-implement' 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.

 - 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-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-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-file-name tag
     Return the name of the file from which TAG originated.  Return
     `nil' if that information can't be obtained.

 - Function: semantic-tag-of-class-p tag class
     Return non-`nil' if class of TAG is CLASS.

 - Function: semantic-tag-of-type-p tag type
     Compare TAG's type against TYPE.  Return non-`nil' if equivalent.
     TYPE can be a string, or a tag of class `'type'.

 - 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 representation into a filename.  (A relative
     filename if necessary.)

 - Function: semantic-tag-include-filename-default tag
     Return a filename representation of TAG.  Returns
     "semantic-tag-name".

 - Function: semantic-tag-code-detail tag
     Return detail information from code that TAG describes.  That is
     the value of the attribute `:detail'.

 - 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 ``type' tag, or the list of arguments to a
     `'function' tag.

 - 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
     function in new code.  Use one of the above instead.


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.

 - Function: semantic-tag-overlay tag
     Return the OVERLAY part of TAG.  That is, an overlay or an
     unloaded buffer representation.

     *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.

 - 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.)

    *Note for language authors:*
          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.

 - 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 belonging 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 value &optional append
     Add onto TAG a HOOK with VALUE.

 - Function: semantic-tag-remove-hook tag hook value
     Remove from TAG the HOOK with VALUE.

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.


File: semantic-appdev.info,  Node: Misc Tag Functions,  Next: Tag Internals,  Prev: Tag Overlay,  Up: Semantic Tags

Misc Tag Functions
==================

 - Function: semantic-narrow-to-tag tag
     Narrow to the region specified by TAG.

 - Function: semantic-with-buffer-narrowed-to-current-tag &rest body
     Execute BODY with the buffer narrowed to the current tag.

 - Function: semantic-with-buffer-narrowed-to-tag tag &rest body
     Narrow to TAG, and execute BODY.

 - Function: semantic-tag-add-hook tag hook value &optional append
     Add onto TAG a HOOK with VALUE.

 - Function: semantic-tag-remove-hook tag hook value
     Remove from TAG the HOOK with VALUE.


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-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-attributes-cdr tag
     Return the cons cell whose car is the ATTRIBUTES part of TAG.
     That function is for internal use only.

 - 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.

 - 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.

 - 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.


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...).

 - 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-properties-cdr tag
     Return the cons cell whose car is the PROPERTIES part of TAG.
     That function is for internal use only.

 - 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.

 - 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.

 - 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.

 - 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.


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.

 - 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.

 - 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.

 - 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.

 - 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.

 - 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.

 - Function: semantic-tag-copy-properties tag1 tag2
     Copy private properties from TAG1 to TAG2.  Return TAG2.  This
     function is for internal use only.


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".


File: semantic-appdev.info,  Node: Tags at Point,  Next: Tag Sorting,  Prev: Searching Tag Tables,  Up: Top

Tags at Point
*************

When you need to get the tag the cursor is on, there is a more
efficient mechanism than using `semantic-brute-find-tag-by-position'.
This mechanism directly queries the overlays the parsing step leaves in
the buffer.  This provides for very rapid retrieval of what function or
variable the cursor is currently in.

These functions query the current buffer's overlay system for tags.

 - Function: semantic-find-tag-by-overlay &optional positionormarker
          buffer
     Find all tags covering POSITIONORMARKER by using overlays.  If
     POSITIONORMARKER is `nil', use the current point.  Optional BUFFER
     is used if POSITIONORMARKER is a number, otherwise the current
     buffer is used.  This finds all tags covering the specified
     position by checking for all overlays covering the current spot.
     They are then sorted from largest to smallest via the start
     location.


     *Compatibility*: `semantic-find-tag-by-overlay' introduced in
     semantic version 2.0 supercedes
     `semantic-find-nonterminal-by-overlay' which is now obsolete.

 - Function: semantic-find-tag-by-overlay-in-region start end &optional
          buffer
     Find all tags which exist in whole or in part between START and
     END.  Uses overlays to determine positin.  Optional BUFFER
     argument specifies the buffer to use.


     *Compatibility*: `semantic-find-tag-by-overlay-in-region'
     introduced in semantic version 2.0 supercedes
     `semantic-find-nonterminal-by-overlay-in-region' which is now
     obsolete.

 - Function: semantic-find-tag-by-overlay-next &optional start buffer
     Find the next tag after START in BUFFER.  If START is in an
     overlay, find the tag which starts next, not the current tag.

 - Function: semantic-find-tag-by-overlay-prev &optional start buffer
     Find the next tag before START in BUFFER.  If START is in an
     overlay, find the tag which starts next, not the current tag.

 - Function: semantic-current-tag
     Return the current tag in the current buffer.  If there are more
     than one in the same location, return the smallest tag.  Return
     `nil' if there is no tag here.


     *Compatibility*: `semantic-current-tag' introduced in semantic
     version 2.0 supercedes `semantic-current-nonterminal' which is now
     obsolete.

 - Function: semantic-current-tag-parent
     Return the current tags parent in the current buffer.  A tag's
     parent would be a containing structure, such as a type containing
     a field.  Return `nil' if there is no parent.


     *Compatibility*: `semantic-current-tag-parent' introduced in
     semantic version 2.0 supercedes
     `semantic-current-nonterminal-parent' which is now obsolete.


File: semantic-appdev.info,  Node: Tag Sorting,  Next: Tag Completion,  Prev: Tags at Point,  Up: Top

Tag Sorting
***********

Sometimes it is important to reorganize a tag stream into a form that
is better for display to a user.  It is important to not use functions
with side effects that could effect the tag cache.

There are some existing utility functions which will reorganize the tag
list for you.

 - Function: semantic-unique-tag-table tags
     Scan a list of TAGS, removing duplicates.  This must first sort
     the tags by position ascending.  TAGS are removed only if they are
     equivalent, as can happen when multiple tag sources are scanned.

 - Function: semantic-unique-tag-table-by-name tags
     Scan a list of TAGS, removing duplicate names.  This must first
     sort the tags by name alphabetically ascending.

 - Function: semantic-bucketize tags &optional parent filter
     Sort TAGS into a group of buckets based on tag class.  Unknown
     classes are placed in a Misc bucket.  Type bucket names are
     defined by either `semantic-symbol->name-assoc-list'.  If PARENT
     is specified, then TAGS belong to this PARENT in some way.  This
     will use `semantic-symbol->name-assoc-list-for-type-parts' to
     generate bucket names.  Optional argument FILTER is a filter
     function to be applied to each bucket.  The filter function will
     take one argument, which is a list of tags, and may re-organize
     the list with side-effects.

 - Variable: semantic-bucketize-tag-class
     Function used to get a symbol describing the class of a token.
     This function must take one argument of a semantic token.  It
     should return a symbol found in `semantic-symbol->name-assoc-list'
     which "semantic-bucketize" uses to bin up tokens.  To create new
     bins for an application augment
     `semantic-symbol->name-assoc-list', and
     `semantic-symbol->name-assoc-list-for-type-parts' in addition to
     setting this variable (locally in your function).

 - Function: semantic-adopt-external-members tags
     Rebuild TAGS so that externally defined members are regrouped.
     Some languages such as C++ and CLOS permit the declaration of
     member functions outside the definition of the class.  It is
     easier to study the structure of a program when such methods are
     grouped together more logically.

     This function uses "semantic-nonterminal-external-member-p" to
     determine when a potential child is an externally defined member.

     Note: Applications which use this function must account for tag
     types which do not have a position, but have children which *do*
     have positions.

     Applications should use `semantic-mark-external-member-function'
     to modify all tags which are found as externally defined to some
     type.  For example, changing the tag type for generating extra
     buckets with the bucket function.

 - Variable: semantic-orphaned-member-metaparent-type
     In "semantic-adopt-external-members", the type of `'type' for
     metaparents.  A metaparent is a made-up type semantic tag used to
     hold the child list of orphaned members of a named type.

 - Variable: semantic-mark-external-member-function
     Function called when an externally defined orphan is found.  Be
     default, the tag is always marked with the `adopted' property.
     This function should be locally bound by a program that needs to
     add additional behaviors into the tag list.  This function is
     called with one argument which is a shallow copy of the tag to be
     modified.  This function should return the tag (or a copy of it)
     which is then integrated into the revised tag list.

