Ignore:
Timestamp:
Jul 15, 2006, 6:28:25 PM (19 years ago)
Author:
ggaren
Message:

Reviewed by Maciej.

  • Moved the arguments passed to JSClassCreate into a single structure, called JSClassDefinition. This will enable easier structure migration/versioning in the future, if necessary.


  • Added support for class names.


  • kJSClassDefinitionNull replaces kJSObjectCallbacksNone.


  • JSClass is becoming a fairly complex struct, so I migrated all of its implementation other than reference counting to the sruct.


  • Also moved JSClass* functions in the API to JSObjectRef.cpp, since they're declared in JSObjectRef.h


  • Also added some more informative explanation to the class structure doc.
File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/JavaScriptCore/API/JSObjectRef.h

    r15444 r15462  
    8484/*!
    8585@typedef JSObjectHasPropertyCallback
    86 @abstract The callback invoked when determining whether an object has a given property.
     86@abstract The callback invoked when determining whether an object has a property.
    8787@param context The current execution context.
    8888@param object The JSObject to search for the property.
    … …  
    9393bool HasProperty(JSContextRef context, JSObjectRef object, JSStringRef propertyName);
    9494
    95 If this function returns false, the hasProperty request forwards to object's static property table, then its parent class chain (which includes the default object class), then its prototype chain.
     95If this function returns false, the hasProperty request forwards to object's statically declared properties, then its parent class chain (which includes the default object class), then its prototype chain.
    9696
    9797This 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.
    … …  
    104104/*!
    105105@typedef JSObjectGetPropertyCallback
    106 @abstract The callback invoked when getting a property from an object.
     106@abstract The callback invoked when getting a property's value.
    107107@param context The current execution context.
    108108@param object The JSObject to search for the property.
    … …  
    114114JSValueRef GetProperty(JSContextRef context, JSObjectRef object, JSStringRef propertyName, JSValueRef* exception);
    115115
    116 If this function returns NULL, 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.
     116If this function returns NULL, the get request forwards to object's statically declared properties, then its parent class chain (which includes the default object class), then its prototype chain.
    117117*/
    118118typedef JSValueRef
    … …  
    121121/*!
    122122@typedef JSObjectSetPropertyCallback
    123 @abstract The callback invoked when setting the value of a given property.
     123@abstract The callback invoked when setting a property's value.
    124124@param context The current execution context.
    125125@param object The JSObject on which to set the property's value.
    … …  
    132132bool SetProperty(JSContextRef context, JSObjectRef object, JSStringRef propertyName, JSValueRef value, JSValueRef* exception);
    133133
    134 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).
     134If this function returns false, the set request forwards to object's statically declared properties, then its parent class chain (which includes the default object class).
    135135*/
    136136typedef bool
    … …  
    139139/*!
    140140@typedef JSObjectDeletePropertyCallback
    141 @abstract The callback invoked when deleting a given property.
     141@abstract The callback invoked when deleting a property.
    142142@param context The current execution context.
    143143@param object The JSObject in which to delete the property.
    … …  
    149149bool DeleteProperty(JSContextRef context, JSObjectRef object, JSStringRef propertyName, JSValueRef* exception);
    150150
    151 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).
     151If this function returns false, the delete request forwards to object's statically declared properties, then its parent class chain (which includes the default object class).
    152152*/
    153153typedef bool
    … …  
    252252(*JSObjectConvertToTypeCallback) (JSContextRef context, JSObjectRef object, JSType type, JSValueRef* exception);
    253253
    254 /*!
    255 @struct JSObjectCallbacks
    256 @abstract This structure contains optional callbacks for supplementing default object behavior. Any callback field can be NULL.
     254/*!
     255@struct JSStaticValue
     256@abstract This structure describes a statically declared value property.
     257@field name A null-terminated UTF8 string containing the property's name.
     258@field getProperty A JSObjectGetPropertyCallback to invoke when getting the property's value.
     259@field setProperty A JSObjectSetPropertyCallback to invoke when setting the property's value.
     260@field attributes A logically ORed set of JSPropertyAttributes to give to the property.
     261*/
     262typedef struct {
     263    const char* const name; // FIXME: convert UTF8
     264    JSObjectGetPropertyCallback getProperty;
     265    JSObjectSetPropertyCallback setProperty;
     266    JSPropertyAttributes attributes;
     267} JSStaticValue;
     268
     269/*!
     270@struct JSStaticFunction
     271@abstract This structure describes a statically declared function property.
     272@field name A null-terminated UTF8 string containing the property's name.
     273@field callAsFunction A JSObjectCallAsFunctionCallback to invoke when the property is called as a function.
     274@field attributes A logically ORed set of JSPropertyAttributes to give to the property.
     275*/
     276typedef struct {
     277    const char* const name; // FIXME: convert UTF8
     278    JSObjectCallAsFunctionCallback callAsFunction;
     279    JSPropertyAttributes attributes;
     280} JSStaticFunction;
     281
     282/*!
     283@struct JSClassDefinition
     284@abstract This structure contains properties and callbacks that define a type of object. All fields are optional. Any field may be NULL.
    257285@field version The version number of this structure. The current version is 0.
    258 @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.
    259 @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.
    260 @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.
    261 @field getProperty The callback invoked when getting the value of a given property.
    262 @field setProperty The callback invoked when setting the value of a given property.
    263 @field deleteProperty The callback invoked when deleting a given property.
     286@field className A null-terminated UTF8 string containing the class's name.
     287@field parentClass A JSClass to set as the class's parent class. Pass NULL use the default object class.
     288@field staticValues A JSStaticValue array containing the class's statically declared value properties. Pass NULL to specify no statically declared value properties. The array must be terminated by a JSStaticValue whose name field is NULL.
     289@field staticFunctions A JSStaticFunction array containing the class's statically declared function properties. Pass NULL to specify no statically declared function properties. The array must be terminated by a JSStaticFunction whose name field is NULL.
     290@field initialize The callback invoked when an object is first created. Use this callback to initialize the object.
     291@field finalize The callback invoked when an object is finalized (prepared for garbage collection). Use this callback to release resources allocated for the object, and perform other cleanup.
     292@field hasProperty The callback invoked when determining whether an object has a property. If this field is NULL, getProperty is 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 is expensive.
     293@field getProperty The callback invoked when getting a property's value.
     294@field setProperty The callback invoked when setting a property's value.
     295@field deleteProperty The callback invoked when deleting a property.
    264296@field addPropertiesToList The callback invoked when adding an object's properties to a property list.
    265297@field callAsFunction The callback invoked when an object is called as a function.
    … …  
    267299@field callAsConstructor The callback invoked when an object is used as a constructor in a 'new' expression.
    268300@field convertToType The callback invoked when converting an object to a particular JavaScript type.
     301@discussion The staticValues and staticFunctions arrays are the simplest and most efficient means for vending custom properties. Statically declared properties autmatically service requests like get, set, and enumerate. Property access callbacks are required only to implement unusual properties, like array indexes, whose names are not known at compile-time.
     302
     303If you named your getter function "GetX" and your setter function "SetX", you would declare a JSStaticValue array containing "X" like this:
     304
     305JSStaticValue StaticValueArray[] = {
     306    { "X", GetX, SetX, kJSPropertyAttributeNone },
     307    { 0, 0, 0, 0 }
     308};
     309
     310Standard JavaScript practice calls for storing functions in prototype objects, so derived objects can share them. Therefore, it is common for prototype classes to have function properties but no value properties, and for object classes to have value properties but no function properties.
     311
     312A NULL callback specifies that the default object callback should substitute, except in the case of hasProperty, where it specifies that getProperty should substitute.
    269313*/
    270314typedef struct {
    271315    int                                 version; // current (and only) version is 0
     316
     317    const char*                         className;
     318    JSClassRef                          parentClass;
     319       
     320    JSStaticValue*                      staticValues;
     321    JSStaticFunction*                   staticFunctions;
     322   
    272323    JSObjectInitializeCallback          initialize;
    273324    JSObjectFinalizeCallback            finalize;
    … …  
    281332    JSObjectHasInstanceCallback         hasInstance;
    282333    JSObjectConvertToTypeCallback       convertToType;
    283 } JSObjectCallbacks;
    284 
    285 /*!
    286 @const kJSObjectCallbacksNone
    287 @abstract A JSObjectCallbacks structure of the current version, filled with NULL callbacks.
    288 @discussion Use this constant as a convenience when creating callback structures. For example, to create a callback structure that has only a finalize method:
    289 
    290 JSObjectCallbacks callbacks = kJSObjectCallbacksNone;
    291 
    292 callbacks.finalize = Finalize;
    293 */
    294 extern const JSObjectCallbacks kJSObjectCallbacksNone;
    295 
    296 /*!
    297 @struct JSStaticValue
    298 @abstract This structure describes a static value property.
    299 @field name A null-terminated UTF8 string containing the property's name.
    300 @field getProperty A JSObjectGetPropertyCallback to invoke when getting the property's value.
    301 @field setProperty A JSObjectSetPropertyCallback to invoke when setting the property's value.
    302 @field attributes A logically ORed set of JSPropertyAttributes to give to the property.
    303 */
    304 typedef struct {
    305     const char* const name; // FIXME: convert UTF8
    306     JSObjectGetPropertyCallback getProperty;
    307     JSObjectSetPropertyCallback setProperty;
    308     JSPropertyAttributes attributes;
    309 } JSStaticValue;
    310 
    311 /*!
    312 @struct JSStaticFunction
    313 @abstract This structure describes a static function property.
    314 @field name A null-terminated UTF8 string containing the property's name.
    315 @field callAsFunction A JSObjectCallAsFunctionCallback to invoke when the property is called as a function.
    316 @field attributes A logically ORed set of JSPropertyAttributes to give to the property.
    317 */
    318 typedef struct {
    319     const char* const name; // FIXME: convert UTF8
    320     JSObjectCallAsFunctionCallback callAsFunction;
    321     JSPropertyAttributes attributes;
    322 } JSStaticFunction;
    323 
    324 /*!
    325 @function
    326 @abstract Creates a JavaScript class suitable for use with JSObjectMake
    327 @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.
    328 @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.
    329 @param callbacks A pointer to a JSObjectCallbacks structure holding custom callbacks for supplementing default object behavior. Pass NULL to specify no custom behavior.
    330 @param parentClass A JSClass to set as the class's parent class. Pass NULL use the default object class.
    331 @result A JSClass with the given properties, callbacks, and parent class. Ownership follows the Create Rule.
    332 @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.
    333 */
    334 JSClassRef JSClassCreate(JSStaticValue* staticValues, JSStaticFunction* staticFunctions, const JSObjectCallbacks* callbacks, JSClassRef parentClass);
     334} JSClassDefinition;
     335
     336/*!
     337@const kJSClassDefinitionNull
     338@abstract A JSClassDefinition structure of the current version, filled with NULL pointers.
     339@discussion Use this constant as a convenience when creating class definitions. For example, to create a class definition with only a finalize method:
     340
     341JSClassDefinition definition = kJSClassDefinitionNull;
     342
     343definition.finalize = Finalize;
     344*/
     345extern const JSClassDefinition kJSClassDefinitionNull;
     346
     347/*!
     348@function
     349@abstract Creates a JavaScript class suitable for use with JSObjectMake.
     350@param definition A JSClassDefinition that defines the class.
     351@result A JSClass with the given definition's name, properties, callbacks, and parent class. Ownership follows the Create Rule.
     352*/
     353JSClassRef JSClassCreate(JSClassDefinition* definition);
     354
    335355/*!
    336356@function
    … …  
    404424/*!
    405425@function
    406 @abstract Tests whether an object has a certain property.
     426@abstract Tests whether an object has a given property.
    407427@param object The JSObject to test.
    408428@param propertyName A JSString containing the property's name.
    … …  
    473493@param object A JSObject whose private data you want to get.
    474494@result A void* that points to the object's private data, if the object has private data, otherwise NULL.
    475 @discussion JSObjectGetPrivate and JSObjectSetPrivate only work on custom objects created by JSObjectMake, JSObjectMakeFunction, and JSObjectMakeConstructor.
     495@discussion JSObjectGetPrivate and JSObjectSetPrivate only work on objects created by JSObjectMake, JSObjectMakeFunction, and JSObjectMakeConstructor.
    476496*/
    477497void* JSObjectGetPrivate(JSObjectRef object);
    … …  
    483503@param data A void* that points to the object's private data.
    484504@result true if the set operation succeeds, otherwise false.
    485 @discussion JSObjectGetPrivate and JSObjectSetPrivate only work on custom objects created by JSObjectMake, JSObjectMakeFunction, and JSObjectMakeConstructor.
     505@discussion JSObjectGetPrivate and JSObjectSetPrivate only work on objects created by JSObjectMake, JSObjectMakeFunction, and JSObjectMakeConstructor.
    486506*/
    487507bool JSObjectSetPrivate(JSObjectRef object, void* data);
    … …  
    556576@function
    557577@abstract Adds a property to a property list.
    558 @discussion Use this method inside a JSObjectAddPropertiesToListCallback to add a custom property to an object's property list.
     578@discussion Use this method inside a JSObjectAddPropertiesToListCallback to add a property to an object's property list.
    559579@param propertyList The JSPropertyList to which you want to add a property.
    560580@param thisObject The JSObject to which the property belongs.
Note: See TracChangeset for help on using the changeset viewer.