Code generation for extensions api

tools/json_schema_compiler/code.py

+# Copyright (c) 2011 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.
+"""Utilities for code generation.
+
+Main classes are Code for appending code and
+TypeManager for managing types for things in model."""
+
+from model import PropertyType
+from datetime import datetime
+
+
+CHROMIUM_LICENSE = (
+"""// Copyright (c) %d 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.""" % datetime.now().year
+)
+WARNING_MESSAGE = """// GENERATED FROM THE API DEFINITION IN
+//   %s
+// DO NOT EDIT."""

[not at google - send to devlin, 2012/01/13 02:14:09]

This is a specific to C/C++, so code.py doesn't seem like the right place for
it.  How about having a shared file for c++ code generation which both
generate_cc and generate_h can use.

[calamity, 2012/01/16 04:01:06]

Done.

+
+INDENT_SIZE = 2
+COMMENT_LENGTH = 80

[not at google - send to devlin, 2012/01/13 02:14:09]

put as members / arguments in the constructor of Code, with default values set
to these.

[calamity, 2012/01/16 04:01:06]

Done.

+class Code(object):

[not at google - send to devlin, 2012/01/13 02:14:09]

is explicitly extending object necessary?

[calamity, 2012/01/16 04:01:06]

It defines it as a "new style" class. Not sure if that's necessary though (I
know you need it for subclassing, but maybe there's something else about it?)

[not at google - send to devlin, 2012/01/17 01:59:24]

Ah... alright.  If it's like Java, classes automatically/implicitly extend from
object, it's weird to see "class Blah extends Object".  But it seems like python
behaves differently.

+  """A convenience object for appending code.

[not at google - send to devlin, 2012/01/13 02:14:09]

s/appending/constructing/

or something.

Also add that all methods (besides |render|) return self.

[calamity, 2012/01/16 04:01:06]

Done.

+
+  Logically each object should be a block of code."""

[not at google - send to devlin, 2012/01/13 02:14:09]

these docstrings should have a blank line after them, and the closing """ should
be on a line of its own.

(same for every class)

http://google-styleguide.googlecode.com/svn/trunk/pyguide.html#Comments

[calamity, 2012/01/16 04:01:06]

Done.

+  def __init__(self):
+    self.code = []
+    # TODO(calamity): Indent stack probably isn't necessary

[not at google - send to devlin, 2012/01/13 02:14:09]

you can delete this comment and _indent_list, right?

[calamity, 2012/01/16 04:01:06]

Done.

+    self._indent_list = []
+    self.indent_level = 0

[not at google - send to devlin, 2012/01/13 02:14:09]

these should have an _ prefix

[calamity, 2012/01/16 04:01:06]

Done.

+
+  def append(self, line=''):
+    """Appends a line of code at the current indent level or just a
+    newline if line is not specified.
+
+    This will strip trailing whitespace."""

[not at google - send to devlin, 2012/01/13 02:14:09]

... newline if line is not specified. Trailing whitespace is stripped.
"""

more concise documentation ftw.

[calamity, 2012/01/16 04:01:06]

Done.

+    self.code.append(((' ' * self.indent_level) + line).rstrip())
+    return self
+
+  def add(self, obj):

[not at google - send to devlin, 2012/01/13 02:14:09]

I wonder if it's more convenient to just merge this into append.  That would let
functions return either a string or a code block depending on what they were
feeling like, and it kind of looks nicer IMO.

def append(self, content=''):
  if isinstance(content, str):
    self.code.append(((' ' * self.indent_level)) + line).rstrip()
  elif isinstance(content, Code):
    for line in content.code:
      self.append(line)
  else:
    raise TypeError('blah type not supported blah')
  return self

you'd need to carefully document that too, of course.

[calamity, 2012/01/16 04:01:06]

Maybe. Might be unpythonic. code.Code is meant to be similar to the list api
which uses append for adding an element and + for adding another list.

[not at google - send to devlin, 2012/01/17 01:59:24]

Cool, don't worry about it then.

+    """Concatenate another Code object onto this one.
+
+    Appends the code at the current indent level. Will fail if there are any
+    un-interpolated format specifiers eg %s, %(something)s which helps
+    isolate any strings that haven't been substituted.
+    """
+    if not isinstance(obj, Code):
+      raise TypeError()
+    for line in obj.code:
+      self.code.append(((' ' * self.indent_level) + line % ()).rstrip())
+
+    return self
+
+  # TODO(calamity): is variable indent size necessary/a good idea?

[not at google - send to devlin, 2012/01/13 02:14:09]

TODO unnecessary

[calamity, 2012/01/16 04:01:06]

Done.

+  def sblock(self, line):
+    """Starts a code block.

[not at google - send to devlin, 2012/01/13 02:14:09]

"""Starts a code block, by appending a line of code then increasing the indent
level.
"""

by the way, for consistency, this method should probably have line='' too.

[calamity, 2012/01/16 04:01:06]

Done.

+
+    Adds a line of code and then increases the indent level."""
+    self.append(line)
+    self.indent_level += INDENT_SIZE
+    return self
+
+  def eblock(self, line=''):
+    """Ends a code block.

[not at google - send to devlin, 2012/01/13 02:14:09]

"""Ends a code block, by decreasing the indent level then appending a line (or
a blank line if none is given.
"""

[calamity, 2012/01/16 04:01:06]

Done.

+
+    Decreases the indent level and then adds the line of code.
+    """
+    # TODO(calamity): Decide if type checking is necessary
+    #if not isinstance(line, basestring):
+    #  raise TypeError
+    self.indent_level -= INDENT_SIZE
+    self.append(line)
+    return self
+
+  def comment(self, comment):
+    """Adds the given string as a comment.
+
+    Will split the comment if it's too long. Use mainly for variable length
+    comments. Otherwise just use code.append('// ...') for comments.
+    """
+    comment_symbol = '// '
+    max_len = COMMENT_LENGTH - self.indent_level - len(comment_symbol)
+    while len(comment) >= max_len:
+      line = comment[0:max_len]
+      last_space = line.rfind(' ')
+      if last_space != -1:
+        line = line[0:last_space]
+        comment = comment[last_space + 1:]
+      else:
+        comment = comment[max_len:]
+      self.append(comment_symbol + line)
+    self.append(comment_symbol + comment)
+    return self
+
+  def substitute(self, d):
+    """Goes through each line and interpolates using the given dict.
+
+    Raises type error if passed something that isn't a dict."""

[not at google - send to devlin, 2012/01/13 02:14:09]

"Raises type error" comment is unnecessary.

[calamity, 2012/01/16 04:01:06]

The style guide says it should list exceptions it raises? To be honest, these
should be documented a lot better than they are.

[not at google - send to devlin, 2012/01/17 01:59:24]

This isn't really an exception though, it's a programmer error.

In fact I think it should be an assertion.

[calamity, 2012/01/18 05:43:08]

Done.

+    if not isinstance(d, dict):
+      raise TypeError('Passed argument is not a dictionary: ' + d)
+    for i, line in enumerate(self.code):
+      # Only need to check %s because arg is a dict and python will allow
+      # '%s %(named)s' but just about nothing else
+      if '%s' in self.code[i] or '%r' in self.code[i]:
+        raise TypeError('%s or %r found in substitution.'
+            'Named arguments only. Use %%s to escape')
+      self.code[i] = line % d
+    return self
+
+  def render(self):
+    """Returns the code joined together as a string."""

[not at google - send to devlin, 2012/01/13 02:14:09]

"""Renders the Code as a string.
"""

[calamity, 2012/01/16 04:01:06]

Done.

+    return '\n'.join(self.code)
+
+def cpp_name(s):

[not at google - send to devlin, 2012/01/13 02:14:09]

this also belongs in a c++ util class

[calamity, 2012/01/16 04:01:06]

Done.

+  """Translates a namespace name or function name into something more
+  suited to C++.
+
+  eg experimental.downloads -> Experimental_Downloads
+  updateAll -> UpdateAll.
+  """
+  return '_'.join([x[0].upper() + x[1:] for x in s.split('.')])
+