Home Contents | # mtd16:trace | Mtd16 | Core4 Lua Commands

## SYNOPSIS

text = msg:trace()

## DESCRIPTION

The trace() command converts msg into human readable text useful for debugging. It makes use of the various lookup tables like mtd16.lutTag and others to generate useful output. Tag names are prefixed with an indicator of their type.

Calling a message in string context will automatically call the trace() function.

### Lookup tables

For each tag inside the message the trace function does a reverse lookup into mtd16.lutTag. If successful, the name is decorated with the data type of the contents and printed. If unsuccessful, the tag is printed hexadecimal, prefixed with 0x.

If the first lookup provided a name and a lookup table mtd16.lutName exists, the value of the field is looked up reverse in that table. When successful, the printed value is replaced by the value found in the lookup table.

### Filtering

If a function named mtd16.filterTrace(messageCode, tag, value) has been defined, it is called for each value. When the function returns non-nil, the function result is printed instead of the actual value. This is useful if sensitive data must be hidden from debug, e.g. passwords and keys.

## RETURN VALUE

A human readable string representation of msg.

## NOTES

The output of this function is meant for human consumption. Do not automatically process this text. If you need machine readable text, use mtd16:toText().

## EXAMPLE

Note how 1 is replaced by busy due to mtd16.lutFnord.

> > > > > >
mtd16.lutTag = { Test = 0xF00F, Fnord = 0x3001, State=0x1001 } mtd16.lutState = { idle = 0, busy = 1 } msg = mtd16.new("Test") msg:append("Fnord", "xyzzy") msg:append("State", 1) print(msg)
msgTest=(sFnord="xyzzy" iState=busy)

## SEE ALSO

#mtd16, mtd16.answerCode, mtd16.fromData, mtd16.fromText, mtd16.isNestedTag, mtd16.lutType, mtd16.new, mtd16.tagCode, mtd16.tagName, mtd16.tagNumber, mtd16.tagType, mtd16:append, mtd16:appendMessageCode, mtd16:contains, mtd16:get, mtd16:getNumber, mtd16:getString, mtd16:isEmpty, mtd16:isValid, mtd16:messageCode, mtd16:nextMessageCode, mtd16:pairs, mtd16:rewind, mtd16:tags, mtd16:toData, mtd16:toText