ILoggerFluentAtLevel

Namespace: ZCore

INTERFACE ILoggerFluentAtLevel

This interfaces contains all methods that are available for the fluent API to log messages.

AppendX methods are used to write additional text to a log message
WithX methods are used to restrict log messages from being written if conditions are not met

The fluent API means that methods of the interface can be chained like this

logger.AtInfo()
      .WithCondition(counter > 5)
      .WithRisingTrigger(boolean1)
      .Append('counter exceeds ').AppendInt(5)
      .Append(' and '.AppendParamOnOff('boolean1', boolean1')
      .LogMessage('');

Methods

Append

METHOD Append (
 [input] text : ZString) : ILoggerFluentAtLevelWith

The Append method can be used to add text to the end of a string represented to the StringBuilder. The following example uses a StringBuilder to write Velocity = 5.4 mm/s into the text variable. Usage:

 _stringBuilder : ZAux.StringBuilder;
 _text : ZCore.ZString;
 ---------------------------------------
 _text := _stringBuilder.Append('Velocity = ').AppendReal(5.4444, 1).Append(' mm/s').ToString();

For already instantiated strings, it is faster to use the AppendRef method instead. This method, however, should be used if dealing with rvalues (temporary strings)

If a string is appended to the current string, which would exceed 255 characters (see ZString, the string is cut off and the last characters are set to ' ...'

Inputs

text ZString

Returns

ILoggerFluentAtLevelWith

AppendBool

METHOD AppendBool (
 [input] val : BOOL) : ILoggerFluentAtLevelWith

Append a BOOL in the form of True or False to a string. There exist more ways to append a bool variable, which result in slightly different appended strings.

METHOD	val	Appended STRING
AppendBool	TRUE	True
AppendBool	FALSE	False
AppendOnOff	TRUE	On
AppendOnOff	FALSE	Off
AppendYesNo	TRUE	Yes
AppendYesNo	FALSE	No

_stringBuilder : ZAux.StringBuilder;
_io1 : BOOL := TRUE;
_io2 : BOOL := FALSE;
_text : ZCore.ZString
---------------------------------------
_text := _stringBuilder.AppendBool(_io1).ToString(); // adds the text 'True' to the string
_text := _stringBuilder.AppendBool(_io2).ToString(); // adds the text 'False' to the string

See Append for details about appending.

Inputs

val BOOL

Returns

ILoggerFluentAtLevelWith

AppendDint

METHOD AppendDint (
 [input] val : DINT) : ILoggerFluentAtLevelWith

Append a DINT primitive type to the string.

_stringBuilder : ZAux.StringBuilder;
_answer : DINT := 42;
_text : ZCore.ZString;
 ---------------------------------------
_text := _stringBuilder.AppendDint(_answer).ToString(); // adds the text '42' to the string

See Append for details.

Inputs

val DINT

Returns

ILoggerFluentAtLevelWith

AppendError

METHOD AppendError (
 [input] error : IError) : ILoggerFluentAtLevelWith

This Append method can be used to return a detailed error summary for an object that failed. It is mainly used within the Zeugwerk Framework context and therefore easy to use.

 _stringBuilder : ZAux.StringBuilder;
 _ctrl : ZEquipment.OnOffController;
 ---------------------------------------
_stringBuilder.AppendError(_ctrl).ToString(); // adds the actual ongoing ErrorMessage to the string

Inputs

error IError

Returns

ILoggerFluentAtLevelWith

AppendFormat

METHOD AppendFormat (
 [input] arg : ANY,
 [input] format : ZString) : ILoggerFluentAtLevelWith

This method can be used to add text to the end of a string represented to the StringBuilder It supports formatting with the usual printf syntax ('%d', '%3.3f') The argument arg may be a primitive, numeric variable (e.g. INT, DINT, LREAL).

Usage:

 _stringBuilder : ZAux.StringBuilder;
 _text : STRING(255);
 _value : REAL := 42.0123;
 ---------------------------------------
 _text := _stringBuilder.Append('Velocity = ').AppendFormat(_value, 1).Append(' mm/s').ToString();

Inputs

arg ANY

format ZString

i.e '%d', '%3.3f'

Returns

ILoggerFluentAtLevelWith

AppendInt

METHOD AppendInt (
 [input] val : INT) : ILoggerFluentAtLevelWith

Append an INT primitive type to the string.

_stringBuilder : ZAux.StringBuilder;
_answer : INT := 42;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendInt(_answer).ToString(); // adds the text '42' to the string

See Append for details.

Inputs

val INT

Returns

ILoggerFluentAtLevelWith

AppendLreal

METHOD AppendLreal (
 [input] val : LREAL,
 [input] decimalPlaces : SINT) : ILoggerFluentAtLevelWith

Append a floating-point type to the string. The number of decimal places that should be used can be configured with an additional parameter. The number of decimals can actually be negative (-1) to prevent the decimal point from showing up.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.Append('Value: ').AppendLreal(4, 0).ToString(); > returns 'Value: 4.'
_text := _stringBuilder.Append('Value: ').AppendLreal(4, -1).ToString(); > returns 'Value: 4'
_text := _stringBuilder.Append('Value: ').AppendLreal(4, 3).ToString(); > returns 'Value: 4.000'

See Append for details.

Inputs

val LREAL
decimalPlaces SINT

Returns

ILoggerFluentAtLevelWith

AppendOnOff

METHOD AppendOnOff (
 [input] val : BOOL) : ILoggerFluentAtLevelWith

Append a BOOL in the form of On or Off to a string. There exist more ways to append a bool variable, which result in slightly different appended strings.

_stringBuilder : ZAux.StringBuilder;
_io1 : BOOL := TRUE;
_io2 : BOOL := FALSE;
_text : ZCore.ZString;
 ---------------------------------------
_text := _stringBuilder.AppendOnOff(_io1).ToString(); // adds the text 'On' to the string
_text := _stringBuilder.AppendOnOff(_io2).ToString(); // adds the text 'Off' to the string

See AppendBool for variants of appending bools. See Append for details about appending.

Inputs

val BOOL

Returns

ILoggerFluentAtLevelWith

AppendParamBool

METHOD AppendParamBool (
 [input] name : STRING,
 [input] val : BOOL) : ILoggerFluentAtLevelWith

Append a parameter with value type BOOL in the form of True or False to a string. This is especially useful for logging parameters. For adding the boolean, internally the method AppendBool is used.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendParamBool('Parameter 1', TRUE).ToString(); // adds the text 'Parameter 1: True' to the string
_text := _stringBuilder.AppendParamBool('Parameter 2', FALSE).ToString(); // adds the text 'Parameter 2: False' to the string

See Append for details.

Inputs

name STRING
val BOOL

Returns

ILoggerFluentAtLevelWith

AppendParamDint

METHOD AppendParamDint (
 [input] name : STRING,
 [input] val : DINT,
 [input] unit : STRING(10)) : ILoggerFluentAtLevelWith

Append a parameter with value type DINT to the string. This is especially useful for logging parameters.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendParamDint('Parameter 1', 5, 'mm').ToString(); // adds the text 'Parameter 1: 5mm' to the string

See Append for details.

Inputs

name STRING
val DINT
unit STRING(10)

Returns

ILoggerFluentAtLevelWith

AppendParamInt

METHOD AppendParamInt (
 [input] name : STRING,
 [input] val : INT,
 [input] unit : STRING(10)) : ILoggerFluentAtLevelWith

Append a parameter with value type INT to the string. This is especially useful for logging parameters.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendParamInt('Parameter 1', 5, 'mm').ToString(); // adds the text 'Parameter 1: 5mm' to the string

See Append for details.

Inputs

name STRING
val INT
unit STRING(10)

Returns

ILoggerFluentAtLevelWith

AppendParamLreal

METHOD AppendParamLreal (
 [input] name : STRING,
 [input] val : LREAL,
 [input] decimalPlaces : SINT,
 [input] unit : STRING(10)) : ILoggerFluentAtLevelWith

Append a parameter with value type LREAL to the string. This is especially useful for logging parameters. The number of decimal places that should be used can be configured with an additional parameter. The number of decimals can actually be negative (-1) to prevent the decimal point from showing up.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendParamLreal('Value', val:=5, decimalPlaces:=-1, unit:='mm').ToString();  // returns 'Value: 5mm'
_text := _stringBuilder.AppendParamLreal('Value', val:=5, decimalPlaces:=-3, unit:='deg').ToString();  // returns 'Value: 5.000deg'

See Append for details.

Inputs

name STRING
val LREAL
decimalPlaces SINT
unit STRING(10)

Returns

ILoggerFluentAtLevelWith

AppendParamOnOff

METHOD AppendParamOnOff (
 [input] name : STRING,
 [input] val : BOOL) : ILoggerFluentAtLevelWith

Append a parameter with value type BOOL in the form of On or Off to a string. This is especially useful for logging parameters. For adding the boolean, internally the method AppendBool is used.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendParamOnOff('Parameter 1', TRUE).ToString(); // adds the text 'Parameter 1: On' to the string
_text := _stringBuilder.AppendParamOnOff('Parameter 2', FALSE).ToString(); // adds the text 'Parameter 2: Off' to the string

See Append for details.

Inputs

name STRING
val BOOL

Returns

ILoggerFluentAtLevelWith

AppendParamReal

METHOD AppendParamReal (
 [input] name : STRING,
 [input] val : REAL,
 [input] decimalPlaces : SINT,
 [input] unit : STRING(10)) : ILoggerFluentAtLevelWith

Append a parameter with value type REAL to the string. This is especially useful for logging parameters. The number of decimal places that should be used can be configured with an additional parameter. The number of decimals can actually be negative (-1) to prevent the decimal point from showing up.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendParamReal('Value', val:=5, decimalPlaces:=-1, unit:='mm').ToString();  // returns 'Value: 5mm'
_text := _stringBuilder.AppendParamReal('Value', val:=5, decimalPlaces:=-3, unit:='deg').ToString();  // returns 'Value: 5.000deg'

See Append for details.

Inputs

name STRING
val REAL
decimalPlaces SINT
unit STRING(10)

Returns

ILoggerFluentAtLevelWith

AppendParamString

METHOD AppendParamString (
 [input] name : STRING,
 [input] str : STRING) : ILoggerFluentAtLevelWith

Append a string parameter to the string. This is especially useful for logging parameters.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendParamDint('Parameter 1', 'Value 1').ToString(); // adds the text 'Parameter 1: Value 1' to the string

See Append for details.

Inputs

name STRING
str STRING

Returns

ILoggerFluentAtLevelWith

AppendParamUdint

METHOD AppendParamUdint (
 [input] name : STRING,
 [input] val : UDINT,
 [input] unit : STRING(10)) : ILoggerFluentAtLevelWith

Append a parameter with value type INT to the string. This is especially useful for logging parameters.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendParamUdint('Parameter 1', 5, 'mm').ToString(); // adds the text 'Parameter 1: 5mm' to the string

See Append for details.

Inputs

name STRING
val UDINT
unit STRING(10)

Returns

ILoggerFluentAtLevelWith

AppendParamUint

METHOD AppendParamUint (
 [input] name : STRING,
 [input] val : UINT,
 [input] unit : STRING(10)) : ILoggerFluentAtLevelWith

Append a parameter with value type UINT to the string. This is especially useful for logging parameters.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendParamUint('Parameter 1', 5, 'mm').ToString(); // adds the text 'Parameter 1: 5mm' to the string

See Append for details.

Inputs

name STRING
val UINT
unit STRING(10)

Returns

ILoggerFluentAtLevelWith

AppendParamUlint

METHOD AppendParamUlint (
 [input] name : STRING,
 [input] val : ULINT,
 [input] unit : STRING(10)) : ILoggerFluentAtLevelWith

Append a parameter with value type ULINT to the string. This is especially useful for logging parameters.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendParamUlint('Parameter 1', 5, 'mm').ToString(); // adds the text 'Parameter 1: 5mm' to the string

See Append for details.

Inputs

name STRING
val ULINT
unit STRING(10)

Returns

ILoggerFluentAtLevelWith

AppendParamYesNo

METHOD AppendParamYesNo (
 [input] name : STRING,
 [input] val : BOOL) : ILoggerFluentAtLevelWith

Append a parameter with value type BOOL in the form of Yes or No to a string. This is especially useful for logging parameters. For adding the boolean, internally the method AppendBool is used.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendParamYesNo('Parameter 1', TRUE).ToString(); // adds the text 'Parameter 1: Yes' to the string
_text := _stringBuilder.AppendParamYesNo('Parameter 2', FALSE).ToString(); // adds the text 'Parameter 1: No' to the string

See Append for details.

Inputs

name STRING
val BOOL

Returns

ILoggerFluentAtLevelWith

AppendReal

METHOD AppendReal (
 [input] val : REAL,
 [input] decimalPlaces : SINT) : ILoggerFluentAtLevelWith

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString;
---------------------------------------
 _text := _stringBuilder.Append('Value: ').AppendReal(4, 0).ToString();
returns 'Value: 4.'
 _text := _stringBuilder.Append('Value: ').AppendReal(4, -1).ToString();
returns 'Value: 4'
 _text := _stringBuilder.Append('Value: ').AppendReal(4, 3).ToString();
returns 'Value: 4.000'

Please note that for the previous example it is also useful to use AppendParamReal.

See Append for details.

Inputs

val REAL
decimalPlaces SINT

Returns

ILoggerFluentAtLevelWith

AppendRef

METHOD AppendRef (
 [input] text : REFERENCE TO ZString) : ILoggerFluentAtLevelWith

see Append

Inputs

text REFERENCE TO ZString

Returns

ILoggerFluentAtLevelWith

AppendUdint

METHOD AppendUdint (
 [input] val : UDINT) : ILoggerFluentAtLevelWith

Append an UDINT primitive type to the string.

_stringBuilder : ZAux.StringBuilder;
_answer : UDINT := 42;
_text : ZCore.ZString;
---------------------------------------
_text := _stringBuilder.AppendUdInt(_answer).ToString(); // adds the text '42' to the string

See Append for details.

Inputs

val UDINT

Returns

ILoggerFluentAtLevelWith

AppendUint

METHOD AppendUint (
 [input] val : UINT) : ILoggerFluentAtLevelWith

Append an UINT primitive type to the string.

_stringBuilder : ZAux.StringBuilder;
_answer : UINT := 42;
_text : ZCore.ZString;
---------------------------------------
_stringBuilder.AppendUint(_answer).ToString(); // adds the text '42' to the string

See Append for details.

Inputs

val UINT

Returns

ILoggerFluentAtLevelWith

AppendUlint

METHOD AppendUlint (
 [input] val : ULINT) : ILoggerFluentAtLevelWith

Append an ULINT primitive type to the string.

_stringBuilder : ZAux.StringBuilder;
_answer : ULINT := 424242;
_text : ZCore.ZString;
---------------------------------------
_stringBuilder.Append('Answer: ').AppendUlint(_answer).ToString(); // adds the text 'Answer: 424242' to the string

See Append for details.

Inputs

val ULINT

Returns

ILoggerFluentAtLevelWith

AppendUrlEncoded

METHOD AppendUrlEncoded (
 [input] text : ZString) : ILoggerFluentAtLevelWith

 _stringBuilder : ZAux.StringBuilder;
 _text : ZCore.ZString;
 ---------------------------------------
 _text := _stringBuilder.Append('Velocity = ').AppendReal(5.4444, 1).Append(' mm/s').ToString();

For already instantiated strings, it is faster to use the AppendRef method instead. This method, however, should be used if dealing with rvalues (temporary strings)

If a string is appended to the current string, which would exceed 255 characters (see ZString, the string is cut off and the last characters are set to ' ...'

In contrast to Append, this method also encodes the passed string for an URL format so that it can be used for http requests.

Inputs

text ZString

Returns

ILoggerFluentAtLevelWith

AppendYesNo

METHOD AppendYesNo (
 [input] val : BOOL) : ILoggerFluentAtLevelWith

Append a BOOL in the form of Yes or No to a string. There exist more ways to append a bool variable, which result in slightly different appended strings.

_stringBuilder : ZAux.StringBuilder;
_text : ZCore.ZString
 ---------------------------------------
_stringBuilder.AppendYesNo(TRUE).ToString(); // adds the text 'Yes' to the string
_stringBuilder.AppendYesNo(FALSE).ToString(); // adds the text 'No' to the string

See AppendBool for variants of appending bools. See Append for details about appending.

Inputs

val BOOL

Returns

ILoggerFluentAtLevelWith

LogMessage

METHOD LogMessage (
 [inout] text : ZString)

This method initiates to write the message that has been set up so far with the fluent API.

InOuts

text ZString

WithAnyTrigger

METHOD WithAnyTrigger (
 [input] on : BOOL) : ILoggerFluentAtLevel

Calling this method in the fluent API chain allows to restrict messages from being writing the variable on if it has not changed since the previous call, e.g.

boolean1 := FALSE;
logger.AtDebug().WithAnyTrigger(boolean1).LogMessage('hello world'); // no output
logger.AtDebug().WithAnyTrigger(boolean1).LogMessage('hello world'); // no output
boolean1 := TRUE;
logger.AtDebug().WithAnyTrigger(boolean1).LogMessage('hello world'); // 'hello world' will be written to the logger
logger.AtDebug().WithAnyTrigger(boolean1).LogMessage('hello world'); // no output
boolean1 := FALSE;
logger.AtDebug().WithAnyTrigger(boolean1).LogMessage('hello world'); // 'hello world' will be written to the logger
logger.AtDebug().WithAnyTrigger(boolean1).LogMessage('hello world'); // no output

Inputs

on BOOL

Returns

ILoggerFluentAtLevel

WithButtonPressed

METHOD WithButtonPressed (
 [input] input : REFERENCE TO BOOL) : ILoggerFluentAtLevel

Calling this method in the fluent API chain allows to restrict messages from being writing ifinput=FALSE. In the case that input=TRUE, the variable will be reset to FALSE as it is commonly done in PLCs with buttons, e.g.

IF input
THEN
  input := FALSE;
  // additional code
END_IF

Inputs

input REFERENCE TO BOOL

Returns

ILoggerFluentAtLevel

WithCondition

METHOD WithCondition (
 [input] condition : BOOL) : ILoggerFluentAtLevel

Calling this method in the fluent API chain allows to restrict messages from being writing if the condition is not met, e.g.

integer1 := 3;
logger.AtDebug().WithCondition(integer1 >= 5).LogMessage('hello world'); // no output
integer1 := 4;
logger.AtDebug().WithCondition(integer1 >= 5).LogMessage('hello world'); // no output
integer1 := 5;
logger.AtDebug().WithCondition(integer1 >= 5).LogMessage('hello world'); // 'hello world' will be written to the logger
integer1 := 6;
logger.AtDebug().WithCondition(integer1 >= 5).LogMessage('hello world'); // 'hello world' will be written to the logger

Inputs

condition BOOL

Returns

ILoggerFluentAtLevel

WithFallingTrigger

METHOD WithFallingTrigger (
 [input] on : BOOL) : ILoggerFluentAtLevel

Calling this method in the fluent API chain allows to restrict messages from being writing the variable on if it did not change to FALSE with respect to the last call to the method.

boolean1 := FALSE;
logger.AtDebug().WithAnyTrigger(boolean1).LogMessage('hello world'); // no output
logger.AtDebug().WithAnyTrigger(boolean1).LogMessage('hello world'); // no output
boolean1 := TRUE;
logger.AtDebug().WithAnyTrigger(boolean1).LogMessage('hello world'); // no output
logger.AtDebug().WithAnyTrigger(boolean1).LogMessage('hello world'); // no output
boolean1 := FALSE;
logger.AtDebug().WithAnyTrigger(boolean1).LogMessage('hello world'); // 'hello world' will be written to the logger
logger.AtDebug().WithAnyTrigger(boolean1).LogMessage('hello world'); // no output

Inputs

on BOOL

Returns

ILoggerFluentAtLevel

WithRisingTrigger

METHOD WithRisingTrigger (
 [input] on : BOOL) : ILoggerFluentAtLevel

Calling this method in the fluent API chain allows to restrict messages from being writing the variable on if it did not change to TRUE with respect to the last call to the method.

boolean1 := FALSE;
logger.AtDebug().WithAnyTrigger(boolean1).LogMessage('hello world'); // no output
logger.AtDebug().WithAnyTrigger(boolean1).LogMessage('hello world'); // no output
boolean1 := TRUE;
logger.AtDebug().WithAnyTrigger(boolean1).LogMessage('hello world'); // 'hello world' will be written to the logger
logger.AtDebug().WithAnyTrigger(boolean1).LogMessage('hello world'); // no output
boolean1 := FALSE;
logger.AtDebug().WithAnyTrigger(boolean1).LogMessage('hello world'); // no output
logger.AtDebug().WithAnyTrigger(boolean1).LogMessage('hello world'); // no output

Inputs

on BOOL

Returns