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

http://github.com/tomahawk-player/tomahawk · C++ Header · 285 lines · 125 code · 44 blank · 116 comment · 0 complexity · becbc8853a52ea0739b367b963856c2a MD5 · raw file

  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. // Author: jschorr@google.com (Joseph Schorr)
  31. // Based on original Protocol Buffers design by
  32. // Sanjay Ghemawat, Jeff Dean, and others.
  33. //
  34. // Utilities for printing and parsing protocol messages in a human-readable,
  35. // text-based format.
  36. #ifndef GOOGLE_PROTOBUF_TEXT_FORMAT_H__
  37. #define GOOGLE_PROTOBUF_TEXT_FORMAT_H__
  38. #include <string>
  39. #include <google/protobuf/message.h>
  40. #include <google/protobuf/descriptor.h>
  41. namespace google {
  42. namespace protobuf {
  43. namespace io {
  44. class ErrorCollector; // tokenizer.h
  45. }
  46. // This class implements protocol buffer text format. Printing and parsing
  47. // protocol messages in text format is useful for debugging and human editing
  48. // of messages.
  49. //
  50. // This class is really a namespace that contains only static methods.
  51. class LIBPROTOBUF_EXPORT TextFormat {
  52. public:
  53. // Outputs a textual representation of the given message to the given
  54. // output stream.
  55. static bool Print(const Message& message, io::ZeroCopyOutputStream* output);
  56. // Print the fields in an UnknownFieldSet. They are printed by tag number
  57. // only. Embedded messages are heuristically identified by attempting to
  58. // parse them.
  59. static bool PrintUnknownFields(const UnknownFieldSet& unknown_fields,
  60. io::ZeroCopyOutputStream* output);
  61. // Like Print(), but outputs directly to a string.
  62. static bool PrintToString(const Message& message, string* output);
  63. // Like PrintUnknownFields(), but outputs directly to a string.
  64. static bool PrintUnknownFieldsToString(const UnknownFieldSet& unknown_fields,
  65. string* output);
  66. // Outputs a textual representation of the value of the field supplied on
  67. // the message supplied. For non-repeated fields, an index of -1 must
  68. // be supplied. Note that this method will print the default value for a
  69. // field if it is not set.
  70. static void PrintFieldValueToString(const Message& message,
  71. const FieldDescriptor* field,
  72. int index,
  73. string* output);
  74. // Class for those users which require more fine-grained control over how
  75. // a protobuffer message is printed out.
  76. class LIBPROTOBUF_EXPORT Printer {
  77. public:
  78. Printer();
  79. ~Printer();
  80. // Like TextFormat::Print
  81. bool Print(const Message& message, io::ZeroCopyOutputStream* output) const;
  82. // Like TextFormat::PrintUnknownFields
  83. bool PrintUnknownFields(const UnknownFieldSet& unknown_fields,
  84. io::ZeroCopyOutputStream* output) const;
  85. // Like TextFormat::PrintToString
  86. bool PrintToString(const Message& message, string* output) const;
  87. // Like TextFormat::PrintUnknownFieldsToString
  88. bool PrintUnknownFieldsToString(const UnknownFieldSet& unknown_fields,
  89. string* output) const;
  90. // Like TextFormat::PrintFieldValueToString
  91. void PrintFieldValueToString(const Message& message,
  92. const FieldDescriptor* field,
  93. int index,
  94. string* output) const;
  95. // Adjust the initial indent level of all output. Each indent level is
  96. // equal to two spaces.
  97. void SetInitialIndentLevel(int indent_level) {
  98. initial_indent_level_ = indent_level;
  99. }
  100. // If printing in single line mode, then the entire message will be output
  101. // on a single line with no line breaks.
  102. void SetSingleLineMode(bool single_line_mode) {
  103. single_line_mode_ = single_line_mode;
  104. }
  105. // Set true to print repeated primitives in a format like:
  106. // field_name: [1, 2, 3, 4]
  107. // instead of printing each value on its own line. Short format applies
  108. // only to primitive values -- i.e. everything except strings and
  109. // sub-messages/groups.
  110. void SetUseShortRepeatedPrimitives(bool use_short_repeated_primitives) {
  111. use_short_repeated_primitives_ = use_short_repeated_primitives;
  112. }
  113. // Set true to output UTF-8 instead of ASCII. The only difference
  114. // is that bytes >= 0x80 in string fields will not be escaped,
  115. // because they are assumed to be part of UTF-8 multi-byte
  116. // sequences.
  117. void SetUseUtf8StringEscaping(bool as_utf8) {
  118. utf8_string_escaping_ = as_utf8;
  119. }
  120. private:
  121. // Forward declaration of an internal class used to print the text
  122. // output to the OutputStream (see text_format.cc for implementation).
  123. class TextGenerator;
  124. // Internal Print method, used for writing to the OutputStream via
  125. // the TextGenerator class.
  126. void Print(const Message& message,
  127. TextGenerator& generator) const;
  128. // Print a single field.
  129. void PrintField(const Message& message,
  130. const Reflection* reflection,
  131. const FieldDescriptor* field,
  132. TextGenerator& generator) const;
  133. // Print a repeated primitive field in short form.
  134. void PrintShortRepeatedField(const Message& message,
  135. const Reflection* reflection,
  136. const FieldDescriptor* field,
  137. TextGenerator& generator) const;
  138. // Print the name of a field -- i.e. everything that comes before the
  139. // ':' for a single name/value pair.
  140. void PrintFieldName(const Message& message,
  141. const Reflection* reflection,
  142. const FieldDescriptor* field,
  143. TextGenerator& generator) const;
  144. // Outputs a textual representation of the value of the field supplied on
  145. // the message supplied or the default value if not set.
  146. void PrintFieldValue(const Message& message,
  147. const Reflection* reflection,
  148. const FieldDescriptor* field,
  149. int index,
  150. TextGenerator& generator) const;
  151. // Print the fields in an UnknownFieldSet. They are printed by tag number
  152. // only. Embedded messages are heuristically identified by attempting to
  153. // parse them.
  154. void PrintUnknownFields(const UnknownFieldSet& unknown_fields,
  155. TextGenerator& generator) const;
  156. int initial_indent_level_;
  157. bool single_line_mode_;
  158. bool use_short_repeated_primitives_;
  159. bool utf8_string_escaping_;
  160. };
  161. // Parses a text-format protocol message from the given input stream to
  162. // the given message object. This function parses the format written
  163. // by Print().
  164. static bool Parse(io::ZeroCopyInputStream* input, Message* output);
  165. // Like Parse(), but reads directly from a string.
  166. static bool ParseFromString(const string& input, Message* output);
  167. // Like Parse(), but the data is merged into the given message, as if
  168. // using Message::MergeFrom().
  169. static bool Merge(io::ZeroCopyInputStream* input, Message* output);
  170. // Like Merge(), but reads directly from a string.
  171. static bool MergeFromString(const string& input, Message* output);
  172. // Parse the given text as a single field value and store it into the
  173. // given field of the given message. If the field is a repeated field,
  174. // the new value will be added to the end
  175. static bool ParseFieldValueFromString(const string& input,
  176. const FieldDescriptor* field,
  177. Message* message);
  178. // Interface that TextFormat::Parser can use to find extensions.
  179. // This class may be extended in the future to find more information
  180. // like fields, etc.
  181. class LIBPROTOBUF_EXPORT Finder {
  182. public:
  183. virtual ~Finder();
  184. // Try to find an extension of *message by fully-qualified field
  185. // name. Returns NULL if no extension is known for this name or number.
  186. virtual const FieldDescriptor* FindExtension(
  187. Message* message,
  188. const string& name) const = 0;
  189. };
  190. // For more control over parsing, use this class.
  191. class LIBPROTOBUF_EXPORT Parser {
  192. public:
  193. Parser();
  194. ~Parser();
  195. // Like TextFormat::Parse().
  196. bool Parse(io::ZeroCopyInputStream* input, Message* output);
  197. // Like TextFormat::ParseFromString().
  198. bool ParseFromString(const string& input, Message* output);
  199. // Like TextFormat::Merge().
  200. bool Merge(io::ZeroCopyInputStream* input, Message* output);
  201. // Like TextFormat::MergeFromString().
  202. bool MergeFromString(const string& input, Message* output);
  203. // Set where to report parse errors. If NULL (the default), errors will
  204. // be printed to stderr.
  205. void RecordErrorsTo(io::ErrorCollector* error_collector) {
  206. error_collector_ = error_collector;
  207. }
  208. // Set how parser finds extensions. If NULL (the default), the
  209. // parser will use the standard Reflection object associated with
  210. // the message being parsed.
  211. void SetFinder(Finder* finder) {
  212. finder_ = finder;
  213. }
  214. // Normally parsing fails if, after parsing, output->IsInitialized()
  215. // returns false. Call AllowPartialMessage(true) to skip this check.
  216. void AllowPartialMessage(bool allow) {
  217. allow_partial_ = allow;
  218. }
  219. // Like TextFormat::ParseFieldValueFromString
  220. bool ParseFieldValueFromString(const string& input,
  221. const FieldDescriptor* field,
  222. Message* output);
  223. private:
  224. // Forward declaration of an internal class used to parse text
  225. // representations (see text_format.cc for implementation).
  226. class ParserImpl;
  227. // Like TextFormat::Merge(). The provided implementation is used
  228. // to do the parsing.
  229. bool MergeUsingImpl(io::ZeroCopyInputStream* input,
  230. Message* output,
  231. ParserImpl* parser_impl);
  232. io::ErrorCollector* error_collector_;
  233. Finder* finder_;
  234. bool allow_partial_;
  235. };
  236. private:
  237. GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(TextFormat);
  238. };
  239. } // namespace protobuf
  240. } // namespace google
  241. #endif // GOOGLE_PROTOBUF_TEXT_FORMAT_H__