TextFormat
Date: 2017-07-08

com.google.protobuf

## Class TextFormat

- java.lang.Object
- - com.google.protobuf.TextFormat

-     public final class TextFormat
      extends java.lang.Object

  Provide text parsing and formatting support for proto2 instances. The implementation largely follows google/protobuf/text_format.cc.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `TextFormat.InvalidEscapeSequenceException` Thrown by `unescapeBytes(java.lang.CharSequence)` and `unescapeText(java.lang.String)` when an invalid escape sequence is seen.
    `static class` | `TextFormat.ParseException` Thrown when parsing an invalid text format message.
    `static class` | `TextFormat.Parser` Parser for text-format proto2 instances.
    `static class` | `TextFormat.UnknownFieldParseException` Thrown when encountering an unknown field while parsing a text format message.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.lang.String` | `escapeBytes(byte[] input)` Like `escapeBytes(ByteString)`, but used for byte array.
    `static java.lang.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.
    `static java.lang.String` | `escapeDoubleQuotesAndBackslashes(java.lang.String input)` Escape double quotes and backslashes in a String for unicode output of a message.
    `static TextFormat.Parser` | `getParser()` Return a `Parser` instance which can parse text-format messages.
    `static void` | `merge(java.lang.CharSequence input, ExtensionRegistry extensionRegistry, Message.Builder builder)` Parse a text-format message from `input` and merge the contents into `builder`.
    `static void` | `merge(java.lang.CharSequence input, Message.Builder builder)` Parse a text-format message from `input` and merge the contents into `builder`.
    `static void` | `merge(java.lang.Readable input, ExtensionRegistry extensionRegistry, Message.Builder builder)` Parse a text-format message from `input` and merge the contents into `builder`.
    `static void` | `merge(java.lang.Readable input, Message.Builder builder)` Parse a text-format message from `input` and merge the contents into `builder`.
    `static void` | `print(MessageOrBuilder message, java.lang.Appendable output)` Outputs a textual representation of the Protocol Message supplied into the parameter output.
    `static void` | `print(UnknownFieldSet fields, java.lang.Appendable output)` Outputs a textual representation of `fields` to `output`.
    `static void` | `printField(Descriptors.FieldDescriptor field, java.lang.Object value, java.lang.Appendable output)`
    `static java.lang.String` | `printFieldToString(Descriptors.FieldDescriptor field, java.lang.Object value)`
    `static void` | `printFieldValue(Descriptors.FieldDescriptor field, java.lang.Object value, java.lang.Appendable output)` Outputs a textual representation of the value of given field value.
    `static java.lang.String` | `printToString(MessageOrBuilder message)` Like `print()`, but writes directly to a `String` and returns it.
    `static java.lang.String` | `printToString(UnknownFieldSet fields)` Like `print()`, but writes directly to a `String` and returns it.
    `static java.lang.String` | `printToUnicodeString(MessageOrBuilder message)` Same as `printToString()`, except that non-ASCII characters in string type fields are not escaped in backslash+octals.
    `static java.lang.String` | `printToUnicodeString(UnknownFieldSet fields)` Same as `printToString()`, except that non-ASCII characters in string type fields are not escaped in backslash+octals.
    `static void` | `printUnicode(MessageOrBuilder message, java.lang.Appendable output)` Same as `print()`, except that non-ASCII characters are not escaped.
    `static void` | `printUnicode(UnknownFieldSet fields, java.lang.Appendable output)` Same as `print()`, except that non-ASCII characters are not escaped.
    `static void` | `printUnknownFieldValue(int tag, java.lang.Object value, java.lang.Appendable output)` Outputs a textual representation of the value of an unknown field.
    `static java.lang.String` | `shortDebugString(Descriptors.FieldDescriptor field, java.lang.Object value)` Generates a human readable form of the field, useful for debugging and other purposes, with no newline characters.
    `static java.lang.String` | `shortDebugString(MessageOrBuilder message)` Generates a human readable form of this message, useful for debugging and other purposes, with no newline characters.
    `static java.lang.String` | `shortDebugString(UnknownFieldSet fields)` Generates a human readable form of the unknown fields, useful for debugging and other purposes, with no newline characters.
    `static ByteString` | `unescapeBytes(java.lang.CharSequence charString)` Un-escape a byte sequence as escaped using `escapeBytes(ByteString)`.
    `static java.lang.String` | `unsignedToString(int value)` Convert an unsigned 32-bit integer to a string.
    `static java.lang.String` | `unsignedToString(long value)` Convert an unsigned 64-bit integer to a string.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### print

          public static void print(MessageOrBuilder message,
                   java.lang.Appendable output)
                            throws java.io.IOException

      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:
        `java.io.IOException`

    - #### print

          public static void print(UnknownFieldSet fields,
                   java.lang.Appendable output)
                            throws java.io.IOException

      Outputs a textual representation of `fields` to `output`.
      Throws:
        `java.io.IOException`

    - #### printUnicode

          public static void printUnicode(MessageOrBuilder message,
                          java.lang.Appendable output)
                                   throws java.io.IOException

      Same as `print()`, except that non-ASCII characters are not escaped.
      Throws:
        `java.io.IOException`

    - #### printUnicode

          public static void printUnicode(UnknownFieldSet fields,
                          java.lang.Appendable output)
                                   throws java.io.IOException

      Same as `print()`, except that non-ASCII characters are not escaped.
      Throws:
        `java.io.IOException`

    - #### shortDebugString

          public static java.lang.String shortDebugString(MessageOrBuilder message)

      Generates a human readable form of this message, useful for debugging and other purposes, with no newline characters.

    - #### shortDebugString

          public static java.lang.String shortDebugString(Descriptors.FieldDescriptor field,
                                          java.lang.Object value)

      Generates a human readable form of the field, useful for debugging and other purposes, with no newline characters.

    - #### shortDebugString

          public static java.lang.String shortDebugString(UnknownFieldSet fields)

      Generates a human readable form of the unknown fields, useful for debugging and other purposes, with no newline characters.

    - #### printToString

          public static java.lang.String printToString(MessageOrBuilder message)

      Like `print()`, but writes directly to a `String` and returns it.

    - #### printToString

          public static java.lang.String printToString(UnknownFieldSet fields)

      Like `print()`, but writes directly to a `String` and returns it.

    - #### printToUnicodeString

          public static java.lang.String printToUnicodeString(MessageOrBuilder message)

      Same as `printToString()`, except that non-ASCII characters in string type fields are not escaped in backslash+octals.

    - #### printToUnicodeString

          public static java.lang.String printToUnicodeString(UnknownFieldSet fields)

      Same as `printToString()`, except that non-ASCII characters in string type fields are not escaped in backslash+octals.

    - #### printField

          public static void printField(Descriptors.FieldDescriptor field,
                        java.lang.Object value,
                        java.lang.Appendable output)
                                 throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### printFieldToString

          public static java.lang.String printFieldToString(Descriptors.FieldDescriptor field,
                                            java.lang.Object value)

    - #### printFieldValue

          public static void printFieldValue(Descriptors.FieldDescriptor field,
                             java.lang.Object value,
                             java.lang.Appendable output)
                                      throws java.io.IOException

      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:
        `java.lang.ClassCastException` - if the value is not appropriate for the given field descriptor
        `java.io.IOException` - if there is an exception writing to the output

    - #### printUnknownFieldValue

          public static void printUnknownFieldValue(int tag,
                                    java.lang.Object value,
                                    java.lang.Appendable output)
                                             throws java.io.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:
        `java.lang.ClassCastException` - if the value is not appropriate for the given field descriptor
        `java.io.IOException` - if there is an exception writing to the output

    - #### unsignedToString

          public static java.lang.String unsignedToString(int value)

      Convert an unsigned 32-bit integer to a string.

    - #### unsignedToString

          public static java.lang.String unsignedToString(long value)

      Convert an unsigned 64-bit integer to a string.

    - #### getParser

          public static TextFormat.Parser getParser()

      Return a `Parser` instance which can parse text-format messages. The returned instance is thread-safe.

    - #### merge

          public static void merge(java.lang.Readable input,
                   Message.Builder builder)
                            throws java.io.IOException

      Parse a text-format message from `input` and merge the contents into `builder`.
      Throws:
        `java.io.IOException`

    - #### merge

          public static void merge(java.lang.CharSequence input,
                   Message.Builder builder)
                            throws TextFormat.ParseException

      Parse a text-format message from `input` and merge the contents into `builder`.
      Throws:
        `TextFormat.ParseException`

    - #### merge

          public static void merge(java.lang.Readable input,
                   ExtensionRegistry extensionRegistry,
                   Message.Builder builder)
                            throws java.io.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:
        `java.io.IOException`

    - #### merge

          public static void merge(java.lang.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`

    - #### escapeBytes

          public static java.lang.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 java.lang.String escapeBytes(byte[] input)

      Like `escapeBytes(ByteString)`, but used for byte array.

    - #### unescapeBytes

          public static ByteString unescapeBytes(java.lang.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`

    - #### escapeDoubleQuotesAndBackslashes

          public static java.lang.String escapeDoubleQuotesAndBackslashes(java.lang.String input)

      Escape double quotes and backslashes in a String for unicode output of a message.