Revision: 1210
http://vcs.pcre.org/viewvc?view=rev&revision=1210
Author: ph10
Date: 2012-11-07 16:58:13 +0000 (Wed, 07 Nov 2012)
Log Message:
-----------
New comments on the PCRE options.
Modified Paths:
--------------
code/trunk/pcre.h.in
Modified: code/trunk/pcre.h.in
===================================================================
--- code/trunk/pcre.h.in 2012-11-07 07:25:07 UTC (rev 1209)
+++ code/trunk/pcre.h.in 2012-11-07 16:58:13 UTC (rev 1210)
@@ -95,57 +95,71 @@
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). */
+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 */
+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 */
#define PCRE_ERROR_NOMATCH (-1)
