CommandTranscriptclassreport.t[606]

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  

isActivereport.t[648]

flag: I'm active; when this is nil, we'll pass text through our filter routine unchanged

isFailurereport.t[617]
flag: the command has failed (i.e., at least one failure report has been generated)

iter_report.t[1235]
iteration number - for an iterated top-level command, this helps us keep the results for a particular iteration grouped together

reports_report.t[1238]
our vector of reports

transforms_report.t[1241]
our list of transformations

Methods  

actionFailed (action)report.t[634]

Did the given action fail? This scans the transcript to determine if there are any failure messages associated with the given action.

activate ( )report.t[842]
activate - set up to capture output

addCommandSep ( )report.t[1148]
Add a command separator.

addMarker ( )report.t[1005]
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)report.t[934]
Add a report.

announceAmbigActionObject (obj, whichObj)report.t[1129]
Announce an object that was resolved with slight ambiguity.

announceDefaultObject (obj, whichObj, action, allResolved)report.t[1138]
Announce a default object.

announceImplicit (action, msgProp)report.t[1080]
Announce that the action is implicit

announceMultiActionObject (preCalcMsg, obj, whichObj)report.t[1119]
Announce one of a set of objects to a multi-object action. We'll record this announcement for display with our report list.

announceRemappedAction ( )report.t[1109]
Announce a remapped action

applyTransforms ( )report.t[1203]
apply transformations

canShowReport (report)report.t[1169]
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 ( )report.t[1157]
clear our reports

construct ( )report.t[607]
no description available

currentActionHasReport (func)report.t[1214]
check to see if the current action has a report matching the given criteria

deactivate ( )report.t[849]
deactivate - stop capturing output

deleteLastReport ( )report.t[991]
delete the last report added

deleteRange (marker1, marker2)report.t[1018]
delete the reports between two markers

endDescription ( )report.t[1071]
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)OVERRIDDENreport.t[1177]
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)report.t[1221]
find a report in the current action that matches the given criteria

flushForInput ( )report.t[871]
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)report.t[1060]
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 ( )report.t[984]
get the last report added

moveRangeAppend (marker1, marker2)report.t[1035]
Pull out the reports between two markers, and reinsert them at the end of the transcript.

newIter ( )report.t[859]
Count an iteration. An Action should call this once per iteration if it's a top-level (non-nested) command.

noteFailure ( )report.t[623]
Note that the current action has failed. This is equivalent to adding a reportFailure() message to the transcript.

showReports (deact)report.t[887]
Show our reports. Returns true if the transcript was previously active, nil if not.

summarizeAction (cond, report)report.t[693]
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