NSAppleScript Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.2 and later.
Companion guide
Declared in
NSAppleScript.h
Related sample code

Overview

The NSAppleScript class provides the ability to load, compile, and execute scripts.

This class provides applications with the ability to

When you create an instance of NSAppleScript object, you can use a URL to specify a script that can be in either text or compiled form, or you can supply the script as a string. Should an error occur when compiling or executing the script, several of the methods return a dictionary containing error information. The keys for obtaining error information, such as NSAppleScriptErrorMessage, are described in the Constants section.

See also NSAppleScript Additions Reference in the Application Kit framework, which defines a method that returns the syntax-highlighted source code for a script.

Adopted Protocols

NSCopying

Tasks

Initializing a Script

Getting Information About a Script

Compiling and Executing a Script

Instance Methods

compileAndReturnError:

Compiles the receiver, if it is not already compiled.

- (BOOL)compileAndReturnError:(NSDictionary **)errorInfo
Parameters
errorInfo

On return, if an error occurs, a pointer to an error information dictionary.

Return Value

YES for success or if the script was already compiled, NO otherwise.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSAppleScript.h

executeAndReturnError:

Executes the receiver, compiling it first if it is not already compiled.

- (NSAppleEventDescriptor *)executeAndReturnError:(NSDictionary **)errorInfo
Parameters
errorInfo

On return, if an error occurs, a pointer to an error information dictionary.

Return Value

The result of executing the event, or nil if an error occurs.

Discussion

Any changes to property values caused by executing the script do not persist.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSAppleScript.h

executeAppleEvent:error:

Executes an Apple event in the context of the receiver, as a means of allowing the application to invoke a handler in the script.

- (NSAppleEventDescriptor *)executeAppleEvent:(NSAppleEventDescriptor *)event error:(NSDictionary **)errorInfo
Parameters
event

The Apple event to execute.

errorInfo

On return, if an error occurs, a pointer to an error information dictionary.

Return Value

The result of executing the event, or nil if an error occurs.

Discussion

Compiles the receiver before executing it if it is not already compiled.

Availability
  • Available in OS X v10.2 and later.
Related Sample Code
Declared In
NSAppleScript.h

initWithContentsOfURL:error:

Initializes a newly allocated script instance from the source identified by the passed URL.

- (id)initWithContentsOfURL:(NSURL *)url error:(NSDictionary **)errorInfo
Parameters
url

A URL that locates a script, in either text or compiled form.

errorInfo

On return, if an error occurs, a pointer to an error information dictionary.

Return Value

The initialized script object, nil if an error occurs.

Discussion

This method is a designated initializer for NSAppleScript.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSAppleScript.h

initWithSource:

Initializes a newly allocated script instance from the passed source.

- (id)initWithSource:(NSString *)source
Parameters
source

A string containing the source code of a script.

Return Value

The initialized script object, nil if an error occurs.

Discussion

This method is a designated initializer for NSAppleScript.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSAppleScript.h

isCompiled

Returns a Boolean value that indicates whether the receiver's script has been compiled.

- (BOOL)isCompiled
Return Value

YES if the receiver is already compiled, NO otherwise.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSAppleScript.h

source

Returns the script source for the receiver.

- (NSString *)source
Return Value

The script source code of the receiver if it is available, nil otherwise.

Discussion

It is possible for an NSAppleScript that has been instantiated with initWithContentsOfURL:error: to be a script for which the source code is not available but is nonetheless executable.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSAppleScript.h

Constants

Error Dictionary Keys

If the result of initWithContentsOfURL:error:, compileAndReturnError:, executeAndReturnError:, or executeAppleEvent:error:, signals failure (nil, NO, nil, or nil, respectively), a pointer to an autoreleased dictionary is put at the location pointed to by the error parameter. The error info dictionary may contain entries that use any combination of the following keys, including no entries at all.

extern NSString *NSAppleScriptErrorMessage;
extern NSString *NSAppleScriptErrorNumber;
extern NSString *NSAppleScriptErrorAppName;
extern NSString *NSAppleScriptErrorBriefMessage;
extern NSString *NSAppleScriptErrorRange;
Constants
NSAppleScriptErrorMessage

An NSString that supplies a detailed description of the error condition.

Available in OS X v10.2 and later.

Declared in NSAppleScript.h.

NSAppleScriptErrorNumber

An NSNumber that specifies the error number.

Available in OS X v10.2 and later.

Declared in NSAppleScript.h.

NSAppleScriptErrorAppName

An NSString that specifies the name of the application that generated the error.

Available in OS X v10.2 and later.

Declared in NSAppleScript.h.

NSAppleScriptErrorBriefMessage

An NSString that provides a brief description of the error.

Available in OS X v10.2 and later.

Declared in NSAppleScript.h.

NSAppleScriptErrorRange

An NSValue that specifies a range.

Available in OS X v10.2 and later.

Declared in NSAppleScript.h.

Declared In
NSAppleScript.h