TextFormat

public struct TextFormat : OutputStreamFormatter

The TextFormat is a configurable implementation of a OutputStreamFormatter which allows complete control over the fields and format of the output log entry.

Since the TextFormat is an instance of OutputStreamFormatter it can be used with any Writer that accepts the OutputStreamFormatter on construction.

TextFormat has a number of options for configuring it for many use-cases. All options have a default value assigned to them to make it easy to get started without configuration. Should refinement of the default behavior be required, these options give you fine grain control over the output.

Output Templates

The primary control of the formatting is through the template parameter which defines the output variables and constants for each logged entry. The template parameter is a Swift.String that allows any constants plus substitution variables that specify the various fields that TraceLog can output.

Substitution variables take the form %{variable-name} and are case sensitive. Each variable can be used within the template String as many times as your use-case requires.

  • Substitution variables:
    • %{date}
    • %{timestamp}
    • %{level}
    • %{tag}
    • %{processName}
    • %{processIdentifier}
    • %{threadIdentifier}
    • %{file}
    • %{function}
    • %{line}
    • %{message}

The default template is a human-readable form meant for debugging purposes and excludes extraneous details such as file, function and line. It is defined as:

template: "%{date} %{processName}[%{processIdentifier}:%{threadIdentifier}] %{level}: <%{tag}> %{message}"

Which produces an output similar to this:

1970-01-01 00:00:00.000 ExampleProcess[100:1100] INFO: <ExampleTag> Example message.

You can easily create other output forms such as TAB DELIMITED using this template (and adjusting the number of fields to your requirements).

template: "\"%{date}\",\"%{processName}\",%{processIdentifier},%{threadIdentifier},\"%{level}\",\"%{tag}\",\"%{message}\""

Your output would look similar to this given the same input as above:

"1970-01-01 00:00:00.000","ExampleProcess",50,200,"WARNING","ExampleTag","Example message.”

Control Characters

TraceLog allows you to embed formatting control characters (\r\n\t) into the message when logging messages. The TextFormat allows you to strip those out or escape them so that the output can be more concise or machine readable if required.

Logging a statement like this is great for reading on the console but could cause issues with parsing a format that requires analyzing the entries.

let formatter = TextFormat(options: [.controlCharacters(.strip)])

TraceLog.configure(writers: [ConsoleWriter(format: formatter)])

logInfo { "\n\t\tThis is a message with control characters that spans multiple lines \n\t\tand is indented with several tab characters." }

Using .controlCharacters(.strip) will allow you to strip those out before output, giving you the following output in the console or file.

1970-01-01 00:00:00.000 ExampleProcess[100:1100] INFO: <ExampleTag> This is a message with control characters that spans multiple lines and is indented with several tab characters.

Using .controlCharacters(.escape) will allow you to escape (\) the characters for output to writers that may require escaping of control characters.

1970-01-01 00:00:00.000 ExampleProcess[100:1100] INFO: <ExampleTag> \\n\\t\\tThis is a message with control characters that spans multiple lines \\n\\t\\tand is indented with several tab characters.

Without this option the output would look like this.

1970-01-01 00:00:00.000 ExampleProcess[100:1100] INFO: <ExampleTag>
        This is a message with control characters that spans multiple lines
        and is indented with several tab characters.

Note: using this option does not affect the terminator output, terminators will still be printed normally.

Character Encoding

The default character encoding of the output is .utf8 which should be suitable for most applications and can encode all the unicode characters.

If required, this encoding can be changed by passing a String.Encoding value at init to change the output encoding.

For instance.

let format = TextFormat(encoding: .utf16)

Any one of the encodings defined by String.Encoding can be used but if you’re logging characters outside the range that the encoding can encode, the formatter will alter or drop (replacing with a placeholder character within the encoding) the character.

If only logging characters within the Ascii character encoding (characters from 0-127) all encodings accept .symbol can be used.

If logging characters outside the Ascii range (0-127), it’s recommended that you use a unicode compatible encoding. All the following encodings can completely encode Unicode:

  • unicode
  • utf8
  • utf16
  • utf16BigEndian
  • utf16LittleEndian
  • utf32
  • utf32BigEndian
  • utf32LittleEndian

  • Note

    We don’t find .symbol very useful due to it’s limited character range and is not supported on linux. .japaneseEUC is also not supported on Linux.

    Terminators

    Each log entry formatted by the formatter can be terminated with a character sequence. The default value is a newline (\n) and can be changed by passing the terminator parameter at construction.

    For instance.

    let formatter = TextFormat(terminator: "\r\n")
    

    In this case we changed the terminator from the default of \n to \r\n. The characters can be any characters that make sense for your application. Keep in mind that for console or file type output, a newline \n is required in order to write multiple lines to the screen or file.

    See also

    OutputStreamFormatter for more information about the base class.
    • The designated initializer for this type.

      See also

      TextFormat.Default for default values to for this class.

      See also

      TextFormat.Option for a list of available options.

      Declaration

      Swift

      public init(template: String = Default.template, dateFormatter: DateFormatter = Default.dateFormatter, options: Set<Option> = Default.options, encoding: String.Encoding = Default.encoding, terminator: String = Default.terminator)

      Parameters

      template

      The template to use to format the log entry.

      dateFormatter

      An instance of a DateFormatter to convert timestamps to dates.

      options

      A Set of Options to allow optional formatting control (see Option for list).

      encoding

      The Character encoding to use for the formatted entry.

      terminator

      A string that will be output at the end of the output to terminate the entry.

    • Special options available to control the output of TextFormat.

      See more

      Declaration

      Swift

      public enum Option : Hashable