Created a state system. See

http://groups.google.com/group/evennia/browse_thread/thread/66a7ff6cce5303b7
for more detailed description.

Created a new folder gamesrc/commands/examples and moved all examples in there.
/Griatch

game/gamesrc/commands/examples/example.py

@@ -0,0 +1,96 @@
+"""
+This is an example command module for showing the pluggable command system
+in action. 
+
+You'll need to make sure that this or any new modules you create are added to
+game/settings.py under CUSTOM_COMMAND_MODULES or CUSTOM_UNLOGGED_COMMAND_MODULES,
+which are tuples of module import path strings. See src/config_defaults.py for more details.
+
+E.g. to add this example command for testing, your entry in game/settings.py would
+look like this:
+
+CUSTOM_COMMAND_MODULES = ('game.gamesrc.commands.examples.example',)
+
+(note the extra comma at the end to make this into a Python tuple. It's only
+needed if you have only one entry.) You need to restart the Evennia server before new
+files are recognized. 
+
+"""
+
+# This is the common global CommandTable object which we'll be adding the
+# example command to. We can add any number of commands this way in the
+# same file.
+from src.cmdtable import GLOBAL_CMD_TABLE
+
+def cmd_example(command):
+    """    
+    This is the help text for the 'example' command, a command to
+    show how the pluggable command system works.
+
+    For testing, you can try calling this with different switches and
+    arguments, like
+       > example/test/test2 Hello
+    and see what is returned.
+
+    <<TOPIC:example_auto_help>>
+
+    This is a subtopic to the main example command help entry.
+    
+    Note that this text is auto-added since auto_help=True
+    was set in the call to add_function. Any number of subtopics like
+    this one can be added on the fly using the auto-help system. See
+    help topics on 'help' and 'help_staff' for more information and
+    options.
+    """
+
+    # By building one big string and passing it at once, we cut down on a lot
+    # of emit_to() calls, which is generally a good idea.
+    retval = "----- Example Command -----\n\r"
+    # source_object is the object executing the command
+    retval += " Source object: %s\n\r" % command.source_object
+    # session points to a user Session (session.py) object (if applicable)
+    retval += " Session: %s\n\r" % command.session
+    # The raw, un-parsed input
+    retval += " Raw input: %s\n\r" % command.raw_input
+    # The command name being executed
+    retval += " Command: %s\n\r" % command.command_string
+    # A list of switches provided (if any)
+    retval += " Switches: %s\n\r" % command.command_switches
+    # A string with any arguments provided with the command
+    retval += " Arguments: %s\n\r" % command.command_argument
+    # The function that was looked up via cmdtable.py
+    retval += " Function: %s\n\r" % command.command_function
+    # Extra variables passed with cmdtable.py's add_command().
+    retval += " Extra vars: %s\n\r" % command.extra_vars
+    command.source_object.emit_to(retval)
+
+# Add the command to the common global command table. Note that
+# since auto_help=True, help entries named "example" and
+# "example_auto_help" (as defined in the __doc__ string) will
+# automatically be created for us.
+GLOBAL_CMD_TABLE.add_command("example", cmd_example, auto_help=True),
+
+#another simple example
+
+def cmd_emote_smile(command):
+    """
+    Simplistic 'smile' emote. 
+    """
+    #get the source object (that is, the player using the command)
+    caller = command.source_object
+    #find name of caller
+    name = caller.get_name(show_dbref=False)
+    #get the location caller is at
+    location = caller.get_location()
+    #build the emote
+    text = "%s smiles." % name
+    #emit the emote to everyone at the current location
+    location.emit_to_contents(text)
+
+#add to global command table (no auto_help activated)
+GLOBAL_CMD_TABLE.add_command('smile', cmd_emote_smile)
+
+
+
+
+

game/gamesrc/commands/examples/state_example.py

@@ -0,0 +1,112 @@
+"""
+Example of using the state system. The Event system allows a player object to be
+'trapped' in a special environment where different commands are available than normal.
+This is very useful in order to implement anything from menus to npc-conversational
+choices and inline text-editors. 
+
+This example uses the State system to create a simple menu. 
+
+To test out this example, add this module to the CUSTOM_COMMAND_MODULES tuple in
+your game/settings.py as 'game.gamesrc.commands.examples.state_example' (see ./example.py
+for another example). You need to restart the Evennia server before new files are
+recognized. 
+
+Next enter the mud and give the command
+> entermenu
+
+Note that the help entries added to the state system with the auto_help flag are NOT
+part of the normal help database, they are stored with the state and only accessible
+from inside it (unless you also set the 'global_help' flag in the add_command(), in
+which case it is also added to the global help system). If you want to describe the
+state itself in more detail you should add that to the main help index manually. 
+"""
+
+#This is the normal command table, accessible by default
+from src.cmdtable import GLOBAL_CMD_TABLE
+
+#The statetable contains sets of cmdtables that is made available
+#only when we are in a particular state, overriding the GLOBAL_CMD_TABLE
+from src.statetable import GLOBAL_STATE_TABLE
+
+#
+# Implementing a simple 'menu' state
+#
+
+#the name of our state, to make sure it's the same everywhere
+STATENAME = 'menu'
+
+
+#
+# 'entry' command
+#    
+def cmd_entermenu(command):
+    """
+    This is the 'entry' command that takes the player from the normal    
+    gameplay mode into the 'menu' state. In order to do this, it
+    must be added to the GLOBAL_CMD_TABLE like any command.
+    """
+    #get the player object calling the command    
+    source_object = command.source_object    
+    #this is important: we use the set_state() command
+    #to shift the player into a state named 'menu'.
+    source_object.set_state(STATENAME)
+    #display the menu.
+    print_menu(source_object)    
+
+#
+# Commands only available while in the 'menu' state. Note that
+#  these have auto_help, so the __doc__ strings of the functions
+#  can be read as help entries when in the menu. 
+#
+def menu_cmd_option1(command):
+    """option1
+    This selects the first option.
+    """
+    source_object = command.source_object
+    print_menu(source_object, 1)
+def menu_cmd_option2(command):
+    """option2
+    This selects the second option. Duh.
+
+    <<TOPIC:About>>
+    This is an extra topic to test the auto_help functionality.
+    """
+    source_object = command.source_object
+    print_menu(source_object, 2)
+def menu_cmd_clear(command):
+    """clear
+    Clears the options.  
+    """
+    source_object = command.source_object
+    print_menu(source_object)
+
+#
+# helper function
+#
+def print_menu(source_obj,choice=None):
+    """
+    Utility function to print the menu. More interesting things
+    would happen here in a real menu. 
+    """
+    if choice==1:
+        ch = "> option1\n  option2"
+    elif choice==2:
+        ch = "  option1\n> option2"
+    else:
+        ch = "  option1\n  option2"
+        
+    s ="Menu---------\n%s\n  help - get help" % ch
+    source_obj.emit_to(s)
+
+
+
+#Add the 'entry' command to the normal command table
+GLOBAL_CMD_TABLE.add_command("entermenu", cmd_entermenu)
+
+#Add the menu commands to the state table by tying them to the 'menu' state. It is
+#important that the name of the state matches what we set the player-object to in
+#the 'entry' command. Since auto_help is on, we will have help entries for all commands
+#while in the menu.
+GLOBAL_STATE_TABLE.add_command(STATENAME, "option1", menu_cmd_option1,auto_help=True)
+GLOBAL_STATE_TABLE.add_command(STATENAME, "option2", menu_cmd_option2,auto_help=True)
+GLOBAL_STATE_TABLE.add_command(STATENAME, "clear", menu_cmd_clear,auto_help=True)