REBOL Quick Start: Part 4 - Help from the Console
REBOL's Designer
Revised: 12-Mar-2024
The Plan
In the prior tutorial, Quick Start: Writing Scripts, you learned how to write a few scripts of your own. I also introduced a few of the basic rules of REBOL.
In this article, I want to show you a few important tools that will help you write and debug your scripts.
Why Learn This?
Let me be open and tell you up front: When you write scripts, you're going to make mistakes. We all do. It is the nature of the science and the art of programming.
Over time, as you learn REBOL, you learn how to avoid making mistakes. The better you get, the fewer mistakes. Eventually, you will be able to write entire scripts with very few errors.
But, for now, while you learn REBOL, you will run into problems. Some problems are going to be discouraging because you don't know how to fix them. Some problems will seem impossible to fix.
But, do not fear. I want to give you a few good tools and techniques for solving such problems. That is the purpose of this chapter. These are the same methods I use every day when I write REBOL, and I am covering this now, rather than later, because you can put it to use immediately. It will also help you with the upcoming tutorials.
So, please pay close attention. This is important stuff.
The Console
You have probably already noticed that REBOL provides an interactive console. The console is one of your main tools for writing and debugging scripts. You can use it for getting help information, testing new ideas, and checking on the variables within your programs.
How to Get It
There are several ways to open the console:
- Click on the Console icon in REBOL/View (on the left side).
- Put a halt word in your REBOL script. Your script will stop and the console will open.
- Change the User preferences for the Viewtop to not "open the desktop on startup". Save your settings. Run REBOL again, and it will open in the console.
- Create a shortcut to REBOL that includes the --noviewtop option. That shortcut will open REBOL to the console.
- Any error in your scripts will open the console.
- Run REBOL/Core (the kernel of REBOL). It always uses the console.
In addition, if you print a value, the console will open to show it. More on this below.
Console Input and Output
Open the console. You are now using REBOL's interactive mode.
When you see the prompt (two arrows), type the first line shown below:
>> print "hello"
hello
When you hit the enter key, REBOL printed the "hello" string back to the console.
Now try:
>> 1 + 2 + 3 == 6 >> now == 5-Nov-2006/13:45:08-8:00 >> read http://data.rebol.com == {<html> <head> <META NAME="Description" CONTENT="Lightweight distr...
The == shows the results for the input you typed.
Above you see a numeric result (6), the current date, time, and timezone, and the HTML code for the www.REBOL.com home page.
Note that results are only printed when there is a result worth seeing. Sometimes there are no results, and other times the results would be too long.
If you type an expression that opens a block, the prompt will change to indicate that more lines are needed. For example:
>> loop 3 [
[ print "hello"
[ ]
hello
hello
hello
The bracket [ at the start of the line lets you add more lines of code. This mode also works for long strings. More on that later.
Copy and Paste
The copy and paste operations are useful in the console.
You can copy code from web pages, such as this tutorial, and paste them into the console. Try copying this example:
view layout [
btn "Press Me" red [alert "It worked!"]
]
Now, paste it into the console. (An easy way to do that is to press CTRL-V on the keyboard.) A window will pop up on your screen. Click the button. It worked.
But, how to get back to the console prompt? Either close the window, or read the next section.
Also note, you can use CTRL-C to copy text that you have selected in the console window. That's how I'm providing the example output for this tutorial.
Escaping Out
If you have the console open, you can press ESC (the escape key) stop REBOL at any time and get a prompt to input new lines.
Run the above example again. But, instead of closing the window, click on the console window and press ESC. The script window will remain open, but the console prompt will return. You can now type:
unview
and the window will close.
Escape can be really important if you accidently print a large value. For example, beginners often type:
print system
After a short period of time, the results will start scrolling down the console window. The result will be several megabytes of text (nearly all of the mezzanine-level source code for REBOL).
To stop it, press ESC. This is really good to know.
Oh, and by the way, if you want to peek around in the REBOL system object, use:
? system
and then include the system fields in lines like:
? system/options
That will keep the length of the results fairly sane.
Auto-Completion
We all like to save time while typing. To help out with that, you can use the TAB key to autocomplete words and filenames.
For example, type:
>> low<tab>
When you press the tab, the console will complete the word:
>> lowercase
If you type just the "lo" and press tab, nothing happens. It matches multiple words. Just press tab again to see the choices:
>> lo
>> logic! logic? load loop log-10 log-2 log-e lowercase logo.gif
local-request-file load-thru load-image load-stock load-stock-block
The tab completion feature also includes words that your script has defined.
Auto completion also works for filenames and directories:
>> list-dir %pub<tab>
>> list-dir %public/
www.rebol.com/ www.rebol.net/
>> do %my-<tab>
>> do %my-script-example.r
Getting Help
REBOL provides built-in help. It is one of your best tools for writing and debugging scripts.
At the console prompt, type:
>> ?
To use HELP, supply a word or value as its
argument:
help insert
help system
help system/script
To view all words that match a pattern use a
string or partial word:
help "path"
help to-
To see words with values of a specific datatype:
help native!
help datatype!
...
Instead of ? you can also type:
>> help
They are the same.
Example
In an early example, you used print. If you want more information about it:
>> help print
USAGE:
PRINT value
DESCRIPTION:
Outputs a value followed by a line break.
PRINT is a native value.
ARGUMENTS:
value -- The value to print (Type: any)
There you have a summary of the print function. As you will soon learn, this information is quite useful for figuring out error messages.
Note that in REBOL, this help information comes from the function definition itself. REBOL code is "self documenting". This is a good thing. It means that help is always accurate, and help also works for all the functions you will be writing. Nice.
Other Information
Help works for many things. To see the fields of the system object (or any object):
>> ? system
SYSTEM is an object of value:
version tuple! 1.3.2.3.1
build date! 5-Dec-2005/18:22:54-8:00
product word! View
core tuple! 2.6.3
components block! length: 54
words object! [unset! error! datatype!...
...
To get a list of the functions defined in REBOL:
>> ? function!
Found these words:
? function! Prints information about...
?? function! Prints a variable name f...
about function! Information about REBOL
alert function! Flashes an alert message...
alter function! If a value is not found ...
append function! Appends a value to the t...
...
(Note that the above list only shows user-defined functions. You can also get a list of native, action, and routine functions in a similar way.)
To search for words, use quotes:
>> ? "-dir"
Found these words:
change-dir function! Changes the active dir...
delete-dir function! Deletes a directory in...
list-dir function! Prints a multi-column ...
make-dir function! Creates the specified ...
req-dir object! [dirs max-dirs cnt pat...
request-dir function! Requests a directory u...
what-dir function! Prints the active dire...
You can now get specific help about any of those.
And, again, all of these help features will automatically include the code that you write.
So, keep help in mind when you write and debug scripts. It's always there ready to help. You don't even need to open a web page.
Next: Files, Directories, and Playing Songs
The tutorial above talked about how to open the console and get help.
In the next tutorial, I'll show you a few things about files, directories, and we will build a script that plays a pile of songs.