JavaScriptCore/bindings/objc/WebScriptObject.h

/*
    Copyright (C) 2004 Apple Computer, Inc. All rights reserved.    
    
    Public header file.
 */

#import <Foundation/Foundation.h>

// NSObject (WebScripting) ----------------------------------------------------- 

/*
    The methods in WebScripting are optionally implemented by classes whose
    interfaces are exported (wrapped) to a web scripting environment.  The 
    scripting environment currently supported by WebKit uses the JavaScript
    language.
    
    Instances automatically reflect their interfaces in the scripting environment.  This
    automatic reflection can be overriden using the class methods defined in the WebScripting
    informal protocol.
    
    Access to the attributes of an instance is done using KVC. Specifically the following
    KVC methods:
	
        - (void)setValue:(id)value forKey:(NSString *)key
        - (id)valueForKey:(NSString *)key
	
    Instances may also intercept property set/get operations and method invocations that are
    made by the scripting environment, but not reflected.  This is done using the KVC
    methods:

        - (void)setValue:(id)value forUndefinedKey:(NSString *)key
        - (id)valueForUndefinedKey:(NSString *)key
    
    If clients need to raise an exception in the script environment
    they can call [WebScriptObject throwException:].  Note that throwing an
    exception using this method will only succeed if the method that throws the exception
    is being called within the scope of a script invocation.
    
    By default all attributes, as defined by KVC, will be exposed.  However, a
    class may further exclude properties that they do not want to expose
    to web script.
	
    Not all methods are exposed.  Only those methods whose parameters and return
    type meets the export criteria will exposed.  Valid types are ObjectiveC instances
    and scalars.  Other types are not allowed.  Classes may further exclude method
    that they do not want to expose.
    
    Types will be converted to appropriate types in the scripting environment.
    After any KVC coercion occurs the ObjectiveC types will converted to a type
    appropriate for the script environment.  For JavaScript NSNumber will be
    converted to numbers.  NSString will be converted to strings.  NSArray will
    be mapped to a special read-only array.  NSNull will be converted to null.  
    WebUndefined will be converted to undefined.  WebScriptObjects will be unwrapped.
    Instances of other classes will be wrapped when passed to the script environment
    and unwrapped when returned to ObjectiveC.  Similar conversion happens in the
    other direction.
*/
@interface NSObject (WebScripting)

/*!
    @method webScriptNameForSelector:
    @param aSelector The selector that will be exposed to the script environment.
    @discussion Use the returned string as the exported name for the selector
    in the script environment.  It is the responsibility of the class to ensure
    uniqueness of the returned name.  If nil is returned or this
    method is not implemented the default name for the selector will
    be used.  The default name concatenates the components of the
    ObjectiveC selector name and replaces ':' with '_'.  '_' characters
    are escaped with an additional '$', i.e. '_' becomes "$_".  '$' are
    also escaped, i.e.
        ObjectiveC name         Default script name
        moveTo::                move__
        moveTo_                 moveTo$_
        moveTo$_                moveTo$$$_
    @result Returns the name to be used to represent the specificed selector in the
    scripting environment.
*/
+ (NSString *)webScriptNameForSelector:(SEL)aSelector;

/*!
    @method isSelectorExcludedFromWebScript:
    @param aSelect  The selector the will be exposed to the script environment.
    @discussion	Return YES to prevent the selector appearing in the script
    environment.  Return NO to expose the selector in the script environment.
    If this method is not implemented on the class all the selector that match
    the export criteria will be exposed.
    @result Returns YES to hide the selector, NO to expose the selector.
*/
+ (BOOL)isSelectorExcludedFromWebScript:(SEL)aSelector;

/*!
    @method webScriptNameForKey:
    @param name The name of the instance variable that will be exposed to the
    script enviroment.  Only that properties that meet the export criteria will
    be exposed.
    @discussion Provide an alternate name for a property.
    @result Returns the name to be used to represent the specificed property in the
    scripting environment.
*/
+ (NSString *)webScriptNameForKey:(const char *)name;

/*!
    @method isKeyExcludedFromWebScript:
    @param name The name of the instance variable that will be exposed to the
    scrip environment.
    @discussion Return YES to exclude the property from visibility in the script environement.
    Return NO to expose the instance varible to the script environment.
    @result Returns YES to hide the property, NO to expose the property.
*/
+ (BOOL)isKeyExcludedFromWebScript:(const char *)name;

/*!
    @method invokeUndefinedMethodFromWebScript:withArguments:
    @param name The name of the method to invoke.
    @param args The args to pass the method.
    @discussion If a script attempt to invoke a method that is not an exposed
    method, scriptInvocation:withArgs: will be called.
    @result The return value of the invocation.  The value will be converted as appropriate
    for the script environment.
*/
- (id)invokeUndefinedMethodFromWebScript:(NSString *)name withArguments:(NSArray *)args;

/*!
    @method invokeDefaultMethodWithArguments:
    @param args The args to pass the method.
    @discussion If a script attempts to invoke a method on an exposed object
    directly this method will be called.
*/
- (id)invokeDefaultMethodWithArguments:(NSArray *)args;

/*!
    @method finalizeForWebScript
    @discussion finalizeForScript is called on objects exposed to the script
    environment just before the script environment releases the object.  After calls to
    finalizeForWebScript the object will no longer be referenced by the script environment.
    Further, any references to WebScriptObjects made by the exposed object will
    be invalid and have undefined consequences.
*/
- (void)finalizeForWebScript;

@end


// WebScriptObject -------------------------------------------------- 

@class WebScriptObjectPrivate;

/*!
    @class WebScriptObject
    @discussion WebScriptObjects are used to wrap script objects passed from
    script environments to ObjectiveC.  WebScriptObjects cannot be created
    directly.  In normal uses of WebKit, you gain access to the script
    environment using the "windowScriptObject" method on WebView.
    
    The following KVC methods are commonly used to access properties of the
    WebScriptObject:
    
	- (void)setValue:(id)value forKey:(NSString *)key
	- (id)valueForKey:(NSString *)key
	
	As it possible to remove attributes from web script objects the following
	additional method augments the basic KVC methods:
	
	- (void)removeWebScriptKey:(NSString *)name;
	
	Also the sparse array access allowed in web script objects doesn't map well to NSArray, so
	the following methods can be used to access index based properties:
	
	- (id)webScriptValueAtIndex:(unsigned int)index;
	- (void)setWebScriptValueAtIndex:(unsigned int)index value:(id)value;
*/
@interface WebScriptObject : NSObject
{
    WebScriptObjectPrivate *_private;
}

/*!
    @method throwException:
    @discussion Throws an exception in the current script execution context.
    @result Either NO if an exception could not be raised, YES otherwise.
*/
+ (BOOL)throwException:(NSString *)exceptionMessage;

/*!
    @method callWebScriptMethod:withArguments:
    @param name The name of the method to call in the script environment.
    @param args The arguments to pass to the script environment.
    @discussion Calls the specified method in the script environment using the
    specified arguments.
    @result Returns the result of calling the script method.
*/
- (id)callWebScriptMethod:(NSString *)name withArguments:(NSArray *)args;

/*!
    @method evaluateWebScript:
    @param script The script to execute in the target script environment.
    @discussion The script will be executed in the target script environment.  The format
    of the script is dependent of the target script environment.
    @result Returns the result of evaluating the script in the script environment.
*/
- (id)evaluateWebScript:(NSString *)script;

/*!
    @method removeWebScriptKey:
    @param name The name of the property to remove.
    @discussion Removes the property from the object in the script environment.
*/
- (void)removeWebScriptKey:(NSString *)name;

/*!
    @method toString
    @discussion Converts the target object to a string representation.  The coercion
    of non string objects type is dependent on the script environment.
    @result Returns the string representation of the object.
*/
- (NSString *)stringRepresentation;

/*!
    @method propertyAtIndex:
    @param index The index of the property to return.  Index based access is dependent 
    @discussion Gets the value of the property at the specified index.
    @result The value of the property.
*/
- (id)webScriptValueAtIndex:(unsigned int)index;

/*!
    @method setPropertyAtIndex:value:
    @param index The index of the property to set.
    @param value The value of the property to set.
    @discussion Sets the property value at the specified index.
*/
- (void)setWebScriptValueAtIndex:(unsigned int)index value:(id)value;

/*!
    @method setException:
    @param description The description of the exception.
    @discussion Raises an exception in the script environment in the context of the
    current object.
*/
- (void)setException: (NSString *)description;

@end


// WebUndefined --------------------------------------------------------------

/*!
    @class WebUndefined
*/
@interface WebUndefined : NSObject <NSCoding, NSCopying>
{
}

/*!
    @method undefined
    @result The WebUndefined shared instance.
*/
+ (WebUndefined *)undefined;

@end