Hide

text_format.h

#include <google/protobuftext_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.
The default printer that converts scalar values from fields into their string representation.
Interface that TextFormat::Parser can use to find extensions.
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/protobuftext_format.h>
namespace google::protobuf

This class implements protocol buffer text format.

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.
static bool
PrintUnknownFields(const UnknownFieldSet & unknown_fields, io::ZeroCopyOutputStream * output)
Print the fields in an UnknownFieldSet. more...
static bool
PrintToString(const Message & message, string * output)
Like Print(), but outputs directly to a string.
static bool
PrintUnknownFieldsToString(const UnknownFieldSet & unknown_fields, string * output)
Like PrintUnknownFields(), but outputs directly to a string.
static void
PrintFieldValueToString(const Message & message, const FieldDescriptor * field, int index, 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(const string & 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(const string & input, Message * output)
Like Merge(), but reads directly from a string.
static bool
ParseFieldValueFromString(const 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::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.


static void TextFormat::PrintFieldValueToString(
        const Message & message,
        const FieldDescriptor * field,
        int index,
        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 format written by Print().


static bool TextFormat::ParseFieldValueFromString(
        const 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::FieldValuePrinter

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

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

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

Members

FieldValuePrinter()
virtual
~FieldValuePrinter()
virtual string
PrintBool(bool val) const
virtual string
PrintInt32(int32 val) const
virtual string
PrintUInt32(uint32 val) const
virtual string
PrintInt64(int64 val) const
virtual string
PrintUInt64(uint64 val) const
virtual string
PrintFloat(float val) const
virtual string
PrintDouble(double val) const
virtual string
PrintString(const string & val) const
virtual string
PrintBytes(const string & val) const
virtual string
PrintEnum(int32 val, const string & name) const
virtual string
PrintFieldName(const Message & message, const Reflection * reflection, const FieldDescriptor * field) const
virtual string
PrintMessageStart(const Message & message, int field_index, int field_count, bool single_line_mode) const
virtual string
PrintMessageEnd(const Message & message, int field_index, int field_count, bool single_line_mode) const

class TextFormat::Finder

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

Interface that TextFormat::Parser can use to find extensions.

This class may be extended in the future to find more information like fields, etc.

Members

virtual
~Finder()
virtual const FieldDescriptor *
FindExtension(Message * message, const string & name) const = 0
Try to find an extension of *message by fully-qualified field name. more...

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

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

Returns NULL if no extension is known for this name or number.

class TextFormat::ParseInfoTree

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

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

Members

ParseInfoTree()
~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/protobuftext_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/protobuftext_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(const string & input, Message * output)
bool
Merge(io::ZeroCopyInputStream * input, Message * output)
bool
MergeFromString(const string & input, Message * output)
void
RecordErrorsTo(io::ErrorCollector * error_collector)
Set where to report parse errors. more...
void
SetFinder(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 string & input, const FieldDescriptor * field, Message * output)
void
AllowFieldNumber(bool allow)

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(
        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.

class TextFormat::Printer

#include <google/protobuftext_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()
~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, string * output) const
bool
PrintUnknownFieldsToString(const UnknownFieldSet & unknown_fields, string * output) const
void
PrintFieldValueToString(const Message & message, const FieldDescriptor * field, int index, 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()
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 FieldValuePrinter * printer)
Set the default FieldValuePrinter that is used for all fields that don't have a field-specific printer registered. more...
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, print fields of a proto message using the order defined in source code instead of the field number. more...
bool
RegisterFieldValuePrinter(const FieldDescriptor * field, const FieldValuePrinter * printer)
Register a custom field-specific FieldValuePrinter for fields with a particular FieldDescriptor. 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 FieldValuePrinter.


void Printer::SetDefaultFieldValuePrinter(
        const FieldValuePrinter * printer)

Set the default FieldValuePrinter 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, print fields of a proto message using the order defined in source code instead of the field number.

By default, use the field number order.


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

Register a custom field-specific FieldValuePrinter 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.