Hackercorp - Hackercorp - Hackercorp - Hackercorp - Hackercorp - Hackercorp TCLREADME 3/15/90 --------- ------- This document is Copyright 1990 by Hackercorp. Permission to use, copy, modify, and distribute this documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies. Hackercorp makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. This is the alpha-2 distribution of Tcl and Tcla. Tcl stands for Tool Command Language, and was created by Dr. John Ousterhout of the University of California at Berkeley as a library package to be embedded in various tools (editors, debuggers, terminal emulators, etc) as the tool's command interpreter. Tcl provides a simple programming language, a set of built-in commands, and has a C interface that tools can use to add application-specific commands to the base set provided by Tcl. Tcla stands for Tool Command Language - Amiga, and it provides several commands (via the C interface) that have been added to Tcl to support Amigas, including support for CLI commands, windows, menus, resources, file requesters, alerts and message passing between Tcla programs. Tcla was created by Karl Lehenbauer of Hackercorp. This package contains both Tcl and Tcla, packaged as an Amiga shared library, tcla.library. Tcl in tcla.library is essentially original Tcl, with a small number of changes described below. Tcl is copyrighted by the University of California, but their copyright allows for reuse for any purpose, including commercial sale, subject to the restriction that the copyright and disclaimer messages must be included unmodified where present (i.e. in the source code). Likewise, Tcla is copyrighted by Hackercorp, but we also allow redistribution for any purpose subject to the same requirements regarding copyright and disclaimer messages. Tcl and Tcla have been compiled into an Amiga shared library, named tcla.library. The 'tcl' program, included with this Tcla release, can open tcla.library and make use of it to create Tcl interpreters and get them to evaluate Tcl commands, and to use the Tcla functions to interface with the supported Amiga interface routines, other Tcla programs, and C subroutines that you may decide to write and make callable from Tcl. tcla.library, in addition to providing the basic capabilities of Tcl, has additional support for many Amiga-specific functions, such as executing CLI commands and getting the result back as a string, opening and manipulating windows and processing window events, file requesters, alerts, support for menus (where menu entries you define from Tcl cause Tcl code to be executed when selected), define and interact with gadgets, and provides sharable Tcl-based handles to various application-specific data entities (resource banks). Further, all Tcla programs have the ability to send and receive Tcl commands to and from other Tcla programs. The tcl demo program, the one that calls tcla.library, should compile without trouble on Manx Aztec C 5.0a or later. A port of the demo program to Lattice should be dead easy -- the program is only a couple dozen lines long. The tcla.library was generated with Aztec C 5.0a, but should be callable by any programming language that can make use of .fd files. For programmers using Aztec C, include files with ANSI function prototypes and pragmas are included. They may need some massaging for use under Lattice. Changes in Tcl from Tcl as provided by John Ousterhout/Berkeley: o In original Tcl assigning an empty string to a variable caused that variable to cease to exist, resulting in an error when you tried to reference it. This broke all sorts of little Tcl programs that should have worked. Peter da Silva came up with changes to fix this, and Amiga Tcl incorporates this change. The changes been forwarded to John Ousterhout (they were minor) and he has agreed to adopt them. o As a positive side effect of the above change, Tcl procedures that can accept a variable number of arguments can now be called with no arguments. Previously if you defined a Tcl procedure as taking a variable number of arguments, it required that at least one argument be passed. This restriction was not true for C extensions, so now neither C extensions nor high-level Tcl procedures require an argument when the procedure expects a variable number of arguments. o ANSI function prototypes have been generated and are used to enable type-checking when compiling Tcl and Tcla. The tcl.h and tcla.h include files declare function prototypes for all C-callable Tcl and Tcla support routines to help insure their correct usage. o Original Tcl did not concern itself with running out of memory. This is understandable as it was developed and used on a virtual memory machine (VAX) running Unix. On the Amiga we have to be more careful, because running out of memory is not such an uncommon occurrence. A mechanism is provided for Tcl to call a programmer- specified routine if it is unable to allocate memory, so memory can be freed if possible. o The panic routine that comes with Berkeley Tcl is not included in the Tcl library. It has been replaced by an Amiga-specific routine that pops up a requester describing the problem, then does other Amiga-specific things. Programmers using the C interface can provide their own panic routine (both Tcl and Tcla library routines call panic when they encounter various unrecoverable conditions) or use the one that is included in the Tcla library (the default). The Tcl documentation consists of the Tcl manual and the Tcl C-interface routine docs. These files are available in the Unix nroff format, but for this release they have already been nroffed and run through col and strike to produce a straight ASCII-printable document. This file is tcl.man in the release. Tcla documentation is provided in the form of several .doc files. These are straight ASCII files at this time, although they will eventually probably be put into the nroff "man" format. Running The Demos ----------------- To run the demos, you need to put the tcl procedures (.tcl files) in a directory that has had an "assign tclprocs:" done on it. Then, cd to that directory, and do a "tcl -f hello.tcl" or a "tcl" followed by "source hello.tcl", "source demo.tcl", etc. To execute from the Tcl command prompt, enter a control-\, which is the Amiga end-of-file. The demos assume that you have a program, more, which takes a filename and displays the contents of the file, and a command, lc, which lists the files in a directory. I hope to acquire PD versions of these programs and include them in future releases. Also, demo.tcl requires ruby.font in the 15 pixel height. Indidentally, hello.tcl can use an alternate font that's specified on the command line. For example, tcl -f hello.tcl ruby.font 15 will cause hello world to be displayed using the 15-pixel-high ruby font. If you resize the window, "Hello, World." will be redisplayed within the window drawing area. Known Bugs In Alpha-2 Release ----------------------------- There is a file, bugs, within the release that details known bugs. Miscellaneous Ruminations ------------------------- The library will probably grow on the whole, rather than shrink, as new capabilities are added. However, with the planned support for attaching additional specially-prepared shared libraries from within tcl to install a set of commands into your Tcl interpreter, the tcl library will probably shrink and a second library will be created to support all of the Intuition functions. Manx 5.0a optimizer really shrinks the code. The library size shrinks by 16K bytes when compiled with optimization. A bunch of the file requester code will eventually go away. Reporting Bug Fixes And Distributing Changes -------------------------------------------- PLEASE DO NOT GENERALLY DISTRIBUTE CODE OR PACKAGES BASED ON ANY ALPHA OR BETA RELEASE OF TCLA. WE DO NOT WANT TO HAVE TO MAINTAIN BACKWARD COMPATIBILITY TO THE MANY BRAIN-DAMAGED ASPECTS OF ALPHA AND/OR BETA RELEASES. Please report bug fixes back to Hackercorp so that we may include them in future releases. Regards, Karl Lehenbauer @ The Hacker's Haven -- Hackercorp "We Are Enthusiasts." 3918 Panorama Missouri City, TX 77459 Internet/BITNET: karl@sugar.hackercorp.com Usenet: uunet!sugar!karl