notebooks/Exceptions.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "injured-revelation",
   "metadata": {},
   "source": [
    "# Exceptions in Ruby\n",
    "\n",
    "An _exception_ is a special kind of object, an instance of the class `Exception` or a descendant of that class that represents some kind of exceptional condition; it indicates that something has gone wrong. When this occurs, an exception is raised (or thrown).\n",
    "\n",
    "By default, Ruby programs terminate when an exception occurs. But it is possible to declare exception handlers. An exception handler is a block of code that is executed if an exception occurs during the execution of some other block of code. _Raising_ an exception means stopping normal execution of the program and transferring the flow-of-control to the exception handling code where you either deal with the problem that's been encountered or exit the program completely. Which of these happens - dealing with it or aborting the program - depends on whether you have provided a `rescue` clause (`rescue` is a fundamental part of the Ruby language). If you haven't provided such a clause, the program terminates; if you have, control flows to the `rescue` clause.\n",
    "\n",
    "Ruby has some predefined classes - [`Exception`](https://ruby-doc.org/core-3.0.0/Exception.html) and its children - that help you to handle errors that can occur in your program. The following list shows the Ruby exception hierarchy.\n",
    "\n",
    "- `Exception`\n",
    "  - `fatal` used internally by Ruby\n",
    "  - `NoMemoryError`\n",
    "  - `ScriptError`\n",
    "    - `LoadError`\n",
    "    - `NotImplementedError`\n",
    "    - `SyntaxError`\n",
    "  - `SecurityError`\n",
    "  - `SignalException`\n",
    "    - `Interrupt`\n",
    "  - `StandardError`\n",
    "    - `ArgumentError`\n",
    "    - `FiberError`\n",
    "    - `IndexError`\n",
    "      - `KeyError`\n",
    "      - `StopIteration`\n",
    "    - `IOError`\n",
    "      - `EOFError`\n",
    "    - `LocalJumpError`\n",
    "    - `NameError`\n",
    "      - `NoMethodError`\n",
    "    - `RangeError`\n",
    "      - `FloatDomainError`\n",
    "    - `RegexpError`\n",
    "    - `RuntimeError`\n",
    "    - `SystemCallError`\n",
    "      - system-dependent exceptions (`Errno::xxx`)\n",
    "    - `ThreadError`\n",
    "    - `TypeError`\n",
    "    - `ZeroDivisionError`\n",
    "  - `SystemExit`\n",
    "  - `SystemStackError`\n",
    "  \n",
    "The chart above shows that most of the subclasses extend a class known as `StandardError`. These are the \"normal\" exceptions that typical Ruby programs try to handle. The other exceptions represent lower-level, more serious, or less recoverable conditions, and normal Ruby programs do not typically attempt to handle them.\n",
    "\n",
    "The following method raises an exception whenever it's called. Its second message will never be printed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "blank-carrier",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "I am before the raise.\n"
     ]
    },
    {
     "ename": "RuntimeError",
     "evalue": "An error has ocurred",
     "output_type": "error",
     "traceback": [
      "\u001b[31mRuntimeError\u001b[0m: An error has ocurred",
      "(eval):3:in `raise_exception'",
      "(eval):7:in `<main>'"
     ]
    }
   ],
   "source": [
    "def raise_exception\n",
    "  puts 'I am before the raise.'\n",
    "  raise 'An error has ocurred'\n",
    "  puts 'I am after the raise.'\n",
    "end\n",
    "\n",
    "raise_exception"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "sunrise-occasions",
   "metadata": {},
   "source": [
    "The `raise` method is from the `Kernel` module. By default, `raise` creates an exception of the `RuntimeError` class.\n",
    "\n",
    "To raise an exception of a specific class, you can pass in the class name as an argument to `raise`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "delayed-fiction",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0.5\n"
     ]
    },
    {
     "ename": "ArgumentError",
     "evalue": "Argument is not numeric",
     "output_type": "error",
     "traceback": [
      "\u001b[31mArgumentError\u001b[0m: Argument is not numeric",
      "(eval):2:in `inverse'",
      "(eval):7:in `<main>'"
     ]
    }
   ],
   "source": [
    "def inverse(x)\n",
    "  raise ArgumentError, 'Argument is not numeric' unless x.is_a? Numeric\n",
    "  1.0 / x\n",
    "end\n",
    "\n",
    "puts inverse(2)\n",
    "puts inverse('not a number')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "flexible-kennedy",
   "metadata": {},
   "source": [
    "Remember, methods that act as queries are often named with a trailing `?`. `is_a?` is a method in the `Object` class and returns `true` or `false`. The `unless` modifier when tracked at the end of a normal statement means execute the preceding expression unless condition is `true`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "recovered-automation",
   "metadata": {},
   "source": [
    "## Defining new exception classes\n",
    "\n",
    "Defining new exception classes to be even more specific about an error, you can define your own `Exception` subclass:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "young-balance",
   "metadata": {},
   "outputs": [],
   "source": [
    "class NotInvertibleError < StandardError\n",
    "end"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cheap-effect",
   "metadata": {},
   "source": [
    "## Handling an Exception\n",
    "\n",
    "To do exception handling, we enclose the code that could raise an exception in a `begin-end` block and use one or more `rescue` clauses to tell Ruby the types of exceptions we want to handle. It is to be noted that the body of a method definition is an implicit `begin-end` block; the `begin` is omitted, and the entire body of the method is subject to exception handling, ending with the `end` of the method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "athletic-johnson",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "I am before the raise.\n",
      "I am rescued.\n",
      "I am after the begin block.\n"
     ]
    }
   ],
   "source": [
    "def raise_and_rescue\n",
    "  begin\n",
    "    puts 'I am before the raise.'\n",
    "    raise 'An error has ocurred'\n",
    "    puts 'I am after the raise.'\n",
    "  rescue\n",
    "    puts 'I am rescued.'\n",
    "  end\n",
    "  puts 'I am after the begin block.'\n",
    "end\n",
    "\n",
    "raise_and_rescue"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "active-consultation",
   "metadata": {},
   "source": [
    "Observe that the code interrupted by the exception never gets run. Once the exception is handled, execution continues immediately after the `begin` block that spawned it.\n",
    "\n",
    "If you write a `rescue` clause with no parameter list, the parameter defaults to `StandardError`. Each `rescue` clause can specify multiple exceptions to catch. At the end of each `rescue` clause you can give Ruby the name of a local variable to receive the matched exception. The parameters to the `rescue` can also be arbitrary expressions (including method calls) that return an `Exception` class. If we use `raise` with no parameters, it re-raises the exception.\n",
    "\n",
    "You can stack `rescue` clauses in a `begin-rescue` block. Exceptions not handled by one `rescue` clause will trickle down to the next:\n",
    "\n",
    "```ruby\n",
    "begin\n",
    "  # -\n",
    "rescue OneTypeOfException\n",
    "  # -\n",
    "rescue AnotherTypeOfException\n",
    "  # -\n",
    "else\n",
    "  # No exceptions\n",
    "end\n",
    "```\n",
    "\n",
    "For each `rescue` clause in the `begin` block, Ruby compares the raised exception against each of the parameters in turn. The match will succeed if the exception named in the `rescue` clause is the same as the type of the currently thrown exception, or is a super-class of that exception.\n",
    "\n",
    "The code in an `else` clause is executed if the code in the body of the `begin` statement runs to completion _without_ exceptions. If an exception occurs, then the `else` clause will obviously not be executed. The use of an `else` clause is not particularly common in Ruby.\n",
    "\n",
    "If you want to interrogate a rescued exception, you can map the exception (we are using the exception `StandardError` below) object to a variable within the `rescue` clause."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "ordered-foster",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "A test exception\n",
      "[\"(eval):2:in `<main>'\", \"/usr/local/lib/ruby/gems/3.0.0/gems/iruby-0.4.0/lib/iruby/backend.rb:44:in `eval'\", \"/usr/local/lib/ruby/gems/3.0.0/gems/iruby-0.4.0/lib/iruby/backend.rb:44:in `eval'\", \"/usr/local/lib/ruby/gems/3.0.0/gems/iruby-0.4.0/lib/iruby/backend.rb:12:in `eval'\", \"/usr/local/lib/ruby/gems/3.0.0/gems/iruby-0.4.0/lib/iruby/kernel.rb:90:in `execute_request'\", \"/usr/local/lib/ruby/gems/3.0.0/gems/iruby-0.4.0/lib/iruby/kernel.rb:49:in `dispatch'\", \"/usr/local/lib/ruby/gems/3.0.0/gems/iruby-0.4.0/lib/iruby/kernel.rb:38:in `run'\", \"/usr/local/lib/ruby/gems/3.0.0/gems/iruby-0.4.0/lib/iruby/command.rb:110:in `run_kernel'\", \"/usr/local/lib/ruby/gems/3.0.0/gems/iruby-0.4.0/lib/iruby/command.rb:40:in `run'\", \"/usr/local/lib/ruby/gems/3.0.0/gems/iruby-0.4.0/bin/iruby:5:in `<top (required)>'\", \"/usr/local/lib/ruby/gems/3.0.0/bin/iruby:23:in `load'\", \"/usr/local/lib/ruby/gems/3.0.0/bin/iruby:23:in `<main>'\"]\n"
     ]
    }
   ],
   "source": [
    "begin\n",
    "  raise 'A test exception'\n",
    "rescue StandardError => e\n",
    "  puts e.message\n",
    "  puts e.backtrace.inspect\n",
    "end"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "offensive-electron",
   "metadata": {},
   "source": [
    "The `Exception` class defines two methods that return details about the exception.\n",
    "\n",
    "- The `message` method returns a string that may provide human-readable details about what went wrong.\n",
    "- The other important method is `backtrace`. This method returns an array of strings that represent the call stack at the point that the exception was raised.\n",
    "\n",
    "If you need the guarantee that some processing is done at the end of a block of code, regardless of whether an exception was raised then the `ensure` clause can be used. `ensure` goes after the last `rescue` clause and contains a chunk of code that will always be executed as the block terminates. The `ensure` blick will always run.\n",
    "\n",
    "Some common exceptions are:\n",
    "\n",
    "`RuntimeError` (this is the default exception raised by the raise method), `StandardError`, `NoMethodError`, `NameError`, `IOError`, `TypeError` and `ArgumentError`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "sophisticated-occurrence",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "#!/usr/bin/env ruby\n",
      "\n",
      "\n",
      "\n",
      "class Dog\n",
      "\n",
      "  def initialize(breed, name)\n",
      "\n",
      "    # Instance variables\n",
      "\n",
      "    @breed = breed\n",
      "\n",
      "    @name = name\n",
      "\n",
      "  end\n",
      "\n",
      "\n",
      "\n",
      "  def bark\n",
      "\n",
      "    puts 'Ruff! Ruff!'\n",
      "\n",
      "  end\n",
      "\n",
      "\n",
      "\n",
      "  def display\n",
      "\n",
      "    puts \"I am of #{@breed} breed and my name is #{@name}\"\n",
      "\n",
      "  end\n",
      "\n",
      "end\n",
      "\n",
      "\n",
      "\n",
      "Created new file at: /var/folders/w5/hj46np3122z1rghzzdhmyp_h0000gn/T/test.rb20210516-17306-qn0tzh\n"
     ]
    }
   ],
   "source": [
    "require 'tempfile'\n",
    "\n",
    "# Open and read from a text file\n",
    "# Note that since a block is given, file will automatically be closed when the block terminates\n",
    "begin\n",
    "  File.open('assets/dog.rb', 'r') do |f1|\n",
    "    while line = f1.gets\n",
    "      puts line\n",
    "    end\n",
    "  end\n",
    "  \n",
    "  # Create a new file and write to it\n",
    "  f2 = Tempfile.new('test.rb')\n",
    "  f2.puts \"Created by Carlos Álvaro\\nThanks for reading this tutorial!\"\n",
    "  f2.close\n",
    "  puts \"Created new file at: #{f2.path}\"\n",
    "rescue StandardError => e\n",
    "  puts e\n",
    "end"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "gentle-divorce",
   "metadata": {},
   "source": [
    "> Improper error messages can provide critical information about an application which may aid an attacker in exploiting the application. The most common problem occurs when detailed internal error messages such as stack traces, database dumps, and error codes are displayed to the user. Security analysts view logging and error handling as potential areas of risk. It is recommended that production applications should not use, for example, a `puts e.backtrace.inspect` call unless it is being directly committed into a log that is not viewable to the end user."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bigger-queens",
   "metadata": {},
   "source": [
    "## Validation example\n",
    "\n",
    "Here's an example from the `Ruby Cookbook`, showing how one can do validation of user's inputs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "ordinary-palestine",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Carlos\n",
      "Carlos Álvaro\n"
     ]
    }
   ],
   "source": [
    "class Name\n",
    "  # Define default getter methods, but not setter methods.\n",
    "  attr_reader :first, :last\n",
    "  \n",
    "  # When someone tries to set a first name, enforce rules about it.\n",
    "  def first=(first)\n",
    "    if first.nil? or first.strip.empty?\n",
    "      raise ArgumentError.new 'Everyone must have a first name.'\n",
    "    end\n",
    "    first = first.dup\n",
    "    first[0] = first[0].chr.capitalize\n",
    "    @first = first\n",
    "  end\n",
    "  \n",
    "  # When someone tries to set a last name, enforce rules about it.\n",
    "  def last=(last)\n",
    "    if last == nil or last.size == 0\n",
    "      raise ArgumentError.new 'Everyone must have a last name.'\n",
    "    end\n",
    "    @last = last\n",
    "  end\n",
    "  \n",
    "  def full_name\n",
    "    \"#{@first} #{@last}\"\n",
    "  end\n",
    "  \n",
    "  # Delegate to the setter methods instead of setting the instance\n",
    "  # variables directly.\n",
    "  def initialize(first, last)\n",
    "    self.first = first\n",
    "    self.last = last\n",
    "  end\n",
    "end\n",
    "\n",
    "carlos = Name.new('Carlos', 'Álvaro')\n",
    "puts carlos.first\n",
    "puts carlos.full_name"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "useful-wednesday",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Kevin Haag\n",
      "Kevin\n"
     ]
    },
    {
     "ename": "ArgumentError",
     "evalue": "Everyone must have a first name.",
     "output_type": "error",
     "traceback": [
      "\u001b[31mArgumentError\u001b[0m: Everyone must have a first name.",
      "(eval):8:in `first='",
      "(eval):7:in `<main>'"
     ]
    }
   ],
   "source": [
    "kevin = Name.new('kevin', 'Haag')\n",
    "puts kevin.full_name\n",
    "\n",
    "kevin.first = 'kevin'\n",
    "puts kevin.first\n",
    "\n",
    "kevin.first = nil"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "possible-dress",
   "metadata": {},
   "outputs": [
    {
     "ename": "ArgumentError",
     "evalue": "Everyone must have a last name.",
     "output_type": "error",
     "traceback": [
      "\u001b[31mArgumentError\u001b[0m: Everyone must have a last name.",
      "(eval):18:in `last='",
      "(eval):31:in `initialize'",
      "(eval):1:in `new'",
      "(eval):1:in `<main>'"
     ]
    }
   ],
   "source": [
    "Name.new('Jaime', nil)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "sharing-receipt",
   "metadata": {},
   "source": [
    "The `Name` class keeps track of people's first and last names. It uses setter methods to enforce two somewhat parochial rules: everyone must have both a first and a last name, and everyone's first name must begin with a capital letter.\n",
    "\n",
    "The `Name` class has been written in such a way, that the rules are enforced both in the constructor and after the object has been created. Sometimes you don't trust the data coming in through the setter methods. That's when you can define your own methods to stop bad data before it infects your objects.\n",
    "\n",
    "Within a class, you have direct access to the instance variables. You can simply assign to an instance variable and the setter method won't be triggered. If you do want to trigger the setter method, you'll have to call it explicitly.\n",
    "\n",
    "Note how, in the `Name#initialize` method above, we call the `first=` and `last=` methods instead of assigning to `@first` and `@last`. This makes sure the validation code gets run for the initial values of every `Name` object.\n",
    "\n",
    "We can't just say `first = first`, because `first` is a variable name in that method."
   ]
  }
 ],
 "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
}