AppleScript_ The Definitive Guide - Matt Neuburg [191]
The problem is particularly acute when the dictionary entry for a verb doesn't provide any meaningful information. For example, here's how delete is listed in most dictionaries:
delete reference --the element to delete
That could mean anything, so it means nothing. The only way to find out what it does mean is by trying it. Another good example is close; there are usually very few objects in an application that can be closed (windows, typically) so why doesn't the dictionary tell you?
Script Debugger is particularly helpful here, because for every class it lists all the places in the dictionary where it's used. But of course this is only as good as the dictionary itself; Script Debugger doesn't have xray eyes that can peer into the workings of an application, and if a dictionary is not specific about what class or classes can serve as the object of a verb, no amount of cross-referencing can tell you.
Part of the problem here is that the dictionary is not designed to communicate the desired information in any complete and coherent manner. The new sdef format may, in some cases, improve the situation. A Cocoa application's sdef can actually include implementation information in the dictionary; a class can list the commands it responds to, and a dictionary display will then be able to pass this along to the human reader.
Until the new sdef format is widely adopted, we're left with trial and error. If AppleScript or an application doesn't want to apply a particular verb to a particular object, it will usually return an error message that "such-and-such an object doesn't understand the so-and-so message." In other words: sorry, guess again.
Coercions
Dictionaries don't list the coercions that can be performed by an application in response to get...as. (See "Explicit Coercion" in Chapter 14.) Only trial and error can give you this information.
A rare exception is the Finder, which defines a class alias list and almost tells you (but not quite) that the purpose of this class is to let you coerce to it:
tell application "Finder"
get every disk as alias list
-- {alias "feathers:", alias "gromit:", alias "Network:"}
end tell
Sometimes, for particular verbs, a comment can help to fill the gap. But sometimes the comment is lying. The path to scripting addition command has an as parameter; the comment tells you that your choices are string and alias. But you can also say Unicode text, and it might be important to do so; the dictionary fails to mention this.
The problem is particularly acute for scripting additions. A scripting addition can implement a coercion, which then works as if it were part of the AppleScript language. (A good example is Jon's Commands , which lets you coerce a script object to a string.) But because coercions are not listed in the dictionary, you have no way to find out about this (except from some other documentation). Even worse, if you then run a script in the absence of that scripting addition, this coercion will break and you might not know why, because you didn't realize that it was working in the first place only because of that scripting addition.
Bad Grammar
When developers decide on the English-like terminology for a dictionary, do they think about the experience of the users who will actually employ this terminology in typical AppleScript expressions? I sometimes wonder, when I find myself saying something like this to the Finder:
if application file n has scripting terminology then
That's illegal, and generates a compile-time error. Instead, you have to say this ungrammatical-sounding phrase:
if application file n is has scripting terminology then -- "is has"???
The trouble is that has scripting terminology is the name of a property. Why would anyone make a property name a verb? If the name of this property were an adjective, such as scriptable, it could be used without sounding unnatural. (See "The "English-likeness " Monster" in Chapter