Getting Started with REBOL/Core

REBOL Technologies
Version 2.5.x

Contents:

1. Overview

REBOL/Core is easy to setup and use. It does not require installation. You can simply run the executable file and Core will start. In order to use the network protocols you will need to provide a few network details. See the Network Setup section below.

1.1 Where's the Documentation?

The complete REBOL User's Guide is available from our Documentation page. The REBOL User's Guide is also available as a book from our REBOL/Press web site.

1.2 What Has Changed?

To find out what has changed since the REBOL/Core 2.3 release, refer to the Core 2.5 Changes documentation.

1.3 What's in this Distribution?

The following files included as part of this distribution:

	rebol	The REBOL/Core executable program. On Windows this is called rebol.exe.
	rebol.r	A system bootstrap file. Refer to the notes below.
	setup.html	This document about getting started with REBOL/Core.
	feedback.r	A script for submitting user feedback or questions to us at REBOL Technologies.
	scripts.r	A script that downloads, decompresses, and builds the REBOL script library on your disk.
	docs.r	A script that downloads and decompresses the current REBOL/Core documentation to your disk.
	license.html	A copy of the REBOL/Core end user license agreement.

1.4 Need Help?

There are several sources of help about REBOL:

• Mailing lists - There are a few mailing lists that discuss a variety of REBOL subjects. They are listed on the our links page.
• Link/World - Coming soon. The best source of information will be Link/World, a special version of REBOL/Link that provides a direct connection to REBOL Headquarters. The on-line conference connects you with thousands of people who know about REBOL, the latest documentation, library of scripts, and links to other REBOL developer sites.
• Feedback - For bug reports, type: do %feedback.r at the REBOL prompt. Alternately, you can send us email at feedback@rebol.com.
• Online Help - The built-in help function provides the description, arguments, and refinements for all functions. Type "help" at the REBOL prompt for more information. Several help options are available.
• Script Library - The script library on the REBOL web site provides many simple and useful examples to help you better understand REBOL.
• Source Function - You can obtain the source to many REBOL functions by using the "source" function from the console. For example, "source join" would show you the source code for the join function.
• REBOL.org - An independent REBOL web site that includes a large library of contributed scripts, chat rooms, archives of mailing lists, and other information about REBOL.

1.5 License Agreement

The license agreement can be viewed at any time by typing:

license

at the REBOL prompt.

1.6 Want More?

Visit the REBOL Web site for the latest information about REBOL/Core, REBOL/Express, REBOL/Link, REBOL/Command, and other products.

2. Unpacking REBOL

REBOL can be unpacked to any directory on your disk. If you experience a problem while unpacking REBOL or any of its distribution files, we would like to know about it. Please contact us at feedback@rebol.com with details about the problem, including the version number or file name of the distribution.

3. Locating REBOL

You can locate REBOL/Core in any directory on your system. You can also copy or move it to any other directory on your disk because no installation is done. You can have multiple versions of REBOL/Core present without a problem.

In addition, to copy REBOL to another computer, you simply copy the executable file along with any of your scripts and files. You do not need a copy of the archive file. REBOL easily fits on a floppy disk with room to spare.

4. Standard Startup Files

When REBOL starts it attempts to load two files:

	rebol.r	A file that contains additional changes or patches to REBOL. It also contains the code that will help you set up your network configuration. Do not edit this file as it will be overwritten with each new release.
	user.r	A file that holds user preferences. On multi-user systems, there can be a different user.r for every user. The user.r file is not part of the distribution, but it will be built the first time you run REBOL. The file can be edited and extended in whatever way you desire.

When REBOL starts, it looks for the rebol.r and user.r files first in the current directory, then in a REBOL home directory (see below).

5. Specifying a Home Directory

The home directory is not required, but it is convenient if you run REBOL scripts from several different locations on your disk.

To specify a home directory, set the HOME environment variable in the appropriate login or startup script for your system. Note that on many operating systems, such as UNIX or Linux, the HOME variable may be set by default already. (So you do not need to set it yourself).

When running Windows NT, you can set the variable by selecting the Settings in the Start Menu, clicking on the System icon, then selecting the Environment tab. Provide HOME as the variable and the installation directory (e.g. C:\REBOL) as the value.

On Windows 95+ systems, edit the C:\autoexec.bat file and add a line such as:

set HOME=c:\REBOL

On UNIX systems, set the HOME environment variable in your profile or login shell scripts. For example, with sh shells:

export HOME=$HOME/rebol

or with csh style shells:

setenv HOME $HOME/rebol-dir/

On Amiga, execute the following shell commands:

setenv HOME rebol-dir
copy env:HOME envarc:

6. Network Setup

The first time you run REBOL it will prompt you for network information. This information is optional, but providing it will allow REBOL to perform certain network functions such as sending email. Once the network questions have been answered, REBOL will create your user.r file with your network settings within it.

The first question will request your email address. Type it as you would normally; for example, name@domain.com.

The second question asks the name of your email server. If you don't 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.

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, restart the setup dialog by typing:

set-user

You can also terminate the dialog at any time by pressing the escape key.

All network settings are stored in the %user.r file, and 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]

The line can be modify to provide your startup network configuration. See the REBOL/Core User's Guide for more information.

7. Proxy Setup

Some organizations use a firewall system or proxy server to access the Internet. To operate with these systems, you will need to provide additional network information.

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 computer or firewall 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 the setup. If you don't know, look at the Web browser settings or ask your network administrator.

REBOL defaults to using a SOCKS proxy protocol. You can specify another other type of proxy by editing the user.r file and supplying the set-net function with the appropriate identification for the type of proxy being used. These settings 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 the set-net line in user.r would look something like:

set-net [luke@rebol.com mail none our-proxy 1080 socks]

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

8. System Specific Issues

REBOL is system independent. A script produced on a Windows NT system can be run without modification on a Macintosh, Amiga, Solaris SPARC, Linux, Windows CE, and other supported platforms. However, REBOL does integrate with operating systems in different ways. They are described below.

8.1 Amiga

Use Amiga's Tool Types to set the REBOL icon to the REBOL executable file. The REBOL console interface now maps shift-left to the home key and shift-right to the end key.

8.2 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.

8.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. (eg: read/binary/custom %file [fork "resource"])

8.4 UNIX/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 permissions include read and write permissions for the user and for the user's group, and read permissions for all others.

8.5 Windows

To start a script in REBOL, use a mouse to drag the script file icon to the REBOL icon. Alternately, change Start/Settings/Folder Options to automatically open *.r files with rebol.exe. To copy, select text with the mouse, then use Edit/Copy 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.

9. Running REBOL

REBOL can be run from Icons or from a shell command line.

9.1 Running from Icons

REBOL can be started by clicking on the REBOL program icon, an associated .r file icon, or a shortcut icon. REBOL/Core does not automatically associate .r files to REBOL (however, that option is available in REBOL/Link). See your specific operating system for more information about icons.

9.2 Running from a Shell

REBOL can be started from the command line with a variety of arguments. To view the options available for any REBOL version, type

usage

at the REBOL prompt.

The format of argument fields on the command line is:

REBOL options script args

All of the arguments are optional and any combination is permitted.

Options -- one or more of the program options as listed below. 
Script -- a script file to evaluate. 
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:

REBOL script.r

To run this script with an option, such as with security turned off:

REBOL -s script.r

The dash (-) is used for a single-character option (shorthand). A double dash is used for a full-word options. This is standard practice on many operating systems.

For instance, to obtain usage information about REBOL, type:

REBOL -?
REBOL --help

To run the program without opening a separate window:

REBOL -w
REBOL --nowindow

To use REBOL scripts with CGI, you can write a command line that changes multiple options at the same time:

REBOL -cs cgi-script.r

This will run in CGI mode with security turned off. This is required for various web servers that restrict the number of arguments allowed on the command line (such as the Apache server on Linux).

You may use "--" to signal the end of command line switches. All remaining items on the command line will be passed to REBOL as an argument.

REBOL -- this is an argument

In this case it is assumed that you have a default script specified in your user.r file.

9.3 Quitting REBOL

You can quit REBOL at any time by typing:

quit

This can be done within any part of a script:

if now/time > 12:00 [quit]

10. REBOL Scripts

REBOL scripts are written as text files, allowing you to create and modify them with any text editor. The normal suffix for REBOL scripts is .r, but any suffix is permitted.

Every script begins with the word REBOL followed by a header that provides information about the script. The header has many uses, including identification, documentation, archiving, revision tracking, and script requirements.

Here is an example script with a typical header:

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

print read http://www.rebol.com

See the REBOL/Core User's Guide for complete details.

11. Security

By default, security is set to prevent scripts from modifying or deleting any files or directories on your disk. This is for your own safety.

For scripts that you trust, you can run REBOL with a variety of security settings that control file and network security, including file and directory sandboxes.

Security Warning

Only you, the user, can approve changes to 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 well trusted source.

To disable security for your own scripts, you can run REBOL with security disabled. For instance, if you use an editor or development environment to interactively develop scripts, run REBOL with a command line such as:

REBOL -s script.r

When working this way, take caution to only run scripts that you have written or scripts that you trust completely.

See the REBOL/Core User's Guide for complete details.

12. Upgrading REBOL

To upgrade to the latest version of REBOL, type upgrade at the REBOL prompt. Note that this requires that your user.r be setup to allow Internet access. Upgrade will access the REBOL web site, compare the version you are currently using with a table of the latest available version for your platform, then ask if you wish to download a new version.