CleanCode Perl Libraries

Perl

Java

JavaScript

Certified
Class

Testable
Class

Standalone
Mode

Diagnostic
Enabled

NAME

pscope - Source code browser for Perl symbols.

SYNOPSIS

pscope [ -dfstiwvbahH ] ( symbol | file | pattern )

OPTIONS

        -d      just show symbol *definitions* (omit symbol *uses*)
        -f      find *files* instead of *symbols*
        -s      find *strings* instead of *symbols*
        -t      search from this directory down, not project root
        -i      ignore case
        -w      wildcard-expand suffix
        -v      verbose
        -b      remove leading blanks from output lines
        -a      examine all files (ignore file extensions)
        -h      help
        -H      longer help (manual page)

REQUIRES

Perl5.005, Getopt::Std, Pod::Usage

DESCRIPTION

Pscope finds instances of the specified symbol, string or file in your working file tree ($HOME by default, or you may override by setting the PSCOPE_ROOT environment variable, or by using the -t option).

By default, pscope finds all occurrences of the specified symbol (uses and definitions). You may alter this to find definitions only (-d), string literals (-s), or file names (-f). Note that -f is currently only implemented for Unix.

You may tailor your search with these environment variables, each of which should be set to a colon-separated list of directories:

        PSCOPE_EXCLUDE_ABSLIST  specifies full path to prune from tree
        PSCOPE_EXCLUDE_RELLIST  specifies leaves to prune from tree

If, for example, you use a source code control system which creates a storage subdirectory in each directory (e.g. CVS), you could set the PSCOPE_EXCLUDE_RELLIST to CVS to ignore each of those storage directories. Or if you have specific directories to ignore you could set PSCOPE_EXCLUDE_ABSLIST to, for example, $HOME/web/hold:$HOME/web/tmp.

Symbols are recognized as $symbol, @symbol, and %symbol, of course. But the flexibility of the Perl language requires others cases as well, even just a plain symbol as in, for example, $obj->symbol. But even further, a symbol could be a string since, for example $item{symbol} and $item{"symbol"} are equivalent. And symbols are still symbols inside genuine strings, as in "welcome $username".

Pscope goes a step further and provides support for server side includes (SSI), in a sense. With SSI, you can have symbols embedded in an HTML file. Possibly more relevant, the HTML::Template module uses symbols which must directly match those in your Perl program. So pscope will scan your html files as well.

The output (as shown in the examples below) consists of three columns: a file name, a line number, and a line context from the file. These are aligned for ease of viewing as follows: The line context column is left justified. The filenames and the line numbers are also aligned, but right-justified. The length of the filename field, in characters, defaults to 50. This may be changed with the PSCOPE_FNAME_LEN environment variable.

Pscope does not distinguish between code and comments by design. So a symbol will be found whether in a code line, an octothorp (#) comment, or a pod comment.

Command-line Options

-d: Definitions: Find matching symbol definitions only (i.e. not symbol references).
-s: Strings: Find matching string literals (i.e. forget about Perl constructs, just find it).
-f: Files: Find matching file names instead of scanning file contents (Unix only).
-w: Word boundary: Whatever you typed is treated as a prefix, rather than as a whole word. So pscope -w check would match check_dates, checkIDs, etc. You may also provide your own pattern to match, instead of a constant. Note that to match symbols, this must be a Perl regular expression, while to match files, it must be a shell regular expression. So you could enter pscope -w 'ch.*item' to match checkitem, changeitem, etc., or pscope -wf 'ch*item' to match the same words as file names.
-v: Verbose; Used with -f, displays the find command modified by PSCOPE_EXCLUDE_ABSLIST and PSCOPE_EXCLUDE_RELLIST. Used without -f, displays the pruned directories as they are encountered.
-b: Blanks; Preserve blank spaces at beginning of output lines. Normally blanks are suppressed, which is particularly handy in files where there are lots of leading spaces or tabs (as in many HTML files).

Environment Variables

PSCOPE_FNAME_LEN: Sets the length of the filename in the output list. The default is 50 (characters).
PSCOPE_EXCLUDE_ABSLIST: Specifies full path to prune from tree during search.
PSCOPE_EXCLUDE_RELLIST: Specifies leaves to prune from tree during search.
PSCOPE_ROOT: Specifies the root of the search tree ($HOME by default).

Examples

Find definitions and uses of a symbol:

  % pscope check_id
     ~/web/stuff/cgi-bin/check.pl   86 ($BRAND,$PHONE) = check_id($id);
     ~/web/stuff/cgi-bin/check.pl  106 sub check_id {
   ~/web/stuff/cgi-bin/process.pl   22 ($BRAND,$PHONE) = check_id($id);
   ~/web/stuff/cgi-bin/process.pl   46 sub check_id {
           ~/web/cgi-bin/print.pl   58 ($BRAND, $PHONE) = check_id($id);
           ~/web/cgi-bin/print.pl   79 sub check_id {

Find definitions only, using the "-d" option:

  % pscope -d month
  ~/web/cgi-bin/userid.pl  275  local( $day, $month, $year ) =
  ~/web/cgi-bin/insert.pl  379  local( $day, $month, $year ) =
   ~/web/cgi-bin/price.pl  100  $month = lookupMon($date);
   ~/web/cgi-bin/price.pl  112  ($day,$month,$time,$std,$year) =
   ~/web/cgi-bin/price.pl  128  ($day,$month,$time,$std,$year) =

Find file names using the -f option:

  % pscope -fw HTML
  /d9/home/msorens/web/lib/perl5/auto/HTML
  /d9/home/msorens/web/lib/perl5/site_perl/HTML
  /d9/home/msorens/web/lib/page.pm
  /d9/home/msorens/web/perl5/man/man3/HTML::Template.3

EXIT STATUS

Return Code 0

Normal exit.

Return Code 1

Help requested (-h or -H).

Return Code 2

-Option conflict: -s cannot be used with -d or -f.

-Bad or missing argument.

-Symbols cannot have spaces; possible intention was a string search, which requires a -s option.

BUGS

None

AUTHOR

Michael Sorens

VERSION

$Revision: 8 $ $Date: 2006-12-19 21:13:43 -0800 (Tue, 19 Dec 2006) $

SINCE

CleanCode 0.9