From: Sean Hunt Date: Sun, 24 May 2015 13:23:18 +0000 (+0900) Subject: Provide documentation for the regex engine. X-Git-Tag: NetHack-3.6.0_RC01~376 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=cc50ecda67173f71a6cd12fee598e0f29c31cace;p=nethack Provide documentation for the regex engine. The guidebook entries could do with more detailed descriptions, but this will do for now. --- diff --git a/DEVEL/code_features.txt b/DEVEL/code_features.txt index d771f7cec..f8bb504eb 100644 --- a/DEVEL/code_features.txt +++ b/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 ========================== diff --git a/doc/Guidebook.mn b/doc/Guidebook.mn index 82da60c6d..3dabeefef 100644 --- a/doc/Guidebook.mn +++ b/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 diff --git a/doc/Guidebook.tex b/doc/Guidebook.tex index adf880a60..62bd58b14 100644 --- a/doc/Guidebook.tex +++ b/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 diff --git a/doc/fixes35.0 b/doc/fixes35.0 index 3c2d4a302..cb91c9526 100644 --- a/doc/fixes35.0 +++ b/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