X-Git-Url: https://git.saurik.com/apple/javascriptcore.git/blobdiff_plain/a253471d7f8e4d91bf6ebabab00155c3b387d3d0..93a3786624b2768d89bfa27e46598dc64e2fb70a:/API/JSExport.h diff --git a/API/JSExport.h b/API/JSExport.h new file mode 100644 index 0000000..96e9fec --- /dev/null +++ b/API/JSExport.h @@ -0,0 +1,130 @@ +/* + * Copyright (C) 2013 Apple Inc. All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY APPLE INC. ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR + * 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. + */ + +#import + +#if JSC_OBJC_API_ENABLED + +// When a JavaScript value is created from an instance of an Objective-C class +// for which no copying conversion is specified a JavaScript wrapper object will +// be created. +// +// In JavaScript inheritance is supported via a chain of prototype objects, and +// for each Objective-C class (and per JSContext) an object appropriate for use +// as a prototype will be provided. For the class NSObject the prototype object +// will be the JavaScript context's Object Prototype. For all other Objective-C +// classes a Prototype object will be created. The Prototype object for a given +// Objective-C class will have its internal [Prototype] property set to point to +// the Prototype object of the Objective-C class's superclass. As such the +// prototype chain for a JavaScript wrapper object will reflect the wrapped +// Objective-C type's inheritance hierarchy. +// +// In addition to the Prototype object a JavaScript Constructor object will also +// be produced for each Objective-C class. The Constructor object has a property +// named 'prototype' that references the Prototype object, and the Prototype +// object has a property named 'constructor' that references the Constructor. +// The Constructor object is not callable. +// +// By default no methods or properties of the Objective-C class will be exposed +// to JavaScript, however methods and properties may explicitly be exported. +// For each protocol that a class conforms to, if the protocol incorporates the +// protocol JSExport, then the protocol will be interpreted as a list of methods +// and properties to be exported to JavaScript. +// +// For each instance method being exported, a corresponding JavaScript function +// will be assigned as a property of the Prototype object, for each Objective-C +// property being exported a JavaScript accessor property will be created on the +// Prototype, and for each class method exported a JavaScript function will be +// created on the Constructor object. For example: +// +// @protocol MyClassJavaScriptMethods +// - (void)foo; +// @end +// +// @interface MyClass : NSObject +// - (void)foo; +// - (void)bar; +// @end +// +// Data properties that are created on the prototype or constructor objects have +// the attributes: writable:true, enumerable:false, configurable:true. Accessor +// properties have the attributes: enumerable:false and configurable:true. +// +// If an instance of MyClass is converted to a JavaScript value, the resulting +// wrapper object will (via its prototype) export the method "foo" to JavaScript, +// since the class conforms to the MyClassJavaScriptMethods protocol, and this +// protocol incorporates JSExport. "bar" will not be exported. +// +// Properties, arguments, and return values of the following types are +// supported: +// +// Primitive numbers: signed values of up to 32-bits are converted in a manner +// consistent with valueWithInt32/toInt32, unsigned values of up to 32-bits +// are converted in a manner consistent with valueWithUInt32/toUInt32, all +// other numeric values are converted consistently with valueWithDouble/ +// toDouble. +// BOOL: values are converted consistently with valueWithBool/toBool. +// id: values are converted consistently with valueWithObject/toObject. +// : - where the type is a pointer to a specified Objective-C +// class, conversion is consistent with valueWithObjectOfClass/toObject. +// struct types: C struct types are supported, where JSValue provides support +// for the given type. Support is built in for CGPoint, NSRange, CGRect, and +// CGSize. +// block types: In addition to support provided by valueWithObject/toObject for +// block types, if a JavaScript Function is passed as an argument, where the +// type required is a block with a void return value (and where the block's +// arguments are all of supported types), then a special adaptor block +// will be created, allowing the JavaScript function to be used in the place +// of a block. +// +// For any interface that conforms to JSExport the normal copying conversion for +// built in types will be inhibited - so, for example, if an instance that +// derives from NSString but conforms to JSExport is passed to valueWithObject: +// then a wrapper object for the Objective-C object will be returned rather than +// a JavaScript string primitive. +@protocol JSExport +@end + +// When a selector that takes one or more arguments is converted to a JavaScript +// property name, by default a property name will be generated by performing the +// following conversion: +// - All colons are removed from the selector +// - Any lowercase letter that had followed a colon will be capitalized. +// Under the default conversion a selector "doFoo:withBar:" will be exported as +// "doFooWithBar". The default conversion may be overriden using the JSExportAs +// macro, for example to export a method "doFoo:withBar:" as "doFoo": +// +// @protocol MyClassJavaScriptMethods +// JSExportAs(doFoo, +// - (void)doFoo:(id)foo withBar:(id)bar +// ); +// @end +// +// Note that the JSExport macro may only be applied to a selector that takes one +// or more argument. +#define JSExportAs(PropertyName, Selector) \ + @optional Selector __JS_EXPORT_AS__##PropertyName:(id)argument; @required Selector + +#endif