1 // Protocol Buffers - Google's data interchange format
2 // Copyright 2008 Google Inc. All rights reserved.
3 // http://code.google.com/p/protobuf/
5 // Redistribution and use in source and binary forms, with or without
6 // modification, are permitted provided that the following conditions are
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
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.
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.
31 // Author: kenton@google.com (Kenton Varda)
32 // Based on original Protocol Buffers design by
33 // Sanjay Ghemawat, Jeff Dean, and others.
35 // This file is the public interface to the .proto file parser.
37 #ifndef GOOGLE_PROTOBUF_COMPILER_IMPORTER_H__
38 #define GOOGLE_PROTOBUF_COMPILER_IMPORTER_H__
44 #include <google/protobuf/descriptor.h>
45 #include <google/protobuf/descriptor_database.h>
46 #include <google/protobuf/compiler/parser.h>
51 namespace io { class ZeroCopyInputStream; }
55 // Defined in this file.
57 class MultiFileErrorCollector;
61 // TODO(kenton): Move all SourceTree stuff to a separate file?
63 // An implementation of DescriptorDatabase which loads files from a SourceTree
66 // Note: This class is not thread-safe since it maintains a table of source
67 // code locations for error reporting. However, when a DescriptorPool wraps
68 // a DescriptorDatabase, it uses mutex locking to make sure only one method
69 // of the database is called at a time, even if the DescriptorPool is used
70 // from multiple threads. Therefore, there is only a problem if you create
71 // multiple DescriptorPools wrapping the same SourceTreeDescriptorDatabase
72 // and use them from multiple threads.
74 // Note: This class does not implement FindFileContainingSymbol() or
75 // FindFileContainingExtension(); these will always return false.
76 class LIBPROTOBUF_EXPORT SourceTreeDescriptorDatabase : public DescriptorDatabase {
78 SourceTreeDescriptorDatabase(SourceTree* source_tree);
79 ~SourceTreeDescriptorDatabase();
81 // Instructs the SourceTreeDescriptorDatabase to report any parse errors
82 // to the given MultiFileErrorCollector. This should be called before
83 // parsing. error_collector must remain valid until either this method
84 // is called again or the SourceTreeDescriptorDatabase is destroyed.
85 void RecordErrorsTo(MultiFileErrorCollector* error_collector) {
86 error_collector_ = error_collector;
89 // Gets a DescriptorPool::ErrorCollector which records errors to the
90 // MultiFileErrorCollector specified with RecordErrorsTo(). This collector
91 // has the ability to determine exact line and column numbers of errors
92 // from the information given to it by the DescriptorPool.
93 DescriptorPool::ErrorCollector* GetValidationErrorCollector() {
94 using_validation_error_collector_ = true;
95 return &validation_error_collector_;
98 // implements DescriptorDatabase -----------------------------------
99 bool FindFileByName(const string& filename, FileDescriptorProto* output);
100 bool FindFileContainingSymbol(const string& symbol_name,
101 FileDescriptorProto* output);
102 bool FindFileContainingExtension(const string& containing_type,
104 FileDescriptorProto* output);
107 class SingleFileErrorCollector;
109 SourceTree* source_tree_;
110 MultiFileErrorCollector* error_collector_;
112 class LIBPROTOBUF_EXPORT ValidationErrorCollector : public DescriptorPool::ErrorCollector {
114 ValidationErrorCollector(SourceTreeDescriptorDatabase* owner);
115 ~ValidationErrorCollector();
117 // implements ErrorCollector ---------------------------------------
118 void AddError(const string& filename,
119 const string& element_name,
120 const Message* descriptor,
121 ErrorLocation location,
122 const string& message);
125 SourceTreeDescriptorDatabase* owner_;
127 friend class ValidationErrorCollector;
129 bool using_validation_error_collector_;
130 SourceLocationTable source_locations_;
131 ValidationErrorCollector validation_error_collector_;
134 // Simple interface for parsing .proto files. This wraps the process
135 // of opening the file, parsing it with a Parser, recursively parsing all its
136 // imports, and then cross-linking the results to produce a FileDescriptor.
138 // This is really just a thin wrapper around SourceTreeDescriptorDatabase.
139 // You may find that SourceTreeDescriptorDatabase is more flexible.
141 // TODO(kenton): I feel like this class is not well-named.
142 class LIBPROTOBUF_EXPORT Importer {
144 Importer(SourceTree* source_tree,
145 MultiFileErrorCollector* error_collector);
148 // Import the given file and build a FileDescriptor representing it. If
149 // the file is already in the DescriptorPool, the existing FileDescriptor
150 // will be returned. The FileDescriptor is property of the DescriptorPool,
151 // and will remain valid until it is destroyed. If any errors occur, they
152 // will be reported using the error collector and Import() will return NULL.
154 // A particular Importer object will only report errors for a particular
155 // file once. All future attempts to import the same file will return NULL
156 // without reporting any errors. The idea is that you might want to import
157 // a lot of files without seeing the same errors over and over again. If
158 // you want to see errors for the same files repeatedly, you can use a
159 // separate Importer object to import each one (but use the same
160 // DescriptorPool so that they can be cross-linked).
161 const FileDescriptor* Import(const string& filename);
163 // The DescriptorPool in which all imported FileDescriptors and their
164 // contents are stored.
165 inline const DescriptorPool* pool() const {
170 SourceTreeDescriptorDatabase database_;
171 DescriptorPool pool_;
173 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(Importer);
176 // If the importer encounters problems while trying to import the proto files,
177 // it reports them to a MultiFileErrorCollector.
178 class LIBPROTOBUF_EXPORT MultiFileErrorCollector {
180 inline MultiFileErrorCollector() {}
181 virtual ~MultiFileErrorCollector();
183 // Line and column numbers are zero-based. A line number of -1 indicates
184 // an error with the entire file (e.g. "not found").
185 virtual void AddError(const string& filename, int line, int column,
186 const string& message) = 0;
189 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(MultiFileErrorCollector);
192 // Abstract interface which represents a directory tree containing proto files.
193 // Used by the default implementation of Importer to resolve import statements
194 // Most users will probably want to use the DiskSourceTree implementation,
196 class LIBPROTOBUF_EXPORT SourceTree {
198 inline SourceTree() {}
199 virtual ~SourceTree();
201 // Open the given file and return a stream that reads it, or NULL if not
202 // found. The caller takes ownership of the returned object. The filename
203 // must be a path relative to the root of the source tree and must not
204 // contain "." or ".." components.
205 virtual io::ZeroCopyInputStream* Open(const string& filename) = 0;
208 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(SourceTree);
211 // An implementation of SourceTree which loads files from locations on disk.
212 // Multiple mappings can be set up to map locations in the DiskSourceTree to
213 // locations in the physical filesystem.
214 class LIBPROTOBUF_EXPORT DiskSourceTree : public SourceTree {
219 // Map a path on disk to a location in the SourceTree. The path may be
220 // either a file or a directory. If it is a directory, the entire tree
221 // under it will be mapped to the given virtual location. To map a directory
222 // to the root of the source tree, pass an empty string for virtual_path.
224 // If multiple mapped paths apply when opening a file, they will be searched
225 // in order. For example, if you do:
226 // MapPath("bar", "foo/bar");
227 // MapPath("", "baz");
230 // the DiskSourceTree will first try to open foo/bar/qux, then baz/bar/qux,
231 // returning the first one that opens successfuly.
233 // disk_path may be an absolute path or relative to the current directory,
234 // just like a path you'd pass to open().
235 void MapPath(const string& virtual_path, const string& disk_path);
237 // Return type for DiskFileToVirtualFile().
238 enum DiskFileToVirtualFileResult {
245 // Given a path to a file on disk, find a virtual path mapping to that
246 // file. The first mapping created with MapPath() whose disk_path contains
247 // the filename is used. However, that virtual path may not actually be
248 // usable to open the given file. Possible return values are:
249 // * SUCCESS: The mapping was found. *virtual_file is filled in so that
250 // calling Open(*virtual_file) will open the file named by disk_file.
251 // * SHADOWED: A mapping was found, but using Open() to open this virtual
252 // path will end up returning some different file. This is because some
253 // other mapping with a higher precedence also matches this virtual path
254 // and maps it to a different file that exists on disk. *virtual_file
255 // is filled in as it would be in the SUCCESS case. *shadowing_disk_file
256 // is filled in with the disk path of the file which would be opened if
257 // you were to call Open(*virtual_file).
258 // * CANNOT_OPEN: The mapping was found and was not shadowed, but the
259 // file specified cannot be opened. When this value is returned,
260 // errno will indicate the reason the file cannot be opened. *virtual_file
261 // will be set to the virtual path as in the SUCCESS case, even though
263 // * NO_MAPPING: Indicates that no mapping was found which contains this
265 DiskFileToVirtualFileResult
266 DiskFileToVirtualFile(const string& disk_file,
267 string* virtual_file,
268 string* shadowing_disk_file);
270 // Given a virtual path, find the path to the file on disk.
271 // Return true and update disk_file with the on-disk path if the file exists.
272 // Return false and leave disk_file untouched if the file doesn't exist.
273 bool VirtualFileToDiskFile(const string& virtual_file, string* disk_file);
275 // implements SourceTree -------------------------------------------
276 io::ZeroCopyInputStream* Open(const string& filename);
283 inline Mapping(const string& virtual_path_param,
284 const string& disk_path_param)
285 : virtual_path(virtual_path_param), disk_path(disk_path_param) {}
287 vector<Mapping> mappings_;
289 // Like Open(), but returns the on-disk path in disk_file if disk_file is
290 // non-NULL and the file could be successfully opened.
291 io::ZeroCopyInputStream* OpenVirtualFile(const string& virtual_file,
294 // Like Open() but given the actual on-disk path.
295 io::ZeroCopyInputStream* OpenDiskFile(const string& filename);
297 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(DiskSourceTree);
300 } // namespace compiler
301 } // namespace protobuf
303 } // namespace google
304 #endif // GOOGLE_PROTOBUF_COMPILER_IMPORTER_H__