Diagnostics

As TADS 3 and Proteus develop, debugging tools specifically designed to take advantage of TADS 3 metadata and reflection features will be put into this module.

Referencing Game Objects in Meta-Commands

Proteus provides three means for identifying a TadsObject class object. Any object can be referenced using commands of the format:

>metacommand <opt> reference

Where:

metacommand is a proteus metacommand, such as @save, or @show.

opt is an optional keyword: sym, tag, or voc, specifying that the reference is to be interpreted as a symbolic, an object reference tag, or a noun phrase and is only required when some ambiguity exists in identifying the reference as a symbolic, object reference tag, or noun phrase.

reference is either a symbolic, an object reference tag, or a noun phrase.

>metacommand <voc> nounPhrase

Where the object defines vocabulary, it is often convenient to use the voc (noun phrase) version of the command to display object information.

>metacommand <sym> symbolicName

Where the object does not define vocabulary using the symbolic will display its object information. The symbolic form is case-sensitive. The symbolic MyThing references a different object from myThing.

>metacommand <tag> tads#hhh

Dynamic objects or objects not defined with symbolics should be referred to by using the object reference tag. Static objects can also be referenced using object reference tags.

Using Command AHref “Drill-down”

Several of the metacommands now use object reference hyperlinks that execute the previously issued command for the object reference that the author clicks on. This allows an author to “drill down” into object inheritance, extension, and containment hierarchies.

To enable this feature make sure that link highlighting has been turned on within the interpreter.

From the menu bar go to VIEW>LINK HIGHLIGHTING>ALWAYS SHOW LINK HIGHLIGHTING.

Going to a Location or Object

The @goto metacommand moves the actor to a location, if derived from BasicLocation or to the outermost room in which the referenced object is located. The command has the following syntax:

@goto <sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)

Listing Object Information

The @list metacommand produces unordered lists and has the following syntax:

Listing Object Ancestors

The @list metacommand can produce an HTML unordered list of all the ancestors for obj. An example follows:

>@list ancestors Actor

Please wait... processing 15 entries

§ class tads#544 ( 5c7 *Actor*)

§ class tads#47a ( 4d2 *Actor*)

§ class Thing

§ class Schedulable

§ class Traveler

§ class tads#5d1 ( 656 *Thing*)

§ class tads#5d0 ( 655 *Thing*)

§ class tads#5cf ( 654 *Thing*)

§ class tads#547 ( 5cc *Thing*)

§ class tads#545 ( 5c8 *Thing*)

§ class tads#47d ( 4d5 *Thing*)

§ class VocabObject

§ class tads#31d ( 349 *VocabObject*)

§ class TadsObject

§ class Object

The syntax is:

Listing Object Children

The @list metacommand can produce an HTML unordered list of the children (immediate descendants) for obj. An example follows:

>@list child Actor

Please wait... processing 1 entries

§ class UntakeableActor

The syntax is:

Listing Object Descendants

The @list metacommand can produce an HTML unordered list of all the descendants for obj. An example follows:

>@list descendant Actor

Please wait... processing 6 entries

§ class Person

§ class UntakeableActor

§ object me

§ object bob

§ object bill

§ object tads#668 (Person)

The syntax is:

Listing Object First Named Ancestors

The @list metacommand can produce an HTML unordered list of the first named ancestors for obj. An example follows:

>@list first named ancestor Actor

Please wait... processing 3 entries

§ class Thing

§ class Schedulable

§ class Traveler

The syntax is:

Listing Object First Named Descendants

The @list metacommand can produce an HTML unordered list of the first named descendants for obj. An example follows:

>@list first named descendant Actor

Please wait... processing 1 entries

§ class UntakeableActor

The syntax is:

Listing Object Modifications

The @list metacommand can produce an HTML unordered list of the modifications (created via the modify keyword) for obj. An example follows:

>@list mod Actor

Please wait... processing 3 entries

§ class Actor

§ class tads#544 ( 5c7 *Actor*)

§ class tads#47a ( 4d2 *Actor*)

The syntax is:

Listing Object Parents

The @list metacommand can produce an HTML unordered list of the parents for obj. An example follows:

>@list parents Actor

Please wait... processing 1 entries

§ class tads#544 ( 5c7 *Actor*)

The syntax is:

Purloining an Object

Any takeable object can be purloined regardless of it’s location within the game world by using the @purloin metacommand. The syntax is:

@purloin <sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)

> @purloin dagger

You purloin the dagger.

Saving Object Information

The @save metacommand is used to save an object’s state. The command has the following syntax:

@save <sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)

@save all

Saving Object States

The @save command can save the states for all Thing class objects or for a specified object.

The syntax for saving the state for all objects is:

@save all

The syntax for saving the state for a given object is:

@save <sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)

For example, suppose we want to save the states of all Thing instances:

Entryway

This large, formal entryway is slightly intimidating: the walls are lined with somber portraits of gray-haired men from decades past; a medieval suit of armor, posed with a battle axe at the ready, towers over a single straight-backed wooden chair. The front door leads back outside to the south. A hallway leads north.

>@save all

Please wait... saving object states...

Similarly, if you want to save the state of a single object, you simply refer to the object by one of the three means:

Entryway

>@save battle axe

State saved for object axe.

Restoring Object Information

The @restore metacommand can be used to restore the states for all Thing class objects, or for a specified object, when the object state has been saved previously using the @save metacommand. The command has the following syntax:

@restore all

@restore <sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)

Restoring Object States

The @restore command can restore the states for all Thing class objects that were saved previously by the @save command. The syntax is:

@restore all

The syntax for restoring a given object is:

@restore <sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)

A sample transcript of the use of <<@save all>> and <<@restore all>> follows:

Welcome to the TADS 3 Library Sample Game!

Living Room

It's a nice, big room. A potted plant is the only attempt at decoration. Passages lead north, east, and west. To the south, the front door of the house leads outside.

An old television, a huge, boxy, massive-looking thing, sits on the floor.

You see a PO Box, a static bowl, a small red ball, a red book, an iron key, a clear jar, a green jar (which contains two copper coins), a blue test booklet, a brass key, a brown box, a tricycle, a rusty key, a green ball, an 8-ball, a large red ball, eight coins (five gold and three silver), and a morphic bowl here.

Bill is here.

Bob is here.

>@save all

Please wait... saving object states...

>take brass key

You pick up the brass key and attach it to the keyring.

>i

You are carrying a duffel bag and a keyring (with a brass key attached).

>l

Living Room

It's a nice, big room. A potted plant is the only attempt at decoration. Passages lead north, east, and west. To the south, the front door of the house leads outside.

An old television, a huge, boxy, massive-looking thing, sits on the floor.

You see a PO Box, a static bowl, a small red ball, a red book, an iron key, a clear jar, a green jar (which contains two copper coins), a blue test booklet, a brown box, a tricycle, a rusty key, a green ball, an 8-ball, a large red ball, eight coins (five gold and three silver), and a morphic bowl here.

Bill is here.

Bob is here.

>@restore all

Please wait... restoring object states...

>i

You are carrying a duffel bag and a keyring.

>l

Living Room

It's a nice, big room. A potted plant is the only attempt at decoration. Passages lead north, east, and west. To the south, the front door of the house leads outside.

An old television, a huge, boxy, massive-looking thing, sits on the floor.

You see a PO Box, a static bowl, a small red ball, a red book, an iron key, a clear jar, a green jar (which contains two copper coins), a blue test booklet, a brass key, a brown box, a tricycle, a rusty key, a green ball, an 8-ball, a large red ball, eight coins (five gold and three silver), and a morphic bowl here.

Bill is here.

Bob is here.

>Showing Object Information

The @show metacommand can be used to show various aspects of an object’s internal definition. The command has the following syntax:

§ @show <sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)

§ @show (delta|deltas) <all>

Showing Object Action Properties

The @show metacommand can produce a display of the object definition specializing in the object’s action properties. This produces a rather long display of the directly-defined action properties (verify, check, remap, action), working along the inheritance hierarchy.

The syntax is:

Showing Object Definition (Defined) Properties

The @show metacommand can produce a display of the object definition focusing on the object’s defined properties. This produces a rather long display of the directly-defined properties, working along the inheritance hierarchy.

The syntax is:

Showing Object (State) Deltas

After having saved an object states with @save command it’s possible to compare the current state of the object with its snapshot by using the @show command. This command will display the state deltas for every Thing class object, displaying the old state followed by the new state.

The syntax is:

@show (delta|deltas) <all>

Similarly, @show can be used to display the state delta for a specified object. The syntax is:

A sample transcript follows:

Entryway

This large, formal entryway is slightly intimidating: the walls are lined with somber portraits of gray-haired men from decades past; a medieval suit of armor, posed with a battle axe at the ready, towers over a single straight-backed wooden chair. The front door leads back outside to the south. A hallway leads north.

>@save all states

Saving object states...

>put axe on chair

(first taking the battle axe)

Done.

>@show all deltas

========== START TADS 3 DIAGNOSTIC ==========

State Delta: tads#58f (Fixed), suitOfArmor

tads#58f (Fixed).contents : TypeList =

[

axe

]

suitOfArmor.contents : TypeList =

[

]

========== END TADS 3 DIAGNOSTIC ============

========== START TADS 3 DIAGNOSTIC ==========

State Delta: tads#590 (Actor), me

tads#590 (Actor).nextRunTime : TypeInt = 0

me.nextRunTime : TypeInt = 1

tads#590 (Actor).nextHoldingIndex : TypeInt = 1

me.nextHoldingIndex : TypeInt = 4

tads#590 (Actor).mostRecentAction : TypeNil = nil

me.mostRecentAction : TypeObject = tads#56d (predicate(PutOn))

========== END TADS 3 DIAGNOSTIC ============

========== START TADS 3 DIAGNOSTIC ==========

State Delta: tads#591 (Thing), axe

tads#591 (Thing).location : TypeObject = suitOfArmor

axe.location : TypeObject = tads#592 (Chair, Fixed)

tads#591 (Thing).holdingIndex : TypeInt = 0

axe.holdingIndex : TypeInt = 3

tads#591 (Thing).moved : TypeNil = nil

axe.moved : TypeTrue = true

========== END TADS 3 DIAGNOSTIC ============

========== START TADS 3 DIAGNOSTIC ==========

State Delta: tads#593 (Chair, Fixed), tads#592 (Chair, Fixed)

tads#593 (Chair, Fixed).objRefTag : TypeSString = 'tads#593'

tads#592 (Chair, Fixed).objRefTag : TypeSString = 'tads#592'

tads#593 (Chair, Fixed).contents : TypeList =

[

]

tads#592 (Chair, Fixed).contents : TypeList =

[

axe

]

========== END TADS 3 DIAGNOSTIC ============

========== START TADS 3 DIAGNOSTIC ==========

State Delta: tads#594 (Chair, Fixed), tads#593 (Chair, Fixed)

tads#594 (Chair, Fixed).objRefTag : TypeSString = 'tads#594'

tads#593 (Chair, Fixed).objRefTag : TypeSString = 'tads#593'

========== END TADS 3 DIAGNOSTIC ============

========== START TADS 3 DIAGNOSTIC ==========

State Delta: tads#595 (Thing), tads#591 (Thing)

tads#595 (Thing).objRefTag : TypeSString = 'tads#595'

tads#591 (Thing).objRefTag : TypeSString = 'tads#591'

========== END TADS 3 DIAGNOSTIC ============

========== START TADS 3 DIAGNOSTIC ==========

State Delta: tads#596 (Actor), tads#590 (Actor)

tads#596 (Actor).objRefTag : TypeSString = 'tads#596'

tads#590 (Actor).objRefTag : TypeSString = 'tads#590'

========== END TADS 3 DIAGNOSTIC ============

========== START TADS 3 DIAGNOSTIC ==========

State Delta: tads#597 (Fixed), tads#58f (Fixed)

tads#597 (Fixed).objRefTag : TypeSString = 'tads#597'

tads#58f (Fixed).objRefTag : TypeSString = 'tads#58f'

========== END TADS 3 DIAGNOSTIC ============

========== START TADS 3 DIAGNOSTIC ==========

State Delta: tads#598 (Fixed), tads#597 (Fixed)

tads#598 (Fixed).objRefTag : TypeSString = 'tads#598'

tads#597 (Fixed).objRefTag : TypeSString = 'tads#597'

========== END TADS 3 DIAGNOSTIC ============

========== START TADS 3 DIAGNOSTIC ==========

State Delta: tads#599 (Actor), tads#596 (Actor)

tads#599 (Actor).objRefTag : TypeSString = 'tads#599'

tads#596 (Actor).objRefTag : TypeSString = 'tads#596'

========== END TADS 3 DIAGNOSTIC ============

========== START TADS 3 DIAGNOSTIC ==========

State Delta: tads#59a (Thing), tads#595 (Thing)

tads#59a (Thing).objRefTag : TypeSString = 'tads#59a'

tads#595 (Thing).objRefTag : TypeSString = 'tads#595'

========== END TADS 3 DIAGNOSTIC ============

========== START TADS 3 DIAGNOSTIC ==========

State Delta: tads#541 (Chair, Fixed), tads#594 (Chair, Fixed)

tads#541 (Chair, Fixed).objRefTag : TypeSString = 'tads#541'

tads#594 (Chair, Fixed).objRefTag : TypeSString = 'tads#594'

========== END TADS 3 DIAGNOSTIC ============

Showing Object Directly-Defined Properties

The @show metacommand can produce a display of the object definition specializing in the object’s directly-defined properties. An example follows:

Object me extends Person

{

DynamOrAnon: nil UnnamedInternal: nil Transient: nil

Lists: Parents Children First Named Ancestors First Named Descendants

Trees: Ancestors Descendants Containment Modifications

Properties: Defined Action State State Delta

properties directly defined by object me

bulkCapacity : TypeInt = 5

issueCommandsSynchronously : TypeTrue = true

location : TypeObject = livingRoom

nextHoldingIndex : TypeInt = 3

contents : TypeList = [duffel, keyring]

pendingCommand : TypeObject = Vector []

antecedentTable : TypeObject = LookupTable []

memoryTable : TypeObject = LookupTable [[television, true], [poBox, true], [staticBowl, true], [smallRedBall, true], [redBook, true], [ironKey, true], [clearJar, true], [greenJar, true], [tads#5cd (CopperCoin), true], [tads#5ce (CopperCoin), true], [blueBook, true], [brassKey, true], [box, true], [tricycle, true], [rustyKey, true], [greenBall, true], [eightball, true], [bigRedBall, true], [tads#5cf (SilverCoin), true], [tads#5d4 (GoldCoin), true], [tads#5d3 (GoldCoin), true], [tads#5d5 (GoldCoin), true], [tads#5d6 (GoldCoin), true], [tads#5d2 (GoldCoin), true], [tads#5d1 (SilverCoin), true], [tads#5d0 (SilverCoin), true], [morphicBowl, true], [bill, true], [bob, true], [livingRoom, true]]

objRefTag : TypeSString = 'tads#580'

tmpAmbient_ : TypeInt = 0

tmpAmbientWithin_ : TypeInt = 0

tmpAmbientFill_ : TypeNil = nil

tmpTrans_ : TypeEnum = transparent

tmpTransWithin_ : TypeEnum = transparent

tmpObstructor_ : TypeNil = nil

tmpObstructorWithin_ : TypeNil = nil

tmpFillMedium_ : TypeNil = nil

scheduleOrder : TypeInt = 100

locationBefore : TypeObject = livingRoom

locationLitBefore : TypeTrue = true

followingActor : TypeNil = nil

}

The display above is the model of all of the @show displays. The highlights (underlined and blue) produce other metacommands, depending on which part of the display they are part of.

The syntax is:

Showing an Object’s State

The @show metacommand can produce a display of the object definition specializing in the object’s state properties. This produces a rather long display of the directly-defined state properties, working along the inheritance hierarchy.

The syntax is:

Showing an Object’s properties

The @show metacommand can be used to display an object’s non-code properties. The syntax is:

@show <sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase) literalPhrase

where literalPhrase is a non-code property of the object. The display produces an object structure, if appropriate, for an object referenced by the property, and an object value. If the property refers to a non-object then only the property’s value is displayed. For instance, here’s an example of displaying the property &antecedentTable for the object me in the sample game:

>@show tag tads#582 antecedentTable

Please wait... processing: object property &antecedentTable

Object LookupTable extends LookupTable

{

DynamOrAnon: true UnnamedInternal: nil Transient: nil

Lists: Parents Children First Named Ancestors First Named Descendants

Trees: Ancestors Descendants Containment Modifications

Properties: Direct Defined Action State State Delta

}

Value

{

[]

}

And this is an example of displaying the property &isHim for the same object:

>@show me isHim

Please wait... processing: object property &isHim

Value

{

nil

}

Proteus library now includes hyperlinks for properties that have propType() TypeObject that produce the @show object property metacommand. Clicking on the hyperlink of the property value issues the command.

>@show me

Please wait... processing: directly-defined properties

Object me extends Person

{

DynamOrAnon: nil UnnamedInternal: nil Transient: nil

Lists: Parents Children First Named Ancestors First Named Descendants

Trees: Ancestors Descendants Containment Modifications

Properties: Defined Action State State Delta

properties directly defined by object me

bulkCapacity : TypeInt = 5

issueCommandsSynchronously : TypeTrue = true

location : TypeObject = livingRoom

nextHoldingIndex : TypeInt = 3

contents : TypeList = [duffel, keyring]

pendingCommand : TypeObject = Vector

antecedentTable : TypeObject = LookupTable

topicMemory : TypeObject = LookupTable

objRefTag : TypeSString = 'tads#582'

tmpAmbient_ : TypeInt = 0

tmpAmbientWithin_ : TypeInt = 0

tmpAmbientFill_ : TypeNil = nil

tmpTrans_ : TypeEnum = transparent

tmpTransWithin_ : TypeEnum = transparent

tmpObstructor_ : TypeNil = nil

tmpObstructorWithin_ : TypeNil = nil

tmpFillMedium_ : TypeNil = nil

scheduleOrder : TypeInt = 100

locationBefore : TypeObject = livingRoom

locationLitBefore : TypeTrue = true

followingActor : TypeNil = nil

mostRecentAction : TypeObject = tads#760 (predicate(ShowPropObj))

nextRunTime : TypeInt = 0

}

Clicking on the hyperlink for tads#760 (predicate(ShowPropObj) would issue the metacommand <<@show tag tads#760 mostRecentAction>> and would produce a display similar to the following:

>@show tag tads#582 mostRecentAction

Please wait... processing: object property &mostRecentAction

Object tads#796 (predicate(TreeDefinerObj)) extends predicate(TreeDefinerObj)

{

DynamOrAnon: true UnnamedInternal: nil Transient: nil

Lists: Parents Children First Named Ancestors First Named Descendants

Trees: Ancestors Descendants Containment Modifications

Properties: Direct Defined Action State State Delta

}

Value

{

tads#796 (predicate(TreeDefinerObj))

}

Treeing Object Information

The @tree metacommand displays the relationship of an object in the object containment and inheritance hierarchies. The command has the following syntax:

§ @tree <cont|containment> <all>

§ @tree definer <sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)

Treeing an Object’s Ancestors

The @tree metacommand can be used to display its ancestors. The syntax is:

This will produce a tree listing of all the objects that are ancestors of this object. For instance:

>@tree ancestors Thing

Please wait... processing 11 entries

§ Object

o TadsObject

o tads#31d ( 349 *VocabObject*)

o VocabObject

o tads#47d ( 4d5 *Thing*)

o tads#53d ( 5c0 *Thing*)

o tads#53f ( 5c4 *Thing*)

o tads#5c7 ( 64c *Thing*)

o tads#5c8 ( 64d *Thing*)

o tads#5c9 ( 64e *Thing*)

o Thing

The syntax is:

Treeing Containment

The @tree metacommand can be used to produce an HTML tree of all objects in the object containment tree, beginning with nil locations and working along the containment hierarchy. An example follows:

>@tree

nil

· defaultEastWall

· lightProbe

· defaultWestWall

· defaultSky

· defaultNorthWall

· defaultSouthWall

· defaultFloor

· defaultGround

· defaultCeiling

· kitchen

o defaultFloor

o defaultCeiling

o defaultNorthWall

o defaultSouthWall

o defaultEastWall

o defaultWestWall

o tads#541 (Fixed, OpenableContainer)

§ tads#542 (Food)

o tads#543 (Fixed, OpenableContainer)

· hallway

o defaultFloor

o defaultCeiling

o defaultNorthWall

o defaultSouthWall

o defaultEastWall

o defaultWestWall

· entryway

o suitOfArmor

§ axe

o me

o defaultFloor

o defaultCeiling

o defaultNorthWall

o defaultSouthWall

o defaultEastWall

o defaultWestWall

o frontDoor

o tads#53f (Chair, Fixed)

o tads#540 (Fixed)

The syntax is:

@tree <cont|containment> <all>

Treeing the Containment for a Single Object

The @tree metacommand trees a single object, displaying its location, and iterating down its contents.

>@tree suitOfArmor

entryway

· suitOfArmor

o axe

The syntax is:

@tree <cont> <sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)

Treeing an Object’s Descendants

The @tree metacommand can be used to display its descendants. The syntax is:

This will produce a tree listing of all the objects descended from this object. For instance:

>@tree descendants Actor

Please wait... processing descendants for object

§ Actor

o UntakeableActor

§ Person

· me

· bob

· bill

The syntax is:

Treeing an Object’s Modifications

The @tree metacommand can be used to display an object’s modifications as created by the modify keyword. The syntax is:

This will produce a tree listing of the original object and all of its modifications. For instance:

>@tree modifications Thing

Please wait... processing 7 entries

§ tads#47d ( 4d5 *Thing*)

o tads#53d ( 5c0 *Thing*)

§ tads#53f ( 5c4 *Thing*)

· tads#5c7 ( 64c *Thing*)

o tads#5c8 ( 64d *Thing*)

§ tads#5c9 ( 64e *Thing*)

· Thing

The syntax is:

This file is part of the TADS 3 Proteus Library Extension