/ 
Devel-Calltree-0.00_2
River stage zero No dependents
/ calltree

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.

The default 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

PROVIDING YOUR OWN REPORT FUNCTIONS

Not yet.

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

Original code copyright (C) 2003 by Mark Jason Dominus

Revisions copyright (C) 2004 by Tassilo von Parseval

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 247:

You forgot a '=back' before '=head1'