← Back to branch summary

~ubuntu-branches/debian/sid/boost1.49/sid

« back to all changes in this revision

Viewing changes to libs/regex/doc/format_boost_syntax.qbk

  • Committer: Package Import Robot
  • Author(s): Steve M. Robbins
  • Date: 2012-02-26 00:31:44 UTC
  • Revision ID: package-import@ubuntu.com-20120226003144-eaytp12cbf6ubpms
Tags: upstream-1.49.0
Import upstream version 1.49.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
libs/regex/doc/format_boost_syntax.qbk
 
1
[/ 
 
2
  Copyright 2006-2007 John Maddock.
 
3
  Distributed under the Boost Software License, Version 1.0.
 
4
  (See accompanying file LICENSE_1_0.txt or copy at
 
5
  http://www.boost.org/LICENSE_1_0.txt).
 
6
]
 
7
 
 
8
 
 
9
[section:boost_format_syntax Boost-Extended Format String Syntax]
 
10
 
 
11
Boost-Extended format strings treat all characters as literals except for 
 
12
'$', '\\', '(', ')', '?', and ':'.
 
13
 
 
14
[h4 Grouping]
 
15
 
 
16
The characters '(' and ')' perform lexical grouping, so use \\( and \\) if you 
 
17
want a to output literal parenthesis.
 
18
 
 
19
[h4 Conditionals]
 
20
 
 
21
The character '?' begins a conditional expression, the general form is:
 
22
 
 
23
?Ntrue-expression:false-expression
 
24
 
 
25
where N is decimal digit.
 
26
 
 
27
If sub-expression N was matched, then true-expression is evaluated and sent to 
 
28
output, otherwise false-expression is evaluated and sent to output.
 
29
 
 
30
You will normally need to surround a conditional-expression with parenthesis in 
 
31
order to prevent ambiguities.
 
32
 
 
33
For example, the format string "(?1foo:bar)" will replace each match found with "foo" if
 
34
the sub-expression $1 was matched, and with "bar" otherwise.
 
35
 
 
36
For sub-expressions with an index greater than 9, or for access to named sub-expressions use:
 
37
 
 
38
?{INDEX}true-expression:false-expression
 
39
 
 
40
or
 
41
 
 
42
?{NAME}true-expression:false-expression
 
43
 
 
44
 
 
45
[h4 Placeholder Sequences]
 
46
 
 
47
Placeholder sequences specify that some part of what matched the regular expression 
 
48
should be sent to output as follows:
 
49
 
 
50
[table
 
51
[[Placeholder][Meaning]]
 
52
[[$&][Outputs what matched the whole expression.]]
 
53
[[$MATCH][As $&]]
 
54
[[${^MATCH}][As $&]]
 
55
[[$\`][Outputs the text between the end of the last match found (or the 
 
56
      start of the text if no previous match was found), and the start 
 
57
      of the current match.]]
 
58
[[$PREMATCH][As $\`]]
 
59
[[${^PREMATCH}][As $\`]]
 
60
[[$'][Outputs all the text following the end of the current match.]]
 
61
[[$POSTMATCH][As $']]
 
62
[[${^POSTMATCH}][As $']]
 
63
[[$+][Outputs what matched the last marked sub-expression in the regular expression.]]
 
64
[[$LAST_PAREN_MATCH][As $+]]
 
65
[[$LAST_SUBMATCH_RESULT][Outputs what matched the last sub-expression to be actually matched.]]
 
66
[[$^N][As $LAST_SUBMATCH_RESULT]]
 
67
[[$$][Outputs a literal '$']]
 
68
[[$n][Outputs what matched the n'th sub-expression.]]
 
69
[[${n}][Outputs what matched the n'th sub-expression.]]
 
70
[[$+{NAME}][Outputs whatever matched the sub-expression named "NAME".]]
 
71
]
 
72
 
 
73
Any $-placeholder sequence not listed above, results in '$' being treated as a literal.
 
74
 
 
75
[h4 Escape Sequences]
 
76
 
 
77
An escape character followed by any character x, outputs that character unless 
 
78
x is one of the escape sequences shown below.
 
79
 
 
80
[table
 
81
[[Escape][Meaning]]
 
82
[[\\a][Outputs the bell character: '\\a'.]]
 
83
[[\\e][Outputs the ANSI escape character (code point 27).]]
 
84
[[\\f][Outputs a form feed character: '\\f']]
 
85
[[\\n][Outputs a newline character: '\\n'.]]
 
86
[[\\r][Outputs a carriage return character: '\\r'.]]
 
87
[[\\t][Outputs a tab character: '\\t'.]]
 
88
[[\\v][Outputs a vertical tab character: '\\v'.]]
 
89
[[\\xDD][Outputs the character whose hexadecimal code point is 0xDD]]
 
90
[[\\x{DDDD}][Outputs the character whose hexadecimal code point is 0xDDDDD]]
 
91
[[\\cX][Outputs the ANSI escape sequence "escape-X".]]
 
92
[[\\D][If D is a decimal digit in the range 1-9, then outputs the text that matched sub-expression D.]]
 
93
[[\\l][Causes the next character to be outputted, to be output in lower case.]]
 
94
[[\\u][Causes the next character to be outputted, to be output in upper case.]]
 
95
[[\\L][Causes all subsequent characters to be output in lower case, until a \\E is found.]]
 
96
[[\\U][Causes all subsequent characters to be output in upper case, until a \\E is found.]]
 
97
[[\\E][Terminates a \\L or \\U sequence.]]
 
98
]
 
99
 
 
100
[endsect]
 
101
 
 
102