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 |
Outputs a textual representation of the given message to the given output stream. more... |
static bool |
Print the fields in an UnknownFieldSet. more... |
static bool |
|
static bool |
Like PrintUnknownFields(), but outputs directly to a string. more... |
static void |
Outputs a textual representation of the value of the field supplied on the message supplied. more... |
static bool |
Parses a text-format protocol message from the given input stream to the given message object. more... |
static bool |
Like Parse(), but reads directly from a string. |
static bool |
Like Parse(), but the data is merged into the given message, as if using Message::MergeFrom(). |
static bool |
Like Merge(), but reads directly from a string. |
static bool |
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)
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)
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)
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)
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)
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)
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)
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 |
|
virtual void |
|
virtual void |
|
virtual size_t |
Returns the current indentation size in characters. |
virtual void |
Print text to the output stream. |
void |
|
template void |
|
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 | |
|---|---|
|
|
virtual |
|
virtual void |
|
virtual void |
|
virtual void |
|
virtual void |
|
virtual void |
|
virtual void |
|
virtual void |
|
virtual void |
|
virtual void |
|
virtual void |
|
virtual void |
|
virtual void |
|
virtual void |
|
virtual bool |
Allows to override the logic on how to print the content of a message. more... |
virtual void |
|
virtual bool FastFieldValuePrinter::PrintMessageContent(
const Message & message,
int field_index,
int field_count,
bool single_line_mode,
BaseTextGenerator * generator) const
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 | |
|---|---|
|
|
virtual |
|
virtual std::string |
|
virtual std::string |
|
virtual std::string |
|
virtual std::string |
|
virtual std::string |
|
virtual std::string |
|
virtual std::string |
|
virtual std::string |
|
virtual std::string |
|
virtual std::string |
|
virtual std::string |
|
virtual std::string |
|
virtual std::string |
|
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 |
|
virtual const FieldDescriptor * |
Try to find an extension of *message by fully-qualified field name. more... |
virtual const FieldDescriptor * |
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 * |
Find the message type for an Any proto. more... |
virtual MessageFactory * |
Find the message factory for the given extension field. more... |
virtual const FieldDescriptor *
Finder::FindExtension(
Message * message,
const std::string & name) const
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
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
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 | |
|---|---|
|
|
virtual |
|
virtual void |
|
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 & |
|
ParseLocation |
Returns the parse location for index-th value of the field in the parsed text. more... |
ParseInfoTree * |
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
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
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 |
|
int |
|
|
|
|
|
class TextFormat::Parser
#include <google/protobuf/text_format.h>
namespace google::protobuf
For more control over parsing, use this class.
Members | |
|---|---|
|
|
|
|
bool |
Like TextFormat::Parse(). |
bool |
|
bool |
Like TextFormat::Merge(). |
bool |
|
void |
Set where to report parse errors. more... |
void |
Set how parser finds extensions. more... |
void |
Sets where location information about the parse will be written. more... |
void |
Normally parsing fails if, after parsing, output->IsInitialized() returns false. more... |
void |
Allow field names to be matched case-insensitively. more... |
bool |
|
void |
When an unknown extension is met, parsing will fail if this option is set to false (the default). more... |
void |
When an unknown field is met, parsing will fail if this option is set to false (the default). more... |
void |
|
void |
Sets maximum recursion depth which parser can use. more... |
void Parser::RecordErrorsTo(
io::ErrorCollector * error_collector)
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)
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)
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)
bool allow)
Normally parsing fails if, after parsing, output->IsInitialized() returns false.
Call AllowPartialMessage(true) to skip this check.
void Parser::AllowCaseInsensitiveField(
bool allow)
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)
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)
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)
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 | |
|---|---|
|
|
bool |
Like TextFormat::Print. |
bool |
|
bool |
|
bool |
|
void |
|
void |
Adjust the initial indent level of all output. more... |
void |
If printing in single line mode, then the entire message will be output on a single line with no line breaks. |
bool |
|
void |
If use_field_number is true, uses field number instead of field name. |
void |
Set true to print repeated primitives in a format like: more... |
void |
Set true to output UTF-8 instead of ASCII. more... |
void |
Set the default FastFieldValuePrinter that is used for all fields that don't have a field-specific printer registered. more... |
void |
|
void |
Sets whether we want to hide unknown fields or not. more... |
void |
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 |
If expand==true, expand google.protobuf.Any payloads. more... |
void |
Set how parser finds message for Any payloads. |
void |
If non-zero, we truncate all string fields that are longer than this threshold. more... |
bool |
Register a custom field-specific FastFieldValuePrinter for fields with a particular FieldDescriptor. more... |
bool |
|
bool |
Register a custom message-specific MessagePrinter for messages with a particular Descriptor. more... |
void Printer::SetInitialIndentLevel(
int indent_level)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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.