This is semantic.info, produced by makeinfo version 4.2 from semantic.texi. START-INFO-DIR-ENTRY * semantic: (semantic). Semantic Parsing for Emacs END-INFO-DIR-ENTRY  File: semantic.info, Node: Style Guide, Prev: Examples, Up: BNF conversion Semantic Token Style Guide ========================== In order for a generalized program using Semantic to work with multiple languages, it is important to have a consistent meaning for the contents of the tokens returned. The variable `semantic-toplevel-bovine-table' is documented with the complete list of a tokens that a functional or OO language may use. While any given language is free to create their own tokens, such a language definition would not produce a stream of tokens usable by a generalized tool. Minimum Requirements ==================== In general, all tokens returned from a parser should be generated with the following form: ("NAME" type-symbol ... "DOCSTRING" PROPERTIES OVERLAY) NAME and TYPE-SYMBOL are the only syntactic elements of a nonterminal which are guaranteed to exist. This means that a parser which uses `nil' for either of these two slots, or some value which is not type consistent is wrong. NAME is also guaranteed to be a string. This string represents the name of the nonterminal, usually a named definition which the language will use elsewhere as a reference to the syntactic element found. TYPE-SYMBOL is a symbol representing the type of the nonterminal. Valid TYPE-SYMBOLs can be anything, as long is it is an Emacs Lisp symbol. DOCSTRING is a required slot in the nonterminal, but can be nil. Some languages have the documentation saved as a comment nearby. In these cases, DOCSTRING is nil, and the function `semantic-find-documentation'. PROPERTIES is a slot generated by the semantic parser harness, and need not be provided by a language author. Programmatically access nonterminal properties with `semantic-token-put' and `semantic-token-get' to access properties. OVERLAY represents positional information for this token. It is automatically generated by the semantic parser harness, and need not be provided by the language author, unless they provide a nonterminal expansion function via `semantic-expand-nonterminal'. The OVERLAY property is accessed via several functions returning the beginning, end, and buffer of a token. Use these functions unless the overlay is really needed (see *Note Token Queries::). 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 token belongs to is not in memory. This happens when a using has activated the Semantic Database *Note semanticdb::. Nonterminals for Functional Languages. ====================================== If a parser produces tokens for a functional language, then the following token formats are available. Variable `("NAME" variable "TYPE" DEFAULT-VALUE EXTRA-SPEC' ` "DOCSTRING" PROPERTIES OVERLAY)' TYPE is a string representing the type of this variable. TYPE can be `nil' for untyped languages. Languages which support variable declarations without a type (Such as C) should supply a string representing the default type for that language. DEFAULT-VALUE can be a string, or something pre-parsed and language specific. Hopefully this slot will be better defined in future versions of Semantic. EXTRA-SPEC are extra specifiers. See below. Function ` ("NAME" function "TYPE" ( ARG-LIST ) EXTRA-SPEC' ` "DOCSTRING" PROPERTIES OVERLAY)' TYPE is a string representing the return type of this function or method. TYPE can be `nil' for untyped languages, or for procedures in languages which support functions with no return data. See above for more. ARG-LIST is a list of arguments passed to this function. Each element in the arg list can be one of the following: Semantic Token A full semantic token with positional information. A partial semantic token Partial tokens may contain the NAME slot, TOKEN-SYMBOL, and possibly a TYPE. String A string representing the name of the argument. Common in untyped languages. Type Declaration ` ("NAME" type "TYPE" ( PART-LIST ) ( PARENTS ) EXTRA-SPEC' ` "DOCSTRING" PROPERTIES OVERLAY)' TYPE a string representing the of the type, such as (in C) "struct", "union", "enum", "typedef", or "class". The TYPE for a type token should not be nil, as even untyped languages with structures have type types. PART-LIST is the list of individual entries inside compound types. Structures, for example, can contain several fields which can be represented as variables. Valid entries in a PART-LIST are: Semantic Token A full semantic token with positional information. A partial semantic token Partial tokens may contain the NAME slot, TOKEN-SYMBOL, and possibly a TYPE. String A string representing the name of the slot or field. Common in untyped languages. PARENTS represents a list of parents of this type. Parents are used in two situations. Inheritance For types which inherit from other types of the same type-type (Such as classes). Aliases For types which are aliases of other types, the parent type is the type being aliased. The Types' type is the command specifying that it is an alias (Such as "typedef" in C or C++). The structure of the PARENTS list is of this form: ( 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. Include files `("FILE" include SYSTEM "DOCSTRING" PROPERTIES OVERLAY)' A statement which gets additional definitions from outside the current file, such as an `#include' statement in C. In this case, instead of NAME, a FILE is specified. FILE can be a subset of the actual file to be loaded. SYSTEM is true if this include is part of a set of system includes. This field isn't currently being used and may be eliminated. Package & Provide statements `("NAME" package DETAIL "DOCSTRING" PROPERTIES OVERLAY)' A statement which declares a given file is part of a package, such as the Java `package' statement, or a `provide' in Emacs Lisp. DETAIL might be an associated file name, or some other language specific bit of information. Extra Specifiers ================ Some default token types have a slot EXTRA-SPEC, for extra specifiers. These specifiers provide additional details not commonly used, or not available in all languages. This list is an alist, and if a given key is nil, it is not in the list, saving space. Some valid extra specifiers are: `(parent . "text")' Name of a parent type/class. This is not the same as a parent for a type. In C++ and CLOS allow the creation of a function outside the body of that class. Such functions will set the PARENT specifier to a plain text string which is the name of that parent. `(dereference . INT)' Number of levels of dereference. In C, the number of array dimensions. `(pointer . INT)' Number of levels of pointers. In C, the number of `*' characters. `(typemodifiers . ( "text" ... ))' Keyword modifiers for a type. In C, such words would include `register'' and `volatile'' `(suffix . "text")' Suffix information for a variable. Not currently used. `(const . t)' This exists if the variable or function return value is constant. `(throws . ( "text" ... ))' For functions or methods in languages that support typed signal throwing, this is a list of exceptions that can be thrown. `(destructor . t)' This exists for functions which are destructor methods in a class definition. In C++, a destructor's name excludes the ~ character. When producing the name of the function, the ~ is added back in. `(constructor . t)' This exists for functions which are constructors in a class definition. In C++ this is t when the name of this function is the same as the name of the parent class. `(user-visible . t)' For functions in interpreted languages such as Emacs Lisp, this signals that a function or variable is user visible. In Emacs Lisp, this means a function is "interactive". `(prototype . t)' For functions or variables that are not declared locally, a prototype is something that will define that function or variable for use. In C, the term represents prototypes generally used in header files. In Emacs Lisp, the `autoload' statement creates prototypes.  File: semantic.info, Node: Compiling, Next: Debugging, Prev: BNF conversion, Up: Top Compiling a language file with the bovinator ******************************************** From a program you can use the function `semantic-bovinate-toplevel'. This function takes one optional parameter specifying if the cache should be refreshed. By default, the cached results of the last parse are always used. Specifying that the cache should be checked will cause it to be flushed if it is out of date. Another function you can use is `semantic-bovinate-nonterminal'. This command takes a token stream returned by the function `semantic-flex' followed by a DEPTH (as above). This takes an additional optional argument of NONTERMINAL which is the nonterminal in your table it is to start parsing with. - Command: bovinate &optional clear Bovinate the current buffer. Show output in a temp buffer. Optional argument CLEAR will clear the cache before bovinating. - Command: semantic-clear-toplevel-cache Clear the toplevel bovine cache for the current buffer. Clearing the cache will force a complete reparse next time a token stream is requested. - Function: semantic-bovinate-toplevel &optional checkcache Bovinate the entire current buffer. If the optional argument CHECKCACHE is non-`nil', then flush the cache iff there has been a size change.  File: semantic.info, Node: Debugging, Next: Programming, Prev: Compiling, Up: Top Debugging ********* Writing language files using BNF is significantly easier than writing then using regular expressions in a functional manner. Debugging them, however, can still prove challenging. There are two ways to debug a language definition if it is not behaving as expected. One way is to debug against the source `.bnf' file. The second is to debug against the lisp table created from the `.bnf' source, or perhaps written by hand. If your language definition was written in BNF notation, debugging is quite easy. The command `bovinate-debug' will start you off. - Command: bovinate-debug Bovinate the current buffer and run in debug mode. If you prefer debugging against the Lisp table, find the table in a buffer, place the cursor in it, and use the command `semantic-bovinate-debug-set-table' in it. - Command: semantic-bovinate-debug-set-table &optional clear Set the table for the next debug to be here. Optional argument CLEAR to unset the debug table. After the table is set, the `bovinate-debug' command can be run at any time for the given language. While debugging, two windows are visible. One window shows the file being parsed, and the syntactic token being tested is highlighted. The second window shows the table being used (either in the BNF source, or the Lisp table) with the current rule highlighted. The cursor will sit on the specific match rule being tested against. In the minibuffer, a brief summary of the current situation is listed. The first element is the syntactic token which is a list of the form: (TYPE START . END) The rest of the display is a list of all strings collected for the currently tested rule. Each time a new rule is entered, the list is restarted. Upon returning from a rule into a previous match list, the previous match list is restored, with the production of the dependent rule in the list. Use `C-g' to stop debugging. There are no commands for any fancier types of debugging.  File: semantic.info, Node: Programming, Next: Current Context, Prev: Debugging, Up: Top Programming *********** Once a source file has been parsed, the following APIs can be used to write programs that use the token stream most effectively. * Menu: * Token Queries:: Getting info about a parsed token (nonterminal). * Nonterminal Streams:: Working with streams of nonterminals. * Nonterminals at point:: Finding nonterminals at point. * Nonterminal Sorting:: Reorganizing streams. * Nonterminal Completion:: Completing read functions. * Override Methods:: Language dependent functions covering conversion to text strings, language dependent queries and local context information * Parser Hooks:: How to know when tags change. * Example Programs:: Simple programming examples.  File: semantic.info, Node: Token Queries, Next: Nonterminal Streams, Prev: Programming, Up: Programming Token Queries ============= When writing programs that use the bovinator, the following functions are needed to find get details out of a nonterminal. - Function: semantic-equivalent-tokens-p token1 token2 Compare TOKEN1 and TOKEN2 and return non-`nil' if they are equivalent. Use "eq" to test of two tokens are the same. Use this function if tokens are being copied and regrouped to test for if two tokens represent the same thing, but may be constructed of different cons cells. - Function: semantic-token-token token Retrieve from TOKEN the token identifier. i.e., the symbol `'variable', `'function', `'type', or other. - Function: semantic-token-name token Retrieve the name of TOKEN. - Function: semantic-token-docstring token &optional buffer Retrieve the documentation of TOKEN. Optional argument BUFFER indicates where to get the text from. If not provided, then only the POSITION can be provided. - Function: semantic-token-overlay token Retrieve the OVERLAY part of TOKEN. The returned item may be an overlay or an unloaded buffer representation. - Function: semantic-token-extent token Retrieve the extent (START END) of TOKEN. - Function: semantic-token-start token Retrieve the start location of TOKEN. - Function: semantic-token-end token Retrieve the end location of TOKEN. - Function: semantic-token-type token Retrieve the type of TOKEN. - Function: semantic-token-put token property value On TOKEN, set PROPERTY to VALUE. - Function: semantic-token-get token property For TOKEN get the value of PROPERTY. - Function: semantic-token-extra-spec token spec Retrieve a specifier for the variable TOKEN. SPC is the symbol whose modifier value to get. This function can get specifiers from any type of TOKEN. Do not use this function if you know what type of token you are dereferencing. Instead, use the function specific to that token type. It will be faster. - Function: semantic-token-type-parts token Retrieve the parts of the type TOKEN. - Function: semantic-token-type-parent token Retrieve the parent of the type TOKEN. The return value is a list. A value of `nil' means no parents. The "car" of the list is either the parent class, or a list of parent classes. The "cdr" of the list is the list of interfaces, or abstract classes which are parents of TOKEN. - Function: semantic-token-type-parent-superclass token Retrieve the parent super classes of type type TOKEN. - Function: semantic-token-type-parent-implement token Retrieve the parent interfaces of type type TOKEN. - Function: semantic-token-type-modifiers token Retrieve the type modifiers for the type TOKEN. - Function: semantic-token-type-extra-specs token Retrieve the extra specifiers for the type TOKEN. - Function: semantic-token-type-extra-spec token spec Retrieve a extra specifier for the type TOKEN. SPEC is the symbol whose modifier value to get. - Function: semantic-token-function-args token Retrieve the arguments of the function TOKEN. - Function: semantic-token-function-modifiers token Retrieve the type modifiers of the function TOKEN. - Function: semantic-token-function-destructor token Non-`nil' if TOKEN is a destructor function. - Function: semantic-token-function-extra-specs token Retrieve the extra specifiers of the function TOKEN. - Function: semantic-token-function-extra-spec token spec Retrieve a specifier for the function TOKEN. SPEC is a symbol whose specifier value to get. - Function: semantic-token-function-throws token Retrieve the throws signal of the function TOKEN. This is an optional field, and returns `nil' if it doesn't exist. - Function: semantic-token-function-parent token The parent of the function TOKEN. A function has a parent if it is a method of a class, and if the function does not appear in body of its parent class. - Function: semantic-token-variable-const token Retrieve the status of constantness from the variable TOKEN. - Function: semantic-token-variable-default token Retrieve the default value of the variable TOKEN. - Function: semantic-token-variable-modifiers token Retrieve type modifiers for the variable TOKEN. - Function: semantic-token-variable-extra-specs token Retrieve extra specifiers for the variable TOKEN. - Function: semantic-token-variable-extra-spec token spec Retrieve a specifier value for the variable TOKEN. SPEC is the symbol whose specifier value to get. - Function: semantic-token-include-system token Retrieve the flag indicating if the include TOKEN is a system include. For override methods that query a token, see *Note Token Details::.  File: semantic.info, Node: Nonterminal Streams, Next: Nonterminals at point, Prev: Token Queries, Up: Programming Nonterminal streams =================== These functions take some key, and returns information found inside the nonterminal stream. Some will return one token (the first matching item found.) Others will return a list of all items matching a given criterion. All these functions work regardless of a buffer being in memory or not. - Function: semantic-find-nonterminal-by-name name streamorbuffer &optional search-parts search-include Find a nonterminal NAME within STREAMORBUFFER. NAME is a string. If SEARCH-PARTS is non-`nil', search children of tokens. If SEARCH-INCLUDE is non-`nil', search include files. - Function: semantic-find-nonterminal-by-property property value streamorbuffer &optional search-parts search-includes Find all nonterminals with PROPERTY equal to VALUE in STREAMORBUFFER. Properties can be added with "semantic-token-put". Optional argument SEARCH-PARTS and SEARCH-INCLUDES are passed to "semantic-find-nonterminal-by-function". - Function: semantic-find-nonterminal-by-extra-spec spec streamorbuffer &optional search-parts search-includes Find all nonterminals with a given SPEC in STREAMORBUFFER. SPEC is a symbol key into the modifiers association list. Optional argument SEARCH-PARTS and SEARCH-INCLUDES are passed to "semantic-find-nonterminal-by-function". - Function: semantic-find-nonterminal-by-extra-spec-value spec value streamorbuffer &optional search-parts search-includes Find all nonterminals with a given SPEC equal to VALUE in STREAMORBUFFER. SPEC is a symbol key into the modifiers association list. VALUE is the value that SPEC should match. Optional argument SEARCH-PARTS and SEARCH-INCLUDES are passed to "semantic-find-nonterminal-by-function". - Function: semantic-find-nonterminal-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. - Function: semantic-find-innermost-nonterminal-by-position position streamorbuffer &optional nomedian Find a list of nonterminals 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. - Function: semantic-find-nonterminal-by-token token streamorbuffer &optional search-parts search-includes Find all nonterminals with a token TOKEN within STREAMORBUFFER. TOKEN is a symbol representing the type of the tokens to find. Optional argument SEARCH-PARTS and SEARCH-INCLUDE are passed to "semantic-find-nonterminal-by-function". - Function: semantic-find-nonterminal-standard streamorbuffer &optional search-parts search-includes Find all nonterminals in STREAMORBUFFER which define simple token types. Optional argument SEARCH-PARTS and SEARCH-INCLUDE are passed to "semantic-find-nonterminal-by-function". - Function: semantic-find-nonterminal-by-type type streamorbuffer &optional search-parts search-includes Find all nonterminals with type TYPE within STREAMORBUFFER. TYPE is a string which is the name of the type of the token returned. Optional argument SEARCH-PARTS and SEARCH-INCLUDES are passed to "semantic-find-nonterminal-by-function". - Function: semantic-find-nonterminal-by-function function streamorbuffer &optional search-parts search-includes Find all nonterminals in which FUNCTION match 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 tokens are searched. The over-loadable function "semantic-nonterminal-children" 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. - Function: semantic-find-nonterminal-by-function-first-match 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. If optional argument SEARCH-PARTS, all sub-parts of tokens are searched. The over-loadable function "semantic-nonterminal-children" is used for searching. If SEARCH-INCLUDES is non-`nil', then all include files are also searched for matches. - Function: semantic-recursive-find-nonterminal-by-name name buffer Recursively find the first occurrence of NAME. Start search with BUFFER. Recurse through all dependencies till found. The return item is of the form (BUFFER TOKEN) where BUFFER is the buffer in which TOKEN (the token found to match NAME) was found.  File: semantic.info, Node: Nonterminals at point, Next: Nonterminal Sorting, Prev: Nonterminal Streams, Up: Programming Nonterminals at point ===================== When you just want to get at a nonterminal the cursor is on, there is a more efficient mechanism than using `semantic-find-nonterminal-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 tokens. - Function: semantic-find-nonterminal-by-overlay &optional positionormarker buffer Find all nonterminals 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 tokens 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. - Function: semantic-find-nonterminal-by-overlay-in-region start end &optional buffer Find all nonterminals which exist in whole or in part between START and END. Uses overlays to determine position. Optional BUFFER argument specifies the buffer to use. - Function: semantic-current-nonterminal Return the current nonterminal in the current buffer. If there are more than one in the same location, return the smallest token. - Function: semantic-current-nonterminal-parent Return the current nonterminals parent in the current buffer. A token's parent would be a containing structure, such as a type containing a field. Return `nil' if there is no parent.  File: semantic.info, Node: Nonterminal Sorting, Next: Nonterminal Completion, Prev: Nonterminals at point, Up: Programming Nonterminal sorting =================== Sometimes it is important to reorganize a token stream into a form that is better for display to a user. It is important to not use functions with side effects when doing this, and that could effect the token cache. There are some existing utility functions which will reorganize the token list for you. - Function: semantic-bucketize tokens &optional parent filter Sort TOKENS into a group of buckets based on token type. Unknown types are placed in a Misc bucket. Type bucket names are defined by either `semantic-symbol->name-assoc-list'. If PARENT is specified, then TOKENS 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 tokens, and may re-organize the list with side-effects. - Variable: semantic-bucketize-token-token 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 tokens Rebuild TOKENS 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 token 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 tokens which are found as externally defined to some type. For example, changing the token 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 token 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 token is always marked with the `adopted' property. This function should be locally bound by a program that needs to add additional behaviors into the token list. This function is called with one argument which is a shallow copy of the token to be modified. This function should return the token (or a copy of it) which is then integrated into the revised token list.  File: semantic.info, Node: Nonterminal Completion, Next: Override Methods, Prev: Nonterminal Sorting, Up: Programming Nonterminal completion ====================== These functions provide ways reading the names of items in a buffer with completion. - Function: semantic-read-symbol prompt &optional default stream filter Read a symbol name from the user for the current buffer. PROMPT is the prompt to use. Optional arguments: DEFAULT is the default choice. If no default is given, one is read from under point. STREAM is the list of tokens to complete from. FILTER is provides a filter on the types of things to complete. FILTER must be a function to call on each element. (See !!! - Function: semantic-read-variable prompt &optional default stream Read a variable name from the user for the current buffer. PROMPT is the prompt to use. Optional arguments: DEFAULT is the default choice. If no default is given, one is read from under point. STREAM is the list of tokens to complete from. - Function: semantic-read-function prompt &optional default stream Read a function name from the user for the current buffer. PROMPT is the prompt to use. Optional arguments: DEFAULT is the default choice. If no default is given, one is read from under point. STREAM is the list of tokens to complete from. - Function: semantic-read-type prompt &optional default stream Read a type name from the user for the current buffer. PROMPT is the prompt to use. Optional arguments: DEFAULT is the default choice. If no default is given, one is read from under point. STREAM is the list of tokens to complete from.  File: semantic.info, Node: Override Methods, Next: Parser Hooks, Prev: Nonterminal Completion, Up: Programming Override Methods ================ These functions are called `override methods' because they provide generic behaviors, which a given language can override. For example, finding a dependency file in Emacs lisp can be done with the `locate-library' command (which overrides the default behavior.) In C, a dependency can be found by searching a generic search path which can be passed in via a variable. * Menu: * Token->Text:: Converting Tokens into text strings * Token Details:: Arbitrary token detail fetching * Local Context:: Deriving information about a language specific local context. * Making New Methods:: How to add your own methods for a tool  File: semantic.info, Node: Token->Text, Next: Token Details, Prev: Override Methods, Up: Override Methods Token->Text ----------- Any given token consists of Meta information which is best viewed in some textual form. This could be as simple as the token's name, or as a prototype to be added to header file in C. Not only are there several default converters from a Token into text, but there is also some convenient variables that can be used with them. Use these variables to allow options on output forms when displaying tokens in your programs. - Variable: semantic-token->text-functions List of functions which convert a token to text. Each function must take the parameters TOKEN &optional PARENT COLOR. TOKEN is the token to convert. PARENT is a parent token or name which refers to the structure or class which contains TOKEN. PARENT is NOT a class which a TOKEN would claim as a parent. COLOR indicates that the generated text should be colored using `font-lock'. - Variable: semantic-token->text-custom-list A List used by customizable variables to choose a token to text function. Use this variable in the `:type' field of a customizable variable. Every token to text conversion function must take the same parameters, which are TOKEN, the token to be converted, PARENT, the containing parent (like a structure which contains a variable), and COLOR, which is a flag specifying that color should be applied to the returned string. When creating, or using these strings, particularly with color, use "concat" to build up larger strings instead of "format". This will preserve text properties. - Function: semantic-name-nonterminal token &optional parent color Return the name string describing TOKEN. The name is the shortest possible representation. Optional argument PARENT is the parent type if TOKEN is a detail. Optional argument COLOR means highlight the prototype with font-lock colors. - Function: semantic-summarize-nonterminal token &optional parent color Summarize TOKEN in a reasonable way. Optional argument PARENT is the parent type if TOKEN is a detail. Optional argument COLOR means highlight the prototype with font-lock colors. - Function: semantic-prototype-nonterminal token &optional parent color Return a prototype for TOKEN. This function should be overloaded, though it need not be used. This is because it can be used to create code by language independent tools. Optional argument PARENT is the parent type if TOKEN is a detail. Optional argument COLOR means highlight the prototype with font-lock colors. - Function: semantic-prototype-file buffer Return a file in which prototypes belonging to BUFFER should be placed. Default behavior (if not overridden) looks for a token specifying the prototype file, or the existence of an EDE variable indicating which file prototypes belong in. - Function: semantic-abbreviate-nonterminal token &optional parent color Return an abbreviated string describing TOKEN. The abbreviation is to be short, with possible symbols indicating the type of token, or other information. Optional argument PARENT is the parent type if TOKEN is a detail. Optional argument COLOR means highlight the prototype with font-lock colors. - Function: semantic-concise-prototype-nonterminal token &optional parent color Return a concise prototype for TOKEN. Optional argument PARENT is the parent type if TOKEN is a detail. Optional argument COLOR means highlight the prototype with font-lock colors. - Function: semantic-uml-abbreviate-nonterminal token &optional parent color Return a UML style abbreviation for TOKEN. Optional argument PARENT is the parent type if TOKEN is a detail. Optional argument COLOR means highlight the prototype with font-lock colors.  File: semantic.info, Node: Token Details, Next: Local Context, Prev: Token->Text, Up: Override Methods Token Details ------------- These functions help derive information about tokens that may not be obvious for non-traditional languages with their own token types. - Function: semantic-nonterminal-children token &optional positionalonly Return the list of top level children belonging to TOKEN. Children are any sub-tokens which may contain overlays. The default behavior (if not overridden with `nonterminal-children' is to return type parts for a type, and arguments for a function. If optional argument POSITIONALONLY is non-`nil', then only return valid children if they contain positions. Some languages may choose to create lists of children without position/overlay information. If this function is overridden, use "semantic-nonterminal-children-default" to also include the default behavior, and merely extend your own. Note for language authors: If a mode defines a language that has tokens in it with overlays that should not be considered children, you should still return them with this function. If you do not, then token re-parsing, and database saving will fail. - Function: semantic-nonterminal-external-member-parent token Return a parent for TOKEN when TOKEN is an external member. TOKEN is an external member if it is defined at a toplevel and has some sort of label defining a parent. The parent return will be a string. The default behavior, if not overridden with `nonterminal-external-member-parent' is get the `'parent' extra specifier of TOKEN. If this function is overridden, use "semantic-nonterminal-external-member-parent-default" to also include the default behavior, and merely extend your own. - Function: semantic-nonterminal-external-member-p parent token Return non-`nil' if PARENT is the parent of TOKEN. TOKEN is an external member of PARENT when it is somehow tagged as having PARENT as it's parent. The default behavior, if not overridden with `nonterminal-external-member-p' is to match `'parent' extra specifier in the name of TOKEN. If this function is overridden, use `semantic-nonterminal-external-member-children-p-default' to also include the default behavior, and merely extend your own. - Function: semantic-nonterminal-external-member-children token &optional usedb Return the list of children which are not *in* TOKEN. If optional argument USEDB is non-`nil', then also search files in the Semantic Database. If USEDB is a list of databases, search those databases. Children in this case are functions or types which are members of TOKEN, such as the parts of a type, but which are not defined inside the class. C++ and CLOS both permit methods of a class to be defined outside the bounds of the class' definition. The default behavior, if not overridden with `nonterminal-external-member-children' is to search using "semantic-nonterminal-external-member-p" in all top level definitions with a parent of TOKEN. If this function is overridden, use "semantic-nonterminal-external-member-children-default" to also include the default behavior, and merely extend your own. - Function: semantic-nonterminal-protection token &optional parent Return protection information about TOKEN with optional PARENT. This function returns on of the following symbols: `nil' - No special protection. Language dependent. `'public' - Anyone can access this TOKEN. `'private' - Only methods in the local scope can access TOKEN. `'friend' - Like private, except some outer scopes are allowed access to token. Some languages may choose to provide additional return symbols specific to themselves. Use of this function should allow for this. The default behavior (if not overridden with `nonterminal-protection' is to return a symbol based on type modifiers. - Function: semantic-nonterminal-abstract token &optional parent Return non `nil' if TOKEN is abstract. Optional PARENT is the parent token of TOKEN. In UML, abstract methods and classes have special meaning and behavior in how methods are overridden. In UML, abstract methods are italicized. The default behavior (if not overridden with `nonterminal-abstract' is to return true if `abstract' is in the type modifiers. - Function: semantic-nonterminal-leaf token &optional parent Return non `nil' if TOKEN is leaf. Optional PARENT is the parent token of TOKEN. In UML, leaf methods and classes have special meaning and behavior. The default behavior (if not overridden with `nonterminal-leaf' is to return true if `leaf' is in the type modifiers. - Function: semantic-nonterminal-static token &optional parent Return non `nil' if TOKEN is static. Optional PARENT is the parent token of TOKEN. In UML, static methods and attributes mean that they are allocated in the parent class, and are not instance specific. UML notation specifies that STATIC entries are underlined. The default behavior (if not overridden with `nonterminal-static' is to return true if `static' is in the type modifiers. - Function: semantic-find-dependency token Find the filename represented from TOKEN. TOKEN may be a stripped element, in which case PARENT specifies a parent token that has positional information. Depends on `semantic-dependency-include-path' for searching. Always searches `.' first, then searches additional paths. - Variable: semantic-dependency-include-path Defines the include path used when searching for files. This should be a list of directories to search which is specific to the file being included. This variable can also be set to a single function. If it is a function, it will be called with one arguments, the file to find as a string, and it should return the full path to that file, or nil. - Function: semantic-find-nonterminal token &optional parent Find the location of TOKEN. TOKEN may be a stripped element, in which case PARENT specifies a parent token that has position information. Different behaviors are provided depending on the type of token. For example, dependencies (includes) will seek out the file that is depended on, and functions will move to the specified definition. - Function: semantic-find-documentation token Find documentation from TOKEN and return it as a clean string. TOKEN might have DOCUMENTATION set in it already. If not, there may be some documentation in a comment preceding TOKEN's definition which we can look for. When appropriate, this can be overridden by a language specific enhancement.  File: semantic.info, Node: Local Context, Next: Making New Methods, Prev: Token Details, Up: Override Methods Local Context ------------- - Function: semantic-up-context &optional point 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. - 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". It can be overridden with `beginning-of-context'. - 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 can be overridden with `end-of-context'. - Function: semantic-get-local-variables &optional point Get the local variables based on POINT's context. Local variables are returned in Semantic token format. Be default, this calculates the current bounds using context blocks navigation, then uses the parser with `bovine-inner-scope' to parse tokens at the beginning of the context. This can be overridden with `get-local-variables'. - 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. This function returns a list of tokens. If the local token returns just a list of strings, then this function will convert them to tokens. Part of this behavior can be overridden with `get-local-arguments'. - Function: semantic-get-all-local-variables &optional point Get all local variables for this context, and parent contexts. Local variables are returned in Semantic token format. Be default, this gets local variables, and local arguments. This can be overridden with `get-all-local-variables'. Optional argument POINT is the location to start getting the variables from. These next set of functions handle local context parsing. This means looking at the code (locally) and navigating, and fetching information such as a the type of the parameter the cursor may be typing in. - Function: semantic-end-of-command Move to the end of the current command. Be default, uses `semantic-command-separation-character'. Override with `end-of-command'. - Function: semantic-beginning-of-command Move to the beginning of the current command. Be default, users `semantic-command-separation-character'. Override with `beginning-of-command'. - 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 can be overridden using `ctxt-current-symbol'. - 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. Override with `ctxt-current-assignment'. - Function: semantic-ctxt-current-function &optional point Return the current function the cursor is in at POINT. The function returned is the one accepting the arguments that the cursor is currently in. This can be overridden with `ctxt-current-function'. - Function: semantic-ctxt-current-argument &optional point Return the current symbol the cursor is on at POINT. Override with `ctxt-current-argument'. - Function: semantic-ctxt-scoped-types &optional point Return a list of type names currently in scope at POINT. Override with `ctxt-scoped-types'. For details on using these functions to get more detailed information about the current context: *Note Context Analysis::.  File: semantic.info, Node: Making New Methods, Prev: Local Context, Up: Override Methods Making New Methods ------------------