NAME

calltree - Who called whom

SYNOPSIS

calltree    --exclude=<pkg1>...<pkgN> --include=<pkg3>...<pkgQ>
            --noempty
            [ -Iinc/path1 -Iinc/path2 -I...] [ -Mmodule1 -Mmodule2 -M...]
            [ -e <CODE> | script.pl ]

calltree    --chkfunc=<fnc1>...<funcN>
            [ -Iinc/path1 -Iinc/path2 -M...] [ -Mmodule1 -Mmodule2 -M...]
            [ -e <CODE> | script.pl ]

OPTIONS

• --exclude

  A comma-separated list of regular expressions. Functions matching any of the expressions are excluded from the report.

• --include

  A comma-separated list of regular expressions. Functions matching any of the expressions are always included from the report (even when they match one in --exclude.

• --chkfunc

  A comma-separated list of regular expressions. All functions matching one of the expression are checked whether they are called at all. This function cannot be used together with --exclude or --include.

• --noempty

  Exclude functions from the generated report that do not call any other functions.

• -Ipath

  The same as perl's -I. This is used to add directories to @INC.

• -Mmodule

  The same as perl's -M. This runs the code after useing the module module. Can be used to print the calltree of a module:

  calltree -MMy::Module

• -e 'CODE'

  The same as perl's -e. This is used to pass the code that shall be inspected.

DESCRIPTION

calltree inspects the OP-tree of a program or module after compilation is done and creates a report showing which method and function has been called by whom.

Output is pretty straightforward. When not using the --chkfunc switch, it looks like this:

Package::func  (/path/to/Package.pm)
  method   'some_method'                                      (68)
  function 'Pkg::function'                                    (70)
  
Package::nest::otherfunc  (/path/to/Package/nest.pm)
  method   'foobar'                                           (10)

...

__MAIN__ (-)
  function 'Package::func::func'                              (3)

It begins with the fully qualified function followed by the path to the file in which this function resides. After that a list of function and method calls follows. The line where this call happens is prepended.

The last in the list is always __MAIN__ which is the report for what happens in package main. This doesn't necessarily exist (e.g. when you only inspect a module).

In --chkfunc mode, output looks like this:

calltree --chkfunc=foo,bar -e 'sub foo {1} print foo()'
These patterns did not match any called function:
  bar

These functions were called:
  function main::foo        from __MAIN__           at line 1

EXAMPLES

See the calltree of a script:

calltree script.pl

Or one of a script given on the command-line:

calltree -e '...'

See the calltree of the module URI:

calltree -MURI

The same, but skip empty functions (those that do not make calls to others):

calltree --noempty -MURI

The same, but ignore functions not in the URI:: namespace:

calltree --noempty --exclude=. --include=URI:: -MURI

Thus, use --exclude=. to exclude everything and then include only functions from the URI:: namespace with --include=URI::.

And finally check whether a particular function is called at all:

calltree --chkfunc=Carp::croak -MURI

ENVIRONMENT VARIABLES

calltree uses PERLLIB and PERL5LIB in a similar fashion as perl does.

TODO

• Add a count for function calls

• Better control over --chkfunc (packages can't currently be excluded)

• ...

AUTHOR

Original idea and code by Mark Jason Dominus <mjd@plover.com>.

Current maintainer Tassilo von Parseval <tassilo.parseval@post.rwth-aachen.de>.

COPYRIGHT AND LICENSE

Copyright (C) 2004 by Tassilo von Parseval

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.2 or, at your option, any later version of Perl 5 you may have available.

cpanm Devel::Calltree

perl -MCPAN -e shell
install Devel::Calltree