Print, Audit, and Trace methods for user objects

Available only for non-system User Language objects, the Print, Audit, and Trace methods output a display of the current values of the Variable members of the method object. Introduced in Sirius Mods Version 8.0, these methods are intended as programmer debugging and auditing tools and are not intended to be a core part of applications.

As an example, to view the content of the %test object variable of your simple user class Test, you issue %test:Print:

class test public variable a is float variable b is string len 32 variable c is enumeration boolean variable d is object stringlist end public end class .... %test:Print

The result is output like this:

\* = Object Test, id=26 a = 1.4142135623731 b = "A bold fusilier came marching back through Rochester" c = False d = Object System:Stringlist, id=27 /* = Object Test, id=26

The particulars of this output format are described below.

The Print, Audit, and Trace methods are not themselves members of a particular class and are sometimes referred to as generic object methods.

Syntax

The syntax for the Print, Audit, and Trace methods is the same for each; the syntax for Print follows:

object:Print([Name=string], [Truncate=num], [Indent=num], [MaxDepth=num], [Prefix=string])

Syntax terms

object	An object variable or expression that belongs to a user-defined class.
Name	The optional Name argument (name required) is a string that is the name to be used in the object display in place of the placeholder asterisk (*) in the object-identifying information.
Truncate	The optional Truncate argument (name required) is the numeric value of the length limit for string values of member Variables in the object output display. The maximum allowed is 255, and the default length is 64. Note: For Unicode strings, the truncated length is the length in characters before character-entity substitution. See the example below.
Indent	The optional Indent argument (name required) is a numeric value that specifies the number of blank characters that precede the values of the class variables at each level in the output display. Its default is 1. For example, specifying %foo:print(indent=10) for the Test object in the introduction, above, produces: \* = Object Test, id=26 a = 1.4142135623731 b = "A bold fusilier came marching back through Rochester" c = False d = Object System:Stringlist, id=27 /* = Object Test, id=26
MaxDepth	The optional MaxDepth argument (name required) is an integer that specifies the maximum number of levels of object-expansion in the output display. If 2, for example, the contents of an object contained within the method object is expanded in a second level of the output display, but if that contained object itself contains an object, the latter is not expanded. Objects already expanded are not expanded a second time, regardless of the MaxDepth value. The default maximum level of nesting is 1, that is, objects contained within the method object are not expanded.
Prefix	The optional Prefix argument (name required) is the string value of the arbitrary characters that precede the lines in the object output display. See below for an example.

Output display

Note the following about the object output display:

\* = Object Test, id=26

• Since objects can be nested within objects, each nesting level begins with a backslash (\) in the object's start column and closes with a forward slash (/) in the same column. The closing of a nesting level repeats the object-identifying information at the start.
• The asterisk (*) in the object-identifying information that follows the slashes is a placeholder for the object variable being printed or for the expression that produced the object being printed.

  You can replace this asterisk with a value you specify using the method's Name parameter. For example: If you specify %test:print(name='%test'), the first line of the output display would be:

  \%test = Object Test, id=26

  If you specify %test:print(name="%foo (iteration " %i ")"), the first line might be:

  \%test (iteration 3) = Object Test, id=26

• The object description (Object Foo) is present to reveal the real class of the object if it is an extended object.
• The id value is the unique internal ID given to every object.

a = 1.4142135623731

Numerical values are displayed as is.

b = "A bold fusilier came marching back through Rochester"

String values are enclosed within double-quotation marks. If the current value of variable b is He said "Yesterday is history", its value in the output display is:

b = "He said ""Yesterday is history"""

The maximum string length displayed is 255, and the default is 64. You set the maximum string length with the Truncate parameter:

%test:print(truncate=20)

If a string is truncated, its value is followed by an ellipsis after a close quote:

\* = Object Test, id=26 a = 1.4142135623731 b = "A bold fusilier came"... c = False d = Object System:Stringlist, id=27 /* = Object Test, id=26

Note: For Unicode strings, the truncated length is the length in characters before character-entity substitution. If variable b above is declared as Unicode, and its value in the program is:

%test:b = 'I think I had too much π for dessert':u

The output after specifying %test:print(truncate=30) is:

b = "I think I had too much π for d":u...

c = False

Enumeration values are displayed as is.

d = Object System:Stringlist, id=27

• The system-class specific Print methods (for example, the Stringlist Print function) are not invoked inside a generic object Print expansion.
• A Null object is indicated as such:

  d = Object System:Stringlist, null

  In this case the object type is the object type of the object variable.
• If an object contains an instance of itself, the generic Print display of the object does not contain a repeated expansion of the object. For example, if variable d is declared in the class Test definition as an object of class Test, and the request contains a sequence like this:

  %test is object test ... %test:d = %test

  The %test:print output display might be:

  \* = Object Test, id=26 a = 1.4142135623731 b = "A bold fusilier came marching back through Rochester" c = False d = Object Test, id=26 (already displayed) /* = Object Test, id=26

Usage notes

• If you have defined your own Print method for a class (or define a local Print method), your methods will hide the generic Print method, and there is no workaround for this.
• These generic output methods display a class's public and private variables but not shared variables.
• You can use the generic Print, Audit, and Trace methods in User Language programs, but they are likely to be of more value in the SirFact dump reader, where you can do something like this to display the object contents:

  d %myObject:print(maxDepth=2)

  Or, if you don't need any special Print method parameters:

  d %myObject

• For the generic Audit and Trace methods especially, you may want output values to be preceded by something to make the values stand out in, say, the audit trail. The Prefix parameter causes each output line to be preceded by some arbitrary text. For example:

  %test:trace(prefix='>>>')

  Using the Test class data from above, this statement displays:

  >>>\* = Object Test, id=26 >>> a = 1.4142135623731 >>> b = "A bold fusilier came marching back through Rochester" >>> c = False >>> d = Object System:Stringlist, id=27 >>>/* = Object Test, id=26

See also

• Object oriented programming in SOUL