third_party/WebKit/Source/devtools/scripts/generate_protocol_externs.py

   1 #!/usr/bin/env python
   2 # Copyright (c) 2011 Google Inc. All rights reserved.
   3 #
   4 # Redistribution and use in source and binary forms, with or without
   5 # modification, are permitted provided that the following conditions are
   6 # met:
   7 #
   8 #     * Redistributions of source code must retain the above copyright
   9 # notice, this list of conditions and the following disclaimer.
  10 #     * Redistributions in binary form must reproduce the above
  11 # copyright notice, this list of conditions and the following disclaimer
  12 # in the documentation and/or other materials provided with the
  13 # distribution.
  14 #     * Neither the name of Google Inc. nor the names of its
  15 # contributors may be used to endorse or promote products derived from
  16 # this software without specific prior written permission.
  17 #
  18 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19 # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20 # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  21 # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22 # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  23 # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  24 # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25 # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26 # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  28 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29
  30 import re
  31
  32 type_traits = {
  33     "any": "*",
  34     "string": "string",
  35     "integer": "number",
  36     "number": "number",
  37     "boolean": "boolean",
  38     "array": "!Array.<*>",
  39     "object": "!Object",
  40 }
  41
  42 promisified_domains = {
  43     "Accessibility",
  44     "CSS",
  45     "Emulation",
  46     "Profiler"
  47 }
  48
  49 ref_types = {}
  50
  51 def full_qualified_type_id(domain_name, type_id):
  52     if type_id.find(".") == -1:
  53         return "%s.%s" % (domain_name, type_id)
  54     return type_id
  55
  56
  57 def fix_camel_case(name):
  58     refined = re.sub(r'-(\w)', lambda pat: pat.group(1).upper(), name)
  59     refined = to_title_case(refined)
  60     return re.sub(r'(?i)HTML|XML|WML|API', lambda pat: pat.group(0).upper(), refined)
  61
  62
  63 def to_title_case(name):
  64     return name[:1].upper() + name[1:]
  65
  66
  67 def generate_enum(name, json):
  68     enum_members = []
  69     for member in json["enum"]:
  70         enum_members.append("    %s: \"%s\"" % (fix_camel_case(member), member))
  71     return "\n/** @enum {string} */\n%s = {\n%s\n};\n" % (name, (",\n".join(enum_members)))
  72
  73
  74 def param_type(domain_name, param):
  75     if "type" in param:
  76         if param["type"] == "array":
  77             items = param["items"]
  78             return "!Array.<%s>" % param_type(domain_name, items)
  79         else:
  80             return type_traits[param["type"]]
  81     if "$ref" in param:
  82         type_id = full_qualified_type_id(domain_name, param["$ref"])
  83         if type_id in ref_types:
  84             return ref_types[type_id]
  85         else:
  86             print "Type not found: " + type_id
  87             return "!! Type not found: " + type_id
  88
  89
  90 def generate_protocol_externs(output_path, input_path):
  91     input_file = open(input_path, "r")
  92     json_string = input_file.read()
  93     json_string = json_string.replace(": true", ": True")
  94     json_string = json_string.replace(": false", ": False")
  95     json_api = eval(json_string)["domains"]
  96
  97     output_file = open(output_path, "w")
  98
  99     output_file.write(
 100 """
 101 var InspectorBackend = {}
 102
 103 var Protocol = {};
 104 /** @typedef {string}*/
 105 Protocol.Error;
 106 """)
 107
 108     for domain in json_api:
 109         domain_name = domain["domain"]
 110         if "types" in domain:
 111             for type in domain["types"]:
 112                 type_id = full_qualified_type_id(domain_name, type["id"])
 113                 ref_types[type_id] = "%sAgent.%s" % (domain_name, type["id"])
 114
 115     for domain in json_api:
 116         domain_name = domain["domain"]
 117         promisified = domain_name in promisified_domains
 118
 119         output_file.write("\n\n/**\n * @constructor\n*/\n")
 120         output_file.write("Protocol.%sAgent = function(){};\n" % domain_name)
 121
 122         if "commands" in domain:
 123             for command in domain["commands"]:
 124                 output_file.write("\n/**\n")
 125                 params = []
 126                 has_return_value = "returns" in command
 127                 explicit_parameters = promisified and has_return_value
 128                 if ("parameters" in command):
 129                     for in_param in command["parameters"]:
 130                         # All parameters are not optional in case of promisified domain with return value.
 131                         if (not explicit_parameters and "optional" in in_param):
 132                             params.append("opt_%s" % in_param["name"])
 133                             output_file.write(" * @param {%s=} opt_%s\n" % (param_type(domain_name, in_param), in_param["name"]))
 134                         else:
 135                             params.append(in_param["name"])
 136                             output_file.write(" * @param {%s} %s\n" % (param_type(domain_name, in_param), in_param["name"]))
 137                 returns = []
 138                 returns.append("?Protocol.Error")
 139                 if ("error" in command):
 140                     returns.append("%s=" % param_type(domain_name, command["error"]))
 141                 if (has_return_value):
 142                     for out_param in command["returns"]:
 143                         if ("optional" in out_param):
 144                             returns.append("%s=" % param_type(domain_name, out_param))
 145                         else:
 146                             returns.append("%s" % param_type(domain_name, out_param))
 147                 callback_return_type = "void="
 148                 if explicit_parameters:
 149                     callback_return_type = "T"
 150                 elif promisified:
 151                     callback_return_type = "T="
 152                 output_file.write(" * @param {function(%s):%s} opt_callback\n" % (", ".join(returns), callback_return_type))
 153                 if (promisified):
 154                     output_file.write(" * @return {!Promise.<T>}\n")
 155                     output_file.write(" * @template T\n")
 156                 params.append("opt_callback")
 157
 158                 output_file.write(" */\n")
 159                 output_file.write("Protocol.%sAgent.prototype.%s = function(%s) {}\n" % (domain_name, command["name"], ", ".join(params)))
 160                 output_file.write("/** @param {function(%s):void=} opt_callback */\n" % ", ".join(returns))
 161                 output_file.write("Protocol.%sAgent.prototype.invoke_%s = function(obj, opt_callback) {}\n" % (domain_name, command["name"]))
 162
 163         output_file.write("\n\n\nvar %sAgent = {};\n" % domain_name)
 164
 165         if "types" in domain:
 166             for type in domain["types"]:
 167                 if type["type"] == "object":
 168                     typedef_args = []
 169                     if "properties" in type:
 170                         for property in type["properties"]:
 171                             suffix = ""
 172                             if ("optional" in property):
 173                                 suffix = "|undefined"
 174                             if "enum" in property:
 175                                 enum_name = "%sAgent.%s%s" % (domain_name, type["id"], to_title_case(property["name"]))
 176                                 output_file.write(generate_enum(enum_name, property))
 177                                 typedef_args.append("%s:(%s%s)" % (property["name"], enum_name, suffix))
 178                             else:
 179                                 typedef_args.append("%s:(%s%s)" % (property["name"], param_type(domain_name, property), suffix))
 180                     if (typedef_args):
 181                         output_file.write("\n/** @typedef {!{%s}} */\n%sAgent.%s;\n" % (", ".join(typedef_args), domain_name, type["id"]))
 182                     else:
 183                         output_file.write("\n/** @typedef {!Object} */\n%sAgent.%s;\n" % (domain_name, type["id"]))
 184                 elif type["type"] == "string" and "enum" in type:
 185                     output_file.write(generate_enum("%sAgent.%s" % (domain_name, type["id"]), type))
 186                 elif type["type"] == "array":
 187                     output_file.write("\n/** @typedef {!Array.<!%s>} */\n%sAgent.%s;\n" % (param_type(domain_name, type["items"]), domain_name, type["id"]))
 188                 else:
 189                     output_file.write("\n/** @typedef {%s} */\n%sAgent.%s;\n" % (type_traits[type["type"]], domain_name, type["id"]))
 190
 191         output_file.write("/** @interface */\n")
 192         output_file.write("%sAgent.Dispatcher = function() {};\n" % domain_name)
 193         if "events" in domain:
 194             for event in domain["events"]:
 195                 params = []
 196                 if ("parameters" in event):
 197                     output_file.write("/**\n")
 198                     for param in event["parameters"]:
 199                         if ("optional" in param):
 200                             params.append("opt_%s" % param["name"])
 201                             output_file.write(" * @param {%s=} opt_%s\n" % (param_type(domain_name, param), param["name"]))
 202                         else:
 203                             params.append(param["name"])
 204                             output_file.write(" * @param {%s} %s\n" % (param_type(domain_name, param), param["name"]))
 205                     output_file.write(" */\n")
 206                 output_file.write("%sAgent.Dispatcher.prototype.%s = function(%s) {};\n" % (domain_name, event["name"], ", ".join(params)))
 207
 208     output_file.write("\n/** @constructor\n * @param {!Object.<string, !Object>} agentsMap\n */\n")
 209     output_file.write("Protocol.Agents = function(agentsMap){this._agentsMap;};\n")
 210     output_file.write("/**\n * @param {string} domain\n * @param {!Object} dispatcher\n */\n")
 211     output_file.write("Protocol.Agents.prototype.registerDispatcher = function(domain, dispatcher){};\n")
 212     for domain in json_api:
 213         domain_name = domain["domain"]
 214         uppercase_length = 0
 215         while uppercase_length < len(domain_name) and domain_name[uppercase_length].isupper():
 216             uppercase_length += 1
 217
 218         output_file.write("/** @return {!Protocol.%sAgent}*/\n" % domain_name)
 219         output_file.write("Protocol.Agents.prototype.%s = function(){};\n" % (domain_name[:uppercase_length].lower() + domain_name[uppercase_length:] + "Agent"))
 220
 221         output_file.write("/**\n * @param {!%sAgent.Dispatcher} dispatcher\n */\n" % domain_name)
 222         output_file.write("Protocol.Agents.prototype.register%sDispatcher = function(dispatcher) {}\n" % domain_name)
 223
 224
 225     output_file.close()
 226
 227 if __name__ == "__main__":
 228     import sys
 229     import os.path
 230     program_name = os.path.basename(__file__)
 231     if len(sys.argv) < 4 or sys.argv[1] != "-o":
 232         sys.stderr.write("Usage: %s -o OUTPUT_FILE INPUT_FILE\n" % program_name)
 233         exit(1)
 234     output_path = sys.argv[2]
 235     input_path = sys.argv[3]
 236     generate_protocol_externs(output_path, input_path)