Description and text parsing documentation.
AweMUD Next Generation
Copyright (C) 2004  AwesomePlay Productions, Inc.
Sean Middleditch <elanthis@awemud.net>
-------------------------------------------------

1. Introduction
   ============

   AweMUD features a text parsing system that is used for room descriptions
   and many other areas of the engine where complex output is required.

   The text parsing system is designed to allow several important features:
   - Provide the ability to display dynamic information.
   - Allow conditional output of text based on game state.
   - Be easy and intuitive to use.

   The parsing system uses simple commands to direct the engine as to
   what text should be output.  The syntax of the format is explained below.

2. Syntax
   ======

   The main format is just a chunk of text.  This chunk of text may be a
   single word, a sentence, a paragraph, or many paragraphs.  Text is
   simply output verbatim, unless a special escape character is encountered.

   The escape character is { (left curly bracket), and the command text
   continues until a matching } (right curly bracket) is encountered.  Thus,
   all commands are inside of {} pairs.

   In the most basic form a single command will be placed inside of the
   brackets.  For example, to get the server software's version, you would
   use enter the following in your block of text:

     {version}

   That's it.  Of course, that isn't very interesting.  Global commands
   can't take into account the local state of the text being output.  For
   that we have parameters.

   Parameters are a list of values that are accessible to the parse system.
   These parameters _may_ have names that make it easier to access them, but
   names may not always be given.  To output the value of a parameter, simply
   use either its parameter index or parameter name as the command.

   For example, if you are entering a room description, the room itself is
   the first parameter, and it is named 'room'.  Thus, to output the room
   (which is displayed as the room's title), you'd use one of the following:

     {1}
     {room}

   Again, not very complex.  Sometimes, however, you will want a lot more than
   just the name.  The room description might include a mirror in which the
   player can see themself.  The player viewing the room description is given
   as the second parameter, and named 'actor'.  You can access particular
   fields of a paramater by appending a . (dot) and the field name to
   parameter index or name in the escape.  To output the player's description
   in a room description, you'd use one of:

     {2.desc}
     {actor.desc}

   Also note that as a convenience you may ommit the parameter index/name
   for the first parameter when accessing a field.  For example, to get the
   unique ID of the room you could use:

     {.id}

   The final major feature (and the feature that is the less developed) is
   the conditional processing commands.  With conditional processing you can
   tell the parser to ignore a chunk of text based on the current game
   state.  For example, a room description might include some descriptions
   of the moonlight during the night, but include descriptions of rays of
   sunlight during the day.  Conditionals are handled using the if, elif,
   else, and end commands.  The if and elif commands are special in that
   they take additional information besides just the command name.  For
   example:

     {if day-or-night = 'day'}It is day.{elif day-or-night = 'night'}It
     is night.{else}Time has ended!{end}

   The first command begins with if, which indicates that it is a
   conditional.  The rest of the command text is broken into three parts:
   the first sub-command, an operator, and the second sub-command.  The
   two sub-commands are expanded just as any other command using the
   normal command rules.  (As an exception, sub-commands may not be
   conditional commands.)  The day-or-night command is explained in the
   appendix below.  It expands to either the text 'day' or the text
   'night' depending on the current day time.

   The operator specifies how the expanded text of the two sub-commands
   are compared.  In the example the equal (=) operator is used.  This
   operator tests if the two values are equal.

   You'll also notice the words 'day' and 'night' with the quotes around
   them.  The quotes tell the engine that the text should not be expanded.
   Without the quotes, the engine would look for a command named day or a
   command named night, and would return an error since no commands by those
   names exist.

   If a conditional command is true (the condition specified by the operator
   is true) then the following text and commands are output as usual.  If it
   is false, they are not output at all.  This state is retained until an
   elif, else, or end command is found.

   The end command is the simplest.  It means that the previous conditional
   is over and to always output text as normal.  (Unless you have nested
   conditionals; one conditional inside of another.  In that case, the state
   of the enclosing conditional is restored when the end command is found.)

   The else command is almost as simple.  It basically means to flip the
   value of the previous conditional.  For example, if your condition was
   true, it would be set to false when the else command is interpreted.  The
   else command will always set the state to false if the opening if or any
   elif commands were true, even if the previous one was false.

   The elif command is very similar to the if command.  You may have more
   than one elif command in a single conditional.  They are the union of
   the else command and the if command.  Basically, if the previous if and
   elif statements were all false, then the conditional in the elif command
   (using the same format as the if command) is used to set the state.  If
   a previous if or elif statement was false, then the elif is always false.

   Yes, that was an ugly explanation.  I'm a coder, not a documenter; deal
   with it.  ;-)

A. Global Commands
   ===============
   - version
     The version of the server software.
  
   - build
     The build date and time of the server binary.
  
   - uptime
     Time passed since the server was brought online.
     
   - player-count
     Number of currently active players.
     
   - day-or-night
     The text 'day' during game day time, and the text 'night' during game
    night time.
     
   - hostname
     The server's recognized hostname.
     
   - date
     The game date.
     
   - time
     The game time.
     
   - date-year
     Current game year.
     
   - date-month
     Current game month.
     
   - date-day
     Current game day of the month.
     
   - time-hours24
     Current game hour in 24-hour format.
     
   - time-hours12
     Current game hour in 12-hour format.
     
   - time-ampm
     The text 'am' during the AM hours, and the text 'pm' during the PM hours.
     
   - time-minutes
     Current approximated game minutes.
