Ruby In Steel 1

Back to -Tutorials -Sapphire (Ruby In Steel) Tutorials -Archives -Ruby In Steel 1

The Ruby Editor

A Short Guide To Editing Ruby Files

In this tutorial we’ll take a quick look at some of the core Ruby code editing features of Ruby In Steel. You can try these out in your own files or you can download the sample Ruby file and follow along step by step.


Note: This tutorial describes the features of Ruby In Steel Developer. Not all editing features are available in the Personal Edition.

Zip - 2.5 kb
Download the Ruby Editor Sample Project

Color Coding

Ruby In Steel provides extensive syntax-sensitive coloring of Ruby code. It adopts the standard Visual Studio colors for keywords, comments, strings, floats and integers. It also color codes Ruby-specific elements such as class, global and instance variables, method definitions and method calls…

- Try It Out

Try entering some code (or copy and paste the following)…

Note that the editor instantly colors different code elements as you enter them. Even the method definition of aMethod and the method-call ob.aMethod may be colored differently...

- Configure Colors

The colors you see when you enter code are unlikely to be the same as those shown in the picture above. You can easily change the colors to your own tastes. To do this, load up the Font Options dialog (Tools->Options->Environment->Fonts and Colors).

The ‘standard’ colors available to Ruby files are: Strings, Comments, Numbers, Keywords, Identifiers and Plain Text. All the ‘special’ Ruby colors are prefixed by ‘Ruby’ (for example, Ruby Class Definition and Ruby Method Call. You may set foreground and background colors and apply bold formatting if you wish. To fine-tune the colors, click the Custom button. The editor font can be changed in the Font drop-down combo.

Hint: to change the colors of local variables, ‘free-standing’ method-calls (i.e. method calls that don’t follow a variable and a dot), and arguments to methods, set the Identifiers color. To change the colors of ‘operators’ such as +, = and =>, set the Plain Text color.

You can also change the colors of RHTML files (these colors are prefixed by Rails in the font list) and various other windows within Visual Studio including the Ruby Console. Select other windows in the Show Settings For combo.

Code Folding

Ruby In Steel provides extensive ‘code folding’ or ‘outlining’ to let you collapse and expand chunks of code. Code folding operates on classes, modules, methods, case statements, if blocks, while, unless, until and for loops, =begin/=end comment blocks and Ruby blocks delimited by { and } or do and end.

- Try It Out

Click the minus characters to the left of a class or def to collapse a block. Notice the ‘collapsed’ marker [...] to its right. You can hover your cursor over this to view a tooltip showing the collapsed code. Meanwhile the margin marker has changed to a plus sign to indicate that there is hidden text. Expand it by clicking the plus sign.

Collapsible Regions

Collapsible ‘regions’ are any sections within a code file, marked by a #region comment at the start (you can optionally add a name such as #region FileOperations and #endregion at the end. Just adding these comments will cause code folding to be applied to the entire region which they delimit....

Delimiter Matching

In long, complex code, it is all too easy to get lost among a forest of brackets or keyword..end pairs. The Ruby In Steel editor can help you get back on track by automatically highlighting matching pairs of brackets (square, round and curly) or by moving the cursor between a pair of brackets or a Ruby keyword (such as def, class, module, if, while and others) and its matching end. Bracket highlighting occurs when you move your text cursor over brackets...

To move the cursor between pairs of brackets of between matching keyword..end pairs, press the CTRL+] hotkey.

- Try It Out

In a complicated Ruby file find a set of end keywords (if you haven’t a suitable file to hand, use our sample file). Put your cursor over an end and press CTRL+]. The cursor will jump to whichever keyword (such as the start of a class or method definition) matches it.

Try this out in a source file containing hundreds or thousands of lines to see just how useful this feature can be!

Keyword..end Completion

Now when you enter a keyword such as def, class, module , begin, while or if, the terminating end can be entered for you...

Automatic Code Formatting

When you press Enter following an end, the code in the block that’s terminated by the end can be auto-formatted. So if, for example, you enter a sloppily formatted method like this...

....it will be reformatted with correct indentation like this:

If you don’t like keyword..end completion and automatic formatting, these can be disabled by unchecking the relevant options in Tools->Options->Text Editor->Ruby-Formatting. Remember that you can always reformat all the code in a file or just the selected block using the options in the Edit->Advanced menu (or their keystroke shortcuts).

Code Navigation

To find the classes, methods, modules and variables in the current file, just select them from the Navigator Bar over the editor...

- Try It Out

Use the left-hand combo to find classes and modules. For example, click M2 to jump to module M2. Use the right-hand combo to find methods and variables. For example, select displayResults() to jump to that method; select h3 to jump to the point at which the h3 hash object is created.

You can also locate the definitions of classes, methods and objects using the Go To Definition tool.

- Try It Out

At the bottom of our sample file, find this line:

p hnew

Right-click hnew and select Go To Definition. Your cursor will jump to the point at which the hnew hash is defined:

hnew = (h2.merge(h3)) Now, right-click merge in this code and, once again, select Go To Definition.

This time, Ruby In Steel loads up a file called hash.rb and places the cursor near an empty method:

def merge (arg)
end

This method is empty due to the fact that the merge method, in common with most of the standard Ruby class library, is actually written in the C language. Ruby In Steel provides a pseudo-Ruby version of the C-language library which includes all the embedded documentation, but not the C source code. When no functional Ruby code exists for a class or method, Go To Definition will display the library documentation.

Tooltip RDOC Documentation

If it’s just the RDOC documentation you are interested in, there is a quicker way to find it. Just hover your mouse over an identifier, such as a class or method name and the documentation will pop up in a tooltip.

- Try It Out Hover your mouse pointer over h2.merge and this is what you will see...

You can add your own documentation to methods and classes. Just place it in a regular comment block and it will automatically appear in tooltips.

Hint: You can turn off RDOC hints if you wish. Select Tools->Options->Text Editor->Ruby-IntelliSense and un-check Display RDOC in tooltips.

Incidentally, you can also browse the Ruby class library (including the extracted documentation from the C-language units) using the Ruby Explorer, available from the Ruby menu.

Auto-Open Required Files

No need to hunt around looking for required files. Double-click a file name...

...and the required file will be loaded into the editor:

More Things To Try

- Mark a block of text and add or remove comments.
- Add a bookmark to the current line and navigate to and from bookmarks.
- Indent / unindent a marked block

These and other features are available on the Text Editor toolbar (View->Toolbars->Text Editor).

The Text Editor Toolbar

- Select text in the editor and drag-and-drop to move it (hold down CTRL while dragging to copy it).
- Try multi-level Undo/Redo (CTRL+Z, CTRL+Y).

Customize The Editor Display

You can view the same document in two window panes by dragging down the little tab at the top-right corner of the editor window (just beneath the Navigation Bar); or select Window->Split.

You can view different sets of tabbed documents in window panes by selecting Window->New Horizontal Tabbed Group or Window->New Vertical Tabbed Group.

If you prefer a ‘clean screen’ editor you can zoom the editor window to full screen and hide the toolbars and panels by pressing SHIFT+ALT+ENTER.

IntelliSense, Debugging and More...

There is much more to the editor than we’ve described in this short introduction. For example, it also provides auto-expansion code snippets and powerful analytical IntelliSense with code completion.

When you are debugging, you can hover over identifiers in the editor in order to display hovering drill-down tooltip.

Be sure to read the manual for more information.

Bookmark and Share   Keywords:  tutorial
© SapphireSteel Software 2014