diff options
Diffstat (limited to 'blt/html/watch.html')
| -rw-r--r-- | blt/html/watch.html | 140 |
1 files changed, 140 insertions, 0 deletions
diff --git a/blt/html/watch.html b/blt/html/watch.html new file mode 100644 index 00000000000..2059c0723a7 --- /dev/null +++ b/blt/html/watch.html @@ -0,0 +1,140 @@ + <!-- manual page source format generated by PolyglotMan v3.0.8+XFree86, --> +<!-- available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z --> + +<HTML> +<HEAD> +<TITLE>watch(n) manual page</TITLE> +</HEAD> +<BODY BGCOLOR="#efefef" TEXT="black" LINK="blue" VLINK="#551A8B" ALINK="red"> +<A HREF="#toc">Table of Contents</A><P> + +<H2><A NAME="sect0" HREF="#toc0">Name</A></H2> +watch - call Tcl procedures before and after each +command +<H2><A NAME="sect1" HREF="#toc1">Synopsis</A></H2> +<B>watch create</B> <I>watchName</I> ?<I>options</I>? <P> +<B>watch activate</B> <I>watchName</I> +<P> +<B>watch deactivate</B> <I>watchName</I> <P> +<B>watch delete</B> <I>watchName</I> <P> +<B>watch configure</B> <I>watchName</I> +?<I>options</I> <P> +<B>watch info</B> <I>watchName</I> <P> +<B>watch names</B> +<H2><A NAME="sect2" HREF="#toc2">Description</A></H2> +The <B>watch</B> command +arranges for Tcl procedures to be invoked before and after the execution +of each Tcl command. +<H2><A NAME="sect3" HREF="#toc3">Introduction</A></H2> +When an error occurs in Tcl, the global +variable <I>errorInfo</I> will contain a stack-trace of the active procedures when +the error occured. Sometimes, however, the stack trace is insufficient. +You may need to know exactly where in the program's execution the error +occured. In cases like this, a more general tracing facility would be useful. +<P> +The <B>watch</B> command lets you designate Tcl procedures to be invoked before +and after the execution of each Tcl command. This means you can display +the command line and its results for each command as it executes. Another +use is to profile your Tcl commands. You can profile any Tcl command (like +<B>if</B> and <B>set</B>), not just Tcl procedures. +<H2><A NAME="sect4" HREF="#toc4">Example</A></H2> +The following example use <B>watch</B> +to trace Tcl commands (printing to standard error) both before and after +they are executed. <BR> +<CODE>proc preCmd { level command argv } {<BR> + set name [lindex $argv 0]<BR> + puts stderr "$level $name => $command"<BR> +}<BR> +<P> +proc postCmd { level command argv retcode results } {<BR> + set name [lindex $argv 0]<BR> + puts stderr "$level $name => $argv0= ($retcode) $results"<BR> +}<BR> +watch create trace \<BR> +<tt> </tt> <tt> </tt> -postcmd postCmd -precmd preCmd<BR> + +<H2><A NAME="sect5" HREF="#toc5"></CODE><P>Operations</A></H2> +The following operations are available for the <B>watch</B> command: + +<DL> + +<DT><B>watch activate <I>watchName</I></B> </DT> +<DD>Activates the watch, causing Tcl commands the +be traced to the maximum depth selected. </DD> + +<DT><B>watch create <I>watchName</I></B> ?<I>options</I>?... +</DT> +<DD>Creates a new watch <I>watchName</I>. It's an error if another watch <I>watchName</I> +already exists and an error message will be returned. <I>Options</I> may have any +of the values accepted by the <B>watch configure</B> command. This command returns +the empty string. </DD> + +<DT><B>watch configure <I>watchName</I></B> ?<I>options...</I>? </DT> +<DD>Queries or modifies +the configuration options of the watch <I>watchName</I>. <I>WatchName</I> is the name +of a watch. <I>Options</I> may have any of the following values: <blockquote></DD> + +<DT><B>-active <I>boolean</I></B> +</DT> +<DD>Specifies if the watch is active. By default, watches are active when created. +</DD> + +<DT><B>-postcmd <I>string</I></B> </DT> +<DD>Specifies a Tcl procedure to be called immediately after +each Tcl command. <I>String</I> is name of a Tcl procedure and any extra arguments +to be passed to it. Before <I>string</I> is invoked, five more arguments are appended: +1) the current level 2) the current command line 3) a list containing the +command after substitutions and split into words 4) the return code of +the command, and 5) the results of the command. The return status of the +postcmd procedure is always ignored. </DD> + +<DT><B>-precmd <I>string</I></B> </DT> +<DD>Specifies a Tcl procedure +to be called immediately before each Tcl command. <I>String</I> is name of a Tcl +procedure and any extra arguments to be passed to it. Before <I>string</I> is +invoked, three arguments are appended: 1) the current level 2) the current +command line, and 3) a list containing the command after substitutions +and split into words. The return status of the <B>-precmd</B> procedure is always +ignored. </DD> + +<DT><B>-maxlevel <I>number</I></B> </DT> +<DD>Specifies the maximum evaluation depth to watch +Tcl commands. The default maximum level is 10000. </DD> +</DL> +</blockquote> + +<DL> + +<DT><B>watch deactivate <I>watchName</I></B> + </DT> +<DD>Deactivates the watch. The <B>-precmd</B> and <B>-postcmd</B> procedures will no longer +be invoked. </DD> + +<DT><B>watch info <I>watchName</I></B> </DT> +<DD>Returns the configuration information +associated with the watch <I>watchName</I>. <I>WatchName</I> is the name of a watch. +</DD> + +<DT><B>watch names</B> ?<I>state</I>? </DT> +<DD>Lists the names of the watches for a given state. <I>State</I> +may be one of the following: <I>active</I>, <I>idle</I>, or <I>ignore</I>. If a <I>state</I> argument +isn't specified, all watches are<BR> + listed. </DD> +</DL> +</blockquote> + +<H2><A NAME="sect6" HREF="#toc6">Keywords</A></H2> +debug, profile <P> + +<HR><P> +<A NAME="toc"><B>Table of Contents</B></A><P> +<UL> +<LI><A NAME="toc0" HREF="#sect0">Name</A></LI> +<LI><A NAME="toc1" HREF="#sect1">Synopsis</A></LI> +<LI><A NAME="toc2" HREF="#sect2">Description</A></LI> +<LI><A NAME="toc3" HREF="#sect3">Introduction</A></LI> +<LI><A NAME="toc4" HREF="#sect4">Example</A></LI> +<LI><A NAME="toc5" HREF="#sect5">Operations</A></LI> +<LI><A NAME="toc6" HREF="#sect6">Keywords</A></LI> +</UL> +</BODY></HTML> |