# SwiftAutomation README

## About

SwiftAutomation is an Apple event bridge that allows Apple's Swift language 
to control "AppleScriptable" macOS applications directly. For example:

  // tell application "iTunes" to play
  try ITunes().play()

  // tell application "Finder" to set fileNames to name of every file of home
  let fileNames = try Finder().home.files.name.get() as [String]


  // tell application "TextEdit" to make new document ¬
  //                                     with properties {text:"Hello World!"}
  try TextEdit().make(new: TED.document, 
                      withProperties: [TED.text: "Hello World!"])


The SwiftAutomation framework defines the basic functionality for constructing
object specifiers, converting data between Swift and AE types, and sending 
Apple events to running applications. Generated Swift files supply the glue
code for controlling individual applications using human-readable terminology.


## Get it

To clone the Xcode project to your own machine:

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

A basic Swift "script editor" (currently under development) is also available:

  https://bitbucket.org/hhas/swiftautoedit


## Install it

To embed SwiftAutomation for use in Swift-based GUI apps see Xcode's Workspace
documentation.

To use SwiftAutomation in Swift "scripting", see the Installing SwiftAutomation
chapter of the SwiftAutomation documentation. Until Swift provides a stable ABI
some manual set-up is required.


## Try it

To run simple examples (see test/main.swift), build and run the `test` target.

Additional glues can be generated by building the `aeglue` target and running
the resulting `aeglue` command line tool in Terminal. For example, to generate
a Swift glue and accompanying documentation for macOS's Photos application:

  /path/to/aeglue -o ~/Desktop Photos

Note that `aeglue` normally retrieves application terminology using `ascrgdte`
('get dynamic terminology') Apple events. Some applications (e.g. Finder) have
faulty `ascrgdte` handlers that fail to return correct terminology, in which
case use the `-s` or 'Use SDEF terminology' options instead. (Be aware that
SDEF-based terminology may also contain bugs and omissions, in which case use
raw four-char codes or correct generated glue code by hand.)

SwiftAutomation requires macOS 10.11 and Swift 3.0 and Xcode 8.0 or later.


## Status

The code is complete except for testing and bug fixes. The documentation lacks
a usable tutorial chapter. Given current uncertainty regarding the future of
Apple event-based automation the project is on hiatus until WWDC17, after which
a final decision on its future can be made.


## Known issues

When using SwiftAutomation within an interactive playground, be aware that Xcode
automatically re-runs ALL code within a playground whenever a line of code is
modified, causing ALL application commands to be re-sent. This is not a problem
when using non-mutating application commands such as `get` and `count`; however,
take care when using commands that modify the application's state - `make`,
`move`, `delete`, etc. - within a playground as sending these more than once may
have unintended/undesirable results. This is a playground issue that affects ALL
non-idempotent and/or unsafe function calls, not just application commands.


## Etc.

SwiftAutomation is released into the public domain.

No warranty given, E&OE, use at own risk, etc.