REBOL/Core Setup and Operation

Version 2.6.2
From REBOL Technologies
WWW.REBOL.COM

Contents:

1. Overview

1.1 Introducing REBOL

REBOL is a new type of language created specifically for the exchange and interpretation of information over the Internet. Unlike other computer languages, REBOL (pronounced "rehb-el") was designed as both a programming language and a data exchange language. The result is an extremely powerful and flexible tool that remains lightweight and easy to use.

REBOL/Core is the kernel of the REBOL system. It includes a unique advanced interpreter, hundreds of predefined functions, dozens of built-in datatypes, more than 10 network protocols, compression and decompression, reflective embedded documentation, and much more.

The worldwide adoption of REBOL continues to expand over time. Although REBOL is still a "young" language in the computing arena, more than two million people have downloaded it since 1998, it is used in a growing number of companies for a wide range of tasks, and it is rapidly gaining interest at educational institutions throughout the world.

1.2 Sources of Documentation

If you are new to REBOL, we recommend that you read the REBOL/Core Users Guide to get started. It is especially important to understand the concept of a series, around which everything in REBOL is built.

For a summary of changes made to REBOL/Core since version 2.5.0, see the REBOL/Core Changes document that is part of this distribution.

Once you start writing REBOL code and just need summary information about functions, the REBOL Dictionary provides a valuable reference. It is the best source for expanded and updated information about specific REBOL functions.

Other REBOL information and updates are available from the REBOL Documentation page of our web site.

1.3 System Requirements

REBOL/Core is lightweight in its system requirements and does not require anything special to run. A system with these minimum capabilities will work fine:

CPU Speed:   100 MHz
Main Memory: 32 MB
Disk Space:  1 MB
Networking:  TCP/IP

Operating Systems:
    Windows XP, NT, 2K, ME, 98, 95
    Macintosh OS X
    Linux x86 Libc6
    Linux x86 Libc5
    Sun Solaris Sparc
    Free BSD x86
    (many more)

UNIX and Linux systems do not require X Windows operation in order to run REBOL/Core.

REBOL/Core is easy to install (no installation) and use with Apache and other web servers to perform CGI script processing. See below.

1.4 Getting Help

The REBOL/Core program has a built-in help function that provides the description, arguments, and refinements for all functions. This is very handy if you simply need to know the arguments to a specific function while you are writing code. For example, to get help about the SEND function you would type:

help send

You can also use help to obtain other information and search for functions by name. Type "help" at the REBOL prompt for more information.

In REBOL/Core you can also type:

what

to see a summary of all REBOL functions. Or, you can run the words.r script that is included in this distribution to create a printable HTML summary of REBOL functions.

And finally, it is often helpful to look at the source code to other scripts, functions, and examples to see how experts and other users have written REBOL code and solved specific problems. You can obtain the source to many REBOL built-in functions by using the SOURCE function from the prompt. For example, typing:

source join

would show you the source code for the JOIN function.

Hundreds of other example scripts can be found in the REBOL Script Library, and on other REBOL related web sites.

Another source for help is the community of users and experts who subscribe to the REBOL.com email list. Answers to most questions are usually posted within a few hours. To subscribe to the REBOL Email List, send an email to rebol-request@rebol.com with the word "subscribe" on the subject line. This can be done in REBOL with the line:

send rebol-request@rebol.com "subscribe"

1.5 License Agreement

The End User License Agreement for REBOL/Core is included as a file in this distribution. In addition, you can review the license at any time by typing:

license

at the REBOL prompt.

1.6 Reporting Problems

To report a problem related to REBOL/Core or its documentation, or to request new features, visit the RAMBO bug database.

If you have some other questions about products please contact REBOL Technologies using the Feedback Form found on our web site. Please be sure to specify the product name and version number.

1.7 Help Promote REBOL

Help us to tell others about REBOL and grow the REBOL community. It would be great if you could put one of these logos on your web site, and linking it to www.rebol.com.

Please read our logo page for more information and other logos.

1.8 Professional Products

If you want more capability than found in our free products, please consider one of the following:

REBOL/SDK (Software Development Kit) provides many additional REBOL functions for professional and commercial developers. It includes encapsulators to create executable programs, advanced encryption methods, DLL and shell command access, as well as the source code to mezzanine functions, Internet protocols, view, visual interface dialect (VID), and more.

REBOL/Command is intended for enterprise developers who need Oracle, MySQL, ODBC (SQLServer, Access, Excel) database interfaces, access to external libraries (DLLs), SSL secure sockets (HTTPS client), encryption, shell commands, Fast-CGI mode, and more.

2. Installing and Running

2.1 Quick Start

To run REBOL/Core, just click on the REBOL icon or type:

REBOL

in your system shell (terminal window).

When you see the REBOL prompt, type:

print "it works"

to test it.

If you have an Internet connection, try typing:

print read http://www.rebol.com

If that does not work, read the network setup section below.

2.2 Installation Not Required

REBOL/Core does not require installation. You simply run the REBOL program file and it starts.

If you want to send Email, or if you have a special network configuration (such as a proxy server), you will need to provide a few network settings. This can easily be done in your script or you can create a user.r file that loads the settings each time you run REBOL. See the Network Setup section below.

After you unarchive (unzip) REBOL/Core, you can locate it in any folder (directory) on your system. You can also copy or move REBOL/Core to any other location on your disk because it has no installation "hooks" to worry about. In addition, to copy REBOL to another computer, you can simply copy the executable file.

2.3 Distribution Files

The REBOL/Core distribution archive includes these files:

	license.txt	A copy of the end user license agreement.
	rebol(.exe)	The REBOL/Core executable program.
	rebol.r	A file that contains additional changes or patches to REBOL, if necessary. This file is not strictly required to run REBOL, but if it exists when REBOL starts, it will automatically be loaded. Note that in more recent releases, this file may be empty.
	setup.html	This document about getting started with REBOL/Core.
	setup.r	A script that you can run to prompt you for your network setup configuration. This script creates a user.r file as a result (that is automatically loaded each time you run REBOL/Core).
	words.r	A small script that builds an HTML summary sheet for all REBOL function words. This is provided as an example script. After running this script, open the words.html file with your web browser to view the results.

2.4 Running From an Icon

REBOL can be started by clicking on the REBOL program icon or a shortcut to the program icon.

Note that because REBOL/Core has no Windows installer, it does not automatically associate .r files to run REBOL. However, you can easily add your own .r file association. In any folder window, click on the View Folder Options menu and select File Types to add it.

Once you have started REBOL, you can run scripts from its command prompt using the DO function. For example:

do %script.r

would run the script.r file. Do not forget the % to indicate that it is a file.

Here is another example that would run a script from a web site:

do http://www.example.com/script.r

If in Windows (or other systems) you want to create a shortcut icon that automatically runs a specific REBOL script, follow the instructions for Running From a Shell described below.

2.5 Running From a Shell

REBOL can be started from the command line with a variety of options and arguments. To view a summary, start REBOL and type:

usage

at the REBOL prompt. Or, run REBOL with the option:

REBOL -?

The format of the REBOL command line is:

REBOL [options] [script] [args]

All of these arguments are optional. They are:

Options -- one or more options as listed below
Script -- a script file to run
Args -- arguments passed to the script

Typically, you will provide REBOL with the name of the script file that you want to evaluate. For instance, to run a script called script.r, type:

REBOL script.r

To run the script with an option, such as the -s option that lowers the security level, write a line such as:

REBOL -s script.r

The dash (-) is used for single-character options. A double dash (--) is used for a full-word options. This is standard practice in many operating systems. For instance, to obtain usage information about REBOL, you can type either of these lines:

REBOL -?
REBOL --help

When the script name is followed by additional words and values, they are passed to the script as arguments. The arguments are passed to the script in the SYSTEM/SCRIPT object. For example, the command line arguments:

REBOL script.r test 1234

can be printed with a line such as:

probe system/script/args

If no script arguments are provided, a NONE is returned.

You can also use a "--" followed by no word to signal the end of command line and pass remaining values to REBOL as script arguments:

REBOL -- example 1234

Because no script file is provided in this example, it is assumed that you have a default script specified in your user.r file. See below.

More about starting REBOL can be found in the Operation Chapter of the REBOL/Core User's Guide.

2.6 Running in CGI Mode

When you use REBOL for CGI scripts, you will need to provide a special -c option to tell REBOL to read the CGI environment variables. For example, the line below:

REBOL -c cgi-script.r

runs the script in CGI mode.

If you also want to run your REBOL CGI script so it can write output files, you will need to lower the default security with the -s option. This command does the job:

REBOL -cs cgi-script.r

For many types of web servers (such as Apache), you can create CGI shell scripts that include both the command line and the script itself. Here is an example of how it is done:

#!/home/user/rebol -cs
REBOL [Title: "CGI Script"]
print "content-type: text/html^/"
print [
    <HTML><BODY>
    "Now is:" now
    <PRE>
    mold system/options/cgi
    </PRE>
    </BODY></HTML>
]

When accessed from a web browser via CGI, this example will print the date and time followed by the CGI environment object (which lets you see all the information that the web server has passed to you.)

Be sure that the script and REBOL have the necessary permissions for your operating system (e.g. Unix file mode 755).

More about CGI operation can be found in the Networking Chapter of the REBOL/Core User's Guide.

2.7 Startup Scripts

When REBOL starts it will automatically run the rebol.r and user.r files, if they exist.

The system looks for these files first in the current directory (or the directory of the script being run), then in the directory that contains the REBOL executable program.

Note that REBOL/Core runs fine without the rebol.r and user.r files. They simply provide an easy way to include additional code and data on startup, such as your network preferences.

2.8 Script Security

REBOL stays on the safe side by not allowing scripts to modify or delete files unless you let them.

In addition, REBOL offers a variety of security settings that control file and network security, including file and directory "sandboxes" (areas where scripts are permitted to access files).

In REBOL/Core the default security lets scripts only modify or delete files in the script's current directory, nowhere else. Changing files anywhere else requires user approval.

For trusted scripts, you can run REBOL with security disabled. This mode lets scripts do anything (including delete files). To run in this mode, start REBOL with the -s option:

REBOL -s script.r

When running this way, be sure to only run scripts that you have written or scripts that you trust completely.

If you want to run scripts with full security for read and write, you can specify the +s command option:

REBOL +s script.r

Now REBOL will prompt you each time your script tries to do anything, including simply reading a file.

Security Warning

Note that only you, the user, can change the security.

When running REBOL, if you receive a security warning, do not approve a change of security or allow file operations if you do not trust the script. Inspect the script first before running it or obtain the script from a trusted source.

There is no way for a script to lower the security level without your approval. Changes can only be made from the command line (with options like -s, +s, and --secure) or from the popup security warning.

See the Operation Chapter of the REBOL/Core User's Guide for more information about security.

2.9 Quitting REBOL

You can quit REBOL at any time by typing:

quit

or just:

q

Note that typing the word EXIT will result in an error message, because EXIT is a word used to return from REBOL functions.

If your script was run in CGI mode, it will automatically quit when it has finished.

3. Network Setup

If your computer has direct access to the Internet, then you can run REBOL/Core without any network setup.

If your computer uses a proxy server to access the Internet, you will need to provide settings to allow REBOL to make connections through the proxy.

If you want to use the SMTP email protocol (for example, use the SEND function to send email), you need to provide a reply address and mail server name.

Network setup can be provided in each script that you run or in your user.r file that is loaded each time you run REBOL. Both methods have their advantages.

3.1 Basic Concepts

REBOL provides the SET-NET function to make it easy to specify your email and network settings.

For example, within a script you can use:

set-net [user@example.com mail.example.com]

to set your email reply address and the name of your SMTP email server.

Set-net can also set your POP and proxy server information. See more below.

Note that SET-NET is just a shortcut function for quick setup. Many other network setup parameters are available, such as network timeouts for each protocol.

See the Networking Chapter of the REBOL/Core User's Guide for full details.

3.2 Interactive Setup

You can ask REBOL to prompt you for network information by running the setup.r script that is included with this distribution. Once the network questions have been answered, REBOL will create a user.r file with your correct network settings within it.

To run the setup script, start REBOL, then type:

do %setup.r

or, just run REBOL with the setup.r script:

REBOL setup.r

The script will ask you a few questions:

1. The first question will request your email address. Type it as you would normally. For example, name@domain.com.
2. The second question asks for the name of your email server. If you do not know it, check the settings or options menu of your current email program. Hint: if your email address is bob@example.com, your email server may be mail.example.com. Otherwise, contact the network service provider for the name of the email SMTP server.
3. The third question asks if you use a proxy server. If you are directly connected to the Internet with a modem or ethernet, then the answer is N for no. Otherwise, read the following section on proxy setup.

If you make a mistake or later decide to change any of these network settings, just run the setup.r script again.

Note that you can terminate the setup script at any time by pressing the ESCAPE key.

When complete, all network settings are stored in your user.r file, and it can be modified with any text editor. The network setting appear in a line the begins with SET-NET. For example:

set-net [luke@rebol.com mail none none]

This line can be modified to provide your startup network configuration.

3.3 Proxy Servers

Some organizations use a proxy server to access the Internet. A proxy server is a gateway that routes network connections from an internal network to the external Internet. To operate REBOL with these systems, you will need to provide additional network information.

In the interactive setup above, when REBOL asks if you use a proxy, answer by typing a Y for yes. You will then be prompted for the name of your proxy host. This is the server that operates as a proxy.

Next, you will be asked for the port number used by that system for proxy requests. Typically, this is port 1080 for SOCKS proxy servers, but it can vary depending on your proxy setup. If you do not know, look at your Web browser's proxy settings or ask your network administrator.

REBOL defaults to using the SOCKS proxy protocol. You can specify other types of proxies by editing your user.r file and supplying the SET-NET function with the appropriate identification for the type of proxy being used.

These proxy types are supported:

socks   - use the latest SOCKS version (5)
socks5  - use socks5 proxy
socks4  - use socks4 proxy
generic - use generic CERN proxy
none    - use no proxy

For example, to setup a proxy with SET-NET in your user.r file, you might write a line like this:

set-net [you@example.com mail none proxy.example.net 1080 socks]

See the Networking Chapter of the REBOL/Core User's Guide for more information.

4. REBOL Scripts

REBOL scripts are written as plain text files. You can easily create or modify them with any text editor.

4.1 REBOL File Suffix

REBOL scripts typically appear with a .r suffix for file names; however, this is just a convention and is not required. The interpreter reads files with any suffix and scans the contents for a valid REBOL script header.

The example command line below will examine the example.txt text file for a REBOL header, and if it is found, will run the REBOL code that follows the header:

REBOL example.txt

This is also true of files run from within REBOL, such as:

do %example.txt

and even:

do http://www.example.com/test.html

4.2 REBOL Headers

Every script must begin with the word REBOL followed by a header object that provides information about the script. Headers have many uses, including identification, documentation, revision tracking, and script requirements.

A minimal script header would be:

REBOL [Title: "Example Script"]

But, it is a better practice to provide more information in your header. Here is an example:

REBOL [
    Title: "Example Script"
    Date: 24-mar-2003
    File: %include.r
    Version: 1.2.3
    Author:  "Luke Lakeswimmer"
    Purpose: {
        Just show the folks how it's done.
        What could be simpler.
    }
]

print read http://www.rebol.com

See the Scripts Chapter of the REBOL/Core User's Guide for complete details about scripts and their headers.

4.3 Converting Line Terminators

Different operating systems use different characters to terminate lines. For example, Windows uses the CR and LF characters, whereas Unix/Linux uses just LF.

REBOL does not care about line terminators. It will properly handle files with any standard type of line termination.

However, if you are editing scripts created by other REBOL users, your text editor may not like the terminators. Fortunately, REBOL can easily convert the lines terminators to the format used by your computer. To do so, just read the text file and write it back. For example,

write %example.r read example.r

will convert the example.r file to use the correct line terminators for the local operating system.

This example converts all the .r files in a directory:

foreach file load %. [
    if (suffix? file) = %.r [
        write file read file
    ]
]

Note: Do not use this on binary files such as program executables, or they may be corrupted.

4.4 Script Compatibility

It is always a good idea to use the most recent version of REBOL for running scripts. Newer versions of REBOL provide new functions and features not found in older models. With very few exceptions, older scripts will run on newer versions of REBOL.

When REBOL/Core runs, it prints its version number to the console. You can also obtain its version with a line such as:

print system/version

You can also determine what REBOL product you are running with the line:

print system/product

Other system information is also available. To see a full list of system variables, type:

help system

5. Platform Specific Notes

5.1 Windows

In Windows, the REBOL console lets you cut, copy and paste lines of text. To copy, select text with the mouse, then use the Edit/Copy menu or Ctrl-C to copy selected text to the clipboard. Use Edit/Paste or Ctrl-V to paste text from the clipboard to REBOL. Or, use the right mouse button to access a Copy/Paste pop-up menu.

On the REBOL console interface for Win32 machines, the Ctrl (control) versions of the cursor keys scroll the display up and down. Control-page-up and control-page-down scroll a page at a time. Control-home and control-end scroll to the first and last line of the display. These control sequences are not passed to the console input port.

The REBOL console on Windows machines offers an option (File Settings) to "Use window width" that will wrap lines at the current window's width. Otherwise, it will wrap at the length in the "Terminal width:" box. As with other platforms, resizing the window's width will not refresh text on the screen. If you prefer, turn "Use window width" off by unchecking the box.

5.2 Mac OS X

Under OS X, REBOL/Core is just a shell executable file that uses standard input and output. It does not by default work as an executable icon. You run REBOL by opening a terminal and typing the command line (as shown above) or by running a shell script.

5.3 Macintosh

REBOL, by default, only reads and writes the data fork of Macintosh files, not the resource information. This means that using REBOL to read and write certain types of files will not produce the desired results.

REBOL 2.5 provides the ability to specify the fork of Macintosh files. This is done with the custom READ and WRITE settings and also the SET-MODES and GET-MODES functions.

For example:

read/binary/custom %file [fork  "resource"]

5.4 UNIX and Linux

REBOL uses the TERMCAP entry provided by UNIX-based systems. If some of your function keys are not operating properly, you will need to setup your computer's TERMCAP entry.

Default file permissions include read and write permissions for the user and for the user's group, and read permissions for all others.

5.5 Amiga

Use Amiga's Tool Types to set the REBOL icon to the REBOL executable file.

5.6 BeOS

REBOL for BeOS is run from a terminal window rather than a console. To open a terminal, click on the Be menu, then choose the Applications sub-menu, and select Terminal. Type the path to the REBOL executable program and press ENTER.

Default permissions now include read and write permissions for the user and for the user's group, and read permissions for all others.