Provide documentation for the regex engine.

The guidebook entries could do with more detailed descriptions, but this
will do for now.

DEVEL/code_features.txt

@@ -1,4 +1,4 @@
-$NHDT-Date: 1426969026 2015/03/21 20:17:06 $  $NHDT-Branch: master $:$NHDT-Revision: 1.137 $
+$NHDT-Date: 1432473678 2015/05/24 13:21:18 $  $NHDT-Branch: master $:$NHDT-Revision: 1.2 $
 code_features.txt
 
 Developer-useful info about code features, assumptions, purpose,
@@ -77,6 +77,29 @@ separation of:
 - sysadmin stuff from user-writeable stuff.
 etc.
 
+==============================================
+REGULAR EXPRESSIONS
+
+There are multiple regular expression libraries supported. Currently, one (and
+only one) of the following files should be linked into a built:
+  sys/share/cppregex.cpp
+  sys/share/posixregex.c
+  sys/share/pmatchregex.c
+
+This provides a way to access different system regular expression libraries,
+or fall back onto pmatch() if none is available. cppregex.cpp uses the regular
+expression library in the C++11 standard, and is the default on Windows.
+posixregex.c uses the POSIX regular expression library, and is the default on
+POSIX. pmatchregex.c is the fallback.
+
+Configuration files written using either of the two true regex engines are
+compatible with one another, as the regular expressions are both POSIX
+extended regular expressions. Configuration files written using the fallback
+engine are incompatible.
+
+Additional regular expression implementations can be written. The full
+interface documentation is in sys/share/posixregex.c
+
 =================== NEXT FEATURE ==========================
 
 

doc/Guidebook.mn

@@ -1,4 +1,4 @@
-.\" $NHDT-Branch: master $:$NHDT-Revision: 1.160 $ $NHDT-Date: 1430043650 2015/04/26 10:20:50 $
+.\" $NHDT-Branch: master $:$NHDT-Revision: 1.164 $ $NHDT-Date: 1432473674 2015/05/24 13:21:14 $
 .ds h0 "NetHack Guidebook
 .ds h1
 .ds h2 %
@@ -2575,7 +2575,15 @@ If the game display is difficult to read, try adjusting these scales;
 if this does not correct the problem, try !color.
 Cannot be set with the `O' command.
 .hn 2
-Configuring autopickup exceptions
+Regular Expressions
+.pg
+Regular expressions are normally POSIX extended regular expressions. It is
+possible to compile NetHack without regular expression support on a platform
+where there is no regular expression library. While this is not true of any
+modern platform, if your NetHack was built this way, patterns are instead glob
+patterns.
+.hn 2
+Configuring Autopickup Exceptions
 .pg
 You can further refine the behavior of the
 .op autopickup
@@ -2594,17 +2602,10 @@ Sets an exception to the
 option.
 The
 .op autopickup_exception
-option should be followed by a string of 1-80 characters to be used as a 
-pattern to match against the singular form of the description of an 
-object at your location.
+option should be followed by a regular expression to be used as a pattern to
+match against the singular form of the description of an object at your
+location.
 .lp ""
-You may use the following special characters in a pattern:
-.sd
-.si
-.CC * "matches zero or more characters;"
-.CC ? "matches any single character."
-.ei
-.ed
 In addition, some characters are treated specially if they occur as the first 
 character in the pattern, specifically:
 .sd
@@ -2657,8 +2658,7 @@ optional, and if left out, you must also leave out the preceding ampersand.
 If no attribute is defined, no attribute is used.
 .PE
 .lp ""
-For explanation on pattern format and the matching routines, see
-the pattern in the ``Configuring User Sounds'' -section.
+The pattern should be a regular expression.
 .lp ""
 Allowed colors are black, red, green, brown, blue, magenta, cyan, gray,
 orange, lightgreen, yellow, lightblue, lightmagenta, lightcyan, and white.
@@ -2710,33 +2710,7 @@ the sound file to play;
 the volume to be set while playing the sound file.
 .PE
 .lp ""
-The exact format for the pattern depends on whether the platform is
-built to use ``regular expressions'' or NetHack's own internal pattern 
-matching facility. The ``regular expressions'' matching can be much more 
-sophisticated than the internal NetHack pattern matching, but requires 
-3rd party libraries on some platforms.  There are plenty of references 
-available elsewhere for explaining ``regular expressions''. You can verify 
-which pattern matching is used by your port with the #version command.  
-.lp ""
-NetHack's internal pattern matching routine uses the following
-special characters in its pattern matching:
-.sd
-.si
-.CC * "matches 0 or more characters;"
-.CC ? "matches any single character."
-.ei
-.ed
-.lp ""
-Here's an example of a sound mapping using NetHack's internal
-pattern matching facility:
-.sd
-.si
-SOUND=MESG "*chime of a cash register*" "gong.wav" 50
-.ei
-.ed
-specifies that any message with "chime of a cash register" contained
-in it will trigger the playing of file \fBgong.wav\fP.  You can have multiple
-SOUND entries in your config file.
+The pattern should be a POSIX extended regular expression.
 .pg
 .hn 2
 Modifying NetHack Symbols 

doc/Guidebook.tex

@@ -3119,9 +3119,18 @@ if this does not correct the problem, try {\tt !color}.
 Cannot be set with the `{\tt O}' command.
 \elist
 
-%.lp
+%.nh 2
+\subsection*{Regular Expressions}
+
+%.pg
+Regular expressions are normally POSIX extended regular expressions. It is
+possible to compile NetHack without regular expression support on a platform where
+there is no regular expression library. While this is not true of any modern
+platform, if your NetHack was built this way, patterns are instead glob
+patterns.
+
 %.hn 2
-\subsection*{Configuring autopickup exceptions}
+\subsection*{Configuring Autopickup Exceptions}
 
 %.pg
 You can further refine the behavior of the ``{\tt autopickup}'' option
@@ -3136,17 +3145,9 @@ autopickup something.
 %.lp
 \item[\ib{autopickup\_exception}]
 Sets an exception to the `{\it pickup\_types}' option.
-The {\it autopickup\_exception\/} option should be followed by a string of 1--80
-characters to be used as a pattern to match against the singular form
-of the description of an object at your location.
-
-%.lp ""
-You may use the following special characters in a pattern:
-
-%.sd .si
-{\tt *} --- matches zero or more characters;\\
-{\tt ?} --- matches any single character.
-%.ei .ed
+The {\it autopickup\_exception\/} option should be followed by a regular
+expression to be used as a pattern to match against the singular form of the
+description of an object at your location.
 
 In addition, some characters are treated specially if they occur as the first 
 character in the pattern, specifically:
@@ -3211,8 +3212,7 @@ If no attribute is defined, no attribute is used.
 \elist
 
 %.lp ""
-For explanation on pattern format and the matching routines, see
-the pattern in the {\it Configuring User Sounds} -section.
+The pattern should be a regular expression.
 
 %.lp ""
 Allowed colors are {\it black}, {\it red}, {\it green}, {\it brown},
@@ -3279,37 +3279,7 @@ Each SOUND entry is broken down into the following parts:
 \elist
 
 %.lp ""
-The exact format for the pattern depends on whether the platform is
-built to use {\it regular expressions \/} or NetHack's own internal pattern 
-matching facility. The {\it regular expressions \/} matching can be much more 
-sophisticated than the internal NetHack pattern matching, but requires 
-3rd party libraries on some platforms.  There are plenty of references 
-available elsewhere for explaining {\it regular expressions \/}. You can verify 
-which pattern matching is used by your port with the 
-\#version command.  
-
-%.lp ""
-NetHack's internal pattern matching routine uses the following
-special characters in its pattern matching:
-
-%.sd
-%.si
-{\tt *} --- matches 0 or more characters;
-{\tt ?} --- matches any single character.
-%.ei
-%.ed
-
-%.lp ""
-Here's an example of a sound mapping using NetHack's internal
-pattern matching facility:
-
-%.sd.si
-{\tt SOUND=MESG "*chime of a cash register*" "gong.wav" 50}
-%.ei.ed
-
-specifies that any message with ``chime of a cash register'' contained
-in it will trigger the playing of file {\tt gong.wav}.  You can have multiple
-SOUND entries in your config file.
+The pattern should be a regular expression.
 
 %.lp
 %.hn 2

doc/fixes35.0

@@ -1143,6 +1143,7 @@ stop travel or run when you get hungry
 	class character to show inventory of items known to be blessed,&c
 debug-mode viewing of object weight
 prizes on various levels now protected by ?oSM scrolls as well as Elbereth
+regexes now use system libraries consistently for all pattern-matching systems
 
 
 Platform- and/or Interface-Specific New Features