.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Trace 3pm"
.TH Trace 3pm "2021-01-04" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Devel::Trace \- Print out each line before it is executed (like "sh \-x")
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  perl \-d:Trace program
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
If you run your program with \f(CW\*(C`perl \-d:Trace program\*(C'\fR, this module
will print a message to standard error just before each line is executed.  
For example, if your program looks like this:
.PP
.Vb 1
\&        #!/usr/bin/perl
\&        
\&        
\&        print "Statement 1 at line 4\en";
\&        print "Statement 2 at line 5\en";
\&        print "Call to sub x returns ", &x(), " at line 6.\en";
\&        
\&        exit 0;
\&        
\&        
\&        sub x {
\&          print "In sub x at line 12.\en";
\&          return 13;
\&        }
.Ve
.PP
Then  the \f(CW\*(C`Trace\*(C'\fR output will look like this:
.PP
.Vb 6
\&        >> ./test:4: print "Statement 1 at line 4\en";
\&        >> ./test:5: print "Statement 2 at line 5\en";
\&        >> ./test:6: print "Call to sub x returns ", &x(), " at line 6.\en";
\&        >> ./test:12:   print "In sub x at line 12.\en";
\&        >> ./test:13:   return 13;
\&        >> ./test:8: exit 0;
.Ve
.PP
This is something like the shell's \f(CW\*(C`\-x\*(C'\fR option.
.SH "DETAILS"
.IX Header "DETAILS"
Inside your program, you can enable and disable tracing by doing
.PP
.Vb 2
\&    $Devel::Trace::TRACE = 1;   # Enable
\&    $Devel::Trace::TRACE = 0;   # Disable
.Ve
.PP
or
.PP
.Vb 2
\&    Devel::Trace::trace(\*(Aqon\*(Aq);  # Enable
\&    Devel::Trace::trace(\*(Aqoff\*(Aq); # Disable
.Ve
.PP
\&\f(CW\*(C`Devel::Trace\*(C'\fR exports the \f(CW\*(C`trace\*(C'\fR function if you ask it to:
.PP
.Vb 1
\&    import Devel::Trace \*(Aqtrace\*(Aq;
.Ve
.PP
Then if you want you just say
.PP
.Vb 2
\&    trace \*(Aqon\*(Aq;                 # Enable
\&    trace \*(Aqoff\*(Aq;                # Disable
.Ve
.SH "TODO"
.IX Header "TODO"
.IP "\(bu" 4
You should be able to  send the trace output to the filehandle of your choice.
.IP "\(bu" 4
You should be able to specify the format of the output.
.IP "\(bu" 4
You should be able to get the output into a string.
.PP
We'll see.
.SH "LICENSE"
.IX Header "LICENSE"
Devel::Trace 0.11 and its source code are hereby placed in the public domain.
.SH "Author"
.IX Header "Author"
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.