blob: 60b165a3c1e400fc8528b4527962235128d2555a [file] [log] [blame]
# Copyright 2016 The Chromium Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.
# pylint: disable=import-error,print-statement,relative-import
"""Generates Web Agent API bindings.
The Web Agent API bindings provide a stable, IDL-generated interface for the
Web Agents.
The Web Agents are the high-level services like Autofill,
Autocomplete, Translate, Distiller, Phishing Detector, and others. Web Agents
typically want to introspec the document and rendering infromation to implement
browser features.
The bindings are meant to be as simple and as ephemeral as possible, mostly just
wrapping existing DOM classes. Their primary goal is to avoid leaking the actual
DOM classes to the Web Agents layer.
import os
import posixpath
import sys
from .code_generator import CodeGeneratorBase, render_template
# TODO(dglazkov): Move TypedefResolver to
from .code_generator_v8 import TypedefResolver
sys.path.append(os.path.join(os.path.dirname(__file__), '..', '..', '..', '..', '..',
'third_party', 'blink', 'tools'))
from blinkpy.common.name_style_converter import NameStyleConverter
MODULE_PYNAME = os.path.splitext(os.path.basename(__file__))[0] + '.py'
STRING_INCLUDE_PATH = 'platform/wtf/text/WTFString.h'
def interface_context(idl_interface, type_resolver):
builder = InterfaceContextBuilder(MODULE_PYNAME, type_resolver)
for idl_attribute in idl_interface.attributes:
for idl_operation in idl_interface.operations:
class TypeResolver(object):
"""Resolves Web IDL types into corresponding C++ types and include paths
to the generated and existing files."""
def __init__(self, interfaces_info):
self.interfaces_info = interfaces_info
def includes_from_interface(self, interface_name):
interface_info = self.interfaces_info.get(interface_name)
if interface_info is None:
raise KeyError('Unknown interface "%s".' % interface_name)
return set([interface_info['include_path']])
def _includes_from_type(self, idl_type):
if idl_type.is_void:
return set()
if idl_type.is_primitive_type:
return set()
if idl_type.is_string_type:
# TODO(dglazkov): Handle complex/weird types.
return self.includes_from_interface(idl_type.base_type)
def includes_from_definition(self, idl_definition):
return self._includes_from_type(idl_definition.idl_type)
def type_from_definition(self, idl_definition):
# TODO(dglazkov): The output of this method must be a reasonable C++
# type that can be used directly in the jinja2 template.
return idl_definition.idl_type.base_type
def base_class_includes(self):
return set(['platform/heap/Handle.h'])
class MethodOverloadSplitter(object):
"""Because of union and optional types being used as arguments, some
operations may result in more than one generated method. This class
contains the logic for spliting an operation into multiple C++ overloads.
def __init__(self, idl_operation):
self.idl_operation = idl_operation
def _update_argument_lists(self, argument_lists, idl_types):
"""Given a list of IdlTypes and an existing list of argument lists (yes,
this is a list of lists), produces a next generation of the list of
lists. This is where the actual splitting into overloads happens.
result = []
for argument_list in argument_lists:
for idl_type in idl_types:
new_argument_list = list(argument_list)
if idl_type is not None:
return result
def _enumerate_argument_types(self, idl_argument):
"""Given an IdlArgument, returns a list of types that are included
in this argument. If optional, the list will include a 'None'."""
argument_type = idl_argument.idl_type
# TODO(dglazkov): What should we do with primitive nullable args?
if (argument_type.is_nullable and
raise ValueError('Primitive nullable types are not supported.')
idl_types = []
if idl_argument.is_optional:
idl_types.append(None) # None is used to convey optionality.
if argument_type.is_union_type:
idl_types = idl_types + argument_type.member_types
return idl_types
def split_into_overloads(self):
"""Splits an operation into one or more overloads that correctly reflect
the WebIDL semantics of the operation arguments. For example,
running this method on an IdlOperation that represents this WebIDL
void addEventListener(
DOMString type,
EventListener? listener,
optional (AddEventListenerOptions or boolean) options)
will produce a list of 3 argument lists:
1) [DOMString, EventListener], since the third argument is optional,
2) [DOMString, EventListener, AddEventListenerOptions], since the
third argument is a union type with AddEventListenerOptions as
one of its member types, and
3) [DOMString, EventListener, boolean], since the other union member
type of the third argument is boolean.
This example is also captured as test in
argument_lists = [[]]
for idl_argument in self.idl_operation.arguments:
idl_types = self._enumerate_argument_types(idl_argument)
argument_lists = self._update_argument_lists(argument_lists,
return argument_lists
class InterfaceContextBuilder(object):
def __init__(self, code_generator, type_resolver):
self.result = {'code_generator': code_generator}
self.type_resolver = type_resolver
def set_class_name(self, class_name):
converter = NameStyleConverter(class_name)
self.result['class_name'] = converter.to_all_cases()
def set_inheritance(self, base_interface):
if base_interface is None:
self.result['base_class'] = base_interface
def _ensure_set(self, name):
return self.result.setdefault(name, set())
def _ensure_list(self, name):
return self.result.setdefault(name, [])
def add_attribute(self, idl_attribute):
def add_operation(self, idl_operation):
if not
overload_splitter = MethodOverloadSplitter(idl_operation)
overloads = overload_splitter.split_into_overloads()
argument_names = [ for argument
in idl_operation.arguments]
for argument_types in overloads:
arguments = []
for position, argument_type in enumerate(argument_types):
self.create_method(idl_operation, arguments))
def create_argument(self, argument_name, argument_type):
name_converter = NameStyleConverter(argument_name)
return {
'name': name_converter.to_snake_case(),
'type': argument_type.base_type,
def create_method(self, idl_operation, arguments):
name_converter = NameStyleConverter(
return_type = self.type_resolver.type_from_definition(idl_operation)
return {
'name': name_converter.to_upper_camel_case(),
'type': return_type,
'arguments': arguments
def create_attribute(self, idl_attribute):
name =
return_type = self.type_resolver.type_from_definition(idl_attribute)
return {
'name': name,
'type': return_type
def build(self):
return self.result
class CodeGeneratorWebAgentAPI(CodeGeneratorBase):
def __init__(self, info_provider, cache_dir, output_dir, snake_case):
CodeGeneratorBase.__init__(self, MODULE_PYNAME, info_provider,
cache_dir, output_dir, snake_case)
self.type_resolver = TypeResolver(info_provider.interfaces_info)
self.typedef_resolver = TypedefResolver(info_provider)
def get_template(self, file_extension):
template_filename = 'web_agent_api_interface.%s.tmpl' % file_extension
return self.jinja_env.get_template(template_filename)
def generate_file(self, template_context, file_extension):
template = self.get_template(file_extension)
path = posixpath.join(
'%s.%s' % (template_context['class_name']['snake_case'],
text = render_template(template, template_context)
return (path, text)
def generate_interface_code(self, interface):
# TODO(dglazkov): Implement callback interfaces.
# TODO(dglazkov): Make sure partial interfaces are handled.
if interface.is_callback or interface.is_partial:
raise ValueError('Partial or callback interfaces are not supported')
template_context = interface_context(interface, self.type_resolver)
return (
self.generate_file(template_context, 'h'),
self.generate_file(template_context, 'cc')
def generate_code(self, definitions, definition_name):
self.typedef_resolver.resolve(definitions, definition_name)
# TODO(dglazkov): Implement dictionaries
if definition_name not in definitions.interfaces:
return None
interface = definitions.interfaces[definition_name]
if WEB_AGENT_API_IDL_ATTRIBUTE not in interface.extended_attributes:
return None
return self.generate_interface_code(interface)