Symbol Functions
SymListInsert (hsyml, isymBefore, symbolNew)
This function inserts a symbol record into the symbol list hsyml. The symbol is inserted just before isymBefore. If isymBefore is –1, then the symbol is appended to the end of the list. The symbol record is given in sym-
bolNew. See “Symbol Record” on page 382.
SymListItem (hsyml, isym)
This function returns the Symbol record at the zero-based index isym in the symbol list hsyml. The size of the
symbol list is returned by SymListCount. See “Symbol Record” on page 382.
Index values start at zero, and continue up to one less than the value returned by SymListCount.
This example enumerates all symbols in the symbol list: csym = SymListCount(hsyml) isym = 0 while (isym < csym)
{ symbol = SymListItem(isym)
// … do something with symbol
Msg ("symbol name = " # symbol.name) isym = isym + 1
}
SymListNew ()
Allocates a new, empty symbol list. Returns the new symbol list handle, or hNil if errors. You should call Sym-
ListFree when you are finished with the symbol list.
SymListRemove (hsyml, isym)
Removes an element from the symbol list hsyml. The symbol element at isym is deleted.
Symbol Functions
Symbol functions allow you to access Source Insight's symbol lookup engine. Source Insight maintains symbolic information about your project in a symbol database. These symbol functions make use of the symbol database and Source Insight's built-in language parsers to locate symbols in your source files.
You may want to review the section "Symbols and Projects" in the "Projects" chapter for a description of how
Source Insight maintains symbolic information and what the lookup rules are.
Symbol Record
The Symbol record describes a symbol declaration. It specifies the location and type of a symbol. It is used to uniquely describe a symbol in a project, or in an open file buffer.
Symbol records are returned by several functions, and Symbol records are used as input to several functions.
See “Symbol Record” on page 382.
GetBufSymCount(hbuf)
Returns the number of symbols declared in the buffer hbuf. Returns zero if no symbols are declared, or if the file could not be processed, or if the document type for the file does not specify a language parser.
GetBufSymLocation(hbuf, isym)
Returns the Symbol record of the symbol indexed by isym in the buffer hbuf. Each parsed file buffer maintains an index of symbols defined in it. The index is sorted by symbol name. Symbol index values start at zero
400 Source Insight 4 User Guide
Symbol Functions
and go up to the count returned by GetBufSymCount minus one. This function maps a symbol index (isym) into a symbol Symbol record.
See “Symbol Record” on page 382.
GetBufSymName(hbuf, isym)
Returns the name of the symbol indexed by isym in the buffer hbuf. Each parsed file buffer maintains an index of symbols defined in it. The index is sorted by symbol name. Symbol index values start at zero and go up to the count returned by GetBufSymCount minus one. This function maps a symbol index (isym) into a symbol name.
This example iterates through all file buffer symbols: isymMax = GetBufSymCount (hbuf) isym = 0 while (isym < isymMax)
{ symname = GetBufSymName (hbuf, isym)
...
isym = isym + 1
}
GetCurSymbol ()
Returns the name of the symbol where the current selection is. The current selection is the selection (or cursor position) in the active window. GetCurSymbol returns an empty string if no symbol is found.
GetSymbolLine (symbol_name)
Returns the line number of the symbol named symbol_name. If multiple symbols are defined with the same name, then the user will be able to select the appropriate one.
GetSymbolLocation (symbol_name)
Returns the location of the symbol name specified in symbol_name. The location is returned in a Symbol
record. An empty string is returned if the symbol is not found. See “Symbol Record” on page 382.
This function performs a look up operation the same way that Source Insight looks up symbols when you use the Jump To Definition command. If the symbol is not found in the current project, or any open file, then all the projects on the project symbol path are searched as well. If more than one declaration is found for symbol_name, then the user is presented with a multiple-definition list to select from.
You can also call GetSymbolLocationEx for more control over how the lookup operation is performed, and to locate multiple definitions of the same symbol name.
This example looks up the definition of a symbol and displays its source file and line number.
symbol = Ask("What symbol do you want to locate?") loc = GetSymbolLocation(symbol) if (loc == "")
Msg (symbol # " was not found") else
Msg (symbol # " was found in " # loc.file #
" at line " # loc.lnFirst)
Locating File Names
GetSymbolLocation can also look up file names. By giving a simple file name as the symbol_name parameter,
GetSymbolLocation can look up the file in the project, or on the project symbol path, and return the fully qualified path to the file in the location.file field. This can be useful for expanding a simple file name into its full path.
Source Insight 4 User Guide 401
Symbol Functions
For example: loc = GetSymbolLocation("simple.c") fullfilename = loc.file
// fullfilename could be something like "d:\proj\simple.c"
GetSymbolLocationEx (symbol_name, output_buffer, fMatchCase, LocateFiles, fLocateSymbols)
Finds all the declarations for the symbol specified in symbol_name. Each declaration location is appended as a line to the given buffer output_buffer as a Symbol record. If fMatchCase, then the symbol name case must match exactly. If fLocateFiles, then file names in the project or on the project symbol path are located.
File extensions don't have to be specified. If fLocateSymbols, then symbol definitions are located. Both fLocateFiles and fLocateSymbols may be set to True.
See “Symbol Record” on page 382.
Since record variables can be expressed as a string, a Symbol record can be written as a line of text in a buffer.
To read a Symbol record from the output buffer, use the GetBufLine function to return the entire line text; in this case a Symbol record. See GetSymbolLocation for a description of the Symbol record.
GetSymbolLocationEx returns the number of matching declarations, or zero if none were found.
Unlike the GetSymbolLocation function, this function will find multiple declarations that match on symbol-
_name. You can use this function to enumerate through each location by scanning each line of the output buffer.
This example looks up a symbol and enumerates through each declaration found: symbol = Ask("What symbol do you want to locate?") hbuf = NewBuf("output") count = GetSymbolLocationEx(symbol, hbuf, 1, 1, 1) ln = 0 while (ln < count)
{ loc = GetBufLine(hbuf, ln) msg (loc.file # " at line " # loc.lnFirst) ln = ln + 1
}
CloseBuf(hbuf)
Locating File Names
GetSymbolLocationEx can also look up file names. By giving a simple file name as the symbol_name parameter, GetSymbolLocationEx can look up the file in the project, or on the project symbol path, and return the fully qualified path to the file in the location.file field. See GetSymbolLocation for an example.
If fLocateFiles is TRUE, and a symbol name is given without an extension, GetSymbolLocationEx will locate files that have this base name, regardless of extension. For example, if you specify "dlg" in symbol_name,
GetSymbolLocationEx may return matches on "dlg.c" (a file), and "dlg.h" (another file). Furthermore, if fLocateSymbols is also TRUE, then "DLG" (a data type) may also be returned.
GetSymbolFromCursor (hbuf, ln, ich)
Returns the Symbol record of the symbol name that appears at the given cursor position. hbuf is the buffer handle. ln is the line number. ich is the zero-based character index on the line.
This works in a similar way to the Jump To Definition command, except it returns the Symbol record, instead
of jumping. See “Symbol Record” on page 382.
GetSymbolLocationFromLn (hbuf, ln)
Returns the Symbol record of the symbol that exists at line number ln within the buffer hbuf. The symbol at ln
is a symbol whose declaration includes the given line number ln. See “Symbol Record” on page 382.
JumpToLocation (symbol_record)
Jumps to the location given in symbol_record. This opens the file in the Symbol record and moves the cursor to the symbol defined there. This works the same way as the Jump To Definition command.
402 Source Insight 4 User Guide
Symbol Functions
The Symbol record is returned by the GetSymbolLocation function. See “Symbol Record” on page 382.
JumpToSymbolDef (symbol_name)
Jumps to the definition of the symbol named symbol_name. This opens a file and moves the cursor to the symbol defined there. This works the same way as the Jump To Definition command.
SymbolChildren (symbol)
Returns a new symbol list handle containing the children of the given symbol. The children of a symbol are the symbols declared within the body of the symbol. For example, the children of a class are the class members.
symbol
contains a Symbol record. See “Symbol Record” on page 382.
You should call SymListFree to free the symbol list handle returned by SymbolChildren.
You can use the Symbol List functions to access the symbol list returned by this function.
Example
This example looks up the definition of a symbol and displays its children: symbolname = Ask("What symbol do you want to locate?") symbol = GetSymbolLocation(symbolname) if (symbol == nil)
Msg (symbolname # " was not found") else
{ hsyml = SymbolChildren(symbol) cchild = SymListCount(hsyml) ichild = 0 while (ichild < cchild)
{ childsym = SymListItem(hsyml, ichild)
Msg (childsym.symbol # " was found in "
# childsym.file # " at line " # childsym.lnFirst) ichild = ichild + 1
}
SymListFree(hsyml)
}
SymbolContainerName (symbol)
Returns the container component of the symbol's name. symbol
contains a Symbol record. See “Symbol Record” on page 382.
Every symbol name is divided into path components, which are separated by dot (.) characters. For example, a symbol name might be "myclass.member1". In this example, "member1" is contained by "myclass".
SymbolDeclaredType (symbol)
Returns a Symbol record of the declared type of the given symbol.
symbol
contains a Symbol record. See “Symbol Record” on page 382.
SymbolLeafName (symbol)
Returns the "leaf", or right-most component of the symbol's name.
symbol
contains a Symbol record. See “Symbol Record” on page 382.
Every symbol name is divided into path components, which are separated by dot (.) characters. For example, a symbol name might be "myclass.member1". In this example, "member1" is contained by "myclass".
SymbolParent (symbol)
Returns a Symbol record of the parent of the given symbol. The parent of a symbol is the symbol that contains it.
Source Insight 4 User Guide 403