Ruby Tutorial

Overview

Before You Start

This tutorial assumes:

Ruby Tutorial Scenario

The Ruby Tutorial demonstrates how to use Komodo to write and debug a simple Ruby program which saves it's data in a YAML file. In this tutorial you will:

  1. Open the Ruby Tutorial Project.
  2. Analyze menagerie.rb the Ruby program included in the Tutorial Project.
  3. Run the program in Komodo.
  4. Debug the program using the Komodo debugger.

See Debugging Programs for more information on debugging in Komodo.

Opening the Tutorial Project

On the File menu, click Open|Project and select ruby_tutorial.kpf from <installdir>r\samples\ruby_tutorials. All files included in the tutorial project are displayed on the Projects tab in the Left Pane.

Overview of the Tutorial Files

The ruby_tutorial project contains:

Open the Ruby Tutorial File

On the Projects tab, double-click the menagerie.rb file. This file opens in the Editor Pane; a tab at the top of the pane displays the filename.

Analyzing the Ruby program

The menagerie.rb program is a simple interactive program that can add, list, and search for information about animals. It can also store this information in a YAML file (e.g. animals.yaml). It is essentially an extremely simple database with predefined fields.

Introduction

In this step, you will analyze the program in sections. Ensure that line numbers are enabled in Komodo (View|View Line Numbers) and that the file menagerie.rb is displayed in the Komodo editor.

Line 6 - Importing the YAML class

Komodo Tip: Notice that syntax elements are displayed in different colors. You can adjust the display options for language elements in the Preferences dialog box.

Line 8 to 13 - Define and Initialize the Entry class

The Entry class contains variables which hold data for individual entries in our simple database, and the behavior of that data. Information about each animal in our menagerie will be contained in an Entry class object.

These variables need to be private (instance variables) rather than global because there will be an instance of the Entry class for each animal in the menagerie.

Line 15 - Expose instance variables

Line 18 to 26 - Data Storage Methods

Komodo Tip: Click on the minus symbol to the left of line 18. The section of code for the sci_name method is collapsed. Doing this at line 8 collapses the entire Entry class. This is called Code Folding.

Line 28 to 35 - Data Behavior Methods

Line 39 to 46 - Command Help

Line 48 to 55 - Define and Initialize the Menagerie class

The Menagerie class contains the @menagerie hash: the container which holds the multiple instances of the Entry class. It also contains all the methods available to the user of the application (via the command interface starting at line 154.

The name of the animal is stored as a key in the @menagerie hash. It references the Entry object which contains the rest of the information, namely the scientific name (sci_name) and description (descr). All the information we store on each animal is kept in two separate areas -- the @menagerie key and the Entry it points to.

Line 57 to 69 - Adding Entries

Exercise: After completing the tutorial, come back to this section and try writing a more "user friendly" version of this cmd_add method which asks for the name, scientific name and description separately (i.e. one at a time).

Line 74 to 88 - Searching for Entries

Line 90 to 98 - Deleting Entries

Line 100 to 102 - Listing Entries

Line 104 to 133 - Saving to a File

Line 135 to 143 - Loading from a File

Line 145 to 149 - Showing Help

Line 151 - Starting the Program

Line 153 to 180 - Handling Commands from the User

The program needs a way to handle input from the user. This section deals with parsing input and splitting it into commands which call methods in the Menagerie class, and arguments for those methods.

Running the Program

In this step you will run the program and interact with it.

  1. To run menagerie.rb without debugging: Select Debug|Go/Continue. The program interface displays in the Command Output tab. Try various commands to test the program.
  2. In the Command Output tab, enter various commands to test the program.
  3. Enter the following commands:

The output of the last command (including "Error: undefined method...") indicates that something is not working correctly. Debugging can help trace this problem. Type quit in the Output window before starting the debugger.

Debugging the Program

In this step you will add breakpoints to the program and "debug" it. Adding breakpoints lets you run the program in sections, making it easier to watch variables and view the output as it is generated.

Breakpoints are used to identify exactly where a program may be having problems. A bug has been intentionally left in the cmd_delete method which can illustrate this.

  1. Set a breakpoint: On the menagerie.rb tab, click on the gray margin immediately to the left of the code on line 93 of the program. This sets a breakpoint, indicated by a red circle.
  2. Run the debugger: Select Debug|Go/Continue (or enter 'F5', or use the Debug Toolbar). The Debugging Options dialog box will then pop up; press the Return key or OK button to dismiss it. You can pass program options to the program with the Script Arguments text box, but this particular program doesn't take any.
  3. Enter commands: In the Command Output tab, re-enter the commands from the Running the Program section ('load animals.yaml', 'list', and 'delete Komodo dragon').

Komodo Tip: Debugger commands can be accessed from the Debug menu, by shortcut keys, or from the Debug Toolbar. For a summary of debugger commands, see the Debugger Command List.

  1. Watch the debug process: After the last command, notice that a yellow arrow appears where breakpoint is set (line 93). This arrow indicates the position at which the debugger has halted. This tells us that our command did match a key in @menagerie.
  2. Check the relevant variables: Click on the Self tab to see the current object's instance and class variables. Notice the @menagerie hash. Expand the view of the hash by clicking the plus symbol next to it. It should only contain the "Leopard gecko" entry after the "Komodo dragon" entry has been deleted.
  3. Set a Watch variable: Select the Watch tab of the debugger window, highlight '@menagerie.has_key?(name))' on line 92 and drag it into the Watch tab. You can place most valid Ruby expressions in this area, including assignments, whether they're in the program or not. For example, placing the expression 'x = 2 + 2' in the Watch tab will show that a local variable called 'x' is set to 4.

Komodo Tip: What do the debugger commands do?

  • Step In: Executes the current line of code and pauses at the following line.
  • Step Over: Executes the current line of code. If the line of code calls a function or method, the function or method is executed in the background and the debugger pauses at the line that follows the original line.
  • Step Out: When the debugger is within a function or method, Step Out executes the code without stepping through the code line-by-line. The debugger stops on the line of code following the function or method call in the calling program.
  1. Step In: Select Debug|Step In until the debugger stops at line 166 (print status_message). "Step In" is a debugger command that causes the debugger to enter a function called from the current line.
  2. View local variable: On the Debug tab, click the Locals tab. Examine the status_message variable. This variable contains the message that will be returned to the user.
  3. Run the debugger: Select Debug|Go/Continue (or enter 'F5', or use the Debug Toolbar). The command returns "#<Entry:0x83096f8>Error: undefined method `[]' for #<Entry:0x83096f8>" which is not a very user-friendly message. The cmd_delete method is missing an explicit return value to provide if the deletion was successful.
  4. Fix the problem: On the Debug menu, click Stop (or use the Stop button on the Debug Toolbar). Uncomment line 94 by removing the "#".
  5. Disable and Delete a breakpoint: Click on the red breakpoint at line 93. The red breakpoint is now white with a red outline. This breakpoint is now disabled. Click on the disabled white breakpoint. This removes the breakpoint.
  6. Run the debugger: Select Debug|Go/Continue and re-run the commands used previously ('load animals.yaml', 'list', and 'delete Komodo dragon'). The 'delete' command now returns the message "Deleted".

More Ruby Resources

Tutorials and Reference Sites

There are many Ruby tutorials and beginner Ruby sites on the Internet, including: