AppleScriptObj-C Routines

AppleScriptObjective-C (also called: AppleScriptObj-C or ASOC) is the dynamic fusion of the AppleScript and Objective-C languages, providing access within scripts to the classes and methods of the core Cocoa frameworks of macOS, while also possessing the ability to query and command applications throughout macOS via Apple Events.

For its 20th anniversary debut in OS X Mavericks, AppleScript gained a long-sought ability: an import command — dramatically extending the scope and power of this unique language.

A new AppleScript construct called the “use statement” imports the terminology and functionality of AppleScript Libraries and scriptable Applications through a simple single-line declaration placed at the top of a script, such as:

• use application "Finder"
• use script "My AppleScript Text Library"
• use framework "Foundation"

The handlers, scriptable objects, properties, and terminology of AppleScript Libraries and scriptable applications imported via a “use statement,” are automatically available globally throughout the hosting script, no longer requiring numerous “tell statements” or “tell blocks” to be compiled and executed. Scripts taking advantage of the “use statement” are more streamlined and clearer than similar scripts not implementing this new construct.

In addition, AppleScript Libraries written in AppleScript/Objective-C, can incorporate “use” statements to import Cocoa frameworks, such as MapKit, EventKit, and WebKit.

AppleScript/Objective-C is available to all scripts, not just library scripts. To use an Objective-C framework in your script, you must specify it with a use statement, such as: use framework "Foundation"

Here’s a short video demonstrating the use of AppleScriptObj-C to sort a list on names:

Important AppleScriptObj-C Constructs

Here are rules to follow when writing AppleScriptObj-C.

1) Identify Cocoa classes and enumerations as belonging to the current application.

2) Cocoa methods are separated from their parameter values by colons, and are shown to belong to their parent class.

3) When retrieving the value of a Cocoa property, the property name is written ending with open/close parens ()

4) When setting the value of a Cocoa Object's property, no ending parens are included. Optionally the property may be used as a method by placing the term set before its capitalized version, followed by a colon and the new value.

Hre are some supporting reference links:

EverdayAppleScriptObjC by Shane Stanely

Mac Automation Scripting Guide

AppleScript release notes

Strings

AppleScriptObj-C provides access to the NSString class of the Foundation frameworks, containing methods for easily manipulating text strings, even those used as paths representing the location of disk items.

The following routines use methods and properties of the NSString class to simplify common text manipulations that are more difficult to perform using the AppleScript language alone.

Converting to Objective-C and Back

There is a typical process for manipulating AppleScript text strings using the NSString class methods and properties of the Frameworks framework. AppleScript text strings are first converted to Objective-C text objects, manipulated using Cocoa class methods and properties, and the result is then coerced back into an AppleScript text string.

The following examples use the described procedure to perform common text manipulations.

Change Case

The native AppleScript language does not offer built-in methods for converting the case of text strings. AppleScriptObj-C can be used to access the NSString methods and properties to change the case of text.

Trim Whitespace

Here a routine for removing tabs, spaces, and paragraph returns from the beginning and end of a provided text string. Use the whitespaceCharacterSet property to remove only tabs and spaces, but not line feeds and returns.

Replace Text in String

Here’s a routine for finding and replacing a text string from within larger strings.

Base Name of a File

The NSString class contains methods and properties that are designed to manipulate POSIX file paths that indicated the location of disk items.

In the following example, the base name (file name without file extension) is returned from a passed file reference.

Container of a File

The NSString class contains methods and properties that are designed to manipulate POSIX file paths that indicated the location of disk items.

In the following example, an alias reference to the containing folder of a passed file reference is returned.

POSIX Path of Item

This routine will return a POSIX path for the designated file reference. Accepts: aliases, file URLs, POSIX files, and relative paths

Derive Path for File in Specified Folder

This routine is very useful when you are creating new files in a specific folder. The routine will check to see if a file with the provided name already exists, and if it does, generate a unique numerically incremented version. For example, if the file named "Report.txt" is already in the target folder, the routine will return a path for the new file with the incremented name "Report-1.txt"

Number to Formatted Currency String

This routine will convert the passed number into a formatted currency string using the current locale.

Number to Percentage Value String

This routine will convert a decimal value into a percentage value string.

Number to Words

This routine converts the passed number into a phrase. For example, 12345678 becomes twelve million three hundred forty-five thousand six hundred seventy-eight.

Number to Decimal String

This routine will return a decimal string from the provided numeric value. You can indicate a specific decimal length for the resulting value. In addition, the numeric value will automatically be rounded during the process of adding decimals.

Number to Ordinal String

Creates an ordinal string based upon the provided number. For example, 23 derives 23rd.

Number to String

This routine converts the passed number to a string. Especially useful for converting scientific notation to “normal” numbers. For example, 1.23456789E+9 becomes 1234567890.

List from String

This routine divides a string into a list of components based upon the indicated delimiter.

List to String

This routine combines the elements of a list into a delimited string.

Percent Encode the String

This routine will percent encode all non-alphanumeric characters in a string. For example, a space will replaced with %20.

Decode Percent Encoded String

This routine will replace percent encoding in a string with corresponding characters.

Arrays

Here are series of routines for manipulating lists (arrays).

Sort List

Here’s a routine for alphabetically sorting a list.

Insert Item in List

This routine inserts an item in the provided list at the indicated position. The first position is 1 not 0.

Remove Item from List

This routine removes all occurrences of an indicated item from the provided list.

Index of First Occurence in List

This routine returns the index of the first occurence of an item in a list. If item is not in the list, then 0 is returned.

Remove Items at Indexes

This routine will remove the items at the provided indexes.

Records

Routines for manipulating records.

New Record from Lists

Turn a list of keys and a list of corresponding values into an AppleScript record.

Property Lists

Routines for manipulating standard property lists (plist).

Here is a simple sample property list file (DOWNLOAD) containing a single key/value pair.

Edit Value of Existing Key

Here is an example script showing how to edit the value of the specified key in the property list. NOTE: the sub-routine in this example is written in Cocoa format with the values for the function and parameters following colon (":") characters:

FYI: here’s a basic routine for retrieving the value of a property list element:

Here’s an example of creating a property list containing multiple elements, each of which is an array:

The resulting property list:

Bookmarks

Routine for generating a minimal bookmark to a file. This routine returns bookmark data that can later be resolved into a URL object for a file even if the user moves or renames it (if the volume format on which the file resides supports doing so).