Browsing Source Code

5

WorkShop's browsing feature is a powerful tool. Using browsing, you can find all occurrences of any symbol or string in a large program, including those found in header files.

This chapter is organized into the following sections:

Understanding Browsing

page 37

Browsing Features

page 38

Quick Start

page 42

Understanding Browsing	page 37
Browsing Features	page 38
Quick Start	page 42

Browsing uses a "what you see is what you browse" paradigm. The source code that you edit and compile is the same source code that WorkShop uses in its searches.

Browsing can be used with multiple languages. When you browse a program that is written in more than one language, the browsing feature automatically determines the language in which each source file is written. The browsing operations do not change from one language to another.

Understanding Browsing

You browse source code by issuing queries that instruct WorkShop to find all occurrences of the symbol, string constant, or search pattern that you have specified. You then view the occurrences or matches of the item you requested, with their surrounding source code.

You can also graph the function relationships in your program. If your source code is written in C++, then you can browse and graph the classes defined in your program.

Browsing responds to queries by searching in a database that contains information about the files you are browsing. You create this database when you compile your source file with the Browsing option.

Pattern Searches or Source Browsing?

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

Click the Pattern Search radio button when you:

Want to do a quick search (grep-style) for a regular expression
Do not have a source browsing database in the directory you want to search
Do not want to graphically view function call relationships or class hierarchies
Do not want to examine the data or member functions of a class

Click the Source Browsing radio button when you:

Have a source browsing database created by adding the -xsb option to your compilation command or your makefile
Want to search for language elements such as functions, classes, structs, unions, and records or for their usage, definitions, or assignments
Want to graphically view function call relationships or class hierarchies
Want to examine the data or member functions of a class

If you modify the files in the database, you must recompile them to get the most accurate information when using source browsing.

Browsing Features

Browsing consists of five main windows:

Browsing window in Pattern Search mode - With pattern searching, you can search for regular expressions and simple text strings.
Browsing window in Source Browsing mode - Using source browsing, you can search for functions, classes, structs, and other language elements.
Call Grapher - With the Call Grapher, you can graphically inspect the relationships of the functions in programs.
Class Grapher - With the Class Grapher, you can graphically inspect the inheritance structure of classes in C++ programs.
Class Browser - With the Class Browser, you can browse through C++ classes and their data and function members. You can also view the class interfaces and relationships.

Relationship of Browsers and Graphers

Figure 5-1 shows how the Browsing window, Call Grapher, Class Grapher, and Class Browser interrelate.

Figure 5-1 How Browsing, the Graphers, and the Class Browser Interrelate

Quick Start

The following five tables show the basic steps involoved in browsing source code. For more detailed information on any of the steps, see the online help for WorkShop.

When you start browsing, first choose the task you want to perform: query a symbol, graph a function, graph a class, or browse a class.

Using Pattern Searching

Table 5-1 Pattern Searching

Task
Description

Browse for a pattern

Choose Browse Pattern Search.

Check Directory

Look in the Browsing window title bar to be sure you are in the correct browsing directory. If not, change directories. Choose Browse Change Browsing Directory.

Enter a query

Enter a simple query in the text field and press Return, choose Query Find Matches, or click the Find Matches button.

Navigate through the matches

Move through the Match list using the mouse, the Next Match and Previous Match buttons or menu items, or press F5 and Shift+F5.

Jump to the source code

Single-click on a match to view the source in the editor window.

Table 5-1 Pattern Searching
Task	Description
Browse for a pattern	Choose Browse Pattern Search.

Check Directory	Look in the Browsing window title bar to be sure you are in the correct browsing directory. If not, change directories. Choose Browse Change Browsing Directory.

Enter a query	Enter a simple query in the text field and press Return, choose Query Find Matches, or click the Find Matches button.

Navigate through the matches	Move through the Match list using the mouse, the Next Match and Previous Match buttons or menu items, or press F5 and Shift+F5.

Jump to the source code	Single-click on a match to view the source in the editor window.

Using Source Browsing

Table 5-2 Source Browsing

Task
Description

Build the application

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

Browse for a symbol

Choose Browse Browse Sources.

Check Directory

Look in the Browsing window title bar to be sure you are in the correct browsing directory. If not, change directories. Choose Browse Change Browsing Directory.

Enter a query

Enter a query in the text field and press Return, choose Query Find Matches, or click the Find Matches button.

Filter or focus a query

Restrict the number of matches returned by choosing a match, type, or scope.

Navigate through the matches

Move through the Match list using the mouse, the Next Match and Previous Match buttons or menu items, or press F5 and Shift+F5.

Jump to the source code

Single-click on a match to view the source in the editor window.

View relationships

Start the graphers or the Class Browser.

Table 5-2 Source Browsing
Task	Description
Build the application	Compile the application using the `-sb` or `-xsb` option, which instructs the compiler to generate a browsing database (`.sb`) during compilation.

Browse for a symbol	Choose Browse Browse Sources.

Check Directory	Look in the Browsing window title bar to be sure you are in the correct browsing directory. If not, change directories. Choose Browse Change Browsing Directory.

Enter a query	Enter a query in the text field and press Return, choose Query Find Matches, or click the Find Matches button.

Filter or focus a query	Restrict the number of matches returned by choosing a match, type, or scope.

Navigate through the matches	Move through the Match list using the mouse, the Next Match and Previous Match buttons or menu items, or press F5 and Shift+F5.

Jump to the source code	Single-click on a match to view the source in the editor window.

View relationships	Start the graphers or the Class Browser.

Graphing Calls

Table 5-3 Graphing Function Calls

Task
Description

Start the Call Grapher

Choose Browse Graph Calls, or select a function in the source code or Debugging window and choose Browse Graph Function Calls.

Display function relationships

Enter a function in the Function field and click Add or press Return.

Navigate the graph

Click on a node to select it.

Expand the call, its callers, or both.

Expand the entire graph, hide some nodes, or show all connected nodes. Double-click to expand calls.

Jump to the source code

Select a node and click Show Source to view the source in the editor window.

Table 5-3 Graphing Function Calls
Task	Description
Start the Call Grapher	Choose Browse Graph Calls, or select a function in the source code or Debugging window and choose Browse Graph Function Calls.

Display function relationships	Enter a function in the Function field and click Add or press Return.

Navigate the graph	Click on a node to select it.
	Expand the call, its callers, or both.
	Expand the entire graph, hide some nodes, or show all connected nodes. Double-click to expand calls.

Jump to the source code	Select a node and click Show Source to view the source in the editor window.

Graphing Classes

Table 5-4 Graphing Class Hierarchies

Task
Description

Start the Class Grapher

Choose Browse Graph Classes, or select a class in the source code or Debugging window and choose Browse Graph Classes.

Display a class hierarchy

Enter a class in the Class field and click Add Current Class or press Return.

Navigate the graph

Click on a node to select it.

Expand the derived classes, the base classes, or both.

Expand the entire graph, hide some nodes, or show all connected nodes. Double-click to expand calls.

Jump to the source code

Select a node and click Show Source to view the source in the editor window.

Table 5-4 Graphing Class Hierarchies
Task	Description
Start the Class Grapher	Choose Browse Graph Classes, or select a class in the source code or Debugging window and choose Browse Graph Classes.

Display a class hierarchy	Enter a class in the Class field and click Add Current Class or press Return.

Navigate the graph	Click on a node to select it.
	Expand the derived classes, the base classes, or both.
	Expand the entire graph, hide some nodes, or show all connected nodes. Double-click to expand calls.

Jump to the source code	Select a node and click Show Source to view the source in the editor window.

Browsing Classes

Table 5-5 Browsing for Class Information

Task
Description

Start the Class Browser

Choose Browse Browse Classes, or select a class in the source code or Debugging window and choose Browse Browse Classes.

Filter the class list

Click the Classes/Structs and the Unions check boxes to filter the classes and data function members listed.

View information about the class

Click on an underlined base, derived, or friend class.

Jump to the source code

Select a line (or a portion of a line) containing a data member or friend function and click Show Source to view the source in the editor window.

Task	Description
Start the Class Browser	Choose Browse Browse Classes, or select a class in the source code or Debugging window and choose Browse Browse Classes.

Filter the class list	Click the Classes/Structs and the Unions check boxes to filter the classes and data function members listed.

View information about the class	Click on an underlined base, derived, or friend class.

Jump to the source code	Select a line (or a portion of a line) containing a data member or friend function and click Show Source to view the source in the editor window.