Documentation

• Example: * Intelligent Putting - Using text capture to improve implicit take messages.

This extension defines four new phrases:

    start capturing text
    stop capturing text
    say captured text
    if text capturing is active

Text that would otherwise be output to the screen is instead captured if it is generated between the first of these phrases and the second. The captured text can subsequently be displayed (or copied to an indexed text variable) using the third of these phrases.

A situation where this might typically useful is where we want not only to suppress the standard report from an action (with 'silently') but any failure reports as well. A typical pattern would be:

    *:start capturing text;
    silently try taking the noun;
    stop capturing text;

If it proved impossible to take the noun (because it was fixed in place or locked in a glass container, say), the failure message would not be displayed, and the action would be completely silent. The failure message would still be available, however: we could either display it at some other point with:

    say captured text;

Or store it in an indexed text variable to do something with it later on:

    now mytextvar is "[captured text]";

The situation where this might typically be useful is in executing a command as an implicit action. This is explained further in the example.

The test "if text capturing is active" can be used to determing whether or text capturing is currently in progress. The phrases "start capturing text" and "stop capturing text" effectively make this check in any case, so that issuing "start capturing text" when text capturing is already active does nothing, as does "stop capturing text" when text capturing is not active.

LIMITATIONS

1. The extension uses only a single text buffer, and each time a start capturing text/output something/stop capturing text sequence is executed, the buffer contents will be overwritten. You can get round this by copying the contents of the buffer to an indexed text variable, as shown above.

2. The text capture buffer can hold a maximum of 256 characters, so it should be used only for fairly short pieces of text, not huge amounts of it all at once. Overrunning the buffer will cause a run-time error in Z-Code games, and the loss of all characters beyond the 256th in Glulx games. If a larger buffer is needed, change CAPTURE_BUFFER_LEN to something larger. You can do this with the option "Use maximum capture buffer length of at least 512" (or whatever other buffer size you want).

3. To make this extension work under Glulx, character number 255 is used as an end-of-string marker. If for any reason the output between start capturing text and end capturing text includes this character, say captured text will truncate the string just before it. This is unlikely to be a problem in the vast majority of games.

4. Beware of using certain debugging verbs such as RULES or RULES ALL whenever text capturing might become active, since their output will be captured as well, almost certainly leading to overflow of the text capture buffer.