Import guile-1.8 as multiple upstream tarball component

[lilypond.git] / guile18 / doc / ref / scheme-debugging.texi

diff --git a/guile18/doc/ref/scheme-debugging.texi b/guile18/doc/ref/scheme-debugging.texi
new file mode 100644 (file)
index 0000000..6166b24
--- /dev/null
+++ b/guile18/doc/ref/scheme-debugging.texi
@@ -0,0 +1,124 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Guile Reference Manual.
+@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007
+@c   Free Software Foundation, Inc.
+@c See the file guile.texi for copying conditions.
+
+@page
+@node Tracing
+@section Tracing
+
+The @code{(ice-9 debug)} module implements tracing of procedure
+applications.  When a procedure is @dfn{traced}, it means that every
+call to that procedure is reported to the user during a program run.
+The idea is that you can mark a collection of procedures for tracing,
+and Guile will subsequently print out a line of the form
+
+@smalllisp
+|  |  [@var{procedure} @var{args} @dots{}]
+@end smalllisp
+
+whenever a marked procedure is about to be applied to its arguments.
+This can help a programmer determine whether a function is being called
+at the wrong time or with the wrong set of arguments.
+
+In addition, the indentation of the output is useful for demonstrating
+how the traced applications are or are not tail recursive with respect
+to each other.  Thus, a trace of a non-tail recursive factorial
+implementation looks like this:
+
+@smalllisp
+[fact1 4]
+|  [fact1 3]
+|  |  [fact1 2]
+|  |  |  [fact1 1]
+|  |  |  |  [fact1 0]
+|  |  |  |  1
+|  |  |  1
+|  |  2
+|  6
+24
+@end smalllisp
+
+While a typical tail recursive implementation would look more like this:
+
+@smalllisp
+[fact2 4]
+[facti 1 4]
+[facti 4 3]
+[facti 12 2]
+[facti 24 1]
+[facti 24 0]
+24
+@end smalllisp
+
+@deffn {Scheme Procedure} trace procedure
+Enable tracing for @code{procedure}.  While a program is being run,
+Guile will print a brief report at each call to a traced procedure,
+advising the user which procedure was called and the arguments that were
+passed to it.
+@end deffn
+
+@deffn {Scheme Procedure} untrace procedure
+Disable tracing for @code{procedure}.
+@end deffn
+
+Here is another example:
+
+@lisp
+(define (rev ls)
+  (if (null? ls)
+      '()
+      (append (rev (cdr ls))
+              (cons (car ls) '())))) @result{} rev
+
+(trace rev) @result{} (rev)
+
+(rev '(a b c d e))
+@result{} [rev (a b c d e)]
+   |  [rev (b c d e)]
+   |  |  [rev (c d e)]
+   |  |  |  [rev (d e)]
+   |  |  |  |  [rev (e)]
+   |  |  |  |  |  [rev ()]
+   |  |  |  |  |  ()
+   |  |  |  |  (e)
+   |  |  |  (e d)
+   |  |  (e d c)
+   |  (e d c b)
+   (e d c b a)
+   (e d c b a)
+@end lisp
+
+Note the way Guile indents the output, illustrating the depth of
+execution at each procedure call.  This can be used to demonstrate, for
+example, that Guile implements self-tail-recursion properly:
+ 
+@lisp
+(define (rev ls sl)
+  (if (null? ls)
+      sl
+      (rev (cdr ls)
+           (cons (car ls) sl)))) @result{} rev
+ 
+(trace rev) @result{} (rev)
+ 
+(rev '(a b c d e) '())
+@result{} [rev (a b c d e) ()]
+   [rev (b c d e) (a)]
+   [rev (c d e) (b a)]
+   [rev (d e) (c b a)]
+   [rev (e) (d c b a)]
+   [rev () (e d c b a)]
+   (e d c b a)
+   (e d c b a)
+@end lisp
+ 
+Since the tail call is effectively optimized to a @code{goto} statement,
+there is no need for Guile to create a new stack frame for each
+iteration.  Tracing reveals this optimization in operation.
+
+
+@c Local Variables:
+@c TeX-master: "guile.texi"
+@c End: