/thirdparty/breakpad/third_party/protobuf/protobuf/src/google/protobuf/text_format.h

  1// Protocol Buffers - Google's data interchange format
  2// Copyright 2008 Google Inc.  All rights reserved.
  3// http://code.google.com/p/protobuf/
  4//
  5// Redistribution and use in source and binary forms, with or without
  6// modification, are permitted provided that the following conditions are
  7// met:
  8//
  9//     * Redistributions of source code must retain the above copyright
 10// notice, this list of conditions and the following disclaimer.
 11//     * Redistributions in binary form must reproduce the above
 12// copyright notice, this list of conditions and the following disclaimer
 13// in the documentation and/or other materials provided with the
 14// distribution.
 15//     * Neither the name of Google Inc. nor the names of its
 16// contributors may be used to endorse or promote products derived from
 17// this software without specific prior written permission.
 18//
 19// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 20// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 21// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 22// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 23// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 24// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 25// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 26// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 27// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 28// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 29// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 30
 31// Author: jschorr@google.com (Joseph Schorr)
 32//  Based on original Protocol Buffers design by
 33//  Sanjay Ghemawat, Jeff Dean, and others.
 34//
 35// Utilities for printing and parsing protocol messages in a human-readable,
 36// text-based format.
 37
 38#ifndef GOOGLE_PROTOBUF_TEXT_FORMAT_H__
 39#define GOOGLE_PROTOBUF_TEXT_FORMAT_H__
 40
 41#include <string>
 42#include <google/protobuf/message.h>
 43#include <google/protobuf/descriptor.h>
 44
 45namespace google {
 46namespace protobuf {
 47
 48namespace io {
 49  class ErrorCollector;      // tokenizer.h
 50}
 51
 52// This class implements protocol buffer text format.  Printing and parsing
 53// protocol messages in text format is useful for debugging and human editing
 54// of messages.
 55//
 56// This class is really a namespace that contains only static methods.
 57class LIBPROTOBUF_EXPORT TextFormat {
 58 public:
 59  // Outputs a textual representation of the given message to the given
 60  // output stream.
 61  static bool Print(const Message& message, io::ZeroCopyOutputStream* output);
 62
 63  // Print the fields in an UnknownFieldSet.  They are printed by tag number
 64  // only.  Embedded messages are heuristically identified by attempting to
 65  // parse them.
 66  static bool PrintUnknownFields(const UnknownFieldSet& unknown_fields,
 67                                 io::ZeroCopyOutputStream* output);
 68
 69  // Like Print(), but outputs directly to a string.
 70  static bool PrintToString(const Message& message, string* output);
 71
 72  // Like PrintUnknownFields(), but outputs directly to a string.
 73  static bool PrintUnknownFieldsToString(const UnknownFieldSet& unknown_fields,
 74                                         string* output);
 75
 76  // Outputs a textual representation of the value of the field supplied on
 77  // the message supplied. For non-repeated fields, an index of -1 must
 78  // be supplied. Note that this method will print the default value for a
 79  // field if it is not set.
 80  static void PrintFieldValueToString(const Message& message,
 81                                      const FieldDescriptor* field,
 82                                      int index,
 83                                      string* output);
 84
 85  // Class for those users which require more fine-grained control over how
 86  // a protobuffer message is printed out.
 87  class LIBPROTOBUF_EXPORT Printer {
 88   public:
 89    Printer();
 90    ~Printer();
 91
 92    // Like TextFormat::Print
 93    bool Print(const Message& message, io::ZeroCopyOutputStream* output) const;
 94    // Like TextFormat::PrintUnknownFields
 95    bool PrintUnknownFields(const UnknownFieldSet& unknown_fields,
 96                            io::ZeroCopyOutputStream* output) const;
 97    // Like TextFormat::PrintToString
 98    bool PrintToString(const Message& message, string* output) const;
 99    // Like TextFormat::PrintUnknownFieldsToString
100    bool PrintUnknownFieldsToString(const UnknownFieldSet& unknown_fields,
101                                    string* output) const;
102    // Like TextFormat::PrintFieldValueToString
103    void PrintFieldValueToString(const Message& message,
104                                 const FieldDescriptor* field,
105                                 int index,
106                                 string* output) const;
107
108    // Adjust the initial indent level of all output.  Each indent level is
109    // equal to two spaces.
110    void SetInitialIndentLevel(int indent_level) {
111      initial_indent_level_ = indent_level;
112    }
113
114    // If printing in single line mode, then the entire message will be output
115    // on a single line with no line breaks.
116    void SetSingleLineMode(bool single_line_mode) {
117      single_line_mode_ = single_line_mode;
118    }
119
120    // Set true to print repeated primitives in a format like:
121    //   field_name: [1, 2, 3, 4]
122    // instead of printing each value on its own line.  Short format applies
123    // only to primitive values -- i.e. everything except strings and
124    // sub-messages/groups.
125    void SetUseShortRepeatedPrimitives(bool use_short_repeated_primitives) {
126      use_short_repeated_primitives_ = use_short_repeated_primitives;
127    }
128
129    // Set true to output UTF-8 instead of ASCII.  The only difference
130    // is that bytes >= 0x80 in string fields will not be escaped,
131    // because they are assumed to be part of UTF-8 multi-byte
132    // sequences.
133    void SetUseUtf8StringEscaping(bool as_utf8) {
134      utf8_string_escaping_ = as_utf8;
135    }
136
137   private:
138    // Forward declaration of an internal class used to print the text
139    // output to the OutputStream (see text_format.cc for implementation).
140    class TextGenerator;
141
142    // Internal Print method, used for writing to the OutputStream via
143    // the TextGenerator class.
144    void Print(const Message& message,
145               TextGenerator& generator) const;
146
147    // Print a single field.
148    void PrintField(const Message& message,
149                    const Reflection* reflection,
150                    const FieldDescriptor* field,
151                    TextGenerator& generator) const;
152
153    // Print a repeated primitive field in short form.
154    void PrintShortRepeatedField(const Message& message,
155                                 const Reflection* reflection,
156                                 const FieldDescriptor* field,
157                                 TextGenerator& generator) const;
158
159    // Print the name of a field -- i.e. everything that comes before the
160    // ':' for a single name/value pair.
161    void PrintFieldName(const Message& message,
162                        const Reflection* reflection,
163                        const FieldDescriptor* field,
164                        TextGenerator& generator) const;
165
166    // Outputs a textual representation of the value of the field supplied on
167    // the message supplied or the default value if not set.
168    void PrintFieldValue(const Message& message,
169                         const Reflection* reflection,
170                         const FieldDescriptor* field,
171                         int index,
172                         TextGenerator& generator) const;
173
174    // Print the fields in an UnknownFieldSet.  They are printed by tag number
175    // only.  Embedded messages are heuristically identified by attempting to
176    // parse them.
177    void PrintUnknownFields(const UnknownFieldSet& unknown_fields,
178                            TextGenerator& generator) const;
179
180    int initial_indent_level_;
181
182    bool single_line_mode_;
183
184    bool use_short_repeated_primitives_;
185
186    bool utf8_string_escaping_;
187  };
188
189  // Parses a text-format protocol message from the given input stream to
190  // the given message object.  This function parses the format written
191  // by Print().
192  static bool Parse(io::ZeroCopyInputStream* input, Message* output);
193  // Like Parse(), but reads directly from a string.
194  static bool ParseFromString(const string& input, Message* output);
195
196  // Like Parse(), but the data is merged into the given message, as if
197  // using Message::MergeFrom().
198  static bool Merge(io::ZeroCopyInputStream* input, Message* output);
199  // Like Merge(), but reads directly from a string.
200  static bool MergeFromString(const string& input, Message* output);
201
202  // Parse the given text as a single field value and store it into the
203  // given field of the given message. If the field is a repeated field,
204  // the new value will be added to the end
205  static bool ParseFieldValueFromString(const string& input,
206                                        const FieldDescriptor* field,
207                                        Message* message);
208
209  // Interface that TextFormat::Parser can use to find extensions.
210  // This class may be extended in the future to find more information
211  // like fields, etc.
212  class LIBPROTOBUF_EXPORT Finder {
213   public:
214    virtual ~Finder();
215
216    // Try to find an extension of *message by fully-qualified field
217    // name.  Returns NULL if no extension is known for this name or number.
218    virtual const FieldDescriptor* FindExtension(
219        Message* message,
220        const string& name) const = 0;
221  };
222
223  // For more control over parsing, use this class.
224  class LIBPROTOBUF_EXPORT Parser {
225   public:
226    Parser();
227    ~Parser();
228
229    // Like TextFormat::Parse().
230    bool Parse(io::ZeroCopyInputStream* input, Message* output);
231    // Like TextFormat::ParseFromString().
232    bool ParseFromString(const string& input, Message* output);
233    // Like TextFormat::Merge().
234    bool Merge(io::ZeroCopyInputStream* input, Message* output);
235    // Like TextFormat::MergeFromString().
236    bool MergeFromString(const string& input, Message* output);
237
238    // Set where to report parse errors.  If NULL (the default), errors will
239    // be printed to stderr.
240    void RecordErrorsTo(io::ErrorCollector* error_collector) {
241      error_collector_ = error_collector;
242    }
243
244    // Set how parser finds extensions.  If NULL (the default), the
245    // parser will use the standard Reflection object associated with
246    // the message being parsed.
247    void SetFinder(Finder* finder) {
248      finder_ = finder;
249    }
250
251    // Normally parsing fails if, after parsing, output->IsInitialized()
252    // returns false.  Call AllowPartialMessage(true) to skip this check.
253    void AllowPartialMessage(bool allow) {
254      allow_partial_ = allow;
255    }
256
257    // Like TextFormat::ParseFieldValueFromString
258    bool ParseFieldValueFromString(const string& input,
259                                   const FieldDescriptor* field,
260                                   Message* output);
261
262   private:
263    // Forward declaration of an internal class used to parse text
264    // representations (see text_format.cc for implementation).
265    class ParserImpl;
266
267    // Like TextFormat::Merge().  The provided implementation is used
268    // to do the parsing.
269    bool MergeUsingImpl(io::ZeroCopyInputStream* input,
270                        Message* output,
271                        ParserImpl* parser_impl);
272
273    io::ErrorCollector* error_collector_;
274    Finder* finder_;
275    bool allow_partial_;
276  };
277
278 private:
279  GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(TextFormat);
280};
281
282}  // namespace protobuf
283
284}  // namespace google
285#endif  // GOOGLE_PROTOBUF_TEXT_FORMAT_H__