Practical Ruby

An Integrated Development Enrivonment for Ruby

Last updates:

2002/05/10: added MFC Dlls to the download section
2002/05/09: Version 0.3.3, simple unit testing integration
2002/05/04: Version 0.2.2, bug fix release
2002/05/03: Version 0.2.1, operational editor.
2002/04/28: Version 0.1.0, 'proof of concept' release.

Content

Overview
Requirement
Licensing
Download
About version numbering
Compiling Project Ruby
Project Ruby Internal
Questions, comments and bugs reports

Overview

    Practical Ruby aims to be a fast evolving IDE for Ruby development. To provide fast evolution, most of Practical Ruby is itself written in Ruby.

    The source editor is build around Scintilla Edit Control , a very flexible source edit control. While the GUI core is written using MFC, most of the tasks are delegated to Ruby scripts. The Scintilla Edit Control has been made accessible from Ruby, with an interface making the control much easier to use than in C++.

    Commands (menu entry selection, toolbar button and keyboard shortcut) processing is also delegated to Ruby.

    Here are some screenshots showing some features: [~20Ko per image]
Bookmarks , Opposite brace highlighting , Brace mismatch , Folding , Unit test failure , Unit test sucess .

    Here is a list of the current features of the IDE:

Opposite braces and brace mismatch highlighting
Smart indent: indent or unindent a line after press Return (not perfect at the current time but handle the most common cases)
Bookmarks
Simple text case insensitive search
Syntax highlighting (flawed, does not recognize /regexp/, %r, %q, %Q at the current time)
Associates .rb files to Practical Ruby to open Practical Ruby from Explorer
Run script and capture output (crude at the current time)
Colorize test/unit output in console window

While at the current, Practical Ruby still have a long way to go to be called an IDE, here is a list of future I'd like to see integrated:

Better integration of Scintilla: auto completion, call tips,...
Dynamic menus: menus would be created from Ruby, removing the need to edit resource to add new commands
HTML Form as Dialog Box (using IE integration ?)
Project management facilities (a simple list of files, or a tree view ?)
Unit testing framework integration: jump to assertion failure (and automatic generation of the require all test files for test/unit)
???

Requirement

To run Practical Ruby

Operating system : Windows 9x/NT/2000...
MFC DLLs (available in the download section)
Ruby 1.6.7 (I'm using the ms-win32 version, which can be downloaded here . It should work with other version (?) )

To compile Practical Ruby from the sources

Compiler: Visual C++ 6.0 SP5.
Optional (a precompiled version is provided with the source): Scintilla Edit Control for Windows

Licensing

Practical Ruby is covered by the Gnu Public License .

Download

    To use Practical Ruby , you only need to download the binary. This documentation is included in source and binary distribution.

    The binary zip includes the executable and this documentation.
    The source zip includes Practical Ruby sources, this documentation, Scintilla Edit Control headers, documentation and precompiled DLL.

MFC DLL [~610Ko] : put them in the same directory as PracticalRuby.exe (or your system directory).

Practical Ruby 0.3.3 binary [~625Ko]
Practical Ruby 0.3.3 source code [~685Ko]

Practical Ruby 0.2.2 binary [~435Ko]
Practical Ruby 0.2.2 source code [~350Ko]

Practical Ruby 0.2.1 binary [~425Ko]
Practical Ruby 0.2.1 source code [~350Ko]

Practical Ruby 0.1.0 binary [~400Ko]
Practical Ruby 0.1.0 source code [~320Ko]

About version numbering

    The version number format is xx.yy.zz , where a change of :
    xx indicates a major architecture change,
    yy indicates that some functionnalities have been added, and
    zz indicates that some bugs have been fixed.

Compiling Practical Ruby

You must have Ruby 1.6.7 installed. A version can be downloaded here for windows
The path to the include and library files must be added in VC++. This can be done in the 'option/directories' tab. For Ruby 1.6.7 mswin32, both were in:
$ruby\lib\ruby\1.6\i586-mswin32, where $ruby is ruby top directory.
Open src/PraticalRuby/PraticalRuby.dsw in VC++
Make PraticalRuby the active project
Make 'Release' the active configuration
Compile and run

To compile the 'Debug' configuration, you need to compile ruby library with the Multithreaded Debug Dll runtime library. See ReadMe.txt notes which explains how to do that.

Practical Ruby Internal

In this section, Project Ruby internal are explained very shortly. Main components are: Ruby C++ wrapper, Ruby helpers, Scintilla ruby extensions, TraceDebug ruby extensions, GUI/Scintilla ruby integration, GUI/Commands ruby integration.

Ruby C++ Wrapper

CppRuby.h: a very simple object layer above ruby API. Helps getting clearer and more compact codes:
Object error = rb_gv_get("$!"); String backtrace = Array(error.methodCall( "backtrace" )).join( "\n\t" );
RubyCppTools.h/.cpp: the equivalent of rb_protect, but use functor instead function pointer. Allow more than one parameter to be passed. An exception handler is specified to handle ruby exception.
CppRubyExceptionHandler.h/.cpp: handles rb_protect failure. Handler provided: display dialog box with failure, trace to debug output, or to stderr.
GcCollectable.h/.cpp: the base class GcCollectableOwner is defined here. It should be inherit by all C++ that reference ruby object. Methods markCollectable() should be overridden to specify which object are referenced.

Ruby Helpers

RubyTools.h/.cpp: some helpers function to use ruby. Mainly works around VC++ non failure to cast function pointers.

Scintilla ruby extension

RubyExtScintilla.cpp/.h: implements ruby methods ScintillaBase#SendEditorMessage , class ScintillaNotification, a wrapper around Scintilla notification structure, and a helper function that forward a Scintilla notification to a given ruby object after wrapping it.

    Ruby script related to Scintilla are in script/scintilla . ScGenerator.rb generates the scripts ScConstant.rb and ScEditControl.rb using Scintilla interface definition Scintilla.iface . The script ScEditControlBase.rb is also used to detect specific function implementation. See comments in ScGenerator.rb for further details.

    ScEditControlBase implements a ruby extension method to send the message to the actual Scintilla window.

    ScEditControl implements Observable and can notify any number of listener of about Scintilla Edit Control events.

TraceDebug ruby extension

RubyExtTraceDebug.h/.cpp: adds method TraceDebug#printInternal to script/TraceDebug.rb. Dump a text to the windows debug stream.

GUI/Scintilla Edit Control integration

EditorView.h/.cpp: implements a CWnd object for Scintilla Edit Control. Forward notification to the ruby ScEditControl object associated to this class. Scintilla Edit Control is a child of this window.
ScintillaEditControl.h/.cpp: implements a CWnd object to subclass Scintilla Edit Control. Used to track gain and lost of focus by the window .

When EditorView is created, it automatically creates a ruby ScEditControl (script/scintilla/ScEditControl.rb ) object. Notification are forwarded to this object. SourceDocument and Console are the objects that actually use ScEditControl : it sets up style colors, lexer mode, and implements a simple 'smart indent'...

GUI/Commands integration

MainFrame.h/.cpp: the main frame of the application. It handles commands event an forward those registered by ruby to ruby. A MainFrame ruby object is automatically created and associated to that object. It also maintains the current active window and keep the ruby MainFrame object up to date concerning that aspect.
EditorFrame.h/.cpp: detects change in the active state of an MDI frame and forward the state to the main frame.
script/MainFrame.rb: implements a simple command/action architecture (probably need to be redesigned using ruby features). At the current time, defines handler for copy/cut/paste and undo/redo.
ActionStatusUpdater.h/cpp: implements ruby class ActionStatusUpdater and defines method enable=, check= and text=. Used to update the state of UI item associated to the actions (delegate to CCmdUI behind the scene).
RubyExtFileDialog.h/cpp, FileDialog.rb: extension for windows open file dialog (open/save)
RubyExtDialog.h/cpp, Dialog.rb: extension for Find dialog and Message dialog.

Updating the user UI items is done in 'pool' mode: the MFC frameworks ask the application to update the state of a specific commands items. The MFC main frame checks if a specific command is handled by the ruby MainFrame and delegate the updates if it is the case. A similar technique is used to handle command execution.

Questions, comments and bugs reports

Questions, comments, grammar/spelling mistakes and bugs reports are more than welcome. You can reach me at the following address: gaiacrtn@free.fr