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

#include <google/protobuf/text_format.h>
namespace google::protobuf

Utilities for printing and parsing protocol messages in a human-readable, text-based format.

Classes in this file

This class implements protocol buffer text format, colloquially known as text proto.

The default printer that converts scalar values from fields into their string representation.

Deprecated: please use FastFieldValuePrinter instead.

Interface that Printers or Parsers can use to find extensions, or types referenced in Any messages.

Data structure which is populated with the locations of each field value parsed from the text.

A location in the parsed text.

For more control over parsing, use this class.

Class for those users which require more fine-grained control over how a protobuffer message is printed out.

class TextFormat

#include <google/protobuf/text_format.h>
namespace google::protobuf

This class implements protocol buffer text format, colloquially known as text proto.

Printing and parsing protocol messages in text format is useful for debugging and human editing of messages.

This class is really a namespace that contains only static methods.

Members

static bool

Print(const Message & message, io::ZeroCopyOutputStream * output)

Outputs a textual representation of the given message to the given output stream. more...

static bool

PrintUnknownFields(const UnknownFieldSet & unknown_fields, io::ZeroCopyOutputStream * output)

Print the fields in an UnknownFieldSet. more...

static bool

PrintToString(const Message & message, std::string * output)

Like Print(), but outputs directly to a string. more...

static bool

PrintUnknownFieldsToString(const UnknownFieldSet & unknown_fields, std::string * output)

Like PrintUnknownFields(), but outputs directly to a string. more...

static void

PrintFieldValueToString(const Message & message, const FieldDescriptor * field, int index, std::string * output)

Outputs a textual representation of the value of the field supplied on the message supplied. more...

static bool

Parse(io::ZeroCopyInputStream * input, Message * output)

Parses a text-format protocol message from the given input stream to the given message object. more...

static bool

ParseFromString(ConstStringParam input, Message * output)

Like Parse(), but reads directly from a string.

static bool

Merge(io::ZeroCopyInputStream * input, Message * output)

Like Parse(), but the data is merged into the given message, as if using Message::MergeFrom().

static bool

MergeFromString(ConstStringParam input, Message * output)

Like Merge(), but reads directly from a string.

static bool

ParseFieldValueFromString(const std::string & input, const FieldDescriptor * field, Message * message)

Parse the given text as a single field value and store it into the given field of the given message. more...


static bool TextFormat::Print(
        const Message & message,
        io::ZeroCopyOutputStream * output)

Outputs a textual representation of the given message to the given output stream.

Returns false if printing fails.


static bool TextFormat::PrintUnknownFields(
        const UnknownFieldSet & unknown_fields,
        io::ZeroCopyOutputStream * output)

Print the fields in an UnknownFieldSet.

They are printed by tag number only. Embedded messages are heuristically identified by attempting to parse them. Returns false if printing fails.


static bool TextFormat::PrintToString(
        const Message & message,
        std::string * output)

Like Print(), but outputs directly to a string.

Note: output will be cleared prior to printing, and will be left empty even if printing fails. Returns false if printing fails.


static bool TextFormat::PrintUnknownFieldsToString(
        const UnknownFieldSet & unknown_fields,
        std::string * output)

Like PrintUnknownFields(), but outputs directly to a string.

Returns false if printing fails.


static void TextFormat::PrintFieldValueToString(
        const Message & message,
        const FieldDescriptor * field,
        int index,
        std::string * output)

Outputs a textual representation of the value of the field supplied on the message supplied.

For non-repeated fields, an index of -1 must be supplied. Note that this method will print the default value for a field if it is not set.


static bool TextFormat::Parse(
        io::ZeroCopyInputStream * input,
        Message * output)

Parses a text-format protocol message from the given input stream to the given message object.

This function parses the human-readable format written by Print(). Returns true on success. The message is cleared first, even if the function fails – See Merge() to avoid this behavior.

Example input: "user {\n id: 123 extra { gender: MALE language: 'en' }\n}"

One use for this function is parsing handwritten strings in test code. Another use is to parse the output from google::protobuf::Message::DebugString() (or ShortDebugString()), because these functions output using google::protobuf::TextFormat::Print().

If you would like to read a protocol buffer serialized in the (non-human-readable) binary wire format, see google::protobuf::MessageLite::ParseFromString().


static bool TextFormat::ParseFieldValueFromString(
        const std::string & input,
        const FieldDescriptor * field,
        Message * message)

Parse the given text as a single field value and store it into the given field of the given message.

If the field is a repeated field, the new value will be added to the end

class TextFormat::BaseTextGenerator

#include <google/protobuf/text_format.h>
namespace google::protobuf

Members

virtual

~BaseTextGenerator()

virtual void

Indent()

virtual void

Outdent()

virtual size_t

GetCurrentIndentationSize() const

Returns the current indentation size in characters.

virtual void

Print(const char * text, size_t size) = 0

Print text to the output stream.

void

PrintString(const std::string & str)

template void

PrintLiteral(const char(&) text)

class TextFormat::FastFieldValuePrinter

#include <google/protobuf/text_format.h>
namespace google::protobuf

The default printer that converts scalar values from fields into their string representation.

You can derive from this FastFieldValuePrinter if you want to have fields to be printed in a different way and register it at the Printer.

Members

FastFieldValuePrinter()

virtual

~FastFieldValuePrinter()

virtual void

PrintBool(bool val, BaseTextGenerator * generator) const

virtual void

PrintInt32(int32 val, BaseTextGenerator * generator) const

virtual void

PrintUInt32(uint32 val, BaseTextGenerator * generator) const

virtual void

PrintInt64(int64 val, BaseTextGenerator * generator) const

virtual void

PrintUInt64(uint64 val, BaseTextGenerator * generator) const

virtual void

PrintFloat(float val, BaseTextGenerator * generator) const

virtual void

PrintDouble(double val, BaseTextGenerator * generator) const

virtual void

PrintString(const std::string & val, BaseTextGenerator * generator) const

virtual void

PrintBytes(const std::string & val, BaseTextGenerator * generator) const

virtual void

PrintEnum(int32 val, const std::string & name, BaseTextGenerator * generator) const

virtual void

PrintFieldName(const Message & message, int field_index, int field_count, const Reflection * reflection, const FieldDescriptor * field, BaseTextGenerator * generator) const

virtual void

PrintFieldName(const Message & message, const Reflection * reflection, const FieldDescriptor * field, BaseTextGenerator * generator) const

virtual void

PrintMessageStart(const Message & message, int field_index, int field_count, bool single_line_mode, BaseTextGenerator * generator) const

virtual bool

PrintMessageContent(const Message & message, int field_index, int field_count, bool single_line_mode, BaseTextGenerator * generator) const

Allows to override the logic on how to print the content of a message. more...

virtual void

PrintMessageEnd(const Message & message, int field_index, int field_count, bool single_line_mode, BaseTextGenerator * generator) const


virtual bool FastFieldValuePrinter::PrintMessageContent(
        const Message & message,
        int field_index,
        int field_count,
        bool single_line_mode,
        BaseTextGenerator * generator) const

Allows to override the logic on how to print the content of a message.

Return false to use the default printing logic. Note that it is legal for this function to print something and then return false to use the default content printing (although at that point it would behave similarly to PrintMessageStart).

class TextFormat::FieldValuePrinter

#include <google/protobuf/text_format.h>
namespace google::protobuf

Deprecated: please use FastFieldValuePrinter instead.

Members

FieldValuePrinter()

virtual

~FieldValuePrinter()

virtual std::string

PrintBool(bool val) const

virtual std::string

PrintInt32(int32 val) const

virtual std::string

PrintUInt32(uint32 val) const

virtual std::string

PrintInt64(int64 val) const

virtual std::string

PrintUInt64(uint64 val) const

virtual std::string

PrintFloat(float val) const

virtual std::string

PrintDouble(double val) const

virtual std::string

PrintString(const std::string & val) const

virtual std::string

PrintBytes(const std::string & val) const

virtual std::string

PrintEnum(int32 val, const std::string & name) const

virtual std::string

PrintFieldName(const Message & message, const Reflection * reflection, const FieldDescriptor * field) const

virtual std::string

PrintMessageStart(const Message & message, int field_index, int field_count, bool single_line_mode) const

virtual std::string

PrintMessageEnd(const Message & message, int field_index, int field_count, bool single_line_mode) const

class TextFormat::Finder

#include <google/protobuf/text_format.h>
namespace google::protobuf

Interface that Printers or Parsers can use to find extensions, or types referenced in Any messages.

Members

virtual

~Finder()

virtual const FieldDescriptor *

FindExtension(Message * message, const std::string & name) const

Try to find an extension of *message by fully-qualified field name. more...

virtual const FieldDescriptor *

FindExtensionByNumber(const Descriptor * descriptor, int number) const

Similar to FindExtension, but uses a Descriptor and the extension number instead of using a Message and the name when doing the look up.

virtual const Descriptor *

FindAnyType(const Message & message, const std::string & prefix, const std::string & name) const

Find the message type for an Any proto. more...

virtual MessageFactory *

FindExtensionFactory(const FieldDescriptor * field) const

Find the message factory for the given extension field. more...


virtual const FieldDescriptor *
    Finder::FindExtension(
        Message * message,
        const std::string & name) const

Try to find an extension of *message by fully-qualified field name.

Returns NULL if no extension is known for this name or number. The base implementation uses the extensions already known by the message.


virtual const Descriptor *
    Finder::FindAnyType(
        const Message & message,
        const std::string & prefix,
        const std::string & name) const

Find the message type for an Any proto.

Returns NULL if no message is known for this name. The base implementation only accepts prefixes of type.googleprod.com/ or type.googleapis.com/, and searches the DescriptorPool of the parent message.


virtual MessageFactory * Finder::FindExtensionFactory(
        const FieldDescriptor * field) const

Find the message factory for the given extension field.

This can be used to generalize the Parser to add extension fields to a message in the same way as the "input" message for the Parser.

class TextFormat::MessagePrinter

#include <google/protobuf/text_format.h>
namespace google::protobuf

Members

MessagePrinter()

virtual

~MessagePrinter()

virtual void

Print(const Message & message, bool single_line_mode, BaseTextGenerator * generator) const = 0

class TextFormat::ParseInfoTree

#include <google/protobuf/text_format.h>
namespace google::protobuf

Data structure which is populated with the locations of each field value parsed from the text.

Members

ParseInfoTree()

ParseInfoTree(const ParseInfoTree & )

ParseInfoTree &

operator=(const ParseInfoTree & )

ParseLocation

GetLocation(const FieldDescriptor * field, int index) const

Returns the parse location for index-th value of the field in the parsed text. more...

ParseInfoTree *

GetTreeForNested(const FieldDescriptor * field, int index) const

Returns the parse info tree for the given field, which must be a message type. more...


ParseLocation ParseInfoTree::GetLocation(
        const FieldDescriptor * field,
        int index) const

Returns the parse location for index-th value of the field in the parsed text.

If none exists, returns a location with line = -1. Index should be -1 for not-repeated fields.


ParseInfoTree * ParseInfoTree::GetTreeForNested(
        const FieldDescriptor * field,
        int index) const

Returns the parse info tree for the given field, which must be a message type.

The nested information tree is owned by the root tree and will be deleted when it is deleted.

struct TextFormat::ParseLocation

#include <google/protobuf/text_format.h>
namespace google::protobuf

A location in the parsed text.

Members

int

line

int

column

ParseLocation()

ParseLocation(int line_param, int column_param)

class TextFormat::Parser

#include <google/protobuf/text_format.h>
namespace google::protobuf

For more control over parsing, use this class.

Members

Parser()

~Parser()

bool

Parse(io::ZeroCopyInputStream * input, Message * output)

Like TextFormat::Parse().

bool

ParseFromString(ConstStringParam input, Message * output)

Like TextFormat::ParseFromString().

bool

Merge(io::ZeroCopyInputStream * input, Message * output)

Like TextFormat::Merge().

bool

MergeFromString(ConstStringParam input, Message * output)

Like TextFormat::MergeFromString().

void

RecordErrorsTo(io::ErrorCollector * error_collector)

Set where to report parse errors. more...

void

SetFinder(const Finder * finder)

Set how parser finds extensions. more...

void

WriteLocationsTo(ParseInfoTree * tree)

Sets where location information about the parse will be written. more...

void

AllowPartialMessage(bool allow)

Normally parsing fails if, after parsing, output->IsInitialized() returns false. more...

void

AllowCaseInsensitiveField(bool allow)

Allow field names to be matched case-insensitively. more...

bool

ParseFieldValueFromString(const std::string & input, const FieldDescriptor * field, Message * output)

void

AllowUnknownExtension(bool allow)

When an unknown extension is met, parsing will fail if this option is set to false (the default). more...

void

AllowUnknownField(bool allow)

When an unknown field is met, parsing will fail if this option is set to false (the default). more...

void

AllowFieldNumber(bool allow)

void

SetRecursionLimit(int limit)

Sets maximum recursion depth which parser can use. more...


void Parser::RecordErrorsTo(
        io::ErrorCollector * error_collector)

Set where to report parse errors.

If NULL (the default), errors will be printed to stderr.


void Parser::SetFinder(
        const Finder * finder)

Set how parser finds extensions.

If NULL (the default), the parser will use the standard Reflection object associated with the message being parsed.


void Parser::WriteLocationsTo(
        ParseInfoTree * tree)

Sets where location information about the parse will be written.

If NULL (the default), then no location will be written.


void Parser::AllowPartialMessage(
        bool allow)

Normally parsing fails if, after parsing, output->IsInitialized() returns false.

Call AllowPartialMessage(true) to skip this check.


void Parser::AllowCaseInsensitiveField(
        bool allow)

Allow field names to be matched case-insensitively.

This is not advisable if there are fields that only differ in case, or if you want to enforce writing in the canonical form. This is 'false' by default.


void Parser::AllowUnknownExtension(
        bool allow)

When an unknown extension is met, parsing will fail if this option is set to false (the default).

If true, unknown extensions will be ignored and a warning message will be generated. Beware! Setting this option true may hide some errors (e.g. spelling error on extension name). This allows data loss; unlike binary format, text format cannot preserve unknown extensions. Avoid using this option if possible.


void Parser::AllowUnknownField(
        bool allow)

When an unknown field is met, parsing will fail if this option is set to false (the default).

If true, unknown fields will be ignored and a warning message will be generated. Beware! Setting this option true may hide some errors (e.g. spelling error on field name). This allows data loss; unlike binary format, text format cannot preserve unknown fields. Avoid using this option if possible.


void Parser::SetRecursionLimit(
        int limit)

Sets maximum recursion depth which parser can use.

This is effectively the maximum allowed nesting of proto messages.

class TextFormat::Printer

#include <google/protobuf/text_format.h>
namespace google::protobuf

Class for those users which require more fine-grained control over how a protobuffer message is printed out.

Members

Printer()

bool

Print(const Message & message, io::ZeroCopyOutputStream * output) const

Like TextFormat::Print.

bool

PrintUnknownFields(const UnknownFieldSet & unknown_fields, io::ZeroCopyOutputStream * output) const

bool

PrintToString(const Message & message, std::string * output) const

Like TextFormat::PrintToString.

bool

PrintUnknownFieldsToString(const UnknownFieldSet & unknown_fields, std::string * output) const

void

PrintFieldValueToString(const Message & message, const FieldDescriptor * field, int index, std::string * output) const

void

SetInitialIndentLevel(int indent_level)

Adjust the initial indent level of all output. more...

void

SetSingleLineMode(bool single_line_mode)

If printing in single line mode, then the entire message will be output on a single line with no line breaks.

bool

IsInSingleLineMode() const

void

SetUseFieldNumber(bool use_field_number)

If use_field_number is true, uses field number instead of field name.

void

SetUseShortRepeatedPrimitives(bool use_short_repeated_primitives)

Set true to print repeated primitives in a format like: more...

void

SetUseUtf8StringEscaping(bool as_utf8)

Set true to output UTF-8 instead of ASCII. more...

void

SetDefaultFieldValuePrinter(const FastFieldValuePrinter * printer)

Set the default FastFieldValuePrinter that is used for all fields that don't have a field-specific printer registered. more...

void

SetDefaultFieldValuePrinter(const FieldValuePrinter * printer)

void

SetHideUnknownFields(bool hide)

Sets whether we want to hide unknown fields or not. more...

void

SetPrintMessageFieldsInIndexOrder(bool print_message_fields_in_index_order)

If print_message_fields_in_index_order is true, fields of a proto message will be printed using the order defined in source code instead of the field number, extensions will be printed at the end of the message and their relative order is determined by the extension number. more...

void

SetExpandAny(bool expand)

If expand==true, expand google.protobuf.Any payloads. more...

void

SetFinder(const Finder * finder)

Set how parser finds message for Any payloads.

void

SetTruncateStringFieldLongerThan(const int64 truncate_string_field_longer_than)

If non-zero, we truncate all string fields that are longer than this threshold. more...

bool

RegisterFieldValuePrinter(const FieldDescriptor * field, const FastFieldValuePrinter * printer)

Register a custom field-specific FastFieldValuePrinter for fields with a particular FieldDescriptor. more...

bool

RegisterFieldValuePrinter(const FieldDescriptor * field, const FieldValuePrinter * printer)

bool

RegisterMessagePrinter(const Descriptor * descriptor, const MessagePrinter * printer)

Register a custom message-specific MessagePrinter for messages with a particular Descriptor. more...


void Printer::SetInitialIndentLevel(
        int indent_level)

Adjust the initial indent level of all output.

Each indent level is equal to two spaces.


void Printer::SetUseShortRepeatedPrimitives(
        bool use_short_repeated_primitives)

Set true to print repeated primitives in a format like:

field_name: [1, 2, 3, 4]

instead of printing each value on its own line. Short format applies only to primitive values – i.e. everything except strings and sub-messages/groups.


void Printer::SetUseUtf8StringEscaping(
        bool as_utf8)

Set true to output UTF-8 instead of ASCII.

The only difference is that bytes >= 0x80 in string fields will not be escaped, because they are assumed to be part of UTF-8 multi-byte sequences. This will change the default FastFieldValuePrinter.


void Printer::SetDefaultFieldValuePrinter(
        const FastFieldValuePrinter * printer)

Set the default FastFieldValuePrinter that is used for all fields that don't have a field-specific printer registered.

Takes ownership of the printer.


void Printer::SetHideUnknownFields(
        bool hide)

Sets whether we want to hide unknown fields or not.

Usually unknown fields are printed in a generic way that includes the tag number of the field instead of field name. However, sometimes it is useful to be able to print the message without unknown fields (e.g. for the python protobuf version to maintain consistency between its pure python and c++ implementations).


void Printer::SetPrintMessageFieldsInIndexOrder(
        bool print_message_fields_in_index_order)

If print_message_fields_in_index_order is true, fields of a proto message will be printed using the order defined in source code instead of the field number, extensions will be printed at the end of the message and their relative order is determined by the extension number.

By default, use the field number order.


void Printer::SetExpandAny(
        bool expand)

If expand==true, expand google.protobuf.Any payloads.

The output will be of form

[type_url] { <value_printed_in_text> }

If expand==false, print Any using the default printer. The output will look like

type_url: "<type_url>"  value: "serialized_content"

void Printer::SetTruncateStringFieldLongerThan(
        const int64 truncate_string_field_longer_than)

If non-zero, we truncate all string fields that are longer than this threshold.

This is useful when the proto message has very long strings, e.g., dump of encoded image file.

NOTE(hfgong): Setting a non-zero value breaks round-trip safe property of TextFormat::Printer. That is, from the printed message, we cannot fully recover the original string field any more.


bool Printer::RegisterFieldValuePrinter(
        const FieldDescriptor * field,
        const FastFieldValuePrinter * printer)

Register a custom field-specific FastFieldValuePrinter for fields with a particular FieldDescriptor.

Returns "true" if the registration succeeded, or "false", if there is already a printer for that FieldDescriptor. Takes ownership of the printer on successful registration.


bool Printer::RegisterMessagePrinter(
        const Descriptor * descriptor,
        const MessagePrinter * printer)

Register a custom message-specific MessagePrinter for messages with a particular Descriptor.

Returns "true" if the registration succeeded, or "false" if there is already a printer for that Descriptor.