Add a simple tripwire to pcretest to lock out certain modifiers.

git-svn-id: svn://vcs.exim.org/pcre/code/trunk@1388 2f5784b3-3f2a-0410-8824-cb99058d5e15

1 files changed, 37 insertions, 7 deletions

diff --git a/doc/pcretest.1 b/doc/pcretest.1
index a1761f4..d177613 100644
--- a/doc/pcretest.1
+++ b/doc/pcretest.1
@@ -1,4 +1,4 @@
-.TH PCRETEST 1 "09 October 2013" "PCRE 8.34"
+.TH PCRETEST 1 "05 November 2013" "PCRE 8.34"
 .SH NAME
 pcretest - a program for testing Perl-compatible regular expressions.
 .SH SYNOPSIS
@@ -254,7 +254,7 @@ option states whether or not \fBreadline()\fP will be used.
 .P
 The program handles any number of sets of input on a single input file. Each
 set starts with a regular expression, and continues with any number of data
-lines to be matched against the pattern.
+lines to be matched against that pattern.
 .P
 Each data line is matched separately and independently. If you want to do
 multi-line matches, you have to use the \en escape sequence (or \er or \er\en,
@@ -595,6 +595,37 @@ The \fB/+\fP modifier works as described above. All other modifiers are
 ignored.
 .
 .
+.SS "Locking out certain modifiers"
+.rs
+.sp
+PCRE can be compiled with or without support for certain features such as
+UTF-8/16/32 or Unicode properties. Accordingly, the standard tests are split up
+into a number of different files that are selected for running depending on
+which features are available. When updating the tests, it is all too easy to
+put a new test into the wrong file by mistake; for example, to put a test that
+requires UTF support into a file that is used when it is not available. To help
+detect such mistakes as early as possible, there is a facility for locking out
+specific modifiers. If an input line for \fBpcretest\fP starts with the string
+"< forbid " the following sequence of characters is taken as a list of
+forbidden modifiers. For example, in the test files that must not use UTF or
+Unicode property support, this line appears:
+.sp
+  < forbid 8W
+.sp
+This locks out the /8 and /W modifiers. An immediate error is given if they are 
+subsequently encountered. If the character string contains < but not >, all the 
+multi-character modifiers that begin with < are locked out. Otherwise, such 
+modifiers must be explicitly listed, for example:
+.sp
+  < forbid <JS><cr>
+.sp
+There must be a single space between < and "forbid" for this feature to be 
+recognised. If there is not, the line is interpreted either as a request to
+re-load a pre-compiled pattern (see "SAVING AND RELOADING COMPILED PATTERNS"
+below) or, if there is a another < character, as a pattern that uses < as its 
+delimiter.
+.
+.
 .SH "DATA LINES"
 .rs
 .sp
@@ -1042,10 +1073,9 @@ exact copy of the compiled pattern. If there is additional study data, this
 writing the file, \fBpcretest\fP expects to read a new pattern.
 .P
 A saved pattern can be reloaded into \fBpcretest\fP by specifying < and a file
-name instead of a pattern. The name of the file must not contain a < character,
-as otherwise \fBpcretest\fP will interpret the line as a pattern delimited by <
-characters.
-For example:
+name instead of a pattern. There must be no space between < and the file name,
+which must not contain a < character, as otherwise \fBpcretest\fP will
+interpret the line as a pattern delimited by < characters. For example:
 .sp
    re> </some/file
   Compiled pattern loaded from /some/file
@@ -1105,6 +1135,6 @@ Cambridge CB2 3QH, England.
 .rs
 .sp
 .nf
-Last updated: 09 October 2013
+Last updated: 05 November 2013
 Copyright (c) 1997-2013 University of Cambridge.
 .fi