Commands

// TO DO: this chapter is still rough, and there's little commonality between ObjC and Swift text; the ObjC API is also not finalized and may change slightly/drastically in future

Syntax

For convenience, AppleEventBridge makes application commands available as methods on every object specifier. (Note: due to the limitations of aete-based terminology, the user must determine for themselves which commands can operate on a particular reference. Some applications document this information separately.) All application commands have the same basic structure: a single, optional direct parameter, followed by zero or more named parameters specific to that command, followed by zero or more event attributes that determine how the Apple event is processed:

func commandName(directParameter: AnyObject = AEBNoParameter,
                 namedParameter1: AnyObject = AEBNoParameter,
                 namedParameter2: AnyObject = AEBNoParameter,
                 ...
                 returnType:      AEBReturnType?         = nil,
                 waitReply:       Bool?                  = nil,
                 withTimeout:     NSTimeInterval?        = nil,
                 considering:     AEBConsiderIgnoreType? = nil,
                 ignoring:        AEBConsiderIgnoreType? = nil) throws -> AnyObject!

Examples

  // tell application "TextEdit" to activate
  TextEdit().activate()

  // tell application "TextEdit" to open fileList
  TextEdit().open(fileList)

  // tell application "Finder" to get version
  Finder().version.get()

  // tell application "Finder" to set name of file "foo.txt" of home to "bar.txt"
  Finder().home.files["foo.txt"].name.set(to: "bar.txt")

  // tell application "TextEdit" to count (text of first document) each paragraph
  TextEdit().documents.first.text.count(each: TED.paragraph)

  // tell application "TextEdit" to make new document at end of documents
  TextEdit().documents.end.make(new: TED.document)

  // tell application "Finder" to get items of home as alias list
  Finder().home.items.get(returnType: FIN.alias)

Special cases

The following special-case behaviours are implemented for convenience:

The two forms are equivalent (AEBSpecifier converts the first form to the second behind the scenes) although the first form is preferred for conciseness.

the object specifier upon which it is called will be packed as the Apple event's "subject" attribute (keySubjectAttr).

Command errors

If a command fails due to an error raised by the target application or Apple Event Manager, or if a given parameter or attribute was not of a supported type, an NSError is thrown. AppleEventBridge errors have the domain AEBErrorDomain, an error code that is typically an OSStatus value or custom value defined by the target application, and a userInfo dictionary containing a standard NSLocalizedDescription key containing the error description string, plus zero or more of the following AEB-defined keys:

Note to AppleScript users

Unlike AppleScript, which implicitly sends a get command to any unresolved application object references at the end of evaluating an expression, AEB only resolves a reference when it receives an appropriate command. For example:

let o = TextEdit().documents

is not the same as:

set o to documents of application "TextEdit"

even though the two statements may look equivalent. In the Swift example, the value assigned to o is an instance of TEDSpecifier, TextEdit(name:"/Applications/TextEdit.app").documents, i.e. an object specifier. Whereas, in the AppleScript example, the evaluating the documents of application "TextEdit" expression not only constructs the same specifier, it also automatically sends a get event to the target application in order to retrieve the specified data, then assigns the result of that request to o:

set o to documents of application "TextEdit"
o
--> {document "Untitled" of application "TextEdit", document "Untitled 2" of application "TextEdit"}

This "implicit get" behavior is built directly into the AppleScript interpreter itself, and automatically applied to any specifier literal that does not already appear as a parameter to an application command, as a tell block target, or as the sole operand to AppleScript's' a reference to operator:

set o to a reference to documents of application "TextEdit"
o
--> every document of application "TextEdit"

In contrast, AEB has no invisible "magic" behaviors attempting to infer your actual intent: it only ever sends an Apple event when you explicitly instruct it to do so:

let o = TextEdit().documents.get()
print(o)
// [TextEdit(...).documents["Untitled"], TextEdit(...).documents["Untitled 2"]]

New users coming from AppleScript or OO language backgrounds may find this unintuitive at first, but AEB's clean separation between query construction and event dispatch ensures AEB's behavior is completely straightforward and predictable, and avoids the hidden gotchas that can bite AppleScript users in various unexpected and confusing ways.