Add the ability to deprecate Flatbuffer fields.

pkg/analyzer/tool/summary/generate.dart

 // Copyright (c) 2015, 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 file contains code to generate serialization/deserialization logic for
  * summaries based on an "IDL" description of the summary format (written in
  * stylized Dart).
  *
  * For each class in the "IDL" input, two corresponding classes are generated:
@@ skipping 45 matching lines @@
 final GeneratedFile schemaTarget =
     new GeneratedFile('lib/src/summary/format.fbs', (String pkgPath) {
   _CodeGenerator codeGenerator = new _CodeGenerator(pkgPath);
   codeGenerator.generateFlatBufferSchema();
   return codeGenerator._outBuffer.toString();
 });
 
 typedef String _StringToString(String s);
 
 class _CodeGenerator {
+  static const String _throwDeprecated =
+      "throw new UnimplementedError('attempt to access deprecated field')";
+
   /**
    * Buffer in which generated code is accumulated.
    */
   final StringBuffer _outBuffer = new StringBuffer();
 
   /**
    * Current indentation level.
    */
   String _indentation = '';
 
@@ skipping 194 matching lines @@
             if (type.name.name == 'List' &&
                 type.typeArguments != null &&
                 type.typeArguments.arguments.length == 1) {
               isList = true;
               type = type.typeArguments.arguments[0];
             }
             if (type.typeArguments != null) {
               throw new Exception('Cannot handle type arguments in `$type`');
             }
             int id;
+            bool isDeprecated = false;
             for (Annotation annotation in classMember.metadata) {
               if (annotation.name.name == 'Id') {
                 if (id != null) {
                   throw new Exception(
                       'Duplicate @id annotation ($classMember)');
                 }
                 if (annotation.arguments.arguments.length != 1) {
                   throw new Exception(
                       '@Id must be passed exactly one argument ($desc)');
                 }
                 Expression expression = annotation.arguments.arguments[0];
                 if (expression is IntegerLiteral) {
                   id = expression.value;
                 } else {
                   throw new Exception(
                       '@Id parameter must be an integer literal ($desc)');
                 }
+              } else if (annotation.name.name == 'deprecated') {
+                if (annotation.arguments != null) {
+                  throw new Exception('@deprecated does not take args ($desc)');
+                }
+                isDeprecated = true;
               }
             }
             if (id == null) {
               throw new Exception('Missing @id annotation ($desc)');
             }
             String doc = _getNodeDoc(lineInfo, classMember);
             idlModel.FieldType fieldType =
                 new idlModel.FieldType(type.name.name, isList);
-            cls.fields.add(new idlModel.FieldDeclaration(
-                doc, classMember.name.name, fieldType, id));
+            cls.allFields.add(new idlModel.FieldDeclaration(
+                doc, classMember.name.name, fieldType, id, isDeprecated));
           } else if (classMember is ConstructorDeclaration &&
               classMember.name.name == 'fromBuffer') {
             // Ignore `fromBuffer` declarations; they simply forward to the
             // read functions generated by [_generateReadFunction].
           } else {
             throw new Exception('Unexpected class member `$classMember`');
           }
         }
       } else if (decl is EnumDeclaration) {
         String doc = _getNodeDoc(lineInfo, decl);
@@ skipping 64 matching lines @@
           out('${value.name}$suffix');
         }
       });
       out('}');
     }
     for (idlModel.ClassDeclaration cls in _idl.classes.values) {
       out();
       outDoc(cls.documentation);
       out('table ${cls.name} {');
       indent(() {
-        for (int i = 0; i < cls.fields.length; i++) {
-          idlModel.FieldDeclaration field = cls.fields[i];
+        for (int i = 0; i < cls.allFields.length; i++) {
+          idlModel.FieldDeclaration field = cls.allFields[i];
           if (i != 0) {
             out();
           }
           outDoc(field.documentation);
-          out('${field.name}:${fbsType(field.type)} (id: ${field.id});');
+          List<String> attributes = <String>['id: ${field.id}'];
+          if (field.isDeprecated) {
+            attributes.add('deprecated');
+          }
+          String attrText = attributes.join(', ');
+          out('${field.name}:${fbsType(field.type)} ($attrText);');
         }
       });
       out('}');
     }
     out();
     // Standard flatbuffers only support one root type.  We support multiple
     // root types.  For now work around this by forcing PackageBundle to be the
     // root type.  TODO(paulberry): come up with a better solution.
     idlModel.ClassDeclaration rootType = _idl.classes['PackageBundle'];
     out('root_type ${rootType.name};');
@@ skipping 109 matching lines @@
       out('bool _finished = false;');
       // Generate fields.
       out();
       for (idlModel.FieldDeclaration field in cls.fields) {
         String fieldName = field.name;
         idlModel.FieldType type = field.type;
         String typeStr = encodedType(type);
         out('$typeStr _$fieldName;');
       }
       // Generate getters and setters.
-      for (idlModel.FieldDeclaration field in cls.fields) {
+      for (idlModel.FieldDeclaration field in cls.allFields) {
         String fieldName = field.name;
         idlModel.FieldType fieldType = field.type;
         String typeStr = encodedType(fieldType);
         String def = defaultValue(fieldType, true);
         String defSuffix = def == null ? '' : ' ??= $def';
         out();
         out('@override');
-        out('$typeStr get $fieldName => _$fieldName$defSuffix;');
-        out();
-        outDoc(field.documentation);
-        constructorParams.add('$typeStr $fieldName');
-        out('void set $fieldName($typeStr _value) {');
-        indent(() {
-          String stateFieldName = '_' + fieldName;
-          out('assert(!_finished);');
-          // Validate that int(s) are non-negative.
-          if (fieldType.typeName == 'int') {
-            if (!fieldType.isList) {
-              out('assert(_value == null || _value >= 0);');
-            } else {
-              out('assert(_value == null || _value.every((e) => e >= 0));');
+        if (field.isDeprecated) {
+          out('$typeStr get $fieldName => $_throwDeprecated;');
+        } else {
+          out('$typeStr get $fieldName => _$fieldName$defSuffix;');
+          out();
+          outDoc(field.documentation);
+          constructorParams.add('$typeStr $fieldName');
+          out('void set $fieldName($typeStr _value) {');
+          indent(() {
+            String stateFieldName = '_' + fieldName;
+            out('assert(!_finished);');
+            // Validate that int(s) are non-negative.
+            if (fieldType.typeName == 'int') {
+              if (!fieldType.isList) {
+                out('assert(_value == null || _value >= 0);');
+              } else {
+                out('assert(_value == null || _value.every((e) => e >= 0));');
+              }
             }
-          }
-          // Set the value.
-          out('$stateFieldName = _value;');
-        });
-        out('}');
+            // Set the value.
+            out('$stateFieldName = _value;');
+          });
+          out('}');
+        }
       }
       // Generate constructor.
       out();
       out('$builderName({${constructorParams.join(', ')}})');
-      for (int i = 0; i < cls.fields.length; i++) {
-        idlModel.FieldDeclaration field = cls.fields[i];
+      List<idlModel.FieldDeclaration> fields = cls.fields.toList();
+      for (int i = 0; i < fields.length; i++) {
+        idlModel.FieldDeclaration field = fields[i];
         String prefix = i == 0 ? '  : ' : '    ';
-        String suffix = i == cls.fields.length - 1 ? ';' : ',';
+        String suffix = i == fields.length - 1 ? ';' : ',';
         out('${prefix}_${field.name} = ${field.name}$suffix');
       }
       // Generate finish.
       if (cls.isTopLevel) {
         out();
         out('List<int> toBuffer() {');
         indent(() {
           out('fb.Builder fbBuilder = new fb.Builder();');
           String fileId = cls.fileIdentifier == null
               ? ''
@@ skipping 134 matching lines @@
       out();
       out('$implName(this._bp);');
       out();
       // Write cache fields.
       for (idlModel.FieldDeclaration field in cls.fields) {
         String returnType = dartType(field.type);
         String fieldName = field.name;
         out('$returnType _$fieldName;');
       }
       // Write getters.
-      for (idlModel.FieldDeclaration field in cls.fields) {
+      for (idlModel.FieldDeclaration field in cls.allFields) {
         int index = field.id;
         String fieldName = field.name;
         idlModel.FieldType type = field.type;
         String typeName = type.typeName;
         // Prepare "readCode" + "def"
         String readCode;
         String def = defaultValue(type, false);
         if (type.isList) {
           if (typeName == 'int') {
             readCode = 'const fb.Uint32ListReader()';
@@ skipping 19 matching lines @@
         } else if (_idl.enums.containsKey(typeName)) {
           readCode = 'const _${typeName}Reader()';
         } else if (_idl.classes.containsKey(typeName)) {
           readCode = 'const _${typeName}Reader()';
         }
         assert(readCode != null);
         // Write the getter implementation.
         out();
         out('@override');
         String returnType = dartType(type);
-        out('$returnType get $fieldName {');
-        indent(() {
-          String readExpr = '$readCode.vTableGet(_bp, $index, $def)';
-          out('_$fieldName ??= $readExpr;');
-          out('return _$fieldName;');
-        });
-        out('}');
+        if (field.isDeprecated) {
+          out('$returnType get $fieldName => $_throwDeprecated;');
+        } else {
+          out('$returnType get $fieldName {');
+          indent(() {
+            String readExpr = '$readCode.vTableGet(_bp, $index, $def)';
+            out('_$fieldName ??= $readExpr;');
+            out('return _$fieldName;');
+          });
+          out('}');
+        }
       }
     });
     out('}');
   }
 
   void _generateMixin(idlModel.ClassDeclaration cls) {
     String name = cls.name;
     String mixinName = '_${name}Mixin';
     out('abstract class $mixinName implements ${idlPrefix(name)} {');
     indent(() {
@@ skipping 94 matching lines @@
       return token.lexeme.split('\n').map((String line) {
         if (line.startsWith(indent)) {
           line = line.substring(indent.length);
         }
         return line;
       }).join('\n');
     }
     return null;
   }
 }