Welcome

What is SwiftAutomation?

SwiftAutomation allows you to control "AppleScriptable" macOS applications using Apple Inc's Swift programming language. SwiftAutomation makes Swift a true alternative to AppleScript for automating your Mac.

For example, to get the value of the first paragraph of the topmost document in TextEdit:

let result = try TextEdit().documents[1].paragraphs[1].get() as String

This is equivalent to the AppleScript statement:

tell application id "com.apple.TextEdit" to get paragraph 1 of document 1

Or to create a new "Hello World!" document in TextEdit:

// tell application id "com.apple.TextEdit"
//   make new document with properties {text:"Hello World!"}
// end tell

let textedit = TextEdit()
try textedit.make(new: TED.document, withProperties: [TED.text: "Hello World!"])

Getting SwiftAutomation

To clone the SwiftAutomation repository to your own machine:

git clone https://bitbucket.org/hhas/swiftae.git

Minimum requirements: macOS 10.11 and Xcode 8.1/Swift 3.0.1.

When working through the SwiftAutomation tutorial and writing #!/usr/bin/swift "scripts" that are compiled and executed each time they are run, the simplest way to get started is to build the SwiftAE project's Release target and then create symlinks to the SwiftAutomation and MacOSGlues frameworks in /Library/Frameworks:

cd /Library/Frameworks
sudo ln -s /path/to/Build/Products/Release/SwiftAutomation.framework
sudo ln -s /path/to/Build/Products/Release/MacOSGlues.framework

and a symlink to the AppleScriptToSwift application in /Applications:

cd /Applications
sudo ln -s /path/to/Build/Products/Release/AppleScriptToSwift.app

When using these frameworks, remember that Swift does not yet provide a stable ABI so Swift programs can only import frameworks compiled with exactly the same version of Swift. Therefore you must rebuild these frameworks whenever you install a new version of Xcode/Swift. [TO DO: what about embedding in CLI and GUI apps? easiest would be to link to instructions in Swift/Xcode docs]

Before you start...

In order to use SwiftAutomation effectively, you will need to understand the differences between the Apple event and Swift/Cocoa object systems.

In contrast to the familiar object-oriented approach of other inter-process communication systems such as COM and Distributed Objects, Apple event IPC is based on a combination of remote procedure calls and first-class queries - somewhat analogous to using XPath over XML-RPC.

While SwiftAutomation uses an object-oriented-like syntax for conciseness and readability, like AppleScript, it behaves according to Apple event rules. As a result, Swift users will discover that some things work differently in SwiftAutomation from what they're used to. For example:

• Object elements are one-indexed, not zero-indexed like Swift Arrays.

• Referencing a property of an application object does not automatically return the property's value (you need a get command for that).

• Many applications allow a single command to operate on multiple objects at the same time, providing significant performance benefits when manipulating large numbers of application objects. (Conversely, sending lots of commands to manipulate single objects one at a time can severely degrade performance.)

Chapters 2 and 3 of this manual provide further information on how Apple event IPC works and a tutorial-based introduction to the SwiftAutomation bridge. Chapters 4 and 10 explain how to generate glue files for controlling specific appications. Chapters 5 through 9 cover the SwiftAutomation API, and chapter 11 discusses techniques for optimising performance.