CleanCode Perl Libraries
Multi-Lingual Library Maintainability
available: Perl not available: Java not available: JavaScript not available: Certified
not available: Testable
not available: Standalone
not available: Diagnostic


pscope - Source code browser for Perl symbols.


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


        -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)


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


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


Definitions: Find matching symbol definitions only (i.e. not symbol references).


Strings: Find matching string literals (i.e. forget about Perl constructs, just find it).


Files: Find matching file names instead of scanning file contents (Unix only).


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.


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.


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


Sets the length of the filename in the output list. The default is 50 (characters).


Specifies full path to prune from tree during search.


Specifies leaves to prune from tree during search.


Specifies the root of the search tree ($HOME by default).


Find definitions and uses of a symbol:

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

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

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

Find file names using the -f option:

  % pscope -fw HTML


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.




Michael Sorens


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


CleanCode 0.9


cscope (C language tool)

CleanCode Perl Libraries Copyright © 2001-2013 Michael Sorens - Revised 2013.06.30 Get CleanCode at Fast, secure and Free Open Source software downloads