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 /*!
  31 @protocol
  32 @abstract JSExport provides a declarative way to export Objective-C instance methods,
  33  class methods, and properties to JavaScript code.
  34
  35 @discussion When a JavaScript value is created from an instance of an Objective-C class
  36  for which no copying conversion is specified a JavaScript wrapper object will
  37  be created.
  38
  39  In JavaScript, inheritance is supported via a chain of prototype objects, and
  40  for each Objective-C class (and per JSContext) an object appropriate for use
  41  as a prototype will be provided. For the class NSObject the prototype object
  42  will be the JavaScript context's Object Prototype. For all other Objective-C
  43  classes a Prototype object will be created. The Prototype object for a given
  44  Objective-C class will have its internal [Prototype] property set to point to
  45  the Prototype object of the Objective-C class's superclass. As such the
  46  prototype chain for a JavaScript wrapper object will reflect the wrapped
  47  Objective-C type's inheritance hierarchy.
  48
  49  In addition to the Prototype object a JavaScript Constructor object will also
  50  be produced for each Objective-C class. The Constructor object has a property
  51  named 'prototype' that references the Prototype object, and the Prototype
  52  object has a property named 'constructor' that references the Constructor.
  53  The Constructor object is not callable.
  54
  55  By default no methods or properties of the Objective-C class will be exposed
  56  to JavaScript; however methods and properties may explicitly be exported.
  57  For each protocol that a class conforms to, if the protocol incorporates the
  58  protocol JSExport, then the protocol will be interpreted as a list of methods
  59  and properties to be exported to JavaScript.
  60
  61  For each instance method being exported a corresponding JavaScript function
  62  will be assigned as a property of the Prototype object. For each Objective-C
  63  property being exported a JavaScript accessor property will be created on the
  64  Prototype. For each class method exported a JavaScript function will be
  65  created on the Constructor object. For example:
  66
  67 <pre>
  68 @textblock
  69     @protocol MyClassJavaScriptMethods <JSExport>
  70     - (void)foo;
  71     @end
  72
  73     @interface MyClass : NSObject <MyClassJavaScriptMethods>
  74     - (void)foo;
  75     - (void)bar;
  76     @end
  77 @/textblock
  78 </pre>
  79
  80  Data properties that are created on the prototype or constructor objects have
  81  the attributes: <code>writable:true</code>, <code>enumerable:false</code>, <code>configurable:true</code>.
  82  Accessor properties have the attributes: <code>enumerable:false</code> and <code>configurable:true</code>.
  83
  84  If an instance of <code>MyClass</code> is converted to a JavaScript value, the resulting
  85  wrapper object will (via its prototype) export the method <code>foo</code> to JavaScript,
  86  since the class conforms to the <code>MyClassJavaScriptMethods</code> protocol, and this
  87  protocol incorporates <code>JSExport</code>. <code>bar</code> will not be exported.
  88
  89  Properties, arguments, and return values of the following types are
  90  supported:
  91
  92  Primitive numbers: signed values of up to 32-bits are converted in a manner
  93     consistent with valueWithInt32/toInt32, unsigned values of up to 32-bits
  94     are converted in a manner consistent with valueWithUInt32/toUInt32, all
  95     other numeric values are converted consistently with valueWithDouble/
  96     toDouble.
  97
  98  BOOL: values are converted consistently with valueWithBool/toBool.
  99
 100  id: values are converted consistently with valueWithObject/toObject.
 101
 102  Objective-C Class: - where the type is a pointer to a specified Objective-C
 103     class, conversion is consistent with valueWithObjectOfClass/toObject.
 104
 105  struct types: C struct types are supported, where JSValue provides support
 106     for the given type. Support is built in for CGPoint, NSRange, CGRect, and
 107     CGSize.
 108
 109  block types: Blocks can only be passed if they had been converted
 110     successfully by valueWithObject/toObject previously.
 111
 112  For any interface that conforms to JSExport the normal copying conversion for
 113  built in types will be inhibited - so, for example, if an instance that
 114  derives from NSString but conforms to JSExport is passed to valueWithObject:
 115  then a wrapper object for the Objective-C object will be returned rather than
 116  a JavaScript string primitive.
 117 */
 118 @protocol JSExport
 119 @end
 120
 121 /*!
 122 @define
 123 @abstract Rename a selector when it's exported to JavaScript.
 124 @discussion When a selector that takes one or more arguments is converted to a JavaScript
 125  property name, by default a property name will be generated by performing the
 126  following conversion:
 127
 128   - All colons are removed from the selector
 129
 130   - Any lowercase letter that had followed a colon will be capitalized.
 131
 132  Under the default conversion a selector <code>doFoo:withBar:</code> will be exported as
 133  <code>doFooWithBar</code>. The default conversion may be overriden using the JSExportAs
 134  macro, for example to export a method <code>doFoo:withBar:</code> as <code>doFoo</code>:
 135
 136 <pre>
 137 @textblock
 138     @protocol MyClassJavaScriptMethods <JSExport>
 139     JSExportAs(doFoo,
 140     - (void)doFoo:(id)foo withBar:(id)bar
 141     );
 142     @end
 143 @/textblock
 144 </pre>
 145
 146  Note that the JSExport macro may only be applied to a selector that takes one
 147  or more argument.
 148 */
 149 #define JSExportAs(PropertyName, Selector) \
 150     @optional Selector __JS_EXPORT_AS__##PropertyName:(id)argument; @required Selector
 151
 152 #endif