REBOL 3 Usage: Starting REBOL

Contents

Security Issues

By default, security is set to prevent scripts from modifying any of your files or directories.

Port Security

The secure function provides flexibility in setting and controlling the security features of REBOL. The current security settings are returned as a result of calling the secure function.

Security settings use a REBOL dialect, that is, a language within a language. The normal dialect consists of a block of paired values. The first value in the pair specifies what is being secured:

file	specifies file security.
net	specifies network security.

A file name or directory path allows you to specify security levels for a specific file or directory.

The second value in the pair specifies the level of security. This can be either a security level word or a block of words. The security level words are:

allow	allow access with no restrictions.
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:

secure [
    net allow ;allows any net access
    file quit ;any file access will cause the program to quit
]

If a block is used instead of a security level word, it can contain pairs of security levels and access types. This lets you specify a greater level of detail about the security you require. The access types allowed are:

read	controls read access.
write	controls write, delete and rename access.
all	controls all access.

The pairs are processed in the order they appear, with later pairs modifying the effect of earlier pairs. This permits setting one type of access without explicitly setting all others. For example:

secure [
    net allow
    file [
        ask all
        allow read
    ]
]

The above sets the security level to ask for all operations except for reading which is to be allowed. This technique can also be used for individual files and directories. For example:

secure [
    net allow
    file quit
    %source/ [ask read]
]

asks if an attempt is made to read the %source directory. Otherwise, it uses the default ('quit).

There is a special case in which 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.

secure quit

The secure function also accepts none!, allowing access with no restrictions (same as allow).

secure none

The default security level is now:

secure [
    net allow
    file [
        ask all
        allow read
    ]
]

If no security access level is specified for either network or file access, it defaults to ask. The current settings will not be modified if an error occurs parsing the security block argument.

[bad-link:concepts/.txt]

Prior Security Settings

The secure function now returns the prior security settings before the new settings were made. This is a block with the global network and file settings followed by file or directory settings. The query word can be used to obtain the settings without modifying them.

current-security: secure query

You can modify the current security level by querying the current settings, modifying them, then using the secure function to set the new values.

Lowering the security level produces a change security settings request. The exception is when the REBOL session is running in quiet mode which will, instead, terminate the REBOL session. No query is generated when security levels are raised. Note that the security request now includes an option to allow all access for the remainder of the scripts processing.

When running REBOL from the shell, the -s argument is equivalent to:

secure allow

and the +s arguments is equivalent to:

secure quit

You can now follow the --secure argument with one of the security access levels for both network and file access:

rebol --secure throw

Program Arguments

There are a number of arguments that can be specified in a shell command line, in a batch script, or in the properties of an icon. To view the arguments and options available for any version of the REBOL language, type usage at the console prompt.

The command line usage is:

    REBOL <options> <script> <arguments>

All fields are optional. Supported options are:

    --cgi (-c)       Check for CGI input
    --do expr        Evaluate expression
    --help (-?)      Display this usage information
    --nowindow (-w)  Do not open a window
    --noinstall (-i) Do not install (View)
    --quiet (-q)     Don't print banners
    --reinstall (+i) Force an install (View)
    --script file    Explicitly specify script
    --secure level   Set security level:
                     (allow ask throw quit)
    --trace (-t)     Enable trace mode
    --uninstall (-u) Uninstall REBOL (View)

Other command line options:

    +q               Force not quiet (View)
    -s               No security
    +s               Full security
    -- args          Provide args without script

Examples:

    REBOL script.r
    REBOL script.r 10:30 test@domain.dom
    REBOL script.r --do "verbose: true"
    REBOL --cgi -s
    REBOL --cgi --secure throw --script cgi.r "debug: true"
    REBOL --secure none

Again, the format of the command line is:

REBOL options script arguments

Where:

options	one or more of the program options. See [bad-link:concepts/specifying.txt] Options below for more details.
script	the file name of the script you want to run. If the file name contains spaces, it should be typed in quotes.
arguments	the arguments passed to the script as a string. These arguments can be accessed from within the script.

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

Shortcut Icons

In some operating systems, like Windows or AmigaOS, you can create icons that supply any of the above options as part of the icon. Using this technique, you can create icons that directly execute REBOL scripts with the correct options.

Script File

Typically, you run REBOL with the file name of the script that you want it to evaluate. Only one script file is allowed. For example:

REBOL script.r

If the file name contains spaces, it must be provided in double quotes.

Specifying Options

Program options are identifed with a plus (+) or minus (-) before a character or by a double dash (--) before a word. This is a standard practice for specifying program options on most operating systems.

Here are several examples of how options are used.

To run a script with an option, such as the -s option, which evaluates the script with security turned off, type:

REBOL -s script.r

To obtain usage information about REBOL, type:

REBOL -?
REBOL --help

To run REBOL without opening a new window (this is done when you need to redirect output to a file or server), type:

REBOL -w
REBOL --nowindow

To prevent the printout of startup information which is useful if you are redirecting the output to a file or server, type:

REBOL -q
REBOL --quiet

To evaluate a REBOL expression from the command line, type:

REBOL --do "print 1 + 2"
REBOL --do "verbose: true" script.r

This lets you evaluate a remote script with a line such as:

REBOL --do "do http://www.rebol.com/speed.r"

To change the security level of REBOL, type:

REBOL -s script.r
REBOL --secure none script.r

To use REBOL scripts for CGI (see the [bad-link:concepts/cgi.txt] - Common Gateway Interface Section of the [bad-link:concepts/network.txt] Protocols Chapter for more information), type:

REBOL -c cgi-script.r
REBOL --cgi

Multiple options are also allowed. Multiple single character options can be included together. Multiple full word options must be separated with spaces.

REBOL -cs cgi-script.r
REBOL --cgi --secure none cgi-script.r

The above example runs in CGI mode, with security turned off. The shorthand method is required for various web servers that restrict the number of arguments allowed on the command line (such as the Apache server on Linux).

File Redirection

On most systems, it is possible to redirect standard input and output from and to files. The example:

rebol -w script.r > output-file

redirects output to a file. Similarly,

rebol -w script.r < input-file

redirects input from a file.

When Redirecting File IO...

Use the -w option to prevent the REBOL console window from opening, as it interferes with standard input and output redirection.

Script Arguments

Everything on the command line that follows the script file name is passed to the script as its argument. This allows you to write scripts that accept arguments directly from the command line. For example, if you start REBOL with the line:

REBOL script.r 10:30 test@domain.dom

There are two ways to obtain the command line arguments. The first method returns the arguments as a block of REBOL values:

probe system/options/args
["10:30" "test@domain.dom"]

The second method returns the arguments as a string:

probe system/script/args
"10:30 test@domain.dom"

Version dependent note:

Earlier versions of REBOL returned the block of values for the script/args field (similar to options/args). It is advised that you verify that your script receives the correct args datatype as shown above.

Startup Files

When REBOL starts, it attempts to load the rebol.r and user.r boot files. These files are optional, but when found, they can be used to set up networking, define common functions, and initialize data used by 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 is overwritten with each new release of REBOL.

The user.r script file holds user preferences. You can edit this file and add whatever definitions or data you require.

On multi-user systems, there can be a different user.r for every user. While the user.r file is not part of the distribution, it is automatically generated if it does not exist.

When REBOL starts, it looks for the rebol.r and user.r files first in the home directory and, if not found there, then in the current directory.

To set a HOME directory, you can set an environment variable in the appropriate login or startup script for your system. Note that some systems, such as UNIX or Linux may already do this, so you do not need to.

For example, on Windows NT to set HOME you can add:

set HOME=C:\REBOL

to your environment by following these steps:

1. Choose Settings Control Panel in the Windows Start Menu,
2. Double-click the System icon, and select the Environment tab.
3. Type HOME in the variable field and [bad-link:concepts/\rebol.txt] (or the path to where you put the REBOL program) in the value field.

On Unix systems, you can set the path to REBOL by adding a line like the following in your login shell script or profile:

set HOME=/usr/bin/rebol

For some versions of REBOL, the path is stored in a .rebol file that is located in your home directory.