OOJSScript Class Reference

#include <OOJSScript.h>

Inheritance diagram for OOJSScript:

Collaboration diagram for OOJSScript:

Instance Methods
(id)	- initWithPath:properties:
(BOOL)	- callMethod:inContext:withArguments:count:result:
(id)	- propertyWithID:inContext:
(BOOL)	- setProperty:withID:inContext:
(BOOL)	- defineProperty:withID:inContext:
(id)	- propertyNamed:
(BOOL)	- setProperty:named:
(BOOL)	- defineProperty:named:
(void)	- dealloc [implementation]
(NSString *)	- oo_jsClassName [implementation]
(NSString *)	- descriptionComponents [implementation]
(void)	- javaScriptEngineWillReset: [implementation]
(id)	- weakRetain [implementation]
(void)	- weakRefDied: [implementation]
(NSString *)	- scriptDescription [implementation]
(void)	- runWithTarget: [implementation]
(jsval)	- oo_jsValueInContext: [implementation]
(NSString *)	- scriptNameFromPath: [implementation]
(NSDictionary *)	- defaultPropertiesFromPath: [implementation]
Instance Methods inherited from OOScript
(NSString *)	- name
(NSString *)	- version
(NSString *)	- displayName
(BOOL)	- requiresTickle
Instance Methods inherited from <OOWeakReferenceSupport>
(id)	- OO_RETURNS_RETAINED

Class Methods
(id)	+ scriptWithPath:properties:
(OOJSScript *)	+ currentlyRunningScript
(NSArray *)	+ scriptStack
(void)	+ pushScript:
(void)	+ popScript:
Class Methods inherited from OOScript
(NSArray *)	+ worldScriptsAtPath:
(NSArray *)	+ scriptsFromFileNamed:
(NSArray *)	+ scriptsFromList:
(NSArray *)	+ scriptsFromFileAtPath:
(id)	+ jsScriptFromFileNamed:properties:
(id)	+ jsAIScriptFromFileNamed:properties:

Private Attributes
JSObject *	_jsSelf
NSString *	name
NSString *	description
NSString *	version
NSString *	filePath
OOWeakReference *	weakSelf

Detailed Description

Definition at line 31 of file OOJSScript.h.

Method Documentation

callMethod:inContext:withArguments:count:result:

- (BOOL) callMethod:		(jsid)	methodID
inContext:		(JSContext *)	context
withArguments:		(jsval *)	argv
count:		(intN)	argc
result:		(jsval *)	outResult

Reimplemented from OOScript.

Definition at line 55 of file OOJSScript.m.

                   :(jsid)methodID
          inContext:(JSContext *)context
      withArguments:(jsval *)argv count:(intN)argc
             result:(jsval *)outResult
{
    NSParameterAssert(name != NULL && (argv != NULL || argc == 0) && context != NULL && JS_IsInRequest(context));
    if (_jsSelf == NULL)  return NO;
    
    JSObject                *root = NULL;
    BOOL                    OK = NO;
    jsval                   method;
    jsval                   ignoredResult = JSVAL_VOID;
    
    if (outResult == NULL)  outResult = &ignoredResult;
    OOJSAddGCObjectRoot(context, &root, "OOJSScript method root");
    
    if (EXPECT(JS_GetMethodById(context, _jsSelf, methodID, &root, &method) && !JSVAL_IS_VOID(method)))
    {
#ifndef NDEBUG
        if (JS_IsExceptionPending(context))
        {
            OOLog(@"script.internalBug", @"Exception pending on context before calling method in %s, clearing. This is an internal error, please report it.", __PRETTY_FUNCTION__);
            JS_ClearPendingException(context);
        }
        
        OOLog(@"script.javaScript.call", @"Calling [%@].%@()", [self name], OOStringFromJSID(methodID));
        OOLogIndentIf(@"script.javaScript.call");
#endif
        
        // Push self on stack of running scripts.
        RunningStack stackElement =
        {
            .back = sRunningStack,
            .current = self
        };
        sRunningStack = &stackElement;
        
        // Call the method.
        OOJSStartTimeLimiter();
        OK = JS_CallFunctionValue(context, _jsSelf, method, argc, argv, outResult);
        OOJSStopTimeLimiter();
        
        if (JS_IsExceptionPending(context))
        {
            JS_ReportPendingException(context);
            OK = NO;
        }
        
        // Pop running scripts stack
        sRunningStack = stackElement.back;
        
#ifndef NDEBUG
        OOLogOutdentIf(@"script.javaScript.call");
#endif
    }
    
    JS_RemoveObjectRoot(context, &root);
    
    return OK;
}

currentlyRunningScript

+ (OOJSScript *) currentlyRunningScript

Definition at line 55 of file OOJSScript.m.

{
    if (sRunningStack == NULL)  return NULL;
    return sRunningStack->current;
}

Referenced by OOJSGuiScreenKeyDefinition::callback, OOJSInterfaceDefinition::callback, OOJSPopulatorDefinition::callback, MissionRunScreen(), MissionSetInstructionsInternal(), ReportJSError(), SystemInfoSetPropertyMethod(), SystemInfoStaticSetInterstellarProperty(), and SystemSetProperty().

Here is the caller graph for this function:

dealloc

- (void) dealloc

implementation

Definition at line 55 of file OOJSScript.m.

{
    [[NSNotificationCenter defaultCenter] removeObserver:self
                                                    name:kOOJavaScriptEngineWillResetNotification
                                                  object:[OOJavaScriptEngine sharedEngine]];
    
    DESTROY(name);
    DESTROY(description);
    DESTROY(version);
    DESTROY(filePath);
    
    if (_jsSelf != NULL)
    {
        JSContext *context = OOJSAcquireContext();
        
        OOJSObjectWrapperFinalize(context, _jsSelf);    // Release weakref to self
        JS_RemoveObjectRoot(context, &_jsSelf);         // Unroot jsSelf
        
        OOJSRelinquishContext(context);
    }
    
    [weakSelf weakRefDrop];
    
    [super dealloc];
}

defaultPropertiesFromPath:

- (NSDictionary *) defaultPropertiesFromPath: (NSString *) path

implementation

Provided by category OOJSScript(OOPrivate).

Definition at line 55 of file OOJSScript.m.

                                            :(NSString *)path
{
    // remove file name, remove OXP subfolder, add manifest.plist
    NSString *manifestPath = [[[path stringByDeletingLastPathComponent] stringByDeletingLastPathComponent] stringByAppendingPathComponent:@"manifest.plist"];
    NSDictionary *manifest = OODictionaryFromFile(manifestPath);
    NSMutableDictionary *properties = [NSMutableDictionary dictionaryWithCapacity:3];
    /* __oolite.tmp.* is allocated for OXPs without manifests. Its
     * values are meaningless and shouldn't be used here */
    if (manifest != nil && ![[manifest oo_stringForKey:kOOManifestIdentifier] hasPrefix:@"__oolite.tmp."])
    {
        if ([manifest objectForKey:kOOManifestVersion] != nil)
        {
            [properties setObject:[manifest oo_stringForKey:kOOManifestVersion] forKey:@"version"];
        }
        if ([manifest objectForKey:kOOManifestIdentifier] != nil)
        {
            // used for system info
            [properties setObject:[manifest oo_stringForKey:kOOManifestIdentifier] forKey:kLocalManifestProperty];
        }
        if ([manifest objectForKey:kOOManifestAuthor] != nil)
        {
            [properties setObject:[manifest oo_stringForKey:kOOManifestAuthor] forKey:@"author"];
        }
        if ([manifest objectForKey:kOOManifestLicense] != nil)
        {
            [properties setObject:[manifest oo_stringForKey:kOOManifestLicense] forKey:@"license"];
        }
    }
    return properties;
}

defineProperty:named:

- (BOOL) defineProperty:		(id)	value
named:		(NSString *)	name

Definition at line 55 of file OOJSScript.m.

                       :(id)value named:(NSString *)propName
{
    if (value == nil || propName == nil)  return NO;
    if (_jsSelf == NULL)  return NO;
    
    JSContext *context = OOJSAcquireContext();
    BOOL result = [self defineProperty:value withID:OOJSIDFromString(propName) inContext:context];
    OOJSRelinquishContext(context);
    
    return result;
}

defineProperty:withID:inContext:

- (BOOL) defineProperty:		(id)	value
withID:		(jsid)	propID
inContext:		(JSContext *)	context

Definition at line 55 of file OOJSScript.m.

                       :(id)value withID:(jsid)propID inContext:(JSContext *)context
{
    NSParameterAssert(context != NULL && JS_IsInRequest(context));
    if (_jsSelf == NULL)  return NO;
    
    jsval jsValue = OOJSValueFromNativeObject(context, value);
    return JS_DefinePropertyById(context, _jsSelf, propID, jsValue, NULL, NULL, OOJS_PROP_READONLY);
}

descriptionComponents

- (NSString *) descriptionComponents

implementation

Reimplemented from OOScript.

Definition at line 55 of file OOJSScript.m.

{
    if (_jsSelf != NULL)  return [super descriptionComponents];
    else  return @"invalid script";
}

initWithPath:properties:

- (id) initWithPath:		(NSString *)	path
properties:		(NSDictionary *)	properties

Definition at line 55 of file OOJSScript.m.

                   :(NSString *)path properties:(NSDictionary *)properties
{
    JSContext               *context = NULL;
    NSString                *problem = nil;     // Acts as error flag.
    JSScript                *script = NULL;
    JSObject                *scriptObject = NULL;
    jsval                   returnValue = JSVAL_VOID;
    NSEnumerator            *keyEnum = nil;
    NSString                *key = nil;
    id                      property = nil;
    
    self = [super init];
    if (self == nil) problem = @"allocation failure";
    else
    {
        context = OOJSAcquireContext();
        
        if (JS_IsExceptionPending(context))
        {
            JS_ClearPendingException(context);
            OOLogERR(@"script.javaScript.load.waitingException", @"Prior to loading script %@, there was a pending JavaScript exception, which has been cleared. This is an internal error, please report it.", path);
        }
        
        // Set up JS object
        if (!problem)
        {
            _jsSelf = JS_NewObject(context, &sScriptClass, sScriptPrototype, NULL);
            if (_jsSelf == NULL) problem = @"allocation failure";
        }
        
        if (!problem && !OOJSAddGCObjectRoot(context, &_jsSelf, "Script object"))
        {
            problem = @"could not add JavaScript root object";
        }
        
        if (!problem && !OOJSAddGCObjectRoot(context, &scriptObject, "Script GC holder"))
        {
            problem = @"could not add JavaScript root object";
        }
        
        if (!problem)
        {
            if (!JS_SetPrivate(context, _jsSelf, OOConsumeReference([self weakRetain])))
            {
                problem = @"could not set private backreference";
            }
        }
        
        // Push self on stack of running scripts.
        RunningStack stackElement =
        {
            .back = sRunningStack,
            .current = self
        };
        sRunningStack = &stackElement;
        
        filePath = [path retain];
        
        if (!problem)
        {
            OOLog(@"script.javaScript.willLoad", @"About to load JavaScript %@", path);
            script = LoadScriptWithName(context, path, _jsSelf, &scriptObject, &problem);
        }
        OOLogIndentIf(@"script.javaScript.willLoad");
        
        // Set default properties from manifest.plist
        NSDictionary *defaultProperties = [self defaultPropertiesFromPath:path];
        for (keyEnum = [defaultProperties keyEnumerator]; (key = [keyEnum nextObject]); )
        {
            if ([key isKindOfClass:[NSString class]])
            {
                property = [defaultProperties objectForKey:key];
                if ([key isEqualToString:kLocalManifestProperty])
                {
                    // this must not be editable
                    [self defineProperty:property named:key];
                }
                else
                {
                    // can be overwritten by script itself
                    [self setProperty:property named:key];
                }
            }
        }
 
        // Set properties. (read-only)
        if (!problem && properties != nil)
        {
            for (keyEnum = [properties keyEnumerator]; (key = [keyEnum nextObject]); )
            {
                if ([key isKindOfClass:[NSString class]])
                {
                    property = [properties objectForKey:key];
                    [self defineProperty:property named:key];
                }
            }
        }
        
        /*  Set initial name (in case of script error during initial run).
            The "name" ivar is not set here, so the property can be fetched from JS
            if we fail during setup. However, the "name" ivar is set later so that
            the script object can't be renamed after the initial run. This could
            probably also be achieved by fiddling with JS property attributes.
        */
        jsid nameID = OOJSID("name");
        [self setProperty:[self scriptNameFromPath:path] withID:nameID inContext:context];
        
        // Run the script (allowing it to set up the properties we need, as well as setting up those event handlers)
        if (!problem)
        {
            OOJSStartTimeLimiterWithTimeLimit(kOOJSLongTimeLimit);
            if (!JS_ExecuteScript(context, _jsSelf, script, &returnValue))
            {
                problem = @"could not run script";
            }
            OOJSStopTimeLimiter();
            
            // We don't need the script any more - the event handlers hang around as long as the JS object exists.
            JS_DestroyScript(context, script);
        }
        
        JS_RemoveObjectRoot(context, &scriptObject);
        
        sRunningStack = stackElement.back;
        
        if (!problem)
        {
            // Get display attributes from script
            DESTROY(name);
            name = [StrippedName([[self propertyWithID:nameID inContext:context] description]) copy];
            if (name == nil)
            {
                name = [[self scriptNameFromPath:path] retain];
                [self setProperty:name withID:nameID inContext:context];
            }
            
            version = [[[self propertyWithID:OOJSID("version") inContext:context] description] copy];
            description = [[[self propertyWithID:OOJSID("description") inContext:context] description] copy];
            
            OOLog(@"script.javaScript.load.success", @"Loaded JavaScript: %@ -- %@", [self displayName], description ? description : (NSString *)@"(no description)");
        }
        
        OOLogOutdentIf(@"script.javaScript.willLoad");
        
        DESTROY(filePath);  // Only used for error reporting during startup.
    }
    
    if (problem)
    {
        OOLog(@"script.javaScript.load.failed", @"***** Error loading JavaScript script %@ -- %@", path, problem);
        JS_ReportPendingException(context);
        DESTROY(self);
    }
    
    OOJSRelinquishContext(context);
    
    if (self != nil)
    {
        [[NSNotificationCenter defaultCenter] addObserver:self
                                                 selector:@selector(javaScriptEngineWillReset:)
                                                     name:kOOJavaScriptEngineWillResetNotification
                                                   object:[OOJavaScriptEngine sharedEngine]];
    }
    
    return self;
}

javaScriptEngineWillReset:

- (void) javaScriptEngineWillReset: (NSNotification *) notification

implementation

Definition at line 55 of file OOJSScript.m.

                                  :(NSNotification *)notification
{
    // All scripts become invalid when the JS engine resets.
    if (_jsSelf != NULL)
    {
        _jsSelf = NULL;
        JSContext *context = OOJSAcquireContext();
        JS_RemoveObjectRoot(context, &_jsSelf);
        OOJSRelinquishContext(context);
    }
}

oo_jsClassName

- (NSString *) oo_jsClassName

implementation

Definition at line 55 of file OOJSScript.m.

{
    return @"Script";
}

oo_jsValueInContext:

- (jsval) oo_jsValueInContext: (JSContext *) context

implementation

Definition at line 55 of file OOJSScript.m.

                            :(JSContext *)context
{
    if (_jsSelf == NULL)  return JSVAL_VOID;
    return OBJECT_TO_JSVAL(_jsSelf);
}

popScript:

+ (void) popScript:

(OOJSScript *)

script

Definition at line 55 of file OOJSScript.m.

                 :(OOJSScript *)script
{
    RunningStack            *element = NULL;
    
    assert(sRunningStack->current == script);
    
    element = sRunningStack;
    sRunningStack = sRunningStack->back;
    free(element);
}

Referenced by MissionRunCallback().

Here is the caller graph for this function:

propertyNamed:

- (id) propertyNamed:

(NSString *)

name

Definition at line 55 of file OOJSScript.m.

                    :(NSString *)propName
{
    if (propName == nil)  return nil;
    if (_jsSelf == NULL)  return nil;
    
    JSContext *context = OOJSAcquireContext();
    id result = [self propertyWithID:OOJSIDFromString(propName) inContext:context];
    OOJSRelinquishContext(context);
    
    return result;
}

Referenced by SystemInfoSetPropertyMethod(), SystemInfoStaticSetInterstellarProperty(), and SystemSetProperty().

Here is the caller graph for this function:

propertyWithID:inContext:

- (id) propertyWithID:		(jsid)	propID
inContext:		(JSContext *)	context

Definition at line 55 of file OOJSScript.m.

                     :(jsid)propID inContext:(JSContext *)context
{
    NSParameterAssert(context != NULL && JS_IsInRequest(context));
    if (_jsSelf == NULL)  return nil;
    
    jsval jsValue = JSVAL_VOID;
    if (JS_GetPropertyById(context, _jsSelf, propID, &jsValue))
    {
        return OOJSNativeObjectFromJSValue(context, jsValue);
    }
    return nil;
}

pushScript:

+ (void) pushScript:

(OOJSScript *)

script

Definition at line 55 of file OOJSScript.m.

                  :(OOJSScript *)script
{
    RunningStack            *element = NULL;
    
    element = malloc(sizeof *element);
    if (element == NULL)  exit(EXIT_FAILURE);
    
    element->back = sRunningStack;
    element->current = script;
    sRunningStack = element;
}

Referenced by MissionRunCallback().

Here is the caller graph for this function:

runWithTarget:

- (void) runWithTarget: (Entity *) target

implementation

Reimplemented from OOScript.

Definition at line 55 of file OOJSScript.m.

                     :(Entity *)target
{
    
}

scriptDescription

- (NSString *) scriptDescription

implementation

Reimplemented from OOScript.

Definition at line 55 of file OOJSScript.m.

{
    return description;
}

scriptNameFromPath:

- (NSString *) scriptNameFromPath: (NSString *) path

implementation

Provided by category OOJSScript(OOPrivate).

Definition at line 55 of file OOJSScript.m.

                                :(NSString *)path
{
    NSString        *lastComponent = nil;
    NSString        *truncatedPath = nil;
    NSString        *theName = nil;
    
    if (path == nil) theName = [NSString stringWithFormat:@"%p", self];
    else
    {
        lastComponent = [path lastPathComponent];
        if (![lastComponent hasPrefix:@"script."]) theName = lastComponent;
        else
        {
            truncatedPath = [path stringByDeletingLastPathComponent];
            if (NSOrderedSame == [[truncatedPath lastPathComponent] caseInsensitiveCompare:@"Config"])
            {
                truncatedPath = [truncatedPath stringByDeletingLastPathComponent];
            }
            if (NSOrderedSame == [[truncatedPath pathExtension] caseInsensitiveCompare:@"oxp"])
            {
                truncatedPath = [truncatedPath stringByDeletingPathExtension];
            }
            
            lastComponent = [truncatedPath lastPathComponent];
            theName = lastComponent;
        }
    }
    
    if (0 == [theName length]) theName = path;
    
    return StrippedName([theName stringByAppendingString:@".anon-script"]);
}

scriptStack

+ (NSArray *) scriptStack

Definition at line 55 of file OOJSScript.m.

{
    NSMutableArray          *result = nil;
    
    result = [NSMutableArray array];
    AddStackToArrayReversed(result, sRunningStack);
    return result;
}

scriptWithPath:properties:

+ (id) scriptWithPath:		(NSString *)	path
properties:		(NSDictionary *)	properties

Definition at line 55 of file OOJSScript.m.

                     :(NSString *)path properties:(NSDictionary *)properties
{
    return [[[self alloc] initWithPath:path properties:properties] autorelease];
}

Referenced by OOScript::descriptionComponents.

Here is the caller graph for this function:

setProperty:named:

- (BOOL) setProperty:		(id)	value
named:		(NSString *)	name

Definition at line 55 of file OOJSScript.m.

                    :(id)value named:(NSString *)propName
{
    if (value == nil || propName == nil)  return NO;
    if (_jsSelf == NULL)  return NO;
    
    JSContext *context = OOJSAcquireContext();
    BOOL result = [self setProperty:value withID:OOJSIDFromString(propName) inContext:context];
    OOJSRelinquishContext(context);
    
    return result;
}

setProperty:withID:inContext:

- (BOOL) setProperty:		(id)	value
withID:		(jsid)	propID
inContext:		(JSContext *)	context

Definition at line 55 of file OOJSScript.m.

                    :(id)value withID:(jsid)propID inContext:(JSContext *)context
{
    NSParameterAssert(context != NULL && JS_IsInRequest(context));
    if (_jsSelf == NULL)  return NO;
    
    jsval jsValue = OOJSValueFromNativeObject(context, value);
    return JS_SetPropertyById(context, _jsSelf, propID, &jsValue);
}

weakRefDied:

- (void) weakRefDied: (OOWeakReference *) weakRef

implementation

Reimplemented from <OOWeakReferenceSupport>.

Definition at line 55 of file OOJSScript.m.

                    :(OOWeakReference *)weakRef
{
    if (weakRef == weakSelf)  weakSelf = nil;
}

weakRetain

- (id) weakRetain

implementation

Definition at line 55 of file OOJSScript.m.

{
    if (weakSelf == nil)  weakSelf = [OOWeakReference weakRefWithObject:self];
    return [weakSelf retain];
}

Referenced by OOJSGuiScreenKeyDefinition::callback, OOJSInterfaceDefinition::callback, OOJSPopulatorDefinition::callback, and ReportJSError().

Here is the caller graph for this function:

Member Data Documentation

_jsSelf

- (JSObject*) _jsSelf

private

Definition at line 35 of file OOJSScript.h.

description

- (NSString*) description

private

Definition at line 38 of file OOJSScript.h.

filePath

- (NSString*) filePath

private

Definition at line 40 of file OOJSScript.h.

name

- (NSString *) name

private

Definition at line 37 of file OOJSScript.h.

Referenced by MissionSetInstructionsInternal().

version

- (NSString *) version

private

Definition at line 39 of file OOJSScript.h.

weakSelf

- (OOWeakReference*) weakSelf

private

Definition at line 42 of file OOJSScript.h.

---

The documentation for this class was generated from the following files:

• src/Core/Scripting/OOJSScript.h
• src/Core/Scripting/OOJSScript.m