diff -r 000000000000 -r 7f656887cf89 libraries/spcre/libpcre/pcre/doc/pcrestack.3
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/libraries/spcre/libpcre/pcre/doc/pcrestack.3 Wed Jun 23 15:52:26 2010 +0100
@@ -0,0 +1,160 @@
+.TH PCRESTACK 3
+.SH NAME
+PCRE - Perl-compatible regular expressions
+.SH "PCRE DISCUSSION OF STACK USAGE"
+.rs
+.sp
+When you call \fBpcre_exec()\fP, it makes use of an internal function called
+\fBmatch()\fP. This calls itself recursively at branch points in the pattern,
+in order to remember the state of the match so that it can back up and try a
+different alternative if the first one fails. As matching proceeds deeper and
+deeper into the tree of possibilities, the recursion depth increases.
+.P
+Not all calls of \fBmatch()\fP increase the recursion depth; for an item such
+as a* it may be called several times at the same level, after matching
+different numbers of a's. Furthermore, in a number of cases where the result of
+the recursive call would immediately be passed back as the result of the
+current call (a "tail recursion"), the function is just restarted instead.
+.P
+The \fBpcre_dfa_exec()\fP function operates in an entirely different way, and
+hardly uses recursion at all. The limit on its complexity is the amount of
+workspace it is given. The comments that follow do NOT apply to
+\fBpcre_dfa_exec()\fP; they are relevant only for \fBpcre_exec()\fP.
+.P
+You can set limits on the number of times that \fBmatch()\fP is called, both in
+total and recursively. If the limit is exceeded, an error occurs. For details,
+see the
+.\" HTML
+.\"
+section on extra data for \fBpcre_exec()\fP
+.\"
+in the
+.\" HREF
+\fBpcreapi\fP
+.\"
+documentation.
+.P
+Each time that \fBmatch()\fP is actually called recursively, it uses memory
+from the process stack. For certain kinds of pattern and data, very large
+amounts of stack may be needed, despite the recognition of "tail recursion".
+You can often reduce the amount of recursion, and therefore the amount of stack
+used, by modifying the pattern that is being matched. Consider, for example,
+this pattern:
+.sp
+ ([^<]|<(?!inet))+
+.sp
+It matches from wherever it starts until it encounters "
+.\"
+http://developer.apple.com/qa/qa2005/qa1419.html.
+.\"
+.
+.
+.SH AUTHOR
+.rs
+.sp
+.nf
+Philip Hazel
+University Computing Service
+Cambridge CB2 3QH, England.
+.fi
+.
+.
+.SH REVISION
+.rs
+.sp
+.nf
+Last updated: 09 July 2008
+Copyright (c) 1997-2008 University of Cambridge.
+.fi