From: peter@ficc.uu.net (Peter da Silva)
Newsgroups: alt.sources
Subject: TCL documentation (part 02/02)
Message-ID: <9T32O+8ficc@ficc.uu.net>
Date: 9 Mar 90 03:48:42 GMT
Distribution: alt
Organization: Xenix Support, FICC
Lines: 1281
Posted: Fri Mar  9 04:48:42 1990


Archive-name: tcl/DocPart02

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then feed it
# into a shell via "sh file" or similar.  To overwrite existing files,
# type "sh file -c".
# The tool that generated this appeared in the comp.sources.unix newsgroup;
# send mail to comp-sources-unix@uunet.uu.net if you want that tool.
# If this archive is complete, you will see the following message at the end:
#		"End of archive 2 (of 2)."
# Contents:  Backslash.3 CreateComm.3 CreateInte.3 CreateTrac.3
#   DeleteComm.3 DeleteInte.3 DeleteTrac.3 Eval.3 Expr.3 GetVar.3
#   Interp.3 Makefile Merge.3 Return.3 SetVar.3 SplitList.3
#   StringMatc.3 WatchInter.3
# Wrapped by peter@ficc.uu.net on Thu Mar  8 21:45:42 1990
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'Backslash.3' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'Backslash.3'\"
else
echo shar: Extracting \"'Backslash.3'\" \(1771 characters\)
sed "s/^X//" >'Backslash.3' <<'END_OF_FILE'
X'\" Copyright 1989 Regents of the University of California
X'\" Permission to use, copy, modify, and distribute this
X'\" documentation for any purpose and without fee is hereby
X'\" granted, provided that this notice appears in all copies.
X'\" The University of California makes no representations about
X'\" the suitability of this material for any purpose.  It is
X'\" provided "as is" without express or implied warranty.
X'\" 
X'\" $Header: /sprite/src/lib/tcl/RCS/Tcl_Backslash.man,v 1.4 89/05/18 16:29:01 ouster Exp $ SPRITE (Berkeley)
X'\" 
X.so \*(]ltmac.sprite
X.HS Tcl_Backslash tcl
X.BS
X.SH NAME
XTcl_Backslash \- parse a backslash sequence
X.SH SYNOPSIS
X.nf
X\fB#include <tcl.h>\fR
X.sp
Xchar
X\fBTcl_Backslash\fR(\fIsrc, countPtr\fR)
X.SH ARGUMENTS
X.AP char *src in
XPointer to a string starting with a backslash.
X.AP int *countPtr out
XIf \fIcountPtr\fR isn't NULL, \fI*countPtr\fR gets filled
Xin with number of characters in the backslash sequence, including
Xthe backslash character.
X.BE
X
X.SH DESCRIPTION
X.PP
XThis is a utility procedure used by several of the Tcl
Xcommands.  It parses a backslash sequence and returns
Xthe single character corresponding to the sequence.
X\fBTcl_Backslash\fR modifies \fI*countPtr\fR to contain the number of characters in
Xthe backslash sequence.  If \fIsrc\fR doesn't point to a backslash
Xsequence understood by Tcl, then Tcl_Backslash returns a backslash
Xas its result and \fI*countPtr\fR gets set to 1 (in this case the
Xbackslash character should not get any special treatment).
X.PP
XSee the Tcl manual entry for information on the valid
Xbackslash sequences.  All of the sequences described in the Tcl
X.VS
Xmanual entry are supported by \fBTcl_Backslash\fR except
Xbackslash-newline, which is not understood.
X.VE
X
X.SH KEYWORDS
Xbackslash, parse
END_OF_FILE
if test 1771 -ne `wc -c <'Backslash.3'`; then
    echo shar: \"'Backslash.3'\" unpacked with wrong size!
fi
# end of 'Backslash.3'
fi
if test -f 'CreateComm.3' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'CreateComm.3'\"
else
echo shar: Extracting \"'CreateComm.3'\" \(4682 characters\)
sed "s/^X//" >'CreateComm.3' <<'END_OF_FILE'
X'\" Copyright 1989 Regents of the University of California
X'\" Permission to use, copy, modify, and distribute this
X'\" documentation for any purpose and without fee is hereby
X'\" granted, provided that this notice appears in all copies.
X'\" The University of California makes no representations about
X'\" the suitability of this material for any purpose.  It is
X'\" provided "as is" without express or implied warranty.
X'\" 
X'\" $Header: /sprite/src/lib/tcl/RCS/Tcl_CreateCommand.man,v 1.2 89/03/24 14:15:58 ouster Exp $ SPRITE (Berkeley)
X'\" 
X.so \*(]ltmac.sprite
X.HS Tcl_CreateCommand tcl
X.BS
X.SH NAME
XTcl_CreateCommand \- define an application-specific command binding
X.SH SYNOPSIS
X.nf
X\fB#include <tcl.h>\fR
X.sp
X\fBTcl_CreateCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
X.SH ARGUMENTS
X.AS ClientData (*deleteProc)()
X.AP Tcl_Interp *interp in
XInterpreter in which to create new command.
X.AP char *cmdName in
XName of new command.  Tcl_CreateCommand makes a copy of this value
Xfor its own use.
X.AP int (*proc)() in
XImplementation of new command:  \fIproc\fR will be called whenever
X\fIcmdName\fR is invoked as a command.
X.AP ClientData clientData in
XArbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
X.AP void (*deleteProc)() in
XProcedure to call before \fIcmdName\fR is deleted from the interpreter;
Xallows for command-specific cleanup.  If NULL, then no procedure is
Xcalled before the command is deleted.
X.BE
X
X.SH DESCRIPTION
X.PP
X\fBTcl_CreateCommand\fR defines a new command in \fIinterp\fR and associates
Xit with procedure \fIproc\fR such that whenever \fIcmdName\fR is
Xinvoked as a Tcl command (via a call to \fBTcl_Eval\fR) the Tcl interpreter
Xwill call \fIproc\fR
Xto process the command.  If there is already a command \fIcmdName\fR
Xassociated with the interpreter, it is deleted.  \fIProc\fP should
Xhave the following structure:
X.nf
X.RS
Xint
Xproc(\fIclientData, interp, argc, argv\fP)
X.RS
XClientData \fIclientData\fP;
XTcl_Interp *\fIinterp\fP;
Xint \fIargc\fP;
Xchar *\fIargv[]\fP;
X.RE
X{
X}
X.RE
X.fi
XThe \fIclientData\fP and \fIinterp\fR parameters are
Xcopies of the \fIclientData\fP and \fIinterp\fR arguments given
Xto \fBTcl_CreateCommand\fR.
XTypically, \fIclientData\fR points to an application-specific
Xdata structure that describes what to do when the command procedure
Xis invoked.  \fIArgc\fR and \fIargv\fR describe the arguments to
Xthe command, \fIargc\fR giving the number of arguments (including
Xthe command name) and \fIargv\fR giving the values of the arguments
Xas strings.  The \fIargv\fR array will contain \fIargc\fR+1 values;
Xthe first \fIargc\fR values point to the argument strings, and the
Xlast value is NULL.
X.PP
X\fIProc\fR must return an integer code that is either \fBTCL_OK\fR, \fBTCL_ERROR\fR,
X\fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR.  See the Tcl overview man page
Xfor details on what these codes mean.  Most normal commands will only
Xreturn \fBTCL_OK\fR or \fBTCL_ERROR\fR.  In addition, \fIproc\fR must set
X\fIinterp->result\fR to point to a string value;
Xin the case of a \fBTCL_OK\fR return code this gives the result
Xof the command, and in the case of \fBTCL_ERROR\fR it gives an error message.
XThe \fBTcl_Return\fR procedure provides an easy interface for setting the return
Xvalue;  for complete details on how the \fIinterp->result\fR field is managed,
Xsee the \fBTcl_Interp\fR man page.  Before invoking a command procedure,
X\fBTcl_Eval\fR sets \fIinterp->result\fR to point to an empty string, so simple
Xcommands can return an empty result by doing nothing at all.
X.PP
XThe contents of the \fIargv\fR array are copies made by the Tcl interpreter
Xfor the use of \fIproc\fR.  \fIProc\fR may alter any of the strings
Xin \fIargv\fR.  However, the \fIargv\fR array
Xis recycled as soon as \fIproc\fR returns, so \fIproc\fR must not set
X\fIinterp->result\fR to point anywhere within the \fIargv\fR values (call Tcl_Return
Xwith status \fBTCL_VOLATILE\fR if you want to return something from the
X\fIargv\fR array).
X.PP
X\fIDeleteProc\fR will be invoked when (if) \fIcmdName\fR is deleted.
XThis can occur through a call to \fBTcl_DeleteCommand\fR or \fBTcl_DeleteInterp\fR,
Xor by replacing \fIcmdName\fR in another call to Tcl_CreateCommand.
X\fIDeleteProc\fR is invoked before the command is deleted, and gives the
Xapplication an opportunity to release any structures associated
Xwith the command.  \fIDeleteProc\fR should have the following form:
X.nf
X.RS
Xvoid
XdeleteProc(\fIclientData\fP)
X.RS
XClientData \fIclientData\fP;
X.RE
X{
X}
X.RE
X.fi
XThe \fIclientData\fR argument will be the same as the \fIclientData\fR
Xargument passed to \fBTcl_CreateCommand\fR.
X
X.SH KEYWORDS
Xbind, command, create, interpreter
END_OF_FILE
if test 4682 -ne `wc -c <'CreateComm.3'`; then
    echo shar: \"'CreateComm.3'\" unpacked with wrong size!
fi
# end of 'CreateComm.3'
fi
if test -f 'CreateInte.3' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'CreateInte.3'\"
else
echo shar: Extracting \"'CreateInte.3'\" \(1372 characters\)
sed "s/^X//" >'CreateInte.3' <<'END_OF_FILE'
X'\" Copyright 1989 Regents of the University of California
X'\" Permission to use, copy, modify, and distribute this
X'\" documentation for any purpose and without fee is hereby
X'\" granted, provided that this notice appears in all copies.
X'\" The University of California makes no representations about
X'\" the suitability of this material for any purpose.  It is
X'\" provided "as is" without express or implied warranty.
X'\" 
X'\" $Header: /sprite/src/lib/tcl/RCS/Tcl_CreateInterp.man,v 1.2 89/03/24 14:16:00 ouster Exp $ SPRITE (Berkeley)
X'\" 
X.so \*(]ltmac.sprite
X.HS Tcl_CreateInterp tcl
X.BS
X.SH NAME
XTcl_CreateInterp \- set up a new Tcl command interpreter
X.SH SYNOPSIS
X.nf
X\fB#include <tcl.h>\fR
X.sp
XTcl_Interp *
X\fBTcl_CreateInterp\fR()
X.BE
X
X.SH DESCRIPTION
X.PP
X\fBTcl_CreateInterp\fR creates a new interpreter structure and returns
Xa token for it.  The token is required in calls to most other Tcl
Xprocedures, such as \fBTcl_CreateCommand\fR, \fBTcl_Eval\fR, and
X\fBTcl_DeleteInterp\fR.
XClients are only allowed to access the fields of Tcl_Interp structures
Xrelated to command return values;  see the Tcl_Interp
Xand \fBTcl_CreateCommand\fR man pages for details.
XThe new interpreter is initialized with no defined variables and only
Xthe built-in Tcl commands.  To bind in additional commands, call
X\fBTcl_CreateCommand\fR.
X
X.SH KEYWORDS
Xcommand, create, interpreter
END_OF_FILE
if test 1372 -ne `wc -c <'CreateInte.3'`; then
    echo shar: \"'CreateInte.3'\" unpacked with wrong size!
fi
# end of 'CreateInte.3'
fi
if test -f 'CreateTrac.3' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'CreateTrac.3'\"
else
echo shar: Extracting \"'CreateTrac.3'\" \(4322 characters\)
sed "s/^X//" >'CreateTrac.3' <<'END_OF_FILE'
X'\" Copyright 1989 Regents of the University of California
X'\" Permission to use, copy, modify, and distribute this
X'\" documentation for any purpose and without fee is hereby
X'\" granted, provided that this notice appears in all copies.
X'\" The University of California makes no representations about
X'\" the suitability of this material for any purpose.  It is
X'\" provided "as is" without express or implied warranty.
X'\" 
X'\" $Header: /sprite/src/lib/tcl/RCS/Tcl_CreateTrace.man,v 1.2 89/03/24 14:16:01 ouster Exp $ SPRITE (Berkeley)
X'\" 
X.so \*(]ltmac.sprite
X.HS Tcl_CreateTrace tcl
X.BS
X.SH NAME
XTcl_CreateTrace \- arrange for command execution to be traced
X.SH SYNOPSIS
X.nf
X\fB#include <tcl.h>\fR
X.sp
XTcl_Trace
X\fBTcl_CreateTrace\fR(\fIinterp, level, proc, clientData\fR)
X.SH ARGUMENTS
X.AS ClientData (clientData)()
X.AP Tcl_Interp *interp in
XInterpreter in which to create new command.
X.AP int level in
XOnly commands at or below this nesting level will be traced.  1 means
Xtop-level commands only, 2 means top-level commands or those that are
Xinvoked as immediate consequences of executing top-level commands
X(procedure bodies, bracketed commands, etc.) and so on.
X.AP void (*proc)() in
XProcedure to call for each command that's executed.  See below for
Xdetails on the calling sequence.
X.AP ClientData clientData in
XArbitrary one-word value to pass to \fIproc\fR.
X.BE
X
X.SH DESCRIPTION
X.PP
X\fBTcl_CreateTrace\fR arranges for command tracing.  From now on, \fIproc\fR
Xwill be invoked before Tcl calls command procedures to process
Xcommands in \fIinterp\fR.  The return value from
X\fBTcl_CreateTrace\fR is a token for the trace,
Xwhich may be passed to \fBTcl_DeleteTrace\fR to remove the trace.  There may
Xbe many traces in effect simultaneously for the same command interpreter.
X.PP
X\fIProc\fR should have the following structure:
X.nf
X.RS
Xvoid
Xproc(\fIclientData, interp, level, command, cmdProc, cmdClientData, argc, argv\fP)
X.RS
XClientData \fIclientData\fP;
XTcl_Interp *\fIinterp\fP;
Xint \fIlevel\fP;
Xchar *\fIcommand\fP;
Xint (*\fIcmdProc\fP)();
XClientData \fIcmdClientData\fP;
Xint \fIargc\fP;
Xchar *\fIargv\fP[];
X.RE
X{
X}
X.RE
X.fi
XThe \fIclientData\fP and \fIinterp\fP parameters are
Xcopies of the corresponding arguments given to \fBTcl_CreateTrace\fR.
X\fIClientData\fR typically points to an application-specific
Xdata structure that describes what to do when \fIproc\fR
Xis invoked.  \fILevel\fR gives the nesting level of the command
X(1 for top-level commands passed to \fBTcl_Eval\fR by the application,
X2 for the next-level commands passed to \fBTcl_Eval\fR as part of parsing
Xor interpreting level-1 commands, and so on).  \fICommand\fR
Xpoints to a string containing the text of the
Xcommand, before any argument substitution.
X\fICmdProc\fR contains the address of the command procedure that
Xwill be called to process the command (i.e. the \fIproc\fR argument
Xof some previous call to \fBTcl_CreateCommand\fR) and \fIcmdClientData\fR
Xcontains the associated client data for \fIcmdProc\fR (the \fIclientData\fR
Xvalue passed to \fBTcl_CreateCommand\fR).  \fIArgc\fR and \fIargv\fR give
Xthe final argument information that will be passed to \fIcmdProc\fR, after
Xcommand, variable, and backslash substitution.
X\fIProc\fR must not modify the \fIcommand\fR or \fIargv\fR strings.
X.PP
XTracing will only occur for commands at nesting level less than
Xor equal to the \fIlevel\fR parameter (i.e. the \fIlevel\fR
Xparameter to \fIproc\fR will always be less than or equal to the
X\fIlevel\fR parameter to \fBTcl_CreateTrace\fR).
X.PP
XCalls to \fIproc\fR will be made by the Tcl parser immediately before
Xit calls the command procedure for the command (\fIcmdProc\fR).  This
Xoccurs after argument parsing and substitution, so tracing for
Xsubstituted commands occurs before tracing of the commands
Xcontaining the substitutions.  If there is a syntax error in a
Xcommand, or if there is no command procedure associated with a
Xcommand name, then no tracing will occur for that command.  If a
Xstring passed to Tcl_Eval contains multiple commands (bracketed, or
Xon different lines) then multiple calls to \fIproc\fR will occur,
Xone for each command.  The \fIcommand\fR string for each of these
Xtrace calls will reflect only a single command, not the entire string
Xpassed to Tcl_Eval.
X
X.SH KEYWORDS
Xcommand, create, interpreter, trace
END_OF_FILE
if test 4322 -ne `wc -c <'CreateTrac.3'`; then
    echo shar: \"'CreateTrac.3'\" unpacked with wrong size!
fi
# end of 'CreateTrac.3'
fi
if test -f 'DeleteComm.3' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'DeleteComm.3'\"
else
echo shar: Extracting \"'DeleteComm.3'\" \(1375 characters\)
sed "s/^X//" >'DeleteComm.3' <<'END_OF_FILE'
X'\" Copyright 1989 Regents of the University of California
X'\" Permission to use, copy, modify, and distribute this
X'\" documentation for any purpose and without fee is hereby
X'\" granted, provided that this notice appears in all copies.
X'\" The University of California makes no representations about
X'\" the suitability of this material for any purpose.  It is
X'\" provided "as is" without express or implied warranty.
X'\" 
X'\" $Header: /sprite/src/lib/tcl/RCS/Tcl_DeleteCommand.man,v 1.2 89/03/24 14:16:03 ouster Exp $ SPRITE (Berkeley)
X'\" 
X.so \*(]ltmac.sprite
X.HS Tcl_DeleteCommand tcl
X.BS
X.SH NAME
XTcl_DeleteCommand \- remove a command from a Tcl interpreter
X.SH SYNOPSIS
X.nf
X\fB#include <tcl.h>\fR
X.sp
X\fBTcl_DeleteCommand\fR(\fIinterp, cmdName\fR)
X.SH ARGUMENTS
X.AS Tcl_Interp *cmdName
X.AP Tcl_Interp *interp in
XInterpreter in which to delete command.
X.AP char *cmdName in
XName of command to be deleted.
X.BE
X
X.SH DESCRIPTION
X.PP
XThis procedure deletes a command from a command interpreter.
XOnce the call completes, attempts to invoke \fIcmdName\fR in
X\fIinterp\fR will result in errors.  If \fIcmdName\fR isn't bound
Xas a command in \fIinterp\fR then \fBTcl_DeleteCommand\fR does nothing.
XThere are no restrictions on \fIcmdName\fR:  it may refer to
Xa built-in command, an application-specific command, or a Tcl procedure.
X
X.SH KEYWORDS
Xcommand, delete, interpreter
END_OF_FILE
if test 1375 -ne `wc -c <'DeleteComm.3'`; then
    echo shar: \"'DeleteComm.3'\" unpacked with wrong size!
fi
# end of 'DeleteComm.3'
fi
if test -f 'DeleteInte.3' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'DeleteInte.3'\"
else
echo shar: Extracting \"'DeleteInte.3'\" \(1180 characters\)
sed "s/^X//" >'DeleteInte.3' <<'END_OF_FILE'
X'\" Copyright 1989 Regents of the University of California
X'\" Permission to use, copy, modify, and distribute this
X'\" documentation for any purpose and without fee is hereby
X'\" granted, provided that this notice appears in all copies.
X'\" The University of California makes no representations about
X'\" the suitability of this material for any purpose.  It is
X'\" provided "as is" without express or implied warranty.
X'\" 
X'\" $Header: /sprite/src/lib/tcl/RCS/Tcl_DeleteInterp.man,v 1.2 89/03/24 14:16:06 ouster Exp $ SPRITE (Berkeley)
X'\" 
X.so \*(]ltmac.sprite
X.HS Tcl_DeleteInterp tcl
X.BS
X.SH NAME
XTcl_DeleteInterp \- destroy a Tcl command interpreter
X.SH SYNOPSIS
X.nf
X\fB#include <tcl.h>\fR
X.sp
X\fBTcl_DeleteInterp\fR(\fIinterp\fR)
X.SH ARGUMENTS
X.AS Tcl_Interp *interp
X.AP Tcl_Interp *interp in
XToken for interpreter to be destroyed.
X.BE
X
X.SH DESCRIPTION
X.PP
XThis procedure destroys a command interpreter and releases all of
Xthe resources associated with it, including variables, procedures,
Xand application-specific command bindings.  After \fBTcl_DeleteInterp\fR
Xreturns the caller should never again use the \fIinterp\fR token.
X
X.SH KEYWORDS
Xcommand, delete, interpreter
END_OF_FILE
if test 1180 -ne `wc -c <'DeleteInte.3'`; then
    echo shar: \"'DeleteInte.3'\" unpacked with wrong size!
fi
# end of 'DeleteInte.3'
fi
if test -f 'DeleteTrac.3' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'DeleteTrac.3'\"
else
echo shar: Extracting \"'DeleteTrac.3'\" \(1233 characters\)
sed "s/^X//" >'DeleteTrac.3' <<'END_OF_FILE'
X'\" Copyright 1989 Regents of the University of California
X'\" Permission to use, copy, modify, and distribute this
X'\" documentation for any purpose and without fee is hereby
X'\" granted, provided that this notice appears in all copies.
X'\" The University of California makes no representations about
X'\" the suitability of this material for any purpose.  It is
X'\" provided "as is" without express or implied warranty.
X'\" 
X'\" $Header: /sprite/src/lib/tcl/RCS/Tcl_DeleteTrace.man,v 1.2 89/03/24 14:16:08 ouster Exp $ SPRITE (Berkeley)
X'\" 
X.so \*(]ltmac.sprite
X.HS Tcl_DeleteTrace tcl
X.BS
X.SH NAME
XTcl_DeleteTrace \- remove a previously-established command trace
X.SH SYNOPSIS
X.nf
X\fB#include <tcl.h>\fR
X.sp
X\fBTcl_DeleteTrace\fR(\fIinterp, trace\fR)
X.SH ARGUMENTS
X.AS Tcl_Interp *interp
X.AP Tcl_Interp *interp in
XInterpreter containing \fItrace\fR.
X.AP Tcl_Trace trace in
XToken for trace to be removed (return value from previous call
Xto Tcl_CreateTrace).
X.BE
X
X.SH DESCRIPTION
X.PP
XThis procedure removes a trace, so that no future calls will be
Xmade to the procedure associated with the trace.  After \fBTcl_DeleteTrace\fR
Xreturns, the caller should never again use the \fItrace\fR token.
X
X.SH KEYWORDS
Xdelete, interpreter, trace
END_OF_FILE
if test 1233 -ne `wc -c <'DeleteTrac.3'`; then
    echo shar: \"'DeleteTrac.3'\" unpacked with wrong size!
fi
# end of 'DeleteTrac.3'
fi
if test -f 'Eval.3' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'Eval.3'\"
else
echo shar: Extracting \"'Eval.3'\" \(3713 characters\)
sed "s/^X//" >'Eval.3' <<'END_OF_FILE'
X'\" Copyright 1989 Regents of the University of California
X'\" Permission to use, copy, modify, and distribute this
X'\" documentation for any purpose and without fee is hereby
X'\" granted, provided that this notice appears in all copies.
X'\" The University of California makes no representations about
X'\" the suitability of this material for any purpose.  It is
X'\" provided "as is" without express or implied warranty.
X'\" 
X'\" $Header: /sprite/src/lib/tcl/RCS/Tcl_Eval.man,v 1.3 90/01/07 16:02:10 ouster Exp $ SPRITE (Berkeley)
X'\" 
X.so \*(]ltmac.sprite
X.HS Tcl_Eval tcl
X.BS
X.SH NAME
XTcl_Eval \- execute a Tcl command string
X.SH SYNOPSIS
X.nf
X\fB#include <tcl.h>\fR
X.sp
Xint
X\fBTcl_Eval\fR(\fIinterp, cmd, flags, termPtr\fR)
X.SH ARGUMENTS
X.AS Tcl_Interp **termPtr;
X.AP Tcl_Interp *interp in
XInterpreter in which to execute the command.  String result will be
Xstored in \fIinterp->result\fR.
X.AP char *cmd in
XCommand (or sequence of commands) to execute.
X.AP char flags in
XEither \fBTCL_BRACKET_TERM\fR or 0.
X.VS
XIf 0, then \fBTcl_Eval\fR will process commands from \fIcmd\fR until
Xit reaches the null character at the end of the string;  newlines
Xwill be treated as command separators.  If \fBTCL_BRACKET_TERM\fR,
Xthen \fBTcl_Eval\fR will process comands from \fIcmd\fR until either it
Xreaches a null character or it encounters a close bracket that isn't
Xbackslashed or enclosed in braces, at which
Xpoint it will return;  newlines will treated as white space, not as
Xcommand separators.  Under normal conditions, \fIflags\fR should be 0.
X.VE
X.AP char **termPtr out
XIf 
X.VS
X\fItermPtr\fR is non-NULL, \fBTcl_Eval\fR fills in *\fItermPtr\fR with
Xthe address of the character just after the last one in the last command
Xsuccessfully executed (normally the null character at the end of \fIcmd\fR).
XIf an error occurs in the first command in \fIcmd\fR, then \fI*termPtr\fR
Xwill be set to \fIcmd\fR.
X.VE
X.BE
X
X.SH DESCRIPTION
X.PP
X\fBTcl_Eval\fR parses commands from \fIcmd\fR and executes them in
Xorder until either an error occurs or \fBTcl_Eval\fR reaches a terminating
Xcharacter (']' or '\0', depending on the value of \fIflags\fR).
XThe return value from \fBTcl_Eval\fR is one
Xof the Tcl return codes \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or
X\fBTCL_CONTINUE\fR, and \fIinterp->result\fR will point to
Xa string with additional information (result value or error message).
XThis return information corresponds to the last command executed from
X\fIcmd\fR.
X.PP
XDuring the processing of a command it is legal to make nested
Xcalls to \fBTcl_Eval\fR (this is how conditionals, loops, and procedures
Xare implemented).  If a code other than
X\fBTCL_OK\fR is returned from a nested \fBTcl_Eval\fR invocation, then the
Xcaller should normally return immediately, passing that same
Xreturn code back to its caller, and so on until the top-level application is
Xreached.  A few commands, like \fBfor\fR, will check for certain
Xreturn codes, like \fBTCL_BREAK\fR and \fBTCL_CONTINUE\fR, and process them
Xspecially without returning.
X.PP
X\fBTcl_Eval\fR keeps track of how many nested Tcl_Eval invocations are
Xin progress for \fIinterp\fR.
XIf a code of \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR is
Xabout to be returned from the topmost \fBTcl_Eval\fR invocation for
X\fIinterp\fR, then \fBTcl_Eval\fR converts the return code to \fBTCL_ERROR\fR
Xand sets \fIinterp->result\fR to point to an error message indicating that
Xthe \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR command was
Xinvoked in an inappropriate place.  This means that top-level
Xapplications should never see a return code from \fBTcl_Eval\fR other then
X\fBTCL_OK\fR or \fBTCL_ERROR\fR.
X
X.SH KEYWORDS
Xcommand, execute, interpreter
END_OF_FILE
if test 3713 -ne `wc -c <'Eval.3'`; then
    echo shar: \"'Eval.3'\" unpacked with wrong size!
fi
# end of 'Eval.3'
fi
if test -f 'Expr.3' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'Expr.3'\"
else
echo shar: Extracting \"'Expr.3'\" \(1767 characters\)
sed "s/^X//" >'Expr.3' <<'END_OF_FILE'
X'\" Copyright 1989 Regents of the University of California
X'\" Permission to use, copy, modify, and distribute this
X'\" documentation for any purpose and without fee is hereby
X'\" granted, provided that this notice appears in all copies.
X'\" The University of California makes no representations about
X'\" the suitability of this material for any purpose.  It is
X'\" provided "as is" without express or implied warranty.
X'\" 
X'\" $Header: /sprite/src/lib/tcl/RCS/Tcl_Expr.man,v 1.2 89/03/24 14:16:11 ouster Exp $ SPRITE (Berkeley)
X'\" 
X.so \*(]ltmac.sprite
X.HS Tcl_Expr tcl
X.BS
X.SH NAME
XTcl_Expr \- evaluate an expression
X.SH SYNOPSIS
X.nf
X\fB#include <tcl.h>\fR
X.sp
Xint
X\fBTcl_Expr\fR(\fIinterp, string, valuePtr\fR)
X.SH ARGUMENTS
X.AS Tcl_Interp *interp
X.AP Tcl_Interp *interp in
XInterpreter in whose context to evaluate \fIstring\fR.
X.AP char *string in
XExpression to be evaluated.
X.AP int *valuePtr out
XThe expression's (integer) value will be stored here.
X.BE
X
X.SH DESCRIPTION
X.PP
X\fBTcl_Expr\fR is a utility procedure used by several of the Tcl commands.
XGiven a string whose contents are an expression of the form
Xaccepted by the \fBexpr\fR command, this procedure evaluates
Xthe expression and returns the integer result in \fI*valuePtr\fR.
XNormally \fBTcl_Expr\fR returns \fBTCL_OK\fR as its result.  However, if
Xthe expression contains a syntax error then Tcl_Expr
Xreturns \fBTCL_ERROR\fR and sets \fIinterp->result\fR to point
Xto an error message in the usual fashion.
X\fBTcl_Expr\fR may make nested calls to \fBTcl_Eval\fR while parsing the
Xexpression;  if any of these calls returns an error then
X\fBTcl_Expr\fR will return that same error information.  If an error
Xis returned, then \fI*valuePtr\fR will not be modified.
X
X.SH KEYWORDS
Xevaluate, expression
END_OF_FILE
if test 1767 -ne `wc -c <'Expr.3'`; then
    echo shar: \"'Expr.3'\" unpacked with wrong size!
fi
# end of 'Expr.3'
fi
if test -f 'GetVar.3' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'GetVar.3'\"
else
echo shar: Extracting \"'GetVar.3'\" \(1725 characters\)
sed "s/^X//" >'GetVar.3' <<'END_OF_FILE'
X'\" Copyright 1989 Regents of the University of California
X'\" Permission to use, copy, modify, and distribute this
X'\" documentation for any purpose and without fee is hereby
X'\" granted, provided that this notice appears in all copies.
X'\" The University of California makes no representations about
X'\" the suitability of this material for any purpose.  It is
X'\" provided "as is" without express or implied warranty.
X'\" 
X'\" $Header: /sprite/src/lib/tcl/RCS/Tcl_GetVar.man,v 1.2 89/03/24 14:16:13 ouster Exp $ SPRITE (Berkeley)
X'\" 
X.so \*(]ltmac.sprite
X.HS Tcl_GetVar tcl
X.BS
X.SH NAME
XTcl_GetVar \- return the value of a Tcl variable
X.SH SYNOPSIS
X.nf
X\fB#include <tcl.h>\fR
X.sp
Xchar *
X\fBTcl_GetVar\fR(\fIinterp, varName, global\fR)
X.SH ARGUMENTS
X.AS Tcl_Interp *interp
X.AP Tcl_Interp *interp in
XInterpreter in which to check for variable.
X.AP char *varName in
XName of desired variable.
X.AP int global in
XIf non-zero, then insist that \fIvarName\fR be interpreted as
Xa global variable regardless of whether a procedure invocation
Xis in progress.
X.BE
X
X.SH DESCRIPTION
X.PP
X\fBTcl_GetVar\fR is a utility procedure used by several of the Tcl commands.
XIt returns the value of variable \fIvarName\fR in
Xinterpreter \fIinterp\fR.  If there isn't a Tcl command procedure
Xbeing interpreted right now, or if \fIglobal\fR is non-zero,
Xthen \fIvarName\fR is always treated
Xas the name of a global variable.  Otherwise, if a procedure is
Xbeing interpreted,
Xthen \fIvarName\fR will be treated as a local variable name, unless
Xit has been declared global using the \fBglobal\fR command.  If
Xno variable by the name \fIvarName\fR exists right now, then the
Xempty string is returned.
X
X.SH KEYWORDS
Xinterpreter, global, local, variable
END_OF_FILE
if test 1725 -ne `wc -c <'GetVar.3'`; then
    echo shar: \"'GetVar.3'\" unpacked with wrong size!
fi
# end of 'GetVar.3'
fi
if test -f 'Interp.3' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'Interp.3'\"
else
echo shar: Extracting \"'Interp.3'\" \(4401 characters\)
sed "s/^X//" >'Interp.3' <<'END_OF_FILE'
X'\" Copyright 1989 Regents of the University of California
X'\" Permission to use, copy, modify, and distribute this
X'\" documentation for any purpose and without fee is hereby
X'\" granted, provided that this notice appears in all copies.
X'\" The University of California makes no representations about
X'\" the suitability of this material for any purpose.  It is
X'\" provided "as is" without express or implied warranty.
X'\" 
X'\" $Header: /sprite/src/lib/tcl/RCS/Tcl_Interp.man,v 1.3 90/01/15 14:58:40 ouster Exp $ SPRITE (Berkeley)
X'\" 
X.so \*(]ltmac.sprite
X.HS Tcl_Interp tcl
X.BS
X.SH NAME
XTcl_Interp \- client-visible fields of interpreter structures
X.SH SYNOPSIS
X.nf
X\fB#include <tcl.h>\fR
X.sp
Xtypedef struct {
X	char *\fIresult\fR;
X	int \fIdynamic\fR;
X	int \fIerrorLine\fR;
X} Tcl_Interp;
X.BE
X
X.SH DESCRIPTION
X.PP
XThe \fBTcl_CreateInterp\fR procedure returns a pointer to a Tcl_Interp
Xstructure.  This pointer is then passed into other Tcl procedures
Xto process commands in the interpreter and perform other operations
Xon the interpreter.  Interpreter structures contain many many fields
Xthat are used by Tcl, but only three that may be accessed by
Xclients:  \fIresult\fR and \fIdynamic\fR.  These fields are used by
XTcl command procedures to return strings that form part of the result
Xof each command.  When Tcl_Eval returns, the string pointed to be
Xthe \fIresult\fR field will be used by Tcl_Eval's caller
Xas a return value or error message.
X.PP
XThe easiest way for command procedures to manipulate the \fIresult\fR
Xand \fIdynamic\fR fields is to call Tcl_Return;  Tcl_Return
Xwill hide all the details of managing these fields.
XThe description below is for those procedures that manipulate the
Xfields directly.
X.PP
XWhenever a command procedure returns, it must ensure
Xthat the \fIresult\fR field of its interpreter points to the string
Xbeing returned by the command.  Normally, these strings are assumed
Xto be statically allocated;  in this case, the \fIdynamic\fR field
Xmust be zero.  As an alternative, a command procedure may dynamically
Xallocate its return value and store a pointer to it in \fIinterp->result\fR.
XIn this case, the command procedure must also set \fIinterp->dynamic\fR
Xto non-zero.  If \fIinterp->dynamic\fR is non-zero, then Tcl will free
Xthe space pointed to by \fIinterp->result\fR before it invokes the next command.
XIf a client procedure overwrites \fIinterp->result\fR field when
X\fIinterp->dynamic\fR is non-zero, then it is responsible for freeing the
Xold \fIinterp->result\fR.  Once again, if clients use the
X\fBTcl_Result\fR procedure to manage these fields, they need not worry
Xabout these issues.
X.PP
XAs part of processing each command, \fBTcl_Eval\fR initializes
X\fIinterp->result\fR
Xand \fIinterp->dynamic\fR just before calling the command procedure for
Xthe command.  The \fIdynamic\fR field will be initialized to zero,
Xand \fIinterp->result\fR will point to an empty string.  Commands that
Xdo not return any value can simply leave the fields alone.
XFurthermore, the empty string pointed to by \fIresult\fR is actually
Xpart of an array of \fBTCL_RESULT_SIZE\fR characters (approximately 200).
XIf a command wishes to return a short string, it can simply copy
Xit to the area pointed to by \fIinterp->result\fR.  Or, it can use
Xthe sprintf procedure to generate a short result string at the location
Xpointed to by \fIinterp->result\fR.
X.PP
XIf a command procedure calls a lower-level procedure that sets
X\fIinterp->result\fR and \fIinterp->dynamic\fR (such as a recursive
Xinstance of \fBTcl_Eval\fR), then the command procedure must reset
X\fIinterp->result\fR if it wishes to return a value different
Xthan that returned by the lower-level procedure.  As part of
Xresetting \fIinterp->result\fR, it must free the space if
X\fIinterp->dynamic\fR is set.  Once again, the easiest way to
Xmake sure this gets done right is to call \fBTcl_Result\fR.
X.PP
XThe \fIerrorLine\fR
X.VS
Xfield is valid only after \fBTcl_Eval\fR returns
Xa \fBTCL_ERROR\fR return code.  In this situation the \fIerrorLine\fR
Xfield identifies the line number of the command being executed when
Xthe error occurred.  The line numbers are relative to the command
Xbeing executed:  1 means the first line of the command passed to
X\fBTcl_Eval\fR, 2 means the second line, and so on.  \fIErrorLine\fR
Xshould not normally be modified except by \fBTcl_Eval\fR.
X.VE
X
X.SH KEYWORDS
Xdynamic, interpreter, result
END_OF_FILE
if test 4401 -ne `wc -c <'Interp.3'`; then
    echo shar: \"'Interp.3'\" unpacked with wrong size!
fi
# end of 'Interp.3'
fi
if test -f 'Makefile' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'Makefile'\"
else
echo shar: Extracting \"'Makefile'\" \(532 characters\)
sed "s/^X//" >'Makefile' <<'END_OF_FILE'
XSHELL=/bin/sh
X
XMANS=\
X	Backslash.3 \
X	CreateComm.3 \
X	CreateInte.3 \
X	CreateTrac.3 \
X	DeleteComm.3 \
X	DeleteInte.3 \
X	DeleteTrac.3 \
X	Eval.3 \
X	Expr.3 \
X	GetVar.3 \
X	Interp.3 \
X	Merge.3 \
X	Return.3 \
X	SetVar.3 \
X	SplitList.3 \
X	StringMatc.3 \
X	WatchInter.3
XDOCS=\
X	Tcl.1
X
XFILES=\
X	$(DOCS:.1=.out) \
X	$(MANS:.3=.out)
X
X.SUFFIXES:
X.SUFFIXES: .out .1 .3
X
X.3.out: tmac.sprite
X	nroff -man $*.3 | col > $*.out
X
X.1.out: tmac.sprite
X	nroff -man $*.1 | col > $*.out
X
Xall: $(FILES)
X
Xprint: $(FILES)
X	strike $(FILES) | npr
X
Xclean:
X	rm $(FILES)
END_OF_FILE
if test 532 -ne `wc -c <'Makefile'`; then
    echo shar: \"'Makefile'\" unpacked with wrong size!
fi
# end of 'Makefile'
fi
if test -f 'Merge.3' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'Merge.3'\"
else
echo shar: Extracting \"'Merge.3'\" \(1395 characters\)
sed "s/^X//" >'Merge.3' <<'END_OF_FILE'
X'\" Copyright 1989 Regents of the University of California
X'\" Permission to use, copy, modify, and distribute this
X'\" documentation for any purpose and without fee is hereby
X'\" granted, provided that this notice appears in all copies.
X'\" The University of California makes no representations about
X'\" the suitability of this material for any purpose.  It is
X'\" provided "as is" without express or implied warranty.
X'\" 
X'\" $Header: /sprite/src/lib/tcl/RCS/Tcl_Merge.man,v 1.2 89/03/24 14:16:16 ouster Exp $ SPRITE (Berkeley)
X'\" 
X.so \*(]ltmac.sprite
X.HS Tcl_Merge tcl
X.BS
X.SH NAME
XTcl_Merge \- generate a Tcl list from a collection of strings
X.SH SYNOPSIS
X.nf
X\fB#include <tcl.h>\fR
X.sp
Xchar *
X\fBTcl_Merge\fR(\fIargc, argv\fR)
X.SH ARGUMENTS
X.AP int argc in
XNumber of strings.
X.AP char *argv[] in
XArray of strings to combine into list.  Must have \fIargc\fR entries.
X.BE
X
X.SH DESCRIPTION
X.PP
X\fBTcl_Merge\fR is a utility procedure used by several of the Tcl commands.
XGiven a collection of strings, it generates a result string
Xthat has proper list structure, such that the \fBindex\fR
XTcl command may be used to extract out the original strings.
XIn order to do this, \fBTcl_Merge\fR may have to add braces
Xand/or backslashes.  The result string is dynamically allocated
Xusing \fBmalloc()\fR;  the caller must eventually release the space
Xusing \fBfree()\fR.
X
X.SH KEYWORDS
Xlist, strings
END_OF_FILE
if test 1395 -ne `wc -c <'Merge.3'`; then
    echo shar: \"'Merge.3'\" unpacked with wrong size!
fi
# end of 'Merge.3'
fi
if test -f 'Return.3' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'Return.3'\"
else
echo shar: Extracting \"'Return.3'\" \(2464 characters\)
sed "s/^X//" >'Return.3' <<'END_OF_FILE'
X'\" Copyright 1989 Regents of the University of California
X'\" Permission to use, copy, modify, and distribute this
X'\" documentation for any purpose and without fee is hereby
X'\" granted, provided that this notice appears in all copies.
X'\" The University of California makes no representations about
X'\" the suitability of this material for any purpose.  It is
X'\" provided "as is" without express or implied warranty.
X'\" 
X'\" $Header: /sprite/src/lib/tcl/RCS/Tcl_Return.man,v 1.3 89/08/16 08:52:46 ouster Exp $ SPRITE (Berkeley)
X'\" 
X.so \*(]ltmac.sprite
X.HS Tcl_Return tcl
X.BS
X.SH NAME
XTcl_Return \- set up a Tcl result string
X.SH SYNOPSIS
X.nf
X\fB#include <tcl.h>\fR
X.sp
X\fBTcl_Return\fR(\fIinterp, string, status\fR)
X.SH ARGUMENTS
X.AP Tcl_Interp *interp out
XInterpreter for which a return value is to be established.
X.AP char *string in
XString value to be returned, or \fBNULL\fR.
X.AP int status in
XIndicates the nature of \fIstring\fR.  Must be either \fBTCL_STATIC\fR,
X\fBTCL_DYNAMIC\fR, or \fBTCL_VOLATILE\fR.
X.BE
X
X.SH DESCRIPTION
X.PP
X\fBTcl_Return\fR is a convenience routine used by several of the Tcl commands.  It
Xarranges for \fIstring\fR to be the return string for the current Tcl
Xcommand in \fIinterp\fR.  If \fIstatus\fR is \fBTCL_STATIC\fR it means that
X\fIstring\fR
Xrefers to an area of static storage that is guaranteed to remain
Xuntouched until at least the next call to \fBTcl_Eval\fR.  If \fIstatus\fR
Xis \fBTCL_DYNAMIC\fR it means that \fIstring\fR was allocated with a call
Xto \fBmalloc()\fR and is now the property of the Tcl system.  \fBTcl_Return\fR
Xwill arrange for the string's storage to be released by calling
X\fBfree()\fR when it is no longer needed.  The third possibility is for
X\fIstatus\fR to be \fBTCL_VOLATILE\fR.  This means that \fIstring\fR points
Xto an area of memory that is likely to be overwritten when \fBTcl_Return\fR
Xreturns.  In this case \fBTcl_Return\fR makes a copy of the string and arranges
Xfor the copy to be the return string for the current Tcl command.
X.PP
XIf \fIstring\fR is \fBNULL\fR, then \fIstatus\fR is ignored and \fBTcl_Return\fR
Xre-initializes \fIinterp\fR's result to point to the pre-allocated result
Xarea, with an empty string in the result area.
X.PP
XIn any of the above cases, if \fIinterp\fR holds a dynamically-allocated
Xresult at the time of the \fBTcl_Return\fR call, the old result's storage
Xis released by calling \fBfree()\fR.
X
X.SH KEYWORDS
Xcommand, result, return value, interpreter
END_OF_FILE
if test 2464 -ne `wc -c <'Return.3'`; then
    echo shar: \"'Return.3'\" unpacked with wrong size!
fi
# end of 'Return.3'
fi
if test -f 'SetVar.3' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'SetVar.3'\"
else
echo shar: Extracting \"'SetVar.3'\" \(1781 characters\)
sed "s/^X//" >'SetVar.3' <<'END_OF_FILE'
X'\" Copyright 1989 Regents of the University of California
X'\" Permission to use, copy, modify, and distribute this
X'\" documentation for any purpose and without fee is hereby
X'\" granted, provided that this notice appears in all copies.
X'\" The University of California makes no representations about
X'\" the suitability of this material for any purpose.  It is
X'\" provided "as is" without express or implied warranty.
X'\" 
X'\" $Header: /sprite/src/lib/tcl/RCS/Tcl_SetVar.man,v 1.3 89/03/24 15:15:17 ouster Exp $ SPRITE (Berkeley)
X'\" 
X.so \*(]ltmac.sprite
X.HS Tcl_SetVar tcl
X.BS
X.SH NAME
XTcl_SetVar \- change the value of a Tcl variable
X.SH SYNOPSIS
X.nf
X\fB#include <tcl.h>\fR
X.sp
X\fBTcl_SetVar\fR(\fIinterp, varName, newValue, global\fR)
X.SH ARGUMENTS
X.AS Tcl_Interp *interp
X.AP Tcl_Interp *interp in
XInterpreter in which to change variable.
X.AP char *varName in
XName of variable.
X.AP char *newValue in
XNew value for \fIvarName\fR
X.AP int global in
XIf non-zero, then insist on interpreting \fIvarName\fR as a global
Xvariable, regardless of whether a procedure invocation is in
Xprogress.
X.BE
X
X.SH DESCRIPTION
X.PP
XThis is a utility procedure used by many of the Tcl commands.
XIt changes the value of variable \fIvarName\fR in
Xinterpreter \fIinterp\fR, such that future calls to \fBTcl_GetVar\fR
Xwill return \fInewValue\fR as the value of \fIvarName\fR.
X\fBTcl_SetVar\fR uses the same rules for selecting
Xa global or local variable as \fBTcl_GetVar\fR.  If \fIvarName\fR
Xdoesn't already exist, then a new variable is created.
X\fBTcl_SetVar\fR copies both \fIvarName\fR and \fInewValue\fR into
Xits own private storage, so the caller may change the contents
Xof these strings after \fBTcl_SetVar\fR returns without affecting
Xthe variable's value.
X
X.SH KEYWORDS
Xinterpreter, variable
END_OF_FILE
if test 1781 -ne `wc -c <'SetVar.3'`; then
    echo shar: \"'SetVar.3'\" unpacked with wrong size!
fi
# end of 'SetVar.3'
fi
if test -f 'SplitList.3' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'SplitList.3'\"
else
echo shar: Extracting \"'SplitList.3'\" \(2157 characters\)
sed "s/^X//" >'SplitList.3' <<'END_OF_FILE'
X'\" Copyright 1989 Regents of the University of California
X'\" Permission to use, copy, modify, and distribute this
X'\" documentation for any purpose and without fee is hereby
X'\" granted, provided that this notice appears in all copies.
X'\" The University of California makes no representations about
X'\" the suitability of this material for any purpose.  It is
X'\" provided "as is" without express or implied warranty.
X'\" 
X'\" $Header: /sprite/src/lib/tcl/RCS/Tcl_SplitList.man,v 1.2 89/03/24 14:16:23 ouster Exp $ SPRITE (Berkeley)
X'\" 
X.so \*(]ltmac.sprite
X.HS Tcl_SplitList tcl
X.BS
X.SH NAME
XTcl_SplitList \- break a Tcl list up into fields
X.SH SYNOPSIS
X.nf
X\fB#include <tcl.h>\fR
X.sp
Xint
X\fBTcl_SplitList\fR(\fIinterp, list, argcPtr, argvPtr\fR)
X.AS Tcl_Interp *argvPtr
X.SH ARGUMENTS
X.AP Tcl_Interp *interp out
XInterpreter to use for error reporting.
X.AP char *list in
XPointer to a string with proper list structure.
X.AP int *argcPtr out
XFilled in with number of elements in \fIlist\fR.
X.AP char ***argvPtr out
X\fI*argvPtr\fR will be filled in with the address of an array of
Xpointers to the strings that are the extracted elements of \fIlist\fR.
XThere will be \fI*argcPtr\fR valid entries in the array.
X.BE
X
X.SH DESCRIPTION
X.PP
X\fBTcl_SplitList\fR is the inverse of \fBTcl_Merge\fR.  Given a list, it extracts
Xall of the elements of the list and returns an array of pointers to
Xthem using \fIargcPtr\fR and \fIargvPtr\fR.  While extracting the
Xarguments, \fBTcl_SplitList\fR obeys the usual
Xrules for backslash substitutions and braces.  The area of
Xmemory pointed to by \fI*argvPtr\fR is dynamically allocated;  in
Xaddition to the array of pointers, it
Xalso holds copies of all the list elements.  It is the caller's
Xresponsibility to free up all of this storage by calling
X.DS
Xfree((char *) \fI*argvPtr\fR)
X.DE
Xwhen the list elements are no longer needed.
X.PP
X\fBTcl_SplitList\fR normally returns \fBTCL_OK\fR, which means the list was
Xsuccessfully parsed.
XIf there was a syntax error in \fIlist\fR, then \fBTCL_ERROR\fR is returned
Xand \fIinterp->result\fR will point to an error message describing the problem.
X
X.SH KEYWORDS
Xlist, split, strings
END_OF_FILE
if test 2157 -ne `wc -c <'SplitList.3'`; then
    echo shar: \"'SplitList.3'\" unpacked with wrong size!
fi
# end of 'SplitList.3'
fi
if test -f 'StringMatc.3' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'StringMatc.3'\"
else
echo shar: Extracting \"'StringMatc.3'\" \(1366 characters\)
sed "s/^X//" >'StringMatc.3' <<'END_OF_FILE'
X'\" Copyright 1989 Regents of the University of California
X'\" Permission to use, copy, modify, and distribute this
X'\" documentation for any purpose and without fee is hereby
X'\" granted, provided that this notice appears in all copies.
X'\" The University of California makes no representations about
X'\" the suitability of this material for any purpose.  It is
X'\" provided "as is" without express or implied warranty.
X'\" 
X'\" $Header: /sprite/src/lib/tcl/RCS/Tcl_StringMatch.man,v 1.1 89/05/15 16:15:36 ouster Exp $ SPRITE (Berkeley)
X'\" 
X.so \*(]ltmac.sprite
X.HS Tcl_StringMatch tcl
X.VS
X.BS
X.SH NAME
XTcl_StringMatch \- test whether a string matches a pattern
X.SH SYNOPSIS
X.nf
X\fB#include <tcl.h>\fR
X.sp
Xint
X\Tcl_StringMatch\fR(\fIstring\fR, \fIpattern\fR)
X.SH ARGUMENTS
X.AP char *string in
XString to test.
X.AP char *pattern in
XPattern to match against string.  May contain special
Xcharacters from the set *?\e[].
X.BE
X
X.SH DESCRIPTION
X.PP
XThis utility procedure determines whether a string matches
Xa given pattern.  If it does, then \fBTcl_StringMatch\fR returns
X1.  Otherwise \fBTcl_StringMatch\fR returns 0.  The algorithm
Xused for matching is the same algorithm used in the ``string match''
XTcl command and is similar to the algorithm used by the C-shell
Xfor file name matching;  see the Tcl manual entry for details.
X
X.SH KEYWORDS
Xmatch, pattern, string
X.VE
END_OF_FILE
if test 1366 -ne `wc -c <'StringMatc.3'`; then
    echo shar: \"'StringMatc.3'\" unpacked with wrong size!
fi
# end of 'StringMatc.3'
fi
if test -f 'WatchInter.3' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'WatchInter.3'\"
else
echo shar: Extracting \"'WatchInter.3'\" \(1953 characters\)
sed "s/^X//" >'WatchInter.3' <<'END_OF_FILE'
X'\" Copyright 1989 Regents of the University of California
X'\" Permission to use, copy, modify, and distribute this
X'\" documentation for any purpose and without fee is hereby
X'\" granted, provided that this notice appears in all copies.
X'\" The University of California makes no representations about
X'\" the suitability of this material for any purpose.  It is
X'\" provided "as is" without express or implied warranty.
X'\" 
X'\" $Header: /sprite/src/lib/tcl/RCS/Tcl_WatchInterp.man,v 1.1 89/05/15 16:15:39 ouster Exp $ SPRITE (Berkeley)
X'/" 
X.so \*(]ltmac.sprite
X.HS Tcl_WatchInterp tcl
X.VS
X.BS
X.SH NAME
XTcl_WatchInterp \- arrange for callback when interpreter is deleted.
X.SH SYNOPSIS
X\fB#include <tcl.h>\fR
X.sp
X\fBTcl_WatchInterp\fR(\fIinterp\fR, \fIproc\fR, \fIclientData\fR)
X.SH ARGUMENTS
X.AS ClientData (*deleteProc)()
X.AP Tcl_Interp *interp in
XInterpreter whose deletion should be monitored.
X.AP char *cmdName in
XName of new command.
X.AP void (*proc)() in
XProcedure to invoke just before \fIinterp\fR is deleted.
X.AP ClientData clientData in
XArbitrary one-word value to pass to \fIproc\fR.
X.BE
X
X.SH DESCRIPTION
X.PP
X\fBTcl_WatchInterp\fR arranges for \fIproc\fR to be called by
X\fBTcl_DeleteInterp\fR if/when \fIinterp\fR is deleted at some future
Xtime.  \fIProc\fR will be invoked just before the interpreter
Xis deleted, but the interpreter will still be valid at the
Xtime of the call.  \fIProc\fR should have the following structure:
X.nf
X.RS
Xvoid
Xproc(\fIclientData\fR, \fIinterp\fR)
X.RS
XClientData \fIclientData\fR;
XTcl_Interp *\fIinterp\fR;
X.RE
X{
X}
X.RE
X.fi
XThe \fIclientData\fP and \fIinterp\fR parameters are
Xcopies of the \fIclientData\fP and \fIinterp\fR arguments given
Xto \fBTcl_WatchInterp\fR.
XTypically, \fIclientData\fR points to an application-specific
Xdata structure that \fIproc\fR uses to perform cleanup when an
Xinterpreter is about to go away.  \fIProc\fR does not return
Xa value.
X
X.SH KEYWORDS
Xcallback, delete, interpreter
X.VE
END_OF_FILE
if test 1953 -ne `wc -c <'WatchInter.3'`; then
    echo shar: \"'WatchInter.3'\" unpacked with wrong size!
fi
# end of 'WatchInter.3'
fi
echo shar: End of archive 2 \(of 2\).
cp /dev/null ark2isdone
MISSING=""
for I in 1 2 ; do
    if test ! -f ark${I}isdone ; then
	MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked both archives.
    rm -f ark[1-9]isdone
else
    echo You still need to unpack the following archives:
    echo "        " ${MISSING}
fi
##  End of shell archive.
exit 0
-- 
 _--_|\  `-_-' Peter da Silva. +1 713 274 5180. <peter@ficc.uu.net>.
/      \  'U`
\_.--._/
      v


