- Tcl® - What is it?
- Tcl® - Where is it?
- Tcl® - How is it installed?
  - For use in the AlphaX text editor, the Wish shell, and other Tcl applications
- Tcl® - How is it used?
- Tcl® - How is it built?
- Tcl® - What's Changed?
  - Version 2.0.5 Ñ August 1, 2010
  - Version 2.0.4 Ñ March 19, 2009
  - Version 2.0.3 Ñ January 10, 2008
  - Version 2.0.2 Ñ July 9, 2007
  - Version 2.0.1 Ñ April 12, 2006
  - Version 2.0 Ñ July 26, 2004
  - Version 2.0b15 Ñ March 3, 2004
  - Version 2.0b14 Ñ June 22, 2003
  - Version 2.0b13 Ñ March 13, 2003
  - Version 2.0b12 Ñ February 21, 2003
  - Version 2.0b11 Ñ November 11, 2002
  - Version 2.0b10 Ñ September 9, 2002
  - Version 2.0b9 Ñ June 11, 2002
  - Version 2.0b8 Ñ October 24, 2000
  - Version 2.0b7 Ñ September 24, 2000
  - Version 2.0b6 Ñ August 24, 2000
  - Version 2.0b5 Ñ May 3, 2000
  - Version 2.0b4 Ñ January 5, 2000
  - Version 2.0b3 Ñ December 22, 1999
  - Version 2.0b2 Ñ December 20, 1999
  - Version 2.0b1 Ñ December 14, 1999
  - Version 1.0

# Tcl® - What is it?

Tcl® enables Tcl applications on the Macintosh to use AppleEvents for communication with other programs and for the AppleEvent Manager to communicate with Tcl applications. The nature of the MacOS (at least prior to MacOS X) makes it impossible to implement any meaningful `exec` command. Between agreeable applications, AppleEvents allow communication of anything that can be passed as an argument to a command-line application and much more. The key is to make the applications agreeable. Tcl® is an attempt to get Tcl to support its end of the bargain. Tcl® is complementary to Jim InghamÕs Tclapplescript.shlb (included in the Tcl distributions). Depending on your task and your relative familiarity with AppleScript and raw AppleEvents, you may find one tool or the other preferable.

Tcl® inherits directly from the AppleEvent facilities in the Alpha text editor, as written by Pete Keleher and Tim Endres. For many years, Alpha has used Jens AlfkeÕs AEGizmos to render the pathologically-typed binary data in AppleEvents into a Tcl-manageable string form. Unfortunately, while AEGizmos are reasonably easy for humans to read, they're not the most convenient format for a computer to interpret. Alpha programmers wishing to interact with other programs have generally applied regular expressions to these strings (with varying degrees of success), in order to extract the information they were interested in. Several years ago, I got tired of writing the same `regexp` expressions and sanity checks over and over, so I set out to write a complete AEGizmo parser. This parser, in one form or another, has been a part of Alpha for a few years.

While this Tcl-based AEGizmo parser works well, it can be incredibly slow. A while back, a small group of AlphaÕs users and I formed the Alpha Cabal to assume development tasks from AlphaÕs originator, Pete Keleher (Pete has irresponsibly decided to procreate and pursue tenure, rather than work on Alpha like heÕs supposed to). One of my prime interests was in improving AlphaÕs AppleEvent capabilities. After some initial efforts at speeding up the parser, my dain bramage cleared up and I set out to simply expose as much of the AppleEvent Manager API to Tcl as possible. By avoiding the parsing step, speedups of a hundred-fold are typical. As the project progressed, it became clear that this could be a useful tool for any Tcl-based program, so I generalized the shared library to work with any Tcl 8 installation, and Pete generously agreed to let me open-source what was left of his code. Many of the design decisions in Tcl® (see Memory Leaks) reflect the need to achieve (nearly) the same results with Alpha 7, Alpha 8, and Wish.

# Tcl® - Where is it?

You can download the latest version of Tcl® from SourceForge.

# Tcl® - How is it installed?

## For use in the AlphaX text editor, the Wish shell, and other Tcl applications

Place TclAE.shlb where Tcl can find it, such as in one of the directories of `$tcl_library` or in the same folder as the application.

Invoke the library by calling `package require tclAE`.

Ever since version 8, Alpha will not work properly if Tcl® is not installed.

Tcl® has been predominantly tested with Tcl 8.4. It may work with other versions, but certainly none before Tcl 8.0.

# Tcl® - How is it used?

- Sending AppleEvents
- Working with AppleEvent Descriptors
- Handling AppleEvents and Descriptor Coercion Requests
- Resolving and Creating Object Specifier Records
- Cheater's Guide to Writing AppleEvent Descriptors
- Archaic Commands
- Glossary

# Tcl® - How is it built?

Tcl® uses the Tcl Extension Architecture (TEA) and should build cleanly on recent Mac OS X machines (certainly works on Intel and PPC Tiger machines, and may build on older OSes). Xcode 2.4 is recommended; older than 2.2 won't work.

- `$ svn co http://tclae.svn.sourceforge.net/svnroot/tclae/trunk tclae`
- `$ mkdir -p build; cd build`
- `$ export CFLAGS='-Wno-deprecated-declarations -mmacosx-version-min=10.2 -arch ppc -arch i386'`
- `$ ../tclae/configure --libdir=/Library/Tcl`
- `$ make -j 2`
- `$ sudo make install`
- or, to install in an alternate directory, e.g. for packaging a distribution

  > `$ make install DESTDIR=`pwd`/../install/`

- `$ make test`
- Please tell me about any problems you encounter.

Although not a requirement of use, please send me any of your changes so that I can incorporate them.

# Tcl® - What's Changed?

## Version 2.0.5 Ñ August 1, 2010

- 64-bit support
- Removed deprecations

## Version 2.0.4 Ñ March 19, 2009

- `tclAE::build::alis` now coerces to `utxt` instead of `TEXT`
- Handled null OSType
- Fixes for `[tclAE::processes]` (see Alpha Bug 2362 and 2363)
- Option to bring launched application to front

## Version 2.0.3 Ñ January 10, 2008

- Fix for fatal incompatibility with Tcl 8.5
- Endian fixes for aetes from Bernard

## Version 2.0.2 Ñ July 9, 2007

- Added `[tclAE::remoteProcessResolverGetProcesses]`
- Intel fixes
- Updated tests
- Updated TEA

## Version 2.0.1 Ñ April 12, 2006

- Switched to building with TEA
- Initial fixes for Intel
- Bug 1217.

## Version 2.0 Ñ July 26, 2004

- It's been in production use for over four years; perhaps it's time to stop being a beta? (Fixes bug 1434)
- Fix for bug 1351.

## Version 2.0b15 Ñ March 3, 2004

- `[tclAE::send]` accepts AEAddresses.
- New commands `[tclAE::launch]` and `[tclAE::processes]`.
- Added more natural support for `typeUnicodeText` and `typeUTF8Text`.

## Version 2.0b14 Ñ June 22, 2003

- Fixed problem with [unknown] loading of coercion and event handlers
- [tclAE::send] returns intermediate errors to caller
- Some automatic treatment of POSIX <-> HFS path conversion
- Bug 907
- Bug 131

## Version 2.0b13 Ñ March 13, 2003

- New Tcl_Obj implementation of AEDescs
- Removed support for AESubDescs
- Removed AlphaTcl variant
- Updated tests

## Version 2.0b12 Ñ February 21, 2003

- December 2002 ProjectBuilder

## Version 2.0b11 Ñ November 11, 2002

- Move to Tcl 8.4, CONSTification, framework headers, PBX 2.0.1 & Jaguar, RAEL
- Bugs 555 & 563, tclAE fixes

## Version 2.0b10 Ñ September 9, 2002

- .tcl file encoding fixes
- Introduced AppleEvent transactions
- Created new AEAddress Tcl object type
- Added POSIX <-> HFS path converter
- Removed parseAppleEventsWithTcl flag
- Removed tclAE::target commands

## Version 2.0b9 Ñ June 11, 2002

- fixes for bugs 469, 530, 554
- Fix -q. Bug 183
- Flush intermediate errors. Bug 182
- OSX AEPrint fixes
- Explicit use of macRoman encoding when interacting with Carbon
- Test file OSX fixes
- Dissentagled Alpha and TclAE
- Support for AppleEvent Object Model
- Carbonization & Bugfixes

## Version 2.0b8 Ñ October 24, 2000

- Routines for generating and reading AppleEvent Terminology resources.
- Combine tclAE::setData and tclAE::setDescType into tclAE::replaceDescData. Better logic and needed for Carbon.
- More consistent treatment of Tcl and C implementations.

## Version 2.0b7 Ñ September 24, 2000

- First public release of shared library
- Major changes to the API
- Better consistency between `.tcl` and `.shlb` versions
- New documentation

## Version 2.0b6 Ñ August 24, 2000

## Version 2.0b5 Ñ May 3, 2000

## Version 2.0b4 Ñ January 5, 2000

- Further AlphaTcl speed improvements

## Version 2.0b3 Ñ December 22, 1999

- AlphaTcl installer fixes

## Version 2.0b2 Ñ December 20, 1999

- AlphaTcl speed improvements

## Version 2.0b1 Ñ December 14, 1999

- Complete rewrite of AlphaTcl code for compatibility with the hard-coded AE parsers in Alpha 8 (which are two to three orders of magnitude faster!).

## Version 1.0

- Assorted Tcl-only implementations for Alpha 7.x

Copyright © 1999Ð2007 Jonathan E. Guyer, Daniel Steffen, Peter J. Keleher and Tim Endres.
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of the authors nor the names of any contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Last modified Sunday, August 1, 2010 12:32:50 PM