Expand overloaded methods and optional parameters in the html library.

tools/dom/scripts/htmldartgenerator.py

 #!/usr/bin/python
 # Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 # for details. All rights reserved. Use of this source code is governed by a
 # BSD-style license that can be found in the LICENSE file.
 
 """This module provides shared functionality for the system to generate
 dart:html APIs from the IDL database."""
 
 import emitter
 from generator import AnalyzeOperation, ConstantOutputOrder, \
     DartDomNameOfAttribute, FindMatchingAttribute, IsDartCollectionType, \
     IsPureInterface, TypeOrNothing, ConvertToFuture, GetCallbackInfo
+from copy import deepcopy
 from htmlrenamer import convert_to_future_members
+import monitored
 
 # Types that are accessible cross-frame in a limited fashion.
 # In these cases, the base type (e.g., WindowBase) provides restricted access
 # while the subtype (e.g., Window) provides full access to the
 # corresponding objects if there are from the same frame.
 _secure_base_types = {
   'Window': 'WindowBase',
   'Location': 'LocationBase',
   'History': 'HistoryBase',
 }
 
 _custom_factories = [
   'Notification',
   'EventSource',
 ]
 
+# Members that have multiple definitions, but their types are vary, so we rename
+# them to make them distinct.
+_renamed_overloads = monitored.Dict('htmldartgenreator.renamed_overloads', {

[blois, 2013/06/24 16:58:02]

Could this go to htmlrenamer, just to keep our renames consolidated?

[Emily Fortuna, 2013/06/25 03:53:31]

Done.

+  'AudioContext.createBuffer(unsigned long numberOfChannels, unsigned long '
+      'numberOfFrames, float sampleRate)': 'createEmptyBuffer',
+  'AudioContext.createBuffer(ArrayBuffer buffer, boolean mixToMono)':
+      'createBufferFromBuffer',
+  'CSS.supports(DOMString conditionText)': 'supportsCondition',
+  'CSS.supports(DOMString property, DOMString value)': 'supportsProperty',
+  'CanvasRenderingContext2D.createPattern(HTMLCanvasElement canvas, '
+      'DOMString repetitionType)': 'createPatternFromCanvas',
+  'CanvasRenderingContext2D.createPattern(HTMLImageElement image, '
+      'DOMString repetitionType)': 'createPatternFromImage',
+  'DataTransferItemList.add(File file)': 'addFile',
+  'DataTransferItemList.add(DOMString data, DOMString type)': 'addData',
+  'FormData.append(DOMString name, DOMString value)': 'appendString',
+  'FormData.append(DOMString name, Blob value, DOMString filename)':
+      'appendBlob',
+  'IDBDatabase.transaction(DOMStringList storeNames, DOMString mode)':
+      'transactionStringList',
+  'IDBDatabase.transaction(sequence<DOMString> storeNames, DOMString mode)':
+      'transactionList',
+  'IDBDatabase.transaction(DOMString storeName, DOMString mode)':
+      'transactionString',
+  'RTCDataChannel.send(ArrayBuffer data)': 'sendByteBuffer',
+  'RTCDataChannel.send(ArrayBufferView data)': 'sendTypedData',
+  'RTCDataChannel.send(Blob data)': 'sendBlob',
+  'RTCDataChannel.send(DOMString data)': 'sendString',
+  'URL.createObjectURL(WebKitMediaSource source)':
+      'createObjectUrlFromSource',
+  'URL.createObjectURL(MediaStream stream)': 'createObjectUrlFromStream',
+  'URL.createObjectURL(Blob blob)': 'createObjectUrlFromBlob',
+  'WebGLRenderingContext.texImage2D(unsigned long target, long level, '
+      'unsigned long internalformat, unsigned long format, unsigned long '
+      'type, ImageData pixels)': 'texImage2DData',
+  'WebGLRenderingContext.texImage2D(unsigned long target, long level, '
+      'unsigned long internalformat, unsigned long format, unsigned long '
+      'type, HTMLImageElement image)': 'texImage2DImage',
+  'WebGLRenderingContext.texImage2D(unsigned long target, long level, '
+      'unsigned long internalformat, unsigned long format, unsigned long '
+      'type, HTMLCanvasElement canvas)': 'texImage2DCanvas',
+  'WebGLRenderingContext.texImage2D(unsigned long target, long level, '
+      'unsigned long internalformat, unsigned long format, unsigned long '
+      'type, HTMLVideoElement video)': 'texImage2DVideo',
+  'WebGLRenderingContext.texSubImage2D(unsigned long target, long level, '
+      'long xoffset, long yoffset, unsigned long format, unsigned long type, '
+      'ImageData pixels)': 'texSubImage2DData',
+  'WebGLRenderingContext.texSubImage2D(unsigned long target, long level, '
+      'long xoffset, long yoffset, unsigned long format, unsigned long type, '
+      'HTMLImageElement image)': 'texSubImage2DImage',
+  'WebGLRenderingContext.texSubImage2D(unsigned long target, long level, '
+      'long xoffset, long yoffset, unsigned long format, unsigned long type, '
+      'HTMLCanvasElement canvas)': 'texSubImage2DCanvas',
+  'WebGLRenderingContext.texSubImage2D(unsigned long target, long level, '
+      'long xoffset, long yoffset, unsigned long format, unsigned long type, '
+      'HTMLVideoElement video)': 'texSubImage2DVideo',
+  'WebGLRenderingContext.bufferData(unsigned long target, '
+      'ArrayBufferView data, unsigned long usage)': 'bufferTypedData',
+  'WebGLRenderingContext.bufferData(unsigned long target, long long size, '
+      'unsigned long usage)': 'bufferEmptyData',
+  'WebGLRenderingContext.bufferSubData(unsigned long target, '
+      'long long offset, ArrayBufferView data)': 'bufferSubTypedData',
+  'WebSocket.send(ArrayBuffer data)': 'sendByteBuffer',
+  'WebSocket.send(ArrayBufferView data)': 'sendTypeData',
+  'WebSocket.send(DOMString data)': 'sendString',
+  'WebSocket.send(Blob data)': 'sendBlob'
+})
+
 class HtmlDartGenerator(object):
   def __init__(self, interface, options):
     self._database = options.database
     self._interface = interface
     self._type_registry = options.type_registry
     self._interface_type_info = self._type_registry.TypeInfo(self._interface.id)
     self._renamer = options.renamer
     self._metadata = options.metadata
     self._library_name = self._renamer.GetLibraryName(self._interface)
 
@@ skipping 36 matching lines @@
     else:
       for parent in self._database.Hierarchy(self._interface):
         if parent == self._interface:
           continue
         parent_type_info = self._type_registry.TypeInfo(parent.id)
         if parent_type_info.list_item_type():
           self.AmendIndexer(parent_type_info.list_item_type())
           break
 
     # Group overloaded operations by name.
+    self._AddRenamedOverloads(interface)
     operationsByName = self._OperationsByName(interface)
 
     # Generate operations.
     for id in sorted(operationsByName.keys()):
       operations = operationsByName[id]
       info = AnalyzeOperation(interface, operations)
       self.AddOperation(info, declare_only)
       if ('%s.%s' % (interface.id, info.declared_name) in
           convert_to_future_members):
         self.AddOperation(ConvertToFuture(info), declare_only)
@@ skipping 16 matching lines @@
       operationsByName =self._OperationsByName(parent_interface)
 
       # Generate operations.
       for id in sorted(operationsByName.keys()):
         if not any(op.id == id for op in interface.operations):
           operations = operationsByName[id]
           info = AnalyzeOperation(interface, operations)
           self.SecondaryContext(parent_interface)
           self.AddOperation(info)
 
+  def _AddRenamedOverloads(self, interface):
+    """The IDL has a number of functions with the same name but that accept
+    different types. This is fine for JavaScript, but results in vague type
+    signatures for Dart. We rename some of these (by adding a new identical
+    operation with a different DartName), but leave the original version as
+    well."""
+    # This function gets called twice per interface if we generate both dart2js

[blois, 2013/06/24 16:58:02]

Is there a more central place we can do this, so it doesn't get called twice?

[Emily Fortuna, 2013/06/25 03:53:31]

Not really if we do it in the python scripts, unless I put the call in the very
top level dartdomgenerator.py script or when we're reading in the database from
the IDL, which is odd because no modifications happen there. Despite the fact
that we have to make sure this runs only once, functionally, it seems more in
keeping to keep it here.

+    # and dartium APIs, but we only want to rename the overloads once, so we
+    # keep track of this via already_renamed.
+    already_renamed = [operation.ext_attrs['DartName'] if 'DartName' in

[blois, 2013/06/24 16:58:02]

Doesn't have to be in this CL, but we should remove all 'DartName' attributes to
the table.

+        operation.ext_attrs else '' for operation in interface.operations]
+    added_operations = []
+    for operation in interface.operations:

[blois, 2013/06/24 16:58:02]

Are there any warnings when there are overloads that have not been separated?

[Emily Fortuna, 2013/06/25 03:53:31]

added a warning output, but it's not super useful for the amount of additional
code added. See what you think.

+      if (self._GetStringRepresentation(
+          interface, operation) in _renamed_overloads and _renamed_overloads[
+            self._GetStringRepresentation(interface, operation)] not in
+            already_renamed):
+        cloned_operation = deepcopy(operation)
+        cloned_operation.ext_attrs['DartName'] = _renamed_overloads[
+            self._GetStringRepresentation(interface, operation)]
+        added_operations.append(cloned_operation)
+    interface.operations += added_operations
+
+  def _GetStringRepresentation(self, interface, operation):
+    """Given an IDLOperation, return a object-independent representation of the
+    operations's signature."""
+    return '%s.%s(%s)' % (interface.id, operation.id, ', '.join(
+        ['%s %s' % (arg.type.id, arg.id) for arg in operation.arguments]))
+
   def _OperationsByName(self, interface):
     operationsByName = {}
     for operation in interface.operations:
       name = operation.ext_attrs.get('DartName', operation.id)
       operationsByName.setdefault(name, []).append(operation)
     return operationsByName
 
   def AddConstant(self, constant):
     const_name = self._renamer.RenameMember(
         self._interface.id, constant, constant.id, 'get:', dartify_name=False)
@@ skipping 453 matching lines @@
     if interface.parents:
       parent = interface.parents[0]
       if IsPureInterface(parent.type.id):
         walk(interface.parents)
       else:
         walk(interface.parents[1:])
     return result
 
   def _DartType(self, type_name):
     return self._type_registry.DartType(type_name)