Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
App::Trace(3)	      User Contributed Perl Documentation	 App::Trace(3)

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

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

	 #!/usr/bin/perl

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

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

	 in a module (i.e. Foo.pm), 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
	     return($self);
	 }
	 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
	     return($value);
	 }
	 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
	     return($value);
	 }
	 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
	     return($value);
	 }

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

	   foo

	 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,Foo.run	  # trace a combo of full packages and specific	methods

DESCRIPTION
       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 Aspect.pm 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 App.pm 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

   sub_entry()
	   * 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).

   sub_exit()
	   * 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.

   in_debug_scope()
	   * 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";
	 }

   debug_indent()
	   * 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.

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

SEE ALSO
perl v5.24.1			  2006-08-19			 App::Trace(3)

NAME | SYNOPSIS | DESCRIPTION | Attributes, Constants, Global Variables, Class Variables | ACKNOWLEDGEMENTS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=App::Trace&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help