Output Filtering

version 2 by Ron Newcomb

  • Home page
  • Beginning
  • Next



  • Documentation



    Section : Basic usage


    This extension allows us to specify rules that can modify any and all game output. Its recommended usage is solving capitalization, punctuation, and whitespace issues. It is general enough to be used for other purposes -- such as renaming people or objects throughout the game -- but this can cause a noticeable speed hit.

    By default, this extension ensures only two things. First, no more than two line breaks may occur in succession (but see below about "[blank line]"), and second, every sentence begins with a capital letter. New rules can be added to the output processing rulebook, and would typically use regular expressions on "the game's response":

        An output processing rule (this is the pilcrow rule):
            replace the regular expression "¶(¶|\s)*" in the game's response with "\n\n". [ starting with literal should be faster ; consecutive paragraph breaks act as one ]
        
        The pilcrow rule is listed before the Paragraph Break rule in the output processing rules.


    The above example rule uses the ¶ΒΆ pilcrow symbol (type Option 7 on Mac keyboards, or ALT 0182 on Windows keyboards) as a paragraph break, and furthermore ensures that multiple paragraph breaks in a row, even if interspersed with whitespace, act as a single paragraph break. (This is how a paragraph break differs from a line break -- a paragraph break is smarter. It's elastic.)

    A pair of phrases toggle output filtering, and if statements test its state:
        start output filtering;
        stop output filtering;
        if output filtering is on begin;
        if output filtering is true begin;

    And finally, to cause the filter to output what it has eaten so far,
        follow the flush output rule;

    Section : Altering the existing rules

    The Autocapitalization and Paragraph Break features may be turned off by de-listing them.
        The Paragraph Break rule is not listed in the output processing rules.
        The Autocapitalization rule is not listed in the output processing rules.

    Occasionally we may specifically want an extra blank line. The say phrase "[blank line]" inserts a blank line, first executing a paragraph break if necessary, for times when we really want extra whitespace:
        say "[blank line]";

    However, if the blank line say phrase is not used in a particular work, it may be turned off for additional code efficiency:
        Use no blank lines.

    Banner text is not normally filtered, but it can be with the use option:
        Use banner text filtering.

    The command prompt is one of the few things not filtered by this extension. Though it's recommended to use existing methods of changing it, it can be set to "", and other code, such as residing in a Before Reading a Command rule, can manually print a filterable command prompt.

    If we decide we'd like to save the game's response for later (by copying it to another variable of indexed text), we can use the "say the filtered" phrase instead of the normal say phrase.
        now the abeyance is the game's response;
        say the filtered abeyance;

    Section : Debugging the extension

    A debugging verb exists for the author:
        > OUTPUT FILTERING
        (O/o)utput filtering is now (TRUE/FALSE).

    When starting filtering, the debugging verb's output will be captured and processed the same as any other output. For example, the letter O would be capitalized.

    Debugging filter problems sometimes requires looking at the actual ZSCII codes being printed out. This can be accomplished with a use option. Note that bold and italic text is still processed, and spaces and newlines are actually printed in lieu of their ZSCII code, for greater readability of the debugging output.
        Use output filter debugging.

    Section : Important technical notes

    Very lengthy passages may exceed the size of the buffer set aside for this extension. It can be increased by raising the number in:
        Use maximum capture buffer length of at least 5000.

    No changes are needed to existing code in order to use bold and italic type, but there are two known issues. First, this extension uses the { open brace, the } close brace, and the < less-than symbol to temporarily represent the textual styles. If a work wishes to print these, then modifying the appropriate Inform 6 part of this extension would be necessary. Second, due to a limitation of regular expressions in Inform, altering the number of blank lines cannot be done with the Z-machine.