| 1 |
MAINTENANCE README FOR PCRE
|
| 2 |
===========================
|
| 3 |
|
| 4 |
The files in the "maint" directory of the PCRE source contain data, scripts,
|
| 5 |
and programs that are used for the maintenance of PCRE, but which do not form
|
| 6 |
part of the PCRE distribution tarballs. This document describes these files and
|
| 7 |
also contains some notes for maintainers. Its contents are:
|
| 8 |
|
| 9 |
Files in the maint directory
|
| 10 |
Updating to a new Unicode release
|
| 11 |
Preparing for a PCRE release
|
| 12 |
Making a PCRE release
|
| 13 |
Long-term ideas (wish list)
|
| 14 |
|
| 15 |
|
| 16 |
Files in the maint directory
|
| 17 |
============================
|
| 18 |
|
| 19 |
---------------- This file is now OBSOLETE and no longer used ----------------
|
| 20 |
Builducptable A Perl script that creates the contents of the ucptable.h file
|
| 21 |
from two Unicode data files, which themselves are downloaded
|
| 22 |
from the Unicode web site. Run this script in the "maint"
|
| 23 |
directory.
|
| 24 |
---------------- This file is now OBSOLETE and no longer used ----------------
|
| 25 |
|
| 26 |
GenerateUtt.py A Python script to generate part of the pcre_tables.c file
|
| 27 |
that contains Unicode script names in a long string with
|
| 28 |
offsets, which is tedious to maintain by hand.
|
| 29 |
|
| 30 |
ManyConfigTests A shell script that runs "configure, make, test" a number of
|
| 31 |
times with different configuration settings.
|
| 32 |
|
| 33 |
MultiStage2.py A Python script that generates the file pcre_ucd.c from three
|
| 34 |
Unicode data tables, which are themselves downloaded from the
|
| 35 |
Unicode web site. Run this script in the "maint" directory.
|
| 36 |
The generated file contains the tables for a 2-stage lookup
|
| 37 |
of Unicode properties.
|
| 38 |
|
| 39 |
pcre_chartables.c.non-standard
|
| 40 |
This is a set of character tables that came from a Windows
|
| 41 |
system. It has characters greater than 128 that are set as
|
| 42 |
spaces, amongst other things. I kept it so that it can be
|
| 43 |
used for testing from time to time.
|
| 44 |
|
| 45 |
README This file.
|
| 46 |
|
| 47 |
Unicode.tables The files in this directory, DerivedGeneralCategory.txt,
|
| 48 |
Scripts.txt and UnicodeData.txt, were downloaded from the
|
| 49 |
Unicode web site. They contain information about Unicode
|
| 50 |
characters and scripts.
|
| 51 |
|
| 52 |
ucptest.c A short C program for testing the Unicode property macros
|
| 53 |
that do lookups in the pcre_ucd.c data, mainly useful after
|
| 54 |
rebuilding the Unicode property table. Compile and run this in
|
| 55 |
the "maint" directory (see comments at its head).
|
| 56 |
|
| 57 |
ucptestdata A directory containing two files, testinput1 and testoutput1,
|
| 58 |
to use in conjunction with the ucptest program.
|
| 59 |
|
| 60 |
utf8.c A short, freestanding C program for converting a Unicode code
|
| 61 |
point into a sequence of bytes in the UTF-8 encoding, and vice
|
| 62 |
versa. If its argument is a hex number such as 0x1234, it
|
| 63 |
outputs a list of the equivalent UTF-8 bytes. If its argument
|
| 64 |
is sequence of concatenated UTF-8 bytes (e.g. e188b4) it
|
| 65 |
treats them as a UTF-8 character and outputs the equivalent
|
| 66 |
code point in hex.
|
| 67 |
|
| 68 |
|
| 69 |
Updating to a new Unicode release
|
| 70 |
=================================
|
| 71 |
|
| 72 |
When there is a new release of Unicode, the files in Unicode.tables must be
|
| 73 |
refreshed from the web site. If the new version of Unicode adds new character
|
| 74 |
scripts, the source file ucp.h and both the MultiStage2.py and the
|
| 75 |
GenerateUtt.py scripts must be edited to add the new names. Then MultiStage2.py
|
| 76 |
can be run to generate a new version of pcre_ucd.c, and GenerateUtt.py can be
|
| 77 |
run to generate the tricky tables for inclusion in pcre_tables.c.
|
| 78 |
|
| 79 |
If MultiStage2.py gives the error "ValueError: list.index(x): x not in list",
|
| 80 |
the cause is usually a missing (or misspelt) name in the list of scripts. I
|
| 81 |
couldn't find a straightforward list of scripts on the Unicode site, but
|
| 82 |
there's a useful Wikipedia page that list them, and notes the Unicode version
|
| 83 |
in which they were introduced:
|
| 84 |
|
| 85 |
http://en.wikipedia.org/wiki/Unicode_scripts#Table_of_Unicode_scripts
|
| 86 |
|
| 87 |
The ucptest program can be compiled and used to check that the new tables in
|
| 88 |
pcre_ucd.c work properly, using the data files in ucptestdata to check a number
|
| 89 |
of test characters. The source file ucptest.c must be updated whenever new
|
| 90 |
Unicode script names are added.
|
| 91 |
|
| 92 |
Note also that both the pcresyntax.3 and pcrepattern.3 man pages contain lists
|
| 93 |
of Unicode script names.
|
| 94 |
|
| 95 |
|
| 96 |
Preparing for a PCRE release
|
| 97 |
============================
|
| 98 |
|
| 99 |
This section contains a checklist of things that I consult before building a
|
| 100 |
distribution for a new release.
|
| 101 |
|
| 102 |
. Ensure that the version number and version date are correct in configure.ac.
|
| 103 |
|
| 104 |
. If new build options have been added, ensure that they are added to the CMake
|
| 105 |
files as well as to the autoconf files.
|
| 106 |
|
| 107 |
. Run ./autogen.sh to ensure everything is up-to-date.
|
| 108 |
|
| 109 |
. Compile and test with many different config options, and combinations of
|
| 110 |
options. The maint/ManyConfigTests script now encapsulates this testing.
|
| 111 |
|
| 112 |
. Run perltest.pl on the test data for tests 1, 4, 6, and 11. The first two can
|
| 113 |
be run with Perl 5.8 or >= 5.10; the last two require Perl >= 5.10. The
|
| 114 |
output should match the PCRE test output, apart from the version
|
| 115 |
identification at the start of each test. The other tests are not
|
| 116 |
Perl-compatible (they use various PCRE-specific features or options).
|
| 117 |
|
| 118 |
. Test with valgrind by running "RunTest valgrind". There is also "RunGrepTest
|
| 119 |
valgrind", though that takes quite a long time.
|
| 120 |
|
| 121 |
. It may also useful to test with Electric Fence, though the fact that it
|
| 122 |
grumbles for missing free() calls can be a nuisance. (A missing free() in
|
| 123 |
pcretest is hardly a big problem.) To build with EF, use:
|
| 124 |
|
| 125 |
LIBS='/usr/lib/libefence.a -lpthread' with ./configure.
|
| 126 |
|
| 127 |
Then all normal runs use it to check for buffer overflow. Also run everything
|
| 128 |
with:
|
| 129 |
|
| 130 |
EF_PROTECT_BELOW=1 <whatever>
|
| 131 |
|
| 132 |
because there have been problems with lookbehinds that looked too far.
|
| 133 |
|
| 134 |
. Test with the emulated memmove() function by undefining HAVE_MEMMOVE and
|
| 135 |
HAVE_BCOPY in config.h. You may see a number of "pcre_memmove defined but not
|
| 136 |
used" warnings for the modules in which there is no call to memmove(). These
|
| 137 |
can be ignored.
|
| 138 |
|
| 139 |
. Documentation: check AUTHORS, COPYING, ChangeLog (check version and date),
|
| 140 |
INSTALL, LICENCE, NEWS (check version and date), NON-UNIX-USE, and README.
|
| 141 |
Many of these won't need changing, but over the long term things do change.
|
| 142 |
|
| 143 |
. Man pages: Check all man pages for \ not followed by e or f or " because
|
| 144 |
that indicates a markup error. However, there is one exception: pcredemo.3,
|
| 145 |
which is created from the pcredemo.c program. It contains three instances
|
| 146 |
of \\n.
|
| 147 |
|
| 148 |
. When the release is built, test it on a number of different operating
|
| 149 |
systems if possible, and using different compilers as well. For example,
|
| 150 |
on Solaris it is helpful to test using Sun's cc compiler as a change from
|
| 151 |
gcc. Adding -xarch=v9 to the cc options does a 64-bit test, but it also
|
| 152 |
needs -S 64 for pcretest to increase the stack size for test 2.
|
| 153 |
|
| 154 |
|
| 155 |
Making a PCRE release
|
| 156 |
=====================
|
| 157 |
|
| 158 |
Run PrepareRelease and commit the files that it changes (by removing trailing
|
| 159 |
spaces). Then run "make distcheck" to create the tarballs and the zipball.
|
| 160 |
Double-check with "svn status", then create an SVN tagged copy:
|
| 161 |
|
| 162 |
svn copy svn://vcs.exim.org/pcre/code/trunk \
|
| 163 |
svn://vcs.exim.org/pcre/code/tags/pcre-8.xx
|
| 164 |
|
| 165 |
Don't forget to update Freshmeat when the new release is out, and to tell
|
| 166 |
webmaster@pcre.org and the mailing list. Also, update the list of version
|
| 167 |
numbers in Bugzilla (edit products).
|
| 168 |
|
| 169 |
|
| 170 |
Future ideas (wish list)
|
| 171 |
========================
|
| 172 |
|
| 173 |
This section records a list of ideas so that they do not get forgotten. They
|
| 174 |
vary enormously in their usefulness and potential for implementation. Some are
|
| 175 |
very sensible; some are rather wacky. Some have been on this list for years;
|
| 176 |
others are relatively new.
|
| 177 |
|
| 178 |
. Optimization
|
| 179 |
|
| 180 |
There are always ideas for new optimizations so as to speed up pattern
|
| 181 |
matching. Most of them try to save work by recognizing a non-match without
|
| 182 |
having to scan all the possibilities. These are some that I've recorded:
|
| 183 |
|
| 184 |
* /((A{0,5}){0,5}){0,5}(something complex)/ on a non-matching string is very
|
| 185 |
slow, though Perl is fast. Can we speed up somehow? Convert to {0,125}?
|
| 186 |
OTOH, this is pathological - the user could easily fix it.
|
| 187 |
|
| 188 |
* Turn ={4} into ==== ? (for speed). I once did an experiment, and it seems
|
| 189 |
to have little effect, and maybe makes things worse.
|
| 190 |
|
| 191 |
* "Ends with literal string" - note that a single character doesn't gain much
|
| 192 |
over the existing "required byte" (reqbyte) feature that just remembers one
|
| 193 |
byte.
|
| 194 |
|
| 195 |
* These probably need to go in pcre_study():
|
| 196 |
|
| 197 |
o Remember an initial string rather than just 1 char?
|
| 198 |
|
| 199 |
o A required byte from alternatives - not just the last char, but an
|
| 200 |
earlier one if common to all alternatives.
|
| 201 |
|
| 202 |
o Friedl contains other ideas.
|
| 203 |
|
| 204 |
* pcre_study() does not set initial byte flags for Unicode property types
|
| 205 |
such as \p; I don't know how much benefit there would be for, for example,
|
| 206 |
setting the bits for 0-9 and all bytes >= xC0 when a pattern starts with
|
| 207 |
\p{N}.
|
| 208 |
|
| 209 |
* There is scope for more "auto-possessifying" in connection with \p and \P.
|
| 210 |
|
| 211 |
. If Perl gets to a consistent state over the settings of capturing sub-
|
| 212 |
patterns inside repeats, see if we can match it. One example of the
|
| 213 |
difference is the matching of /(main(O)?)+/ against mainOmain, where PCRE
|
| 214 |
leaves $2 set. In Perl, it's unset. Changing this in PCRE will be very hard
|
| 215 |
because I think it needs much more state to be remembered.
|
| 216 |
|
| 217 |
. Perl 6 will be a revolution. Is it a revolution too far for PCRE?
|
| 218 |
|
| 219 |
. Unicode
|
| 220 |
|
| 221 |
* A different approach to Unicode might be to use a typedef to do everything
|
| 222 |
in unsigned shorts instead of unsigned chars. Actually, we'd have to have a
|
| 223 |
new typedef to distinguish data from bits of compiled pattern that are in
|
| 224 |
bytes, I think. There would need to be conversion functions in and out. I
|
| 225 |
don't think this is particularly trivial - and anyway, Unicode now has
|
| 226 |
characters that need more than 16 bits, so is this at all sensible?
|
| 227 |
|
| 228 |
* There has been a request for direct support of 16-bit characters and
|
| 229 |
UTF-16. However, since Unicode is moving beyond purely 16-bit characters,
|
| 230 |
is this worth it at all? One possible way of handling 16-bit characters
|
| 231 |
would be to "load" them in the same way that UTF-8 characters are loaded.
|
| 232 |
|
| 233 |
. Allow errorptr and erroroffset to be NULL. I don't like this idea.
|
| 234 |
|
| 235 |
. Line endings:
|
| 236 |
|
| 237 |
* Option to use NUL as a line terminator in subject strings. This could now
|
| 238 |
be done relatively easily since the extension to support LF, CR, and CRLF.
|
| 239 |
If it is done, a suitable option for pcregrep is also required.
|
| 240 |
|
| 241 |
. Option to provide the pattern with a length instead of with a NUL terminator.
|
| 242 |
This affects quite a few places in the code and is not trivial.
|
| 243 |
|
| 244 |
. Catch SIGSEGV for stack overflows?
|
| 245 |
|
| 246 |
. A feature to suspend a match via a callout was once requested.
|
| 247 |
|
| 248 |
. Option to convert results into character offsets and character lengths.
|
| 249 |
|
| 250 |
. Option for pcregrep to scan only the start of a file. I am not keen - this is
|
| 251 |
the job of "head".
|
| 252 |
|
| 253 |
. A (non-Unix) user wanted pcregrep options to (a) list a file name just once,
|
| 254 |
preceded by a blank line, instead of adding it to every matched line, and (b)
|
| 255 |
support --outputfile=name.
|
| 256 |
|
| 257 |
. Consider making UTF-8 and UCP the default for PCRE n.0 for some n > 8.
|
| 258 |
|
| 259 |
. Add a user pointer to pcre_malloc/free functions -- some option would be
|
| 260 |
needed to retain backward compatibility.
|
| 261 |
|
| 262 |
. Define a union for the results from pcre_fullinfo().
|
| 263 |
|
| 264 |
. Provide a "random access to the subject" facility so that the way in which it
|
| 265 |
is stored is independent of PCRE. For efficiency, it probably isn't possible
|
| 266 |
to switch this dynamically. It would have to be specified when PCRE was
|
| 267 |
compiled. PCRE would then call a function every time it wanted a character.
|
| 268 |
|
| 269 |
. Wild thought: the ability to compile from PCRE's internal byte code to a real
|
| 270 |
FSM and a very fast (third) matcher to process the result. There would be
|
| 271 |
even more restrictions than for pcre_dfa_exec(), however. This is not easy.
|
| 272 |
|
| 273 |
. Should pcretest have some private locale data, to avoid relying on the
|
| 274 |
available locales for the test data, since different OS have different ideas?
|
| 275 |
This won't be as thorough a test, but perhaps that doesn't really matter.
|
| 276 |
|
| 277 |
. pcregrep: add -rs for a sorted recurse? Having to store file names and sort
|
| 278 |
them will of course slow it down.
|
| 279 |
|
| 280 |
. Someone suggested --disable-callout to save code space when callouts are
|
| 281 |
never wanted. This seems rather marginal.
|
| 282 |
|
| 283 |
. Check names that consist entirely of digits: PCRE allows, but do Perl and
|
| 284 |
Python, etc?
|
| 285 |
|
| 286 |
. A user suggested a parameter to limit the length of string matched, for
|
| 287 |
example if the parameter is N, the current match should fail if the matched
|
| 288 |
substring exceeds N. This could apply to both match functions. The value
|
| 289 |
could be a new field in the extra block.
|
| 290 |
|
| 291 |
. Callouts with arguments: (?Cn:ARG) for instance.
|
| 292 |
|
| 293 |
. A user is going to supply a patch to generalize the API for user-specific
|
| 294 |
memory allocation so that it is more flexible in threaded environments. This
|
| 295 |
was promised a long time ago, and never appeared...
|
| 296 |
|
| 297 |
. Write a function that generates random matching strings for a compiled regex.
|
| 298 |
|
| 299 |
. Write a wrapper to maintain a structure with specified runtime parameters,
|
| 300 |
such as recurse limit, and pass these to PCRE each time it is called. Also
|
| 301 |
maybe malloc and free. A user sent a prototype.
|
| 302 |
|
| 303 |
. Pcregrep: an option to specify the output line separator, either as a string
|
| 304 |
or select from a fixed list. This is not dead easy, because at the moment it
|
| 305 |
outputs whatever is in the input file.
|
| 306 |
|
| 307 |
. Improve the code for duplicate checking in pcre_dfa_exec(). An incomplete,
|
| 308 |
non-thread-safe patch showed that this can help performance for patterns
|
| 309 |
where there are many alternatives. However, a simple thread-safe
|
| 310 |
implementation that I tried made things worse in many simple cases, so this
|
| 311 |
is not an obviously good thing.
|
| 312 |
|
| 313 |
. Make the longest lookbehind available via pcre_fullinfo(). This is not
|
| 314 |
straightforward because lookbehinds can be nested inside lookbehinds. This
|
| 315 |
case will have to be identified, and the amounts added. This should then give
|
| 316 |
the maximum possible lookbehind length. The reason for wanting this is to
|
| 317 |
help when implementing multi-segment matching using pcre_exec() with partial
|
| 318 |
matching and overlapping segments.
|
| 319 |
|
| 320 |
. PCRE cannot at present distinguish between subpatterns with different names,
|
| 321 |
but the same number (created by the use of ?|). In order to do so, a way of
|
| 322 |
remembering *which* subpattern numbered n matched is needed. Bugzilla #760.
|
| 323 |
Now that (*MARK) has been implemented, it can perhaps be used as a way round
|
| 324 |
this problem.
|
| 325 |
|
| 326 |
. Instead of having #ifdef HAVE_CONFIG_H in each module, put #include
|
| 327 |
"something" and the the #ifdef appears only in one place, in "something".
|
| 328 |
|
| 329 |
Philip Hazel
|
| 330 |
Email local part: ph10
|
| 331 |
Email domain: cam.ac.uk
|
| 332 |
Last updated: 03 June 2010
|
Parent Directory
| 
Revision Log