((section 2 "Outdated egg!" (p "This is an egg for CHICKEN 4, the unsupported old release.  You're almost certainly looking for " (int-link "/eggref/5/trace" "the CHICKEN 5 version of this egg") ", if it exists.") (p "If it does not exist, there may be equivalent functionality provided by another egg; have a look at the " (link "https://wiki.call-cc.org/chicken-projects/egg-index-5.html" "egg index") ". Otherwise, please consider porting this egg to the current version of CHICKEN.") (tags "egg") (toc)) (section 2 "trace" (section 3 "Introduction" (p "The extension provides traced execution of procedures and setting breakpoints on procedure entry.") (p "This replaces the tracing facilities of CHICKEN versions prior to 4.2.12.")) (section 3 "Requirements" (p (int-link "/eggref/4/advice" "advice") ", " (int-link "/eggref/4/miscmacros" "miscmacros"))) (section 3 "Documentation" (section 4 "trace" (def (sig (procedure "(trace [PROCEDURE ...])" (id trace))) (p "Modifies the given procedures by printing some information on entry and exit. When given no arguments, " (tt "(trace)") " lists all currently traced procedures.") (p "Note that " (tt "PROCEDURE") " may be any procedure and doesn't necessarily have to be a toplevel definition."))) (section 4 "untrace" (def (sig (procedure "(untrace [PROCEDURE ...])" (id untrace))) (p "Removes tracing from " (tt "PROCEDURE ...") ", which should previously have been traced with " (tt "trace") ". When given no arguments, " (tt "(untrace)") " removes untraces all currently traced procedures."))) (section 4 "trace/untrace" (def (sig (procedure "(trace/untrace PROCEDURE ...)" (id trace/untrace))) (p "Toggles tracing on/off for the given procedures."))) (section 4 "trace-module" (def (sig (procedure "(trace-module MODULENAME ...)" (id trace-module))) (p "Traces all exported toplevel procedures of the modules with the names given in " (tt "MODULENAME ...") ". The module must already be loaded. Note that core-library modules can not be traced."))) (section 4 "untrace-module" (def (sig (procedure "(untrace-module MODULENAME ...)" (id untrace-module))) (p "Untraces all currently traced exports of the given modules."))) (section 4 "break" (def (sig (procedure "(break [PROCEDURE ...])" (id break))) (p "Modifies the given procedures to signal a condition on entry. The condition is of the kinds " (tt "exn") " and " (tt "breakpoint") " and will terminate execution unless caught. In the interpreter, the condition is accessible on the toplevel using the " (tt ",exn") " command. Use " (tt "(continue)") " to continue execution. If no arguments are given, " (tt "(break)") " lists all procedures that currently have breakpoints set.") (p "Note that " (tt "PROCEDURE") " may be any procedure and doesn't necessarily have to be a toplevel definition."))) (section 4 "unbreak" (def (sig (procedure "(unbreak [PROCEDURE ...])" (id unbreak))) (p "Removes breakpoints from the given procedures (or from all, if no arguments are given)."))) (section 4 "continue" (def (sig (procedure "(continue [CONDITION])" (id continue)) (procedure "(c [CONDITION])" (id c))) (p "Continues execution from the breakpoint that signalled " (tt "CONDITION") ", or from the last breakpoint if " (tt "CONDITION") " is not given."))) (section 4 "trace-output-port" (def (sig (parameter "(trace-output-port [PORT])" (id trace-output-port))) (p "Specifies the port to which tracing information should be written and defaults to the value of " (tt "(current-output-port)") ".")))) (section 3 "trace-verbose" (def (sig (parameter "(trace-verbose [BOOL])" (id trace-verbose))) (p "If true (the default) show a message when enabling or disabling trace- or break-points for a procedure."))) (section 3 "trace-length-limit" (def (sig (parameter "(trace-length-limit [LIMIT])" (id trace-length-limit))) (p "This allows you to determine the maximum length of the part of the output that shows the traced procedure plus its arguments.  " (tt "LIMIT") " is a number of characters, or " (tt "#f") " in case you don't want to limit it (the default)."))) (section 3 "trace-call-sites" (def (sig (parameter "(trace-call-sites [BOOL])" (id trace-call-sites))) (p "If true, show call site information in the trace, which makes it easier to see where the procedure is called from.  This information is taken from the trace buffer: it shows the most recent entry in that buffer, so this only works reliably if the call sites aren't optimised away and are compiled with " (tt "-d2") " or higher (and " (tt "-no-trace") " is not used).") (p "This option defaults to " (tt "#f") "."))) (section 3 "trace-call-site-length-limit" (def (sig (parameter "(trace-call-site-length-limit [LIMIT])" (id trace-call-site-length-limit))) (p "When " (tt "trace-call-sites") " is " (tt "#t") ", this allows you to determine the maximum length of the call site text.  " (tt "LIMIT") " is a number of characters, or " (tt "#f") " in case you don't want to limit it.") (p "This option defaults to " (tt "100")))) (section 3 "License" (p "This code is placed into the public domain.")) (section 3 "Version history" (dl (dt "0.9") (dd "Added " (tt "trace-length-limit") " and added call site tracing (thanks to Matt Welland).") (dt "0.8") (dd "Changed " (tt "trace-module") " to only trace exported procedures, not other objects.") (dt "0.7") (dd "Fixed scrutinizer warnings about procedure call with wrong argument count (#842, thanks to Mario Goulart).") (dt "0.6") (dd "added " (tt "trace-module") " and " (tt "untrace-module")) (dt "0.4") (dd "added " (tt "trace/untrace") " and " (tt "trace-verbose")) (dt "0.3") (dd "handles non-local exits correctly") (dt "0.2") (dd "fixed incorrect category") (dt "0.1") (dd "initial release")))))