Class TextFormat

java.lang.Object
com.google.protobuf.TextFormat
public final class TextFormat extends Object
This class implements the Protobuf Text Format.

Printing and parsing protocol messages in text format is useful for debugging and human editing of messages.

Unlike the Binary and ProtoJSON formats, Text Format is not designed to be used as a wire format; instead it is intended for human-in-the-loop configuration use-cases.

Systems processing untrusted inputs should strongly prefer to use Binary format instead. If a textual format of untrusted inputs is required, consider using ProtoJSON format instead.

  • Field Details

    • logger

      private static final Logger logger

    • DEBUG_STRING_SILENT_MARKER

      private static final String DEBUG_STRING_SILENT_MARKER
      See Also:

    • ENABLE_INSERT_SILENT_MARKER_ENV_NAME

      private static final String ENABLE_INSERT_SILENT_MARKER_ENV_NAME
      See Also:

    • ENABLE_INSERT_SILENT_MARKER

      private static final boolean ENABLE_INSERT_SILENT_MARKER

    • REDACTED_MARKER

      private static final String REDACTED_MARKER
      See Also:

    • PARSER

      private static final TextFormat.Parser PARSER

  • Constructor Details

    • TextFormat

      private TextFormat()

  • Method Details

    • shortDebugString

      @Deprecated public static String shortDebugString(MessageOrBuilder message)
      Deprecated.
      Use printer().emittingSingleLine(true).printToString(MessageOrBuilder)
      Generates a human readable form of this message, useful for debugging and other purposes, with no newline characters. This is just a trivial wrapper around TextFormat.Printer.shortDebugString(MessageOrBuilder).

    • printUnknownFieldValue

      public static void printUnknownFieldValue(int tag, Object value, Appendable output) throws IOException
      Outputs a textual representation of the value of an unknown field.
      Parameters:
      tag - the field's tag number
      value - the value of the field
      output - the output to which to append the formatted value
      Throws:
      ClassCastException - if the value is not appropriate for the given field descriptor
      IOException - if there is an exception writing to the output

    • printUnknownFieldValue

      private static void printUnknownFieldValue(int tag, Object value, TextFormat.TextGenerator generator, boolean redact) throws IOException
      Throws:
      IOException

    • printer

      public static TextFormat.Printer printer()
      Printer instance which escapes non-ASCII characters.

    • debugFormatPrinter

      public static TextFormat.Printer debugFormatPrinter()
      Printer instance which escapes non-ASCII characters and prints in the debug format.

    • defaultFormatPrinter

      public static TextFormat.Printer defaultFormatPrinter()
      Printer instance which escapes non-ASCII characters and prints in the debug format.

    • print

      @Deprecated @InlineMe(replacement="TextFormat.printer().print(message, output)", imports="com.google.protobuf.TextFormat") public static void print(MessageOrBuilder message, Appendable output) throws IOException
      Deprecated.
      Use printer().print(MessageOrBuilder, Appendable)
      Outputs a textual representation of the Protocol Message supplied into the parameter output. (This representation is the new version of the classic "ProtocolPrinter" output from the original Protocol Buffer system)
      Throws:
      IOException

    • printUnicode

      @Deprecated public static void printUnicode(MessageOrBuilder message, Appendable output) throws IOException
      Deprecated.
      Use printer().escapingNonAscii(false).print(MessageOrBuilder, Appendable)
      Same as print(), except that non-ASCII characters are not escaped.
      Throws:
      IOException

    • printToString

      @Deprecated public static String printToString(MessageOrBuilder message)
      Deprecated.
      Use message.toString()
      Like print(), but writes directly to a String and returns it.

    • printToUnicodeString

      @Deprecated public static String printToUnicodeString(MessageOrBuilder message)
      Deprecated.
      Use printer().escapingNonAscii(false).printToString(MessageOrBuilder)
      Same as printToString(), except that non-ASCII characters in string type fields are not escaped in backslash+octals.

    • printFieldValue

      @Deprecated @InlineMe(replacement="TextFormat.printer().printFieldValue(field, value, output)", imports="com.google.protobuf.TextFormat") public static void printFieldValue(Descriptors.FieldDescriptor field, Object value, Appendable output) throws IOException
      Deprecated.
      Use printer().printFieldValue(FieldDescriptor, Object, Appendable)
      Outputs a textual representation of the value of given field value.
      Parameters:
      field - the descriptor of the field
      value - the value of the field
      output - the output to which to append the formatted value
      Throws:
      ClassCastException - if the value is not appropriate for the given field descriptor
      IOException - if there is an exception writing to the output

    • unsignedToString

      public static String unsignedToString(int value)
      Convert an unsigned 32-bit integer to a string.

    • unsignedToString

      public static String unsignedToString(long value)
      Convert an unsigned 64-bit integer to a string.

    • setSingleLineOutput

      private static TextFormat.TextGenerator setSingleLineOutput(Appendable output, boolean singleLine)

    • setSingleLineOutput

      private static TextFormat.TextGenerator setSingleLineOutput(Appendable output, boolean singleLine, Descriptors.Descriptor rootMessageType, TextFormat.Printer.FieldReporterLevel fieldReporterLevel, boolean shouldEmitSilentMarker)

    • getParser

      public static TextFormat.Parser getParser()
      Return a TextFormat.Parser instance which can parse text-format messages. The returned instance is thread-safe.

    • merge

      public static void merge(Readable input, Message.Builder builder) throws IOException
      Parse a text-format message from input and merge the contents into builder.
      Throws:
      IOException

    • merge

      public static void merge(CharSequence input, Message.Builder builder) throws TextFormat.ParseException
      Parse a text-format message from input and merge the contents into builder.
      Throws:
      TextFormat.ParseException

    • parse

      public static <T extends Message> T parse(CharSequence input, Class<T> protoClass) throws TextFormat.ParseException
      Parse a text-format message from input.
      Returns:
      the parsed message, guaranteed initialized
      Throws:
      TextFormat.ParseException

    • merge

      public static void merge(Readable input, ExtensionRegistry extensionRegistry, Message.Builder builder) throws IOException
      Parse a text-format message from input and merge the contents into builder. Extensions will be recognized if they are registered in extensionRegistry.
      Throws:
      IOException

    • merge

      public static void merge(CharSequence input, ExtensionRegistry extensionRegistry, Message.Builder builder) throws TextFormat.ParseException
      Parse a text-format message from input and merge the contents into builder. Extensions will be recognized if they are registered in extensionRegistry.
      Throws:
      TextFormat.ParseException

    • parse

      public static <T extends Message> T parse(CharSequence input, ExtensionRegistry extensionRegistry, Class<T> protoClass) throws TextFormat.ParseException
      Parse a text-format message from input. Extensions will be recognized if they are registered in extensionRegistry.
      Returns:
      the parsed message, guaranteed initialized
      Throws:
      TextFormat.ParseException

    • escapeBytes

      public static String escapeBytes(ByteString input)
      Escapes bytes in the format used in protocol buffer text format, which is the same as the format used for C string literals. All bytes that are not printable 7-bit ASCII characters are escaped, as well as backslash, single-quote, and double-quote characters. Characters for which no defined short-hand escape sequence is defined will be escaped using 3-digit octal sequences.

    • escapeBytes

      public static String escapeBytes(byte[] input)
      Like escapeBytes(ByteString), but used for byte array.

    • unescapeBytes

      public static ByteString unescapeBytes(CharSequence charString) throws TextFormat.InvalidEscapeSequenceException
      Un-escape a byte sequence as escaped using escapeBytes(ByteString). Two-digit hex escapes (starting with "\x") are also recognized.
      Throws:
      TextFormat.InvalidEscapeSequenceException

    • escapeText

      static String escapeText(String input)
      Like escapeBytes(ByteString), but escapes a text string. Non-ASCII characters are first encoded as UTF-8, then each byte is escaped individually as a 3-digit octal escape. Yes, it's weird.

    • escapeDoubleQuotesAndBackslashes

      public static String escapeDoubleQuotesAndBackslashes(String input)
      Escape double quotes and backslashes in a String for emittingUnicode output of a message.

    • unescapeText

      static String unescapeText(String input) throws TextFormat.InvalidEscapeSequenceException
      Un-escape a text string as escaped using escapeText(String). Two-digit hex escapes (starting with "\x") are also recognized.
      Throws:
      TextFormat.InvalidEscapeSequenceException

    • isOctal

      private static boolean isOctal(byte c)
      Is this an octal digit?

    • isHex

      private static boolean isHex(byte c)
      Is this a hex digit?

    • digitValue

      private static int digitValue(byte c)
      Interpret a character as a digit (in any base up to 36) and return the numeric value. This is like Character.digit() but we don't accept non-ASCII digits.

    • parseInt32

      static int parseInt32(String text) throws NumberFormatException
      Parse a 32-bit signed integer from the text. Unlike the Java standard Integer.parseInt(), this function recognizes the prefixes "0x" and "0" to signify hexadecimal and octal numbers, respectively.
      Throws:
      NumberFormatException

    • parseUInt32

      static int parseUInt32(String text) throws NumberFormatException
      Parse a 32-bit unsigned integer from the text. Unlike the Java standard Integer.parseInt(), this function recognizes the prefixes "0x" and "0" to signify hexadecimal and octal numbers, respectively. The result is coerced to a (signed) int when returned since Java has no unsigned integer type.
      Throws:
      NumberFormatException

    • parseInt64

      static long parseInt64(String text) throws NumberFormatException
      Parse a 64-bit signed integer from the text. Unlike the Java standard Integer.parseInt(), this function recognizes the prefixes "0x" and "0" to signify hexadecimal and octal numbers, respectively.
      Throws:
      NumberFormatException

    • parseUInt64

      static long parseUInt64(String text) throws NumberFormatException
      Parse a 64-bit unsigned integer from the text. Unlike the Java standard Integer.parseInt(), this function recognizes the prefixes "0x" and "0" to signify hexadecimal and octal numbers, respectively. The result is coerced to a (signed) long when returned since Java has no unsigned long type.
      Throws:
      NumberFormatException

    • parseInteger

      private static long parseInteger(String text, boolean isSigned, boolean isLong) throws NumberFormatException
      Throws:
      NumberFormatException