ILoggerFluentAtLevel

Namespace: ZCore

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('');

INTERFACE ILoggerFluentAtLevel

Methods

Append

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 ' ...'

METHOD Append (
 text : ZString) : ILoggerFluentAtLevelWith

Inputs

text ZString

Returns

ILoggerFluentAtLevelWith

AppendBool

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.

METHOD AppendBool (
 val : BOOL) : ILoggerFluentAtLevelWith

Inputs

val BOOL

Returns

ILoggerFluentAtLevelWith

AppendDint

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.

METHOD AppendDint (
 val : DINT) : ILoggerFluentAtLevelWith

Inputs

val DINT

Returns

ILoggerFluentAtLevelWith

AppendError

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

METHOD AppendError (
 error : IError) : ILoggerFluentAtLevelWith

Inputs

error IError

Returns

ILoggerFluentAtLevelWith

AppendFormat

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();

METHOD AppendFormat (
 arg : ANY,
 format : ZString) : ILoggerFluentAtLevelWith

Inputs

arg ANY

format ZString

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

Returns

ILoggerFluentAtLevelWith

AppendInt

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.

METHOD AppendInt (
 val : INT) : ILoggerFluentAtLevelWith

Inputs

val INT

Returns

ILoggerFluentAtLevelWith

AppendLreal

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.

METHOD AppendLreal (
 val : LREAL,
 decimalPlaces : SINT) : ILoggerFluentAtLevelWith

Inputs

val LREAL
decimalPlaces SINT

Returns

ILoggerFluentAtLevelWith

AppendOnOff

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.

METHOD AppendOnOff (
 val : BOOL) : ILoggerFluentAtLevelWith

Inputs

val BOOL

Returns

ILoggerFluentAtLevelWith

AppendParamBool

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.

METHOD AppendParamBool (
 name : STRING,
 val : BOOL) : ILoggerFluentAtLevelWith

Inputs

name STRING
val BOOL

Returns

ILoggerFluentAtLevelWith

AppendParamDint

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.

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

Inputs

name STRING
val DINT
unit STRING(10)

Returns

ILoggerFluentAtLevelWith

AppendParamInt

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.

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

Inputs

name STRING
val INT
unit STRING(10)

Returns

ILoggerFluentAtLevelWith

AppendParamLreal

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.

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

Inputs

name STRING
val LREAL
decimalPlaces SINT
unit STRING(10)

Returns

ILoggerFluentAtLevelWith

AppendParamOnOff

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.

METHOD AppendParamOnOff (
 name : STRING,
 val : BOOL) : ILoggerFluentAtLevelWith

Inputs

name STRING
val BOOL

Returns

ILoggerFluentAtLevelWith

AppendParamReal

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.

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

Inputs

name STRING
val REAL
decimalPlaces SINT
unit STRING(10)

Returns

ILoggerFluentAtLevelWith

AppendParamString

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.

METHOD AppendParamString (
 name : STRING,
 str : STRING) : ILoggerFluentAtLevelWith

Inputs

name STRING
str STRING

Returns

ILoggerFluentAtLevelWith

AppendParamUdint

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.

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

Inputs

name STRING
val UDINT
unit STRING(10)

Returns

ILoggerFluentAtLevelWith

AppendParamUint

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.

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

Inputs

name STRING
val UINT
unit STRING(10)

Returns

ILoggerFluentAtLevelWith

AppendParamUlint

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.

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

Inputs

name STRING
val ULINT
unit STRING(10)

Returns

ILoggerFluentAtLevelWith

AppendParamYesNo

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.

METHOD AppendParamYesNo (
 name : STRING,
 val : BOOL) : ILoggerFluentAtLevelWith

Inputs

name STRING
val BOOL

Returns

ILoggerFluentAtLevelWith

AppendReal

_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.

METHOD AppendReal (
 val : REAL,
 decimalPlaces : SINT) : ILoggerFluentAtLevelWith

Inputs

val REAL
decimalPlaces SINT

Returns

ILoggerFluentAtLevelWith

AppendRef

see Append

METHOD AppendRef (
 text : REFERENCE TO ZString) : ILoggerFluentAtLevelWith

Inputs

text REFERENCE TO ZString

Returns

ILoggerFluentAtLevelWith

AppendUdint

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.

METHOD AppendUdint (
 val : UDINT) : ILoggerFluentAtLevelWith

Inputs

val UDINT

Returns

ILoggerFluentAtLevelWith

AppendUint

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.

METHOD AppendUint (
 val : UINT) : ILoggerFluentAtLevelWith

Inputs

val UINT

Returns

ILoggerFluentAtLevelWith

AppendUlint

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.

METHOD AppendUlint (
 val : ULINT) : ILoggerFluentAtLevelWith

Inputs

val ULINT

Returns

ILoggerFluentAtLevelWith

AppendUrlEncoded

 _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.

METHOD AppendUrlEncoded (
 text : ZString) : ILoggerFluentAtLevelWith

Inputs

text ZString

Returns

ILoggerFluentAtLevelWith

AppendYesNo

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.

METHOD AppendYesNo (
 val : BOOL) : ILoggerFluentAtLevelWith

Inputs

val BOOL

Returns

ILoggerFluentAtLevelWith

LogMessage

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

METHOD LogMessage (
 text : ZString)

Inouts

text ZString

WithAnyTrigger

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

METHOD WithAnyTrigger (
 on : BOOL) : ILoggerFluentAtLevel

Inputs

on BOOL

Returns

ILoggerFluentAtLevel

WithButtonPressed

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

METHOD WithButtonPressed (
 input : REFERENCE TO BOOL) : ILoggerFluentAtLevel

Inputs

input REFERENCE TO BOOL

Returns

ILoggerFluentAtLevel

WithCondition

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

METHOD WithCondition (
 condition : BOOL) : ILoggerFluentAtLevel

Inputs

condition BOOL

Returns

ILoggerFluentAtLevel

WithFallingTrigger

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

METHOD WithFallingTrigger (
 on : BOOL) : ILoggerFluentAtLevel

Inputs

on BOOL

Returns

ILoggerFluentAtLevel

WithRisingTrigger

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

METHOD WithRisingTrigger (
 on : BOOL) : ILoggerFluentAtLevel

Inputs

on BOOL

Returns