IRT

Interactive Ruby Tools - Improved irb and rails console with a lot of easy and powerful tools.

What is IRT?

IRT is an improved irb / rails console (for rails 2 and 3) that adds a lot of features to the standard irb. If you use IRT in place of irb, you will have all the regular irb/rails console features, plus a lot of tools that will make your life a lot easier.

Powerful and easy

• clean colored output for easy reading
• 3 types of sessions: interactive, inspecting and binding
• irb/irt opening from your code (or erb templates) as a binding session
• irb/irt opening from inside the Rails Server window
• optional colored Rails log in the console
• contextual ri doc with completion
• recording of session steps with filtering
• easy testing based on recorded steps
• easy in place opening of backtraced files
• in place editing of objects and files with syntax highlight
• visual comparing tool, navigation and inspecting aids
• system and session shortcuts... and much more

Testing made easy

IRT records all the steps of your interactive session with irb (or rails console), and can re-run them as tests. In practice, if you use IRT properly, when you are done with your code, you are done with your tests.

Fixing made easy

Don't you feel frustrated when a traditional test fails, printing a bunch of stuff difficult to distinguish, and showing NOTHING about the test code that produced the failure?

When something fails IRT assumes that you don't want just to know that something went wrong, but that you actually want to fix it! IRT assumes that...

• you want to know exactly what are the resulting diffs
• you want to look at the code that failed without having to search for it
• you want to play with it IMMEDIATELY in an interactive session, right in the context of the failure
• you want to eventually edit and possibly fix it, right in the console
• you want to rerun the fix right away, without waiting for the end of the whole suite

Try the Tutorial first!

You can have a quick enlightening look (with a lot of screenshots) by reading the IRT Tutorial first, then if you want more details you can read this documentation.

Installation

$ [sudo] gem install irt

Executable Usage

$ irt --help

Command/Directives Usage

>> irt_help         # in an irt session

Colored and Styled Output

This is a nice feature, enabled by default in the terminals that support it, that is really helpful to visually catch what you need in the mess of the terminal input/output.

IRT uses colors consistently, so you will have an instant feedback about what a text or a label is referring to.

• cyan for files, saved values (and object 'a' in a diff)
• magenta for interactive sessions
• black/white for generic stdin/stdout and inspecting sessions (e.g. 'irt my_obj')
• blue for the Virtual Log, Rails Log and generic labels
• yellow for result echo (not setting last value), for binding sessions and for tests with diffs
• green for result echo (setting last value) (and object 'b' in a diff)
• red for errors, exceptions and rerun

Besides IRT is using reversed and bold styles to compose a more readable/graphical output.

ANSI colors for Windoze

The Windoze shell does not support ANSI escape codes natively, so if dumping Windoze is a luxury that you cannot afford, you could use another shell (e.g. the bash that comes with git for windows works), or you can enable it unless you are running Windows 7 (which has still no known ANSI support at the moment of this writing).

If you want to enable it there is an official Microsoft page about that matter, or you can eventually find useful this simple tutorial.

ANSI colors on jruby

You should use the IRT.force_color(true) and IRT.force_tty(true) options in the ~/.irtrc file in order to see colors when you use jruby.

Sessions / Modes

There are 4 irt modes / session types: file, interactive, inspect, binding.

File Mode (cyan)

IRT always start in file mode, which simply means that it will execute the code in a file. Indeed you launch irt passing a path argument of one or more existing files or dirs. If any path does not refer to any existing file, irt will ask you to confirm that you want to create that file. Eventually if you don't pass any path argument, irt will create a temporary one-empty-line file.

Notice: When you pass a dir as the path, irt will recursively execute all the '.irt' files in it, so suffixing with '.irt' the files is not just a convention. It allows to skip any non .irt file, like libraries or files used with the 'insert_file' directive.

Note about new files

The new created files are implicitly run with the -i (--interative-eol) flag by default. That flag instruct irt to open an interactive session at the end of the file, so you will have the possibilty to add your statements. As long as you rerun the file (with the 'rr' command) IRT will remember the flag, anyway, if the session ends and you have to re-launch it from the command line, you must pass the -i flag explicitly or no interactive session will be opened automatically.

You can save any running file as another file with the 'save_as' command.

Interactive Sessions (magenta)

IRT opens an interactive session when you manually add the 'irt' directive in an irt file, or automatically, when an exception is raised or when a test has some diffs (fails).

The interactive session retains all the variables and the last returned value at the last evalued line, so you have the possibility to play with your variables and methods, inspect, try and fix what you want, and specially use the irt commands to manage your environment.

When you close an interactive session with 'exit' (or 'x' or 'q'), IRT will continue to run the file from the point it left, retaining also the variables you eventually changed or added, passing back also the last value. (In practice it's like everything happened in the session has happened in the file).

Inspecting Sessions (black/white)

You can open an inspecting session with the command 'irt <obj>'. The 'self' of the new session will be the <obj> itself, so you can inspect it as you would be in its definition class.

When you close the session with 'exit' (or 'x' or 'q'), IRT will not pass back anything from the inspecting session.

Binding Sessions (yellow)

You can open a binding session from any file with the directive 'irt binding': you don't even need to use the IRT executable. It works also from the rails code, while the server is running. (See Rails)

The 'self' of the new session will be the 'self' at the line you called it, so you can play with local variables and methods as you would do it at that line.

If you use 'nano', 'emacs' or 'vi' in a binding session you will open the file that contains the 'irt binding' call at that line: very handy to edit your code in place.

When you close the session with 'exit' (or 'x' or 'q'), IRT will not pass back anything from the binding session.

Virtual Log

The Virtual Log is a special filtered-and-extended history of what has been executed at any given time. It records ALL the lines executed from a file till that moment, and all the RELEVANT steps you did in an interactive session (inspecting and binding sessions are ignored).

RELEVANT is anything that is changing something in the code you are executing (plus comments and blank lines used for description and formatting).

Filtered steps

If you are in an interactive session, make a typo and get an error, that's not relevant for your code so the typo and the error doesn't get recorded in the log.

When you just inspect a variable, using p, pp, ap, puts, y, ... or use any irt command... that are not relevant steps that you want to rerun the next time, so they don't get recorded in the log.

Also, if you are in an inspecting or binding session, that steps are not relevant for your tests, so they don't get recorded in the log.

Log Management

You can type 'log' (or simply 'l') to have the tail of your log, or type 'full_log' (or simply 'll') to see all the logged lines from the start.

The lines in the log are graphically grouped in differently colored hunks: cyan for file lines, magenta for interactive session lines.

The log contains the reference line numbers of the steps: notice that for interactive sessions they might not be continuous if some step has been filtered out. The numbers could also be repeated if some step has generated more lines, like it might happen with 'add_test' (or 'tt').

You can copy and save your last steps in a file to rerun later. You can use 'print_lines' (or 'pl') to print the last session lines without any added reference number, for easy copying, or if your system supports it you can use 'copy_lines' (or 'cl') and have them right in the clipboard, ready to paste. You can also do the same with all the session lines using 'print_all_lines' (or 'pll') or copy them all 'copy_all_lines' (or 'cll').

That 'pl'-copy or 'cl' plus the 'vi', 'nano' or 'emacs' irt command (or the 'cnn' and 'cvi' commands) are a very time saver combination. See the IRT Tutorial for details.

Testing

Unlike the traditional testing cycle, where you write your test before or after coding, IRT writes the tests for you DURING the coding: you will have just to copy and paste them into an irt file.

Adding a test is as easy as typing 'tt' (or 'add_test') in the console at any given time. When you type 'tt' irt serializes the current (la