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:
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
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 (seeOption
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.
-
The encoding that will be used to encode the
message
attribute of theWriter.LogEntry
and the entire message if this is a String type output.Declaration
Swift
public let encoding: String.Encoding
-
Text conversion function required by the
OutputStreamFormatter
protocol.See also
OutputStreamFormatter
for more information about this function.Declaration
Swift
public func bytes(from entry: Writer.LogEntry) -> Result<[UInt8], OutputStreamFormatterError>
-
Default values used for
See moreTextFormat
Declaration
Swift
public enum Default
-
Special options available to control the output of
See moreTextFormat
.Declaration
Swift
public enum Option : Hashable