Tcl® - AppleEvents with Tcl

- Tcl® - What is it?
- Tcl® - Where is it?
- Tcl® - How is it installed?
  - For use in version 8 of the Alpha 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 Ñ July 26, 2004
  - Version 2.0b15 Ñ February 28, 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 version 8 of the Alpha 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`.

Starting with 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?

The supplied TclAE.shlb is ready for use on PowerPC machines. The supplied CFM68k shared library is completely untested. I have nothing to run it on, so I welcome any user reports. Starting with version 1.1a4, Apple has incorporated AEGizmos in the CarbonLib SDK, so a build with that should be forthcoming.

If youÕd like to get a head-start on Carbon, fix whatever (if anything) is wrong with CFM68k, or if you'd like to make changes to the library, I've provided all of the sources in the :Build: directory, along with a CodeWarrior Pro 5 project file. If youÕd like to take a stab at building under MPW or with the OS X native tools, contact me for an XML export of the project file; IÕll help as much as I can and will be happy to include any resulting `makefiles` in future distributions.

- Obtain a full Tcl source distribution from the Tcl Developer Xchange and build at least TclLibraries.¹. Tcl® was originally built against Tcl 8.2, but all recent work has been with versions of Tcl 8.3. Earlier and later versions may work, but havenÕt been tested. The `Tcl_Obj` and binary facilities of Tcl 8 are a must.
- Obtain AEGizmos version 1.4.2 from Jens AlfkeÕs site.
- Obtain FindErrorLib from one of the Mac download archives and follow its installation instructions. This library is useful, but not necessary, so you can remove the appropriate `#define` from MW_TclAE.pch if you donÕt have the library. Many of the Tcl `.test` entries will fail because the error messages will be wrong, but Tcl® should still work properly in all other respects.
- Run the Build Shared Library AppleScript. This isnÕt strictly necessary, but it will automate the setting of Tcl®Õs source tree paths. When prompted for paths, just select the parent folder for the item requested; there's no need to choose a specific source or library folder within that folder.
- When you get a successful build and install message, try it out. There is a folder of Tcl `.test` scripts included with Tcl®. These tests work from either Alpha 8 or any of the Tcl 8 shells; they do not require Tk. I can provide a `.tcl` script that permits them to run under Alpha 7.
- 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 Ñ 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Ð2004 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 Monday, July 26, 2004 12:09:55 AM