Janis Danisevskis | 8b979b2 | 2016-08-15 16:09:16 +0100 | [diff] [blame] | 1 | .TH PCRE2SAMPLE 3 "02 February 2016" "PCRE2 10.22" |
Janis Danisevskis | 53e448c | 2016-03-31 13:35:25 +0100 | [diff] [blame] | 2 | .SH NAME |
| 3 | PCRE2 - Perl-compatible regular expressions (revised API) |
| 4 | .SH "PCRE2 SAMPLE PROGRAM" |
| 5 | .rs |
| 6 | .sp |
| 7 | A simple, complete demonstration program to get you started with using PCRE2 is |
| 8 | supplied in the file \fIpcre2demo.c\fP in the \fBsrc\fP directory in the PCRE2 |
| 9 | distribution. A listing of this program is given in the |
| 10 | .\" HREF |
| 11 | \fBpcre2demo\fP |
| 12 | .\" |
| 13 | documentation. If you do not have a copy of the PCRE2 distribution, you can |
| 14 | save this listing to re-create the contents of \fIpcre2demo.c\fP. |
| 15 | .P |
Janis Danisevskis | 8b979b2 | 2016-08-15 16:09:16 +0100 | [diff] [blame] | 16 | The demonstration program compiles the regular expression that is its |
| 17 | first argument, and matches it against the subject string in its second |
| 18 | argument. No PCRE2 options are set, and default character tables are used. If |
| 19 | matching succeeds, the program outputs the portion of the subject that matched, |
| 20 | together with the contents of any captured substrings. |
Janis Danisevskis | 53e448c | 2016-03-31 13:35:25 +0100 | [diff] [blame] | 21 | .P |
| 22 | If the -g option is given on the command line, the program then goes on to |
| 23 | check for further matches of the same regular expression in the same subject |
| 24 | string. The logic is a little bit tricky because of the possibility of matching |
| 25 | an empty string. Comments in the code explain what is going on. |
| 26 | .P |
Janis Danisevskis | 8b979b2 | 2016-08-15 16:09:16 +0100 | [diff] [blame] | 27 | The code in \fBpcre2demo.c\fP is an 8-bit program that uses the PCRE2 8-bit |
| 28 | library. It handles strings and characters that are stored in 8-bit code units. |
| 29 | By default, one character corresponds to one code unit, but if the pattern |
| 30 | starts with "(*UTF)", both it and the subject are treated as UTF-8 strings, |
| 31 | where characters may occupy multiple code units. |
| 32 | .P |
Janis Danisevskis | 53e448c | 2016-03-31 13:35:25 +0100 | [diff] [blame] | 33 | If PCRE2 is installed in the standard include and library directories for your |
| 34 | operating system, you should be able to compile the demonstration program using |
Janis Danisevskis | 8b979b2 | 2016-08-15 16:09:16 +0100 | [diff] [blame] | 35 | a command like this: |
Janis Danisevskis | 53e448c | 2016-03-31 13:35:25 +0100 | [diff] [blame] | 36 | .sp |
Janis Danisevskis | 8b979b2 | 2016-08-15 16:09:16 +0100 | [diff] [blame] | 37 | cc -o pcre2demo pcre2demo.c -lpcre2-8 |
Janis Danisevskis | 53e448c | 2016-03-31 13:35:25 +0100 | [diff] [blame] | 38 | .sp |
| 39 | If PCRE2 is installed elsewhere, you may need to add additional options to the |
| 40 | command line. For example, on a Unix-like system that has PCRE2 installed in |
| 41 | \fI/usr/local\fP, you can compile the demonstration program using a command |
| 42 | like this: |
| 43 | .sp |
| 44 | .\" JOINSH |
Janis Danisevskis | 8b979b2 | 2016-08-15 16:09:16 +0100 | [diff] [blame] | 45 | cc -o pcre2demo -I/usr/local/include pcre2demo.c \e |
| 46 | -L/usr/local/lib -lpcre2-8 |
Janis Danisevskis | 53e448c | 2016-03-31 13:35:25 +0100 | [diff] [blame] | 47 | .sp |
Janis Danisevskis | 8b979b2 | 2016-08-15 16:09:16 +0100 | [diff] [blame] | 48 | Once you have built the demonstration program, you can run simple tests like |
| 49 | this: |
Janis Danisevskis | 53e448c | 2016-03-31 13:35:25 +0100 | [diff] [blame] | 50 | .sp |
| 51 | ./pcre2demo 'cat|dog' 'the cat sat on the mat' |
| 52 | ./pcre2demo -g 'cat|dog' 'the dog sat on the cat' |
| 53 | .sp |
| 54 | Note that there is a much more comprehensive test program, called |
| 55 | .\" HREF |
| 56 | \fBpcre2test\fP, |
| 57 | .\" |
Janis Danisevskis | 8b979b2 | 2016-08-15 16:09:16 +0100 | [diff] [blame] | 58 | which supports many more facilities for testing regular expressions using all |
| 59 | three PCRE2 libraries (8-bit, 16-bit, and 32-bit, though not all three need be |
| 60 | installed). The |
Janis Danisevskis | 53e448c | 2016-03-31 13:35:25 +0100 | [diff] [blame] | 61 | .\" HREF |
| 62 | \fBpcre2demo\fP |
| 63 | .\" |
Janis Danisevskis | 8b979b2 | 2016-08-15 16:09:16 +0100 | [diff] [blame] | 64 | program is provided as a relatively simple coding example. |
Janis Danisevskis | 53e448c | 2016-03-31 13:35:25 +0100 | [diff] [blame] | 65 | .P |
| 66 | If you try to run |
| 67 | .\" HREF |
| 68 | \fBpcre2demo\fP |
| 69 | .\" |
| 70 | when PCRE2 is not installed in the standard library directory, you may get an |
| 71 | error like this on some operating systems (e.g. Solaris): |
| 72 | .sp |
Janis Danisevskis | 8b979b2 | 2016-08-15 16:09:16 +0100 | [diff] [blame] | 73 | ld.so.1: pcre2demo: fatal: libpcre2-8.so.0: open failed: No such file or directory |
Janis Danisevskis | 53e448c | 2016-03-31 13:35:25 +0100 | [diff] [blame] | 74 | .sp |
| 75 | This is caused by the way shared library support works on those systems. You |
| 76 | need to add |
| 77 | .sp |
| 78 | -R/usr/local/lib |
| 79 | .sp |
| 80 | (for example) to the compile command to get round this problem. |
| 81 | . |
| 82 | . |
| 83 | .SH AUTHOR |
| 84 | .rs |
| 85 | .sp |
| 86 | .nf |
| 87 | Philip Hazel |
| 88 | University Computing Service |
| 89 | Cambridge, England. |
| 90 | .fi |
| 91 | . |
| 92 | . |
| 93 | .SH REVISION |
| 94 | .rs |
| 95 | .sp |
| 96 | .nf |
Janis Danisevskis | 8b979b2 | 2016-08-15 16:09:16 +0100 | [diff] [blame] | 97 | Last updated: 02 February 2016 |
| 98 | Copyright (c) 1997-2016 University of Cambridge. |
Janis Danisevskis | 53e448c | 2016-03-31 13:35:25 +0100 | [diff] [blame] | 99 | .fi |