REBOL |
/Internet Messaging LanguageTM |
REBOL/core
Setup Guide
Version 2.1.2
(27-Aug-1999)
Here are the instructions for unpackaging and running the REBOLTM Internet Messaging Language on supported operating systems as well as information about platform-specific issues. Refer to the User's Guide and REBOL Dictionary for more information about the language. Refer to the Release Notes text file (notes.html) included with this distribution for a list of modifications since the prior version. Refer to our website for a library of example scripts and how-tos.
To place the language and supporting files on your computer, extract the compressed file to the directory in which you want to run, then unarchive it using your platform's compression tool. Enclosed are the executable program and supporting information and scripts. Contact feedback@REBOL.com if you have problems with unarchiving the compressed file.
When REBOL starts, it attempts to load the rebol.r and user.r files. These files are optional, but when found they can be used to set up networking, common functions and data used by your scripts.
The rebol.r script file holds special functions or extensions to REBOL that are provided as part of the standard distribution. It is suggested that you do not edit this file as it will be overwritten with each new release.
The user.r script file 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 will be built the first time you run REBOL and answer the setup questions. 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 that is specified with the operating system environment variable called REBOL_HOME. To setup the home directory, set the environment variable in the appropriate login or startup script for your system. For example:
set REBOL_HOME=c:\REBOL
On a PC running Windows NT, you can set this by selecting the Settings in the Start Menu, clicking on the System icon, then selecting the Environment tab. Provide REBOL_HOME as the variable and C:\REBOL as the value.
On Windows 95+ systems, edit the C:\autoexec.bat file and place the line shown above within it.
On UNIX systems, add the line to your profiles or login shell scripts.
On Amiga, add it to the s:user-startup file. See the operating system documentation for details.
The first time you run REBOL it will prompt you for network information. This information is optional, but providing it will allow REBOL to send email. Once the startup questions have been answered, REBOL will create your user.r file and place the 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@bluesea.com, your email server may be mail.bluesea.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.
It is a common practice for organizations to use a firewall system or proxy server to access the Internet. To operate with these systems, you will need to provide some additional 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, 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 some 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
These are provided as the sixth argument to the set-net function in the user.r file. In addition, the proxy for all of REBOL's network protocols can be changed with a line such as:
system/schemes/default/proxy/type: 'socks
Note that the tick (') is required because the word following is a symbol value, not a variable. In addition, you can individually set different proxy settings for each network protocol. For instance, you can specify that HTTP use a generic proxy, but FTP use a SOCKS4 proxy.
The REBOL messaging language is platform independent. A script produced on a Windows NT system, for example, can be run on a Macintosh, Amiga, Solaris SPARC, Linux, and other supported platforms with no changes. Resulting data, too, can be passed between platforms with the assurance of full compatibility.
Of course, each system has its own operating differences. Here are some of the known conditions.
Amiga's time zone is set by default to US Central Time rather than GMT. Add the following line to the end of s:user-startup:
echo "PST8PDT" >ENV:TZ ;for PST where 8 is the GMT offsetSave the user-startup and reboot. You system will then be set to 8 hours behind Greenwich Mean Time (GMT). You can also echo this line to ENVARC:TZ as all files in ENVARC are automatically copied to ENV when the computer boots up. We also expect to be supporting the locale library on the next release.
Use Amiga's Tool Types to set the REBOL icon to the REBOL executable file.
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.
REBOL only copies 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. This is a common problem on the Macintosh, and we will be providing additional capability in a future release.
The network busy indicator doesn't work correctly on Macintosh. Until fixed, either turn it off in the user.r file with:
system/console/busy: noneor change it to rotate in place with:
system/console/busy: "|^M/^M-^M\^M"
If you receive the following message, contact REBOL support:
ld.so.1: rebol: fatal: libcurses.so.1: open failed: No such file or directory
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 now include read and write permissions for the user and for the user's group, and read permissions for all others.
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. Simultaneously press the Shift key to select only text typed at the keyboard. 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.
In addition, older computers and some palmtops with minimum memory may have problems evaluating larger REBOL scripts.
REBOL can be started from the command line with arguments to start REBOL scripts. 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 above 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 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 option. 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 prevent the printout of startup information (as when you are redirecting the output of REBOL):
REBOL -q REBOL --quiet
To evaluate a REBOL expression from the command line:
REBOL --do "print 1 + 2" REBOL --do "verbose: true" script.r
To change the security level of REBOL:
REBOL --secure none script.r
that also can be written as:
REBOL -s script.r
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).
REBOL scripts are written and exchanged as ASCII text files, allowing them to be created and modified with any text editor. The script begins with the word REBOL followed by a header block that provides information about the script. The header has many uses for documentation, archiving, revision tracking, script requirements, or other purposes. Here's a typical header:
REBOL [ Title: "Include Files" Date: 24-Aug-1999 Needs: 2.1.2 File: %include.r Purpose: { A useful function for including a single file or a block of files. Web and other file paths are allowed. } ]
Text that appears before the header block is ignored. Text appearing after the header is the script itself.
Use the semicolon ";" to mark the beginning of a comment that continues through the end of a line.
name: "Franklin" ; the name of the manufacturer
REBOL script headers can include the script title, date, name, version, file name, home url, author's name and email address, owner, rights, tab spaces, version requirement (needs), language, character set, purpose, history, example, and other useful information. Refer to the User's Guide for more information. The REBOL header is evaluated before the script so you can use the header to set special options that the script will use.
To evaluate a REBOL script and see the results, you have two choices. First, you can start the REBOL language and type at the >> prompt:
do %filename.r
The file will be loaded and evaluated. (The % tells the language that the value is a file name rather than a word, function, or data.)
Second option: you can specify a script from the shell or GUI (if your computer platform supports it):
REBOL filename.r
This immediately starts the language running with the script.
Everything else on the command line after the script file name will be passed to the script as its argument. This allows you to write scripts that accept arguments directly from the command line.
REBOL script.r 10:30 test@domain.dom
The script is passed these arguments in the system object. For instance, to print the arguments that have been passed:
probe system/script/args
The probe function is used here to show the args within the block.
The default security settings for REBOL do not allow scripts to write files or write to the network. This is done to provide a level of safety to your system and information. Because of this default, you will be prompted by REBOL each time it tries to write to your disk or to the network.
However, if you trust a script because you wrote it yourself, downloaded it from a reputable source or inspected the script carefully in advance, you can lower the security level to make operation more convenient. There are two ways to do so. You can run REBOL with:
REBOL -s script.r
This will lower the security without asking because it is assumed that only you can start REBOL running.
However, you also can add this line to the user.r file:
secure none
You will be prompted each time you run REBOL to determine if you want to lower security for the script being run. You also can write:
if error? try [secure none] [print "Security not changed"]
to allow the script to continue.
There are five user-selected levels of security. The secure native allows you to change the security level of scripts with an argument:
none ;turns off security and allows all operations read ;secures against write access, prompting the user ask ;prompts the user to read or write throw ;denies the operation and provides an error trap to the script quit ;denies the operation and quits the program
The default security level when running REBOL is read. That is, by default REBOL allows the reading of files and network connections, but does not allow writing files or sending to the network. To lower the security level and allow writing to files and the network, you can execute REBOL with either of these command line options:
REBOL -s REBOL --secure none
In addition, you can add a line to your user.r file and other scripts to request a security level different from the current settings. For instance:
secure none
And you will be prompted each time to approve the change of security before the script will continue.
The command line options may be included in the icon on some types of systems. For instance, under Windows you can create a shortcut icon to REBOL and then edit its Properties (right mouse button) to add the options you desire, such as running REBOL with security disabled. On the Amiga you can add the options to the tooltypes for each icon.
You also can set up icons to run specific scripts with various options when you click on them. For instance, you can create an icon that, on the click of a button, uploads your web site to a remote web server using FTP.
Each line that is input into REBOL is stored in a history block and can be recalled later using the up and down arrow keys. For instance, pressing the up arrow once recalls the prior input line.
The history block containing all input lines can be accessed from the system console object:
probe system/console/history
The resulting block can be saved as a file with:
save %history.r system/console/history
and can be reloaded later with:
system/console/history: load %history.r
These can be placed in your user.r file to give you a history recall that spans multiple REBOL sessions.
When REBOL must wait for a network operation to complete, a busy indicator indicates that something is happening. You can change the indicator with a line like:
system/console/busy: "123456789-"
The busy indicator will not be displayed when REBOL is run with the quiet option. If using a Macintosh, see the above note.
You can quit REBOL at any time by typing:
quit
This also can be done from within a script:
if now/time > 12:00 [quit]
The word exit cannot be used in this example. It is used to exit from a function not from the REBOL system.
You can upgrade to the latest version of the REBOL language free of charge from our web site at http://www.REBOL.com. You can also download copies of the documentation which can be read and printed using a web browser program. For technical support, type do %feedback.r at the REBOL prompt, press ENTER and follow the instructions. Alternately, you can email feedback@REBOL.com.
You can use the help function to get the description, arguments, and refinements for all functions. Type help and the function name at the prompt:
>> help cosine Returns the trigonometric cosine in degrees. Arguments: value -- (number) Refinements: /radians -- Value is specified in radians.
To get a list of all functions with arguments, type what at the REBOL prompt.
You can view the interface specification of any native or mezzanine (higher level system) function. For example,
source join join: func [ "Concatenates values." value "Base value" rest "Value or block of values" ][ value: either series? value [copy value] [form value] append value reduce rest ]
To upgrade to the latest version of REBOL, type upgrade at the REBOL prompt (requires user.r). It 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 it.