Diff | Source/Git

Download diff

	4b825dc642cb6eb9a060e54bf8d69288fbee4904		cfad47cfa334b206c65f22086bcc5d63e6f70944
		1	<html>
		2
		3	<title>TADS Revision History</title>
		4
		5	<body>
		6
		7	<br><br><br>
		8	<center><font size=+3>Recent Changes to TADS</font>
		9	</center>
		10
		11	<h4>Index to Versions</h4>
		12	<ul>
		13	<li><a href='#tads2514'><b>Version 2.5.14</b></a><br>
		14	<li><a href='#tads2513'><b>Version 2.5.13</b></a><br>
		15	<li><a href='#tads2512'><b>Version 2.5.12</b></a><br>
		16	<li><a href='#tads2511'><b>Version 2.5.11</b></a><br>
		17	<li><a href='#tads2510'><b>Version 2.5.10</b></a><br>
		18	<li><a href='#tads259'><b>Version 2.5.9</b></a><br>
		19	<li><a href='#tads258'><b>Version 2.5.8</b></a><br>
		20	<li><a href='#tads257'><b>Version 2.5.7</b></a><br>
		21	<li><a href='#tads256'><b>Version 2.5.6</b></a><br>
		22	<li><a href='#tads255'><b>Version 2.5.5</b></a><br>
		23	<li><a href='#tads254'><b>Version 2.5.4</b></a><br>
		24	<li><a href='#tads253'><b>Version 2.5.3</b></a><br>
		25	<li><a href='#tads252'><b>Version 2.5.2</b></a><br>
		26	<li><a href='#tads251'><b>Version 2.5.1</b></a><br>
		27	<li><a href='#tads250'><b>Version 2.5.0</b></a><br>
		28	</ul>
		29
		30	<h4>Organization of this Page</h4>
		31
		32	<p>This page is a list of recent changes to TADS, arranged
		33	chronologically: changes are grouped by release, with the most recent
		34	release listed first. Each release incorporates all new features and
		35	corrections of each prior release unless otherwise stated.
		36
		37	<h4>Generic and Platform-Specific Changes</h4>
		38
		39	<p>
		40	Since version 2.2.6, the TADS change log has been divided into
		41	two separate files: one for "generic" changes that apply to TADS on
		42	all types of computers and operating systems, and one for changes
		43	that apply only to specific platforms. This file contains the
		44	generic release notes. Platform-specific release notes are in a
		45	separate file for each platform:
		46
		47	<blockquote>
		48	<p><a href='dosver.htm'>Changes specific to MS-DOS and Windows</a>
		49	</blockquote>
		50
		51	<h4>Multimedia vs. Text-Only Interpreters</h4>
		52
		53	<p>These release notes sometimes refer to the "character-mode" or
		54	"text-only" TADS Interpreter. This is meant to distinguish the
		55	traditional TADS Interpreter, which can only display text, from the
		56	multimedia interpreters such as HTML TADS and HyperTADS, which can
		57	display graphics as well as text. The traditional TADS Interpreter
		58	has a graphical user interface on some systems, such as the
		59	Macintosh, so it's not really a character-mode application on those
		60	systems; nonetheless, we still refer to it here as the character-mode
		61	Interpreter simply to make it clear that we're not talking about one
		62	of the multimedia versions.
		63
		64	<h4><a name='oldlog'>Older Revisions</a></h4>
		65
		66	<p>To keep the size of this page under control, changes are listed here
		67	only for the most recent several versions of TADS. Older release notes
		68	are in separate files:
		69
		70	<ul>
		71	<li>Generic changes from version 2.2.3 through 2.4.0 are in TADSV240.TXT.
		72
		73	<li>DOS-specific changes from version 2.2.3 through 2.4.0 are in
		74	TADSV240.DOS.
		75
		76	<li>For DOS, all revisions from 2.0 through 2.1.0 are available in the
		77	file TADSV200.DOS; those from 2.1.1 through 2.2.2 are in TADSV222.DOS.
		78
		79	<li>Similar files are available for
		80	other platforms; please refer to your platform-specific release
		81	notes for details.
		82
		83	</ul>
		84
		85	<p>Because the older revision history files are quite large and are
		86	static (they are, after all, historical), they're not included in the
		87	normal TADS distributions, but you can download them from the
		88	Interactive Fiction Archive via the internet at <a
		89	href='ftp://ftp.ifarchive.org/if-archive/programming/tads2/manuals/'>
		90	ftp://ftp.ifarchive.org/if-archive/programming/tads2/manuals/</a>
		91	(note that ftp.ifarchive.org is the new home, effective August 2001,
		92	of the former ftp.gmd.de archive).
		93
		94	<!------------------------------------------------------------------------>
		95	<br><br><hr>
		96	<h3><a name='tads2514'>Version 2.5.14</a></h3>
		97	<i>Released on May 5, 2009</i>
		98
		99	<ul>
		100
		101	<li>Objects created with 'new' during the preinit phase are now marked
		102	as ordinary objects in the .gam file, as though they'd been defined
		103	statically in the source code. The same thing applies to the
		104	vocabulary words they use. This change means that objects created
		105	dynamically during preinit are effectively permanent: they persist
		106	through RESTART, RESTORE, UNDO, and the like, and they can't be
		107	deleted with the 'delete' operator.
		108	(<a href="http://bugdb.tads.org/view.php?id=0000055">bugdb.tads.org #0000055</a>)
		109
		110	</ul>
		111
		112
		113	<!------------------------------------------------------------------------>
		114	<br><br><hr>
		115	<h3><a name='tads2513'>Version 2.5.13</a></h3>
		116	<i>Released on April 28, 2009</i>
		117
		118	<ul>
		119
		120	<li>The new systemInfo() codes __SYSINFO_AUDIO_FADE and
		121	__SYSINFO_AUDIO_CROSSFADE let you determine if the interpreter
		122	supports audio fades and audio cross-fades, respectively. (Audio
		123	fades are accessed through the HTML TADS <SOUND> tag.) These
		124	codes return nil or 0 if fades/cross-fades aren't supported at all, or
		125	an integer giving a combination of bit-flags indicating which audio
		126	formats support fades/cross-fades. The bit flags are
		127	__SYSINFO_AUDIOFADE_WAV, __SYSINFO_AUDIOFADE_MPEG,
		128	__SYSINFO_AUDIOFADE_OGG, and __SYSINFO_AUDIOFADE_MIDI (for WAV, MP3,
		129	Ogg Vorbis, and MIDI files, respectively). For example, if
		130	systemInfo(__SYSINFO_AUDIO_FADE) returns (__SYSINFO_AUDIOFADE_WAV \|
		131	__SYSINFO_AUDIOFADE_OGG), it means that WAV and Ogg Vorbis files
		132	support fades, but other audio formats don't.
		133
		134	<li>A bug in the compiler sometimes made the debugger show the wrong
		135	source location when single-stepping within a single-line expression
		136	property. (That is, a property with an executable expression, but no
		137	curly braces, with the whole definition on a single line of text.)
		138	This bug was mostly cosmetic, but in rare cases triggered a separate
		139	bug in the debugger that could crash the debugger. When a single-line
		140	expression property was immediately followed by a single-line method
		141	(with braces), and execution stopped in the method due to
		142	single-stepping or due to a run-time error, the debugger was unable to
		143	show the execution location, and sometimes even crashed. Both of
		144	these bugs are now fixed.
		145
		146	</ul>
		147
		148
		149	<!------------------------------------------------------------------------>
		150	<br><br><hr>
		151	<h3><a name='tads2512'>Version 2.5.12</a></h3>
		152	<i>Released on September 28, 2008</i>
		153
		154	<ul>
		155
		156	<li>The cvtnum() built-in function returned the wrong result for
		157	negative values on occasion. The problem was dependent on chance
		158	arrangements of the run-time string/list heap, so it occurred
		159	essentially at random. This has been corrected - cvtnum() now
		160	correctly stops at the end of the string. (<b>Workaround for
		161	older versions:</b> append a non-digit character to the cvtnum()
		162	argument - e.g., <tt>cvtnum(str + ';')</tt>. The problem was that
		163	cvtnum() didn't properly detect the end of the input string, so it
		164	sometimes scanned into random bytes in memory following the string
		165	<i>if</i> those bytes happened to look like ASCII digits. However,
		166	the function did always correctly stop upon reaching any non-digit
		167	character, so explicitly appending a non-digit was enough to make the
		168	function stop scanning, ensuring that it wouldn't stray past the end
		169	of the string. This workaround isn't necessary with 2.5.12 and later,
		170	since the underlying problem in cvtnum() is now fixed, but you can use
		171	the workaround if you want to ensure compatibility with older
		172	interpreter versions that some players might still be using.)
		173
		174	<li>In the past, run-time error messages (e.g., "[TADS-1010: object
		175	value required]") were omitted from the transcript. This was
		176	particularly inconvenient for beta testing, since any errors
		177	encountered by testers were invisible in their session logs. These
		178	messages are now included in the transcript.
		179	(<a href="http://bugdb.tads.org/view.php?id=0000032">bugdb.tads.org #0000032</a>)
		180
		181	</ul>
		182
		183
		184	<!------------------------------------------------------------------------>
		185	<br><br><hr>
		186	<h3><a name='tads2511'>Version 2.5.11</a></h3>
		187	<i>Released on August 9, 2008</i>
		188
		189	<ul>
		190
		191	<li>The parser now leaves the antecedent of "it" intact when a command
		192	involves a number or string. That is, "it" will simply refer to the
		193	noun phrase from the second-most-recent command when the most recent
		194	command involves a number or string as its noun phrase: "x box; note
		195	5; x it" will now treat the "it" in the last command as referring to
		196	the box. In the past, the parser simply forgot any antecedent in this
		197	type of situation. That was intentional, to avoid any confusion over
		198	whether "it" should refer to the number or string, but in practice
		199	players don't seem to find this confusing at all and expect "it" to
		200	continue referring to the last real object.
		201	(<a href="http://bugdb.tads.org/view.php?id=0000014">bugdb.tads.org #0000014</a>)
		202
		203	<li>The parser showed a somewhat confusing parser error message for
		204	player commands of the form "verb x OF y" in some cases. If x and y
		205	were valid nouns or adjectives, but the combination "x OF y" didn't
		206	match any object's vocabulary (e.g., there's a BOX and some PAPER, but
		207	there's no such object as BOX OF PAPER), the parser treated this
		208	command as though it were a <i>two-object</i> verb, such as PUT IN or
		209	LOCK WITH - that is, the OF was treated as a verb-phrase preposition,
		210	and x and y were treated as (respectively) the direct and indirect
		211	objects. This often resulted in the parser error "I don't recognize
		212	that sentence," since OF is a rare preposition in verb phrases. For
		213	example, EXAMINE BOX OF PAPER would be treated as an EXAMINE OF
		214	command, which most games don't defined as a valid verb phrase. In
		215	such cases, the parser now checks to see if it <i>could</i> have
		216	formed a syntactically valid noun phrase from the whole "x OF y"
		217	phrase, and if so, shows the more sensible error "I don't see any x of
		218	y here."
		219	(<a href="http://bugdb.tads.org/view.php?id=0000010">bugdb.tads.org #0000010</a>)
		220
		221	<li>If the game executed parserReplaceCommand() from within certain of
		222	the "parser hook" functions, the interpreter displayed the run-time
		223	error "TADS-1024: 'abort' statement executed". This happened because
		224	of the way parserReplaceCommand() works internally, but it obviously
		225	shouldn't result in an error message. This is now fixed.
		226	(<a href="http://bugdb.tads.org/view.php?id=0000011">bugdb.tads.org #0000011</a>)
		227
		228	<li>The compiler's -p option (to make the compiler pause before
		229	terminating, to give you a chance to read the output) didn't work
		230	in some cases where an error occurred during compilation. This
		231	has been fixed.
		232	(<a href="http://bugdb.tads.org/view.php?id=0000015">bugdb.tads.org #0000015</a>)
		233
		234	</ul>
		235
		236	<!------------------------------------------------------------------------>
		237	<br><br><hr>
		238	<h3><a name='tads2510'>Version 2.5.10</a></h3>
		239
		240	<i>Released on August 17, 2006</i>
		241
		242	<ul>
		243
		244	<li>The INVENTORY TALL command now respects "quiet" containers and
		245	surfaces (that is, the contents of these objects will not be listed in
		246	the inventory). In the past, the default INVENTORY WIDE mode
		247	respected the "quiet" flags, but TALL mode didn't. INVENTORY TALL
		248	also now properly takes into account the "contentsVisible" settings of
		249	the objects listed. These changes ensure that WIDE and TALL modes
		250	yield the same information.
		251
		252	<li>In adv.t, the default message for TELL <i>thing</i> ABOUT
		253	<i>topic</i> now properly takes into account the number (singular or
		254	plural) of the thing, so the message will now change to "...are
		255	interested" when the thing has a plural name. In the past, the text
		256	always said "is interested," which was ungrammatical when the thing
		257	had a plural name.
		258
		259	<li>A bug in the interpreter caused unpredictable behavior, sometimes
		260	crashing the interpreter, when starting certain games, including
		261	recent release <i>Finding Martin</i>. The problem was triggered by
		262	a very large number of objects (more than about 150) in a single
		263	location, so it didn't affect most games, and it appeared somewhat
		264	sporadically even for games that did trigger it. The bug has now
		265	been fixed.
		266
		267	<li>An interpreter bug caused delword() to occasionally and
		268	unpredictably delete extra words beyond what it was actually
		269	asked to delete. This has been corrected.
		270
		271	<li>In the past, if the player's answer to a disambiguation question
		272	had certain kinds of syntax errors, the parser responded with a
		273	suitable error message, but incorrectly showed that message twice in a
		274	row. This was due to an interpreter bug, which has now been corrected.
		275
		276	<li>In adv.t, the messages for "the key doesn't fit" in
		277	doorway.doLockWith and doorway.doUnlockWith were phrased incorrectly
		278	in some cases (in particular, the subject and verb didn't always
		279	agree). This has been corrected.
		280
		281	</ul>
		282
		283
		284	<!------------------------------------------------------------------------>
		285	<br><br><hr>
		286	<h3><a name='tads259'>Version 2.5.9</a></h3>
		287
		288	<i>Released on September 12, 2004</i>
		289
		290	<ul>
		291
		292	<li>The "file safety" levels have changed slightly to provide better
		293	security against malicious game programs. First, level 2, which
		294	formerly provided global read access but no write access, now instead
		295	provides read/write access to the current working directory only (the
		296	game isn't allowed any access to files outside of the working
		297	directory). Second, the default safety level is now level 2. In the
		298	past, level 1 (read from any file/write to current directory only) was
		299	the default, which left open the possibility that a game could access
		300	data outside of the working directory. A malicious game could
		301	conceivably have exploited this by, for example, secretly copying
		302	sensitive data to the game directory for later use by a coordinating
		303	network worm, or by encoding the data in a hyperlink (displayed in an
		304	HTML-enabled game) that takes the player to a spyware site when
		305	clicked. The new default setting should effectively eliminate these
		306	risks by barring access to any files outside of the working directory.
		307
		308	<li>A bug in the compiler sometimes caused crashes when the "preinit"
		309	function called certain built-in functions, particularly for file
		310	manipulation. The problem was somewhat random, and tended to show up
		311	on some machines and not others, because it depended on memory
		312	conditions left over from other programs. The problem showed up for
		313	several people when they included the "gameinfo.t" module in their
		314	games, because that module writes a text file during preinit. The bug
		315	has now been fixed.
		316
		317	<li>An interpreter bug was capable of corrupting list values during
		318	game execution under very rare conditions. The bug only showed up
		319	when assigning a value to an indexed element of a list (either
		320	directly or via the "+=" or "-=" operators) at just the right moment
		321	to trigger garbage collection, and only then when the list happened to
		322	be situated in memory in just the right way. The bug was more likely
		323	to occur with small "heap" memory settings (the "-mh" option); with
		324	the large default heap of most current interpreters, the bug almost
		325	never showed up. The bug was also quite unlikely to occur except in
		326	games that perform unusually heavy list processing. The bug
		327	manifested itself in unpredictable ways, ranging from spurious
		328	run-time errors to interpreter crashes. This has now been fixed.
		329	Note that most games that were likely to trigger the bug in the past
		330	will now instead cause a "heap overflow" error; this error is valid,
		331	and indicates that the game exhausted the available memory for
		332	processing list and string values. If a heap overflow does occur
		333	while running a game, try increasing the heap size using the "-mh"
		334	command-line option when you run the game.
		335
		336	<li>An inconsistency in the command parser has been fixed. In the
		337	past, the parser didn't properly take into account whether responses
		338	to missing object prompts were singular or plural. This caused some
		339	subtle differences between typing a full command and piecing a command
		340	together with missing object prompts. In particular, the parser
		341	didn't announce the object names for a plural response, and didn't
		342	check rejectMultiDobj. This has been fixed, so the parser's behavior
		343	is now consistent for missing object responses.
		344
		345	<li>In the past, the parser incorrectly treated THEM as plural even
		346	when it referred to only one object, so it checked with
		347	rejectMultiDobj in these cases. This is undesirable in some cases,
		348	especially when the single object being referred to is an object whose
		349	name has plural usage. The parser now treats THEM as singular when it
		350	refers to just one object.
		351
		352	</ul>
		353
		354	<!------------------------------------------------------------------------>
		355	<br><br><hr>
		356	<h3><a name='tads258'>Version 2.5.8</a></h3>
		357
		358	<i>Released on June 12, 2004</i>
		359
		360	<ul>
		361
		362	<li>In adv.t, THROW AT now uses a new method, throwHitDest, to
		363	determine where the thrown object lands. This method is called for
		364	the actor's current location; by default, it simply returns 'self', so
		365	a thrown object simply lands in the actor's current location. This is
		366	the same behavior as in the past. However, the special 'theFloor'
		367	object overrides this to return the current room. This corrects a
		368	problem that occurred when the player sat on the floor and then threw
		369	something: because the object formerly ended up in the actor's
		370	location, the object landed in the 'theFloor' object, at which point
		371	the object became inaccessible. This change ensures that a thrown
		372	object will never be moved into 'theFloor', but will always land in
		373	the actor's actual room location. As a side benefit, the new method
		374	also makes it possible to customize the location where objects land
		375	when thrown from within a nested room.
		376
		377	<li>When running in HTML mode, the default parser error message 1 ("I
		378	don't understand the punctuation %c") now includes an "\H-" sequence
		379	before the message to ensure that the unrecognized character is
		380	displayed literally if it's an HTML markup-significant character
		381	(such as '<' or '&'). It also shows an "\H+" sequence after
		382	the message to restore HTML mode. In the past, if the player entered
		383	a markup-significant character while the interpreter was in HTML
		384	mode, the HTML parser could become momentarily confused, leading to
		385	strange output.
		386
		387	<li>The new parser hook parseDefaultExt() extends the parseDefault()
		388	function. The new function takes two additional parameters, giving
		389	the actor and deepverb object involved in the command; the new
		390	parameter list is parseDefaultExt(actor, verb, obj, prp). If the game
		391	defines parseDefaultExt(), then the interpreter ignores parseDefault()
		392	and calls parseDefaultExt() instead. If the game does not define
		393	parseDefaultExt(), but does define parseDefault(), the interpreter
		394	uses parseDefault() as it used to, which ensures that existing games
		395	will continue to run unchanged. You can use the new extended version
		396	of the function if you need the actor and/or verb information in
		397	displaying the default object message; this is useful in some
		398	non-English languages where a default object name's noun phrase must
		399	be inflected according to its usage in the command.
		400
		401	<li>The new parser hook preparseExt() allows the game to inspect and
		402	optionally change text the player types in response to parser
		403	questions: disambiguation queries, requests for missing direct or
		404	indirect objects, and OOPS typo-correction opportunities. The new
		405	function's parameter list is preparseExt(actor, verb, str, typ), where
		406	'actor' is the actor performing the command, 'verb' is the deepverb
		407	object, 'str' is a string containing the exact text the player typed
		408	in, and 'typ' is an integer giving the type of query the player is
		409	responding to. The meaning of 'typ' is the same as the that of the
		410	type codes passed to commandPrompt() and commandAfterRead(). The
		411	function can return a new string, which the parser will use to replace
		412	the text the user typed; true, to proceed with the original text the
		413	user typed; or nil, to treat the user's text as a brand new command,
		414	bypassing the special interpretation as a response to the parser's
		415	question. The game doesn't have to define the preparseExt() function;
		416	it's purely optional, so existing games will not be affected.
		417
		418	<li>When the interpreter looks for external resource bundles (*.rsN files),
		419	it now looks for the files using lower-case <i>and</i> upper-case suffixes
		420	(in other words, it looks for both .rs0 and .RS0, and likewise for digits
		421	1-9). Lower-case suffixes are tried first, then upper-case. This change
		422	makes the naming system more flexible on systems with case-sensitive
		423	file systems, such as Unix; for systems such as Windows and Macintosh that
		424	have case-insensitive file systems, this change will have no effect.
		425
		426	<li>A bug in the parser made it impossible to use numeric adjectives
		427	in certain phrasings. In particular, if a given word was defined in
		428	a game as both a noun and an adjective, but the word was defined only as
		429	a noun for a given object that takes a numeric adjective, then the
		430	phrasing <i>noun</i> <i>number</i> didn't match the object. For example,
		431	if the word "switch" was defined as a noun for a given numbered switch,
		432	but "switch" was defined as an adjective for some other object, then
		433	"switch 5" didn't match the switch even if "5 switch" did. This has
		434	been corrected.
		435
		436	<li>The compiler now checks for missing symbols before running the
		437	'preinit' function, and skips running preinit if any symbols are
		438	undefined. In the past, the compiler called preinit even if some
		439	symbols were undefined; if preinit itself called any undefined
		440	functions or invoked methods of undefined objects, this sometimes
		441	led to misleading error messages. The compiler will now simply
		442	point out the missing symbols, and skip running preinit entirely.
		443
		444	<li>The compiler now allows filenames up to 255 characters to appear
		445	in the source file names in debugging records. In the past, the limit
		446	was 127 characters. <b>Important note:</b> due to a bug, older
		447	interpreters cannot properly handle .gam files compiled with debugging
		448	information with path names over 127 characters. Attempting to load
		449	.gam files with debugging information containing long source file
		450	names will cause unpredictable results. Since some users might still
		451	have older interpreter versions, <b>we strongly advise against
		452	releasing games compiled with debugging information</b>. That is, you
		453	should never release a game that you compiled with the "-ds" or "-ds2"
		454	options.
		455
		456	<li>In the past, if the game code called a function or method, using
		457	the return value of another function or method as an argument, and the
		458	other function or method didn't actually return any value for the
		459	argument, the results were unpredictable; in some cases, this even
		460	caused the interpreter to crash. The interpreter is now more careful
		461	about checking for these cases; when they occur, the interpreter now
		462	automatically adds 'nil' values for the missing arguments. This
		463	should ensure that errant code won't crash the interpreter, without
		464	breaking any existing code with "asymptomatic" instances of this
		465	error.
		466
		467	<li>The default "file safety level" for the command-line interpreters
		468	is now set to 1, which allows reading files from anywhere on the disk,
		469	but allows writing files only to the current working directory. This
		470	protects against malicious game authors attempting, for example, to
		471	modify your operating system's files. You can manually override this
		472	to use a more permissive or more protective level using the "-s" option.
		473
		474	<li>External functions are now obsolete and can no longer be used on
		475	any platform. One of the nice things about running games with a
		476	system like TADS is that you don't have to worry as much about
		477	viruses and other malicious code when playing downloaded games, since
		478	games run in the interpreter environment rather than as native code.
		479	The external function feature made it possible for games to call out
		480	to native code, though, so a malicious author could have used
		481	external functions to do damage to a user's system. Removing this
		482	feature eliminates this security loophole. External functions were
		483	only supported on a few platforms to start with, and they never
		484	caught on with authors, probably because they were difficult to use
		485	and had serious drawbacks (such as complete unportability). Since no
		486	one has ever had much use for this feature, and because of the
		487	potential security vulnerability, we've decided that there's no
		488	reason to keep it around.
		489
		490	<li>In the past, the compiler did not accept 'self' as an element in a
		491	list, even in contexts where 'self' was otherwise valid. The compiler
		492	now does accept 'self' as a list element in method contexts.
		493
		494	<li>A bug in the interpreter sometimes made the result of the
		495	subtract-and-assign operator ("-=") incorrect under certain
		496	circumstances: specifically, the problem occurred when the left-hand
		497	side was a local variable, the local variable contained a list value,
		498	and the list value did <i>not</i> contain the value on the right-hand
		499	side of the operator. In some such cases, a run-time error occurred;
		500	in some others, the wrong value was assigned to the local variable.
		501	This has been corrected; when the value on the right side is not in
		502	the list, the list value in the local is simply left unchanged.
		503
		504	<li>Due to a bug, the compiler sometimes crashed if you used a "break"
		505	and "continue" statement in an invalid context (i.e., outside of a
		506	"while", "for", "do", or, in the case of "break", a "switch"
		507	statement). This has been corrected; the compiler now simply flags
		508	these as errors, but shouldn't crash.
		509
		510	</ul>
		511
		512
		513	<!------------------------------------------------------------------------>
		514	<br><br><hr>
		515	<h3><a name='tads257'>Version 2.5.7</a></h3>
		516
		517	<i>Released on September 22, 2002</i>
		518
		519	<ul>
		520
		521	<li>The new system information code __SYSINFO_INTERP_CLASS returns
		522	information on the "class" of interpreter currently running. This
		523	returns one of the following codes:
		524
		525	<ul>
		526	<li>__SYSINFO_IC_TEXT: a text-only, character-mode interpreter,
		527	such as an MS-DOS or Unix interpreter. These interpreters use
		528	a single, fixed-pitch font, and support the text-only HTML subset.
		529
		530	<li>__SYSINFO_IC_TEXTGUI: a text-only interpreter on a graphical
		531	platform, such as MacTADS or WinTADS. These interpreters behave
		532	essentially identically to character-mode text-only interpreters,
		533	so from the game program's perspective there is no practical
		534	difference between this and character-mode interpreters.
		535
		536	<li>__SYSINFO_IC_HTML: a full HTML-enabled interpreter on a
		537	graphical platform, such as HTML TADS on Windows or HyperTADS on
		538	Macintosh. These interpreters can display text and graphics,
		539	use multiple fonts, and interpret the full HTML TADS markup language.
		540	</ul>
		541
		542	<li>The travel system in adv.t has been enhanced slightly to allow
		543	rooms to differentiate their travel behavior for travel by the player
		544	character vs. travel by non-player characters. The new properties
		545	actorNorth, actorSouth, actorEast, actorWest, actorNE, actorNW,
		546	actorSE, actorSW, actorUp, actorDown, actorIn, and actorOut are now
		547	called when an NPC attempts travel; these properties correspond to the
		548	traditional properties north, south, east, west, and so on, and the
		549	only difference is that the new properties are called when NPC's
		550	travel. The traditional properties are still called for all player
		551	character travel. By default, each of the new actorXxx properties
		552	simply returns the value of the corresponding traditional property: so
		553	actorNorth by default simply returns the value of (self.north). This
		554	means that if you don't want to differentiate NPC travel from PC
		555	travel, you need do nothing at all; but if you want a particular
		556	travel direction from a particular room to work differently for
		557	an NPC than it does for the player character, you simply need to
		558	override actorNorth (or whichever direction you want to customize)
		559	in that location. Thanks to Tommy Nordgren for suggesting this
		560	enhancement.
		561
		562	</ul>
		563
		564	<!------------------------------------------------------------------------>
		565	<br><br><hr>
		566	<h3><a name='tads256'>Version 2.5.6</a></h3>
		567
		568	<i>Released on June 1, 2002</i>
		569
		570	<ul>
		571
		572	<li>The new system information code __SYSINFO_TEXT_COLORS tests for
		573	text color support. Currently, only the HTML interpreters support
		574	text colors; the text-only interpreters have no text color support.
		575	The return value indicates the level of support available:
		576
		577	<ul>
		578	<li>0/nil - no text color support
		579	<li>1 - parameterized color names only (TEXT, STATUSTEXT, etc.)
		580	<li>2 - the eight ANSI colors (white, black, red, blue, green,
		581	yellow, magenta, cyan) are supported for the text
		582	foreground color, but the background color cannot be set
		583	<li>3 - the eight ANSI colors are supported for text foreground
		584	and background colors
		585	<li>4 - full RGB colors are supported, foreground and background
		586	(the HTML interpreters generally return this code)
		587	</ul>
		588
		589	<li>The new system information code __SYSINFO_TEXT_HILITE tests for
		590	text highlighting support. This returns 1 if the interpreter is
		591	capable of rendering highlighted text (i.e., text within "\( \)"
		592	sequences, or text in HTML <B> sequences) with a distinctive
		593	appearance, 0 or nil if not. Most interpreters are capable of
		594	showing highlighting, except when running in "plain" mode or when
		595	using a terminal or display device that has no ability to show
		596	different text colors or styles.
		597
		598	<li>The new system information code __SYSINFO_OGG tests for Ogg Vorbis
		599	audio format support. systemInfo(__SYSINFO_OGG) returns 1 if the Ogg
		600	Vorbis format is supported by the interpreter, 0 if not.
		601
		602	<li>The new system information codes __SYSINFO_MNG, __SYSINFO_MNG_TRANS,
		603	and __SYSINFO_MNG_ALPHA test for basic MNG (animated image) suport,
		604	MNG transparency support, and MNG alpha-channel support, respectively.
		605	These are analogous in meaning to the PNG information codes.
		606
		607	<li>The interpreter now includes the name of the external resource
		608	(.rsn) file in error messages that result from errors reading these
		609	files. In the past, the interpreter did not indicate which specific
		610	file was causing the problem, which made it difficult to track down
		611	where the problem was. (The non-specific error message worked fine
		612	in the days before external resource files, when everything was
		613	always in the single .gam file, but the new, more specific diagnostic
		614	information is important now that a game's resources can be put in
		615	several separate files.)
		616
		617	<li>In adv.t, <tt>basicMe.moveInto(room)</tt> now calls a new method,
		618	<tt>room.meIsMovingInto(self)</tt>, whenever the <tt>basicMe</tt> object being
		619	moved is the current player character (i.e., <tt>self</tt> is the object that
		620	<tt>parserGetMe()</tt> returns). A default implementation of
		621	<tt>meIsMovingInto(meActor)</tt> has been added to <tt>room</tt>;
		622	this default implementation does nothing. Finally, an overriding
		623	implementation of <tt>meIsMovingInto(meActor)</tt> has been added
		624	to <tt>theFloor</tt>; this implementation sets <tt>theFloor.sitloc</tt>
		625	to the player character actor's previous location. The purpose of all
		626	of this new mechanism is to ensure that <tt>theFloor.sitloc</tt> is
		627	properly set to the player character's prior location whenever the
		628	player character is explicitly moved into <tt>theFloor</tt>. In the
		629	past, <tt>theFloor.sitloc</tt> was set whenever the player character
		630	moved to <tt>theFloor</tt> via a "sit on the floor" command from the
		631	player, but wasn't set when the object was moved to <tt>theFloor</tt>
		632	through other means. The <tt>theFloor</tt> object uses the <tt>sitloc</tt>
		633	property to remember the location that originally contained the actor
		634	before sitting on the floor; this is needed because <tt>theFloor</tt>
		635	is a floating item and thus doesn't have an actual location of its own.
		636
		637	<li>In adv.t, the various <tt>hider</tt> subclasses (<tt>underHider</tt>,
		638	<tt>searchHider</tt>, <tt>behindHider</tt>) now check to see if they
		639	were never hiding anything to start with, and issue an appropriate
		640	message if so. In the past, if an object was defined using one of
		641	the <tt>hider</tt> subclasses, but no other object was ever hidden
		642	inside the <tt>hider</tt>, looking in/under/behind the object generated
		643	an erroneous message, of the form "You find , which you take." Now,
		644	when the list of hidden objects is initially empty, the generated
		645	message is simply "You find nothing under (the object)."
		646
		647	<li>The <tt>parserDictLookup()</tt> function can now be called
		648	from within <tt>init()</tt>. In the past, this function caused
		649	a run-time error if called while <tt>init()</tt> was running; this
		650	has been corrected.
		651
		652	<li>Fixed a problem in parserGetObj(PO_ACTOR) that caused the incorrect
		653	actor to be reported between the time <tt>preinit</tt> was called and
		654	the time <tt>preCommand</tt> was called. During this window, if a
		655	command was the first command on a new command line, and the command
		656	line didn't start with a target actor ("bob, ..."), then
		657	parserGetObj(PO_ACTOR) incorrectly returned the actor from the
		658	previous command. This no longer occurs; the function now correctly
		659	returns the current "me" object in such cases.
		660
		661	<li>Fixed a problem in the output formatter that caused problems
		662	with displaying a series of quoted spaces ('\ ' sequences) in some
		663	situations, especially on platforms with proportionally-spaced
		664	display fonts such as the Mac. This has been corrected.
		665
		666	<li>The compiler no longer treats any characters in the "extended"
		667	character set (i.e., characters with character codes outside the
		668	ASCII range 0 to 127) as whitespace. In the past, the compiler on
		669	some platforms treated certain extended characters as spaces, which
		670	sometimes caused problems for authors working in non-English
		671	languages. The compiler has no knowledge of the attributes of any
		672	localized character sets (the compiler's character set translation
		673	mechanism does not provide attribute information, only set-to-set
		674	mapping information), so it was incorrect of the compiler to assume
		675	anything about which extended characters represented whitespace
		676	characters. This problem manifested itself most apparently when
		677	a string containing extended characters spanned several lines of
		678	source; if the compiler mistook any of the leading characters on
		679	continuation lines for whitespace, it would remove them, resulting
		680	in incorrect text displayed at run-time. This has been corrected;
		681	the compiler now treats all extended characters as non-whitespace
		682	characters.
		683
		684	<li>Fixed a problem in the <tt>execCommand()</tt> built-in function
		685	that caused various problems ranging from data value corruptions to
		686	interpreter crashes. The problem appeared when <tt>execCommand</tt>
		687	was used to execute a command that terminated with an <tt>exit</tt> or
		688	<tt>abort</tt>, and then only when certain combinations of operations
		689	on local variables followed. The problem has been corrected.
		690
		691	<li>Fixed a compiler bug that caused an infinite loop when parsing
		692	certain nested <tt>switch</tt> statements. A <tt>switch</tt> containing
		693	string constant <tt>case</tt> labels nested within another <tt>switch</tt>
		694	with string constant <tt>case</tt> labels sporadically caused this
		695	problem. This has been corrected.
		696
		697	<li>Fixed a problem in the compiler that caused the <tt>contents</tt>
		698	lists of objects to be initialized improperly in certain cases. In
		699	particular, if an object's <tt>contents</tt> list was used during
		700	execution of the <tt>preinit</tt> function, any object that inherited
		701	a <tt>location</tt> value equal to the given object was omitted from
		702	the given object's <tt>contents</tt> list, when clearly the object
		703	should have been included in the list. This only affected
		704	<tt>preinit</tt>, and then only when a <tt>contents</tt> that should
		705	have contained an object with an inherited location was referenced
		706	from within the <tt>preinit</tt> function. This has been corrected;
		707	inherited <tt>location</tt> values are now properly handled when
		708	<tt>preinit</tt> is executing.
		709
		710	<li>The compiler and interpreter must sometimes create temporary
		711	files for internal memory management purposes. On certain systems
		712	(in particular, DOS, Windows, and Unix), TADS determines a suitable
		713	directory location to store any needed temporary files by looking in
		714	the environment for variables called TEMPDIR, TMPDIR, TEMP, and TMP
		715	(in that order), and using the value of the first such variable it
		716	finds as the temporary directory path. In past versions, if the path
		717	found in this manner was invalid, the interpreter or compiler would
		718	usually terminate with an error message that wasn't very helpful in
		719	tracking down the problem. In most cases, the error message was
		720	"unable to open swap file." This has been changed; now, if the
		721	temporary path obtained from the environment variables is invalid,
		722	TADS ignores the path and simply creates any necessary temporary
		723	files in the current working directory.
		724
		725	<li>A number of messages in adv.t now use format strings ("%you%" and
		726	the like) where they didn't before but should have, to facilitate
		727	games written in styles other than second-person. Thanks go to
		728	Bennett Standeven for catching these.
		729
		730	<li>Fixed a problem that caused interpreter crashes under rare
		731	circumstances for interpreters that could play more than one game in
		732	a single session (such as the HTML TADS interpreter). If the
		733	interpreter loaded a game that used the "output filter function"
		734	feature, and then that game was terminated and another game was
		735	loaded into the same interpreter session, and the new game didn't use
		736	its own output filter function, results were unpredictable, and
		737	interpreter crashes sometimes occurred. This has been corrected.
		738	(This problem did not affect most platforms, because most
		739	interpreters terminate when the game being executed terminates.)
		740
		741	<li>Fixed an interpreter problem that caused the "<tt>new</tt>"
		742	operator to generate a run-time error in some unusual situations.
		743	In particular, if the constructor modified a property of the
		744	object containing the method that invoked the <tt>new</tt>
		745	operator (directly in its own code, or in any code it invoked),
		746	then the error "TADS-5: attempting to reallocate a locked object"
		747	appeared sporadically. This has been corrected.
		748
		749	</ul>
		750
		751	<!------------------------------------------------------------------------>
		752	<br><br><hr>
		753	<h3><a name='tads255'>Version 2.5.5</a></h3>
		754
		755	<i>Released on September 27, 2000</i>
		756
		757	<ul>
		758
		759	<li>In adv.t, a comment in listcontgen() has been fixed to reflect
		760	that it's actually part of the "tall" listing rather than the "wide"
		761	listing.
		762
		763	<li>In adv.t, in moveableActor.travelTo, if the actor's previous
		764	location was nil, a run-time error occurred. This has been corrected.
		765
		766	<li>In adv.t, in thing.thatdesc, the plural form has been changed to
		767	display "those" rather than "them"; this provides a better parallel to
		768	the singular display ("that").
		769
		770	</ul>
		771
		772	<!------------------------------------------------------------------------>
		773	<br><br><hr>
		774	<h3><a name='tads254'>Version 2.5.4</a></h3>
		775
		776	<i>Released on June 17, 2000</i>
		777
		778	<h4>New systemInfo() flags for PNG transparency</h4>
		779
		780	<p>Two new systemInfo() flags have been added to test for support of
		781	certain features of the PNG image format:
		782
		783	<ul>
		784
		785	<li>__SYSINFO_PNG_TRANS: tests for PNG transparency support. Some
		786	newer versions of the HTML interpreter support PNG transparency,
		787	which allows parts of a PNG image to be designated as transparent so
		788	that the background shows through. systemInfo(__SYSINFO_PNG_TRANS)
		789	returns true if transparency is supported when displaying PNG images,
		790	nil if not. This will never return true under interpreters that don't
		791	support PNG images at all. Note that this flag indicates only <i>simple</i>
		792	transparency support, which allows pixels to be designated as fully
		793	opaque or fully transparent, and does not imply support of full alpha
		794	blending; some interpreters (such as the Windows
		795	HTML interpreter 2.5.4) support only simple transparency but not
		796	alpha blending.
		797
		798	<li>__SYSINFO_PNG_ALPHA: tests for PNG "alpha blending" support, which
		799	allows individual pixels of a PNG image to be designated as partially
		800	transparent. Currently, none of the interpreters support alpha blending
		801	in PNG images; this flag has been added for possible future use.
		802
		803	</ul>
		804
		805	<h4>Bug Fixes</h4>
		806
		807	<ul>
		808
		809	<li>A bug in the compiler caused a crash under certain unusual conditions
		810	when the program defined a symbol as an object, and the symbol
		811	was already defined as a property or function. Most of the time, the
		812	compiler reported an error ("redefining symbol as object"), but in some
		813	cases the compiler crashed. This has been corrected.
		814
		815	</ul>
		816
		817
		818	<br><br><hr>
		819	<h3><a name='tads253'>Version 2.5.3</a></h3>
		820
		821	<i>Released on April 16, 2000</i>
		822
		823	<p>This version contains no changes to text-only versions of TADS; the
		824	only changes are in HTML versions.
		825
		826	<br><br><hr>
		827	<h3><a name='tads252'>Version 2.5.2</a></h3>
		828
		829	<i>Released on March 27, 2000</i>
		830
		831	<h4>Index of Changes</h4>
		832
		833	<ul>
		834	<li><a href='#isThem'>Parser recognizes isThem</a>
		835	<li><a href='#scoreFormat'>New scoreFormat() Function</a>
		836	<li><a href='#sysinfo252'>New systemInfo() Capability Codes</a>
		837	<li><a href='#bugs252'>Bugs Fixed</a>
		838	</ul>
		839
		840	<a name='isThem'></a>
		841	<h4>Parser recognizes isThem</h4>
		842
		843	<p>
		844	The parser now recognizes the <tt>isThem</tt> property for the purposes
		845	of deciding on the pronoun to display when prompting for an indirect
		846	object. In the past, the parser only recognized the <tt>isHim</tt>
		847	and <tt>isHer</tt> properties, and used the pronoun "it" if neither of
		848	these properties were consistently defined for the objects matching the
		849	direct object. The parser now uses the pronoun "them" if the matching
		850	objects all have <tt>isThem</tt> set to <tt>true</tt>.
		851
		852	<p>
		853	For example:
		854
		855	<p><pre>
		856	>throw pants
		857	What do you want to throw them at?
		858	</pre>
		859
		860	<a name='scoreFormat'></a>
		861	<h4>New <tt>scoreFormat()</tt> Function</h4>
		862
		863	<p>
		864	The way that adv.t displays the status line has been changed slightly
		865	to simplify coding of special formats. A new function,
		866	<tt>scoreFormat()</tt>, is now responsible for formatting the string
		867	to display in the right half of the status line. <tt>scoreFormat()</tt>
		868	takes the current score and the current turn counter as arguments, and
		869	returns a string to display in the right half of the status line. The
		870	default implementation in adv.t simply returns a string consisting of
		871	the score, a slash ("/"), and the turn count, which provides the same
		872	format that adv.t has traditionally used for the status line.
		873
		874	<p>
		875	The existing function
		876	<tt>scoreStatus()</tt> now calls <tt>scoreFormat()</tt> to generate the
		877	display. In addition, the code in <tt>room.statusLine</tt> that generates
		878	the HTML version of the status line now calls <tt>scoreFormat()</tt> as
		879	well. This makes <tt>scoreFormat()</tt> the single point in adv.t where
		880	the right half of the status line is formatted.
		881
		882	<p>
		883	The advantage of this new mechanism is that you can customize the display
		884	of the right half of the status line for both text-only and HTML-enabled
		885	games simply by replacing the <tt>scoreFormat()</tt> function.
		886
		887	<p>
		888	Of course, HTML-enabled games are not limited to using the traditional
		889	status line display; if you want a completely custom status line display
		890	when running under an HTML-enabled interpreter, you can replace adv.t's
		891	<tt>room.statusLine</tt> and generate your own <BANNER> display.
		892	The new <tt>scoreFormat()</tt> mechanism, however, is convenient when
		893	you simply want to customize the right half of the status line, but still
		894	use the traditional single-line status format.
		895
		896
		897	<a name='sysinfo252'></a>
		898	<h4>New <tt>systemInfo()</tt> Capability Codes</h4>
		899
		900	<p>
		901	The <tt>systemInfo()</tt> function accepts several new capability
		902	codes that let you discover whether the system is capable of following
		903	URL-style <A HREF> hypertext links in HTML-formatted text.
		904	The new codes are:
		905
		906	<p>
		907	<ul>
		908	<li><tt>__SYSINFO_LINKS_HTTP</tt> - checks if the system can follow
		909	HTTP links to display web pages. HTTP URL's start with "<tt>http:</tt>".
		910
		911	<li><tt>__SYSINFO_LINKS_FTP</tt> - determines if the system can follow
		912	FTP links, which start with "<tt>ftp:</tt>".
		913
		914	<li><tt>__SYSINFO_LINKS_NEWS</tt> - determines if the system can follow
		915	news links to Usenet newsgroups, which start with "<tt>news:</tt>".
		916
		917	<li><tt>__SYSINFO_LINKS_MAILTO</tt> - determines if the system can follow
		918	mail links to send email; these links start with "<tt>mailto:</tt>".
		919
		920	<li><tt>__SYSINFO_LINKS_TELNET</tt> - checks if the system can follow
		921	telnet links, which start with "<tt>telnet:</tt>".
		922	</ul>
		923
		924	<p>For example, suppose you want to display a link to a web page you've
		925	created for your game, so that players can check for updates and hints
		926	on your web site. You can use <tt>__SYSINFO_LINKS_HTTP</tt> to check the
		927	user's TADS interpreter for HTTP link capability; if the interpreter can
		928	follow HTTP links, you can show your link with a friendly display, and
		929	fall back on spelling out the URL when the interpreter can't directly
		930	follow the link.
		931
		932	<pre>
		933	"You can check for updates to this game at ";
		934	if (systemInfo(__SYSINFO_LINKS_HTTP))
		935	"<A HREF='http://www.mysite.com/mygame.htm'>my web site</A>";
		936	else
		937	"my web site (http://www.mysite.com/mygame.htm)"
		938	". This site also has hints and some background
		939	information about the game. ";
		940	</pre>
		941
		942
		943	<a name='bugs252'></a>
		944	<h4>Bugs Fixed</h4>
		945
		946	<ul>
		947
		948	<li>For a verb defined with the <tt>[disambigDobjFirst]</tt> flag, the
		949	parser called the indirect object's <tt>verIo<i>Verb</i></tt> method
		950	incorrectly in cases where the player omitted an indirect object,
		951	causing the parser to try to find a default indirect object. For
		952	example, suppose you were to make the following definitions:
		953
		954	<p><pre>
		955	waveVerb: deepverb
		956	verb='wave'
		957	sdesc="wave"
		958	prepDefault = atPrep
		959	ioAction(atPrep) = [disambigDobjFirst] 'WaveAt'
		960	;
		961	modify thing
		962	verDoWaveAt(actor) = {}
		963	verIoWaveAt(actor, dobj) = {}
		964	ioWaveAt(actor, dobj) = { "Nothing special happens. "; }
		965	;
		966	</pre>
		967	<p>
		968	In the past, if you typed a "wave" command with no indirect object, as
		969	in "wave flag," the parser incorrectly invoked the <tt>verIoWaveAt</tt>
		970	method with only one argument, causing a run-time error. This no
		971	longer occurs; the parser consistently calls the <tt>verIo<i>Verb</i></tt>
		972	method in these cases with the correct number of arguments.
		973
		974	<li>In past versions, the <tt>parserTokenize()</tt> built-in function
		975	did not work properly when the input text contained a quoted string;
		976	in particular, the text of the quoted string was not included in the
		977	list. This has been corrected; the tokenized list now correctly
		978	includes the quoted string, enclosed in double quote marks (following
		979	the same rules as <tt>preparseCmd()</tt>). The same problem affected
		980	the token list passed to <tt>parseUnknownVerb()</tt>; this has been
		981	corrected as well.
		982
		983	<li>If the <tt>preparse()</tt> or <tt>preparseCmd()</tt> functions
		984	executed an <tt>exit</tt>, <tt>exitobj</tt>, or <tt>abort</tt>, the
		985	interpreter displayed an error message (such as "'abort' statement
		986	executed"). This was mostly harmless; these types of statements
		987	are generally not needed within <tt>preparse()</tt> and
		988	<tt>preparseCmd()</tt>, because these functions use return codes rather
		989	than <tt>exit</tt> and the like to control further processing.
		990	However, certain built-in functions perform <tt>abort</tt> operations
		991	implicitly; in particular, the <tt>parserReplaceCommand()</tt> function
		992	uses <tt>abort</tt> to start processing the new command immediately.
		993	To enable the use of such built-ins in <tt>preparse()</tt> and
		994	<tt>preparseCmd()</tt>, the interpreter no longer displays an error
		995	message when <tt>exit</tt>, <tt>exitobj</tt>, or <tt>abort</tt> are
		996	used in these user functions.
		997
		998	<li>In the past, the <tt>parserResolveObjects()</tt> built-in
		999	function did not correctly handle unknown words; in particular, the
		1000	function did not display any message if the noun phrase contained an
		1001	unknown word, even when the "silent" parameter was nil. This has
		1002	been corrected. Now, when "silent" is nil, the function handles
		1003	unknown words by displaying the normal error message ("I don't know
		1004	the word..."), then prompting the player for a new command. If
		1005	the player responds with "oops" (or "o") followed by another word,
		1006	the function returns the new result code <tt>PRSERR_OOPS_UPDATE</tt>,
		1007	with the corrected version of the noun phrase string as the second
		1008	element. Refer to the <i>Parser Manual</i> for details.
		1009
		1010	<li>A problematic interaction between <tt>parseUnknownVerb()</tt>,
		1011	and <tt>parserReplaceCommand()</tt> has been corrected. In the past,
		1012	if <tt>parserReplaceCommand()</tt> was used within the
		1013	<tt>parseUnknownVerb()</tt> function, and the parser called
		1014	<tt>parseUnknownVerb()</tt> because of an unknown word in the command,
		1015	the parser incorrectly deferred processing the replacement command
		1016	until after checking to see if the player tried to use OOPS to correct
		1017	the unknown word. This is undesirable, because in this case the game
		1018	has already provided the replacement command, so there is no reason to
		1019	give the player a chance to use OOPS. This has been corrected.
		1020
		1021	<li>Due to a bug, the parser did not correctly set the
		1022	<tt>PRSFLG_ENDADJ</tt> flag for some objects when calling the
		1023	<tt>disambigDobj</tt> and <tt>disambigIobj</tt> methods. The parser
		1024	omitted the flag when a noun phrase ended in an adjective, and the
		1025	vocabulary word involved was <i>only</i> defined as an adjective (in
		1026	other words, the word was never defined as a noun or plural for any
		1027	object in the entire game). This has been corrected. (Thanks to
		1028	Amir Karger for helping to track down this problem.)
		1029
		1030	<li>A parser bug caused a strange response message in certain cases.
		1031	If the player answered a disambiguation question with a special word
		1032	(such as "it" or "her"), the parser displayed a
		1033	<tt>preparse</tt>-style special word code in the response, as in "I
		1034	don't see any R book here." This has been corrected; the parser now
		1035	displays an improved message ("I don't see any such book here").
		1036
		1037	<li>A bug in the compiler caused a crash under certain obscure
		1038	circumstances. If a symbol was defined as a property or an object,
		1039	and then later in the source code a function definition appeared using
		1040	the same symbol name, the compiler sometimes crashed. This has been
		1041	corrected.
		1042
		1043	<li>A compiler bug caused the incorrect method to be called at
		1044	run-time in a certain situation. If code in an object used
		1045	<tt>pass</tt> or <tt>inherited</tt> to inherit code in a base
		1046	class, and the base class was an object that had been
		1047	modified with the <tt>modify</tt> keyword, and the method
		1048	being inherited had been replaced with the <tt>replace</tt> keyword
		1049	within the modifying class, the system did not correctly call the
		1050	replaced version of the method. This has been corrected.
		1051
		1052	<li>In past versions, the compiler accepted a <tt>case</tt> label in
		1053	a <tt>switch</tt> statement with <tt>self</tt> as the value. Since
		1054	<tt>self</tt> is not a constant, this type of <tt>case</tt> label has
		1055	never been legal, and at run-time the code after the "<tt>case
		1056	self:</tt>" label was never executed; however, the compiler should
		1057	not have accepted the construct in the first place. The compiler now
		1058	displays an error when it encounters a "<tt>case self:</tt>" label in
		1059	a <tt>switch</tt> statement.
		1060
		1061	<li>In the <tt>basicMe</tt> class in adv.t, the <tt>ioGiveTo</tt>
		1062	method generated an incorrect message. This has been corrected.
		1063
		1064	<li>The inventory listing code in adv.t (in the <tt>iVerb</tt>
		1065	object) produced an incorrect display ("You are carrying.") when the
		1066	player character was carrying only items marked as unlistable
		1067	(<tt>isListed = nil</tt>). This has been corrected.
		1068
		1069	<li>The <tt>thing</tt> class in adv.t now has default verification
		1070	methods for the verbs "attach x to y," "detach x," and "detach x from y."
		1071	These default verification methods each simply display the message "There's
		1072	no obvious way to do that."
		1073
		1074	<li>In the past, the text-only interpreter did not correctly suppress
		1075	certain markup sequences (in particular, BR, TAB, and HR) that appeared
		1076	within <TITLE> and <ABOUTBOX> tags. All text, including
		1077	these markups, is now properly suppressed within TITLE and ABOUTBOX
		1078	sequences.
		1079
		1080
		1081	</ul>
		1082
		1083
		1084	<br><br><hr>
		1085	<h3><a name='tads251'>Version 2.5.1</a></h3>
		1086
		1087	<i>Released on September 21, 1999</i>
		1088
		1089	<h4>Index of Changes</h4>
		1090
		1091	<ul>
		1092	<li><a href='#parseAskobjIndirect'>New Parser Hook: parseAskobjIndirect()</a>
		1093	<li><a href='#prefixdesc'>New Parser Hook: prefixdesc</a>
		1094	<li><a href='#resourceExists'>New built-in function: resourceExists()</a>
		1095	<li><a href='#newDefined'>New defined() Codes</a>
		1096	<li><a href='#newParserGetObj'>New parserGetObj() Codes</a>
		1097	<li><a href='#rscUrl'>Filename-to-URL Conversions in tadsrsc</a>
		1098	<li><a href='#cantReachMulti'>cantReach with Multiple Objects</a>
		1099	<li><a href='#inputkey251'>Changes to inputkey()</a>
		1100	<li><a href='#adv251'>Changes to adv.t</a>
		1101	<li><a href='#bugs251'>Bugs Fixed</a>
		1102	</ul>
		1103
		1104	<h4><a name='parseAskobjIndirect'>
		1105	New Parser Hook: <tt>parseAskobjIndirect</tt></a></h4>
		1106
		1107	<p>
		1108	A new parser hook, named <tt>parseAskobjIndirect()</tt>, has been added
		1109	to provide more control over the message that the parser uses to ask
		1110	the player to supply an indirect object when none is provided in the
		1111	command but the verb requires one. This new function supplements the
		1112	existing <tt>parseAskobj()</tt> and <tt>parseAskobjActor()</tt>
		1113	functions.
		1114
		1115	<p>
		1116	Refer to the <i>TADS Parser Manual</i> (version 2.5.1) for details
		1117	on this new parser hook.
		1118
		1119
		1120	<h4><a name='prefixdesc'>
		1121	New Parser Hook: <tt>prefixdesc</tt></a></h4>
		1122
		1123	<p>
		1124	The parser now calls a new method, called <tt>prefixdesc</tt>, to
		1125	display the object name prefix that comes before the execution results for
		1126	each object in a command with multiple direct objects. This new
		1127	method effectively replaces the existing <tt>multisdesc</tt> mechanism.
		1128	Refer to the <i>TADS Parser Manual</i> (version 2.5.1) for details
		1129	on this new parser hook.
		1130
		1131	<h4><a name='resourceExists'>
		1132	New built-in function: <tt>resourceExists()</tt></a></h4>
		1133
		1134	<p>
		1135	A new built-in function, <tt>resourceExists()</tt>, allows you to determine
		1136	whether a named resource (such as a JPEG image or an MP3 audio file) can
		1137	be loaded. This function takes as its single argument a string giving the
		1138	name of a resource to find; the function returns true if the resource can
		1139	be loaded, nil if not. The function returns nil if the interpreter is
		1140	simply not capable of loading resources at all (the text-only interpreters
		1141	thus always return nil for this function), or if the resource can't be
		1142	found. The function returns true only if the interpreter is capable of
		1143	loading resources at all, and the resource is available.
		1144
		1145	<p>
		1146	If you're writing a multi-media game for the HTML interpreters, but you
		1147	also want your game to work on text-only systems, you can use this function
		1148	for finer control over the presentation on the text systems; you might,
		1149	for example, want to provide additional text to make up for missing
		1150	graphics or sounds. You can also use this function if you're planning
		1151	to distribute your game in different subset versions in order to provide
		1152	players with different options for download and install sizes; if you
		1153	make some of your graphics optional (by bundling some into a separate
		1154	".RSn" resource file, for example), you can use <tt>resourceExists()</tt>
		1155	to detect at run-time which resources the player has chosen to install,
		1156	and customize the presentation accordingly.
		1157
		1158	<p>
		1159	Here's an example that checks to see if a JPEG image is available
		1160	for display:
		1161
		1162	<p>
		1163	<pre>
		1164	if (!resourceExists('images/title.jpg'))
		1165	{
		1166	// the title graphic isn't available - display a text version
		1167	...
		1168	}
		1169	</pre>
		1170
		1171
		1172	<h4><a name='newDefined'>
		1173	New <tt>defined()</tt> Codes</a></h4>
		1174
		1175	<p>
		1176	The <tt>defined()</tt> function, which tests an object to determine
		1177	whether it defines or inherits a given property, provides a new "flags"
		1178	argument that lets you get more specific information about the property
		1179	definition. The new third argument is optional; if provided, it can be
		1180	one of the following values, defined in adv.t:
		1181
		1182	<p>
		1183	<table>
		1184	<tr><td>
		1185	<td>
		1186	<table cellpadding=2>
		1187
		1188	<tr><td valign=top><tt>DEFINED_ANY</tt>  <td valign=top>
		1189
		1190	This is the default, and has the same effect as omitting the flag
		1191	argument. The function returns true if the object defines or inherits
		1192	the property, nil if not.
		1193
		1194	<tr><td valign=top><tt>DEFINED_DIRECTLY</tt>  <td valign=top>
		1195
		1196	The function returns true only if the object <i>directly</i> defines
		1197	the property. If the object doesn't define the property at all,
		1198	or merely inherits the definition from a superclass, the function
		1199	returns nil.
		1200
		1201	<tr><td valign=top><tt>DEFINED_INHERITS</tt>  <td valign=top>
		1202
		1203	The function returns true only if the object inherits the property.
		1204	If the object doesn't define the property, or defines the property
		1205	directly rather than inheriting it from a superclass, the function
		1206	returns nil.
		1207
		1208	<tr><td valign=top><tt>DEFINED_GET_CLASS</tt>  <td valign=top>
		1209
		1210	The function returns the class where the property is defined. If the
		1211	object directly defines the property, the function returns the object
		1212	itself. If the object inherits the property from a superclass, the
		1213	function returns the superclass from which the property is inherited.
		1214	If the object doesn't define or inherit the property, the function
		1215	returns nil.
		1216
		1217	</table></table>
		1218
		1219	<p>
		1220	For example, to determine if the object <tt>redBook</tt> directly
		1221	defines <tt>verDoTake</tt>, you could use this code:
		1222
		1223	<p>
		1224	<pre>
		1225	if (defined(redBook, &verDoTake, DEFINED_DIRECTLY))
		1226	"verDoTake is overridden directly in redBook. ";
		1227	</pre>
		1228
		1229
		1230	<h4><a name='newParserGetObj'>
		1231	New <tt>parserGetObj()</tt> Codes</a></h4>
		1232
		1233	<p>
		1234	The <tt>parserGetObj()</tt> function now accepts several new code
		1235	values to get additional objects. These new code values are defined
		1236	in adv.t:
		1237
		1238	<p>
		1239	<p>
		1240	<table>
		1241	<tr><td>
		1242	<td>
		1243	<table cellpadding=2>
		1244
		1245	<tr><td valign=top><tt>PO_IT</tt>  <td valign=top>
		1246	Get the object that the word "it" refers to in player commands.
		1247	This is nil if there is not "it" object.
		1248
		1249	<tr><td valign=top><tt>PO_HIM</tt>  <td valign=top>
		1250	Get the object that the word "him" refers to in player commands.
		1251
		1252	<tr><td valign=top><tt>PO_HER</tt>  <td valign=top>
		1253	Get the object that the word "her" refers to in player commands.
		1254
		1255	<tr><td valign=top><tt>PO_THEM</tt>  <td valign=top>
		1256	Get the list of objects that the word "them" refers to in player
		1257	commands. This is an empty list if "them" doesn't refer to anything
		1258	at the moment.
		1259
		1260	</table></table>
		1261
		1262	These new codes are used in the same manner as the original ones.
		1263	For example, to get the object that the word "him" currently
		1264	refers to, you'd write this:
		1265
		1266	<p>
		1267	<pre>
		1268	local himObj;
		1269
		1270	himObj := parserGetObj(PO_HIM);
		1271	</pre>
		1272
		1273	<p>
		1274
		1275	<h4><a name='rscUrl'>
		1276	Filename-to-URL Conversions in <tt>tadsrsc</tt></a></h4>
		1277
		1278	<p>
		1279	The resource bundling tool, <tt>tadsrsc</tt>, in the past did not convert
		1280	filenames entered with explicit paths to URL notation. This problem
		1281	only affected individual filenames entered with explicit paths (i.e.,
		1282	files in subdirectories); the tool correctly converted paths to URL
		1283	notation when adding entire directories to a resource file, and also
		1284	worked when adding individual files that were in the current
		1285	directory and thus didn't need an explicit path.
		1286
		1287	<p>
		1288	Instead of storing resource names in URL notation, the resource tool
		1289	stored the actual filenames in local file system notation. This didn't
		1290	work with HTML TADS, because the HTML resource loader requires image
		1291	and sound resources to be named using URL notation.
		1292
		1293	<p>
		1294	This problem has been corrected; the resource tool now converts all
		1295	paths used in resource filenames to URL notation.
		1296
		1297
		1298	<h4><a name='cantReachMulti'>
		1299	<tt>cantReach</tt> with Multiple Objects</a></h4>
		1300
		1301	When the player refers to an object that is visible but is not
		1302	reachable (an item within a closed transparent container, for example),
		1303	the parser calls the object's <tt>cantReach</tt> to display a message
		1304	explaining why the object is not accessible. This has not been changed,
		1305	but the multiple-object prefix mechanism has been.
		1306
		1307	<p>In the past, when the
		1308	command had multiple unreachable objects, the parser called the object's
		1309	<tt>sdesc</tt> method, then displayed message 200 (":").
		1310	This has been changed. Now, the parser uses the same mechanism
		1311	that it does for any other multiple-object listing prefix: for each
		1312	object, before calling <tt>cantReach</tt>, the parser
		1313	calls the object's <tt>multisdesc</tt> method then displays message 120
		1314	(":").
		1315
		1316	<p>
		1317	This minor change is for consistency; in particular, the change allows
		1318	the game to override multiple-object prefix displays in a uniform
		1319	manner for all types of these displays.
		1320
		1321
		1322	<h4><a name='inputkey251'>Changes to <tt>inputkey()</tt></a></h4>
		1323
		1324	<p>
		1325	The <tt>inputkey()</tt> built-in function now returns certain keys
		1326	more consistently and portably. The codes that
		1327	<tt>inputkey()</tt> returns vary by platform according to what keys
		1328	are available on the keyboard. In addition, in the past, the function
		1329	mapped certain keystrokes to high-level functional codes in different
		1330	ways on different platforms; this corresponded to the differing ways
		1331	that platforms used certain keyboard keys.
		1332
		1333	<p>The return codes from <tt>inputkey()</tt> are now somewhat more
		1334	consistent. The Escape key now returns the string <tt>'[esc]'</tt>
		1335	on most platforms that provide such a key, and the "control" keys
		1336	now return <tt>'[ctrl-<i>X</i>]'</tt> for almost all of the control
		1337	keys on most platforms. In the past, the escape key didn't return
		1338	anything on most platforms, and control keys frequently were mapped
		1339	to other functions (for example, on Unix, the Ctrl-E key returned
		1340	<tt>'[end]'</tt>, since this key is used on Unix TADS interpreters
		1341	to move the cursor to the end of the line when entering a command).
		1342
		1343	<p>
		1344	A few new command keys have been added. The full set of command keys
		1345	is shown below. The exact assignment of these keys varies by platform,
		1346	as it has in past versions, and any given platform might support only
		1347	a subset of these keys.
		1348
		1349	<p>
		1350	<table>
		1351	<tr><td>
		1352	<td>
		1353	<table cellpadding=2>
		1354
		1355	<tr><td valign=top><tt>[up]</tt>
		1356	<td>Up arrow
		1357
		1358	<tr><td valign=top><tt>[down]</tt>
		1359	<td>Down arrow
		1360
		1361	<tr><td valign=top><tt>[right]</tt>
		1362	<td>Right arrow
		1363
		1364	<tr><td valign=top><tt>[left]</tt>
		1365	<td>Left arrow
		1366
		1367	<tr><td valign=top><tt>[end]</tt>
		1368	<td>End of line
		1369
		1370	<tr><td valign=top><tt>[home]</tt>
		1371	<td>Home
		1372
		1373	<tr><td valign=top><tt>[del-eol]</tt>
		1374	<td>Delete to end of line
		1375
		1376	<tr><td valign=top><tt>[del-line]</tt>
		1377	<td>Delete line
		1378
		1379	<tr><td valign=top><tt>[del]</tt>
		1380	<td>Del (delete character)
		1381
		1382	<tr><td valign=top><tt>[page up]</tt>
		1383	<td>Page up
		1384
		1385	<tr><td valign=top><tt>[page down]</tt>
		1386	<td>Page down
		1387
		1388	<tr><td valign=top><tt>[top]</tt>
		1389	<td>Top of file
		1390
		1391	<tr><td valign=top><tt>[bottom]</tt>
		1392	<td>Bottom of file
		1393
		1394	<tr><td valign=top><tt>[f<i>N</i>]</tt>
		1395	<td>Function key <i>N</i> (<i>N</i> is replaced by a number, 1 through 10)
		1396
		1397	<tr><td valign=top><tt>[tab]</tt>
		1398	<td>Tab
		1399
		1400	<tr><td valign=top><tt>[word-left]</tt>
		1401	<td>Word left
		1402
		1403	<tr><td valign=top><tt>[word-right]</tt>
		1404	<td>Word right
		1405
		1406	<tr><td valign=top><tt>[del-word]</tt>
		1407	<td>Delete word
		1408
		1409	<tr><td valign=top><tt>[bksp]</tt>
		1410	<td>Backspace
		1411
		1412	<tr><td valign=top><tt>[esc]</tt>
		1413	<td>Escape
		1414
		1415	<tr><td valign=top><tt>[ctrl-<i>X</i>]</tt>
		1416	<td>Control-<i>X</i> (<i>X</i> is replaced by a lower-case letter:
		1417	Control-C is <tt>[ctrl-c]</tt>)
		1418
		1419	<tr><td valign=top><tt>[alt-<i>X</i>]</tt>
		1420	<td>Alt-<i>X</i> or Meta-<i>X</i> (<i>X</i> is replaced by a lower-case
		1421	letter: Alt-F is <tt>[alt-f]</tt>)
		1422
		1423	</table>
		1424	</table>
		1425	<p>
		1426
		1427
		1428	<h4><a name='adv251'>Changes to adv.t</a></h4>
		1429
		1430	<ul>
		1431	<li>Added verifier methods to class <tt>thing</tt> to accomodate
		1432	the verbs <tt>screwVerb</tt> and <tt>unscrewVerb</tt>. All of
		1433	these verifier methods simply stop the command with a default
		1434	failure message (variations on "You see now way to do that").
		1435	The new methods are:
		1436
		1437	<ul>
		1438	<li><tt>verDoScrew</tt>
		1439	<li><tt>verDoScrewWith</tt>
		1440	<li><tt>verIoScrewWith</tt>
		1441	<li><tt>verDoUnscrew</tt>
		1442	<li><tt>verDoUnscrewWith</tt>
		1443	<li><tt>verIoUnscrewWith</tt>
		1444	</ul>
		1445
		1446	<li>The <tt>fopen()</tt> built-in function's <tt>'r+'</tt> mode did
		1447	not correctly create a new file when the file being opened did not
		1448	previously exist, as it is documented to do. This has been corrected;
		1449	if no file exists, the <tt>'r+'</tt> mode creates a new file, otherwise
		1450	it opens the existing file, keeping its contents intact.
		1451
		1452	<li>The <tt>moveInto</tt> method in the <tt>basicMe</tt> object
		1453	in adv.t now works properly when the object is not the current player
		1454	character. <tt>moveInto</tt> now uses the default handling inherited
		1455	from <tt>Actor</tt> when the object is not the current player character;
		1456	this is important for games that switch among different player character
		1457	objects.
		1458
		1459	<li>The <tt>ioGiveTo</tt> method in <tt>basicMe</tt> in adv.t now
		1460	uses format strings (such as "%You%"), so that it adapts properly
		1461	when the object is not the current player character.
		1462
		1463	</ul>
		1464
		1465
		1466	<h4><a name='bugs251'>Bugs Fixed</a></h4>
		1467
		1468	<ul>
		1469
		1470	<li>Format strings (such as "%You%") can now be used from within the
		1471	<tt>endCommand()</tt> function. In the past, the actor setting that
		1472	the output formatter uses to translate format strings was forgotten
		1473	before the parser called <tt>endCommand()</tt>, even though the
		1474	parser still had the necessary information internally. The output
		1475	formatter now keeps track of this information until after
		1476	<tt>endCommand()</tt> returns, which allows you to use format strings
		1477	from within <tt>endCommand()</tt>.
		1478
		1479	<li>Fixed a parser bug: Executing <tt>exit</tt> within
		1480	<tt>preCommand()</tt> did not have the documented effect of skipping
		1481	all of the remaining objects in the command, but simply skipped the
		1482	first object in the command. <tt>exit</tt> in <tt>preCommand()</tt>
		1483	now correctly skips the entire object list for the command.
		1484
		1485	<li>Fixed a parser bug: An object defined with the same leading
		1486	substring six characters or longer in multiple adjectives sometimes
		1487	appeared more than once in a disambiguation query ("Which book do you
		1488	mean, the yellow book, or the yellow book?"). This same type of
		1489	problem was fixed in most cases in version 2.4.0, but one type of
		1490	the problem remained; this has now been fixed.
		1491
		1492	<li>Another bug, related to the bug above, was fixed. In some cases,
		1493	when the player responded to a disambiguation query with <i>multiple</i>
		1494	objects, the parser would ask the disambiguation question again with
		1495	every object in the entire game, whether accessible to the player or not,
		1496	in the list of possible objects. This has been corrected.
		1497
		1498	<li>Another parser bug was fixed: If a word referred to more than about 200
		1499	objects, the parser displayed a double error message (specifically,
		1500	"The word 'foo' refers to too many objects.I don't see any foo here.").
		1501	This has been corrected; only the first message ("too many objects")
		1502	is displayed now.
		1503
		1504	<li>Fixed a bug in adv.t: the <tt>listcontgen()</tt> function, when
		1505	the "recursive" flag was set, incorrectly tried to evaluate <tt>itemcnt()</tt>
		1506	with an object rather than a list, causing a run-time error. This has
		1507	been corrected.
		1508
		1509	<li>The parser's handling of situations where an "again" command is
		1510	impossible due to object deletion has been improved. In the past,
		1511	if an object involved in the previous command was deleted, and the
		1512	player typed "again," the parser would respond with parser message
		1513	26 ("There's no command to repeat"). The parser now responds with
		1514	the more suitable message 27 ("You can't repeat that command").
		1515
		1516	<li>The parser now properly restores the text of the player's
		1517	original command words for the direct and indirect object when the
		1518	player repeats a command with "again." In the past, the parser did
		1519	not retain the text of the previous command's words, so <tt>objwords()</tt>
		1520	returned empty lists when the game attempted to retrieve the object
		1521	words during execution of a repeated command. This inconsistency
		1522	has been corrected.
		1523
		1524	<li>The <tt>parseNounList()</tt> function returned an incorrect word
		1525	index value in the first element of its return list in two cases:
		1526	when the noun phrase did not match any objects; and when there was no
		1527	noun phrase present. In both of these cases, the returned index value
		1528	had a value one less than the correct value. This has been corrected.
		1529
		1530	<li>Fixed a problem that occasionally caused a crash when the player
		1531	entered a command containing an ampersand ("&") when the game was
		1532	running in HTML mode.
		1533
		1534	<li>Fixed a parser bug that occasionally caused a crash when the player
		1535	responded to a disambiguation prompt ("which book do you mean...") with
		1536	"him" or "her."
		1537
		1538	</ul>
		1539
		1540	<br><br><hr>
		1541	<h3><a name='tads250'>Version 2.5.0</a></h3>
		1542
		1543	<i>Released on July 10, 1999</i>
		1544
		1545	<h4>Index of Changes</h4>
		1546
		1547	<ul>
		1548	<li><a href='#precmd'>preCommand()</a>
		1549	<li><a href='#postact'>postAction() and endTurn()</a>
		1550	<li><a href='#inputdialog'>inputdialog()</a>
		1551	<li><a href='#inputline'>inputline()</a>
		1552	<li><a href='#restore_ret'>New restore() return codes</a>
		1553	<li><a href='#askfile_ext'>Extended askfile() interface</a>
		1554	<li><a href='#switchPlayer'>switchPlayer()</a>
		1555	<li><a href='#iwide'>Inventory Wide and Tall</a>
		1556	<li><a href='#nestlistcont'>nestlistcont()</a>
		1557	<li><a href='#listcontgen'>listcontgen()</a>
		1558	<li><a href='#basicMeTravelTo'>basicMe.travelTo changes</a>
		1559	<li><a href='#movableActorTravelTo'>movableActor.travelTo changes</a>
		1560	<li><a href='#ds2'>New compiler debug record format (-ds2)</a>
		1561	<li><a href='#parserbug250'>Parser bug fixes</a>
		1562	<li><a href='#tdbbug250'>Debugger bug fixes</a>
		1563	<li><a href='#tcbug250'>Compiler bug fixes</a>
		1564	</ul>
		1565
		1566
		1567
		1568	<h4><a name='precmd'>
		1569	New pre-execution processing: <tt>preCommand</tt></a></h4>
		1570
		1571	<p>
		1572	At the start of the execution phase, before calling <tt>verbAction()</tt>
		1573	for the first direct object in the command, the parser invokes
		1574	the new function <tt>preCommand()</tt>:
		1575
		1576	<p>
		1577	<pre>
		1578	preCommand(<i>actor, verb, dobj_list, prep, iobj</i>);
		1579	</pre>
		1580
		1581	<p>
		1582	The "actor", "verb", "prep", and "iobj" parameters are objects giving
		1583	the actor, verb, preposition, and indirect object in the command,
		1584	respectively. The "dobj_list" parameter is a list of the direct objects
		1585	in the command, in the same order as they appear in the command.
		1586
		1587	<p>
		1588	This function can use <tt>exit</tt> to skip to fuses and daemons,
		1589	or it can use <tt>abort</tt> to cancel the command entirely, in which
		1590	case the parser will skip directly to the <tt>endCommand</tt> function
		1591	(see below). If this function simply returns, the parser continues
		1592	processing the command as normal.
		1593
		1594
		1595	<h4><a name='postact'>New end-of-turn processing: <tt>postAction</tt> and
		1596	<tt>endCommand</tt></a></h4>
		1597
		1598	<p>
		1599	In past versions of TADS, it wasn't possible to add special event
		1600	processing at the end of a turn. The closest approximation was to
		1601	put processing in a fuse or daemon, but this approach has several
		1602	drawbacks: no information is available in a fuse or daemon on the
		1603	last command executed, and it is not possible to specify the order
		1604	of execution of fuses and daemons.
		1605
		1606	<p>
		1607	Two new parser hooks provide for structured event handling at the
		1608	end of a turn. The first hook, the <tt>postAction</tt> function,
		1609	lets you write code that the parser calls immediately after the
		1610	"action" method, and before any fuses or daemons. The second hook,
		1611	the <tt>endCommand</tt> function, lets you write code that the
		1612	parser calls at the end of a turn, just after running all of the
		1613	fuses and daemons for the turn.
		1614
		1615	<p>The parser calls <tt>postAction</tt> once for each object in a
		1616	command with multiple direct objects, just after it calls the
		1617	"action" method for the object. If the command is terminated early
		1618	with <tt>exit</tt>, <tt>exitobj</tt>, or <tt>abort</tt>, the parser
		1619	invoked <tt>postAction</tt> immediately after the <tt>exit</tt>,
		1620	<tt>exitobj</tt>, or <tt>abort</tt> statement executes. The parser
		1621	calls <tt>postAction</tt> with the following arguments:
		1622
		1623	<p>
		1624	<pre>
		1625	postAction(<i>actor, verb, dobj, prep, iobj, status</i>);
		1626	</pre>
		1627
		1628	<p>
		1629	The first five parameters specify the current command; any of the objects
		1630	except "actor" and "verb" can be nil. The "status" parameter has the
		1631	same meaning as the return codes from the <tt>execCommand</tt> built-in
		1632	function; it can be one of the following values, defined in adv.t:
		1633
		1634	<p>
		1635	<table>
		1636	<tr><td>
		1637	<td>
		1638	<table cellpadding=2>
		1639
		1640	<tr><td valign=top><tt>EC_SUCCESS</tt>  <td valign=top>
		1641	The command executed successfully, which indicates that everything
		1642	up through and including the command's "action" method
		1643	(<tt><i>verb</i>.action</tt>, <tt><i>dobj</i>.doAction</tt>, or
		1644	<tt><i>iobj</i>.ioAction</tt>, as appropriate).
		1645
		1646	<tr><td valign=top><tt>EC_EXIT</tt>  <td valign=top>
		1647	An <tt>exit</tt> statement was executed.
		1648
		1649	<tr><td valign=top><tt>EC_EXITOBJ</tt>  <td valign=top>
		1650	An <tt>exitobj</tt> statement was executed.
		1651
		1652	<tr><td valign=top><tt>EC_ABORT</tt>  <td valign=top>
		1653	An <tt>exit</tt> statement was executed.
		1654
		1655	</table>
		1656	</table>
		1657
		1658	<p>
		1659	The <tt>postAction</tt> function returns no value.
		1660
		1661	<p>
		1662	The parser invokes the <tt>endCommand</tt> after all of the fuses
		1663	and daemons have finished running at the end of a turn. This function
		1664	is called once per command, not per object; in a command with multiple
		1665	direct objects, this function is called only once, just as fuses and
		1666	daemons are called only once for the entire command.
		1667
		1668	<p>
		1669	The parser calls <tt>endCommand</tt> as follows:
		1670
		1671	<p>
		1672	<pre>
		1673	endCommand(<i>actor, verb, dobj_list, prep, iobj, status</i>);
		1674	</pre>
		1675
		1676	<p>
		1677	The "status" parameter has the same meaning as the status code parameter
		1678	to <tt>postAction</tt>. The other parameters have the same values
		1679	as they did in the call to <tt>preCommand</tt> that the parser makes
		1680	at the start of the execution phase for the command.
		1681
		1682	<p> <tt>endCommand</tt> is always invoked at the end of a turn. If an
		1683	<tt>abort</tt> statement is executed in the course of a turn, the parser
		1684	skips directly to <tt>endCommand</tt>, because <tt>abort</tt> skips the
		1685	daemons and fuses. This means that <tt>endCommand</tt> is executed at
		1686	the end of a turn even when fuses and daemons are skipped.
		1687
		1688	<p>
		1689	The <tt>endCommand</tt> function returns no value.
		1690
		1691	<h4><a name='inputdialog'>
		1692	New built-in function <tt>inputdialog()</tt></a></h4>
		1693
		1694	<p>A new built-in function, <tt>inputdialog()</tt>, lets you ask the
		1695	player a multiple-choice question. On graphical systems,
		1696	</tt>inputdialog()</tt> displays a system dialog box, and lets the
		1697	user respond by clicking a button. On text systems, this function
		1698	displays a textual prompt and lets the user respond with the keyboard.
		1699
		1700	<p>
		1701	<tt>inputdialog</tt> takes the following parameters:
		1702
		1703	<p>
		1704	<pre>
		1705	inputdialog(<i>icon, prompt, response_list, default_idx, cancel_idx</i>)
		1706	</pre>
		1707
		1708	<p>
		1709	The "icon" parameter indicates which icon, if any, to display. The icon
		1710	will only be displayed on graphical systems; text-only systems ignore
		1711	this parameter. These icon constants are defined in adv.t:
		1712
		1713	<p>
		1714	<table>
		1715	<tr><td>
		1716	<td>
		1717	<table cellpadding=2>
		1718	<tr><td valign=top><tt>INDLG_ICON_NONE</tt>  <td valign=top>
		1719	Do not use any icon.
		1720
		1721	<tr><td valign=top><tt>INDLG_ICON_WARNING</tt>  <td valign=top>
		1722	Show a "warning" icon. This indicates a potential or minor problem.
		1723	(On Windows, this displays an exclamation-point icon.)
		1724
		1725	<tr><td valign=top><tt>INDLG_ICON_INFO</tt>  <td valign=top>
		1726	Show an "information" icon. This indicates to the user that the dialog
		1727	is being displayed to inform them of the status of an operation.
		1728	(On Windows, this displays an icon with a small letter "i" in a circle.)
		1729
		1730	<tr><td valign=top><tt>INDLG_ICON_QUESTION</tt>  <td valign=top>
		1731	Show a "question" icon. This indicates that additional information
		1732	from the user is required.
		1733	(On Windows, this displays a question-mark icon.)
		1734
		1735	<tr><td valign=top><tt>INDLG_ICON_ERROR</tt>  <td valign=top>
		1736	Show an "error" icon. This indicates that a problem has occurred.
		1737	(On Windows, this displays a stop-sign icon.)
		1738
		1739	</table>
		1740	</table>
		1741
		1742	<p>
		1743	The "prompt" parameter is the message string to display. For graphical
		1744	systems, this message is displayed in a dialog box; for text systems,
		1745	it's simply displayed on the terminal.
		1746
		1747	<p>The "response_list" is a list of strings giving the valid responses.
		1748	Each entry in the list is a string giving one possible response.
		1749	On graphical systems, one button is displayed in the dialog for each
		1750	response string; the response string is the button's label. On text
		1751	systems, the responses are displayed to the player after the prompt
		1752	string.
		1753
		1754	<p>
		1755	Each string in the response list can optionally include an ampersand
		1756	character ("&") before the character that serves as a keyboard
		1757	short-cut for the response. The ampersand is not displayed in the
		1758	button label or response list displayed to the player. For example,
		1759	the response list string '&Yes' makes the "Y" key a short-cut for
		1760	the button, which is labeled "Yes" in the dialog. On some systems
		1761	the short-cut key will be indicated visually in the dialog; on Windows,
		1762	for example, the "Y" in the "Yes" button would be underlined to indicate
		1763	that the letter "Y" is the short-cut for the button. If no ampersand
		1764	appears in a response list item, the item has no short-cut.
		1765
		1766	<p>
		1767	On text-only systems, the keyboard short-cut will be indicated visually
		1768	by enclosing the short-cut letter in parentheses when dispalying the
		1769	list of possible responses to the player. If a response item has no
		1770	short-cut key, the player must enter a sufficiently long leading substring
		1771	of the response item so that the response is unambiguous with the other
		1772	valid responses.
		1773
		1774	<p>Each element of the list can be a number, rather than a string.
		1775	If an element is a number, it specifies that the button should use
		1776	a pre-defined standard label. You should use standard labels when
		1777	possible, because these labels will follow local system conventions
		1778	and will be localized to the player's language settings; these labels
		1779	are read from external resources on platforms with appropriate operating
		1780	system support, so they can be localized easily. To select a standard
		1781	label, use one of the following values, defined in adv.t:
		1782
		1783	<p>
		1784	<table>
		1785	<tr><td>
		1786	<td>
		1787	<table cellpadding=2>
		1788	<tr><td valign=top><tt>INDLG_LBL_OK</tt>  <td valign=top>
		1789	"OK", or local system or language equivalent
		1790
		1791	<tr><td valign=top><tt>INDLG_LBL_CANCEL</tt>  <td valign=top>
		1792	"Cancel"
		1793
		1794	<tr><td valign=top><tt>INDLG_LBL_YES</tt>  <td valign=top>
		1795	"Yes"
		1796
		1797	<tr><td valign=top><tt>INDLG_LBL_NO</tt>  <td valign=top>
		1798	"No"
		1799	</table>
		1800	</table>
		1801	<p>
		1802	The strings shown above do not necessarily reflect the actual button
		1803	text that the player will see, because the actual label will vary by
		1804	platform and by language. Whatever label is displayed, though, will
		1805	convey to the user the same meaning.
		1806
		1807	<p>You can also select an entire standard set of buttons, rather than
		1808	specifying each button individually. If the response_list parameter
		1809	is a number, rather than a list, it indicates that a standard set of
		1810	buttons is to be used, selected from a pre-defined list. The
		1811	advantage of using one of these pre-defined button sets when possible
		1812	is that the buttons will automatically follow local system
		1813	conventions and be localized to the player's language settings, on
		1814	platforms with appropriate operating system support. To select a
		1815	pre-defined button set, use one of the following values, defined in
		1816	adv.t, for the response_list parameter:
		1817
		1818	<p>
		1819	<table>
		1820	<tr><td>
		1821	<td>
		1822	<table cellpadding=2>
		1823	<tr><td valign=top><tt>INDLG_OK</tt>  <td valign=top>
		1824	The dialog will display an "OK" button, properly localized.
		1825
		1826	<tr><td valign=top><tt>INDLG_OKCANCEL</tt>  <td valign=top>
		1827	The dialog will display an "OK" button and a "Cancel" button, properly
		1828	localized.
		1829
		1830	<tr><td valign=top><tt>INDLG_YESNO</tt>  <td valign=top>
		1831	The dialog will display an "Yes" button and a "No" button, properly
		1832	localized.
		1833
		1834	<tr><td valign=top><tt>INDLG_YESNOCANCEL</tt>  <td valign=top>
		1835	The dialog will display a "Yes" button, a "No" button, and a
		1836	"Cancel" button, properly localized.
		1837
		1838	</table>
		1839	</table>
		1840
		1841	<p> The "default_idx" parameter gives the index in the response list
		1842	of the default response. If the user presses the "Return" key, or
		1843	performs any other action appropriate to the system user interface
		1844	that by local convention accepts the default response to a dialog,
		1845	this response will be used. The first list entry is at index 1.
		1846	Pass nil in this parameter if there is no default response, in which
		1847	case TADS will require the user to select a specific button. (Note
		1848	that, on some systems, passing nil for this parameter will not make a
		1849	noticeable difference; on Windows, for example, one of the buttons
		1850	will always have keyboard focus, so pressing the Return key will
		1851	always select one of the buttons.)
		1852
		1853	<p>
		1854	The "cancel_idx" parameter gives the index in the response list of the
		1855	cancellation response. Most GUI systems have a standard way of cancelling
		1856	a dialog; the Escape key has this effect on Windows, for example, as does
		1857	the Command-Period key combination on the Macintosh. If the user performs
		1858	the appropriate system-specific action to cancel the dialog, this response
		1859	is used. The first list entry is at index 1. Pass nil in this parameter
		1860	if there is no cancel response, in which case TADS will not allow the
		1861	player to cancel the dialog.
		1862
		1863	<p> The dialog returns the index of the response that the player
		1864	selects: 1 for the first response in the response list, 2 for the
		1865	second entry in the list, and so on. For the standard response lists
		1866	(<tt>INDLG_YESNO</tt> and so on), the response are in the order described
		1867	for the constant name: <tt>INDLG_YESNO</tt> has a "Yes" button at index
		1868	1 and a "No" button at index 2, for example.
		1869
		1870	<p>
		1871	Here's an example of using this function.
		1872
		1873	<p>
		1874	<pre>
		1875	ret := inputdialog('What would you like to do next?',
		1876	['&Restore', 'Re&start', '&Quit'],
		1877	nil, 3);
		1878	switch(ret)
		1879	{
		1880	case 1:
		1881	/* restore a game... */
		1882	break;
		1883
		1884	case 2:
		1885	/* restart the game */
		1886	restart();
		1887	break;
		1888
		1889	case 3:
		1890	/* quit */
		1891	quit();
		1892	break;
		1893	}
		1894	</pre>
		1895
		1896	<p>
		1897	On a graphical system, this would display a dialog with the message
		1898	text "What would you like to do next?", and three buttons: one
		1899	with the label "Restore", one with the label "Restart", and one with
		1900	the label "Quit". If the user presses the "R" key, the "Restore" button
		1901	would be selected; if the user presses "S", the "Restart" button would
		1902	be selected; if the user presses "Q", or cancels the dialog (by pressing
		1903	the Escape key on a Windows machine, for example), the "Quit" button
		1904	would be selected.
		1905
		1906	<p>
		1907	On a text-only system, TADS would display this text on the terminal,
		1908	on a new line (TADS would output a "\n" sequence to start a new line):
		1909
		1910	<p><pre>
		1911	What would you like to do next? (R)estore/Re(s)tart/(Q)uit >
		1912	</pre>
		1913
		1914	<p>
		1915	TADS would then wait for the player to enter a line of text (as with
		1916	the <tt>input()</tt> built-in function). If the player enters one
		1917	letter, TADS would check the letter against each response's short-cut,
		1918	and return the one that matches. If the player enters more than one
		1919	letter, TADS would check the string against the leading substring of
		1920	each possible response; if the string matches one of the responses
		1921	unambiguously, TADS would return that response. If the player enters
		1922	something invalid or ambiguous, TADS would redisplay the prompt and
		1923	await another response.
		1924
		1925	<p><tt>inputdialog()</tt> has certain limits. The prompt string can
		1926	be no longer than 256 characters. There can be no more than ten
		1927	responses, and the total length of the text in all of the responses
		1928	must not exceed 256 characters. In addition, to ensure portability,
		1929	you should choose a reasonably short label for each button; some
		1930	systems use buttons of a fixed size, so a long label name might not
		1931	fit in the available space on some systems. Whenever possible, use
		1932	a single word for each button label.
		1933
		1934
		1935	<h4><a name='inputline'>New <tt>inputline()</tt> function in adv.t</a></h4>
		1936
		1937	<p>A new function, <tt>inputline()</tt>, is defined in adv.t. This
		1938	function is a simple cover for the built-in function <tt>input()</tt>,
		1939	with the additional feature that <tt>inputline()</tt> switches to
		1940	the "TADS-Input" font when the game is running in HTML mode. This
		1941	means that the text that the player enters during an <tt>inputline()</tt>
		1942	has the same appearance as the text entered on a normal command line.
		1943
		1944	<p>
		1945	Note that the <tt>input()</tt> function does not switch to the
		1946	"TADS-Input" font itself, because if it did, you'd have no way to
		1947	override this behavior. Rather than forcing input text to be displayed
		1948	in the "TADS-Input" font, the <tt>input()</tt> function leaves it up to
		1949	the game author to determine how input text should look. In most cases,
		1950	you should use <tt>inputline()</tt> rather than calling <tt>input()</tt>
		1951	directly, to ensure that the player's input has the normal command line
		1952	appearance. In some cases, however, you might wish to use a specific
		1953	appearance for input text, rather than using the default setting;
		1954	in these cases, you should set your own font choice, then call
		1955	the <tt>input()</tt> function directly, since it won't change the
		1956	appearance from what you choose.
		1957
		1958	<h4><a name='restore_ret'>New <tt>restore()</tt> return code</a></h4>
		1959
		1960	<p>The <tt>restore()</tt> built-in function's return code has been changed.
		1961	In the past, this function returned nil to indicate success, and true
		1962	to indicate failure. The return value is now a number; different
		1963	values are returned for different error conditions, which makes it
		1964	possible to provide better information to the player about the
		1965	specific problem that caused the operation to fail.
		1966
		1967	<p>
		1968	The new return values, defined in adv.t, are:
		1969
		1970	<p>
		1971
		1972	<table>
		1973	<tr><td>
		1974	<td>
		1975	<table cellpadding=2>
		1976	<tr><td valign=top><tt>RESTORE_SUCCESS</tt>  <td valign=top>
		1977	Success
		1978
		1979	<tr><td valign=top><tt>RESTORE_FILE_NOT_FOUND</tt>  <td valign=top>
		1980	The file to be restored does not
		1981	exist (or could not be opened for some other reason).
		1982
		1983	<tr><td valign=top><tt>RESTORE_NOT_SAVE_FILE</tt>  <td valign=top>
		1984	The file is not a valid saved game.
		1985
		1986	<tr><td valign=top><tt>RESTORE_BAD_FMT_VSN</tt>  <td valign=top>
		1987	The file was saved by an incompatible
		1988	version of the TADS Interpreter
		1989
		1990	<tr><td valign=top><tt>RESTORE_BAD_GAME_VSN</tt>  <td valign=top>
		1991	The file was saved by a different
		1992	game, or by a different version of the same game.
		1993
		1994	<tr><td valign=top><tt>RESTORE_READ_ERROR</tt>  <td valign=top>
		1995	An error occurred reading the file.
		1996	This could indicate that the file was corrupted, or that the physical
		1997	medium containing the file is damaged.
		1998
		1999	<tr><td valign=top><tt>RESTORE_NO_PARAM_FILE</tt>  <td valign=top>
		2000	No parameter file has been
		2001	specified. This is returned only when <tt>restore(nil)</tt> is
		2002	called to attempt to load the file specified by a start-up parameter;
		2003	it indicates that there is in fact no parameter file to load.
		2004
		2005	</table>
		2006	</table>
		2007
		2008
		2009	<p>For compatibility, <tt>RESTORE_SUCCESS</tt> is defined as 0, and
		2010	all of the other values are non-zero. In most cases, this should
		2011	allow existing code (that assumes the nil/true return value) to
		2012	continue working without changes, since <tt>if (restore(fname))</tt> will
		2013	continue to have the same effect with this change. Only code that
		2014	explicitly compared the return value to nil or true will need to be
		2015	changed.
		2016
		2017	<p>The code in adv.t that calls <tt>restore()</tt> has been updated to
		2018	reflect this change, and uses the additional information to display a
		2019	more precise message when an error occurs.
		2020
		2021	<h4><a name='askfile_ext'>Extended <tt>askfile()</tt> Interface</a></h4>
		2022
		2023	<p>The <tt>askfile()</tt> built-in function's interface has been extended.
		2024
		2025	<p>A new, optional fourth argument lets you specify additional flags
		2026	to the <tt>askfile</tt> function. The possible flag values, defined
		2027	in adv.t, are:
		2028
		2029	<p>
		2030	<table>
		2031	<tr><td>
		2032	<td>
		2033	<table cellpadding=2>
		2034
		2035	<tr><td valign=top><tt>ASKFILE_EXT_RESULT</tt>  <td valign=top>
		2036	Return extended result codes (described below). If this flag is
		2037	provided, the function returns extended results; if this flag is
		2038	not specified, the function returns the traditional results.
		2039
		2040	</table>
		2041	</table>
		2042
		2043	<p>
		2044	In order to specify the new flag value argument, you must specify
		2045	the prompt type and file type arguments as well; if you omitted the
		2046	prompt or file type argument, the <tt>askfile</tt> function would not
		2047	be able to tell that you meant the last argument as the flags value.
		2048
		2049	<p>If you omit the flags argument, <tt>askfile</tt> uses a default
		2050	value of zero, which makes the function behave the same as in past
		2051	versions. Because older code never specifies a flags value, the
		2052	function will always behave compatibly with past versions when called
		2053	from older code.
		2054
		2055	<p>Traditionally, <tt>askfile</tt> returned a string on success, or
		2056	nil for any type of failure; this didn't permit the caller to
		2057	determine exactly what kind of failure occurred, and in particular
		2058	did not allow the caller to distinguish between an actual error and
		2059	the player cancelling the file selector dialog. When
		2060	<tt>ASKFILE_EXT_RESULT</tt> is specified, the function will return
		2061	additional information that allows the caller to distinguish these
		2062	cases.
		2063
		2064	<p>When the <tt>ASKFILE_EXT_RESULT</tt> flag is specified,
		2065	<tt>askfile</tt> returns a list that contains two elements. The
		2066	first element is a number which indicates the status of the file
		2067	selection; the second element is a string if a file was successfully
		2068	chosen, or nil if not. The possible values for the first element of
		2069	the returned list, defined in adv.t, are:
		2070
		2071	<p>
		2072	<table>
		2073	<tr><td>
		2074	<td>
		2075	<table cellpadding=2>
		2076
		2077	<tr><td valign=top><tt>ASKFILE_SUCCESS</tt>  <td valign=top>
		2078	A file was successfully chosen. The second element of the list contains
		2079	a string giving the chosen filename.
		2080
		2081	<tr><td valign=top><tt>ASKFILE_FAILURE</tt>  <td valign=top>
		2082	An error occurred prompting for a filename. This usually indicates
		2083	that the file selector dialog could not be shown for some reason
		2084	(insufficient memory, for example).
		2085
		2086	<tr><td valign=top><tt>ASKFILE_CANCEL</tt>  <td valign=top>
		2087	The user canceled the file selector dialog. On the Macintosh, for
		2088	example, this means that the user clicked the "Cancel" button. This
		2089	indicates that the user does not wish to proceed with whatever operation
		2090	is in progress, so the operation should be aborted. Since the user
		2091	explicitly chose to cancel the operation, the program should not indicate
		2092	that an error occurred, but simply that the operation will be terminated
		2093	in accordance with the user's request.
		2094
		2095	</table>
		2096	</table>
		2097
		2098	<p>
		2099	All code in adv.t that calls <tt>askfile</tt> has been updated to use
		2100	the new extended results information, so that it can provide more
		2101	appropriate responses when the user cancels a file selector dialog.
		2102
		2103	<p>
		2104	Here's an example, from the "restore" command's implementation in
		2105	adv.t, of using the new extended results.
		2106
		2107	<p>
		2108	<pre>
		2109	local savefile;
		2110
		2111	savefile := askfile('File to restore game from',
		2112	ASKFILE_PROMPT_OPEN, FILE_TYPE_SAVE,
		2113	ASKFILE_EXT_RESULT);
		2114	switch(savefile[1])
		2115	{
		2116	case ASKFILE_SUCCESS:
		2117	return mainRestore(savefile[2]);
		2118
		2119	case ASKFILE_CANCEL:
		2120	"Canceled. ";
		2121	return nil;
		2122
		2123	case ASKFILE_FAILURE:
		2124	default:
		2125	"Failed. ";
		2126	return nil;
		2127	}
		2128	</pre>
		2129
		2130	<h4><a name='switchPlayer'>
		2131	New <tt>switchPlayer()</tt> function in adv.t</a></h4>
		2132
		2133	<p>
		2134	The standard library file adv.t provides a new function,
		2135	<tt>switchPlayer</tt>, that you can use to switch the player character
		2136	to a new actor. This function uses the built-in function
		2137	<tt>parserSetMe()</tt> to change the parser's internal player
		2138	character record, and in addition performs some book-keeping
		2139	work that's necessary when switching to a new player.
		2140
		2141	<p>Call <tt>switchPlayer()</tt> with one argument: the actor object
		2142	that is to become the new player character.
		2143
		2144	<p>First, <tt>switchPlayer()</tt> adds the outgoing player
		2145	character object to its room's contents list, and removes the
		2146	new player character object from its room's contents list. By
		2147	convention in adv.t, the active player character is never in its
		2148	location's contents list, but other actor objects are. Since the
		2149	outgoing object is switching from being the active player object to
		2150	an ordinary actor, it must be added to its room's contents list;
		2151	likewise, since the new object is changing from an ordinary actor
		2152	to the player character, it must be removed from its location's
		2153	contents list.
		2154
		2155	<p>Second, <tt>switchPlayer()</tt> removes the vocabulary words
		2156	"me" and "myself" from the outgoing player character object, and
		2157	adds these vocabulary words to the incoming player character.
		2158	This way, these words always refer to the current player character.
		2159
		2160	<p>If your game is based on adv.t, you should use <tt>switchPlayer()</tt>
		2161	to change to a new player character object, rather than calling
		2162	<tt>parserSetMe()</tt> directly, to ensure that the adv.t conventions
		2163	for the active player character object are maintained through the
		2164	change.
		2165
		2166	<p>Thanks to Scott Starkey for his help defining this function.
		2167
		2168	<h4><a name='iwide'>New adv.t verbs: inventory wide, inventory tall</a></h4>
		2169
		2170	<p>
		2171	The standard library file adv.t defines two new verbs: "inventory wide"
		2172	and "inventory tall." These verbs let the player control the inventory
		2173	display format. "Inventory wide" displays the player's inventory in
		2174	the traditional paragraph-style format. "Inventory tall" displays the
		2175	inventory in a single-column format, showing one object per line, and
		2176	showing the contents of each object indented one tab stop from its
		2177	container.
		2178
		2179	<p>
		2180	Once the player enters an "inventory tall" or "inventory wide" command,
		2181	subsequent "inventory" commands (without a format specified) will default
		2182	to the format of the previous command. The traditional "wide" format is
		2183	the initial setting, but you can change this in your game by setting
		2184	<tt>iVerb.useInventoryTall</tt> to <tt>true</tt> in your
		2185	<tt>init</tt> function.
		2186
		2187
		2188	<h4><a name='nestlistcont'>
		2189	New <tt>nestlistcont()</tt> function in adv.t</a></h4>
		2190
		2191	<p>
		2192	The standard library file adv.t has a new function, <tt>nestlistcont()</tt>,
		2193	that displays a listing of an object's contents in a nested single-column
		2194	format. This function can be used to display "tall" inventory listing,
		2195	rather than the paragraph-style "wide" listings that adv.t normally
		2196	displays.
		2197
		2198	<p>
		2199	<tt>nestlistcont()</tt> takes two arguments: the object whose contents are
		2200	to be listed, and a number giving the initial indenting. The function
		2201	indents the contents of the given object by the given number of tabs.
		2202	For each object contained in the given object that has a contents list
		2203	of its own, the function displays that object's contents indented one
		2204	additional tab level, and so on for their contents.
		2205
		2206	<p>
		2207	<tt>nestlistcont()</tt> displays an object's contents only if the
		2208	object's contents are visible, using the normal visibility rules.
		2209	If the object's contents are not visible, this function has no effect.
		2210	Furthermore, the function displays the contents of objects it displays
		2211	only for those objects whose contents are themselves visible.
		2212
		2213	<p>
		2214	Thanks to Kevin Forchione for providing this addition to adv.t.
		2215
		2216	<h4><a name='listcontgen'>
		2217	New <tt>listcontgen()</tt> function in adv.t</a></h4>
		2218
		2219	<p>
		2220	To support the <tt>nestlistcont()</tt> function, adv.t includes another
		2221	new listing function, <tt>listcontgen()</tt>. This function is a
		2222	general-purpose lister that provides the functionality of the traditional
		2223	<tt>listcont()</tt> function as well as the new <tt>nestlistcont()</tt>
		2224	function, which are essentially the same except for the display format.
		2225
		2226	<p>
		2227	<tt>listcontgen()</tt> takes three parameters:
		2228
		2229	<p>
		2230	<pre>
		2231	listcontgen(<i>obj, flags, depth</i>);
		2232	</pre>
		2233
		2234	<p>
		2235	The "obj" parameter is the object whose contents are to be listed, or
		2236	simply a list of objects to display. "flags" specifies a set of flag
		2237	values, defined in adv.t:
		2238
		2239	<p>
		2240	<table>
		2241	<tr><td>
		2242	<td>
		2243	<table cellpadding=2>
		2244	<tr><td valign=top><tt>LCG_TALL</tt>  <td valign=top>
		2245	Show a "tall" listing, with one item listed per line. If this flag
		2246	is specified, each line will be indented by the number of tab stops
		2247	given by the "indent" parameter. If <tt>LCG_TALL</tt> isn't specified,
		2248	the function shows a "wide" paragraph-style listing, with the items
		2249	separated by commas.
		2250
		2251	<tr><td valign=top><tt>LCG_CHECKVIS</tt>  <td valign=top>
		2252	Checks the visibility of the contents of "obj" before listing the
		2253	contents. If "obj" is a list, this flag is ignored. If this flag
		2254	isn't specified, the function lists the contents of "obj" without
		2255	checking to see if they're visible.
		2256
		2257	<tr><td valign=top><tt>LCG_RECURSE</tt>  <td valign=top>
		2258	Show a recursive listing. If this flag is specified, the function
		2259	lists the contents of each item it displays. The recursive call
		2260	uses the same "flags" value and increments the "indent" depth by
		2261	one. If this flag isn't specified, the function doesn't show the
		2262	contents of the objects it lists.
		2263	</table></table>
		2264
		2265	<p>
		2266	Note that <tt>listcontgen()</tt> allows you to produce an object
		2267	listing for lists other than contents of objects. If you pass a
		2268	list in the "obj" parameter, the function lists the items in the
		2269	list using the same formatting that it would for a contents list.
		2270	This allows you to display a contents-style listing for some collection
		2271	of objects other than a contents list.
		2272
		2273
		2274	<h4><a name='basicMeTravelTo'><tt>basicMe.travelTo</tt> changes</a></h4>
		2275
		2276	<p>In adv.t, the <tt>basicMe.travelTo</tt> method now checks to see
		2277	if "self" is actually the active player character object; if not, the
		2278	method inherits the <tt>travelTo</tt> processing for a regular actor,
		2279	rather than using the special behavior for the current player character.
		2280	This change facilitates using <tt>basicMe</tt> as a base class for
		2281	defining player character objects in a game with more than one player
		2282	character.
		2283
		2284
		2285	<h4><a name='movableActorTravelTo'>
		2286	<tt>movableActor.travelTo</tt> changes</a></h4>
		2287
		2288	<p>In adv.t, the <tt>movableActor.travelTo</tt> method uses an improved
		2289	algorithm for determining when to show the "leaving" and "arriving"
		2290	messages for the actor. The new algorithm considers the actor's visibility
		2291	to the player, before and after the move, in determining whether to show
		2292	the messages; the old algorithm considered only the immediate container
		2293	of the actor and of the player, which produced the wrong results when
		2294	the actor was moving between locations that are both visible to the
		2295	player, such as a nested room. In addition, the new algorithm handles
		2296	obstacles (such as doors) properly.
		2297
		2298	<p>
		2299	Thanks to Kevin Forchione for providing this improved implementation.
		2300
		2301
		2302	<h4><a name='ds2'>New compiler debug record format</a></h4>
		2303
		2304	<p>A new compiler option, <tt>-ds2</tt>, tells the compiler to
		2305	generate a new style of debugging information designed to work with
		2306	the Windows HTML TADS Debugger (part of TADS Workbench). If you're
		2307	running your game with the Windows debugger version 2.5.0 or later,
		2308	you <b>must</b> compile with the <tt>-ds2</tt> option. If you're
		2309	using an older version of the Windows debugger, or you're using the
		2310	debugger on another platform (DOS, Unix, Mac), you must continue to
		2311	use the original <tt>-ds</tt> option as before.
		2312
		2313
		2314	<h4><a name='parserbug250'>Parser bug fixes</a></h4>
		2315
		2316	<p>The following player command parser bugs have been fixed:
		2317
		2318	<ul>
		2319
		2320	<li>Fixed a parser bug that caused an infinite loop (which caused the
		2321	game to lock up) if a game defined the same vocabulary word as both
		2322	an adjective and a plural.
		2323
		2324	<li>Fixed a parser bug involving <tt>disambigDobj</tt> and
		2325	<tt>disambigIobj</tt>. When these methods returned a list of objects
		2326	that was still ambiguous, the parser's default question ("Which
		2327	<i>noun-phrase</i> do you mean...") didn't format the list of
		2328	possibilities correctly; in particular, extra commas and "or"'s
		2329	sometimes appeared at the end of the list. This has been corrected.
		2330
		2331	</ul>
		2332
		2333	<h4><a name='tdbbug250'>Debugger bug fixes</a></h4>
		2334
		2335	<p>The following debugger problems have been corrected:
		2336
		2337	<ul>
		2338
		2339	<li>Fixed a debugger problem that caused single-step execution to skip
		2340	past a line containing a disabled breakpoint.
		2341
		2342	<li>Fixed a problem in the debugger that caused a sporadic crash when
		2343	displaying a stack traceback where a function in the stack trace had
		2344	a string argument value, and the string was over about 40 characters
		2345	long. This bug affected all versions of the debugger, but was most
		2346	noticeable on the Windows HTML version, because the Windows debugger
		2347	builds a stack traceback every time it takes control (on hitting a
		2348	breakpoint, for example, or after single-stepping a line of code).
		2349
		2350	<li>In certain cases, the debugger showed the current source line
		2351	(and breakpoints) off by a couple of lines from where it should have
		2352	been. This happened when the source file had one or more lines that
		2353	were exactly 97 characters long, and had DOS-style line termination
		2354	(CR-LF newline sequences). (This was actually a bug in the compiler
		2355	and not the debugger, but it showed up most visibly using the
		2356	debugger.) This has been corrected.
		2357
		2358	</ul>
		2359
		2360	<h4><a name='tcbug250'>Compiler bug fix</a></h4>
		2361
		2362	<p> This version corrects an obscure compiler bug that caused
		2363	<tt>preinit</tt> to execute incorrectly under certain circumstances.
		2364	This bug occurred when <tt>preinit</tt> called a method in an object,
		2365	and the method modified a list-valued property of the object, and the
		2366	property was defined earlier in the object than the method (i.e., the
		2367	property's definition in the source file preceded that of the
		2368	method). In such cases, the compiler's behavior was unpredictable;
		2369	sometimes it ran correctly, sometimes it stored incorrect values in
		2370	the list, and sometimes the compiler crashed. This problem should no
		2371	longer occur.
		2372
		2373	<br><br><br>
		2374
		2375	</html>
		2376

FrobTADS

cfad47cfa3/tads2/tadsver.htm