Bug #5709 ยป 0001-Improve-Regexp-documentation.patch
| doc/re.rdoc | ||
|---|---|---|
|
Specifically, <tt>/st/</tt> requires that the string contains the letter
|
||
|
_s_ followed by the letter _t_, so it matches _haystack_, also.
|
||
|
== <tt>=~</tt> and Regexp#match
|
||
|
Pattern matching may be achieved by using <tt>=~</tt> operator or Regexp#match
|
||
|
method.
|
||
|
=== <tt>=~</tt> operator
|
||
|
<tt>=~</tt> is Ruby's basic pattern-matching operator.
|
||
|
One operand must be a regular expression and one must be a string (this
|
||
|
operator is equivalently defined by Regexp and String). If a match is found,
|
||
|
the operator returns index of first match in string, otherwise it returns
|
||
|
+nil+.
|
||
|
/hay/ =~ 'haystack' #=> 0
|
||
|
/a/ =~ 'haystack' #=> 1
|
||
|
/u/ =~ 'haystack' #=> nil
|
||
|
Using <tt>=~</tt> operator sets <tt>$~</tt> global variable after a successful
|
||
|
match. <tt>$~</tt> holds a MatchData object. Regexp.last_match is equivalent to
|
||
|
<tt>$~</tt>.
|
||
|
=== Regexp#match method
|
||
|
#match method return a MatchData object :
|
||
|
/st/.match('haystack') #=> #<MatchData "st">
|
||
|
== Metacharacters and Escapes
|
||
|
The following are <i>metacharacters</i> <tt>(</tt>, <tt>)</tt>,
|
||
| ... | ... | |
|
* <tt>/[[:print:]]/</tt> - Like [:graph:], but includes the space character
|
||
|
* <tt>/[[:punct:]]/</tt> - Punctuation character
|
||
|
* <tt>/[[:space:]]/</tt> - Whitespace character (<tt>[:blank:]</tt>, newline,
|
||
|
carriage return, etc.)
|
||
|
carriage return, etc.)
|
||
|
* <tt>/[[:upper:]]/</tt> - Uppercase alphabetical
|
||
|
* <tt>/[[:xdigit:]]/</tt> - Digit allowed in a hexadecimal number (i.e.,
|
||
|
0-9a-fA-F)
|
||
| ... | ... | |
|
Parentheses can be used for <i>capturing</i>. The text enclosed by the
|
||
|
<i>n</i><sup>th</sup> group of parentheses can be subsequently referred to
|
||
|
with <i>n</i>. Within a pattern use the <i>backreference</i>
|
||
|
<tt>\</tt><i>n</i>; outside of the pattern use
|
||
|
<tt>\n</tt>; outside of the pattern use
|
||
|
<tt>MatchData[</tt><i>n</i><tt>]</tt>.
|
||
|
# 'at' is captured by the first group of parentheses, then referred to
|
||
| ... | ... | |
|
/a(?i:b)c/.match('aBc') #=> #<MatchData "aBc">
|
||
|
/a(?i:b)c/.match('abc') #=> #<MatchData "abc">
|
||
|
Options may also be used with <tt>Regexp.new</tt>:
|
||
|
Regexp.new("abc", Regexp::IGNORECASE) #=> /abc/i
|
||
|
Regexp.new("abc", Regexp::MULTILINE) #=> /abc/m
|
||
|
Regexp.new("abc # Comment", Regexp::EXTENDED) #=> /abc # Comment/x
|
||
|
Regexp.new("abc", Regexp::IGNORECASE | Regexp::MULTILINE) #=> /abc/mi
|
||
|
== Free-Spacing Mode and Comments
|
||
|
As mentioned above, the <tt>x</tt> option enables <i>free-spacing</i>
|
||
| ... | ... | |
|
#=> Encoding::CompatibilityError: incompatible encoding regexp match
|
||
|
(ISO-8859-1 regexp with UTF-8 string)
|
||
|
== Special global variables
|
||
|
Pattern matching sets some global variables :
|
||
|
* <tt>$~</tt> is equivalent to Regexp.last_match;
|
||
|
* <tt>$&</tt> contains the complete matched text;
|
||
|
* <tt>$`</tt> contains string before match;
|
||
|
* <tt>$'</tt> contains string after match;
|
||
|
* <tt>$1</tt>, <tt>$2</tt> and so on contain text matching first, second, etc
|
||
|
capture group;
|
||
|
* <tt>$+</tt> contains last capture group.
|
||
|
Example:
|
||
|
m = /s(\w{2}).*(c)/.match('haystack') #=> #<MatchData "stac" 1:"ta" 2:"c">
|
||
|
$~ #=> #<MatchData "stac" 1:"ta" 2:"c">
|
||
|
Regexp.latch_match #=> #<MatchData "stac" 1:"ta" 2:"c">
|
||
|
|
||
|
$& #=> "stac"
|
||
|
# same as m[0]
|
||
|
$` #=> "hay"
|
||
|
# same as m.pre_match
|
||
|
$' #=> "k"
|
||
|
# same as m.post_match
|
||
|
$1 #=> "ta"
|
||
|
# same as m[1]
|
||
|
$2 #=> "c"
|
||
|
# same as m[2]
|
||
|
$3 #=> nil
|
||
|
# no third group in pattern
|
||
|
$+ #=> "c"
|
||
|
# same as m[-1]
|
||
|
These global variables are thread-local and method-local varaibles.
|
||
|
== Performance
|
||
|
Certain pathological combinations of constructs can lead to abysmally bad
|
||