Line data Source code
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 <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 127 : 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 0 : virtual bool GenerateAll(const vector<const FileDescriptor*>& files,
101 : const string& parameter,
102 : GeneratorContext* generator_context,
103 : string* error) const {
104 0 : *error = "Unimplemented GenerateAll() method.";
105 0 : 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 17 : 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 25 : 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__
|
