initial import of Devel-Trace 0.10 from CPAN

git-cpan-module:   Devel-Trace
git-cpan-version:  0.10
git-cpan-authorid: MJD
git-cpan-file:     authors/id/M/MJ/MJD/Devel-Trace-0.10.tar.gz

Changes

@@ -0,0 +1,5 @@
+Revision history for Perl extension Devel::Trace.
+
+0.01  Mon Sep  6 21:32:55 1999
+	- original version; created by h2xs 1.19
+

MANIFEST

@@ -0,0 +1,7 @@
+Changes
+MANIFEST
+Makefile.PL
+Trace.pm
+test.pl
+sample
+README

Makefile.PL

@@ -0,0 +1,7 @@
+use ExtUtils::MakeMaker;
+# See lib/ExtUtils/MakeMaker.pm for details of how to influence
+# the contents of the Makefile that is written.
+WriteMakefile(
+    'NAME'	=> 'Devel::Trace',
+    'VERSION_FROM' => 'Trace.pm', # finds $VERSION
+);

README

@@ -0,0 +1,81 @@
+NAME
+    Devel::Trace - Print out each line before it is executed (like `sh -x')
+
+SYNOPSIS
+      perl -d:Trace program
+
+
+DESCRIPTION
+    If you run your program with `perl -d:Trace program', this module will
+    print a message to standard error just before each line is executed. For
+    example, if your program looks like this:
+
+            #!/usr/bin/perl
+
+
+            print "Statement 1 at line 4\n";
+            print "Statement 2 at line 5\n";
+            print "Call to sub x returns ", &x(), " at line 6.\n";
+
+            exit 0;
+
+
+            sub x {
+              print "In sub x at line 12.\n";
+              return 13;
+            }
+
+
+    Then the `Trace' output will look like this:
+
+            >> ./test:4: print "Statement 1 at line 4\n";
+            >> ./test:5: print "Statement 2 at line 5\n";
+            >> ./test:6: print "Call to sub x returns ", &x(), " at line 6.\n";
+            >> ./test:12:   print "In sub x at line 12.\n";
+            >> ./test:13:   return 13;
+            >> ./test:8: exit 0;
+
+
+    This is something like the shell's `-x' option.
+
+DETAILS
+    Inside your program, you can enable and disable tracing by doing
+
+        $Devel::Trace::TRACE = 1;   # Enable
+        $Devel::Trace::TRACE = 0;   # Disable
+
+
+    or
+
+        Devel::Trace::trace('on');  # Enable
+        Devel::Trace::trace('off'); # Disable
+
+
+    `Devel::Trace' exports the `trace' function if you ask it to:
+
+        import Devel::Trace 'trace';
+
+
+    Then if you want you just say
+
+        trace 'on';                 # Enable
+        trace 'off';                # Disable
+
+
+TODO
+    *   You should be able to send the trace output to the filehandle of your
+        choice.
+
+    *   You should be able to specify the format of the output.
+
+    *   You should be able to get the output into a string.
+
+
+    We'll see.
+
+Author
+    Mark-Jason Dominus (`mjd-perl-trace+@plover.com'), Plover Systems co.
+
+    See the `Devel::Trace.pm' Page at http://www.plover.com/~mjd/perl/Trace
+    for news and upgrades.
+

Trace.pm

@@ -0,0 +1,150 @@
+# -*- perl -*-
+
+package Devel::Trace;
+$VERSION = '0.10';
+$TRACE = 1;
+
+# This is the important part.  The rest is just fluff.
+sub DB::DB {
+  return unless $TRACE;
+  my ($p, $f, $l) = caller;
+  my $code = \@{"::_<$f"};
+  print STDERR ">> $f:$l: $code->[$l]";
+}
+
+
+sub import {
+  my $package = shift;
+  foreach (@_) {
+    if ($_ eq 'trace') {
+      my $caller = caller;
+      *{$caller . '::trace'} = \&{$package . '::trace'};
+    } else {
+      use Carp;
+      croak "Package $package does not export `$_'; aborting";
+    }
+  }
+}
+
+my %tracearg = ('on' => 1, 'off' => 0);
+sub trace {
+  my $arg = shift;
+  $arg = $tracearg{$arg} while exists $tracearg{$arg};
+  $TRACE = $arg;
+}
+
+1;
+
+
+=head1 NAME
+
+Devel::Trace - Print out each line before it is executed (like C<sh -x>)
+
+=head1 SYNOPSIS
+
+  perl -d:Trace program
+
+=head1 DESCRIPTION
+
+If you run your program with C<perl -d:Trace program>, this module
+will print a message to standard error just before each line is executed.  
+For example, if your program looks like this:
+
+        #!/usr/bin/perl
+        
+        
+        print "Statement 1 at line 4\n";
+        print "Statement 2 at line 5\n";
+        print "Call to sub x returns ", &x(), " at line 6.\n";
+        
+        exit 0;
+        
+        
+        sub x {
+          print "In sub x at line 12.\n";
+          return 13;
+        }
+
+Then  the C<Trace> output will look like this:
+
+        >> ./test:4: print "Statement 1 at line 4\n";
+        >> ./test:5: print "Statement 2 at line 5\n";
+        >> ./test:6: print "Call to sub x returns ", &x(), " at line 6.\n";
+        >> ./test:12:   print "In sub x at line 12.\n";
+        >> ./test:13:   return 13;
+        >> ./test:8: exit 0;
+
+This is something like the shell's C<-x> option.
+
+=head1 DETAILS
+
+Inside your program, you can enable and disable tracing by doing
+
+    $Devel::Trace::TRACE = 1;   # Enable
+    $Devel::Trace::TRACE = 0;   # Disable
+
+or
+
+    Devel::Trace::trace('on');  # Enable
+    Devel::Trace::trace('off'); # Disable
+
+
+C<Devel::Trace> exports the C<trace> function if you ask it to:
+
+    import Devel::Trace 'trace';
+
+Then if you want you just say
+
+    trace 'on';                 # Enable
+    trace 'off';                # Disable
+
+
+=head1 TODO
+
+=over 4
+
+=item *
+
+You should be able to  send the trace output to the filehandle of your choice.
+
+=item *
+
+You should be able to specify the format of the output.
+
+=item *
+
+You should be able to get the output into a string.
+
+=back
+
+We'll see.
+
+=head1 Author
+
+=begin text
+
+Mark-Jason Dominus (C<mjd-perl-trace@plover.com>), Plover Systems co.
+
+See the C<Devel::Trace.pm> Page at http://www.plover.com/~mjd/perl/Trace
+for news and upgrades.  
+
+=end text
+
+=begin man
+
+Mark-Jason Dominus (C<mjd-perl-trace@plover.com>), Plover Systems co.
+
+See the C<Devel::Trace.pm> Page at http://www.plover.com/~mjd/perl/Trace
+for news and upgrades.  
+
+=end man
+
+=begin html
+<p>Mark-Jason Dominus (<a href="mailto:mjd-perl-trace@plover.com"><tt>mjd-perl-trace@plover.com</tt></a>), Plover Systems co.</p>
+<p>See <a href="http://www.plover.com/~mjd/perl/Trace/">The <tt>Devel::Trace.pm</tt> Page</a> for news and upgrades.</p>
+
+=end html
+
+
+=cut
+

sample

@@ -0,0 +1,14 @@
+#!/usr/bin/perl
+
+
+print "Statement 1 at line 4\n";
+print "Statement 2 at line 5\n";
+print "Call to sub x returns ", &x(), " at line 6.\n";
+
+exit 0;
+
+
+sub x {
+  print "In sub x at line 12.\n";
+  return 13;
+}

test.pl

@@ -0,0 +1,21 @@
+# Before `make install' is performed this script should be runnable with
+# `make test'. After `make install' it should work as `perl test.pl'
+
+######################### We start with some black magic to print on failure.
+
+BEGIN { $| = 1; print "1..1\n"; }
+END {print "not ok 1\n" unless $loaded;}
+use Devel::Trace;
+$loaded = 1;
+print "ok 1\n";
+
+######################### End of black magic.
+
+open S, "< sample" or die "Couldn't open sample demo file: $!; aborting";
+print while <S>;
+close S;
+print "\n";
+print "Press enter to execute this file.  \n";
+<STDIN>;
+system("perl -I./blib/lib -d:Trace sample");
+$? and die "Problem running sample program: $? exit status\n";