Reviewed by Maciej.
authorggaren <ggaren@268f45cc-cd09-0410-ab3c-d52691b4dbfc>
Sat, 8 Jul 2006 02:02:47 +0000 (02:02 +0000)
committerggaren <ggaren@268f45cc-cd09-0410-ab3c-d52691b4dbfc>
Sat, 8 Jul 2006 02:02:47 +0000 (02:02 +0000)
        More API action.

        - Headerdoc finished

        Semantic Changes:
        - Added a JSContextRef argument to many functions, because you need a
        JSContextRef for doing virtually anything. I expect to add this argument
        to even more functions in a future patch.

        - Removed the globalObjectPrototype argument to JSContextCreate because
        you can't create an object until you have a context, so it's impossible
        to pass a prototype object to JSContextCreate. That's OK because (1) there's
        no reason to give the global object a prototype and (2) if you really want
        to, you can just use a separate call to JSObjectSetPrototype.

        - Removed the JSClassRef argument to JSClassCreate because it was unnecessary,
        and you need to be able to make the global object's class before you've
        created a JSContext.

        - Added an optional exception parameter to JSFunctionMakeWithBody because anything
        less would be uncivilized.

        - Made the return value parameter to JSObjectGetProperty optional to match
        all other return value parameters in the API.

        - Made JSObjectSetPrivate/JSObjectGetPrivate work on JSCallbackFunctions
        and JSCallbackConstructors. You could use an abstract base class or strategic
        placement of m_privateData in the class structure to implement this, but
        the former seemed like overkill, and the latter seemed too dangerous.

        - Fixed a bug where JSPropertyEnumeratorGetNext would skip the first property.

        Cosmetic Changes:
        - Reversed the logic of the JSChar #ifdef to avoid confusing headerdoc

        - Removed function names from @function declarations because headeroc
        can parse them automatically, and I wanted to rule out manual mismatch.

        - Changed Error::create to take a const UString& instead of a UString*
        because it was looking at me funny.

        - Renamed JSStringBufferCreateWithCFString to JSStringBufferCreateCF
        because the latter is more concise and it matches JSStringBufferCreateUTF8.

        * API/JSCallbackObject.cpp:
        (KJS::JSCallbackObject::getOwnPropertySlot):
        (KJS::JSCallbackObject::put):
        (KJS::JSCallbackObject::deleteProperty):
        (KJS::JSCallbackObject::getPropertyList):
        (KJS::JSCallbackObject::toBoolean):
        (KJS::JSCallbackObject::toNumber):
        (KJS::JSCallbackObject::toString):
        * API/JSClassRef.cpp:
        (JSClassCreate):
        * API/JSContextRef.cpp:
        (JSContextCreate):
        (JSContextSetException):
        * API/JSContextRef.h:
        * API/JSNode.c:
        (JSNodePrototype_class):
        (JSNode_class):
        * API/JSNodeList.c:
        (JSNodeListPrototype_class):
        (JSNodeList_class):
        * API/JSObjectRef.cpp:
        (JSObjectGetProperty):
        (JSObjectGetPrivate):
        (JSObjectSetPrivate):
        (JSObjectCallAsFunction):
        (JSObjectCallAsConstructor):
        (JSPropertyEnumeratorGetNext):
        * API/JSObjectRef.h:
        * API/JSStringBufferRef.cpp:
        (JSStringBufferCreateCF):
        * API/JSStringBufferRef.h:
        * API/JSValueRef.cpp:
        (JSValueIsInstanceOf):
        * API/JSValueRef.h:
        * API/minidom.c:
        (main):
        * API/minidom.js:
        * API/testapi.c:
        (MyObject_hasProperty):
        (MyObject_setProperty):
        (MyObject_deleteProperty):
        (MyObject_getPropertyList):
        (MyObject_convertToType):
        (MyObject_class):
        (main):
        * JavaScriptCore.exp:

git-svn-id: https://svn.webkit.org/repository/webkit/trunk@15224 268f45cc-cd09-0410-ab3c-d52691b4dbfc

21 files changed:
JavaScriptCore/API/JSCallbackObject.cpp
JavaScriptCore/API/JSClassRef.cpp
JavaScriptCore/API/JSContextRef.cpp
JavaScriptCore/API/JSContextRef.h
JavaScriptCore/API/JSNode.c
JavaScriptCore/API/JSNodeList.c
JavaScriptCore/API/JSObjectRef.cpp
JavaScriptCore/API/JSObjectRef.h
JavaScriptCore/API/JSStringBufferRef.cpp
JavaScriptCore/API/JSStringBufferRef.h
JavaScriptCore/API/JSValueRef.cpp
JavaScriptCore/API/JSValueRef.h
JavaScriptCore/API/minidom.c
JavaScriptCore/API/testapi.c
JavaScriptCore/ChangeLog
JavaScriptCore/JavaScriptCore.exp
JavaScriptCore/kjs/function_object.cpp
JavaScriptCore/kjs/interpreter.cpp
JavaScriptCore/kjs/nodes.cpp
JavaScriptCore/kjs/object.cpp
JavaScriptCore/kjs/object.h

index 9b99653c586ebdf9a440624473d90c5f9e398916..afd94cd10f80d6df3392d20a37d2339e67e77ee6 100644 (file)
@@ -80,19 +80,20 @@ UString JSCallbackObject::className() const
 
 bool JSCallbackObject::getOwnPropertySlot(ExecState* exec, const Identifier& propertyName, PropertySlot& slot)
 {
+    JSContextRef context = toRef(exec);
     JSObjectRef thisRef = toRef(this);
     JSStringBufferRef propertyNameRef = toRef(propertyName.ustring().rep());
     
     for (JSClassRef jsClass = m_class; jsClass; jsClass = jsClass->parent) {
         // optional optimization to bypass getProperty in cases when we only need to know if the property exists
         if (JSHasPropertyCallback hasPropertyCallback = jsClass->callbacks.hasProperty) {
-            if (hasPropertyCallback(thisRef, propertyNameRef)) {
+            if (hasPropertyCallback(context, thisRef, propertyNameRef)) {
                 slot.setCustom(this, callbackGetter);
                 return true;
             }
         } else if (JSGetPropertyCallback getPropertyCallback = jsClass->callbacks.getProperty) {
             JSValueRef returnValue;
-            if (getPropertyCallback(toRef(exec), thisRef, propertyNameRef, &returnValue)) {
+            if (getPropertyCallback(context, thisRef, propertyNameRef, &returnValue)) {
                 // cache the value so we don't have to compute it again
                 // FIXME: This violates the PropertySlot design a little bit.
                 // We should either use this optimization everywhere, or nowhere.
@@ -128,12 +129,13 @@ bool JSCallbackObject::getOwnPropertySlot(ExecState* exec, unsigned propertyName
 
 void JSCallbackObject::put(ExecState* exec, const Identifier& propertyName, JSValue* value, int attr)
 {
+    JSContextRef context = toRef(exec);
     JSObjectRef thisRef = toRef(this);
     JSStringBufferRef propertyNameRef = toRef(propertyName.ustring().rep());
 
     for (JSClassRef jsClass = m_class; jsClass; jsClass = jsClass->parent) {
         if (JSSetPropertyCallback setPropertyCallback = jsClass->callbacks.setProperty) {
-            if (setPropertyCallback(thisRef, propertyNameRef, value))
+            if (setPropertyCallback(context, thisRef, propertyNameRef, value))
                 return;
         }
     
@@ -142,7 +144,7 @@ void JSCallbackObject::put(ExecState* exec, const Identifier& propertyName, JSVa
                 if (entry->attributes & kJSPropertyAttributeReadOnly)
                     return;
                 if (JSSetPropertyCallback setPropertyCallback = entry->setProperty) {
-                    if (setPropertyCallback(thisRef, propertyNameRef, value))
+                    if (setPropertyCallback(context, thisRef, propertyNameRef, value))
                         return;
                 }
             }
@@ -167,12 +169,13 @@ void JSCallbackObject::put(ExecState* exec, unsigned propertyName, JSValue* valu
 
 bool JSCallbackObject::deleteProperty(ExecState* exec, const Identifier& propertyName)
 {
+    JSContextRef context = toRef(exec);
     JSObjectRef thisRef = toRef(this);
     JSStringBufferRef propertyNameRef = toRef(propertyName.ustring().rep());
     
     for (JSClassRef jsClass = m_class; jsClass; jsClass = jsClass->parent) {
         if (JSDeletePropertyCallback deletePropertyCallback = jsClass->callbacks.deleteProperty) {
-            if (deletePropertyCallback(thisRef, propertyNameRef))
+            if (deletePropertyCallback(context, thisRef, propertyNameRef))
                 return true;
         }
 
@@ -259,11 +262,12 @@ JSValue* JSCallbackObject::callAsFunction(ExecState* exec, JSObject* thisObj, co
 
 void JSCallbackObject::getPropertyList(ExecState* exec, ReferenceList& propertyList, bool recursive)
 {
+    JSContextRef context = toRef(exec);
     JSObjectRef thisRef = toRef(this);
 
     for (JSClassRef jsClass = m_class; jsClass; jsClass = jsClass->parent) {
         if (JSGetPropertyListCallback getPropertyListCallback = jsClass->callbacks.getPropertyList)
-            getPropertyListCallback(thisRef, toRef(&propertyList));
+            getPropertyListCallback(context, thisRef, toRef(&propertyList));
 
         if (__JSClass::StaticValuesTable* staticValues = jsClass->staticValues) {
             typedef __JSClass::StaticValuesTable::const_iterator iterator;
@@ -293,12 +297,13 @@ void JSCallbackObject::getPropertyList(ExecState* exec, ReferenceList& propertyL
 
 bool JSCallbackObject::toBoolean(ExecState* exec) const
 {
+    JSContextRef context = toRef(exec);
     JSObjectRef thisRef = toRef(this);
 
     for (JSClassRef jsClass = m_class; jsClass; jsClass = jsClass->parent) {
         if (JSConvertToTypeCallback convertToTypeCallback = jsClass->callbacks.convertToType) {
             JSValueRef returnValue;
-            if (convertToTypeCallback(thisRef, kJSTypeBoolean, &returnValue))
+            if (convertToTypeCallback(context, thisRef, kJSTypeBoolean, &returnValue))
                 return toJS(returnValue)->getBoolean();
         }
     }
@@ -307,12 +312,13 @@ bool JSCallbackObject::toBoolean(ExecState* exec) const
 
 double JSCallbackObject::toNumber(ExecState* exec) const
 {
+    JSContextRef context = toRef(exec);
     JSObjectRef thisRef = toRef(this);
 
     for (JSClassRef jsClass = m_class; jsClass; jsClass = jsClass->parent) {
         if (JSConvertToTypeCallback convertToTypeCallback = jsClass->callbacks.convertToType) {
             JSValueRef returnValue;
-            if (convertToTypeCallback(thisRef, kJSTypeNumber, &returnValue))
+            if (convertToTypeCallback(context, thisRef, kJSTypeNumber, &returnValue))
                 return toJS(returnValue)->getNumber();
         }
     }
@@ -321,12 +327,13 @@ double JSCallbackObject::toNumber(ExecState* exec) const
 
 UString JSCallbackObject::toString(ExecState* exec) const
 {
+    JSContextRef context = toRef(exec);
     JSObjectRef thisRef = toRef(this);
 
     for (JSClassRef jsClass = m_class; jsClass; jsClass = jsClass->parent) {
         if (JSConvertToTypeCallback convertToTypeCallback = jsClass->callbacks.convertToType) {
             JSValueRef returnValue;
-            if (convertToTypeCallback(thisRef, kJSTypeString, &returnValue))
+            if (convertToTypeCallback(context, thisRef, kJSTypeString, &returnValue))
                 return toJS(returnValue)->getString();
         }
     }
index 6e46eced41b4b62f875ed6ee7df6ba1a92d17608..bfa3e8517c2510ed629a86c6648c2f70d44a51a0 100644 (file)
@@ -32,7 +32,7 @@ using namespace KJS;
 
 const JSObjectCallbacks kJSObjectCallbacksNone = { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 };
 
-JSClassRef JSClassCreate(JSContextRef, JSStaticValue* staticValues, JSStaticFunction* staticFunctions, const JSObjectCallbacks* callbacks, JSClassRef parentClass)
+JSClassRef JSClassCreate(JSStaticValue* staticValues, JSStaticFunction* staticFunctions, const JSObjectCallbacks* callbacks, JSClassRef parentClass)
 {
     JSClassRef jsClass = new __JSClass;
     if (staticValues) {
index 2acbfb321359348c0138513e95019f7d49e171eb..140bdf40988f4ac1e79ae7eabef860c8a07b475b 100644 (file)
 
 using namespace KJS;
 
-JSContextRef JSContextCreate(JSClassRef globalObjectClass, JSObjectRef globalObjectPrototype)
+JSContextRef JSContextCreate(JSClassRef globalObjectClass)
 {
     JSLock lock;
 
-    JSObject* jsPrototype = toJS(globalObjectPrototype);
-
     JSObject* globalObject;
-    if (globalObjectClass) {
-        if (jsPrototype)
-            globalObject = new JSCallbackObject(globalObjectClass, jsPrototype);
-        else
-            globalObject = new JSCallbackObject(globalObjectClass);
-    } else {
-        // creates a slightly more efficient object
-        if (jsPrototype)
-            globalObject = new JSObject(jsPrototype);
-        else
-            globalObject = new JSObject();
-    }
+    if (globalObjectClass)
+        globalObject = new JSCallbackObject(globalObjectClass);
+    else
+        globalObject = new JSObject();
 
     Interpreter* interpreter = new Interpreter(globalObject); // adds the built-in object prototype to the global object
     return toRef(interpreter->globalExec());
@@ -130,4 +120,3 @@ void JSContextSetException(JSContextRef context, JSValueRef value)
     JSValue* jsValue = toJS(value);
     exec->setException(jsValue);
 }
-
index 8abaa284c134476f429c2ee29031e0fa7edc0813..46c2054b1775af356ef04879da0ccdb31b04d432 100644 (file)
 extern "C" {
 #endif
 
-JSContextRef JSContextCreate(JSClassRef globalObjectClass, JSObjectRef globalObjectPrototype);
+/*!
+@function
+@abstract Creates a JavaScript execution context.
+@discussion JSContextCreate allocates a global object and populates it with all the
+ built-in JavaScript objects, such as Object, Function, String, and Array.
+@param globalObjectClass The class to use when creating the JSContext's global object.
+ Pass NULL to use the default object class.
+@result A JSContext with a global object of class globalObjectClass.
+*/
+JSContextRef JSContextCreate(JSClassRef globalObjectClass);
+
+/*!
+@function
+@abstract       Destroys a JavaScript execution context, freeing its resources.
+@param context  The JSContext to destroy.
+*/
 void JSContextDestroy(JSContextRef context);
 
+/*!
+@function
+@abstract       Returns the global object of a JavaScript execution context.
+@param context  The JSContext whose global object you want to retrieve.
+@result         context's global object.
+*/
 JSObjectRef JSContextGetGlobalObject(JSContextRef context);
 
-JSValueRef JSContextGetException(JSContextRef context); // NULL if there is no exception
+/*!
+@function
+@abstract       Returns the current exception in a JavaScript execution context.
+@param context  The JSContext whose exception you want to retrieve.
+@result         A JSValue representing context's exception, or NULL if no exception has been set.
+*/
+JSValueRef JSContextGetException(JSContextRef context);
+/*!
+@function
+@abstract       Sets an exception in a JavaScript execution context.
+@param context  The JSContext whose exception you want to set.
+@param value    The exception you want to set.
+*/
 void JSContextSetException(JSContextRef context, JSValueRef value);
+/*!
+@function
+@abstract       Clears the exception in a JavaScript execution context.
+@param context  The JSContext whose exception you want to clear.
+*/
 void JSContextClearException(JSContextRef context);
-    
+
 // Evaluation
 /*!
-  @function JSEvaluate
-  Evaluates a string of JavaScript
-  @param context            execution context to use
-  @param script             a character buffer containing the JavaScript to evaluate
-  @param thisObject         the object to use as "this," or NULL to use the global object as "this."
-  @param sourceURL          URL to the file containing the JavaScript, or NULL - this is only used for error reporting
-  @param startingLineNumber the JavaScript's starting line number in the file located at sourceURL - this is only used for error reporting
-  @param exception          pointer to a JSValueRef in which to store an uncaught exception, if any; can be NULL
-  @result                   result of evaluation, or NULL if an uncaught exception was thrown
+@function
+@abstract                 Evaluates a string of JavaScript.
+@param context            The execution context to use.
+@param script             A JSStringBuffer containing the script to evaluate.
+@param thisObject         The object to use as "this," or NULL to use the global object as "this."
+@param sourceURL          A JSStringBuffer containing a URL for the script's source file. This is only used when reporting exceptions. Pass NULL if you do not care to include source file information in exceptions.
+@param startingLineNumber An integer value specifying the script's starting line number in the file located at sourceURL. This is only used when reporting exceptions.
+@param exception          A pointer to a JSValueRef in which to store an uncaught exception, if any. Pass NULL if you do not care to store an uncaught exception.
+@result                   The JSValue that results from evaluating script, or NULL if an uncaught exception is thrown.
 */
 JSValueRef JSEvaluate(JSContextRef context, JSStringBufferRef script, JSObjectRef thisObject, JSStringBufferRef sourceURL, int startingLineNumber, JSValueRef* exception);
 
 /*!
-  @function JSCheckSyntax
-  Check for syntax errors in a string of JavaScript
-  @param context            execution context to use
-  @param script             a character buffer containing the JavaScript to evaluate
-  @param sourceURL          URL to the file containing the JavaScript, or NULL - this is only used for error reporting
-  @param startingLineNumber the JavaScript's starting line number in the file located at sourceURL - this is only used for error reporting
-  @param exception          pointer to a JSValueRef in which to store a syntax error, if any; can be NULL
-  @result                   true if the script is syntactically correct, false otherwise
-
+@function JSCheckSyntax
+@abstract                 Checks for syntax errors in a string of JavaScript.
+@param context            The execution context to use.
+@param script             A JSStringBuffer containing the JavaScript to check for syntax errors.
+@param sourceURL          A JSStringBuffer containing a URL for the script's source file. This is only used when reporting exceptions. Pass NULL if you do not care to include source file information in exceptions.
+@param startingLineNumber An integer value specifying the script's starting line number in the file located at sourceURL. This is only used when reporting exceptions.
+@param exception          A pointer to a JSValueRef in which to store a syntax error exception, if any. Pass NULL if you do not care to store a syntax error exception.
+@result                   true if the script is syntactically correct, otherwise false.
 */
 bool JSCheckSyntax(JSContextRef context, JSStringBufferRef script, JSStringBufferRef sourceURL, int startingLineNumber, JSValueRef* exception);
 
index 3f920f0a32fc790bb49ee26367b45c358f93e587..335cda41eba36379bad692330ac1ff087d0f2f2a 100644 (file)
@@ -109,7 +109,7 @@ static JSClassRef JSNodePrototype_class(JSContextRef context)
 {
     static JSClassRef nodePrototypeClass;
     if (!nodePrototypeClass)
-        nodePrototypeClass = JSClassCreate(context, NULL, JSNodePrototype_staticFunctions, &kJSObjectCallbacksNone, NULL);
+        nodePrototypeClass = JSClassCreate(NULL, JSNodePrototype_staticFunctions, &kJSObjectCallbacksNone, NULL);
     return nodePrototypeClass;
 }
 
@@ -169,7 +169,7 @@ static JSClassRef JSNode_class(JSContextRef context)
         JSObjectCallbacks JSNode_callbacks = kJSObjectCallbacksNone;
         JSNode_callbacks.finalize = JSNode_finalize;
         
-        nodeClass = JSClassCreate(context, JSNode_staticValues, NULL, &JSNode_callbacks, NULL);
+        nodeClass = JSClassCreate(JSNode_staticValues, NULL, &JSNode_callbacks, NULL);
     }
     return nodeClass;
 }
index 61e9eaefd5320229777c8e66cf192c2f33c8d3db..29a181398d0d72ccbd0aad8b4f3b6050507b6b95 100644 (file)
@@ -50,7 +50,7 @@ static JSClassRef JSNodeListPrototype_class(JSContextRef context)
 {
     static JSClassRef jsClass;
     if (!jsClass) {
-        jsClass = JSClassCreate(context, NULL, JSNodeListPrototype_staticFunctions, &kJSObjectCallbacksNone, NULL);
+        jsClass = JSClassCreate(NULL, JSNodeListPrototype_staticFunctions, &kJSObjectCallbacksNone, NULL);
     }
     
     return jsClass;
@@ -103,7 +103,7 @@ static JSClassRef JSNodeList_class(JSContextRef context)
         callbacks.getProperty = JSNodeList_getProperty;
         callbacks.finalize = JSNodeList_finalize;
         
-        jsClass = JSClassCreate(context, JSNodeList_staticValues, NULL, &callbacks, NULL);
+        jsClass = JSClassCreate(JSNodeList_staticValues, NULL, &callbacks, NULL);
     }
     
     return jsClass;
index 003f8ef1a0749432ebbc2e977e0d1be78170969a..9ff7f67c457e2e253ae287d619a3eb412f824d5e 100644 (file)
@@ -70,18 +70,26 @@ JSObjectRef JSConstructorMake(JSContextRef context, JSCallAsConstructorCallback
     return toRef(new JSCallbackConstructor(exec, callAsConstructor));
 }
 
-JSObjectRef JSFunctionMakeWithBody(JSContextRef context, JSStringBufferRef body, JSStringBufferRef sourceURL, int startingLineNumber)
+JSObjectRef JSFunctionMakeWithBody(JSContextRef context, JSStringBufferRef body, JSStringBufferRef sourceURL, int startingLineNumber, JSValueRef* exception)
 {
     JSLock lock;
     
     ExecState* exec = toJS(context);
     UString::Rep* bodyRep = toJS(body);
-    UString::Rep* sourceURLRep = toJS(sourceURL);
+    UString jsSourceURL = UString(toJS(sourceURL));
+
     if (!bodyRep)
         bodyRep = &UString::Rep::null;
-    RefPtr<FunctionBodyNode> bodyNode = Parser::parse(UString(sourceURLRep), startingLineNumber, bodyRep->data(), bodyRep->size(), NULL, NULL, NULL);
-    if (!bodyNode)
+    
+    int sid;
+    int errLine;
+    UString errMsg;
+    RefPtr<FunctionBodyNode> bodyNode = Parser::parse(jsSourceURL, startingLineNumber, bodyRep->data(), bodyRep->size(), &sid, &errLine, &errMsg);
+    if (!bodyNode) {
+        if (exception)
+            *exception = Error::create(exec, SyntaxError, errMsg, errLine, sid, jsSourceURL);
         return NULL;
+    }
 
     ScopeChain scopeChain;
     scopeChain.push(exec->dynamicInterpreter()->globalObject());
@@ -126,8 +134,10 @@ bool JSObjectGetProperty(JSContextRef context, JSObjectRef object, JSStringBuffe
     JSObject* jsObject = toJS(object);
     UString::Rep* nameRep = toJS(propertyName);
 
-    *value = toRef(jsObject->get(exec, Identifier(nameRep)));
-    return !JSValueIsUndefined(*value);
+    JSValue* jsValue = jsObject->get(exec, Identifier(nameRep));
+    if (value)
+        *value = toRef(jsValue);
+    return !jsValue->isUndefined();
 }
 
 bool JSObjectSetProperty(JSContextRef context, JSObjectRef object, JSStringBufferRef propertyName, JSValueRef value, JSPropertyAttributes attributes)
@@ -160,21 +170,38 @@ void* JSObjectGetPrivate(JSObjectRef object)
 {
     JSObject* jsObject = toJS(object);
     
-    if (!jsObject->inherits(&JSCallbackObject::info))
-        return 0;
+    if (jsObject->inherits(&JSCallbackObject::info))
+        return static_cast<JSCallbackObject*>(jsObject)->getPrivate();
     
-    return static_cast<JSCallbackObject*>(jsObject)->getPrivate();
+    if (jsObject->inherits(&JSCallbackFunction::info))
+        return static_cast<JSCallbackFunction*>(jsObject)->getPrivate();
+    
+    if (jsObject->inherits(&JSCallbackConstructor::info))
+        return static_cast<JSCallbackConstructor*>(jsObject)->getPrivate();
+    
+    return 0;
 }
 
 bool JSObjectSetPrivate(JSObjectRef object, void* data)
 {
     JSObject* jsObject = toJS(object);
     
-    if (!jsObject->inherits(&JSCallbackObject::info))
-        return false;
+    if (jsObject->inherits(&JSCallbackObject::info)) {
+        static_cast<JSCallbackObject*>(jsObject)->setPrivate(data);
+        return true;
+    }
+        
+    if (jsObject->inherits(&JSCallbackFunction::info)) {
+        static_cast<JSCallbackFunction*>(jsObject)->setPrivate(data);
+        return true;
+    }
+        
+    if (jsObject->inherits(&JSCallbackConstructor::info)) {
+        static_cast<JSCallbackConstructor*>(jsObject)->setPrivate(data);
+        return true;
+    }
     
-    static_cast<JSCallbackObject*>(jsObject)->setPrivate(data);
-    return true;
+    return false;
 }
 
 bool JSObjectIsFunction(JSObjectRef object)
@@ -193,8 +220,8 @@ JSValueRef JSObjectCallAsFunction(JSContextRef context, JSObjectRef object, JSOb
     List argList;
     for (size_t i = 0; i < argc; i++)
         argList.append(toJS(argv[i]));
-    
-    JSValueRef result = toRef(jsObject->call(exec, jsThisObject, argList));
+
+    JSValueRef result = toRef(jsObject->call(exec, jsThisObject, argList)); // returns NULL if object->implementsCall() is false
     if (exec->hadException()) {
         if (exception)
             *exception = exec->exception();
@@ -220,7 +247,7 @@ JSObjectRef JSObjectCallAsConstructor(JSContextRef context, JSObjectRef object,
     for (size_t i = 0; i < argc; i++)
         argList.append(toJS(argv[i]));
     
-    JSObjectRef result = toRef(jsObject->construct(exec, argList));
+    JSObjectRef result = toRef(jsObject->construct(exec, argList)); // returns NULL if object->implementsCall() is false
     if (exec->hadException()) {
         if (exception)
             *exception = exec->exception();
@@ -259,8 +286,9 @@ JSStringBufferRef JSPropertyEnumeratorGetNext(JSContextRef context, JSPropertyEn
     ExecState* exec = toJS(context);
     ReferenceListIterator& iterator = enumerator->iterator;
     if (iterator != enumerator->list.end()) {
+        JSStringBufferRef result = toRef(iterator->getPropertyName(exec).ustring().rep());
         iterator++;
-        return toRef(iterator->getPropertyName(exec).ustring().rep());
+        return result;
     }
     return 0;
 }
index e50a3c633952dd04432f6459a1d77b095049f862..c374c5ab8052124cdc2fa2ccb657c3dfc711a36d 100644 (file)
 extern "C" {
 #endif
 
+/*!
+@enum JSPropertyAttribute
+@constant kJSPropertyAttributeNone         Specifies that a property has no special attributes.
+@constant kJSPropertyAttributeReadOnly     Specifies that a property is read-only.
+@constant kJSPropertyAttributeDontEnum     Specifies that a property should not be enumerated by JSPropertyEnumerators and JavaScript for...in loops.
+@constant kJSPropertyAttributeDontDelete   Specifies that the delete operation should fail on a property.
+*/
 enum { 
     kJSPropertyAttributeNone         = 0,
     kJSPropertyAttributeReadOnly     = 1 << 1,
     kJSPropertyAttributeDontEnum     = 1 << 2,
     kJSPropertyAttributeDontDelete   = 1 << 3
 };
+
+/*! 
+@typedef JSPropertyAttributes
+@abstract A set of JSPropertyAttributes. Combine multiple attributes by logically ORing them together.
+*/
 typedef unsigned JSPropertyAttributes;
 
+/*! 
+@typedef JSInitializeCallback
+@abstract The callback invoked when an object is first created.
+@param object The JSObject being created.
+@discussion If you named your function Initialize, you would declare it like this:
+
+void Initialize(JSObjectRef object);
+*/
+
+// FIXME: Needs to take a context argument, but can't because no context exists when we're creating the global object
 typedef void
 (*JSInitializeCallback)         (JSObjectRef object);
 
+/*! 
+@typedef JSFinalizeCallback
+@abstract The callback invoked when an object is finalized (prepared for garbage collection).
+@param object The JSObject being finalized.
+@discussion If you named your function Finalize, you would declare it like this:
+
+void Finalize(JSObjectRef object);
+*/
 typedef void            
 (*JSFinalizeCallback)           (JSObjectRef object);
 
+/*! 
+@typedef JSHasPropertyCallback
+@abstract The callback invoked when determining whether an object has a given property.
+@param context The current execution context.
+@param object The JSObject to search for the property.
+@param propertyName A JSStringBuffer containing the name of the property look up.
+@result true if object has the property, otherwise false.
+@discussion If you named your function HasProperty, you would declare it like this:
+
+bool HasProperty(JSContextRef context, JSObjectRef object, JSStringBufferRef propertyName);
+
+This callback enables optimization in cases where only a property's existence needs to be known, not its value, and computing its value would be expensive. If this callback is NULL, the getProperty callback will be used to service hasProperty calls.
+*/
 typedef bool
-(*JSHasPropertyCallback)        (JSObjectRef object, JSStringBufferRef propertyName);
+(*JSHasPropertyCallback)        (JSContextRef context, JSObjectRef object, JSStringBufferRef propertyName);
+
+/*! 
+@typedef JSGetPropertyCallback
+@abstract The callback invoked when getting a property from an object.
+@param context The current execution context.
+@param object The JSObject to search for the property.
+@param propertyName A JSStringBuffer containing the name of the property to get.
+@param returnValue A pointer to a JSValue in which to store the property's value.
+@result true if object has the property in question, otherwise false. If this function returns true, returnValue is assumed to contain a valid JSValue.
+@discussion If you named your function GetProperty, you would declare it like this:
 
+bool GetProperty(JSContextRef context, JSObjectRef object, JSStringBufferRef propertyName, JSValueRef* returnValue);
+
+If this function returns false, the get request forwards to object's static property table, then its parent class chain (which includes the default object class), then its prototype chain.
+*/
 typedef bool
 (*JSGetPropertyCallback)        (JSContextRef context, JSObjectRef object, JSStringBufferRef propertyName, JSValueRef* returnValue);
 
+/*! 
+@typedef JSSetPropertyCallback
+@abstract The callback invoked when setting the value of a given property.
+@param context The current execution context.
+@param object The JSObject on which to set the property's value.
+@param propertyName A JSStringBuffer containing the name of the property to set.
+@param value A JSValue to use as the property's value.
+@result true if the property was successfully set, otherwise false.
+@discussion If you named your function SetProperty, you would declare it like this:
+
+bool SetProperty(JSContextRef context, JSObjectRef object, JSStringBufferRef propertyName, JSValueRef value);
+
+If this function returns false, the set request forwards to object's static property table, then its parent class chain (which includes the default object class).
+*/
 typedef bool
-(*JSSetPropertyCallback)        (JSObjectRef object, JSStringBufferRef propertyName, JSValueRef value);
+(*JSSetPropertyCallback)        (JSContextRef context, JSObjectRef object, JSStringBufferRef propertyName, JSValueRef value);
+
+/*! 
+@typedef JSDeletePropertyCallback
+@abstract The callback invoked when deleting a given property.
+@param context The current execution context.
+@param object The JSObject in which to delete the property.
+@param propertyName A JSStringBuffer containing the name of the property to delete.
+@result true if propertyName was successfully deleted, otherwise false.
+@discussion If you named your function DeleteProperty, you would declare it like this:
 
+bool DeleteProperty(JSContextRef context, JSObjectRef object, JSStringBufferRef propertyName);
+
+If this function returns false, the delete request forwards to object's static property table, then its parent class chain (which includes the default object class).
+*/
 typedef bool
-(*JSDeletePropertyCallback)     (JSObjectRef object, JSStringBufferRef propertyName);
+(*JSDeletePropertyCallback)     (JSContextRef context, JSObjectRef object, JSStringBufferRef propertyName);
+
+/*! 
+@typedef JSGetPropertyListCallback
+@abstract The callback invoked when adding an object's properties to a property list.
+@param context The current execution context.
+@param object The JSObject whose properties need to be added to propertyList.
+@param propertyList A JavaScript property list that will be used to enumerate object's properties.
+@discussion If you named your function GetPropertyList, you would declare it like this:
+
+void GetPropertyList(JSContextRef context, JSObjectRef object, JSPropertyListRef propertyList);
 
+Use JSPropertyListAdd to add properties to propertyList.
+
+Property lists are used by JSPropertyEnumerators and JavaScript for...in loops.
+*/
 typedef void
-(*JSGetPropertyListCallback)    (JSObjectRef object, JSPropertyListRef propertyList);
+(*JSGetPropertyListCallback)    (JSContextRef context, JSObjectRef object, JSPropertyListRef propertyList);
+
+/*! 
+@typedef JSCallAsFunctionCallback
+@abstract The callback invoked when an object is called as a function.
+@param context The current execution context.
+@param function A JSObject that is the function being called.
+@param thisObject A JSObject that is the 'this' variable in the function's scope.
+@param argc An integer count of the number of arguments in argv.
+@param argv A JSValue array of the  arguments passed to the function.
+@result A JSValue that is the function's return value.
+@discussion If you named your function CallAsFunction, you would declare it like this:
+
+JSValueRef CallAsFunction(JSContextRef context, JSObjectRef function, JSObjectRef thisObject, size_t argc, JSValueRef argv[]);
+
+If your callback were invoked by the JavaScript expression 'myObject.myMemberFunction()', function would be set to myMemberFunction, and thisObject would be set to myObject.
 
+If this callback is NULL, calling your object as a function will throw an exception.
+*/
 typedef JSValueRef 
-(*JSCallAsFunctionCallback)     (JSContextRef context, JSObjectRef object, JSObjectRef thisObject, size_t argc, JSValueRef argv[]);
+(*JSCallAsFunctionCallback)     (JSContextRef context, JSObjectRef function, JSObjectRef thisObject, size_t argc, JSValueRef argv[]);
+
+/*! 
+@typedef JSCallAsConstructorCallback
+@abstract The callback invoked when an object is used as a constructor in a 'new' statement.
+@param context The current execution context.
+@param constructor A JSObject that is the constructor being called.
+@param argc An integer count of the number of arguments in argv.
+@param argv A JSValue array of the  arguments passed to the function.
+@result A JSObject that is the constructor's return value.
+@discussion If you named your function CallAsConstructor, you would declare it like this:
+
+JSObjectRef CallAsConstructor(JSContextRef context, JSObjectRef constructor, size_t argc, JSValueRef argv[]);
+
+If your callback were invoked by the JavaScript expression 'new myConstructorFunction()', constructor would be set to myConstructorFunction.
 
+If this callback is NULL, using your object as a constructor in a 'new' statement will throw an exception.
+*/
 typedef JSObjectRef 
-(*JSCallAsConstructorCallback)  (JSContextRef context, JSObjectRef object, size_t argc, JSValueRef argv[]);
+(*JSCallAsConstructorCallback)  (JSContextRef context, JSObjectRef constructor, size_t argc, JSValueRef argv[]);
 
+/*! 
+@typedef JSConvertToTypeCallback
+@abstract The callback invoked when converting an object to a particular JavaScript type.
+@param context The current execution context.
+@param object The JSObject to convert.
+@param typeCode A JSTypeCode specifying the JavaScript type to convert to.
+@param returnValue A pointer to a JSValue in which to store the converted value.
+@result true if the value was converted, otherwise false. If this function returns true, returnValue is assumed to contain a valid JSValue.
+@discussion If you named your function ConvertToType, you would declare it like this:
+
+bool ConvertToType(JSContextRef context, JSObjectRef object, JSTypeCode typeCode, JSValueRef* returnValue);
+
+If this function returns false, the conversion request forwards to object's parent class chain (which includes the default object class).
+*/
 typedef bool
-(*JSConvertToTypeCallback)      (JSObjectRef object, JSTypeCode typeCode, JSValueRef* returnValue);
+(*JSConvertToTypeCallback)      (JSContextRef context, JSObjectRef object, JSTypeCode typeCode, JSValueRef* returnValue);
 
-typedef struct __JSObjectCallbacks {
+/*!
+@struct JSObjectCallbacks
+@abstract This structure contains optional callbacks for supplementing default object behavior. Any callback field can be NULL.
+@field version The version number of this structure. The current version is 0.
+@field initialize The callback invoked when an object is first created. Use this callback in conjunction with JSObjectSetPrivate to initialize private data in your object.
+@field finalize The callback invoked when an object is finalized (prepared for garbage collection). Use this callback to release resources allocated for your object, and perform other cleanup.
+@field hasProperty The callback invoked when determining whether an object has a given property. If this field is NULL, getProperty will be called instead. The hasProperty callback enables optimization in cases where only a property's existence needs to be known, not its value, and computing its value would be expensive. 
+@field getProperty The callback invoked when getting the value of a given property.
+@field setProperty The callback invoked when setting the value of a given property.
+@field deleteProperty The callback invoked when deleting a given property.
+@field getPropertyList The callback invoked when adding an object's properties to a property list.
+@field callAsFunction The callback invoked when an object is called as a function.
+@field callAsConstructor The callback invoked when an object is used as a constructor in a 'new' statement.
+@field convertToType The callback invoked when converting an object to a particular JavaScript type.
+*/
+typedef struct {
     int                         version; // current (and only) version is 0
     JSInitializeCallback        initialize;
     JSFinalizeCallback          finalize;
@@ -86,8 +246,25 @@ typedef struct __JSObjectCallbacks {
     JSConvertToTypeCallback     convertToType;
 } JSObjectCallbacks;
 
+/*! 
+@const kJSObjectCallbacksNone 
+@abstract A JSObjectCallbacks structure of the current version, filled with NULL callbacks.
+@discussion Use this constant as a convenience when creating callback structures. For example, to create a callback structure that has only a finalize method:
+
+JSObjectCallbacks callbacks = kJSObjectCallbacksNone;
+
+callbacks.finalize = Finalize;
+*/
 extern const JSObjectCallbacks kJSObjectCallbacksNone;
 
+/*! 
+@struct JSStaticValue
+@abstract This structure describes a static value property.
+@field name A UTF8 buffer containing the property's name.
+@field getProperty A JSGetPropertyCallback to invoke when getting the property's value.
+@field setProperty A JSSetPropertyCallback to invoke when setting the property's value.
+@field attributes A logically ORed set of JSPropertyAttributes to give to the property.
+*/
 typedef struct {
     const char* const name; // FIXME: convert UTF8
     JSGetPropertyCallback getProperty;
@@ -95,53 +272,240 @@ typedef struct {
     JSPropertyAttributes attributes;
 } JSStaticValue;
 
+/*! 
+@struct JSStaticFunction
+@abstract This structure describes a static function property.
+@field name A UTF8 buffer containing the property's name.
+@field callAsFunction A JSCallAsFunctionCallback to invoke when the property is called as a function.
+@field attributes A logically ORed set of JSPropertyAttributes to give to the property.
+*/
 typedef struct {
     const char* const name; // FIXME: convert UTF8
     JSCallAsFunctionCallback callAsFunction;
     JSPropertyAttributes attributes;
 } JSStaticFunction;
 
-JSClassRef JSClassCreate(JSContextRef context, JSStaticValue* staticValues, JSStaticFunction* staticFunctions, const JSObjectCallbacks* callbacks, JSClassRef parentClass);
-void JSClassRelease(JSClassRef jsClass);
+/*!
+@function
+@abstract Creates a JavaScript class suitable for use with JSObjectMake. Ownership follows the create rule.
+@param staticValues A JSStaticValue array representing the class's static value properties. Pass NULL to specify no static value properties. The array must be terminated by a JSStaticValue whose name field is NULL.
+@param staticFunctions A JSStaticFunction array representing the class's static function properties. Pass NULL to specify no static function properties. The array must be terminated by a JSStaticFunction whose name field is NULL.
+@param callbacks A pointer to a JSObjectCallbacks structure holding custom callbacks for supplementing default object behavior. Pass NULL to specify no custom behavior.
+@param parentClass A JSClass to set as the class's parent class. Pass NULL use the default object class.
+@discussion The simplest and most efficient way to add custom properties to a class is by specifying static values and functions. Standard JavaScript practice calls for functions to be placed in prototype objects, so that they can be shared among objects.
+*/
+JSClassRef JSClassCreate(JSStaticValue* staticValues, JSStaticFunction* staticFunctions, const JSObjectCallbacks* callbacks, JSClassRef parentClass);
+/*!
+@function
+@abstract Retains a JavaScript class.
+@param jsClass The JSClass to retain.
+@result A JSClass that is the same as jsClass.
+*/
 JSClassRef JSClassRetain(JSClassRef jsClass);
+/*!
+@function
+@abstract Releases a JavaScript class.
+@param jsClass The JSClass to release.
+*/
+void JSClassRelease(JSClassRef jsClass);
 
-// pass NULL as prototype to get the built-in object prototype
+/*!
+@function
+@abstract Creates a JavaScript object with a given class and prototype.
+@param context The execution context to use.
+@param jsClass The JSClass to assign to the object. Pass NULL to use the default object class.
+@param prototype The prototype to assign to the object. Pass NULL to use the default object prototype.
+@result A JSObject with the given class and prototype.
+*/
 JSObjectRef JSObjectMake(JSContextRef context, JSClassRef jsClass, JSObjectRef prototype);
 
-// Will be assigned the built-in function prototype
+/*!
+@function
+@abstract Convenience method for creating a JavaScript function with a given callback as its implementation.
+@param context The execution context to use.
+@param callAsFunction The JSCallAsFunctionCallback to invoke when the function is called.
+@result A JSObject that is an anonymous function. The object's prototype will be the default function prototype.
+*/
 JSObjectRef JSFunctionMake(JSContextRef context, JSCallAsFunctionCallback callAsFunction);
-// Will be assigned the built-in object prototype
+/*!
+@function
+@abstract Convenience method for creating a JavaScript constructor with a given callback as its implementation.
+@param context The execution context to use.
+@param callAsConstructor The JSCallAsConstructorCallback to invoke when the constructor is used in a 'new' statement.
+@result A JSObject that is a constructor. The object's prototype will be the default object prototype.
+*/
 JSObjectRef JSConstructorMake(JSContextRef context, JSCallAsConstructorCallback callAsConstructor);
 
-// returns NULL if functionBody has a syntax error
-JSObjectRef JSFunctionMakeWithBody(JSContextRef context, JSStringBufferRef body, JSStringBufferRef sourceURL, int startingLineNumber);
+/*!
+@function
+@abstract Creates a function with a given script as its body.
+@param context The execution context to use.
+@param body A JSStringBuffer containing the script to use as the function's body.
+@param sourceURL A JSStringBuffer containing a URL for the script's source file. This is only used when reporting exceptions. Pass NULL if you do not care to include source file information in exceptions.
+@param startingLineNumber An integer value specifying the script's starting line number in the file located at sourceURL. This is only used when reporting exceptions.
+@param exception A pointer to a JSValueRef in which to store a syntax error exception, if any. Pass NULL if you do not care to store a syntax error exception.
+@result A JSObject that is an anonymous function, or NULL if body contains a syntax error. The returned object's prototype will be the default function prototype.
+@discussion Use this method when you want to execute a script repeatedly, to avoid the cost of re-parsing the script before each execution.
+*/
+JSObjectRef JSFunctionMakeWithBody(JSContextRef context, JSStringBufferRef body, JSStringBufferRef sourceURL, int startingLineNumber, JSValueRef* exception);
 
+/*!
+@function
+@abstract Gets a short description of a JavaScript object.
+@param context The execution context to use.
+@param object The object whose description you want to get.
+@result A JSStringBuffer containing the object's description. This is usually the object's class name.
+*/
 JSStringBufferRef JSObjectGetDescription(JSObjectRef object);
 
+/*!
+@function
+@abstract Gets an object's prototype.
+@param object A JSObject whose prototype you want to get.
+@result A JSValue containing the object's prototype.
+*/
 JSValueRef JSObjectGetPrototype(JSObjectRef object);
+/*!
+@function
+@abstract Sets an object's prototype.
+@param object The JSObject whose prototype you want to set.
+@param value A JSValue to set as the object's prototype.
+*/
 void JSObjectSetPrototype(JSObjectRef object, JSValueRef value);
 
+/*!
+@function
+@abstract Tests whether an object has a certain property.
+@param object The JSObject to test.
+@param propertyName A JSStringBuffer containing the property's name.
+@result true if the object has a property whose name matches propertyName, otherwise false.
+*/
 bool JSObjectHasProperty(JSContextRef context, JSObjectRef object, JSStringBufferRef propertyName);
+/*!
+@function
+@abstract Gets a property from an object.
+@param context The execution context to use.
+@param object The JSObject whose property you want to get.
+@param propertyName A JSStringBuffer containing the property's name.
+@param value A pointer to a JSValueRef in which to store the property's value. On return, value will contain the property's value. Pass NULL if you do not care to store the property's value.
+@result true if the object has a property whose name matches propertyName, otherwise false. If this function returns false, the contents of value will be unmodified.
+*/
 bool JSObjectGetProperty(JSContextRef context, JSObjectRef object, JSStringBufferRef propertyName, JSValueRef* value);
+/*!
+@function
+@abstract Sets a property on an object.
+@param context The execution context to use.
+@param object The JSObject whose property you want to set.
+@param propertyName A JSStringBuffer containing the property's name.
+@param value A JSValue to use as the property's value.
+@param attributes A logically ORed set of JSPropertyAttributes to give to the property.
+@result true if the set operation succeeds, otherwise false (for example, if the object already has a property of the given name with the kJSPropertyAttributeReadOnly attribute set).
+*/
 bool JSObjectSetProperty(JSContextRef context, JSObjectRef object, JSStringBufferRef propertyName, JSValueRef value, JSPropertyAttributes attributes);
+/*!
+@function
+@abstract Deletes a property from an object.
+@param context The execution context to use.
+@param object The JSObject whose property you want to delete.
+@param propertyName A JSStringBuffer containing the property's name.
+@result true if the delete operation succeeds, otherwise false (for example, if the property has the kJSPropertyAttributeDontDelete attribute set).
+*/
 bool JSObjectDeleteProperty(JSContextRef context, JSObjectRef object, JSStringBufferRef propertyName);
 
-// Only works with objects created by JSObjectMake
+/*!
+@function
+@abstract Gets a pointer to private data from an object.
+@param object A JSObject whose private data you want to get.
+@result A void* that points to the object's private data, or NULL if the object has no private data.
+@discussion JSObjectGetPrivate and JSObjectSetPrivate only work on custom objects created by JSObjectMake, JSFunctionMake, and JSConstructorMake.
+*/
 void* JSObjectGetPrivate(JSObjectRef object);
+/*!
+@function
+@abstract Sets a pointer to private data on an object.
+@param object A JSObject whose private data you want to set.
+@param data A void* that points to the object's private data.
+@result true if the set operation succeeds, otherwise false.
+@discussion JSObjectGetPrivate and JSObjectSetPrivate only work on custom objects created by JSObjectMake, JSFunctionMake, and JSConstructorMake.
+*/
 bool JSObjectSetPrivate(JSObjectRef object, void* data);
 
+/*!
+@function
+@abstract Tests whether an object is a function.
+@param object The JSObject to test.
+@result true if the object is a function, otherwise false.
+*/
 bool JSObjectIsFunction(JSObjectRef object);
+/*!
+@function
+@abstract Calls an object as a function.
+@param context The execution context to use.
+@param object The JSObject to call as a function.
+@param thisObject The JSObject to use as 'this' in the function call.
+@param argc An integer count of the number of arguments in argv.
+@param argv A JSValue array of the  arguments to pass to the function.
+@param exception A pointer to a JSValueRef in which to store an uncaught exception, if any. Pass NULL if you do not care to store an uncaught exception.
+@result The JSValue that results from calling object as a function, or NULL if an uncaught exception is thrown or object is not a function.
+*/
 JSValueRef JSObjectCallAsFunction(JSContextRef context, JSObjectRef object, JSObjectRef thisObject, size_t argc, JSValueRef argv[], JSValueRef* exception);
+/*!
+@function
+@abstract Tests whether an object is a constructor.
+@param object The JSObject to test.
+@result true if the object is a constructor, otherwise false.
+*/
 bool JSObjectIsConstructor(JSObjectRef object);
+/*!
+@function
+@abstract Calls an object as a constructor.
+@param context The execution context to use.
+@param object The JSObject to call as a constructor.
+@param argc An integer count of the number of arguments in argv.
+@param argv A JSValue array of the  arguments to pass to the function.
+@param exception A pointer to a JSValueRef in which to store an uncaught exception, if any. Pass NULL if you do not care to store an uncaught exception.
+@result The JSObject that results from calling object as a constructor, or NULL if an uncaught exception is thrown or object is not a constructor.
+*/
 JSObjectRef JSObjectCallAsConstructor(JSContextRef context, JSObjectRef object, size_t argc, JSValueRef argv[], JSValueRef* exception);
 
-// Used for enumerating the names of an object's properties like a for...in loop would
+/*!
+@function
+@abstract Creates an enumerator for an object's properties.
+@param context The execution context to use.
+@param object The object whose properties you want to enumerate.
+@result A JSPropertyEnumerator with a list of object's properties. Ownership follows the create rule.
+*/
 JSPropertyEnumeratorRef JSObjectCreatePropertyEnumerator(JSContextRef context, JSObjectRef object);
+/*!
+@function
+@abstract Retains a property enumerator.
+@param enumerator The JSPropertyEnumerator to retain.
+@result A JSPropertyEnumerator that is the same as enumerator.
+*/
 JSPropertyEnumeratorRef JSPropertyEnumeratorRetain(JSPropertyEnumeratorRef enumerator);
+/*!
+@function
+@abstract Releases a property enumerator.
+@param enumerator The JSPropertyEnumerator to release.
+*/
 void JSPropertyEnumeratorRelease(JSPropertyEnumeratorRef enumerator);
+/*!
+@function
+@abstract Gets a property enumerator's next property.
+@param context The execution context to use.
+@param enumerator The JSPropertyEnumerator whose next property you want to get.
+@result A JSStringBuffer containing the property's name, or NULL if all properties have been enumerated.
+*/
 JSStringBufferRef JSPropertyEnumeratorGetNext(JSContextRef context, JSPropertyEnumeratorRef enumerator);
 
-// Used for adding property names to a for...in enumeration
+/*!
+@function
+@abstract Adds a property to a property list.
+@discussion Use this method inside a JSGetPropertyListCallback to add a custom property to an object's property list.
+@param propertyList The JSPropertyList to which you want to add a property.
+@param thisObject The JSObject to which the property belongs.
+@param propertyName A JSStringBuffer specifying the property's name.
+*/
 void JSPropertyListAdd(JSPropertyListRef propertyList, JSObjectRef thisObject, JSStringBufferRef propertyName);
 
 #ifdef __cplusplus
index c42a47f1d78ed33a1942a07ec87602ddc2de4541..7594b9060e1115ef46ef68cf6e3a7b9309669b6d 100644 (file)
@@ -139,7 +139,7 @@ bool JSStringBufferIsEqualUTF8(JSStringBufferRef a, const char* b)
 }
 
 #if defined(__APPLE__)
-JSStringBufferRef JSStringBufferCreateWithCFString(CFStringRef string)
+JSStringBufferRef JSStringBufferCreateCF(CFStringRef string)
 {
     JSLock lock;
     CFIndex length = CFStringGetLength(string);
index e4218aecf0a42c1a0cbc8ce1607655671961e2cf..2a7dcabafcbfc7129f3730568e1420c5c4606f55 100644 (file)
 extern "C" {
 #endif
 
-#if defined(WIN32) || defined(_WIN32)
-    typedef wchar_t JSChar;
-#else
+/*!
+@typedef JSChar
+@abstract A Unicode character.
+*/
+#if !defined(WIN32) && !defined(_WIN32)
     typedef unsigned short JSChar;
+#else
+    typedef wchar_t JSChar;
 #endif
-    
+
+/*!
+@function
+@abstract         Creates a JavaScript string buffer from a buffer of Unicode characters.
+@param chars      The buffer of Unicode characters to copy into the new JSStringBuffer.
+@param numChars   The number of characters to copy from the buffer pointed to by chars.
+@result           A JSStringBuffer containing chars. Ownership follows the create rule.
+*/
 JSStringBufferRef JSStringBufferCreate(const JSChar* chars, size_t numChars);
+/*!
+@function
+@abstract         Creates a JavaScript string buffer from a null-terminated UTF8 string.
+@param string     The null-terminated UTF8 string to copy into the new JSStringBuffer.
+@result           A JSStringBuffer containing string. Ownership follows the create rule.
+*/
 JSStringBufferRef JSStringBufferCreateUTF8(const char* string);
 
+/*!
+@function
+@abstract         Retains a JavaScript string buffer.
+@param buffer     The JSStringBuffer to retain.
+@result           A JSStringBuffer that is the same as buffer.
+*/
 JSStringBufferRef JSStringBufferRetain(JSStringBufferRef buffer);
+/*!
+@function
+@abstract         Releases a JavaScript string buffer.
+@param buffer     The JSStringBuffer to release.
+*/
 void JSStringBufferRelease(JSStringBufferRef buffer);
 
+/*!
+@function
+@abstract         Returns the number of Unicode characters in a JavaScript string buffer.
+@param buffer     The JSStringBuffer whose length (in Unicode characters) you want to know.
+@result           The number of Unicode characters stored in buffer.
+*/
 size_t JSStringBufferGetLength(JSStringBufferRef buffer);
+/*!
+@function
+@abstract         Quickly obtains a pointer to the Unicode character buffer that 
+ serves as the backing store for a JavaScript string buffer.
+@param buffer     The JSStringBuffer whose backing store you want to access.
+@result           A pointer to the Unicode character buffer that serves as buffer's 
+ backing store, which will be deallocated when buffer is deallocated.
+*/
 const JSChar* JSStringBufferGetCharactersPtr(JSStringBufferRef buffer);
+/*!
+@function
+@abstract         Copies a JavaScript string buffer's Unicode characters into an 
+ external character buffer.
+@param inBuffer   The source JSStringBuffer.
+@param outBuffer  The destination JSChar buffer into which to copy inBuffer's 
+ characters. On return, outBuffer contains the requested Unicode characters.
+@param numChars   The number of Unicode characters to copy. This number must not 
+ exceed the length of the string buffer.
+*/
 void JSStringBufferGetCharacters(JSStringBufferRef inBuffer, JSChar* outBuffer, size_t numChars);
 
+/*!
+@function
+@abstract         Returns the maximum number of bytes required to encode the 
+ contents of a JavaScript string buffer as a null-terminated UTF8 string.
+@param buffer     The JSStringBuffer whose maximum encoded length (in bytes) you 
+ want to know.
+@result           The maximum number of bytes required to encode buffer's contents 
+ as a null-terminated UTF8 string.
+*/
 size_t JSStringBufferGetMaxLengthUTF8(JSStringBufferRef buffer);
-// Returns the number of bytes written into outBuffer, including the trailing '\0'
+/*!
+@function
+@abstract         Converts a JavaScript string buffer's contents into a 
+ null-terminated UTF8 string, and copies the result into an external byte buffer.
+@param inBuffer   The source JSStringBuffer.
+@param outBuffer  The destination byte buffer into which to copy a UTF8 string 
+ representation of inBuffer. The buffer must be at least bufferSize bytes in length. 
+ On return, outBuffer contains a UTF8 string representation of inBuffer. 
+ If bufferSize is too small, outBuffer will contain only partial results.
+@param bufferSize The length of the external buffer in bytes.
+@result           The number of bytes written into outBuffer (including the null-terminator byte).
+*/
 size_t JSStringBufferGetCharactersUTF8(JSStringBufferRef inBuffer, char* outBuffer, size_t bufferSize);
 
+/*!
+@function
+@abstract     Tests whether the characters in two JavaScript string buffers match.
+@param a      The first JSStringBuffer to test.
+@param b      The second JSStringBuffer to test.
+@result       true if the characters in the two buffers match, otherwise false.
+*/
 bool JSStringBufferIsEqual(JSStringBufferRef a, JSStringBufferRef b);
+/*!
+@function
+@abstract     Tests whether the characters in a JavaScript string buffer match 
+ the characters in a null-terminated UTF8 string.
+@param a      The JSStringBuffer to test.
+@param b      The null-terminated UTF8 string to test.
+@result       true if the characters in the two buffers match, otherwise false.
+*/
 bool JSStringBufferIsEqualUTF8(JSStringBufferRef a, const char* b);
 
 #if defined(__APPLE__)
 #include <CoreFoundation/CoreFoundation.h>
 // CFString convenience methods
-JSStringBufferRef JSStringBufferCreateWithCFString(CFStringRef string);
+/*!
+@function
+@abstract         Creates a JavaScript string buffer from a CFString.
+@discussion       This function is optimized to take advantage of cases when 
+ CFStringGetCharactersPtr returns a valid pointer.
+@param string     The CFString to copy into the new JSStringBuffer.
+@result           A JSStringBuffer containing string. Ownership follows the create rule.
+*/
+JSStringBufferRef JSStringBufferCreateCF(CFStringRef string);
+/*!
+@function
+@abstract         Creates a CFString form a JavaScript string buffer.
+@param alloc      The alloc parameter to pass to CFStringCreate.
+@param buffer     The JSStringBuffer to copy into the new CFString.
+@result           A CFString containing buffer. Ownership follows the create rule.
+*/
 CFStringRef CFStringCreateWithJSStringBuffer(CFAllocatorRef alloc, JSStringBufferRef buffer);
 #endif // __APPLE__
     
index 6d0f8b8759fc759afb8007481299169eafe27b0e..7b86c74f2c044d34c03b339075789277e6a39471 100644 (file)
@@ -135,14 +135,14 @@ bool JSValueIsStrictEqual(JSContextRef context, JSValueRef a, JSValueRef b)
     return result;
 }
 
-bool JSValueIsInstanceOf(JSContextRef context, JSValueRef value, JSObjectRef object)
+bool JSValueIsInstanceOf(JSContextRef context, JSValueRef value, JSObjectRef constructor)
 {
     ExecState* exec = toJS(context);
     JSValue* jsValue = toJS(value);
-    JSObject* jsObject = toJS(object);
-    if (!jsObject->implementsHasInstance())
+    JSObject* jsConstructor = toJS(constructor);
+    if (!jsConstructor->implementsHasInstance())
         return false;
-    bool result = jsObject->hasInstance(exec, jsValue);
+    bool result = jsConstructor->hasInstance(exec, jsValue);
     if (exec->hadException())
         exec->clearException();
     return result;
index 4779bd5e9ff32f61041ac82e471c139214841f68..8347b0dc67a5b9ecd6a8c473b2addfec4deedb9a 100644 (file)
@@ -21,7 +21,7 @@
  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
 #ifndef JSValueRef_h
 #include "JSBase.h"
 
 /*!
-  @enum JSTypeCode
-  A constant identifying the type of a JSValueRef.
-  @constant kJSTypeUndefined the unique undefined value
-  @constant kJSTypeNull the unique null value
-  @constant kJSBoolean a primitive boolean value, one of true or false
-  @constant kJSTypeNumber a primitive number value
-  @constant kJSTypeString a primitive string value
-  @constant kJSTypeObject an object (meaning that this JSValueRef is a JSObjectRef)
+@enum JSTypeCode
+@abstract     A constant identifying the type of a JSValue.
+@constant     kJSTypeUndefined  The unique undefined value.
+@constant     kJSTypeNull       The unique null value.
+@constant     kJSTypeBoolean    A primitive boolean value, one of true or false.
+@constant     kJSTypeNumber     A primitive number value.
+@constant     kJSTypeString     A primitive string value.
+@constant     kJSTypeObject     An object value (meaning that this JSValueRef is a JSObjectRef).
 */
 typedef enum {
     kJSTypeUndefined,
@@ -53,199 +53,213 @@ extern "C" {
 #endif
 
 /*!
-  @function JSValueGetType
-  Get the type code for a particular JavaScript value
-  @param value the JS value for which the type should be determined
-  @result      a type code identifying the type
+@function
+@abstract       Returns a JavaScript value's type code.
+@param value    The JSValue whose type you want to obtain.
+@result         A value of type JSTypeCode that identifies value's type.
 */
 JSTypeCode JSValueGetType(JSValueRef value);
 
 /*!
-  @function JSValueIsUndefined
-  Determine if value is of type undefined
-  @param value the JS value to check for undefined type
-  @result      true if the value is undefined, false otherwise
+@function
+@abstract       Tests whether a JavaScript value's type is the undefined type.
+@param value    The JSValue to test.
+@result         true if value's type is the undefined type, otherwise false.
 */
 bool JSValueIsUndefined(JSValueRef value);
 
 /*!
-  @function JSValueIsNull
-  Determine if value is of type null
-  @param value the JS value to check for null type
-  @result      true if the value is null, false otherwise
+@function
+@abstract       Tests whether a JavaScript value's type is the null type.
+@param value    The JSValue to test.
+@result         true if value's type is the null type, otherwise false.
 */
 bool JSValueIsNull(JSValueRef value);
 
 /*!
-  @function JSValueIsBoolean
-  Determine if value is of type boolean
-  @param value the JS value to check for boolean type
-  @result      true if the value is a boolean, false otherwise
+@function
+@abstract       Tests whether a JavaScript value's type is the boolean type.
+@param value    The JSValue to test.
+@result         true if value's type is the boolean type, otherwise false.
 */
 bool JSValueIsBoolean(JSValueRef value);
 
 /*!
-  @function JSValueIsNumber
-  Determine if value is of type number
-  @param value the JS value to check for number type
-  @result      true if the value is a number, false otherwise
+@function
+@abstract       Tests whether a JavaScript value's type is the number type.
+@param value    The JSValue to test.
+@result         true if value's type is the number type, otherwise false.
 */
 bool JSValueIsNumber(JSValueRef value);
 
 /*!
-  @function JSValueIsString
-  Determine if value is of type string
-  @param value the JS value to check for string type
-  @result      true if the value is a string, false otherwise
+@function
+@abstract       Tests whether a JavaScript value's type is the string type.
+@param value    The JSValue to test.
+@result         true if value's type is the string type, otherwise false.
 */
 bool JSValueIsString(JSValueRef value);
 
 /*!
-  @function JSValueIsObject
-  Determine if value is of type object
-  @param value the JS value to check for object type
-  @result      true if the value is an object, false otherwise
+@function
+@abstract       Tests whether a JavaScript value's type is the object type.
+@param value    The JSValue to test.
+@result         true if value's type is the object type, otherwise false.
 */
 bool JSValueIsObject(JSValueRef value);
+
+/*!
+@function
+@abstract       Tests whether a JavaScript value is an object with a given 
+ class in its class chain.
+@param value    The JSValue to test.
+ @result        true if value is an object and has jsClass in its class chain, 
+ otherwise false.
+*/
 bool JSValueIsObjectOfClass(JSValueRef value, JSClassRef jsClass);
 
 // Comparing values
 
 /*!
-  @function JSValueIsEqual
-  Check if two values are equal by JavaScript rules, as if compared by the JS == operator
-  @param context the execution context to use 
-  @param a       the first value to compare
-  @param b       the second value to compare
-  @result        true if the two values are equal, false otherwise
+@function
+@abstract       Tests whether two JavaScript values are equal, as compared by the JS == operator.
+@param context  The execution context to use.
+@param a        The first value to test.
+@param b        The second value to test.
+@result         true if the two values are equal, otherwise false.
 */
 bool JSValueIsEqual(JSContextRef context, JSValueRef a, JSValueRef b);
 
 /*!
-  @function JSValueIsStrictEqual
-  Check if two values are strict equal by JavaScript rules, as if compared by the JS === operator
-  @param context the execution context to use 
-  @param a       the first value to compare
-  @param b       the second value to compare
-  @result        true if the two values are strict equal, false otherwise
+@function
+@abstract       Tests whether two JavaScript values are strict equal, as compared by the JS === operator.
+@param context  The execution context to use.
+@param a        The first value to test.
+@param b        The second value to test.
+@result         true if the two values are strict equal, otherwise false.
 */
 bool JSValueIsStrictEqual(JSContextRef context, JSValueRef a, JSValueRef b);
 
 /*!
-  @function JSValueIsInstanceOf
-  Check if a value is an instance of a particular object; generally this means the object
-  was used as the constructor for that instance
-  @param context the execution context to use 
-  @param value   the possible instance
-  @param object  the possible constructor
-  @result        true if value is an instance of object
+@function
+@abstract       Tests whether a JavaScript value is an object constructed by
+ a given constructor, as compared by the JS instanceof operator.
+@param context  The execution context to use.
+@param value    The JSValue to test.
+@param object   The constructor to test against.
+@result         true if value is an object constructed by constructor, as compared
+ by the JS instanceof operator, otherwise false.
 */
-bool JSValueIsInstanceOf(JSContextRef context, JSValueRef value, JSObjectRef object);
+bool JSValueIsInstanceOf(JSContextRef context, JSValueRef value, JSObjectRef constructor);
 
 // Creating values
 
 /*!
-  @function JSUndefinedMake
-  Make a value of the undefined type.
-  @result The unique undefined value.
+@function
+@abstract   Creates a JavaScript value of the undefined type.
+@result     The unique undefined value.
 */
 JSValueRef JSUndefinedMake(void);
 
 /*!
-  @function JSNullMake
-  Make a value of the null type.
-  @result the unique null value
+@function
+@abstract   Creates a JavaScript value of the null type.
+@result     The unique null value.
 */
 JSValueRef JSNullMake(void);
 
 /*!
-  @function JSBooleanMake
-  Make a value of the boolean type.
-  @param value whether the returned value should be true or false
-  @result      a JS true or false boolean value, as appropriate
+@function
+@abstract       Creates a JavaScript value of the boolean type.
+@param value    The boolean value to assign to the newly created JSValue.
+@result         A JSValue of the boolean type, representing the boolean value of value.
 */
 
 JSValueRef JSBooleanMake(bool value);
 
 /*!
-  @function JSNumberMake
-  Make a value of the number type.
-  @param  value the numberic value of the number to make
-  @result a JS number corresponding to value
+@function
+@abstract       Creates a JavaScript value of the number type.
+@param value    The numeric value to assign to the newly created JSValue.
+@result         A JSValue of the number type, representing the numeric value of value.
 */
 JSValueRef JSNumberMake(double value);
 
 /*!
-  @function JSStringMake
-  Make a value of the string type.
-  @param  buffer the internal string contents for the string value
-  @result a JS string value that has the value of the buffer
+@function
+@abstract       Creates a JavaScript value of the string type.
+@param buffer   The JSStringBuffer to assign to the newly created JSValue. The
+ newly created JSValue retains buffer, and releases it upon garbage collection.
+@result         A JSValue of the string type, representing the string value of buffer.
 */
 JSValueRef JSStringMake(JSStringBufferRef buffer);
 
 // Converting to primitive values
 
 /*!
-  @function JSValueToBoolean
-  Convert a JavaScript value to boolean and return the resulting boolean
-  @param context the execution context to use 
-  @param value   the value to convert
-  @result        the boolean result of conversion
+@function
+@abstract       Converts a JavaScript value to boolean and returns the resulting boolean.
+@param context  The execution context to use.
+@param value    The JSValue to convert.
+@result         The boolean result of conversion.
 */
 bool JSValueToBoolean(JSContextRef context, JSValueRef value);
 
 /*!
-  @function JSValueToNumber
-  Convert a JavaScript value to number and return the resulting number
-  @param context the execution context to use 
-  @param value   the value to convert
-  @result        the numeric result of conversion, or NaN if conversion fails
+@function
+@abstract       Converts a JavaScript value to number and returns the resulting number.
+@param context  The execution context to use.
+@param value    The JSValue to convert.
+@result         The numeric result of conversion, or NaN if conversion fails.
 */
 double JSValueToNumber(JSContextRef context, JSValueRef value);
 
 /*!
-  @function JSValueCopyStringValue
-  Convert a JavaScript value to string and copy the resulting string into a newly allocated character buffer
-  @param context the execution context to use
-  @param value   the value to convert
-  @result        a character buffer containing the result of conversion, or an empty character buffer if conversion fails
+@function
+@abstract       Converts a JavaScript value to string and copies the resulting
+ string into a newly allocated JavaScript string buffer.
+@param context  The execution context to use.
+@param value    The JSValue to convert.
+@result         A JSStringBuffer containing the result of conversion, or an empty
+ string buffer if conversion fails. Ownership follows the copy rule.
 */
 JSStringBufferRef JSValueCopyStringValue(JSContextRef context, JSValueRef value);
 
 /*!
-  @function JSValueToObject
-  Convert a JavaScript value to object and return the resulting object
-  @param context the execution context to use 
-  @param value   the value to convert
-  @result        the object result of conversion, or NULL if conversion fails
+@function
+@abstract Converts a JavaScript value to object and returns the resulting object.
+@param context  The execution context to use.
+@param value    The JSValue to convert.
+@result         The JSObject result of conversion, or NULL if conversion fails.
 */
 JSObjectRef JSValueToObject(JSContextRef context, JSValueRef value);
 
 // Garbage collection
 /*!
-  @function JSGCProtect
-  Protect a JavaScript value from garbage collection; a value may be
-  protected multiple times and must be unprotected an equal number of
-  times to become collectable again.
+@function
+@abstract       Protects a JavaScript value from garbage collection.
+@param value    The JSValue to protect.
+@discussion     A value may be protected multiple times and must be unprotected an
+ equal number of times before becoming eligible for garbage collection.
 */
 void JSGCProtect(JSValueRef value);
 
 /*!
-  @function JSGCProtect
-  Stop protecting a JavaScript value from garbage collection; a value may be
-  protected multiple times and must be unprotected an equal number of
-  times to become collectable again.
+@function
+@abstract       Unprotects a JavaScript value from garbage collection.
+@param value    The JSValue to unprotect.
+@discussion     A value may be protected multiple times and must be unprotected an 
+ equal number of times before becoming eligible for garbage collection.
 */
 void JSGCUnprotect(JSValueRef value);
 
-/*! 
-  @function JSGCCollect
-  Immediately perform a JavaScript garbage collection. JavaScript
-  values that are on the machine stack, in a register, protected, set
-  as the global object of any interpreter, or reachable from any such
-  value will not be collected. It is not normally necessary to call
-  this function directly; the JS runtime will garbage collect as
-  needed.
+/*!
+@function
+@abstract Performs a JavaScript garbage collection. 
+@discussion JavaScript values that are on the machine stack, in a register, 
+ protected by JSGCProtect, set as the global object of an execution context, or reachable from any such
+ value will not be collected. It is not normally necessary to call this function 
+ directly; the JS runtime will garbage collect as needed.
 */
 void JSGCCollect(void);
 
index 3659b351a553aec0461bcc2bbbaf2bea7962a2dc..2771fc0a982b4e4c573fed782e112a326f95eba8 100644 (file)
@@ -36,7 +36,7 @@ int main(int argc, char* argv[])
     UNUSED_PARAM(argc);
     UNUSED_PARAM(argv);
     
-    JSContextRef context = JSContextCreate(NULL, NULL);
+    JSContextRef context = JSContextCreate(NULL);
     JSObjectRef globalObject = JSContextGetGlobalObject(context);
     
     JSStringBufferRef printBuf = JSStringBufferCreateUTF8("print");
index 38a886fe6a583501f59eb76472039e3911845cef..34b79d0f64801d5f9fe32fb1ded71a113418a5ff 100644 (file)
@@ -129,8 +129,9 @@ static void MyObject_initialize(JSObjectRef object)
     didInitialize = true;
 }
 
-static bool MyObject_hasProperty(JSObjectRef object, JSStringBufferRef propertyName)
+static bool MyObject_hasProperty(JSContextRef context, JSObjectRef object, JSStringBufferRef propertyName)
 {
+    UNUSED_PARAM(context);
     UNUSED_PARAM(object);
 
     if (JSStringBufferIsEqualUTF8(propertyName, "alwaysOne")
@@ -165,8 +166,9 @@ static bool MyObject_getProperty(JSContextRef context, JSObjectRef object, JSStr
     return false;
 }
 
-static bool MyObject_setProperty(JSObjectRef object, JSStringBufferRef propertyName, JSValueRef value)
+static bool MyObject_setProperty(JSContextRef context, JSObjectRef object, JSStringBufferRef propertyName, JSValueRef value)
 {
+    UNUSED_PARAM(context);
     UNUSED_PARAM(object);
     UNUSED_PARAM(value);
 
@@ -176,8 +178,9 @@ static bool MyObject_setProperty(JSObjectRef object, JSStringBufferRef propertyN
     return false;
 }
 
-static bool MyObject_deleteProperty(JSObjectRef object, JSStringBufferRef propertyName)
+static bool MyObject_deleteProperty(JSContextRef context, JSObjectRef object, JSStringBufferRef propertyName)
 {
+    UNUSED_PARAM(context);
     UNUSED_PARAM(object);
     
     if (JSStringBufferIsEqualUTF8(propertyName, "cantDelete"))
@@ -186,8 +189,10 @@ static bool MyObject_deleteProperty(JSObjectRef object, JSStringBufferRef proper
     return false;
 }
 
-static void MyObject_getPropertyList(JSObjectRef object, JSPropertyListRef propertyList)
+static void MyObject_getPropertyList(JSContextRef context, JSObjectRef object, JSPropertyListRef propertyList)
 {
+    UNUSED_PARAM(context);
+    
     JSStringBufferRef propertyNameBuf;
     
     propertyNameBuf = JSStringBufferCreateUTF8("alwaysOne");
@@ -222,8 +227,9 @@ static JSObjectRef MyObject_callAsConstructor(JSContextRef context, JSObjectRef
     return JSValueToObject(context, JSNumberMake(0));
 }
 
-static bool MyObject_convertToType(JSObjectRef object, JSTypeCode typeCode, JSValueRef* returnValue)
+static bool MyObject_convertToType(JSContextRef context, JSObjectRef object, JSTypeCode typeCode, JSValueRef* returnValue)
 {
+    UNUSED_PARAM(context);
     UNUSED_PARAM(object);
     
     switch (typeCode) {
@@ -267,7 +273,7 @@ static JSClassRef MyObject_class(JSContextRef context)
 {
     static JSClassRef jsClass;
     if (!jsClass) {
-        jsClass = JSClassCreate(context, NULL, NULL, &MyObject_callbacks, NULL);
+        jsClass = JSClassCreate(NULL, NULL, &MyObject_callbacks, NULL);
     }
     
     return jsClass;
@@ -311,7 +317,7 @@ int main(int argc, char* argv[])
     UNUSED_PARAM(argc);
     UNUSED_PARAM(argv);
     
-    context = JSContextCreate(NULL, NULL);
+    context = JSContextCreate(NULL);
 
     JSValueRef jsUndefined = JSUndefinedMake();
     JSValueRef jsNull = JSNullMake();
@@ -338,12 +344,12 @@ int main(int argc, char* argv[])
                                                           1,
                                                           kCFAllocatorNull);
 
-    JSStringBufferRef jsCFStringBuf = JSStringBufferCreateWithCFString(cfString);
+    JSStringBufferRef jsCFStringBuf = JSStringBufferCreateCF(cfString);
     JSValueRef jsCFString = JSStringMake(jsCFStringBuf);
     
     CFStringRef cfEmptyString = CFStringCreateWithCString(kCFAllocatorDefault, "", kCFStringEncodingUTF8);
     
-    JSStringBufferRef jsCFEmptyStringBuf = JSStringBufferCreateWithCFString(cfEmptyString);
+    JSStringBufferRef jsCFEmptyStringBuf = JSStringBufferCreateCF(cfEmptyString);
     JSValueRef jsCFEmptyString = JSStringMake(jsCFEmptyStringBuf);
 
     CFIndex cfStringLength = CFStringGetLength(cfString);
@@ -499,11 +505,14 @@ int main(int argc, char* argv[])
 
     JSValueRef result;
     JSValueRef exception;
+    JSValueRef v;
+    JSObjectRef o;
 
     result = JSEvaluate(context, goodSyntaxBuf, NULL, NULL, 1, NULL);
     assert(result);
     assert(JSValueIsEqual(context, result, jsOne));
-    
+
+    exception = NULL;
     result = JSEvaluate(context, badSyntaxBuf, NULL, NULL, 1, &exception);
     assert(!result);
     assert(!JSContextGetException(context));
@@ -526,8 +535,8 @@ int main(int argc, char* argv[])
     JSStringBufferRelease(goodSyntaxBuf);
     JSStringBufferRelease(badSyntaxBuf);
 
+    v = NULL;
     JSStringBufferRef arrayBuf = JSStringBufferCreateUTF8("Array");
-    JSValueRef v;
     assert(JSObjectGetProperty(context, globalObject, arrayBuf, &v));
     JSObjectRef arrayConstructor = JSValueToObject(context, v);
     JSStringBufferRelease(arrayBuf);
@@ -538,12 +547,19 @@ int main(int argc, char* argv[])
     
     JSStringBufferRef functionBuf;
     
+    v = NULL;
+    exception = NULL;
     functionBuf = JSStringBufferCreateUTF8("rreturn Array;");
-    assert(!JSFunctionMakeWithBody(context, functionBuf, NULL, 1));
+    JSStringBufferRef lineBuf = JSStringBufferCreateUTF8("line");
+    assert(!JSFunctionMakeWithBody(context, functionBuf, NULL, 1, &exception));
+    assert(JSValueIsObject(exception));
+    assert(JSObjectGetProperty(context, exception, lineBuf, &v));
+    assertEqualsAsNumber(v, 2); // FIXME: Lexer::setCode bumps startingLineNumber by 1 -- we need to change internal callers so that it doesn't have to (saying '0' to mean '1' in the API would be really confusing -- it's really confusing internally, in fact)
     JSStringBufferRelease(functionBuf);
+    JSStringBufferRelease(lineBuf);
 
     functionBuf = JSStringBufferCreateUTF8("return Array;");
-    JSObjectRef function = JSFunctionMakeWithBody(context, functionBuf, NULL, 1);
+    JSObjectRef function = JSFunctionMakeWithBody(context, functionBuf, NULL, 1, NULL);
     JSStringBufferRelease(functionBuf);
 
     assert(JSObjectIsFunction(function));
@@ -557,14 +573,32 @@ int main(int argc, char* argv[])
     JSStringBufferRelease(myObjectBuf);
 
     JSStringBufferRef printBuf = JSStringBufferCreateUTF8("print");
-    JSObjectSetProperty(context, globalObject, printBuf, JSFunctionMake(context, print_callAsFunction), kJSPropertyAttributeNone); 
+    JSValueRef printFunction = JSFunctionMake(context, print_callAsFunction);
+    JSObjectSetProperty(context, globalObject, printBuf, printFunction, kJSPropertyAttributeNone); 
     JSStringBufferRelease(printBuf);
+    
+    assert(JSObjectSetPrivate(printFunction, (void*)1));
+    assert(JSObjectGetPrivate(printFunction) == (void*)1);
 
     JSStringBufferRef myConstructorBuf = JSStringBufferCreateUTF8("MyConstructor");
-    JSObjectSetProperty(context, globalObject, myConstructorBuf, JSConstructorMake(context, myConstructor_callAsConstructor), kJSPropertyAttributeNone);
+    JSValueRef myConstructor = JSConstructorMake(context, myConstructor_callAsConstructor);
+    JSObjectSetProperty(context, globalObject, myConstructorBuf, myConstructor, kJSPropertyAttributeNone);
     JSStringBufferRelease(myConstructorBuf);
+    
+    assert(JSObjectSetPrivate(myConstructor, (void*)1));
+    assert(JSObjectGetPrivate(myConstructor) == (void*)1);
+    
+    o = JSObjectMake(context, NULL, NULL);
+    JSObjectSetProperty(context, o, jsOneString, JSNumberMake(1), kJSPropertyAttributeNone);
+    JSObjectSetProperty(context, o, jsCFString,  JSNumberMake(1), kJSPropertyAttributeDontEnum);
+    JSPropertyEnumeratorRef enumerator = JSObjectCreatePropertyEnumerator(context, o);
+    int count = 0;
+    while (JSPropertyEnumeratorGetNext(context, enumerator))
+        ++count;
+    JSPropertyEnumeratorRelease(enumerator);
+    assert(count == 1); // jsCFString should not be enumerated
 
-    JSClassRef nullCallbacksClass = JSClassCreate(context, NULL, NULL, NULL, NULL);
+    JSClassRef nullCallbacksClass = JSClassCreate(NULL, NULL, NULL, NULL);
     JSClassRelease(nullCallbacksClass);
     
     char* script = createStringWithContentsOfFile("testapi.js");
index 687fc6fa0b931e6bb656517ce5beed04c6676eab..444bde026201f4014eacaf5c894c6976c7816d06 100644 (file)
@@ -1,3 +1,98 @@
+2006-07-06  Geoffrey Garen  <ggaren@apple.com>
+
+        Reviewed by Maciej.
+        
+        More API action.
+        
+        - Headerdoc finished
+
+        Semantic Changes:
+        - Added a JSContextRef argument to many functions, because you need a 
+        JSContextRef for doing virtually anything. I expect to add this argument
+        to even more functions in a future patch.
+        
+        - Removed the globalObjectPrototype argument to JSContextCreate because
+        you can't create an object until you have a context, so it's impossible
+        to pass a prototype object to JSContextCreate. That's OK because (1) there's
+        no reason to give the global object a prototype and (2) if you really want
+        to, you can just use a separate call to JSObjectSetPrototype.
+        
+        - Removed the JSClassRef argument to JSClassCreate because it was unnecessary,
+        and you need to be able to make the global object's class before you've
+        created a JSContext.
+        
+        - Added an optional exception parameter to JSFunctionMakeWithBody because anything
+        less would be uncivilized.
+        
+        - Made the return value parameter to JSObjectGetProperty optional to match
+        all other return value parameters in the API.
+        
+        - Made JSObjectSetPrivate/JSObjectGetPrivate work on JSCallbackFunctions
+        and JSCallbackConstructors. You could use an abstract base class or strategic
+        placement of m_privateData in the class structure to implement this, but 
+        the former seemed like overkill, and the latter seemed too dangerous.
+        
+        - Fixed a bug where JSPropertyEnumeratorGetNext would skip the first property.
+
+        Cosmetic Changes:
+        - Reversed the logic of the JSChar #ifdef to avoid confusing headerdoc
+        
+        - Removed function names from @function declarations because headeroc
+        can parse them automatically, and I wanted to rule out manual mismatch.
+
+        - Changed Error::create to take a const UString& instead of a UString*
+        because it was looking at me funny.
+        
+        - Renamed JSStringBufferCreateWithCFString to JSStringBufferCreateCF
+        because the latter is more concise and it matches JSStringBufferCreateUTF8.
+        
+        * API/JSCallbackObject.cpp:
+        (KJS::JSCallbackObject::getOwnPropertySlot):
+        (KJS::JSCallbackObject::put):
+        (KJS::JSCallbackObject::deleteProperty):
+        (KJS::JSCallbackObject::getPropertyList):
+        (KJS::JSCallbackObject::toBoolean):
+        (KJS::JSCallbackObject::toNumber):
+        (KJS::JSCallbackObject::toString):
+        * API/JSClassRef.cpp:
+        (JSClassCreate):
+        * API/JSContextRef.cpp:
+        (JSContextCreate):
+        (JSContextSetException):
+        * API/JSContextRef.h:
+        * API/JSNode.c:
+        (JSNodePrototype_class):
+        (JSNode_class):
+        * API/JSNodeList.c:
+        (JSNodeListPrototype_class):
+        (JSNodeList_class):
+        * API/JSObjectRef.cpp:
+        (JSObjectGetProperty):
+        (JSObjectGetPrivate):
+        (JSObjectSetPrivate):
+        (JSObjectCallAsFunction):
+        (JSObjectCallAsConstructor):
+        (JSPropertyEnumeratorGetNext):
+        * API/JSObjectRef.h:
+        * API/JSStringBufferRef.cpp:
+        (JSStringBufferCreateCF):
+        * API/JSStringBufferRef.h:
+        * API/JSValueRef.cpp:
+        (JSValueIsInstanceOf):
+        * API/JSValueRef.h:
+        * API/minidom.c:
+        (main):
+        * API/minidom.js:
+        * API/testapi.c:
+        (MyObject_hasProperty):
+        (MyObject_setProperty):
+        (MyObject_deleteProperty):
+        (MyObject_getPropertyList):
+        (MyObject_convertToType):
+        (MyObject_class):
+        (main):
+        * JavaScriptCore.exp:
+
 2006-07-07  Geoffrey Garen  <ggaren@apple.com>
 
         Reviewed by John.
index 7e1a3d717aa396d63272c6384d3768b105f2b489..81a1daf3c39f5ccf784306aaa626c7b176b21e4d 100644 (file)
@@ -43,7 +43,7 @@ _JSPropertyEnumeratorRetain
 _JSPropertyListAdd
 _JSStringBufferCreate
 _JSStringBufferCreateUTF8
-_JSStringBufferCreateWithCFString
+_JSStringBufferCreateCF
 _JSStringBufferGetCharacters
 _JSStringBufferGetCharactersPtr
 _JSStringBufferGetCharactersUTF8
index cea81eafd65242ab7a3927eafa4514f8e4ac7d14..cff13c0a4847ce472de8301883acb17f98f7314e 100644 (file)
@@ -201,7 +201,7 @@ JSObject* FunctionObjectImp::construct(ExecState* exec, const List& args, const
   if (!progNode)
     // we can't return a Completion(Throw) here, so just set the exception
     // and return it
-    return throwError(exec, SyntaxError, errMsg, errLine, sid, &sourceURL);
+    return throwError(exec, SyntaxError, errMsg, errLine, sid, sourceURL);
 
   ScopeChain scopeChain;
   scopeChain.push(exec->lexicalInterpreter()->globalObject());
index 7eafa9e058376824d2e14a86e21c35d5d8eeacff..3429a613c801af35448a439e39b667cf98d95ac2 100644 (file)
@@ -425,7 +425,7 @@ Completion Interpreter::checkSyntax(const UString& sourceURL, int startingLineNu
     UString errMsg;
     RefPtr<ProgramNode> progNode = Parser::parse(sourceURL, startingLineNumber, code, codeLength, 0, &errLine, &errMsg);
     if (!progNode)
-        return Completion(Throw, Error::create(&m_globalExec, SyntaxError, errMsg, errLine, 0, &sourceURL));
+        return Completion(Throw, Error::create(&m_globalExec, SyntaxError, errMsg, errLine, 0, sourceURL));
     return Completion(Normal);
 }
 
@@ -457,7 +457,7 @@ Completion Interpreter::evaluate(const UString& sourceURL, int startingLineNumbe
     
     // no program node means a syntax error occurred
     if (!progNode)
-        return Completion(Throw, Error::create(&m_globalExec, SyntaxError, errMsg, errLine, sid, &sourceURL));
+        return Completion(Throw, Error::create(&m_globalExec, SyntaxError, errMsg, errLine, sid, sourceURL));
     
     m_globalExec.clearException();
     
index 9e44d49bc904ae7b55f5855ba305cf4cc64f3b64..fba2acfedca3bcae903acb6eba4574cb00abf582 100644 (file)
@@ -195,19 +195,19 @@ static inline const UString& currentSourceURL(ExecState* exec)
 
 Completion Node::createErrorCompletion(ExecState* exec, ErrorType e, const char *msg)
 {
-    return Completion(Throw, Error::create(exec, e, msg, lineNo(), currentSourceId(exec), &currentSourceURL(exec)));
+    return Completion(Throw, Error::create(exec, e, msg, lineNo(), currentSourceId(exec), currentSourceURL(exec)));
 }
 
 Completion Node::createErrorCompletion(ExecState *exec, ErrorType e, const char *msg, const Identifier &ident)
 {
     UString message = msg;
     substitute(message, ident.ustring());
-    return Completion(Throw, Error::create(exec, e, message, lineNo(), currentSourceId(exec), &currentSourceURL(exec)));
+    return Completion(Throw, Error::create(exec, e, message, lineNo(), currentSourceId(exec), currentSourceURL(exec)));
 }
 
 JSValue *Node::throwError(ExecState* exec, ErrorType e, const char *msg)
 {
-    return KJS::throwError(exec, e, msg, lineNo(), currentSourceId(exec), &currentSourceURL(exec));
+    return KJS::throwError(exec, e, msg, lineNo(), currentSourceId(exec), currentSourceURL(exec));
 }
 
 JSValue *Node::throwError(ExecState *exec, ErrorType e, const char *msg, JSValue *v, Node *expr)
@@ -215,7 +215,7 @@ JSValue *Node::throwError(ExecState *exec, ErrorType e, const char *msg, JSValue
     UString message = msg;
     substitute(message, v->toString(exec));
     substitute(message, expr->toString());
-    return KJS::throwError(exec, e, message, lineNo(), currentSourceId(exec), &currentSourceURL(exec));
+    return KJS::throwError(exec, e, message, lineNo(), currentSourceId(exec), currentSourceURL(exec));
 }
 
 
@@ -223,7 +223,7 @@ JSValue *Node::throwError(ExecState *exec, ErrorType e, const char *msg, const I
 {
     UString message = msg;
     substitute(message, label.ustring());
-    return KJS::throwError(exec, e, message, lineNo(), currentSourceId(exec), &currentSourceURL(exec));
+    return KJS::throwError(exec, e, message, lineNo(), currentSourceId(exec), currentSourceURL(exec));
 }
 
 JSValue *Node::throwError(ExecState *exec, ErrorType e, const char *msg, JSValue *v, Node *e1, Node *e2)
@@ -232,7 +232,7 @@ JSValue *Node::throwError(ExecState *exec, ErrorType e, const char *msg, JSValue
     substitute(message, v->toString(exec));
     substitute(message, e1->toString());
     substitute(message, e2->toString());
-    return KJS::throwError(exec, e, message, lineNo(), currentSourceId(exec), &currentSourceURL(exec));
+    return KJS::throwError(exec, e, message, lineNo(), currentSourceId(exec), currentSourceURL(exec));
 }
 
 JSValue *Node::throwError(ExecState *exec, ErrorType e, const char *msg, JSValue *v, Node *expr, const Identifier &label)
@@ -241,7 +241,7 @@ JSValue *Node::throwError(ExecState *exec, ErrorType e, const char *msg, JSValue
     substitute(message, v->toString(exec));
     substitute(message, expr->toString());
     substitute(message, label.ustring());
-    return KJS::throwError(exec, e, message, lineNo(), currentSourceId(exec), &currentSourceURL(exec));
+    return KJS::throwError(exec, e, message, lineNo(), currentSourceId(exec), currentSourceURL(exec));
 }
 
 JSValue *Node::throwError(ExecState *exec, ErrorType e, const char *msg, JSValue *v, const Identifier &label)
@@ -249,7 +249,7 @@ JSValue *Node::throwError(ExecState *exec, ErrorType e, const char *msg, JSValue
     UString message = msg;
     substitute(message, v->toString(exec));
     substitute(message, label.ustring());
-    return KJS::throwError(exec, e, message, lineNo(), currentSourceId(exec), &currentSourceURL(exec));
+    return KJS::throwError(exec, e, message, lineNo(), currentSourceId(exec), currentSourceURL(exec));
 }
 
 JSValue *Node::throwUndefinedVariableError(ExecState *exec, const Identifier &ident)
index 0b6d90dd07050c192c13b0d4c15e2d6295927708..244300041f2adf419e2b2c73a97da6f95f9fa597 100644 (file)
@@ -562,7 +562,7 @@ const char * const errorNamesArr[] = {
 const char * const * const Error::errorNames = errorNamesArr;
 
 JSObject *Error::create(ExecState *exec, ErrorType errtype, const UString &message,
-                         int lineno, int sourceId, const UString *sourceURL)
+                         int lineno, int sourceId, const UString &sourceURL)
 {
   JSObject *cons;
   switch (errtype) {
@@ -601,8 +601,8 @@ JSObject *Error::create(ExecState *exec, ErrorType errtype, const UString &messa
   if (sourceId != -1)
     err->put(exec, "sourceId", jsNumber(sourceId));
 
-  if(sourceURL)
-   err->put(exec,"sourceURL", jsString(*sourceURL));
+  if(!sourceURL.isNull())
+    err->put(exec, "sourceURL", jsString(sourceURL));
  
   return err;
 
@@ -645,7 +645,7 @@ JSObject *throwError(ExecState *exec, ErrorType type, const char *message)
     return error;
 }
 
-JSObject *throwError(ExecState *exec, ErrorType type, const UString &message, int line, int sourceId, const UString *sourceURL)
+JSObject *throwError(ExecState *exec, ErrorType type, const UString &message, int line, int sourceId, const UString &sourceURL)
 {
     JSObject *error = Error::create(exec, type, message, line, sourceId, sourceURL);
     exec->setException(error);
index d0c28452e27a81cfbbad998787d0bf3ae9b8eb89..4dcf56a583abe5913694bbe339373bc416c9bc38 100644 (file)
@@ -553,7 +553,7 @@ namespace KJS {
      * @param sourceId Optional source id.
      * @param sourceURL Optional source URL.
      */
-    static JSObject *create(ExecState *, ErrorType, const UString &message, int lineNumber, int sourceId, const UString *sourceURL);
+    static JSObject *create(ExecState *, ErrorType, const UString &message, int lineNumber, int sourceId, const UString &sourceURL);
     static JSObject *create(ExecState *, ErrorType, const char *message);
 
     /**
@@ -562,7 +562,7 @@ namespace KJS {
     static const char * const * const errorNames;
   };
 
-JSObject *throwError(ExecState *, ErrorType, const UString &message, int lineNumber, int sourceId, const UString *sourceURL);
+JSObject *throwError(ExecState *, ErrorType, const UString &message, int lineNumber, int sourceId, const UString &sourceURL);
 JSObject *throwError(ExecState *, ErrorType, const UString &message);
 JSObject *throwError(ExecState *, ErrorType, const char *message);
 JSObject *throwError(ExecState *, ErrorType);