text_format.h

text_format.h

#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
TextFormat This class implements protocol buffer text format.
TextFormat::Finder Interface that  TextFormat::Parser can use to find extensions.
TextFormat::ParseInfoTree Data structure which is populated with the locations of each field value parsed from the text.
TextFormat::ParseLocation A location in the parsed text.
TextFormat::Parser For more control over parsing, use this class.
TextFormat::Printer 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.

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::Finder

#include <google/protobuf/text_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/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()
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(const string & input, Message * output) Like  TextFormat::ParseFromString().
bool	Merge(io::ZeroCopyInputStream * input, Message * output) Like  TextFormat::Merge().
bool	MergeFromString(const string & input, Message * output) Like  TextFormat::MergeFromString().
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...
bool	ParseFieldValueFromString(const string & input, const FieldDescriptor * field, Message * output) Like  TextFormat::ParseFieldValueFromString.

---

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.

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()
	~Printer()
bool	Print(const Message & message, io::ZeroCopyOutputStream * output) const Like  TextFormat::Print.
bool	PrintUnknownFields(const UnknownFieldSet & unknown_fields, io::ZeroCopyOutputStream * output) const Like  TextFormat::PrintUnknownFields.
bool	PrintToString(const Message & message, string * output) const Like  TextFormat::PrintToString.
bool	PrintUnknownFieldsToString(const UnknownFieldSet & unknown_fields, string * output) const Like  TextFormat::PrintUnknownFieldsToString.
void	PrintFieldValueToString(const Message & message, const FieldDescriptor * field, int index, string * output) const Like  TextFormat::PrintFieldValueToString.
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.
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 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.