This chapter covers queries, which ask the Static Analyzer for specific information about the source code files included in the fileset. You'll find these topics here:
Defining the Scope of a Query
The Static Analyzer has two types of queries: comprehensive queries, such as "List All Functions" and "List Global Symbols," that don't require a query target; and specific queries, such as "Who Is Called By?" and "List Methods In Class," that require a query target. Specific queries are grayed in the Queries menu unless you supply target text in the Query Target field.
To enter text in the Query Target field, put the pointer in the text area and type. You can also click an element in the query results area; the Static Analyzer pastes it into the text area. For example, you can click a function name displayed in the query results area to enter the function name in the Query Target field.
To make a query based on target text, choose a query from the Queries menu. The Static Analyzer returns all elements that match the parameters of the query and the target text. You can also make a query by pressing <Enter> while the pointer is in the Query Target field; the Static Analyzer repeats the last type of query you made, using the contents of the Query Target field as target text. Use this convenient keyboard shortcut to repeat a query with a new target text each time—for example, if you're following a thread of function calls.
Target Text as a Regular Expression
The Static Analyzer reads target text in the Query Target field as a regular expression, which is a system of string constructions used by the UNIX ed command to construct literal strings or wild card strings. Regular expression syntax is described in the reference (man) pages for ed; you'll also find the same description on the Static Analyzer's Help screen for regular expressions.
If you enter target text without using any regular expression special characters (which are \, ., *, (, ), [, ^, $, and +), the Static Analyzer reads the text as a literal string (without wild cards) and searches only for that text. If you use special characters to create a wild card expression, the Static Analyzer searches for a variety of target text in a single query, a useful tool for expanding the scope of a specific query.
| Note: Don't confuse regular expressions with the shell expressions you use to create a fileset. They're completely different systems. For example, the regular expression "q.*" matches strings that begin with "q," while the shell expression "q.*" matches strings that begin with "q."
|
The Static Analyzer normally recognizes the difference between uppercase and lowercase characters in target text during queries. If you want to ignore case in target text during a query (useful for Fortran code, which is case-insensitive), choose "General Options" from the Admin menu to open the General Options dialog box shown in Figure 4-1. Click the "Ignore Case In Searches" button to turn it on, then click the Close button to close the dialog box. You can return to the dialog box to turn off the option when you want to recognize case in queries.
To make a query, choose a query type from the Queries menu, which organizes queries in submenus of related queries (see Figure 4-2). The Static Analyzer shows the results in the query results area of its main window, using the view that is turned on. If the view isn't appropriate for the query (file dependency view for a function query, for example), the Static Analyzer informs you; no elements are listed in the query results area.
The "General" submenu (see
Figure 4-3) contains a variety of general-purpose queries designed to find strings or nonspecific program elements. Several of these queries find symbols, which are programmatic tokens sent to the compiler—macro names, functions, variables, and other source code elements. The general queries are:
"List Global Symbols" | |
returns all global symbols it finds in the files defined by the fileset. It ignores any target text. (Global symbols are standard elements of code: functions, macros, variables, classes, and so forth.)
|
"List All Constants" | |
returns all constants in the source code (includes enums, named constants, and Fortran 77 parameters).
|
"Where Symbol Used?" | |
expects a symbol name in the Query Target field. It returns the source code locations of all references to the symbol.
|
"Where Defined?" | |
expects a symbol name in the Query Target field. It finds all symbols that match the target text and returns the source code locations where those symbols are defined.
|
"Find String" | |
expects a literal string in the Query Target field. It returns the source code locations of all strings that match the target text. When you use this query, you ask the Static Analyzer not to interpret the target text as a regular expression, which allows you to use regular expression special characters as part of a literal text string.
|
"Find Regular Expression" | |
expects a general expression in the Query Target field. It returns the source code locations of all strings that match the target text.
|
The "Macros" submenu (see
Figure 4-4) contains queries that deal with macros:
"List All Macros" | |
returns all macros it finds in the files defined by the fileset. It ignores any target text.
|
"Where Defined?" | |
expects a macro name in the Query Target field. It finds all the macros that match the target text and returns the source code locations where those macros are defined.
|
"Where Undefined?" | |
expects a macro name in the Query Target field. It finds all the macros that match the target text and returns the source code locations where those macros are undefined (using #undef).
|
"Where Used?" | |
finds all locations where the macro entered in the Query Target field is used.
|
"List Unused Macros" | |
lists macros defined but never used.
|
The "Variables" submenu contains queries that deal with variables. In performing a variable query, you typically list variables first and then select an individual variable for further information. Figure 4-5 shows the results of the "List All Global Variables" selection with the _lastCmd variable selected. Notice that the variable list has five columns: Name, Function, File, Line, and Source. These identify the variable, its function or <global> if no function, the file in which it is defined or declared, the line number at which it is first defined or declared, and the actual source line.
From a list resulting from "List All Global Variables", you can select individual variables for specific queries. You do this by clicking the variable name. Figure 4-6 shows the results of a "Who References?" query.
The column headings are the same as for the "List All Global Variables" query results. In this case, the Line and Source fields refer to the line where the reference took place.
The "Variables submenu" appears in
Figure 4-7 and offers these selections:
"List All Global Variables" | |
returns the global variables it finds in files defined by the fileset. It ignores any target text.
|
"Where Declared?" | |
finds the location where the selected variable was declared.
|
"Where Defined?" | |
finds the location(s) where the variable was defined.
|
"Who References?" | |
expects a variable name in the Query Target field. It finds all variables that match the target text and returns all references to those variables.
|
"Who Sets?" | |
expects a variable name in the Query Target field. It finds all variables that match the target text and returns all source code locations where the values of those variables are set.
|
"Where Address Taken" | |
finds all locations where the address of the variable is taken.
|
"List Unused Variables" | |
lists all variables that have been defined or declared but not otherwise used in the source code.
|
"Where Allocated" | |
lists all locations where memory was allocated for the selected variable.
|
"Where Deallocated" | |
lists all locations where memory was deallocated for the selected variable.
|
The "Functions" submenu (see
Figure 4-8)contains queries that deal with functions. It operates in similar fashion to the variable queries—you create a list of functions and select individual functions for detailed queries. The selections are:
"List All Functions" | |
returns all functions it finds implemented in the fileset. It ignores any target text.
|
"Where Function Declared" | |
returns the location where the function was declared.
|
"Where Defined?" | |
returns all source code locations where those functions are defined.
|
"Where Function Used" | |
returns all source code locations where the function appears.
|
"Who Calls?" | |
returns all source code locations where the function is called.
|
"Who Is Called By?" | |
returns the names of all functions called by the selected (or entered) function, including the line number and source code where the call is made.
|
"List Undefined" | |
returns all functions called but not implemented in the fileset (usually library functions).
|
"List Unused Function" | |
returns functions that were declared or defined but not otherwise used in the source code.
|
"List Local Declarations" | |
returns all local variables and arguments in the source code and the line and source code in which the declaration is made.
|
The "Files" submenu (see
Figure 4-10) contains queries that deal with files.
"List All Files" | |
returns all files included in the fileset as well as any included files specified by files within the fileset (such as header files). It ignores any target text.
|
"List All Header Files" | |
returns all header (<filename>.h) files in the fileset.
|
"List Matching Files" | |
expects either a filename in the Query Target field or no target text at all. If it finds target text, it returns all filenames that match the regular expression. If it finds no target text, it returns the same results as the "List All Files" query.
|
"Who Includes?" | |
expects a filename in the Query Target field or a selected filename. It returns the names of all files that include the file(s) specified by the target text.
|
"Who is Included By?" | |
expects a filename in the Query Target field or a selected filename. It returns the names of all files that are included by the specified file(s).
|
The "Classes" submenu (see
Figure 4-11) contains queries that deal with C++ classes:
"List All Classes" | |
returns all classes it finds in the files defined by the fileset. It ignores any target text.
|
"Where Defined?" | |
expects a class name in the Query Target field. It finds all classes that match the target text and returns the source code locations where those classes are defined.
|
"List Subclasses" | |
expects a class name in the Query Target field. It returns the immediate subclasses of the classes matching the target text.
|
"List Superclasses" | |
expects a class name in the Query Target field. It returns the immediate superclasses of the classes that match the target text.
|
"List Methods In Class" | |
expects a class name in the Query Target field. It returns those methods defined within the classes that match the target text.
|
The "Methods" submenu (see
Figure 4-12) contains queries that deal with C++ member functions, also called methods:
"List All Methods" | |
returns all methods in the fileset. It ignores any target text.
|
"Where Defined?" | |
expects a method name in the Query Target field. It finds all methods that match the target text and returns all source code locations where those methods are defined.
|
"Where Declared?" | |
expects a method in the Query Target field. It returns source code locations of all class declarations that include methods that match the target text.
|
The "Common Blocks" submenu (see
Figure 4-13) applies to Fortran source code only. It contains these selections:
"List All Common Blocks" | |
lists all common blocks in the fileset.
|
"List All Symbols in Common Block" | |
lists all symbols used in common blocks in the fileset.
|
"Where Common Block Defined" | |
expects a common block in the Query Target field. It finds all common blocks that match the target text and returns the source code locations where the common blocks are defined.
|
"Where Common Block Referenced" | |
returns all source code locations where the common block appears.
|
The "Types" submenu (see
Figure 4-14) helps you get type information. It contains the following choices:
"List All Types" | |
returns all types used in the source code.
|
"Where Type Defined" | |
expects a type in the Query Target field. It finds all types that match the target text and returns the source code locations where the types are defined.
|
"List Functions of Type" | |
returns all functions of the given type and the source code locations where they are declared or defined.
|
"List Data of Type" | |
returns all data declarations and definitions using the given type and the source code locations where they are declared or defined.
|
"Where Type Used" | |
returns all source code locations where the type and functions and data items using the type appear.
|
The "Directories" submenu (see
Figure 4-15) helps you determine the organization of the current fileset. It contains these selections:
"List Directories" | |
lists all directories in the fileset.
|
"List Files" | |
lists all files in the fileset.
|
| Note: The "Packages" submenu is only available if you have purchased the ProDev Ada package.
|
The "Packages" submenu helps you get package information when you are analyzing programs written in Ada. It contains
"List All Packages" | |
lists all packages in the fileset
|
"Which Package Defines" | |
expects a package name in the Query Target field. It finds all package that match the target text and returns all source code locations where those packages are defined.
|
"List Functions" | |
expects a package name in the Query Target field and returns all functions declared in the package spec and the body.
|
"List Data" | |
expects a package name in the Query Target field and returns data declared in the package spec and body.
|
"Where Withed" | |
expects a package name in the Query Target field and returns all packages that with the given package.
|
| Note: The "Tagged Types" submenu is only available if you have purchased the ProDev Ada package.
|
The "Tagged Types" submenu
"List All Tagged Types" | |
lists all tagged types in the fileset.
|
"Where Tagged Types Defined" | |
expects a tagged type name in the Query Target field and returns all tagged types that match the target text and returns all source code locations where those tagged types are defined.
|
"List Parent Types" | |
lists the parent types for the tagged type entered in the Query Target field.
|
"List Derived Types" | |
lists the derived types for the tagged type entered in the Query Target field.
|
"List Primitive Operations" | |
lists the primitive operations for the tagged type entered in the Query Target field.
|
"List Components" | |
lists the parent types for the tagged type entered in the Query Target field.
|
"Where Type Used" | |
returns all declarations of functions and data of this type. as well as sites where other types derive from this one or refer to it.
|
| Note: The "Task Types" submenu is only available if you have purchased the ProDev Ada package.
|
The "Task Types" submenu
"List All Task Types" | |
lists all task types in the fileset.
|
"Where Task Type Defined" | |
expects a task type name in the Query Target field and returns all task types that match the target text and returns all source code locations where those task types are defined.
|
"List Entries" | |
|
"List Body Data" | |
lists the data local to the body for the given task type.
|
"List Body Functions" | |
lists all non-entry functions local to the task body.
|
"List Body Types" | |
lists all types declared that are local to the task body.
|
"Where Type Used" | |
lists all tasks of this type, as well as other types that derive from this type or refer to it.
|
When the Static Analyzer returns query results, you can look at each element's source code. To do this, double-click an element in the query results area, or single-click an element and then choose "Edit" from the Admin menu. Either of these actions opens up the Source View window as shown in Figure 4-18.
The Source View window opens the file containing the element and highlights the source line. Although the Source View window is set by default to be read only, you can edit text if you wish. If you have a configuration management tool installed, you can use the "Versioning" selection from the File menu to check out the file for editing.
If you prefer to view source code in a text editor other than Source View, you can choose "General Options" from the Admin menu to open the General Options dialog box, which offers the option Use Source View. Turn this option off to use the default alternate text editor, vi, whenever you double-click to see source code. To set a different alternate text editor, add the line
to your .Xdefaults file, where <editor> is the command for the editor you wish to use. The next time you use the Static Analyzer with the Source View option turned off, the editor you specified will appear when you view source code.
The Static Analyzer retains a list of your 15 most recent queries and presents them in the History menu. You can choose any of the queries listed in this menu to repeat the query. The Static Analyzer remembers the query type and the target text it used; it doesn't remember any view settings, such as the view type, view options, or Scope Manager settings. If you change view settings and then choose a query from the History menu to repeat the query, the Static Analyzer will return the same query results but will display them differently.
You can save query results by choosing "Save Query..." from the Admin menu to open the Save Query File Browser window shown in Figure 4-19. This is the standard Save File Browser.
To save query results, move to a directory in which you want to make the save. To specify a directory, you can use the path navigation bar, enter a path in the text field, or drag a folder into the drop pocket. Then click the OK button to save the query results and close the Save Query File Browser window.
The Static Analyzer saves the contents of the query results area to the file you named in the Browser. If you're in Text View, the Static Analyzer saves the results in text format; if you're looking at a graphical view, the graph is saved in PostScript format. It adds a heading to the text that lists query type and the target text that specified the query. It also includes field headings (such as Function, File, and so on) to match those at the top of the query results area in the main window.