Regular Expression Construction
Switch branches/tags
Nothing to show
Latest commit 8082b30 Sep 3, 2012 @jimweirich update build
Failed to load latest commit information.
bench Added a benchmark file. Dec 29, 2009
lib Added regexml example. May 6, 2010
rakelib update build Sep 3, 2012
test update build Sep 3, 2012
.gitignore Fixed type in .gitignore May 6, 2010
.togglerc added a toggle file. Dec 28, 2009
MIT-LICENSE Updated MIT license text with dates. Dec 29, 2009
README.textile Add ci link Sep 3, 2012
Rakefile update build Sep 3, 2012


Regular Expression Construction

Complex regular expressions are hard to construct and even harder to
read. The Re library allows users to construct complex regular
expressions from simpler expressions. For example, consider the
following regular expression that will parse dates:

   /\A((?:19|20)[0-9]{2})[\- \/.](0[1-9]|1[012])[\- \/.](0[1-9]|[12][0-9]|3[01])\z/

Using the Re library, that regular expression can be built
incrementaly from smaller, easier to understand expressions.
Perhaps something like this:

  require 're'

  include Re

  delim                = re.any("- /.")
  century_prefix       = re("19") | re("20")
  under_ten            = re("0") + re.any("1-9")
  ten_to_twelve        = re("1") + re.any("012")
  ten_and_under_thirty = re.any("12") + re.any("0-9")
  thirties             = re("3") + re.any("01")

  year = (century_prefix + re.digit.repeat(2)).capture(:year)
  month = (under_ten | ten_to_twelve).capture(:month)
  day = (under_ten | ten_and_under_thirty | thirties).capture(:day)

  date = (year + delim + month + delim + day).all

Although it is more code, the individual pieces are smaller and
easier to independently verify. As an additional bonus, the capture
groups can be retrieved by name:

  result = date.match("2009-01-23")
  result[:year]      # => "2009"
  result[:month]     # => "01"
  result[:day]       # => "23"


This document describes Re version 0.0.6.


  include Re

  number = re.any("0-9").all
  if number =~ string
    puts "Matches!"
    puts "No Match"


Simple Examples

  re("a")                -- matches "a"
  re("a") + re("b")      -- matches "ab"
  re("a") | re("b")      -- matches "a" or "b"
  re("a").many           -- matches "", "a", "aaaaaa"
  re("a").one_or_more    -- matches "a", "aaaaaa", but not ""
  re("a").optional       -- matches "" or "a"
  re("a").all            -- matches "a", but not "xab"

See Re::Rexp for a complete list of expressions.

Using re without an argument allows access to a number of common
regular expression constants. For example: / re.spaces  -- matches " ", "\n" or "\t"
  re.digit / re.digits  -- matches a digit / sequence of digits

Also, re without arguments can also be used to construct character

  re.any                -- Matches any charactor
  re.any("abc")         -- Matches "a", "b", or "c"
  re.any("0-9")         -- Matches the digits 0 through 9
  re.any("A-Z", "a-z", "0-9", "_")
                        -- Matches alphanumeric or an underscore

See Re::ConstructionMethods for a complete list of common constants
and character class functions.

See, Re::Rexp, and Re::ConstructionMethods for details.

regexml Example

Regexml is an XML based language to express regular expressions.
Here is their example for matching URLs.

    <regexml xmlns="">
        <expression id="url">
            <match equals="[A-Za-z]" max="*" capture="true"/> <!-- scheme (e.g., http) -->
            <match equals=":"/>
            <match equals="//" min="0"/> <!-- mailto: and news: URLs do not require forward slashes -->
            <match equals="[0-9.\-A-Za-z@]" max="*" capture="true"/> <!-- domain (e.g., -->
            <group min="0">
                <match equals=":"/>
                <match equals="\d" max="5" capture="true"/> <!-- port number -->
            <group min="0" capture="true"> <!-- resource (e.g., /sample/resource) -->
                <match equals="/"/>
                <match except="[?#]" max="*"/>
            <group min="0">
                <match equals="?"/>
                <match except="#" min="0" max="*" capture="true"/> <!-- query string -->
            <group min="0">
                <match equals="#"/>
                <match equals="." min="0" max="*" capture="true"/> <!-- anchor tag -->

Here is the Re expression to match URLs:

      re.any("A-Z", "a-z").one_or_more.capture(:scheme) +
      re(":") +
      re("//").optional +
      re.any("0-9", "A-Z", "a-z", "-@.").one_or_more.capture(:host) +
      (re(":") + re.digit.repeat(1,5).capture(:port)).optional +
      (re("/") + re.none("?#").many).capture(:path).optional +
      (re("?") + re.none("#").many.capture(:query)).optional +
      (re("#") + re.any.many.capture(:anchor)).optional



We should say a word or two about performance.

First of all, building regular expressions using Re is slow. If you
use Re to build regular expressions, you are encouraged to build the
regular expression once and reuse it as needed. This means you
won’t do a lot of inline expressions using Re, but rather assign the
generated Re regular expression to a constant. For example:

  PHONE_RE = re.digit.repeat(3).capture(:area) +
               re("-") +
               re.digit.repeat(3).capture(:exchange) +
               re("-") +

Alternatively, you can arrange for the regular expression to be
constructed only when actually needed. Something like:q

  def phone_re
    @phone_re ||= re.digit.repeat(3).capture(:area) +
                    re("-") +
                    re.digit.repeat(3).capture(:exchange) +
                    re("-") +

That method constructs the phone number regular expression once and
returns a cached value thereafter. Just make sure you put the
method in an object that is instantiated once (e.g. a class method).

When used in matching, Re regular expressions perform fairly well
compared to native regular expressions. The overhead is a small
number of extra method calls and the creation of a Re::Result object
to return the match results.

If regular expression performance is a premium in your application,
then you can still use Re to construct the regular expression and
extract the raw Ruby Regexp object to be used for the actual
matching. You lose the ability to use named capture groups easily,
but you get raw Ruby regular expression matching performance.

For example, if you wanted to use the raw regular expression from
PHONE_RE defined above, you could extract the regular expression
like this:


And then use it directly:

  if PHONE_REGEXP =~ string
    # blah blah blah

The above match runs at full Ruby matching speed. If you still
wanted named capture groups, you can something like this:

  match_data = PHONE_REGEXP.match(string)
  area_code = match_data[PHONE_RE.name_map[:area]]

License and Copyright

Copyright 2009 by Jim Weirich (
All rights Reserved.

Re is provided under the MIT open source license (see MIT-LICENSE)


Documentation ::
Source ::
GemCutter ::
Download ::
Bug Tracker ::
Continuous Integration ::!/jimweirich/re
Author ::