TweetFollow Us on Twitter

AppleScript Scorecard

Volume Number: 14 (1998)
Issue Number: 2
Column Tag: Scripting

The AppleScript Scorecard Guidelines

by Cal Simone and Bill Cheeseman

Is your application truly scriptable? These guidelines may help you find the answer

For users writing scripts in AppleScript, the number one challenge is the lack of intuitiveness in scripting implementations and consistency when moving among scriptable applications of different types. To aid potential users of scriptable applications in determining the suitability of particular products for their scripting scenarios and, more importantly, to promote these characteristics among developers of scriptable applications, a set of guidelines has been developed, in the form of an AppleScript "Scorecard".

By the time you read this, the Catalog of Scriptable Products should be available on the Web, tentatively at http://www.mainevent.com/scorecard/. The Catalog is a comprehensive directory of scriptable applications, and includes reviews and ratings. The guidelines put forth in this article were developed to form the basis for the reviews and ratings found in the Catalog.

Although the guidelines were developed primarily as an aid for users, they are offered here so that, as the developer of a scriptable product, you can see, in broad terms, what makes up an application that delivers the power of user scripting into the hands of users. Note that, at the time of writing this, we were close to completion, but the final point distribution had not been frozen.

Even if you don't submit your application for a rating, following the criteria of this scoring system will guide you to making your application more easily scripted and more consistent with other well-designed object model-based applications.

The Guidelines

These Guideline are Copyright 1997-1998, Cal Simone and Bill Cheeseman. Printed courtesy of MacTech Magazine, April 1998. The Guidelines may be freely used and distributed, provided that they are copied or distributed in complete form, without alteration, and provided this notice is included.

To promote full AppleScript support in the widest range of products, an application is rated in the AppleScript Scorecard in part for the full and proper implementation of specific scripting features, such as the object model and recordability. To promote the highest quality, an application is also rated on a more qualitative assessment of the design, completeness, transparency, stability and documentation of its AppleScript implementation. In the first phase of rating an application, a range of points is awarded for the presence of specific features, taking into account the extent to which each feature is implemented and its conformity to Apple standards and conventions. In the second phase, additional points are awarded on a sliding scale for specific overall qualities of the scripting implementation.

The AppleScript Scorecard rates an application's support for AppleScript on a scale of 0 to 100. The final score is converted to a scale of one to five "scripts", with half-scripts (1-10 = 1/2 script, 11-20 = 1 script, etc.). The "scripts" score is the primary rating for public distribution, but the points score can be published in parentheses (after converting it to a scale of 0.0 to 10.0 with one decimal place). An example: "3-1/2 scripts (7.2)".

An application is not considered scriptable, and it is not rated, if it has no dictionary or terminology ('aete') resource, or if it has a dictionary that supports only the Required Suite (the run, open, print and quit Apple events) and the "do script" event. Its Finder "scriptable" property may be true because it does respond to the Required Suite, but this by itself does not reach the threshold necessary to be rated.

To be considered for rating, therefore, an application must implement a meaningful and reasonably useful set of verbs in addition to those in the Required Suite (run, open, print and quit), although not necessarily in the form of additional, named suites. Even a small number of supported commands suffices, as long as they enable a scripter to take advantage of some significant and useful functionality of the application. The "do script" event, without more, does not qualify (because this is a rating of the application's AppleScript features, not of a proprietary internal scripting system.)

Phase 1 -- Scripting Features Supported

Points are awarded in Phase 1 for the presence of the specific AppleScript features described below. A range of points may be awarded for the presence of each feature to take into account the extent of its implementation and its conformity to Apple standards and conventions, but Phase 1 does not otherwise rate qualitative aspects of the application's AppleScript support.

Implementation of any of these AppleScript features in conformity to its description here merits awarding the maximum number of points for that feature. Points should be deducted from the maximum for failure to implement specific aspects of a feature where indicated. Points should also be subtracted for limiting a scripting feature such as the object model to a narrow subset of an application's functionality; the penalty should be roughly proportional to the fraction of the application's functionality that is not covered by the scripting implementation. The maximum score for complete implementation of all possible scripting features is 40 points.

Object Model Support -- supports the Apple event object model -- 0 to 25 points

The application supports the object model. It includes at least the essential verbs in the Core, or Standard, Suite ("make", "get" and "set," at a minimum). It also implements a meaningful set of objects that can contain other objects and that have properties. The elements contained in objects have a variety of reference forms (e.g., by index, by name, by unique ID) suitable to their intended use. Its supported commands, including new verbs devised for the application, can operate on various objects and properties in object model fashion. For example, instead of providing commands that are verb-noun hybrids like "GetColor", a graphics application might support objects of several classes, including "picture," which can have any of several properties, including "color," and commands that can operate flexibly on any of those objects and properties to allow a scripter to create complex statements such as "make new picture with properties {color:red}", "get the color of the first picture" and "set the color of picture 3 to red." The objects supported by an application must correspond to all of the conceptual structures of the application (windows, pictures and so on; not its internal programmatic objects). 5 points should be withheld if the application does not support the filter reference form ("whose" clauses).

Recordable -- supports recording -- 0 to 5 points

The application automatically generates the text of valid AppleScript statements when actions are recorded by a script editor. To receive the full 5 points, the generated script must be executable without editing when run under the same conditions under which it was recorded, and its statements should be in general form (for example, they should not refer to objects by unique id).

Attachable -- supports a "Scripts" menu -- 0 to 5 points

The application has a "Scripts" menu which lists AppleScripts written by the user and allows them to be run from the menu bar. An application typically installs the scripts in the Scripts menu when the user places them in a folder within the application's folder. Withhold 1 point if the Scripts menu does not support hierarchical menus (scripts installed in subfolders of the Scripts folder), and withhold 1 point if the Scripts menu is not updated "on the fly" when a new script is placed in the Scripts folder. Withhold 2 points if the menu has a name other than "Scripts" or its synonym in non-English systems.

Embeddable -- supports embedding of scripts in the user interface generally -- 0 to 5 points

The application provides a means to integrate user-written AppleScripts into the user interface in any of a variety of ways in addition to or instead of installing them in a "Scripts" menu. For example, scripts can be executed by clicking on buttons on a tool palette, or scripts can be run as background agents in response to events occurring in the application such as the launching of the application, the opening or closing of a window or the receipt of e-mail. The specific user interface and the manner in which these scripts are stored is not specified and is not relevant to the score. To receive the full 5 points, the manner in which embedded scripts are made available to the user should be creative, consistent with the user interface generally and easy to use.

Phase 2 -- Quality of Scripting Implementation

In addition to the points awarded in Phase 1 for specific scripting features, additional points are awarded in Phase 2 on the basis of the following qualitative assessments of specific aspects of an application's AppleScript support. In general, these categories rate the degree to which an application's AppleScript support forms a consistent and useful user interface in its own right.

An award of 0 points in any one category means that the implementation is abysmal in that respect; 2 or 3 points, that it is barely useful; 6 points, that it is average and therefore acceptable; 9 or 10 points, that it is very good; and 12 points, that it is nearly perfect. In general, a conservative approach is taken so that room will be left at the extreme ends of the scale to distinguish the worst and the best implementations. An average score is not bad, and the scores of most applications should cluster around 6. A score of 4 or 5 points will not be uncommon for slightly below average implementations, and 7 or 8 points should be considered appropriate for good implementations. The maximum score for quality is 60 points. To be awarded the full score, an application's AppleScript support should achieve all of the desired qualities in each category described here.

Design -- fidelity to the application's structure and function -- 0 to 12 points

The Application's commands, objects and properties, and the containment hierarchy and relationship of objects to one another, flow naturally from its subject matter and function instead of rigidly and slavishly mimicking its menu commands and dialogs. The richness of the application is reflected in a relatively large number of objects, or nouns, and a relatively small number of events, or verbs, that act upon them. Commands and objects from established suites, such as the Text Suite, are implemented faithfully if the application is one for which the suite is appropriate. For an application in an area that has no established suites, its commands and objects reflect an equally appropriate fidelity to the structure and function of the application. Consistency with good scripting implementations in the run of scriptable applications in a particular field is closely observed or, if a new and different approach is taken, it is creative, imaginative and, above all, natural and intuitive -- and still in keeping with the "look and feel" of standard AppleScript. Verbs and nouns that go beyond the standard features of established and well-designed suites must extend the language in a consistent and useful manner.

Completeness -- depth, breadth and thoroughness of scriptability -- 0 to 12 points

The application implements a large number of commands, a wide array of objects having a deep containment structure, and a rich and extensive set of properties, exposing the application's full complexity and overall functionality through its scripting interface. The AppleScript implementation is thorough, detailed and complete, making all appropriate functions of the application available to the scripter.

Transparency -- resemblance to plain English words and syntax -- 0 to 12 points

AppleScripts written with the application's dictionary are made up of simple English sentences. Common words in everyday use are employed in a familiar way to describe commands, objects and properties. The application's terminology and syntax are natural and intuitive, not awkward and obscure. A traditional computer programmer would think that an AppleScript statement written using the application's dictionary was a conceptual description of a script, not its executable code. A nonprogrammer would have a good chance of getting an AppleScript statement right the first time without looking at the manual, and scripters experienced with the application would have little difficulty remembering how to script it.

Stability -- absence of bugs -- 0 to 12 points

The application's AppleScript implementation is bug-free, and it works according to specification.

Documentation -- documentation and examples are provided -- 0 to 12 points

Instructions for most or all of the application's scripting features are provided, whether in print or on disk. The documentation is clearly written, well organized and thorough. A large number of useful examples are provided. Apple Guide help (or another help facility available within the application) covers the topic of scripting. The scripting dictionary ('aete' resource) within the application has comments sufficient to remind a user familiar with the application how to use its commands and objects without the need to resort to the external documentation.

Getting Your Product Rated

Send your application (including documentation), in a StuffIt archive, to review@script.org. Submitting to this address will cause the terms in your vocabulary to be added to the databases (both inside and outside of Apple) that are used to analyze and maintain the AppleScript language. This also submits your product for review in the Catalog of Scriptable Products. A submission form is also available in the Catalog's web area, tentatively http://www.mainevent.com/scorecard/. If your application is large, has printed manuals, or is packaged in a box, instructions can be found on the submission form for shipping your product, manuals, or other materials for review.

More Resources for Implementing Scriptability

A roadmap for achieving a thoughtfully designed and well-executed scripting implementation can be found in "According To Script: Steps to Scriptablility" in develop issue 24.

Many of the style guidelines, conventions, tips, and tricks (including the reasons for implementing the object model) are offered in "Designing a Scripting Implementation" in develop issue 21, and the rest of the "According to Script" series, issues 22-26 and 29.

Details of the Apple Event Manager and OSA (Open Scripting Architecture) API are described in Inside Macintosh: Interapplication Communication.


Cal Simone, cal@script.org, champion of AppleScript, is the President of Main Event Software mainevent@his.com and the designer of the Scripter authoring and development environment for AppleScript. In the first half of 1997, Cal spearheaded a 5-month effort to rescue AppleScript from the chopping block during Apple's "technology evaluation" (also known as the "spring cleaning") and to convince Apple's top management to commit to AppleScript in Rhapsody.

Bill Cheeseman, cheeseb@mediaone.net is a lawyer in Massachusetts, and he maintains The AppleScript SourceBook site at http://oasis.bellevue.k12.wa.us/cheeseb/index.html. A true-life legal experience of his is the subject of the best-selling book "A Civil Action," and it is being made into a Hollywood movie, starring John Travolta, to be released in late 1998. Bill has been programming Apple computers as a hobby since 1977.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Latest Forum Discussions

See All

Whitethorn Games combines two completely...
If you have ever gone fishing then you know that it is a lesson in patience, sitting around waiting for a bite that may never come. Well, that's because you have been doing it wrong, since as Whitehorn Games now demonstrates in new release Skate... | Read more »
Call of Duty Warzone is a Waiting Simula...
It's always fun when a splashy multiplayer game comes to mobile because they are few and far between, so I was excited to see the notification about Call of Duty: Warzone Mobile (finally) launching last week and wanted to try it out. As someone who... | Read more »
Albion Online introduces some massive ne...
Sandbox Interactive has announced an upcoming update to its flagship MMORPG Albion Online, containing massive updates to its existing guild Vs guild systems. Someone clearly rewatched the Helms Deep battle in Lord of the Rings and spent the next... | Read more »
Chucklefish announces launch date of the...
Chucklefish, the indie London-based team we probably all know from developing Terraria or their stint publishing Stardew Valley, has revealed the mobile release date for roguelike deck-builder Wildfrost. Developed by Gaziter and Deadpan Games, the... | Read more »
Netmarble opens pre-registration for act...
It has been close to three years since Netmarble announced they would be adapting the smash series Solo Leveling into a video game, and at last, they have announced the opening of pre-orders for Solo Leveling: Arise. [Read more] | Read more »
PUBG Mobile celebrates sixth anniversary...
For the past six years, PUBG Mobile has been one of the most popular shooters you can play in the palm of your hand, and Krafton is celebrating this milestone and many years of ups by teaming up with hit music man JVKE to create a special song for... | Read more »
ASTRA: Knights of Veda refuse to pump th...
In perhaps the most recent example of being incredibly eager, ASTRA: Knights of Veda has dropped its second collaboration with South Korean boyband Seventeen, named so as it consists of exactly thirteen members and a video collaboration with Lee... | Read more »
Collect all your cats and caterpillars a...
If you are growing tired of trying to build a town with your phone by using it as a tiny, ineffectual shover then fear no longer, as Independent Arts Software has announced the upcoming release of Construction Simulator 4, from the critically... | Read more »
Backbone complete its lineup of 2nd Gene...
With all the ports of big AAA games that have been coming to mobile, it is becoming more convenient than ever to own a good controller, and to help with this Backbone has announced the completion of their 2nd generation product lineup with their... | Read more »
Zenless Zone Zero opens entries for its...
miHoYo, aka HoYoverse, has become such a big name in mobile gaming that it's hard to believe that arguably their flagship title, Genshin Impact, is only three and a half years old. Now, they continue the road to the next title in their world, with... | Read more »

Price Scanner via MacPrices.net

B&H has Apple’s 13-inch M2 MacBook Airs o...
B&H Photo has 13″ MacBook Airs with M2 CPUs and 256GB of storage in stock and on sale for up to $150 off Apple’s new MSRP, starting at only $849. Free 1-2 day delivery is available to most US... Read more
M2 Mac minis on sale for $100-$200 off MSRP,...
B&H Photo has Apple’s M2-powered Mac minis back in stock and on sale today for $100-$200 off MSRP. Free 1-2 day shipping is available for most US addresses: – Mac mini M2/256GB SSD: $499, save $... Read more
Mac Studios with M2 Max and M2 Ultra CPUs on...
B&H Photo has standard-configuration Mac Studios with Apple’s M2 Max & Ultra CPUs in stock today and on Easter sale for $200 off MSRP. Their prices are the lowest available for these models... Read more
Deal Alert! B&H Photo has Apple’s 14-inch...
B&H Photo has new Gray and Black 14″ M3, M3 Pro, and M3 Max MacBook Pros on sale for $200-$300 off MSRP, starting at only $1399. B&H offers free 1-2 day delivery to most US addresses: – 14″ 8... Read more
Department Of Justice Sets Sights On Apple In...
NEWS – The ball has finally dropped on the big Apple. The ball (metaphorically speaking) — an antitrust lawsuit filed in the U.S. on March 21 by the Department of Justice (DOJ) — came down following... Read more
New 13-inch M3 MacBook Air on sale for $999,...
Amazon has Apple’s new 13″ M3 MacBook Air on sale for $100 off MSRP for the first time, now just $999 shipped. Shipping is free: – 13″ MacBook Air (8GB RAM/256GB SSD/Space Gray): $999 $100 off MSRP... Read more
Amazon has Apple’s 9th-generation WiFi iPads...
Amazon has Apple’s 9th generation 10.2″ WiFi iPads on sale for $80-$100 off MSRP, starting only $249. Their prices are the lowest available for new iPads anywhere: – 10″ 64GB WiFi iPad (Space Gray or... Read more
Discounted 14-inch M3 MacBook Pros with 16GB...
Apple retailer Expercom has 14″ MacBook Pros with M3 CPUs and 16GB of standard memory discounted by up to $120 off Apple’s MSRP: – 14″ M3 MacBook Pro (16GB RAM/256GB SSD): $1691.06 $108 off MSRP – 14... Read more
Clearance 15-inch M2 MacBook Airs on sale for...
B&H Photo has Apple’s 15″ MacBook Airs with M2 CPUs (8GB RAM/256GB SSD) in stock today and on clearance sale for $999 in all four colors. Free 1-2 delivery is available to most US addresses.... Read more
Clearance 13-inch M1 MacBook Airs drop to onl...
B&H has Apple’s base 13″ M1 MacBook Air (Space Gray, Silver, & Gold) in stock and on clearance sale today for $300 off MSRP, only $699. Free 1-2 day shipping is available to most addresses in... Read more

Jobs Board

Medical Assistant - Surgical Oncology- *Apple...
Medical Assistant - Surgical Oncology- Apple Hill Location: WellSpan Medical Group, York, PA Schedule: Full Time Sign-On Bonus Eligible Remote/Hybrid Regular Apply Read more
Omnichannel Associate - *Apple* Blossom Mal...
Omnichannel Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Cashier - *Apple* Blossom Mall - JCPenney (...
Cashier - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Blossom Mall Read more
Operations Associate - *Apple* Blossom Mall...
Operations Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Business Analyst | *Apple* Pay - Banco Popu...
Business Analyst | Apple PayApply now " Apply now + Apply Now + Start applying with LinkedIn Start + Please wait Date:Mar 19, 2024 Location: San Juan-Cupey, PR Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.