--------------------------------------------------------------------------- Pname.h, Version 1.1, 10 May 2001, copyright 2001, by Neil Cerutti (cerutti@together.net) This version of pname.h is recommended for use only with version 6/10 of the Inform Library. This is the documentation for pname.h, a package which, by supplementing the object name recognition code in the Inform Library, greatly reduces the need to write parse_name routines. It contains the following sections: INTRODUCTION INSTALLATION and USAGE Q&A OPERATORS PARSING TECHNICAL NOTES RESERVED WORDS DISTRIBUTION NO WARRANTY SPECIAL THANKS VERSION HISTORY --------------------------------------------------------------------------- INTRODUCTION If your game includes objects with similar names occuring in the same place (for example, a Kitchen containing a JUICY ORANGE and some ORANGE JUICE), you'll be familiar with the problem of disambiguation: EXAMINE JUICY and EXAMINE JUICE describe respectively the fruit and the beverage, but EXAMINE ORANGE prompts for a more precise specification of which object is meant. To avoid irritating the player -- who may consider it 'obvious' that in this case the fruit is the intended target -- you are then forced to replace these objects' name properties (with their simple lists of dictionary words) by more complex parse_name properties; these comprise customized routines which can be tricky to write and debug. The pname.h package defines a new object property, pname (short for phrase name), with a similar look and feel to the standard name property: both contain a list of dictionary words. However, in a pname property the order of the words is significant, and special operators '.p' '.or' and '.x' enable you to embed some intelligence into the list. In most cases where the standard name property isn't enough, you can now just replace it with a pname property, rather than write a parse_name property routine. For example, to solve the problem above, all you need is: Object example_fruit "juicy orange" with pname '.x' 'juicy' 'orange', ... ; Object example_beverage "orange juice" with pname '.x' 'orange' 'juice', ... ; That is, a pname property is like a name property that has the enhanced capability of defining 'phrases' -- sequences of words -- that increase an object's likelihood of being selected when the player types matching words. In doing so, it provides an alternative to parse_name which is quick, flexible, and easy to use. --------------------------------------------------------------------------- INSTALLATION and USAGE To incorporate this package into your program, do three things: 1. Add four lines near the head of the program (before you include Parser.h). Replace MakeMatch; Replace Identical; Replace NounDomain; Replace TryGivenObject; 2. Include the pname.h header just after you include Parser.h. Include "Parser"; Include "pname.h"; 3. Add pname properties to those objects which require phrase recognition. Here's an example of an Inform program which uses this package: Constant Story "TEST STORY"; Constant Headline "^This is only a test^^"; Replace MakeMatch; ! /---- add these lines before Parser.h Replace Identical; ! | Replace NounDomain; ! | Replace TryGivenObject; !<' Include "Parser"; Include "pname.h"; ! <---- add this line after Parser.h Include "VerbLib"; ... Object shed "garden shed" with description "The wooden shed...", pname '.x' 'wooden' '.x' 'garden' 'shed', ... ; Object path "garden path" with description "The stony path...", pname '.x' 'stony' '.x' 'garden' 'path', ... ; Object garden "garden" with description "The garden...", name 'garden', ... ; ... A pname property defines one or more phrases that can refer to the given object, using dictionary words and simple operators. For instance, consider the pname declaration for the garden shed: pname '.x' 'wooden' '.x' 'garden' 'shed' The "garden shed" object's pname property contains one phrase in which the words 'wooden' and 'garden' are optional and 'shed' is mandatory. During parsing, the property generates a 'phrase match' -- a signal which increases its chance of being picked without the need for a disambiguation prompt -- in response to the inputs: WOODEN GARDEN SHED, WOODEN SHED, GARDEN SHED, and SHED. (For that matter, it would also generate matches for GARDEN GARDEN WOODEN WOODEN WOODEN GARDEN SHED, but not for TIMBER SHED or SHED WOODEN GARDEN.) --------------------------------------------------------------------------- Q&A Q: In what ways is the pname property different from the name property? A: In a pname property, the order in which the words appear makes a difference during the disambiguation process. In the standard name property, word order doesn't matter. In addition, you can include operators in your pname properties to help define them more precisely. The name property is always completely general. Q: Can't I already do this sort of thing with a parse_name routine? A: Not exactly, not as easily, not as generally, and not as quickly. (Also, don't worry if you don't understand parse_name routines... you won't have much need of them if you use pname.h.) For example, suppose your game contains some coffee and a coffee table: Object coffee "coffee" with name 'coffee', description "It's piping hot, with a stern warning label written on the side concerning debilitating tongue burns.", ... ; Object coffee_table "coffee table" with name 'coffee' 'table', description "It's rectangular, made of black marble and has an overstuffed magazine-rack underneath.", ... ; However, disambiguation fails if the coffee and the coffee table are ever in scope together: You can see a coffe table and some coffee here. >EXAMINE COFFEE Which do you mean, the coffee or the coffee table? >COFFEE Which do you mean, the coffee or the coffee table? The coffee has become impossible to refer to! The traditional solution to this problem is to put a restrictive parse_name routine on the coffee table, which forces the game never to recognize the word COFFEE alone as referring to the table. Object coffee_table "coffee table" with parse_name [ wd; wd = NextWord(); if (wd == 'coffee' && NextWord() == 'table') return 2; else if (wd == 'table') return 1; else return 0; ], description "It's rectangular... ", ... ; This solution works great when both objects are in scope: You can see a coffee table and some coffee here. >EXAMINE COFFEE It's piping hot... >EXAMINE COFFEE TABLE It's rectangular... But there's still a trap. This doesn't work when the coffee table is in scope but the coffee is not, causing frustration to players when perfectly unambiguous input is rejected: You can see a coffee table here. >EXAMINE COFFEE You can't see any such thing. In this case, the parse_name routine is too restrictive. A more flexible routine would know that, when the coffee is not in scope, it's okay for COFFEE alone to refer to the coffee table. You can fix this problem by enhancing your parse_name, but you'll affect performance: Object coffee_table "coffee table" with name 'coffee' 'table', parse_name [ wd; if (~~TestScope(coffee)) return -1; ! use name prop instead wd = NextWord(); if (wd == 'coffee' && NextWord() == 'table') return 2; else if (wd == 'table') return 1; else return 0; ], description "It's rectangular... ", ... ; Here, the table's parse_name routine applies only when the coffee isn't in scope. However, calling TestScope() is computationally expensive; calling it from within a parse_name routine is very expensive, and doing so will noticeably slow down your game even on a fast computer. The situation, already messy, becomes worse if another ambiguous object (for example, a coffee table book) is added to the game; you're then forced to modify all your working parse_name routines. But, help is at hand! Using pname.h, you can simply code: Object coffee "coffee" with name 'coffee', description "It's piping hot... ", ... ; Object coffee_table "coffee table" with pname '.x' 'coffee' 'table', description "It's rectangular... ", ... ; Object coffee_table_book "coffee table book" with pname '.x' 'coffee' '.x' 'table' 'book', description "Hard covered and beautifully decorated,... ", ... ; Q: Cool! So I should use pname properties on all my objects, right? A: That's not necessary. You should use pname properties only when disambiguation might become a problem, such as the coffee table situation described above. There is no advantage to using them when Inform's normal system of name recognition is sufficient. For example, if you have a coffee mug and a litter bug in your game, the name property is capable of distinguishing between them and using a pname property would be a waste. Q: I defined a pname property for the black rod from Adventure: Object black_rod "black rod" with pname 'black' 'rod', ... ; Since both words 'black' and 'rod', are mandatory in that phrase, the single word BLACK and the phrase ROD BLACK will never refer to my object. Is that right? A: It depends; the object could still end up being the most likely match in scope. Remember that the pname property acts only as an _aid_ to disambiguation. If the player's input isn't ambiguous then the parser selects the black rod even if the phrase 'black' 'rod' isn't matched by the input. The phrase matcher in pname.h is not restrictive; rather, it applies bonuses during the disambiguation process for phrases that are matched. Q: Oh. So what's a phrase, and what's a phrase match? A: A phrase is a string of dictionary words in a pname property, possibly containing operators. More than one phrase can appear in a single pname property if they are separated by the '.p' phrase separator operator. A phrase match results when the words input by the player match one of the phrases specified in a pname property. If there is a phrase match, the object receives a bonus during disambiguation. Q: Is pname.h Glulx compatible? In other words, Can I use pname.h in an Inform program designed to be compiled for the new Glulx virtual machine? A: Yes. Q: OK. I'm convinced that pname.h will make my life easier. But what are the disadvantages of using pname.h in my program, if any? A: The biggest disadvantage is that pname.h replaces several important routines that are integral to the Inform Library. You are effectively locked into using a specific Library version with pname.h, and any modifications you have made to those routines in your copy of the Library will be overridden by pname.h. This version of pname.h is designed for the Library version shown at the head of this file, and is very likely to be incompatible with past and future versions. A smaller disadvantage is that pname.h doesn't quite live up to its promise of obviating parse_name routines. You will probably still need to write a few of them; see the TECHNICAL NOTES section below. An even smaller disadvantage is that it uses up one of Inform's limited stock of object attributes. --------------------------------------------------------------------------- OPERATORS The pname property takes a list of dictionary words in single quotes, in exactly the same manner as name. The primary difference is that some of those words can be the pname operators '.p', '.or', and '.x' which are defined here. '.p' phrase separator operator Used to separate phrase declarations in a pname property. Everything after it and up to the end of the property or the next phrase separator is interpreted as a single phrase. All pname properties begin with an implied '.p' if no phrase separator is provided. Using this operator, you can declare more than one phrase for the same object. For example: pname 'old' 'brass' 'lantern' '.p' 'shining' 'light' defines two phrases: 'old' 'brass' 'lantern' and 'shining' 'light'. It would generate phrase matches for the inputs OLD BRASS LANTERN and SHINING LIGHT, but not for BRASS LIGHT or SHINING LANTERN. '.or' or operator A binary operator used in phrases to show that certain words in the phrase might be substituted for other words. For example: pname 'soda' '.or' 'pop' 'machine' would generate phrase matches for the inputs SODA MACHINE and POP MACHINE. You can string together as many words as you like with this operator. For example: pname 'soda' '.or' 'pop' '.or' 'bubbly' '.or' 'coke' 'machine' A phrase match would then result from all of the following inputs: SODA MACHINE, POP MACHINE, BUBBLY MACHINE and COKE MACHINE. But there would be no phrase match for any of: MACHINE, SODA SODA MACHINE, SODA POP MACHINE, SODA BUBBLY MACHINE, MACHINE SODA or COKE. '.x' optional operator A unary prefix operator, which introduces a dictionary word that is optional in a phrase. The first dictionary word to the right of a '.x' operator is interpreted as optional. For example: pname 'soda' '.x' 'machine' 'button' denotes that the word 'machine' is optional in the above phrase. It would generate a phrase match for the inputs SODA MACHINE BUTTON and SODA BUTTON. There would be now match with MACHINE BUTTON, because 'soda' is not marked as optional. You can string together as many optional words as you like; all input words that match any of the words in the string of options will be matched, in any order. For example: pname '.x' 'black' '.x' 'swimming' 'trunks' This would generate a phrase match for all of the following inputs: TRUNKS, BLACK TRUNKS, BLACK SWIMMING TRUNKS, SWIMMING TRUNKS, SWIMMING BLACK TRUNKS and SWIMMING SWIMMING BLACK BLACK SWIMMING TRUNKS. No phrase match results from any of: BLACK, SWIMMING or TREE TRUNKS. A pname property that contained all optional words would act just like a standard name property. --------------------------------------------------------------------------- PARSING The pname.h parser counts the number of words in the input that appear in the pname property of the given object. It also records whether or not the input happens to match any of the phrases specified for the object. If the number of total words that match is equal to the longest possible phrase match, then the object is marked as having matched a phrase in the input. An object with a name property is treated as if it were a pname property in which all the words are optional -- so every match results in a phrase match. If an object has both a name property and a pname property, pname effectively masks the existence of the name property from the parser. The same is true for parse_name routines. If you have a parse_name routine on an object with a pname property, the parse_name will not be called during parsing. Next, during an early phase of Inform's disambiguation process, from all the objects that match at least one word in the input, only the ones that match the most consecutive words in the input are retained. Finally, among the objects that matched the most words, only the ones that generated a phrase match are retained (unless none of them generated a phrase match, in which case they are all retained). Thus, it's possible for an object that generates no phrase matches to be selected as the most likely. In the coffee table example in the Q&A section above, when the coffee was not in scope and the player specified only COFFEE, even though the single word COFFEE does not produce a phrase match for the coffee table, the coffee table is still deemed the most likely object by the parser because it matched a word in the input. Here's a longer example and a more detailed explanation. The starting location of _Uncle Zebulon's Will_ by Magnus Olsson has some troubling parsing problems. There's a garden, a garden path, and a garden shed all in scope at once. Using pname phrases, you can solve the problem by making 'garden' optional for the garden path and the garden shed: Object garden "garden" with name 'garden', description "The garden...", ... ; Object path "garden path" with pname '.x' 'garden' 'path', description "The path...", ... ; Object shed "garden shed" with pname '.x' 'garden' 'shed', description "The shed...", ... ; The following table shows phrase matches and word matches for several possible inputs and explains which object results. Words Input Object Matched Phrase match? ----------- ------- ------- ------------------------ GARDEN garden: 1 yes path: 1 no shed: 1 no ------------------- result: garden SHED garden: 0 no path: 0 no shed: 1 no ------------------- result: shed GARDEN SHED garden: 1 yes path: 0 no shed: 2 yes ------------------- result: shed [it matched the most words - on that basis, it would have won even if it had not generated a phrase match] PATH garden: 0 no path: 1 yes shed: 0 no ------------------- result: path GARDEN PATH garden: 1 yes path: 2 yes shed: 1 no ------------------- result: path --------------------------------------------------------------------------- TECHNICAL NOTES I recommend you use only the latest version of the Inform Library. You may use either the standard version by Graham Nelson or Andrew Plotkin's cross-platform port for compiling Glulx files. The pname parser considers as indistinguishable any two objects that have equivalent name properties and duplicate pname properties. To be indistinguishable, the name property of the two objects must be equivalent: every word in one must appear somewhere in the other (See Nelson, Graham: _The Inform Designer's Manual_, 3rd Ed, Section 25). pname properties must be identical. The pname property is additive. That means that pname properties inherit the pname property of their parent class. The way this works in practice is: the pname properties of the instance and its parent classes are concatenated into a list and that list is assigned to the instance as its pname property. When a name property is created through inheritance, the order in which the properties are concatenated doesn't matter. However, since the order of the words in a pname property is important, you need to understand the order of inheritance. Inheritance start with the instance and works its way back up through its parent classes. Class Rod with pname 'rod' '.or' 'wand'; Rod black_rod with pname '.x' 'black; Rod blue_rod with pname '.x' 'blue'; After compilation, the black rod's pname property is '.x' 'black' 'rod' '.or' 'wand' and the blue rod's is '.x' 'blue' 'rod' '.or' 'wand'. For multiple inheritance, the order in which the list is created is equivalent to the order the classes are declared in the class clause of the inheriting object. Class Rod with pname 'rod'; Class Wand with pname 'wand'; Object black_rod class Rod Wand with pname '.x' 'black'; In this case the pname property of the black_rod is '.x' 'black' 'rod' 'wand' which is probably not what you wanted! You have to be careful. If you don't want pname properties of Class objects to have a chance of interfering with pname properties of its intances, you can include a phrase separator operator in the declaration. Class Rod with pname '.p' 'rod'; Class Wand with pname '.p' 'wand'; Object black_rod class Rod Wand with pname 'black'; The black_rod, after compilation, will have a pname property of 'black' '.p' 'rod' '.p' 'wand', in other words, a pname property which contains three one-word phrases. If a class contains a name property then it will be masked by the existence of any instances that contain a pname property. pname_verify will print warnings in this case (see DEBUGGING). You may use plural flagged dictionary words in your pname properties, and they will be recognized by the pname parser. A plural dictionary word is defined with a //p on the end (for example, 'dogs//p'). If the parser sees one, it knows that the player may be referring to more than one object. (See: Nelson, Section 25.) There are some uses for parse_name routines that pname.h doesn't cover. A parse_name must be used to dynamically change the name of an object during the course of a game. In addition, a parse_name routine may be needed by a class of similar objects in order to be explicit about what is indistinguishable and what isn't. As noted in the PARSING section above, do not try to have a parse_name and a pname in the same object. They do not coexist happily. --------------------------------------------------------------------------- DEBUGGING This package contains a useful set of debugging diagnostic statements for times when thorny parsing issues arise (they were also of great help while debugging this package!); these are compiled only if DEBUG is defined. The parser trace level must be set to 7 or higher for full phrase parsing diagnostics to print (See: Nelson, Section 30), although trace level 5 is enough to show which objects produced phrase matches. Due to speed and algorithmic simplicity concerns, pname.h does not do error checking for bad pname declarations during parsing. To ameliorate this shortcoming, pname.h provides a pname_verify routine. When DEBUG is defined, you may call pname_verify() in your Initialise() routine to verify the pname properties in your objects. Here's what I suggest: [ Initialise; #ifdef DEBUG; pname_verify(); #endif; ! etc... ]; pname_verify loops over all the game objects and reports errors and warnings for pname properties it finds suspect. The game is aborted if any errors are reported. pname_verify report a warning if it finds 'x', 'p', or 'or' in a pname property, since they are most likely typos for '.x', '.p' and '.or', respectively. pname_verify also reports a warning for objects with pname property and a name or parse_name property, because a pname property masks both the parse_name and name properties from the parser. You can call pname_verify with 'true' as its argument to suppress these warning messages: pname_verify(true); ! suppress warnings --------------------------------------------------------------------------- RESERVED WORDS In addition to the identifiers reserved by Inform and the standard Library, pname.h defines the following. You mustn't use any of the following words in a program that Includes pname.h, except as documented here. Globals: matches_in_match_list Constants: PHRASE_OP '.p' OR_OP '.or' OPT_OP '.x' You may use any of these constants in your program but you must not try to define them yourself. Routines: _pn_pname _pn_matchPhrase _pn_inpWord _pn_inpLen _pn_TryGivenObject additionally, if DEBUG is defined: pname_verify _pn_printInpWord _pn_printPhrase _pn_isOp _pn_error _pn_warning You shouldn't call any of the above routines in your program except for pname_verify. Attributes: phrase_matched This is used internally by the pname parser to mark objects for which a phrase match has been detected. Standard Library routines: MakeMatch Identical NounDomain TryGivenObject These Library routines are replaced in pname.h so don't try to replace them yourself. If you want to hack one of these routine in a program that includes pname.h you will need to hack pname.h instead. --------------------------------------------------------------------------- DISTRIBUTION You may use the header file pname.h in any Inform program. You may distribute source code which uses pname.h, but you may not distribute pname.h with your source code except as described below. The header file pname.h itself may only be distributed if this documentation file, pname.txt, is included and pname.h is not modified in any way. This documentation file, 'pname.txt' may not be altered without the permission of the author, Neil Cerutti , except if the contents remain unchanged. It is permissible to adapt it to a different file format, e.g., HTML, PDF, PS, however and I don't consider such adaptation to be an alteration. You may distribute compiled game files which include pname.h. You may also distribute compiled game files which include an altered version of pname.h. --------------------------------------------------------------------------- NO WARRANTY Because this software is distributed without charge, you assume the entire responsibility for determining whether the program fits your needs and whether it is correct and/or complete. Neil Cerutti, and any distributors of this software specifically disclaim any and all warranties, expressed or implied, including but not limited to implied warranties of merchantability and fitness for a particular purpose, with regard to this software. In no event will the author or any distributor of this software be liable to you for any damages, including lost profits, lost savings, or other incidental or consequential damages arising out of the use or inability to use this software, even if any of these parties has been advised of the possibility of such damages, or for any claim by any other party. --------------------------------------------------------------------------- SPECIAL THANKS Thanks to Roger Firth who submitted an unsolicited re-organization of this file that helped transform it from a specification into documentation. His rewrites were invaluable in writing this documentation. Thanks to Marnie Parker and David Cornelson, who both looked at very early drafts of this document and gave good advice and asked good questions, which helped streamline and clarify the design of pname.h, which was originally much more complex. Thanks to Andrew Plotkin for donating the code for the cross-platform (Z and Glulx) versions of Identical, TryGivenObject, MakeMatch and ParseNoun from his cross-platform port of Inform Library 6/10. --------------------------------------------------------------------------- VERSION HISTORY 1.0 18 April 2001 Initial release 1.1 10 May 2001 o Fixed bug that caused to the parser to never generate a phrase match for a phrase in which an optional word was followed by the same consecutive word, or in an '.or' clause, e.g., '.x' 'card' 'card'. The phrase '.x' 'card' 'card' will now generate a 1 word phrase match for the input CARD and an N word phrase match for input containing N instances of the word CARD, i.e., CARD CARD CARD CARD would cause a 4 word phrase match.