text_format.h

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)
bool
ParseFromString(ConstStringParam input, Message * output)
bool
Merge(io::ZeroCopyInputStream * input, Message * output)
bool
MergeFromString(ConstStringParam input, Message * output)
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
bool
PrintUnknownFields(const UnknownFieldSet & unknown_fields, io::ZeroCopyOutputStream * output) const
bool
PrintToString(const Message & message, std::string * output) const
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.