Usenet 1994 January/usenetsourcesnewsgroupsinfomagicjanuary1994.iso/sources/misc/volume26/tclx/part20

Text File | 1991-11-19 | 47.6 KB | 1,202 lines

Newsgroups: comp.sources.misc
From: [e-mail] (Karl Lehenbauer)
Subject:  v26i020:  tclx - extensions and on-line help for tcl 6.1, Part20/23
Message-ID: <[e-mail]>
X-Md4-Signature: 050056e14f4a568272054b0962de5ab0
Date: Tue, 19 Nov 1991 13:57:33 GMT
Approved: [e-mail]

Submitted-by: [e-mail] (Karl Lehenbauer)
Posting-number: Volume 26, Issue 20
Archive-name: tclx/part20
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 <file", e.g..  If this archive is complete, you
# will see the following message at the end:
#        "End of archive 20 (of 23)."
# Contents:  extended/README.EXTD extended/man/TclShell.man
# Wrapped by karl@one on Wed Nov 13 21:50:32 1991
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'extended/README.EXTD' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'extended/README.EXTD'\"
else
echo shar: Extracting \"'extended/README.EXTD'\" \(24101 characters\)
sed "s/^X//" >'extended/README.EXTD' <<'END_OF_FILE'
X
X
X              *** README.EXTD - README file for Extended Tcl ***
X
X
XEXTENDED TCL
X============
X
XExtended Tcl, also known as NeoSoft Tcl, defines a set of extensions
Xto Tcl 6.1, the Tool Command Language invented by Dr. John Ousterhout
Xof the University of California at Berkeley.  Extended Tcl is upwardly
Xcompatible from Tcl 6.1.  You take the Extended Tcl package, add it to
XTcl 6.1, and from that you get Extended Tcl.  Extended Tcl was designed
Xand implemented by Karl Lehenbauer ([e-mail]) and Mark Diekhans
X([e-mail]), with help in the early stages from Peter da Silva
X([e-mail]).
X
XExtended Tcl (TclX for short) was first publicly released as version
X4.0, to the Usenet alt.sources newsgroup in December of 1990.  The
Xextensions built upon the embeddable Tcl interpreter to create a
Xpowerful string and file processing language for Unix, adding support
Xfor extended string and list operations, stdio-style I/O to files and
Xpipelines, scanning files for lines matching regular expressions,
Xsorting, sorted file searching, arrays, Unix multitasking operations
X(fork, wait, kill, exec, etc), extensions for interactive use as a
Xshell and awk-like command-line operation.  It also included
Xdemand-loading of procedures from files and Tcl source libraries, a
Xcommand trace capability, on-line help, and more.  We also supported
XExtended Tcl on a number of versions of Unix, most significantly
Xadding support for Unix System V, unlike the original Tcl, which was
XBerkeley BSD-only.
X
XAt that time, Extended Tcl introduced some incompatibilities with
XOusterhout's Tcl 3.3, upon which it was based.  We made Extended Tcl
Xincompatible, with regrets, based on our experience using the
Xlanguage.  Adding arrays, for example, introduced an incompatibility,
Xas did changes we made in the way the exec command worked, among a few
Xother small differences.
X
XHappily, John Ousterhout worked closely with Mark and Karl over the
Xlast few months, and with his release of Tcl 6.1, most of the
Xcapabilities of Extended Tcl 4.0 have been included in his Tcl 6.1
Xbaseline.  Also, we've ironed out the incompatibilities so that
XExtended Tcl 6.1a adds new capabilities to Tcl 6.1 without introducing
Xany backward incompatibilities.  Finally, John's Tcl 6.1 now supports
Xthe most popular Unix variants.
X
XAs with the original Tcl, all of Extended Tcl is freely
Xredistributable, including commercial use and resale.
X
X
XFEATURES ADDED BY EXTENDED TCL
X==============================
X
X    o A shell, which provides an environment for developmenting and executing
X      Tcl programs.  A Tcl code library facility is provided.
X
X    o General Commands
X
X        commandloop - create and enter an interactive command environment
X
X        cmdtrace - debugging tool for tracing Tcl command execution
X
X
X        infox - find out additional information about extended Tcl,
X                such as the version, patchlevel, name, version and
X                long name of any embedded application.
X
X        loop -  a higher-performance for-style loop
X
X    o Unix Access Commands
X
X        chgrp, chmod, chown, execvp, fork, kill, sleep, system, umask,
X        unlink, wait
X
X        fmtclock - format a long integer time value into human-readable form
X
X        getclock - return current date and time as a long integer
X
X        id - get and set user, group, process and process group id's
X
X        signal - specify action to be taken when a signal occurs
X
X        times - get process and child execution times
X
X
X    o File I/O Commands
X
X        bsearch - binary search a sorted file
X
X        copyfile - copy remainder of one open file into another
X
X        dup - duplicate an open filehandle
X
X        fcntl - get or set open file access options
X
X        fstat - obtain status information about an open file
X
X        pipe - create a pipe
X
X        select - synchronous I/O multiplexing (on systems that support it)
X
X    o File Scanning Commands
X
X        scancontext - manage file scan contexts
X
X        scanfile - scan specified file against selected scan context
X
X        scanmatch - specify Tcl code to execute when scan pattern matches
X
X    o Math Commands
X
X        acos, asin, atan, ceil, cos, cosh, exp, fabs, floor, mod, max,
X        min, log, log10, pow, sin, sinh, sqrt, tan, tah
X
X        random - return a pseudorandom integer or seed the random number
X            generator
X
X
X    o List Manipulation Commands
X
X        lempty - determine if a list is empty
X
X        lvarpop - pop or replace the specified element from a list
X
X    o Keyed Lists - support for struct-like lists
X
X        keyldel - delete a field of a keyed list
X
X        keylget - get the value of a field in a keyed list
X
X        keylset - set the value of a field of a keyed list
X
X    o String and Character Manipulation Commands
X
X        cindex - return the indexed character from the specified string
X
X        clength - return the length of the specified string
X
X        crange - return a range of characters from the specified string
X
X        csubstr - return a range of character from a string a different way
X
X        ctype - determine if string has various characteristics
X
X        replicate - replicate string a number of times
X
X        translit - translate characters in a string like the "tr" command
X
X    o Procedures in the Tcl Library
X
X        assign_fields - assign successive elements in lists to variables
X
X        edprocs - call editor on named, or all, procedures
X
X        for_array_keys - do a foreach-style loop on each key in an array
X
X        for_file - do a foreach-style loop on each line in a file
X
X        for_recursive_glob - perform a foreach-style loop on each file
X                and directory that matches one or more patterns
X
X        intersect - return the logical intersection of two lists
X
X        intersect3 - return the intersection of two lists, with remainders
X
X        pushd/popd/dirs - Cshell-style directory stack routines
X
X        read_file - read in a file to a string
X
X        recursive_glob - do filename globbing, recursively descending
X                all matched directories
X
X        lrmdups - sort a list and remove duplicate elements
X
X        saveprocs - save the definitions of named, or all, procedures
X
X        showproc - lists the definition of the named procedure
X
X        showprocs - list the definition of the named procedures, or all
X
X        union - return the logical union of two lists
X
X        write_file - write the specified string to the specified file
X
X
XON-LINE HELP
X============
X
XThere is a help system included with Extended Tcl.  It contains some
Xdocumentation on every command in Berkeley Tcl, and Extended Tcl.  You
Xcan invoke it interactively from within Extended Tcl by typing "help".
X
XOnce you bring Tcl up and have gotten it to pass all the tests, try
Xtyping "help help" to learn how to use help.
X
X
XMANUAL PAGES
X============
X
XMan pages in nroff/troff format are provided for all of Tcl and the
Xextensions.  These are in the "tcl6.1/doc" and "extended/man"
Xdirectories.  Of greatest importance are Berkeley Tcl's
Xtcl6.1/doc/Tcl.man, and Extended Tcl's TclX.man and TclShell.man,
Xlocated in the extended/man directory.
X
XAn ASCII version of a paper that John Ousterhout presented at the
XWinter '90 Usenix conference is also included.  It contains an
Xoverview of Tcl, the rationale for creating a new embeddable
Xprogramming language rather than using an existing one, speculations
Xon future uses and so forth.  This file is usenix.text in the
Xtcl6.1/doc directory.
X
X
XEXTENDED TCL VERSION NAMING
X===========================
X
XExtended Tcl takes its version number from the corresponding version
Xof Berkeley (Ousterhout) Tcl upon which it is based, with the addition
Xof a trailing letter in case there are multiple releases of Extended
XTcl within a single release of baseline Tcl.
X
XFor example, the first release of Extended Tcl for Tcl 6.1 is called
XExtended Tcl 6.1a.
X
X
XC PROGRAMMERS CAN USE THIS PACKAGE TO BUILD TCL INTO THEIR APPLICATIONS, TOO
X============================================================================
X
XAs an embeddable interpreter, Tcl offers a powerful, plug-in-and-go
Xprogramming language that saves the programmer who needs to provide
Xprogrammability in an application from having to design and implement
Xhis or her own.  Tcl provides a better and more complete language than
Xmost programmers have the time or inclination to write, and could
Xreduce the all-too-common proliferation of similar-but-incompatible
Xembedded programming languages.
X
XIn addition to the Tcl programming environment for Unix, this release
Xalso provides C and C++ programmers with everything they need to embed
Xthe Tcl programming language into an existing application or to build
Xa new application and include Tcl within it.  C and C++ programmers
X(and people programming in languages from which they can make
XC-compatible calls for that matter) can link against the tcl.a
Xlibrary, which this package should produce when you get it built
Xsuccessfully, to include all of the baseline capabilities, plus any of
Xour extensions that they like, plus any application-specific
Xextensions they add themselves to produce a package with a significant
Xruntime programmability.
X
XWe have found that including Tcl into large programs provides a good
Xway to decouple the bulk of the application from the user interface,
Xallows sophisticated users to write programs to control the application,
Xshortens turnaround time during development, makes many debugging tasks
Xeasier, and allows you to code tricky data processing tasks in just a
Xfew lines of Tcl.
X
X
XINTERFACING TCL AND C++
X=======================
X
XC++ programmers can include the file "tcl++.h" to define C++ classes
Xthat can be used to access a Tcl interpreter.  This is based on Tcl
XC++ classes originally developed by Parag Patel.
X
X
XTCL DIRECTORY HIERARCHY
X=======================
X
XHere is an overview of the directory hierarchy:
X
X                              top_level_directory
X
X             tcl6.1                                 extended
X
X    compat doc library test       man ossupport src tcllib tclsrc tests ucbsrc
X
X                                                     help
X
XThe subdirectories of the tcl6.1 directory contain Berkeley Tcl,
Xunmodified.  Note that tcl6.1 is just a suggested name; you can
Xcall the directory anything you want, by changing one line in
Xextended/Makefile, as long as the directory is parallel to the
X"extended" directory.
X
XWithin the tcl6.1 directory is the README file, the config program,
Xmakefile and all of the C source files and include files.  The
X"compat" directory contains implementations for routines that may
Xnot be present on all unix systems.
X
XThe "doc" directory contains all of the manual pages for baseline Tcl
Xin nroff/troff format, plus the text of the Usenix paper.
X
X"library" includes various Tcl procedures defined in baseline Tcl.
X
XFinally, "test" contains all of the tests for baseline Tcl.
X
XWithin the "extended" directory, the "man" directory contains all of
Xthe manpages for Extended Tcl, "ossupport" contains routines that
XExtended Tcl needs that may not be present on all systems, and "src"
Xcontains all of the C source and include files comprising the
XTcl extensions.
X
XThe "tcllib" directory contains several demo programs for Extended
XTcl, and the Tcl procedure library and index are built here.  Also
Xthe "help" subdirectory contains all of the help files.
X
XThe "tclsrc" directory contains the Tcl source files that are
Xconcatenated to create the Tcl procedure library, and the "tests"
Xdirectory contains the tests for Extended Tcl.
X
XFinally, the "ucbsrc" directory contains a replacement for the
Xbaseline version of tclBasic.c.  This was necessary because a
Xcouple of small changes needed to be made to tclBasic.c to support
Xthe signal processing of Extended Tcl.
X
X
XHOW TO BUILD IT
X===============
X
XPlease read TclX.man and TclShell.man in the extended/man directory
Xbefore starting the engine or working under the hood.
X
XCreate a directory that you want to create Tcl and Extended Tcl in,
Xcd to that directory and unpack tcl6.1.tar.Z by doing a
X"compress -dc tcl6.1.tar.Z | tar xvf -" or equivalent.
X
XIf you got tcl6.1 from the comp.sources.misc newsgroup, create the
Xbuild directory and unshar all of the parts of Tcl 6.1 there.
X
XTo configure Tcl 6.1 for your machine, do a "csh config" to run the
Xconfigure script.  This script determines things about the version
Xof Unix you're using, looks for routines that aren't present in all
Xversions, and configures the Makefile to use public domain equivalents
Xthat are included with the release.  (Eventually we would like to
Xreplace this with a configure script generated by Larry Wall's
X"metaconfig" program.  Anyone, please feel free to help out on this.)
X
XNext do a "make".  If all goes well, this will create a library,
Xtcl.a, which contains the core functions of the Tcl 6.1 interpreter.
X
XIn the next step, we will  build and install Extended Tcl.
X
XFirst, "cd" back to the top-level directory you've created to build
XTcl and Extended Tcl in, and unpack tclX6.1.tar.Z by doing a
X"compress -dc tclx6.1.tar.Z | tar xvf -" or equivalent.
X
XAgain, if you got Extended Tcl from the comp.sources.misc newsgroup,
Xunshar all of the parts of Tcl 6.1 while your current directory is
Xset to the build directory you created earlier.
X
XNext, "cd" to the "extended" directory which was created by untaring
Xor unsharing extended Tcl, and edit the Makefile, commenting in
Xthe configuration lines for your version of Unix, be it System V/3.2.0,
XSystem V/3.2.2 or SCO Unix, Berkeley BSD, Sun OS, Xenix, or HPUX.
X
XThen do a "make".  If all goes well, this will augment the tcl.a
Xlibrary will all of the functions defined by Extended Tcl, and
Xcreate an executable version of tcl in the "extended" directory called,
Xsimply enough, "tcl".
X
XNext fire up "tcl" and, if everything worked, you should be greated
Xby a tcl prompt:
X
Xtcl>
X
XCongratulations, you have successfully built Tcl.
X
X
XRUN TESTS TO INSURE THAT TCL IS WORKING PROPERLY
X================================================
X
XTcl comes with over 1400 tests that you can run to insure that it
Xis working properly.  These tests have greatly helped us while
Xworking on Tcl by detecting bugs that get introduced accidentally
Xas side-effects of changes.  Consequently, we have found Tcl
Xto be very reliable, and have had very few cases where a new
Xrelease has regressed by introducing new bugs in old functions,
Xor reintroducing old bugs in old fucntions.
X
XThere are two sets of tests:  tests for the Tcl baseline,
Xand tests for extended Tcl, which test both the new commands
Xadded by Extended Tcl and the procedures defined in the Tcl
Xprocedure library.
X
XFirst, run the tests for baseline Tcl.  After firing up Tcl,
Xcd to the baseline tests directory, "cd ../tcl6.1/tests" and
Xdo a "source all".  Tcl will print the names of the test
Xfiles as it executes them, and it will report the test number
Xof any test that fails, along with what the test expected and
Xwhat it actually got.
X
XIf a test fails, please dig into the test and the C source for
Xthe function being tested, fix the bug and mail us the change.
XIf you're not inclined to do this, please report the problem,
Xincluding the output of the test, to [e-mail]
Xor [e-mail].
X
XAfter your build of Tcl has successfully passed the baseline
Xtests, you are ready to run the tests of the functions in
XExtended Tcl.  Exit tcl by entering a control-D at the command
Xprompt, or issue the "exit" command.  Then restart Tcl and cd
Xto the "tests" directory (extended/tests).  Now do another
X"source all" command.
X
XOnce all of the tests have been passed, your build of Tcl has
Xbeen validated as much as possible, and you are ready to beging
Xwriting and using Tcl programs.
X
XIf you're having trouble with the baseline tests, and you suspect
Xthat the extensions might be involved, you can build a special
Xminimal version of baseline Tcl by cd'ing to the tcl6.1
Xdirectory and doing a "make tclTest".  You can then invoke
X"tclTest", where you should be greeted by a "%" prompt.  Next,
Xcd to the tests directory and do a "source all".
X
XNote that the baseline tests turn off tcl's ability to autoload
Xprocedures from the Tcl source library, so after running the
Xtests, you should usually exit Tcl and restart it.
X
X
XINSTALLING EXTENDED TCL
X=======================
X
XTo install Extended Tcl, edit the extended/Makefile installation configuration
Xsection to match your preferences. Read the information in the Makefile
Xcarefully before configuring it. Cd to the extended directory and do a
X"make install".
X
X
XMAKING EXECUTABLE TCL SCRIPTS
X=============================
X
XIt is common to want to write Tcl scripts, put them in a directory
Xalong your search path, and execute them just like you do with
Xshell scripts.
X
XOn systems that support the "#!" convention, you can put a
X
X#!/usr/local/bin/tcl
X
Xas the first line of your script, and executing the script will
Xautomatically invoke tcl to process it.  Of course if you install
XTcl somewhere else, you'll use a different path.
X
XFor systems that don't support this convention (most System V
Xsystems, for example), it is probably best to create a shell
Xscript that does something like:
X
Xexec tcl commandfile.tcl
X
X
XPACKAGE LIBRARIES
X=================
X
XPackage Libraries are a Tcl source code management tool included in
Xthis release.  Package libraries allow you to group Tcl procedures
Xinto logical bundles and create single files, libraries, that contain
Xmultiple packages.  The package code provides a low-overhead means of
Xautomatically demand-loading a package on the first attempt to execute
Xone of the procedures defined within it.  As such, package libraries
Xprovide a mechanism to accomodate the creation of Tcl applications and
Xlibraries of a substantial size.
X
XPackage iibraries are documented in detail in extended/man/TclShell.man.
X
X
XSUPPORT FOR EXTENDED TCL
X========================
X
XWe are committed to providing continuing support for Extended Tcl.
XPlease send questions, bug reports, and bug fixes to
[e-mail] (uupsi!sugar!tcl-project).
X
XIf you are unable to send electronic mail, please send surface
Xmail to:
X
X        NeoSoft
X        Attention: TCL Project
X        3918 Panorama
X        Missouri City, TX  77459
X        USA
X
XOr leave a note on our BBS at [phone]
X
X
XSEND US YOUR LIBRARY ROUTINES
X=============================
X
XIf you write a useful Tcl procedure and would like to share it with
Xeveryone, send us a copy and we'll include it in the Tcl library!
X
X
XCAVEATS
X=======
X
XAlthough Tcl compiles and executes the tests properly on Intel/Bell
XTech System V/3.2.0, SCO Unix System V/3.2.2, Xenix System V/386
Xand SunOS, it has not had much use under Xenix System V/386 or SunOS.
X
XPrevious versions of Extended Tcl have also run under Berkeley BSD,
XHP-UX and Xenix/286.  This release, however, has not been tested
Xon these machines, although there is configuration information in
Xthe makefile for BSD and HP-UX, and Extended Tcl should come up
Xfairly easily on these machines.
X
XInstallation, performed by doing a "make install" in the "extended"
Xdirectory, has not be heavily tested, either.
X
XDo not create any set-user-id versions of Tcl yet.  There are holes in
Xthe startup sequence involving shell variables and default files that need
Xto be plugged first.
X
X
XMAILING LISTS AND NEWSGROUPS FOR TCL
X====================================
X
XThere are two mailing lists dedicated to Tcl.  To subscribe to a
Xmailing list about Tcl and the Tk toolkit, send mail to
[e-mail].  To subscribe to a mailing list about
XExtended Tcl, send mail to [e-mail].
X
XAs of the time of this writing (Nov 8th, '91), the discussion period
Xhas nearly completed and a call for votes is about to be issued for a
Xnew Usenet newsgroup, comp.lang.tcl.  Unless serious opposition occurs
X(and this isn't anticipated), the newsgroup should be created around
Xthe middle of December.  It is expected that, should the newsgroup be
Xcreated, discussion will shift from the mailing lists to the
Xnewsgroup.  The newsgroup will be gatewayed to a mailing list for
Xthose unable to receive the newsgroup.
X
X
XACKNOWLEDGEMENTS
X================
X
XWe'd like to thank John Ousterhout for challenging and thrilling us
Xwith the creation and release of Tcl, and his close support and
Xinteraction the last seven months as we all worked toward this major
Xnew release.
X
XThanks also to everyone who acquired Tcl and Extended Tcl from the net
Xand gave us feedback in terms of bug fixes, suggested enhancements and
Xaccolades.  It's very energizing to know that something you've worked
Xon is being used.
X
XMark and Karl would like to thank all their friends for being their
Xfriends.  The check is in the mail.
X
X
XWHERE TO GET IT
X===============
X
XTcl 6.1 and Extended Tcl 6.1a were posted to the comp.sources.misc
Xnewsgroup.  Any site that archives comp.sources.misc should have it.
X
XTcl 6.1 and Extended Tcl 6.1a can be downloaded by anonymous UUCP
Xfrom Sugar Land Unix and Grizzly's Osprey.  Add one of these lines
Xto your Systems file:
X
X    sugar Any ACU 2400 1-713-684-5900 in:--in: nuucp word: ""
X    sugar Any ACU 19200 1-713-684-5928 in:--in: nuucp word: ""
X
X    osprey Any ACU 2400 1-408-427-1398 in:--in: nuucp word: ""
X    osprey Any ACU 19200 1-408-427-1398 in:--in: nuucp word: ""
X
X(The second lines are for people with V.32/V.42bis or Telebit PEP-capable
X modems)
X
XYou may also have to add one of the following lines to your Permissions
Xfile:
X
X    LOGNAME=sugar MACHINE=osprey REQUEST=yes
X    LOGNAME=osprey MACHINE=osprey REQUEST=yes
X
XThen enter a uucp command:
X
X    uucp sugar!/usr/spool/anon-uucp/tcl6.1.tar.Z your_machine!~
X
X...to download Tcl 6.1, and...
X
X    uucp sugar!/usr/spool/anon-uucp/tcl6.1Xa.tar.Z your_machine!~
X
X...to download Extended Tcl 6.1a.
X
XFor downloading from osprey:
X    uucp osprey!/usr/spool/anon-uucp/tcl6.1.tar.Z your_machine!~
X    uucp osprey!/usr/spool/anon-uucp/tcl6.1Xa.tar.Z your_machine!~
X
X
XCONVERTING FROM EXTENDED TCL 4.0 TO EXTENDED TCL 6.1a
X=====================================================
X
XHere are the things to look out for, and change:
X
XMost list-oriented commands now begin with "l".  Consequently, "index"
Xbecomes "lindex", "range" becomes "lrange", "empty" becomes "lempty",
X"length" becomes "llength", and "sortlist" becomes "lsort".
X
XThe "replace" command is now "lvarpop"; a new command, "lreplace" has
Xmuch of the functionality of "replace", but works on the contents of a
Xlist, returning a new list, rather than working on a variable name
Xcontaining a list, as lvarpop now does.
X
XCommand parameter ordering has been changed for "file", "split", and
X"join".
X
XThe "chars" options to "index", "range", and so forth, have been
Xremoved.  The "string" command has several new suboptions, "index",
X"length" and "range" to name a few.
X
XThe "uppercase" and "lowercase" commands have been replaced by "string
Xtoupper" and "string tolower".
X
XThe "trim_string", "trim_left" and "trim_right" commands have been
Xreplaced by "string trim", "string trimleft" and "string trimright".
X
XIn Extended Tcl 4.0 the "gets" command returned "1" if the read
Xsucceeded, and "0" on end of file.  Dr. Ousterhout decided, in his
Ximplementation, to have "gets" return the number of bytes read, or
X"-1" on end of file.  This can lead to subtle bugs in porting
XExtended Tcl 4.0 programs to 6.1a, causing while...gets loops
Xto return early or to not return at all.  The change requires that
Xstatements along the line of "while {[gets $fp line]} {..."  be
Xmodified to read "while {[gets $fp line] >= 0} {...".
X
XFor developers of Tcl extensions in C, the routines "Tcl_RetError" and
X"Tcl_RetUnixError" have been removed.  They were unsafe, anyway,
Xbecause they rendered into a static buffer, which could result in
Xoverflows which, although usually detected in software, could
Xnonetheless crash Tcl in unanticipated ways.  Developers should now
Xuse the "Tcl_AppendResult" call, and return TCL_ERROR explicitly.
X
XFor more details on changes in Tcl 6.1, examine the file "changes" in
Xthe tcl6.1 subdirectory.
X
X
END_OF_FILE
if test 24101 -ne `wc -c <'extended/README.EXTD'`; then
    echo shar: \"'extended/README.EXTD'\" unpacked with wrong size!
fi
# end of 'extended/README.EXTD'
fi
if test -f 'extended/man/TclShell.man' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'extended/man/TclShell.man'\"
else
echo shar: Extracting \"'extended/man/TclShell.man'\" \(20766 characters\)
sed "s/^X//" >'extended/man/TclShell.man' <<'END_OF_FILE'
X.TH TCLSHELL TCL "" "Tcl"
X.ad b
X'@index: tclshell
X.SH NAME
XTcl - Tcl interactive shell.
X.SH SYNOPSIS
X.br
X.B tcl [-q] [[-f] \fIscript\fB]|[-c \fIcommand\fB] [\fIargs\fR]
X
X.SH DESCRIPTION
X.PP
X'@help: tclshell/intro
X'@brief: Introduction to the tcl shell.
X.B tcl [-q] [[-f] \fIscript\fB]|[-c \fIcommand\fB] [\fIargs\fR]
X.PP
X\fBTcl\fR starts the interactive Tcl command interpreter.  The Tcl shell
Xprovides an environment for writing, debugging and executing Tcl scripts.  The
Xfunctionality of the Tcl shell can also be obtained in any Tcl-based
Xapplication.
X.PP
XThe \fBtcl\fR command, issued without any arguments,
Xinvokes an interactive Tcl shell.
XIf \fIscript\fR is specified, then the script is executed noninteractively
Xwith \fIargs\fR being supplied in the Tcl variable `\fBargv\fR'.  If
X\fIcommand\fR is supplied, then this command (or series of commands,
Xseparated by `;') is executed, with `\fBargv\fR' containing \fIargs\fR.
X.P
XThe Tcl shell is intended as an environment for Tcl program development and
Xexecution.  While it is not a full-featured interactive shell, it provides a
Xcomfortable environment for the interactive development of Tcl code.  Note
Xthat the package library code described here overrides the \fBunknown\fR
Xcommand provided as part of the standard Berkeley Tcl library facility,
Xalthough Tcl source libraries coded to that standard can be loaded and used by
XExtended Tcl.
X'@endhelp
X'
X.SH "INITIALIZATION SEQUENCE"
X'@help: tclshell/initialize
X'@brief: Tcl shell initialization sequence.
X.PP
XThe standard Tcl shell initialization consists of the following steps:
X.IP
XSearch for a default file.  The default file is a Tcl script that is executed
Xto set important Tcl variables that govern startup, such as \fBTCLPATH\fR.
XThe Tcl default file is searched for using the following
Xalgorithm:  The current Extended Tcl version, represented by $ver, is included
Xin the default file naming to allow multiple Tcl versions to exists on a
Xsystem.  Note that the Extended Tcl version is the standard Tcl version number
Xwith an alphabetic character added to indicated the version of Extended Tcl.
XThe \fBinfox version\fR command will return this version number.
X.sp
X.RS 10
X- An environment variable, \fBTCLDEFAULT\fR, is checked for.  If present,
Xit is used as the name of the
Xdefault file.
X.sp
X- A file, \fBTCLDEFAULT\fR, is looked for in the current directory.
X.sp
X- A global default file with is usually either \fB/etc/default/tcl$ver\fR or
X\fB/usr/local/lib/tcldefault$ver\fR.  (Tcl may be compiled to use a different
Xdirectory on some systems).
X.RE
X.IP
XFirst, \fBTcl\fR executes the default file.  This file normally sets at
Xleast two Tcl variables:
X\fBTCLPATH\fR, which contains a list of directories that contain tcl source
Xfiles, and \fBTCLINIT\fR, the
Xfull pathname of the Tcl source file that performs Tcl initialization.
XOther site-specific variables may also be set in
Xthis file.
X.IP
XNext, \fBtcl\fR executes the initialization file specified by the Tcl
Xvariable \fBTCLINIT\fR.
XThis is normally the \fBTclInit.Tcl\fR file distributed with Tcl.  This
Xfile defines the Tcl environment, including standard Tcl procs and variables.
X'@endhelp
X'
X.SH FLAGS
X'@help: tclshell/flags
X'@brief: Tcl shell command line flags.
X.TP
X.B \-q
XQuick initialization flag.  If this flag is set the only initialization step
Xperformed is to locate the Tcl default file and save its name in the Tcl
Xvariable TCLDEFAULT.  The file is not evaluated nor is the TclInit.tcl file.
XThis provides for a faster start up, but does not make any of the standard
XTcl procedures and facilities available.
X.TP
X.B \-f
XTake the next argument as a Tcl script to source rather than enter interactive
Xmode.  The \fB-f\fR flag is optional.  Normally the first argument that does
Xnot start with a `-' is taken as the script to execute unless the `-c' option
Xis specified.  All following arguments are passed to the script in \fBargv\fR,
Xthus any other Tcl shell flags must precede this option.
X.TP
X.B \-c
XTake the next argument as a Tcl command to execute.  It may be series of
Xcommands to execute, separated by `;'.  All following arguments are passed in
X\fBargv\fR, thus any other Tcl shell flags must precede this option.
X.TP
X.B \-\-
XMark the end of the arguments to the Tcl shell. All arguments following this
Xare passed in the Tcl variable \fBargv\fR.  This is useful to pass arguments
Xwithout attempting to execute a Tcl script.
X'@endhelp
X'
X.SH "TCLINIT FILE"
X'@help: tclshell/tclinit
X'@brief: Tcl shell initialization file.
X.PP
XThe Tcl initialization file, normally \fITclInit.tcl\fR in the main Tcl script
Xdirectory, initializes the Tcl shell.  It defines various Tcl procedures
Xthat are required to implement loading of Tcl source from libraries via the
Xpackage libraries and autoload facilities.
X.PP
XIf the Tcl is invoked interactively, it will source a \fI.tclrc\fR in the
Xuser's home directory, if it exists.  Tcl is viewed primarly as a programming
Xlanguage, not an interactive shell, so the \fI.tclrc\fR is intended for use for
Xloading development utilities, not to support programs, which should not rely
Xon the user's environment.
X'
X'@endhelp
X'
X.SH VARIABLES
X'@help: tclshell/variables
X'@brief: Tcl shell variables.
X.PP
XThe following variables are set and/or used by the Tcl shell.
X.TP
X.B argv
XA list containing the arguments passed in from the command line, excluding
Xarguments used by the Tcl shell.  The first element is the first passed
Xargument, not the program name.
X.TP
X.B interactiveSession
XSet to \fB1\fR if Tcl shell is invoked interactively, or \fB0\fR if the
XTcl shell is directly
Xexecuting a script.
X.TP
X.B noAutoExec
XIf this variable exists and has a value of \fB1\fR, then the Tcl shell will not
Xattempt to exec an non-existent command as a shell command.
X.TP
X.B programName
XThe name that the Tcl shell is executing as.  All directory
Xcomponents are removed from the program name.
X.TP
X.B scriptName
XThe name of the script that the Tcl shell is executing if the script was
Xinvoked on the command line.
X.TP
X.B TCLDEFAULT
XName of the default file that was used to locate all other files used by the
XTcl shell.
X.TP
X.B TCLENV
XArray that contains information used internally by various Tcl procedures that
Xare part of the Tcl shell.
X.TP
X.B TCLENV(topLevelPromptHook)
XContains code to run to generate the prompt used when interactively prompting
Xfor commands.  The code in this hook will be evaluated and the result will be
Xused for the prompt.
X.TP
X.B TCLENV(downLevelPromptHook)
XContains code to run to generate the prompt used when interactively prompting
Xfor continuation of an incomplete command.  The code in this hook
Xwill be evaluated and the result will be used for the prompt
X.TP
X.B TCLINIT
XThe name of the file that initializes, and does startup processing of,
XTcl.
X.TP
X.B TCLPATH
XPath to search to locate Tcl scripts.  Used by the \fBload\fR and
X\fBdemand_load\fR procedures.
X'@endhelp
X'
X.SH "HELP FACILITY"
X'@help: help
X'@brief: Tcl shell help facility.
X.PP
XThe help facility allows for display of help files extracted from
Xthe standard Tcl manual pages and Tcl scripts.  Help files are structured in a
Xmultilevel directory tree of subjects and help files.  The
Xfollowing commands and options are provided with the help package:
X.TP
X.B help
X.br
XHelp, without arguments, lists of all the top-level help subject
Xdirectories and files.
X.TP
X.B help \fIsubjectdir\fR
XDisplays all of help files and lower level subject files (if any exist) under
Xthe directory \fIsubjectdir\fR.
X.TP
X.B help \fIsubjectdir/helpfile\fR
XDisplay the specified help file.  The help output is passed through a simple
Xpager if output exceeds 23 lines, pausing waiting for a return to be entered.
XIf any other character is entered, the output is terminated.
X.TP
X.B helpcd [\fIsubjectdir\fR]
XChange the current subject directory, which is much like the Unix current
Xdirectory.  This directory can be changed with the \fBhelpcd\fR command.  If
X\fIsubjectdir\fR is not specified, return to the top-level of the help tree.
XHelp path names may also include ``..'' elements.
X.TP
X.B helppwd
XDisplays the current help subject directory.
X.TP
X.B help help | ?
XDisplays help on the help facility at any directory level.
X.TP
X.B apropos \fIpattern\fR
XThis command locates subjects by searching their one-line descriptions for a
Xpattern.  \fRApropos\fR is useful when you can remember part of the name or
Xdescription of a command, and want to search through the one-line summaries
Xfor matching lines.  Full regular expressions may be specified (see
Xthe \fBregexp\fR command).
X'@endhelp
X'
X.SH "COMMAND RESULTS"
X'@help: tclshell/results
X'@brief: Tcl shell command result processsing.
X.PP
XThe string result of a command typed at the Tcl shell command prompt is
Xnormally echoed back to the user.  If an error occurs, then the string result
Xis displayed, along with the error message.  The error message will be
Xpreceded by the string ``Error:''.
X.PP
XThe \fBset\fR command is a special case.  If the command is called to set
Xa variable (i.e. with two arguments), then the result will not be echoed.
XIf only one argument, the name of a variable, is supplied to \fBset\fR, then
Xthe result will be echoed.
X'@endhelp
X'
X.SH "EXECUTION OF UNIX COMMANDS"
X'@help: tclshell/unixcommands
X'@brief: Tcl shell Unix command execution.
X.PP
XIf an unknown Tcl command is entered from the command line, then the Unix
Xcommand path, specified in the environment variable \fBPATH\fR,
Xwill be searched for a command of the same name.
XIf found, the command will be executed.
XThis feature is provided to enhance the interactive environment for developing
XTcl scripts. This is only supported from the command line, not in script files
Xor in procedures, to eliminate confusion.  The \fBexec\fR or \fBsystem\fR
Xcommand should be used to run Unix commands inside scripts.
X'@endhelp
X'
X.SH "TCL SHELL PROCEDURES"
X.PP
XThe follow additional procedures are defined by the Tcl shell and may be
Xgenerally useful:
X.TP
X'@help: tclshell/load
X'@brief: Search the TCLPATH for a file to source.
X.B load \fIfile\fR
XSource a file, as with the source command, except search the TCLPATH for
Xthe file.
X'@endhelp
X.TP
X'@help: tclshell/utilprocs
X'@brief: Search a path list for a file.
X.B searchpath \fIpath file\fR
XSearch all directories in the specified path, which is a Tcl list, for the
Xspecified file.  Returns the full path name of the file, or an empty string
Xif the file is not found.
X'@endhelp
X'
X.SH AUTOLOAD
X'@help: tclshell/autoload
X'@brief: Autoloading of commands.
X.PP
X.B autoload \fIfile proc1\fR [..\fIprocN\fR]
X.sp
XThe \fIautoload\fR procedure, defined in \fBTclInit.tcl\fR, allows the Tcl
Xprogrammer to name one or more procedures and the file they are defined in.
XAfter \fIautoload\fR has been executed to inform Tcl of the presence of them,
Xa subsequent attempt to execute one of the procedures will cause the
Xcorresponding file to be loaded transparently prior to executing the function.
XFor example, executing:
X.IP
Xautoload showproc.tcl showproc showprocs
X.PP
Xtells Tcl to automatically load the file \fBshowproc.tcl\fR the first time
Xin the current session that either \fIshowproc\fR or \fIshowprocs\fR is
Xexecuted.
X'@endhelp
X'
X'@help: tclshell/packagelib
X'@brief: Tcl shell package libraries.
X.SH "PACKAGE LIBRARIES
X.PP
XPackage libraries work like \fIautoload\fR, except that a package library file
Xcan contain multiple independent Tcl packages.  A package is a collection
Xof related Tcl procedures.
X.PP
XThe package library file is just a regular Unix text file, editable with your
Xfavorite text editor, containing packages of Tcl source code. The package
Xlibrary must end in \fB.tlib\fR, an index file with the suffix \fB.tndx\fR
Xwill be built corresponding to the package library.  The start of a package
Xis delimited by:
X.IP
X.B #@package: \fIpackage_name proc1\fR [\fI..procN\fR]
X.PP
XThese lines must start in column one.
XEverything between the \fBpackage\fR keyword and
Xthe next \fBpackage\fR keyword, or the end of the file,
Xbecomes part of the named
Xpackage. The specified procedures, \fIproc1..procN\fR, are the entry points
Xof the package.  When a command named in a package command is executed and
Xdetected as an unknown command, all code in the specified package will be
Xsourced.  This
Xpackage should define all of the procedures named on the package line, define
Xany support procedures required by the package and do any package-specific
Xinitialization.
X.PP
XFor example, in a package source file, the presence of the following line:
X.IP
X\fB#@package: directory_stack pushd popd dirs\fR
X.PP
Xsays that the text lines following that line in the package file up
Xto the next \fIpackage\fR line or the end of the file is a package named
X\fBdirectory_stack\fR and that an attempt to execute either \fIpushd\fR,
X\fIpopd\fR or \fIdirs\fR when the routine is not already defined will cause
Xthe \fBdirectory_stack\fR portion of the package file to be loaded.
X'
X.SH PACKAGE INDEX FILES
X.PP
XA package library file has associated with it an index file
Xcalled a \fB.tndx\fR file.  The \fB.tndx\fR file contains the names
Xof the packages in the \fB.tlib\fR file, their addresses and lengths
Xwithin the \fB.tlib\fR file and the functions that are to cause the
Xdifferent packages to be autoloaded when an attempt is made to execute
Xthem.
X.PP
XThe first time Tcl tries to execute a procedure where the procedure doesn't
Xexist and isn't an autoload, Tcl will search along \fBTCLPATH\fR looking
Xfor any files ending in \fB.tlib\fR.  For each one it finds, it checks
Xto see if there is a corresponding file in the same directory ending
Xin \fB.tndx\fR.  If the \fB.tndx\fR file doesn't exist, or if its date
Xof last modification is older than that of the \fB.tlib\fR file,
Xthe \fB.tndx\fR is automatically (re)generated if possible.  If Tcl can't
Xregenerate the file (most likely due to file or directory permission
Xproblems), an error occurs.
X.PP
XDemand loading is also supported from indexes build by the \fBmkindex.tcl\fR
Xprogram, supplied with standard Tcl.  However, \fBinit.tcl\fR
Xis not loaded.  Note that the \fBinfo library\fR command is not used to locate
Xlibraries by this shell; the \fBTCLPATH\fR variable is set by the default file
Xand is used to locate the libraries.
X'@endhelp
X'
X.SH "PACKAGE MANAGEMENT COMMANDS"
X.PP
XSeveral commands are available for building and managing package libraries.
XIf you are not building package libraries and are using the standard Tcl
Xinitialization file, they are all transparent.  These commands are either
Xdefined or autoloaded by \fBTclInit.tcl\fR.
X.TP
X'@help: tclshell/autoprocs
X'@brief: List names of autload and package library procs.
X.B autoprocs
XLists the names of all known autoload and package library procedures.
X'@endhelp
X.TP
X'@help: tclshell/buildpackageindex
X'@brief: Build an index to a package library.
X.B buildpackageindex \fIlibfile\fR
XBuild an index for a package library.  The the \fIlibfile\fR name must end with
Xthe suffix \fB.tlib\fR.
X'@endhelp
X.TP
X'@help: tclshell/demand_load
X'@brief: Force an autoload proc or a package to be loaded.
X.B demand_load \fIprocname\fR
XAttempt to load the specified procedure, either as an autoload function or by
Xloading the package containing the procedure.  If the package indexes have not
Xbeen loaded for all package libraries in \fBTCLPATH\fR, they will be loaded.
XOut-of-date library indexes will be rebuilt if they are writable.  The
Xprocedure returns \fB1\fR if the procedure was sucessfully
Xloaded, or \fB0\fR if it was
Xnot.
X'@endhelp
X.TP
X'@help: tclshell/loadlibindex
X'@brief: Load the index of a package library
X.B loadlibindex \fIlibfile\fR
XLoad the package library index of the library file \fBlibfile\fR (which must
Xhave the suffix \fI.tlib\fR).  Package library indexes along the \fBTCLPATH\fR
Xare loaded automatically on the first demand_load; this command is provided to
Xexplicitly load libraries that are not in the path.  If the index file (with
Xa \fI.tndx\fR suffix)
Xdoes not exists or is out of date, it will be rebuilt if the user has
Xdirectory permissions to create it.
X'@endhelp
X.TP
X'@help: tclshell/packages
X'@brief: List all known packages.
X.B packages
XReturns a list of the names of all known packages.
X'@endhelp
X.TP
X'
X.SH "TCL SHELL INTERNAL STRUCTURE"
X.PP
XThis section discusses the internal structure of the standard Tcl
Xinitialization file and the facilities it implements.  This is intended
Xprimarily for developers who want to customize these facilities for their
Xapplications.
X'
X.SS "Autoload and Package Library Structures"
X.PP
XThe package library index consists of an entry for each package in the library,
Xwhere each entry
Xis a call to the \fBTCLSH:defpkg\fR procedure.  Loading of the package
Xindex is done with the \fBsource\fR command.
XThe \fIdefpackage\fR routine initializes elements of
Xthe \fBTCLENV\fR array which are used by \fBdemand_load\fR to locate and load
Xa package.  The \fBbuildpackageindex\fR procedure is contained in
X\fBpackages.tcl\fR.
X'
X.PP
XThe following elements of the \fBTCLENV\fR are used to implement the autoload
Xand package library facility.
X.TP
X\fBTCLENV(PROC:\fIprocName\fB)\fR
XEach procedure that is to be loaded by the \fBdemand_load\fR command has an
Xentry in this
Xarray, indexed by the concatenation of `PROC:' with the procedure name.
XIf the entry is for a package, it is a list consisting `P' followed by the
Xname of the package.  The package name must be looked up in the TCLENV array
Xto find the actual library file.  If the entry is for an autoload procedure,
Xit is a list consisting of 'F' followed by the name of the file to load.
X.TP
X\fBTCLENV(PKG:\fIpackageName\fB)\fR
XEach package has an entry in the array indexed by the concatenation of
X`PKG:' and the name of the package.  The entry is a list containing the
Xfull path to the library file, the byte offset in the file of the start of the
Xpackage, and the length of the package.
X.TP
X\fBTCLENV(packageIndexesLoaded)\fR
XA boolean that indicates if the package indexes have been loaded.  They will
Xnot be loaded until the first call to \fBdemand_load\fR.
X.TP
X\fBTCLENV(inUnknown)\fR
XIndicates if the \fBunknown\fR command is currently being executed.
XIt is used
Xto detect recursion in situations where an unknown command is found
Xduring unknown command processing.
X'
X.PP
XThe following procedures are used to implement the internals of the autoload
Xand package library facility, and are defined by \fBTclInit.tcl\fR:
X.TP
X\fBTCLSH:defpkg\fR \fIpkgname libfile offset len proc1\fR [..\fIprocN\fR]
XDefine a package for the current interpreter.  \fIPkgname\fR is the name
Xof the package to define, \fIlibfile\fR is the full path to the library file.
X\fIoffset\fR is the byte offset into the of the start of the package code;
X\fIlen\fR is the length of the package code, in bytes, and
X\fIproc1..procN\fR are the entry point procedures defined by the package.
XThis procedure is normally not called directly by the user or the
Xuser's script.  The library index files
Xconsists of calls to this procedure to define every package in a library.
X.TP
X\fBTCLSH:LoadOusterIndex dir\fR
XLoad an index file, \fIdir\fR/\fBtclIndex\fR, of the type built by John
XOusterhout's \fBmkindex.tcl\fR program (included with the standard Tcl
Xdistribution).  This style of index defines procedure names and the files that
Xcontain them.  It is a one-index-to-many-source-files structure. All of the
Xfiles pointed to by this must reside in \fIdir\fR.  The procedures in these
Xlibraries will be defined as if the autoload command had been used.
X.TP
X\fBTCLSH:LoadPackageIndexes\fR
XThis procedure searches the path defined by Tcl variable \fBTCLPATH\fR and
Xloads all of the indexes for all of the \fI.tlib\fR package libraries in the
Xpath.  If any of the indexes are older that their corresponding library file
Xor do not exist, then they will be rebuilt if the user has write access to the
Xdirectory.  Also all Ousterhout-style indexes found along the path will be
Xloaded.
X.TP
X\fBunknown\fR
XThis is the actual unknown command trap handler.  It will first do a
X\fBdemand_load\fR, loading the \fBunknown\fR command if it has been defined by
X\fBautoload\fR, or by a package library index.  The library indexes will be be
Xloaded if this is the first call to \fBunknown\fR.  If the command is not
Xfound by \fBdemand_load\fR, the Unix path (in the environment
Xvariable \fBPATH\fR,
Xwill be searched for the command.  If it is found, it will be executed via the
X\fBsystem\fR command, providing full shell (\fBsh\fR) command line expansion,
Xwith output going to standard out rather than being returned as the result of
Xthe command.  This binary path search will only occur if this is an
Xinteractive session running at the top level (i.e., not in a procedure or a
Xscript). This behavior can be disabled with the \fBnoAutoExec\fR variable.
X
END_OF_FILE
if test 20766 -ne `wc -c <'extended/man/TclShell.man'`; then
    echo shar: \"'extended/man/TclShell.man'\" unpacked with wrong size!
fi
# end of 'extended/man/TclShell.man'
fi
echo shar: End of archive 20 \(of 23\).
cp /dev/null ark20isdone
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 ; do
    if test ! -f ark${I}isdone ; then
    MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked all 23 archives.
    echo "Now cd to "extended", edit the makefile, then do a "make""
    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: [e-mail]
Sterling Software, IMD           UUCP:     uunet!sparky!kent
Phone:    [phone]         FAX:      [phone]
Please send comp.sources.misc-related mail to [e-mail].