[TOC] [Prev] [Next]

ITKInterp

Inherits From:
NSObject

Conforms To:
NSObject (NSObject)
NSCoding (ITKInterp)

Declared in: itkRuntime/ITKInterp.h

Class At a Glance:

Purpose

ITKInterp is an abstract class providing the generic functionality of an interpreter for some unspecified scripting language. Concrete subclasses of ITKInterp will override some of its methods in terms of the API for a specific scripting language. Each concrete instance of ITKInterp has its own private namespace for global variables and procedures.

Principle Attributes

Creation

InterfaceBuilder

- init

Designated initializer.

Commonly Used Methods

+ mainInterp

Returns the main interpreter instance for the class.
- scriptingLanguage

Returns an ITKScriptingLanguage conforming object that describes the language understood by the interpreter.
- commandWindow

Returns a window for communicating with the interpreter in shell-like fashion.
- sourceFile:

Makes the interpreter source a script file.
- evalString:global:

Makes the interpreter evaluate some string as a script and returns the result.
- setVariable:toValue:global:

Assigns a new value to one of the interpreter's variables.
- valueOfVariable:global:

Returns the value of some interpreter variable.
- enableJavaSupport

Makes Java accessible from the interpreter's scripting language, loading Java frameworks and creating a Java VM if necessary.
Getting the main interpreter instance
+ mainInterp
Getting meta information about the scripting language
- scriptingLanguage
Sourcing files
- sourceFile:
Evaluating scripts
- evalString:global:
- evalValue:global:
Scheduling evaluation of scripts
- evalString:afterDelay:
- evalString:afterDelay:inModes:
- evalString:withInterval:
- evalString:withInterval:inModes:
- evalString:afterThisEventOrdered:
- evalString:afterThisEventOrdered:inModes:
- evalString:afterEveryEventOrdered:
- evalString:afterEveryEventOrdered:inModes:
- evalStringWhenDeleted:
- removeTimedEval:
Accessing variables
- valueOfVariable:global:
- setVariable:toValue:global:
- unsetVariable:global:
- setPostsChangedNotifications:forVariable:global:
Java support
- enableJavaSupport
- enableJavaSupportIfNeeded
Command window
- commandWindow
- showCommandWindow:
- clearCommandWindow:
- commandWindowTitle
- commandPrompt
Access to lower level API
- nativeInterp

Class Methods

mainInterp

mainInterp

Returns the first concrete instance of ITKInterp created by the application, or nil. Implemented by concrete subclasses to return the first instance of that subclass (its main interpreter), creating one if none exists.

Instance Methods

clearCommandWindow:

- (void)clearCommandWindow:(id)sender

Target-action method that clears the contents of the command window's buffer.

commandPrompt

- (NSString *)commandPrompt

Returns the string that is to be used as the prompt in the interpreter's command window.

commandWindow

- (NSWindow *)commandWindow

Returns a window containing a shell-like user interface to interactively evaluate commands in the interpreter.

commandWindowTitle

- (NSString *)commandWindowTitle

Returns the string that is to be used as the title for the interpreter's command window.

enableJavaSupport

- (void)enableJavaSupport

Will add support for calling Java to the interpreter, loading Java frameworks and creating a Java virtual machine if necessary. Raises an exception if unsuccessful.

enableJavaSupportIfNeeded

- (void)enableJavaSupportIfNeeded

Conditionally calls enableJavaSupport, depending on the value of the preference setting Automatic Java Support. If set to None will do nothing; if set to Greedy will enable Java support; if set to Lazy will either enable it if a Java virtual machine already exists, or arrange for the interpreter to enable it automatically as soon as one gets created. Concrete subclasses of ITKInterp call this method at an appropriate point in their init method.

evalString:afterDelay:

- (id)evalString:(NSString *)string afterDelay:(NSTimeInterval)delay

Calls evalString:afterDelay:inModes: with a modes array containing just NSDefaultRunLoopMode.

evalString:afterDelay:inModes:

- (id)evalString:(NSString *)string afterDelay:(NSTimeInterval)delay inModes:(NSArray *)modes

Arranges for the interpreter to evaluate string as a script in its global scope when the time interval delay has passed and the default run loop is in one of the modes specified in the modes array. Returns some token object that can be used to cancel the request using removeTimedEval:

evalString:afterEveryEventOrdered:

- (id)evalString:(NSString *)string afterEveryEventOrdered:(unsigned)order

Calls evalString:afterEveryEventOrdered:inModes: with a modes array containing just NSDefaultRunLoopMode.

evalString:afterEveryEventOrdered:inModes:

- (id)evalString:(NSString *)string afterEveryEventOrdered:(unsigned)order inModes:(NSArray *)modes

Arranges for the interpreter to repeatedly evaluate string as a script in its global scope whenever the default run loop has completed an iteration in any of the modes specified in the modes array. Requests with a lower order value will be scheduled before requests with a higher order value. Returns some token object that can be used to cancel the request using removeTimedEval:

evalString:afterThisEventOrdered:

- (id)evalString:(NSString *)string afterThisEventOrdered:(unsigned)order

Calls evalString:afterThisEventOrdered:inModes: with a modes array containing just NSDefaultRunLoopMode.

evalString:afterThisEventOrdered:inModes:

- (id)evalString:(NSString *)string afterThisEventOrdered:(unsigned)order inModes:(NSArray *)modes

Arranges for the interpreter to evaluate string as a script in its global scope after the default run loop has completed an iteration in any of the modes specified in the modes array. Requests with a lower order value will be scheduled before requests with a higher order value. Returns some token object that can be used to cancel the request using removeTimedEval:

evalString:global:

- (ITKValue *)evalString:(NSString *)string global:(BOOL)global

Makes the interpreter evaluate string as a script and returns the result. If global is YES, the evaluation will be done in global scope, else in the currently executing scope. Any errors will result in an exception being raised.

See also: - evalValue:global:

evalValue:global:

- (ITKValue *)evalValue:(ITKValue *)value global:(BOOL)global

Makes the interpreter evaluate value as a script and returns the result. If global is YES, the evaluation will be done in global scope, else in the currently executing scope. Any errors will result in an exception being raised. Note that value's class must match the concrete ITKValue subclass that is used by the interpreter's scripting language, or undefined behaviour will result.

See also: - evalString:global:

evalString:withInterval:

- (id)evalString:(NSString *)string withInterval:(NSTimeInterval)interval

Calls evalString:withInterval:inModes: with a modes array containing just NSDefaultRunLoopMode.

evalString:withInterval:inModes:

- (id)evalString:(NSString *)string withInterval:(NSTimeInterval)interval inModes:(NSArray *)modes

Arranges for the interpreter to repeatedly evaluate string as a script in its global scope whenever the time interval interval has passed and the default run loop is in one of the modes specified in the modes array. Returns some token object that can be used to cancel the request using removeTimedEval:

evalStringWhenDeleted:

- (id)evalStringWhenDeleted:(NSString *)string

Arranges for the interpreter to evaluate string as a script in its global scope when it is dealloc'ed. Returns some token object that can be used to cancel the request using removeTimedEval:

nativeInterp

- (void *)nativeInterp

Implemented by concrete subclasses to return a "handle" to the interpreter that can be used with the scripting language's low level API.

removeTimedEval:

- (void)removeTimedEval:(id)token

When passed a token returned from one of evalString:afterDelay:inModes:, evalString:withInterval:inModes:, evalString:afterThisEventOrdered:inModes:, evalString:afterEveryEventOrdered:inModes:, or evalStringWhenDeleted:, will cancel the corresponding evaluation request. Will raise an exception if passed an invalid token.

scriptingLanguage

- (id <ITKScriptingLanguage>)scriptingLanguage

Implemented by concrete subclasses to return an ITKScriptingLanguage conforming object providing meta information about the language understood by the interpreter, e.g. the typical file extension for script files, or which concrete subclass of ITKInterp and ITKValue the language uses.

setPostsChangedNotifications:forVariable:global:

- (void)setPostsChangedNotifications:(BOOL)flag forVariable:(NSString *)variable global:(BOOL)global

If flag is YES, arranges for the interpreter to post an ITKInterpVariableDidChangeNotification anytime the variable variable changes its value. If flag is NO, disables posting of such notifications for that variable. If global is YES, looks for variable in the global scope, otherwise in the currently executing scope.

setVariable:toValue:global:

- (ITKValue *)setVariable:(NSString *)variable toValue:(ITKValue *)value global:(BOOL)global

Changes the value of the interpreter variable variable to value. If global is YES, looks for variable in the global scope, otherwise in the currently executing scope. Returns value after any necessary conversions to match the variable's type. Note that value's class must match the concrete ITKValue subclass that is used by the interpreter's scripting language, or undefined behaviour will result!

showCommandWindow:

- (void)showCommandWindow:(id)sender

Target-action method that makes the interpreter's command window the key window and brings it to the front.

sourceFile:

- (ITKValue *)sourceFile:(NSString *)file

Makes the interpreter source file as a script and returns the result of evaluating it. The scripting language's default script file extension will be appended automatically to file if not already present. Any errors will result in an exception being raised.

unsetVariable:global:

- (void)unsetVariable:(NSString *)variable global:(BOOL)global

Implemented by concrete subclasses to reset the interpreter variable variable to an uninitialized, "virgin" state. Depending on the scripting language, this could mean deleting the variable from the interpreter's name space, or simply assigning it some "undefined" value. If global is YES, looks for variable in the global scope, otherwise in the currently executing scope.

valueOfVariable:global:

- (ITKValue *)valueOfVariable:(NSString *)variable global:(BOOL)global

Returns the value of the interpreter variable variable. If global is YES, looks for variable in the global scope, otherwise in the currently executing scope.

The following notification is declared by ITKInterp and posted by concrete subclasses.

ITKInterpVariableDidChangeNotification

Notification Object
The concrete ITKInterp instance
userInfo Dictionary

Key Value
ITKVariableKey The name of the variable
ITKOldValueKey The value of the variable before the change
ITKNewValueKey The value of the variable after the change

This notification is broadcast whenever an interpreter variable that has been watched with setPostsChangedNotifications:forVariable:global: changes its value.



[TOC] [Prev] [Next]

Copyright © 1999, AAA+ Software. All rights reserved.