readme.txt

                                 REBOL/core
                             Installation Guide
                                Version 2.1

                                  $Date: 1999/07/03 00:13:57 $

License

By downloading or installing the software, you are consenting to be bound
by and are becoming a party to the REBOL Technologies Software End User
License Agreement. If you do not agree to all of the terms of this
agreement, do not install the software.

Support

You can download 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.

  ------------------------------------------------------------------------

How to Install and Run REBOL on Your Platform

Here are the instructions for unpackaging and running the REBOLTM Internet
Messaging Language version 2.1 on supported operating systems as well as
information about platform-specific issues. Refer to the User's Guide and
REBOL Dictionary for more information. Refer to the changes section for a
list of modifications since version 2.0.0. Refer to our website for a
library of example scripts and how-tos.

Unpackaging REBOL

To place the messaging language and supporting files on your computer,
simply extract the compressed file to the directory in which you want to
run, then unarchive it using your platform's compression tool. Enclosed
will be the executable program and supporting scripts. Contact
feedback@REBOL.com if you have problems with unarchiving the compressed
file.

Setting the Home Directory

To simplify using REBOL in multiple directories, we've added the REBOL_HOME
feature. This allows common REBOL scripts (such as %user.r) to reside in
only one directory and be found regardless of the directory in which you
started REBOL. This is accomplished by setting a REBOL_HOME environment
variable in your operating system:

     set REBOL_HOME=C:\REBOL\home

This command must appear in one of your system startup or login scripts.
The form and location of this setting varies between operating systems. For
instance, under Windows-95/98 you would add this to your autoexec.bat file.
See instructions for your system's environment variables.

Each time you run REBOL, it will look for rebol.r and user.r first in your
current directory, then in your home directory.

Setting the Proxy

Computers that use a proxy server require sockets or socks to make the
connection. You can now indicate which socks proxy type the computer uses:

     system/schemes/default/proxy/type: 'socks
             socks ;uses the latest version (currently version 5)
             socks5 ;uses a socks5 handshake on connections
             socks4 ;uses a socks4 handshake on connections
             generic ;uses generic proxy support
             none ;uses no proxy

In addition, you can use set-net to define your email address, mail server,
and optional settings:

     do set-net [email-addr default-server pop-server proxy-server proxy-port-id proxy-type]

Platform Issues

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

     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 offset

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

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. We will be
     supporting a console window in a future release.

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

Macintosh

     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 produce the desired results.
     This is a common problem on the Macintosh, and we will be
     providing additional capability in a future release.

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

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

Running REBOL

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:    11-May-1999
         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 which 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, 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 something else.)

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.

REBOL can be started from the command line with arguments to start REBOL
scripts:

     REBOL file.r
     REBOL file.r script args here
     REBOL --cgi script args here
     REBOL --secure none
     REBOL --cgi --script file.r
     REBOL --cgi --script file.r script args here

Type usage at the REBOL prompt to view the command line arguments.

The CGI variations were added because HTTP servers often append the
remainder of a URL to the command line. CGI runs in quiet mode unless an
error occurs which is then printed to stdout so the user can report the
problem to the webmaster.

To accommodate setting multiple options, you can also provide multiple
characters at the command prompt. For example,

     -cs  ;sets CGI mode with security off (security defaults ON)
     -sq  ;sets security off and the quiet mode on
     -sqw ;sets security off, quiet mode on, and the window off

Dictionary

A concise REBOL Dictionary can be built using the rebdoc.r script that came
with your version of REBOL. To build the HTML file:

     do %rebdoc.r

To build a 100+ page REBOL Dictionary in HTML format, download the script
reboldoc.r from our website, then:

     do %reboldoc.r

It will compile an HTML document that includes all REBOL words, their
arguments, concise and extended descriptions, examples, and links to
related words. The REBOL-generated document is twice as large as the REBOL
program!

Alternately, you can download the dictionary in HTML format from our
website.

Security

REBOL/core 2.1 offers 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.

Directories

Here are some examples of directory references:

     %/Volume/Directory/File   ;path to a file
     %/                        ;root of current volume
     %//path/                  ;root of system
     %path                     ;relative to current directory
     %../path                  ;up one level from current dir
     %.                        ;current directory

To find the name of the current directory::

     what-dir

To view a directory listing, enter the following:

     list-dir %mydir/     ;or whatever directory you want

Help Features

You can use the helpfunction 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 bind
     bind: native [
         "Binds words to a specified context."
         words [block! word!] "A block of words or single word."
         known-word [word!] "A sample word from the target context."
         /copy "Deep copies block before binding it."
     ]

     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
     ]

Upgrade REBOL

You can upgrade to the latest version of REBOL by typing upgrade at the
REBOL prompt. 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.

More Tips

   * Extensive error handling has been added to version 2.1. An error will
     return a description, type, and location of the Script Error. For
     example,

             path? xyz
             Script Error: xyz has no value
             Where: path? xyz

   * Use the now native to return the current date and time if the Time
     Zone is correctly set in your computer's environment variables.
     Usenow/zone to check the time zone setting on your computer. For
     example, Pacific Time is -8:00 or 8 hours behind GMT.
   * And to determine REBOL's version number, type system/version at the
     command line.

  ------------------------------------------------------------------------

Changes in REBOL/core Version 2.1

Here are the changes made to this version since version 2.0.0:

   * Parse-XML function added.
   * Decode-CGI function improved.
   * Enbase and debase functions for base 64, 16, and 2.
   * Protect function added for word modification and error trapping.
   * Switch function has been added.
   * Enhancements made to secure.
   * Upgrade function added to download latest REBOL.
   * The whois protocol has been added.
   * User input can be hidden for password entry.
   * Added the any keyword to parse dialect.
   * Confirm function added for asking yes/no questions.
   * URL based NNTP (news) protocol added.
   * Released on additional platforms.
   * Enhancements made to the proxy object.
   * Extended default permissions for BeOS and UNIX/LINUX systems.
   * Modified version numbering system for seven platforms to accommodate
     extended platform list.
   * FTP now caches up to five connections to increase transfer speed.
   * HTTP now detects circular forwarding.
   * The deep/copy and change-dir functions have been repaired.
   * The bug in saving and loading hash has been fixed.
   * Problems in list have been fixed.
   * Fixed various minor bugs.

  ------------------------------------------------------------------------

           REBOL TECHNOLOGIES SOFTWARE END USER LICENSE AGREEMENT

REBOL Technologies (REBOL) hereby grants you a non-exclusive and
non-transferable license to use the Software and Documentation for the
purpose of designing, developing, writing, testing and running computer
software applications. If you do not agree with the terms herein, then do
not use the software.

The Software and Documentation are licensed, not sold, to you. REBOL
retains all right, title and interest in and to the Software including,
without limitation, all intellectual property rights relating to or
embodied in the Software and Documentation.

You may not remove from the Software or alter or add to its copyright,
trademark and other proprietary rights notices contained in the Software.
You may not reverse engineer, decompile, or disassemble the Software.

You agree to use the Software in compliance with all applicable laws and
regulations including all laws governing the export or re-export of the
Software. You agree to indemnify REBOL from and against your violation of
any such laws or regulations.

THE SOFTWARE AND DOCUMENTATION ARE PROVIDED ON AN "AS IS" BASIS, WITHOUT
WARRANTY OF ANY KIND, EXPRESS, IMPLIED OR STATUTORY INCLUDING WITHOUT
LIMITATION ANY IMPLIED WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT OR
FITNESS FOR PARTICULAR USE OR PURPOSE.

IN NO EVENT SHALL REBOL OR ITS SUPPLIERS OR RESELLERS BE LIABLE TO YOU OR
ANY OTHER PERSON FOR ANY INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES OF ANY KIND INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF
PROFITS OR DATA, ARISING OUT OF THIS AGREEMENT OR USE OF THE SOFTWARE. IN
NO EVENT WILL REBOL BE LIABLE FOR (a) ANY DAMAGES IN EXCESS OF THE AMOUNT
REBOL RECEIVED FROM YOU FOR A LICENSE TO THE SOFTWARE, EVEN IF REBOL HAS
BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES AND NOTWITHSTANDING THE
FAILURE OF ESSENTIAL PURPOSE OF ANY REMEDY, OR (b) FOR ANY CLAIM BY ANY
THIRD PARTY.

This Agreement shall be governed by the laws of the State of California. If
any provision of this Agreement is held to be unenforceable, such provision
shall be reformed only to the extent necessary to make it enforceable. This
Agreement may only be modified in writing signed by both parties.

REBOL can be contacted at www.REBOL.com.
