CommandTranscriptclass
Command Transcript. This is a “semantic transcript” of the results of a command. This provides a list of CommandReport objects describing the results of the command.
class CommandTranscript : OutputFilter
Superclass Tree (in declaration order)
CommandTranscript
OutputFilter
` object`
Subclass Tree
(none)
Global Objects
(none)
Summary of Properties
isActive isFailure iter_ reports_ transforms_
Summary of Methods
actionFailed activate addCommandSep addMarker addReport announceAmbigActionObject announceDefaultObject announceImplicit announceMultiActionObject announceRemappedAction applyTransforms canShowReport clearReports construct currentActionHasReport deactivate deleteLastReport deleteRange endDescription filterText findCurrentActionReport flushForInput forEachReport getLastReport moveRangeAppend newIter noteFailure showReports summarizeAction
Properties
isActive
flag: I’m active; when this is nil, we’ll pass text through our filter routine unchanged
isFailure
flag: the command has failed (i.e., at least one failure report has been generated)
iter_
iteration number - for an iterated top-level command, this helps us keep the results for a particular iteration grouped together
reports_
our vector of reports
transforms_
our list of transformations
Methods
actionFailed (action)
Did the given action fail? This scans the transcript to determine if there are any failure messages associated with the given action.
activate ( )
activate - set up to capture output
addCommandSep ( )
Add a command separator.
addMarker ( )
Add a marker report. This adds a marker to the report stream, and returns the marker object. The marker doesn’t show any message in the final display, but callers can use a pair of markers to identify a range of reports for later reordering or removal.
addReport (report)
Add a report.
announceAmbigActionObject (obj, whichObj)
Announce an object that was resolved with slight ambiguity.
announceDefaultObject (obj, whichObj, action, allResolved)
Announce a default object.
announceImplicit (action, msgProp)
Announce that the action is implicit
announceMultiActionObject (preCalcMsg, obj, whichObj)
Announce one of a set of objects to a multi-object action. We’ll record this announcement for display with our report list.
announceRemappedAction ( )
Announce a remapped action
applyTransforms ( )
apply transformations
canShowReport (report)
Can we show a given report? By default, we always return true, but subclasses might want to override this to suppress certain types of reports.
clearReports ( )
clear our reports
construct ( )
no description available
currentActionHasReport (func)
check to see if the current action has a report matching the given criteria
deactivate ( )
deactivate - stop capturing output
deleteLastReport ( )
delete the last report added
deleteRange (marker1, marker2)
delete the reports between two markers
endDescription ( )
End the description section of the report. This adds a marker report that indicates that anything following (and part of the same action) is no longer part of the description; this can be important when we apply the default description suppression transformation, because it tells us not to consider the non-descriptive messages following this marker when, for example, suppressing default descriptive messages.
filterText (ostr, txt)OVERRIDDEN
Filter text. If we’re active, we’ll turn the text into a command report and add it to our report list, blocking the text from reaching the underlying stream; otherwise, we’ll pass it through unchanged.
findCurrentActionReport (func)
find a report in the current action that matches the given criteria
flushForInput ( )
Flush the transcript in preparation for reading input. This shows all pending reports, clears the backlog of reports (so that we don’t show them again in the future), and deactivates the transcript’s capture feature so that subsequent output goes directly to the output stream.
We return the former activation status - that is, we return true if the transcript was activated before the call, nil if not.
forEachReport (func)
Perform a callback on all of the reports in the transcript. We’ll invoke the given callback function func(rpt) once for each report, with the report object as the parameter.
getLastReport ( )
get the last report added
moveRangeAppend (marker1, marker2)
Pull out the reports between two markers, and reinsert them at the end of the transcript.
newIter ( )
Count an iteration. An Action should call this once per iteration if it’s a top-level (non-nested) command.
noteFailure ( )
Note that the current action has failed. This is equivalent to adding a reportFailure() message to the transcript.
showReports (deact)
Show our reports. Returns true if the transcript was previously active, nil if not.
summarizeAction (cond, report)
Summarize the current action’s reports. This allows a caller to turn a series of iterated reports into a single report for the entire action. For example, we could change something like this:
gold coin: Bob accepts the gold coin.
gold coin: Bob accepts the gold coin.
gold coin: Bob accepts the gold coin.
into this:
Bob accepts the three gold coins.
This function runs through the reports for the current action, submitting each one to the ‘cond’ callback to see if it’s of interest to the summary. For each consecutive run of two or more reports that can be summarized, we’ll remove the reports that ‘cond’ accepted, and we’ll remove the multiple-object announcement reports associated with them, and we’ll insert a new report with the message returned by the ‘report’ callback.
‘cond’ is called as cond(x), where ‘x’ is a report object. This callback returns true if the report can be summarized for the caller’s purposes, nil if not.
‘report’ is called as report(vec), where ‘vec’ is a Vector consisting of all of the consecutive report objects that we’re now summarizing. This function returns a string giving the message to use in place of the reports we’re removing. This should be a summary message, standing in for the set of individual reports we’re removing.
There’s an important subtlety to note. If the messages you’re summarizing are conversational (that is, if they’re generated by TopicEntry responses), you should take care to generate the full replacement text in the ‘report’ part, rather than doing so in separate code that you run after summarizeAction() returns. This is important because it ensures that the Conversation Manager knows that your replacement message is part of the same conversation. If you wait until after summarizeAction() returns to generate more response text, the conversation manager won’t realize that the additional text is part of the same conversation.
TADS 3 Library Manual
Generated on 5/16/2013 from TADS version 3.1.3