← Back to branch summary

~ubuntu-branches/ubuntu/trusty/glib2.0/trusty-proposed

« back to all changes in this revision

Viewing changes to docs/reference/glib/html/glib-regex-syntax.html

  • Committer: Bazaar Package Importer
  • Author(s): Sebastien Bacher
  • Date: 2010-06-18 13:50:39 UTC
  • mfrom: (1.30.1 upstream) (3.4.16 experimental)
  • Revision ID: james.westby@ubuntu.com-20100618135039-546pvldpgilh981h
Tags: 2.25.9-1ubuntu1
* Resync on Debian
* debian/patches/90_git_fix_typo.patch:
  - the change is in the new version
* debian/patches/80-gtester-subunit.patch:
  - the change is in the new version 

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reference/glib/html/glib-regex-syntax.html
31
31
<td valign="top" align="right"></td>
32
32
</tr></table></div>
33
33
<div class="refsect1" title="GRegex regular expression details">
34
 
<a name="id622427"></a><h2>GRegex regular expression details</h2>
 
34
<a name="id528117"></a><h2>GRegex regular expression details</h2>
35
35
<p>
36
36
A regular expression is a pattern that is matched against a
37
37
string from left to right. Most characters stand for themselves in a
59
59
metacharacters are as follows:
60
60
</p>
61
61
<div class="table">
62
 
<a name="id603222"></a><p class="title"><b>Table 1. Metacharacters outside square brackets</b></p>
 
62
<a name="id508912"></a><p class="title"><b>Table 1. Metacharacters outside square brackets</b></p>
63
63
<div class="table-contents"><table summary="Metacharacters outside square brackets" border="1">
64
64
<colgroup>
65
65
<col align="center">
126
126
class". In a character class the only metacharacters are:
127
127
</p>
128
128
<div class="table">
129
 
<a name="id607653"></a><p class="title"><b>Table 2. Metacharacters inside square brackets</b></p>
 
129
<a name="id513343"></a><p class="title"><b>Table 2. Metacharacters inside square brackets</b></p>
130
130
<div class="table-contents"><table summary="Metacharacters inside square brackets" border="1">
131
131
<colgroup>
132
132
<col align="center">
163
163
<br class="table-break">
164
164
</div>
165
165
<div class="refsect1" title="Backslash">
166
 
<a name="id637700"></a><h2>Backslash</h2>
 
166
<a name="id543390"></a><h2>Backslash</h2>
167
167
<p>
168
168
The backslash character has several uses. Firstly, if it is followed by
169
169
a non-alphanumeric character, it takes away any special meaning that
193
193
classes.
194
194
</p>
195
195
<div class="refsect2" title="Non-printing characters">
196
 
<a name="id637734"></a><h3>Non-printing characters</h3>
 
196
<a name="id543423"></a><h3>Non-printing characters</h3>
197
197
<p>
198
198
A second use of backslash provides a way of encoding non-printing
199
199
characters in patterns in a visible manner. There is no restriction on the
203
203
sequences than the binary character it represents:
204
204
</p>
205
205
<div class="table">
206
 
<a name="id637747"></a><p class="title"><b>Table 3. Non-printing characters</b></p>
 
206
<a name="id543436"></a><p class="title"><b>Table 3. Non-printing characters</b></p>
207
207
<div class="table-contents"><table summary="Non-printing characters" border="1">
208
208
<colgroup>
209
209
<col align="center">
304
304
a data character. Any subsequent digits stand for themselves. For example:
305
305
</p>
306
306
<div class="table">
307
 
<a name="id638113"></a><p class="title"><b>Table 4. Non-printing characters</b></p>
 
307
<a name="id543802"></a><p class="title"><b>Table 4. Non-printing characters</b></p>
308
308
<div class="table-contents"><table summary="Non-printing characters" border="1">
309
309
<colgroup>
310
310
<col align="center">
368
368
</div>
369
369
<hr>
370
370
<div class="refsect2" title="Absolute and relative back references">
371
 
<a name="id638271"></a><h3>Absolute and relative back references</h3>
 
371
<a name="id543961"></a><h3>Absolute and relative back references</h3>
372
372
<p>
373
373
The sequence \g followed by a positive or negative number, optionally enclosed
374
374
in braces, is an absolute or relative back reference. Back references are
377
377
</div>
378
378
<hr>
379
379
<div class="refsect2" title="Generic character types">
380
 
<a name="id638284"></a><h3>Generic character types</h3>
 
380
<a name="id543974"></a><h3>Generic character types</h3>
381
381
<p>
382
382
Another use of backslash is for specifying generic character types.
383
383
The following are always recognized:
384
384
</p>
385
385
<div class="table">
386
 
<a name="id638295"></a><p class="title"><b>Table 5. Generic characters</b></p>
 
386
<a name="id543985"></a><p class="title"><b>Table 5. Generic characters</b></p>
387
387
<div class="table-contents"><table summary="Generic characters" border="1">
388
388
<colgroup>
389
389
<col align="center">
447
447
</div>
448
448
<hr>
449
449
<div class="refsect2" title="Newline sequences">
450
 
<a name="id638434"></a><h3>Newline sequences</h3>
 
450
<a name="id544124"></a><h3>Newline sequences</h3>
451
451
<p>Outside a character class, the escape sequence \R matches any Unicode
452
452
newline sequence.
453
453
This particular group matches either the two-character sequence CR followed by
459
459
</div>
460
460
<hr>
461
461
<div class="refsect2" title="Unicode character properties">
462
 
<a name="id638450"></a><h3>Unicode character properties</h3>
 
462
<a name="id544139"></a><h3>Unicode character properties</h3>
463
463
<p>
464
464
To support generic character types there are three additional escape
465
465
sequences, they are:
466
466
</p>
467
467
<div class="table">
468
 
<a name="id638460"></a><p class="title"><b>Table 6. Generic character types</b></p>
 
468
<a name="id544150"></a><p class="title"><b>Table 6. Generic character types</b></p>
469
469
<div class="table-contents"><table summary="Generic character types" border="1">
470
470
<colgroup>
471
471
<col align="center">
595
595
The following general category property codes are supported:
596
596
</p>
597
597
<div class="table">
598
 
<a name="id638898"></a><p class="title"><b>Table 7. Property codes</b></p>
 
598
<a name="id544587"></a><p class="title"><b>Table 7. Property codes</b></p>
599
599
<div class="table-contents"><table summary="Property codes" border="1">
600
600
<colgroup>
601
601
<col align="center">
798
798
</div>
799
799
<hr>
800
800
<div class="refsect2" title="Simple assertions">
801
 
<a name="id639401"></a><h3>Simple assertions</h3>
 
801
<a name="id545091"></a><h3>Simple assertions</h3>
802
802
<p>
803
803
The final use of backslash is for certain simple assertions. An
804
804
assertion specifies a condition that has to be met at a particular point in
807
807
The backslashed assertions are:
808
808
</p>
809
809
<div class="table">
810
 
<a name="id639413"></a><p class="title"><b>Table 8. Simple assertions</b></p>
 
810
<a name="id545103"></a><p class="title"><b>Table 8. Simple assertions</b></p>
811
811
<div class="table-contents"><table summary="Simple assertions" border="1">
812
812
<colgroup>
813
813
<col align="center">
889
889
</div>
890
890
</div>
891
891
<div class="refsect1" title="Circumflex and dollar">
892
 
<a name="id639573"></a><h2>Circumflex and dollar</h2>
 
892
<a name="id545263"></a><h2>Circumflex and dollar</h2>
893
893
<p>
894
894
Outside a character class, in the default matching mode, the circumflex
895
895
character is an assertion that is true only if the current matching
947
947
</p>
948
948
</div>
949
949
<div class="refsect1" title="Full stop (period, dot)">
950
 
<a name="id639654"></a><h2>Full stop (period, dot)</h2>
 
950
<a name="id545344"></a><h2>Full stop (period, dot)</h2>
951
951
<p>
952
952
Outside a character class, a dot in the pattern matches any one character
953
953
in the string, including a non-printing character, but not (by
980
980
</p>
981
981
</div>
982
982
<div class="refsect1" title="Matching a single byte">
983
 
<a name="id639698"></a><h2>Matching a single byte</h2>
 
983
<a name="id545387"></a><h2>Matching a single byte</h2>
984
984
<p>
985
985
Outside a character class, the escape sequence \C matches any one byte,
986
986
both in and out of UTF-8 mode. Unlike a dot, it always matches any line
997
997
</p>
998
998
</div>
999
999
<div class="refsect1" title="Square brackets and character classes">
1000
 
<a name="id639717"></a><h2>Square brackets and character classes</h2>
 
1000
<a name="id545407"></a><h2>Square brackets and character classes</h2>
1001
1001
<p>
1002
1002
An opening square bracket introduces a character class, terminated by a
1003
1003
closing square bracket. A closing square bracket on its own is not special. If a closing square bracket is required as a member of the class,
1082
1082
</p>
1083
1083
</div>
1084
1084
<div class="refsect1" title="Posix character classes">
1085
 
<a name="id639803"></a><h2>Posix character classes</h2>
 
1085
<a name="id545493"></a><h2>Posix character classes</h2>
1086
1086
<p>
1087
1087
GRegex supports the POSIX notation for character classes. This uses names
1088
1088
enclosed by [: and :] within the enclosing square brackets. For example,
1095
1095
names are
1096
1096
</p>
1097
1097
<div class="table">
1098
 
<a name="id639824"></a><p class="title"><b>Table 9. Posix classes</b></p>
 
1098
<a name="id545513"></a><p class="title"><b>Table 9. Posix classes</b></p>
1099
1099
<div class="table-contents"><table summary="Posix classes" border="1">
1100
1100
<colgroup>
1101
1101
<col align="center">
1190
1190
</p>
1191
1191
</div>
1192
1192
<div class="refsect1" title="Vertical bar">
1193
 
<a name="id589350"></a><h2>Vertical bar</h2>
 
1193
<a name="id495040"></a><h2>Vertical bar</h2>
1194
1194
<p>
1195
1195
Vertical bar characters are used to separate alternative patterns. For
1196
1196
example, the pattern
1206
1206
</p>
1207
1207
</div>
1208
1208
<div class="refsect1" title="Internal option setting">
1209
 
<a name="id589375"></a><h2>Internal option setting</h2>
 
1209
<a name="id495065"></a><h2>Internal option setting</h2>
1210
1210
<p>
1211
1211
The settings of the <code class="varname">G_REGEX_CASELESS</code>, <code class="varname">G_REGEX_MULTILINE</code>, <code class="varname">G_REGEX_MULTILINE</code>,
1212
1212
and <code class="varname">G_REGEX_EXTENDED</code> options can be changed from within the pattern by a
1214
1214
option letters are
1215
1215
</p>
1216
1216
<div class="table">
1217
 
<a name="id589401"></a><p class="title"><b>Table 10. Option settings</b></p>
 
1217
<a name="id495091"></a><p class="title"><b>Table 10. Option settings</b></p>
1218
1218
<div class="table-contents"><table summary="Option settings" border="1">
1219
1219
<colgroup>
1220
1220
<col align="center">
1288
1288
</p>
1289
1289
</div>
1290
1290
<div class="refsect1" title="Subpatterns">
1291
 
<a name="id589570"></a><h2>Subpatterns</h2>
 
1291
<a name="id495260"></a><h2>Subpatterns</h2>
1292
1292
<p>
1293
1293
Subpatterns are delimited by parentheses (round brackets), which can be
1294
1294
nested. Turning part of a pattern into a subpattern does two things:
1352
1352
</p>
1353
1353
</div>
1354
1354
<div class="refsect1" title="Named subpatterns">
1355
 
<a name="id589655"></a><h2>Named subpatterns</h2>
 
1355
<a name="id495345"></a><h2>Named subpatterns</h2>
1356
1356
<p>
1357
1357
Identifying capturing parentheses by number is simple, but it can be
1358
1358
very hard to keep track of the numbers in complicated regular expressions.
1393
1393
</p>
1394
1394
</div>
1395
1395
<div class="refsect1" title="Repetition">
1396
 
<a name="id589698"></a><h2>Repetition</h2>
 
1396
<a name="id495387"></a><h2>Repetition</h2>
1397
1397
<p>
1398
1398
Repetition is specified by quantifiers, which can follow any of the
1399
1399
following items:
1456
1456
abbreviations:
1457
1457
</p>
1458
1458
<div class="table">
1459
 
<a name="id589810"></a><p class="title"><b>Table 11. Abbreviations for quantifiers</b></p>
 
1459
<a name="id495499"></a><p class="title"><b>Table 11. Abbreviations for quantifiers</b></p>
1460
1460
<div class="table-contents"><table summary="Abbreviations for quantifiers" border="1">
1461
1461
<colgroup>
1462
1462
<col align="center">
1597
1597
</p>
1598
1598
</div>
1599
1599
<div class="refsect1" title="Atomic grouping and possessive quantifiers">
1600
 
<a name="id590037"></a><h2>Atomic grouping and possessive quantifiers</h2>
 
1600
<a name="id495726"></a><h2>Atomic grouping and possessive quantifiers</h2>
1601
1601
<p>
1602
1602
With both maximizing ("greedy") and minimizing ("ungreedy" or "lazy")
1603
1603
repetition, failure of what follows normally causes the repeated
1715
1715
</p>
1716
1716
</div>
1717
1717
<div class="refsect1" title="Back references">
1718
 
<a name="id590172"></a><h2>Back references</h2>
 
1718
<a name="id495862"></a><h2>Back references</h2>
1719
1719
<p>
1720
1720
Outside a character class, a backslash followed by a digit greater than
1721
1721
0 (and possibly further digits) is a back reference to a capturing subpattern
1824
1824
</p>
1825
1825
</div>
1826
1826
<div class="refsect1" title="Assertions">
1827
 
<a name="id590299"></a><h2>Assertions</h2>
 
1827
<a name="id495988"></a><h2>Assertions</h2>
1828
1828
<p>
1829
1829
An assertion is a test on the characters following or preceding the
1830
1830
current matching point that does not actually consume any characters.
1848
1848
negative assertions.
1849
1849
</p>
1850
1850
<div class="refsect2" title="Lookahead assertions">
1851
 
<a name="id590324"></a><h3>Lookahead assertions</h3>
 
1851
<a name="id496013"></a><h3>Lookahead assertions</h3>
1852
1852
<p>
1853
1853
Lookahead assertions start with (?= for positive assertions and (?! for
1854
1854
negative assertions. For example,
1885
1885
</div>
1886
1886
<hr>
1887
1887
<div class="refsect2" title="Lookbehind assertions">
1888
 
<a name="id590374"></a><h3>Lookbehind assertions</h3>
 
1888
<a name="id496064"></a><h3>Lookbehind assertions</h3>
1889
1889
<p>
1890
1890
Lookbehind assertions start with (?&lt;= for positive assertions and (?&lt;!
1891
1891
for negative assertions. For example,
1974
1974
</div>
1975
1975
<hr>
1976
1976
<div class="refsect2" title="Using multiple assertions">
1977
 
<a name="id590489"></a><h3>Using multiple assertions</h3>
 
1977
<a name="id496178"></a><h3>Using multiple assertions</h3>
1978
1978
<p>
1979
1979
Several assertions (of any sort) may occur in succession. For example,
1980
1980
</p>
2019
2019
</div>
2020
2020
</div>
2021
2021
<div class="refsect1" title="Conditional subpatterns">
2022
 
<a name="id590553"></a><h2>Conditional subpatterns</h2>
 
2022
<a name="id496242"></a><h2>Conditional subpatterns</h2>
2023
2023
<p>
2024
2024
It is possible to cause the matching process to obey a subpattern
2025
2025
conditionally or to choose between two alternative subpatterns, depending
2040
2040
recursion, a pseudo-condition called DEFINE, and assertions.
2041
2041
</p>
2042
2042
<div class="refsect2" title="Checking for a used subpattern by number">
2043
 
<a name="id590581"></a><h3>Checking for a used subpattern by number</h3>
 
2043
<a name="id496271"></a><h3>Checking for a used subpattern by number</h3>
2044
2044
<p>
2045
2045
If the text between the parentheses consists of a sequence of digits, the
2046
2046
condition is true if the capturing subpattern of that number has previously
2069
2069
</div>
2070
2070
<hr>
2071
2071
<div class="refsect2" title="Checking for a used subpattern by name">
2072
 
<a name="id590617"></a><h3>Checking for a used subpattern by name</h3>
 
2072
<a name="id496307"></a><h3>Checking for a used subpattern by name</h3>
2073
2073
<p>
2074
2074
Perl uses the syntax (?(&lt;name&gt;)...) or (?('name')...) to test for a used
2075
2075
subpattern by name, the Python syntax (?(name)...) is also recognized. However,
2088
2088
</div>
2089
2089
<hr>
2090
2090
<div class="refsect2" title="Checking for pattern recursion">
2091
 
<a name="id590643"></a><h3>Checking for pattern recursion</h3>
 
2091
<a name="id496332"></a><h3>Checking for pattern recursion</h3>
2092
2092
<p>
2093
2093
If the condition is the string (R), and there is no subpattern with the name R,
2094
2094
the condition is true if a recursive call to the whole pattern or any
2111
2111
</div>
2112
2112
<hr>
2113
2113
<div class="refsect2" title="Defining subpatterns for use by reference only">
2114
 
<a name="id590672"></a><h3>Defining subpatterns for use by reference only</h3>
 
2114
<a name="id496361"></a><h3>Defining subpatterns for use by reference only</h3>
2115
2115
<p>
2116
2116
If the condition is the string (DEFINE), and there is no subpattern with the
2117
2117
name DEFINE, the condition is always false. In this case, there may be only one
2139
2139
</div>
2140
2140
<hr>
2141
2141
<div class="refsect2" title="Assertion conditions">
2142
 
<a name="id590704"></a><h3>Assertion conditions</h3>
 
2142
<a name="id496394"></a><h3>Assertion conditions</h3>
2143
2143
<p>
2144
2144
If the condition is not in any of the above formats, it must be an
2145
2145
assertion. This may be a positive or negative lookahead or lookbehind
2162
2162
</div>
2163
2163
</div>
2164
2164
<div class="refsect1" title="Comments">
2165
 
<a name="id590733"></a><h2>Comments</h2>
 
2165
<a name="id496422"></a><h2>Comments</h2>
2166
2166
<p>
2167
2167
The sequence (?# marks the start of a comment that continues up to the
2168
2168
next closing parenthesis. Nested parentheses are not permitted. The
2176
2176
</p>
2177
2177
</div>
2178
2178
<div class="refsect1" title="Recursive patterns">
2179
 
<a name="id590754"></a><h2>Recursive patterns</h2>
 
2179
<a name="id496444"></a><h2>Recursive patterns</h2>
2180
2180
<p>
2181
2181
Consider the problem of matching a string in parentheses, allowing for
2182
2182
unlimited nested parentheses. Without the use of recursion, the best
2308
2308
</p>
2309
2309
</div>
2310
2310
<div class="refsect1" title="Subpatterns as subroutines">
2311
 
<a name="id590911"></a><h2>Subpatterns as subroutines</h2>
 
2311
<a name="id496601"></a><h2>Subpatterns as subroutines</h2>
2312
2312
<p>
2313
2313
If the syntax for a recursive subpattern reference (either by number or
2314
2314
by name) is used outside the parentheses to which it refers, it operates
2350
2350
</p>
2351
2351
</div>
2352
2352
<div class="refsect1" title="Copyright">
2353
 
<a name="id590985"></a><h2>Copyright</h2>
 
2353
<a name="id496675"></a><h2>Copyright</h2>
2354
2354
<p>
2355
2355
This document was copied and adapted from the PCRE documentation,
2356
2356
specifically from the man page for pcrepattern.