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@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 <string> 42 #include <utility> 43 #include <vector> 44 #include <google/protobuf/stubs/common.h> 45 46 #include <google/protobuf/port_def.inc> 47 48 namespace google { 49 namespace protobuf { 50 51 namespace io { 52 class ZeroCopyOutputStream; 53 } 54 class FileDescriptor; 55 56 namespace compiler { 57 class AccessInfoMap; 58 59 class Version; 60 61 // Defined in this file. 62 class CodeGenerator; 63 class GeneratorContext; 64 65 // The abstract interface to a class which generates code implementing a 66 // particular proto file in a particular language. A number of these may 67 // be registered with CommandLineInterface to support various languages. 68 class PROTOC_EXPORT CodeGenerator { 69 public: CodeGenerator()70 inline CodeGenerator() {} 71 virtual ~CodeGenerator(); 72 73 // Generates code for the given proto file, generating one or more files in 74 // the given output directory. 75 // 76 // A parameter to be passed to the generator can be specified on the command 77 // line. This is intended to be used to pass generator specific parameters. 78 // It is empty if no parameter was given. ParseGeneratorParameter (below), 79 // can be used to accept multiple parameters within the single parameter 80 // command line flag. 81 // 82 // Returns true if successful. Otherwise, sets *error to a description of 83 // the problem (e.g. "invalid parameter") and returns false. 84 virtual bool Generate(const FileDescriptor* file, 85 const std::string& parameter, 86 GeneratorContext* generator_context, 87 std::string* error) const = 0; 88 89 // Generates code for all given proto files. 90 // 91 // WARNING: The canonical code generator design produces one or two output 92 // files per input .proto file, and we do not wish to encourage alternate 93 // 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 std::vector<const FileDescriptor*>& files, 101 const std::string& parameter, 102 GeneratorContext* generator_context, 103 std::string* error) const; 104 105 // This is no longer used, but this class is part of the opensource protobuf 106 // library, so it has to remain to keep vtables the same for the current 107 // version of the library. When protobufs does a api breaking change, the 108 // method can be removed. HasGenerateAll()109 virtual bool HasGenerateAll() const { return true; } 110 111 private: 112 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(CodeGenerator); 113 }; 114 115 // CodeGenerators generate one or more files in a given directory. This 116 // abstract interface represents the directory to which the CodeGenerator is 117 // to write and other information about the context in which the Generator 118 // runs. 119 class PROTOC_EXPORT GeneratorContext { 120 public: GeneratorContext()121 inline GeneratorContext() { 122 } 123 virtual ~GeneratorContext(); 124 125 // Opens the given file, truncating it if it exists, and returns a 126 // ZeroCopyOutputStream that writes to the file. The caller takes ownership 127 // of the returned object. This method never fails (a dummy stream will be 128 // returned instead). 129 // 130 // The filename given should be relative to the root of the source tree. 131 // E.g. the C++ generator, when generating code for "foo/bar.proto", will 132 // generate the files "foo/bar.pb.h" and "foo/bar.pb.cc"; note that 133 // "foo/" is included in these filenames. The filename is not allowed to 134 // contain "." or ".." components. 135 virtual io::ZeroCopyOutputStream* Open(const std::string& filename) = 0; 136 137 // Similar to Open() but the output will be appended to the file if exists 138 virtual io::ZeroCopyOutputStream* OpenForAppend(const std::string& filename); 139 140 // Creates a ZeroCopyOutputStream which will insert code into the given file 141 // at the given insertion point. See plugin.proto (plugin.pb.h) for more 142 // information on insertion points. The default implementation 143 // assert-fails -- it exists only for backwards-compatibility. 144 // 145 // WARNING: This feature is currently EXPERIMENTAL and is subject to change. 146 virtual io::ZeroCopyOutputStream* OpenForInsert( 147 const std::string& filename, const std::string& insertion_point); 148 149 // Returns a vector of FileDescriptors for all the files being compiled 150 // in this run. Useful for languages, such as Go, that treat files 151 // differently when compiled as a set rather than individually. 152 virtual void ListParsedFiles(std::vector<const FileDescriptor*>* output); 153 154 // Retrieves the version number of the protocol compiler associated with 155 // this GeneratorContext. 156 virtual void GetCompilerVersion(Version* version) const; 157 158 159 private: 160 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(GeneratorContext); 161 }; 162 163 // The type GeneratorContext was once called OutputDirectory. This typedef 164 // provides backward compatibility. 165 typedef GeneratorContext OutputDirectory; 166 167 // Several code generators treat the parameter argument as holding a 168 // list of options separated by commas. This helper function parses 169 // a set of comma-delimited name/value pairs: e.g., 170 // "foo=bar,baz,qux=corge" 171 // parses to the pairs: 172 // ("foo", "bar"), ("baz", ""), ("qux", "corge") 173 PROTOC_EXPORT void ParseGeneratorParameter( 174 const std::string&, std::vector<std::pair<std::string, std::string> >*); 175 176 } // namespace compiler 177 } // namespace protobuf 178 } // namespace google 179 180 #include <google/protobuf/port_undef.inc> 181 182 #endif // GOOGLE_PROTOBUF_COMPILER_CODE_GENERATOR_H__ 183