Add Python flow to bindings generation, move dummy-generating IDL files over

Source/bindings/scripts/build_ir.py

+# Copyright (C) 2013 Google Inc. All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#     * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+#     * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+"""Convert generic Web IDL AST to Blink IR.
+
+This converts the AST (produced by the parser) into the IR (a Python object
+of class IdlDocument).
+This is the last phase of the frontend, after the lexer and the parser.
+This also merges interface dependencies (partial interfaces and implements),
+and validates extended attributes.
+The result is an object representing a complete, validated interface.
+The IR is then used by the code generator to produce .cpp/.h files.
+
+Ideally the parser would generate the IR directly, rather then requiring this
+additional phase, but that would require major changes to the parser, which
+currently produces a generic AST instead.
+
+FIXME: Currently a stub, as part of landing the parser incrementally.
+Just computes dependencies, and should always raise an exception,
+indicating no file found, so no actual parsing done.
+"""
+
+import os.path
+
+
+def read_merged_idl(idl_filename, supplemental_dependency_file=None, additional_idl_files=None):
+    """Returns Blink IR for an IDL file, including all dependencies."""
+    basename = os.path.basename(idl_filename)
+
+    # First check dependency files, so throws exception if not listed.
+    dependency_idl_files = compute_dependency_idl_files(basename, supplemental_dependency_file, additional_idl_files)
+    # FIXME: currently *must* raise IdlNotFoundError (indicating that dummy
+    # .cpp and .h files should be generated), as actual parser not present yet.
+    raise RuntimeError('Stub: parser not implemented yet')
+    # FIXME: turn on parser and other steps once these land
+    # blink_ir = read_idl_file(idl_filename, verbose=verbose)
+    # interface = get_interface(blink_ir, interface_name)
+    # merge_interface_dependencies(interface, idl_filename, dependency_idl_files, verbose=verbose)
+    # validate_extended_attributes(blink_ir, basename, idl_attributes_file)
+
+
+class IdlNotFoundError(Exception):

[haraken, 2013/07/09 11:16:48]

Instead of raising IdlNotFoundError, can we just return [] from read_merged_idl?
Exception gives me an impression that something unexpected happens.

[Nils Barth (inactive), 2013/07/10 02:38:32]

It is a bit more explicit to return None, since this isn't actually
unexpected. Done!
(This also avoids having a long description of the error.)

+    """Raised if IDL file not found in lists of files to generate bindings for.
+
+    Concretely, this means the IDL filename is neither found as a head entry in
+    the dependencies file nor in the additional files list.
+    This indicates that the IDL should not have bindings generated, and
+    occurs if one tries to compute dependencies for a file that is itself
+    a dependency, i.e., a partial dependency or an interface that is
+    implemented by another interface.
+    """
+    pass
+
+
+def compute_dependency_idl_files(target_idl_basename, interface_dependencies_filename, additional_idl_files):
+    """Returns list of IDL file dependencies for a given main IDL file.
+
+    - Returns a list of IDL files on which a given IDL file depends,
+      possibly empty.
+    - Dependencies consist of partial interface files and files for other
+      interfaces that the given interface implements.

[haraken, 2013/07/09 11:16:48]

Nit: Let's put these two sentences in one paragraph. In this comment, we want to
explain one return value in one paragraph.

[Nils Barth (inactive), 2013/07/10 02:38:32]

Done.

+    - Returns an empty list also if the given IDL file is an additional IDL
+      file.
+    - Raises IdlNotFoundError otherwise. This happens when the given IDL file
+      is a dependency, for which we don't want to generate bindings.
+    """
+    # The format of the interface dependencies file is:
+    #
+    # Document.idl P.idl
+    # Event.idl
+    # Window.idl Q.idl R.idl S.idl
+    # ...
+    #
+    # The above indicates that:
+    # Document.idl depends on P.idl,
+    # Event.idl depends on no other IDL files, and
+    # Window.idl depends on Q.idl, R.idl, and S.idl.
+    #
+    # The head entries (first IDL file on a line) are the files that should
+    # have bindings generated.
+    #
+    # An IDL file that is a dependency of another IDL file (e.g., P.idl in the
+    # above example) does not have its own line in the dependency file:
+    # dependencies do not have bindings generated, and do not have their
+    # own dependencies.
+
+    if interface_dependencies_filename is None:
+        return []
+    with open(interface_dependencies_filename) as interface_dependencies_file:
+        for line in interface_dependencies_file:
+            idl_filename, _, dependency_files = line.partition(' ')
+            if os.path.basename(idl_filename) == target_idl_basename:
+                return dependency_files.split()
+
+    # additional_idl_files is a list of IDL files which should not be included
+    # in DerivedSources*.cpp, and hence are not listed in the supplemental
+    # dependency file, but for which we should generate .cpp and .h files.
+    additional_idl_basenames = set(map(os.path.basename, additional_idl_files))
+    if target_idl_basename in additional_idl_basenames:
+        return []
+    raise IdlNotFoundError