Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  APP::TRACE (3)

.ds Aq ’


App::Trace - Embedded debug statements, including call/return tracing



  In a program (such as the following one named "foo"), you can do the following...


  use App::Option;  # App::Trace was written to be used with App::Options
  use App::Trace;   # enable tracing support

  use Foo;
  sub run {
      &App::sub_entry if ($App::trace);        # trace subroutine entry
      my $foo = Foo->new();
      &App::sub_exit() if ($App::trace);       # trace subroutine exit

  in a module (i.e., you can do the following...

  package Foo;
  # new(): a generic object constructor
  sub new {
      &App::sub_entry if ($App::trace);        # trace method entry
      my ($this, @args) = @_;
      my $class = ref($this) || $this;
      my $self = { @args };
      bless $self, $class;
      &App::sub_exit($self) if ($App::trace);  # trace method exit
  sub run {
      &App::sub_entry if ($App::trace);        # trace method entry
      print "Expression: (1 + 2) * (7 - (2*2))\n";
      my $value = $self->multiply(
          $self->add(1, 2),
          $self->subtract(7, $self->multiply(2, 2))
      print "Value:      $value\n";
      &App::sub_exit() if ($App::trace);       # trace method exit
  sub add {
      &App::sub_entry if ($App::trace);        # trace method entry
      my ($self, $operand1, $operand2) = @_;
      my $value = $operand1 + $operand2;
      &App::sub_exit($value) if ($App::trace); # trace method exit
  sub subtract {
      &App::sub_entry if ($App::trace);        # trace method entry
      my ($self, $operand1, $operand2) = @_;
      my $value = $operand1 - $operand2;
      &App::sub_exit($value) if ($App::trace); # trace method exit
  sub multiply {
      &App::sub_entry if ($App::trace);        # trace method entry
      my ($self, $operand1, $operand2) = @_;
      my $value = $operand1 * $operand2;
      &App::sub_exit($value) if ($App::trace); # trace method exit

  Then when you invoke the program normally, you get no debug output.
  You only get the expected program output.


  However, when you invoke the program with something like the following...

    foo --trace

  you get trace output like the following.


  Try the following options...

    foo --trace --trace_width=0    # unlimited width (long lines wrap on screen)
    foo --trace --trace_width=78   # set max width of output
    foo --trace --trace_width=78 --trace_justify    # right-justify package
    foo --trace=main               # only trace subs in "main" package
    foo --trace=Foo                # only trace subs in "Foo" package
    foo --trace=Foo.multiply       # only trace the multiply() method in the Foo package
    foo --trace=main,       # trace a combo of full packages and specific methods


App::Trace provides debug/tracing support for perl programs and modules.

The basic concept is that you put a special call at the beginning and end of each subroutine/method, and when tracing is enabled, you can see the flow of your program.

This module reflects my dislike of the perl debugger. I also dislike putting in print statements to debug, then commenting them out when I’m done. I would rather put debug statements in my code and leave them there. That way, when programs work their way into production, they can still be debugged by using appropriate command line options.

Perl modules which are written to be used with App::Trace can be debugged easily without entering the perl debugger. The output of tracing is a program trace which shows the entry and exit of every subroutine/method (and the arguments). This trace is printed in a format which allows you to follow the flow of the program.

Someday I might figure out how to do this at a language level so it will work on any module, not just ones which have been specially instrumented with &App::sub_entry() and &App::sub_exit() calls. In fact, I started work on this with the module, but that was specific to perl version 5.6.x and didn’t work with 5.8.x. That’s when I decided I would write App::Trace which would work on any Perl (even back to 5.5.3, which I consider to be the first Perl 5 to support for deep backward compatibility).

The App-Trace distribution began life as a collection of routines pulled out of the App-Context distribution. I created App-Trace because these routines were very useful independent of the rest of the framework provided by App-Context.

App::Trace is dependent on App::Options. It is possible to use App::Trace without App::Options, but they share a common convention with regard to certain global variables in the App package/namespace.

It is expected that when App::Trace is mature, the routines included will be removed from module in the App-Context distribution. The App-Context distribution will then be dependent on App::Trace for these features.

Attributes, Constants, Global Variables, Class Variables

    Global Variables

 * Global Variable: %App::scope              scope for debug or tracing output
 * Global Variable: $App::scope_exclusive    flag saying that the scope is exclusive (a list of things *not* to debug/trace)
 * Global Variable: %App::trace              trace level
 * Global Variable: $App::DEBUG              debug level
 * Global Variable: $App::DEBUG_FILE         file for debug output


    * Signature: &App::sub_entry;
    * Signature: &App::sub_entry(@args);
    * Param:     @args        any
    * Return:    void
    * Throws:    none
    * Since:     0.01

This is called at the beginning of a subroutine or method (even before $self may be shifted off).


    * Signature: &App::sub_exit(@return);
    * Param:     @return      any
    * Return:    void
    * Throws:    none
    * Since:     0.01

This subroutine is called just before you return from a subroutine or method.


    * Signature: &App::in_debug_scope
    * Signature: App->in_debug_scope
    * Param:     <no arg list supplied>
    * Return:    void
    * Throws:    none
    * Since:     0.01

This is called within a subroutine or method in order to see if debug output should be produced.

  if ($App::debug && &App::in_debug_scope) {
      print "This is debug output\n";

Note: The App::in_debug_scope subroutine also checks $App::debug, but checking it in your code allows you to skip the subroutine call if you are not debugging.

  if (&App::in_debug_scope) {
      print "This is debug output\n";


    * Signature: &App::debug_indent()
    * Signature: App->debug_indent()
    * Param:     void
    * Return:    $indent_str     string
    * Throws:    none
    * Since:     0.01

This subroutine returns the $indent_str string which should be printed before all debug lines if you wish to line the debug output up with the nested/indented trace output.


 * Author:  Stephen Adkins <>
 * License: This is free software. It is licensed under the same terms as Perl itself.


Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 APP::TRACE (3) 2006-08-19

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.