importer.h

This section contains reference documentation for working with protocol buffer classes in C++.

#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

An implementation of DescriptorDatabase which loads files from a SourceTree and parses them.
Simple interface for parsing .proto files.
If the importer encounters problems while trying to import the proto files, it reports them to a MultiFileErrorCollector.
Abstract interface which represents a directory tree containing proto files.
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 a DescriptorDatabase, 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(SourceTree * source_tree, DescriptorDatabase * fallback_database)
If non-NULL, fallback_database will be checked if a file doesn't exist in the specified 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 std::string & filename, FileDescriptorProto * output)
Find a file by file name. more...
virtual bool
FindFileContainingSymbol(const std::string & symbol_name, FileDescriptorProto * output)
Find the file that declares the given fully-qualified symbol name. more...
virtual bool
FindFileContainingExtension(const std::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 the SourceTreeDescriptorDatabase 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 std::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 std::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 std::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 a FileDescriptor.

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

Members

Importer(SourceTree * source_tree, MultiFileErrorCollector * error_collector)
~Importer()
const FileDescriptor *
Import(const std::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.
void
AddUnusedImportTrackFile(const std::string & file_name, bool is_error = false)
void
ClearUnusedImportTrackFiles()

const FileDescriptor *
    Importer::Import(
        const std::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 std::string & filename, int line, int column, const std::string & message) = 0
Line and column numbers are zero-based. more...
virtual void
AddWarning(const std::string & , int , int , const std::string & )

virtual void MultiFileErrorCollector::AddError(
        const std::string & filename,
        int line,
        int column,
        const std::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 DiskSourceTree implementation, below.

Known subclasses:

Members

SourceTree()
virtual
~SourceTree()
virtual io::ZeroCopyInputStream *
Open(const std::string & filename) = 0
Open the given file and return a stream that reads it, or NULL if not found. more...
virtual std::string
GetLastErrorMessage()
If Open() returns NULL, calling this method immediately will return an description of the error. more...

virtual io::ZeroCopyInputStream *
    SourceTree::Open(
        const std::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.

virtual std::string SourceTree::GetLastErrorMessage()

If Open() returns NULL, calling this method immediately will return an description of the error.

Subclasses should implement this method and return a meaningful value for better error reporting.

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
DiskSourceTree()
~DiskSourceTree()
void
MapPath(const std::string & virtual_path, const std::string & disk_path)
Map a path on disk to a location in the SourceTree. more...
DiskFileToVirtualFileResult
DiskFileToVirtualFile(const std::string & disk_file, std::string * virtual_file, std::string * shadowing_disk_file)
Given a path to a file on disk, find a virtual path mapping to that file. more...
bool
VirtualFileToDiskFile(const std::string & virtual_file, std::string * disk_file)
Given a virtual path, find the path to the file on disk. more...

implements SourceTree

virtual io::ZeroCopyInputStream *
Open(const std::string & filename)
Open the given file and return a stream that reads it, or NULL if not found. more...
virtual std::string
GetLastErrorMessage()
If Open() returns NULL, calling this method immediately will return an description of the error. more...

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

Return type for DiskFileToVirtualFile().

SUCCESS
SHADOWED
CANNOT_OPEN
NO_MAPPING

void DiskSourceTree::MapPath(
        const std::string & virtual_path,
        const std::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 successfully.

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 std::string & disk_file,
        std::string * virtual_file,
        std::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 std::string & virtual_file,
        std::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 std::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.

virtual std::string DiskSourceTree::GetLastErrorMessage()

If Open() returns NULL, calling this method immediately will return an description of the error.

Subclasses should implement this method and return a meaningful value for better error reporting.