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:
§
@list (ancestor|ancestors)
<sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)
§
@list (child|children)
<sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)
§
@list
(descendant|descendants) <sym|tag|voc>
(symbolicLiteral|objRefTag|nounPhrase)
§
@list (parent|parents)
<sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)
§
@list first named (ancestor|ancestors) <sym|tag|voc>
(symbolicLiteral|objRefTag|nounPhrase)
§
@list first named (descendant|descendants) <sym|tag|voc>
(symbolicLiteral|objRefTag|nounPhrase)
§
@list
(mod|modification|modifications) <sym|tag|voc>
(symbolicLiteral|objRefTag|nounPhrase)
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:
@list
(ancestor|ancestors) <sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)
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:
@list
(child|children) <sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)
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:
@list
(descendant|descendants) <sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)
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:
@list first named (ancestor|ancestors) <sym|tag|voc>
(symbolicLiteral|objRefTag|nounPhrase)
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:
@list first named (descendant|descendants) <sym|tag|voc>
(symbolicLiteral|objRefTag|nounPhrase)
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:
@list
(mod|modification|modifications) <sym|tag|voc>
(symbolicLiteral|objRefTag|nounPhrase)
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:
@list
(parent|parents) <sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)
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
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 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 (act|action|actions)
<sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)
§
@show (def|definition)
<sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)
§
@show (delta|deltas)
<sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)
§
@show (dir|direct) <sym|tag|voc>
(symbolicLiteral|objRefTag|nounPhrase)
§
@show (state|states)
<sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)
§
@show (delta|deltas) <all>
§
@show (delta|deltas)
<sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)
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:
@show (act|action|actions) <sym|tag|voc>
(symbolicLiteral|objRefTag|nounPhrase)
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:
@show (def|definition) <sym|tag|voc>
(symbolicLiteral|objRefTag|nounPhrase)
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:
@show
(delta|deltas) <sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)
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:
@show
<dir|direct> <sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)
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:
@show
(state|states) <sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)
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 (ancestor|ancestors)
<sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)
§
@tree definer <sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)
§
@tree
(descendant|descendants) <sym|tag|voc>
(symbolicLiteral|objRefTag|nounPhrase)
§
@tree (mod|modification|medications)
<sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)
Treeing
an
Object’s Ancestors
The @tree metacommand can be used to display its ancestors. The syntax is:
@tree
(ancestor|ancestors) <sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)
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:
@tree
(ancestor|ancestors) <sym|tag|voc> (symbolicLiteral|objRefTag|nounPhrase)
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