|
REBOL |
/Internet Communications LanguageTM |
REBOL/Core
Setup Guide
Version 2.2.0
(29-October-1999)
Following are the instructions for unpacking and running the REBOLTM Internet Communications Language on supported operating systems as well as information about platform-specific issues. Refer to the User's Guide and 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 the REBOL Technologies 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. If installing on a multi-user platform, REBOL will also read these files from the current user's home directory.
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 on proxy setup.
| REBOL Note |
|
If you make a mistake or later decide to change any of these network settings, restart the setup dialog by entering: set-user at the REBOL prompt. 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 directly modified with any text editor. Within the file is a line such as: set-net [ luke@rebol.com mail none proxy 1080 socks ] The line can be changed to modify your startup network configuration. To obtain more information about the set-net function type: help set-net or download the REBOL Dictionary from the REBOL Technologies web site. In addition, the source code for set-user can be viewed by typing: source set-net To output it to a text file, type: echo %set-net.r source set-net echo none |
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 communications language is platform independent. A script produced on a Windows NT system, for example, can be run on a Macintosh, Amiga, Solaris SPARC, Linux, Windows CE, 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 with 8 hour 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.
The REBOL console interface now maps shift-left to the home key and shift-right to the end key.
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"
The REBOL console interface now uses a TERMCAP entry to determine the key sequences to be used.
Libcurses is a library found on most posix-compliant platforms. If you receive the following message,
ld.so.1: rebol: fatal: libcurses.so.1: open failed: No such file or directory
you will need to install libcurses on the system or link libcurses to a compatible library (such as ncurses). First, search to determine whether it is elsewhere on your machine:
find / -name "*curses*" 2>/dev/nullIf libcurses.so.1 is found, copy it to /usr/lib.
Alternately, email feedback@REBOL.com with the subject: "Please send libcurses REBOL x.x.x.x.x" replacing xs with the version of REBOL/Core that you are running. The version with libcurses will be automatically emailed to you.
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.
On the REBOL console interface for Win32 machines, the Ctrl (control) versions of the cursor keys scroll the display up, down, left, or right. Control-page-up and control-page-down scroll a screen at a time. Control-home and control-end scroll to the first and last line of the display, respectively. These control sequences are not passed to the console input port.
The REBOL console on Windows machines now 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.
Note that older computers and some palmtops with minimal 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: 9-Sep-1999
Needs: 2.2.0
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 secure function has changed with version 2.2. The new function provides much more flexibility in setting and controlling the security features of REBOL. The new function is not backward compatible with previous versions of REBOL and will require changes to scripts that use the secure native function.
The new secure function provides a number of new features. It is now possible to specify separate security settings for file and network access. In addition, file access can be specified with a much finer granularity. Finally, the current security settings are returned as a result of calling the secure function.
The new function's syntax employs a dialect to specify the many possible security settings. The normal dialect consists of a block of paired values. The first value in the pair specifies what is being secured. This value can be one of the following:
net - the word net is used to control network security.
file - the word file is used to control generic file security.
file! - a file! is used to control specific file or directory security.
The second value in the pair specifies the level of security. This can be in one of two forms. The first form simply sets the level of security for all forms of access. This form consists of a word with one of the following values:
allow - allow access with no restrictions ( formerly none ).
ask - ask permission if any restricted access occurs.
throw - throw an error if any restricted access occurs.
quit - quit this REBOL session if any restricted access occurs.
For example, to allow all network access, but to quit on any file access the following would be used:
secure [ net allow file quit ]
File access can be broken down by type of access. To specify a more detailed access, a block can replace the security level word. Within the block are pairs of security levels and access types. The access type words are:
read - controls read access.
write - controls write, delete and rename access.
execute - controls execute access ( REBOL/command ).
all - controls all access.
The pairs are read in order, with later pairs modifying the effect of earlier pairs. This permits setting one type of access without explicitly setting all others. For example:
[ask all allow read]
says to set the security level to ask for all operations except for reading which is to be allowed.
In the same way that security access pairs are read in order and used to modify previous settings, settings for individual files and directories modify previous settings providing extensive control over security.
If no security access level is specified for either network or file access, it defaults to ask.
There is a special case where the secure function takes a single word argument that must be one of the security access levels. In that case, the security level for all network and file access is set to that level. This is very similar to the old syntax except that there is no way to specify separate read and write access like there is in the old syntax. The default security level (which corresponds to the old read level) is now:
secure [ net allow file [ ask all allow read ] ]
Also, if the argument to the secure function is the value none, no change is made to the security levels, but the current settings are still returned.
The secure function now returns a value that consists of the current state before the new security settings were made. This return value is a block containing the global network and file settings followed by any specific file or directory settings. This is true even if the single word argument form has been used. This allows the current security level to be modified by querying the current security settings, modifying the block returned and using it with the secure function to set the new values.
As in the past, any change to the current security settings that result in a lower level of security will produce a change security settings request unless the REBOL session is running in quiet mode which will, instead, terminate the REBOL session. No query is ever generated when security levels are raised.
If an error occurs parsing the security block argument, the current settings will not be modified.
The ask security level query operates the same as before with the addition of an option to allow all access.
As in previous versions, the -s and +s arguments set minimum and maximum security levels and are equivalent to specifying secure allow and secure quit respectively. The --secure argument can now be followed by one of the security access levels which will affect both network and file access.
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:
This copy of [Platform] REBOL/Core [your version] is not up to date. Current version is: [newest version] Download current version?