1 // Protocol Buffers - Google's data interchange format 2 // Copyright 2008 Google Inc. All rights reserved. 3 // https://developers.google.com/protocol-buffers/ 4 // 5 // Redistribution and use in source and binary forms, with or without 6 // modification, are permitted provided that the following conditions are 7 // met: 8 // 9 // * Redistributions of source code must retain the above copyright 10 // notice, this list of conditions and the following disclaimer. 11 // * Redistributions in binary form must reproduce the above 12 // copyright notice, this list of conditions and the following disclaimer 13 // in the documentation and/or other materials provided with the 14 // distribution. 15 // * Neither the name of Google Inc. nor the names of its 16 // contributors may be used to endorse or promote products derived from 17 // this software without specific prior written permission. 18 // 19 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 22 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 23 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 24 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 25 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 29 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 31 // Author: kenton (at) google.com (Kenton Varda) 32 // Based on original Protocol Buffers design by 33 // Sanjay Ghemawat, Jeff Dean, and others. 34 // 35 // Defines the abstract interface implemented by each of the language-specific 36 // code generators. 37 38 #ifndef GOOGLE_PROTOBUF_COMPILER_CODE_GENERATOR_H__ 39 #define GOOGLE_PROTOBUF_COMPILER_CODE_GENERATOR_H__ 40 41 #include <google/protobuf/stubs/common.h> 42 #include <string> 43 #include <vector> 44 #include <utility> 45 46 namespace google { 47 namespace protobuf { 48 49 namespace io { class ZeroCopyOutputStream; } 50 class FileDescriptor; 51 52 namespace compiler { 53 54 // Defined in this file. 55 class CodeGenerator; 56 class GeneratorContext; 57 58 // The abstract interface to a class which generates code implementing a 59 // particular proto file in a particular language. A number of these may 60 // be registered with CommandLineInterface to support various languages. 61 class LIBPROTOC_EXPORT CodeGenerator { 62 public: 63 inline CodeGenerator() {} 64 virtual ~CodeGenerator(); 65 66 // Generates code for the given proto file, generating one or more files in 67 // the given output directory. 68 // 69 // A parameter to be passed to the generator can be specified on the 70 // command line. This is intended to be used by Java and similar languages 71 // to specify which specific class from the proto file is to be generated, 72 // though it could have other uses as well. It is empty if no parameter was 73 // given. 74 // 75 // Returns true if successful. Otherwise, sets *error to a description of 76 // the problem (e.g. "invalid parameter") and returns false. 77 virtual bool Generate(const FileDescriptor* file, 78 const string& parameter, 79 GeneratorContext* generator_context, 80 string* error) const = 0; 81 82 // Generates code for all given proto files, generating one or more files in 83 // the given output directory. 84 // 85 // This method should be called instead of |Generate()| when 86 // |HasGenerateAll()| returns |true|. It is used to emulate legacy semantics 87 // when more than one `.proto` file is specified on one compiler invocation. 88 // 89 // WARNING: Please do not use unless legacy semantics force the code generator 90 // to produce a single output file for all input files, or otherwise require 91 // an examination of all input files first. The canonical code generator 92 // design produces one output file per input .proto file, and we do not wish 93 // to encourage alternate designs. 94 // 95 // A parameter is given as passed on the command line, as in |Generate()| 96 // above. 97 // 98 // Returns true if successful. Otherwise, sets *error to a description of 99 // the problem (e.g. "invalid parameter") and returns false. 100 virtual bool GenerateAll(const vector<const FileDescriptor*>& files, 101 const string& parameter, 102 GeneratorContext* generator_context, 103 string* error) const { 104 *error = "Unimplemented GenerateAll() method."; 105 return false; 106 } 107 108 // Returns true if the code generator expects to receive all FileDescriptors 109 // at once (via |GenerateAll()|), rather than one at a time (via 110 // |Generate()|). This is required to implement legacy semantics. 111 virtual bool HasGenerateAll() const { return false; } 112 113 private: 114 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(CodeGenerator); 115 }; 116 117 // CodeGenerators generate one or more files in a given directory. This 118 // abstract interface represents the directory to which the CodeGenerator is 119 // to write and other information about the context in which the Generator 120 // runs. 121 class LIBPROTOC_EXPORT GeneratorContext { 122 public: 123 inline GeneratorContext() {} 124 virtual ~GeneratorContext(); 125 126 // Opens the given file, truncating it if it exists, and returns a 127 // ZeroCopyOutputStream that writes to the file. The caller takes ownership 128 // of the returned object. This method never fails (a dummy stream will be 129 // returned instead). 130 // 131 // The filename given should be relative to the root of the source tree. 132 // E.g. the C++ generator, when generating code for "foo/bar.proto", will 133 // generate the files "foo/bar.pb.h" and "foo/bar.pb.cc"; note that 134 // "foo/" is included in these filenames. The filename is not allowed to 135 // contain "." or ".." components. 136 virtual io::ZeroCopyOutputStream* Open(const string& filename) = 0; 137 138 // Similar to Open() but the output will be appended to the file if exists 139 virtual io::ZeroCopyOutputStream* OpenForAppend(const string& filename); 140 141 // Creates a ZeroCopyOutputStream which will insert code into the given file 142 // at the given insertion point. See plugin.proto (plugin.pb.h) for more 143 // information on insertion points. The default implementation 144 // assert-fails -- it exists only for backwards-compatibility. 145 // 146 // WARNING: This feature is currently EXPERIMENTAL and is subject to change. 147 virtual io::ZeroCopyOutputStream* OpenForInsert( 148 const string& filename, const string& insertion_point); 149 150 // Returns a vector of FileDescriptors for all the files being compiled 151 // in this run. Useful for languages, such as Go, that treat files 152 // differently when compiled as a set rather than individually. 153 virtual void ListParsedFiles(vector<const FileDescriptor*>* output); 154 155 private: 156 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(GeneratorContext); 157 }; 158 159 // The type GeneratorContext was once called OutputDirectory. This typedef 160 // provides backward compatibility. 161 typedef GeneratorContext OutputDirectory; 162 163 // Several code generators treat the parameter argument as holding a 164 // list of options separated by commas. This helper function parses 165 // a set of comma-delimited name/value pairs: e.g., 166 // "foo=bar,baz,qux=corge" 167 // parses to the pairs: 168 // ("foo", "bar"), ("baz", ""), ("qux", "corge") 169 extern void ParseGeneratorParameter(const string&, 170 vector<pair<string, string> >*); 171 172 } // namespace compiler 173 } // namespace protobuf 174 175 } // namespace google 176 #endif // GOOGLE_PROTOBUF_COMPILER_CODE_GENERATOR_H__ 177
