Added the apropos command for broader help searching (uses icontains).

The suggestions: footer used in help gave too narrow results, now using apropos-style search instead.
Bug fix of state-help command to make it accept switches.
Added several new example commands and cleaned up old ones to be more user-friendly.
Added protection in @delevent to make it harder to delete system events.
Some small bug fixes and other cleanup.

game/gamesrc/commands/examples/example.py

@@ -30,10 +30,10 @@ def cmd_example(command):
     example - example command
 
     Usage:
-      example[/switches] <text>
+      @testcommand[/switches] <text>
 
     switches:
-      use any string 
+      (can be any string, e.g. /test1 or /tom/sarah/peter)
 
     This is the help text for the 'example' command, a command to
     show how the pluggable command system works.
@@ -70,17 +70,34 @@ def cmd_example(command):
     # 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
+    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
+
+    # Some more info for more advanced commands.
+    if not command.command_switches and \
+           command.command_argument:
+        retval += "\n Obs: When no switches, also multi-word\n"
+        retval += " command names are possible. Max allowed\n"
+        retval += " length is set in game/settings.py.\n"
+        retval += " So if there exist a matching command in the\n"
+        retval += " command table, Evennia would also allow\n"
+        retval += " the following as valid commands (and the\n"
+        retval += " argument list would shrink accordingly):\n"
+        multi = ""
+        for arg in command.command_argument.split():
+            multi += " %s" % arg
+            retval += "   %s%s\n" % (command.command_string, multi)
+
+    # send string to player
     command.source_object.emit_to(retval)
 
 # Add the command to the common global command table. Note that
 # this will auto-create help entries 'example' and
 # "example_auto_help" for us.
-GLOBAL_CMD_TABLE.add_command("example", cmd_example)
+GLOBAL_CMD_TABLE.add_command("@testcommand", cmd_example)
 
 #
 # another simple example

game/gamesrc/commands/examples/misc_tests.py

@@ -0,0 +1,135 @@
+"""
+This module contains various commands for testing some
+of Evennia's subsystems. They were used for initial testing
+but are also instructive for playing around with to learn
+how different systems work. See also state_example.py. 
+
+To make these commands available in-game, add this module
+to the CUSTOM_COMMAND_MODULES tuple in game/settings.py
+as 'game.gamesrc.commands.examples.misc_tests'. 
+
+None of these commands are auto-added to the help database
+(they have no docstrings) in order to help make it clean. 
+"""
+from src.cmdtable import GLOBAL_CMD_TABLE
+
+#------------------------------------------------------------
+# Tests of the event system 
+#------------------------------------------------------------
+
+def cmd_testevent(command):
+    #
+    # This test allows testing the event system 
+    #
+    # Usage:
+    #   @testevent [pid]
+    #
+    # Without argument, this command creates
+    # a dummy event in the process table.
+    # Use @ps to see it. Give the equivalent
+    # pid to remove it again (careful though,
+    # this command can also remove useful
+    # events if you give the wrong pid).
+    # 
+    from src import events
+    from src import scheduler
+
+    source_object = command.source_object
+
+    if not source_object.is_superuser():
+        # To avoid accidental access to process table
+        source_object.emit_to("This command is superuser only.")
+        return 
+
+    if not command.command_argument:
+        # No argument given; create a new test event. 
+        event = events.IntervalEvent()
+        event.description = "Test event created with @testevent."
+        event.repeats = 3
+        event.interval = 5
+        pid = scheduler.add_event(event)
+        string = "Event with pid %s added. " % pid
+        string += "It repeats %i times and waits " % event.repeats
+        string += "for %i seconds between each repeat." % event.interval
+        string += "After all repeats, it will delete itself."
+        string += "\nUse @ps to see it and give this "
+        string += "command with the pid as argument to delete it."
+        source_object.emit_to(string)
+    else:
+        # An argument given; assume this is a pid. 
+        try:
+            pid = int(command.command_argument)
+        except:
+            source_object.emit_to("Not a valid argument. You must give a number.")
+            return 
+        if pid < 3:
+            string = "This low pid might belong to a system process, \n"
+            string += "so as a safety measure you cannot delete it using \n"
+            string += "this test command. Use @delevent instead."
+            source_object.emit_to(string)
+            return 
+        pid = command.command_argument
+        scheduler.del_event(pid)
+        string = "Event with pid %s removed (if it existed)." % pid
+        string += " Confirm this worked using @ps."
+        source_object.emit_to(string)
+GLOBAL_CMD_TABLE.add_command("@testevent", cmd_testevent,
+                             auto_help_override=False)    
+
+
+#------------------------------------------------------------
+# Test of Cache system
+#------------------------------------------------------------
+
+def cmd_testcache(command):    
+    #
+    # Tests the cache system by writing to it
+    # back and forth several times.
+    # 
+    # Usage: 
+    #    @testcache [get]
+    #
+    # Use without 'get' to store test data in
+    # caches and with 'get' to read them back
+    # and make sure they all saved as they
+    # should. You might also want to
+    # try shut down the server between
+    # calls to make sure the persistent
+    # cache does survive the shutdown. 
+
+    from src.cache import cache
+    from src import gametime
+
+    source_object = command.source_object
+    switches = command.command_switches
+
+    s1 = "Value: Cache: OK"
+    s2 = "Value: PCache 1 (set using property assignment): OK"
+    s3 = "Value: PCache 2 (set using function call): OK"
+    if switches and "get" in switches:
+        # Reading from cache
+        source_object.emit_to("Reading from cache ...")
+        cache.load_pcache()
+        cache_vol = source_object.cache.testcache        
+        source_object.emit_to("< volatile cache:\n  %s" % cache_vol)
+        cache_perm = source_object.pcache.testcache_perm
+        source_object.emit_to("< persistent cache 1/2:\n  %s" % cache_perm)
+        cache_perm2 = cache.get_pcache("permtest2")
+        source_object.emit_to("< persistent cache 2/2:\n  %s" % cache_perm2)
+    else:
+        # Saving to cache
+        source_object.emit_to("Save to cache ...")
+        source_object.cache.testcache = s1
+        # using two different ways to set pcache
+        source_object.pcache.testcache_perm = s2
+        cache.set_pcache("permtest2", s3)
+
+        source_object.emit_to("> volatile cache:\n  %s" % s1)
+        source_object.emit_to("> persistent cache 1/2:\n  %s" % s2)
+        source_object.emit_to("> persistent cache 2/2:\n  %s" % s3)
+        cache.save_pcache()
+        string = "Caches saved. Use /get as a switch to read them back."
+        source_object.emit_to(string)
+    source_object.emit_to("Running Gametime: %i" % gametime.time())
+GLOBAL_CMD_TABLE.add_command("@testcache", cmd_testcache,
+                             auto_help_override=False)   

game/gamesrc/commands/examples/state_example.py

@@ -15,7 +15,7 @@ files are recognized.
 
 Next enter the mud and give the command
 
-> entermenu
+> @testmenu
 
 Note that the help entries related to this little menu are not part of
 the normal help database, they are stored with the state and only
@@ -25,10 +25,12 @@ in action.
 
 To further test the state system, try the command
 
-> enterstate
+> @teststate
 
 This takes arguments between 1-6 to set up various states with varying
 access to different global commands.
+
+See also misc_tests.py for other tests.
 """
 
 # This is the normal command table, accessible by default
@@ -54,7 +56,7 @@ STATENAME = 'menu'
 def cmd_entermenu(command):
     """
     entermenu - enter the example menu
-
+    
     Usage:
       entermenu 
     
@@ -144,7 +146,8 @@ def print_menu(source_obj, choice=None):
     source_obj.emit_to(string)
 
 # Add the 'entry' command to the normal command table
-GLOBAL_CMD_TABLE.add_command("entermenu", cmd_entermenu)
+GLOBAL_CMD_TABLE.add_command("@testmenu", cmd_entermenu,
+                             auto_help_override=False)
 
 # create the state. We make sure the player can exit it at
 # any time by @exit. 
@@ -182,11 +185,11 @@ TSTATE6 = 'noglobal_allow_exits_obj_cmds'
 #
 def cmd_test_state(command):
     """
-    enterstate - testing the state system
+    @teststate - testing the state system
 
-    Usage: enterstate [1 - 6]
+    Usage: @teststate [1 - 6]
 
-    Give arguments 1..6 to enter different game states. Use @exit to
+    Give arguments 1-6 to enter different game states. Use @exit to
     get out of the state at any time.
 
     1: A very limited state; only contains the 'test' state command.
@@ -202,13 +205,13 @@ def cmd_test_state(command):
        both traverse exits and use object-based cmds.
 
     Ideas for in-game use:
-    1: Try out the 'entermenu' command for an example of this state.
+    1: Try out the '@testmenu' command for an example of this state.
     2: Could be used in order to stop someone from moving despite exits
        being open (tied up? In combat?)
     3: someone incapacitated or blinded might get only limited commands
        available
     4: in e.g. a combat state, things like crafting should not be
-       possible
+       possible.
     5: Pretty much default operation, just removing some global commands.
        Maybe limiting the use of magical weapons in a room or similar. 
     6: A state of panic - You can move, but not take in your surroundings.
@@ -219,7 +222,7 @@ def cmd_test_state(command):
     args = command.command_argument
     # check for missing arguments
     if not args:
-        source_object.emit_to("Usage: enterstate  [1 - 6]")
+        source_object.emit_to("Usage: @teststate [1 - 6]")
         return
     # build up a return string 
     string = "\n Entering state ... \nThis state includes the"
@@ -325,6 +328,6 @@ GLOBAL_STATE_TABLE.add_command(TSTATE5, 'test', cmd_instate_cmd)
 GLOBAL_STATE_TABLE.add_command(TSTATE6, 'test', cmd_instate_cmd)
 
 #create the entry function for testing all states
-GLOBAL_CMD_TABLE.add_command('enterstate', cmd_test_state)
+GLOBAL_CMD_TABLE.add_command('@teststate', cmd_test_state)