API/JSExport.h

   1 /*
   2  * Copyright (C) 2013 Apple Inc. All rights reserved.
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions
   6  * are met:
   7  * 1. Redistributions of source code must retain the above copyright
   8  *    notice, this list of conditions and the following disclaimer.
   9  * 2. Redistributions in binary form must reproduce the above copyright
  10  *    notice, this list of conditions and the following disclaimer in the
  11  *    documentation and/or other materials provided with the distribution.
  12  *
  13  * THIS SOFTWARE IS PROVIDED BY APPLE INC. ``AS IS'' AND ANY
  14  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  16  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE INC. OR
  17  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  18  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  19  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  20  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
  21  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  22  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  23  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  24  */
  25
  26 #import <JavaScriptCore/JavaScriptCore.h>
  27
  28 #if JSC_OBJC_API_ENABLED
  29
  30 // When a JavaScript value is created from an instance of an Objective-C class
  31 // for which no copying conversion is specified a JavaScript wrapper object will
  32 // be created.
  33 //
  34 // In JavaScript inheritance is supported via a chain of prototype objects, and
  35 // for each Objective-C class (and per JSContext) an object appropriate for use
  36 // as a prototype will be provided. For the class NSObject the prototype object
  37 // will be the JavaScript context's Object Prototype. For all other Objective-C
  38 // classes a Prototype object will be created. The Prototype object for a given
  39 // Objective-C class will have its internal [Prototype] property set to point to
  40 // the Prototype object of the Objective-C class's superclass. As such the
  41 // prototype chain for a JavaScript wrapper object will reflect the wrapped
  42 // Objective-C type's inheritance hierarchy.
  43 //
  44 // In addition to the Prototype object a JavaScript Constructor object will also
  45 // be produced for each Objective-C class. The Constructor object has a property
  46 // named 'prototype' that references the Prototype object, and the Prototype
  47 // object has a property named 'constructor' that references the Constructor.
  48 // The Constructor object is not callable.
  49 //
  50 // By default no methods or properties of the Objective-C class will be exposed
  51 // to JavaScript, however methods and properties may explicitly be exported.
  52 // For each protocol that a class conforms to, if the protocol incorporates the
  53 // protocol JSExport, then the protocol will be interpreted as a list of methods
  54 // and properties to be exported to JavaScript.
  55 //
  56 // For each instance method being exported, a corresponding JavaScript function
  57 // will be assigned as a property of the Prototype object, for each Objective-C
  58 // property being exported a JavaScript accessor property will be created on the
  59 // Prototype, and for each class method exported a JavaScript function will be
  60 // created on the Constructor object. For example:
  61 //
  62 //    @protocol MyClassJavaScriptMethods <JSExport>
  63 //    - (void)foo;
  64 //    @end
  65 //
  66 //    @interface MyClass : NSObject <MyClassJavaScriptMethods>
  67 //    - (void)foo;
  68 //    - (void)bar;
  69 //    @end
  70 //
  71 // Data properties that are created on the prototype or constructor objects have
  72 // the attributes: writable:true, enumerable:false, configurable:true. Accessor
  73 // properties have the attributes: enumerable:false and configurable:true.
  74 //
  75 // If an instance of MyClass is converted to a JavaScript value, the resulting
  76 // wrapper object will (via its prototype) export the method "foo" to JavaScript,
  77 // since the class conforms to the MyClassJavaScriptMethods protocol, and this
  78 // protocol incorporates JSExport. "bar" will not be exported.
  79 //
  80 // Properties, arguments, and return values of the following types are
  81 // supported:
  82 //
  83 // Primitive numbers: signed values of up to 32-bits are converted in a manner
  84 //    consistent with valueWithInt32/toInt32, unsigned values of up to 32-bits
  85 //    are converted in a manner consistent with valueWithUInt32/toUInt32, all
  86 //    other numeric values are converted consistently with valueWithDouble/
  87 //    toDouble.
  88 // BOOL: values are converted consistently with valueWithBool/toBool.
  89 // id: values are converted consistently with valueWithObject/toObject.
  90 // <Objective-C Class>: - where the type is a pointer to a specified Objective-C
  91 //    class, conversion is consistent with valueWithObjectOfClass/toObject.
  92 // struct types: C struct types are supported, where JSValue provides support
  93 //    for the given type. Support is built in for CGPoint, NSRange, CGRect, and
  94 //    CGSize.
  95 // block types: In addition to support provided by valueWithObject/toObject for
  96 //    block types, if a JavaScript Function is passed as an argument, where the
  97 //    type required is a block with a void return value (and where the block's
  98 //    arguments are all of supported types), then a special adaptor block
  99 //    will be created, allowing the JavaScript function to be used in the place
 100 //    of a block.
 101 //
 102 // For any interface that conforms to JSExport the normal copying conversion for
 103 // built in types will be inhibited - so, for example, if an instance that
 104 // derives from NSString but conforms to JSExport is passed to valueWithObject:
 105 // then a wrapper object for the Objective-C object will be returned rather than
 106 // a JavaScript string primitive.
 107 @protocol JSExport
 108 @end
 109
 110 // When a selector that takes one or more arguments is converted to a JavaScript
 111 // property name, by default a property name will be generated by performing the
 112 // following conversion:
 113 //  - All colons are removed from the selector
 114 //  - Any lowercase letter that had followed a colon will be capitalized.
 115 // Under the default conversion a selector "doFoo:withBar:" will be exported as
 116 // "doFooWithBar". The default conversion may be overriden using the JSExportAs
 117 // macro, for example to export a method "doFoo:withBar:" as "doFoo":
 118 //
 119 //    @protocol MyClassJavaScriptMethods <JSExport>
 120 //    JSExportAs(doFoo,
 121 //    - (void)doFoo:(id)foo withBar:(id)bar
 122 //    );
 123 //    @end
 124 //
 125 // Note that the JSExport macro may only be applied to a selector that takes one
 126 // or more argument.
 127 #define JSExportAs(PropertyName, Selector) \
 128     @optional Selector __JS_EXPORT_AS__##PropertyName:(id)argument; @required Selector
 129
 130 #endif