YOUSEFUL / DELPHI / COMPONENTS

`TAtlasTextFormatter`

Formats an event as one line of text from a pattern of tokens.

Class Unit Atlas.LogFormat · Inherits TAtlasLogFormatter · Product Atlas Log

Description

Used by the text sinks and the viewer; create one yourself to format events from a memory sink. The pattern is parsed once into tokens. Tokens, in braces, names ignoring case:

{time}, {time:mask}: local time, formatted with FormatDateTime (default mask yyyy-mm-dd hh:nn:ss.zzz); {utc}, {utc:mask}: the same in UTC.
{level} (warning), {level:short} (WRN), {seq}, {thread}.
{category}, {scope} (in brackets, [import/row 7]), {message}.
{exception}: | EClass: text when there is one; {props}: {name=value, ...} when there are any.

{{ and }} are literal braces. A token that renders empty also drops one neighbouring space, so optional parts leave no double spaces, and trailing spaces are removed. Masks use the program's format settings: : and / in a mask are the locale's time and date separators; quote them (hh":"nn) for fixed output.

Members

Member	Kind	What it does
`DefaultPattern`	field	The pattern used when none is given, and the default of the text sinks.
`Create`	constructor	Creates a formatter with `APattern`, or `DefaultPattern` when it is empty, and `EscapeLineBreaks = True`.
`Format`	method	The event as one line, without a line break.
`Pattern`	property	The pattern.
`EscapeLineBreaks`	property	On by default: CR LF, LF and CR in the category, scope, message, exception message and properties are written as `\n`, so a message cannot forge extra log lines.

Constructors

`Create` constructor

constructor Create(const APattern: string = '');

Creates a formatter with APattern, or DefaultPattern when it is empty, and EscapeLineBreaks = True. An invalid pattern raises EAtlasLogError.

Properties

`Pattern` property

property Pattern: string read FPattern write SetPattern;

The pattern. An unknown token, an unterminated { or a single } raises EAtlasLogError, and the previous pattern stays.

`EscapeLineBreaks` property

property EscapeLineBreaks: Boolean read FEscapeLineBreaks write FEscapeLineBreaks;

On by default: CR LF, LF and CR in the category, scope, message, exception message and properties are written as \n, so a message cannot forge extra log lines. Turn it off only for output that is not read line by line. The text sinks always escape.

Methods

`Format` method

function Format(const Event: TAtlasLogEvent): string; override;

The event as one line, without a line break.

Fields

`DefaultPattern` field

const DefaultPattern = '{time:yyyy-mm-dd hh:nn:ss.zzz} [{level:short}] {category} {scope} {message}{exception}{props}';

The pattern used when none is given, and the default of the text sinks.

Examples

Export recent events as text

Formats a memory sink with a custom pattern and saves it.

uses System.SysUtils, System.IOUtils, Atlas.Log, Atlas.LogFormat, Atlas.LogSinks;

procedure SaveAsText(Memory: TAtlasMemorySink; const FileName: string);
var
  Formatter: TAtlasTextFormatter;
  Events: TArray<TAtlasLogEvent>;
  Lines: TArray<string>;
  I: Integer;
begin
  Formatter := TAtlasTextFormatter.Create('{utc:yyyy-mm-dd"T"hh":"nn":"ss"Z"} {level:short} {seq} {category} {message}{exception}');
  try
    Events := Memory.Snapshot;
    SetLength(Lines, Length(Events));
    for I := 0 to High(Events) do Lines[I] := Formatter.Format(Events[I]);
    TFile.WriteAllLines(FileName, Lines, TEncoding.UTF8);
  finally
    Formatter.Free;
  end;
end;

TAtlasLogFormatter · TAtlasJsonFormatter · TAtlasTextSink · TAtlasLogView

Also in Atlas Log

TAtlasLogger · TAtlasMemorySink · TAtlasCallbackSink · TAtlasConsoleSink · TAtlasDebugSink · TAtlasFileSink · TAtlasAsyncSink · TAtlasLogView

TAtlasTextFormatter