Home | History | Annotate | Download | only in compiler
      1 // Protocol Buffers - Google's data interchange format
      2 // Copyright 2008 Google Inc.  All rights reserved.
      3 // http://code.google.com/p/protobuf/
      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 // This file is the public interface to the .proto file parser.
     36 
     37 #ifndef GOOGLE_PROTOBUF_COMPILER_IMPORTER_H__
     38 #define GOOGLE_PROTOBUF_COMPILER_IMPORTER_H__
     39 
     40 #include <string>
     41 #include <vector>
     42 #include <set>
     43 #include <utility>
     44 #include <google/protobuf/descriptor.h>
     45 #include <google/protobuf/descriptor_database.h>
     46 #include <google/protobuf/compiler/parser.h>
     47 
     48 namespace google {
     49 namespace protobuf {
     50 
     51 namespace io { class ZeroCopyInputStream; }
     52 
     53 namespace compiler {
     54 
     55 // Defined in this file.
     56 class Importer;
     57 class MultiFileErrorCollector;
     58 class SourceTree;
     59 class DiskSourceTree;
     60 
     61 // TODO(kenton):  Move all SourceTree stuff to a separate file?
     62 
     63 // An implementation of DescriptorDatabase which loads files from a SourceTree
     64 // and parses them.
     65 //
     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.
     73 //
     74 // Note:  This class does not implement FindFileContainingSymbol() or
     75 //   FindFileContainingExtension(); these will always return false.
     76 class LIBPROTOBUF_EXPORT SourceTreeDescriptorDatabase : public DescriptorDatabase {
     77  public:
     78   SourceTreeDescriptorDatabase(SourceTree* source_tree);
     79   ~SourceTreeDescriptorDatabase();
     80 
     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;
     87   }
     88 
     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_;
     96   }
     97 
     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,
    103                                    int field_number,
    104                                    FileDescriptorProto* output);
    105 
    106  private:
    107   class SingleFileErrorCollector;
    108 
    109   SourceTree* source_tree_;
    110   MultiFileErrorCollector* error_collector_;
    111 
    112   class LIBPROTOBUF_EXPORT ValidationErrorCollector : public DescriptorPool::ErrorCollector {
    113    public:
    114     ValidationErrorCollector(SourceTreeDescriptorDatabase* owner);
    115     ~ValidationErrorCollector();
    116 
    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);
    123 
    124    private:
    125     SourceTreeDescriptorDatabase* owner_;
    126   };
    127   friend class ValidationErrorCollector;
    128 
    129   bool using_validation_error_collector_;
    130   SourceLocationTable source_locations_;
    131   ValidationErrorCollector validation_error_collector_;
    132 };
    133 
    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.
    137 //
    138 // This is really just a thin wrapper around SourceTreeDescriptorDatabase.
    139 // You may find that SourceTreeDescriptorDatabase is more flexible.
    140 //
    141 // TODO(kenton):  I feel like this class is not well-named.
    142 class LIBPROTOBUF_EXPORT Importer {
    143  public:
    144   Importer(SourceTree* source_tree,
    145            MultiFileErrorCollector* error_collector);
    146   ~Importer();
    147 
    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.
    153   //
    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);
    162 
    163   // The DescriptorPool in which all imported FileDescriptors and their
    164   // contents are stored.
    165   inline const DescriptorPool* pool() const {
    166     return &pool_;
    167   }
    168 
    169  private:
    170   SourceTreeDescriptorDatabase database_;
    171   DescriptorPool pool_;
    172 
    173   GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(Importer);
    174 };
    175 
    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 {
    179  public:
    180   inline MultiFileErrorCollector() {}
    181   virtual ~MultiFileErrorCollector();
    182 
    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;
    187 
    188  private:
    189   GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(MultiFileErrorCollector);
    190 };
    191 
    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,
    195 // below.
    196 class LIBPROTOBUF_EXPORT SourceTree {
    197  public:
    198   inline SourceTree() {}
    199   virtual ~SourceTree();
    200 
    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;
    206 
    207  private:
    208   GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(SourceTree);
    209 };
    210 
    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 {
    215  public:
    216   DiskSourceTree();
    217   ~DiskSourceTree();
    218 
    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.
    223   //
    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");
    228   // and then you do:
    229   //   Open("bar/qux");
    230   // the DiskSourceTree will first try to open foo/bar/qux, then baz/bar/qux,
    231   // returning the first one that opens successfuly.
    232   //
    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);
    236 
    237   // Return type for DiskFileToVirtualFile().
    238   enum DiskFileToVirtualFileResult {
    239     SUCCESS,
    240     SHADOWED,
    241     CANNOT_OPEN,
    242     NO_MAPPING
    243   };
    244 
    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
    262   //   it is not useful.
    263   // * NO_MAPPING: Indicates that no mapping was found which contains this
    264   //   file.
    265   DiskFileToVirtualFileResult
    266     DiskFileToVirtualFile(const string& disk_file,
    267                           string* virtual_file,
    268                           string* shadowing_disk_file);
    269 
    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);
    274 
    275   // implements SourceTree -------------------------------------------
    276   io::ZeroCopyInputStream* Open(const string& filename);
    277 
    278  private:
    279   struct Mapping {
    280     string virtual_path;
    281     string disk_path;
    282 
    283     inline Mapping(const string& virtual_path, const string& disk_path)
    284       : virtual_path(virtual_path), disk_path(disk_path) {}
    285   };
    286   vector<Mapping> mappings_;
    287 
    288   // Like Open(), but returns the on-disk path in disk_file if disk_file is
    289   // non-NULL and the file could be successfully opened.
    290   io::ZeroCopyInputStream* OpenVirtualFile(const string& virtual_file,
    291                                            string* disk_file);
    292 
    293   // Like Open() but given the actual on-disk path.
    294   io::ZeroCopyInputStream* OpenDiskFile(const string& filename);
    295 
    296   GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(DiskSourceTree);
    297 };
    298 
    299 }  // namespace compiler
    300 }  // namespace protobuf
    301 
    302 }  // namespace google
    303 #endif  // GOOGLE_PROTOBUF_COMPILER_IMPORTER_H__
    304