Extended Parser for CoffeeMud 4.7.x
----------------------------------------------------------------------------

Included in this package is a patch to allow users of the CoffeMud code base
to enter much more english like commands than are normally supported by the
typical mud.  The system included herein is easily extensible, but includes
the following capabilities by default:

Feature: The ability to use english words to denote a particular item among
         others with the same name.
Example: get first sword
         get fifth axe

Feature: The ability to use an alternative numeric shortcut (#) to denote a
         particular item among others with the same name.
Example: get #2sword
Example: get sword#2
         
Feature: The ability to use shortcuts for common commands is already included
         in the codebase, but this extended parser allows those shortcuts to
         be used in conjunction with the other extended parser features.
Example: g first sword
         ea pie

Feature: The ability to substitute certain english synonyms for command 
         words, such as "open up <container>" for "open <container>" and 
         "place" for "put"
Example: place sword sack 
         open up chest
        
Feature: The ability to use english qualifiers with common commands
Example: look in sack
         look inside sack
         look at sword
         put sword inside sack
         put sword in sack

Feature: The ability to include extraneous words when issueing commands on 
         exits (my answer to non-sequential exit handling)
Example: open door east
         close west gate
         look at the west door

Feature: The ability to combine certain commands into a single sentence when
         the "and" conjunction is specified. (This is very cool -- B.Z.)
Example: get sword and wield sword
         get helmet and wear it
         get axe from sack and put it in chest

Feature: The ability to issue commands against N target items, so long as 
         the syntax does not violate that of the basic command.  For 
         instance, the command GET 1.<item1> 2.<item2>, according to basic
         syntax, means get the first item1 from the second container item2.
         For this reason, if you want to use GET to target multiple items,
         you would need to use commas or the and conjunction to specify that
         you are not trying to target a container.  Using the "from" keyword
         also solves this problem.
Example: get 1.sword 2.axe 3.lan
Example: wear sword, axe, lantern
Example: open chest and sack and window
Example: close chest, sack, and window
Example: get 1.sword 2.axe, sack, and lantern
Example: get 1.sword 2.axe, dagger, and lantern from sack

Feature: The ability to specify extraneous articles when naming items without
         losing the ability of the parser to find the item.
Example: get the sword, and that axe
Example: eat a pie

Feature: The ability to combine all the above capabilities to create rather
         complex sentences.
Example: place the 1.sword, my third axe, and a lantern in my second sack
Example: get my third pie and eat it

Methods
----------------------------------------------------------------------------

Just in case you are curious, this patch is implemented using one self
contained library class "ExtendedParser", a parsing definitions file 
"extended_parser.properties", and exactly one (1) line changed in the base
code in order to hook in the new library.

The library class is documented for those who want to understand how it
works.  However, it is simple enough to explain.  The library reads in the
parsing definitions and compiles a series of regular expressions, pairing
each with a replacement string.  Whenever the player enters a command, the
library iterates through the regular expressions list looking for matches. 
When a match is found, the replacement string is applied to the users command.
If the resulting string or strings should prove shorter than the original
string, the same regular expression is tried again.  If the expression does not
match, or if a resulting string is longer or the same length as the original 
string, the library will proceed to the next regular expression in the list.  
This rule of length is applied to prevent accidental lock-ups, should you 
decide to expand your extended_parser.properties definitions and make an error.

The syntax for the extended_parser.properties file is documented inside that
file.  The reguar expressions format is as dictated by the rules of Java
Regular Expressions.  You can find information on that syntax at the following
URL:
http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html

Installation Requirements
----------------------------------------------------------------------------

This patch has been successfully tested with the CoffeeMud code base, 
versions 4.7.1, 4.7.6, and 4.7.13.  This patch may work with older
versions as well, but I could only do so much testing, and I havn't seen
anyone running 4.5 or older builds in quite awhile.  

If you plan to try the patch with any version other than 4.7.6, or you have
already rebuilt 4.7.6, you will also need the Java JDK (or J2SDK or JSDK) 
version 1.4 or better.  You will need this to compile the patch for versions
other than 4.7.6 with official distributed class files.

Installation
----------------------------------------------------------------------------

If you are installing this patch for version 4.7.6 with official distributed
class files, you should follow the instructions below:
1. copy the file 476built/ExtendedParser.class to com/planet_ink/coffee_mud/utils
2. copy 2 files 476built/TelnetSession*.class  to com/planet_ink/coffee_mud/system
3. copy the file extended_parser.properties to resources directory
4. Reboot your mud and play around with the new features

For everyone else, you must follow these instructions:
1. copy the file extended_parser.properties to resources directory
2. copy the file ExtendedParser.java to com/planet_ink/coffee_mud/utils
3. From your base CoffeeMud directory, compile the above with a 
   command similar to this one:
MY_JDK_DIR/bin/javac com/planet_ink/coffee_mud/utils/ExtendedParser.java
4. Open the file com/planet_ink/coffee_mud/system/TelnetSession.java into a text
   editor.  We will need to "hook" in our library to the codebase now.
5. Utilitizing the text editors search feature, find the string:
mob.enqueCommand(CMDS,0);
   There is only one such line in the file, and it should be in the 900s.
6. Replace the above string with:
ExtendedParser.queExtendedCommands(mob, CMDS);
   A copy of this file from version 4.7.6, already changed, is in the changed
   directory of this package.  While that file will only work with version 4.7.6,
   in can be used as an example if you have problems.
7. Save your changes to TelnetSession.java
8. From your base CoffeeMud directory, compile the above with a 
   command similar to this one:
MY_JDK_DIR/bin/javac com/planet_ink/coffee_mud/system/TelnetSession.java
9. Reboot your mud and play around with the new features



