<title>TADS 3 Change History</title>

<h1>TADS 3 Change History</h1>

<p>For information on changes to the library (adv3), refer to the

<a href="../lib/adv3/changes.htm">Recent Library Changes</a> list.

<!------------------------------------------------------------------------>

<h3>Changes for 3.0.18.1 (May 5, 2009)</h3>

<ul>

<li>The behavior of the multi-method inherited() operator has changed.

The operator now chooses the inherited function to call based on the

actual argument values, rather than the formal (declared) parameters

to the current function.  This is more consistent with the inherited()

operator for regular methods.

<li>A bug in the compiler, versions 3.0.17, 3.0.17.1, and 3.0.18,

caused incorrect (too small) stack size requests to be generated for

some functions and methods.  This generally had no noticeable effect

on valid programs, but it made it possible for an errant program (with

infinite recursion, for example) to cause a stack overflow that the

interpreter doesn't detect immediately, which could conceivably crash

the interpreter.  An actual crash would require an unlikely

combination of factors, even with an errant program compiled with this

bug, so you'll probably never notice it.  Even so, if you distributed

any .t3 files compiled with t3make versions 3.0.17 through 3.0.18, we

recommend recompiling with the current t3make version and replacing

your previously distributed files, if it's easy for you to do so.

</ul>

<!------------------------------------------------------------------------>

<h3>Changes for 3.0.18 (April 28, 2009)</h3>

<ul>

<li>The <tt>inherited</tt> operator can now be used within a multi-method

to inherit an overridden version of the method.  The new syntax

<tt>inherited&lt;<i>type-list</i>&gt;(<i>arg-list</i>)</tt> lets you

inherit a specific version of the multi-method, while the basic syntax

<tt>inherited(<i>arg-list</i>)</tt> automatically selects the next

more general version of the multi-method.  See the System Manual

section on multi-methods for documentation.

<li>The compiler pre-defines the new preprocessor symbol (i.e., macro)

__TADS3, which expands simply to the number 1.  This provides an easy

way to detect that the compiler is a TADS 3 compiler (as opposed to a

TADS 2 compiler) for conditional compilation purposes.  (This might

seem redundant with the existing symbol __TADS_SYSTEM_MAJOR, but

__TADS3 can be used in one way that __TADS_SYSTEM_MAJOR can't.  If for

some reason you wanted to create a single source file that could be

compiled under TADS 2 or TADS 3, using conditional compilation to

handle the syntax differences between the language versions, you

couldn't do it with __TADS_SYSTEM_MAJOR.  This is because TADS 2

doesn't support #if, which is the only way you could use

__TADS_SYSTEM_MAJOR to conditionally compile based on compiler version

(e.g., <tt>#if __TADS_SYSTEM_MAJOR == 3</tt>).  Since TADS 2 and 3

both support #ifdef, though, you can use the presence or absence of

the __TADS3 symbol to conditionally include or omit code based on

language version.  Of course, since older versions of the TADS 3

compiler also lack this symbol, this approach requires using 3.0.17.2

or later on the TADS 3 side.)

<li>In past versions, writing to text files with a UTF-16 encoding

generated incorrect newline sequences when running on Windows.  The

problem had to do with the two-character representation of a newline

in Windows.  This has been corrected.

<li>In the past, multi-methods defined in one source file and called

from another resulted in an "undefined symbol" error.  This has been

corrected.

</ul>

<!------------------------------------------------------------------------>

<h3>Changes for 3.0.17.1 (8/12/2008)</h3>

<ul>

<li><p>A compiler bug introduced in 3.0.17 caused Workbench (and the

stand-alone interpreter) to crash when loading certain games when

compiled for debugging.  The compiler was mis-calculating some

internal data structure sizes, which effectively corrupted the .t3

file; this happened when the byte code for a function plus its debug

symbols was over a certain threshold size.  This has been corrected.

</ul>

<!------------------------------------------------------------------------>

<h3>Changes for 3.0.17 (8/9/2008)</h3>

<ul>

<li><p>The compiler has a new feature called "multi-methods."  This

implements a relatively new object-oriented programming technique

known as multiple dispatch, in which the types of <i>multiple</i>

arguments can be used to determine which of several possible functions

to call.  The traditional TADS method call uses a

<i>single-dispatch</i> system: when you write "x.foo(3)", you're

invoking the method foo as defined on the object x, or as inherited

from the nearest superclass of x that defines that method.  This is

known as single dispatch because a single value (x) controls the

selection of which definition of foo will be invoked.  With multiple

dispatch, this notion is extended so that multiple values can be

considered when selecting which method to invoke.  For example, you

could write one version of a function "putIn()" that operates on a

Thing and a Container, and another version of the same function that

operates on a Liquid and a Vessel, and the system will automatically

choose the correct version at run-time based on the types of

<i>both</i> arguments.  This new system is described more fully

in the <i>System Manual</i>.

</p>

<li><p>The compiler can now generate information in each object about the

source file where the object was defined.  This new information is

stored in a new property, sourceTextGroup; this supplements the

existing sourceTextOrder property.  Since the new information takes up

extra space in the compiled file, it's not generated by default.  To

generate it, include the new compiler option "-Gstg" in your makefile

or command line, <i>or</i> place the directive <tt>#pragma

sourceTextGroup(on)</tt> directive in each source module where you

wish to generate the information.  The #pragma lets you selectively

generate the information in specific source files, or even in specific

portions of specific source files: the corresponding directive

<tt>#pragma sourceTextGroup(off)</tt> lets you turn off the

information in a section where you don't need it.</p>

<p>When you turn on sourceTextGroup generation, the compiler

automatically adds a sourceTextGroup property to each object, just as

it automatically adds a sourceTextOrder value.  The sourceTextGroup

value is a reference to an anonymous object that the compiler

automatically creates.  One such object is generated per source module

for which sourceTextGroup generation is activated.  This object

contains two properties: sourceTextGroupName is a string giving the

name of the module, as it appeared in the compiler command line,

makefile (.t3m), or library (.tl) file; sourceTextGroupOrder is an

integer giving the relative order of the module among the list of

modules comprising the overall program.

</p>

<p>sourceTextGroup is useful in cases where you want to establish the

order of appearance in source files among objects in multiple modules.

For a given object <tt>x</tt>,

<tt>x.sourceTextGroup.sourceTextGroupOrder</tt> gives you the relative

order within the overall build of the module where <tt>x</tt> was

defined, and <tt>x.sourceTextOrder</tt> gives you the relative order

of <tt>x</tt> among the objects defined within that module.  Between

the two values, you can establish a linear ordering for all of the

statically defined objects in the entire program.</p>

<li><p>The compiler now stores "links" to resource files in the .t3 file

when compiling in Debug mode.  This makes it easier to test a game

that uses multimedia resources, by making the Build environment match

the Release environment more precisely.</p>

<p>In the past, when building in Debug

mode, the compiler completely ignored multimedia resource files listed

in the "-res" section of the command line or makefile.  This was by

design; the reasoning was that when you're compiling in Debug mode,

you'll only be running that copy on your development machine, within

your build environment, where all of the resource files are available

as local files; and since the files are all available as separate

local files anyway, we can make the compilation go faster by skipping

the step where we copy those files into the .t3 file.</p>

<p>This worked

fine <i>most</i> of the time, but it didn't work in the occasional

case where the resource name is different from the corresponding local

file's name in the file system.  One example is the Cover Art file,

which is always stored in the game under the resource name

".system/CoverArt.jpg", which is usually <i>not</i> the same name the

file has locally.  This meant that if you tried to refer to such a

resource via HTML (such as with an <IMG> tag), the resource was

reported as missing when running the debug build.</p>

<p>The new arrangement

fixes this problem without giving up the time savings.  With the new

scheme, the compiler stores a <b>link</b> for each resource in the .t3

file: this simply records the mapping from resource name to local

file name.  The HTML renderer can then look up the appropriate local

file for each resource, including any resources that have special

names.  As before, the actual contents of the resources are not

copied.

</p>

<p>Note that none of this affects Release builds.  The compiler has

always copied the full contents of all resources into the .t3 file

when doing a Release build, and continues to do so.  Release builds

continue to be fully self-contained, so that you only have to

distribute the .t3 file to players, <i>not</i> the individual

graphics and sound files it refers to.</p>

<li><p>The compiler's status output didn't add a line break after each

resource files being added to the project, resulting in poorly formatted

displays.  This has been corrected.</p>

</ul>

<!------------------------------------------------------------------------>

<h3>Changes for 3.0.16 (4/10/2008)</h3>

<ul>

<li>The Author's Kit installer now gives you an option to skip

creating the Windows file type associations for Workbench

(specifically, project (.t3m) files).

<li>The main startup routine in the library now performs an explicit

garbage collection pass just before performing pre-initialization.  In

most cases, this is unnecessary (and harmless, obviously, apart from

the added execution time required to perform the GC pass).  However,

under a certain combination of conditions, it can be important.  In

particular, it's important when a program is compiled so that preinit

is performed at run-time rather than compile-time (this is normally

the case for a "debug mode" build, but can be explicitly selected for

a release build as well), <i>and</i> the program has

pre-initialization code that performs global object loops.  In such a

program, a RESTART would re-run preinit, which could then encounter

garbage objects still around from before the RESTART.  The explicit GC

pass just before preinit ensures that preinit sees only reachable

objects in any global object loops it performs.

<li>A bug in the ByteArray intrinsic class caused an interpreter crash

when copying exactly the full bounds of an array onto itself.  This has

been corrected.

<li>The rexReplace() intrinsic function got stuck in an infinite loop

when the pattern to be replaced matched zero characters of the subject

string.  For example, a match pattern of "x*" is able to match any

number of "x" characters in a row, <i>including</i> zero of them.  The

problem was that the function simply spun its wheels, repeatedly

finding the same zero-character match and replacing it over and over.

This no longer occurs: the function will apply each zero-character

replacement once only, and then move on to the next character of the

subject string before attempting a new match.

<li>The rexSearch() and rexReplace() functions didn't properly take

into account "^" (start-of-string) pattern specifiers when a starting

offset for the search was explicitly specified.  The functions

incorrectly considered "^" to match the start of the substring

starting at the given starting offset, whereas it should have only

matched the start of the entire string.  In other words, "^" should

never match when the starting offset is greater than 1.  This has been

corrected.

<li>A bug in the t3DebugTrace() intrinsic function sometimes caused the

debugger to stop execution at the second line after the t3DebugTrace()

function, rather than at the next line.  This happened if you used the

"Go" command to resume execution from the point where t3DebugTrace()

stopped, then encountered the same t3DebugTrace() call without any

intervening debugger activity.  This has been corrected.

<li>Comparing another object value to "self" in a global breakpoint

expression sometimes caused the debugger to crash in past versions.

This has been corrected.

<li>In the past, the compiler returned a "success" indication to the

operating system shell as long as no error messages were displayed

during the compilation.  This was incorrect in cases where the "treat

warnings as errors" option was enabled and one or more warning

messages were displayed; in these cases, the compiler should have

returned a "failure" indication to reflect the fact that warnings

count as full-fledged errors under this option setting.  This has

been corrected.

<li>Applying toInteger() to BigNumber values near the capacity limits

of the 32-bit integer type, but not exceeding them, sometimes produced

spurious "numeric overflow" errors.  In particular, values over

2147483640 or under -2147483640 that needed to be rounded up in their

fractional parts (e.g., 2147483640.9) produced this spurious error.

This has been corrected.

</ul>

<!------------------------------------------------------------------------>

<h3>Changes for 3.0.15.3 (11/2/2007)</h3>

<ul>

<li>A bug in the compiler made it impossible to refer to items in

global scope (such as enum values or objects) in constant expressions

within anonymous functions.  For example, it was impossible to use

an enum value or object name as a 'case' label in a 'switch' statement

within an anonymous function.  This has been corrected.

<li>A bug in the GrammarProd intrinsic class caused incorrect results

in some cases for an empty production (i.e., a grammar rule consisting

of no tokens).  The problem had to do with the way the empty

production figured its position in the input token list; since

enclosing levels in the match tree find their positions relative to

child nodes, the problem typically manifested itself by giving

incorrect token list positions for one or more match levels enclosing

an empty match.  This is now fixed.

</ul>

<!------------------------------------------------------------------------>

<h3>Changes for 3.0.15.2 (9/13/2007)</h3>

<ul>

<li>The inputFile() function now makes some additional checks when the

filename is supplied by an active event script file.  If the dialog

type is InFileOpen, the function checks to make sure the filename read

from the script refers to an existing file.  If the dialog type is

InFileSave, and the named file doesn't already exist, the function

tries to create a dummy copy of the file; if that succeeds, the

function immediately deletes the dummy copy.  The function also still

tests, as it did before, to make sure the file <i>doesn't</i> already

exist for InFileSave dialogs.  If any of these tests fail, the

function warns the user about the problem and offers the same options

it did in the past for the save-overwrite case: use the filename as

given in the script, choose a different file, or cancel the script

playback.

<li>A bug in the VM caused sporadic, unpredictable errors when

finalizers were used.  The problem affected one opcode (OPCGETPROPR0);

if a finalizer invocation happened to interrupt this particular

opcode, the result was unpredictable, but could include spurious

run-time errors or corruptions of calculated results.  This has been

corrected.

</ul>

<!------------------------------------------------------------------------>

<h3>Changes for 3.0.15.1 (7/19/2007)</h3>

<ul>

<li>The keyword <tt>replaced</tt> can now be used within anonymous

functions that are nested in modifier functions (i.e., functions

defined with <tt>modify <i>funcname</i> ...</tt>).  In the past, the

compiler only allowed <tt>replaced</tt> to be used <b>directly</b>

within a modifier function - not in nested anonymous functions defined

within a modifier function.  There's no inherent reason for

disallowing this construct; it was simply a limitation of the

compiler, which has now been lifted.

<li>In the system library, the several internal convenience macros

defined with the Tokenizer class (tokRuleName, tokRulePat,

tokRuleType, etc) have been moved from the tok.t class file to the

tok.h header file.  The macros are unchanged, so this change won't

affect existing code.  The macros were formerly defined in tok.t

rather than in the header because they were meant as private macros

for internal use within the Tokenizer class itself, not for client

code that uses the Tokenizer class.  However, they're also useful in

subclasses of Tokenizer, so it's desirable to have them defined in a

header - that way, user code implementing Tokenizer subclasses can

access the macros simply by #including tok.h.

<li>The compiler is now stricter about interpreting tokens as

BigNumber constants.  In the past, the compiler treated an "E"

following a numeric constant as an exponent signifier, even if no

digits followed.  For example, "3E-a" was taken to be the BigNumber

constant "3E-0", followed by a separate token "a".  The compiler now

treats an "E" as the start of a separate token if no digits follow it

(or the optional + or - sign after the "E"), so "3E-a" would now be

treated as four tokens: "3", "E", "-", and "a".

<li>The compiler now displays a specific error if it finds a decimal

digit within an octal constant value.  In the past, the compiler

simply assumed that a decimal digit terminated the octal constant

token and started a new token.  This typically led to a confusing

parsing error, since the compiler saw two consecutive numeric constant

tokens where the user almost always intended one.  The compiler now

flags a specific error about the ill-formed octal value, and skips any

decimal digits following the octal constant, which makes the error

much easier to pinpoint.

<li>The compiler is now strict about disallowing the old TADS 2

"<>" (unequal-to) operator.  This variation was not documented,

but has up to now been allowed.

<li>The compiler no longer treats <tt>delete</tt> as a reserved word.

(It did so in the past as a hold-over from TADS 2, where

<tt>delete</tt> is indeed reserved.)

</ul>

<!------------------------------------------------------------------------>

<h3>Changes for 3.0.15 (3/8/2007)</h3>

<ul>

<li>When an input event script is being played back, the inputFile()

function now prompts the user if the result would likely overwrite an

existing file.  inputFile() in this case prompts the user

interactively, momentarily halting script playback until the user

responds.  This is described more fully in the Input Scripts section

of the System Manual.

<li>The compiler reported an internal error ("too much unsplicing") in

certain complex expressions involving multi-line string literals as

macro arguments in embedded &lt< >> expressions.  This has

been corrected.

</ul>

<!------------------------------------------------------------------------>

<h3>Changes for 3.0.14 (2/9/2007)</h3>

<ul>

<li>The raiseToPower() method of the BigNumber class incorrectly

returned 1 as the result of raising 0 to a non-zero exponent.  The

correct result should, of course, be 0 for any positive exponent, and

an exception for any non-positive exponent (as 0^0 is undefined, and

0^n with n<0 is effectively division by zero).  The method now

yields these results.

</ul>

<!------------------------------------------------------------------------>

<h3>Changes for 3.0.13 (1/19/2007)</h3>

<ul>

<li>A new t3make option, -we, tells the compiler to treat warnings as

though they were errors, for the purposes of determining whether or

not to proceed with compilation after a warning occurs.  When the

compiler finds an error within a source file, it stops the build

process after finishing with that compilation unit, requiring you to

fix the error before continuing.  In contrast, warnings do not, by

default, interrupt the build.  This is because a warning message

indicates a situation that's <i>technically</i> correct, but which

contains a common pitfall.  Compiler warnings tend to be right often

enough to warrant close inspection, so many programmers adhere to the

discipline of insisting on "clean" builds every time - that is, with

no warning messages.  The -we option is a convenient way of enforcing

that discipline.  When you specify the -we option, the compiler will

stop the build after finishing with any module that generates any

warning messages, just as it does for error messages.  If you want

to explicitly set the default mode, where warnings do not interrupt

the build, use the -we- option.

<li>A new interpreter (t3run) option, -I, runs a command script in

"echo" mode.  This works almost the same as the existing -i option,

but -I causes all output to be displayed to the console as the script

is read; in contrast, -i reads the script in "quiet" mode, meaning

that no output is displayed while the script is running.

<li>The command script recorder and player can now handle virtually

any input event type, not just command lines.  The script mechanism

can now handle keyboard input, hyperlinks, ad hoc dialogs, and file

dialogs; the functions inputKey(), inputEvent(), inputFile(), and

inputDialog() can now take their input from a script.  (inputLine()

and inputLineTimeout() have always been able to read from scripts.)

To handle the greater range of event types, a new script file format

has been added; files written in new format are called Event Scripts.

Event scripts are identified by a special signature: the first line of

the file must read <tt>&lt;eventscript&gt;</tt>, with nothing else on

the line (not even spaces).  If a script doesn't start with this

signature, the script reader will interpret it as the original script

format, which is now called the Command-line Script.  This allows old

scripts to work without changes; of course, Command-line Scripts can

only contain line input events, as they always have.  When you create

a script with RECORD or the with the Interpreter's -o option, the

script is now recorded in the new Event Script format, and the

recorder will automatically include all event types in the script.

(There's no option with RECORD or -o to record an old-style

Command-line Script instead - there wouldn't seem to be much call for

this, as the functionality in Event Scripts is a superset of that of

Command-line Scripts.)  The new scripting functionality is described

in the "Input Scripts" chapter of the System Manual.

<li>The setScriptFile() intrinsic function now accepts a new type

code, LogTypeEvent.  This type signifies that a new-style Event Script

should be created.  The code LogTypeCommand, which was present in

previous versions, continues to signify that an old-style Command-line

Script should be created.

<li>Input scripts now nest during playback.  In the past, reading from

a new input script terminated reading from any input script already in

effect.  Now, the console suspends the original script, and resumes

reading from it upon reaching the end of the new script.  Scripts can

be nested to any depth.  This allows an input script to "include"

another by using, for example, the REPLAY command within the script.

<li>In the past, the getFuncParams() intrinsic function didn't accept

an anonymous function as its argument.  Anonymous functions are now

accepted.

<li>The inputLine() intrinsic function (in the 'tads-io' function set)

didn't correctly map non-ASCII characters (such as accented letters)

from the user's input to Unicode.  This has been corrected.

<li>A compiler bug caused a crash if a "modify" or "replace" statement

in one source module referred to a symbol that was actually defined in

a source module that was included in the build after the first source

file.  This is an error condition anyway - a symbol has to be defined

in the build before it can be modified or replaced, so the original

definition has to occur in a source module listed earlier than the

modifying module.  However, the compiler now handles such an error

properly, by displaying the appropriate error message and halting the

build.

<li>A bug in File.writeBytes() caused unpredictable results, sometimes

including an interpreter crash, if a zero or negative value was passed

for the starting index.  The starting index is now checked for range.

<li>Some internal changes to the portable VM and compiler code have

been made to improve portability to 64-bit architectures.

</ul>

<!------------------------------------------------------------------------>

<h3>Changes for 3.0.12 (9/15/2006)</h3>

<p><b>This is the TADS 3.0 General Release version.</b>

<ul>

<li>A couple of compiler error messages were internally mis-numbered,

which could have caused the compiler to report the wrong error message

for the affected error codes.  These have been corrected.

</ul>

<!------------------------------------------------------------------------>

<h3>Changes for 3.0.11 (9/8/2006)</h3>

<ul>

<li>The % operator now accepts only integer operands.  (In the past,

it failed to throw an error if a BigNumber operand was used, and

instead produced a meaningless result.)

<li>A comparison of the form "a==b", where a is an integer value and b

is a BigNumber value, now coerces the integer to a BigNumber before

comparing it.  In the past, this type of comparison coerced the

integer to a BigNumber only when the BigNumber was the left-hand

operand.  This correction ensures that "a==b" and "b==a" yield the

same results when comparing integers and BigNumber values.  The same

change applies to the != operator.

<li>In the past, the compiler reserved the names <tt>void</tt>,

<tt>int</tt>, <tt>string</tt>, <tt>list</tt>, <tt>boolean</tt>, and

<tt>any</tt>.  These names are no longer reserved and thus can now be

used freely as symbol names (for local variables, object names, etc).

(These names were originally reserved in anticipation of the eventual

introduction of optional static type declarations.  Reserving the

keywords ensured that no one would write code that would be

incompatible if the feature had ever been added.  The static typing

feature will definitely not appear in the official 3.0 release, and at

this point it seems very unlikely to be in any future version, so

there's no longer any good reason to reserve these names.)

<li>A compiler bug caused invalid code to be generated in the following

situation:

<p><pre>

   x: object

     m(p) { }

     n = (p)  // bad code generated here

     p = nil

   ;

</pre>

<p>The bad code resulted from the compiler mistakenly using the local

symbol table from the method m(p) while generating the code for n; so

the compiler incorrectly treated p as a parameter variable in n, even

though n has no parameters.  This has been corrected.

<p>The local-to-Unicode character set mapper now converts any

unmappable character found in a source string to Unicode U+FFFD, the

standard Unicode "replacement character."  In the past, the mapper

converted unmappable characters to question marks, "?".  Converting to

question marks was undesirable because of the ambiguity it created.

When compiling source code, for example, it led the compiler to think

that the source file literally contained a question mark where the

unmappable character was found; the diagnostics the compiler reported

in these cases were thus confusing and misleading.  Unicode defines

the character U+FFFD specifically for the purpose of replacing source

characters that cannot be mapped to Unicode; this gives the compiler

and other consumers of mapped characters an unambiguous indication

that the original input character was unmappable.  The compiler uses

this new information to report a specific diagnostic message when it

finds a U+FFFD in the input stream.

</ul>

<!------------------------------------------------------------------------>

<h3>Changes for 3.0.10 (8/17/2006)</h3>

<ul>

<li>Libraries (".tl" files) can now easily include their own

multimedia resources in a build.  In the past, there was no direct

support for multimedia resources in libraries; an author using a

library that included multimedia resources would have had to copy the

library resources into the game's directory tree and then explicitly

add those resources to the build.  This is no longer necessary.  Two

new features support library resources:

  <ul>

  <li>First, Workbench for Windows now automatically adds each

  top-level library's directory path to the search list for individual

  resource files (.jpg, .png, .ogg, etc).  Note that a "top-level"

  library is a library included directly in the Project window; a

  library included from within another library isn't top-level, so

  it's directory won't be included in the search list.  When running

  the game under the debugger, this allows individual resources to be

  found under any library's directory tree.

  <li>Second, the compiler accepts a new "resource:" keyword in

  library (.tl) files.  After this keyword, list one individual

  resource file, or one directory containing resource files.  You can

  use this keyword as many times as you like to include multiple files

  or directories.  As usual for library files, the file or directory

  mentioned after the "resource:" keyword is given with a URL-style

  relative path, relative to the library containing the library file.

  </ul>

These new features allow a library to include multimedia resources

with complete transparency to game authors using the library - game

authors won't have to do anything extra to use the library multimedia

resources.  Library authors only have to perform a few easy extra

steps.  First, create a subdirectory of your library directory to

contain the resources.  For example, if your library is called

mylib.tl, create a "mylibres" subdirectory under the directory

containing mylib.tl.  (The name isn't important, but it's desirable to

pick a unique enough name that there won't be any conflict with other

libraries that game authors might also be including.  Your resources

will be named relative to the subdirectory name, so don't pick a

generic name like "resources" - it's best to use a name that

incorporates your library name.)  Second, put all of your library's

resources (.jpg files, .png files, etc.) in your new subdirectory.

Third, add the line "resource: mylibres" to your .tl file; this will

tell the compiler to bundle all of the files in the "mylibres"

subdirectory into the compiled .t3 file when a game includes your

library.  Finally, in the HTML that your library generates to

reference your resources, refer to them using your subdirectory path -

for example, you'd write <IMG SRC="mylibres/compass.png"> to

refer to an image resource file.

<li>The <a href="sysman/t3vm.htm">t3GetStackTrace()</a>

function (in the 't3vm' function set) has a new optional argument that

lets you get information on a single stack level.  This provides more

efficient access to stack trace information in cases where you only

want information on a specific level, such as the immediate caller.

<li>When a game is compiled into a stand-alone executable (on systems

where this is implemented, such as Windows), it's now possible to pass

command-line arguments to the embedded .t3 program.  To do this, use a

dash ("-") to separate the interpreter arguments from the program

arguments.  The stand-alone version of the interpreter is also now

strict about not accepting an image file argument; this means that you

can't use a bundled stand-alone game to run a different .t3 image file.

<li>You can now write directly to the main game window's log file, if

one is open.  (This is the log file that's opened via the setLogFile()

function - the one that the library creates when the player types the

SCRIPT command.)  There are two ways to write to the log file.  The

simple way is to use the new <LOG> tag - this tag is simply the

complement of the <NOLOG> tag: any text enclosed between

<LOG> and </LOG> will be included only in the log file,

and hidden in the game window.  This approach is usually the right

one, because you can mix your log-only text directly with other output

text, ensuring that it's processed through the usual stack of output

filters and the like.  However, on occasion it's useful to be able to

bypass the usual output stream mechanism, which brings us to the

second way: you can use logConsoleSay(), passing in the special handle

value MainWindowLogHandle as the handle.  Using this approach bypasses

mainOutputStream and all of its filters, and goes directly to the log

file.

<li>The compiler now warns on nested block comment ("/* ... */"

comments).  If the compiler finds a "/*" sequence within a block

comment, it generates a warning.  (Nested block comments aren't

allowed, so a "/*" within a block comment usually indicates that a

previous comment wasn't terminated properly.  The warning makes it

easier to notice such cases.)

<li>The compiler now automatically word-wraps error messages to 80

columns when the "verbose" error message option is selected.  This

makes the long error messages much easier to read, especially in

Workbench, which has an essentially infinitely wide message window -

the word-wrapping saves you the trouble of manually scrolling

horizontally to see the full message text.

<li>A bug in the compiler sometimes caused a crash if a 'foreach'

statement was used in a source file which never #included the system

headers.  The compiler correctly flagged the error, but didn't always

recover properly.  The compiler now handles this situation gracefully.

<li>A bug in the compiler caused the compiler to ignore the last line

of a library (.tl) file when the last line didn't end in a newline

character of some sort.  The same bug affected Workbench on Windows.

This has been corrected.

<li>A bug in the compiler caused incorrect results when a 'grammar'

statement's token list started with an empty alternative.  For

example, the token list "( | 'x')" was compiled incorrectly.  This

problem only occurred when the empty alternative was the <i>first</i>

element of the entire token list.  This has been corrected.

<li>In the past, the TadsObject type didn't retain 'undo' information

when the superclass list was changed with setSuperclassList().  This

meant that if an object's superclass was changed, an 'undo' operation

didn't properly restore the original superclass list.  This has been

corrected; this undo information is now properly retained and applied.

<li>A bug introduced in 3.0.9 caused the interpreter to misinterpret

certain Unicode characters outside of the plain ASCII range when

entered on a command line.  This has been fixed.

<li>A bug in TadsObject.setSuperclassList() caused sporadic problems.

The bug was most likely to manifest itself as a stack overflow error

when a call to self.setSuperclassList() was the first (or nearly the

first) executable code within a method.  The bug is now fixed.

<li>The regular expression parser didn't accept the special character

pattern <tab>, which is documented as matching the character

'\t' (or, equivalently, '\u0009').  This has been corrected.

<li>The regular expression parser didn't formerly classify as

whitespace several control characters that are conventionally

considered whitespace.  This was due to a strict interpretation of the

character properties defined in the Unicode character database, which

defines all of the ASCII control characters as class "Other" rather

than "Separator."  The Unicode database has some additional property

information, though, that does mark the appropriate control characters

as whitespace, and the character classifier now takes this extra

information into account.  This means that characters \u0009 (tab),

\u000A (line feed), \u000B (line tab), \u000C (form feed), \u000D

(carriage return), \u001c (IS4), \u001d (IS3), \u001e (IS2), and

\u001f (IS1) are now considered whitespace, and thus match the

<space> character class pattern in regular expressions.

<li>In the past, the compiler always assumed it was running under a

DOS box, so it used the DOS box code page for any messages it

displayed.  On most systems, depending on localization, the DOS box

uses a different code page from the Windows code page used by native

Windows applications; this is because the DOS box is designed for

compatibility with old MS-DOS applications, which sometimes rely upon

the DOS line-drawing characters and so forth.  This occasionally

caused odd character mapping problems in error messages when compiling

from Workbench, because Workbench uses the standard Windows code page

instead of the DOS code page.  This has been corrected, as follows:

the compiler now checks to see if it's associated with a DOS box

window, and uses the DOS box code page for its error messages if so,

or the regular Windows code page if not.

</ul>

<!------------------------------------------------------------------------>

<h3>Changes for 3.0.9 (8/29/2005)</h3>

<ul>

<li>The banner API has a new pair of style flags: BannerStyleHStrut

("horizontal strut") and BannerStyleVStrut ("vertical strut").  These

style flags let you specify that bannerSetSize() should take a child

banner's width (horizontal strut) and/or height (vertical strut) into

account when figuring the parent banner's content size.  By default,

only the contents of the parent banner are considered, but these new

styles let you include a child's contents in the parent banner's size

calculation.

<li>The File intrinsic class has a new feature in its various "open"

methods.  The filename passed to an "open" method can now be one of a

set of distinguished values (defined in file.h) that identify

"special" files.  These are files that are meant to be used for

particular purposes.  Rather than opening these files by name, you

open them by specifying their special identifiers.  The interpreter

determines the actual name and location of a special file in the local

file system.  This allows the interpreter to use different names of

paths on different systems, to better conform to local conventions.

Currently, there's only one special file defined: LibraryDefaultsFile,

which is a text file that's used to store the library's global

settings.

<li>The new GrammarProd method <a href="sysman/gramprod.htm">

getGrammarInfo()</a> provides programmatic access to information on

GrammarProd objects, which allows the game to retrieve full

information on the 'grammar' statements in the source code.  Sample

code demonstrating how to use the new method to display a production's

internal information in human-readable format is included in the

samples directory, in the file gramdisp.t.

<li>The interpreter now uses the default file-contents character set

rather than the display character set as the default for log file

output.  On most systems, this change won't have any noticeable

effect, as the default display and file-contents character sets are

usually the same anyway.  However, on a few systems, the display and

file-contents character sets can differ; it makes more sense on these

systems to use the file-contents character set for log files than it

does to use the display character set, since it's usually desirable to

treat log files as ordinary text files.

<li>The new interpreter option "-csl <i>charset</i>" lets you

explicitly specify the character set for log files, overriding the

default.  (The default log file character set is the file-contents

character set, as described above.)

<li>The logConsoleCreate() function now accepts nil for the character

set argument.  This chooses the default log file character set.

<li>In tadsio.h, the constant InEvtNotimeout has been renamed to

InEvtNoTimeout (that is, the "T" in "Timeout" has been capitalized).

This change is simply cosmetic, for better consistency with the naming

convention that each word in a symbol name starts with a capital

letter.  (The "o" in "Timeout" is still a minuscule, and this is

consistent with the naming convention: in computerese, "timeout" is

usually considered a single word.)  To avoid breaking compatibility

with code based on previous versions, the old name is still defined as

a synonym for the new name.

<li>The Vector class's constructor now throws an error ("value out of

range") if the maximum-length argument exceeds 65535, which is the

maximum number of elements that a Vector can have.  (In the past,

attempting to create a vector with a maximum length of more than 65535

appeared to succeed, but didn't really; it actually created a vector

with a maximum of <i>n</i> mod 65536, where <i>n</i> was the given

length.)

<li>The compiler incorrectly considered the statement following a

'do-while' loop reachable if the loop's condition wasn't a constant

'true' expression, even if the condition itself was never reachable

and the loop contained no 'break' statements.  This caused the

compiler to issue spurious warnings in certain obscure situations,

such as when such a 'do-while' was at the end of a function that had

returned values elsewhere; it also caused the compiler to fail to

generate an "unreachable statement" warning when a statement followed

such a loop.  The compiler now correctly realizes that the statement

following such a loop is unreachable, and generates control flow

warnings accordingly.

<li>A compiler bug sometimes caused problems when generating code

involving a nested anonymous function (that is, an anonymous function

defined within another anonymous function), which was defined within

an object method, <i>and</i> which made reference to local variables

defined within two or more enclosing lexical contexts.  The problem

only affected code with all of these attributes, and then only showed

up some of the time.  The problem manifested itself as a spurious

run-time error ("invalid index operation - this type of value cannot

be indexed") when the nested anonymous function was invoked.  This

has been corrected.

<li>A bug in the compiler caused sporadic problems that sometimes

included crashing the compiler when source code contained a constant

expression involving a list indexed by a value exactly one greater

than the number of elements in the list, as in "[1,2][3]".  The

problem only occurred when everything in the expression - all of the

list elements, as well as the index value - was a constant.  This has

been fixed.

<li>Due to a bug, the compiler didn't recognize the "^="

(XOR-and-assign) operator.  This has been corrected.

<li>A bug in the rexGroup() function caused the interpreter to crash

in a particular, rare situation: specifically, when rexGroup() was

called immediately after a call to rexSearch() or rexMatch() that

caused a run-time error.  This has been corrected.

<li>A bug in the interpreter sometimes caused unpredictable behavior,

including crashes, when t3SetSay() was used to set a property pointer

handler, and a double-quoted string was then displayed from within a

function (not an object method).  This has been fixed.