REBOL Document

Getting Started with REBOL/Command

REBOL/Command Version 2.5.6

Contents:

1. Overview
      1.1 Where's the Documentation?
      1.2 What's in this Distribution?
      1.3 Need Help?
      1.4 License Agreement
2. Locating REBOL
3. Standard Startup Files
4. Network Setup
5. Proxy Setup
6. Running REBOL
      6.1 Running from Icons
      6.2 Running from a Shell
      6.3 Quitting REBOL
7. REBOL Scripts
8. Security


1. Overview

REBOL/Command is easy to setup and use. It does not require installation. You can simply run the executable file and Command 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 REBOL/Command distribution package includes all related documentation. This includes documentation specific to Command as well as more general REBOL documentation.

All documentation including the REBOL User's Guide are available from the documentation page of our web site.

1.2 What's in this Distribution?

The following files are included as part of this distribution:

 rebcmd (.exe)The REBOL/Command executable program.
 rebcmdview (.exe)The REBOL/Command/View executable program.
 rebol (.exe)REBOL/Core of same version as /Command.
 license.keyThe REBOL/Command license file. This file needs to be placed in the same directory as the REBOL program you are using. See the section on Installation for more information.
 docs/The docs directory contains the REBOL/Command documentation files in HTML format.

1.3 Need Help?

There are several sources of help about REBOL:

  • 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.
  • Mailing lists - There are a few mailing lists that discuss a variety of REBOL subjects. They are listed on the REBOL developers page.

1.4 License Agreement

The license agreement can be viewed at any time from within the product by typing:


    license

at the REBOL prompt.


2. Locating REBOL

You can locate REBOL/Command in any directory on your system. You can also copy or move it to any other directory on your disk because no installation is required. You can have multiple versions of REBOL/Command present without conflicts. If you move REBOL/Command to a new directory, the license.key file in this distribution must also be moved with it.


3. Standard Startup Files

When REBOL starts, it attempts to load:

 rebol.rA patch file (normally empty) that may be provided by REBOL Technologies.
 user.rA file that holds user preferences. You can use it for common code that will be loaded each time you run REBOL. On multi-user systems, there can be a different user.r for every user. The user.r file is not part of the distribution.


4. Network Setup

When you first run REBOL/Command/View, it will allow you to setup your network configuration. These setting can be changed at any time directly from the REBOL desktop.

REBOL/Command does not have a graphical configuration. In order to setup your network configuration, type:


    do %set-net.r

from the REBOL prompt. The set-net.r script will ask all the required questions to get your network services running.

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, run the set-net.r file again or manually edit your user.r file.

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/Command User's Guide for more information.


5. 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/Command User's Guide for more information.


6. Running REBOL

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

6.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/Command 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.

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

6.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]


7. 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/Command User's Guide for complete details.


8. 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/Command User's Guide for complete details.


REBOL/MakeDoc 2.0

REBOL is a registered trademark of REBOL Technologies
Copyright 2003 REBOL Technologies

6-Aug-2003