Programming Ruby

The Pragmatic Programmer's Guide

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('\\*?{}.') ƒT \\\\\*\?\{\}\.

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+') ƒT /^a-z+:\s+\w+/

r2 = Regexp.new(r1, true) ƒT /^a-z+:\s+\w+/i

r3 = Regexp.new(r2, Regexp::EXTENDED) ƒT /^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 ƒT false

/abc/ == /abc/i ƒT false

/abc/u == /abc/n ƒT 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" ƒT nil

/SIT/i =~ "insensitive" ƒT 5

~ ~ rxp -> anInteger or nil

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


 rxp =~ $_

$_ = "input data"

~ /at/ ƒT 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] ƒT "b"

source rxp.source -> aString

Returns the original string of the pattern.

/ab+c/ix.source ƒT "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.