This file is part of the TADS Parser Manual.
Copyright © 1987-2000 by Michael J. Roberts.
All rights reserved.
This manual is based upon the New Book of the Parser
by Michael J. Roberts,
as converted to HTML by
N.
K. Guy,
tela design.
The TADS Parser Manual
A Guide to the TADS Command Parser
by
Michael J. Roberts
Introduction and Table of Contents
September, 2000
When I released version 2.2 of TADS over two years ago, I felt that the programmatic interface to the parser had grown so much that the chapter of the TADS Author's Manual describing the parser, which had last been revised for TADS version 2.0, was hopelessly out of date and needed to be rewritten. To this end, I wrote a completely new and updated version of the chapter, dubbed it the New Book of the Parser, and included it as part of the version 2.2 release notes.
The TADS parser has not stood still since then, and with TADS 2.4 the time has come once again to overhaul the parser documentation to reflect the modern reality and to provide game authors with a single source of information that encompasses the entire parser in, I hope, an organized fashion.
For new game authors who haven't used TADS before version 2.4, you need look no further than this TADS Parser Manual for complete information on the 2.4 parser: you can in particular ignore Chapter Four of the 2.0 Author's Manual, as well as the 2.2 New Book. For experienced TADS game authors, you might still want to refer to the release notes (TADSVER.HTM) for a list of changes made since your previous version of TADS, but this manual should provide you with a complete reference to all of the parser's functionality, old and new.
This update to the parser manual is based upon the New Book of the Parser from TADS 2.2, which superseded the original "Writing Adventures" chapter in the TADS Author's Manual. If you've read that earlier edition, you'll find that most of the original material is retained in this update, though much of it is revised and expanded. In addition, this version is substantially reorganized relative to the 2.2 edition to make the contents more approachable and useful.
Because of the volume of material now constituting a complete description of the TADS parser, and in pursuit of a better organization, the Parser Chapter is now the Parser Manual. The first chapter after this introduction provides an overview of how the parser interacts with the game; subsequent chapters describe in increasing detail how to use and program the parser. The final chapter provides a summary of the parser's programmatic interface.
At the beginning of this introductory chapter you will find a comprehensive Table of Contents to the entire parser manual.
Throughout the Parsing Fundamentals chapter, you'll find what we light-heartedly refer to as "theorems"; these call out facts about the parser that are especially important and subtle. In most cases, the theorems point out features that frequently confuse game authors who are first learning TADS; if you're skimming this manual for the first time, you should pay special attention to these points. The theorems are by no means a complete summary, but are simply meant to highlight the most subtle topics.
Experienced game authors might find the section Summary of Parsing and Execution Sequence to be a useful quick reference to the parser's operations.
I would like to thank everyone who has offered suggestions for new features and improvements; I hope you find at least a few of the items on your TADS wish list fulfilled in TADS 2.4. The continuing improvement of the parser is due, in large part, to the bold imaginings of game authors who steadily invent new things to do with TADS.
I'd especially like to thank Stephen Granade, TenthStone, Pieter Spronck, Neil K. Guy, Kevin Forchione, and Suzanne Skinner for their advice and many fine ideas. I am also grateful to Neil for bringing the TADS documentation into the modern age through his HTML conversion of the TADS Author's Manual and of the original New Book of the Parser, which served as the basis for this update; and to Kevin for his considerable help in editing this new version.
If you were going to write a text adventure game, and you didn't have a system such as TADS, you would be faced with the daunting prospect of designing a player command parser. The job is so large that you'd probably spend more time designing and implementing your parser than on any other part of the game.
Fortunately, if you're taking the time to read this, you're at least thinking about building your game with TADS, which means that you won't have to write your own parser. Using an existing parser will save you a vast amount of work, but won't eliminate your work entirely: you won't have to write your own parser, but you will have to learn at least a little about the parser you're using to write your game.
With TADS, the amount you need to learn depends on what you want to do. You can do quite a lot with TADS without learning anything at all about the parser - by using existing class libraries (such as the standard library adv.t supplied with TADS), you can create objects whose interactions with the parser have already been defined, so that all you need to do is fill in some simple information on the objects, such as their names and descriptions. Once you've become comfortable with the basics of writing TADS games, though, you'll want to create your own object classes, with their own interactions with existing verbs; to do this, you'll have to learn a little bit about how the parser processes commands, so that you can add code to your new objects that lets them respond to certain commands. You'll probably also want to be able to create your own verbs, which requires that you learn how to define your own commands. After you've done all of this, you may want to start making more complicated changes, which will require that you learn about some of the more esoteric aspects of the parser.
The built-in parser handles most of the "syntactic analysis" part of parsing: dividing a command into individual words (or "tokens"), determining the sentence boundaries of command lines with multiple commands, figuring out which words specify the verb and prepositions, and identifying noun phrases. The built-in portion also defines the execution process by calling a series of methods in the objects involved in a command to carry out the action of the command.
The portion of the parser that is built in to the TADS interpreter obviously cannot be changed directly by the TADS game program. However, the built-in parser has numerous customization "hooks," which are specific places in the parsing process where the game can define custom behavior. The number of customization hooks has increased over time, as has their power; with modern versions of TADS, there's very little of the built-in parser that you can't override.
The parser customization hooks take several forms. Some of the hooks let you define strings that the parser uses for certain special words, such as "all" and "except". Most of the hooks let you define a function or an object method that the parser invokes at a certain stage in the parsing process, which you can use to modify the way that stage works. In most cases, a customization hook function lets you completely override an aspect of the built-in parser.
The built-in parser does not provide any of its own verbs, prepositions, or objects; this is the job of the game program. Since most games have a large set of basic commands and object classes in common, TADS includes in its standard library (defined in the file adv.t) numerous verbs and prepositions.
Your game program can change anything in the library; for that matter, you can throw the library away entirely and create your own, or use a library someone else has designed (WorldClass, for example).