Programming Ruby

The Pragmatic Programmer's Guide
Previous < Contents ^
Next >
class Regexp
Parent: Object
Version: 1.6

Index:

compile escape last_match new quote == === =~ ~ casefold? kcode match source

A Regexp holds a regular expression, used to match a pattern against strings. Regexps are created using the /.../ and %r{...} literals, and by the Regexp.new constructor.

constants

EXTENDED Ignore spaces and newlines in regexp.
IGNORECASE Matches are case insensitive.
MULTILINE Newlines treated as any other character.

class methods
compile Regexp.compile( pattern [, options [ lang ] ] ) -> aRegexp

Synonym for Regexp.new.

escape Regexp.escape( aString ) -> aNewString

Escapes any characters that would have special meaning in a regular expression. For any string, Regexp.escape(str)=~str will be true.

Regexp.escape('\\*?{}.') » \\\\\*\?\{\}\.

last_match Regexp.last_match -> aMatchData

Returns the MatchData object generated by the last successful pattern match. Equivalent to reading the global variable $~. MatchData is described on page 336.

new Regexp.new( pattern [, options [ lang ] ] ) -> aRegexp

Constructs a new regular expression from pattern, which can be either a String or a Regexp (in which case that regexp's options are not propagated). If options is a Fixnum, it should be one or more of the constants Regexp::EXTENDED, Regexp::IGNORECASE, and Regexp::POSIXLINE, or-ed together. Otherwise, if options is not nil, the regexp will be case insensitive. The lang parameter enables multibyte support for the regexp: `n', `N' = none, `e', `E' = EUC, `s', `S' = SJIS, `u', `U' = UTF-8.

r1 = Regexp.new('^a-z+:\\s+\w+') » /^a-z+:\s+\w+/
r2 = Regexp.new(r1, true) » /^a-z+:\s+\w+/i
r3 = Regexp.new(r2, Regexp::EXTENDED) » /^a-z+:\s+\w+/x

quote Regexp.quote( aString ) -> aNewString

Synonym for Regexp.escape.

instance methods
== rxp == aRegexp -> true or false

Equality---Two regexps are equal if their patterns are identical, they have the same character set code, and their casefold? values are the same.

/abc/  == /abc/x » false
/abc/  == /abc/i » false
/abc/u == /abc/n » false

=== rxp === aString -> true or false

Case Equality---Synonym for Regexp#=~ used in case statements. 

a = "HELLO"
case a
when /^a-z*$/; print "Lower case\n"
when /^A-Z*$/; print "Upper case\n"
else;            print "Mixed case\n"
end
produces: 
Upper case

=~ rxp =~ aString -> anInteger or nil

Match---Matches rxp against aString, returning the offset of the start of the match or nil if the match failed.

/SIT/  =~ "insensitive" » nil
/SIT/i =~ "insensitive" » 5

~ ~ rxp -> anInteger or nil

Match---Matches rxp against the contents of $_. Equivalent to rxp =~ $_.

$_ = "input data"
~ /at/ » 7

casefold? rxp.casefold? -> true or false

Returns the value of the case-insensitive flag.

kcode rxp.kcode -> aString

Returns the character set code for the regexp.

match rxp.match(aString) -> aMatchData or nil

Returns a MatchData object (see page 336) describing the match, or nil if there was no match. This is equivalent to retrieving the value of the special variable $~ following a normal match.

/(.)(.)(.)/.match("abc")[2] » "b"

source rxp.source -> aString

Returns the original string of the pattern.

/ab+c/ix.source » "ab+c"

Previous < Contents ^
Next >

Extracted from the book "Programming Ruby - The Pragmatic Programmer's Guide"
Copyright © 2001 by Addison Wesley Longman, Inc. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/)).

Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder.

Distribution of the work or derivative of the work in any standard (paper) book form is prohibited unless prior permission is obtained from the copyright holder.