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

Source/bindings/scripts/idl_reader.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.
+
+"""Read an IDL file or complete IDL interface, producing an IdlDocument object.
+
+For a single IDL file, this library calls the parser, which produces a generic
+Web IDL AST. The AST is then converted into the IR, a Python object of class
+IdlDocument.
+For a complete interface, it calls the dependency resolver, which reads all
+IDLs files needed by an interface (main file plus partial interfaces and
+implements), merges these into a single IdlDocument, and then calls the
+validator to validate extended attributes.
+The result is an IdlDocument representing a complete, validated interface.
+This IdlDocument is then used by the code generator to produce .h/.cpp files.
+
+Ideally the parser would generate the IdlDocument directly, rather then
+requiring this additional phase, but that would require major changes to the
+parser, which currently produces a generic AST instead.

[haraken, 2013/07/10 06:22:48]

I'd remove this comment at this point, since none of them has implemented.

Basically, comments in this CL are a bit verbose. You don't need to add comments
to each method in the future CLs. They are very likely to be out-dated, which we
really want to avoid.

[Nils Barth (inactive), 2013/07/10 07:04:11]

Got it; will add when actually implemented.
Yeah, the comments have a mix of "overview" (top of file),
"what's not implemented yet" (but is about to), and
usual "interface/what this function does".
A bit of overview and interface documentation is helpful,
but in landing the parser itself let's make sure there's no cruft.

+
+FIXME: Currently a stub, as part of landing the parser incrementally.
+Just create dummy IdlDocuments (no parsing or object building done), and
+resolve dependencies.
+The interface reader should always return None, indicating that bindings should
+not be generated, since the code generator has also not landed yet.
+"""
+
+import os.path
+
+import idl_dependency_resolver
+
+
+class IdlDocument():

[haraken, 2013/07/10 06:22:48]

There is no concept of "IdlDocument" in the spec. You might want to rename it to
"InterfaceDefinition".

Ideally, we should support InterfaceDefinition*s*, but we don't yet support
multiple interfaces written in one IDL file. So, for now, I think we can just
assume one interface per IDL file and just use "InterfaceDefinition" here.

[Nils Barth (inactive), 2013/07/10 07:04:11]

Closest to the spec would be "IdlDefinitions", as Definitions
include interfaces, callbacks, enums, dictionaries, exceptions, etc.

Currently (Perl IDL) we have an IdlDocument object (which I'm
following),
which contains lists of callback_functions, enumerations, and interfaces, so it
would be confusing to use "Interface" for the
whole object too.

We definitely need to do some renaming: "DomFunction" is nowhere
in the *IDL* spec!
We only have one interface, but callbacks and enums are also definitions,
so it is accurate to call it "IdlDefinition*s*".

Also, we probably also need to read parent interfaces and include them here,
so the code generator can refer to the parent interfaces without
having to call the parser itself!
(The Perl code generator reads parent interfaces.)

So even though we only have one interface per file,
we need to read several other interfaces to generate the code
for a single interface.

+    """Top-level IDL class.
+
+    In Web IDL spec terms, represents a set of definitions, obtained by parsing
+    a set of IDL fragments (i.e., the contents of .idl files)."""

[haraken, 2013/07/10 06:22:48]

Would you add a link to the exact position of the spec?

[Nils Barth (inactive), 2013/07/10 07:04:11]

Done.

+    # FIXME: Dummy class; full class hierarchy will be added with parser
+    pass
+
+
+def read_idl_interface(idl_filename, interface_dependencies_filename, additional_idl_filenames):
+    """Returns an IdlDocument for an IDL interface, including all dependencies."""
+    basename = os.path.basename(idl_filename)
+
+    idl_document = read_idl_file(idl_filename)
+    should_generate_bindings = idl_dependency_resolver.merge_interface_dependencies(idl_document, idl_filename, interface_dependencies_filename, additional_idl_filenames)
+    if not should_generate_bindings:
+        return None
+    # FIXME: turn on validator
+    # idl_validator.validate_extended_attributes(idl_document, basename, options.idl_attributes_file)
+    return idl_document
+
+
+def read_idl_file(idl_filename, verbose=False):
+    """Returns an IdlDocument for an IDL file, without any dependencies."""
+    # FIXME: Currently returns dummy object, as parser not present yet.
+    # parser = BlinkIDLParser(verbose=verbose)
+    # file_node = blink_idl_parser.parse_file(parser, idl_filename)
+    # return idl_document_builder.file_node_to_idl_document(file_node)
+    return IdlDocument()