The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Tk-Browser-0.81
River stage zero No dependents
/ Tk::Browser

NAME

Tk::Browser.pm -- Perl library browser.

SYNOPSIS

# Call from a shell prompt:

  # browser <module_pathname>  # Open a library file by name
  # browser <package_name>     # Open a package(s) matching 
                               # <package_name> (Unix specific);
  # browser                    # Browse the entire library.

# Call from a Perl Script:

  use Tk::Browser;
  use Lib::Module;

  # Construct Browser object:
  $b = new Browser;   

  # Browse entire library:
  $b -> open();       

  # Browse a package by name:
  $b -> open(package => IO::File);   

  # Browse a package by module path name:
  $b -> open(pathname =>"/usr/local/lib/perl5/5.6.0/open.pm");

DESCRIPTION

Tk::Browser.pm creates a library browser for Perl modules. A browser has three sub-windows, a module listing at the upper left, a symbol listing at the upper right, and a text display in the bottom half of the browser main window.

The Tk::Browser.pm module contains mainly the window and user interface code. The Lib:: modules, included in the distribution archive, do the actual scanning of the library files and keep track of symbol reference information.

Clicking with the left mouse button in the upper left-hand pane selects a package module. If no module was specified when the browser was opened with the Tk::Browser::open method, the the Lib::Module package scans first instance of each .pm and .pl file in the Perl library's @INC array of directories. Duplicate library modules and symlinked directories are skipped.

Default Perl configurations include '.' in the @INC path, so that modules in the current directory and its subdirectories are also scanned.

The window in the upper right-hand corner of the browser lists all of the symbols and their values of the currently selected package's symbol table hash (stash), a lexical scan of the source file, and, optionally, records the results of a cross-reference scan, depending on the settings of the Symbol menu options.

A text window in the lower half of the frame optionally displays the module source code, POD documentation, or version and file information, depending on the setting of the View menu options.

All of the menu bar commands are described in section, MENU FUNCTIONS, below.

Clicking the right mouse button in a subwindow displays a pop-up menu for that pane. Popup menu functions are also described below.

By default, the browser lists all Perl source modules, when no modules are specified to the open() method. The module class hierarchy then starts with UNIVERSAL, the abstract superclass of all Perl modules, the default Perl class. Selecting the main:: Symbol Table display from the View menu displays all of the symbols in the default stash, including those of the the Browser itself. In this stash also are the path names of library modules that are imported at run time.

All imported modules, not only source modules with the *.pm and *.pl extension can be listed and browsed separately using the Modules ==> List Imports menu option.

Opening a browser with the open() method's 'package' option browses the first package which has a matching name, after locating it in the Perl library's @INC directories. The 'pathname' argument specifies the path name of a single Perl module to browse.

The Perl script 'browser', listed below, is included in the archive. It will open a Browser from a shell prompt. If a the pathname of a module is supplied as the argument it will open that module. If the argument is a package name, if will search the library and open that package:

  #!/usr/bin/perl 
  # browser -- Launcher for Browser.pm
  # Substitute path of the perl binary on your system
  # in the line above.
  # When installing, change permissions to executable:
  #  'chmod +x browser'.  

  use Tk;
  use Tk::Browser;
  use Lib::Module;
  use Env qw(_);

  my $b;

  $b = new Tk::Browser;

  if( -e $ARGV[0] ) { # assume it's a file name;
    $b -> open(pathname => $ARGV[0]);
  } elsif( $ARGV[0] ) { # assume the arg's a package name and 
                        # we have to scan for it.
    $b -> open(package => $ARGV[0]);
  } else {  # No argument: open everything.
    $b -> open;
  }

  MainLoop;

  # End of browser listing

MENU FUNCTIONS

File Menu

Open Selected Module -- Open a new browser for the module selected in the module list window.

Save Info... -- Open a FileBrowser and prompt for a file name. Save the information in each of the browser windows to the text file.

Exit -- Close the browser and exit the program.

Edit Menu

Cut -- Move selected text from the editor pane to the X clipboard.

Copy -- Copy selected text from the editor pane to the X clipboard.

Paste -- Insert text from the X clipboard at the text editor pane's insertion point.

View Menu

Source -- View module source code of selected module.

POD Documentation -- Format and view the selected module's POD documentation, if any.

Module Info -- List the selected module's package name, module filename, version, and superclasses.

main:: Stash -- List symbols in the current main:: Stash. (That is the stash of the browser.)

Package Stashes -- Filter current symbol list to show only secondary stashes and their symbols.

Library Menu

Read Again -- Re-scan the Perl library directories and files.

View Imported -- List and optionally open files listed in the main:: stash that were imported by Perl.

Packages Menu

Stash -- View symbols that are in the module's symbol table hash.

Lexical -- View symbols parsed from the module's source code.

Cross References -- For non-local stash symbols, check for cross references in other modules that have been loaded by the interpreter. Warning: Cross referencing can take a considerable amount of time.

Help Menu

About -- Display the version number and authorship of the Browser library.

Help -- View the Browser's POD documentation.

Find -- Search for text in that pane where the menu is popped up by pressing the right mouse button.

Open Module -- In the module list window, query for the module name on which to open a new browser.

COPYRIGHT

The software in this package is distributed under the terms of the Perl Artistic License. Please refer to the file "Artistic" in the distribution archive file.

REVISION

$Id: Browser.pm,v 0.81 2001/07/15 18:38:21 kiesling Exp $

SEE ALSO

The manual pages for: Lib::Module(3), Tk(3), perl(1), perlmod(1), perlmodlib(1), perlreftut(1), and perlref(1)