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.

  Popup Menus

    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 1.19 2000/09/21 20:54:57 kiesling Exp $

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

