src/third_party/WebKit/Source/bindings/scripts/v8_methods.py

   1 # Copyright (C) 2013 Google Inc. All rights reserved.
   2 #
   3 # Redistribution and use in source and binary forms, with or without
   4 # modification, are permitted provided that the following conditions are
   5 # met:
   6 #
   7 #     * Redistributions of source code must retain the above copyright
   8 # notice, this list of conditions and the following disclaimer.
   9 #     * Redistributions in binary form must reproduce the above
  10 # copyright notice, this list of conditions and the following disclaimer
  11 # in the documentation and/or other materials provided with the
  12 # distribution.
  13 #     * Neither the name of Google Inc. nor the names of its
  14 # contributors may be used to endorse or promote products derived from
  15 # this software without specific prior written permission.
  16 #
  17 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  18 # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  19 # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  20 # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  21 # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  22 # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  23 # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  24 # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  25 # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  26 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  27 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28
  29 """Generate template values for methods.
  30
  31 Extends IdlType and IdlUnionType with property |union_arguments|.
  32
  33 Design doc: http://www.chromium.org/developers/design-documents/idl-compiler
  34 """
  35
  36 from idl_types import IdlType, IdlUnionType, inherits_interface
  37 from v8_globals import includes
  38 import v8_types
  39 import v8_utilities
  40 from v8_utilities import has_extended_attribute_value
  41
  42
  43 def generate_method(interface, method):
  44     arguments = method.arguments
  45     extended_attributes = method.extended_attributes
  46     idl_type = method.idl_type
  47     is_static = method.is_static
  48     name = method.name
  49
  50     idl_type.add_includes_for_type()
  51     this_cpp_value = cpp_value(interface, method, len(arguments))
  52
  53     def function_template():
  54         if is_static:
  55             return 'functionTemplate'
  56         if 'Unforgeable' in extended_attributes:
  57             return 'instanceTemplate'
  58         return 'prototypeTemplate'
  59
  60     is_call_with_script_arguments = has_extended_attribute_value(method, 'CallWith', 'ScriptArguments')
  61     if is_call_with_script_arguments:
  62         includes.update(['bindings/v8/ScriptCallStackFactory.h',
  63                          'core/inspector/ScriptArguments.h'])
  64     is_call_with_script_state = has_extended_attribute_value(method, 'CallWith', 'ScriptState')
  65     if is_call_with_script_state:
  66         includes.add('bindings/v8/ScriptState.h')
  67     is_check_security_for_node = 'CheckSecurity' in extended_attributes
  68     if is_check_security_for_node:
  69         includes.add('bindings/v8/BindingSecurity.h')
  70     is_custom_element_callbacks = 'CustomElementCallbacks' in extended_attributes
  71     if is_custom_element_callbacks:
  72         includes.add('core/dom/custom/CustomElementCallbackDispatcher.h')
  73
  74     has_event_listener_argument = any(
  75         argument for argument in arguments
  76         if argument.idl_type.name == 'EventListener')
  77     is_check_security_for_frame = (
  78         'CheckSecurity' in interface.extended_attributes and
  79         'DoNotCheckSecurity' not in extended_attributes)
  80     is_raises_exception = 'RaisesException' in extended_attributes
  81
  82     return {
  83         'activity_logging_world_list': v8_utilities.activity_logging_world_list(method),  # [ActivityLogging]
  84         'arguments': [generate_argument(interface, method, argument, index)
  85                       for index, argument in enumerate(arguments)],
  86         'conditional_string': v8_utilities.conditional_string(method),
  87         'cpp_type': idl_type.cpp_type,
  88         'cpp_value': this_cpp_value,
  89         'deprecate_as': v8_utilities.deprecate_as(method),  # [DeprecateAs]
  90         'do_not_check_signature': not(is_static or
  91             v8_utilities.has_extended_attribute(method,
  92                 ['DoNotCheckSecurity', 'DoNotCheckSignature', 'NotEnumerable',
  93                  'ReadOnly', 'RuntimeEnabled', 'Unforgeable'])),
  94         'function_template': function_template(),
  95         'idl_type': idl_type.base_type,
  96         'has_event_listener_argument': has_event_listener_argument,
  97         'has_exception_state':
  98             has_event_listener_argument or
  99             is_raises_exception or
 100             is_check_security_for_frame or
 101             any(argument for argument in arguments
 102                 if argument.idl_type.name == 'SerializedScriptValue' or
 103                    argument.idl_type.is_integer_type),
 104         'is_call_with_execution_context': has_extended_attribute_value(method, 'CallWith', 'ExecutionContext'),
 105         'is_call_with_script_arguments': is_call_with_script_arguments,
 106         'is_call_with_script_state': is_call_with_script_state,
 107         'is_check_security_for_frame': is_check_security_for_frame,
 108         'is_check_security_for_node': is_check_security_for_node,
 109         'is_custom': 'Custom' in extended_attributes,
 110         'is_custom_element_callbacks': is_custom_element_callbacks,
 111         'is_do_not_check_security': 'DoNotCheckSecurity' in extended_attributes,
 112         'is_do_not_check_signature': 'DoNotCheckSignature' in extended_attributes,
 113         'is_partial_interface_member':
 114             'PartialInterfaceImplementedAs' in extended_attributes,
 115         'is_per_world_bindings': 'PerWorldBindings' in extended_attributes,
 116         'is_raises_exception': is_raises_exception,
 117         'is_read_only': 'ReadOnly' in extended_attributes,
 118         'is_static': is_static,
 119         'is_variadic': arguments and arguments[-1].is_variadic,
 120         'measure_as': v8_utilities.measure_as(method),  # [MeasureAs]
 121         'name': name,
 122         'number_of_arguments': len(arguments),
 123         'number_of_required_arguments': len([
 124             argument for argument in arguments
 125             if not (argument.is_optional or argument.is_variadic)]),
 126         'number_of_required_or_variadic_arguments': len([
 127             argument for argument in arguments
 128             if not argument.is_optional]),
 129         'per_context_enabled_function': v8_utilities.per_context_enabled_function_name(method),  # [PerContextEnabled]
 130         'property_attributes': property_attributes(method),
 131         'runtime_enabled_function': v8_utilities.runtime_enabled_function_name(method),  # [RuntimeEnabled]
 132         'signature': 'v8::Local<v8::Signature>()' if is_static or 'DoNotCheckSignature' in extended_attributes else 'defaultSignature',
 133         'union_arguments': idl_type.union_arguments,
 134         'v8_set_return_value_for_main_world': v8_set_return_value(interface.name, method, this_cpp_value, for_main_world=True),
 135         'v8_set_return_value': v8_set_return_value(interface.name, method, this_cpp_value),
 136         'world_suffixes': ['', 'ForMainWorld'] if 'PerWorldBindings' in extended_attributes else [''],  # [PerWorldBindings]
 137     }
 138
 139
 140 def generate_argument(interface, method, argument, index):
 141     extended_attributes = argument.extended_attributes
 142     idl_type = argument.idl_type
 143     this_cpp_value = cpp_value(interface, method, index)
 144     is_variadic_wrapper_type = argument.is_variadic and idl_type.is_wrapper_type
 145
 146     return {
 147         'cpp_type': idl_type.cpp_type_args(used_in_cpp_sequence=is_variadic_wrapper_type),
 148         'cpp_value': this_cpp_value,
 149         'enum_validation_expression': idl_type.enum_validation_expression,
 150         'has_default': 'Default' in extended_attributes,
 151         'has_event_listener_argument': any(
 152             argument_so_far for argument_so_far in method.arguments[:index]
 153             if argument_so_far.idl_type.name == 'EventListener'),
 154         'has_legacy_overload_string':  # [LegacyOverloadString]
 155             'LegacyOverloadString' in extended_attributes,
 156         'has_type_checking_interface':
 157             (has_extended_attribute_value(interface, 'TypeChecking', 'Interface') or
 158              has_extended_attribute_value(method, 'TypeChecking', 'Interface')) and
 159             idl_type.is_wrapper_type,
 160         'has_type_checking_unrestricted':
 161             (has_extended_attribute_value(interface, 'TypeChecking', 'Unrestricted') or
 162              has_extended_attribute_value(method, 'TypeChecking', 'Unrestricted')) and
 163             idl_type.name in ('Float', 'Double'),
 164         # Dictionary is special-cased, but arrays and sequences shouldn't be
 165         'idl_type': not idl_type.array_or_sequence_type and idl_type.base_type,
 166         'idl_type_object': idl_type,
 167         'index': index,
 168         'is_clamp': 'Clamp' in extended_attributes,
 169         'is_callback_interface': idl_type.is_callback_interface,
 170         'is_nullable': idl_type.is_nullable,
 171         'is_optional': argument.is_optional,
 172         'is_variadic_wrapper_type': is_variadic_wrapper_type,
 173         'vector_type': v8_types.cpp_ptr_type('Vector', 'HeapVector', idl_type.gc_type),
 174         'is_wrapper_type': idl_type.is_wrapper_type,
 175         'name': argument.name,
 176         'v8_set_return_value_for_main_world': v8_set_return_value(interface.name, method, this_cpp_value, for_main_world=True),
 177         'v8_set_return_value': v8_set_return_value(interface.name, method, this_cpp_value),
 178         'v8_value_to_local_cpp_value': v8_value_to_local_cpp_value(argument, index),
 179     }
 180
 181
 182 ################################################################################
 183 # Value handling
 184 ################################################################################
 185
 186 def cpp_value(interface, method, number_of_arguments):
 187     def cpp_argument(argument):
 188         idl_type = argument.idl_type
 189         if idl_type.name == 'EventListener':
 190             if (interface.name == 'EventTarget' and
 191                 method.name == 'removeEventListener'):
 192                 # FIXME: remove this special case by moving get() into
 193                 # EventTarget::removeEventListener
 194                 return '%s.get()' % argument.name
 195             return argument.name
 196         if (idl_type.is_callback_interface or
 197             idl_type.name in ['NodeFilter', 'XPathNSResolver']):
 198             # FIXME: remove this special case
 199             return '%s.release()' % argument.name
 200         return argument.name
 201
 202     # Truncate omitted optional arguments
 203     arguments = method.arguments[:number_of_arguments]
 204     cpp_arguments = v8_utilities.call_with_arguments(method)
 205     # Members of IDL partial interface definitions are implemented in C++ as
 206     # static member functions, which for instance members (non-static members)
 207     # take *impl as their first argument
 208     if ('PartialInterfaceImplementedAs' in method.extended_attributes and
 209         not method.is_static):
 210         cpp_arguments.append('*impl')
 211     cpp_arguments.extend(cpp_argument(argument) for argument in arguments)
 212     this_union_arguments = method.idl_type and method.idl_type.union_arguments
 213     if this_union_arguments:
 214         cpp_arguments.extend(this_union_arguments)
 215
 216     if 'RaisesException' in method.extended_attributes:
 217         cpp_arguments.append('exceptionState')
 218
 219     if method.name == 'Constructor':
 220         base_name = 'create'
 221     elif method.name == 'NamedConstructor':
 222         base_name = 'createForJSConstructor'
 223     else:
 224         base_name = v8_utilities.cpp_name(method)
 225
 226     cpp_method_name = v8_utilities.scoped_name(interface, method, base_name)
 227     return '%s(%s)' % (cpp_method_name, ', '.join(cpp_arguments))
 228
 229
 230 def v8_set_return_value(interface_name, method, cpp_value, for_main_world=False):
 231     idl_type = method.idl_type
 232     extended_attributes = method.extended_attributes
 233     if not idl_type or idl_type.name == 'void':
 234         # Constructors and void methods don't have a return type
 235         return None
 236
 237     release = False
 238     # [CallWith=ScriptState], [RaisesException]
 239     if (has_extended_attribute_value(method, 'CallWith', 'ScriptState') or
 240         'RaisesException' in extended_attributes or
 241         idl_type.is_union_type):
 242         cpp_value = 'result'  # use local variable for value
 243         release = idl_type.release
 244
 245     script_wrappable = 'impl' if inherits_interface(interface_name, 'Node') else ''
 246     return idl_type.v8_set_return_value(cpp_value, extended_attributes, script_wrappable=script_wrappable, release=release, for_main_world=for_main_world)
 247
 248
 249 def v8_value_to_local_cpp_value(argument, index):
 250     extended_attributes = argument.extended_attributes
 251     idl_type = argument.idl_type
 252     name = argument.name
 253     if argument.is_variadic:
 254         vector_type = v8_types.cpp_ptr_type('Vector', 'HeapVector', idl_type.gc_type)
 255         return 'TONATIVE_VOID({vector_type}<{cpp_type}>, {name}, toNativeArguments<{cpp_type}>(info, {index}))'.format(
 256             vector_type=vector_type, cpp_type=idl_type.cpp_type, name=name,
 257             index=index)
 258     # [Default=NullString]
 259     if (argument.is_optional and idl_type.name == 'String' and
 260         extended_attributes.get('Default') == 'NullString'):
 261         v8_value = 'argumentOrNull(info, %s)' % index
 262     else:
 263         v8_value = 'info[%s]' % index
 264     return idl_type.v8_value_to_local_cpp_value(extended_attributes, v8_value,
 265                                                 name, index=index)
 266
 267
 268 ################################################################################
 269 # Auxiliary functions
 270 ################################################################################
 271
 272 # [NotEnumerable]
 273 def property_attributes(method):
 274     extended_attributes = method.extended_attributes
 275     property_attributes_list = []
 276     if 'NotEnumerable' in extended_attributes:
 277         property_attributes_list.append('v8::DontEnum')
 278     if 'ReadOnly' in extended_attributes:
 279         property_attributes_list.append('v8::ReadOnly')
 280     if property_attributes_list:
 281         property_attributes_list.insert(0, 'v8::DontDelete')
 282     return property_attributes_list
 283
 284
 285 def union_arguments(idl_type):
 286     """Return list of ['result0Enabled', 'result0', 'result1Enabled', ...] for union types, for use in setting return value"""
 287     return [arg
 288             for i in range(len(idl_type.member_types))
 289             for arg in ['result%sEnabled' % i, 'result%s' % i]]
 290
 291 IdlType.union_arguments = property(lambda self: None)
 292 IdlUnionType.union_arguments = property(union_arguments)