Next Page > Hide TOC

NSScriptObjectSpecifier Class Reference

Overview

NSScriptObjectSpecifier is the abstract superclass for classes that instantiate objects called “object specifiers.” An object specifier represents an AppleScript reference form, which is a natural-language expression such as words 10 through 20 or front document or words whose color is red.

The scripting system maps these words or phrases to attributes and relationships of scriptable objects. A reference form rarely occurs in isolation; usually a script statement consists of a series of reference forms preceded by a command and typically connected to each other by of, such as:

get words whose color is blue of paragraph 10 of front document

The expression words whose color is blue of paragraph 10 of front document specifies a location in the application's AppleScript object model—the objects the application makes available to scripters. The classes of objects in the object model often closely match the classes of actual objects in the application, but they are not required to. An object specifier locates objects in the running application that correspond to the specified object model objects.

Your application typically creates object specifiers when it implements the objectSpecifier method for its scriptable classes. That method is defined by the NSScriptObjectSpecifiers protocol.

It is unlikely that you would ever need to create your own subclass of NSScriptObjectSpecifier; the set of valid AppleScript reference forms is determined by Apple Computer and object specifier classes are already implemented for this set. If for some reason you do need to create a subclass, you must override the primitive method indicesOfObjectsByEvaluatingWithContainer:count: to return indices to the elements within the container whose values are matched with the child specifier’s key. In addition, you probably need to declare any special instance variables and implement an initializer that invokes super’s designated initializer, initWithContainerClassDescription:containerSpecifier:key:, and initializes these variables.

For a comprehensive treatment of object specifiers, including sample code, see Object Specifiers in Cocoa Scripting Guide.

Adopted Protocols

• – encodeWithCoder:

• – initWithCoder:

Tasks

Obtaining an Object Specifier for a Descriptor

• + objectSpecifierWithDescriptor:

Initializing an Object Specifier

• – initWithContainerClassDescription:containerSpecifier:key:
• – initWithContainerSpecifier:key:

Evaluating an Object Specifier

• – indicesOfObjectsByEvaluatingWithContainer:count:
• – objectsByEvaluatingSpecifier
• – objectsByEvaluatingWithContainers:

Getting, Testing, and Setting Containers

• – containerClassDescription
• – containerIsObjectBeingTested
• – containerIsRangeContainerObject
• – containerSpecifier
• – setContainerClassDescription:
• – setContainerIsObjectBeingTested:
• – setContainerSpecifier:
• – setContainerIsRangeContainerObject:

Getting and Setting Child References

• – childSpecifier
• – setChildSpecifier:

Getting and Setting Object Keys

• – key
• – keyClassDescription
• – setKey:

Getting Evaluation Errors

• – evaluationErrorSpecifier
• – evaluationErrorNumber
• – setEvaluationErrorNumber:

Getting a Descriptor for the Object Specifier

• – descriptor

Class Methods

objectSpecifierWithDescriptor:

Returns a new object specifier for an Apple event descriptor.

+ (NSScriptObjectSpecifier *)objectSpecifierWithDescriptor:(NSAppleEventDescriptor *)descriptor

Parameters

descriptor

An Apple event descriptor. The descriptor must have the type typeObjectSpecifier.

Return Value

An object specifier, or nil if an error occurs.

Discussion

If objectSpecifierWithDescriptor: is invoked and fails during the execution of a script command, information about the error that caused the failure is recorded in [NSScriptCommand currentCommand].

Availability

• Available in Mac OS X v10.5 and later.

Declared In

Instance Methods

childSpecifier

Returns the receiver’s child reference.

- (NSScriptObjectSpecifier *)childSpecifier

Return Value

The receiver’s child reference, that is, the object specifier evaluating to the object or objects that the receiver contains.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setChildSpecifier:

Declared In

containerClassDescription

Returns the class description of the object indicated by the receiver’s container specifier.

- (NSScriptClassDescription *)containerClassDescription

Return Value

The class description of the object indicated by the receiver’s container specifier.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setContainerClassDescription:

Declared In

containerIsObjectBeingTested

If the receiver’s container specifier is nil, returns a Boolean value that indicates whether the receiver’s container is the object involved in a specifier test.

- (BOOL)containerIsObjectBeingTested

Return Value

YES if the receiver’s container is the object involved in a specifier test, otherwise NO.

Discussion

An example of a specifier test is whose color is blue). If the returned value is YES, then the top-level object is the object being tested (that is, the specifier has no container specifier).

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – objectBeingTested (NSScriptExecutionContext)

Declared In

containerIsRangeContainerObject

If the receiver’s container specifier is nil, returns a Boolean value that indicates whether the container for the receiver contains the range of elements represented by an NSRangeSpecifier.

- (BOOL)containerIsRangeContainerObject

Return Value

YES if the container for the receiver contains the range of elements represented by an NSRangeSpecifier, otherwise NO.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setContainerIsRangeContainerObject:

Declared In

containerSpecifier

Returns the receiver’s container specifier.

- (NSScriptObjectSpecifier *)containerSpecifier

Return Value

The receiver’s container specifier, which is the object specifier that must be evaluated to provide a context for the evaluation of the receiver.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – childSpecifier
• – containerClassDescription
• – setContainerSpecifier:

Declared In

descriptor

Returns an Apple event descriptor that represents the receiver.

- (NSAppleEventDescriptor *)descriptor

Return Value

An Apple event descriptor of type typeObjectSpecifier.

Discussion

If the receiver was created with objectSpecifierWithDescriptor:, the passed-in descriptor is returned. Otherwise, a new descriptor is created and returned, autoreleased.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

evaluationErrorNumber

Returns the constant identifying the type of error that caused evaluation to fail.

- (NSInteger)evaluationErrorNumber

Return Value

The constant identifying the type of error that caused evaluation to fail.

Discussion

This error code could be associated with the receiver or any container specifier “above” the receiver. Possible return values are defined in “Constants.”

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – evaluationErrorSpecifier

Declared In

evaluationErrorSpecifier

Returns the object specifier in which an evaluation error occurred.

- (NSScriptObjectSpecifier *)evaluationErrorSpecifier

Return Value

The object specifier in which an evaluation error occurred.

Discussion

The object specifier failing to evaluate could be the receiver or any container specifier “above” the receiver.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – evaluationErrorNumber

Declared In

indicesOfObjectsByEvaluatingWithContainer:count:

This primitive method must be overridden by subclasses to return a pointer to an array of indices identifying objects in the key of a given container that are identified by the receiver of the message.

- (NSInteger *)indicesOfObjectsByEvaluatingWithContainer:(id)aContainer count:(NSInteger *)numRefs

Discussion

This primitive method must be overridden by subclasses to return a pointer to an array of indices identifying objects in the key of the container aContainer that are identified by the receiver of the message. The method uses key-value coding to obtain values based on the receiver’s key. It returns the number of such matching objects by indirection in numRefs. It returns nil directly and –1 via numRefs if all objects in the container (or the sole object) match the value of the receiver’s key. This method is invoked by objectsByEvaluatingWithContainers:. The default implementation returns nil directly and –1 indirectly via numRefs.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

initWithContainerClassDescription:containerSpecifier:key:

Returns an NSScriptObjectSpecifier object initialized with the given attributes.

- (id)initWithContainerClassDescription:(NSScriptClassDescription *)classDescription containerSpecifier:(NSScriptObjectSpecifier *)specifier key:(NSString *)key

Return Value

An NSScriptObjectSpecifier object initialized with container specifier specifier, key key, and the class description of the object specifier classDescription, derived from the value of the specifier’s key.

Discussion

You should never pass nil for the value of classDescription. The receiver’s child reference is set to nil.

This is the designated initializer for NSScriptObjectSpecifier.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

initWithContainerSpecifier:key:

Returns an NSScriptObjectSpecifier object initialized with a given container specifier and key.

- (id)initWithContainerSpecifier:(NSScriptObjectSpecifier *)specifier key:(NSString *)key

Return Value

An NSScriptObjectSpecifier object initialized with container specifier specifier and key key.

Discussion

The class description of the container is set automatically.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

key

Returns the key of the receiver.

- (NSString *)key

Return Value

The key of the receiver.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – keyClassDescription
• – setKey:

Related Sample Code

• Sketch-112

Declared In

keyClassDescription

Returns the class description of the objects specified by the receiver.

- (NSScriptClassDescription *)keyClassDescription

Return Value

The class description of the objects specified by the receiver.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – key
• – setKey:

Related Sample Code

• Sketch-112

Declared In

objectsByEvaluatingSpecifier

Returns the actual object represented by the nested series of object specifiers.

- (id)objectsByEvaluatingSpecifier

Return Value

The actual object represented by the nested series of object specifiers.

Discussion

Recursively obtains the next container in a nested series of object specifiers until it reaches the top-level container specifier (which is either an NSWhoseSpecifier or the application object), after which it begins evaluating each object specifier (objectsByEvaluatingWithContainers:) going in the opposite direction (top-level to innermost) as it unwinds from the stack. Returns the actual object represented by the nested series of object specifiers. Returns nil if a container specifier could not be evaluated or if no top-level container specifier could be found. Thus nil can be a valid value or can indicate an error; you can use evaluationErrorNumber to determine if and which error occurred and evaluationErrorSpecifier to find the container specifier responsible for the error. In the normal course of command processing, this method is invoked by an NSScriptCommand object’s evaluatedArguments and evaluatedReceivers methods, which take as message receiver the innermost object specifier.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – indicesOfObjectsByEvaluatingWithContainer:count:

Related Sample Code

• Sketch-112

Declared In

objectsByEvaluatingWithContainers:

Returns the actual object or objects specified by the receiver as evaluated in the context of given container object.

- (id)objectsByEvaluatingWithContainers:(id)containers

Return Value

The actual object or objects specified by the receiver as evaluated in the context of its container object or objects (containers).

Discussion

Invokes indicesOfObjectsByEvaluatingWithContainer:count: on self to get an array of pointers to indices of elements in containers that have values paired with the message receiver’s key. This method then uses key-value coding to obtain the object or objects associated with the key; it returns these objects or nil if there are no matching values in containers. If there are multiple matching values, they are returned in an NSArray; if matching values are nil, NSNull objects are substituted. If containers is an NSArray, the method recursively evaluates each element in the array and returns an NSArray with evaluated objects (including NSNulls) in their corresponding slots.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – objectsByEvaluatingSpecifier

Related Sample Code

• Sketch-112

Declared In

setChildSpecifier:

Sets the receiver’s child reference.

- (void)setChildSpecifier:(NSScriptObjectSpecifier *)child

Parameters

child

The receiver’s child reference.

Discussion

Do not invoke this method directly; it is automatically invoked by setContainerSpecifier:.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – childSpecifier

Declared In

setContainerClassDescription:

Sets the class description of the receiver’s container specifier to a given specifier.

- (void)setContainerClassDescription:(NSScriptClassDescription *)classDescription

Parameters

classDescription

The class description of the receiver’s container specifier.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – containerClassDescription

Declared In

setContainerIsObjectBeingTested:

Sets whether the receiver’s container should be an object involved in a filter reference or the top-level object.

- (void)setContainerIsObjectBeingTested:(BOOL)flag

Discussion

If the receiver’s container specifier is nil and flag is YES, sets the receiver’s container to be an object involved in a filter reference (for example, whose color is blue). If the receiver’s container specifier is nil and flag is NO, sets the receiver’s container to be the top-level object.

If flag is YES setContainerIsRangeContainerObject: should not also be invoked with an argument of YES.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – containerIsObjectBeingTested

Declared In

setContainerIsRangeContainerObject:

Sets whether the receiver’s container is to be the container for a range specifier or a top-level object.

- (void)setContainerIsRangeContainerObject:(BOOL)flag

Discussion

If the receiver’s container specifier is nil and flag is YES, sets the receiver’s container to be the container for a range specifier. If the receiver’s container specifier is nil and flag is NO, sets the receiver’s container to be the top-level object.

If flag is YES, setContainerIsObjectBeingTested: should not also be invoked with an argument of YES.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – containerIsRangeContainerObject

Declared In

setContainerSpecifier:

Sets the container specifier of the receiver.

- (void)setContainerSpecifier:(NSScriptObjectSpecifier *)objSpecifier

Parameters

objSpecifier

The container specifier for the receiver.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – containerSpecifier

Declared In

setEvaluationErrorNumber:

Sets the value of the evaluation error.

- (void)setEvaluationErrorNumber:(NSInteger)error

Parameters

error

The value for the evaluation error.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – evaluationErrorNumber

Declared In

setKey:

Sets the key of the receiver.

- (void)setKey:(NSString *)key

Parameters

key

The key for the receiver.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – key
• – keyClassDescription

Declared In

Constants

NSScriptObjectSpecifier—Specifier Evaluation Errors

NSScriptObjectSpecifier provides the following constants for error codes for specific problems evaluating specifiers:

enum {
   NSNoSpecifierError = 0,
   NSNoTopLevelContainersSpecifierError,
   NSContainerSpecifierError,
   NSUnknownKeySpecifierError,
   NSInvalidIndexSpecifierError,
   NSInternalSpecifierError,
   NSOperationNotSupportedForKeySpecifierError
};

Constants

NSNoSpecifierError

No error encountered.

Available in Mac OS X v10.0 and later.

Declared in NSScriptObjectSpecifiers.h.

NSNoTopLevelContainersSpecifierError

Someone called evaluate with nil.

Available in Mac OS X v10.0 and later.

Declared in NSScriptObjectSpecifiers.h.

NSContainerSpecifierError

Error evaluating container specifier.

Available in Mac OS X v10.0 and later.

Declared in NSScriptObjectSpecifiers.h.

NSUnknownKeySpecifierError

Receivers do not understand the key.

Available in Mac OS X v10.0 and later.

Declared in NSScriptObjectSpecifiers.h.

NSInvalidIndexSpecifierError

Index out of bounds.

Available in Mac OS X v10.0 and later.

Declared in NSScriptObjectSpecifiers.h.

NSInternalSpecifierError

Other internal error.

Available in Mac OS X v10.0 and later.

Declared in NSScriptObjectSpecifiers.h.

NSOperationNotSupportedForKeySpecifierError

Attempt made to perform an unsupported operation on some key.

Available in Mac OS X v10.0 and later.

Declared in NSScriptObjectSpecifiers.h.

Declared In

Next Page > Hide TOC