Cocoa Scriptability in practice

Even taking into account all the complaints I may have about AppleScript as a language (in short: an advanced OO-concept covered under a thin veil of too few coercion handlers that still expose its strong typing, plus an English-like syntax that negates itself by allowing imperative sentences as subordinate clauses and objects), it is still the best way to remote-control your applications. This is mostly due to Apple Events, which are a solid and proven foundation for inter-application communication.

In addition, we have tools like Growl available, and Automator on the horizon with 10.4. Scriptability is becoming more and more interesting to application developers, especially if you're writing small tools that would benefit from Unix-style daisy-chaining to be combined with other apps. And finally, AppleScript is both documented on Apple's web site and available for Cocoa, with XML-based .scriptSuite and .scriptTerminology files replacing the 'aete' resource that required special tools or Rez wizardry.

So much for theory. In practice, the XML files aren't much easier to edit. The best bet right now is using a text editor (like SubEthaEdit), which makes it even more annoying than the Rez files of old. Property List Editor attempts to help with editing, but most of the time just disables the type popups due to a bug. Not to mention it still doesn't support copy & paste and keeps on moving items without taking along the selection. So, if you want to retain your sanity, use a text editor and optionally convert to the ASCII Property List format.

Update: I just heard about SdefEditor, an app that seems to fill the gap of providing an editor for these files. I haven't used it in earnest, but in a cursory test run it looked quite nice.

The docs are another sore point. Basically, they consist of lots of text that tells you how cool AppleScript is and contain so many cross-references you lose track too easily. Generally cross-references are a plus, but in this case it means that it's very hard to read through the docs sequentially in a sensible order.

There's also a number of tables that describe the contents and names of the various entries in the XML files. Sadly, those are sorely missing information on how these relate to each other. You can infer some of it from the names of the tables, but even the names aren't used consistently, and it's easy to miss one of the smaller tables that just tells you what kind of object to wrap another table's fields in.

Also, the samples aren't real-world samples like we had them in Inside Macintosh and other good examples of documentation. Rather, they are unnecessarily long excerpts from the dictionaries for Apple's built-in suites. They are needlessly complex, and since they come standard with the OS, won't be used by anyone but the people who want to replace standard behavior - by definition a minority. Where'd the good old SurfWriter samples go?

Anyway, right now the best way to generate an AppleScript suite is to just take a gander at one of a shipping application and use it as a reference when writing your own one. Mail.app, Adium and Colloquy were rather helpful in this regard. Here's a quick rundown on adding simple scripting support to your app. I'll especially focus on adding commands that aren't bound to any object here because the object-bound stuff is already as sample code on your hard disk and another sample is available at ScifiHifi.

The first thing to do is to turn on scriptability in your app's Info.plist by setting NSAppleScriptEnabled to YES.

On the page that documents this you'll also find info on getting some debugging info you may need later when things start going wrong, and a nice overview of all the techniques and tools available, and how this fits in with MVC.

The executive summary is basically: There are two files. The Suite Definition contains the actual associations of AppleEvents with messages in your Cocoa objects. The Suite Terminology contains the info AppleScript needs to translate from AS-commands to AppleEvents. And scripting stuff ideally goes in the model layer.

Once you've turned on scripting, create your Suite Definition and Terminology files. Pick a name for your suite (typically this will just be the name of your app, e.g. MyApp, MSWord, or whatever...), and use the .scriptSuite suffix for the definition and .scriptTerminology for the AppleScript-to-AppleEvents info.

Script Suite Definition

{
    "AppleEventCode" = "SfWr";    // Unique identifier for this suite.
    "Classes" = {};        // All your classes.
    "Commands" = {};        // Standalone commands.
    "Enumerations" = {};    // Constants.
    "Name" = "SurfWriter"; // Name of the suite (filename w/o suffix)
    "UsedFeatures" = ( "UnnamedArguments" );
}

{
    "AppleEventCode" = "SfWr";    // Unique identifier for this suite.
    "Classes" = {};        // All your classes.
    "Commands" =        // Standalone commands.
    {
        "DontPanic" =
        {
            "AppleEventClassCode" = "SfWr";
            "AppleEventCode" = "PNIK";
            "Arguments" = {};
            "UnnamedArgument" = {};
            "CommandClass" = "MyDontPanicCommand";
        };
    };
    "Enumerations" = {};    // Constants.
    "Name" = "SurfWriter"; // Name of the suite (filename w/o suffix)
    "UsedFeatures" = ( "UnnamedArguments" );}

"category" =
{
    "AppleEventCode" = "theC"
    "Optional" = NO
    "Type" = "NSString"
};

[[self evaluatedArguments] objectForKey: @"category"];

Script Terminology

{
    "Classes" = {};        // All your classes.
    "Commands" =           // Standalone commands.
    {
        "DontPanic" =
        {
            "Arguments" =
            {
                "category" =
                {
                    "Description" = "The kind of panic to be avoided.";
                    "Name" = "in category";
                };
            };
            "Description" = "do not panic";
            "Name" = "do not panic";
            "UnnamedArgument" = {};
        };
    };
    "Enumerations" = {};    // Constants.
    "Name" = "Surf Writer Suite"; // Name of the suite.
}