#charset "us-ascii"
/*
* Copyright (c) 2000, 2006 Michael J. Roberts. All Rights Reserved.
*
* TADS 3 Library - output formatting
*
* This module defines the framework for displaying output text.
*/
/* include the library header */
#include "adv3.h"
/* ------------------------------------------------------------------------ */
/*
* The standard library output function. We set this up as the default
* display function (for double-quoted strings and for "<< >>"
* embeddings). Code can also call this directly to display items.
*/
say(val)
{
/* send output to the active output stream */
outputManager.curOutputStream.writeToStream(val);
}
/* ------------------------------------------------------------------------ */
/*
* Generate a string for showing quoted text. We simply enclose the
* text in a <Q>...</Q> tag sequence and return the result.
*/
withQuotes(txt)
{
return '<q><<txt>></q>';
}
/* ------------------------------------------------------------------------ */
/*
* Output Manager. This object contains global code for displaying text
* on the console.
*
* The output manager is transient because we don't want its state to be
* saved and restored; the output manager state is essentially part of
* the intepreter user interface, which is not affected by save and
* restore.
*/
transient outputManager: object
/*
* Switch to a new active output stream. Returns the previously
* active output stream, so that the caller can easily restore the
* old output stream if the new output stream is to be established
* only for a specific duration.
*/
setOutputStream(ostr)
{
local oldStr;
/* remember the old stream for a moment */
oldStr = curOutputStream;
/* set the new output stream */
curOutputStream = ostr;
/*
* return the old stream, so the caller can restore it later if
* desired
*/
return oldStr;
}
/*
* run the given function, using the given output stream as the
* active default output stream
*/
withOutputStream(ostr, func)
{
/* establish the new stream */
local oldStr = setOutputStream(ostr);
/* make sure we restore the old active stream on the way out */
try
{
/* invoke the callback */
(func)();
}
finally
{
/* restore the old output stream */
setOutputStream(oldStr);
}
}
/* the current output stream - start with the main text stream */
curOutputStream = mainOutputStream
/*
* Is the UI running in HTML mode? This tells us if we have a full
* HTML UI or a text-only UI. Full HTML mode applies if we're
* running on a Multimedia TADS interpreter, or we're using the Web
* UI, which runs in a separate browser and is thus inherently
* HTML-capable.
*
* (The result can't change during a session, since it's a function
* of the game and interpreter capabilities, so we store the result
* on the first evaluation to avoid having to recompute it on each
* query. Since 'self' is a static object, we'll recompute this each
* time we run the program, which is important because we could save
* the game on one interpreter and resume the session on a different
* interpreter with different capabilities.)
*/
htmlMode = (self.htmlMode = checkHtmlMode())
;
/* ------------------------------------------------------------------------ */
/*
* Output Stream. This class provides a stream-oriented interface to
* displaying text on the console. "Stream-oriented" means that we write
* text as a sequential string of characters.
*
* Output streams are always transient, since they track the system user
* interface in the interpreter. The interpreter does not save its UI
* state with a saved position, so objects such as output streams that
* track the UI state should not be saved either.
*/
class OutputStream: PreinitObject
/*
* Write a value to the stream. If the value is a string, we'll
* display the text of the string; if it's nil, we'll ignore it; if
* it's anything else, we'll try to convert it to a string (with the
* toString() function) and display the resulting text.
*/
writeToStream(val)
{
/* convert the value to a string */
switch(dataType(val))
{
case TypeSString:
/*
* it's a string - no conversion is needed, but if it's
* empty, it doesn't count as real output (so don't notify
* anyone, and don't set any output flags)
*/
if (val == '')
return;
break;
case TypeNil:
/* nil - don't display anything for this */
return;
case TypeInt:
case TypeObject:
/* convert integers and objects to strings */
val = toString(val);
break;
}
/* run it through our output filters */
val = applyFilters(val);
/*
* if, after filtering, we're not writing anything at all,
* there's nothing left to do
*/
if (val == nil || val == '')
return;
/* write the text to our underlying system stream */
writeFromStream(val);
}
/*
* Watch the stream for output. It's sometimes useful to be able to
* call out to some code and determine whether or not the code
* generated any text output. This routine invokes the given
* callback function, monitoring the stream for output; if any
* occurs, we'll return true, otherwise we'll return nil.
*/
watchForOutput(func)
{
local mon;
/* set up a monitor filter on the stream */
addOutputFilter(mon = new MonitorFilter());
/* catch any exceptions so we can remove our filter before leaving */
try
{
/* invoke the callback */
(func)();
/* return the monitor's status, indicating if output occurred */
return mon.outputFlag;
}
finally
{
/* remove our monitor filter */
removeOutputFilter(mon);
}
}
/*
* Call the given function, capturing all text output to this stream
* in the course of the function call. Return a string containing
* the captured text.
*/
captureOutput(func, [args])
{
/* install a string capture filter */
local filter = new StringCaptureFilter();
addOutputFilter(filter);
/* make sure we don't leave without removing our capturer */
try
{
/* invoke the function */
(func)(args...);
/* return the text that we captured */
return filter.txt_;
}
finally
{
/* we're done with our filter, so remove it */
removeOutputFilter(filter);
}
}
/* my associated input manager, if I have one */
myInputManager = nil
/* dynamic construction */
construct()
{
/*
* Set up filter list. Output streams are always transient, so
* make our filter list transient as well.
*/
filterList_ = new transient Vector(10);
}
/* execute pre-initialization */
execute()
{
/* do the same set-up we would do for dynamic construction */
construct();
}
/*
* Write text out from this stream; this writes to the lower-level
* stream underlying this stream. This routine is intended to be
* called only from within this class.
*
* Each output stream is conceptually "stacked" on top of another,
* lower-level stream. At the bottom of the stack is usually some
* kind of physical device, such as the display, or a file on disk.
*
* This method must be defined in each subclass to write to the
* appropriate underlying stream. Most subclasses are specifically
* designed to sit atop a system-level stream, such as the display
* output stream, so most implementations of this method will call
* directly to a system-level output function.
*/
writeFromStream(txt) { }
/*
* The list of active filters on this stream, in the order in which
* they are to be called. This should normally be initialized to a
* Vector in each instance.
*/
filterList_ = []
/*
* Add an output filter. The argument is an object of class
* OutputFilter, or any object implementing the filterText() method.
*
* Filters are always arranged in a "stack": the last output filter
* added is the first one called during output. This method thus
* adds the new filter at the "top" of the stack.
*/
addOutputFilter(filter)
{
/* add the filter to the end of our list */
filterList_.append(filter);
}
/*
* Add an output filter at a given point in the filter stack: add
* the filter so that it is "below" the given existing filter in the
* stack. This means that the new filter will be called just after
* the existing filter during output.
*
* If 'existingFilter' isn't in the stack of existing filters, we'll
* add the new filter at the "top" of the stack.
*/
addOutputFilterBelow(newFilter, existingFilter)
{
/* find the existing filter in our list */
local idx = filterList_.indexOf(existingFilter);
/*
* If we found the old filter, add the new filter below the
* existing filter in the stack, which is to say just before the
* old filter in our vector of filters (since we call the
* filters in reverse order of the list).
*
* If we didn't find the existing filter, simply add the new
* filter at the top of the stack, by appending the new filter
* at the end of the list.
*/
if (idx != nil)
filterList_.insertAt(idx, newFilter);
else
filterList_.append(newFilter);
}
/*
* Remove an output filter. Since filters are arranged in a stack,
* only the LAST output filter added may be removed. It's an error
* to remove a filter other than the last one.
*/
removeOutputFilter(filter)
{
/* get the filter count */
local len = filterList_.length();
/* make sure it's the last filter */
if (len == 0 || filterList_[len] != filter)
t3DebugTrace(T3DebugBreak);
/* remove the filter from my list */
filterList_.removeElementAt(len);
}
/* call the filters */
applyFilters(val)
{
/*
* Run through the list, applying each filter in turn. We work
* backwards through the list from the last element, because the
* filter list is a stack: the last element added is the topmost
* element of the stack, so it must be called first.
*/
for (local i in filterList_.length()..1 step -1 ; val != nil ; )
val = filterList_[i].filterText(self, val);
/* return the result of all of the filters */
return val;
}
/*
* Apply the current set of text transformation filters to a string.
* This applies only the non-capturing filters; we skip any capture
* filters.
*/
applyTextFilters(val)
{
/* run through the filter stack from top to bottom */
for (local i in filterList_.length()..1 step -1 ; val != nil ; )
{
/* skip capturing filters */
local f = filterList_[i];
if (f.ofKind(CaptureFilter))
continue;
/* apply the filter */
val = f.filterText(self, val);
}
/* return the result */
return val;
}
/*
* Receive notification from the input manager that we have just
* ended reading a line of input from the keyboard.
*/
inputLineEnd()
{
/* an input line ending doesn't look like a paragraph */
justDidPara = nil;
}
/*
* Internal state: we just wrote a paragraph break, and there has
* not yet been any intervening text. By default, we set this to
* true initially, so that we suppress any paragraph breaks at the
* very start of the text.
*/
justDidPara = true
/*
* Internal state: we just wrote a character that suppresses
* paragraph breaks that immediately follow. In this state, we'll
* suppress any paragraph marker that immediately follows, but we
* won't suppress any other characters.
*/
justDidParaSuppressor = nil
;
/*
* The OutputStream for the main text area.
*
* This object is transient because the output stream state is
* effectively part of the interpreter user interface, which is not
* affected by save and restore.
*/
transient mainOutputStream: OutputStream
/*
* The main text area is the same place where we normally read
* command lines from the keyboard, so associate this output stream
* with the primary input manager.
*/
myInputManager = inputManager
/* the current command transcript */
curTranscript = nil
/* we sit atop the system-level main console output stream */
writeFromStream(txt)
{
/* if an input event was interrupted, cancel the event */
inputManager.inputEventEnd();
/* write the text to the console */
aioSay(txt);
}
;
/* ------------------------------------------------------------------------ */
/*
* Paragraph manager. We filter strings as they're about to be sent to
* the console to convert paragraph markers (represented in the source
* text using the "style tag" format, <.P>) into a configurable display
* rendering.
*
* We also process the zero-spacing paragraph, <.P0>. This doesn't
* generate any output, but otherwise acts like a paragraph break in that
* it suppresses any paragraph breaks that immediately follow.
*
* The special marker <./P0> cancels the effect of a <.P0>. This can be
* used if you want to ensure that a newline or paragraph break is
* displayed, even if a <.P0> was just displayed.
*
* Our special processing ensures that paragraph tags interact with one
* another and with other display elements specially:
*
* - A run of multiple consecutive paragraph tags is treated as a single
* paragraph tag. This property is particularly important because it
* allows code to write out a paragraph marker without having to worry
* about whether preceding code or following code add paragraph markers
* of their own; if redundant markers are found, we'll filter them out
* automatically.
*
* - We can suppress paragraph markers following other specific
* sequences. For example, if the paragraph break is rendered as a blank
* line, we might want to suppress an extra blank line for a paragraph
* break after an explicit blank line.
*
* - We can suppress other specific sequences following a paragraph
* marker. For example, if the paragraph break is rendered as a newline
* plus a tab, we could suppress whitespace following the paragraph
* break.
*
* The paragraph manager should always be instantiated with transient
* instances, because this object's state is effectively part of the
* interpreter user interface, which doesn't participate in save and
* restore.
*/
class ParagraphManager: OutputFilter
/*
* Rendering - this is what we display on the console to represent a
* paragraph break. By default, we'll display a blank line.
*/
renderText = '\b'
/*
* Flag: show or hide paragraph breaks immediately after input. By
* default, we do not show paragraph breaks after an input line.
*/
renderAfterInput = nil
/*
* Preceding suppression. This is a regular expression that we
* match to individual characters. If the character immediately
* preceding a paragraph marker matches this expression, we'll
* suppress the paragraph marker in the output. By default, we'll
* suppress a paragraph break following a blank line, because the
* default rendering would add a redundant blank line.
*/
suppressBefore = static new RexPattern('\b')
/*
* Following suppression. This is a regular expression that we
* match to individual characters. If the character immediately
* following a paragraph marker matches this expression, we'll
* suppress the character. We'll apply this to each character
* following a paragraph marker in turn until we find one that does
* not match; we'll suppress all of the characters that do match.
* By default, we suppress additional blank lines after a paragraph
* break.
*/
suppressAfter = static new RexPattern('[\b\n]')
/* pre-compile some regular expression patterns we use a lot */
leadingMultiPat = static new RexPattern('(<langle><dot>[pP]0?<rangle>)+')
leadingSinglePat = static new RexPattern(
'<langle><dot>([pP]0?|/[pP]0)<rangle>')
/* process a string that's about to be written to the console */
filterText(ostr, txt)
{
local ret;
/* we don't have anything in our translated string yet */
ret = '';
/* keep going until we run out of string to process */
while (txt != '')
{
local len;
local match;
local p0;
local unp0;
/*
* if we just wrote a paragraph break, suppress any
* character that matches 'suppressAfter', and suppress any
* paragraph markers that immediately follow
*/
if (ostr.justDidPara)
{
/* check for any consecutive paragraph markers */
if ((len = rexMatch(leadingMultiPat, txt)) != nil)
{
/* discard the consecutive <.P>'s, and keep going */
txt = txt.substr(len + 1);
continue;
}
/* check for a match to the suppressAfter pattern */
if (rexMatch(suppressAfter, txt) != nil)
{
/* discard the suppressed character and keep going */
txt = txt.substr(2);
continue;
}
}
/*
* we have a character other than a paragraph marker, so we
* didn't just scan a paragraph marker
*/
ostr.justDidPara = nil;
/*
* if we just wrote a suppressBefore character, discard any
* leading paragraph markers
*/
if (ostr.justDidParaSuppressor
&& (len = rexMatch(leadingMultiPat, txt)) != nil)
{
/* remove the paragraph markers */
txt = txt.substr(len + 1);
/*
* even though we're not rendering the paragraph, note
* that a logical paragraph just started
*/
ostr.justDidPara = true;
/* keep going */
continue;
}
/* presume we won't find a <.p0> or <./p0> */
p0 = unp0 = nil;
/* find the next paragraph marker */
match = rexSearch(leadingSinglePat, txt);
if (match == nil)
{
/*
* there are no more paragraph markers - copy the
* remainder of the input string to the output
*/
ret += txt;
txt = '';
/* we just did something other than a paragraph */
ostr.justDidPara = nil;
}
else
{
/* add everything up to the paragraph break to the output */
ret += txt.substr(1, match[1] - 1);
/* get the rest of the string following the paragraph mark */
txt = txt.substr(match[1] + match[2]);
/* note if we found a <.p0> or <./p0> */
p0 = (match[3] is in ('<.p0>', '<.P0>'));
unp0 = (match[3] is in ('<./p0>', '<./P0>'));
/*
* note that we just found a paragraph marker, unless
* this is a <./p0>
*/
ostr.justDidPara = !unp0;
}
/*
* If the last character we copied out is a suppressBefore
* character, note for next time that we have a suppressor
* pending. Likewise, if we found a <.p0> rather than a
* <.p>, this counts as a suppressor.
*/
ostr.justDidParaSuppressor =
(p0 || rexMatch(suppressBefore,
ret.substr(ret.length(), 1)) != nil);
/*
* if we found a paragraph marker, and we didn't find a
* leading suppressor character just before it, add the
* paragraph rendering
*/
if (ostr.justDidPara && !ostr.justDidParaSuppressor)
ret += renderText;
}
/* return the translated string */
return ret;
}
;
/* the paragraph manager for the main output stream */
transient mainParagraphManager: ParagraphManager
;
/* ------------------------------------------------------------------------ */
/*
* Output Filter
*/
class OutputFilter: object
/*
* Apply the filter - this should be overridden in each filter. The
* return value is the result of filtering the string.
*
* 'ostr' is the OutputStream to which the text is being written,
* and 'txt' is the original text to be displayed.
*/
filterText(ostr, txt) { return txt; }
;
/* ------------------------------------------------------------------------ */
/*
* Output monitor filter. This is a filter that leaves the filtered
* text unchanged, but keeps track of whether any text was seen at all.
* Our 'outputFlag' is true if we've seen any output, nil if not.
*/
class MonitorFilter: OutputFilter
/* filter text */
filterText(ostr, val)
{
/* if the value is non-empty, note the output */
if (val != nil && val != '')
outputFlag = true;
/* return the input value unchanged */
return val;
}
/* flag: has any output occurred for this monitor yet? */
outputFlag = nil
;
/* ------------------------------------------------------------------------ */
/*
* Capture Filter. This is an output filter that simply captures all of
* the text sent through the filter, sending nothing out to the
* underlying stream.
*
* The default implementation simply discards the incoming text.
* Subclasses can keep track of the text in memory, in a file, or
* wherever desired.
*/
class CaptureFilter: OutputFilter
/*
* Filter the text. We simply discard the text, passing nothing
* through to the underlying stream.
*/
filterText(ostr, txt)
{
/* leave nothing for the underlying stream */
return nil;
}
;
/*
* "Switchable" capture filter. This filter can have its blocking
* enabled or disabled. When blocking is enabled, we capture
* everything, leaving nothing to the underlying stream; when disabled,
* we pass everything through to the underyling stream unchanged.
*/
class SwitchableCaptureFilter: CaptureFilter
/* filter the text */
filterText(ostr, txt)
{
/*
* if we're blocking output, return nothing to the underlying
* stream; if we're disabled, return the input unchanged
*/
return (isBlocking ? nil : txt);
}
/*
* Blocking enabled: if this is true, we'll capture all text passed
* through us, leaving nothing to the underyling stream. Blocking
* is enabled by default.
*/
isBlocking = true
;
/*
* String capturer. This is an implementation of CaptureFilter that
* saves the captured text to a string.
*/
class StringCaptureFilter: CaptureFilter
/* filter text */
filterText(ostr, txt)
{
/* add the text to my captured text so far */
addText(txt);
}
/* add to my captured text */
addText(txt)
{
/* append the text to my string of captured text */
txt_ += txt;
}
/* my captured text so far */
txt_ = ''
;
/* ------------------------------------------------------------------------ */
/*
* Style tag. This defines an HTML-like tag that can be used in output
* text to display an author-customizable substitution string.
*
* Each StyleTag object defines the name of the tag, which can be
* invoked in output text using the syntax "<.name>" - we require the
* period after the opening angle-bracket to plainly distinguish the
* sequence as a style tag, not a regular HTML tag.
*
* Each StyleTag also defines the text string that should be substituted
* for each occurrence of the "<.name>" sequence in output text, and,
* optionally, another string that is substituted for occurrences of the
* "closing" version of the tag, invoked with the syntax "<./name>".
*/
class StyleTag: object
/* name of the tag - the tag appears in source text in <.xxx> notation */
tagName = ''
/*
* opening text - this is substituted for each instance of the tag
* without a '/' prefix
*/
openText = ''
/*
* Closing text - this is substituted for each instance of the tag
* with a '/' prefix (<./xxx>). Note that non-container tags don't
* have closing text at all.
*/
closeText = ''
;
/*
* HtmlStyleTag - this is a subclass of StyleTag that provides different
* rendering depending on whether the interpreter is in HTML mode or not.
* In HTML mode, we display our htmlOpenText and htmlCloseText; when not
* in HTML mode, we display our plainOpenText and plainCloseText.
*/
class HtmlStyleTag: StyleTag
openText = (outputManager.htmlMode ? htmlOpenText : plainOpenText)
closeText = (outputManager.htmlMode ? htmlCloseText : plainCloseText)
/* our HTML-mode opening and closing text */
htmlOpenText = ''
htmlCloseText = ''
/* our plain (non-HTML) opening and closing text */
plainOpenText = ''
plainCloseText = ''
;
/*
* Define our default style tags. We name all of these StyleTag objects
* so that authors can easily change the expansion text strings at
* compile-time with the 'modify' syntax, or dynamically at run-time by
* assigning new strings to the appropriate properties of these objects.
*/
/*
* <.roomname> - we use this to display the room's name in the
* description of a room (such as in a LOOK AROUND command, or when
* entering a new location). By default, we display the room name in
* boldface on a line by itself.
*/
roomnameStyleTag: StyleTag 'roomname' '\n<b>' '</b><br>\n';
/* <.roomdesc> - we use this to display a room's long description */
roomdescStyleTag: StyleTag 'roomdesc' '' '';
/*
* <.roompara> - we use this to separate paragraphs within a room's long
* description
*/
roomparaStyleTag: StyleTag 'roompara' '<.p>\n';
/*
* <.inputline> - we use this to display the text actually entered by the
* user on a command line. Note that this isn't used for the prompt text
* - it's used only for the command-line text itself.
*/
inputlineStyleTag: HtmlStyleTag 'inputline'
/* in HTML mode, switch in and out of TADS-Input font */
htmlOpenText = '<font face="tads-input">'
htmlCloseText = '</font>'
/* in plain mode, do nothing */
plainOpenText = ''
plainCloseText = ''
;
/*
* <.a> (named in analogy to the HTML <a> tag) - we use this to display
* hyperlinked text. Note that this goes *inside* an HTML <a> tag - this
* doesn't do the actual linking (the true <a> tag does that), but rather
* allows customized text formatting for hyperlinked text.
*/
hyperlinkStyleTag: HtmlStyleTag 'a'
;
/* <.statusroom> - style for the room name in a status line */
statusroomStyleTag: HtmlStyleTag 'statusroom'
htmlOpenText = '<b>'
htmlCloseText = '</b>'
;
/* <.statusscore> - style for the score in a status line */
statusscoreStyleTag: HtmlStyleTag 'statusscore'
htmlOpenText = '<i>'
htmlCloseText = '</i>'
;
/*
* <.parser> - style for messages explicitly from the parser.
*
* By default, we do nothing special with these messages. Many games
* like to use a distinctive notation for parser messages, to make it
* clear that the messages are "meta" text that's not part of the story
* but rather specific to the game mechanics; one common convention is
* to put parser messages in [square brackets].
*
* If the game defines a special appearance for parser messages, for
* consistency it might want to use the same appearance for notification
* messages displayed with the <.notification> tag (see
* notificationStyleTag).
*/
parserStyleTag: StyleTag 'parser'
openText = ''
closeText = ''
;
/*
* <.notification> - style for "notification" messages, such as score
* changes and messages explaining how facilities (footnotes, exit
* lists) work the first time they come up.
*
* By default, we'll put notifications in parentheses. Games that use
* [square brackets] for parser messages (i.e., for the <.parser> tag)
* might want to use the same notation here for consistency.
*/
notificationStyleTag: StyleTag 'notification'
openText = '('
closeText = ')'
;
/*
* <.assume> - style for "assumption" messages, showing an assumption
* the parser is making. This style is used for showing objects used by
* default when not specified in a command, objects that the parser
* chose despite some ambiguity, and implied commands.
*/
assumeStyleTag: StyleTag 'assume'
openText = '('
closeText = ')'
;
/*
* <.announceObj> - style for object announcement messages. The parser
* shows an object announcement for each object when a command is applied
* to multiple objects (TAKE ALL, DROP KEYS AND WALLET). The
* announcement simply shows the object's name and a colon, to let the
* player know that the response text that follows applies to the
* announced object.
*/
announceObjStyleTag: StyleTag 'announceObj'
openText = '<b>'
closeText = '</b>'
;
/* ------------------------------------------------------------------------ */
/*
* "Style tag" filter. This is an output filter that expands our
* special style tags in output text.
*/
styleTagFilter: OutputFilter, PreinitObject
/* pre-compile our frequently-used tag search pattern */
tagPattern = static new RexPattern(
'<nocase><langle>%.(/?[a-z][a-z0-9]*)<rangle>')
/* filter for a style tag */
filterText(ostr, val)
{
local idx;
/* search for our special '<.xxx>' tags, and expand any we find */
idx = rexSearch(tagPattern, val);
while (idx != nil)
{
local xlat;
local afterOfs;
local afterStr;
/* ask the formatter to translate it */
xlat = translateTag(rexGroup(1)[3]);
/* get the part of the string that follows the tag */
afterOfs = idx[1] + idx[2];
afterStr = val.substr(idx[1] + idx[2]);
/*
* if we got a translation, replace it; otherwise, leave the
* original text intact
*/
if (xlat != nil)
{
/* replace the tag with its translation */
val = val.substr(1, idx[1] - 1) + xlat + afterStr;
/*
* figure the offset of the remainder of the string in
* the replaced version of the string - this is the
* length of the original part up to the replacement
* text plus the length of the replacement text
*/
afterOfs = idx[1] + xlat.length();
}
/*
* search for the next tag, considering only the part of
* the string following the replacement text - we do not
* want to re-scan the replacement text for tags
*/
idx = rexSearch(tagPattern, afterStr);
/*
* If we found it, adjust the starting index of the match to
* its position in the actual string. Note that we do this
* by adding the OFFSET of the remainder of the string,
* which is 1 less than its INDEX, because idx[1] is already
* a string index. (An offset is one less than an index
* because the index of the first character is 1.)
*/
if (idx != nil)
idx[1] += afterOfs - 1;
}
/* return the filtered value */
return val;
}
/*
* Translate a tag
*/
translateTag(tag)
{
local isClose;
local styleTag;
/* if it's a close tag, so note and remove the leading slash */
isClose = tag.startsWith('/');
if (isClose)
tag = tag.substr(2);
/* look up the tag object in our table */
styleTag = tagTable[tag];
/*
* if we found it, return the open or close text, as
* appropriate; otherwise return nil
*/
return (styleTag != nil
? (isClose ? styleTag.closeText : styleTag.openText)
: nil);
}
/* preinitialization */
execute()
{
/* create a lookup table for our style table */
tagTable = new LookupTable();
/*
* Populate the table with all of the StyleTag instances. Key
* by tag name, storing the tag object as the value for each
* key. This will let us efficiently look up the StyleTag
* object given a tag name string.
*/
forEachInstance(StyleTag, { tag: tagTable[tag.tagName] = tag });
}
/*
* Our tag translation table. We'll initialize this during preinit
* to a lookup table with all of the defined StyleTag objects.
*/
tagTable = nil
;
/* ------------------------------------------------------------------------ */
/*
* MessageBuilder - this object provides a general text substitution
* mechanism. Text to be substituted is enclosed in {curly braces}.
* Within the braces, we have the substitution parameter name, which can
* be in the following formats:
*
* id
*. id obj
*. id1/id2 obj
*. id1 obj/id2
*
* The ID string gives the type of substitution to perform. The ID's
* all come from a table, which is specified by the language-specific
* subclass, so the ID's can vary by language (to allow for natural
* template-style parameter names for each language). If the ID is in
* two pieces (id1 and id2), we concatenate the two pieces together with
* a slash between to form the name we seek in the table - so {the/he
* dobj} and {the dobj/he} are equivalent, and both look up the
* identifier 'the/he'. If a two-part identifier is given, and the
* identifier isn't found in the table, we'll try looking it up with the
* parts reversed: if we see {he/the dobj}, we'll first try finding
* 'he/the', and if that fails we'll look for 'the/he'.
*
* If 'obj' is present, it specificies the target object providing the
* text to be substitutued; this is a string passed to the current
* Action, and is usually something like 'actor', 'dobj', or 'iobj'.
*
* One instance of this class, called langMessageBuilder, should be
* created by the language-specific library.
*/
class MessageBuilder: OutputFilter, PreinitObject
/* pre-compile some regular expressions we use a lot */
patUpper = static new RexPattern('<upper>')
patAllCaps = static new RexPattern('<upper><upper>')
patIdObjSlashId = static new RexPattern(
'(<^space|/>+)<space>+(<^space|/>+)(/<^space|/>+)')
patIdObj = static new RexPattern('(<^space>+)<space>+(<^space>+)')
patIdSlash = static new RexPattern('([^/]+)/([^/]+)')
/*
* Given a source string with substitution parameters, generate the
* expanded message with the appropriate text in place of the
* parameters.
*/
generateMessage(orig)
{
local result;
/* we have nothing in the result string so far */
result = '';
/* keep going until we run out of substitution parameters */
for (;;)
{
local idx;
local paramStr;
local paramName;
local paramObj;
local info;
local initCap, allCaps;
local targetObj;
local newText;
local prop;
/* get the position of the next brace */
idx = orig.find('{');
/*
* if there are no braces, the rest of the string is simply
* literal text; add the entire remainder of the string to
* the result, and we're done
*/
if (idx == nil)
{
result += processResult(genLiteral(orig));
break;
}
/* add everything up to the brace to the result string */
result += processResult(genLiteral(orig.substr(1, idx - 1)));
/*
* lop off everything up to and including the brace from the
* source string, since we're done with the part up to the
* brace now
*/
orig = orig.substr(idx + 1);
/*
* if the brace was the last thing in the source string, or
* it's a stuttered brace, add it literally to the result
*/
if (orig.length() == 0)
{
/*
* nothing follows - add a literal brace to the result,
* and we're done
*/
result += processResult('{');
break;
}
else if (orig.substr(1, 1) == '{')
{
/*
* it's a stuttered brace - add a literal brace to the
* result
*/
result += processResult('{');
/* remove the second brace from the source */
orig = orig.substr(2);
/* we're finished processing this brace - go back for more */
continue;
}
/* find the closing brace */
idx = orig.find('}');
/*
* if there is no closing brace, include the brace and
* whatever follows as literal text
*/
if (idx == nil)
{
/* add the literal brace to the result */
result += processResult('{');
/* we're done with the brace - go back for more */
continue;
}
/*
* Pull out everything up to the brace as the parameter
* text.
*/
paramStr = orig.substr(1, idx - 1);
/* assume for now that we will have no parameter object */
paramObj = nil;
/*
* drop everything up to and including the closing brace,
* since we've pulled it out for processing now
*/
orig = orig.substr(idx + 1);
/*
* Note the capitalization of the first two letters. If
* they're both lower-case, we won't adjust the case of the
* substitution text at all. If the first is a capital and
* the second isn't, we'll capitalize the first letter of
* the replacement text. If they're both capitals, we'll
* capitalize the entire replacement text.
*/
initCap = (rexMatch(patUpper, paramStr) != nil);
allCaps = (rexMatch(patAllCaps, paramStr) != nil);
/* lower-case the entire parameter string for matching */
local origParamStr = paramStr;
paramStr = paramStr.toLower();
/* perform any language-specific rewriting on the string */
paramStr = langRewriteParam(paramStr);
/*
* Figure out which format we have. The allowable formats
* are:
*
* id
* obj
*. id obj
*. id1/id2
*. id1/id2 obj
*. id1 obj/id2
*/
if (rexMatch(patIdObjSlashId, paramStr) != nil)
{
/* we have the id1 obj/id2 format */
paramName = rexGroup(1)[3] + rexGroup(3)[3];
paramObj = rexGroup(2)[3];
}
else if (rexMatch(patIdObj, paramStr) != nil)
{
/* we have 'id obj' or 'id1/id2 obj' */
paramName = rexGroup(1)[3];
paramObj = rexGroup(2)[3];
}
else
{
/* we have no spaces, so we have no target object */
paramName = paramStr;
paramObj = nil;
}
/* look up our parameter name */
info = paramTable_[paramName];
/*
* If we didn't find it, and the parameter name contains a
* slash ('/'), try reversing the order of the parts before
* and after the slash.
*/
if (info == nil && rexMatch(patIdSlash, paramName) != nil)
{
/*
* rebuild the name with the order of the parts
* reversed, and look up the result
*/
info = paramTable_[rexGroup(2)[3] + '/' + rexGroup(1)[3]];
}
/*
* If we didn't find a match, simply put the entire thing in
* the result stream literally, including the braces.
*/
if (info == nil)
{
/*
* We didn't find it, so try treating it as a string
* parameter object. Try getting the string from the
* action.
*/
newText = (gAction != nil
? gAction.getMessageParam(paramName) : nil);
/* check what we found */
if (dataType(newText) == TypeSString)
{
/*
* It's a valid string parameter. Simply add the
* literal text to the result. If we're in html
* mode, translate the string to ensure that any
* markup-significant characters are properly quoted
* so that they aren't taken as html themselves.
*/
result += processResult(newText.htmlify());
}
else
{
/*
* the parameter is completely undefined; simply add
* the original text, including the braces
*/
result += processResult('{<<origParamStr>>}');
}
/*
* we're done with this substitution string - go back
* for more
*/
continue;
}
/*
* If we have no target object specified in the substitution
* string, and the parameter name has an associated implicit
* target object, use the implied object.
*/
if (paramObj == nil && info[3] != nil)
paramObj = info[3];
/*
* If we have a target object name, ask the current action
* for the target object value. Otherwise, use the same
* target object as the previous expansion.
*/
if (paramObj != nil)
{
/* check for a current action */
if (gAction != nil)
{
/* get the target object by name through the action */
targetObj = gAction.getMessageParam(paramObj);
}
else
{
/* there's no action, so we don't have a value yet */
targetObj = nil;
}
/*
* if we didn't find a value, look up the name in our
* global name table
*/
if (targetObj == nil)
{
/* look up the name */
targetObj = nameTable_[paramObj];
/*
* if we found it, and the result is a function
* pointer or an anonymous function, invoke the
* function to get the result
*/
if (dataTypeXlat(targetObj) == TypeFuncPtr)
{
/* evaluate the function */
targetObj = (targetObj)();
}
}
/*
* remember this for next time, in case the next
* substitution string doesn't include a target object
*/
lastTargetObj_ = targetObj;
lastParamObj_ = paramObj;
}
else
{
/*
* there's no implied or explicit target - use the same
* one as last time
*/
targetObj = lastTargetObj_;
paramObj = lastParamObj_;
}
/*
* if the target object wasn't found, treat the whole thing
* as a failure - put the entire parameter string back in
* the result stream literally
*/
if (targetObj == nil)
{
/* add it to the output literally, and go back for more */
result += processResult('{' + paramStr + '}');
continue;
}
/* get the property to call on the target */
prop = getTargetProp(targetObj, paramObj, info);
/* evaluate the parameter's associated property on the target */
newText = targetObj.(prop);
/* apply the appropriate capitalization to the result */
if (allCaps)
newText = newText.toUpper();
else if (initCap)
newText = newText.substr(1, 1).toUpper() + newText.substr(2);
/*
* append the new text to the output result so far, and
* we're finished with this round
*/
result += processResult(newText);
}
/* return the result string */
return result;
}
/*
* Get the property to invoke on the target object for the given
* parameter information entry. By default, we simply return
* info[2], which is the standard property to call on the target.
* This can be overridden by the language-specific subclass to
* provide a different property if appropriate.
*
* 'targetObj' is the target object, and 'paramObj' is the parameter
* name of the target object. For example, 'paramObj' might be the
* string 'dobj' to represent the direct object, in which case
* 'targetObj' will be the gDobj object.
*
* The English version, for example, uses this routine to supply a
* reflexive instead of the default entry when the target object
* matches the subject of the sentence.
*/
getTargetProp(targetObj, paramObj, info)
{
/* return the standard property mapping from the parameter info */
return info[2];
}
/*
* Process result text. This takes some result text that we're
* about to add and returns a processed version. This is called for
* all text as we add it to the result string.
*
* The text we pass to this method has already had all parameter
* text fully expanded, so this routine does not need to worry about
* { } sequences - all { } sequences will have been removed and
* replaced with the corresponding expansion text before this is
* called.
*
* This routine is called piecewise: the routine will be called once
* for each parameter replacement text and once for each run of text
* between parameters, and is called in the order in which the text
* appears in the original string.
*
* By default we do nothing with the result text; we simply return
* the original text unchanged. The language-specific subclass can
* override this as desired to further modify the text for special
* language-specific parameterization outside of the { } mechanism.
* The subclass can also use this routine to maintain internal state
* that depends on sentence structure. For example, the English
* version looks for sentence-ending punctuation so that it can
* reset its internal notion of the subject of the sentence when a
* sentence appears to be ending.
*/
processResult(txt) { return txt; }
/*
* "Quote" a message - double each open or close brace, so that braces in
* the message will be taken literally when run through the substitution
* replacer. This can be used when a message is expanded prior to being
* displayed to ensure that braces in the result won't be mistaken as
* substitution parameters requiring further expansion.
*
* Note that only open braces need to be quoted, since lone close braces
* are ignored in the substitution process.
*/
quoteMessage(str)
{
return str.findReplace(['{', '}'], ['{{', '}}'], ReplaceAll);
}
/*
* Internal routine - generate the literal text for the given source
* string. We'll remove any stuttered close braces.
*/
genLiteral(str)
{
/* replace all '}}' sequences with '}' sequences */
return str.findReplace('}}', '}', ReplaceAll);
}
/*
* execute pre-initialization
*/
execute()
{
/* create a lookup table for our parameter names */
paramTable_ = new LookupTable();
/* add each element of our list to the table */
foreach (local cur in paramList_)
paramTable_[cur[1]] = cur;
/* create a lookup table for our global names */
nameTable_ = new LookupTable();
/*
* Add an entry for 'actor', which resolves to gActor if there is
* a gActor when evaluated, or the current player character if
* not. Note that using a function ensures that we evaluate the
* current gActor or gPlayerChar each time we need the 'actor'
* value.
*/
nameTable_['actor'] = {: gActor != nil ? gActor : gPlayerChar };
}
/*
* Our output filter method. We'll run each string written to the
* display through our parameter substitution method.
*/
filterText(ostr, txt)
{
/* substitute any parameters in the string and return the result */
return generateMessage(txt);
}
/*
* The most recent target object. Each time we parse a substitution
* string, we'll remember the target object here; when a
* substitution string doesn't imply or specify a target object,
* we'll use the previous one by default.
*/
lastTargetObj_ = nil
/* the parameter name of the last target object ('dobj', 'actor', etc) */
lastParamObj_ = nil
/* our parameter table - a LookupTable that we set up during preinit */
paramTable_ = nil
/* our global name table - a LookupTable we set up during preinit */
nameTable_ = nil
/*
* Rewrite the parameter string for any language-specific rules. By
* default, we'll return the original parameter string unchanged;
* the language-specific instance can override this to provide any
* special syntax extensions to the parameter string syntax desired
* by the language-specific library. The returned string must be in
* one of the formats recognized by the generic handler.
*/
langRewriteParam(paramStr)
{
/* by default, return the original unchanged */
return paramStr;
}
/*
* our parameter list - this should be initialized in the
* language-specific subclass to a list like this:
*
* [entry1, entry2, entry3, ...]
*
* Each entry is a list like this:
*
* [paramName, &prop, impliedTargetName, <extra>]
*
* paramName is a string giving the substitution parameter name;
* this can be one word or two ('the' or 'the obj', for example).
*
* prop is a property identifier. This is the property invoked on
* the target object to obtain the substitution text.
*
* impliedTargetName is a string giving the target object name to
* use. When this is supplied, the paramName is normally used in
* message text with no object name. This should be nil for
* parameters that do not imply a particular target.
*
* <extra> is any number of additional parameters for the
* language-specific subclass. The generic code ignores these extra
* parameters, but the langague-specific subclass can use them if it
* requires additional information.
*
* Here's an example:
*
* paramList_ = [
*. ['you', &theDesc, nil, 'actor'],
*. ['the obj' &theObjDesc, &itReflexive, nil]
*. ]
*
* The first item specifies a substitution name of 'you', which is
* expanded by evaluating the property theDesc on the target object,
* and specifies an implied target object of 'actor'. When this is
* expanded, we'll call the current action to get the meaning of
* 'actor', then evaulate property theDesc on the result.
*
* The second item specifies a substitution name of 'the obj',
* expanded by evaluating property theObjDesc on the target object.
* This one doesn't have an implied object, so the target object is
* the one explicitly given in the message source text or is the
* previous target object if one isn't specified in the message
* text.
*/
paramList_ = []
;
/* ------------------------------------------------------------------------ */
/*
* Command Sequencer Filter. This is an output filter that handles the
* special <.commandsep> tag for visual command separation. This tag has
* the form of a style tag, but must be processed specially.
*
* <.commandsep> shows an appropriate separator between commands. Before
* the first command output or after the last command output, this has no
* effect. A run of multiple consecutive <.commandsep> tags is treated
* as a single tag.
*
* Between commands, we show gLibMessages.commandResultsSeparator. After
* an input line and before the first command result text, we show
* gLibMessages.commandResultsPrefix. After the last command result text
* before a new input line, we show gLibMessages.commandResultsSuffix.
* If we read two input lines, and there is no intervening text output at
* all, we show gLibMessages.commandResultsEmpty.
*
* The input manager should write a <.commandbefore> tag whenever it
* starts reading a command line, and a <.commandafter> tag whenever it
* finishes reading a command line.
*/
enum stateReadingCommand, stateBeforeCommand, stateBeforeInterruption,
stateInCommand, stateBetweenCommands, stateWriteThrough,
stateNoCommand;
transient commandSequencer: OutputFilter
/*
* Force the sequencer into mid-command mode. This can be used to
* defeat the resequencing into before-results mode that occurs if
* any interactive command-line input must be read in the course of
* a command's execution.
*/
setCommandMode() { state_ = stateInCommand; }
/*
* Internal routine: write the given text directly through us,
* skipping any filtering we'd otherwise apply.
*/
writeThrough(txt)
{
local oldState;
/* remember our old state */
oldState = state_;
/* set our state to write-through */
state_ = stateWriteThrough;
/* make sure we reset things on the way out */
try
{
/* write the text */
say(txt);
}
finally
{
/* restore our old state */
state_ = oldState;
}
}
/* pre-compile our tag sequence pattern */
patNextTag = static new RexPattern(
'<nocase><langle><dot>'
+ 'command(sep|int|before|after|none|mid)'
+ '<rangle>')
/*
* Apply our filter
*/
filterText(ostr, txt)
{
local ret;
/*
* if we're in write-through mode, simply pass the text through
* unchanged
*/
if (state_ == stateWriteThrough)
return txt;
/* scan for tags */
for (ret = '' ; txt != '' ; )
{
local match;
local cur;
local tag;
/* search for our next special tag sequence */
match = rexSearch(patNextTag, txt);
/* check to see if we found a tag */
if (match == nil)
{
/* no more tags - the rest of the text is plain text */
cur = txt;
txt = '';
tag = nil;
}
else
{
/* found a tag - get the plain text up to the tag */
cur = txt.substr(1, match[1] - 1);
txt = txt.substr(match[1] + match[2]);
/* get the tag name */
tag = rexGroup(1)[3];
}
/* process the plain text up to the tag, if any */
if (cur != '')
{
/* check our state */
switch(state_)
{
case stateReadingCommand:
case stateWriteThrough:
case stateInCommand:
case stateNoCommand:
/* we don't need to add anything in these states */
break;
case stateBeforeCommand:
/*
* We're waiting for the first command output, and
* we've now found it. Write the command results
* prefix separator.
*/
ret += gLibMessages.commandResultsPrefix;
/* we're now inside some command result text */
state_ = stateInCommand;
break;
case stateBeforeInterruption:
/*
* An editing session has been interrupted, and we're
* showing new output. First, switch to normal
* in-command mode - do this before doing anything
* else, since we might recursively show some more
* text in the course of canceling the input line.
*/
state_ = stateInCommand;
/*
* Now tell the input manager that we're canceling
* the input line that was under construction. Don't
* reset the input editor state, though, since we
* might be able to resume editing the same line
* later.
*/
inputManager.cancelInputInProgress(nil);
/* insert the command interruption prefix */
ret += gLibMessages.commandInterruptionPrefix;
break;
case stateBetweenCommands:
/*
* We've been waiting for a new command to start
* after seeing a <.commandsep> tag. We now have
* some text for the new command, so show a command
* separator.
*/
ret += gLibMessages.commandResultsSeparator;
/* we're now inside some command result text */
state_ = stateInCommand;
break;
}
/* add the plain text */
ret += cur;
}
/* if we found the tag, process it */
switch(tag)
{
case 'none':
/* switching to no-command mode */
state_ = stateNoCommand;
break;
case 'mid':
/* switching back to mid-command mode */
state_ = stateInCommand;
break;
case 'sep':
/* command separation - check our state */
switch(state_)
{
case stateReadingCommand:
case stateBeforeCommand:
case stateBetweenCommands:
case stateWriteThrough:
/* in these states, <.commandsep> has no effect */
break;
case stateInCommand:
/*
* We're inside some command text. <.commandsep>
* tells us that we've reached the end of one
* command's output, so any subsequent output text
* belongs to a new command and thus must be visually
* separated from the preceding text. Don't add any
* separation text yet, because we don't know for
* sure that there will ever be any more output text;
* instead, switch our state to between-commands, so
* that any subsequent text will trigger addition of
* a separator.
*/
state_ = stateBetweenCommands;
break;
}
break;
case 'int':
/*
* we've just interrupted reading a command line, due to
* an expired timeout event - switch to the
* before-interruption state
*/
state_ = stateBeforeInterruption;
break;
case 'before':
/* we're about to start reading a command */
switch (state_)
{
case stateBeforeCommand:
/*
* we've shown nothing since the last command; show
* the empty command separator
*/
writeThrough(gLibMessages.commandResultsEmpty());
break;
case stateBetweenCommands:
case stateInCommand:
/*
* we've written at least one command result, so
* show the after-command separator
*/
writeThrough(gLibMessages.commandResultsSuffix());
break;
default:
/* do nothing in other modes */
break;
}
/* switch to reading-command mode */
state_ = stateReadingCommand;
break;
case 'after':
/*
* We've just finished reading a command. If we're
* still in reading-command mode, switch to
* before-command-results mode. Don't switch if we're
* in another state, since we must have switched to
* another state already by a different route, in which
* case we can ignore this notification.
*/
if (state_ == stateReadingCommand)
state_ = stateBeforeCommand;
break;
}
}
/* return the results */
return ret;
}
/* our current state - start out in before-command mode */
state_ = stateBeforeCommand
;
/* ------------------------------------------------------------------------ */
/*
* Log Console output stream. This is a simple wrapper for the system
* log console, which allows console-style output to be captured to a
* file, with full processing (HTML expansion, word wrapping, etc) but
* without displaying anything to the game window.
*
* This class should always be instantiated with transient instances,
* since the underlying system object doesn't participate in save/restore
* operations.
*/
class LogConsole: OutputStream
/*
* Utility method: create a log file, set up to capture all console
* output to the log file, run the given callback function, and then
* close the log file and restore the console output. This can be
* used as a simple means of creating a file that captures the output
* of a command.
*/
captureToFile(filename, charset, width, func)
{
local con;
/* set up a log console to do the capturing */
con = new LogConsole(filename, charset, width);
/* capture to the console and run our command */
outputManager.withOutputStream(con, func);
/* done with the console */
con.closeConsole();
}
/* create a log console */
construct(filename, charset, width)
{
/* inherit base class handling */
inherited();
/* create the system log console object */
handle_ = logConsoleCreate(filename, charset, width);
/* install the standard output filters */
addOutputFilter(typographicalOutputFilter);
addOutputFilter(new transient ParagraphManager());
addOutputFilter(styleTagFilter);
addOutputFilter(langMessageBuilder);
}
/*
* Close the console. This closes the underlying system log console,
* which closes the operating system file. No further text can be
* written to the console after it's closed.
*/
closeConsole()
{
/* close our underlying system console */
logConsoleClose(handle_);
/*
* forget our handle, since it's no longer valid; setting the
* handle to nil will make it more obvious what's going on if
* someone tries to write more text after we've been closed
*/
handle_ = nil;
}
/* low-level stream writer - write to our system log console */
writeFromStream(txt) { logConsoleSay(handle_, txt); }
/* our system log console handle */
handle_ = nil
;
/* ------------------------------------------------------------------------ */
/*
* Output stream window.
*
* This is an abstract base class for UI widgets that have output
* streams, such as Banner Windows and Web UI windows. This base class
* essentially handles the interior of the window, and leaves the details
* of the window's layout in the broader UI to subclasses.
*/
class OutputStreamWindow: object
/*
* Invoke the given callback function, setting the default output
* stream to the window's output stream for the duration of the call.
* This allows invoking any code that writes to the current default
* output stream and displaying the result in the window.
*/
captureOutput(func)
{
/* make my output stream the global default */
local oldStr = outputManager.setOutputStream(outputStream_);
/* make sure we restore the default output stream on the way out */
try
{
/* invoke the callback function */
(func)();
}
finally
{
/* restore the original default output stream */
outputManager.setOutputStream(oldStr);
}
}
/*
* Make my output stream the default in the output manager. Returns
* the previous default output stream; the caller can note the return
* value and use it later to restore the original output stream via a
* call to outputManager.setOutputStream(), if desired.
*/
setOutputStream()
{
/* set my stream as the default */
return outputManager.setOutputStream(outputStream_);
}
/*
* Create our output stream. We'll create the appropriate output
* stream subclass and set it up with our default output filters.
* Subclasses can override this as needed to customize the filters.
*/
createOutputStream()
{
/* create a banner output stream */
outputStream_ = createOutputStreamObj();
/* set up the default filters */
outputStream_.addOutputFilter(typographicalOutputFilter);
outputStream_.addOutputFilter(new transient ParagraphManager());
outputStream_.addOutputFilter(styleTagFilter);
outputStream_.addOutputFilter(langMessageBuilder);
}
/*
* Create the output stream object. Subclasses can override this to
* create the appropriate stream subclass. Note that the stream
* should always be created as a transient object.
*/
createOutputStreamObj() { return new transient OutputStream(); }
/*
* My output stream - this is a transient OutputStream instance.
* Subclasses must create this explicitly by calling
* createOutputStream() when the underlying UI window is first
* created.
*/
outputStream_ = nil
;
TADS 3 Library Manual
Generated on 5/16/2013 from TADS version 3.1.3