Added help for stash-search (dpeg).

git-svn-id: https://crawl-ref.svn.sourceforge.net/svnroot/crawl-ref/trunk@3338 c06c8d41-db1a-0410-9941-cceddc491573

10 files changed, 225 insertions, 90 deletions

diff --git a/crawl-ref/source/cio.cc b/crawl-ref/source/cio.cc
index f51b3a49bd..526c4d07b2 100644
--- a/crawl-ref/source/cio.cc
+++ b/crawl-ref/source/cio.cc
@@ -302,6 +302,10 @@ line_reader::line_reader(char *buf, size_t sz, int wrap)
 {
 }
 
+line_reader::~line_reader()
+{
+}
+
 std::string line_reader::get_text() const
 {
     return (buffer);
diff --git a/crawl-ref/source/cio.h b/crawl-ref/source/cio.h
index 75e9ca048d..f0a0c2afa3 100644
--- a/crawl-ref/source/cio.h
+++ b/crawl-ref/source/cio.h
@@ -219,6 +219,7 @@ class line_reader
 public:
     line_reader(char *buffer, size_t bufsz, 
                 int wrap_col = get_number_of_cols());
+    virtual ~line_reader();
 
     typedef int (*keyproc)(int &key);
 
@@ -231,14 +232,14 @@ public:
 
 protected:
     void cursorto(int newcpos);
-    int process_key(int ch);
+    virtual int process_key(int ch);
     void backspace();
     void killword();
     void kill_to_begin();
 
     bool is_wordchar(int c);
 
-private:
+protected:
     char            *buffer;
     size_t          bufsz;
     input_history   *history;
diff --git a/crawl-ref/source/command.cc b/crawl-ref/source/command.cc
index 426e5c7d5d..cb9ec35c6f 100644
--- a/crawl-ref/source/command.cc
+++ b/crawl-ref/source/command.cc
@@ -557,30 +557,6 @@ static bool cmdhelp_textfilter(const std::string &tag)
     return (false);
 }
 
-static const char *level_map_help = 
-    "<h>Level Map ('<w>X</w><h>' in main screen):\n"
-    "<w>Esc</w> : leave level map (also Space)\n"
-    "<w>Dir.</w>: move cursor\n"
-    "<w>/ Dir.</w>, <w>Shift-Dir.</w>: move cursor far\n"
-    "<w>-</w>/<w>+</w> : scroll level map up/down\n"
-    "<w>.</w>   : travel (also <w>Enter</w> and <w>,</w> and <w>;</w>)\n"
-    "       (moves cursor to last travel\n"
-    "       destination if still on @)\n"
-    "<w><<</w>/<w>></w> : cycle through up/down stairs\n"
-    "<w>^</w>   : cycle through traps\n"
-    "<w>Tab</w> : cycle through shops and portals\n"
-    "<w>X</w>   : cycle through travel eXclusions\n"
-    "<w>x</w>   : change the radius of a travel exclusion\n"
-    "<w>W</w>   : cycle through waypoints\n"
-    "<w>*</w>   : cycle forward through stashes\n"
-    "<w>/</w>   : cycle backward through stashes\n"
-    "<w>_</w>   : cycle through altars\n"
-    "<w>Ctrl-X</w> : set travel eXclusion\n"
-    "<w>Ctrl-E</w> : Erase all travel exclusions\n"
-    "<w>Ctrl-W</w> : set Waypoint\n"
-    "<w>Ctrl-C</w> : Clear level and main maps\n"
-    "<w>Ctrl-F</w> : Forget level map\n";
-
 static const char *targeting_help_1 =
     "<h>Examine surroundings ('<w>x</w><h>' in main):\n"
     "<w>Esc</w> : cancel (also <w>Space</w>)\n"
@@ -620,32 +596,6 @@ static const char *targeting_help_2 =
     "<w>Ctrl-N</w> : cycle to next missile.\n";
     
 
-static const char *interlevel_travel_branch_help =
-    "<h>Interlevel Travel (choose a branch):\n"
-    " Use the shortcut letter for a branch to select the branch for travel.\n"
-    "\n"
-    " Once you select a branch, you will be prompted for a depth in that\n"
-    " branch (more help is available there).\n"
-    "\n"
-   " <w>Enter</w>  : Repeat last interlevel travel.\n"
-    " <w>.</w>      : Travel to a level in the current branch.\n"
-    " <w><<</w>      : Go up the nearest stairs.\n"
-    " <w>></w>      : Go down the nearest stairs.\n"
-    " <w>Ctrl-P</w> : Travel to a level in the branch above this one.\n"
-    " <w>*</w>      : Show available waypoints (if any are set).\n"
-    " <w>0</w>-<w>9</w>    : Go to the numbered waypoint.\n";
-
-static const char *interlevel_travel_depth_help =
-    "<h>Interlevel Travel (go to a specific level in the selected branch)\n"
-    " Type in the level number you want to go to and hit Enter, or use:\n"
-    " <w>Enter</w>  : Go to the default level.\n"
-    " <w><<</w>      : Change the default to one level above the current.\n"
-    " <w>></w>      : Change default to one level below the current.\n"
-    " <w>-</w>/<w>p</w>    : Change default to the branch above this one.\n"
-    " <w>$</w>      : Change default to deepest visited level in this branch.\n"
-    " <w>^</w>      : Change default to the entrance to the current level.\n"
-    "\n";
-
 // Add the contents of the file fp to the scroller menu m.
 // If first_hotkey is nonzero, that will be the hotkey for the
 // start of the contents of the file.
@@ -1469,7 +1419,7 @@ static void show_keyhelp_menu(const std::vector<formatted_string> &lines,
     cmd_help.show();
 }
 
-void show_specific_help( const char* help )
+void show_specific_help( const std::string &help )
 {
     std::vector<std::string> lines = split_string("\n", help, false, true);
     std::vector<formatted_string> formatted_lines;
@@ -1482,7 +1432,7 @@ void show_specific_help( const char* help )
 
 void show_levelmap_help()
 {
-    show_specific_help( level_map_help );
+    show_specific_help( getHelpString("level-map") );
 }
 
 void show_targeting_help()
@@ -1498,12 +1448,17 @@ void show_targeting_help()
 
 void show_interlevel_travel_branch_help()
 {
-    show_specific_help( interlevel_travel_branch_help );
+    show_specific_help( getHelpString("interlevel-travel.branch.prompt") );
 }
 
 void show_interlevel_travel_depth_help()
 {
-    show_specific_help( interlevel_travel_depth_help );
+    show_specific_help( getHelpString("interlevel-travel.depth.prompt") );
+}
+
+void show_stash_search_help()
+{
+    show_specific_help( getHelpString("stash-search.prompt") );
 }
 
 void list_commands(bool wizard, int hotkey, bool do_redraw_screen)
@@ -1532,8 +1487,8 @@ void list_commands(bool wizard, int hotkey, bool do_redraw_screen)
             "or vi keys:\n"
             "              <w>1 2 3      y k u\n"
             "               \\|/        \\|/\n"
-            "              <w>4</w>-5-<w>6</w>"
-                              "      <w>h</w>-.-<w>l</w>\n"
+            "              <w>4</w>-<w>5</w>-<w>6</w>"
+                    "      <w>h</w>-<w>.</w>-<w>l</w>\n"
             "               /|\\        /|\\\n"
             "              <w>7 8 9      b j n\n",
             true, true, cmdhelp_textfilter);
@@ -1619,7 +1574,10 @@ void list_commands(bool wizard, int hotkey, bool do_redraw_screen)
             "\n"
             "Searching in stashes allows regular\n"
             "expressions, and terms like 'altar'\n"
-            "or 'artefact' or 'long blades'.\n",
+            "or 'artefact' or 'long blades'.\n"
+            "\n"
+            "For more help on searching, you can\n"
+            "hit ? at the search prompt.\n",
             true, true, cmdhelp_textfilter);
 
     cols.add_formatted(
diff --git a/crawl-ref/source/command.h b/crawl-ref/source/command.h
index b64e4059d0..1ed6709f6e 100644
--- a/crawl-ref/source/command.h
+++ b/crawl-ref/source/command.h
@@ -62,6 +62,7 @@ void show_levelmap_help();
 void show_targeting_help();
 void show_interlevel_travel_branch_help();
 void show_interlevel_travel_depth_help();
+void show_stash_search_help();
 void list_commands(bool wizard, int hotkey = 0,
                    bool do_redraw_screen = false);
 void list_tutorial_help(void);
diff --git a/crawl-ref/source/dat/help.txt b/crawl-ref/source/dat/help.txt
new file mode 100644
index 0000000000..22b849aba5
--- /dev/null
+++ b/crawl-ref/source/dat/help.txt
@@ -0,0 +1,117 @@
+%%%%
+stash-search.prompt
+
+<h>Searching the stash-tracker</h>
+
+You can search for items and dungeon features by name (or a substring of the
+name). In the list of search results, you can select a search result by its
+hotkey to travel to its location.
+
+You can also examine shops and items in the search results by pressing <w>?</w>
+and then hitting the hotkey for the search result. This will show you a
+description of the item or the contents of the shop.
+
+Some examples of search strings:
+<w>cure mutation</w> find all potions of cure mutation, including potions
+              in shops.
+<w>cloak</w>         find all cloaks in the dungeon.
+<w>Lair:2</w>        find everything known to be on Lair:2.
+<w>Lair:[2-4]</w>    finds everything on Lair:2-4. Regexes are allowed! Note
+              that Lair:[3-10] will not work as intended, since [x-y] is
+              a regex character range.
+<w>.</w>             is a shortcut to find everything on your current level.
+<w>Lair.*axe</w> 
+or
+<w>axe && Lair</w>   both show all axes in the Lair.
+
+
+<h>Searching by item properties:</h>
+
+You can search for spell names (such as <w>Ignite Poison</w>) to find spellbooks
+or rods that contain the spell.
+
+You can search for artefact item properties (such as <w>prevents.*teleport</w>)
+to find artefacts that have the property.
+
+If you're using <w>stash.lua</w>, you can also search by some additional item
+properties:
+<w>artefact</w> will find identified artefacts.
+Skill names (such as <w>Polearms</w> or <w>Long Blades</w>) will find all
+weapons that train that skill.
+
+If you're using stash.lua and have set annotate_item_class = true in your
+init.txt, you can also search by item types such as <w>book</w> or
+<w>jewellery</w>.
+
+
+<h>Finding Dungeon Features:</h>
+
+You can search for dungeon features by name: all shops will be found by a search
+for <w>shop</w> (including shops that do not have "shop" in their name); other
+dungeon features can also be found by name: <w>fountain</w>, <w>axe trap</w>,
+<w>altar</w>, etc. You can also search for altars by deity name: <w>Zin</w>.
+
+
+The stash search string is case-insensitive.
+
+
+<h>Non-regex operators:</h>
+
+You can use !! to negate a search string, && for a boolean AND, || for
+boolean OR, and <<<< >> for grouping.
+
+For instance, to find rings (jewellery) but not ring mail you could use:
+<w>ring && !!mail</w>
+%%%%
+level-map
+
+<h>Level Map ('<w>X</w><h>' in main screen):
+<w>Esc</w> : leave level map (also Space)
+<w>Dir.</w>: move cursor
+<w>/ Dir.</w>, <w>Shift-Dir.</w>: move cursor far
+<w>-</w>/<w>+</w> : scroll level map up/down
+<w>.</w>   : travel (also <w>Enter</w> and <w>,</w> and <w>;</w>)
+       (moves cursor to last travel
+       destination if still on @)
+<w><<</w>/<w>></w> : cycle through up/down stairs
+<w>^</w>   : cycle through traps
+<w>Tab</w> : cycle through shops and portals
+<w>X</w>   : cycle through travel eXclusions
+<w>x</w>   : change the radius of a travel exclusion
+<w>W</w>   : cycle through waypoints
+<w>*</w>   : cycle forward through stashes
+<w>/</w>   : cycle backward through stashes
+<w>_</w>   : cycle through altars
+<w>Ctrl-X</w> : set travel eXclusion
+<w>Ctrl-E</w> : Erase all travel exclusions
+<w>Ctrl-W</w> : set Waypoint
+<w>Ctrl-C</w> : Clear level and main maps
+<w>Ctrl-F</w> : Forget level map
+%%%%
+interlevel-travel.branch.prompt
+
+<h>Interlevel Travel (choose a branch):
+ Use the shortcut letter for a branch to select the branch for travel.
+
+ Once you select a branch, you will be prompted for a depth in that
+ branch (more help is available there).
+
+ <w>Enter</w>  : Repeat last interlevel travel.
+ <w>.</w>      : Travel to a level in the current branch.
+ <w><<</w>      : Go up the nearest stairs.
+ <w>></w>      : Go down the nearest stairs.
+ <w>Ctrl-P</w> : Travel to a level in the branch above this one.
+ <w>*</w>      : Show available waypoints (if any are set).
+ <w>0</w>-<w>9</w>    : Go to the numbered waypoint.
+%%%%
+interlevel-travel.depth.prompt
+
+<h>Interlevel Travel (go to a specific level in the selected branch)
+ Type in the level number you want to go to and hit Enter, or use:
+ <w>Enter</w>  : Go to the default level.
+ <w><<</w>      : Change the default to one level above the current.
+ <w>></w>      : Change default to one level below the current.
+ <w>-</w>/<w>p</w>    : Change default to the branch above this one.
+ <w>$</w>      : Change default to deepest visited level in this branch.
+ <w>^</w>      : Change default to the entrance to the current level.
+%%%%
diff --git a/crawl-ref/source/database.cc b/crawl-ref/source/database.cc
index ff1b59bf2c..04accbd4f3 100644
--- a/crawl-ref/source/database.cc
+++ b/crawl-ref/source/database.cc
@@ -35,6 +35,7 @@ enum db_id
 {
     DB_SHOUT,
     DB_SPEAK,
+    DB_HELP,
     MAX_DBID
 };
 
@@ -50,7 +51,8 @@ struct SingleFileDB
 SingleFileDB singleFileDBs[MAX_DBID] = 
 {
     SingleFileDB("shout"),
-    SingleFileDB("speak")
+    SingleFileDB("speak"),
+    SingleFileDB("help")
 };
 
 #define DESC_BASE_NAME "descript"
@@ -233,10 +235,8 @@ static void execute_embedded_lua(std::string &str)
 
         if (clua.execstring(lua.c_str(), "db_embedded_lua", 1))
         {
-            std::string err = "{{" + clua.error;
-            err += "}}";
+            std::string err = "{{" + clua.error + "}}";
             str.replace(pos, lua_full.length(), err);
-
             return;
         }
 
@@ -249,11 +249,6 @@ static void execute_embedded_lua(std::string &str)
     } // while (pos != std::string::npos)
 }
 
-static void trim_right(std::string &s)
-{
-    s.erase(s.find_last_not_of(" \r\t\n") + 1);
-}
-
 static void trim_leading_newlines(std::string &s)
 {
     s.erase(0, s.find_first_not_of("\n"));
@@ -310,7 +305,7 @@ static void parse_text_db(std::ifstream &inf, DBM *db)
         else
         {
             std::string line = buf;
-            trim_right(line);
+            trim_string_right(line);
             value += line + "\n";
         }
     }
@@ -478,6 +473,27 @@ static std::string getRandomizedStr(DBM *database, const std::string &key,
     return str;
 }
 
+static std::string query_database(DBM *db, std::string key,
+                                  bool canonicalise_key, bool run_lua)
+{
+    if (canonicalise_key)
+    {
+        // We have to canonicalize the key (in case the user typed it
+        // in and got the case wrong.)
+        lowercase(key);
+    }
+    
+    // Query the DB.
+    datum result = database_fetch(db, key);
+    
+    std::string str((const char *)result.dptr, result.dsize);
+
+    if (run_lua)
+        execute_embedded_lua(str);
+    
+    return (str);
+}
+
 /////////////////////////////////////////////////////////////////////////////
 // Description DB specific functions.
 
@@ -486,19 +502,7 @@ std::string getLongDescription(const std::string &key)
     if (!descriptionDB)
         return ("");
 
-    // We have to canonicalize the key (in case the user typed it
-    // in and got the case wrong.)
-    std::string canonical_key = key;
-    lowercase(canonical_key);
-    
-    // Query the DB.
-    datum result = database_fetch(descriptionDB, canonical_key);
-    
-    // Cons up a (C++) string to return.  The caller must release it.
-    std::string str((const char *)result.dptr, result.dsize);
-
-    execute_embedded_lua(str);
-    return (str);
+    return query_database(descriptionDB, key, true, true);
 }
 
 std::vector<std::string> getLongDescKeysByRegex(const std::string &regex,
@@ -598,3 +602,10 @@ std::string getSpeakString(const std::string &monst)
     return getRandomizedStr(get_dbm(DB_SPEAK), monst, "", num_replacements); 
 }
 
+/////////////////////////////////////////////////////////////////////////////
+// Help DB specific functions.
+
+std::string getHelpString(const std::string &topic)
+{
+    return query_database(get_dbm(DB_HELP), topic, false, true);
+}
diff --git a/crawl-ref/source/database.h b/crawl-ref/source/database.h
index 09b90364ea..a23773c6ce 100644
--- a/crawl-ref/source/database.h
+++ b/crawl-ref/source/database.h
@@ -60,4 +60,6 @@ std::vector<std::string> getLongDescBodiesByRegex(const std::string &regex,
 std::string getShoutString(const std::string &monst,
                            const std::string &suffix = "");
 std::string getSpeakString(const std::string &monst);
+std::string getHelpString(const std::string &topic);
+
 #endif
diff --git a/crawl-ref/source/files.cc b/crawl-ref/source/files.cc
index eed436232c..c656e2f596 100644
--- a/crawl-ref/source/files.cc
+++ b/crawl-ref/source/files.cc
@@ -356,7 +356,7 @@ static bool create_dirs(const std::string &dir)
         if (!dir_exists(path) && create_directory(path.c_str()))
             return (false);
 
-        path += FILE_SEPARATOR;        
+        path += FILE_SEPARATOR;
     }
     return (true);
 }
diff --git a/crawl-ref/source/ouch.cc b/crawl-ref/source/ouch.cc
index e57f43ccc0..2d7d5b5348 100644
--- a/crawl-ref/source/ouch.cc
+++ b/crawl-ref/source/ouch.cc
@@ -859,7 +859,7 @@ void ouch( int dam, int death_source, kill_method_type death_type,
     // prevent bogus notes
     activate_notes(false);
 
-    // CONSTRUCT SCOREFILE ENTRY
+    // construct scorefile entry.
     scorefile_entry se(dam, death_source, death_type, aux);
 
 #ifdef SCORE_WIZARD_CHARACTERS
diff --git a/crawl-ref/source/stash.cc b/crawl-ref/source/stash.cc
index 815146bb95..6e002ca209 100644
--- a/crawl-ref/source/stash.cc
+++ b/crawl-ref/source/stash.cc
@@ -11,6 +11,7 @@
 #include "chardump.h"
 #include "cio.h"
 #include "clua.h"
+#include "command.h"
 #include "describe.h"
 #include "direct.h"
 #include "food.h"
@@ -1360,8 +1361,7 @@ void StashTracker::show_stash_search_prompt()
     if (level_type_is_stash_trackable(you.level_type)
         && lastsearch != ".")
     {
-        opts.push_back(
-            make_stringf("press . for all items on level"));
+        opts.push_back("? for help");
     }
 
     std::string prompt_qual =
@@ -1373,13 +1373,54 @@ void StashTracker::show_stash_search_prompt()
     mprf(MSGCH_PROMPT, "Search for what%s?\n", prompt_qual.c_str());
 }
 
+class stash_search_reader : public line_reader
+{
+public:
+    stash_search_reader(char *buf, size_t sz,
+                        int wcol = get_number_of_cols())
+        : line_reader(buf, sz, wcol)
+    {
+    }
+protected:
+    int process_key(int ch)
+    {
+        if (ch == '?' && !pos)
+        {
+            *buffer = 0;
+            return (ch);
+        }
+        return line_reader::process_key(ch);
+    }
+};
+
 void StashTracker::search_stashes()
 {
-    show_stash_search_prompt();
-    
     char buf[400];
-    bool validline = 
-        !cancelable_get_line(buf, sizeof buf, 80, &search_history);
+
+    stash_search_reader reader(buf, sizeof buf);
+
+    bool validline = false;
+    while (true)
+    {
+        show_stash_search_prompt();
+
+        int ret = reader.read_line();
+        if (!ret)
+        {
+            validline = true;
+            break;
+        }
+        else if (ret == '?')
+        {
+            show_stash_search_help();
+            redraw_screen();
+        }
+        else
+        {
+            break;
+        }
+    }
+    
     mesclr();
     if (!validline || (!*buf && !lastsearch.length()))
         return;