Mac Developer Library

Developer

Foundation Framework Reference NSScriptCommand Class Reference

Options
Deployment Target:

On This Page
Language:

NSScriptCommand

An instance of NSScriptCommand represents a scripting statement, such as set word 5 of the front document to word 1 of the second document, and contains the information needed to perform the operation specified by the statement.

When an Apple event reaches a Cocoa application, Cocoa’s built-in scripting support transforms it into a script command (that is, an instance of NSScriptCommand or one of the subclasses provided by Cocoa scripting or by your application) and executes the command in the context of the application. Executing a command means either invoking the selector associated with the command on the object or objects designated to receive the command, or having the command perform its default implementation method (performDefaultImplementation).

Your application most likely calls methods of NSScriptCommand to extract the command arguments. You do this either in the performDefaultImplementation method of a command subclass you have created, or in an object method designated as the selector to handle a particular command.

As part of Cocoa’s standard scripting implementation, NSScriptCommand and its subclasses can handle the default command set for AppleScript's Standard suite for most applications without any subclassing. The Standard suite includes commands such as copy, count, create, delete, exists, and move, as well as common object classes such as application, document, and window.

For more information on working with script commands, see Script Commands in Cocoa Scripting Guide.

Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in OS X v10.0 and later.
  • Returns an a script command object initialized from the passed command description.

    Declaration

    Swift

    init(commandDescription commandDesc: NSScriptCommandDescription)

    Objective-C

    - (instancetype)initWithCommandDescription:(NSScriptCommandDescription *)commandDesc

    Parameters

    commandDesc

    A command description for the command to be created.

    Return Value

    A newly initialized instance of NSScriptCommand or a subclass.

    Discussion

    To make this command object usable, you must set its receiving objects and arguments (if any) after invoking this method.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • If a command is being executed in the current thread by Cocoa scripting's built-in Apple event handling, return the command.

    Declaration

    Swift

    class func currentCommand() -> NSScriptCommand?

    Objective-C

    + (NSScriptCommand *)currentCommand

    Discussion

    A command is being executed in the current thread by Cocoa scripting's built-in Apple event handling if an instance of NSScriptCommand is handling an executeCommand message at this instant as the result of the dispatch of an Apple event. Returns nil otherwise. setScriptErrorNumber: and setScriptErrorString: messages sent to the returned command object will affect the reply event sent to the sender of the event from which the command was constructed, if the sender has requested a reply.

    A suspended command is not considered the current command. If a command is suspended and no other command is being executed in the current thread, currentCommand returns nil.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

  • If the receiver was constructed by Cocoa scripting's built-in Apple event handling, returns the Apple event descriptor from which it was constructed.

    Declaration

    Swift

    @NSCopying var appleEvent: NSAppleEventDescriptor? { get }

    Objective-C

    @property(readonly, copy) NSAppleEventDescriptor *appleEvent

    Discussion

    The effects of mutating or retaining this descriptor are undefined, although it may be copied.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

  • Executes the command if it is valid and returns the result, if any.

    Declaration

    Swift

    func executeCommand() -> AnyObject?

    Objective-C

    - (id)executeCommand

    Discussion

    Before this method executes the command (through NSInvocation mechanisms), it evaluates all object specifiers involved in the command, validates that the receivers can actually handle the command, and verifies that the types of any arguments that were initially object specifiers are valid.

    You shouldn’t have to override this method. If the command’s receivers want to handle the command themselves, this method invokes their defined handler. Otherwise, it invokes performDefaultImplementation.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Overridden by subclasses to provide a default implementation for the command represented by the receiver.

    Declaration

    Swift

    func performDefaultImplementation() -> AnyObject?

    Objective-C

    - (id)performDefaultImplementation

    Discussion

    Do not invoke this method directly. executeCommand invokes this method when the command being executed is not supported by the class of the objects receiving the command. The default implementation returns nil.

    You need to create a subclass of NSScriptCommand only if you need to provide a default implementation of a command.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the object or objects to which the command is to be sent (called both the “receivers” or “targets” of script commands).

    Declaration

    Swift

    var evaluatedReceivers: AnyObject? { get }

    Objective-C

    @property(readonly, retain) id evaluatedReceivers

    Discussion

    It evaluates receivers, which are always object specifiers, to a proper object. If the command does not specify a receiver, or if the receiver doesn’t accept the command, it returns nil.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the object specifier that, when evaluated, yields the receiver or receivers of the command.

    Declaration

    Swift

    var receiversSpecifier: NSScriptObjectSpecifier?

    Objective-C

    @property(retain) NSScriptObjectSpecifier *receiversSpecifier

    Discussion

    The receiver is typically a container. For example, if the original command is get the third paragraph of the first document, the receiver specifier is the first document—it’s the document that knows how to get or set words or paragraphs it contains.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Sets the object specifier to receiversSpec that, when evaluated, indicates the receiver or receivers of the command.

    Declaration

    Swift

    var receiversSpecifier: NSScriptObjectSpecifier?

    Objective-C

    @property(retain) NSScriptObjectSpecifier *receiversSpecifier

    Discussion

    If you create a subclass of NSScriptCommand, you don’t necessarily need to override this method, though some of Cocoa’s subclasses do. An override should perform the same function as the superclass method, with a critical difference: it causes the container specifier part of the passed-in object specifier to become the receiver specifier of the command, and the key part of the passed-in object specifier to become the key specifier. In an override, for example, if receiversRef is a specifier for the third rectangle of the first document, the receiver specifier is the first document while the key specifier is the third rectangle.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the arguments of the command.

    Declaration

    Swift

    var arguments: [NSObject : AnyObject]!

    Objective-C

    @property(copy) NSDictionary *arguments

    Discussion

    If there are no arguments, returns an empty NSDictionary object. When you subclass NSScriptCommand or one of its subclasses, you rarely call this method because it returns the arguments directly, without evaluating any arguments that are object specifiers. If any of a command’s arguments may be object specifiers, which is generally the case, call evaluatedArguments instead.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a dictionary containing the arguments of the command, evaluated from object specifiers to objects if necessary. The keys in the dictionary are the argument names.

    Declaration

    Swift

    var evaluatedArguments: [NSObject : AnyObject]? { get }

    Objective-C

    @property(readonly, copy) NSDictionary *evaluatedArguments

    Discussion

    Arguments initially can be either a normal object or an object specifier such as word 5 (represented as an instance of an NSScriptObjectSpecifier subclass). If arguments are object specifiers, the receiver evaluates them before using the referenced objects. Returns nil if the command is not well formed. Also returns nil if an object specifier does not evaluate to an object or if there is no type defined for the argument in the command description.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Sets the arguments of the command to args.

    Declaration

    Swift

    var arguments: [NSObject : AnyObject]!

    Objective-C

    @property(copy) NSDictionary *arguments

    Discussion

    Each argument in the dictionary is identified by the same name key used for the argument in the command’s class declaration in the script suite file.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the object that corresponds to the direct parameter of the Apple event from which the receiver derives.

    Declaration

    Swift

    var directParameter: AnyObject?

    Objective-C

    @property(retain) id directParameter

    Return Value

    An object. Returns nil if the received Apple event doesn’t contain a direct parameter.

    Discussion

    For example, the direct parameter of a print documents Apple event contains a list of documents. This method may return the same object or objects returned by receiversSpecifier.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Sets the object that corresponds to the direct parameter of the Apple event from which the receiver derives.

    Declaration

    Swift

    var directParameter: AnyObject?

    Objective-C

    @property(retain) id directParameter

    Parameters

    directParameter

    An object to be set as the direct parameter.

    Discussion

    You don’t normally override this method.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the command description for the command.

    Declaration

    Swift

    var commandDescription: NSScriptCommandDescription { get }

    Objective-C

    @property(readonly, retain) NSScriptCommandDescription *commandDescription

    Discussion

    Once a command is created, its command description is immutable.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • isWellFormed - isWellFormed Available in OS X v10.0 through OS X v10.9

    Returns a Boolean value indicating whether the receiver is well formed according to its command description.

    Declaration

    Objective-C

    - (BOOL)isWellFormed

    Discussion

    The method ensures that there is a description of the command and that the number of arguments and the types of non-specifier arguments conform to the command description.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.0 through OS X v10.9.

  • Returns the type descriptor that was put in the reply Apple event if the sender requested a reply, execution of the receiver completed, and an error number was set.

    Declaration

    Swift

    var scriptErrorExpectedTypeDescriptor: NSAppleEventDescriptor?

    Objective-C

    @property(retain) NSAppleEventDescriptor *scriptErrorExpectedTypeDescriptor

    Return Value

    A descriptor that specifies a type.

    Discussion

    When an error occurs during script command execution because an Apple event descriptor wasn’t of the expected type, and the sender requested a reply, Cocoa scripting returns a descriptor for the expected type in a reply Apple event. You can invoke setScriptErrorExpectedTypeDescriptor: to set this descriptor directly.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Returns the script error number, if any, associated with execution of the command.

    Declaration

    Swift

    var scriptErrorNumber: Int32

    Objective-C

    @property int scriptErrorNumber

    Discussion

    When you subclass NSScriptCommand or one of its subclasses, you shouldn’t need to override this method.

    For error conditions specific to your application you can define your own error return values. For some common errors, you may want to return error values defined in MacErrors.h, a header in CarbonCore.framework (a subframework of CoreServices.framework). Look for error constants that start with errAE. For example, errAEEventNotHandled indicates a handler wasn’t able to handle the Apple event.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the object descriptor that was put in the reply Apple event if the sender requested a reply, execution of the receiver completed, and an error number was set.

    Declaration

    Swift

    var scriptErrorOffendingObjectDescriptor: NSAppleEventDescriptor?

    Objective-C

    @property(retain) NSAppleEventDescriptor *scriptErrorOffendingObjectDescriptor

    Return Value

    A descriptor that specifies an object.

    Discussion

    When an error that occurs during script command execution is caused by a specific object, and the sender requested a reply, Cocoa scripting returns a descriptor for the offending object in a reply Apple event. You can invoke setScriptErrorOffendingObjectDescriptor: to set this descriptor directly.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Returns the script error string, if any, associated with execution of the command.

    Declaration

    Swift

    var scriptErrorString: String?

    Objective-C

    @property(copy) NSString *scriptErrorString

    Discussion

    When you subclass NSScriptCommand or one of its subclasses, you shouldn’t need to override this method.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Sets a descriptor for the expected type that will be put in the reply Apple event if the sender requested a reply, execution of the receiver completes, and an error number was set.

    Declaration

    Swift

    var scriptErrorExpectedTypeDescriptor: NSAppleEventDescriptor?

    Objective-C

    @property(retain) NSAppleEventDescriptor *scriptErrorExpectedTypeDescriptor

    Parameters

    errorExpectedTypeDescriptor

    A descriptor that specifies a type.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Sets a descriptor for an object that will be put in the reply Apple event if the sender requested a reply, execution of the receiver completes, and an error number was set.

    Declaration

    Swift

    var scriptErrorOffendingObjectDescriptor: NSAppleEventDescriptor?

    Objective-C

    @property(retain) NSAppleEventDescriptor *scriptErrorOffendingObjectDescriptor

    Parameters

    errorOffendingObjectDescriptor

    A descriptor that specifies an object that was responsible for an error.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Sets a script error number that is associated with the execution of the command and is returned in the reply Apple event, if a reply was requested by the sender.

    Declaration

    Swift

    var scriptErrorNumber: Int32

    Objective-C

    @property int scriptErrorNumber

    Parameters

    errorNumber

    An error number to associate with the command.

    Discussion

    If you override performDefaultImplementation and an error occurs, you should call this method to supply an appropriate error number. In fact, any script handler should call this method when an error occurs. The error number you supply is returned in the reply Apple event.

    Invoking setScriptErrorNumber: causes an error message to be displayed. To associate a specific error message with the error number, you invoke setScriptErrorString:. This make sense, for example, when you set an error number that is specific to your application, or when you can supply a specific and useful error message to the user.

    If setScriptErrorNumber: is invoked on an NSScriptCommand with multiple receivers, the command will stop sending command handling messages to more receivers.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Sets a script error string that is associated with execution of the command.

    Declaration

    Swift

    var scriptErrorString: String?

    Objective-C

    @property(copy) NSString *scriptErrorString

    Parameters

    errorString

    A string that describes an error.

    Discussion

    If you override performDefaultImplementation and an error occurs, you should call this method to supply a string that provides a useful explanation. In fact, any script handler should call this method when an error occurs.

    Calling this method alone does not cause an error message to be be displayed—you must also call setScriptErrorNumber: to supply an error number.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Suspends the execution of the receiver.

    Declaration

    Swift

    func suspendExecution()

    Objective-C

    - (void)suspendExecution

    Discussion

    Suspends the execution of the receiver only if the receiver is being executed in the current thread by Cocoa scripting's built-in Apple event handling (that is, the receiver would be returned by [NSScriptCommand currentCommand])—otherwise, does nothing. A matching invocation of resumeExecutionWithResult: must be made.

    Another command can execute while a command is suspended.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

  • If a successful, unmatched, invocation of suspendExecution has been made, resume the execution of the command.

    Declaration

    Swift

    func resumeExecutionWithResult(_ result: AnyObject?)

    Objective-C

    - (void)resumeExecutionWithResult:(id)result

    Discussion

    Resumes the execution of the command if a successful, unmatched, invocation of suspendExecution has been made—otherwise, does nothing. The value for result is dependent on the segment of command execution that was suspended:

    • If suspendExecution was invoked from within a command handler of one of the command's receivers, result is considered to be the return value of the handler. Unless the command has received a setScriptErrorNumber: message with a nonzero error number, execution of the command will continue and the command handlers of other receivers will be invoked.

    • If suspendExecution was invoked from within an override of performDefaultImplementation the result is treated as if it were the return value of the invocation of performDefaultImplementation.

    resumeExecutionWithResult: may be invoked in any thread, not just the one in which the corresponding invocation of suspendExecution occurred.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.3 and later.

  • NSScriptCommand uses the following error codes for general command execution problems:

    Declaration

    Swift

    var NSNoScriptError: Int { get } var NSReceiverEvaluationScriptError: Int { get } var NSKeySpecifierEvaluationScriptError: Int { get } var NSArgumentEvaluationScriptError: Int { get } var NSReceiversCantHandleCommandScriptError: Int { get } var NSRequiredArgumentsMissingScriptError: Int { get } var NSArgumentsWrongScriptError: Int { get } var NSUnknownKeyScriptError: Int { get } var NSInternalScriptError: Int { get } var NSOperationNotSupportedForKeyScriptError: Int { get } var NSCannotCreateScriptCommandError: Int { get }

    Objective-C

    enum { NSNoScriptError = 0, NSReceiverEvaluationScriptError, NSKeySpecifierEvaluationScriptError, NSArgumentEvaluationScriptError, NSReceiversCantHandleCommandScriptError, NSRequiredArgumentsMissingScriptError, NSArgumentsWrongScriptError, NSUnknownKeyScriptError, NSInternalScriptError, NSOperationNotSupportedForKeyScriptError, NSCannotCreateScriptCommandError };

    Constants

    • NSNoScriptError

      NSNoScriptError

      No error.

      Available in OS X v10.0 and later.

    • NSReceiverEvaluationScriptError

      NSReceiverEvaluationScriptError

      The object or objects specified by the direct parameter to a command could not be found.

      Available in OS X v10.0 and later.

    • NSKeySpecifierEvaluationScriptError

      NSKeySpecifierEvaluationScriptError

      The object or objects specified by a key (for commands that support key specifiers) could not be found.

      Available in OS X v10.0 and later.

    • NSArgumentEvaluationScriptError

      NSArgumentEvaluationScriptError

      The object specified by an argument could not be found.

      Available in OS X v10.0 and later.

    • NSReceiversCantHandleCommandScriptError

      NSReceiversCantHandleCommandScriptError

      The receivers don’t support the command sent to them.

      Available in OS X v10.0 and later.

    • NSRequiredArgumentsMissingScriptError

      NSRequiredArgumentsMissingScriptError

      An argument (or more than one argument) is missing.

      Available in OS X v10.0 and later.

    • NSArgumentsWrongScriptError

      NSArgumentsWrongScriptError

      An argument (or more than one argument) is of the wrong type or is otherwise invalid.

      Available in OS X v10.0 and later.

    • NSUnknownKeyScriptError

      NSUnknownKeyScriptError

      An unidentified error occurred; indicates an error in the scripting support of your application.

      Available in OS X v10.0 and later.

    • NSInternalScriptError

      NSInternalScriptError

      An unidentified internal error occurred; indicates an error in the scripting support of your application.

      Available in OS X v10.0 and later.

    • NSOperationNotSupportedForKeyScriptError

      NSOperationNotSupportedForKeyScriptError

      The implementation of a scripting command signaled an error.

      Available in OS X v10.0 and later.

    • NSCannotCreateScriptCommandError

      NSCannotCreateScriptCommandError

      Could not create the script command; an invalid or unrecognized Apple event was received.

      Available in OS X v10.0 and later.