test

Using Sun WorkShop

Using the Browsing Window

Two types of browsing are available through the Browsing window: pattern searches and source browsing.

Use pattern searching when you:

Use source browsing when you:

Pattern Search Mode

With pattern searching, you can search for regular expressions and simple text strings using the Browsing window.

Pattern searching searches all of the directories listed in the sb_init file (see "Importing Databases").

Browsing Window in Pattern Search Mode

Figure 3-2 shows the Browsing window in Pattern Search mode (see Figure 3-1 to identify the other components of the window).

Figure 3-2 Browsing Window in Pattern Search Mode

Graphic

Pattern text box 

Allows you to enter a regular expression to be matched 

Files text box 

Allows you to specify a file filter for the search 

Searching for a Pattern

To search for a pattern:

  1. In the Sun WorkShop main window, choose Browse > Pattern Search or click the Browsing button; then click the Pattern Search radio button in the Browsing window.

  2. Look in the Browsing window title bar to be sure you are in the correct browsing directory.

    If not, choose Browse > Change Browsing Directory and select the correct directory in the Pattern Search Directory dialog box.

  3. Type the pattern for which you want to search in the Pattern text box.

    If you cannot remember the exact symbol for which you want to search, you can use wildcard characters (., *. ^, and $) in your pattern (see "Special Characters in Patterns").

  4. Type a filter in the Files text box.

    The default filter searches the current directory for all files ending in .h, .c, .cc, or .f. Sun WorkShop saves the filter in your WorkSet whenever you save the WorkSet.

    Pattern searching uses the sb_init file to search multiple directories. It applies the Files filter to each directory.

  5. Press Return, choose Query > Find Matches, or click the Find Matches button.

  6. Move through the Match pane using the mouse, the Next Match and Previous Match buttons or menu items, or by pressing F5 and Shift+F5.

  7. Click a match to view the source in the editor window.

    Note -

    If you are overwhelmed by the number of matches found, restrict the types of files searched by changing the file types in the Files text box, and repeat the search.

You can search text displayed in the editor window. Double-click the text in the editor window to copy it, and paste it in the Browsing window's text box. If you are using vi or XEmacs as your text editor, you can also select text in the editor window and click the Find Refs button in the tool bar.

Special Characters in Patterns

Although you can enter a pattern exactly as it appears in the code, you can also use special characters to specify a set of patterns. You can use the special characters in Table 3-1 in patterns.

Table 3-1 Special Characters in Patterns

Character 

 Meaning Example

Period (.) 

Matches any character 

l.nes matches all occurrences of lanes or lines.

Asterisk (*) 

Matches any number of characters, including zero or more consecutive occurrences of the character that precedes it, except when it is the first character in the pattern

file.*() matches any string that fcontains file followed by zero or more characters and (), such as traffic_file_close() and file_save_popup. *file. matches only strings that begin with file.

Circumflex (^) 

Constrains the search to match the beginning of a line 

^tr* finds all lines that begin with traffic, truck, or any other string beginning with tr.

Dollar sign ($) 

Constrains the search to match the end of a line 

lanes$ finds all the lines that end with the string lanes.

For example, suppose you want to search for window_popup in the code, but only those instances that begin a line. You would type the following query:

^window_popup*

The circumflex (^) tells the browser to look only at those matches that start a line of code, while the asterisk (*) asks for all matches with window_popup, including window_popup_name_objects and window_popup1_objects.

Note -

Surrounding an expression with a circumflex and a dollar sign constrains the search to match the entire line.

Source Browsing Mode

Using source browsing, you can search for language elements such as functions, classes, structs, unions, and records or for their usage, definitions, or assignments. You can also graphically view function call relationships or class hierarchies. And you can examine the data or member functions of a class.

Source Browsing Databases

The Source Browser obtains the information it uses from a database that describes the static structure of your program. To use source browsing, you must first create a source browsing database by adding the -xsb option to your compilation command or your makefile.

The browser has different levels of functionality depending upon the database it accesses:

Compiler-generated database 

use full browser functionality 

Tags-generated database 

Allows queries on functions and global variables and can display function calls. Graphing features are not available. 

No database 

Must use the Pattern Search mode of the Source Browser. 

Using a tags-generated database has some advantages over using a database generated by a compiler:

Generating a Browser Database

When you compile your source files with the source browser option, Sun WorkShop creates a database containing information about the files. The Source Browser responds to queries by searching through this database.

When you create a compiler-generated database, you can access all browsing features.

To generate the browsing database, add the source browser option to your makefile:

Language 

Compiler Source Browser Option 

C++ 

-xsb or -sb

ANSI C 

-xsb

FORTRAN 77 

-xsb or -sb

Assembler 

-b

Creating a Tags Database

A tags database provides a quick and convenient method for browsing source files without compilation. The database is based on a lexical analysis of the source file. It will not always correctly identify all language constructs, but it will operate on files that you cannot compile.

Note -

The source browsing tags are not in the same format as ctags; the tags discussed here are in a format that works specifically with source browsing.

If you browse using a tags database, you:

A tags database recognizes only global definitions for variables, types, and functions, and collects information on function calls. Function calls for C++ members are recognized only when called explicitly.

To create a tags database:

  1. From the Browsing window, choose Browse > Create Tags Database.

  2. In the Create Tags Database dialog box, click OK to accept the default file filter or enter the type of files you want to scan and click OK.

    The browser creates the tags database.

Searching Multiple Directories

If you keep your source files in several different directories, you are likely to execute the compiler in each of these directories. As a result, the default compiler behavior generates a separate source browser database in each directory.

Since the Source Browser looks at only one database at a time, only the part of your application located in the current directory is searched. You can override this default behavior by importing databases.

Importing Databases

Instead of merging separate databases, you can import databases. Use the sb_init file to read more than one database. You can start browsing in the same directory that holds the sb_init file.

To import databases:

  1. Identify where your sb_init file resides.

  2. Add an import command to the sb_init file for each directory in which the compiler is executed:

    import absolute_or_relative_pathname

  3. Set your SUNPRO_SB_INIT_FILE_NAME environment variable to point to your sb_init file.

    Add the following line to your .login file:

    setenv SUNPRO_SB_INIT_FILE_NAME path to sb_init file/sb_init

Note -

Use the import option to search your entire source tree for source files and browser databases. Just add an import command to the sb_init file for each directory in your source tree.

Note -

Because pattern searching uses sb_init to search source files in multiple directories, and source browsing uses sb_init to search browser databases (which include object files) in multiple directories, you may want to include import commands for both source and object directories in your sb_init file.

Browsing Window in Source Browsing Mode

Figure 3-3 shows the Browsing window in Source Browsing mode (see Figure 3-1 to identify the other components of the window).

Figure 3-3 Browsing Window in Source Browsing Mode

Graphic

Match list  

Allows you to filter the search to specific uses of the query. You can select from the following usage types: 

All Occurrences of--No restrictions on the match type of the given entry 

Uses of--Show all uses of the given entry 

Definitions of-- Show all definitions for the given entry 

Assignments to--Show all assignments to the given entry 

Match text box 

Contains the query on which you want to search. 

Type list  

Allows you to set a filter for the entry being queried. You can select from the following types: 

All--No restrictions on the language element type of the given entry 

Member/Field--Instances of the given entry as class member, or record fields 

Class/Struct/Record--Instances of the given entry as classes, structs, or records 

Static--Instances of the given entry as functions or variables that have static storage 

Function--Instance of the given entry as a function 

Symbolic Constant--Constant referred to by a symbolic name; for example, ENUM members, PARAMETER statement defined constants, set members, and #define macros (with or without arguments)

Scope list  

Allows you to restrict the search to specific elements in the source. Enter the string for the element in the Scope text box. Shell-style expressions are supported. You can select one of the following components: 

All--No restrictions on the scope of the given entry 

Program/Library--Search only in the specified program or library files 

Class/Struct--Search only in the specified class or struct 

Function--Search only in specified functions 

Source File--Search only in the specified source files 

Using Source Browsing

To use source browsing:

  1. Compile the application using the -sb or -xsb option, which instructs the compiler to generate a browsing database during compilation.

    (See "Generating a Browser Database".)

  2. Choose Browse > Browse Sources, or click the Browsing button in the Sun WorkShop main window tool bar, and then click the Source Browsing radio button in the Browsing window.

  3. Look in the Browsing window title bar to be sure you are in the correct browsing directory.

    If not, choose Browse > Change Browsing Directory and use the Browsing Directory dialog box to select the directory that contains the source browser database.

    Note -

    You can search files in multiple directories in the browsing database. See "Searching Multiple Directories".

  4. Type a query in the Match text box and press Return, choose Query > Find Matches, or click the Find Matches button.

    For details on writing a query, see "Composing a Query".

  5. Restrict the number of matches returned by choosing a match, type, or scope from the appropriate pulldown list.

    For information on the lists, see "Browsing Window in Source Browsing Mode". For detailed information on restricting a query, see "Restricting a Query" in the Sun WorkShop online help.

  6. Move through the Match pane using the mouse, the Next Match and Previous Match buttons or menu items, or by pressing F5 and Shift+F5.

    Each match line contains the name of the source file, the line number, and the text on that line. Matches are sorted with definitions first, declarations last, and everything else in between. Within each group, the matches are listed alphabetically by file name, then by line number.

  7. Click a match to view the source in the editor window.

  8. Start the Call Grapher, Class Grapher, or the Class Browser to view relationships in the source.

Composing a Query

When you use source browsing, a query instructs the browser to find all occurrences of the symbol, string constant, or search pattern entered in the search field. The item actively being searched for is called the current query.

All symbols in the code identical to the query are referred to as matches.

In general, you cannot query for reserved words. The exception is language-defined type names in ANSI C or C++. For example, you can query on int, float, double, or long in ANSI C or C++ programs; however, you cannot query on integer or print in Fortran programs.

You can search for a variable, function, type, constant or macro. If you are unsure of what to browse for, begin by selecting main or another identifier used early in your program.

Special Characters in Queries

Although you can enter a name or function exactly as it appears in the code, you can also use wildcard characters to specify a set of character strings.

Use the wildcard characters in Table 3-2 in queries you type in the Match text box:

Table 3-2 Special Character in Queries
 Character Meaning Example

period (.) 

Matches any character 

.ehicle matches all occurrences of vehicle or Vehicle

asterisk (*) 

Matches any number of characters, including zero or more consecutive occurrences of the character that precedes it. 

vehi.* matches any string that begins with veh, such as vehicle_length(). vehi* matches veh but not vehicle_length().

Using the Double Colon Operator

The double colon operator (::) qualifies a C++ member function or top-level function with the following:

The syntax is as follows:

class_name::function_name

For example, hand::grasp.

To find RW::ListPtr::insert(), the following regular expressions will work:

insert ListPtr::insert RW::ListPtr::insert

The first two regular expressions are equivalent to .*::.*::insert and .*::ListPtr::insert and might match more symbols. The entry insert matches all functions or member functions with the name insert instead of requiring .*insert.