Newsgroups: comp.sources.misc From: karl@sugar.neosoft.com (Karl Lehenbauer) Subject: v25i076: tcl - tool command language, version 6.1, Part08/33 Message-ID: <1991Nov14.202831.23669@sparky.imd.sterling.com> X-Md4-Signature: a92a88a7189035c173b1d62f27300529 Date: Thu, 14 Nov 1991 20:28:31 GMT Approved: kent@sparky.imd.sterling.com Submitted-by: karl@sugar.neosoft.com (Karl Lehenbauer) Posting-number: Volume 25, Issue 76 Archive-name: tcl/part08 Environment: UNIX #! /bin/sh # This is a shell archive. Remove anything before this line, then unpack # it by saving it into a file and typing "sh file". To overwrite existing # files, type "sh file -c". You can also feed this as standard input via # unshar, or by typing "sh 'tcl6.1/README' <<'END_OF_FILE' XTcl X Xby John Ousterhout XUniversity of California at Berkeley Xouster@sprite.berkeley.edu X X1. Introduction X--------------- X XThis directory contains the sources and documentation for Tcl, an Xembeddable tool command language. The information here corresponds Xto release 6.1. The 6.x releases of Tcl are different in many ways Xfrom releases before 6.0. See below for general information on potential Xincompatibilies. The file "changes" has a complete list of all changes Xmade to Tcl, with incompatible changes specially marked. Tcl 6.1 has Xonly one incompatible change relative to 6.0, concerning the "regexp" Xcommand. X XFor an introduction to the facilities provided by Tcl, see the paper X``Tcl: An Embeddable Command Language'', in the Proceedings of the X1990 Winter USENIX Conference. A copy of that paper is included here Xin Postscript form in the file "doc/usenix.ps" and in text form in the Xfile "doc/usenix.text". However, the paper corresponds to a much Xearlier version of Tcl (approximately version 3.0), so some details Xof the paper may not be correct anymore and there are many new features Xnot documented in the paper. X X2. Documentation X---------------- X XThe "doc" subdirectory contains a complete set of manual entries Xfor Tcl. The file "doc/Tcl.man" gives an overall description of the XTcl language and describes the core Tcl commands. The other ".man" Xfiles in "doc" describe the library procedures that Tcl provides for XTcl-based applications. Read the "Tcl" man page first. To print any Xof the man pages, cd to the "doc" directory and invoke your favorite Xvariant of troff using the normal -man macros, for example X X ditroff -man X Xwhere is the name of the man page you'd like to print. X X3. Machines supported X--------------------- X XIf you follow the directions below, this release should compile Xand run on the following configurations either "out of the box" Xor with only trivial changes: X X - Sun-3's, Sun-4's, SPARCstation-1's and SPARCstation-2's running X many variants of SunOS, such as 4.1. X - DECstation-3100's and DECstation-5000's running many versions of X Ultrix, such as 2.0 and 4.2. X - DEC VAXes running many versions of Ultrix or BSD UNIX. X - Intel 386 based systems running SCO Unix 3.2v2. X - Intel 386 based systems running SCO Xenix 2.3.3. X - Intel 386 based systems running Bell-Tech (now Intel) Unix 3.2.0. X - Silicon Graphics systems running IRIX 4.0. X - Various H-P machines running versions of HP-UX such as 7.05 X XIf you find problems running Tcl on any of the above configurations, Xplease let me know. Also, if you are able to compile Tcl and run the Xtest suite successfully on configurations not listed above, please Xlet me know and tell me what changes, if any, you needed to make to Xdo it. I'd like to keep the above list up-to-date and continue to Ximprove the portability of Tcl. X X4. Compiling Tcl X---------------- X XTo compile Tcl on any of the configurations listed above, or systems Xsimilar to them, do the following: X X (a) Edit the "set" commands at the beginning of the file "config" X if necessary to correspond to your system configuration (they X should already be right for most versions of Unix). X X (b) Type "./config" in the top-level directory. "Config" is a script X that pokes around in your system to see if certain almost-standard X things are missing (header files, library procedures, etc.); X if your system doesn't seem to have them, it configures Tcl to X use its own copies of these things instead (Tcl's copies are X kept in the "compat" subdirectory). Config prints out messages X for all the substitutions it made. You can ignore any of the X messages unless they say "ERROR!!"; in this case something is X fundamentally wrong and the config script couldn't handle your X system configuration. X X (c) Type "make" to compile the library. This will create the Tcl X library in "libtcl.a". The Makefile should work without any X modifications but you may wish to personalize it, e.g. to X turn on compiler optimization. X X (d) If the combination of "config" and "make" doesn't work for you, X then I suggest the following approach: X - Start again with a fresh copy of the distribution. X - Set the #defines that appear at the very front of X tclUnix.h (before the first #include) to correspond X to your system. X - Modify Makefile to set CC, CFLAGS, etc. for your system. X - If things don't compile or don't link, then you may need X to copy some of the .c or .h files from the "compat" X directory into the main Tcl directory to compensate for X files missing from your system. Modify the COMPAT_OBJS X definition in Makefile to include a .o name for each of X the .c files that you copied up from the compat directory. X X (e) Create a directory /usr/local/lib/tcl and copy all the files X from the "library" subdirectory to /usr/local/lib/tcl. Or, X you can use some other directory as library, but you'll need X to modify the Makefile to reflect this fact (change the X TCL_LIBRARY definition). X X (f) Type "make tclTest", which will create a simple test program that X you can use to try out the Tcl facilities. TclTest is just a X main-program sandwich around the Tcl library. It reads standard X input until it reaches the end of a line where parentheses and X backslashes are balanced, then sends everything it's read to the X Tcl interpreter. When the Tcl interpreter returns, tclTest prints X the return value or error message. TclTest defines a few other X additional commands, most notably: X X echo arg arg ... X X The "echo" command prints its arguments on standard output, X separated by spaces. X X5. Test suite X------------- X XThere is a relatively complete test suite for all of the Tcl core in Xthe subdirectory "tests". To use it, run tclTest in this directory Xand then type the following commands: X X cd tests X source all X XYou should then see a printout of the test files processed. If any Xerrors occur, you'll see a much more substantial printout for each Xerror. Tcl should pass the test suite cleanly on all of the systems Xlisted in Section 3. See the README file in the "tests" directory Xfor more information on the test suite. X X6. Compiling on non-UNIX systems X-------------------------------- X XThe Tcl features that depend on system calls peculiar to UNIX (stat, Xfork, exec, times, etc.) are now separate from the main body of Tcl, Xwhich only requires a few generic library procedures such as malloc Xand strcpy. Thus it should be relatively easy to compile Tcl for Xthese machines, although a number of UNIX-specific commands will Xbe absent (e.g. exec, time, and glob). See the comments at the Xtop of Makefile for information on how to compile without the UNIX Xfeatures. X X7. Major changes for release 6.0 X-------------------------------- X XVersion 6.0 is a major new release with a number of improvements over Xearlier releases and several changes that are not backward compatible. XIf you've been using earlier releases of Tcl you'll need to make changes Xto both your Tcl scripts and to your C application code in order to Xuse this release. In general, a change in the major release number X(e.g. from 5.x to 6.x) means that there are significant incompatibilities Xbetween the new release and old releases. X XA complete list of all changes to Tcl can be found in the file "changes", Xin chronological order. In addition, the manual entries contain change Xbars in the right margins for all recent changes (the "changes" file Xindicates the last time that all the change bars were removed from the Xdocumentation). Here is a short list of some of the most significant Xenhancements in Tcl 6.0: X X - Floating-point support in expressions X - Associative arrays X - Support in "exec" for pipelines, background, redirection X - Support for regular expressions and other forms of string manipulation X - New commands for file I/O (open, close, gets, puts, etc.) X - Support for demand-loading of Tcl scripts X - Several new list-manipulation commands X - Improved portability, especially to System-V systems X - ANSI C function prototypes X - Improved test suite X - Many other new commands X XHere is a list of the most important incompatibilities introduced by XTcl 6.0: X X - Newlines inside bracketed commands used to be treated as word X separators; they are now treated as command separators (this is X consistent with the way newlines are treated elsewhere in Tcl). X - The order of arguments to the "file" command has been changed so X that the "option" argument is first instead of second (this makes X "file" consistent with all other Tcl commands). X - The "index", "length", "print", and "range" commands have all been X deleted (similar effects can be achieved using other commands). X - Command abbreviations are no longer supported directly (but they X can be added using the "unknown" command and are supported in the X library version of "unknown"). X - The "<" notation in "exec" has been changed to "<<". X - The "exec" command deletes the last character of program output if X it is a newline (in most cases this makes it easier to parse the X program output). X - The variable-tracing mechanism has been totally changed to accommodate X associative arrays; most of the C interfaces to Tcl variables have X changed at least slightly. X - The C interfaces to the expression evaluator and to Tcl_Eval have X changed slightly. X X8. Special thanks X----------------- X XMark Diekhans and Karl Lehenbauer of Santa Cruz Operation deserve special Xthanks for all their help during the development of Tcl 6.0. Many of the Xnew features in Tcl 6.0 were inspired by an enhanced version of Tcl 3.3 Xcalled Extended Tcl 4.0, which was created by Mark, Karl, and Peter Xda Silva. Mark and Karl explained these features to me and provided Xexcellent (and challenging) feedback during the 6.0 development process. XThey were also a great help in finding and fixing portability problems. XWithout their ideas and assistance Tcl 6.0 would be much less powerful. X X9. Support X---------- X XThere is no official support organization for Tcl, and I can't promise Xto provide much hand-holding to people learning Tcl. However, I'm very Xinterested in receiving bug reports and suggestions for improvements. XBugs usually get fixed quickly (particularly if they are serious), but Xenhancements may take a while and may not happen at all unless there Xis widespread support for them. X X10. Tcl mailing list X-------------------- X XI maintain a mail alias of people interested in exchanging ideas and Xexperiences with Tcl and Tcl-based applications (such as the Tk Xtoolkit). If you would like to join the mailing list, send a Xrequest to "tcl-request@sprite.berkeley.edu". Traffic on the Xmailing list is moderate to low: a few messages per week, on average. XThere will be a "comp.lang.tcl" newsgroup soon. END_OF_FILE if test 10992 -ne `wc -c <'tcl6.1/README'`; then echo shar: \"'tcl6.1/README'\" unpacked with wrong size! fi # end of 'tcl6.1/README' fi if test -f 'tcl6.1/doc/SetResult.man' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'tcl6.1/doc/SetResult.man'\" else echo shar: Extracting \"'tcl6.1/doc/SetResult.man'\" \(9903 characters\) sed "s/^X//" >'tcl6.1/doc/SetResult.man' <<'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: /user6/ouster/tcl/doc/RCS/SetResult.man,v 1.6 91/09/04 16:37:49 ouster Exp $ SPRITE (Berkeley) X'\" X.\" The definitions below are for supplemental macros used in Sprite X.\" manual entries. X.\" X.\" .HS name section [date [version]] X.\" Replacement for .TH in other man pages. See below for valid X.\" section names. X.\" X.\" .AP type name in/out [indent] X.\" Start paragraph describing an argument to a library procedure. X.\" type is type of argument (int, etc.), in/out is either "in", "out", X.\" or "in/out" to describe whether procedure reads or modifies arg, X.\" and indent is equivalent to second arg of .IP (shouldn't ever be X.\" needed; use .AS below instead) X.\" X.\" .AS [type [name]] X.\" Give maximum sizes of arguments for setting tab stops. Type and X.\" name are examples of largest possible arguments that will be passed X.\" to .AP later. If args are omitted, default tab stops are used. X.\" X.\" .BS X.\" Start box enclosure. From here until next .BE, everything will be X.\" enclosed in one large box. X.\" X.\" .BE X.\" End of box enclosure. X.\" X.\" .VS X.\" Begin vertical sidebar, for use in marking newly-changed parts X.\" of man pages. X.\" X.\" .VE X.\" End of vertical sidebar. X.\" X.\" .DS X.\" Begin an indented unfilled display. X.\" X.\" .DE X.\" End of indented unfilled display. X.\" X' # Heading for Sprite man pages X.de HS X.if '\\$2'cmds' .TH \\$1 1 \\$3 \\$4 X.if '\\$2'lib' .TH \\$1 3 \\$3 \\$4 X.if '\\$2'tcl' .TH \\$1 3 \\$3 \\$4 X.if '\\$2'tk' .TH \\$1 3 \\$3 \\$4 X.if t .wh -1.3i ^B X.nr ^l \\n(.l X.ad b X.. X' # Start an argument description X.de AP X.ie !"\\$4"" .TP \\$4 X.el \{\ X. ie !"\\$2"" .TP \\n()Cu X. el .TP 15 X.\} X.ie !"\\$3"" \{\ X.ta \\n()Au \\n()Bu X\&\\$1 \\fI\\$2\\fP (\\$3) X.\".b X.\} X.el \{\ X.br X.ie !"\\$2"" \{\ X\&\\$1 \\fI\\$2\\fP X.\} X.el \{\ X\&\\fI\\$1\\fP X.\} X.\} X.. X' # define tabbing values for .AP X.de AS X.nr )A 10n X.if !"\\$1"" .nr )A \\w'\\$1'u+3n X.nr )B \\n()Au+15n X.\" X.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n X.nr )C \\n()Bu+\\w'(in/out)'u+2n X.. X' # BS - start boxed text X' # ^y = starting y location X' # ^b = 1 X.de BS X.br X.mk ^y X.nr ^b 1u X.if n .nf X.if n .ti 0 X.if n \l'\\n(.lu\(ul' X.if n .fi X.. X' # BE - end boxed text (draw box now) X.de BE X.nf X.ti 0 X.mk ^t X.ie n \l'\\n(^lu\(ul' X.el \{\ X.\" Draw four-sided box normally, but don't draw top of X.\" box if the box started on an earlier page. X.ie !\\n(^b-1 \{\ X\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' X.\} X.el \}\ X\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' X.\} X.\} X.fi X.br X.nr ^b 0 X.. X' # VS - start vertical sidebar X' # ^Y = starting y location X' # ^v = 1 (for troff; for nroff this doesn't matter) X.de VS X.mk ^Y X.ie n 'mc \s12\(br\s0 X.el .nr ^v 1u X.. X' # VE - end of vertical sidebar X.de VE X.ie n 'mc X.el \{\ X.ev 2 X.nf X.ti 0 X.mk ^t X\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' X.sp -1 X.fi X.ev X.\} X.nr ^v 0 X.. X' # Special macro to handle page bottom: finish off current X' # box/sidebar if in box/sidebar mode, then invoked standard X' # page bottom macro. X.de ^B X.ev 2 X'ti 0 X'nf X.mk ^t X.if \\n(^b \{\ X.\" Draw three-sided box if this is the box's first page, X.\" draw two sides but no top otherwise. X.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c X.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c X.\} X.if \\n(^v \{\ X.nr ^x \\n(^tu+1v-\\n(^Yu X\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c X.\} X.bp X'fi X.ev X.if \\n(^b \{\ X.mk ^y X.nr ^b 2 X.\} X.if \\n(^v \{\ X.mk ^Y X.\} X.. X' # DS - begin display X.de DS X.RS X.nf X.sp X.. X' # DE - end display X.de DE X.fi X.RE X.sp .5 X.. X.HS Tcl_SetResult tcl X.BS X.SH NAME XTcl_SetResult, Tcl_AppendResult, Tcl_AppendElement, Tcl_ResetResult \- manipulate Tcl result string X.SH SYNOPSIS X.nf X\fB#include \fR X.sp X.VS X\fBTcl_SetResult\fR(\fIinterp, string, freeProc\fR) X.VE X.sp X\fBTcl_AppendResult(\fIinterp, string, string, ... , \fB(char *) NULL\fR) X.sp X.VS X\fBTcl_AppendElement\fR(\fIinterp, string, noSep\fR) X.sp X\fBTcl_ResetResult\fR(\fIinterp\fR) X.sp X\fBTcl_FreeResult\fR(\fIinterp\fR) X.VE X.SH ARGUMENTS X.AS Tcl_FreeProc freeProc X.AP Tcl_Interp *interp out XInterpreter whose result is to be modified. X.AP char *string in XString value to be become result for \fIinterp\fR or to be Xappended to existing result. X.AP Tcl_FreeProc freeProc in X.VS XAddress of procedure to call to release storage at X\fIstring\fR, or \fBTCL_STATIC\fR, \fBTCL_DYNAMIC\fR, or X\fBTCL_VOLATILE\fR. X.AP int noSep in XIf non-zero then don't output a space character before this element, Xeven if the element isn't the first thing in the result string. X.VE X.BE X X.SH DESCRIPTION X.PP XThe procedures described here are utilities for setting the Xresult/error string in a Tcl interpreter. X.PP X\fBTcl_SetResult\fR Xarranges for \fIstring\fR to be the return string for the current Tcl Xcommand in \fIinterp\fR, replacing any existing result. X.VS XIf \fIfreeProc\fR is \fBTCL_STATIC\fR it means that \fIstring\fR Xrefers to an area of static storage that is guaranteed not to be Xmodified until at least the next call to \fBTcl_Eval\fR. XIf \fIfreeProc\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. X\fBTcl_SetResult\fR will arrange for the string's storage to be Xreleased by calling \fBfree()\fR when it is no longer needed. XIf \fIfreeProc\fR is \fBTCL_VOLATILE\fR it means that \fIstring\fR Xpoints to an area of memory that is likely to be overwritten when X\fBTcl_SetResult\fR returns (e.g. it points to something in a stack frame). XIn this case \fBTcl_SetResult\fR will make a copy of the string in Xdynamically allocated storage and arrange for the copy to be the Xreturn string for the current Tcl command. X.PP XIf \fIfreeProc\fR isn't one of the values \fBTCL_STATIC\fR, X\fBTCL_DYNAMIC\fR, and \fBTCL_VOLATILE\fR, then it is the address Xof a procedure that Tcl should call to free the string. XThis allows applications to use non-standard storage allocators. XWhen Tcl no longer needs the storage for the string, it will Xcall \fIfreeProc\fR. \fIFreeProc\fR should have arguments and Xresult that match the type \fBTcl_FreeProc\fR: X.nf X.RS X Xtypedef void Tcl_FreeProc(char *\fIblockPtr\fR); X X.RE X.fi XWhen \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to Xthe value of \fIstring\fR passed to \fBTcl_SetResult\fR. X.VE X.PP XIf \fIstring\fR is \fBNULL\fR, then \fIfreeProc\fR is ignored Xand \fBTcl_SetResult\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 X.VS XIf \fBTcl_SetResult\fR is called at a time when \fIinterp\fR holds a Xresult, \fBTcl_SetResult\fR does whatever is necessary to dispose Xof the old result (see the \fBTcl_Interp\fR manual entry for details Xon this). X.VE X.PP X\fBTcl_AppendResult\fR makes it easy to build up Tcl results in pieces. XIt takes each of its \fIstring\fR arguments and appends them in order Xto the current result associated with \fIinterp\fR. X.VS XIf the result is in its initialized empty state (e.g. a command procedure Xwas just invoked or \fBTcl_ResetResult\fR was just called), Xthen \fBTcl_AppendResult\fR sets the result to the concatenation of Xits \fIstring\fR arguments. X.VE X\fBTcl_AppendResult\fR may be called repeatedly as additional pieces Xof the result are produced. X\fBTcl_AppendResult\fR takes care of all the Xstorage management issues associated with managing \fIinterp\fR's Xresult, such as allocating a larger result area if necessary. XAny number of \fIstring\fR arguments may be passed in a single Xcall; the last argument in the list must be a NULL pointer. X.PP X\fBTcl_AppendElement\fR is similar to \fBTcl_AppendResult\fR in X.VS Xthat it allows results to be built up in pieces. XHowever, \fBTcl_AppendElement\fR takes only a single \fIstring\fR Xargument and it appends that argument to the current result Xas a proper Tcl list element. X\fBTcl_AppendElement\fR adds backslashes or braces if necessary Xto ensure that \fIinterp\fR's result can be parsed as a list and that X\fIstring\fR will be extracted as a single element. XUnder normal conditions, \fBTcl_AppendElement\fR will add a space Xcharacter to \fIinterp\fR's result just before adding the new Xlist element, so that the list elements in the result are properly Xseparated. XHowever, if \fIinterp\fR's result is empty when \fBTcl_AppendElement\fR Xis called, or if the \fInoSep\fR argument is 1, then no space Xis added. X.PP X\fBTcl_ResetResult\fR clears the result for \fIinterp\fR, Xfreeing the memory associated with it if the current result was Xdynamically allocated. XIt leaves the result in its normal initialized state with X\fIinterp->result\fR pointing to a static buffer containing X\fBTCL_RESULT_SIZE\fR characters, of which the first character Xis zero. X\fBTcl_ResetResult\fR also clears the error state managed by X\fBTcl_AddErrorInfo\fR and \fBTcl_SetErrorCode\fR. X.PP X\fBTcl_FreeResult\fR is a macro that performs part of the work Xof \fBTcl_ResetResult\fR. XIt frees up the memory associated with \fIinterp\fR's result Xand sets \fIinterp->freeProc\fR to zero, but it doesn't Xchange \fIinterp->result\fR or clear error state. X\fBTcl_FreeResult\fR is most commonly used when a procedure Xis about to replace one result value with another. X.VE X X.SH "SEE ALSO" XTcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_Interp X X.SH KEYWORDS Xappend, command, element, list, result, return value, interpreter END_OF_FILE if test 9903 -ne `wc -c <'tcl6.1/doc/SetResult.man'`; then echo shar: \"'tcl6.1/doc/SetResult.man'\" unpacked with wrong size! fi # end of 'tcl6.1/doc/SetResult.man' fi if test -f 'tcl6.1/doc/SetVar.man' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'tcl6.1/doc/SetVar.man'\" else echo shar: Extracting \"'tcl6.1/doc/SetVar.man'\" \(9653 characters\) sed "s/^X//" >'tcl6.1/doc/SetVar.man' <<'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: /user6/ouster/tcl/man/RCS/SetVar.man,v 1.7 91/11/01 14:40:53 ouster Exp $ SPRITE (Berkeley) X'\" X.\" The definitions below are for supplemental macros used in Sprite X.\" manual entries. X.\" X.\" .HS name section [date [version]] X.\" Replacement for .TH in other man pages. See below for valid X.\" section names. X.\" X.\" .AP type name in/out [indent] X.\" Start paragraph describing an argument to a library procedure. X.\" type is type of argument (int, etc.), in/out is either "in", "out", X.\" or "in/out" to describe whether procedure reads or modifies arg, X.\" and indent is equivalent to second arg of .IP (shouldn't ever be X.\" needed; use .AS below instead) X.\" X.\" .AS [type [name]] X.\" Give maximum sizes of arguments for setting tab stops. Type and X.\" name are examples of largest possible arguments that will be passed X.\" to .AP later. If args are omitted, default tab stops are used. X.\" X.\" .BS X.\" Start box enclosure. From here until next .BE, everything will be X.\" enclosed in one large box. X.\" X.\" .BE X.\" End of box enclosure. X.\" X.\" .VS X.\" Begin vertical sidebar, for use in marking newly-changed parts X.\" of man pages. X.\" X.\" .VE X.\" End of vertical sidebar. X.\" X.\" .DS X.\" Begin an indented unfilled display. X.\" X.\" .DE X.\" End of indented unfilled display. X.\" X' # Heading for Sprite man pages X.de HS X.if '\\$2'cmds' .TH \\$1 1 \\$3 \\$4 X.if '\\$2'lib' .TH \\$1 3 \\$3 \\$4 X.if '\\$2'tcl' .TH \\$1 3 \\$3 \\$4 X.if '\\$2'tk' .TH \\$1 3 \\$3 \\$4 X.if t .wh -1.3i ^B X.nr ^l \\n(.l X.ad b X.. X' # Start an argument description X.de AP X.ie !"\\$4"" .TP \\$4 X.el \{\ X. ie !"\\$2"" .TP \\n()Cu X. el .TP 15 X.\} X.ie !"\\$3"" \{\ X.ta \\n()Au \\n()Bu X\&\\$1 \\fI\\$2\\fP (\\$3) X.\".b X.\} X.el \{\ X.br X.ie !"\\$2"" \{\ X\&\\$1 \\fI\\$2\\fP X.\} X.el \{\ X\&\\fI\\$1\\fP X.\} X.\} X.. X' # define tabbing values for .AP X.de AS X.nr )A 10n X.if !"\\$1"" .nr )A \\w'\\$1'u+3n X.nr )B \\n()Au+15n X.\" X.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n X.nr )C \\n()Bu+\\w'(in/out)'u+2n X.. X' # BS - start boxed text X' # ^y = starting y location X' # ^b = 1 X.de BS X.br X.mk ^y X.nr ^b 1u X.if n .nf X.if n .ti 0 X.if n \l'\\n(.lu\(ul' X.if n .fi X.. X' # BE - end boxed text (draw box now) X.de BE X.nf X.ti 0 X.mk ^t X.ie n \l'\\n(^lu\(ul' X.el \{\ X.\" Draw four-sided box normally, but don't draw top of X.\" box if the box started on an earlier page. X.ie !\\n(^b-1 \{\ X\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' X.\} X.el \}\ X\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' X.\} X.\} X.fi X.br X.nr ^b 0 X.. X' # VS - start vertical sidebar X' # ^Y = starting y location X' # ^v = 1 (for troff; for nroff this doesn't matter) X.de VS X.mk ^Y X.ie n 'mc \s12\(br\s0 X.el .nr ^v 1u X.. X' # VE - end of vertical sidebar X.de VE X.ie n 'mc X.el \{\ X.ev 2 X.nf X.ti 0 X.mk ^t X\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' X.sp -1 X.fi X.ev X.\} X.nr ^v 0 X.. X' # Special macro to handle page bottom: finish off current X' # box/sidebar if in box/sidebar mode, then invoked standard X' # page bottom macro. X.de ^B X.ev 2 X'ti 0 X'nf X.mk ^t X.if \\n(^b \{\ X.\" Draw three-sided box if this is the box's first page, X.\" draw two sides but no top otherwise. X.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c X.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c X.\} X.if \\n(^v \{\ X.nr ^x \\n(^tu+1v-\\n(^Yu X\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c X.\} X.bp X'fi X.ev X.if \\n(^b \{\ X.mk ^y X.nr ^b 2 X.\} X.if \\n(^v \{\ X.mk ^Y X.\} X.. X' # DS - begin display X.de DS X.RS X.nf X.sp X.. X' # DE - end display X.de DE X.fi X.RE X.sp .5 X.. X.HS Tcl_SetVar tcl X.BS X.VS X.SH NAME XTcl_SetVar, Tcl_SetVar2, Tcl_GetVar, Tcl_GetVar2, Tcl_UnsetVar, Tcl_UnsetVar2 \- manipulate Tcl variables X.SH SYNOPSIS X.nf X\fB#include \fR X.sp Xchar * X\fBTcl_SetVar\fR(\fIinterp, varName, newValue, flags\fR) X.sp Xchar * X\fBTcl_SetVar2\fR(\fIinterp, name1, name2, newValue, flags\fR) X.sp Xchar * X\fBTcl_GetVar\fR(\fIinterp, varName, flags\fR) X.sp Xchar * X\fBTcl_GetVar2\fR(\fIinterp, name1, name2, flags\fR) X.sp Xint X\fBTcl_UnsetVar\fR(\fIinterp, varName, flags\fR) X.sp Xint X\fBTcl_UnsetVar2\fR(\fIinterp, name1, name2, flags\fR) X.SH ARGUMENTS X.AS Tcl_Interp *interp X.AP Tcl_Interp *interp in XInterpreter containing variable. X.AP char *varName in XName of variable. May refer to a scalar variable or an element of Xan array variable. X.AP char *newValue in XNew value for variable. X.AP int flags in XOR-ed combination of bits providing additional information for Xoperation. See below for valid values. X.AP char *name1 in XName of scalar variable, or name of array variable if \fIname2\fR Xis non-NULL. X.AP char *name2 in XIf non-NULL, gives name of element within array and \fIname1\fR Xmust refer to an array variable. X.BE X X.SH DESCRIPTION X.PP XThese procedures may be used to create, modify, read, and delete XTcl variables from C code. X\fBTcl_SetVar\fR and \fBTcl_SetVar2\fR will create a new variable Xor modify an existing one. XBoth of these procedures set the given variable to the value Xgiven by \fInewValue\fR, and they return a pointer to a Xcopy of the variable's new value, which is stored in Tcl's Xvariable structure. XTcl keeps a private copy of the variable's value, so the caller Xmay change \fInewValue\fR after these procedures return without Xaffecting the value of the variable. XIf an error occurs in setting the variable (e.g. an array Xvariable is referenced without giving an index into the array), Xthen NULL is returned. X.PP XThe name of the variable may be specified in either of two ways. XIf \fBTcl_SetVar\fR is called, the variable name is given as Xa single string, \fIvarName\fR. XIf \fIvarName\fR contains an open parenthesis and ends with a Xclose parenthesis, then the value between the parentheses is Xtreated as an index (which can have any string value) and Xthe characters before the first open Xparenthesis are treated as the name of an array variable. XIf \fIvarName\fR doesn't have parentheses as described above, then Xthe entire string is treated as the name of a scalar variable. XIf \fBTcl_SetVar2\fR is called, then the array name and index Xhave been separated by the caller into two separate strings, X\fIname1\fR and \fIname2\fR respectively; if \fIname2\fR is Xzero it means that a scalar variable is being referenced. X.PP XThe \fIflags\fR argument may be used to specify any of several Xoptions to the procedures. XIt consists of an OR-ed combination of any of the following Xbits: X.IP TCL_GLOBAL_ONLY XUnder normal circumstances the procedures look up variables Xat the current level of procedure call for \fIinterp\fR, or Xat global level if there is no call active. XHowever, if this bit is set in \fIflags\fR then the variable Xis looked up at global level even if there is a procedure Xcall active. X.IP TCL_LEAVE_ERR_MSG XIf an error is returned and this bit is set in \fIflags\fR, then Xan error message will be left in \fI\%interp->result\fR. If this Xflag bit isn't set then no error message is left (\fI\%interp->result\fR Xwill not be modified). X.IP TCL_APPEND_VALUE XIf this bit is set then \fInewValue\fR is appended to the current Xvalue, instead of replacing it. XIf the variable is currently undefined, then this bit is ignored. X.IP TCL_LIST_ELEMENT XIf this bit is set, then \fInewValue\fR is converted to a valid XTcl list element before setting (or appending to) the variable. XIf the list element is being appended to an non-empty value, then Xa space character is appended before the new list element to Xseparate it from previous elements. X.IP TCL_NO_SPACE XIf this bit is set, it prevents the output of a separating space Xcharacter in TCL_LIST_ELEMENT appends. XThis bit has no effect if the TCL_LIST_ELEMENT bit isn't set. X.PP X\fBTcl_GetVar\fR and \fBTcl_GetVar2\fR return the current value Xof a variable. XThe arguments to these procedures are treated in the same way Xas the arguments to \fBTcl_SetVar\fR and \fBTcl_SetVar2\fR. XUnder normal circumstances, the return value is a pointer Xto the variable's value (which is stored in Tcl's variable Xstructure and will not change before the next call to \fBTcl_SetVar\fR Xor \fBTcl_SetVar2\fR). XThe only bits of \fIflags\fR that are used are TCL_GLOBAL_ONLY Xand TCL_LEAVE_ERR_MSG, both of Xwhich have Xthe same meaning as for \fBTcl_SetVar\fR. XIf an error occurs in reading the variable (e.g. the variable Xdoesn't exist or an array element is specified for a scalar Xvariable), then NULL is returned. X.PP X\fBTcl_UnsetVar\fR and \fBTcl_UnsetVar2\fR may be used to remove Xa variable, so that future calls to \fBTcl_GetVar\fR or \fBTcl_GetVar2\fR Xfor the variable will return an error. XThe arguments to these procedures are treated in the same way Xas the arguments to \fBTcl_GetVar\fR and \fBTcl_GetVar2\fR. XIf the variable is successfully removed then 0 is returned. XIf the variable cannot be removed because it doesn't exist Xor because a trace is active for it, then -1 is returned. XIf an array element is specified, the given element is removed Xbut the array remains. XIf an array name is specified without an index, then the entire Xarray is removed. X X.SH "SEE ALSO" XTcl_TraceVar X X.SH KEYWORDS Xarray, interpreter, scalar, set, unset, variable X.VE END_OF_FILE if test 9653 -ne `wc -c <'tcl6.1/doc/SetVar.man'`; then echo shar: \"'tcl6.1/doc/SetVar.man'\" unpacked with wrong size! fi # end of 'tcl6.1/doc/SetVar.man' fi if test -f 'tcl6.1/tests/string.test' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'tcl6.1/tests/string.test'\" else echo shar: Extracting \"'tcl6.1/tests/string.test'\" \(9785 characters\) sed "s/^X//" >'tcl6.1/tests/string.test' <<'END_OF_FILE' X# Commands covered: string X# X# This file contains a collection of tests for one or more of the Tcl X# built-in commands. Sourcing this file into Tcl runs the tests and X# generates output for errors. No output means no errors were found. X# X# Copyright 1991 Regents of the University of California X# Permission to use, copy, modify, and distribute this X# software and its documentation for any purpose and without X# fee is hereby granted, provided that this copyright notice X# appears in all copies. The University of California makes no X# representations about the suitability of this software for any X# purpose. It is provided "as is" without express or implied X# warranty. X# X# $Header: /sprite/src/lib/tcl/tests/RCS/string.test,v 1.5 91/09/11 16:45:17 ouster Exp $ (Berkeley) X Xif {[string compare test [info procs test]] == 1} then {source defs} X Xtest string-1.1 {string compare} { X string compare abcde abdef X} -1 Xtest string-1.2 {string compare} { X string c abcde ABCDE X} 1 Xtest string-1.3 {string compare} { X string compare abcde abcde X} 0 Xtest string-1.4 {string compare} { X list [catch {string compare a} msg] $msg X} {1 {wrong # args: should be "string compare string1 string2"}} Xtest string-1.5 {string compare} { X list [catch {string compare a b c} msg] $msg X} {1 {wrong # args: should be "string compare string1 string2"}} X Xtest string-2.1 {string first} { X string first bq abcdefgbcefgbqrs X} 12 Xtest string-2.2 {string first} { X string fir bcd abcdefgbcefgbqrs X} 1 Xtest string-2.3 {string first} { X string f b abcdefgbcefgbqrs X} 1 Xtest string-2.4 {string first} { X string first xxx x123xx345xxx789xxx012 X} 9 Xtest string-2.5 {string first} { X list [catch {string first a} msg] $msg X} {1 {wrong # args: should be "string first string1 string2"}} Xtest string-2.6 {string first} { X list [catch {string first a b c} msg] $msg X} {1 {wrong # args: should be "string first string1 string2"}} X Xtest string-3.1 {string index} { X string index abcde 0 X} a Xtest string-3.2 {string index} { X string i abcde 4 X} e Xtest string-3.3 {string index} { X string index abcde 5 X} {} Xtest string-3.4 {string index} { X list [catch {string index abcde -10} msg] $msg X} {0 {}} Xtest string-3.5 {string index} { X list [catch {string index} msg] $msg X} {1 {wrong # args: should be "string index string charIndex"}} Xtest string-3.6 {string index} { X list [catch {string index a b c} msg] $msg X} {1 {wrong # args: should be "string index string charIndex"}} Xtest string-3.7 {string index} { X list [catch {string index a xyz} msg] $msg X} {1 {expected integer but got "xyz"}} X Xtest string-4.1 {string last} { X string la xxx xxxx123xx345x678 X} 1 Xtest string-4.2 {string last} { X string last xx xxxx123xx345x678 X} 7 Xtest string-4.3 {string last} { X string las x xxxx123xx345x678 X} 12 Xtest string-4.4 {string last} { X list [catch {string last a} msg] $msg X} {1 {wrong # args: should be "string last string1 string2"}} Xtest string-4.5 {string last} { X list [catch {string last a b c} msg] $msg X} {1 {wrong # args: should be "string last string1 string2"}} X Xtest string-5.1 {string length} { X string length "a little string" X} 15 Xtest string-5.2 {string length} { X string le "" X} 0 Xtest string-5.3 {string length} { X list [catch {string length} msg] $msg X} {1 {wrong # args: should be "string length string"}} Xtest string-5.4 {string length} { X list [catch {string length a b} msg] $msg X} {1 {wrong # args: should be "string length string"}} X Xtest string-6.1 {string match} { X string match abc abc X} 1 Xtest string-6.2 {string match} { X string m abc abd X} 0 Xtest string-6.3 {string match} { X string match ab*c abc X} 1 Xtest string-6.4 {string match} { X string match ab**c abc X} 1 Xtest string-6.5 {string match} { X string match ab* abcdef X} 1 Xtest string-6.6 {string match} { X string match *c abc X} 1 Xtest string-6.7 {string match} { X string match *3*6*9 0123456789 X} 1 Xtest string-6.8 {string match} { X string match *3*6*9 01234567890 X} 0 Xtest string-6.9 {string match} { X string match a?c abc X} 1 Xtest string-6.10 {string match} { X string match a??c abc X} 0 Xtest string-6.11 {string match} { X string match ?1??4???8? 0123456789 X} 1 Xtest string-6.12 {string match} { X string match {[abc]bc} abc X} 1 Xtest string-6.13 {string match} { X string match {a[abc]c} abc X} 1 Xtest string-6.14 {string match} { X string match {a[xyz]c} abc X} 0 Xtest string-6.15 {string match} { X string match {12[2-7]45} 12345 X} 1 Xtest string-6.16 {string match} { X string match {12[ab2-4cd]45} 12345 X} 1 Xtest string-6.17 {string match} { X string match {12[ab2-4cd]45} 12b45 X} 1 Xtest string-6.18 {string match} { X string match {12[ab2-4cd]45} 12d45 X} 1 Xtest string-6.19 {string match} { X string match {12[ab2-4cd]45} 12145 X} 0 Xtest string-6.20 {string match} { X string match {12[ab2-4cd]45} 12545 X} 0 Xtest string-6.21 {string match} { X string match {a\*b} a*b X} 1 Xtest string-6.22 {string match} { X string match {a\*b} ab X} 0 Xtest string-6.23 {string match} { X string match {a\*\?\[\]\\\x} "a*?\[\]\\x" X} 1 Xtest string-6.24 {string match} { X list [catch {string match a} msg] $msg X} {1 {wrong # args: should be "string match pattern string"}} Xtest string-6.25 {string match} { X list [catch {string match a b c} msg] $msg X} {1 {wrong # args: should be "string match pattern string"}} X Xtest string-7.1 {string range} { X string range abcdefghijklmnop 2 14 X} {cdefghijklmno} Xtest string-7.2 {string range} { X string range abcdefghijklmnop 7 1000 X} {hijklmnop} Xtest string-7.3 {string range} { X string range abcdefghijklmnop 10 e X} {klmnop} Xtest string-7.4 {string range} { X string range abcdefghijklmnop 10 9 X} {} Xtest string-7.5 {string range} { X string range abcdefghijklmnop -3 2 X} {abc} Xtest string-7.6 {string range} { X string range abcdefghijklmnop -3 -2 X} {} Xtest string-7.7 {string range} { X string range abcdefghijklmnop 1000 1010 X} {} Xtest string-7.8 {string range} { X string range abcdefghijklmnop -100 end X} {abcdefghijklmnop} Xtest string-7.9 {string range} { X list [catch {string range} msg] $msg X} {1 {wrong # args: should be "string range string first last"}} Xtest string-7.10 {string range} { X list [catch {string range a 1} msg] $msg X} {1 {wrong # args: should be "string range string first last"}} Xtest string-7.11 {string range} { X list [catch {string range a 1 2 3} msg] $msg X} {1 {wrong # args: should be "string range string first last"}} Xtest string-7.12 {string range} { X list [catch {string range abc abc 1} msg] $msg X} {1 {expected integer but got "abc"}} Xtest string-7.13 {string range} { X list [catch {string range abc 1 eof} msg] $msg X} {1 {expected integer or "end" but got "eof"}} X Xtest string-8.1 {string trim} { X string trim " XYZ " X} {XYZ} Xtest string-8.2 {string trim} { X string trim "\t\nXYZ\t\n\r\n" X} {XYZ} Xtest string-8.3 {string trim} { X string trim " A XYZ A " X} {A XYZ A} Xtest string-8.4 {string trim} { X string trim "XXYYZZABC XXYYZZ" ZYX X} {ABC } Xtest string-8.5 {string trim} { X string trim " \t\r " X} {} Xtest string-8.6 {string trim} { X string trim {abcdefg} {} X} {abcdefg} Xtest string-8.7 {string trim} { X string trim {} X} {} Xtest string-8.8 {string trim} { X string trim ABC DEF X} {ABC} Xtest string-8.9 {string trim} { X list [catch {string trim} msg] $msg X} {1 {wrong # args: should be "string trim string ?chars?"}} Xtest string-8.10 {string trim} { X list [catch {string trim a b c} msg] $msg X} {1 {wrong # args: should be "string trim string ?chars?"}} X Xtest string-9.1 {string trimleft} { X string trimleft " XYZ " X} {XYZ } Xtest string-9.2 {string trimleft} { X list [catch {string triml} msg] $msg X} {1 {wrong # args: should be "string trimleft string ?chars?"}} X Xtest string-10.1 {string trimright} { X string trimright " XYZ " X} { XYZ} Xtest string-10.2 {string trimright} { X string trimright " " X} {} Xtest string-10.3 {string trimright} { X string trimright "" X} {} Xtest string-10.4 {string trimright errors} { X list [catch {string trimr} msg] $msg X} {1 {wrong # args: should be "string trimright string ?chars?"}} Xtest string-10.5 {string trimright errors} { X list [catch {string trimg a} msg] $msg X} {1 {bad option "trimg": should be compare, first, index, last, length, \ Xmatch, range, tolower, toupper, trim, trimleft, or trimright}} X Xtest string-11.1 {string tolower} { X string tolower ABCDeF X} {abcdef} Xtest string-11.2 {string tolower} { X string tolower "ABC XyZ" X} {abc xyz} Xtest string-11.3 {string tolower} { X string tolower {123#$&*()} X} {123#$&*()} Xtest string-11.4 {string tolower} { X list [catch {string tolower} msg] $msg X} {1 {wrong # args: should be "string tolower string"}} Xtest string-11.5 {string tolower} { X list [catch {string tolower a b} msg] $msg X} {1 {wrong # args: should be "string tolower string"}} X Xtest string-12.1 {string toupper} { X string toupper abCDEf X} {ABCDEF} Xtest string-12.2 {string toupper} { X string toupper "abc xYz" X} {ABC XYZ} Xtest string-12.3 {string toupper} { X string toupper {123#$&*()} X} {123#$&*()} Xtest string-12.4 {string toupper} { X list [catch {string toupper} msg] $msg X} {1 {wrong # args: should be "string toupper string"}} Xtest string-12.5 {string toupper} { X list [catch {string toupper a b} msg] $msg X} {1 {wrong # args: should be "string toupper string"}} X Xtest string-13.1 {error conditions} { X list [catch {string gorp a b} msg] $msg X} {1 {bad option "gorp": should be compare, first, index, last, length, \ Xmatch, range, tolower, toupper, trim, trimleft, or trimright}} Xtest string-13.2 {error conditions} { X list [catch {string} msg] $msg X} {1 {wrong # args: should be "string option arg ?arg ...?"}} END_OF_FILE if test 9785 -ne `wc -c <'tcl6.1/tests/string.test'`; then echo shar: \"'tcl6.1/tests/string.test'\" unpacked with wrong size! fi # end of 'tcl6.1/tests/string.test' fi echo shar: End of archive 8 \(of 33\). cp /dev/null ark8isdone MISSING="" for I in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 ; do if test ! -f ark${I}isdone ; then MISSING="${MISSING} ${I}" fi done if test "${MISSING}" = "" ; then echo You have unpacked all 33 archives. rm -f ark[1-9]isdone ark[1-9][0-9]isdone else echo You still need to unpack the following archives: echo " " ${MISSING} fi ## End of shell archive. exit 0 exit 0 # Just in case... -- Kent Landfield INTERNET: kent@sparky.IMD.Sterling.COM Sterling Software, IMD UUCP: uunet!sparky!kent Phone: (402) 291-8300 FAX: (402) 291-4362 Please send comp.sources.misc-related mail to kent@uunet.uu.net.