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: Lexical Safety, Prev: Parser Hooks, Up: Parser Features Lexical Safety ============== If you application frequenly requests lists of tags upon user request, it may be important to avoid lexical problems that frequenly occur when the user has partially written an expression, such as starting a string, or argument list. You can protect your code from lexical problems with this macro: - Function: semantic-lex-catch-errors symbol &rest forms Using SYMBOL, execute FORMS catching lexical errors. If FORMS results in a call to the parser that throws a lexical error, the error will be caught here without the buffer's cache being thrown out of date. If there is an error, the syntax that failed is returned. If there is no error, then the last value of FORMS is returned. It is important to provide a good SYMBOL so that these macros can nest correctly. If you want your code to run anyway, even if there is a lexical error, using this macro like this: (semantic-lex-catch-errors (semantic-fetch-tags)) will put the parser into the 'unparseable' state, and allow other routines to request the tag table without incurring additional parser attempts.  File: semantic-appdev.info, Node: Semantic Database, Next: Idle Scheduling, Prev: Parser Features, Up: Top Semantic Database ***************** Semanticdb is a database mechanism for storing tags parsed by semantic. The database operates in the background, saving tags as they are parsed between sessions. When a file is read in, and there is a previously created set of tags available for it, sematnicdb will save time by not parsing the file, and using the cached copy. In applications, semanticdb can provide access to the sum of all tags in a project or in the basic system. This database can they be searched using a set of special routines. * Menu: * Semanticdb in Programs:: Basic usage. * Semanticdb Tag Queries:: Searching for tokens in the databases. * System Databases:: Special kinds of databases for system tags.  File: semantic-appdev.info, Node: Semanticdb in Programs, Next: Semanticdb Tag Queries, Up: Semantic Database Semanticdb in Programs:: ======================== If you write a program using semanticdb, you will probably want to make sure it is active in your program. - Function: semanticdb-minor-mode-p Return non-`nil' if `semanticdb-minor-mode' is active. Since semanticdb is optional, it is best if a program can gracefully degrade service when semanticdb is not available, or to throw an error letting the user know it is required to be active. At the simplest level, you can ask if a given file is in the database, recieving a tag table. Semanticdb will give you an accurate set of tags just by asking. - Function: semanticdb-file-stream file Return a list of tags belonging to FILE. If file has database tags available in the database, return them. If file does not have tags available, then load the file, and create them. Alternately, you can get at the table object for a file by asking for it. - Function: semanticdb-file-table-object file &optional dontload Return a semanticdb table belonging to FILE. If file has database tags available in the database, return it. If file does not have tags available, and DONTLOAD is `nil', then load the tags for FILE, and create a new table object for it. DONTLOAD does not affect the creation of new database objects.  File: semantic-appdev.info, Node: Semanticdb Tag Queries, Next: System Databases, Prev: Semanticdb in Programs, Up: Semantic Database Semanticdb Tag Queries ====================== You can search for tags in the semantic database using the semanticdb-find API. It is important to note that database search functions do not return a plain list of tags. This is because some tags may not be loaded in a buffer, which means that the found tag would not have an overlay, and no way to determine where it came from. As such, all search functions return a special Database Results list. There are several types of searches, divided into groups by implementation. While it is possible to add new types of searches, or write custom searches, the built in searches are usually the only ones available in system backends *Note System Databases::. When the term brute or brutish is used as a search criteria, that is distinguishing between an include-path based search, and a search that scans everything available in a project. Non-brute force searches assume that all symbols available in a given buffer are on the search path, or in some file that has been included, imported, or otherwise indicated in the source file itself. While not always true for interpreted languages (such as Emacs Lisp), it is common among declaritive languages. Sometimes a brute force approach is needed, scanning every file available to the database. You may want to do this if your application is collecting data unrelated to a file currently being worked on. * Menu: * DB Results:: Accessing the results of a search. * DB Search Paths:: The list of tables to search. * DB Basic Name Search:: Searches based on name. * DB Basic Brute Search:: Searches on common tag attributes. * DB Advanced Search:: Complex searches on associations * DB Generic Brute Search:: Do It Yourself search criteria  File: semantic-appdev.info, Node: DB Results, Next: DB Search Paths, Up: Semanticdb Tag Queries DB Results ---------- The successful results of a search returns a special list of the following form: ( (DATABASE TAG1 TAG2 ...) (DATABASE2 TAG3 TAG4 ...) ...) It should not be necessary to access the results in this way, however, as there are several routines that can be used to access this list. To turn a semanticdb search result into a simple tag table, use: - Function: semanticdb-strip-find-results results &optional find-file-match Strip a semanticdb search RESULTS to exclude objects. This makes it appear more like the results of a `semantic-find-' call. Optional FIND-FILE-MATCH loads all files associated with RESULTS into buffers. This has the side effect of enabling "semantic-tag-buffer" to return a value. To write a function that accepts a tag table, or a semanticdb search result, use this to test if it is a semanticdb search result: - Function: semanticdb-find-results-p resultp Non-`nil' if RESULTP is in the form of a semanticdb search result. This query only really tests the first entry in the list that is RESULTP, but should be good enough for debugging assertions. - Function: semanticdb-find-result-with-nil-p resultp Non-`nil' of RESULTP is in the form of a semanticdb search result. `nil' is a valid value where a TABLE usually is, but only if the TAG results include overlays. This query only really tests the first entry in the list that is RESULTP, but should be good enough for debugging assertions. To operate on the search results as though it were a simple tags table, or plain list, use these routines. - Function: semanticdb-find-result-length result Number of tags found in RESULT. - Function: semanticdb-find-result-nth result n In RESULT, return the Nth search result. This is a 0 based search result, with the first match being element 0. The returned value is a cons cell: (TAG . TABLE) where TAG is the tag at the Nth position. TABLE is the semanticdb table where the TAG was found. Sometimes TABLE can be `nil'. - Function: semanticdb-find-result-nth-in-buffer result n In RESULT, return the Nth search result. Like "semanticdb-find-result-nth", except that only the TAG is returned, and the buffer it is found it will be made current. If the result tag has no position information, the originating buffer is still made current.  File: semantic-appdev.info, Node: DB Search Paths, Next: DB Basic Name Search, Prev: DB Results, Up: Semanticdb Tag Queries DB Search Paths --------------- For searches based on an include path (non-brutish) a path of tables needs to be generated. Searching a lot of tables is slow, which is why a brutish search is not always recommended. An include-based approach can also generate a lot of tables, so you can control how detailed a search is with a throttle variable. Ideally, each language mode will have a mode-specific value for this throttle value. A user can also specify their own values if the default is not good enough. - Variable: semanticdb-find-default-throttle The default throttle for `semanticdb-find' routines. The throttle controls how detailed the list of database tables is for a symbol lookup. The value is a list with the following keys: `file' The file the search is being performed from. This option is here for completeness only, and is assumed to always be on. `local' Tables from the same local directory are included. This includes files directly referenced by a file name which might be in a different directory. `project' Tables from the same local project are included If `project' is specified, then `local' is assumed. `unloaded' If a table is not in memory, load it. If it is not cached on disk either, get the source, parse it, and create the table. `system' Tables from system databases. These are specifically tables from system header files, or language equivalent. `recursive' For include based searches, includes tables referenced by included files. `omniscience' Included system databases which are omniscience, or somehow know everything. Omniscience databases are found in `semanticdb-project-system-databases'. The Emacs Lisp system DB is an omniscience database. You can use the command `semanticdb-find-test-translate-path' to interactively test out how the path translator is working. The path translation routines are: - Function: semanticdb-find-translate-path path brutish Translate PATH into a list of semantic tables. Path translation involves identifying the PATH input argument in one of the following ways: `nil' - Take the current buffer, and use it's include list buffer - Use that buffer's include list. filename - Use that file's include list. If the file is not in a buffer, see of there is a semanticdb table for it. If not, read that file into a buffer. tag - Get that tag's buffer of file file. See above. table - Search that table, and it's include list. find result - Search the results of a previous find. In addition, once the base path is found, there is the possibility of each added table adding yet more tables to the path, so this routine can return a lengthy list. If argument BRUTISH is non-`nil', then instead of using the include list, use all tables found in the parent project of the table identified by translating PATH. Such searches use brute force to scan every available table. The return value is a list of objects of type "semanticdb-table" or it's children. In the case of passing in a find result, the result is returned unchanged. This routine uses "semanticdb-find-table-for-include" to translate specific include tags into a semanticdb table. This function can be overloaded (see "define-mode-local-override" for details). - Function: semanticdb-find-table-for-include includetag &optional table For a single INCLUDETAG found in TABLE, find a "semanticdb-table" object INCLUDETAG is a semantic TAG of class `'include'. TABLE as defined by "semantic-something-to-tag-table" to identify where the tag came from. TABLE is optional if INCLUDETAG has an overlay of `:filename' attribute. This function can be overloaded (see "define-mode-local-override" for details).  File: semantic-appdev.info, Node: DB Basic Name Search, Next: DB Basic Brute Search, Prev: DB Search Paths, Up: Semanticdb Tag Queries DB Basic Name Search -------------------- These searches scan a database table collection for tags based on name. They are divided into normal and deep searches. A deep search, as with in buffer tag scanning, implies that all entries are scanned, including those in type declarations. Normal Searches: - Function: semanticdb-find-tags-by-name name &optional path find-file-match Search for all tags matching NAME on PATH. See "semanticdb-find-translate-path" for details on PATH. FIND-FILE-MATCH indicates that any time a match is found, the file associated with that tag should be loaded into a buffer. - Function: semanticdb-find-tags-by-name-regexp regexp &optional path find-file-match Search for all tags matching REGEXP on PATH. See "semanticdb-find-translate-path" for details on PATH. FIND-FILE-MATCH indicates that any time a match is found, the file associated with that tag should be loaded into a buffer. - Function: semanticdb-find-tags-for-completion prefix &optional path find-file-match Search for all tags matching PREFIX on PATH. See "semanticdb-find-translate-path" for details on PATH. FIND-FILE-MATCH indicates that any time a match is found, the file associated with that tag should be loaded into a buffer. - Function: semanticdb-find-tags-by-class class &optional path find-file-match Search for all tags of CLASS on PATH. See "semanticdb-find-translate-path" for details on PATH. FIND-FILE-MATCH indicates that any time a match is found, the file associated with that tag should be loaded into a buffer. Deep Searches: - Function: semanticdb-deep-find-tags-by-name name &optional path find-file-match Search for all tags matching NAME on PATH. Search also in all components of top level tags founds. See "semanticdb-find-translate-path" for details on PATH. FIND-FILE-MATCH indicates that any time a match is found, the file associated with that tag should be loaded into a buffer. - Function: semanticdb-deep-find-tags-by-name-regexp regexp &optional path find-file-match Search for all tags matching REGEXP on PATH. Search also in all components of top level tags founds. See "semanticdb-find-translate-path" for details on PATH. FIND-FILE-MATCH indicates that any time a match is found, the file associated with that tag should be loaded into a buffer. - Function: semanticdb-deep-find-tags-for-completion prefix &optional path find-file-match Search for all tags matching PREFIX on PATH. Search also in all components of top level tags founds. See "semanticdb-find-translate-path" for details on PATH. FIND-FILE-MATCH indicates that any time a match is found, the file associated with that tag should be loaded into a buffer.  File: semantic-appdev.info, Node: DB Basic Brute Search, Next: DB Advanced Search, Prev: DB Basic Name Search, Up: Semanticdb Tag Queries DB Basic Brute Search --------------------- These searches allow searching on specific attributes of tags, such as name, type, or other attribute. - Function: semanticdb-brute-deep-find-tags-by-name name &optional path find-file-match Search for all tags matching NAME on PATH. See "semanticdb-find-translate-path" for details on PATH. The argument BRUTISH will be set so that searching includes all tables in the current project. FIND-FILE-MATCH indicates that any time a matchi is found, the file associated wit that tag should be loaded into a buffer.  File: semantic-appdev.info, Node: DB Advanced Search, Next: DB Generic Brute Search, Prev: DB Basic Brute Search, Up: Semanticdb Tag Queries DB Advanced Search ------------------ These are searches that were needed to accomplish some specialized tasks as discovered in utilities. Advanced searches include matching methods defined outside some parent class. The reason for advanced searches are so that external repositories such as the Emacs obarray, or java `.class' files can quickly answer these needed questions without dumping the entire symbol list into Emacs for a regular semanticdb search. - Function: semanticdb-find-tags-external-children-of-type type &optional path find-file-match Search for all tags defined outside of TYPE w/ TYPE as a parent. See "semanticdb-find-translate-path" for details on PATH. FIND-FILE-MATCH indicates that any time a match is found, the file associated with that tag should be loaded into a buffer.  File: semantic-appdev.info, Node: DB Generic Brute Search, Prev: DB Advanced Search, Up: Semanticdb Tag Queries DB Generic Brute Search ----------------------- The generic search, "semanticdb-find-nonterminal-by-function" will call your function with every tag available. (Very slow for system databases.) NOTE: There is no such function. Hopefully we can get away without implementing one, which will make system databases more useful. If you are really stuck, you can use the following, though I don't recommend it. - Function: semanticdb-find-tags-collector function &optional path find-file-match brutish Search for all tags returned by FUNCTION over PATH. See "semanticdb-find-translate-path" for details on PATH. FIND-FILE-MATCH indicates that any time a match is found, the file associated with that tag should be loaded into a buffer. If optional argument BRUTISH is non-`nil', then ignore include statements, and search all tables in this project tree.  File: semantic-appdev.info, Node: System Databases, Prev: Semanticdb Tag Queries, Up: Semantic Database System Databases ================ System Databases are special implementations of the database and table API which make some external tag source appear as though it were a normal buffer with semantic parsed tags available. Search routines for these databases return a special type of table not associated with a file. It is important to be aware of this possible return value. - Type: semanticdb-project-database-emacs-lisp Database representing Emacs core. This Emacs database is loaded automatically. - Type: semanticdb-project-database-ebrowse Semantic Database deriving tags using the EBROWSE tool. EBROWSE is a C/C++ parser for use with `ebrowse' Emacs program. To create new EBROWSE project databases, use: - Command: semanticdb-create-ebrowse-database dir Create an EBROSE database for directory DIR. The database file is stored in ~/.semanticdb, or whichever directory is specified by `semanticdb-default-system-save-directory'. Semantic Parsed System Databases -------------------------------- Another kind of system database is one created by the semantic tools, but saved in a special way. These databases are created with a script, or at some other convenient time. They can then be searched normally. They will appear on the same list of system databases as back ends that refer to object files indirectly. A simple way to create one from Emacs is with this function: - Command: semanticdb-create-system-database path &optional class Create a system database starting at PATH. PATH should be a top level directory for a series of files containing declarations for SYSTEM files. In C, this would be header filaes. CLASS is the class for the database to create. Only child classes of symbol "semanticdb-project-database-system" are accepted.  File: semantic-appdev.info, Node: Idle Scheduling, Next: Example Programs, Prev: Semantic Database, Up: Top Idle Scheduling *************** The Semantic Idle Scheduler is a minor mode which performs semantic specific tasks in idle time. See *note (semantic-user.info)Idle Scheduler::. It performs the following tasks in order: 1. Reprarse the current buffer if needed 2. Reparse other buffers that need it 3. Execute other scheduled semantic related operations. Care is take in the idle scheduler to exit immediatly if user input is detected, improving editing performance. The reason for grouping these tasks together is so that the automatic reparsing code executes before other idle services. This allows lexically broken buffers to be detected so that the other applications that follow do not accidentally reparse the buffer leaving unmatched syntax all over. You can create new minor modes that are automatically scheduled by the semantic idle scheduler. Create the new minor mode with: - Function: define-semantic-idle-service name doc &rest forms Create a new idle services with NAME. DOC will be a documentation string describing FORMS. FORMS will be called during idle time after the current buffer's semantic tag information has been updated. This routines creates the following functions and variables: User Input Handling =================== When writing an idle service, it is important for tasks that can take a long time to correctly exit upon user input. You can test for user input in your idle handler with the following routines: - Function: semantic-throw-on-input from Exit with "throw" when in "semantic-exit-on-input" on user input. FROM is an indication of where this function is called from as a value to pass to "throw". It is recommended to use the name of the function calling this one. If you need to carefully extract from your function, you can wrap just a section of your function to exit on user input by wrapping it with this macro: - Function: semantic-exit-on-input symbol &rest forms Using SYMBOL as an argument to "throw", execute FORMS. If FORMS includes a call to `semantic-thow-on-input', then if a user presses any key during execution, this form macro will exit with the value passed to "semantic-throw-on-input". If FORMS completes, then the return value is the same as "progn". Upon catching user input, you can try to detect if there was an exit from the return argument, and continue throwing with an additional call to `semantic-throw-on-input'.  File: semantic-appdev.info, Node: Example Programs, Next: Current Context, Prev: Idle Scheduling, Up: Top Programming Examples ******************** *** NOTE *** These examples are for semantic 1.4. Using the below functions will generate compile time warnings with advice on what functions to use in semantic 2.0. Here are some simple examples that use different aspects of the semantic library APIs. For fully functional example programs with lots of comments, see the file `semantic-examples.el'. Interactively querying for a token name ======================================= If you need a command that asks the user for a token name, you can get full range completion using the query functions *Note Tag Completion::. (interactive (list (semantic-read-symbol "Symbol: "))) Finding a symbol in a buffer ============================ If you have the name of a function or variable, and need to find its location in a buffer, you need a search function. There is a wide range of searches you can perform *Note Searching Tag Tables::. (semantic-find-nonterminal-by-name "some-name" (current-buffer) t ;; look inside structures and classes for these symbols nil) ;; do not look inside header files. Finding a symbol in a project ============================= If you have the name of a function or variable, and need to find its location somewhere in a project, you need to use the Semantic Database *note (semanticdb)semanticdb::. There are many search functions similar to the ones found in *Note Searching Tag Tables::. The Semantic Database is interesting in that the return structure is not Locating a token in a buffer ============================ If you have a nonterminal token, or a list of them, you may want to find their position in a buffer. (semanticdb-find-nonterminal-by-name "symbol" nil ;; Defaults to the current project's database list. t ;; Search inside types nil ;; Do not search include files nil ;; Only search files in the same mode (all C files) t ;; When a token is found, make sure it is loaded in a buffer. ) Of interesting note above, semanticdb can find symbols in files that are not loaded into an Emacs buffer. These tokens do not have an associated overlay, and the function "semantic-token-buffer" will fail. The last parameter's tells the search function to "find-file-noselect" any file in which a matching token was found. This will allow you to merge all the tokens into a completion list, or other flat list needed by most functions that use association lists. If you do not ask semanticdb to load those files, you will need to explicitly request the database object (found in the `car' of each sublist) get the file loaded. It is useful to not auto find all files if you don't need to jump to that token. Converting a token into a human readable string. ================================================ A tag is a rather unpleasant Lisp structure when trying to decipher what is going on. As such, there is a wide range of functions available that can convert a token into a human readable, and colorful string *Note Format Tag::. If you program interfaces with lots of users, you will probably want to have your program define a configurable variable that will let users change the visible portion of your program. (defcustom my-summary-function 'semantic-uml-prototype-nonterminal "*Function to use when showing info about my tag." :group 'my-program :type semantic-format-tag-custom-list) Note the special type provided by Semantic. Next, you can call this function to create a string. (funcall my-summary-function tag tag-parent t ; use color ) In this case, TAG-PARENT is an optional argument. In many cases, parent is not used by the outputting function. The parent must be a tag whose `semantic-tag-componenets' contains TAG, or nil for top-level definitions. In particular, C++ needs the parent to correctly calculate the protection of each method.  File: semantic-appdev.info, Node: Current Context, Next: App Debugger, Prev: Example Programs, Up: Top Deriving the Current Context **************************** This chapter deals with how to derive the current context, and also how a language maintainer can get the current context API to work with their language. By default, the behavior will function in C like languages. This means languages with parenthetical blocks, and type dereferencing which uses a similar form. * Menu: * Blocks:: * Local Variables:: Getting lists of local variables. * Derived Context:: What goes at a given location? * Context Analysis:: Analysis information about the local context.  File: semantic-appdev.info, Node: Blocks, Next: Local Variables, Up: Current Context Blocks and Navigation ===================== Source code is typically built up of control structures, and blocks of context, or lexical scope. Semantic terms these lexical scopes as a "context". The following functions can be used to navigate contexts. Some of them are override functions. Language authors can override a subset of them to make them work for their language. - Function: semantic-up-context &optional point bounds-type Move point up one context from POINT. Return non-`nil' if there are no more context levels. Overloaded functions using `up-context' take no parameters. BOUNDS-TYPE is a symbol representing a tag class to restrict movement to. If this is `nil', `'function' is used. This will find the smallest tag of that class (function, variable, type, etc) and make sure non-`nil' is returned if you cannot go up past the bounds of that tag. This function can be overloaded (see "define-mode-local-override" for details). - Function: semantic-beginning-of-context &optional point Move POINT to the beginning of the current context. Return non-`nil' if there is no upper context. The default behavior uses "semantic-up-context". This function can be overloaded (see "define-mode-local-override" for details). - Function: semantic-end-of-context &optional point Move POINT to the end of the current context. Return non-`nil' if there is no upper context. Be default, this uses "semantic-up-context", and assumes parenthetical block delimiters. This function can be overloaded (see "define-mode-local-override" for details). These next set of functions can be used to navigate across commands. - Function: semantic-end-of-command Move to the end of the current command. Be default, uses `semantic-command-separation-character'. This function can be overloaded (see "define-mode-local-override" for details). - Function: semantic-beginning-of-command Move to the beginning of the current command. Be default, uses `semantic-command-separation-character'. This function can be overloaded (see "define-mode-local-override" for details).  File: semantic-appdev.info, Node: Local Variables, Next: Derived Context, Prev: Blocks, Up: Current Context Deriving local variables ======================== Within a given context, or block of code, local variables are often defined. These functions can be used to retrieve lists of locally scoped variables. - Function: semantic-get-local-variables &optional point Get the local variables based on POINT's context. Local variables are returned in Semantic tag format. This can be overriden with `get-local-variables'. This function can be overloaded (see "define-mode-local-override" for details). - Function: semantic-get-local-arguments &optional point Get arguments (variables) from the current context at POINT. Parameters are available if the point is in a function or method. Return a list of tags unlinked from the originating buffer. Arguments are obtained by overriding `get-local-arguments', or by the default function "semantic-get-local-arguments-default". This, must return a list of tags, or a list of strings that will be converted to tags. This function can be overloaded (see "define-mode-local-override" for details). - Function: semantic-get-all-local-variables &optional point Get all local variables for this context, and parent contexts. Local variables are returned in Semantic tag format. Be default, this gets local variables, and local arguments. Optional argument POINT is the location to start getting the variables from. This function can be overloaded (see "define-mode-local-override" for details).  File: semantic-appdev.info, Node: Derived Context, Next: Context Analysis, Prev: Local Variables, Up: Current Context Deriving the Current Context ============================ While a context has already been used to describe blocks of code, other context include more local details, such as the symbol the cursor is on, or the fact we are assigning into some other variable. These context deriving functions can be overridden to provide language specific behavior. By default, it assumes a C like language. - Function: semantic-ctxt-current-symbol &optional point Return the current symbol the cursor is on at POINT in a list. This will include a list of type/field names when applicable. This function can be overloaded (see "define-mode-local-override" for details). - Function: semantic-ctxt-current-assignment &optional point Return the current assignment near the cursor at POINT. Return a list as per "semantic-ctxt-current-symbol". Return `nil' if there is nothing relevant. This function can be overloaded (see "define-mode-local-override" for details). - Function: semantic-ctxt-current-function &optional point Return the current function call the cursor is in at POINT. The function returned is the one accepting the arguments that the cursor is currently in. It will not return function symbol if the cursor is on the text representing that function. This function can be overloaded (see "define-mode-local-override" for details). - Function: semantic-ctxt-current-argument &optional point Return the index of the argument position the cursor is on at POINT. This function can be overloaded (see "define-mode-local-override" for details). - Function: semantic-ctxt-current-thing Calculate a thing identified by the current cursor position. Calls previously defined `semantic-ctxt-current-...' calls until something gets a match. See "semantic-ctxt-current-symbol", "semantic-ctxt-current-function", and "semantic-ctxt-current-assignment" for details on the return value. - Function: semantic-ctxt-current-class-list &optional point Return a list of tag classes that are allowed at POINT. If POINT is `nil', the current buffer location is used. For example, in Emacs Lisp, the symbol after a ( is most likely a function. In a makefile, symbols after a : are rules, and symbols after a $( are variables. This function can be overloaded (see "define-mode-local-override" for details). - Function: semantic-ctxt-scoped-types &optional point Return a list of type names currently in scope at POINT. The return value can be a mixed list of either strings (names of types that are in scope) or actual tags (type declared locally that may or may not have a name.) This function can be overloaded (see "define-mode-local-override" for details).  File: semantic-appdev.info, Node: Context Analysis, Prev: Derived Context, Up: Current Context Analysis of the current context =============================== The context parsing API is used in a context analysis library. This library provides high level routines for scanning through token databases to create lists of token associates. At it's core is a set of EIEIO classes defining a context. The context contains information about what was parsed at a given position, such as the strings there, and they type of assignment. The analysis library then searches the databases to determine the types and names available. Two high level functions which can be run interactively are: - Command: semantic-analyze-current-context &optional position Analyze the current context at optional POSITION. If called interactively, display interesting information about POSITION in a separate buffer. Returns an object based on symbol "semantic-analyze-context". This function can be overriden with the symbol `analyze-context'. When overriding this function, your override will be called while cursor is at POSITION. In addition, your function will not be called if a cached copy of the return object is found. This function can be overloaded (see "define-mode-local-override" for details). - Command: semantic-analyze-possible-completions context Return a list of semantic tags which are possible completions. CONTEXT is either a position (such as point), or a precalculated context. Passing in a context is useful if the caller also needs to access parts of the analysis. Completions run through the following filters: * Elements currently in scope * Constants currently in scope * Elements match the `:prefix' in the CONTEXT. * Type of the completion matches the type of the context. Context type matching can identify the following: * No specific type * Assignment into a variable of some type. * Argument to a function with type constraints. When called interactively, displays the list of possible completions in a buffer. This function can be overloaded (see "define-mode-local-override" for details). * Menu: * Analysis Overview:: A description of how the analyzer works. * Analysis Objects:: What is in the analysis object. * Completion Overview:: How completions are calculated.  File: semantic-appdev.info, Node: Analysis Overview, Next: Analysis Objects, Up: Context Analysis Analysis Overview ----------------- The semantic analysis function "semantic-analye-current-context" creates an Analysis Object. See *Note Analysis Objects::. This object contains many useful pieces of information needed to do any other kind of intelligent action on the local context. If you call this function interactively, it will popup a buffer with a summary of the return value. This is useful when debugging. +--------+ +----------------+ +----------------------------+ | Buffer |---| Context Parser |---| Local Context Synax Result | +--------+ +----------------+ +----------------------------+ | | +--------+ +-----------+ | | Parser |---| Tag Table |------------+ | +--------+ +-----------+ | | V V +-------------+ +-------------------+ | Semantic DB |-------------------->| Semantic Analyzer | +-------------+ +-------------------+ | V +-----------------+ | Analysis Object | +-----------------+  File: semantic-appdev.info, Node: Analysis Objects, Next: Completion Overview, Prev: Analysis Overview, Up: Context Analysis Analysis Objects ----------------  File: semantic-appdev.info, Node: Completion Overview, Prev: Analysis Objects, Up: Context Analysis Completion Overview -------------------  File: semantic-appdev.info, Node: App Debugger, Next: GNU Free Documentation License, Prev: Current Context, Up: Top Application level Data structure debugger ***************************************** The data structures that Semantic provides can be complex, and figuring out why some level of application API performs incorrectly can be difficult. The semantic Application debugger provides a way to look inside the various data structures of Semantic in a structures and complete way to help identify what a problem may be. App Debugger Entry Points ========================= There are a few basic functions that enter into the debugger: - Command: semantic-adebug-bovinate The same as "bovinate". Display the results in a debug buffer. - Command: semantic-adebug-searchdb regex Search the semanticdb for REGEX for the current buffer. Display the results as a debug list. - Command: semantic-adebug-analyze Perform "semantic-analyze-current-context". Display the results as a debug list. adebug-mode =========== The semantic debugger mode provides a simple user facing UI for looking into the data structures. - Command: semantic-adebug-mode Major-mode for the Analyzer debugger. Keybindings: `spc' semantic-adebug-expand-or-contract `n' semantic-adebug-next-expando `p' semantic-adebug-prev-expando `n' semantic-adebug-next `p' semantic-adebug-prev `' semantic-adebug-expand-or-contract-mouse Create new debugger entry commands ================================== Creating a new Application debugger entry point is easy. First, get a datastructure you need to analyze. The first function to call is: - Function: semantic-adebug-new-buffer name Create a new adebug buffer with NAME. Next, you need to find the correct function for inserting your datastructure. All adebug insertion functions are of the form `semantic-adebug-insert-THING', where THING is whatever you object is. Use Emacs help to pick something out.