 | Tcl Dev Kit User Guide |  |
Cross Reference Tool
The Tcl Dev Kit Cross Reference Tool (XRef) is a graphical
browser that maps out the structure of a Tcl program and helps make
complex code more understandable. The XRef tool scans
Tcl source code, and then builds a cross-referenced database showing you
the relationships among Tcl code components. These components include
packages, files,
namespaces,
commands,
and variables. Each Tcl component is
presented in a tree hierarchy that can be expanded to display where
the code is defined, declared, used, and located.
The XRef tool is useful for building, debugging, and maintaining Tcl code.
For example, when changing a variable definition, use the XRef tool to identify
the files and commands where the variable is declared, and then update them to
the new variable definition.
The Tcl Dev Kit Cross Reference Tool can be used to extract Tcl component
information from programs and packages contained in TclApp (or Prowrap)
projects, Tcl Dev Kit Package
definitions (".tap" files), and from
Komodo
project files.
Cross Reference Tool features include:
- Switching between hierarchical views to gain a higher-level or lower-level
understanding of any Tcl source component.
- Drilling down into specific areas of code.
- Finding dependencies between commands, variables etc.
- Browsing from a listed namespace, command, or variable definition
and jumping to the actual source code where it is declared.
Note: XRef will launch Tcl source code in
the Komodo editor if it is installed.
- Filtering components based-on packages, files, namespaces, commands and
variables.
- At-a-glance overview of code areas that could be affected by
changing a command or variable definition.
The XRef BWidgets demo uses the Cross Reference Tool to extract component
information from the BWidgets package. See the
XRef BWidgets Demo for more information.
 Top
This section lists the platforms and Tcl versions that the Tcl Dev Kit
Cross Reference Tool supports. It then describes how to start the tool
and provides a tour of the main window.
The Tcl Dev Kit Cross Reference Tool works with Tcl
version 8.4 or greater.
The Cross Reference tool is an application that builds a database of
program components, including packages, files, namespaces, commands and
variables.
Windows
- Start Menu: Start | Programs | ActiveState Tcl Dev Kit |
Tcl Dev Kit Cross Reference Tool
- Command Line:
tclxref.exe
Unix
Note: When using the command line to
start the XRef tool, you can specify the filename of a database to load.
See Opening a Database for more information.
The Cross Reference Tool explorer window consists of the following
components:
Note: To change the font size displayed in the
Cross Reference Tool Explorer, press Ctrl-plus to increase the font
size or Ctrl-minus to decrease the displayed font size. If using
Windows with a mouse wheel, you can alternatively press the Ctrl
key and then rotate the mouse wheel to increase or decrease the font size
displayed in the Cross Reference Tool Explorer.
The menu contains File and Help content.
- File: Use the File menu to open,
close, and save cross-referenced databases. See
Opening a Database for more information.
- Help: Use the Help menu to access
online help. Select Help | Help topics.
The component display lists the scanned component data.
Where applicable, component data is displayed in expandable hierarchical
lists. Each list can be drilled down, using expanding and collapsing
tree nodes, to display the commands and variables associated with a
particular component.
The Cross Reference Tool displays Tcl program component types on individual
tabs. Each tab presents the same scanned database content in a different view,
depending on the component tab selected. For example, the
Files tab shows the components used and defined within
a particular file. These file components could include: namespaces, commands,
variables, and packages. The Commands tab, however,
provides a narrower view of the scanned database as only the
lower-level variables associated with a particular command are displayed.
By switching between these two component tab views, you gain
a higher or lower-level understanding of any Tcl source component.
The component tabs include:
Each component tab has a unique filter that limits the number of
components listed in the display window. Component Filters
are opened from any component tab using the Filter
 button. Each filter can
be configured to find exact matches, and to perform glob-style matching
(using the asterisk (*) to match any sequence of characters and a question
mark (?) to match any single character). When configured, only elements
matching that pattern are displayed.
Note: Only top-level nodes of a hierarchical
list are filtered. Node children are not filtered.
XRef Component Explorers focus on the low-level details
of a single component. An XRef Component Explorer
is invoked from any component tab using the Open
 button.
Each component tab launches a unique component
explorer interface to view the specifics of the selected component.
The Component Source Code Viewer is only applicable
to those without an ActiveState
Komodo installation.
The XRef Component Source Code Viewer displays scanned source
code on systems without a Komodo installation. If Komodo is installed, all
component source code is loaded in Komodo and the
Component Source Code Viewer is never invoked.
Top
The Packages tab displays the Tcl packages that are
used and defined within the scanned Tcl source code. The
#Provides and #Requires columns
display the number of times each package is used within the database.
The #Provides column indicates the
total number of times the scanned source files contain a require
statement for a selected package. The #Requires column
lists the number of packages that a selected package uses.
Click a column title to sort package content in ascending or descending order.
The current sort column selected is shaded pink.
Filtering Packages
To filter packages:
- Click the Filter
button.
The Filter Packages screen appears.
- Enter the filter conditions, based-on any combination of the
following:
- Name: Package name.
- #Provides: Number of times the package has been
required.
- #Requires: Number of packages this package
requires.
- Select a filter action:
- Click Ok to enable and close the filter.
- Click Apply to enable the filter.
The filter screen stays open.
- Click Cancel to abort and close the filter.
Use the Open button to view details
on a particular package, such as the name of the file where a
required statement calls the package.
Opening a package's details invokes an XRef Package Explorer
window, which displays lower-level code details specific to the package
selected. To open a package's details in an
XRef Package Explorer window:
- Select the desired package name.
- Click the Open button. An
XRef Package Explorer window appears.
This explorer is titled 'XRef Package: [package_name]'.
Note: Alternatively, double-click the package name to
invoke an XRef Package Explorer.
The XRef Package Explorer displays the files that are
used and defined within the selected package component.
Toggle between the Uses and Definition
tabs to view what files are used and where those files are defined.
The File column lists all files
the package uses or defines. The Line column provides the
source-code line number. This combination of
XRef Package Explorer tabs and columns are useful for
obtaining very low-level details on the file where the package is required.
It is possible to invoke numerous XRef Package Explorers
while inspecting the scanned database. To continue exploring package file details,
click the Open button once again. The total number of
XRef Package Explorers that can be invoked depends on the
structure and contents of your Tcl source code.
At some point when invoking multiple XRef Package Explorers,
the lowest level of code is reached. At this point, you can jump to the actual
source file where the package is declared. To jump to the source file:
- Select the desired file name.
- Click the Open button. If the Komodo
editor is installed, the source file opens in Komodo. Otherwise, the file
opens in the XRef Component Source
Code Viewer.
- Within the source file, navigate to the line of code specified in the
XRef Package Explorer.
Top
The Files tab displays the Tcl files
used in the scanned Tcl source code. Files are presented in a collapsible
tree that can be expanded to drill down into the commands,
variables and namespaces used within a particular file. Click the
Files column to sort file names in either ascending
or descending order.
To filter files:
- Click the Filter
button.
The Filter Files screen appears.
- Enter the filter condition in the Files text box.
- Select a filter action:
- Click Ok to enable and close the filter.
- Click Apply to enable the filter.
The filter screen stays open.
- Click Cancel to abort and close the filter.
Use the Open
button to view details
on a particular file. This button opens the selected file in a code editor. See
Jumping to the File Source
Code for more information.
Alternatively, drill down into a file list, using the expanding and
collapsing tree nodes, to display the packages, namespaces, commands,
and variables used in a particular file. Using the Open
button with one of these components invokes an
XRef Component Explorer window
specific to that code component. For example, opening a variable component
launches an XRef Variable Explorer. To open the details of
one of these components, see:
To jump to the file's source code:
- Select the desired file name.
- Click the Open button. If the Komodo editor is
installed, the source file opens in Komodo. Otherwise, the file opens
in the XRef Component Source Code Viewer.
Note: Double-clicking the file name also
launches the source file into a viewer.
Top
The Namespaces tab alphabetically displays
all namespaces used and defined within the scanned Tcl source code.
The #Definitions and #Uses columns
display the number of times each namespace is used within the scanned
Tcl source code. Click a column title to sort namespace content in ascending or
descending order. The current sort column selected is shaded pink.
Initially, the Cross Reference Tool explorer only displays the
global namespace '::' in the component display. The global
namespace is the parent node of all namespaces organized within a collapsible
tree. Expand the global node to view all namespaces under the parent namespace.
Further expand a particular namespace node to view all commands and
variables nested within the scope of that namespace.
To filter namespaces:
- Click the Filter
button. The
Filter Namespaces screen appears.
- Enter the filter conditions, based-on any combination of the
following:
- Namespace: The name of the namespace.
- #Definitions: Number of times the namespace is
defined.
- #Uses: Number of times the namespace is used.
- Select a filter action:
- Click Ok to enable and close the filter.
- Click Apply to enable the filter.
The filter screen stays open.
- Click Cancel to abort and close the filter.
Use the Open
button to view details on a particular namespace, such as the name of the file
where the namespace exists. Opening namespace details invokes an
XRef Namespace Explorer window, which displays lower-level
code details specific to the namespace selected. To open a namespace's
details in an XRef Namespace Explorer window:
- Select the desired namespace.
- Click the Open button. An
XRef Namespace Explorer window appears. This explorer
is titled 'XRef Namespace: [::namespace_name]'. Note: Alternatively,
double-click the namespace name to invoke and
XRef Namespace Explorer.
The XRef Namespace Explorer displays the namespaces,
commands, and variables that are within the scope of the selected namespace
component. These components are accessible though toggling these component tabs.
The Uses and Definition tabs list the files
that are within the scope of this namespace. Both the Uses
and Definitions tabs contain the following columns:
- File column: The file(s) where the namespace is
used or defined.
- Line column: Provides the source-code line number
where the package is used or defined.
- Objects? column: Displays 'yes' if objects
are defined within the specified location, otherwise, 'no'.
- Begin column: The number of bytes in the file
before the namespace definition.
- Size column: The length of the definition in bytes.
This combination of XRef Namespace Explorer tabs and
columns are useful for obtaining very low-level details on the components within
the selected namespace.
It is possible to invoke numerous XRef Namespace Explorers
while inspecting the scanned database. To continue exploring namespace
component details, click the Open button once again.
The total number of XRef Namespace Explorers that can
be invoked depends on the structure and contents of your Tcl source code.
Alternatively, drill down into a namespace list, using the expanding and
collapsing tree nodes, to display the commands and variables
within the scope of a particular namespace. Using the Open
button with one of these components invokes an
XRef Component Explorer window
specific to that code component. To open the details of one of these
components, see:
Use the Show parent namespace
 button to invoke
an XRef Namespace Explorer that displays the parent
namespace of the current namespace. To view the parent namespace of the
current namespace:
- Click the Show parent namespace button. An
XRef Namespace Explorer appears.
The title of this explorer follows the pattern:
'XRef Namespace: [::namespace_name]'.
Note: The global namespace '::'
does not have a parent.
At some point when invoking multiple
XRef Namespace Explorers, the lowest
level of code is reached. At this point, you can jump to the actual
source file where the namespace either used or defined.
To jump to the source file:
- Select the desired namespace name.
- Click the Open button. If the Komodo editor is
installed, the source file opens in Komodo. Otherwise, the file opens in
the XRef Component Source Code
Viewer.
- Within the source file, navigate to the line of code specified in the
XRef Namespace Explorer.
Top
The Commands tab alphabetically displays
all commands used and defined within the scanned Tcl source code.
The #Definitions and #Uses columns
display the number of times each command is used within the scanned Tcl
source code. Click a column title to sort command content in ascending or
descending order. The current sort column selected is shaded pink.
Commands are presented in a collapsible tree that can be expanded to drill
down into the variables used and defined within a particular command.
To filter commands:
- Click the Filter
button. The
Filter Commands screen appears.
- Enter the filter conditions, based-on any combination of the
following:
- Name: Command name.
- #Definitions: Number of times the command is
defined.
- #Uses: Number of times the command is used.
- Select a filter action:
- Click Ok to enable and close the filter.
- Click Apply to enable the filter.
The filter screen stays open.
- Click Cancel to abort and close the filter.
Use the Open
button to view details on a particular
command, such as the variables used within the command.
Opening a command's details invokes an XRef Command Explorer
window, which displays lower-level code details specific to the command selected.
To open command details in an XRef Command Explorer window:
- Select the desired command.
- Click the Open button. An
XRef Commands Explorer window appears.
This explorer is titled 'XRef Command: [command_name]'.
Note: Alternatively, double-click the command name to invoke an
XRef Command Explorer.
Alternatively, drill down into a command list, using the expanding and
collapsing tree nodes, to display the variables defined and used within
a particular command. See,
Opening Variable Details for more information.
The XRef Command Explorer displays the variables that are
used and defined within the selected command component.
Variable components are accessible though toggling to the
Variable tab. Toggle between the Uses
and Definitions tabs to view what files are used and where
those files are defined. The Definitions tab contains the
following columns:
- File column: The file(s) where the command is
defined.
- Line column: Provides the source-code line number
where the command is defined.
- Type column: The component type
(command or variable).
- Prot column: Component protection level.
For example, 'public'.
- Scope column: The scope of the command.
- Origin? column: Displays the name of the command at
its original location if imported into a namespace.
Displays the initial name of the command if renamed.
This combination of XRef Command Explorer tabs and columns
is useful for obtaining low-level details on the components within
the selected command. It is possible to invoke numerous XRef Command
Explorers while inspecting the scanned database. To continue exploring
command component details, click the Open button once
again. The total number of XRef Command Explorers that can
be invoked depends on the structure and contents of your Tcl source code.
Use the Show execution namespace
button to invoke
an XRef Command Explorer, which displays the parent
namespace of the current command. To view the parent namespace of the
current command:
- Click the Show execution namespace button. An
XRef Command Explorer appears.
Note: The global namespace '::'
does not have a parent.
Use the Show origin
 button to show the origin of
the command.
- Click the Show origin button. An
XRef Command Explorer appears displaying the origin of
the command.
At some point when invoking multiple XRef Command Explorers,
the lowest level of code is reached. At this point, you can jump to the actual
source file where the command is declared. To jump to the source file:
- Select the desired command name.
- Click the Open button. If the Komodo editor is
installed, the source file opens in Komodo. Otherwise, the file opens in the
XRef Component Source Code Viewer.
- Within the source file, navigate to the line of code specified in the
XRef Command Explorer.
Top
The Variable tab alphabetically lists
all variables used and defined within the scanned Tcl source code.
The #Definitions and #Uses columns
display the number of times each variable is used. This tab provides the
lowest-level view of the database. For this reason, variables are presented
in a flat list and cannot be expanded for drilling further down into the
code.
To filter variables:
- Click the Filter
button. The
Filter Variables screen appears.
- Enter the filter conditions, based on any combination of the
following:
- Scope: Variable scope.
- Name: Variable name.
- #Definitions: Number of times the variable is
defined.
- #Uses: Number of times the variable is used.
- Select a filter action:
- Click Ok to enable and close the filter.
- Click Apply to enable the filter.
The filter screen stays open.
- Click Cancel to abort and close the filter.
Use the Open
button to view details on a particular
variable, such as the files containing the variable definitions.
Opening a variable's details invokes an XRef Variable Explorer
window, which displays lower-level code details specific to the variable
selected. To open a variable's details in an
XRef Variable Explorer window:
- Select the desired variable.
- Click the Open button. An
XRef Variable Explorer window appears. This explorer is
titled 'XRef Variable: [namespace :: variable_name]'.
Note: Alternatively, double-click the variable name to
invoke an XRef Variable Explorer.
The XRef Variable Explorer displays the files where the
selected variable is used and defined. Toggle between the
Uses and Definitions tabs to
view the all the files where the variable is used and defined. The
Definitions tab contains the following columns:
- File column: The file(s) where the variable is
defined.
- Line column: Provides the source-code line number
where the variable is defined.
- Type column: The variable definition type.
- Origin column: Displays the name of the variable at
its original location if imported into a namespace or procedure scope.
- Callers? column: Commands that call the procedure the
specified variable belongs to. This is only for variables imported into
a procedure scope via
[upvar].
Use the Show defining scope
button to invoke
an XRef Variable Explorer, which displays the namespace or
procedure the variable is defined in. To view the namespace or procedure
scope of the variable:
- Click the Show defining scope button. An
XRef Variable Explorer appears.
Note: The global namespace '::'
does not have a parent.
Use the Show origin
button to show the origin of the
variable.
- Click the Show origin button. An
XRef Variable Explorer appears displaying the origin
of the variable.
To jump to a variable's source code:
- Select the desired file where the variable is used or declared.
- Click the Open button. If the Komodo editor
is installed, the source variable opens in Komodo. Otherwise, the variable
opens in the XRef Component
Source Code Viewer. Note:
Double-clicking the variable name also launches the source file
into a viewer.
Top
The Cross Reference Tool builds component databases by scanning
the Tcl source contained in the specified input. Use File | Save
to store the extracted component information in a database. Cross Reference Tool
database files have a ".txr" extension. There are two approaches
to building a database for use with the XRef tool. These include:
- Specifying Tcl Source Code Files
- Specifying Projects and Packages
The XRef Tool can extract Tcl program component information
from various Tcl source files. On the command-line, specify the input as follows:
Windows
- Command Line:
tclxref.exe -scan dbfile.txr file1.tcl file2.tcl ...
Where dbfile is the name of the database file used to store the
extracted component information.
Unix
- Shell Prompt:
tclxref -scan dbfile.txr file1.tcl file2.tcl ...
Where dbfile is the name of the database file used to store the
extracted component information.
The Cross Reference Tool can extract program component information from
programs and packages contained in TclApp (or Prowrap) projects,
Tcl Dev Kit Package definitions (".tap" files), and from Komodo
project files. Use the Windows File Menu, command line, or the Unix shell
prompt as follows:
Windows
File Menu:
- TclApp Projects: File | Scan files for database
| Tcl Dev Kit TclApp/Prowrap project
- Package Definitions: File | Scan files for database
| Tcl Dev Kit Package Definition
- TEApot Package Definitions: File | Scan files for
database | TEApot meta data
- Komodo Project Files: File | Scan files for database
| Komodo project
Command Line:
- TclApp Projects:
tclxref.exe -tpj tclapp.tpj
- TAP Package Definitions:
tclxref.exe -tap package.tap
- TEApot Package Definitions:
tclxref.exe -teapot teapot.txt
- Komodo Project Files:
tclxref.exe -komodo project.kpf
Unix
Shell Prompt:
- TclApp Projects:
tclxref -tpj tclapp.tpj
- TAP Package Definitions:
tclxref -tap package.tap
- TEApot Package Definitions:
tclxref -teapot teapot.txt
- Komodo Project Files:
tclxref -komodo project.kpf
Use the following commands to load a database file into an
XRef explorer window. XRef tool database files have a ".txr" extension.
Windows
- File Menu: File | Open database
- Command Line:
tclxref.exe -gui dbfile
Where dbfile is the name of the database file used to store the
extracted component information.
Unix
- File Menu: File | Open database
- Shell Prompt:
tclxref -gui dbfile.txr
Where dbfile is the name of the database file used to store the
extracted component information.
Opening a Database in a New Window
To open a database file in a new XRef explorer window:
Windows
- File Menu: File | Open database in new window
To close a Tcl database file:
Windows
Top
|
icon
denotes a package component.
icon denotes a
file component.
icon denotes a
namespace component.
icon denotes a
command component.
icon denotes a
variable component.