importer.h

importer.h

#include <google/protobuf/compiler/importer.h>
namespace google::protobuf::compiler

This file is the public interface to the .proto file parser.

Classes in this file
SourceTreeDescriptorDatabase An implementation of  DescriptorDatabase which loads files from a  SourceTree and parses them.
Importer Simple interface for parsing .proto files.
MultiFileErrorCollector If the importer encounters problems while trying to import the proto files, it reports them to a  MultiFileErrorCollector.
SourceTree Abstract interface which represents a directory tree containing proto files.
DiskSourceTree An implementation of  SourceTree which loads files from locations on disk.

class SourceTreeDescriptorDatabase: public DescriptorDatabase

#include <google/protobuf/compiler/importer.h>
namespace google::protobuf::compiler

An implementation of DescriptorDatabase which loads files from a SourceTree and parses them.

Note: This class is not thread-safe since it maintains a table of source code locations for error reporting. However, when a DescriptorPool wraps aDescriptorDatabase, it uses mutex locking to make sure only one method of the database is called at a time, even if the DescriptorPool is used from multiple threads. Therefore, there is only a problem if you create multiple DescriptorPools wrapping the same SourceTreeDescriptorDatabase and use them from multiple threads.

Note: This class does not implement FindFileContainingSymbol() or FindFileContainingExtension(); these will always return false.

Members
	SourceTreeDescriptorDatabase(SourceTree * source_tree)
	~SourceTreeDescriptorDatabase()
void	RecordErrorsTo(MultiFileErrorCollector * error_collector) Instructs the  SourceTreeDescriptorDatabase to report any parse errors to the given  MultiFileErrorCollector. more...
DescriptorPool::ErrorCollector*	GetValidationErrorCollector() Gets a  DescriptorPool::ErrorCollector which records errors to the  MultiFileErrorCollector specified with RecordErrorsTo().  more...
implements DescriptorDatabase
virtual bool	FindFileByName(const string & filename, FileDescriptorProto * output) Find a file by file name.  more...
virtual bool	FindFileContainingSymbol(const string & symbol_name, FileDescriptorProto * output) Find the file that declares the given fully-qualified symbol name.  more...
virtual bool	FindFileContainingExtension(const string & containing_type, int field_number,FileDescriptorProto * output) Find the file which defines an extension extending the given message type with the given field number. more...

---

void SourceTreeDescriptorDatabase::RecordErrorsTo(
        MultiFileErrorCollector * error_collector)

Instructs the SourceTreeDescriptorDatabase to report any parse errors to the given MultiFileErrorCollector.

This should be called before parsing. error_collector must remain valid until either this method is called again or theSourceTreeDescriptorDatabase is destroyed.

---

DescriptorPool::ErrorCollector * 
    SourceTreeDescriptorDatabase::GetValidationErrorCollector()

Gets a DescriptorPool::ErrorCollector which records errors to the MultiFileErrorCollector specified with RecordErrorsTo().

This collector has the ability to determine exact line and column numbers of errors from the information given to it by the DescriptorPool.

---

virtual bool SourceTreeDescriptorDatabase::FindFileByName(
        const string & filename,
        FileDescriptorProto * output)

Find a file by file name.

Fills in in *output and returns true if found. Otherwise, returns false, leaving the contents of *output undefined.

---

virtual bool SourceTreeDescriptorDatabase::FindFileContainingSymbol(
        const string & symbol_name,
        FileDescriptorProto * output)

Find the file that declares the given fully-qualified symbol name.

If found, fills in *output and returns true, otherwise returns false and leaves *output undefined.

---

virtual bool SourceTreeDescriptorDatabase::FindFileContainingExtension(
        const string & containing_type,
        int field_number,
        FileDescriptorProto * output)

Find the file which defines an extension extending the given message type with the given field number.

If found, fills in *output and returns true, otherwise returns false and leaves *output undefined. containing_type must be a fully-qualified type name.

class Importer

#include <google/protobuf/compiler/importer.h>
namespace google::protobuf::compiler

Simple interface for parsing .proto files.

This wraps the process of opening the file, parsing it with a Parser, recursively parsing all its imports, and then cross-linking the results to produce aFileDescriptor.

This is really just a thin wrapper around SourceTreeDescriptorDatabase. You may find that SourceTreeDescriptorDatabase is more flexible.

TODO(kenton): I feel like this class is not well-named.

Members
	Importer(SourceTree * source_tree, MultiFileErrorCollector * error_collector)
	~Importer()
const FileDescriptor *	Import(const string & filename) Import the given file and build a  FileDescriptor representing it.  more...
const DescriptorPool *	pool() const The  DescriptorPool in which all imported FileDescriptors and their contents are stored.

---

const FileDescriptor * 
    Importer::Import(
        const string & filename)

Import the given file and build a FileDescriptor representing it.

If the file is already in the DescriptorPool, the existing FileDescriptor will be returned. The FileDescriptor is property of the DescriptorPool, and will remain valid until it is destroyed. If any errors occur, they will be reported using the error collector and Import() will return NULL.

A particular Importer object will only report errors for a particular file once. All future attempts to import the same file will return NULL without reporting any errors. The idea is that you might want to import a lot of files without seeing the same errors over and over again. If you want to see errors for the same files repeatedly, you can use a separate Importer object to import each one (but use the same DescriptorPool so that they can be cross-linked).

class MultiFileErrorCollector

#include <google/protobuf/compiler/importer.h>
namespace google::protobuf::compiler

If the importer encounters problems while trying to import the proto files, it reports them to a MultiFileErrorCollector.

Members
	MultiFileErrorCollector()
virtual	~MultiFileErrorCollector()
virtual void	AddError(const string & filename, int line, int column, const string & message) = 0 Line and column numbers are zero-based.  more...

---

virtual void MultiFileErrorCollector::AddError(
        const string & filename,
        int line,
        int column,
        const string & message) = 0

Line and column numbers are zero-based.

A line number of -1 indicates an error with the entire file (e.g. "not found").

class SourceTree

#include <google/protobuf/compiler/importer.h>
namespace google::protobuf::compiler

Abstract interface which represents a directory tree containing proto files.

Used by the default implementation of Importer to resolve import statements Most users will probably want to use the DiskSourceTreeimplementation, below.

Known subclasses:

• DiskSourceTree

Members
	SourceTree()
virtual	~SourceTree()
virtual io::ZeroCopyInputStream *	Open(const string & filename) = 0 Open the given file and return a stream that reads it, or NULL if not found.  more...

---

virtual io::ZeroCopyInputStream * 
    SourceTree::Open(
        const string & filename) = 0

Open the given file and return a stream that reads it, or NULL if not found.

The caller takes ownership of the returned object. The filename must be a path relative to the root of the source tree and must not contain "." or ".." components.

class DiskSourceTree: public SourceTree

#include <google/protobuf/compiler/importer.h>
namespace google::protobuf::compiler

An implementation of SourceTree which loads files from locations on disk.

Multiple mappings can be set up to map locations in the DiskSourceTree to locations in the physical filesystem.

Members
enum	DiskFileToVirtualFileResult Return type for  DiskFileToVirtualFile().  more...
	DiskSourceTree()
	~DiskSourceTree()
void	MapPath(const string & virtual_path, const string & disk_path) Map a path on disk to a location in the  SourceTree.  more...
DiskFileToVirtualFileResult	DiskFileToVirtualFile(const string & disk_file, string * virtual_file, string * shadowing_disk_file) Given a path to a file on disk, find a virtual path mapping to that file.  more...
bool	VirtualFileToDiskFile(const string & virtual_file, string * disk_file) Given a virtual path, find the path to the file on disk.  more...
implements SourceTree
virtualio::ZeroCopyInputStream *	Open(const string & filename) Open the given file and return a stream that reads it, or NULL if not found.  more...

---

enum DiskSourceTree::DiskFileToVirtualFileResult {
  SUCCESS,
  SHADOWED,
  CANNOT_OPEN,
  NO_MAPPING
}

Return type for DiskFileToVirtualFile().

SUCCESS
SHADOWED
CANNOT_OPEN
NO_MAPPING

---

void DiskSourceTree::MapPath(
        const string & virtual_path,
        const string & disk_path)

Map a path on disk to a location in the SourceTree.

The path may be either a file or a directory. If it is a directory, the entire tree under it will be mapped to the given virtual location. To map a directory to the root of the source tree, pass an empty string for virtual_path.

If multiple mapped paths apply when opening a file, they will be searched in order. For example, if you do:

MapPath("bar", "foo/bar");
MapPath("", "baz");

and then you do:

Open("bar/qux");

the DiskSourceTree will first try to open foo/bar/qux, then baz/bar/qux, returning the first one that opens successfuly.

disk_path may be an absolute path or relative to the current directory, just like a path you'd pass to open().

---

DiskFileToVirtualFileResult 
    DiskSourceTree::DiskFileToVirtualFile(
        const string & disk_file,
        string * virtual_file,
        string * shadowing_disk_file)

Given a path to a file on disk, find a virtual path mapping to that file.

The first mapping created with MapPath() whose disk_path contains the filename is used. However, that virtual path may not actually be usable to open the given file. Possible return values are:

• SUCCESS: The mapping was found. *virtual_file is filled in so that calling Open(*virtual_file) will open the file named by disk_file.
• SHADOWED: A mapping was found, but using Open() to open this virtual path will end up returning some different file. This is because some other mapping with a higher precedence also matches this virtual path and maps it to a different file that exists on disk. *virtual_file is filled in as it would be in the SUCCESS case. *shadowing_disk_file is filled in with the disk path of the file which would be opened if you were to call Open(*virtual_file).
• CANNOT_OPEN: The mapping was found and was not shadowed, but the file specified cannot be opened. When this value is returned, errno will indicate the reason the file cannot be opened. *virtual_file will be set to the virtual path as in the SUCCESS case, even though it is not useful.
• NO_MAPPING: Indicates that no mapping was found which contains this file.

---

bool DiskSourceTree::VirtualFileToDiskFile(
        const string & virtual_file,
        string * disk_file)

Given a virtual path, find the path to the file on disk.

Return true and update disk_file with the on-disk path if the file exists. Return false and leave disk_file untouched if the file doesn't exist.

---

virtual io::ZeroCopyInputStream * 
    DiskSourceTree::Open(
        const string & filename)

Open the given file and return a stream that reads it, or NULL if not found.

The caller takes ownership of the returned object. The filename must be a path relative to the root of the source tree and must not contain "." or ".." components.