notebooks/RegularExpressions.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "turned-tourism",
   "metadata": {},
   "source": [
    "# Regular Expressions in Ruby\n",
    "\n",
    "Regular expressions, though cryptic, is a powerful tool for worjing with text. Ruby has this feature built-in. It's used for pattern-matching and text processing.\n",
    "\n",
    "Many people find regular expressions difficult to use, difficult to read, un-maintainable, and ultimately couterproductive. You may end up using only a modest number of regular expressions in your Ruby and Rails applications. Becoming recular expressions wizard isn't a prerequisite for Rails programming. _However, it's advisable to learn at least the basics of how regular expressions work_.\n",
    "\n",
    "**A regular expression is simply a way of specifying a pattern of characters to be matched in a string**. In Ruby, you tipically create a regular expression by writting a pattern between slash characters ('/pattern/').\n",
    "\n",
    "In Ruby, regular expressions are objects (of type `Regexp`) and can be manipulated as such. `//` is a regular expression and an instance of the `Regexp` class, as shown bellow."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "biblical-basin",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Regexp"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "//.class"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "stuck-holmes",
   "metadata": {},
   "source": [
    "You could write a pattern that matches a string containing the text Pune or the text Ruby using the following regular expression:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "generic-yorkshire",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "/Pune|Ruby/"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "/Pune|Ruby/"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "incident-demand",
   "metadata": {},
   "source": [
    "The forward slashes delimit the pattern, which consists of the two things we are matching, separated by a pipe character (`|`). The pipe character means \"either the thing on the right or the thing on the left\", in this case _Pune or Ruby_.\n",
    "\n",
    "The simplest way to find out whether there's a match between a pattern and a string is with the `match` method. You can do this in either direction: Regular expression objects and string objects both responds to `match`. If there's no match, you get back `nil`. If there's a match, it returns an instance of the class `MatchData`. We can also use the match operator `=~` to match a string against a regular expression. If the pattern is found in the string, `=~` returns its starting position, otherwise it returns `nil`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "directed-brick",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "MatchData\n",
      "14\n"
     ]
    }
   ],
   "source": [
    "m1 = /Ruby/.match(\"The future is Ruby\")\n",
    "puts m1.class\n",
    "\n",
    "m2 = \"The future is Ruby\" =~ /Ruby/\n",
    "puts m2"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "outdoor-victory",
   "metadata": {},
   "source": [
    "The possible components of a regular expression include the following:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "metropolitan-wichita",
   "metadata": {},
   "source": [
    "## Literal characters\n",
    "\n",
    "Any literal character you put in a regular expression matches _itself_ in the string.\n",
    "\n",
    "```ruby\n",
    "/a/\n",
    "```\n",
    "\n",
    "This regular expression matches the string \"a\", as well as any string containing the letter \"a\".\n",
    "\n",
    "Some characters have special meanings to the regexp parser. When you want to match one of these special characters as itself, you have to scape it with a backslash (`\\`). For example, to match the character `?` (question mark), you have to write this:\n",
    "\n",
    "```ruby\n",
    "/\\?/\n",
    "```\n",
    "\n",
    "The backslash means \"don't treat the next character as special; treat it as itself\".\n",
    "\n",
    "The special characters include `^`, `$`, `?`, `.`, `/`, `[`, `]`, `{`, `}`, `(`, `)`, `+` and `*`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "jewish-copper",
   "metadata": {},
   "source": [
    "## The wildcard character `.` (dot)\n",
    "\n",
    "Sometimes you'll want to match any character at some point in your pattern. You do this with the special wildcard character `.` (dot). A dot matches any character with the exception of a newline. This regular expression:\n",
    "\n",
    "```ruby\n",
    "/.ejected/\n",
    "```\n",
    "\n",
    "matches both \"dejected\" and \"rejected\". It also matches \"%ejected\" and \"8ejected\". The wildcard dot is handy, but sometimes it gives you more matches than you want. However, you can impose constrains on matches while still allowing for multiple possible strings, using _character classes_."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "raised-parameter",
   "metadata": {},
   "source": [
    "## Character classes\n",
    "\n",
    "A character class is an explicit list of characters, placed inside the regular expression in square brackets:\n",
    "\n",
    "```ruby\n",
    "/[dr]ejected/\n",
    "```\n",
    "\n",
    "This means \"match either d or r, followed by ejected\". This new pattern matches either \"dejected\" or \"rejected\" but not \"&ejected\". A character class is a kind of quasi-wildcard: It allows for multiple possible characters, but only a limited number of them.\n",
    "\n",
    "Inside a character class, you can also insert a range of characters. A common case is this, for lowercase letters:\n",
    "\n",
    "```ruby\n",
    "/[a-z]/\n",
    "```\n",
    "\n",
    "To match a hexadecimal digit, you might use several ranges inside a character class:\n",
    "\n",
    "```ruby\n",
    "/[^A-Fa-f0-9]/\n",
    "```\n",
    "\n",
    "Some characters classes are so common that they have special abbreviations."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "competent-table",
   "metadata": {},
   "source": [
    "## Special escape sequences for common character classes\n",
    "\n",
    "To match any digit, you can do this:\n",
    "\n",
    "```ruby\n",
    "/[0-9]/\n",
    "```\n",
    "\n",
    "But you can also accomplish the same thing more concisely with the special escape sequence `\\d`:\n",
    "\n",
    "```ruby\n",
    "/\\d/\n",
    "```\n",
    "\n",
    "Two other useful escape sequences for predefined character classes are these:\n",
    "\n",
    "- `\\w` matches any digit, alphabetical character, or underscore(`_`).\n",
    "- `\\s` matches any whitespace character (space, tab, newline).\n",
    "\n",
    "Each of these predefined character classes also has a negated form. You can match _any character that is not a digit_ by doing this:\n",
    "\n",
    "```ruby\n",
    "/\\D/\n",
    "```\n",
    "\n",
    "Similarly, `\\W` matches _any character other than an alphanumeric character or underscore_, and `\\S` matches _any non-whitespace character_.\n",
    "\n",
    "A successful match returns a `MatchData` object.\n",
    "\n",
    "Every `match` operation either succeeds or fails. Let's start with the simpler case: failure. When you try to match a string to a pattern, and the string doesn't match, the result is always `nil`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "streaming-excuse",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "true"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "/a/.match(\"b\").nil?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "moving-restriction",
   "metadata": {},
   "source": [
    "This `nil` stands in for the false or no answer when you treat the match as a true/false test.\n",
    "\n",
    "Unlike `nil`, the `MatchData` object returned by a successful `match` has a Boolean value of true, which makes it handy for simple match/no-match tests. Beyond this, however, it also stores information about the match, which you can pry out of them with the appropiate methods: where the match began (at what character in the string), how much of the string is covered, what was captured in the parenthetical groups, and so forth.\n",
    "\n",
    "To use the `MatchData` object, you must first save it.\n",
    "\n",
    "Consider an example where we want to pluck a phone number from a string and save the various parts of it (area code, exchange, number) in groupings:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "coordinate-classroom",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The whole string we started with: My phone number is (123) 555-1234.\n",
      "The entire part of the string matched: (123) 555-1234\n",
      "The three captures:\n",
      "Capture #1: 123\n",
      "Capture #2: 555\n",
      "Capture #3: 1234\n",
      "Here's another way to get at the first capture:\n",
      "Capture #1: 123\n"
     ]
    }
   ],
   "source": [
    "string = \"My phone number is (123) 555-1234.\"\n",
    "phone_re = /\\((\\d{3})\\)\\s+(\\d{3})-(\\d{4})/\n",
    "m = phone_re.match(string)\n",
    "unless m\n",
    "  puts \"There was no match...\"\n",
    "  exit\n",
    "end\n",
    "print \"The whole string we started with: \"\n",
    "puts m.string\n",
    "print \"The entire part of the string matched: \"\n",
    "puts m[0]\n",
    "puts \"The three captures:\"\n",
    "3.times do |index|\n",
    "  puts \"Capture ##{index+1}: #{m.captures[index]}\"\n",
    "end\n",
    "puts \"Here's another way to get at the first capture:\"\n",
    "print \"Capture #1: \"\n",
    "puts m[1]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "competent-intellectual",
   "metadata": {},
   "source": [
    "In this code, we use the `string` method of `MatchData` (`puts m.string`) to get the entire string on which the `match` operation was performed.\n",
    "\n",
    "To get the part of the string that matched our pattern, we address the `MatchData` object with square brackets, with an index of 0 (`puts m[0]`).\n",
    "\n",
    "We also use the `times` method (`3.times do |index|`) to iterate exactly three times through a code block and print out submatches (the parenthetical captures) in succession. Inside that code block, a method called `captures` fishes out the substrings that matches the parenthesized parts of the pattern.\n",
    "\n",
    "Finally, we take another look at the first capture, this time through a different technique: indexing the `MatchData` object directly with square brackets and positive integers, each integer corresponding to a capture."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Ruby 3.0.0",
   "language": "ruby",
   "name": "ruby"
  },
  "language_info": {
   "file_extension": ".rb",
   "mimetype": "application/x-ruby",
   "name": "ruby",
   "version": "3.0.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}