New comments on the PCRE options.

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

1 files changed, 63 insertions, 49 deletions

diff --git a/pcre.h.in b/pcre.h.in
index c868a61..0bc00c2 100644
--- a/pcre.h.in
+++ b/pcre.h.in
@@ -95,56 +95,70 @@ it is needed here for malloc. */
 extern "C" {
 #endif
 
-/* Options. Some are compile-time only, some are run-time only, and some are
-both, so we keep them all distinct. However, almost all the bits in the options
-word are now used. In the long run, we may have to re-use some of the
-compile-time only bits for runtime options, or vice versa. In the comments
-below, "compile", "exec", and "DFA exec" mean that the option is permitted to
-be set for those functions; "used in" means that an option may be set only for
-compile, but is subsequently referenced in exec and/or DFA exec. Any of the
+/* Public options. Some are compile-time only, some are run-time only, and some
+are both, so we keep them all distinct. However, almost all the bits in the
+options word are now used. In the long run, we may have to re-use some of the
+compile-time only bits for runtime options, or vice versa. Any of the
 compile-time options may be inspected during studying (and therefore JIT
-compiling). */
-
-#define PCRE_CASELESS           0x00000001  /* Compile */
-#define PCRE_MULTILINE          0x00000002  /* Compile */
-#define PCRE_DOTALL             0x00000004  /* Compile */
-#define PCRE_EXTENDED           0x00000008  /* Compile */
-#define PCRE_ANCHORED           0x00000010  /* Compile, exec, DFA exec */
-#define PCRE_DOLLAR_ENDONLY     0x00000020  /* Compile, used in exec, DFA exec */
-#define PCRE_EXTRA              0x00000040  /* Compile */
-#define PCRE_NOTBOL             0x00000080  /* Exec, DFA exec */
-#define PCRE_NOTEOL             0x00000100  /* Exec, DFA exec */
-#define PCRE_UNGREEDY           0x00000200  /* Compile */
-#define PCRE_NOTEMPTY           0x00000400  /* Exec, DFA exec */
-/* The next three are all used in compile, exec and DFA exec */
-#define PCRE_UTF8               0x00000800  /* Same as PCRE_UTF16 and PCRE_UTF32 */
-#define PCRE_UTF16              0x00000800  /* Same as PCRE_UTF8 and PCRE_UTF32 */
-#define PCRE_UTF32              0x00000800  /* Same as PCRE_UTF8 and PCRE_UTF16 */
-#define PCRE_NO_AUTO_CAPTURE    0x00001000  /* Compile */
-/* The next three are all used in compile, exec and DFA exec */
-#define PCRE_NO_UTF8_CHECK      0x00002000  /* Same as PCRE_NO_UTF16_CHECK and PCRE_NO_UTF32_CHECK */
-#define PCRE_NO_UTF16_CHECK     0x00002000  /* Same as PCRE_NO_UTF8_CHECK and PCRE_NO_UTF32_CHECK */
-#define PCRE_NO_UTF32_CHECK     0x00002000  /* Same as PCRE_NO_UTF8_CHECK and PCRE_NO_UTF16_CHECK */
-#define PCRE_AUTO_CALLOUT       0x00004000  /* Compile */
-#define PCRE_PARTIAL_SOFT       0x00008000  /* Exec, DFA exec */
-#define PCRE_PARTIAL            0x00008000  /* Backwards compatible synonym */
-#define PCRE_DFA_SHORTEST       0x00010000  /* DFA exec */
-#define PCRE_DFA_RESTART        0x00020000  /* DFA exec */
-#define PCRE_FIRSTLINE          0x00040000  /* Compile, used in exec, DFA exec */
-#define PCRE_DUPNAMES           0x00080000  /* Compile */
-#define PCRE_NEWLINE_CR         0x00100000  /* Compile, exec, DFA exec */
-#define PCRE_NEWLINE_LF         0x00200000  /* Compile, exec, DFA exec */
-#define PCRE_NEWLINE_CRLF       0x00300000  /* Compile, exec, DFA exec */
-#define PCRE_NEWLINE_ANY        0x00400000  /* Compile, exec, DFA exec */
-#define PCRE_NEWLINE_ANYCRLF    0x00500000  /* Compile, exec, DFA exec */
-#define PCRE_BSR_ANYCRLF        0x00800000  /* Compile, exec, DFA exec */
-#define PCRE_BSR_UNICODE        0x01000000  /* Compile, exec, DFA exec */
-#define PCRE_JAVASCRIPT_COMPAT  0x02000000  /* Compile, used in exec */
-#define PCRE_NO_START_OPTIMIZE  0x04000000  /* Compile, exec, DFA exec */
-#define PCRE_NO_START_OPTIMISE  0x04000000  /* Synonym */
-#define PCRE_PARTIAL_HARD       0x08000000  /* Exec, DFA exec */
-#define PCRE_NOTEMPTY_ATSTART   0x10000000  /* Exec, DFA exec */
-#define PCRE_UCP                0x20000000  /* Compile, used in exec, DFA exec */
+compiling).
+
+Some options for pcre_compile() change its behaviour but do not affect the
+behaviour of the execution functions. Other options are passed through to the
+execution functions and affect their behaviour, with or without affecting the
+behaviour of pcre_compile(). 
+
+Options that can be passed to pcre_compile() are tagged Cx below, with these
+variants:
+
+C1   Affects compile only
+C2   Does not affect compile; affects exec, dfa_exec
+C3   Affects compile, exec, dfa_exec
+C4   Affects compile, exec, dfa_exec, study
+C5   Affects compile, exec, study
+
+Options that can be set for pcre_exec() and/or pcre_dfa_exec() are flagged with
+E and D, respectively. They take precedence over C3, C4, and C5 settings passed
+from pcre_compile(). Those that are compatible with JIT execution are flagged
+with J. */
+
+#define PCRE_CASELESS           0x00000001  /* C1       */
+#define PCRE_MULTILINE          0x00000002  /* C1       */
+#define PCRE_DOTALL             0x00000004  /* C1       */
+#define PCRE_EXTENDED           0x00000008  /* C1       */
+#define PCRE_ANCHORED           0x00000010  /* C4 E D   */
+#define PCRE_DOLLAR_ENDONLY     0x00000020  /* C2       */
+#define PCRE_EXTRA              0x00000040  /* C1       */
+#define PCRE_NOTBOL             0x00000080  /*    E D J */
+#define PCRE_NOTEOL             0x00000100  /*    E D J */
+#define PCRE_UNGREEDY           0x00000200  /* C1       */
+#define PCRE_NOTEMPTY           0x00000400  /*    E D J */
+#define PCRE_UTF8               0x00000800  /* C4        )          */
+#define PCRE_UTF16              0x00000800  /* C4        ) Synonyms */
+#define PCRE_UTF32              0x00000800  /* C4        )          */
+#define PCRE_NO_AUTO_CAPTURE    0x00001000  /* C1       */
+#define PCRE_NO_UTF8_CHECK      0x00002000  /* C1 E D J  )          */
+#define PCRE_NO_UTF16_CHECK     0x00002000  /* C1 E D J  ) Synonyms */
+#define PCRE_NO_UTF32_CHECK     0x00002000  /* C1 E D J  )          */
+#define PCRE_AUTO_CALLOUT       0x00004000  /* C1       */
+#define PCRE_PARTIAL_SOFT       0x00008000  /*    E D J  ) Synonyms */
+#define PCRE_PARTIAL            0x00008000  /*    E D J  )          */
+#define PCRE_DFA_SHORTEST       0x00010000  /*      D   */
+#define PCRE_DFA_RESTART        0x00020000  /*      D   */
+#define PCRE_FIRSTLINE          0x00040000  /* C3       */
+#define PCRE_DUPNAMES           0x00080000  /* C1       */
+#define PCRE_NEWLINE_CR         0x00100000  /* C3 E D   */
+#define PCRE_NEWLINE_LF         0x00200000  /* C3 E D   */
+#define PCRE_NEWLINE_CRLF       0x00300000  /* C3 E D   */
+#define PCRE_NEWLINE_ANY        0x00400000  /* C3 E D   */
+#define PCRE_NEWLINE_ANYCRLF    0x00500000  /* C3 E D   */
+#define PCRE_BSR_ANYCRLF        0x00800000  /* C3 E D   */
+#define PCRE_BSR_UNICODE        0x01000000  /* C3 E D   */
+#define PCRE_JAVASCRIPT_COMPAT  0x02000000  /* C5       */
+#define PCRE_NO_START_OPTIMIZE  0x04000000  /* C2 E D    ) Synonyms */
+#define PCRE_NO_START_OPTIMISE  0x04000000  /* C2 E D    )          */
+#define PCRE_PARTIAL_HARD       0x08000000  /*    E D J */
+#define PCRE_NOTEMPTY_ATSTART   0x10000000  /*    E D J */
+#define PCRE_UCP                0x20000000  /* C3       */
 
 /* Exec-time and get/set-time error codes */