Core

REBOL™ TECHNOLOGIES
REBOL/CORE USER
GUIDE
VERSION 2.3
SEPTEMBER 2000
REBOL™ Technologies, 301 South State Street, Ukiah, CA 95482
http://www.REBOL.com
Copyright © 2000 REBOL Technologies
All rights reserved.
Printed in the United States of America
No part of this publication may be stored in a retrieval system, transmitted, or reproduced in any way, including
but not limited to photocopy, photographic, magnetic or other record, without the prior agreement and written
permission of REBOL Technologies.
Windows® is a registered trademark of Microsoft Corporation.
REBOL and the REBOL logo are trademarks of REBOL Technologies.
All other product names, marks, logos, and symbols may be trademarks or registered trademarks of their
respective owners.
We would like to thank the following individuals for their contributions in the production of this manual:
Carl Sassenrath Barbara Ramsey Erin Thomas Scott Allen
Jennifer Nelson Dan Ramsey Cynthia Sassenrath Dan Stevens
Dave Turner Jessica Johnson Mitch Rodgers Andrew Morton
09292000
Contents
Introduction
About REBOL/Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
About this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
Additional Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii
Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii
Contacting REBOL Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . xxiii
REBOL Welcomes Your Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv
Chapter 1. Operation
Installing REBOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Distribution Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Network Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Proxy and Firewall Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
License Agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
Starting REBOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
From an Icon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
From a Shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
From Another Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Security Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Program Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
Script File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-10
Specifying Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-10
File Redirection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-12
Script Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-12
iii
Startup Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13
Quitting REBOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14
Using the Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14
Mulitple Line Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-15
Interrupting a Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-16
History Recall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-16
Word Completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-16
Busy Indicator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-17
Network Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-17
Virtual Terminal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-17
Getting Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-18
Online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-18
Viewing Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-22
Download Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-23
Script Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-23
User Mailing List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-23
Contacting Us . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-23
Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-25
Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-25
Redirecting Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-26
Upgrading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-26
Chapter 2. Quick Tour

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Dates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Money . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Tuples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
iv
Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Email Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Filenames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
Binary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12
Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13
Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15
Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16
Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17
Networking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-19
HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-19
FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-20
SMTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-20
POP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-20
NNTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21
Daytime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21
Whois . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21
Finger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21
DNS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-22
TCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-22
v
Chapter 3. Expressions
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
Evaluating Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6
Evaluating Console Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6
Evaluating Directly Expressed Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6
Evaluating Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7
Reducing Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9
Evaluating Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-10
Evaluating Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11
Evaluation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12
Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13
Word Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13
Word Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15
Setting Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-16
Getting Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18
Literal Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-19
Unset Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-21
Protecting Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22
Conditional Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-23
Conditional Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-23
Any and All . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-26
Conditional Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-28
Common Mistakes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30
Repeated Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-31
Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-31
Repeat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-32
For . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-33
Foreach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-35
vi
Forall and Forskip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-36
Forever . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-38
Break . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-38
Selective Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-40
Select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-40
Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-41
Stopping Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-45
Trying Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-46
Chapter 4. Scripts
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
File Suffix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Script Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7
Program Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8
Running Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9
Loading Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9
Saving Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11
Commenting Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-12
Style Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13
Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-13
Word Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-16
Script Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-18
Function Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-18
Script File Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-18
Embedded Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-19
Embedded Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-19
Minimize Globals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-19
Script Cleanup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20
vii
Chapter 5. Series
Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
Traversing a Series . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
Skipping Around . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Extracting Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-10
Extracting a Sub-series . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12
Inserting and Appending . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13
Removing Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16
Changing Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19
Series Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-21
Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-21
Navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-21
Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-22
Extraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-22
Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-23
Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-23
Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-24
Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-24
Series Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-24
Block Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-25
String Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-25
Pseudo-types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-26
Type Test Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-26
Series Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-26
Length? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-26
Head? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-29
Tail? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-29
Index? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-30
Offset? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-31
Making and Copying Series . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-31
vii i
Partial Copies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-33
Deep Copies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-33
Initial Copies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-34
Series Iteration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-36
While Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-36
Forall Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-37
Forskip Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-39
Foreach Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-39
The Break Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-40
Searching Series . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-41
Simple Find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-41
Refinement Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-42
Partial Searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-43
Tail Positions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-44
Backward Searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-45
Repeated Searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-46
Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-46
Wildcard Searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-49
Select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-50
Search and Replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-51
Sorting Series . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-53
Simple Sorting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-54
Group Sorting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-56
Comparison Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-56
Series as Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-57
Unique . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-58
Intersect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-58
Union . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-60
Exclude . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-62
Difference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-62
Multiple Series Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-64
ix
Modification Refinements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-65
Part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-65
Only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-67
Dup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-67
Chapter 6. Block Series

Blocks of Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
Paths for Nested Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3
Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6
Creating Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
Initial Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9
Composing Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9
Chapter 7. String Series

String Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2
Converting Values to Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4
Join . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4
Rejoin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6
Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7
Reform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8
Mold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9
Remold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-10
String Spacing Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-11
Uppercase and Lowercase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-15
Checksum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-15
Compression and Decompression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-17
Number Base Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-18
Internet Hexadecimal Decoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-20
x
Chapter 8. Functions
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
Evaluating Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3
Argument Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5
Refinements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7
Function Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9
Defining Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10
Interface Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11
Literal Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-14
Get Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-16
Defining Refinements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-17
Local Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-18
Returning a Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-20
Returning Multiple Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-22
Nested Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-23
Unnamed Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-24
Conditional Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-25
Function Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-26
Forward References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-29
Scope of Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-29
Reflective Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-31
Online Function Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-33
Viewing Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-35
Chapter 9. Objects
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2
Making Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2
Cloning Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4
xi
Accessing Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6
Object Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7
Prototype Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-10
Referring to Self . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-12
Encapsulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-13
Reflective Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-15
Chapter 10. Math

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2
Scalar Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2
Evaluation Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-8
Standard Functions and Operators . . . . . . . . . . . . . . . . . . . . . . . . . . 10-10
absolute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-10
add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-11
complement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-12
divide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-13
multiply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-14
negate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-15
random . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-16
remainder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-18
subtract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-18
Type Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-20
Comparison Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-20
equal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-20
greater . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-21
greater-or-equal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-21
lesser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-22
lesser-or-equal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-23
not equal to . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-24
same . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-25
xii
strict-equal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-26
strict-not-equal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-27
Logarithmic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-28
exp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-28
log-10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-28
log-2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-29
log-e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-29
power . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-29
square-root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-29
Trigonometric Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-29
arccosine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-29
arcsine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-30
arctangent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-30
cosine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-30
sine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-30
tangent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-30
Logic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-31
and . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-31
or . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-32
xor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-32
complement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-33
not . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-33
Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-33
Attempt to divide by zero . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-34
Math or number overflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-34
Positive number required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-34
Cannot use operator on datatype! value . . . . . . . . . . . . . . . . . . . . . . . . . 10-34
Chapter 11. Files

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2
Names and Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2
x iii
File Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2
Path Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-3
Case Sensitivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-5
File Name Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-5
Reading Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-6
Reading Text Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-6
Reading Binary Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-7
Reading Over the Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-7
Writing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-8
Writing Text Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-8
Writing Binary Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-9
Writing Files to a Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-9
Line Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-10
Blocks of Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-11
File and Directory Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-13
Directory Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-13
File Existence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-14
File Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-14
File Modification Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-14
Directory Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-15
Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-16
Reading a Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-16
Making a Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-17
Renaming Directories and Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-17
Deleting Directories and Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-18
Current Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-19
Changing the Current Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-19
Listing the Current Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-19
xiv
Chapter 12. Network Protocols
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2
REBOL Networking Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3
Modes of Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-3
Specifying Network Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-4
Schemes, Handlers, and Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-6
Initial Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-9
Basic Network Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-9
Proxy Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-10
Other Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-12
Access to Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-13
DNS - Domain Name Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-14
Whois Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-16
Finger Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-18
Daytime - Network Time Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 12-19
HTTP - Hyper Text Transfer Protocol . . . . . . . . . . . . . . . . . . . . . . . . 12-20
Reading a Web Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-20
Scripts on Web Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-21
Loading Markup Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-22
Other Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-24
Acting Like a Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-25
Posting CGI Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-25
SMTP - Simple Mail Transport Protocol . . . . . . . . . . . . . . . . . . . . . . . 12-26
Sending Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-26
Multiple Recipients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-27
Bulk Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-28
Subject Line and Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-29
Debug Your Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-29
POP – Post Office Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-30
Reading Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-30
xv
Removing Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-32
Handling Email Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-33
FTP - File Transfer Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-36
Using FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-36
FTP URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-37
Transferring Text Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-37
Transferring Binary Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-39
Appending to Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-39
Reading Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-40
File Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-40
Making Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-42
Deleting Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-42
Renaming Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-42
About Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-43
Transferring Large Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-44
NNTP – Network News Transfer Protocol . . . . . . . . . . . . . . . . . . . . . 12-45
Reading the Newsgroup List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-45
Reading All Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-45
Reading Single Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-46
Handling News Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-47
Sending a News Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-47
CGI - Common Gateway Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 12-49
CGI Server Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-49
CGI Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-50
Generating HTML Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-52
CGI Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-53
CGI Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-54
Processing HTML Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-56
TCP - Transmission Control Protocol . . . . . . . . . . . . . . . . . . . . . . . . 12-59
Creating Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-59
Creating Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-61
xvi
A Tiny Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-63
Testing TCP Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-64
UDP (User Datagram Protocol) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12-64
Chapter 13. Ports

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2
Opening a Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3
Open Refinements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-4
Closing a Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4
Reading from a Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-5
Writing to a Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-6
Updating a Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-7
Waiting for a Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-7
Other Port Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-9
Line Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13-9
Read and Write Only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-10
Direct Port Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-10
Skipping Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-11
File Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-12
Directory Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-13
Chapter 14. Parsing

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-2
Simple Splitting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-2
Grammar Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4
Skipping Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-7
Match Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-8
Recursive Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-10
Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-10
x vii
Return Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-11
Expressions in Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-12
Copying the Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-14
Marking the Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-14
Modifying the String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-16
Using Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-17
Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-18
Dealing with Spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-19
Parsing Blocks and Dialects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-21
Matching Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-21
Matching Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-22
Characters Not Allowed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-22
Dialect Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-22
Parsing Sub-blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14-24
Summary of Parse Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-26
Appendix A. Values
Number Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2
Decimal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2
Integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5
Series Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-8
Binary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-8
Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10
Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-14
File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-17
Hash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-19
Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-20
Issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-22
List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-24
Paren . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-27
Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-30
xvi ii
String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-40
Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-43
URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-45
Other Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-48
Character . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-48
Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-51
Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-58
Money . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-62
None . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-67
Pair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-69
Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-71
Tuple . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-77
Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-79
Appendix B. Errors
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-2
Error Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2
Syntax Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2
Script Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3
Math Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3
Access Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3
User Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3
Internal Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3
Catching Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3
Error Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-6
Generating Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-7
Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-11
Syntax Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B-11
Script Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-12
Access Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-22
x ix
Internal Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-28
Appendix C. Console
Command Prompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-2
History Recall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-2
Busy Indicator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-3
Advanced Console Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-3
Keyboard Input Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-4
Terminal Output Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-4
xx
Introduction
This chapter provides an introduction to REBOL/Core. It contains the following

information:
■ “About REBOL/Core” on page xxii

■ “About this Guide” on page xxii
■ “Additional Documentation” on page xxiii
■ “Document Conventions” on page xxiii

■ “Contacting REBOL Technical Support” on page xxiii
■ “REBOL Welcomes Your Comments” on page xxiv
xxi
About REBOL/Core 0
REBOL is the Relative Expression-Based Object Language designed by Carl

Sassenrath, the software architect responsible for the Amiga OS -- one of the world's
first personal computer multitasking operating systems.
REBOL is the next generation of distributed communications. REBOL code and data
can span more than 40 platforms without modification using ten built-in Internet
protocols. A script written and executed on a Windows platform can also be run on
a UNIX platform with no changes. REBOL can exchange not only traditional files
and text, but also graphical user interface content and domain specific dialects that
communicate specific meaning between systems. Distributed communications
includes information exchanged between computers, between people and
computers, and between people. REBOL can be used for all of these.
REBOL is a messaging language that provides a broad range of practical solutions

to the daily challenges of Internet computing. REBOL/Core is the foundation for all
of REBOL’s technology. While designed to be simple and productive for novices, the
language extends a new dimension of power to professionals. REBOL offers a new
approach to the exchange and interpretation of network-based information over a
wide variety of computing platforms.
REBOL scripts are as easy to write as HTML or shell scripts. A script can be a single
line or an entire application.
About this Guide 0
This guide provides the basic information necessary for using REBOL/Core. It
assumes that the reader is already familiar with general programming and operating
system terminology and concepts.
xx ii REBOL/Core User Guide Version 1.0

Additional Documentation 0
The following documentation should be used in conjunction with this guide:
REBOL Dictionary
For copies of these documents, please refer to the REBOL Technologies Web
site at http://www.REBOL.com.
Document Conventions 0
The following table describes the typographical conventions used in this guide.
Item Convention Example
Native REBOL words Bold make/library

REBOL code samples Bold, do %feedback.r
monospace
type
Returned results in REBOL code Non-bold, == true
samples monospace
type
File names, directory names, program Monospace myfile.txt
names, variable names, and other type
programming language keywords.
Contacting REBOL Technical Support 0
If you encounter a problem, contact REBOL Technologies by sending an email

message to [email protected]. The easiest way to do this is to run the REBOL
script, feedback.r, which is in the REBOL directory, as shown in the following
example:
do %feedback.r
REBOL/Core User Guide Version 1.0 xxiii

This script presents a menu that guides you though the feedback process.
Using the feedback script automatically includes your REBOL version number in the
email sent to REBOL's help desk.
REBOL Welcomes Your Comments 0
To help us with future versions of this documentation, we want to know about any
corrections or clarifications that you would find useful. Please include in your
message the following information:
■ Title and version of the guide
■ Your name, company name, job title or functional area, phone number, and
email address
Send comments and corrections to [email protected].
xx iv REBOL/Core User Guide Version 1.0

1
Operation
This chapter gives basic information on how to install and operate REBOL/Core. It
includes the following information:
■ “Installing REBOL” on page 1-2

■ “Starting REBOL” on page 1-4
■ “Quitting REBOL” on page 1-14
■ “Using the Console” on page 1-14

■ “Getting Help” on page 1-18
■ “Errors” on page 1-25
■ “Upgrading” on page 1-26
1- 1
Operation
Installing REBOL
Installing REBOL A
REBOL installation takes only a few seconds and is very easy, non-intrusive, and
non-disruptive.
For REBOL/Core, the only installation procedure is to uncompress the distribution

files and store them in any directory on your system. In addition, some operating
systems such as UNIX, require an environment variable, REBOL_HOME, to help
REBOL find its bootstrap files.
For other REBOL products, installation may require you to provide additional
information, such as where to store related files. Refer to the release notes that are
included with the distribution files.
Distribution Files 0
REBOL/Core includes the following distribution files:
■ rebol.exe or rebol—An executable program that starts the REBOL console.
■ rebol.r—A system bootstrap file.
■ setup.html-Information about the set-up and installation of REBOL/Core.
■ notes.html—Notes about the current release.
■ feedback.r—A script for submitting user feedback or questions to REBOL

Technologies.
■ scripts.r— A script that downloads the REBOL script library, which contains
■ docs.r—A script that downloads all current REBOL documentation.
Network Setup 0
The first time you start REBOL, it prompts you for network information. This
information is optional. Some protocols, such as email or FTP, require an email
address or an email server name. In addition, if you are behind a firewall or use a
proxy server, you need to provide specific information to access the Internet.
To set up your network:
1-2 REBOL/Core User Guide Version 2.3

Operation
Installing REBOL
■ Type your email address. For example, [email protected].

■ Type the name of your email server. For example, [email protected].
■ Use the name of the email server you normally use. If you are not sure of the
name of the server, contact your network administrator or Internet service
provider for the name of your SMTP (email) server.
■ Specify whether you use a proxy server. If you are directly connected to the
Internet with a modem or ethernet, type N (no). If you use a proxy or firewall,
provide the required information as described in “Proxy and Firewall Settings”
below.
■ Once the startup questions are answered, REBOL creates a user.r file and
places your network settings in it. You can change these settings at any time by
editing the user.r file.
Proxy and Firewall Settings 0
Frequently, organizations use a firewall or proxy server to protect access to and from
the Internet. Before REBOL can access the Internet through these systems, you need
to provide some additional information.
■ To provide proxy server information:
■ When REBOL asks if you use a proxy server, answer by typing Y (yes).
■ Type the name of your proxy host. This is the computer or firewall on your
network serving as a proxy.
■ Type the port number used by the proxy host for proxy requests. Typically, this
is port 1080, but this can vary. If you don’t know the port number, check your
Web browser settings or ask your network administrator.
REBOL/Core User Guide Version 2.3 1- 3

Operation
Starting REBOL
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. The following 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 settings are provided as the sixth argument to the set-net function called in
the user.r file. For more information about modifying the proxy settings in the
user.r file, refer to the “Network Protocols” Chapter.
License Agreement 0
The REBOL end-user license agreement that you agreed to when you downloaded
or installed REBOL can be viewed at any time from the REBOL console by typing
license at the REBOL prompt.
Starting REBOL A
REBOL runs over a large variety of systems. You start REBOL the same way you
start other applications on your system. Depending on the specific operating
system, REBOL can be started from one or more of the following: an icon, the
command shell, or other applications.
From an Icon 0
REBOL can be started by double-clicking the REBOL program icon, an associated

.r file, or a REBOL shortcut icon.
If you double-click on the program icon, REBOL boots, displays the console, and
provides you with a prompt.

Operation
Starting REBOL
If you want to launch REBOL with a script, you can do so in the following ways:
■ Drag the script to the program icon

■ Associate the file with the REBOL program
■ Create a shortcut or alias icon.
From a Shell 0
From a shell command line, go to the directory that contains the REBOL.exe file,
and type rebol or ./rebol.
On some operating systems, such as UNIX, you can create alias shell commands
that are able to run REBOL with a set of arguments and files. In addition, UNIX
enables you to create shell scripts that include a path, such as !#/path/to/rebol,
in the top line of the script file. When you type the name of the script file at the
command prompt, UNIX will launch REBOL to execute the script.
From Another Application 0
For writing and debugging REBOL scripts, it is handy to set up your favorite text
editor to run REBOL and pass it the script file you are editing. Each text editor does
this differently. For instance, in the Premia Codewright editor you can use the
language compiler options to set up REBOL. Specify the REBOL program rather
than a compiler. You can press a single key that saves the script and evaluates it.
Security Issues 0
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. This function is not backward-compatible with previous
versions of REBOL and will require changes to scripts that use the secure native
function. The current security settings are returned as a result of calling the secure
function.

Operation
Starting REBOL
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:
The word net applies to network security.
The word file applies to default level of file 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 (formerly none.)
ask -- ask permission if any restricted access occurs.
throw -- throw an error if any restricted accessoccurs.
quit -- quit this REBOL session if any restricted access
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.

Operation
Starting REBOL
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. This is very similar to the previous syntax
except that there is no way to specify separate read and write access using this
form.
secure quit
The secure function also accepts none, allowing access with no restrictions (same
as allow).
The default security level (which corresponds to the old read level) is now:
secure [
net allow
file [
ask all
allow read
]
]

Operation
Starting REBOL
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.
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.
As in the past, 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

Operation
Starting REBOL
Program Arguments 0
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:
(none write read throw quit)
--trace (-t) Enable trace mode
Other command line options:
+q Force not quiet (View)

-s No security
+s Full security
Examples:
REBOL script.r
REBOL script.r 10:30 [email protected]
REBOL script.r -do "verbose: true"
REBOL --cgi –s
REBOL --cgi --secure throw --script cgi.r
REBOL --secure none

Operation
Starting REBOL
Again, the format of the command line is:
REBOL options script arguments
Where:
■ options is one or more of the program options. See “Specifying Options”

below for more details.
■ script is the file name of the script you want to run. If the file name contains
spaces, it should be typed in quotes.
■ arguments are 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.
NOTE: In some operating systems, like Windows or Amiga, 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 0
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 typed in double quotes.
Specifying Options 0
Program options are identifed with a plus sign (+) or minus sign (–) before a
single character or by a double dash (--) before a full word. This is a standard
practice for specifying program options on most operating systems.
Here are several examples of how options are used.

Operation
Starting REBOL
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
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 “CGI - Common Gateway Interface” Section
of the “Network Protocols” Chapter for more information), type:
REBOL -c cgi-script.r
REBOL --cgi

Operation
Starting REBOL
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 0
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.
NOTE: The -w option prevents the REBOL console window from opening, as it
interferes with standard input and output redirection.
Script Arguments 0
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.
REBOL script.r 10:30 [email protected]

Operation
Starting REBOL
The script in the above example is passed these arguments in the system object. To
print the arguments that have been passed, type:
probe system/script/args
["10:30" "[email protected]"]
Startup Files 0
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 current
directory. If the files are not found, REBOL looks in a directory that is specified with
the operating system environment variable REBOL_HOME or by examining the
contents of the .rebol file in your user home directory.
To provide a home directory, you can set an environment variable in the appropriate
login or startup script for your system. For example, on Windows NT you can add:
set REBOL_HOME=C:\REBOL
to your startup by following these steps:
■ Choose Settings > Control Panel in the Windows Start Menu,
■ Double-click the System icon, and select the Environment tab.
■ Type REBOL_HOME in the variable field and C:\REBOL in the value field.

Operation
Quitting REBOL
■ 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 REBOL_HOME=/usr/bin/rebol
For some versions of REBOL, the path is stored in a .rebol file that is located in
your home directory.
Quitting REBOL A
To exit REBOL at any time, select Quit from the Console File menu or by type quit
or q at the prompt. You can also quit the program from within a script:
if now/time > 12:00 [quit]
The REBOL console may also quit if an error occurs during startup.
Note: Do not use the word exit to quit REBOL. This word is used for exiting
functions and generates an error if used for quitting.
Using the Console A
Whenever you run REBOL/Core, it opens a console to display output and accept
input. If you provide a script argument to the program, the script is run, and you
see the output from that script. If you do not provide a script file, the console
prompts you for input. The input prompt looks like this:
>>
If you type an expression at the input prompt, it is evaluated and any returned
values are displayed following the output prompt:
==.

Operation
Using the Console
For example:
>> 100 + 20
== 120
>> now - 7-Dec-1944
== 20341
NOTE: The prompt characters can be changed. See the “Console” Appendix for more
information.
The console also becomes active if a script encounters an error or if the script calls
the halt function directly.
Mulitple Line Input 0
If you begin a block on the command line and don’t end it, the block is extended to
the next line. This is indicated by a prompt that begins with a bracket and is
followed by indentation. The line will be indented four spaces for each open block.
For example:
loop 10 [
[ print "example"
[ if odd? random 10 [
[ print "here"
[ ]
[ ]
This is also true for multilined strings enclosed in braces.
Print {This is a long

{ string that has more
{ than one line.}
Brackets and braces that appear within quoted strings are ignored. You can escape
from input at any time by pressing the ESCAPE key.

Operation
Using the Console
Interrupting a Script 0
A script can be interrupted by pressing the ESCAPE key, which returns immediately
to the command prompt.
During some types of operating system or network activity there may be a delay in
response from the ESCAPE interrupt.
History Recall 0
Each line that is typed into REBOL is stored for later recall. The up and down arrow
keys are used to scroll through the list of previous lines. For instance, pressing the
up arrow once recalls the prior input line.
History lines can be written to a file by saving the history block. See the “Console”
Appendix for more information.
Word Completion 0
To help speed typing of long words and file names, the REBOL console has word
and file name completion. After typing a few letters of a word, press the tab key.
If the letters uniquely identify the word, the rest of the word is displayed. For
example, typing:
>> sq
then pressing tab results in:
>> square-root
If the letters do not uniquely identify the word, you can press tab again to get a list
of choices. For example, typing:
>> so
then pressing tab twice results in:
>> sort source

so

Operation
Using the Console
and you can type the rest of the word or enough of it to be unique.
Completion works for all words, including user-defined words.
Completion also works for files when they are begun with a percent sign.
>> print read %r
Pressing tab would produce:
>> print read %rebol.r
depending on your current directory.
Busy Indicator 0
When REBOL waits for a network operation to complete, a busy indicator appears
to indicate that something is happening. You can change the indicator to your own
character pattern. See the “Console” Appendix for more information.
Network Connections 0
As network connections are initiated, a message appears on the console. For

instance, typing:
>> read http://www.rebol.com
connecting to: www.rebol.com
If necessary, you can disable this output by setting the quiet flag. See the “Console”
Appendix for more information.
Virtual Terminal 0
The console provides virtual terminal capability that allows you to perform
operations such as cursor movement, cursor addressing, line editing, screen
clearing, control key input, and cursor position querying.

Operation
Getting Help
The virtual terminal uses the standard ANSI character sequences. This allows you
to write platform-independent terminal programs such as text editors, email clients,
or telnet emulators.
More information can be found in the “Console” Appendix.
Getting Help A
Several sources of information exist online help built into REBOL, the source
function, documents on the REBOL web site, the REBOL script library, the REBOL
mailing list, and sending feedback to REBOL.
Online Help 0
The online help function provides a quick way to obtain summary information
about REBOL words. There are several ways to use help.

Operation
Getting Help
Type help or ? at the console prompt to view a summary of help:
>> help
The help function provides a simple way to get information

about words and values. To use it
supply a word or value as its argument:
help insert
help find
To view all words that match a pattern:
help "path"
help to-
To view all words of a specified datatype:
help native!
help datatype!
There is also word completion from the command

line. Type a few chars and press TAB to complete
the word. If nothing happens, there is more than
one word that matches. Enough chars are needed
to uniquely identify the word.
Other useful functions:
about - for general info

usage - for the command line arguments
license - for the terms of user license
source func - print source for given function
upgrade - updates your copy of REBOL

Operation
Getting Help
If you provide a function word as an argument, help prints all of the information
that was provided about the function:
>> ? insert
USAGE:
INSERT series value /part range /only /dup count
DESCRIPTION:
Inserts a value into a series and returns the
series after the insert.
INSERT is an action value.
ARGUMENTS:
series -- Series at point to insert

(Type: series port bitset)
value -- The value to insert (Type: any-type)
REFINEMENTS:
/part -- Limits to a given length or position.

range -- (Type: number series port)
/only -- Inserts a series as a series.
/dup -- Duplicates the insert a specified
number of times.
count -- (Type: number)

Operation
Getting Help
The help function also finds words that contain a specified string. For instance, to
find all of the words that include the string path, type:
>> ? "path"
Found these words:

clean-path (function)
lit-path! (datatype)
lit-path? (action)
path! (datatype)
path? (action)
set-path! (datatype)
set-path? (action)
split-path (function)
to-lit-path (function)
to-path (function)
to-set-path (function)
You can also search for all globally defined words that are of a given data type. For
example, to list all words that are function! data types, type:
>> ? function!
Found these words:
? (function)
?? (function)
about (function)
append (function)
array (function)
ask (function)
build-tag (function)
change-dir (function)
charset (function)
choose (function)
...

Operation
Getting Help
To obtain a list of the REBOL data types, type:
>> ? datatype!
Found these words:
action! (datatype)
any-block! (datatype)
any-function! (datatype)
any-string! (datatype)
any-type! (datatype)
any-word! (datatype)
binary! (datatype)
bitset! (datatype)
block! (datatype)
char! (datatype)
datatype! (datatype)
date! (datatype)
...
The help function does not provide useful information about the objects of the
system.
Viewing Source Code 0
Advanced users can learn more about specific REBOL functions by examining the
source code. The source function displays the code for any mezzanine level or
user-defined function:
>> source join
join: func [
"Concatenates values."
value "Base value"
rest "Value or block of values"
][
value: either series? value [copy value] [form value]
repend value rest
]

Operation
Getting Help
Mezzanine functions are built-in functions implemented in REBOL. Native functions

are built-in functions implemented in machine code.
Download Documents 0
Check the REBOL Web site (http://www.REBOL.com) for a list of the current
documentation. In addition to this manual, there is a REBOL Dictionary.
The REBOL Dictionary includes all predefined words available in REBOL. If the
console help or this guide does not contain sufficient information about a REBOL
word, look in the Dictionary for a detailed description.
The Dictionary is updated with each release of REBOL and is available at

http://www.REBOL.com/dictionary.html.
Script Library 0
The REBOL Web site contains a library with numerous useful debugged scripts that
cover a variety of topics. The library is divded into categories to make it easy to
find a script specific to a given function. You can also search the library for scripts
that contain a specific word.
The script library can be found at

http://www.REBOL.com/library/library.html.
User Mailing List 0
You can also obtain help from the on-line REBOL community by joining the email
discussion list. To sign up, send an email to [email protected] with the subject line
containing the word "subscribe". For example:
send [email protected] "subscribe"
Be sure that your correct email address has been set up in advance with set-net.
Contacting Us 0
We want to know what you think; please contact us to:

Operation
Getting Help
■ Report crashes or problems

■ Tell us how you are using REBOL
■ Make suggestions
■ Request more information about our products.
You can contact the REBOL Technologies customer support group by sending an
email message to [email protected].
Another way to provide feedback is to run the feedback.r script that is part of
the distribution. Type:
do %feedback.r
This script presents a menu to help guide you though the feedback process.
FEEDBACK CATEGORY
--------------------
1 > Bug report
2 > General Question
3 > Enhancement idea
4 > Comment/Praise
5 > Documentation note
6 > Other
7 > Quit
Using the feedback script automatically includes the version number of REBOL
release you are using in the email sent to REBOL’s helpdesk. If you contact us
directly at feedback, please provide the version number of the product you are
using.

Operation
Errors
Errors A
Error Messages 0
There are several types of errors within REBOL. When an error occurs a message is
displayed that tells you what the error was and approximately where it occurred.
For instance if you type:
>> abc
** Script Error: abc has no value.
** Where: abc
The type of error is indicated by the first few words of the message. In the above
example, the error is a Script Error. Script errors are the most common and occur
when you use a function of the language in the wrong way or with improper
arguments. Other types of errors are described in Table 1-1.
Table 1-1. Error Types
Error Type Description
Syntax errors Occur when the script contains an invalid value or a missing
header, quote, bracket, or parenthesis.
Math errors Occur when dividing a number by zero or there was a math
overflow or underflow.
Access errors Occur when a file, directory, or network operation cannot be
accessed or access permissions are restricted.
Throw errors Occur when a break, exit, or throw is used in an improper
manner.
User errors Defined by the user’s script.
Internal errors Returned when a problem occurs within the REBOL system. If
you encounter one of these types of errors, please report it to
[email protected].
Most types of errors can be trapped and processed by your script. See “Trying
Blocks” on page 3-46 for a description of the try function.

Operation
Upgrading
The “Errors” Appendix also includes useful information about errors.
Redirecting Errors 0
When errors are encountered in non-interactive sessions, such as when running in

CGI mode (-c or --cgi) or in no Windows mode (-w or --nowindow), the
session is automatically terminated.
If a script terminates while running in non-interactive mode, you can use the shell
reduction operator (>>) to output the error to a file:
shell> REBOL -cs my_script.r >> my_script.log
The shell reduction operator appends the output to a file in most operating systems.
Upgrading A
On initialization, a banner is displayed that identifies the program version. Version

numbers have the format:
version.revision.update.platform.variation
For example, the version number:
2.3.0.3.1
indicates that you are running version 2, revision 3, update 0, for Windows 95/98/
NT (REBOL platform number 3.1).
You can obtain the version number from the REBOL prompt with:
print system/version
Only the latest release of REBOL is supported by REBOL Technologies. You can
verify that you have the latest version and automatically update it if out of date. To
do so, be sure that you are connected to the Internet, then from within REBOL type:
upgrade

Operation
Upgrading
REBOL returns one of the following messages about your version:
This copy of Windows 95/98/NT iX86 REBOL/core 2.3.0.3.1

is currently up to date.
or:
This copy of Windows 95/98/NT iX86 REBOL/core 2.1.2.3.1

is not up to date. Current version is: 2.3.0.3.1.
Download current version?
To upgrade to the latest version, type Y (yes). Otherwise, type N (no).

Operation
Upgrading

2
Quick Tour
This chapter describes how to format and execute scripts in REBOL/Core. It

■ “Overview” on page 2-2

■ “Values” on page 2-2
■ “Words” on page 2-6
■ “Blocks” on page 2-7

■ “Variables” on page 2-9
■ “Evaluation” on page 2-10
■ “Functions” on page 2-12

■ “Paths” on page 2-13
■ “Objects” on page 2-15
■ “Scripts” on page 2-16

■ “Files” on page 2-17
■ “Networking” on page 2-19
2- 1
Quick Tour
Overview
Overview B
This chapter provides a quick way to familiarize yourself with the REBOL language.
Using examples, this chapter presents the basic concepts and structure of the
language, illustrating everything from data values to performing network
operations.
Values B
A script is written with a sequence of values. A wide variety of values exist; you
are familiar with most of them from daily experience. This section lists all the valid
values and describes how they are expressed in REBOL.
Note that where possible, REBOL allows the use of international formats for values
such as decimal numbers, money, time, and date.
Numbers 0
Numbers are written as integers, decimals, or scientific notation. For example:
1234 -432 3.1415 1.23E12
0,01 –1,234.00 1,2E12 (non-British format)
Times 0
Time is written in hours, minutes, and seconds, each separated by colons. For
example:
12:34 20:05:32 0:25.345 0:25,345
Seconds can include a decimal sub-second.

Quick Tour
Values
Dates 0
Dates are written in either international format: day-month-year or year-month-day.

A date can also include a time and a time zone. The name or abbreviation of a
month can be used to make its format more identifiable in the United States. For
example:
20-Apr-1998 20/Apr/1998 (USA friendly)
20-4-1998 1998-4-20 (international)
1980-4-20/12:32 (date with time)
1998-3-20/8:32-8:00 (with time zone)
Money 0
Money is written as an international three-letter currency symbol followed by a

numeric amount. For example:
$12.34 USD$12.34 CAD$123.45 DEM$1234,56
Tuples 0
Tuples are used for version numbers, RGB color values, and network addresses
They are written as short numeric sequences separated by dots. For example:
2.3.0.3.1 255.255.0 199.4.80.7

Quick Tour
Values
Strings 0
Strings are written in a single-line format or a multiline format. Single-line-format

strings are enclosed in quotes. Multiline-format strings are enclosed in brackets.
Strings that include quotes, tabs, or line breaks must be enclosed in brackets using
the multiline format. For example:
"Here is a single-line string"
{Here is a multiline string that
contains a "quoted" string.}
Tags 0
Tags are useful for markup languages such as XML and HTML. Tags are enclosed in
angle brackets For example:
<title> </body>
<font size="2" color="blue">
Email Addresses 0
Email addresses are written directly in REBOL. They must include an at sign(@).
For example:
[email protected]
[email protected]

Quick Tour
Values
URLs 0
Most types of Internet URLs are accepted directly by REBOL. They begin with a
scheme name (e.g., http) followed by a path. For example:
http://www.rebol.com
ftp://ftp.rebol.com/sendmail.r
ftp://freda:[email protected]/dir/files/
mailto:[email protected]
Filenames 0
Filenames are preceded by a percent sign to distinguish them from other words. For
example:
%data.txt
%images/photo.jpg
%../scripts/*.r
Pairs 0
Pairs are used to indicate spatial coordinates, such as positions on a display. They
are used to indicate both positions and sizes. Coordinates are separated by an x.
For example:
100x50
1024x800
-50x200

Quick Tour
Words
Issues 0
Issues are identification numbers, such as telephone numbers, model numbers,

credit card numbers. For example:
#707-467-8000
#0000-1234-5678-9999
#MFG-932-741-A
Binary 0
Binary values are byte strings of any length. They can be encoded directly as
hexidecimal or base-64. For example:
#{42652061205245424F4C}
64#{UkVCT0wgUm9ja3Mh}
Words B
Words are the symbols used by REBOL. A word may or may not be a variable,
depending on how it is used. Words are also used directly as symbols.
show next image
Install all files here
Country State City Street Zipcode
on off true false one none
REBOL has no keywords; there are no restrictions on what words are used or how
they are used. For instance, you can define your own function called print and
use it instead of the predefined function for printing values.

Quick Tour
Blocks
Words are not case sensitive and can include hyphens and a few other special
characters such as +, -, ‘, *, !, ~, &, ., and ?. The following examples illustrate
valid words:
number? time? date!
image-files l’image
++ -- == +-
***** *new-line*
left&right left|right
The end of a word is indicated by a space, a line break, or one of the following
characters:
[ ] ( ) { } " : ; /
The following characters are not allowed in words:
@ # $ % ^ ,
Blocks B
Values and words are grouped in blocks. Blocks are used for code, lists, arrays,
tables, directories, associations, and other sequences. A block is a type of series,
which is a set of values organized in a specific order.

Quick Tour
Blocks
A block is enclosed in square brackets [ ]. Within a block, values and words can
be organized in any order and can span any number of lines. The following
examples illustrate the valid forms of blocks:
[white red green blue yellow orange black]
["Spielberg" "Back to the Future" 1:56:20 MCA]
[
Ted [email protected] #213-555-1010
Bill [email protected] #315-555-1234
Steve [email protected] #408-555-4321
]
[
"Elton John" 6894 0:55:68
"Celine Dion" 68861 0:61:35
"Pink Floyd" 46001 0:50:12
]
Blocks are used for code as well as for data, as shown in the following examples:
loop 10 [print "hello"]
if time > 10:30 [send jim news]
sites: [
http://www.rebol.com [save %reb.html data]
http://www.cnn.com [print data]
ftp://www.amiga.com [send [email protected] data]
]
foreach [site action ] [

data: read site
do action
]

Quick Tour
Variables
A script itself also is a block. Although it does not include the brackets, the block
is implied. The example script:
red
green
blue
yellow
is a block that contains red, green, blue, and yellow. It is equivalent to writing:
[red green blue yellow]
Variables B
Words can be used as variables that refer to values. To define a word as a variable,
follow the word with a colon (:), then the value to which the variable refers as
shown in the following examples:.
age: 22
snack-time: 12:32
birthday: 20-Mar-1997
friends: ["John" "Paula" "Georgia"]
A variable can refer to any type of value, including functions (see “Functions” on
page 2-12) and objects (see “Objects” on page 2-15).
A variable refers to a specific value only within a defined context, such as a block,
a function, or an entire program. Outside that context the variable can refer to some
other value or to no value at all. The context of a variable can span an entire
program or it can be restricted to a particular block, function, or object. In other
languages, the context of a variable is often referred to as the scope of a variable.

Quick Tour
Evaluation
Evaluation B
Blocks are evaluated to compute their results. When a block is evaluated the values
of its variables are obtained. The following examples evaluate the variables age,
snack-time, birthday, and friends that were defined in the previous section:
print age
22
if current-time > snack-time [print snack-time]
12:32
print third friends
Georgia
NOTE: Each of these code lines is a block, even though the brackets are not shown.
All scripts have an implied block around their entire text.
A block can be evaluated multiple times by using a loop, as shown in the following
examples:
loop 10 [prin "*"] ;(not a typo, see manual)
**********
loop 20 [
wait 8:00
send [email protected] read http://www.cnn.com
]
repeat count 3 [print ["count:" count]]
count: 1
count: 2
count: 3

Quick Tour
Evaluation
The evaluation of a block returns a result. In the following examples, 5 and PM are
the results of evaluating each block:
print do [2 + 3]
print either now/time < 12:00 ["AM"]["PM"]
PM
In REBOL, there are no special operator precedence rules for evaluating blocks. The
values and words of a block are always evaluated from first to last, as shown in the
following example:
print 2 + 3 * 10
50
Parentheses can be used to control the order of evaluation, as shown in the

following examples:
2 + (3 * 10)
32
(length? "boat") + 2
You can also evaluate a block and return each result that was computed within it.
This is the purpose of the reduce function:
reduce [1 + 2 3 + 4 5 + 6]
3 7 11

Quick Tour
Functions
Functions B
A function is a block with variables that are given new values each time the block
is evaluated. These variables are called the arguments of the function.
In the following example, the word sum is set to refer to a function that accepts two
arguments, a and b:
sum: func [a b] [a + b]
In the above example, func is used to define a new function. The first block in the
function describes the arguments of the function. The second block is the block of
code that gets evaluated when the function is used. In this example, the second
block adds two values and returns the result.
The next example illustrates one use of the function sum that was defined in the
previous example:
print sum 2 3
Some functions need variables as well as arguments. To define this type of function,
use function, instead of func, as shown in the following example:
average: function [series] [total] [

total: 0
foreach value series [total: total + value]
total / (length? series)
]
print average [37 1 42 108]
47
In the above example, the word series is an argument and the word total is a
local variable used by the function for calculation purposes.

Quick Tour
Paths
The function argument block can contain strings to describe the purpose of a
function and its argument, as shown in the following example:
average: function [
"Return the numerical average of numbers"
series "Numbers to average"
] [total] [
total: 0
foreach value series [total: total + value]
total / (length? series)
]
These descriptive strings are kept with the function and can be viewed by asking
for help about the function, as shown below:
help average
USAGE:
AVERAGE series
DESCRIPTION:
Return the numerical average of numbers
AVERAGE is a function value.
ARGUMENTS:
series -- Numbers to average (Type: any)
Paths B
If you are using files and URLs, then you are already familiar with the concept of
paths. A path provides a set of values that are used to navigate from one point to
another. In the case of a file, a path specifies the route through a set of directories
to the location of the file. In REBOL, the values in a path are called refinements.

Quick Tour
Paths
A slash (/) is used to separate words and values in a path, as shown in the following
examples of a file path and a URL path:
%source/images/globe.jpg
http://www.rebol.com/examples/simple.r
Paths can also be used to select values from blocks, pick characters from strings,
access variables in objects, and refine the operation of a function, as shown in the
following examples:
USA/CA/Ukiah/size (block selection)
names/12 (string position)
account/balance (object function)
match/any (function option)
The print function in next example shows the simplicity of using a path to access
a mini-database created from a few blocks:
towns: [
Hopland [
phone #555-1234
web http://www.hopland.ca.gov
]
Ukiah [
phone #555-4321
web http://www.ukiah.com
email [email protected]
]
]
print towns/ukiah/web
http://www.ukiah.com

Quick Tour
Objects
Objects B
An object is a block of variables that have values in a specific context. Objects are
used for managing data structures that have more complex behavior. The following
example shows how a bank account can benefit from using an object to specify its
attributes and functions:
account: make object! [

name: "James"
balance: $100
ss-number: #1234-XX-4321
deposit: func [amount] [balance: balance + amount]
withdraw: func [amount] [balance: balance - amount]
In the above example, the words name, balance, ss-number, deposit, and
withdraw are local variables of the account object. The deposit and
withdraw variables are functions that are defined within the object. The variables
of the account can be accessed with a path, as shown in the next example:
print account/balance
$100.00
account/deposit $300
print ["Balance for" account/name "is" account/balance]
Balance for James is $400.00
The next example shows how to make another account with a new balance but with
all the other values remaining the same
checking-account: make account [

balance: $2000
]

Quick Tour
Scripts
You can also create an account that extends the account object by adding the bank
name and last activity date, as shown in the following example:
checking-account: make account [

bank: "Savings Bank"
last-active: 20-Jun-2000
]
print checking-account/balance
$2000.00
print checking-account/bank
Savings Bank
print checking-account/last-active
20-Jun-2000
Scripts B
A script is a file that holds a block that can be loaded and evaluated. The block can
contain code or data, and typically contains a number of sub-blocks.

Quick Tour
Files
Scripts require a header to identify the presence of code. The header can include
the script title, date, and other information. In the following example of a script, the
first block contains the header information:
REBOL [
Title: "Web Page Change Detector"
File: %webcheck.r
Author: "Reburu"
Date: 20-May-1999
Purpose: {
Determine if a web page has changed since it was
last checked, and if it has, send the new page
via email.
}
Category: [web email file net 2]
]
page: read http://www.rebol.com
page-sum: checksum page
if any [
not exists? %page-sum.r
page-sum <> (load %page-sum.r)
][
print ["Page Changed" now]
save %page-sum.r page-sum
send [email protected] page
]
Files B
In REBOL, files are easily accessed. The following table describes some of the ways
to access files.
You can read a text file with:
data: read %plan.txt

Quick Tour
Files
You can display a text file with:
print read %plan.txt
To write a text file:
write %plan.txt data
For instance, you could write out the current time with:
write %plan.txt now
You can also easily append to the end of a file:
write/append %plan data
Binary files can be read and written with:
data: read/binary %image.jpg
write/binary %new.jpg data
To load a file as a REBOL block or value:
data: load %data.r
Saving a block or a value to a file is just as easy:
save %data.r data
To evaluate a file as a script (It needs a header to do this.):
do %script.r
You can read a file directory with:
dir: read %images/
and, you can then display the file names with:
foreach file dir [print file]

Quick Tour
Networking
To make a new directory:
Make-dir %newdir/
To find out the current directory path:
print what-dir
If you need to delete a file:
delete %oldfile.txt
You can also rename a file with:
rename %old.txt %new.txt
To get information about a file:
print size? %file.txt
print modified? %file.txt
print dir? %image
Networking B
There are a number of Internet protocols built into REBOL. These protocols are easy
to use and require very little knowledge of networking.
HTTP 0
The following example shows how to use the HTTP protocol to read a web page:

Quick Tour
Networking
The next example fetches an image from a web page and writes it to a local file:
image: read/binary http://www.page.dom/image.jpg
write/binary %image.jpg image
FTP 0
The following reads and writes files to a server using the file transfer protocol (FTP):
file: read ftp://ftp.rebol.com/test.txt
write ftp://user:[email protected]/test.txt file
The next example gets a directory listing from FTP:
print read ftp://ftp.rebol.com/pub
SMTP 0
The following example sends email with the simple mail transfer protocol (SMTP):
send [email protected] "Use the force."
The next example sends the text of a file as an email:
send [email protected] read %plan.txt
POP 0
The following example fetches email with the post office protocol (POP) and prints
all of the current messages but leaves them on the server:
foreach message read pop://user:[email protected] [

print message
]

Quick Tour
Networking
NNTP 0
The following example fetches news with the network news transfer protocol
(NNTP), reading all of the news in a particular news group:
messages: read nntp://news.server.dom/comp.lang.rebol
The next example reads a list of all news group and prints them:
news-groups: read nntp://news.some-isp.net
foreach group news-groups [print group]
Daytime 0
The following example gets the current time from a server:
print read daytime://everest.cclabs.missouri.edu
Whois 0
The following example finds out who is in charge of a domain using the whois
protocol:
print read whois://[email protected]
Finger 0
The following example gets user information with the finger protocol:
print read finger://[email protected]

Quick Tour
Networking
DNS 0
The following example determines an Internet address from a domain name and a
domain name from an address:
print read dns://www.rebol.com
print read dns://207.69.132.8
TCP 0
Direct connections with TCP/IP are also possible in REBOL. The following example
is a simple, but useful, server that waits for connections on a port:
server-port: open/lines tcp://:9999
forever [
connection-port: first server-port
until [
wait connection-port
error? try [do first connection-port]
]
close connection-port
]

3
Expressions
This chapter explains the use of blocks, values and words, as well as the functions
necessary to evaluate expressions in REBOL. It includes the following information:

■ “Blocks” on page 3-4
■ “Values” on page 3-5
■ “Evaluating Expressions” on page 3-6

■ “Words” on page 3-13
■ “Conditional Evaluation” on page 3-23
■ “Repeated Evaluation” on page 3-31

■ “Selective Evaluation” on page 3-40
■ “Stopping Evaluation” on page 3-45
■ “Trying Blocks” on page 3-46
3- 1
Expressions
Overview
Overview C
The foremost goal of REBOL is to establish a standard method of communication

that spans all computer systems. REBOL provides a simple, direct means of
expressing any kind of information with optimal flexibility in structure and minimal
syntax. For example, read the following line:
Sell 100 shares of "Microsoft" at $47.97 per share
The expression shown in the above example looks a lot like English, making it easy
to compose if you are sending it and easy to understand if you are receiving it.
However, this line is actually a valid expression in REBOL, so your computer could
also understand and act on it. REBOL provides a common language between you
and your computer. In addition, if your computer sends this expression to your
stock broker’s computer, which is also running REBOL, your stock broker’s
computer can understand the expression and act on it. REBOL provides a common
language between computers. The line could be sent to millions of other computer
systems that could also act on it.
The following line is another example of a REBOL expression:
Reschedule exam for 2-January-1999 at 10:30
The expression shown in the above example may have come from your doctor
typing it, or perhaps it originated from an application that was run by your doctor.
It does not matter. What is important is that the expression can be acted upon
regardless of the type of computer, hand-held device, kiosk, or television console
you are using.
The data values (numbers, strings, prices, dates, and times) in all of the expressions
shown in the previous examples are standardized valid REBOL formats. The
words, however, depend on a specific context of interpretation to convey their
meaning. Words such as sell, at, and read have different meanings in different
contexts. The words are relative expressions—their meaning is context dependent.

Expressions
Overview
Expressions can be processed in one of two ways: directly by the REBOL interpreter,
or indirectly by a REBOL script. A script processed indirectly is called a dialect. The
previous examples are dialects and, therefore, are processed by a script. The
following example is not a dialect and is processed directly by the REBOL
interpreter:
send [email protected] read http://www.rebol.com
In this example, the words send and read are functions that are processed by the
REBOL interpreter.
The distinction REBOL makes is that information is either directly or indirectly

interpreted. The distinction is not whether information is code or data, but how it
is processed. In REBOL, code is often handled as data and data is frequently
processed as code, so the traditional division between code and data blurs. How
information is processed determines whether it is code or data.

Expressions
Blocks
Blocks C
Expressions are based on one concept: you combine values and words into blocks.
In scripts, a block is normally enclosed with square brackets [ ]. Everything within

the square brackets is part of the block. The block contents can span any number
of lines, and its format is completely freeform. The following examples show
various ways of formatting block content:
[white red green blue yellow orange black]
["Spielberg" "Back to the Future" 1:56:20 MCA]
[
"Bill" [email protected] #315-555-1234
"Steve" [email protected] #408-555-4321
"Ted" [email protected] #213-555-1010
]
sites: [
http://www.rebol.com [save %reb.html data]
http://www.cnn.com [print data]
ftp://www.amiga.com [send [email protected] data]
]
Some blocks do not require square brackets, because they are implied. For example,
in a REBOL script, there are no brackets around the entire script, however, the script
content is a block. The square brackets of an outer-block of the script are implied.
The same is true for expressions typed at the command prompt or for REBOL
messages sent between computers—each is an implied block.
Another important aspect of blocks is that they imply additional information.

Blocks group a set of values in a particular order. That is, a block can be used as a
data set as well as a sequence. This will be described in more detail in the “Series”
Chapter.

Expressions
Values
Values C
REBOL provides a built-in set of values that can be expressed and exchanged
between all systems. Values are the primary elements for composing all REBOL
expressions.
Values can be directly or indirectly expressed.
A directly expressed value is known as it is lexically, or literally, written. For

instance, the number 10 or the time 10:30 are directly expressed values.
An indirectly expressed value is unknown until it is evaluated. The values none,

true, and false all require words to represent them. These values are indirectly
expressed because they must be evaluated for their values to be known. This is also
true of other values, such as lists, hashes, functions, objects.
Every REBOL value is of a particular data type. A data type is a definition of a set
of data that specifies the possible range of values of the set, the operations that can
be performed on the values, and the way in which the values are stored in memory.
By convention, REBOL data type words are followed by an exclamation point (!),
as shown in the following examples:
integer! char! word!
See the “Values” Appendix for a description of all the REBOL data types.

Expressions
Evaluating Expressions
Evaluating Expressions C
To evaluate an expression is to compute its value. REBOL operates by evaluating

the series of expressions constituting a script and then returning the result.
Evaluating is also called running, processing, or executing a script.
Evaluation is performed on blocks. Blocks can be typed at the console or loaded

from a script file. Either way, the process of evaluation is the same.
Evaluating Console Input 0
Any expression that can be evaluated in a script, can also be evaluated from the
REBOL prompt, providing a simple means of testing individual expressions in a
script.
For example, if you type the following expression at the console prompt:
>> 1 + 2
the expression is evaluated and the following result is returned:
== 3
NOTE: In the example above, the console prompt (>>) and result indicator
(==)are shown to give you an idea of how they appear in the console. For the
examples that follow, the prompt and result strings are not shown. However, you
can assume that these examples can be typed into the console to verify their results.
Evaluating Directly Expressed Values 0
Since the value of directly expressed values is known, when they are evaluated the
known value is returned. For example, if you type the following line:
10:30

Expressions
the value 10:30 is returned. This is the behavior of all directly expressed values,
including:
integer 1234
decimal 12.34
string "REBOL world!"
time 13:47:02
date 30-June-1957
tuple 199.4.80.1
money $12.49
pair 100x200
char #"A"
binary #{ab82408b}
issue #707-467-8000
tag <IMG SRC="xray.jpg">
file %xray.jpg
url http://www.rebol.com/
block [milk bread butter]
Evaluating Blocks 0
Normally, blocks are not evaluated. For example, typing the following block:
[1 + 2]
returns the same block:
[1 + 2]
The block is not evaluated; it is simply treated as data.
To evaluate a block, use the do function, as shown in the following example:
do [1 + 2]

Expressions
The do function returns the result of the evaluation. In the previous example, the
number 3 is returned.
If a block contains multiple expressions, only the result of the last expression is
returned:
do [
1 + 2
3 + 4
]
In this example, both expressions are evaluated, but only the result of the
expression 3 + 4 is returned.
There are a number of functions such as if, loop, while, and foreach that evaluate
a block as part of their function. These functions are discussed in detail later in this
chapter, but here are a few examples:
if time > 12:30 [print "past noon"]
past noon
loop 4 [print "looping"]
looping
looping
looping
looping
This is important to remember: blocks are treated as data until they are explicitly
evaluated by a function. Only a function can cause them to be evaluated.

Expressions
Reducing Blocks 0
When you evaluate a block with do, only the value of its last expression is returned
as a result. However, there are times when you want the values of all the
expressions in a block to be returned. To return the results of all of the expressions
in a block, use the reduce function. In the following example, reduce is used to
return the results of both expressions in the block:
reduce [
1 + 2
3 + 4
]
[3 7]
In the above example, the block was reduced to its evaluation results. The reduce
function returns results in a block.
The reduce function is important because it enables you to create blocks of

expressions that are evaluated and passed to other functions. Reduce evaluates
each expression in a block and puts the result of that expression into a new block.
That new block is returned as the result of reduce.
Some functions, like print, use reduce as part of their operation, as shown in the
following example:
print [1 + 2 3 + 4]
3 7

Expressions
The rejoin, reform, and remold functions also use reduce as part of their
operation, as shown in the following examples:
print rejoin [1 + 2 3 + 4]
37
print reform [1 + 2 3 + 4]
3 7
print remold [1 + 2 3 + 4]
[3 7]
The rejoin, reform, and remold functions are based on the join, form, and mold
functions, but reduce their blocks first.
Evaluating Scripts 0
The do function can be used to evaluate entire scripts. Normally, do evaluates a

block, as shown in the following example:
do [print "Hello!"]
Hello!
But, when do evaluates a file name instead of a block, the file will be loaded into
the interpreter as a block, then evaluated as shown in the following example:
do %script.r
NOTE: Note that for a script file to be evaluated, it must include a valid REBOL
header, which is described in the “Scripts” Chapter. The header identifies that the
file contains a script and not just random text.

Expressions
Evaluating Strings 0
The do function can be used to evaluate expressions that are found within text
strings. For example, the following expression:
do "1 + 2"
returns the result 3. First the string is converted to a block, then the block is
evaluated.
Evaluating strings can be handy at times, but it should be done only when
necessary. For example, to create a REBOL console line processor, type the
following expression:
forever [probe do ask "=> "]
The above expression would prompt you with => and wait for you to type a line of
text. The text would then be evaluated, and its result would be printed. (Of course,
it’s not really quite this simple, because the script could have produced an error.)
Unless it is necessary, evaluating strings is not generally a good practice. Evaluating

strings is less efficient than evaluating blocks, and the context of words in a string
is not known. For example, the following expression:
do form ["1" "+" "2"]
is much less efficient than typing:
do [1 + 2]
REBOL blocks can be constructed just as easily as strings, and blocks are better for
expressions that need to be evaluated.

Expressions
Evaluation Errors 0
Errors may occur for many different reasons during evaluation. For example, if you
divide a number by zero, evaluation is stopped and an error is displayed
100 / 0
** Math Error: Attempt to divide by zero.
** Where: 100 / 0
A common error is using a word before it has been defined:
size + 10
** Script Error: size has no value.
** Where: size + 10
Another common error is not providing the proper values to a function in an

expression:
10 + [size]
** Script Error: Cannot use add on block! value.
** Where: 10 + [size]
Sometimes errors are not so obvious, and you will need to experiment to determine
what is causing the error.

Expressions
Words
Words C
Expressions are built from values and words. Words are used to represent meaning.
A word can represent an idea or it can represent a specific value.
In the previous examples in this chapter, a number of words were used within
expressions without explanation. For instance, the do, reduce, and try words are
used, but not explained.
Words are evaluated somewhat differently than directly expressed values. When a
word is evaluated, its value is looked up, evaluated, and returned as a result. For
example, if you type the following word:
zero
==0
the value 0 is returned. The word zero is predefined to be the number zero. When
the word is looked up, a zero is found and is returned.
When words like do and print are looked up, their values are found to be functions,
rather than a simple value. In such cases, the function is evaluated, and the result
of the function is returned.
Word Names 0
Words are composed of alphabetic characters, numbers, and any of the following
characters:
? ! . ’ + - * & | = _ ~
A word cannot begin with a number, and there are also some restrictions on words
that could be interpreted as numbers. For example, -1 and +1 are numbers, not
words.
The end of a word is marked by a space, a new line, or one of the following
characters:
[ ] ( ) { } " : ; /

Expressions
Words
Thus, the brackets of a block are not part of a word. For example, the following
block contains the word test:
[test]
The following characters are not allowed in words as they cause words to be
misinterpreted or to generate an error:
@ # $ % ^ ,
Words can be of any length, but cannot extend past the end of a line:
this-is-a-very-long-word-used-as-an-example
The following examples demonstrate valid words:
Copy print test
number? time? date!
++ -- == +-
***** *new-line*
REBOL is not case sensitive. The following words all refer to the same word:
blue
Blue
BLUE
The case of a word is preserved when it is printed.

Expressions
Words
Words can be reused. The meaning of a word is dependent on its context, so words
can be reused in different contexts. There are no keywords in REBOL. You can
reuse any word, even those that are predefined in REBOL. For instance, you can
use the word if in your code differently than the REBOL interpreter uses this word.
NOTE: Pick the words you use carefully. Words are used to associate meaning. If
you pick your words well, it will be easier for you and others to understand your
scripts.
Word Usage 0
Words are used in two ways: as symbols or as variables. In the following block,
words are used as symbols for colors.
[red green blue]
In the following line:
print second [red green blue]
green
the words have no meaning other than their use as names for colors. All words used
within blocks serve as symbols until they are evaluated.
When a word is evaluated, it is used as a variable. In the previous example, the

words print and second are variables that hold native functions which perform the
required processing.

Expressions
Words
A word can be written in four ways to indicate how it is to be treated, as shown in

Table 3-1.
Table 3-1. Word Formats
Word Format REBOL’s Treatment
word Evaluates the word. This is the most natural and common way to
write words. If the word holds a function, it will be evaluated.
Otherwise, the value of the word will be returned.
word: Defines or sets the value of a word. It is given a new value. The
value can be anything, including a function. See “Setting Words”
below.
:word Gets the word’s value, but doesn’t evaluate it. This is useful for
referring to functions and other data without evaluating them.
See “Getting Words” below.
’word Treats the word as a symbol, but does not evaluate it. The word
itself is the value.
Setting Words 0
A word followed by a colon (:) is used to define or set its value:
age: 42
lunch-time: 12:32
birthday: 20-March-1990
town: "Dodge City"
test: %stuff.r
NOTE: The reason words are set using a colon is to make their expression atomic.
You can write code that finds set-word operations. They also distinguish the set
operation from equality(=).

Expressions
Words
You can set a word to be any type of value. In the previous examples, words are
defined to be integer, time, date, string, and file values. You can also set words to
be more complex types of values. For example, the following words are set to block
and function values:
towns: ["Ukiah" "Willits" "Mendocino"]

code: [if age > 32 [print town]]
say: func [item] [print item]
Multiple words can be set at one time by cascading the word definitions. For
example, each of the following words are set to 42:
age: number: size: 42
Words can also be set with the set function:
set ’time 10:30
In this example, the line sets the word time to 10:30. The word time is written
as a literal (using a single quote) so that it will not be evaluated.
The set function can also set multiple words:
set [number num ten] 10
print [number num ten]
10 10 10

Expressions
Words
In the above example, notice that the words do not need to be quoted because they
are within a block, which is not evaluated. The print function shows that each
word is set to the integer 10.
If set is provided a block of values, each of the individual values are set to the
words. In this example, one, two, and three are set to 1, 2, and 3:
set [one two three] [1 2 3]
print three
print [one two three]
1 2 3
See the “Words” Section in the “Values” Appendix for more about setting words.
Getting Words 0
To get the value of a word that was previously defined, place a colon (:) at the front
of the word. A word prefixed with a colon obtains the value of the word, but does
not evaluate it further if it is a function. For example, the following line:
drucken: :print
defines a new word, drucken (which is German for print), to refer to the same
function print does. This is possible because :print returns the function for print,
but does not evaluate it.
Now, drucken performs the same function as print:
drucken "test"
test

Expressions
Words
Both print and drucken are set to the same value, which is the function that does
printing.
This can also be accomplished with the get function. When given a literal word, get
returns its value, but does not evaluate it:
stampa: get ’print
stampa "test"
test
The ability to get the value of a word is also important if you want to determine
what the value is without evaluating it. For example, you can determine if a word
is a native function using the following line:
print native? :if
true
Here the get returns the function for if. The if function is not evaluated, but rather
it is passed to the native? function which checks if it is a native data type. Without
the colon, the if function would be evaluated, and, because it has no arguments, an
error would occur.
Literal Words 0
The ability to deal with a word as a literal is useful. Both set and get, as well as
other functions like value?, unset, protect, and unprotect, expect a literal value.
Literal words can be written in one of two ways: by prefixing the word with a single
quotation mark, also known as a tick, (‘) or by placing the word in a block.
You can use a tick in front of a word that is evaluated:
word: ’this

Expressions
Words
In the above example, the word variable is set to the literal word this, not to the
value of this. The word variable just uses the name symbolically. The example
below shows that if you print the value of the word, you will see the this word:
print word
this
You can also obtain literal words from an unevaluated block. In the following
example, the first function fetches the first word from the block. This word is then
set to the word variable.
word: first [this and that]
Any word can be used as a literal. It may or may not refer to a value. For example,
in the example below the word here has no value. The word print does have a
value, but it can still be used as a literal because literal words are not evaluated.
word: ’here
print word
here
word: ’print
print word
print
The next example illustrates the importance of literal values:
video: [
title "Independence Day"
length 2:25:24
date 4/july/1996
]
print select video ’title
Independence Day

Expressions
Words
In this example, the word title is searched for in a block. If the tick was missing
from title, then its natural value would be used. If title has no natural value,
an error is displayed.
See the “Words” Section in the “Values” Appendix for more information about word
literals.
Unset Words 0
A word that has no value is unset. If an unset word is evaluated, an error will occur:
>> outlook
** Script Error: outlook has no value.
** Where: outlook
The error message in the previous example indicates that the word has not been set
to a value. The word is unset. Do not confuse this with a word that has been set to
none, which is a valid value.
A previously defined word can be unset at any time using unset:
unset ’word
When a word is unset, its value is lost.
To determine if a word has been set, use the value? function, which takes a literal
word as its argument:
if not value? ’word [print "word is not set"]
word is not set
Determining whether a word is set can be useful in scripts that call other scripts.
For instance, a script may set a default parameter that was not previously set:
if not value? ’test-mode [test-mode: on]

Expressions
Words
Protecting Words 0
You can prevent a word from being set with the protect function:
protect ’word
An attempt to redefine a protected word causes an error:
word: "here"
** Script Error: Word word is protected, cannot modify.
** Where: word: "here"
A word can be unprotected as well using unprotect:
unprotect ’word
word: "here"
The protect and unprotect functions also accept a block of words:
protect [this that other]

Expressions
Conditional Evaluation
Important function and system words can be protected using the protect-system
function. Protecting function and system words is especially useful for beginners
who might accidentally set important words. If protect-system is placed in your
user.r file, then all predefined words are protected.
Conditional Evaluation C
As previously mentioned, blocks are not normally evaluated. A do function is

required to force a block to be evaluated. There are times when you may need to
conditionally evaluate a block. The following section describes several ways to do
this.
Conditional Blocks 0
The if function takes two arguments. The first argument is a condition and the
second argument is a block. If the condition is true, the block is evaluated,
otherwise it is not evaluated.
if now/time > 12:00 [print "past noon"]
past noon
The condition is normally an expression that evaluates to true or false; however,

other values can also be supplied. Only a false or a none value prevents the block
from being evaluated. All other values (including zero) are treated as true, and
cause the block to be evaluated. This can be useful for checking the results of find,
select, next, and other functions that return none:
string: "let’s talk about REBOL"

if find string "talk" [print "found"]
found

Expressions
The either function extends if to include a third argument, which is the block to
evaluate if the condition is false:
either now/time > 12:00 [

print "after lunch"
][
print "before lunch"
]
after lunch
The either function also interprets a none value as false.
Both the if and either functions return the result of evaluating their blocks. In the
case of an if, the block value is only returned if the block is evaluated; otherwise, a
none is returned. The if function is useful for conditional initialization of variables:
flag: if time > 13:00 ["lunch eaten"]
print flag
lunch eaten
Making use of the result of the either function, the previous example could be
rewritten as follows:
print either now/time > 12:00 [

"after lunch"
][
"before lunch"
]
after lunch

Expressions
Since both if and either are functions, their block arguments can be any expression
that results in a block when evaluated. In the following examples, words are used
to represent the block argument for if and either.
notice: [print "Wake up!"]

if now/time > 7:00 notice
Wake up!
notices: [
[print "It’s past sunrise!"]
[print "It’s past noon!"]
[print "It’s past sunset!"]
]
if now/time > 12:00 second notices
It’s past noon!
sleep: [print "Keep sleeping"]

either now/time > 7:00 notice sleep
Wake up!
The conditional expressions used for the first argument of both if and either can be
composed from a wide variety of comparison and logic functions. Refer to the
“Math” Chapter for more information.
NOTE: The most commonly made mistake in REBOL is to forget the second block on
either or add a second block to if. These types of errors may be difficult to detect,
so keep this in mind if the function does not seem to be doing what you expect.

Expressions
Any and All 0
The any and all functions offer a shortcut to evaluating some types of conditional
expressions. These functions can be used in a number of ways:either in conjunction
with if, either, and other conditional functions, or separately.
Both any and all accept a block of expressions, which is evaluated one expression
at a time. The any function returns on the first true expression, and the all function
returns on the first false expression. Keep in mind that a false expression can also
be none, and that a true expression is any value other than false or none.
The any function returns the first value that is not false, otherwise it returns
none. The all function returns the last value if all the expressions are not false,
otherwise it returns none.
Both the any and all functions only evaluate as much as they need. For example,
once any has found a true expression, none of the remaining expressions are
evaluated. Here is an example of using any:
size: 50
if any [size < 10 size > 90] [
print "Size is out of range."
]
The behavior of any is also useful for setting default values. For example, the
following lines set a number to 100, but only when its value is none:
number: none
print number: any [number 100]
100
Similarly, if you have various potential values, you can use the first one that actually
has a value (is not none):
num1: num2: none

num3: 80
print number: any [num1 num2 num3]
80

Expressions
You can use any with functions like find to always return a valid result:
data: [123 456 789]

print any [find data 432 999]
999
Similarly, all can be used for conditions that require all expressions to be true:
if all [size > 10 size < 90] [print "Size is in range"]
Size is in range
You can verify that values have been set up before evaluating a function:
a: "REBOL/"
b: none
probe all [string? a string? b append a b]
none
b: "Core"
probe all [string? a string? b append a b]
REBOL/Core

Expressions
Conditional Loops 0
The until and while functions repeat the evaluation of a block until a condition is
met.
The until function repeats a block until the evaluation of the block returns true
(that is, not false or none). The evaluation block is always evaluated at least
once. The until function returns the value of its block.
The example below will print each word in the color block. The block begins by
printing the first word of the block. It then moves to the next color for each color
in the block. The tail? function checks for the end of the block, and will return
true, which will cause the until function to exit.
color: [red green blue]

until [
print first color
tail? color: next color
]
red
green
blue
The break function can be used to escape from the until loop at any time.
The while function repeats the evaluation of its two block arguments while the first
block returns true. The first block is the condition block, the second block is the
evaluation block. When the condition block returns false or none, the expression
block will no longer be evaluated and the loop terminates.

Expressions
Here is a similar example to that show above. The while loop will continue to print
a color while there are still colors to print.

while [not tail? color] [
print first color
color: next color
]
red
green
blue
The condition block can contain any number of expressions, so long as the last
expression returns the condition. To illustrate this, the next example adds a print to
the condition block. This will print the index value of the color. It will then check
for the tail of the color block, which is the condition used for the loop.

while [
print index? color
not tail? color
][
print first color
color: next color
]
1
red
2
green
3
blue
4

Expressions
The last value of the block is returned from the while function.
A break can be used to escape from the loop at any time.
Common Mistakes 0
Conditional expressions are only false when they return false or none, and they
are true when they return any other value. All of the conditional expressions in
the following examples return true, even the zero and empty block values:
if true [print "yep"]
yep
if 1 [print "yep"]
yep
if 0 [print "yep"]
yep
if [] [print "yep"]
yep
The following conditional expressions return false:
if false [print "yep"]
if none [print "yep"]
Do not enclose conditional expressions in a block. Conditional expressions enclosed

in blocks, always return a true result:
if [false] [print "yep"]
yep

Expressions
Repeated Evaluation
Do not confuse either with if. For example, if you intended to write:
either some-condition [a: 1] [b: 2]
but instead wrote:
if some-condition [a: 1] [b: 2]
the if function would ignore the second block. This would not cause an error, but
the second block would never get evaluated.
The opposite is also true. If you write the following line, omitting a second block:
either some-condition [a: 1]
the either function will not evaluate the correct code and may produce an
erroneous result.
Repeated Evaluation C
The while and until functions above where used to loop until a condition was met.
There are also several functions that let you loop for a specified a number of times.
Loop 0
The loop function evaluates a block a specified number of times. The following
example prints a line of 40 dashes:
loop 40 [prin "-"]
----------------------------------------
Note that the prin function is similar to the print function, but prints its argument
without a line termination.

Expressions
Repeated Evaluation
The loop function returns the value of the final evaluation of the block:
i: 0
print loop 40 [i: i + 10]
400
Repeat 0
The repeat function extends loop by allowing you to monitor the loop counter. The
repeat function’s first argument is a word that will be used to hold the count value:
repeat count 3 [print ["count:" count]]
count: 1
count: 2
count: 3
The final block value is also returned:
i: 0
print repeat count 10 [i: i + count]
55
In the previous examples, the count word only has its value within the repeat
block. In other words, the value of count is local to the block. After repeat
finishes, count returns to any previous set value.

Expressions
Repeated Evaluation
For 0
The for function extends repeat by allowing the starting value, the ending value,
and the increment to the value to be specified. Any of the values can be positive or
negative.
The example below begins at zero and counts to 50 by incrementing 10 each time
through the loop.
for count 0 50 10 [print count]
0
10
20
30
40
50
The for function cycles through the loop up to and including the ending value.
However, if the count exceeds the ending value, the loop is still terminated. The
example below specifies an ending value of 55. That value will never be hit because
the loop increments by 10 each time. The loop stops at 50.
for count 0 55 10 [prin [count " "]]
0 10 20 30 40 50
The next example shows how to count down. It begins at four and counts down to
zero one at a time.
for count 4 0 -1 [print count]
4
3
2
1
0

Expressions
Repeated Evaluation
The for function also works for decimal numbers, money, times, dates, series, and
characters. Be sure that both the starting and ending values are of the same data
type. Here are several examples of using the for loop with other data types.
for count 10.5 0.0 -1 [prin [count " "]]
10.5 9.5 8.5 7.5 6.5 5.5 4.5 3.5 2.5 1.5 0.5
for money $0.00 $1.00 $0.25 [prin [money " "]]
$0.00 $0.25 $0.50 $0.75 $1.00
for time 10:00 12:00 0:20 [prin [time " "]]
10:00 10:20 10:40 11:00 11:20 11:40 12:00
for date 1-jan-2000 4-jan-2000 1 [prin [date " "]]
1-Jan-2000 2-Jan-2000 3-Jan-2000 4-Jan-2000
for char #"a" #"z" 1 [prin char]
abcdefghijklmnopqrstuvwxyz
The for function also works on series. The following example uses for on a string
value. The word end is defined as the string with its current index at the d
character. The for function moves through the string series one character at a time
and stops when it reaches the character position defined to end:
str: "abcdef"
end: find str "d"
for s str end 1 [print s]
abcdef
bcdef
cdef
def

Expressions
Repeated Evaluation
Foreach 0
The foreach function provides a convenient way to repeat the evaluation of a block
for each element of a series. It works for all types of block and string series.
In the example below, each word in the block will be printed:
colors: [red green blue]

foreach color colors [print color]
red
green
blue
In the next example, each character in a string will be printed:
string: "REBOL"
foreach char string [print char]
R
E
B
O
L
In the example below, each filename in a directory block will be printed:
files: read %.
foreach file files [
if find file ".t" [print file]
]
file.txt
file2.txt
fox.txt
newfile.txt
output.txt
somefile.txt
test.txt

Expressions
Repeated Evaluation
When a block contains groups of values that are related, the foreach function can
fetch all the values of the group at the same time. For example, here is a block that
contains a time, string, and price. By providing the foreach function with a block
of words for the group, each of their values can be fetched and printed.
movies: [
8:30 "Contact" $4.95
10:15 "Ghostbusters" $3.25
12:45 "Matrix" $4.25
]
foreach [time title price] movies [

print ["See" title "at" time "for" price]
]
See Contact at 8:30 for $4.95

See Ghostbusters at 10:15 for $3.25
See Matrix at 12:45 for $4.25
In the above example, the foreach value block, [time title price], specifies
that three values are to be fetched from movies for each evaluation of the block.
The variables used to hold the foreach values are local to the block. Their value
are only set within the block that is being repeated. Once the loop has exited, the
variables return to their previously set values.
Forall and Forskip 0
Similar to foreach, the forall function evaluates a block for every value in a series.
However, there are some important differences. The forall function is handed the
series that is set to the beginning of the loop. As it proceeds through the loop, forall
modifies the position within the series.

forall colors [print first colors]
red
green
blue

Expressions
Repeated Evaluation
In the above example, after each evaluation of the block, the series is advanced to
its next position. When forall returns, the color index is at the tail of the series.
To continue to use the series you will need to return it to its head position with the
following line:
colors: head colors
The forskip function evaluates a block for groups of values in a series. The second
argument to forskip is the count of how many elements to move forward after each
cycle of the loop.
Like forall, forskip is handed the series with the series index set to where it is to
begin. Then, forskip modifies the index position as it continues the loop. After each
evaluation of the body block, the series index is advanced by the skip amount to its
next index position. The following example demonstrates forskip:
movies: [
8:30 "Contact" $4.95
10:15 "Ghostbusters" $3.25
12:45 "Matrix" $4.25
]
forskip movies 3 [print second movies]
Contact
Ghostbusters
Matrix
In the above example, forskip returns with the movies series at its tail position.
You will need to use the head function to return the series back to its head position.

Expressions
Repeated Evaluation
Forever 0
The forever function evaluates a block endlessly or until a it encounters the break
function.
The following example uses forever to check for the existence of a file every ten
minutes:
forever [
if exists? %datafile [break]
wait 0:10
]
Break 0
You can stop the repeated evaluation of a block with the break function. The break
function is useful when a special condition is encountered and the loop must be
stopped. The break function works with all types of loops.
In the following example, the loop will break if a number is greater than 5.
repeat count 10 [
if (random count) > 5 [break]
print "testing"
]
testing
testing
testing
testing
testing
testing
testing

Expressions
Repeated Evaluation
The break function does not return a value from the loop unless a /return
refinement is used:
print repeat count 10 [

if (random count) > 5 [break/return "stop here"]
print "testing"
"normal exit"
]
testing
testing
testing
testing
stop here
In the above example, if the repeat terminates without the condition occurring, the
block returns the string normal exit. Otherwise, break/return will return the
string stop here.

Expressions
Selective Evaluation
Selective Evaluation C
There are several methods to selectively evaluate expressions in REBOL. These

methods provide a way for evaluation to branch many different ways, based on a
key value.
Select 0
The select function is often used to obtain a particular value or block, given a target
value. If you define a block of values and actions, you can use select to search for
the action that corresponds to a value.
cases: [
center [print "center"]
right [print "right"]
left [print "left"]
]
action: select cases ’right
if action [do action]
right
In the previous example, the select function finds the word right and returns
the block that follows it. (If for some reason the block was not found, then none
would have been returned.) The block is then evaluated. The values used in the
example are words, but they can be any kind of value:
cases: [
5:00 [print "everywhere"]
10:30 [print "here"]
18:45 [print "there"]
]
action: select cases 10:30
if action [do action]
here

Expressions
Switch 0
The select function is used so often that there is a special version of it called switch,
which includes the evaluation of the resulting block. The switch function makes it
easier to perform inline selective evaluation. For instance, to switch on a simple
numeric case:
switch 22 [
11 [print "here"]
22 [print "there"]
]
there
The switch function also returns the value of the block it evaluates, so the previous
example can also be written as:
str: copy "right "
print switch 22 [
11 [join str "here"]
22 [join str "there"]
]
right there
and:
car: pick [Ford Chevy Dodge] random 3

print switch car [
Ford [351 * 1.4]
Chevy [454 * 5.3]
Dodge [154 * 3.5]
]
2406.2

Expressions
The cases can be any valid data type, including numbers, strings, words, dates,
times, urls, and files. Here are some examples:
Strings:
person: "kid"
switch person [
"dad" [print "here"]
"mom" [print "there"]
"kid" [print "everywhere"]
]
everywhere
Words:
person: ’kid
switch person [
dad [print "here"]
mom [print "there"]
kid [print "everywhere"]
]
everywhere
Files:
file: %rebol.r
switch file [
%user.r [print "here"]
%rebol.r [print "everywhere"]
%file.r [print "there"]
]
everywhere

Expressions
URLs:
url: ftp://ftp.rebol.org
switch url [
http://www.rebol.com [print "here"]
http://www.cnet.com [print "there"]
ftp://ftp.rebol.org [print "everywhere"]
]
everywhere
Tags:
tag: <LI>
print switch tag [
<PRE> ["Preformatted text"]
<TITLE> ["Page title"]
<LI> ["Bulleted list item"]
]
Bulleted list item
Times:
time: 12:30
switch time [
8:00 [send [email protected] "Hey, get up"]
12:30 [send [email protected] "Join me for lunch."]
16:00 [send [email protected] "Dinner anyone?"]
]

Expressions
Default Case
A default case can be specified when none of the other cases match. Use the default
refinement to specify a default:.
time: 7:00
switch/default time [
5:00 [print "everywhere"]
10:30 [print "here"]
18:45 [print "there"]
] [print "nowhere"]
nowhere
Common Cases
If you have common cases, where the result would be the same for several values,
you can define a word to hold a common block of code:
case1: [print length? url] ; the common block
url: http://www.rebol.com
switch url [
http://www.rebol.com case1
http://www.cnet.com [print "there"]
ftp://ftp.rebol.org case1
]
20
Other Cases
More than just blocks can be evaluated for cases. This example evaluates the file
that corresponds to a day of the week:
switch now/weekday [
1 %monday.r
5 %friday.r
6 %saturday.r
]

Expressions
Stopping Evaluation
So, if it’s Friday, the friday.r file is evaluated and its result is returned from the
switch. This type of evaluation also works for URLs:
switch time [
8:30 ftp://ftp.rebol.org/wakeup.r
10:30 http://www.rebol.com/break.r
18:45 ftp://ftp.rebol.org/sleep.r
]
The cases for switch are enclosed in a block, and therefore can be defined apart
from the switch statement:
schedule: [
8:00 [send [email protected] "Hey, get up"]
12:30 [send [email protected] "Join me for lunch."]
16:00 [send [email protected] "Dinner anyone?"]
]
switch 8:00 schedule
NOTE: Note that for best performance, you can put the most frequently used cases
first.
Stopping Evaluation C
Evaluation of a script can be stopped at any time by pressing the ESC key on the
keyboard or by using the halt and quit functions.
The halt function stops evaluation and returns you to the REBOL console prompt:
if time > 12:00 [halt]
The quit function stops evaluation and exits the REBOL interpreter:
if error? try [print test] [quit]

Expressions
Trying Blocks
Trying Blocks C
There are times when you want to evaluate a block, but should an error occur, you
do not want to stop the evaluation of the rest of your script.
For example, you might be performing a number division, but do not want your
script to stop if a divide-by-zero occurs.
The try function allows you to catch errors during the evaluation of a block. It is
almost identical to do. The try function will normally return the result of the block;
however, if an error occurs, it will return an error value instead.
In the following example, when the divide by zero occurs, the script will pass an
error back to the try function, and evaluation will continue from that point.
for num 5 0 –1 [
if error? try [print 10 / num] [print “error”]
]
5
4
3
2
1
error
More about error handling can be found in the “Errors” Appendix.

4
Scripts
This chapter describes how to format and execute scripts in REBOL/Core. It


■ “Headers” on page 4-2
■ “Script Arguments” on page 4-7
■ “Running Scripts” on page 4-9

■ “Style Guide” on page 4-13
■ “Script Cleanup” on page 4-20
4- 1
Scripts
Overview
Overview D
The term script refers not only to single files that are evaluated but also to source
text embedded within other types of files (such as, web pages), or fragments of
source text that are saved as data files or passed as messages.
File Suffix 0
REBOL scripts typically append a .r suffix to file names; however, this convention
is not required. The interpreter reads files with any suffix and scans the contents for
a valid REBOL script header.
Structure 0
The structure of a script is free-form. Indentation and spacing can be used to clarify
the structure and content of the script. In addition, you are encouraged to use the
standard scripting style to make scripts more universally readable. See the “Style
Guide” on page 4-13 for more information.
Headers D
Directly preceding the script body, every script must have a header that identifies
its purpose and other script attributes. A header can contain the script name,
author, date, version, file name, and additional information. REBOL data files that
are not intended for direct evaluation do not require a header.
Headers are useful for several reasons.
■ They identify a script as being valid source text for the REBOL interpreter.
■ The interpreter uses the header to print out the script’s title and determine what
resources and versions it needs before evaluating the script.
■ Headers provide a standard way to communicate the title, purpose, author, and
other details of scripts. You can often determine from a script’s header if a script
interests you.

Scripts
Headers
■ Script archives and web sites use headers for generating script directories,
categories, and cross references.
■ Some text editors access and update a script’s header to keep track of
information such as the author, date, version, and history.
The general form of a script header is:
REBOL [block]
For the interpreter to recognize the header, the block must immediately follow the
word REBOL. Only white space (spaces, tabs, and lines) is permitted between the
word REBOL and the block.
The block that follows the REBOL word is an object definition that describes the
script. The preferred minimal header is:
REBOL [
Title: "Scan Web Sites"
Date: 2-Feb-2000
File: %webscan.r
Author: "Jane Doer"
Version: 1.2.3
]
When a script is loaded, the header block is evaluated and its words are set to their
defined values. These values are used by the interpreter and can also be used by
the script itself.
Note that words defined as a single value can also be defined as multiple values by
providing them in a block:
REBOL [
Title: "Scan Web Sites"
Date: 12-Nov-1997
Author: ["Ema User" "Wasa Writer"]
]

Scripts
Headers
Headers can be more complex, providing information about the author, copyright,
formatting, version requirements, revision history, and more. Because the block is
used to construct the header object, it can also be extended with new information.
This means that a script can extend the header as needed, but it should be done
with care to avoid ambiguous or redundant information.

Scripts
Headers
A full header might look something like this:
REBOL [
Title: "Full REBOL Header Example"
Date: 8-Sep-1999
Name: ’Full-Header ; For window title bar
Version: 1.1.1
File: %headfull.r
Home: http://www.rebol.com/rebex/
Author: "Carl Sassenrath"

Owner: "REBOL Headquarters"
Rights: "Copyright (C) Carl Sassenrath 1999"
Needs: [2.0 ODBC]

Tabs: 4
Purpose: {
The purpose or general reason for the program
should go here.
}
Note: {
An important comment or notes about the program
can go here.
}
History: [
0.1.0 [5-Sep-1999 "Created this example" "Carl"]
0.1.1 [8-Sep-1999 {Moved the header up, changed
comment on extending the header, added
advanced user comment.} "Carl"]
]
Language: ’English
]

Scripts
Headers
Prefaced Scripts
Script text does not need to begin with a header. Scripts can begin with any text,
allowing them to be inserted into email messages, web pages, and other files.
The header marks the beginning of the script, and the text that follows is the body
of the script. Text that appears before the header is called the preface and is ignored
during evaluation.
The text that appears before the header is ignored

by REBOL and can be used for comments, email headers,
HTML tags, etc.
REBOL [
Title: "Preface Example"
Date: 8-Jul-1999
]
print "This file has a preface before the header"
Embedded Scripts
If a script is to be followed by other text unrelated to the script itself, the script must
be enclosed with square brackets [ ]:
Here is some text before the script.

[
REBOL [
Title: "Embedded Example"
Date: 8-Nov-1997
]
print "done"
]
Here is some text after the script.
Only white space is permitted between the initial bracket and the word REBOL.

Scripts
Script Arguments
Script Arguments D
When a script is evaluated, it has access to information about itself. This is found
in the system/script object. The object contains the fields listed in Table 4-1.
Table 4-1. Object Fields for system/script
Field Description
Header The header object of the script. This can be used to

access the script’s title, author, version, date, and other
fields.
Parent If the script was evaluated from another script, this is
the system/script object for the parent script.
Path The file directory path or URL to the script being
evaluated.
Args The arguments to the script. These are passed from the
operating system command line or from the do function
that was used to evaluate the script.
Examples of using the script object are:
print system/script/title
print system/script/header/date
do system/script/args
do system/script/path/script.r
The last example evaluates a script called script.r in the same directory as the
script that is currently running.

Scripts
Script Arguments
Program Options 0
Scripts also have access to the options provided to the REBOL interpreter when it
was started. These are found in the system/options object. The object contains
the fields listed in Table 4-2.
Table 4-2. Object Fields for system/options
Field Description
Home The file path as determined by your operating system’s

environment. This is the path set in the REBOL_HOME
or HOME environment variable for systems that support
it. This is the path used to find the rebol.r and
user.r files.
Script The file name of the initial script provided when the
interpreter was launched.
Path The path to the current directory.
Args The initial arguments provided to the interpreter on the
command line.
Do-arg The string provided as an argument to the –-do option
on the command line.
The system/options object also contains additional options that were provided
on the command line. Type
probe system/options
to examine the contents of the options object.
Examples:
print system/options/script
probe system/options/args
print read system/options/home/user.r

Scripts
Running Scripts
Running Scripts D
There are two ways to run a script: as the initial script when the REBOL interpreter
is started, or from the do function.
To run a script when starting the interpreter, provide the script name on the
command line following the REBOL program name:
rebol script.r
As soon as the interpreter initializes, the script is evaluated.
From the do function, provide the script file name or URL as an argument. The file
is loaded into the interpreter and evaluated:
do %script.r
do http://www.rebol.com/script.r
The do function returns the result of the script when it finishes evaluation.
Note that the script file must include a valid REBOL header.
Loading Scripts 0
Script files can be loaded as data with the load function. This function reads the
script and translates the script into values, words, and blocks, but does not evaluate
the script. The result of the load function is a block, unless only a single value was
loaded, then that value is returned.
The script argument to the load function is a file name, URL, or a string.
load %script.r
load %datafile.txt
load http://www.rebol.org/script.r
load "print now"
The load function performs the following steps:
■ Reads the text from the file, URL, or string.

Scripts
Running Scripts
■ Searches for a script header, if present.

■ Translates data beginning after the header, if found.
■ Returns a block containing the translated values.
For example, if a script file buy.r contained the text:
Buy 100 shares at $20.00 per share
it could be loaded with the line:
data: load %buy.r
which would result in a block:
probe data
[Buy 100 shares at $20.00 per share]
Note that a file does not require a header to be loaded. The header is necessary only
if the file is to be run as a script.
The load function supports a few refinements. Table 4-3 lists the refinements and a
description of their functionality:
Table 4-3. The load Function Refinements
Refinement Description
/header Includes the header if present.

/next Loads only the next value, one value at a time. This is useful for
parsing REBOL scripts.
/markup Treats the file as an HTML or XML file and returns a block that holds
its tags and text.
Normally, load does not return the header from the script. But, if the /header
refinement is used the returned block contains the header object as its first
argument.

Scripts
Running Scripts
The /next refinement loads the next value and returns a block containing two
values. The first returned value is the next value from the series. The second
returned value is the string position immediately following the last item loaded.
The /markup refinement loads HTML and XML data as a block of tags and strings.
All tags are tag data types. All other data are treated as strings.
If the following file contents where loaded with load/markup:
<title>This is an example</title>
a block would be produced:
probe data
[<title> "This is an example" </title>]
Saving Scripts 0
Data can be saved to a script file in a format that can be loaded into REBOL with
the load function. This is a useful way to save data values and blocks of data. In
this fashion, it is possible to create entire mini-databases.
The save function expects two arguments: a file name and either a block or a value
to be saved:
data: [Buy 100 shares at $20.00 per share]
save %data.r data
The data is written out in REBOL source text format, which can be loaded later
with:
data: load %data.r
Simple values can also be saved and loaded. For instance, a date stamp can be
saved with:
save %date.r now

Scripts
Running Scripts
and later reloaded with:
stamp: load %date.r
In the previous example, because stamp is a single value, it is not enclosed in a

block when loaded.
To save a script file with a header, the header can be provided in a refinement as
either an object or a block:
header: [Title: "This is an example"]
save/header %data.r data header
Commenting Scripts 0
Commenting is useful for clarifying the purpose of sections of a script. Script

headers provide a high level description of the script and comments provide short
descriptions of functions. It is also a good idea to provide comments for other parts
of your code as well.
A single-line comment is made with a semicolon. Everything following the

semicolon to the end of the line is part of the comment:
zertplex: 10 ; set to the highest quality
You can also use strings for comments. For instance, you can create multi-line
comments with a string enclosed in braces:
{
This is a long multilined comment.
}
This technique of commenting works only when the string is not interpreted as an
argument to a function. If you want to make sure that a multi-line comment is
recognized as a comment and is not interpreted as code, precede the string with the
word comment:
comment {
This is a long multilined comment.
}

Scripts
Style Guide
The comment function tells REBOL to ignore the following block or string.
NOTE: Note that string and block comments are actually part of the script block.
Care should be taken to avoid placing them in data blocks, because they would
appear as part of the data.
Style Guide D
REBOL scripts are free-form. You can write a script using the indenting, spacing,
line length, and line terminators you prefer. You can put each word on a separate
line or join them together on one long line.
While the formatting of your script does not affect the interpreter, it does affect its
human readability. Because of this, REBOL Technologies encourages you to follow
the standard scripting style described in this section.
Of course, you don’t have to follow any of these suggestions. However, scripting
style is more important than it first seems. It can make a big difference in the
readability and reuse of scripts. Users may judge the quality of your scripts by the
clarity of their style. Sloppy scripts often mean sloppy code. Experienced script
writers usually find that a clean, consistent style makes their code easier to produce,
maintain, and revise.
Formatting 0
Use the following guidelines for formatting REBOL scripts for clarity.
Indent Content for Clarity

The contents of a block are indented, but the block’s enclosing square brackets [ ]
are not. That’s because the square brackets belong to the prior level of syntax, as
they define the block but are not contents of the block. Also, it’s easier to spot
breaks between adjacent blocks when the brackets stand out.

Scripts
Style Guide
Where possible, an opening square bracket remains on the line with its associated
expression. The closing bracket can be followed by more expressions of that same
level. These same rules apply equally to parenthesis ( ) and braces { }.
if check [do this and that]
if check [
do this and do that
do another thing
do a few more things
]
either check [do something short][

do something else]
either check [
when an expression extends
past the end of a block...
][
this helps keep things
straight
]
while [
do a longer expression
to see if it’s true
][
the end of the last block
and start of the new one
are at the WHILE level
]
adder: func [
"This is an example function"
arg1 "this is the first arg"
arg2 "this is the second arg"
][
arg1 + arg2
]

Scripts
Style Guide
An exception is made for expressions that normally belong on a single line, but
extend to multiple lines:
if (this is a long conditional expression that

breaks over a line and is indented
)[
so this looks a bit odd
]
This also applies to grouped values that belong together, but must be wrapped to fit
on the line:
[
"Hitachi Precision Focus" $1000 10-Jul-1999
"Computers Are Us"
"Nuform Natural Keyboard" $70 20-Jul-1999

"The Keyboard Store"
]
Standard Tab Size

REBOL standard tab size is four spaces. Because people use different editors and
readers for scripts, you can elect to use spaces rather than tabs.
Detab Before Posting

The tab character (ASCII 9) does not indent four spaces in many viewers, browsers,
or shells, so use an editor or REBOL to detab a script before publishing it to the net.
The following function detabs a file with standard four-space tabs:
detab-file: func [file-name [file!]] [

write file-name detab read file-name
]
detab-file %script.r
The following function converts an eight-space tabs to four-space tabs:
detab-file: func [file-name [file!]] [

write file-name detab entab/size read file-name 8
]

Scripts
Style Guide
Limit Line Lengths to 80 Characters

For ease of reading and portability among editors and email readers, limit lines to
80 characters. Long lines that get wrapped in the wrong places by email clients are
difficult to read and have problems loading.
Word Names 0
Words are a user’s first exposure to your code, so it is critical to choose words
carefully. A script should be clear and concise. When possible, the words should
relate to their English or other human language equivalent, in a simple, direct way.
Following are standard naming conventions for REBOL.
Use the Shortest Word that Communicates the Meaning

Short, crisp words work best where possible:
size time send wait make quit
Local words can often be shortened to a single word. Longer, more descriptive
words are better for global words.
Use Whole Words Where Possible

What you save when abbreviating a word is rarely worth it. Type date not dt, or
image-file not imgfl.
Hyphenate Multiple Word Names

The standard style is to use hyphens, not character case, to distinguish words.
group-name image-file clear-screen bake-cake
Begin Function Names with a Verb

Function names begin with a verb and are followed by a noun, adverb, or adjective.
Some nouns can also be used as verbs.
make print scan find show hide take

rake-coals find-age clear-screen

Scripts
Style Guide
Avoid unnecessary words. For instance, quit is just as clear as quit-system.
When using a noun as a verb, use special characters such as ? where applicable.
For instance, the function for getting the length of a series is length?. Other REBOL
functions using this naming convention are:
size? dir? time? modified?
Begin Data Words with Nouns

Words for objects or variables that hold data should begin with a noun. They can
include modifiers (adjectives) as needed:
image sound big-file image-files start-time
Use Standard Names

There are standard names in REBOL that should be used for similar types of
operations. For instance:
make-blub ;creating something new

free-blub ;releasing resources of something
copy-blub ;copying the contents of something
to-blub ;converting to it
insert-blub ;inserting something
remove-blub ;removing something
clear-blub ;clearing something

Scripts
Style Guide
Script Headers 0
The advantage of using headers is clear. Headers give users a summary of a script
and allow other scripts to process the information (like a cataloging script). A
minimum header provides a title, date, file name and purpose. Other fields can also
be provided such as author, notes, usage, and needs.
REBOL [
Title: "Local Area Defringer"
Date: 1-Jun-1957
File: %defringe.r
Purpose: {
Stabilize the wide area ignition transcriber
using a double ganged defringing algorithm.
}
]
Function Headers 0
It is useful to provide a description in function specification blocks. Limit such text

to one line of 70 characters or less. Within the description, mention what type of
value the function normally returns.
defringe: func [
"Return the defringed localization radius."
area "Topo area to defringe"
time "Time allotted for operation"
/cost num "Maximum cost permitted"
/compound "Compound the calculation"
][
...code...
]
Script File Names 0
The best way to name a file is to think about how you can best find that file in a
few months. Short and clear names are often enough. Plurals should be avoided,
unless meaningful.

Scripts
Style Guide
In addition, when naming a script, consider how the name will sort in a directory.
For instance, keep related files together by starting them with a common word.
%net-start.r
%net-stop.r
%net-run.r
Embedded Examples 0
Where appropriate, provide examples within a script to show how the script
operates and to give users a quick way of verifying that the script works correctly
on their system.
Embedded Debugging 0
It is often useful to build in debugging functions as part of the script. This is

especially true of networking and file handling scripts where it is not desirable to
send and write files while running in test mode. Such tests can be enabled with a
control variable at the head of the script.
verbose: on
check-data: off
Minimize Globals 0
In large scripts and where possible, avoid using global variables that carry their
internal state from one module or function to another. For short scripts, this isn’t
always practical. But recognize that short scripts may become longer scripts over
time.
If you have a collection of global variables that are closely related, consider using
an object to keep track of them:
user: make object! [

name: "Fred Dref"
age: 94
phone: 707-555-1234
email: [email protected]
]

Scripts
Script Cleanup
Script Cleanup D
Here is a short script that can be used to clean up the indentation of a script. It
works by parsing the REBOL syntax and reconstructing each line of the script. This
example can be found in the REBOL Script Library at www.REBOL.com.
out: none ; output text

spaced: off ; add extra bracket spacing
indent: "" ; holds indentation tabs
emit-line: func [] [append out newline]
emit-space: func [pos] [

append out either newline = last out [indent] [
pick [#" " ""] found? any [
spaced
not any [find "[(" last out
find ")]" first pos]
]
]
]
emit: func [from to] [

emit-space from append out copy/part from to
]
clean-script: func [
"Returns new script text with standard spacing."
script "Original Script text"
/spacey "Optional spaces near brackets/parens"
/local str new
] [
spaced: found? Spacey
out: append clear copy script newline
parse script blk-rule: [
some [
str:
newline (emit-line) |
#";" [thru newline | to end] new:

Scripts
Script Cleanup
(emit str new) |
[#"[" | #"("]
(emit str 1 append indent tab)
blk-rule |
[#"]" | #")"]
(remove indent emit str 1) |
skip (set [value new]
load/next str emit str new) :new
]
]
remove out ; remove first char
]
script: clean-script read %script.r
write %new-script.r script

Scripts
Script Cleanup

5
Series
This chapter explains the concepts behind series and how they are used in
REBOL/Core. It includes the following information:
■ “Basic Concepts” on page 5-2

■ “Series Functions” on page 5-21
■ “Series Data Types” on page 5-24
■ “Series Information” on page 5-26

■ “Making and Copying Series” on page 5-31
■ “Series Iteration” on page 5-36
■ “Searching Series” on page 5-41

■ “Sorting Series” on page 5-53
■ “Series as Data Sets” on page 5-57
■ “Multiple Series Variables” on page 5-64

■ “Modification Refinements” on page 5-65
5- 1
Series
Basic Concepts
Basic Concepts E
The concept of a series is quite simple to grasp and is the basis for nearly everything
in REBOL. It is very important to understand series well.
A series is a set of values organized in a specific order.
There are many series data types in REBOL. A block, a string, a list, a URL, a path,
an email, a file, a tag, a binary, a bitset, a port, a hash, an issue, and an image are
all series data types. Series data types can all be accessed and processed in the same
way with the same small set of functions.
Traversing a Series 0
Since a series is an ordered set of values, you can traverse within it. As an example,
take a series of three colors defined by the following block:
There is nothing special about this block. It is a series containing three words. It
has a set of values: red, green, and blue. The values are organized into a specific
order: red is first, green is second, and blue is third.
The first position of the block is called its head. This is the position occupied by
the word red. The last position of the block is called its tail. This is the position
immediately after the last word in the block. If you were to draw a diagram of the
block, it would look like this:
red green blue
Head Tail
Notice that the tail is just past the end of the block. The importance of this will
become more clear shortly.

Series
Basic Concepts
The variable colors is used to refer to the block. It is currently set to the head of
the block:
red green blue
Colors
print head? colors
true
The colors variable is at the first index position of the block.
print index? colors
The block has a length of three:
print length? colors
The first item in the block is:
print first colors
red
The second item in the block is:
print second colors
green

Series
Basic Concepts
You can reposition the colors variable in the block using various functions. To
move the colors variable to the next position in the colors block, use the next
function:
colors: next colors
The next function moves forward one value in the block and returns that position
as a result. The colors variable is now set to that new position:
red green blue
Colors
The position of the colors variable has changed. Now the variable is no longer
at the head of the block:
print head? colors
false
It is at the second position in the block:
print index? colors
However, if you obtain the first item of colors, you get:
print first colors
green
The position of the value that is returned by the first function is relative to the
position that colors has in the block. The returned value is not the first color in
the block, but the first color immediately following the current position of the block.

Series
Basic Concepts
Similarly, if you ask for the length or the second color, you find that these are
relative as well:
print length? Colors
print second colors
blue
You could move to the next position, and get a similar set of results:
colors: next colors
print index? colors
print first colors
blue
The block diagram now looks like this:
red green blue
Colors

Series
Basic Concepts
The colors variable is now at the last color in the block, but it is not yet to the tail
position.
print tail? colors
false
To reach the tail, it has to be moved to the next position:
colors: next colors
Now the colors variable is resting at the tail of the block. It is no longer
positioned at a valid color, but is past the end of the block.
re d green blue
Colors
If you try your code, you will get:
print tail? colors
false
print index? colors
print length? Colors
print first colors
** Script Error: Out of range or past end.

** Where: print first colors

Series
Basic Concepts
You receive an error in this last case because there is no valid first item when you
are past the end of the block.
It is also possible to move backwards in the block. If you write:
colors: back colors
you will move the colors variable back one position in the series:
red green blue
Colors
All of the same code will work as before:
print index? colors
print first colors
blue
Skipping Around 0
The previous examples move through the series one item at a time. However, there
are times when you want to skip past multiple items using the skip function.
Assume that the colors variable is positioned at the head of a series:
red green blue
Colors

Series
Basic Concepts
You can skip forward two items using:
colors: skip colors 2
The skip function is similar to next in that skip returns the series at the new
position.
red green blue
Colors
The following code confirms the new position:
print index? colors
print first colors
blue
To move backward, use skip with negative values:
colors: skip colors -1
This is similar to back. In the above example, a skip of –1 moves back one item.
red green blue
Colors
print first colors
green

Series
Basic Concepts
Note that you cannot skip past the tail or the head of a series. If you attempt to do
so, skip only goes as far as it can. It will not generate an error.
If you skip too far forward, skip returns the tail of the series:
colors: skip colors 20
print tail? colors
true
If you skip too far back, skip returns the head of the series:
colors: skip colors –100
print head? colors
true
To skip directly to the head of the series, use the head function:
colors: head colors
print head? colors
true
print first colors
red
You can return to the tail with the tail function:
colors: tail colors
print tail? colors
true

Series
Basic Concepts
Extracting Values 0
Some of the previous examples made use of the first and second ordinal functions
to extract specific values from a series. The full set of ordinal functions is:
first
second
third
fourth
fifth
last
Ordinal functions are provided as a convenience, and are used for picking values
from the most common position in a series. Here are some examples:
colors: [red green blue gold indigo teal]
print first colors
red
print third colors
blue
print fifth colors
indigo
print last colors
teal

Series
Basic Concepts
To extract from a numeric position, use the pick function:
print pick colors 3
blue
print pick colors 5
indigo
A shorthand notation for pick is to use a path:
print colors/3
blue
print colors/5
indigo
Remember, as shown earlier, extraction is performed relative to the series variable

that you provide. If the colors variable were at another position in the series, the
results would be different.
Extracting a value past the end of its series generates an error in the case of the
ordinal functions and returns none in the case of the pick function or a pick path:
print pick colors 10
none
print colors/10
none

Series
Basic Concepts
Extracting a Sub-series 0
You can extract multiple values from a series with the copy function. To do so, use
copy with the /part refinement, which specifies the number of values that you want
to extract:
sub-colors: copy/part colors 2
probe sub-colors
[red green]
Graphically, this would look like:
red green blue
copy/part colors 2
red green
To copy a sub-series from any position within the series, first traverse to the starting
position. The following example moves forward to the second position in the series
using next before performing the copy:
sub-colors: copy/part next colors 2
probe sub-colors
[green blue]

Series
Basic Concepts
This would be diagrammed as:
red green blue
copy/part next colors 2
green blue
The length of the series to copy can be specified as an ending position, as well as a
copy count. Note that the position indicates where the copy should stop, not the
ending position.
probe copy/part colors next colors
[red]
probe copy/part colors back tail colors
[red green]
probe copy/part next colors back tail colors
[green]
This can be useful when the ending position is found as the result of the find
function:
file: %image.jpg
print copy/part file find file "."
image
Inserting and Appending 0
You can insert one or more new values into any part of a series using the insert
function. When you insert a value at a position in a series, space is made by shifting
its prior values toward the tail of the series.

Series
Basic Concepts
For instance, the block:
colors: [red green]
would be shown as:
red green
Colors
To insert a new value at the head of the block where the colors variable is now
positioned:
insert colors 'blue
The red and green words are shifted over and the blue word (which is prefixed
with a tick because it is a word and should not be evaluated) is inserted at the head
of the list.
blue red green
Colors
Note that the colors variable remains positioned at the head of the list.
probe colors
[blue red green]
Also note that the return from the insert function was not used because it was not
set to a variable or passed along to another function. If the return had been used to
set the value of the colors variable with the line:
colors: insert colors 'blue

Series
Basic Concepts
the effect on the block would have been the same, but the position of the colors
variable would have changed as a result of setting the return value. The position
returned from insert is immediately following the insertion point.
blue red green
Colors
An insertion can be made anywhere in the series. The position of the insert can be
specified, and it can include the tail. Inserting at the tail has the effect of appending
to the series.
colors: tail colors
insert colors 'gold
probe colors
[blue red green gold]
Before the insertion:
blue red green
Colors
After the insertion:
blue red green gold
Colors

Series
Basic Concepts
The word gold has been inserted at the tail of the series.
Another way to insert at the tail of a series is with the append function. The
append function works in the same way as insert, but always inserts at the tail.
The previous example would become:
append colors 'gold
The result is the same as the previous example.
The insert and append function also accept a block of arguments to insert. As an
example:
colors: [red green]
insert colors [blue yellow orange]
probe colors
[blue yellow orange red green]
If you want to insert the new values between the red and green words:
colors: [red green]
insert next colors [blue yellow orange]
probe colors
[red blue yellow orange green]
The insert and append functions have other capabilities that are covered in more
detail in a later section.
Removing Values 0
You can remove one or more values from any part of a series by using the remove
function.

Series
Basic Concepts
For instance, starting with the block:
Colors: [red green blue gold]
As shown here:
red green blue gold
Colors
You can remove the first value from the block with the line:
remove colors
The block becomes:
green blue gold
Colors
It can be printed with:
probe colors
[green blue gold]
The remove function removes values relative to the position of the colors
variable. You can remove values from anywhere in the series by setting the
position.
remove next colors

Series
Basic Concepts
The block is now:
green gold
Colors
Multiple values can be removed by supplying the /part refinement.
remove/part colors 2
This removes the remaining values, leaving an empty block:
Colors
Similar to insert/part, the argument to remove/part can also be a position within

the block.
Removing all of the remaining values is a common operation. The clear function is
provided to make this more direct. Clear removes all values from the current
position to the tail. For example:
Colors: [blue red green gold]
As shown here:
blue red green gold
Colors

Series
Basic Concepts
Everything after blue can be removed with:
clear next colors
The block becomes:
blue
Colors
You can easily clear the entire block with:
clear colors
Changing Values 0
One additional set of functions is provided for changing values in a series. The
change function replaces one or more values with new values. Although this can
be accomplished by removing and inserting values, it is more efficient to use
change.
Defining the block:
colors: [blue red green gold]
blue red green gold
Colors
Its second value could be changed with the line:
change next colors 'yellow

Series
Basic Concepts
And it would become:
blue yellow green gold
Colors
The block would now become:
probe colors
[blue yellow green gold]
The poke function allows you to specify that the change occur at a particular
position relative to the colors variable. The poke function is similar to the pick
function described earlier.
poke colors 3 'red
The block is now:
blue yellow red gold
Colors
As proven by:
probe colors
[blue yellow red gold]
The change function has additional refinements that are described later in this
chapter.

Series
Series Functions
Series Functions E
Here is a summary of the functions that operate on series. Most of these were
described in detail in the previous section. Others will be covered in more detail in
this section.
Creation 0
Table 5-1. Creation Functions
Function Description
make Makes a new series of the given type.

copy Copies a series.
Navigation 0
Table 5-2. Navigation Functions
next Returns the next position in a series.

back Returns the previous position in a series.
head Returns the head position of a series.
tail Returns the tail position of a series.
skip Returns the position plus or minus an integer.
at Returns the position plus or minus an integer, but uses the same
indexing as pick.

Series
Series Functions
Information 0
Table 5-3. Information Functions
head? Returns true if at the head of the series.

tail? Returns true if at the tail of the series.
index? Returns the offset from the head of the series.
length? Returns the length of a series from the current position.
offset? Returns the distance between two series positions.
empty? Returns true if the series is empty from this position.
Extraction 0
Table 5-4. Extraction Functions
pick Extracts a single value from a position in a series.

copy/part Extracts a sub-series from a series.
first Extracts the first value from a series.
second Extracts the second value from a series.
third Extracts the third value from a series.
fourth Extracts the fourth value from a series.
fifth Extracts the fifth value from a series.
last Extracts the last value from a series.

Series
Series Functions
Modification 0
Table 5-5. Modification Functions
insert Inserts values into a series.

append Appends values to the tail of a series.
remove Removes values from a series.
clear Clears values to the tail of a series.
change Changes values in a series.
poke Changes values at a position in a series.
Search 0
Table 5-6. Search Functions
find Finds a value in a series.

select Finds an associated value in a series.
replace Searches and replaces values in a series.
parse Parses values in a series.

Series
Series Data Types
Ordering 0
Table 5-7. Ordering Functions
sort Sorts the values in a series into an order.

reverse Reverse the order of values in a series
Data Sets 0
Table 5-8. Data Set Functions
unique Returns a unique set of values, removing duplicates.

intersect Returns only the values found in both series.
union Returns the combined values from two series.
exclude Returns one series less another.
difference Returns the values not found in either series.
Series Data Types E
All series data types can be divided into two broad classes. Each includes a data
type value and a type test function.

Series
Series Data Types
Block Types 0
Table 5-9. Block Types
Block Type Description
Block! Blocks of values

Paren! Blocks of values enclosed in parentheses
Path! Paths of values
List! Linked lists
Hash! Associative arrays
String Types 0
Table 5-10. String Types
String Type Description
String! Character strings

Binary! Byte strings
Tag! HTML and XML tags
File! File names
URL! Internet uniform resource locators
Email! Email names
Image! Image data
Issue! Sequence codes

Series
Series Information
Pseudo-types 0
Series data types are grouped into a few pseudo-types that make function argument
and type testing easier:
Table 5-11. Pseudo-types
Pseudo-type Description
Series! A series data type

Any-block! Any of the block data types
Any-string! Any of the string data types
Type Test Functions 0
Block type tests:
Block? Paren? Path? List? Hash?
String type tests:
String? Binary? Tag? File? URL?
Email? Image? Issue?
Other series type tests:
Series? Any-block? Any-string?
Series Information E
Length? 0
The length of a series is the number of items (values for a block or characters for a
string) from the current position to the tail. If the current position is the head of the
series, then the length is the number of items in the entire series.

Series
Series Information
The length? function returns the number of items to the tail.
colors: [blue red green]

All three values are part of the length:
Length of 3
blue red green
Colors Tail
If the position of the color variable is advanced to the next value:
color: next color

print length? color
the length becomes two:
Length of 2
blue red green
Colors Tail

Series
Series Information
Other examples of length?:
print length? "Ukiah"
print length? []
print length? ""
data: [1 2 3 4 5 6 7 8]
print length? data
data: next data

print length? data
data: skip data 5

print length? data

Series
Series Information
Head? 0
The head of a series is the position of its first value. If a series is at its head, the
head? function returns true:
data: [1 2 3 4 5]
print head? data
true
data: next data

print head? data
false
Tail? 0
The tail of a series is the position immediately following the last value. If a series
variable is at the tail, the tail? function returns true:
data: [1 2 3 4 5]
print tail? data
false
data: tail data

print tail? data
true
The empty? function is equivalent to the tail? function.
print empty? data
true

Series
Series Information
If empty? returns true, it means there are no values between the current position
and the tail; however, there still may be values in the series. Values can still be
present before the current position. If you need to determine if the series is empty
from head to tail, use:
print empty? head data
false
Index? 0
The index is the position in a series relative to the head of the series. To determine
the index position for a series variable, use the index? function:
data: [1 2 3 4 5]
print index? data
data: next data

print index? data
data: tail data

print index? data

Series
Making and Copying Series
Offset? 0
The distance between two positions in a series can be determined with the offset?
function.
data: [1 2 3 4]
data1: next data
data2: back tail data
print offset? data1 data2
In this example, the offset is the difference between position 2 and position 4:
Offset of 2
1 2 3 4
data1 data2
Empty?
Making and Copying Series E
New series are created with the make and copy functions.
Use the make function to create a new series from a series data type and an initial
size. The size is an estimate of the size needed for the series. If the initial size is
too small, the series will automatically expand, but at a slight performance cost.
block: make block! 50
string: make string! 10000
list: make list! 128
file: make file! 64

Series
The copy function creates a new series by copying an existing series:
string: copy "Message in a bottle"
new-string: copy string
block: copy [1 2 3 4 5]
new-block: copy block
Copying is also important for use with functions that modify the contents of a
series. For instance, if you want to change the case of a string without modifying
the original, use the copy:
string: uppercase copy "Message in a bottle"

Series
Partial Copies 0
The copy function /part refinement takes a single argument, which is either an
integer specifying the number of items to copy or a position within the series
indicating the last position to copy.
str: "Message in a bottle"

print str
Message in a bottle
print copy/part str find str " "
Message
new-str: copy/part (find str "in") (find str "bottle")

print new-str
in a
blk: [ages [10 12 32] sizes [100 20 30]]

new-blk: copy/part blk 2
probe new-blk
[ages [10 12 32]]
Deep Copies 0
Many blocks contain other blocks and strings. When such a block is copied, its
sub-series are not copied. The sub-series are referred to directly and are the same
series data as the original block. If you modify any of these sub-series, you modify
them in the original block as well.
The copy/deep refinement forces a copy of all series values within a block:
blk-one: ["abc" [1 2 3]]

probe blk-one
["abc" [1 2 3]]

Series
The next example assigns a normal copy of blk-one to blk-two:
blk-two: copy blk-one

probe blk-one
probe blk-two
["abc" [1 2 3]]
["abc" [1 2 3]]
If either the string or block contained in blk-two is modified, the series values in
blk-one are also modified.
append blk-two/1 "DEF"

append blk-two/2 [4 5 6]
probe blk-one
probe blk-two
["abcDEF" [1 2 3 4 5 6]]
["abcDEF" [1 2 3 4 5 6]]
Using copy/deep makes a copy of all series values found in the block:
blk-two: copy/deep blk-one

append blk-two/1 "ghi"
append blk-two/2 [7 8 9]
probe blk-one
probe blk-two
["abcDEF" [1 2 3 4 5 6]]
["abcDEFghi" [1 2 3 4 5 6 7 8 9]]
Initial Copies 0
When initializing a string or block series, use copy on the value to make is a unique
series:
str: copy ""

blk: copy []

Series
Using copy assures that a new series is created for the word every time the word is
initialized. Here is an example of why this is important.
print-it: func [/local str] [

str: ""
insert str "ha"
print str
]
print-it
ha
print-it
haha
print-it
hahaha
In this example, because copy wasn’t used, the empty string series is modified with
every call of print-it. The string series ha is inserted into str each time
print-it is called.
Examining the source of the function as it now exists exposes the root of the
problem:
source print-it

str: "hahaha"
insert str "ha"
print str
]

Series
Series Iteration
Although str is a local variable, its string value is global. To avoid this problem,
the function should copy the empty string or use make on the string.

str: copy ""
insert str "ha"
print str
]
print-it
ha
print-it
ha
print-it
ha
Series Iteration E
You can use a loop to traverse a series. There are a few loop functions that can help
automate the iteration process.
While Loop 0
The most flexible approach is to use a while loop, which allows you to do just about
anything to the series without problems.
colors: [red green blue yellow orange]
while [not tail? colors] [

print first colors
colors: next colors
]

Series
Series Iteration
The method shown below allows you to insert values without hitting a value twice:
colors: head colors

if colors/1 = 'yellow [
colors: insert colors 'blue
]
colors: next colors
]
This example illustrates that the insert returns the position immediately following
the insertion.
To remove a value without accidentally skipping a value, use the following code:
colors: head colors

either colors/1 = 'blue [
remove colors
][
colors: next colors
]
]
Notice that if a removal is done, the next function is not performed.
Forall Loop 0
The forall loop is similar to the while loop, but eliminates some of the effort
required. The forall loop starts from the current index and advances through a
series to its tail evaluating a block for every value.

Series
Series Iteration
The forall loop takes two arguments: a series variable and a block to evaluate for
each iteration.
forall colors [print first colors]
red
green
blue
yellow
orange
The forall advances the variable position through the series, so when it returns the
variable is left at its tail:
print tail? colors
true
Therefore, the variable must be reset before it is used again:
colors: head colors
Also, if the block modifies the series, be careful to avoid missing or repeating a
value. The forall loop works in some cases; however, if you are uncertain, use the
while loop instead.
forall colors [
if colors/1 = 'blue [remove colors]
print first colors
]
red
green
yellow
orange

Series
Series Iteration
Forskip Loop 0
Similar to forall, the forskip loop advances through a series starting at the current
position, but skips the specified number of values each time.
The forskip loop takes three arguments: a series variable, the skip between each
iteration, and a block to evaluate for each iteration.
forskip colors 2 [print first colors]
red
blue
orange
The forskip loop leaves the series at its tail, requiring you to reset it.
print tail? colors
true
colors: head colors
Foreach Loop 0
The foreach loop moves through a series setting a word or multiple words in to the
values in the series.

Series
Series Iteration
The foreach loop takes three arguments: a word or a block of words that holds the
values for each iteration, a series, and a block to evaluate for each iteration.
colors: [red green blue yellow orange gold]
foreach color colors [print color]
red
green
blue
yellow
orange
gold
foreach [c1 c2] colors [print [c1 c2]]
red green
blue yellow
orange gold
foreach [c1 c2 c3] colors [print [c1 c2 c3]]
red green blue

yellow orange gold
The foreach loop does not advance the current index through the series, so there is
no need to reset its series variable.
The Break Function 0
Any of the loops can be stopped at any time by evaluating the break function from
within the evaluation block. See the “Expressions” Chapter for more information
about the break function.

Series
Searching Series
Searching Series E
The find function searches through block or string series for a value or pattern.
This function has many refinements that permit a wide range of variations in search
parameters.
Simple Find 0
The simplest and most common use of find is to search a block or string for a value.
In this case, find requires only two arguments: the series to search and the value to
find.
An example of using find on a block is:

where: find colors 'blue
probe where
[blue yellow orange]
print first where
blue
The find function can also search for values by data type. This can be quite useful.
items: [10:30 20-Feb-2000 Cindy "United"]

where: find items date!
print first where
20-Feb-2000
where: find items string!

print first where
United

Series
Searching Series
An example of using find on a string is:
colors: "red green blue yellow orange"

where: find colors "blue"
print where
blue yellow orange
When a search fails, none is returned.

probe find colors 'indigo
none
Refinement Summary 0
Find has many refinements that support a wide variety of search parameters:
Table 5-12. Refinement Summary
/part Limits a search on a series to a given length or ending position.

/only Treats a series value as a single value.
/case Uses case-sensitive string comparison.
/any Allows the use of pattern wildcards that allow matches to be
made with any character. An asterisk (*) in the pattern
matches any string, and a question mark (?) in the pattern
matches any character.
/with Allows pattern wildcards with different characters other than
asterisk (*) and (?). This allows a pattern to contain asterisks
and question marks.
/match Matches a pattern beginning at the current series position,
rather than finding the first occurrence of a value or string.
Returns the tail position if the match is found.

Series
Searching Series
Table 5-12. Refinement Summary
/tail Return the tail position of a match on a successful search,

rather than returning the point at which the match was found.
/last Searches backwards for the match, starting at the tail of the
series.
/reverse Searches backwards for the match, starting at the current
position.
Partial Searches 0
The /part refinement allows a search to be confined to a specific portion of a series.

For instance, you may want to restrict a search to a given line or section of text.
Similar to insert/part and remove/part, find/part takes either a count or an ending

position. The following example uses a count and restricts the search to the first
three items:
colors: [red green blue yellow blue orange gold]

probe find/part colors 'blue
[blue yellow blue orange gold]
The next search is restricted to the first 15 characters:
text: "Keep things as simple as you can."

print find/part text "as" 15
as simple as you can.

Series
Searching Series
The next example uses an ending position. The search is restricted to a single line
of text:
text: {
This is line one.
This is line two.
}
start: find text "this"

end: find start newline
item: find/part start "line" end
print item
line one.
Tail Positions 0
The find function returns the position in the series where an item was found. The
/tail refinement returns the position immediately following the item that was
found. Here’s an example:
filename: %script.txt
print find filename "."
.txt
print find/tail filename "."
txt
clear change find/tail filename "." "r"

print filename
script.r
In this example, clear is necessary to remove xt, which follows t.

Series
Searching Series
Backward Searches 0
The last example in the previous section would fail if the filename had more than
one period. For instance:
filename: %new.script.txt
print find filename "."
.script.txt
In this example we want the last occurrence of the period in the string, which can
be found using the /last refinement. The /last refinement searches backward
through a series.
print find/last filename "."
.txt
The /last refinement can be combined with /tail to produce:
print find/last filename "."
txt
If you want to continue to search backward through the string, you need the
/reverse refinement. This refinement performs a search from the current position
backward toward the head, rather than forward toward the tail.
where: find/last filename "."

print where
.txt
print find/reverse where "."
.script.txt
Notice that /reverse continues the search just before the position of the last match.
This prevents it from finding the same period again.

Series
Searching Series
Repeated Searches 0
You can easily repeat the find function to search for multiple occurrences of a value
or string. Here is an example that would print all the strings found in a block:
blk: load %script.r

while [blk: find blk string!] [
print first blk
blk: next blk
]
The next example counts the number of new lines in a script. It uses the /tail
refinement to prevent an infinite loop and returns the position immediately
following the match.
text: read %script.r

count: 0
while [text: find/tail text newline] [count: count + 1]
To perform a repeated search in reverse, use the /reverse refinement. The following
example prints all of the index positions in reverse order for the text of a script.
while [text: find/reverse tail text newline] [

print index? text
]
Matching 0
The /match refinement modifies the behavior of find to perform pattern matching
on the current position of a series. This refinement allows parsing operations to be
performed by matching the next part of a series with expected patterns. See the
chapter on “Parsing” for another way to match series.

Series
Searching Series
A simple example of matching is as follows:
blk: [1432 "Franklin Pike Circle"]

probe find/match blk integer!
["Franklin Pike Circle"]
probe find/match blk 1432
["Franklin Pike Circle"]
probe find/match blk "test"
none
str: "Keep things simple."

probe find/match str "keep"
" things simple."
print find/match str "things"
none
Notice in the example that a search is not performed. The beginning of the series
either matches or it does not. If it does match, the series is advanced the position
immediately following the match point, allowing you to match the next sequence.

Series
Searching Series
Here is a simple parser written with find/match:
grammar: [
["keep" "make" "trust"]
["things" "life" "ideas"]
["simple" "smart" "happy"]
]
parse-it: func [str /local new] [

foreach words grammar [
foreach word words [
if new: find/match str word [break]
]
if none? new [return false]
str: next new ;skip space
]
true
]
print parse-it "Keep things simple"
true
print parse-it "Make things smart"
true
print parse-it "Trust life well"
false
Matching can be made case-sensitive with the /case refinement.
The capability of /match can be greatly extended with the addition of the /any
refinement as discussed below.

Series
Searching Series
Wildcard Searches 0
The /any refinement enables wildcard pattern matching. The question mark (?)
and asterisk (*) characters act as wildcards for matching any single character or any
number of characters respectively. The /any refinement can be used in conjunction
with find with or without the /match refinement.
Examples:
str: "abcdefg"
print find/any str "c*f"
cdefg
print find/any str "??d"
bcdefg
email-list: [
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
]
foreach email email-list [
if find/any email *@rebol.dom [print email]
]
[email protected]
[email protected]
[email protected]

Series
Searching Series
The next example uses the /match refinement to attempt to match the pattern to
the next part of the series:
file-list: [
%rebol.exe
%notes.html
%setup.html
%feedback.r
%nntp.r
%rebdoc.r
%rebol.r
%user.r
]
foreach file file-list [

if find/match/any file %reb*.r [print file]
]
rebdoc.r
rebol.r
If either of the wildcard characters are part of what is to be matched, substitute

wildcard characters can be provided using the /with refinement.
Select 0
A useful variation of the find function is the select function, which returns the
value following the one found. The select function is often used to lookup a value
in tagged blocks of data. The select function takes the same arguments as find: the
series to search and the value find. However, unlike find, which returns a series
position, the select function returns the value that follows the match.

print select colors 'green
blue

Series
Searching Series
Given a simple database, the select function can be used to access its values:
email-book: [
"George" [email protected]
"Paul" [email protected]
"Ringo" [email protected]
"Robert" [email protected]
]
The following code locates a specific email address:
print select email-book "Paul"
[email protected]
Use the select function to find a block of expressions to evaluate. For example, given
the following data:
cases: [
10 [print "ten"]
20 [print "twenty"]
30 [print "thirty"]
]
a block can be evaluated based on a selector:
do select cases 10
ten
do select cases 30
thirty
Search and Replace 0
To replace values throughout a series, you can use the replace function. This
function searches for a specific value in a series, then replaces it with a new value.

Series
Searching Series
The replace function takes three arguments: the series to search, value to replace,
and the new value.
str: "hello world hello"

probe replace str "hello" "aloha"
"aloha world hello"
data: [1 2 8 4 5]
probe replace data 8 3
[1 2 3 4 5]
probe replace data 4 ‘four
[1 2 3 four 5]
probe replace data integer! 0
[0 2 3 four 5]

Series
Sorting Series
Use the /all refinement to replace all occurrences of the value from the current
position to the tail.
probe replace/all data integer! 0
[0 0 0 four 0]
code: [print "hello" print "world"]

replace/all code 'print 'probe
probe code
[probe "hello" probe "world"]
do code
hello
world
str: "hello world hello"

probe replace/all str "hello" "aloha"
"aloha world aloha"
Sorting Series E
The sort function offers a simple, quick method of sorting series. It is most useful
for blocks of data, but can also be used on strings of characters.

Series
Sorting Series
Simple Sorting 0
The simplest examples of sort are:
names: [Eve Luke Zaphod Adam Matt Betty]

probe sort names
[Adam Betty Eve Luke Matt Zaphod]
print sort [321.3 78 321 42 321.8 12 98]
12 42 78 98 321 321.3 321.8
print sort "plosabelm"
abellmops
Notice that sort is destructive to its argument series. It reorders the original data.
To prevent this, use copy, as in the following example:
probe sort copy names
By default, sorting is case insensitive:
print sort ["Fred" "fred" "FRED"]
Fred fred FRED
print sort "G4C28f9I15Ed3bA076h"
0123456789AbCdEfGhI

Series
Sorting Series
Providing the /case refinement makes sorting case sensitive:
print sort/case "gCcAHfiEGeBIdbFaDh"
ABCDEFGHIabcdefghi
print sort/case ["Fred" "fred" "FRED"]
FRED Fred fred
print sort/case "g4Dc2BI8fCF9i15eAd3bGaE07H6h"
0123456789ABCDEFGHIabcdefghi
Many other data types can be sorted:
print sort [1.3.3.4 1.2.3.5 2.2.3.4 1.2.3.4]
1.2.3.4 1.2.3.5 1.3.3.4 2.2.3.4
print sort [$4.23 $23.45 $62.03 $23.23 $4.22]
$4.22 $4.23 $23.23 $23.45 $62.03
print sort [11:11:43 4:12:53 4:14:53 11:11:42]
4:12:53 4:14:53 11:11:42 11:11:43
print sort [11-11-1999 10-11-9999 11-4-1999 11-11-1998]
11-Nov-1998 11-Apr-1999 11-Nov-1999 10-Nov-9999
print sort [[email protected] [email protected] [email protected]]
[email protected] [email protected] [email protected]
print sort [%user.r %rebol.r %history.r %notes.html]
history.r notes.html rebol.r user.r

Series
Sorting Series
Group Sorting 0
Often it is necessary to sort a data set that has more than one value per record. The
/skip refinement supports this for sorting records that have a fixed length. The
refinement takes one additional argument: an integer specifying length of each
record.
Here is an example that sorts a block that contains first name, last name, ages, and
emails. The block is sorted by its first column, first-name.
names: [
"Evie" "Jordan" 43 [email protected]
"Matt" "Harrison" 87 [email protected]
"Luke" "Skywader" 32 [email protected]
"Beth" "Landwalker" 104 [email protected]
"Adam" "Beachcomber" 29 [email protected]
]
sort/skip names 4
foreach [first-name last-name age email] names [
print [first-name last-name age email]
]
Adam Beachcomber 29 [email protected]

Beth Landwalker 104 [email protected]
Evie Jordan 43 [email protected]
Luke Skywader 32 [email protected]
Matt Harrison 87 [email protected]
Comparison Functions 0
The /compare refinement allows you to perform custom comparisons on the data
being sorted. This refinement takes an additional argument, which is the
comparison function to use for ordering the data.
A comparison function is written as a regular function that takes two arguments.

These arguments are the values to be compared. A comparison function returns
true if the first value should be placed before the second value and false if the
first value should be placed after the second value.

Series
Series as Data Sets
A normal comparison places data in ascending order:
ascend: func [a b] [a < b]
If the first value is less than the second, then true is returned from the function
and the first value is placed before the second value.
data: [100 101 -20 37 42 -4]

probe sort/compare data :ascend
[-20 -4 37 42 100 101]
Similarly:
descend: func [a b] [a > b]
If the first value is greater than the second value, then true is returned and the data
is sorted with greater values first. The sort will descend from greater values.
probe sort/compare data :descend
[101 100 42 37 -4 -20]
Notice that in both cases the comparison function is passed by providing its name
preceded with a colon. The name preceded with a colon causes the function to be
passed to sort without first being evaluated. The comparison function could also
be provided directly with:
probe sort/compare data func [a b] [a > b]
[101 100 42 37 -4 -20]
Series as Data Sets E
There are a few functions that operate on series as data sets. These functions allow
you to perform operations such as finding the union or intersection between two
series.

Series
Series as Data Sets
Unique 0
The unique function returns a unique set that contains no duplicate values.
Examples:
data: [Bill Betty Bob Benny Bart Bob Bill Bob]

probe unique data
[Bill Betty Bob Benny Bart]
print unique "abracadabra"
abrcd
Intersect 0
The intersect function takes two series and returns a series that contains the values
that are present in both series.

Series
Series as Data Sets
Examples:
probe intersect [Bill Bob Bart] [Bob Ted Fred]
[Bob]
lunch: [ham cheese bread carrot]

dinner: [ham salad carrot rice]
probe intersect lunch dinner
[ham carrot]
print intersect [1 3 2 4] [3 5 4 6]
3 4
string1: "CBAD" ; A B C D scrambled

string2: "EDCF" ; C D E F scrambled
print sort intersect string1 string2
CD
The intersection can be found between bitsets:
all-chars: "ABCDEFGHI"
charset1: charset "ABCDEF"
charset2: charset "DEFGHI"
charset3: intersect charset1 charset2
print find charset3 "E"
true
print find charset3 "B"
false

Series
Series as Data Sets
The /case refinement allows case-sensitive intersection:
probe intersect/case [Bill bill Bob bob] [Bart bill Bob]
[bill Bob]
Union 0
The union function takes two series and returns a series that contains all the values
from both series, but no duplicates.
Examples:
probe union [Bill Bob Bart] [Bob Ted Fred]
[Bill Bob Bart Ted Fred]

probe union lunch dinner
[ham cheese bread carrot salad rice]
print union [1 3 2 4] [3 5 4 6]
1 3 2 4 5 6
string1: "CBDA" ; A B C D scrambled

print sort union string1 string2
ABCDEF

Series
Series as Data Sets
The union function can also be used on bitsets:
charset1: charset "ABCDEF"

charset2: charset "DEFGHI"
charset3: union charset1 charset2
print find charset3 "C"
true
print find charset3 "G"
true
The /case refinement allows case-sensitive unions:
probe union/case [Bill bill Bob bob] [bill Bob]
[Bill bill Bob bob]

Series
Series as Data Sets
Exclude 0
The exclude function takes two series and returns a series that contains all the
values of the first series, less the values of the second.
probe exclude [1 2 3 4] [1 2 3 5]
[4]
probe exclude [Bill Bob Bart] [Bob Ted Fred]
[Bill Bart]

probe difference/only lunch dinner
[cheese bread]

print sort difference string1 string2
AB
The /case refinement allows case-sensitive exclusion:
probe exclude/case [Bill bill Bob bob] [

Bart bart bill Bob]
[Bill bob]
Difference 0
The difference function takes two series and returns a series that contains all of the
values not in common with both series.

Series
Series as Data Sets
Examples:
probe difference [1 2 3 4] [1 2 3 5]
[4 5]
probe difference [Bill Bob Bart] [Bob Ted Fred]
[Bill Bart Ted Fred]

probe difference lunch dinner
[cheese bread salad rice]

print sort difference string1 string2
ABEF
The /case refinement allows case-sensitive differences.
probe difference/case [Bill bill Bob bob] [

Bart bart bill Bob]
[Bill bob Bart bart]

Series
Multiple Series Variables
Multiple Series Variables E
Multiple variables can refer to the same series. For instance:
data: [1 2 3 4 5]
start: find data 3
end: find start 4
print first start
print first end
Both the start and end variables refer to the series. They have different positions,
but the series they reference is the same.
1 2 3 4 5
start end
If an insert or remove function is performed on a series, the values in the series will
shift and the start and end variables may no longer refer to the same values. For
instance, if a value is removed from the series at the start position:
remove start
print first start
print first end

Series
Modification Refinements
The series has shifted to the left and the variables now refer to different values.
1 3 4 5
start end
Notice that the index positions of the variables have not changed, but the values in
the series have changed. The same situation would occur when using insert.
Sometimes this side effect will work to your advantage. Sometimes it will not, and
you will need to correct for it in your code.
Modification Refinements E
The change, insert, and remove functions can take additional refinements to
modify their operation.
Part 0
The /part refinement accepts a count or a position in the series and uses it to limit
the effect of the function.
For example, using the following series:
str: "abcdef"
blk: [1 2 3 4 5 6]

Series
you can change part of str and blk using change/part:
change/part str [1 2 3 4] 3
probe str
1234def
change/part blk "abcd" 3

probe blk
["abcd" 4 5 6]
You can insert part of a series into the tail of str and blk using insert/part.
insert/part tail str "-ghijkl" 4

probe str
1234def-ghi
insert/part tail blk ["--" 7 8 9 10 11 12] 4

probe blk
["abcd" 4 5 6 "--" 7 8 9]
To remove part of the str and blk series, use remove/part. Note how find is used
to obtain the series position:
remove/part (find str "d") (find str "-")

probe str
1234-ghi
remove/part (find blk 4) (find blk "--")

probe blk
["abcd" "--" 7 8 9]

Series
Only 0
The /only refinement changes or inserts a block as a block, rather than its
individual values.
Examples:
blk: [1 2 3 4 5 6]
You can replace the 2 in blk with the block [a b c] and insert the block [$1 $2
$3] at the position of the 5.
change/only (find blk 2) [a b c]

probe blk
[1 [a b c] 3 4 5 6]
insert/only (find blk 5) [$1 $2 $3]

probe blk
[1 [a b c] 3 4 [$1.00 $2.00 $3.00] 5 6]
Dup 0
The /dup refinement changes or inserts a value a specified number of times.
Examples:
str: "abcdefghi"
blk: [1 2 3 4 5 6]

Series
You can change the first four values in a string or block series to an asterisk(*)
with:
change/dup str "*" 4

probe str
****efghi
change/dup blk "*" 4

probe blk
["*" "*" "*" "*" 5 6]
To insert a dash (-) four times before the last value in a string or block:
insert/dup (back tail str) #"-" 4

probe str
****efgh----i
insert/dup (back tail blk) #"-" 4

probe blk
["*" "*" "*" "*" 5 #"-" #"-" #"-" #"-" 6]

6
Block Series
This chapter explores the block series type in more detail. It includes the following
information:
■ “Blocks of Blocks” on page 6-2

■ “Paths for Nested Blocks” on page 6-3
■ “Arrays” on page 6-6
■ “Composing Blocks” on page 6-9
6- 1
Block Series
Blocks of Blocks
Blocks of Blocks F
When a block appears as a value within another block, it counts as a single value
regardless of how many values it contains. For example:
values: [
"new" [1 2]
%file1.txt ["one" ["two" %file2.txt]]
]
probe values
["new" [1 2] %file1.txt ["one" ["two" %file2.txt]]]
The length? of values is four. The second and fourth values are counted as single
values:
print length? values
The block values within the values block can be used as a block as well. In the
following examples, second is used to extract the second value from values.
To print the block, type:
probe second values
[1 2]
To get the length of the block, type:
print length? second values
To print the data type of the block, type:
print type? second values
block

Block Series
Paths for Nested Blocks
In the same way, series operations can be performed on other types of series values
in blocks. In the following examples, pick is used to extract %file1.txt from
values.
To look at the value, type:
probe pick values 3
%file1.txt
To get the length of the value:
print length? pick values 3
to see the data type of the value:
print type? pick values 3
file
Paths for Nested Blocks F
The path notation is useful for nested blocks.
The fourth value in values is a block containing another block. The following
examples use a path to get information about this value.
To look at nested values, type:
probe values/4
["one" ["two" %file2.txt]]
probe values/4/2
["two" %file2.txt]

Block Series
To get the lengths of nested values, type:
print length? values/4
print length? values/4/2
To see what the data type of a nested value, type:
print type? values/4
block
print type? values/4/2
block
The two series values in the fourth value’s block can also be accessed.
To look at the values, type:
probe values/4/2/1
two
probe values/4/2/2
%file2.txt

Block Series
To get the lengths of the values:
print length? values/4/2/1
print length? values/4/2/2
To see what data type the values are:
print type? values/4/2/1
string
print type? values/4/2/2
file
To modify the values:
change (next values/4/2/1) "o"

probe values/4/2/1
too
change/part (next find values/4/2/2 ".") "r" 3

probe values/4/2/2
%file2.r
The above examples illustrate REBOL’s ability to operate on values nested inside
blocks. Note that in the last series of examples, change is used to modify a string
and file series three layers deep in values. Printing out the values block
produces:
probe values
["new" [1 2] %file1.txt ["one" ["too" %file2.r]]]

Block Series
Arrays
Arrays F
Blocks are used for arrays.
An example of a statically defined two dimensional array is:
arr: [
[1 2 3 ]
[a b c ]
[$10 $20 $30]
]
You can obtain the values of an array with the series extraction functions:
probe first arr
[1 2 3]
probe pick arr 3
[$10.00 $20.00 $30.00]
probe first first arr
You can also use paths to obtain values from the array:
probe arr/1
[1 2 3]
probe arr/3
[$10.00 $20.00 $30.00]
probe arr/3/2
$20.00

Block Series
Arrays
Paths can also be used to change the values in an array:
arr/1/2: 20
probe arr/1
[1 20 3]
arr/3/2: arr/3/1 + arr/3/3

probe arr/3/2
$40.00
Creating Arrays 0
The array function creates arrays dynamically. The function takes an argument that
is either an integer or a block of integers and returns a block that is the array. By
default, the cells of an array are initialized to none. To initialize array cells to some
other value, use the /initial refinement explained in the next section.
When array is supplied with a single integer, a one-dimensional array of that size
is returned:
arr: array 5
probe arr
[none none none none none]
When a block of integers is provided, the array has multiple dimensions. Each
integer provides the size of the corresponding dimension.
Here is an example of a two dimensional array that has six cells, two rows of three
columns:
arr: array [2 3]
probe arr
[[none none none] [none none none]]

Block Series
Arrays
This can be made into a three dimensional array by adding another integer to the
block:
arr: array [2 3 2]
foreach lst arr [probe lst]
[[none none] [none none] [none none]]

[[none none] [none none] [none none]]
The block of integers that is passed to array can be as big as your memory will
support.

Block Series
Composing Blocks
Initial Values 0
To initialize the cells of an array to a value other than none, use the /initial
refinement. This refinement takes one argument: the initial value. Here are some
examples:
arr: array/initial 5 0
probe arr
[0 0 0 0 0]
arr: array/initial [2 3] 0
probe arr
[[0 0 0] [0 0 0]]
arr: array/initial 3 "a"

probe arr
["a" "a" "a"]
arr: array/initial [3 2] ’word

probe arr
[[word word] [word word] [word word]]
arr: array/initial [3 2 1] 11:11

probe arr
[[[11:11] [11:11]] [[11:11] [11:11]] [[11:11] [11:11]]]
Composing Blocks F
The compose function is handy for creating blocks from dynamic values. It can be
used for creating both data and code.

Block Series
Composing Blocks
The compose function takes a block as an argument and returns a block that has
each value in the argument block. Values in parentheses are evaluated before the
block is returned. For example:
probe compose [1 2 (3 + 4)]
[1 2 7]
probe compose ["The time is" (now/time)]
["The time is" 10:32:45]
If the values in parentheses return a block, that block’s individual values are used:
probe compose [a b ([c d])]
[a b c d]
To prevent this, you need to enclose the result in an extra block:
probe compose [a b ([[c d]])]
[a b [c d]]
An empty block inserts nothing:
probe compose [a b ([]) c d]
[a b c d]
When compose is given a block that contains sub-blocks, the sub-blocks are not
evaluated, even if they contain parentheses:
probe compose [a b [c (d e)]]
[a b [c (d e)]]

Block Series
Composing Blocks
If you would like the sub-blocks to be evaluated, use the /deep refinement. The
/deep refinement causes all parentheses to be evaluated, regardless of where they
are:
probe compose/deep [a b [c (d e)]]
[a b [c d e]]

Block Series
Composing Blocks

7
String Series
This chapter describes the string series type and its use in REBOL/Core. It includes
the following information:
■ “String Functions” on page 7-2

■ “Converting Values to Strings” on page 7-4
7- 1
String Series
String Functions
String Functions G
There are a wide variety of functions that operate on or produce strings. Functions
are available for modifying strings, searching strings, compressing and
decompressing strings, changing the spacing of strings, parsing strings, and
converting strings. These functions operate on all string related datatypes, such as
string!, binary!, tag!, file!, URL!, email!, and issue!.
The string creation, modification and search functions are covered in the “Series”
chapter. They include the items listed in Table 7-1.
Table 7-1. String Functions
Copy copy all or part of a string

Make allocate storage for a string
Insert insert a character or substring into another string
Remove remove one or more characters from a string
Change change one or more characters in a string
Append insert a character or substring at the tail of a string
Find find or match a character or string in another string
Replace find a string and replace it with another string
In addition, the series traversing functions like next, back, head, and tail were
covered. They are used to reposition in strings. In addition, the series test functions
allow you to determine your position within a string.

String Series
String Functions
This chapter will introduce functions that convert REBOL values into strings. These
functions are used often, and they are also used by the print and probe functions.
They include:
Table 7-2. String Conversion Functions
form convert values with spaces and in human readable format

mold convert values in REBOL readable format
join convert values with no spaces
reform reduces values before forming them
remold reduces values before molding them
rejoin reduces values before joining them
This chapter will also describes these string functions:

Table 7-3. Other String Functions
detab replace tabs with spaces

entab replace spaces with tabs
trim remove white space or lines around strings
uppercase convert string to uppercase
lowercase convert string to lowercase
checksum compute a checksum for string
compress compress string
decompress decompress string
enbase convert a string to base value

String Series
Converting Values to Strings
Table 7-3. Other String Functions
debase convert an enbased string to a string

dehex convert hexadecimal ASCII values to characters
Converting Values to Strings G
Join 0
The join function takes two arguments and concatenates them into a single series.
The data type of series returned is based on the value of the first argument. When
the first argument is a series value, that series type is returned.
str: "abc"
file: %file
url: http://www.rebol.com/
probe join str [1 2 3]
abc123
probe join file ".txt"
%file.txt
probe join url %index.html
http://www.rebol.com/index.html

String Series
When the first argument is not a series, the join converts it to a string first, then
performs the append:
print join $11 " dollars"
$11.00 dollars
print join 9:11:01 " elapsed"
9:11:01 elapsed
print join now/date " -- today"
30-Jun-2000 -- today
print join 255.255.255.0 " netmask"
255.255.255.0 netmask
print join 412.452 " light-years away"
412.452 light-years away

String Series
When the second argument to join is a block, the values of that block are evaluated
and appended to the series returned.
print join "a" ["b" "c" 1 2]
abc12
print join %/ [%dir1/ %sub-dir/ %filename ".txt"]
%/dir1/sub-dir/filename.txt
print join 11:09:11 ["AM" " on " now/date]
11:09:11AM on 30-Jun-2000
print join 312.423 [123 987 234]
312.423123987234
Rejoin 0
The rejoin function is identical to join, except that it takes one argument, a block.
print rejoin ["try" 1 2 3]
try123
print rejoin ["h" ’e #"l" (to-char 108) "o"]
hello

String Series
Form 0
The form function converts a value to a string:
print form $1.50
$1.50
print type? $1.50
money
print type? form $1.50
string
The following example uses form to find a number by its decimal value:
blk: [11.22 44.11 11.33 11.11]

foreach num blk [if find form num ".11" [print num]]
44.11
11.11
When form is used on a block, all values in the block are converted to string values
with spaces between each value:
print form [11.22 44.11 11.33]
11.22 44.11 11.33

String Series
The form function does not evaluate the values of a block. This results in words
being converted to string values:
print form [a block of undefined words]
a block of undefined words
print form [33.44 num "-- unevaluated string:" str]
33.44 num -- unevaluated string: str
Reform 0
The reform function is like form, except that blocks are reduced before being
converted.
str1: "Today’s date is:"

str2: "The time is now:"
print reform [str1 now/date newline str2 now/time]
Today’s date is: 30-Jun-2000

The time is now: 14:41:44
The print function is based on the reform function.

String Series
Mold 0
The mold function converts a value to a string that is usable by REBOL. Strings
created with mold can be converted back to values with the load function.
blk: [[11 * 4] ($15 - $3.89) "eleven dollars"]

probe blk
[[11 * 4] ($15.00 - $3.89) "eleven dollars"]
molded-blk: mold blk

probe molded-blk
{[[11 * 4] ($15.00 - $3.89) "eleven dollars"]}
print type? blk
block
print type? molded-blk
string
probe first blk
[11 * 4]
probe first molded-blk
#"["

String Series
The strings returned from mold can be loaded by REBOL:
new-blk: load molded-blk

probe new-blk
[[11 * 4] ($15.00 - $3.89) "eleven dollars"]
print type? new-blk
block
probe first new-blk
[11 * 4]
The mold function does not evaluate the values of a block.
money: $11.11
sub-blk: [inside another block mold this is unevaluated]
probe mold [$22.22 money "-- unevaluated block:" sub-blk]
{[$22.22 money "-- unevaluated block:" sub-blk]}
probe mold [a block of undefined words]
[a block of undefined words]
Remold 0
The remold function works just like mold, except that blocks are reduced before
being converted.
str1: "Today’s date is:"

probe remold [str1 now/date]
{["Today’s date is:" 30-Jun-2000]}

String Series
String Spacing Functions 0
Trim
The trim function removes extra spaces from a string.
The default operation of trim is to remove extra spaces from the head and tail of a
string:
str: " line of text with spaces around it "

print trim str
line of text with spaces around it
Note that the string is modified in the process:
print str
To trim a copy of the string, write:
print trim copy str
Trim includes a number of refinements to specify where space is to be removed from

a string:
/head – removes space from the head of the string
/tail – removes space from the tail of the string
/auto – removes space from each line, relative to the first line
/lines – removes newlines, replacing them with spaces
/all -- removes all whitespace
/with – removes all specified characters

String Series
Use the /head and /tail refinements to trim from either end of a string:
probe trim/head copy str
probe trim/tail copy str
Use the /auto refinement to trim leading spaces from multiple lines leaving
indented spaces intact:
str: {
indent text
indent text
indent text
indent text
indent text
}
print str
indent text
indent text
indent text
indent text
indent text
probe trim/auto copy str
{indent text
indent text
indent text
indent text
indent text
}

String Series
Use /lines to trim the head and tail and also convert newlines into spaces:
probe trim/lines copy str
{indent text indent text indent text indent text indent

text}
Use /all to remove all whitespace:
probe trim/all copy str
indenttextindenttextindenttextindenttextindenttext
The /with refinement will remove all characters that you specify. In the following
example, spaces, line breaks and the characters e and t are removed:
probe trim/with copy str " ^/et"
indnxindnxindnxindnxindnx
Detab and Entab

The detab and entab will convert tabs to spaces and spaces to tabs.
str:
{^(tab)line one
^(tab)^(tab)line two
^(tab)^(tab)^(tab)line three
^(tab)line^(tab)full^(tab)of^(tab)tabs}
print str
line one
line two
line three
line full of tabs

String Series
By default, the detab function converts tabs to four spaces (the REBOL standard
spacing). All tabs in the string will be converted to spaces, regardless of where they
are located.
probe detab str
{ line one
line two
line three
line full of tabs}
Note that the detab and entab functions affect the string that is provided as an
argument. To change a copy of the source string, use the copy function.
The entab function converts spaces to tabs. Every four spaces will be converted to
a single tab. Only spaces at the beginning of a line will be converted to tabs.
probe entab str
{^-line one
^-^-line two
^-^-^-line three
^-line full of tabs}
You can use the /size refinement to specify the size of tabs. For instance, if you
want to convert each tab to eight spaces, or convert every eight spaces to a tab, you
can use this example:
probe detab/size str 8

{ line one
line two
line three
line full of tabs}
probe entab/size str 8
{^- line one

^-^-^-line two
^-^-^-^- line three
^- line full of tabs}

String Series
Uppercase and Lowercase 0
There are two functions for changing character casing: uppercase and lowercase.
The uppercase function takes a string argument and converts its characters to
uppercase:
print uppercase "SamPle TExT, tO test CASES"
SAMPLE TEXT, TO TEST CASES
The lowercase function converts characters to lowercase:
print lowercase "Sample TEXT, tO teST Cases"
sample text, to test cases
To convert only a portion of a string, use the /part refinement:
print upppercase/part "ukiah" 1
Ukiah
Checksum 0
The checksum returns the checksum of the string value. There are three types of
checksum that can be computed:
CRC – 24 bit circular redundancy checksum
TCP – standard Internet 16 bit checksum
Secure – a cryptographically secure checksum

String Series
By default, the CRC checksum is computed:
print checksum "hello"
52719
print checksum (read http://www.rebol.com/)
356358
To compute a TCP 16-bit checksum, use the /tcp refinement:
print checksum/tcp "hello"
10943
A secure checksum will return a binary value, not an integer. Use the /secure
refinement to compute a secure checksum:
print checksum/secure "hello"
#{AAF4C61DDCC5E8A2DABEDE0F3B482CD9AEA9434D}

String Series
Compression and Decompression 0
The compress function will compress a string and return a binary datatype. In the
following example, a small file is compressed by reading its contents, compressing
them, then writing it back to disk:
Str:
{I wanted the gold, and I sought it,

I scrabbled and mucked like a slave.
Was it famine or scurvy -- I fought it;
I hurled my youth into a grave.
I wanted the gold, and I got it --
Came out with a fortune last fall, --
Yet somehow life’s not what I thought it,
And somehow the gold isn’t all.}
print [size? str "bytes"]
306 bytes
bin: compress str
print [size? bin "bytes"]
156 bytes
Note that the result of the compression is a binary data type.

String Series
The decompress function decompresses a previously compressed string.
print decompress bin
I wanted the gold, and I sought it,

And somehow the gold isn’t all.
NOTE: Always keep an uncompressed backup of compressed data. If you lose only
one byte from a compressed binary, it can be difficult to recover the data. Do not
store file archives in a compressed format unless you have copies that are not
compressed.
Number Base Conversion 0
To be sent as text, binary strings must be converted to hexadecimal or base64

encoding. This is often done for email and newsgroup content.
The enbase function will encode a binary string:
line: "No! There’s a land!"

print enbase line
Tm8hIFRoZXJlJ3MgYSBsYW5kIQ==

String Series
Encoded strings can be decoded with the debase function. Note that the result is a
binary value. To convert it back to a string, use the to-string function.
b-line: debase e-line

print type? b-line
binary
probe b-line
#{4E6F2120546865726527732061206C616E6421}
print to-string b-line
No! There’s a land!
The /base refinement may be used with enbase and debase to specify a base2
(binary), base16 (hexadecimal), or base64 encoding.
Here are some examples using base2:
e2-str: enbase/base str 2

print e2-str
01100001
b2-str: debase/base e2-str 2

print type? b2-str
binary
probe b2-str
#{61}
print to-string b2-str

String Series
Here are some examples using base16:
e16-line: enbase/base line 16

print e16-line
4E6F2120546865726527732061206C616E6421
b16-line: debase/base e16-line 16

print type? b16-line
binary
probe b16-line
#{4E6F2120546865726527732061206C616E6421}
print to-string b16-line
No! There’s a land!
Internet Hexadecimal Decoding 0
The dehex function converts Internet URL and CGI style hexadecimal encoded
characters to strings. Hexadecimal ASCII representations appear in a URL or CGI
string as %xx, where xx is the hexadecimal value.
str: "there%20seem%20to%20be%20no%20spaces"
print dehex str
there seem to be no spaces
print dehex "%68%65%6C%6C%6F"
hello

8
Functions
This chapter introduces the use of functions in REBOL. It includes the following
information:

■ “Evaluating Functions” on page 8-3
■ “Defining Functions” on page 8-10
■ “Nested Functions” on page 8-23

■ “Unnamed Functions” on page 8-24
■ “Conditional Functions” on page 8-25
■ “Function Attributes” on page 8-26

■ “Forward References” on page 8-29
■ “Scope of Variables” on page 8-29
■ “Reflective Properties” on page 8-31

■ “Online Function Help” on page 8-33
■ “Viewing Source Code” on page 8-35
8- 1
Functions
Overview
Overview H
There are several kinds of functions provided by REBOL:

Table 8-1. Function Types in REBOL
Function Type Description
Native A function that is evaluated directly by the processor. These are

the lowest level functions of the language.
Operator A function that is used as an infix operator. Examples are +, -, *
and /.
Function A higher level function that is defined by a block and is evaluated
by evaluating the functions within the block. Also called
user-defined functions.
Mezzanine A name for higher level functions that are a standard part of the
language. These are not native functions.
Routine A function that is used to call external library functions (only
available in REBOL/Command).

Functions
Evaluating Functions
Evaluating Functions H
The “Expressions” Chapter covered the general details of evaluation. The way
function arguments are evaluated dictates the general order of words and values in
the language. This section goes into more detail on how functions are evaluated.
Arguments 0
Functions receive arguments and return results. Most functions require one or more
arguments; although, some functions, such as now (current date and time), do not
require any arguments.
The arguments that are supplied to a function are processed by the interpreter and
then passed to the function. Arguments are processed in the same way, regardless
of the type of function called, be it a native function, operator, user-defined
function, or otherwise. For example, the send function expects two arguments:
friend: [email protected]
message: "message in a bottle"
send friend message
The word friend is first evaluated and its value ([email protected]) is

provided as the first argument to send. Next, the word message is evaluated, and
its value becomes the second argument. Think of the values of the friend and
message variables as being substituted into the line before send is done:
send [email protected] "message in a bottle"
If you provide too few arguments to a function, an error message is returned. For
example, the send function expects two arguments and if you send one, an error is
returned
send friend
** Script Error: send is missing its message argument.

** Where: send friend

Functions
If too many arguments are provided, the extra values are ignored.
send friend message "urgent"
In the previous example, send already has two arguments, so the string, which is
the third argument, is ignored. Notice that no error message occurs. In this case,
there were no functions expecting the third argument. However, in some cases the
third argument may belong to another function that was evaluated before send.
Arguments to a function are evaluated from left to right. This order is followed even
when the arguments themselves are functions. For example, if you write:
send friend detab copy message
the second argument must be computed by evaluating the detab function and the
copy function. The result of the copy will be passed to detab, and the result of
detab will be passed to send. In the previous example, the copy function is taking
a single argument, the message, and returns a copy of it. The copied message is
passed to the detab function, which removes the tab characters and returns the
detabbed message, which is passed to the send function. Notice how the results of
functions flow from right to left as the expression is evaluated.
The evaluation that is happening here can be shown by using parentheses to clarify
what is evaluated first. (However, the parentheses are not required, and actually
slow down the evaluation slightly.)
send friend (detab (copy message))
The cascading effect of results passed to functions is quite useful. Here is an

example that uses insert twice within the same expression:
file: %image
insert tail insert file %graphics/ %.jpg
print file
graphics/image.jpg

Functions
In the following example, a directory name and a suffix are added to the base file
name. Parentheses can be used to clarify the order of evaluation:
insert (tail (insert file %graphics/)) %.jpg
NOTE: Parentheses make good “training wheels” to get started in writing REBOL.
However, it won’t take long before you can shed this aid and write the expressions
directly without the parentheses. Not using parentheses lets the interpreter
evaluate expressions quicker.
Argument Data Types 0
Functions usually require arguments of a specific data type. For example, the first
argument to the send function can only be an email address or block of email
addresses. Any other type of value will produce an error:
send 1234 "numbers"
** Script Error: send expected address argument of type:

email block.
** Where: send 1234 "numbers"
In the previous example, the error message is telling you that the address argument
of the send function needs to be either an email address or a block.

Functions
A quick way to find out what types of arguments are accepted by a function is to
type the following at the console prompt:
help send
USAGE:
SEND address message /only /header header-obj
DESCRIPTION:
Send a message to an address (or block of
addresses)
SEND is a function value.
ARGUMENTS:
address -- An address or block of addresses
(Type: email block)
message -- Text of message. First line is subject.
(Type: any)
REFINEMENTS:
/only -- Send only one message to multiple addresses
/header -- Supply your own custom header
header-obj -- The header to use (Type: object)
The ARGUMENTS section indicates the data type of each argument. Notice that the
second argument can be of any data type. So, it is valid to write:
send [email protected] $1000.00

Functions
Refinements 0
A refinement specifies a variation in the normal evaluation of a function.

Refinements also allow optional arguments to be provided. Refinements are
available for both native and user-defined functions.
Refinements are specified by following the function name with a forward slash (/)
and a refinement name. For instance:
copy/part (copy just part of a string)
find/tail (return the tail of the match)
load/markup (return XML/HTML tags and strings)
Functions can also include multiple refinements:
find/case/tail (match case and return tail)
insert/only/dup (insert entire block multiple times)
You have seen the copy function used to make a copy of a string. By default, copy
returns a copy of its argument:
string: "no time like the present"

print copy string
no time like the present
Using the /part refinement, copy returns part of the string:
print copy/part string 7
no time
In the previous example, the /part refinement specifies that only seven characters
of the string are copied.

Functions
To review what refinements are allowed on a function such as copy, use online help:
help copy
USAGE:
COPY value /part range /deep
DESCRIPTION:
Returns a copy of a value.
COPY is an action value.
ARGUMENTS:
value -- Usually a series
(Type: series port bitset)
REFINEMENTS:
/part -- Limits to a given length or position.
range -- (Type: number series port)
/deep -- Also copies series values within the block.
Notice that the /part refinement requires an additional argument. Not all
refinements require additional arguments. For example, the /deep refinement
specifies that copy make copies of all its sub-blocks. No other arguments are
required.
When multiple refinements are used with a function, the order of the extra
arguments is determined by the order in which the refinements are specified. For
example:
str: "test"
insert/dup/part str "this one" 4 5
print str
this this this this test

Functions
Reversing the order of the /dup and /part refinement changes the order of the
arguments. You can see the difference:
str: "test"
insert/part/dup str "this one" 4 5
print str
thisthisthisthisthistest
The refinements indicate the order of the arguments.
Function Values 0
The previous examples describe how functions return values when they are
evaluated. Sometimes, however, you want to obtain the function as a value, not the
value it returns. This can be done by preceding the function name with a colon or
using the get function. For example, to set a word, pr, to the print function, you
would write:
pr: :print
You could also write:
pr: get ‘print
Now pr is equivalent to the print function:
pr "this is a test"
this is a test

Functions
Defining Functions
Defining Functions H
You can define functions that work in the same way as native functions. These are
called user-defined functions. User-defined functions are of the function! data type.
You can make simple functions that require no arguments with the does function.
This example defines a new function that prints the current time:
print-time: does [print now/time]

print-time
10:30
The does function returns a value, which is the new function. In the example, the
print-time word is set to the function. However, this function value can be set
to a word, passed to another function, returned as the result of a function, saved in
a block, or immediately evaluated.
Functions that require arguments are made with the func function, which accepts
two arguments:
func spec body
The first argument is a block that specifies the interface to the function. It includes
a description of the function, its arguments, the types allowed for arguments,
descriptions of the arguments, and other items. The second argument is a block of
code that is evaluated whenever the function is evaluated.
Here is an example of a new function called sum:
sum: func [arg1 arg2] [arg1 + arg2]
The newly defined function accepts two arguments, as specified in the first block.
The second block is the body of the function, which, when evaluated, adds the two
arguments together. The new function is returned as a value from func and the sum
word is set to it. Here it is in use:
print sum 123 321
444

Functions
Defining Functions
The result of arg1 being added to arg2 is returned and printed.
NOTE: Func is a function that makes other functions. It performs a make on the
function! data type. Func is defined as:
func: make function! [args body] [

make function! args body
]
Interface Specifications 0
The first block of a function definition is called its interface specification. This block
includes a description of the function, its arguments, the data types allowed for
arguments, descriptions of the arguments, and other items.
The interface specification is a dialect of REBOL (because it has different evaluation

rules than normal code). The specification block has the format:
[
"function description"
[optional attributes]
argument-1 [optional type]
"argument description"
argument-2 [optional type]
"argument description"
...
/refinement
"refinement description"
refinement-arg-1 [optional type]
"refinement argument description”
...
]

Functions
Defining Functions
The fields of the specification block are:

Table 8-2. Specification Block Fields
Field Description
Description A short description of the function. This is a string that can be

accessed by other functions such as help to output descriptions
of functions.
Attributes A block that describes special properties of the function, such as
its behavior on errors. It may be expanded in the future to
include flags for optimizations.
Argument A variable that is used to access an argument from within the
body of the function.
Arg Type A block that identifies the data types that are accepted by the
function. If a data type not identified in this block is passed to
the function, an error will occur.
Arg A short description of the argument. Like the function
Description description, this can be accessed by other functions such as help.
Refinement A refinement word that indicates special behavior is required of
the function.
Refinement A short description of the refinement.
Description
Refinement A variable that is used by the refinement.
Argument
Refinement A block that identifies the data types that are accepted by the
Argument refinement.
Type
Refinement A short description of the refinement argument.
Argument
Description
All of these fields are optional.
As an example, the argument block of the sum function (defined in a previous

Functions
Defining Functions
example) is expanded to restrict the type of arguments accepted. It also includes a

description of the function and its expected arguments.
sum: func [
"Return the sum of two numbers."
arg1 [number!] "first number"
arg2 [number!] "second number"
][
arg1 + arg2
]
Now, the data type of the arguments is automatically checked, catching errors like:
print sum 1 "test"

** Script Error: sum expected arg2 argument of type:
number.
** Where: print sum 1 "test"
To allow additional argument data types, more than one can be given:
sum: func [
arg1 [number! tuple! money!] "first number"
arg2 [number! tuple! money!] "second number"
][
arg1 + arg2
]
print sum 1.2.3 3.2.1
4.4.4
print sum $1234 100
$1334.00

Functions
Defining Functions
Now the sum function accepts a number, tuple, or monetary value as arguments.
If within the function you need to distinguish what data type was passed, you can
use the data type test functions:
if tuple? arg1 [print arg1]
if money? arg2 [print arg2]
Because the sum function provided description strings, the help function now
supplies useful information about it:
help sum
USAGE:
SUM arg1 arg2
DESCRIPTION:
Return the sum of two numbers.
SUM is a function value.
ARGUMENTS:
arg1 -- first number (Type: number tuple money)
arg2 -- second number (Type: number tuple money)
Literal Arguments 0
As described earlier, the interpreter evaluates the arguments of functions and passes
them to the function body. However, there are times when you do not want
function arguments evaluated. For instance, if you need to pass a word and access
it from the function body, you do not want it evaluated as an argument. The help
function, which expects a word, is a good example:
help print
To prevent print from being evaluated, the help function must specify that its
argument should not be evaluated.

Functions
Defining Functions
To specify that an argument not be evaluated, precede the argument name with a
single quote (indicates a literal word). For example:
zap: func [‘var] [set var 0]
test: 10
zap test
print test
10
The var argument is preceded with a single quote, which instructs the interpreter
to obtain the argument without evaluating it first. The argument is passed as the
word. For example:
say: func [‘var] [probe var]

say test
test
The example prints the word that is passed as an argument.
Another example is a function that increments a variable by one and returns its
result (similar to the ++ increment function in C):
++: func [’word] [set word 1 + get word]
count: 0
++ count
print count
print ++ count

Functions
Defining Functions
Get Arguments 0
Function arguments can also specify that a word’s value be fetched but not
evaluated. This is similar to the literal arguments described above, but rather than
passing the word, the value of the word is passed without being evaluated.
To specify that an argument be fetched but not evaluated, precede the argument
name with a colon. For example, the following function accepts functions as
arguments:
print-body: func [:fun] [probe second :fun]
The sample function prints the body of a function that is passed to it. The argument
is preceded by a colon, which indicates that the value of the word should be
obtained, but not further evaluated.
print-body reform
[
form reduce value
]
print-body rejoin
[
block: reduce block
append either series? first block [copy first block]
[form first block]
next block
]

Functions
Defining Functions
Defining Refinements 0
Refinements can be used to specify variation in the normal evaluation of a function

as well as provide optional arguments. Refinements are added to the function
specification block as a word preceded by a forward slash (/).
Within the body of the function, the refinement word is used as a logic value to
determine if the refinement was provided when the function was called.
For example, the following code adds a refinement to the sum function, which was
defined in a previous example:
sum: func [
/average "return the average of the numbers"
][
either average [arg1 + arg2 / 2][arg1 + arg2]
]
The sum function specifies the /average refinement. In the body of the function,
the word is tested with the either function, which returns true when the refinement
is specified.
print sum/average 123 321
222
To specify a refinement that accepts additional arguments, follow the refinement

with the arguments definitions:
sum: func [
/times "multiply the result"
amount [number!] "how many times"
][
either times [arg1 + arg2 * amount][arg1 + arg2]
]

Functions
Defining Functions
The amount is only valid when the times refinement is true. Here is an example:
print sum/times 123 321 10
4440
Do not forget to check the refinement word before using the additional arguments.
If a refinement argument is used without the refinement being specified, it will have
a none value.
Local Variables 0
A local variable is a word whose value is defined within the scope of a function.
Changes to a local variable only affect the function in which the variable is defined.
If the same word is used outside of the function, it will not be affected by the
changes to the local variable of the same name.
Argument variables and refinements are local variables. Their values are defined
within the scope of the function. By convention, additional local variables can be
specified with the /local refinement. The /local refinement is followed by a list of
words that are used as local variables within the function.
average: func [
block "Block of numbers"
/local total length
][
total: 0
length: length? block
foreach num block [total: total + num]
either length > 0 [total / length][0]
]
Here the total and length words are local to the function.

Functions
Defining Functions
Another method of creating local words is to use the function function, which is
identical to func, but accepts a separate block that contains the local words:
average: function [
block "Block of numbers"
][
total length
][
total: 0
length: length? block
foreach num block [total: total + num]
either length > 0 [total / length][0]
]
In this example, notice that the /local refinement is not used with the function
function. The function function creates the refinements for you.
If a local variable is used before its value has been set within the body of its
function, it will have a none value.
Local Variables Containing Series

Local variables that hold series need to be copied if the series is used multiple times.
For example, if you want the stars string to be the same each time you call the
start-name function, you should write:
star-name: func [name] [

stars: copy "**"
insert next stars name
stars
]
Otherwise, if you write:
star-name: func [name] [

stars: "**"
insert next stars name
stars
]

Functions
Defining Functions
you will be using the same string each time and each time the function is used the
pervious name will appear within the result.
print star-name "test"
*test*
print star-name "this"
*thistest*
Returning a Value 0
As you know from the “Expressions” Chapter, blocks return their last value when
they return from evaluation:
do [1 + 3 5 + 7]
12
This is also true for functions. The last value is returned as the value of the function:
sum: func [a b] [
print a
print b
a + b
]
print sum 123 321
123
321
444

Functions
Defining Functions
In addition, the return function can be used to stop the evaluation of a function at
any point and return a value:
find-value: func [series value] [

forall series [
if (first series) = value [
return series
]
]
none
]
probe find-value [1 2 3 4] 3
[3 4]
In the example, if the value is found, the function returns the series at the position
of the match. Otherwise, the function returns none.
To stop a function evaluation without returning a value, use the exit function:
source: func [
"Print the source code for a word"
’word [word!]
][
prin join word ": "
if not value? word [print "undefined" exit]
either any [
native? get word op? get word action? get word
][
print ["native" mold third get word]
][print mold get word]
]

Functions
Defining Functions
Returning Multiple Values 0
To return more than one value from a function, use a block. You can do this easily
by returning a block that has been reduced.
For example:
find-value: func [series value /local count] [

forall series [
if (first series) = value [
reduce [series index? series]
]
]
none
]
The function returns a block that holds the series and the index value where the
value was found.
probe find-value [1 2 3 4] 3
[[3 4] 3]
The reduce is necessary to create a block of values from the block of words that it
is given. Do not return the local variables themselves. That is not a supported mode
of operation (currently).
To easily set variables to the return value of the function, use set:
set [block index] find-value [1 2 3 4] 3

print block
3 4
print index

Functions
Nested Functions
Nested Functions H
Functions can define other functions. The sub-functions can be global, local, or
returned as a result, depending on their purpose.
For example, to create a global function from within a function, assign it to a global
variable:
make-timer: func [code] [

timer: func [time] code
]
make-timer [wait time]
timer 5
To make a local function, assign it to a local variable:
do-timer: func [code delay /local timer] [

timer: func [time] code
timer delay
timer delay
]
do-timer [wait time] 5
The timer function only exists during the period when the do-timer function is
being evaluated.
To return a function as a result:
make-timer: func [code] [

func [time] code
]
timer: make-timer [wait time]
timer 5

Functions
Unnamed Functions
WARNING: You should avoid using variables that are local to the top level function as
an unevaluated part of the nested function. For example:
make-timer: func [code delay] [

timer: func [time] [wait time + delay]
]
In the example, the delay word dynamically belongs to the make-timer

function. This should be avoided, as the delay value will change in
subsequent calls to make-timer.
Unnamed Functions H
Function names are variables. In REBOL, a variable is a variable, regardless of what

it holds. There is nothing special about function variables.
Furthermore, functions do not require names. You can create a function and
immediately evaluate it, store it in a block, pass it as an argument to a function, or
return it as a result from a function. Such functions are unnamed.
Here is an example that creates a block of unnamed functions:
funcs: []
repeat n 10 [
append funcs func [t] compose [t + (n * 100)]
]
print funcs/1 10
110
print funcs/5 10
510

Functions
Conditional Functions
Functions can also be created and passed to other functions. For instance, when you
use sort with your own comparison, you provide a function as an argument:
sort/compare data func [a b] [a > b]
Conditional Functions H
Because functions are created dynamically by evaluation, you can determine how
you want a function created, based on other information.
NOTE: This is a way to provide conditional code creation as is found in some

languages.
For instance, you may want to create a debugging version of a function that prints
additional information:
test-mode: on
timer: either test-mode [

func [delay] [
print "delaying..."
wait delay
print "resuming"
]
][
func [delay] [wait delay]
]

Functions
Function Attributes
Here you will create one of two functions, based on the test-mode you are running.
This can also be written shorter as:
timer: func [delay] either test-mode [

print "delaying..."
wait delay
print "resuming"
][
wait delay
]
Function Attributes H
Function attributes provide control over specific function behaviors, such as the
method a function uses to handle errors or to exit. The attributes are an optional
block of words within the interface specifications.
There are currently two function attributes: catch and throw.
Error messages typically are displayed when they occur within the function. If the
catch attribute is specified, errors that are thrown within the function are caught
automatically by the function. The errors are not displayed within the function but

Functions
Function Attributes
at the point where the function was used. This is useful if you are providing a
function library (mezzanine functions) and don’t want the error to be displayed
within your function, but where it was called:
root: func [[catch] num [number!]] [

if num < 0 [
throw make error! "only positive numbers"
]
square-root num
]
root 4
root -4
**User Error: only positive numbers

**Where: root -4
Notice that in this example, the error occurs where root was called even though
the actual error was generated in the body of the function. This is because the catch
attribute was used.
Without the catch attribute, the error would occur within the root function:
root: func [num [number!]] [

square-root num
]
root –4
** Math Error: Positive number required.

** Where: square-root num
The user may not know anything about the internals of the root function. So the
error message would be confusing. The user only knows about root, but the error
was in square-root.

Functions
Function Attributes
Do not get the catch attribute mixed up with the catch function. Although they are
similar, the catch function can be applied to any block that is evaluated. [!See the
Expressions chapter].
The throw attribute allows you to write your own control functions, such as for,
foreach, if, loop, and forever, by allowing your functions to pass the return and
exit operations. For example, this loop function:
loop-time: func [time block] [

while [now/time < time] block
]
evaluates a block until a specific time has been reached or passed. This loop can
then be used within a function:
do-job: func [job][

loop-time 10:30 [
if error? try [page: read http://www.rebol.com]
[return none]
]
page
]
Now, what happens when the [return none] block is evaluated? Because this
block is evaluated by the loop-time function, the return occurs in that function,
not in do-job.
This can be prevented with the throw attribute:
loop-time: func [[throw] time block] [

while [now/time < time] block
]
The throw attribute causes a return or exit that has occurred within the block to
be thrown up to the previous level, which is the next function causing do-job to
return.

Functions
Forward References
Forward References H
Sometimes a script needs to refer to a function before it has been defined. This can
be done as long as the variable for the function is not evaluated before it is defined.
buy: func [item] [

append own item
sell head item ; appears before it is defined
]
sell: func [item] [

remove find own item
]
Scope of Variables H
The context of variables is called their scope. The broad scope of variables is that
of global and local. REBOL uses a form of static scoping, which is called
definitional scoping. The scope of a variable is determined when its context is
defined. In the case of a function, it is determined by when the function is defined.

Functions
Scope of Variables
All of the local variables defined within a function are scoped relative to that
function. Nested functions and objects are able to access their parent’s words.
a-func: func [a] [

print ["a:" a]
b-func: func [b] [
print ["b:" b]
print ["a:" a]
print a + b
]
b-func 10
]
a-func 11
a: 11
b: 10
a: 11
21
Note here that the b-func has access to the a-func variable.
Words that are bound outside of a function maintain those bindings even when
evaluated within a function. This is the result of static scoping, and it allows you
to write your own block evaluation functions (like if, while, loop).
For example, here is a signed if function that evaluates one of three blocks based on
the sign of a conditional value:
ifs: func [
"If positive do block 1, zero do block 2, minus do 3"
condition block1 block2 block3
][
if positive? condition [return do block1]
if negative? condition [return do block3]
return do block2
]
print ifs 12:00 - now/time ["morning"]["noon"]["night"]
night

Functions
Reflective Properties
The blocks passed may contain the same words used within the ifs function
without interfering with the words defined local to the function. This is because the
words passed to the function are not bound to the function.
The next example passes the words block1, block2 and block3 to ifs as
pre-defined words. The ifs function does not get confused between the words
passed as arguments and the words of the same name defined locally:
block1: "morning right now"

block2: "just turned noon"
block3: "evening time"
print ifs (12:00 - now/time) [block1][block2][block3]
evening time
Reflective Properties H
The specification of all functions can be obtained and manipulated during run-time.
For example, you can print the specification block for a function with:
probe third :if
[
"If condition is TRUE, evaluates the block."
condition
then-block [block!]
/else "If not true, evaluate this block"
else-block [block!]
]

Functions
The body code of functions can be obtained with:
probe second :append
[
head either only [insert/only tail series :value
] [
insert tail series :value
]
]
Functions can be dynamically queried during evaluation. This is how the help and
source functions work and how errors messages are formatted.
In addition, this feature is useful for creating your own unique versions of existing
functions. For example, a user-defined print function can be created that has exactly
the same specification as print, but sends its output to a string rather than the
display:
output: make string! 1000
print-str: func third :print [

repend output [reform :value newline]
]
The name of the argument used for print-str is obtained from the interface
specification for print. You can examine that specification with:
probe third :print
[
"Outputs a value followed by a line break."
value "The value to print"
]

Functions
Online Function Help
Online Function Help H
Useful information about all functions of the system can be retrieved with the help
function:
help send
USAGE:
SEND address message /only /header header-obj
DESCRIPTION:
Send a message to an address (or block of
addresses)
SEND is a function value.
ARGUMENTS:
address -- An address or block of addresses
(Type: email block)
message -- Text of message. First line is subject.
(Type: any)
REFINEMENTS:
/only -- Send only one message to multiple addresses
/header -- Supply your own custom header
header-obj -- The header to use (Type: object)
All of this information comes from the definition of the function. Help can be
obtained for all types of functions, not just natives or built-in functions. The help
function can also be used for user-defined functions. The documentation that is
displayed about a function is provided when the function is defined.

Functions
Online Function Help
You can also search for help on functions that contain various patterns. For
instance, at the command prompt, you could type
Help "path"
Found these words:
lit-path! (datatype)
lit-path? (action)
path! (datatype)
path? (action)
set-path! (datatype)
set-path? (action)
split-path (function)
to-lit-path (function)
to-path (function)
to-set-path (function)
to display all the words that contain the string path.
To view a list of all functions available in REBOL, type what at the command
prompt.

Functions
Viewing Source Code
Viewing Source Code H
Another technique for learning about REBOL and for saving time in writing your
own function is to look at how many of the REBOL mezzanine functions are
defined. You can use the source function to do this.
source source
source: func [
"Prints the source code for a word."
'word [word!]
][
prin join word ": "
if not value? word [print "undefined" exit]
either any [native? get word op?
get word action? get word] [
print ["native" mold third get word]
] [print mold get word]
]
Here the source function is used to print its own source code.
Note that you cannot see the source code for native functions because they exist
only as machine code.

Functions
Viewing Source Code

9
Objects
This chapter introduces the use of objects in REBOL. It includes the following
information:

■ “Making Objects” on page 9-2
■ “Accessing Objects” on page 9-6
■ “Object Functions” on page 9-7

■ “Prototype Objects” on page 9-10
■ “Referring to Self” on page 9-12
■ “Encapsulation” on page 9-13

■ “Reflective Properties” on page 9-15
9- 1
Objects
Overview
Overview I
Objects group values into a common context. An object can include scalar values,
series, functions, and other objects. Objects are useful in dealing with complex
structures as they allow related data and code to be encapsulated and passed as a
single value to functions.
Making Objects I
New objects are created with the make function. The make function requires two
arguments and returns a new object. The format of the make function is:
new-object: make parent-object new-values
The first argument, parent-object, is the parent object from which the new
object is made. If no parent object is available, as when defining an initial object,
use the object! data type, as shown below:
new-object: make object! new-values
The second argument, new-values, is a block that defines additional variables

and initial values for the new object. Each variable that is defined within the block
is an instance variable of the object. For example, if the block contained two
variable definitions, then they would be variables of the object:
example: make object! [

var1: 10
var2: 20
]
The example object has two variables that hold two integers.

Objects
Making Objects
The block is evaluated, so it can include any type of expression to compute the
values of the variables:

var1: 10
var2: var1 + 10
var3: now/time
]
Once an object has been made, it can serve as a prototype for creating new objects:
example2: make example []
The above example makes a second instance of the example object. The new object
is a clone of the first object. New values for the second object are set in the block:
example2: make example [

var1: 30
var2: var1 + 10
]
In the example above, the example2 object has different values than the original
example object for two of its variables.
The example2 object can also extend the object definition by adding new variables
to it:
example2: make example [

var4: now/date
var5: "example"
]
The result is an object that has five variables: Three that came from the original
object, example, and two new ones.
The process of extending the definition of an object can be repeated any number of
times.

Objects
Making Objects
You can also create an object that contains variables that are initialized to some
common value. This can be done using a cascaded set of word definitions:
example3: make object! [

var1: var2: var3: var4: none
]
In the example above, the four variables are set to none within the new object.
To summarize, the process of creating an object involves these steps:
■ Use make to create a new object based on a parent object or the object! data
type.
■ Add any new variables that are defined in the block to the new object.
■ Evaluate the block, which causes the variables defined in the block to be set to
the values in the new object.
■ The new object is returned as a result.
Cloning Objects 0
When you use a parent object to make a new object, the parent object is cloned
rather than inherited. This means that if the parent object is modified, it has no
effect on the child object.
As an example, the following code creates a bank account object, whose variables
are blank:
bank-account: make object! [

first-name:
last-name:
account:
balance: none
]

Objects
Making Objects
To use the new object, values can be provided to create an account for a customer:
luke: make bank-account [

first-name: "Luke"
last-name: "Lakeswimmer"
account: 89431
balance: $1204.52
]
Since new accounts are made on a regular basis, it helps to use a function and some
global variables to create them:
last-account: 89431
bank-bonus: $10.00
make-account: func [
"Returns a new account object"
f-name [string!] "First name"
l-name [string!] "Last name"
start-balance [money!] "Starting balance"
][
last-account: last-account + 1
make bank-account [
first-name: f-name
last-name: l-name
account: last-account
balance: start-balance + bank-bonus
]
]
Now a new account object for Fred would only require:
fred: make-account "Fred" "Smith" $500.00

Objects
Accessing Objects
Accessing Objects I
Variables within objects are accessed with paths. The path consists of the object
name followed by the name of the variable. For example, the following code
accesses the variables in the example object:
example/var1
example/var2
Here are examples using the bank-account object:
print luke/last-name
Lakeswimmer
print fred/balance
$510.00
Using a path, the variables of an object can also be modified:
fred/balance: $1000.00
print fred/balance
$1000.00
You can use the in function to access object variables by fetching their words from
within their object context:
print in fred 'balance
balance
The balance word returned has the object fred as its context. You can get the
value it holds by using get:
print get in fred 'balance
$1000.00

Objects
Object Functions
The second argument to the in function is a literal word. This allows you to
dynamically change words depending on what is needed:
words: [first-name last-name balance]

foreach word words [print get in fred word]
Fred
Smith
$1000.00
Each word in the block is used to obtain its value in the object.
The in function can also be used to set object variables.
set in fred 'balance $20.00

print fred/balance
$20.00
If a word is not defined within an object, the in function returns none. This is
useful for detecting when a variable exists within an object.
if get in fred 'bank [print fred/bank]
Object Functions I
An object can contain variables that refer to functions that are defined within the
context of the object. This is useful because the functions are encapsulated within
the context of the object, and can access the other variables of the object directly,
without a need for a path.

Objects
Object Functions
As a simple example, the example object can include functions for computing new
values within the object:

var1: 10
var2: var1 + 10
var3: now/time
set-time: does [var3: now/time]
calculate: func [value] [
var1: value
var2: value + 10
]
]
Notice in the example that the functions are able to refer to the variables of the
object directly, rather than as paths. That is possible because the functions are
defined within the same context as the variables they access.
To set a new time, use:
example/set-time
This example evaluates the function that sets var3 to the current time.
To calculate new values for var1 and var2, use:
example/calculate 100
print example/var2
110

Objects
Object Functions
In the case of the bank-account object, the functions for deposit and
withdraw can be added to the current definition:
bank-account: make bank-account [

deposit: func [amount [money!]] [
balance: balance + amount
]
withdraw: func [amount [money!]] [
either negative? balance [
print ["Denied. Account overdrawn by"
absolute balance]
][balance: balance – amount]
]
]
In the example, notice that the functions are able to refer to the balance directly
within the object. That’s because the functions are part of the object’s context.

Objects
Prototype Objects
Now if a new account is made, it will contain functions for depositing and
withdrawing money. For example:
lily: make-account "Lily" "Lakeswimmer" $1000
print lily/balance
$1010.00
lily/deposit $100
print lily/balance
$1110.00
lily/withdraw $2000
print lily/balance
-$890.00
lily/withdraw $2.10
Denied. Account overdrawn by $890.00
Prototype Objects I
Any object can serve as a prototype for making new objects. For instance, the lily
account object previously defined can be used to make new objects with a line such
as:
maya: make lily []

Objects
Prototype Objects
This makes an instance of an object. The object is a copy of the customer object and
has identical values:
print lily/balance
-$890.00
print maya/balance
-$890.00
You can modify the new object while making it by providing the new values within
the definition block:
maya: make lily [

first-name: "Maya"
balance: $10000
]
print maya/balance
$10000.00
maya/deposit $500
print maya/balance
$10500.00
print maya/first-name
Maya
The lily object serves as a prototype for creating the new object. Any words that
are not redefined for the new object continue to have the values of the old object:
print maya/last-name
Lakeswimmer

Objects
Referring to Self
New words are added to the object in a similar way:
maya: make lily [

birthdate: 4-July-1977
]
Referring to Self I
Every object includes a predefined variable called self. Within the context of an
object, the self variable refers to the object itself. It can be used to pass the object
to other functions or to return it as a result of a function.
In the following example, the show-date function requires

an object as its argument and self is passed to
it:show-date: func [obj] [print obj/date]

date: now
show: does [show-date self]
]
example/show
16-Jul-2000/11:08:37-7:00

Objects
Encapsulation
Another example of using the self variable is a function that clones itself:
person: make object! [

name: days-old: none
new: func [name’ birthday] [
make self [
name: name’
days-old: now/date - birthday
]
]
]
lulu: person/new "Lulu Ulu" 17-May-1980
print lulu/days-old
7366
Encapsulation I
An object provides a good way to encapsulate a group of variables that should not
appear at the global level. When function variables are defined as globals, they can
unintentionally be modified by other functions.

Objects
Encapsulation
The solution to this problem of global variables is to wrap an object around both
the variables and the function. When that is done, the function can still access the
variables, but the variables cannot be accessed globally. For example:
Bank: make object! [
last-account: 89431
bank-bonus: $10.00
set 'make-account func [

"Returns a new account object"
f-name [string!] "First name"
l-name [string!] "Last name"
start-balance [money!] "Starting balance"
][
last-account: last-account + 1
make bank-account [
first-name: f-name
last-name: l-name
account: last-account
balance: start-balance + bank-bonus
]
]
]
In this example, the variables are safe from accidental modification. Notice that the
make-account function was set to a variable using the set function, rather than
using a variable definition. This was done to make it a global function. The
function can be used in the same way as functions set with a variable definition,
but does not require an object path:
bob: make-account "Bob" "Baker" $4000

Objects
Reflective Properties I
As with many other REBOL data types, you can access the components of objects
in a manner that allows you to write useful tools and utilities for creating,
monitoring, and debugging them.
The first and second functions allow you to access the components of an object.
The first function returns the words defined for an object. The second function
returns the values that the objects are set to. The following diagram shows the
relationship between the return values of first and second:
Figure 0-1. Return values for first and second
first second
first-name "Luke"
last-name "Lakesw immer"
account 89431
balance $1204.52
The advantage to using first is that it allows you to obtain a list of the words for the
function without knowing anything else about the function:
probe first luke
[self first-name last-name account balance]
In the above example, notice that the list contains the word, self, which is a
reference to the object itself. You can exclude self when getting an object’s word
list by using next:
probe next first luke
[first-name last-name account balance]

Objects
Now you have a way to write a function that can probe the contents of an object:
probe-object: func [object][

foreach word next first object [
print rejoin [word ":" tab get in object word]
]
]
probe-object fred
first-name: Luke
last-name: Lakeswimmer
account: 89431
balance: $1204.52
When accessing objects in this fashion, care should be taken to avoid infinite loops.
For instance, if you attempt to probe certain objects that contain references to
themselves, your code may begin an endless loop. This is the reason why you
cannot probe the system object directly. The system object contains many
references to itself.

10
Math
This chapter describes the operation and evaluation of math functions in REBOL,
as well as a list of valid data types. It includes the following information:

■ “Scalar Data Types” on page 10-2
■ “Evaluation Order” on page 10-8
■ “Standard Functions and Operators” on page 10-10

■ “Type Conversion” on page 10-20
■ “Comparison Functions” on page 10-20
■ “Logarithmic Functions” on page 10-28

■ “Trigonometric Functions” on page 10-29
■ “Logic Functions” on page 10-31
■ “Errors” on page 10-33
10- 1
Math
Overview
Overview J
REBOL provides a comprehensive set of mathematical and trigonometric

operations. Many of these operators can handle multiple datatypes, including
integer, decimal, money, tuple, time, and date. Some of these datatypes may even
be mixed, or coerced.
Scalar Data Types J
The mathematical functions of REBOL operate in a consistent manner over a wide

range of scalar (numerical) data types. These data types include:
Table 10-1. Scalar Data Types
Data Type Description
Integer! 32 bit numbers without decimal point

Decimal! 64 bit floating point numbers
Money! currency with 64 bit floating point number
Time! hours, minutes, seconds, and sub-seconds
Date! day, month, year, time, time zone
Pair! graphical position or size
Tuple! versions, colors, network addresses
The following are a few examples that show a range of math operations over the
scalar data types. Notice that operators produce useful results for each data type.

Math
Scalar Data Types
The integer and decimal data types:
print 2 + 1
3
print 2 - 1
1
print 2 * 10
20
print 20 / 10
2
print 21 // 10
1
print 2.2 + 1
3.2
print 2.2 - 1
1.2
print 2.2 * 10
22
print 2.2 / 10
0.22
print random 10
5

Math
Scalar Data Types
The time data type:
print 2:20 + 1:40

4:00
print 2:20 + 5
2:20:05
print 2:20 + 60
2:21
print 2:20 + 2.2
2:20:02.2
print 2:20 - 1:20
1:00
print 2:20 - 5
2:19:55
print 2:20 - 120
2:18
print 2:20 * 2
4:40
print 2:20 / 2
1:10
print 2:20:01 / 2
1:10:00.5
print 2:21 // 2
0:00
print - 2:20
-2:20
print random 10:00
5:30:52

Math
Scalar Data Types
The date data type:
print 1-Jan-2000 + 1
2-Jan-2000
print 1-Jan-2000 - 1
31-Dec-1999
print 1-Jan-2000 + 31
1-Feb-2000
print 1-Jan-2000 + 366
1-Jan-2001
birthday: 7-Dec-1944
print ["I’ve lived" (now/date - birthday) "days."]
I’ve lived 20305 days.
print random 1-1-2000
29-Apr-1695

Math
Scalar Data Types
The money data type:
print $2.20 + $1
$3.20
print $2.20 + 1
$3.20
print $2.20 + 1.1
$3.30
print $2.20 - $1
$1.20
print $2.20 * 3
$6.60
print $2.20 / 2
$1.10
print $2.20 / $1.10
2
print $2.21 // 2
$0.21
print random $10.00
$6.00

Math
Scalar Data Types
The pair data type:
print 100x200 + 10x20

110x220
print 10x10 + 3
13x13
print 10x20 * 2x4
20x80
print 100x100 * 3
300x300
print 100x30 / 10x3
10x10
print 100x30 / 10
10x3
print 101x32 // 10x3
1x2
print 101x32 // 10
1x2
print random 100x20
67x12

Math
Evaluation Order
The tuple data type:
print 1.2.3 + 3.2.1

4.4.4
print 1.2.3 - 1.0.1
0.2.2
print 1.2.3 * 3
3.6.9
print 10.20.30 / 10
1.2.3
print 11.22.33 // 10
1.2.3
print 1.2.3 * 1.2.3
1.4.9
print 10.20.30 / 10.20.30
1.1.1
print 1.2.3 + 7
8.9.10
print 1.2.3 - 1
0.1.2
print random 10.20.30
8.18.12
Evaluation Order J
There are two rules to remember when evaluating mathematical expressions:
■ Expressions are evaluated from left to right.
■ Operators take precedence over functions.

Math
Evaluation Order
The evaluation of expressions from left to right is independent of the type of

operator that is used. For example:
print 1 + 2 * 3
In the example above, notice that the result is not seven, as would be the case if
multiplication took precedence over addition.
If you need to evaluate in some other order, reorder the expression or use
parentheses:
print 2 * 3 + 1
print 1 + (2 * 3)
When functions are mixed with operators, the operators are evaluated first, then the
functions:
print absolute -10 + 5
In the above example, the addition is performed first, and its result is provided to
the absolute function.
In the next example:
print 10 + sine 30 + 60
11

Math
Standard Functions and Operators
the expression is evaluated in this order:
30 + 60 => 90
sine 90 => 1
10 + 1 => 11
print
To change the order such that the sine of 30 is done first, use parentheses:
print 10 + (sine 30) + 60
70.5
or reorder the expression:
print 10 + 60 + sine 30
70.5
Standard Functions and Operators J
This section describes the standard math functions and operators used in REBOL.
absolute 0
absolute value
value
Returns the absolute value of value.

Math
Works with integer, decimal, money, time, pair data types
print absolute -10
10
print absolute -1.2
1.2
print absolute -$1.2
$1.20
print absolute -10:20
10:20
print absolute -10x-20
10x20
add 0
value1 + value2
add value1 value2
Returns result of adding value1 to value2.

Math
Works with integer, decimal, money, time, tuple, pair, date, char data types.
print 1 + 2
print 1.2 + 3.4
4.6
print 1.2.3 + 3.4.5
4.6.8
print $1 + $2
$3.00
print 1:20 + 3:40
5:00
print 10x20 + 30x40
40x60
print #"A" + 10
print add 1 2
complement 0
complement value
Returns the numeric complement (bitwise complement) of a value.

Math
Works with integer, decimal, tuple data types.
print complement 10
-11
print complement 10.5
-11
print complement 100.100.100
155.155.155
divide 0
value1 / value2
divide value1 value2
Returns result of dividing value1 by value2.

Math
Works with integer, decimal, money, time, tuple, pair, char data types.
print 10 / 2
print 1.2 / 3
0.4
print 11.22.33 / 10
1.2.3
print $12.34 / 2
$6.17
print 1:20 / 2
0:40
print 10x20 / 2
5x10
print divide 10 2
multiply 0
value1 * value2
multiply value1 value2
Returns result of multiplying value1 by value2.

Math
Works with integer, decimal, money, time, tuple, pair, char data types.
print 10 * 2
20
print 1.2 * 3.4
4.08
print 1.2.3 * 3.4.5
3.8.15
print $10 * 2
$20.00
print 1:20 * 3
4:00
print 10x20 * 3
30x60
print multiply 10 2
20
negate 0
value
negate value
Changes the sign of the value.

Math
Works with integer, decimal, money, time, pair, char data types.
print - 10
-10
print - 1.2
-1.2
print - $10
-$10.00
print - 1:20
-1:20
print - 10x20
-10x-20
print negate 10
-10
random 0
random value
Return random value that is less than or equal to value given.
Note that for integers random begins at 1, not 0, and is inclusive of the value given.
This allows random to be used directly with functions like pick.
When a decimal is used the result is a decimal data type rounded to an integer.

Math
The /seed refinement restarts the random generator. Use the /seed refinement with
random first it if you want unique random number generation. You can use the
current date and time to make the seed more random:
random/seed now
print random 10
print random 10.5
print random 100.100.100
79.95.66
print random $100
$32.00
print random 10:30
6:37:33
print random 10x20
2x4
print random 30-Jun-2000
27-Dec-1171

Math
remainder 0
value1 // value2
remainder value1 value2
Returns remainder of dividing value1 by value2.
Works with integer, decimal, money, time, tuple, pair data types.
print 11 // 2
print 11.22.33 // 10
1.2.3
print 11x22 // 2
1x0
print remainder 11 2
subtract 0
value1 - value2
subtract value1 value2
Returns result of subtracting value2 from value1.

Math
print 2 - 1
print 3.4 - 1.2
2.2
print 3.4.5 - 1.2.3
2.2.2
print $2 - $1
$1.00
print 3:40 - 1:20
2:20
print 30x40 - 10x20
20x20
print #"Z" - 1
print subtract 2 1

Math
Type Conversion
Type Conversion J
When math operations are performed between data types, normally the non-integer
or non-decimal data type is returned. When integers are combined with decimals,
a decimal data type is returned.
Comparison Functions J
All comparison functions return either true or false.
equal 0
value1 = value2
equal? value1 value2
Returns true if the first and second values are equal.
Works with integer, decimal, money, time, date, tuple, char and series data types.
print 11-11-99 = 11-11-99
true
print equal? 111.112.111.111 111.112.111.111
true
print #"B" = #"B"
true
print equal? "a b c d" "A B C D"
true

Math
Comparison Functions
greater 0
value1 > value2
greater? value1 value2
Returns true if the first value is greater than the second value.
print 13-11-99 > 12-11-99
true
print greater? 113.111.111.111 111.112.111.111
true
print #"C" > #"B"
true
print greater? [12 23 34] [12 23 33]
true
greater-or-equal 0
value1 >= value2
greater-or-equal? value1 value2
Returns true if the first value is greater than or equal to the second value.

Math
print 11-12-99 >= 11-11-99
true
print greater-or-equal? 111.112.111.111 111.111.111.111
true
print #"B" >= #"A"
true
print greater-or-equal? [b c d e] [a b c d]
true
lesser 0
value1 < value2
lesser? value1 value2
Returns true if the first value is less than second value.

Math
Works with integer, decimal, money, time, date, tuple, char and series data types:
print 25 < 50
true
print lesser? 25.3 25.5
true
print $2.00 < $2.30
true
print lesser? 00:10:11 00:11:11
true
lesser-or-equal 0
value1 <= value2
lesser-or-equal? value1 value2
Returns true if the first value is less than or equal to the second value.

Math
print 25 <= 25
true
print lesser-or-equal? 25.3 25.5
true
print $2.29 <= $2.30
true
print lesser-or-equal? 11:11:10 11:11:11
true
not equal to 0
value1 <> value2
not-equal? value1 value2
Returns true if the first and second values are not equal.

Math
print 26 <> 25
true
print not-equal? 25.3 25.5
true
print $2.29 <> $2.30
true
print not-equal? 11:11:10 11:11:11
true
same 0
value1 =? value2
same? value1 value2
Returns true if two words refer to the same value. For instance, when you want to
see if two words are referencing the same index in a series.

Math
Work with all data types.
reference-one: "abcdef"
reference-two: reference-one
print same? reference-one reference-two
true
reference-one: next reference-one

false
reference-two: next reference-two

true
reference-two: copy reference-one

false
strict-equal 0
value1 == value2
strict-equal? value1 value2
Returns true if the first and second values are strictly the same. Can be used as a
case-sensitive version of the equal? (=) operator for strings and to differentiate
between integers and decimals when their values are the same.

Math
Works with all data types.
print strict-equal? "abc" "ABC"
false
print equal? "abc" "ABC"
true
print strict-equal? "abc" "abc"
true
print strict-equal? 1 1.0
false
print equal? 1 1.0
true
print strict-equal? 1.0 1.0
true
strict-not-equal 0
strict-not-equal? value1 value2
Returns true if the first and second values are strictly not the same. Can be used
as a case-sensitive version of the not-equal? (<>) operator for strings and to
differentiate between integers and decimals when their values are the same.

Math
Logarithmic Functions
Works with all data types.
print strict-not-equal? "abc" "ABC"
true
print not-equal? "abc" "ABC"
false
print strict-not-equal? "abc" "abc"
false
print strict-not-equal? 1 1.0
true
print not-equal? 1 1.0
false
print strict-not-equal? 1.0 1.0
false
Logarithmic Functions J
exp 0
exp value
Raises E (natural number) to the power of value.
log-10 0
log-10 value

Math
Trigonometric Functions
Returns base-10 logarithm of value.
log-2 0
log-2 value
Returns base-2 logarithm of value.
log-e 0
log-e value
Returns base-E (natural number) log. of value.
power 0
value1 ** value2
power value1 value2
Returns result of raising value1 to value2 power.
square-root 0
square-root value
Returns square root of value.
Trigonometric Functions J
The trigonometric functions deal in degrees. Use the /radians refinement with any
of the trigonometric functions to operate in and return radians.
arccosine 0
arccosine value

Math
Trigonometric Functions
Returns trigonometric arccosine of value.
arcsine 0
arcsine value
Returns trigonometric arcsine of value.
arctangent 0
arctangent value
Returns trigonometric arctangent of value.
cosine 0
cosine value
Returns trigonometric cosine of value.
sine 0
sine value
Returns trigonometric sine of value.
tangent 0
tangent value
Returns trigonometric tangent of value.

Math
Logic Functions
Logic Functions J
Logic functions can be performed on logic values and on some scalar values
including integer, char, tuple, and bitset. When working with logic values, the
logic functions return boolean values. When working with other types of values,
the logic functions on the bits.
and 0
The and function compares two logic values and returns true if they are both
true:
print (1 < 2) and (2 < 3)
true
print (1 < 2) and (4 < 3)
false
When used with integers, the and function compares bit for bit and returns 1 if both
bits are 1, or 0 if neither bit is 1:
print 3 and 5

Math
Logic Functions
or 0
The or function compares two logic values and returns true if either of them are
true or false or if both are false:
print (1 < 2) or (2 < 3)
true
print (1 < 2) or (4 < 3)
true
print (3 < 2) or (4 < 3)
false
When used with integers, or compares bit for bit and returns 1 if either bit is 1 or
0 if both bits are 0:
print 3 or 5
xor 0
The xor function compares two logic values and returns true if and only if one of
the values is true and the other is false.
print (1 < 2) xor (2 < 3)
false
print (1 < 2) xor (4 < 3)
true
print (3 < 2) xor (4 < 3)
false

Math
Errors
When used with integers, xor compares bit for bit and returns 1 if and only if one
bit is 1 and the other 0. Otherwise, it returns 0:
print 3 xor 5
complement 0
The complement function returns the logic or bitwise complement of a value. It is

used for bitmask integer numbers and inverting bitsets.
print complement true
false
print complement 3
-4
not 0
For a logic value not returns true if the value is false and false if the value is
true. It does not perform numerical bitwise operations.
print not true
false
print not false
true
Errors J
Math errors are reported when an illegal operation is performed or when an

overflow or underflow occurs. The following are errors encountered in math
operations.

Math
Errors
Attempt to divide by zero 0
An attempt was made to divide a number by 0.
1 / 0
Math or number overflow 0
An attempt was made to process a number too large for REBOL to handle.
1E+300 + 1E+400
Positive number required 0
An attempt was made to process a negative number with a math operator that
accepts only positive numbers.
log-10 -1
Cannot use operator on datatype! value 0
An attempt was made to process incompatible data types. The data type of the
second argument in the operation is returned as listed.
10:30 + 1.2.3

11
Files
This chapter explains how to manipulate files and directories in REBOL. It includes
the following information:

■ “Names and Paths” on page 11-2
■ “Reading Files” on page 11-6
■ “Writing Files” on page 11-8

■ “Line Conversion” on page 11-10
■ “Blocks of Lines” on page 11-11
■ “File and Directory Information” on page 11-13

■ “Directories” on page 11-16
11- 1
Files
Overview
Overview K
An important aspect of REBOL’s power is its ability to manipulate files and

directories. REBOL provides a wide range of functions designed to allow operations
ranging from simple file reads to direct access to files and directories. For more
information on direct access to files and directories, see the “Ports” Chapter.
Names and Paths K
REBOL provides a standard, machine independent file and path naming

convention.
File Names 0
In scripts, file names and paths are written with a percent sign (%) followed by a
sequence of characters:
%examples.r
%big-image.jpg
%graphics/amiga.jpg
%/c/plug-in/video.r
%//sound/goldfinger.mp3
The percent sign is necessary to prevent file names from being interpreted as words
within the language.
Although it is not a good practice, spaces can be included in file names by enclosing
the file name in double quotes (“ “). The double quotes prevent the file name from
being interpreted as multiple words:
%"this file.txt"
%"cool movie clip.mpg"

Files
Names and Paths
The standard Internet convention of using a percent sign (%) and a hex code is also
allowed for character encoding. When this is done, quotes are not required. The
above file names could also be written as:
%this%20file.txt
%cool%20movie%20clip.mpg
Note that the standard file suffix for REBOL scripts is .r. On systems where this
convention collides with another file type, a .reb suffix can be used instead.
Path Strings 0
File paths are written with a percent sign (%) followed by a sequence of directory
names that are each separated by a forward slash (/).
%dir/file.txt
%/file.txt
%dir/
%/dir/
%/dir/subdir/
%../dir/file.txt
The standard character for separating directories is the forward slash (/), not the
backslash (\). If backslashes are found they are converted to forward slashes:
probe %\some\cool\movie.mpg
%/some/cool/movie.mpg
REBOL provides a standard, operating system independent method for specifying

directory paths. Paths can be relative to the current directory or absolute from the
top-level file structure of the operating system.
File paths that do not begin with a forward slash (/) are relative paths.
%docs/intro.txt
%docs/new/notes.txt
%"new mail/inbox.mbx"

Files
Names and Paths
The standard convention of using double dots (..) to indicate a parent directory or
a single dot (.) to refer to the current directory is also supported. For example:
%.
%./
%./file.txt
%..
%../
%../script.r
%../../plans/schedule.r
File paths use the standard Internet convention of beginning absolute paths with a
forward slash (/). The forward slash indicates to start at the top level of the file
system. (Generally, absolute paths should be avoided to ensure
machine-independent scripts.) The example:
%/home/file.txt
would refer to a disk volume or partition named home. Other examples are:
%/ram/temp/test.r
%/cd0/scripts/test/files.r
To refer to the C volume that is often used by Windows, the notation is:
%/C/docs/file.txt
%"/c/program files/qualcomm/eudora mail/out.mbx"
Notice in the above lines that the disk volume, C, is not written as:
%c:/docs/file.txt
The above example is not a machine independent format and causes an error.
If the first directory name is absent, and the path begins with double forward
slashes (//), then the file path is relative to the current volume:
%//docs/notes

Files
Names and Paths
Case Sensitivity 0
In REBOL, file names are not case-sensitive by default. However, when new files
are created by the language, they keep the case they were typed in:
write %Script-File.r file-data
The above example creates the file name with the S and F in uppercase.
In addition, when file names are read from directories, the case is preserved:
print read %/home
For case-sensitive systems, such as UNIX, REBOL finds the closest case match to the
specified file. For example, if a script asks to read %test.r, but only finds
%TEST.r, the %TEST.r file is read. This behavior is necessary to allow
machine-independent scripts.
File Name Functions 0
Various functions are provided to help you create file names and paths. These are
listed below in Table 11-1.
Table 11-1. File Name Functions
to-file Converts strings and blocks into a file name or file path.
split-path Splits a path into its directory part and its file name.
clean-path Returns the absolute path that is equivalent to any given path
containing double dot (..) or dot (.).
what-dir Returns the absolute path to the current directory.

Files
Reading Files
Reading Files K
Files are read as a series of text characters or as binary bytes. The source of the file
is either a local file on your system or a file from the network.
Reading Text Files 0
To read a local text file, use the read function:
text: read %file.txt
The read function returns a string that holds the entire text of the file. In the above
example, the variable text refers to that string.
Within the string returned by read, line terminators are converted to newline
characters, regardless of what style of line termination is used on your operating
system. This allows you to write scripts that search for newline without concern
for what particular character or characters constitute a line termination.
next-line: next find text newline
A file can also be read as separate lines that are stored in a block:
lines: read/lines %file.txt
See the “Line Conversion” section for more information about newline and
reading lines.
To read a file a piece at a time, use the open function as described in the “Ports”
Chapter.
To view the contents of a text file, you can read it using read and print it using print:
print read %service.txt


Files
Reading Files
Reading Binary Files 0
To read a binary file such as an image, a program, or a sound, use read/binary:
data: read/binary %file.bin
The read/binary function returns a binary series that holds the entire contents of
the file. In the above example, the variable data refers to the binary series. No
conversion of any type is done to the file.
To read a binary file a piece at a time, use the open function as described in the
“Ports” Chapter..
Reading Over the Network 0
Files can be read from a network. For example, to view a text file from a network
using the HTTP protocol:
print read http://www.rebol.com/test.txt
Hello
there
new
user!
The file could be written locally with the line:
write %test.txt read http:/www.rebol.com/test.txt
In the write process the file will have its line termination converted to that which is
used by your operating system.
To read and save a binary file, such as an image, use the following line:
write %image.jpg
read/binary http:/www.rebol.com/image.jpg

Files
Writing Files
Refer to the chapter on “Network Protocols” for more information and examples of
accessing files across networks.
Writing Files K
You can write a file as a series of text characters or as binary bytes. The location of
the file can be either a local file on your system or a file on a network.
Writing Text Files 0
To write a local text file, use the following line of code:
write %file.txt "sample text here"
This writes the entire text to the file.
If a file contains newline characters, they will be converted to those used by your
local file system. This allows you to deal with files in a consistent manner, but write
them out using the convention that is standard to your file system.
For instance, the following line converts any text file from one line termination
format (UNIX, Macintosh, PC, Amiga) to that which is used by your local system:
write %newfile.txt read %file.txt
The above line reads the entire file while converting its line termination to the
REBOL standard, then writes the file converting it to the local operating system
format.
To append to the end of a file, use the /append refinement:
write/append %file.txt "more text"
A file can also be written from separate lines that are stored in a block.
write/lines %file.txt lines

Files
Writing Files
To write a file a piece at a time, use the open function as described in the “Ports”
Chapter.
Writing Binary Files 0
To write a binary file such as an image, a program, a sound, use write/binary:
write/binary %file.bin data
The write/binary function creates the file if it does not exist or overwrites the file
if it already exists. No conversion of any type is done to the file.
To write a binary file a piece at a time, use the open function as described in the
“Ports” Chapter.
Writing Files to a Network 0
Files can also be written to a network. For example, to write a text file to a network
using FTP, use:
write ftp://ftp.domain.com/file.txt "save this text"
The file can be read locally and written to the net with a line such as:
write ftp://ftp.domain.com/file.txt read %file.txt
In the process, the file has its line termination converted to the standard CRLF
format.
To write a binary file, such as an image, to the network, use the following lines of
code:
write/binary ftp://ftp.domain.com/file.txt/image.jpg
read/binary %image.jpg
Refer to the chapter on “Network Protocols” for more information and examples of
accessing files from networks.

Files
Line Conversion
Line Conversion K
When a file is read as text, all line terminators are converted to newline (line feed)
characters. Line feeds (used as line terminators on Amiga, Linux, and UNIX
systems), carriage returns (used as line terminators on Macintosh), and the CR/LF
combination (PC and Internet) are all converted to the equivalent newline
characters.
Using a standard line terminator within scripts allows them to operate in a

machine-independent fashion. For example, to search for and count all newline
characters within a text file:
text: read %file.txt

count: 0
while [spot: find text newline][
count: count + 1
text: next spot
]
The line conversion is also useful for reading network files:
text: read ftp://ftp.rebol.com/test.txt
When a file is written, the newline character is converted to the line termination
style standard for the operating system being used. For instance, the newline
character is converted to a CRLF on the PC, LF on UNIX or Amiga, or CR for a
Macintosh. Network files are written with CRLF.
The following function converts any text file with any terminator style to that used
by the local operating system:
convert-lines: func [file] [write file read file]
The file is read and all line terminators are converted, then the file is written and
newline characters are converted to the local operating system style.
Line conversion can be disabled by reading the file as binary. For instance, the
following line:
write/binary %newfile.txt read/binary %oldfile.txt

Files
Blocks of Lines
preserves the line terminators of the text file.
Blocks of Lines K
Text files can be easily accessed and managed as individual lines of text, rather than
as a single series of characters. For example, to read a file as a block of lines:
lines: read/lines %service.txt
The above example returns a block containing a series of strings (one for each line)
without line terminators. Empty lines are represented by empty strings.
To print a specific line you use the following code:
print first lines

print last lines
print pick lines 100
print lines/500
To print all of the lines of a file, use the following line of code:
foreach line lines [print line]


Files
Blocks of Lines
To print all of the lines that contain the string gold, use the following line of code:
foreach line lines [

if find line "gold" [print line]
]

You can write the text file out as lines using the write function:
write/lines %output.txt lines
To write out specific lines from a block, use:
write/lines %output.txt [
"line one"
"line two"
"line three"
]
In fact, the functions read/lines and write/lines can be combined to process files
one line at a time. For example the following code removes all of the comments from
a REBOL script:
script: read/lines %script.r

foreach line script [
where: find line ";"
if where [clear where]
]
write/lines %script1.r script
NOTE: The sample script in the previous example is for demonstration purposes
only. In addition to removing comments, the sample script would also remove valid
semicolons in quoted strings.

Files
File and Directory Information
Files can be read as lines from a network as well:
data: read/lines http://www.rebol.com
print pick (read/lines ftp://ftp.rebol.com/test.txt) 3
new
The /lines refinement can be used with the open function to read a line at a time
from console input. See the chapter on “Ports” for more information.
In addition /lines can be used with /append to append lines from a block to a file.
File and Directory Information K
There are a number of functions that provide useful information about a file, such
as whether it exists, its file size in bytes, when it was last modified, and whether it
is a directory.
Directory Check 0
To determine if a file name is that of a directory, use the dir? function:
print dir? %file.txt
false
print dir? %.
true
The dir? function works with some network protocols as well:
print dir? ftp://www.rebol.com/pub/
true

Files
File Existence 0
To determine if a file exists, use the exists? function:
print exists? %file.txt
To determine if a file exists before you read it, use:
if exists? file [text: read file]
To avoid overwriting a file you can check it with, use:
if not exists? file [write file data]
The exists? function also works with some network protocols:
print exists? ftp://www.rebol.com/file.txt
File Size 0
To obtain the byte size of a file, use the size? function:
print size? %file.txt
The size? function also works with some network protocols:
print size? ftp://www.rebol.com/file.txt
File Modification Date 0
To obtain the last modification date of a file, use the modified? function:
print modified? %file.txt
30-Jun-2000/14:41:55-7:00

Files
Not all operating systems keep track of the creation date of a file, so to keep REBOL
scripts operating system independent only the last modification date is accessible.
The modified? function also works with some network protocols:
print modified? ftp://www.rebol.com/file.txt
Directory Information 0
The info? function obtains all file directory information at the same time. The
information is returned as an object:
probe info? %file.txt
make object! [
size: 306
date: 30-Jun-2000/14:41:55-7:00
type: ’file
]
To print information about all files in the current directory, use:
foreach file read %. [

info: info? file
print [file info/size info/date info/type]
]
build-guide.r 22334 30-Jun-2000/14:24:43-7:00 file

code/ 11 11-Oct-1999/18:37:04-7:00 directory
data.r 41 30-Jun-2000/14:41:36-7:00 file
file.txt 306 30-Jun-2000/14:41:55-7:00 file
The info? function also works with some network protocols:
probe info? ftp://www.rebol.com/file.txt

Files
Directories
Directories K
There are several easy-to-use functions for reading directories, managing

subdirectories, making new directories, renaming files, and deleting files. In
addition, there are standard functions for getting, changing, and listing the current
directory. For more information on direct access to directories, see the “Ports”
Chapter.
Reading a Directory 0
Directories are read in the same manner as files. The read function returns a block
of file names rather than text or binary data.
To read all the file names from the current directory, use the following line of code:
read %.
The above example reads the entire directory and returns a block of file names.
To print the names of all files in a directory, use the following line of code:
print read %intro/
CVS/ history.t intro.t overview.t quick.t
Within the returned block, names of directories are indicated with a trailing forward
slash. To print each file name on a separate line, use:
foreach file read %intro/ [print file]
CVS/
history.t
intro.t
overview.t
quick.t

Files
Directories
Here is an easy way to print just the directories that were found:
foreach file read %intro/ [

if #"/" = last file [print file]
]
CVS/
If you want to read a directory from the network, be sure to include a forward slash
at the end of the URL to indicate to the protocol that you are referring to a directory:
print read ftp://ftp.rebol.com/
Making a Directory 0
The make-dir function makes a new directory. The new name for the directory can
be relative to either the current directory or an absolute path.
make-dir %new-dir
make-dir %local-dir/
make-dir %/work/docs/old-docs/
The trailing slash is optional for this function.
Internally, the make-dir function calls open with the /new refinement. The line:
close open/new %local-dir/
also creates a new directory. The trailing slash is important in this example,
indicating that a directory is to be created rather than a file.
If you use the make-dir function to create a directory that already exists, an error
will occur. The error can be caught with the try function. The directory can be
checked in advance with the exists? function.
Renaming Directories and Files 0
To rename a file, use the rename function:
rename %old-file %new-file

Files
Directories
The old file name may include a complete path to the file, but the new file name
must not include a path. This is because the rename function is not intended to
move files between directories (various operating systems do not provide this
function).
rename %../docs/intro.txt %conclusion.txt
If the old file name is a directory (indicated by a trailing slash), the rename function
renames the directory:
rename %../docs/ %manual/
If the file cannot be renamed, an error will occur. The error can be caught with the
try function.
Deleting Directories and Files 0
Files can be deleted using the delete function:
delete %file
The file to delete can include a path:
delete %source/docs/file.txt
A block of files within the same directory can also be deleted:
delete [%file1 %file2 %file3]
A group of files can be deleted using a wildcard character and the /any refinement:
delete/any %file*
delete/any %secret.?
The asterisk (*) wildcard character matches all characters, and the question mark
(?) wildcard character matches a single character.
To delete a directory, provide a trailing forward slash:
delete %dir/
delete %../docs/old/

Files
Directories
If the file cannot be deleted, an error will occur. The error can be caught with the
try function.
Current Directory 0
Use the what-dir function to determine the current directory:
print what-dir
/work/REBOL/
The what-dir function refers to the current script’s directory path, as found in
system/script/path.
Changing the Current Directory 0
To change the current directory, use:
change-dir %new-path/to-dir/
If the trailing slash is not included, the function adds it.
Listing the Current Directory 0
To list the contents of the current directory, use:
list-dir
The number of columns used to show the directory is dependent on the console
window size and the maximum file name length.

Files
Directories

12
Network Protocols
This chapter explains REBOL’s networking capabilities. It includes the following

information:

■ “REBOL Networking Basics” on page 12-3
■ “Initial Setup” on page 12-9
■ “DNS - Domain Name Service” on page 12-14

■ “Whois Protocol” on page 12-16
■ “Finger Protocol” on page 12-18
■ “Daytime - Network Time Protocol” on page 12-19

■ “HTTP - Hyper Text Transfer Protocol” on page 12-20
■ “SMTP - Simple Mail Transport Protocol” on page 12-26
■ “POP - Post Office Protocol” on page 12-30

■ “FTP - File Transfer Protocol” on page 12-36
■ “NNTP - Network News Transfer Protocol” on page 12-45
■ “CGI - Common Gateway Interface” on page 12-49
■ “TCP - Transmission Control Protocol” on page 12-59
12- 1
Network Protocols
Overview
Overview L
REBOL includes several of the primary Internet service protocols built-in. These
protocols are easy to use within your scripts; they require no extra libraries or
include files, and many useful operations can be done with only a single line of
source code.
The protocols listed in Table 12-1 are supported:

Table 12-1. Network Protocols
Protocol Description
DNS Domain Name Service: translates computer names into

addresses, and addresses into names.
Finger Obtains information about a user from their profile.
Whois Obtains information about domain registration.
Daytime Network Time Protocol. Gets the time from a server.
HTTP Hypertext Transfer Protocol. Used for the Web.
SMTP Simple Mail Transfer Protocol. Used for sending email.
POP Post Office Protocol. Used for fetching email.
FTP File Transfer Protocol. Exchanges files with a server.
NNTP Network News Transfer Protocol. Posts or reads Usenet news.
TCP Transmission Control Protocol. Basic Internet protocol.
UDP User Datagram Protocol. Packet-based protocol.
In addition, you can create handlers for other Internet protocols or make your own
custom protocols.

Network Protocols
REBOL Networking Basics
REBOL Networking Basics L
Modes of Operation 0
There are two basic modes of network operation: atomic and port-based.
Atomic network operations are those that are accomplished in a single function. For
instance, you can read an entire Web page with a single call to the read function.
There is no need to separately open a connection or set up the read. All of that is
done automatically as part of the read. For example, you can type:
print read http://www.rebol.com
The host is found and opened, its Web page transferred, and the connection closed.
The port-based mode of operation is one that uses a more traditional programming
approach. It involves opening a port and performing various series operations on
the port. For instance, if you want to read your email from a POP server one
message at a time, you would use this method. Here is an example that reads and
displays all of your email:
pop: open pop://user:[email protected]

forall pop [print first pop]
close pop
The atomic method of operation is easier, but it is also more limited. The port-based
method allows more types of operations, but also requires a greater understanding
of networking.

Network Protocols
Specifying Network Resources 0
REBOL provides two approaches for specifying network resources: URLs and port
specifications.
Uniform Resource Locators (URL) are used on the Internet to identify a network
resource, such as a Web page, FTP site, email address, file, or other resource or
service. URLs are integral to the operation of REBOL, and they can be expressed
directly in the language.
The standard notation for URLs consists of a scheme followed by a specification:
scheme:specification
The scheme is often the name of a protocol, such as HTTP, FTP, SMTP, and POP;
however, that is not a requirement. A scheme can be any name that identifies the
method used to access a resource.
The format of a scheme’s specification depends on the scheme; however, most

schemes share a common format for identifying network hosts, user names,
passwords, port numbers, and file paths. Here are a few commonly used formats:
scheme://host
scheme://host:port
scheme://user@host
scheme://user:pass@host
scheme://user:pass@host:port
scheme://host/path
scheme://host:port/path
scheme://user@host/path
scheme://user:pass@host/path
scheme://user:pass@host:port/path

Network Protocols
Table 12-2 lists the fields used in the above formats.

Table 12-2. Network Resource Specification
Field Description
scheme The name used to identify the type of resource, often the same
as the protocol. For example, HTTP, FTP, and POP.
host The network name or address for a machine. For example,
www.rebol.com, cnn.com, accounting.
port Port number on the host machine for the scheme being used.
Normally there is a default for this, so it is not required most of
the time. Examples: 21, 23, 80, 8000.
user A user name to access the resource.
pass A password to verify the user name.
path A file path or some other method for referencing the resource.
This is scheme dependent. Some schemes include patterns and
script arguments (such as CGI).
Another way to identify a resource is with a REBOL port specification. In fact, when
a URL is used, it is automatically converted into a port specification. A port
specification can accept many more arguments than a URL, but it requires multiple
lines to express.
A port specification is written as an object block definition that provides each of the
parameters necessary to access the network resource. For instance, the URL to
access a Web site is:
read http://www.rebol.com/developer.html
but, it can also be written as:
read [
scheme: 'HTTP
host: "www.rebol.com"
target: %/developer.html
]

Network Protocols
The URL for an FTP read can be:
read ftp://bill:[email protected]:8000/file.txt
but, it can also be written as:
read [
scheme: 'FTP
host: "ftp.example.com"
port-id: 8000
target: %/file.txt
user: "bill"
pass: "vbs"
]
In addition, there are many other port fields that can be specified, such as timeout,
type of access, and security.
Schemes, Handlers, and Protocols 0
REBOL networking operates by using schemes to identify handlers that

communicate with protocols.
In REBOL a scheme is used to identify the method of accessing a resource. That

method uses a code object that is called a handler. Each of the URL schemes that
are supported by REBOL (such as HTTP, FTP) has a handler. The list of schemes
can be obtained with:
probe next first system/schemes
[default Finger Whois Daytime SMTP POP HTTP FTP NNTP]
In addition, there are lower level scheme names that are not shown here. For
instance, the TCP and UDP schemes are used for direct, lower level communication.
New schemes can be added to this list. For instance, you can define your own
scheme, called FTP2, that provides special features for FTP access, such as
automatically supplying your username and password so it does not need to be
included in every FTP URL.

Network Protocols
Most handlers are used to provide an interface to a network protocol. A protocol is

used to communicate between various devices, including clients and servers.
Although each protocol is quite different in how it communicates, it does have some
things in common with other protocols. For instance, most protocols require a
network connection to be opened, read, written, and closed. These common
operations are performed by a default handler in REBOL. This handler makes
protocols like finger, whois, and daytime almost trivial to implement.
Scheme handlers are written as objects. The default handler serves as the root
object for all the other handlers. When a handler requires a particular field, such
as a timeout value to use for reading data, if the value is not defined in the specific
handler, it will be provided by the default handler. Hence, handlers overlay one
another with their fields and value. You can also create handlers that use other
handlers for default values. For instance, you can create an FTP2 handler that looks
for missing fields first in the FTP handler, then in the default handler.
When a port is used to access network resources, it is linked to a specific handler.

The handler and the port together form the unit that is used to provide the data,
code, and state information to process all protocols.
The source code to handlers can be obtained from the system/scheme object. This
can be useful if you want to modify the behavior of a handler or build your own
handler. For instance, to view the code for the whois handler, type:
probe get in system/schemes 'whois
Note that what you are seeing is a composite of the default handler with the whois
handler. The actual source code that is used to create the whois handler is only a
few lines:
make Root-Protocol [
open-check: [[any [port/user ""]] none]
net-utils/net-install Whois make self [] 43
]

Network Protocols
Monitoring Handlers
For debugging purposes, you can monitor the actions of any handler. Each handler
has its own debugging output to indicate what operations are being performed. To
enable network debugging, turn network tracing on with the line:
trace/net on
To turn network debugging off, use:
trace/net off
Here is an example:
read pop://carl:[email protected]
URL Parse: carl poof zen.example.com none none none
Net-log: ["Opening tcp for" POP]
connecting to: zen.example.com
Net-log: [none "+OK"]
Net-log: {+OK QPOP (version 2.53) at zen.example.com

starting. }
Net-log: [["USER" port/user] "+OK"]
Net-log: "+OK Password required for carl."
Net-log: [["PASS" port/pass] "+OK"]
** User Error: Server error: tcp -ERR Password supplied

for "carl" is incorrect.
** Where: read pop://carl:[email protected]

Network Protocols
Initial Setup
Initial Setup L
REBOL networking is built-in. To create scripts that use the network protocols you
do not need any special include files or libraries. The only requirement is that you
provide the basic information necessary to enable protocols to connect to servers or
through firewalls and proxies. For instance, to send an email, the SMTP protocol
needs an SMTP server name and a reply email address.
Basic Network Settings 0
When you run REBOL the first time, you re prompted for the necessary network
settings, which is stored in the user.r file. REBOL uses this file to load the
required network settings each time it is started. If a user.r is not created and
REBOL cannot find an existing user.r file in its paths, no settings are loaded. See
the chapter on “Operation” for more information.
To change the network settings, type set-user at the prompt. This runs the same
network configuration script that ran when REBOL first started. This script is
loaded from the rebol.r file. If that file cannot be found, or if you want to edit
the setting directly, you can use a text editor on the user.r file.
Within the user.r file the network settings are found in a block that follows the
set-net function. At a minimum the block should contain two items:
■ Your email address for use in the from and reply fields of email and for
anonymous FTP login
■ Your default server; this is also your primary email server
In addition, you can specify a few other items:
■ A different incoming email server (for POP)

■ A proxy server (for connecting to the network)
■ A proxy port number
■ A proxy type (see “Proxy Settings” below).

Network Protocols
Initial Setup
You can also add lines after the set-net function to configure other protocol values.
For instance you can set the timeout values for protocols, set the FTP passive mode,
set the HTTP user-agent identifier, set up separate proxies for different protocols,
and more.
An example of set-net is:
set-net [[email protected] mail.server.dom]
The first field specifies your email from address, and the second field indicates your
default server (notice that it does not need quotes here). For most networks, this is
enough and no other settings are necessary (unless you require a proxy). Also your
default server is used whenever a specific server is not provided.
In addition, if you use a POP server (for incoming email) that is different from your
SMTP server (for outgoing email), you can specify that as well:
set-net [
[email protected]
mail.server.dom
pop.server.dom
]
However, if your SMTP and POP servers are the same, then this is not necessary.
Proxy Settings 0
If you use a proxy or firewall, you can provide the set-net function with your proxy
settings. This can include the proxy server name or address, a proxy port number
to access the server, and an optional proxy type. For example:
set-net [
email@addr
mail.example.com
pop.example.com
proxy.example.com
1080
socks
]

Network Protocols
Initial Setup
This example would use a proxy called proxy.example.com on its TCP port 1080
with the socks proxy method. To use a socks4 proxy server, use the word socks4
rather than socks. To use the generic CERN server, use the word generic.
You can also set the proxy to be different machines for different schemes
(protocols). Each protocol has its own proxy object where you can set the proxy
values for just that scheme. Here is an example of setting a proxy for FTP:
system/schemes/ftp/proxy/host: "proxy2.example.com"
system/schemes/ftp/proxy/port-id: 1080
system/schemes/ftp/proxy/type: 'socks
In this case, only FTP uses a special proxy server. Notice that the machine name
must be a string and the proxy type must be a literal word.
Here are two more examples. The first example sets the proxy for HTTP to be the
generic (CERN) proxy method:
system/schemes/http/proxy/host: "wp.example.com"
system/schemes/http/proxy/port-id: 8080
system/schemes/http/proxy/type: 'generic
In the above example, all HTTP requests go through a generic proxy on

wp.example.com using TCP port 8080.
If you want to disable the proxy settings for a particular scheme, you can set the
proxy fields to false.
system/schemes/smtp/proxy/host: false
system/schemes/smtp/proxy/port-id: false
system/schemes/smtp/proxy/type: false

Network Protocols
Initial Setup
In the above example, all outgoing email does not go through a proxy. The false
value prevents even the default proxy from being used. If you set these fields to
none, then the default proxy is used if it is configured.
If you want to bypass the proxy settings for particular machines, such as those on
your local network, you can provide a bypass list. Here is a bypass list for the
default proxy:
system/schemes/default/proxy/bypass:
["host.example.net" "*.example.com"]
Note that the asterisk (*) and question mark (?) characters can be used for pattern
matching. The asterisk (*) as used in the example above bypasses any machine that
ends with example.com.
To set a bypass list for only the HTTP scheme, type:
system/schemes/http/proxy/bypass:
["host.example.net" "*.example.com"]
Other Settings 0
In addition to proxy settings, you can set network timeout values for all of the
schemes (in the default) or for specific schemes. For instance, to increase the
timeout for all schemes, you can write:
system/schemes/default/timeout: 0:05
This sets the network timeout for 5 minutes.
If you want to increase the timeout just for SMTP, you would write:
system/schemes/smtp/timeout: 0:10
Some schemes have custom fields. For instance, the FTP scheme allows you to set
passive mode for all transfers:
system/schemes/ftp/passive: on

Network Protocols
Initial Setup
FTP passive mode is useful because FTP servers that are set to passive mode do not
attempt to connect back through your firewall.
When making HTTP accesses to Web sites, you may want to use a different
user-agent field in the HTTP request to get better results on a few sites that detect
the browser type:
system/schemes/http/user-agent: "Mozilla/4.0"
Access to Settings 0
Each time REBOL is started, it reads the user.r file to find its network settings.
These settings are made with the set-net function. Scripts have access to these
settings through the system/schemes object.
system/user/email ; used for email from and reply

system/schemes/default/host – your primary server
system/schemes/pop/host – your POP server
system/schemes/default/proxy/host – proxy server
system/schemes/default/proxy/port-id – proxy port
system/schemes/default/proxy/type – proxy type
Below is a function that returns a block containing the network settings in the same
order as set-net accepts them:
get-net: func [][

reduce [
system/user/email
system/schemes/default/host
system/schemes/pop/host
system/schemes/default/proxy/host
system/schemes/default/proxy/port-id
system/schemes/default/proxy/type
]
]
probe get-net

Network Protocols
DNS - Domain Name Service
DNS - Domain Name Service L
DNS is the network service that translates domain names to their associated IP
address. In addition, you can use DNS to find a machine and domain name from
an IP address.
The DNS protocol can be used in three ways: you can lookup the primary IP
address of a machine name, you can lookup the domain name for an IP address,
and you can find the name and IP address of your local system.
To lookup the primary IP address of a specific machine within a specific domain,

type:
print read dns://www.rebol.com
207.69.132.8
You can also obtain the domain name that is associated with a particular IP address:
rebol.com
Note that it is not unusual for this reverse DNS lookup to return a none. There are
machines that do not have host names.
none
To find your system’s host name, read an empty DNS URL of the form:
print read dns://
crackerjack
The data returned here depends on the type of machine. It may be the unqualified
host name, as shown above, but it can also be the fully-qualified host name,
crackerjack.example.com. This depends on the operating system and the
network configuration in the operating system.

Network Protocols
DNS - Domain Name Service
Here’s an example that looks up and prints the IP addresses for a number of Web
sites:
domains: [
www.rebol.com
www.rebol.org
www.mochinet.com
www.sirius.com
]
foreach domain domains [

print ["address for" domain "is:"
read join dns:// domain]
]
address for www.rebol.com is: 207.69.132.8

address for www.rebol.org is: 207.66.107.61
address for www.mochinet.com is: 216.127.92.70
address for www.sirius.com is: 205.134.224.1

Network Protocols
Whois Protocol
Whois Protocol L
The whois protocol retrieves information about domain names from a central
registry. The whois service is provided by the organizations that run the Internet.
Whois is often used to retrieve registration information about an Internet domain
or server. It can tell you who owns the domain, how their technical contact can be
reached, along with other information.
To obtain information, use the read function with a whois URL. This URL should
contain the domain name and a whois server name separated by an at sign (@).
For example to obtain information about example.com from the Internic registry:
connecting to: rs.internic.net
Whois Server Version 1.1
Domain names in the .com, .net, and .org domains can now
be registered with many different competing registrars. Go
to http://www.internic.net for detailed information.
Domain Name: EXAMPLE.COM

Registrar: NETWORK SOLUTIONS, INC.
Whois Server: whois.networksolutions.com
Referral URL: www.networksolutions.com
Name Server: NS.ISI.EDU
Name Server: VENERA.ISI.EDU
Updated Date: 17-aug-1999
>>> Last update of whois database: Sun, 16 Jul 00 03:16:34

EDT <<<
The Registry database contains ONLY .COM, .NET, .ORG, .EDU

domains andRegistrars.
NOTE: The above code is only an example. The details of the information being
returned and the servers that support whois change over time.

Network Protocols
Whois Protocol
If instead of a domain name you provide a word, all entries that match that word
are returned:
connecting to: rs.internic.net
Whois Server Version 1.1
Domain names in the .com, .net, and .org domains can now
be registered with many different competing registrars. Go
to http://www.internic.net for detailed information.
EXAMPLE.512BIT.ORG
EXAMPLE.ORG
EXAMPLE.NET
EXAMPLE.EDU
EXAMPLE.COM
To single out one record, look it up with "xxx", where xxx

is one of the of the records displayed above. If the
records are the same, look them up with "=xxx" to receive
a full display for each record.
>>> Last update of whois database: Sun, 16 Jul 00 03:16:34

EDT <<<
The Registry database contains ONLY .COM, .NET, .ORG, .EDU

domains and Registrars.
NOTE: The whois protocol does not accept URLs, such as www.example.com,
unless the URL is part of the registrant’s company name.

Network Protocols
Finger Protocol
Finger Protocol L
The finger protocol retrieves user-specific information stored in the user log file.
To request user information from a server it must be running the finger protocol.
The information is requested by reading a finger URL that contains a username and
a domain name in an email style format:
The above example retrieves information about the user at [email protected].

The information returned depends on the information provided by the user and the
settings of the finger server. Also, the details of the information being returned are
up to each server; the examples below only describe typical servers. Many servers
can have non-standard behaviors on their finger ports.
For instance, the following information may be returned:
Login: username Name: Firstname Lastname

Directory: /home/user Shell: /usr/local/bin/tcsh
Office: City, State +1 555 555 5555
Last login Wed Jul 28 01:10 (PDT) on ttyp0 from some.exam-
ple.com
No Mail.
No Plan.
Notice that finger reports when the user last logged in from a machine, and whether
the user has mail waiting. If the user reads email from this account, finger
sometimes reports when mail was received and when the user last retrieved email:
New mail received Sun Sep 26 11:39 1999 (PDT)

Unread since Tue Sep 21 04:45 1999 (PDT)
The finger server can also report the contents of a plan file and a project file if
they exist. Users can include any information they want in a plan or project file.
It is also possible to retrieve information about users using their real first name or
their last name. Some finger servers require that you capitalize the names exactly
as they appear in the login file or in the file used by the online finger server, to
retrieve user information. Other finger servers are more liberal about capitalization.

Network Protocols
Daytime - Network Time Protocol
A finger server will respond to real name queries by returning all listings that match
the query criteria. For instance, if there are several users on a host that have the first
name zaphod, then entering the query
will retrieve all such users whose first or last name is Zaphod.
Some finger servers return a listing of users when the user name is omitted. For
example,
print read finger://main.example.com
retrieves a list of all users who are logged onto the machine, if the finger service
installed on the hosting machine allows it.
Some host machines limit finger services for security reasons. They may require a
valid username and only return information regarding that user. If you finger such
a server without providing user information, the server will report that it requires
specific user information.
If a system does not support the finger protocol, REBOL reports an access error:
print read finger://host.dom

connecting to: host.dom
Access Error: Cannot connect to host.dom.
Where: print read finger://host.dom
Daytime - Network Time Protocol L
The daytime protocol retrieves the current day and time. To connect to a daytime
server use read with a daytime URL. The URL contains the name of the server to
read the date from:
print read daytime://everest.cclabs.missouri.edu
Fri Jun 30 16:40:46 2000

Network Protocols
HTTP - Hyper Text Transfer Protocol
The format of the information returned by servers may vary, depending on the
server. Notice that the time zone may not be present.
If the server you choose does not support daytime, REBOL returns an error:
print read daytime://www.example.com
connecting to: www.example.com

** Access Error: Cannot connect to www.example.com.
** Where: print read daytime://www.example.com
HTTP - Hyper Text Transfer Protocol L
The world wide Web is driven by two fundamental technologies: HTTP and HTML.
HTTP is the Hypertext Transfer Protocol that controls how Web servers and Web
browsers communicate with each other. HTML is the Hypertext Markup Language
that defines the structure and contents of a Web page.
To retrieve a Web page, the browser sends a request to a Web server using HTTP.
On receiving the request, the server interprets it, sometimes using a CGI script (see
“CGI - Common Gateway Interface” on page 12-49), and sends back data. This data
can be just about anything, including HTML, text, images, programs, and sound.
Reading a Web Page 0
To read a Web page, use the read function with an HTTP URL. For example:

Network Protocols
This returns the Web page for www.rebol.com. Note that a string that contains
the HTML code for the page is returned by the read. No graphics or other
information are fetched. To do so you would need to provide additional reads. The
page can be displayed as HTML code using print, it can be written to a file with
write, or it can be sent as email using send.
print page
write %index.html page
The page can be processed in a variety of ways by using a variety of REBOL

functions, such as parse, find, and load.
For instance, to search a Web page for all occurrences of the word REBOL, you can
write:
parse read http://www.rebol.com [

any [to "REBOL" copy line to newline (print line)]
]
Scripts on Web Sites 0
A Web server can provide more than just HTML scripts. Web servers are quite
useful for supplying REBOL scripts as well.
You can load REBOL scripts directly from a Web server with load:
data: load http://www.rebol.com/data.r
You can also evaluate scripts directly from a server with do:
data: do http://www.rebol.com/code.r
NOTE: Do this with care. Evaluating arbitrary scripts on open Internet servers is
asking for trouble. Evaluate a script only if you completely trust its source, have
fully inspected its source, or have kept your REBOL security settings on maximum.

Network Protocols
In addition, Web pages that contain HTML can contain embedded REBOL scripts,
and they can be run with:
data: do http://www.rebol.com/example.html
To determine if a script exists on a page before evaluating it, use the script?
function.
if page: script? http://www.rebol.com [do page]
NOTE: The script? function reads the page from the Web site and returns the page at
its REBOL header position.
Loading Markup Pages 0
HTML and XML pages can be quickly converted to a REBOL block with the
load/markup function. This function returns a block that consists of all the tags
and strings found within the page. All spacing and line breaks are left intact.
To filter out all of the tags for a Web page and just print its text, type:
tag-text: load/markup http://www.rebol.com

text: make string! 2000
foreach item tag-text [

if string? item [append text item]
]
print text
You could then search this text for string patterns. It will contain all of the spaces
and line breaks of the original HTML file.

Network Protocols
Here’s another example that checks all links found on a Web page to make sure that
the pages they reference exist:
REBOL []
page: http://www.rebol.com/developer.html
set [path target] split-path page
system/options/quiet: true ; turn off connection msgs
tag-text: load/markup page
links: make block! 100
foreach tag tag-text [ ; find all anchor href tags

if tag? tag [
if parse tag [
"A" thru "HREF="
[{"} copy link to {"} | copy link to ">"]
to end
][
append links link
]
]
]
print links
foreach link unique links [ ; try each link

if all [
link/1 <> #"#"
any [flag: not find link ":"
find/match link "http:"]
][
link: either flag [path/:link][to-url link]
prin [link "... "]
print either error? try [read link]
["failed"]["OK"]
]
]

Network Protocols
Other Functions 0
To check if a Web page exists, use the exists? function, which returns true if the
page exists.
if exists? http://www.rebol.com [
print "page still there"
]
Note: It is usually faster to just read the page rather than checking first to see if it
exists. Otherwise the script must contact the server twice, and that can be time
consuming.
To request the date on which a Web page was last modified, use the modified?
function:
print modified? http://www.rebol.com/developer.html
However, note that not all Web servers provide modification date information.
Dynamically generated Web pages typically do not return a modification date.
Another way to determine if a Web page has changed is poll it every so often and
check it. A handy way to verify that a Web page has changed is by using the
checksum function. If the previously calculated checksum of a Web page differs
from its current value, then the Web page has been modified since it was last
checked. Here is an example that uses this technique. It checks a page every eight
hours.
forever [
page-sum: checksum page
if any [
not exists? %page-sum
page-sum <> (load %page-sum)
][
print ["Page changed" now]
save %page-sum page-sum
]
wait 8:00
]

Network Protocols
Whenever the page changes, it is sent to Luke via email.
Acting Like a Browser 0
Normally, REBOL identifies itself to a server when it reads from a Web site.
However, some servers are programmed to respond to particular browsers only. If
a request to a server does not produce the correct Web page, you can change the
request to make it look like it came from some other type of Web browser.
Pretending to be a Web browser is done by many programs to get Web sites to
respond correctly. However, this practice does end up defeating the purpose behind
the browser identification.
To change HTTP requests to look as though they are being sent by Netscape 4.0,
you can modify the user-agent within the HTTP handler:
system/options/http/user-agent: "Mozilla/4.0"
Setting this variable affects all HTTP requests that follow.
Posting CGI Requests 0
HTTP CGI requests can be posted in two ways. You can include the CGI request
data in the URL or you can provide the request data through an HTTP post
operation.
The URL CGI request uses a normal URL. The example below sends the CGI script
test.r the data value of 10.
read http://www.example.com/cgi-bin/test.r?data=10
The post CGI request requires that you supply the CGI data as part of a custom
refinement to the read function. The example below shows how data is posted to
CGI:
read/custom http://www.example.com/cgi-bin/test.r [
post "data: 10"
]

Network Protocols
SMTP - Simple Mail Transport Protocol
In this example, the /custom refinement is used to provide additional information

to the read. The second argument is a block that begins with the word post and is
followed by the string to send.
The post method is useful for easily sending REBOL code and data to a web server
that runs CGI. The following example illustrates this:
data: [sell 10 shares of "ACME" at $123.45]
read/custom http://www.example.com/cgi-bin/test.r reduce

[
‘post mold data
]
The mold function will produce the proper REBOL string to be sent to the server.
SMTP - Simple Mail Transport Protocol L
The Simple Mail Transport Protocol (SMTP) controls the transfer of email messages
on the Internet. SMTP defines the interaction between Internet hosts that
participate in forwarding email from a sender to its destination.
Sending Email 0
Email is sent through SMTP by using the send function. This function can send an
email message to one or more email addresses.
For send to operate correctly, your networking must be set up. The send function
requires that you specify your email From address and your default email server.
See “Initial Setup” on page 12-9 above.
The send function takes two arguments: an email address and a message. For
example:
send [email protected] "Hi from REBOL"

Network Protocols
The first argument must be an email or block data type. The second argument can
be any data type.
send [email protected] $1000.00
send [email protected] 10:30:40
send [email protected] [email protected]
send [email protected] [Today 9-Apr-99 10:30]
Each of these simple email messages can be interpreted on the receiver's side (with
REBOL) or viewed with a normal email program.
You can send an entire file by reading the file and passing it as the second argument
to the send function:
send [email protected] read %task.txt
Binary data, such as an image or executable file, can also be sent:
send [email protected] read/binary %rebol
The binary data is encoded to allow it to be transferred as text.
To send a self-extracting binary message you can write:
send [email protected] join "REBOL for the job" [

newline "REBOL []" newline
"write/binary %rebol decompress "
compress read/binary %rebol
]
When the message is received, the file can be extracted by using the do function.
Multiple Recipients 0
To send to multiple recipients, you can provide a block of email names:
send [[email protected] [email protected]] message

Network Protocols
In this case, each message is individually addressed with only the recipient's email
name appearing in the To field (similar to BCC addressing).
The block of email addresses can be any size or even a file that you load. Just be
sure that they are valid addresses, not strings. Strings are ignored.
friends: [
[email protected]
[email protected]
[email protected]
[email protected]
...
]
send friends read %newsletter.txt
Bulk Mail 0
If you are sending email to a large group, you can reduce the load on your server
by delivering everyone in the group a single message. This is the purpose of the
/only refinement. It uses a feature of SMTP to send only one message to multiple
email addresses. Using the friends list from the previous example:
send/only friends message
The messages are not individually addressed. You may have seen this mode in some
of the bulk email that you receive. When you receive bulk email, your address does
not appear in the To field.
NOTE: The bulk email mode of SMTP should be used for email lists and not for
sending spam. Spam email is not proper network etiquette, it is illegal in some
countries and states, and spam will get you banned from your ISP and from other
sites.

Network Protocols
Subject Line and Headers 0
By default the send function uses the first line of a message as the subject line. To
provide your own subject line, you need to supply an email header to the send
function. In addition to a subject line, you can provide an organization, date, CC,
and even your own custom fields.
To include a header, use the /header refinement of the send function and include
a header object. The header object must be made from the
system/standard/email object. For example:
header: make system/standard/email [

Subject: "Seen REBOL yet?"
Organization: "Freedom Fighters"
]
Notice that the standard fields, such as the From address, are not required and are
supplied automatically by the send function.
The header is then provided as an argument to send/header:
send/header friends message header
The email above is sent using the custom header for each message.
Debug Your Scripts 0
When testing email scripts, it is advised that you send email to yourself first, before
sending it to others. Examine your test email carefully to make sure that it is what
you want. It is common to have errors such as sending a file name rather than the
file contents. For instance, you might write:
send person %the-data-file.txt
This sends the name of the file, not the file itself.

Network Protocols
POP - Post Office Protocol
POP - Post Office Protocol L
The Post Office Protocol (POP) allows you to fetch email that is waiting in a mail
server mailbox. POP defines a number of operations for how to access and store
email on your server.
Reading Email 0
You can read all of your email in a single line without removing it from the email
server: This is done by reading from a POP URL in which you provided your
username, password, and email host.
mail: read pop://user:[email protected]
The messages are returned as a block of strings which you can handle one message
at a time using code such as:
foreach message mail [print message]
To read individual email messages from the server, you need to open a port
connection to the server and handle each message one at a time. To open the POP
port:
mailbox: read pop://user:[email protected]
In the example, mailbox can be accessed as a series. It responds to many of the

standard series functions, such as length?, first, second, third, pick, next, back,
head, tail, head?, tail?, remove, and clear, .
To determine the number of mail messages residing on the server, use the length?
function.
print length? mailbox
37

Network Protocols
In addition, you can find out the total size of all messages and the individual sizes
of messages with:
print mailbox/locals/total-size
print mailbox/locals/sizes
To display the first, second, and last messages, you can write:
print first mailbox
print second mailbox
print last mailbox
You can also use pick to fetch a specific message:
print pick mailbox 27
You can fetch and display each message from the oldest to the newest using a loop
that is identical to that used for other types of series:
while [not tail? mailbox] [

print first mailbox
mailbox: next mailbox
]
You can also read your email from newest to oldest with a loop such as:
mailbox: tail mailbox
while [not head? mailbox] [

mailbox: back mailbox
print first mailbox
]
When you are done, be sure to close the mailbox. This can be done with a line such
as:
close mailbox

Network Protocols
Removing Email 0
As with series, the remove function can be used to delete a single message, and the
clear function can be used to delete all of the messages from the current position
to the end of the mailbox.
For example, to read a message, save it to a file, and remove it from the server:
mailbox: open pop://user:[email protected]

write %mail.txt first mailbox
remove mailbox
close mailbox
The message is removed from the server when the close is done.
To remove the 22nd email message from the server, you can write:
user:[email protected]
remove at mailbox 22
close mailbox
You can remove a number of messages by using the /part refinement with the
remove function:
remove/part mailbox 5
To remove all of the messages in your mailbox, use the clear function:

clear mailbox
close mailbox
The clear function can also be used at different positions within the mailbox to
remove messages to the end of the mailbox.

Network Protocols
Handling Email Headers 0
Email messages always include a header. The header holds information such as the
sender, recipient, subject, date, and other fields.
In REBOL email headers are handled as objects that contain all of the necessary
fields. To convert email message to a header object you can use the import-email
function. For example:
msg: import-email first mailbox
print first msg/from ; the email address

print msg/date
print msg/subject
print msg/content
You can easily write a filter that scans your email for messages that begin with a
particular subject line:

msg: import-email first mailbox
if find/match msg/subject "[REBOL]" [
print msg/subject
]
mailbox: next mailbox
]
close mailbox

Network Protocols
Here is another example that informs you when email is received from a group of
friends:
friends: [[email protected] [email protected]]
messages: read pop://user:[email protected]
foreach message messages [

msg: import-email message
if find friends first msg/from [
print [msg/from newline msg/content]
send first msg/from "Got your email!"
]
]
This spam filter removes all messages from the server that do not contain your
email name anywhere within the message:

mailbox: either find first mailbox [email protected]
[next mailbox][remove mailbox]
]
close mailbox

Network Protocols
Here is a simple email list server that receives messages and sends them to a group.
The server only accepts email from people in the group.
group: [[email protected] [email protected]]

message: import-email first mailbox
mailbox: either find group first message/from [
send/only group first mailbox
remove mailbox
][next mailbox]
]
close mailbox

Network Protocols
FTP - File Transfer Protocol
FTP - File Transfer Protocol L
The File Transfer Protocol (FTP) is used widely on the Internet for transferring files
to and from a remote host. FTP is commonly used for uploading pages to a Web
site and for providing online file archives.
Using FTP 0
In REBOL FTP file operations are handled in much the same way as local file
operations. Functions such as read, write, load, save, do, open, close, exists?,
size?, modified?, and others are used with FTP. REBOL distinguishes between local
files and files accessible by FTP through the use of an FTP URL.
Access to FTP servers can be open or closed. Open access allows anyone to login
to the site and download files. This is called anonymous access and it is used
frequently for public file archives. Closed access requires that you provide a
username and password to download and upload files. This is the mode of
operation for uploading Web pages to a Web site.
Although FTP does not require your REBOL networking to be configured, if you
wish to use anonymous access, an email address is required. This address is found
in the system/user/email object. Normally, when you boot REBOL, this field
is set from your user.r file. See “Initial Setup” on page 12-9 for more detail.
If you are using FTP through a proxy server or firewall, FTP may need to operate in
passive mode. Passive mode does not require reverse connections from the FTP
server to the client for data transfers. This mode only makes outgoing connections
from your machine and allows a greater level of security. To enable passive mode
you need to set a flag in the FTP protocol handler:
system/schemes/ftp/passive: true
If you do not know if it is necessary, try FTP first without it. If that does not work,
try setting the passive flag.

Network Protocols
FTP URLs 0
An FTP URL has the basic form:
ftp://user:pass@host/directory/file
For anonymous access the username and password can be left out:
ftp://host/directory/file
Most of the examples in this section use this form for simplicity; however, they also
work with a username and password.
To access a remote directory, end the URL with a slash, such as:
ftp://user:pass@host/directory/
ftp://host/directory/
ftp://host/
More about directory access is shown below.
It is convenient to put the URL in a variable and use paths to provide the file names.
This allows you to refer to the URL with just a word. For example:
site: ftp://ftp.rebol.com/pub/
read site/readme.txt
This technique is used in some of the sections that follow.
Transferring Text Files 0
FTP distinguishes between text files and binary files. When transferring text files,
FTP converts the line break characters. This is not desirable for binary files.
To read a text file, supply the read function with an FTP URL:
file: read ftp://ftp.site.com/file.r

Network Protocols
This puts the contents of the file into a string. To write the file locally, use this line:
write %file.r read ftp://ftp.site.com/file.r
Many of the refinements of read can also be used. For instance, you can use
read/lines with:
data: read/lines ftp://ftp.site.com/file.r
This example returns a block of lines for the file. See the “Files” chapter for more
information about the refinements to the read function.
To write a text file to the server, use the write function:
write ftp://ftp.site.com/file.r read %file.r
The write function can also include refinements. See the “Files” chapter.
As with normal text file transfers, all line termination will be properly converted
during FTP transfers.
Here is a simple script that updates files to your Web site:
site: ftp://wwwuser:[email protected]/pages
files: [%index.html %home.html %info.html]
foreach file files [write site/:file read file]
This should not be used for transferring graphics or sound files, as they are binary.
Use the technique shown in “Transferring Binary Files” on page 12-39.
In addition to the read and write functions, you can use the load, save, and do
functions with FTP.
data: load ftp://ftp.site.com/database.r
save ftp://ftp.site.com/data.r data-block
do ftp://ftp.site.com/scripts/test.r

Network Protocols
Transferring Binary Files 0
To avoid the line termination conversion when transferring binary files (images,
archives, executable files), use the /binary refinement. For instance, to read a
binary file from an FTP server:
data: read/binary ftp://ftp.site.com/file
To make a local copy of the file:
write/binary %file read/binary ftp://ftp.site.com/file
To write a binary file to a server:
write/binary ftp://ftp.site.com/file read/binary %file
No line termination conversions are performed.
To transfer a set of graphics files to a Web site, use this script:
site: ftp://user:[email protected]/www/graphics
files: [%icon.gif %logo.gif %photo.jpg]
foreach file files [

write/binary site/:file read/binary file
]
Appending to Files 0
FTP also allows you to append text and data to an existing file. To do so, use the
write/append refinement as described in the “Files” chapter.
write/append ftp://ftp.site.com/pub/log.txt reform

["Log entry date:" now newline]
This can also be used with binary files.
write/binary/append ftp://ftp.site.com/pub/log.txt
read/binary %datafile

Network Protocols
Reading Directories 0
To read the file names of an FTP directory, follow the directory name with a forward
slash:
print read ftp://ftp.site.com/
pub-files: read ftp://ftp.site.com/pub/
The ending forward slash (/) indicates that this is a directory access not a file
access. The forward slash is not always required, but it is recommended when you
know you are accessing a directory.
The block of files that is returned includes all of the files in the directory. Within
that block, directory names are indicated with a forward slash following their
names. For example:
foreach file read ftp://ftp.site.com/pub/ [

print file
]
readme.txt
rebol.r
rebol.exe
library/
docs/
You can also use the dir? function on a file to determine if it is a directory.
File Information 0
The same functions that provide information about files also provide information
about FTP files. This includes the modified?, size?, exists?, dir?, and info?
functions.
You can use the exists? function to determine if a file exists:
if exists? ftp://ftp.site.com/pub/log.txt [
print "Log file is there"
]

Network Protocols
This works for directories too, but include the forward slash at the end of the
directory name:
if exists? ftp://ftp.site.com/pub/rebol/ [
print read ftp://ftp.site.com/pub/rebol/
]
To get the size or modification date for a file:
print size? ftp://ftp.site.com/pub/log.txt
print modified? ftp://ftp.site.com/pub/log.txt
To determine if the file is actually a directory:
if dir? ftp://ftp.site.com/pub/text [
print "It's a directory"
]
You can obtain all this information in a single access by using the info? function:
file-info: info? ftp://ftp.site.com/pub/log.txt
probe file-info
print file-info/size
To perform the same operation on a directory:
probe info? ftp://ftp.site.com/pub/
To print a directory listing:
files: open ftp://ftp.site.com/pub/
forall files [
file: first files
info: info? file
print [file info/date info/size info/type]
]

Network Protocols
Making Directories 0
New FTP directories can be created with the make-dir function:
make-dir ftp://user:[email protected]/newdir/
Deleting Files 0
With appropriate permission settings, files can be deleted from a remote FTP server
by using the delete function:
delete ftp://user:[email protected]/upload.txt
You can also delete directories:
delete ftp://user:[email protected]/newdir/
Note that a directory must be empty for this to succeed.
Renaming Files 0
You can rename a file with the line:
rename ftp://user:[email protected]/foo.r %bar.r
The new name for the file will be bar.r.
FTP also allows you to move a file to a different directory with:
rename ftp://user:[email protected]/foo.r %pub/bar.r
To rename a directory on an FTP site be sure to follow the directory name with a
slash:
rename ftp://user:[email protected]/rebol/ rebol-old/

Network Protocols
About Passwords 0
The above examples include the password within their URLs, but if you plan on
sharing your script, you probably don't want that information to be known. Here's
a simple way to prompt for a password and build the correct URL:
pass: ask "Password? "
data: read join ftp://user: [pass "@ftp.site.com/file"]
Or, you can ask for both the username and password:
user: ask "Username? "

data: read join ftp:// [
user ":" pass "@ftp.site.com/file"
]
You can also open FTP connections by using a port specification rather than a URL.
This allows you to use any password, even ones containing special characters that
are not easily written in URLs. An example of a port specification to open an FTP
connection is:
ftp-port: open [
scheme: ‘ftp
host: "ftp.site.com"
user: ask "Username? "
]

Network Protocols
See “Specifying Network Resources” on page 12-4 above for more detail.
Transferring Large Files 0
Transferring large files requires special considerations. You may want to transfer
the file in chunks to reduce the memory required by your computer and to provide
user feedback while the transfer is happening.
Here is an example that downloads a very large binary file in chunks.
inp: open/binary/direct ftp://ftp.site.com/big-file.bmp

out: open/binary/new/direct %big-file.bmp
buf-size: 200000
buffer: make binary! buf-size + 2
while [not zero? size: read-io inp buffer buf-size][

write-io out buffer size
total: total + size
print ["transferred:" total]
]
Be sure to use the /direct refinement, otherwise the entire file will be buffered
internally by REBOL. The read-io and write-io functions allow reuse of the buffer
memory that has already allocated. Other functions such as copy would allocate
additional memory.
If the transfer fails, you can restart FTP from where it left off. To do so, examine
the output file or the size variable to determine where to restart the transfer. Open
the file again with a custom refinement that specifies restart and the location from
which to start the read. Here is an example of the open function to use when the
total variable indicates the length already read:
inp: open/binary/direct/custom
ftp://ftp.site.com/big-file.bmp
reduce ['restart total]
You should note that restart only works for binary transfers. It cannot be used with
text transfers because the line terminator conversion that takes place will cause
incorrect offsets.

Network Protocols
NNTP - Network News Transfer Protocol
NNTP - Network News Transfer Protocol L
The Network News Transfer Protocol (NNTP) is the basis for tens of thousands of
newsgroups that provide a public forum for millions of Internet users. REBOL
includes two levels of support for NNTP.
The built-in support for NNTP that provides very limited functionality and access.
This is the NTTP scheme.
An extended level of functionality that is provided by the news scheme that is

implemented in the file distributed as nntp.r.
Reading the Newsgroup List 0
NNTP consists of two components: a list of newsgroups supported by a specific

newsgroup server (newsgroups are typically selected by an Internet service
provider); and, a database of messages that are currently available for any particular
newsgroup.
To retrieve the list of all newsgroups from a specific news server, use the read
function with an NNTP URL such as:
groups: read nntp://news.example.com
This may take a while, depending on your connection; there are thousands of
newsgroups.
Reading All Messages 0
If you are using a fast connection, you can read all of the pending messages for a
newsgroup with:
messages: read nntp://news.example.com/alt.test
However, caution is advised. Some newsgroups can have thousands of messages.

It can take a long time to download all the messages, and you may run out of
memory to hold them.

Network Protocols
Reading Single Messages 0
To read single messages, open NNTP as a port and use series functions to access
messages. This is similar to how you read email from a POP port. For example:
group: open nntp://news.example.com/alt.test
You can use the length? function to determine the number of messages that are
available in the newsgroup:
print length? group
To read the first message available in the newsgroup, use first:
message: first group
To select a specific message in the group by index, use pick:
message: pick group 37
To create a simple loop that scans all messages for a keyword, use:
forall group [
if find msg: first first group "REBOL" [
print msg
]
]
Remember that when the loop returns, the group series is positioned to the tail. If
you need to return to the head of the group:
group: head group
Be sure to close a port once you are done using it:
close group

Network Protocols
Handling News Headers 0
News messages always include a header. The header holds information such as the
sender, summary, keywords, subject, date, and other fields.
Headers are handled as objects. To convert a news message to a news header object
you can use the import-email function. For example:
message: first first group

header: import-email message
You can now access the fields of the news message:
print [header/from header/subject header/date]
Different newsgroups and newsgroup clients use different fields in their header. To
view the fields available for a specific message display the first item of the header
object:
print first header
Sending a News Message 0
Before you can send a news message, you need to create a header for it. Here is a
generic header that can be used for news:
news-header: make object! [

Path: "not-for-mail"
Sender: Reply-to: From: system/user/email
Subject: "Test message"
Newsgroups: "alt.test"
Message-ID: none
Organization: "Docs For All"
Keywords: "Test"
Summary: "A test message"
]

Network Protocols
Before you can send it, you need to create a unique global identification number for
it. Here is a function that does that:
make-id: does [
rejoin [
"<"
system/user/email/user
"."
checksum form now
"."
random 999999
"@"
read dns://
">"
]
]
print news-header/message-id: make-id
<[email protected]>
Now you can combine the header with the message. They must be separated by at
least one blank line. The content of the message is read from a file.
write nntp://news.example.net/alt.test rejoin [

net-utils/export news-header
newline newline
read %message.txt
newline
]
NOTE: Keep in mind that whenever you post to newsgroups you may get spammed
by news crawlers that use newsgroups as a source for valid email addresses.

Network Protocols
CGI - Common Gateway Interface
CGI - Common Gateway Interface L
The common gateway interface is used with many Web servers to provide
processing beyond the normal HTTP Web interface. CGI requests are submitted
from Web browsers to Web servers. When a server receives a CGI request, it
typically executes a script to process the request and return a result to the browser.
These CGI scripts can be written in a variety of languages, and REBOL provides one
of the easier ways of handling CGI.
CGI Server Setup 0
Setting up CGI access is different for every Web server. See the instructions
provided with your server.
Typically a server has an option for enabling CGI operation. You need to enable this
option and provide a path to the directory where your CGI scripts reside. A common
directory for CGI scripts is in cgi-bin.
On Apache servers, the ExecCGI option enables CGI scripts, and you can provide
a directory (cgi-bin) for your scripts. This is normally set up by default
installation of Apache.
To configure CGI for Microsoft IIS, go to the properties for cgi-bin and click on the
configuration button. On the configuration panel click add and enter the path to
your rebol.exe file. The format for this is:
C:\rebol\rebol.exe -cs %s %s
The two %s symbols are required for correctly passing the script and command line
arguments to REBOL. Add the extension for REBOL files (.r) and set the last field
to PUT, DELETE. The script engine does not need to be selected.
The –cs option that is provided to REBOL enables CGI operation and allows the
script to access all files. (!!See notes below on how scripts can limit file access to
selected directories).
With Web servers other than those described above, the server requires
configuration to execute the REBOL executable for .r extension files and run
REBOL with the required option -cs.

Network Protocols
CGI Scripts 0
Before a script can be executed on most CGI servers, it needs to have the correct file
permissions. On UNIX-type systems or those that use the Apache server you need
to change the permissions to enable the script to be readable and executable by all
users. This can be done with the chmod function. If you are new to this concept,
you should read your operating system manual or talk with your system
administrator before changing file permissions.
For Apache and various other Web servers to run REBOL scripts, you need to
provide the correct header at the top of each script file. The header specifies the
path to the REBOL executable file and the -cs option. This can be followed by the
normal REBOL script header. Here is a simple CGI script that prints the string,
hello!.
#!/path/to/rebol -cs
REBOL [Title: "CGI Test Script"]
print "Content-Type: text/plain"
print "" ; required
print "Hello!"
There are many things that prevent a CGI script from running correctly. Get this
simple script working first before you try more complex scripts. If your script does
not work, here are a few items to check:
You have CGI enabled on your Web server.
The first line begins with a #! and the correct path to REBOL.
The –cs option is supplied to REBOL.
The script begins with “Content-Type:” being printed. (!!see below)
The script is in the correct directory. (normally the cgi-bin directory)
The script has the correct file permissions (readable and executable by all).

Network Protocols
The script contains the correct line break characters. Some servers do not run
scripts that contain the CR character for line breaks. You may need to convert the
file. (Use REBOL to do this in one line: write file, read file).
The script does not contain errors. Test it without CGI to make sure that the script
loads (does not have syntax errors) and functions properly. Provide some sample
data and test it.
All files that are accessed by the script have the correct file permissions.
Often one or more of the above items is wrong and prevent your script from
running. You may see an error when viewing the Web page. If it says “Server Error”
or “CGI Error” then it is typically something to do with the permissions or setup of
the script. If it shows a REBOL error message, then the script is running, but you
have an error within the script.
In the example script shown above, the Content-Type line is critical. It is part of
the HTTP header that is returned to the browser, and it tells the browser the type of
content being delivered. This is followed by a blank line to separate it from the
actual content.
Many different types of content can be delivered. The previous example was plain
text, but you can also deliver HTML as is shown in the next example. (See your
Web server manual for more information about content types.)
The content type and blank line can be combined into a single line. The caret
forward slash (^/) symbol provides an additional line break to separate it from the
content.
print "Content-Type: text/plain^/"
It is a good practice to always print this line immediately from your script. This
allows error messages to be seen by the browser if your script encounters an error.

Network Protocols
Here is a simple CGI script that prints the time:
REBOL [Title: "Time Script"]
print ["The time is now" now/time]
Generating HTML Content 0
There are as many ways to create HTML content as there are ways to create strings.
This page creates a page that displays a page hit counter:
REBOL [Title: "HTML Example"]
print "Content-Type: text/html^/"
count: either exists? %counter [load %counter][0]

save %counter count: count + 1
print [
{<HTML><BODY><H2>Web Counter Page</H2>
You are visitor} count {to this page!<P>
</BODY></HTML>}
]
The script in the example above loads and saves to a counter text file. For this file
to be accessible, it will require the appropriate permissions be set to allow access
by all users.

Network Protocols
CGI Environment 0
When a CGI script is run the server provides information to REBOL about the CGI
request and its arguments. All of this information is provided as an object within
the system/options object. To view the fields of the object, type:
probe system/options/cgi
make object! [
server-software: none
server-name: none
gateway-interface: none
server-protocol: none
server-port: none
request-method: none
path-info: none
path-translated: none
script-name: none
query-string: none
remote-host: none
remote-addr: none
auth-type: none
remote-user: none
remote-ident: none
Content-Type: none
content-length: none
other-headers: []
]
Of course, your script will ignore most of this information, but some of it could be
of use. For instance, you may want to create a log file that records the network
address of the system that made the request, or check the type of browser being
used.

Network Protocols
To generate a CGI page that displays this content in your browser:
REBOL [Title: "Dump CGI Server Variables"]
print "Server Variables:"
probe system/options/cgi
If you want to use this information in a log, you can write it to a file. For example,
to log the addresses of visitors to your CGI page you could write:
write/append/lines %cgi.log
system/options/cgi/remote-addr
The /append and /lines refinements causes the write to be at the tail of the file and
include a line-break. Here’s another approach that puts multiple items on the same
line:
write/append %cgi.log reform [

system/options/cgi/remote-addr
system/options/cgi/remote-ident
system/options/cgi/content-type
newline
]
CGI Requests 0
There are two methods for CGI to provide request data to your scripts: GET and
POST.
The GET method encodes CGI data into the URL. This is used to provide
information to the server. You may have noticed before that some URLs look like
this:
http://www.example.com/cgi-bin/test.r?&data=test

Network Protocols
The string that follows the question mark (?) provides the arguments to CGI. At
times they can be quite long. This string is provided to your script when it is run.
It can be obtained from the cgi/query-string field. For instance, to print the
string from a script:
print system/options/cgi/query-string
The data within the string can include whatever data you require. However,
because the string is part of a URL, data must be encoded. There are restrictions
on the characters that are allowed.
In addition, when the data is created by HTML forms, it is encoded in a standard

way. This data can be decoded and placed within an object with the code:
cgi: make object! decode-cgi-query

system/options/cgi/query-string
The decode-cgi-query function returns a block that contains variable names

and their values. See the HTML form example in the next section.
The POST method provides the CGI data as a string. The data does not need to be
encoded. It can be in any format you desire and can even be binary. Post data is
read from the standard input device. You will need to read it from the input with a
line such as:
data: make string! 2002

read-io system/ports/input data 2000
This would read up to the first 2000 bytes of POST data and put it in a string.
A good format for POST data is to use a REBOL dialect and create a simple parser.
The POST data can be loaded and parsed as a block. See the “Parsing” chapter.
WARNING: It is not a good idea to pass REBOL blocks that are directly evaluated
because this can present a security risk. For instance, someone could POST a block
that reads or deletes your files.

Network Protocols
Here is an example script that displays the post data in your browser:
REBOL [Title: "Show POST data"]

data: make string! 10000
foreach line copy system/ports/input [
repend data [line newline]
]
print [
<HTML><BODY>
{Here is the posted data.}
<HR><PRE>data</PRE>
</BODY></HTML>
]
Processing HTML Forms 0
CGI is often used for processing HTML forms. The forms accept input from various
fields and submit them to the Web server as an HTML get or post method.
Here is an example that uses the CGI get to process a form and send an email as the
result. There are two parts to this: the HTML page and the CGI script.

Network Protocols
Here is an HTML page that includes a form:
<HTML><BODY>
<FORM ACTION="http://example.com/cgi-bin/send.r"
METHOD="GET">
<H1>CGI Emailer</H1><HR>
Enter your email address:<P>
<INPUT TYPE="TEXT" NAME="email" SIZE="30"><P>
<TEXTAREA NAME="message" ROWS="7" COLS="35">

Enter message here.
</TEXTAREA><P>
<INPUT TYPE="SUBMIT" VALUE="Submit">
</FORM>
</BODY></HTML>

Network Protocols
When the above script is submitted, it needs a CGI script to handle its results. Here
is an example of such a script. This example script decodes the form data and sends
the email. It returns a confirmation page.
REBOL [Title: "Send CGI Email"]
cgi: make object! decode-cgi-query

system/options/cgi/query-string
print {<HTML><BODY><H1>Email Status</H1><HR><P>}
failed: error? try [send to-email cgi/email cgi/message]
print either failed [

{The email could not be sent.}
][
[{The email to} cgi/email {was sent.}]
}
print {</BODY><HTML>}
This script should be named send.r and stored in the cgi-bin directory. It’s
permissions must be set to being readable and executable by all.
When the form has been submitted by a browser, this script will run. It decodes
the CGI query string into a cgi object. The object now has email and message
variables that are used for the send function. Before send is done, the email field
is converted from a string to an email datatype.
The send function is placed within a try block to catch errors if they occur while
sending the email. The failed variable is set to true if an error occurred, and the
appropriate message is generated.
Other CGI examples can be found in the REBOL Script Library at

http://www.rebol.com/library/library.html

Network Protocols
TCP - Transmission Control Protocol
TCP - Transmission Control Protocol L
In addition to those protocols previously described, you can create your own
network servers and clients with the transmission control protocol, TCP.
Creating Clients 0
TCP ports can be opened in the same way as other REBOL protocols, using the TCP
URL. To open a TCP connection to an HTTP (Web) server on TCP port number 80:
http-port: open tcp://www.example.com:80
Another way of opening a TCP connection is to provide the port specification

directly. This is a substitute for using a URL and is often quite useful:
http-port: open [
scheme: 'tcp
host: "www.example.com"
port-id: 80
Since ports are series, you can use the same series functions for sending and
receiving data. The example below queries the HTTP server opened in the previous
example. It uses the insert function to put data into the port series which sends it
to the server:
insert http-port join "GET / HTTP/1.0^/^/"
The two newline characters are used to tell the sever that the header has been sent.
NOTE: The newline characters are automatically converted to CR LF sequences

because the port was opened in text mode.
The server processes the HTTP request and returns a result to the port series. To
read the result, use the copy function:
while [data: copy http-port] [prin data]

Network Protocols
This loop will continue to fetch data until a none is returned from copy. This
behavior differs between protocols. A none is returned because the server closes
the connection. Other protocols may send a special character to indicate the end of
the transfer.
Now that all the data has been received, HTTP port should be closed:
close http-port
Here is another example that connects to a POP port on a server:
pop: open/lines tcp://fred.example.com:110
This example uses the /lines refinement. The connection will now be line oriented.
Data will be written and read as lines. To read the first line from the server:
print first pop
+OK QPOP (version 2.53) at fred.example.com starting.
To send the server a username for POP login:
insert pop "user carl"
Because the port is operating in line mode, a line terminator is sent after the insert.
The server response can be read with with:
print first pop
+OK Password required for carl.

Network Protocols
And the rest of the communication would proceed as:
insert pop "pass secret"
print first pop
+OK carl has 0 messages (0 octets).
insert pop "quit"
first pop
+OK Pop server at fred.example.com signing off.
The connection should now be closed:
close pop
Creating Servers 0
To create a server you need to wait for connections and respond to them as they
occur. To set up a port on your machine that can be used to wait for incoming
connections:
listen: open tcp://:8001
Notice that you do not supply a host name, only a port number. This type of port is
called a listen port. The system now accepts connections on port number 8001.
To wait for a connection from another machine, you wait on the listen port.
wait listen
This function does not return until a connection has been made.
NOTE: There are other options available for wait. For instance, you can wait on
multiple ports or for a timeout as well.

Network Protocols
You can now open the connection port from the machine that has contacted your
system:
connection: first listen
This returns the connection that has been made to the listen port. It is a port like
all others and can now be used to receive and send data using the insert, copy, first,
and other series functions:
insert connection "you are connected^/"
while [newline <> char: first connection] [

print char
]
When the communications is complete, the connection should be closed:
close connection
You are now ready for the next connection on the listen port. You can wait again
and use first again to get the connection.
When you are done with serving, you can close the listen port with:
close listen

Network Protocols
A Tiny Server 0
Here is a useful REBOL server that only requires a few lines of code. This server
evaluates whatever REBOL code is sent to it. Lines of REBOL are read from the
client until an error occurs. Each line must be a complete REBOL expression. They
can be of any length but must be a single line.
server-port: open/lines tcp://:4321
forever [
connection-port: first server-port
until [
wait connection-port
error? try [do first connection-port]
]
close connection-port
]
close server-port
If an error occurs, the connection is closed and the server waits for the next
connection.
Here is an example of a client script that allows you to enter REBOL command lines
remotely:
server: open/lines tcp://localhost:4321

until [error? try [insert server ask "R> "]]
close server
Here the query is used to determine if the connection was been closed due to an
error.

Network Protocols
Testing TCP Code 0
To test your server code, connect from your own machine, rather than requiring
both a server and a client. This can be done from two separate REBOL processes
or even from the same process.
To connect to your local machine, you can use a line such as:
port: open tcp://localhost:8001
Here is an example that makes two ports connect to each other in line mode. This
is a sort of echo port since you're sending data to yourself. It provides a good test of
your code and networking:
listen: open/lines tcp://:8001

remote: open/lines tcp://localhost:8001
local: first listen
insert local "How are you?"
print first remote ; response
close local
close remote
close listen
UDP (User Datagram Protocol) 0
The User Datagram Protocol is another transport layer protocol that provides a
connectionless method of communicating between machines. It allows you to send
datagrams, packets, between machines.
The operation of UDP is much different than TCP. UDP is simpler, but it is
essentially unreliable. There is no guarantee that a packet will ever reach its
destination. In addition, UDP has no flow control. If you send messages too
quickly, packets may be lost.
Like TCP, the wait function can be used to wait for the next packet to arrive and the
copy function is used to return the data. If there is no data, copy waits until there
is. Note, however, that insert never waits.

Network Protocols
Here is an example of a simple UDP server script:
udp: open udp://:9999

wait udp
print copy udp
insert udp "response"
close udp
The messages inserted here by the server are sent to the client the server last
received a message from. This allows responses to be sent for incoming messages.
However, unlike TCP you do not have a continuous connection between the
machines. Each packet transfer is a separate exchange.
The client script to communicate with the above server would be:
udp: open udp://localhost:9999

insert udp "Test"
wait udp
print copy udp
close udp
You should know that the maximum UDP packet size depends on the operating
system. 32 KB and 64 KB are common values. In order to send larger amounts of
data, you will need to buffer the data, chopping it into smaller pieces. However,
careful programming is required to make sure that each piece of the data is received.
Remember that with UDP, there are no guarantees.

Network Protocols

13
Ports
This chapter explains the types of ports and how they are manipulated within
REBOL/Core. It includes the following information:

■ “Opening a Port” on page 13-3
■ “Closing a Port” on page 13-4
■ “Reading from a Port” on page 13-5

■ “Writing to a Port” on page 13-6
■ “Updating a Port” on page 13-7
■ “Waiting for a Port” on page 13-7

■ “Other Port Modes” on page 13-9
■ “File Permissions” on page 13-12
■ “Directory Ports” on page 13-13
13- 1
Ports
Overview
Overview M
Ports access external series such as files, networks, consoles, events, databases, data
encoders, and data decoders. Port data is processed using the standard REBOL
series functions as described in the “Series” chapter.
Ports are used for both input and output. The type of data a port handles depends
on how the port is opened. Three types of data are possible:
Table 13-1. Port Data Types
Data Type Description
String a series of bytes, converts line breaks (default)

Binary a series of bytes, no conversion of the data
Block a series of REBOL values
A port can be opened in one of two buffering modes:

Table 13-2. Port Buffering Modes
Buffering Mode Description
Buffered all of the data is held in memory (default)

Direct data is not held in memory
In addition, a port can be opened with:

Table 13-3. Wait Options
Wait Option Description
Wait port will wait for data (default)

Nowait port will not wait for data

Ports
Opening a Port
Opening a Port M
The open function initializes access to a port according to specified parameters. The
function can be supplied with a filename, a URL, or an object. In addition, there
are several refinements that will affect the open operation or the access to the port’s
data.
The simplest method of using open is to provide it with a filename or URL as its
argument. In the example below, a file port is opened:
fp: open %file.txt
The fp variable refers to the port. If the port did not open, an error will occur.
If necessary, the error can be caught with the try function.
By default the file is opened as buffered. This means that the file is accessed and
modified in memory and changes to the file are not written out until the port is
closed or updated.
For files, the open function will automatically create the file if it does not already
exist.
close open %somefile.txt

if exists? %somefile.txt [print "somefile exists"]
somefile exists
The /new refinement can be used to overwrite an existing file.
write %somefile.txt "text in some file"

print read %somefile.txt
text in some file
close insert open/new %somefile.txt "new data"

print read %somefile.txt
new data

Ports
Closing a Port
Once a port is open, the series operations such as copy, insert, remove, clear, first,
next, and length? can be used to access and change the contents the port.
Open Refinements 0
The open function accepts a number of refinements that can be used to modify its
operation:
Table 13-4. Open Refinements
/binary port data is binary

/string port data is text, translate all line terminators
/with specify an alternate line termination
/lines handle data a line at a time or as a block of lines
/direct do not buffer the port
/new create or recreate the target of the port
/read open for read only operation
/write open for write only operation
/nowait do not wait for data
/skip skip part of the data
/allow specify protection attributes of files
/custom allow special refinements
Closing a Port M
Access to a port is terminated with the close function. All buffered data that has
not been saved will be written to the target file. The example below will close a
port opened earlier:
close fp

Ports
Reading from a Port
If you attempt to close a port that is not open, an error will occur.
A port that is closed can be reopened again with the open function:
open fp
Reading from a Port M
The series copy function is used to read data from an open port:
print copy fp

...
This function will wait for the port data. If you don’t want to wait for the data, open
the port with the /nowait refinement.
To read only a portion of the port data, use copy/part:
print copy/part fp 35
Note that the second argument to copy can be a length or a position within the port.
You can use the series find and copy functions to read just part of the port’s data:
a: find fp "famine"
print copy/part a find a newline
famine or scurvy -- I fought it;

Ports
Writing to a Port
The first, next, and other positional series functions can also be used on the port:
print first fp
print first next next fp
The copy function will return none when all data have been read from a port.
When running in /nowait mode, the copy function will return an empty string if no
data is available for the port.
tp: open/direct/binar/nowait tcp://system:8000

content: make binary! 1000
while [wait tp data: copy tp] [append content data]
close tp
Writing to a Port M
The insert function is used to write to a port.
insert fp "I was a fool to seek it."
If the port is buffered, the change will occur externally when the port is closed or
updated (with the update function). If the port is opened with /direct, then the
change will occur immediately.
All of the insert refinements can be used on the port. For example, to write 20
spaces into a port:
insert/dup fp " " 20
You can also use the remove, clear, change, append, replace, and other series
modifying functions on the port.

Ports
Updating a Port
For example, to remove a single character or a number of characters:
remove fp
remove/part fp 20
and to remove all remaining characters, write:
clear fp
Updating a Port M
The update function forces a port to update its status with respect to the external
device. For example, when writing a buffered file, the update function can be used
to force the data buffer out to the file. When reading, the update function can be
used to be certain that any pending data has been read into memory.
update fp
Waiting for a Port M
The wait function is essential to programs that need to handle asynchronous data
transfers. With wait, you can wait for data on one or more ports, or for a timeout
to occur.
The wait function will accept a single port:
wait port
or, an entire block of ports can be provided:
wait [port1 port2 port3]

Ports
Waiting for a Port
In addition, a timeout value can be provided as a number of seconds or as a time

value:
wait [port1 port2 10]
wait [port1 port2 0:00:05]
The first example will time out in ten seconds. The second example will timeout in
five minutes.
The wait function will return the port that is ready or none if the timeout occurred.
ready: wait [port1 port2 10]

if ready [data: copy ready]
The above example will read data from the first ready port if a timeout did not occur.
To obtain a block of all ports that are ready, use the /all refinement.
ready: wait/all [port1 port2 10]

if ready [
foreach port ready [
append data copy port
]
]
This example would append data from all ready ports into a single series.

Ports
Other Port Modes
You can also use the dispatch function to evaluate a block or function based on the
results of a wait on multiple ports.
dispatch [
port1 [print "port1 awake"]
port2 [print "port2 awake"]
10 [print "timeout!"]
]
NOTE: To use wait with most ports, you will need to specify the /nowait and /direct
refinements as part of the open. This indicates that the normal data access
functions should not block and that data is not buffered.
port1: open/nowait/direct tcp://system:8000
Other Port Modes M
Line Mode 0
The open function allows ports to be opened for line access. In line mode, the first
function will return a line of text, rather than a character. The example below reads
a file one line at a time:
fp: open/lines %file.txt

print first fp
print third fp
The /lines refinement is also useful for Internet protocols that are line oriented.
tp: open/lines tcp://server:8000

print first tp

Ports
Other Port Modes
Read and Write Only 0
You can use the /read refinement to open a port as read only:
fp: open/read %file.txt
Changes made to the port’s buffer, are not written back to the file.
To open for write only, use the /write refinement:
fp: open/write %file.txt
File ports opened with the /write refinement will not read the current data upon
opening the port.
Closing, or updating a write only file port will cause existing data in the file to be
overwritten:
insert fp "This is the law of the Yukon..."

close fp
print read %file.txt
This is the law of the Yukon...
Direct Port Access 0
The /direct refinement opens an unbuffered port. This is useful to access files a
portion at a time, such as when a file is too large to be held in memory.
fp: open/direct %file.txt
Reading the data with a copy function will move the port’s head forward:
I wanted the gold, and I sought it,^/ I
scrabbled and mucked like a slave.^/Was i

Ports
Other Port Modes
In direct mode, the port will always be at its head position:
print head? fp
true
The copy function will return none when the port has reached its end.
Here is an example that uses direct ports to copy a file of any size:
from-port: open/direct %a-file.jpg

to-port: open/direct %a-file.jpg
while [data: copy/part from-port 100000 ][
append to-port data
]
close from-port
close to-port
Skipping Data 0
There are two ways to skip data that exists in a port. First, you can open the port
with the /skip refinement. This open function will automatically skip to a point in
the port. For example:
fp: open/direct/skip %file.big 1000000
fp: open/skip http://www.example.com/bigfile.dat 100000
You can also use the skip function on the port. For files that are opened with /direct
and /binary the skip operation is identical to a file system seek operation. Data is
not read into memory. This is not possible in /string mode because the line breaks
interfere with the skip size.
fp: open/direct/binary %file.dat

fp: skip fp 100000

Ports
File Permissions
File Permissions M
When files are created by REBOL, default access permissions are set. On Windows
and Macintosh systems files are created with full access privileges. On UNIX
systems files are created with the permissions set to the current umask setting.
When using open or write to access a file the /allow refinement is used to set file
access permissions.
The /allow refinement takes a block as an argument. This block can consist of any
or all of the three words read, write and execute.
NOTE: The /allow refinement will only set permissions on operating systems
supporting the specified permission setting. If the operating system does not
support a permission setting used, the setting will be ignored. For instance, files on
UNIX systems may be set as executable (execute), but the Windows and Macintosh
operating systems don’t support this. When dealing with UNIX systems,
permissions set using /allow will only set the user permissions. Using / allow will
cause all access permissions to be removed for users and others.
To make a file read only, use open/allow, or write/allow with a read block.
write/allow %file.txt [read]
To make a file readable and executable:
open/allow %file.txt [read execute]
You can set similar permissions for write access:
write/allow %file.txt [read write]
To prevent any access to a file (for operating systems where this would make a
difference) provide an empty permissions block:
write/allow %file.txt []

Ports
Directory Ports
To permit full access:
write/allow %file [read write execute]
Directory Ports M
Directory ports allow you to open direct access to file directories. Within the
system, this is how most other directory functions are created.
When you open a directory, you gain direct access to the directory as a block of
filenames:
mydir: open %intro/

forall mydir [print first mydir]
CVS/
history.t
intro.t
overview.t
quick.t
close mydir
You can advance to a specific position within a directory series and remove a file
with code such as:
dir: open %.
remove next dir
close dir
This deletes the second file in the current directory. Similarly,
remove at dir 5
would delete the fifth file in the directory, and:
clear dir
would delete all of the files in the directory.

Ports
Directory Ports
To delete all files that contain with the word “junk”, you can write:
dir: open %intro/

while [not tail? dir] [
either find first dir "junk" [remove dir][
dir: next dir
]
]
close dir
The changes made to a directory are made when the directory is closed or when it
is updated. To force the action to occur immediately use a line such as:
update dir
The method of directory access can also be used for changing the names of files.
After the open, the line:
change at dir 3 %newname.txt
will rename the third file in the directory. Similarly, the names of any of the files in
the directory can be changed.
Here is an example that renames all of the files in a directory by adding the word
REBOL to their names:
dir: open %intro/

forall dir [insert first dir "REBOL"]
close dir

14
Parsing
This chapter describes the features of parse within REBOL/Core. It includes the
following information:

■ “Simple Splitting” on page 14-2
■ “Grammar Rules” on page 14-4
■ “Skipping Input” on page 14-7

■ “Match Types” on page 14-8
■ “Recursive Rules” on page 14-10
■ “Evaluation” on page 14-10

■ “Dealing with Spaces” on page 14-19
■ “Parsing Blocks and Dialects” on page 14-21
■ “Summary of Parse Operations” on page 14-26
14- 1
Parsing
Overview
Overview N
Parsing splits a sequence of characters or values into smaller parts. It can be used
for recognizing characters or values that occur in a specific order. In addition to
providing a powerful, readable, and maintainable approach to regular expression
pattern matching, parsing enables you to create your own custom languages for
specific purposes.
The parse function has the general form:
parse series rules
The series argument is the input that is parsed and can be a string or a block. If
the argument is a string, it is parsed by character. If the argument is a block, it is
parsed by value.
The rules argument specifies how the series argument is parsed. The rules
argument can be a string for simple types of parsing or a block for sophisticated
parsing.
The parse function also accepts two refinements: /all and /case. The /all
refinement parses all the characters within a string, including all delimiters, such as
space, tab, newline, comma, and semicolon. The /case refinement parses a string
based on case. When /case is not specified, upper and lower cases are treated the
same.
Simple Splitting N
A simple form of parse is for splitting strings:
parse string none

Parsing
Simple Splitting
The parse function splits the input argument, string, into a block of multiple
strings, breaking each string wherever it encounters a delimiter, such as a space,
tab, newline, comma, or semicolon. The none argument indicates that no other
delimiters other than these. For example:
probe parse "The trip will take 21 days" none
["The" "trip" "will" "take" "21" "days"]
Similarly,
probe parse "here there,everywhere; ok" none
["here" "there" "everywhere" "ok"]
In the example above, notice that the commas and semicolons have been removed
from the resulting strings.
You can specify other delimiters in the second argument to parse, which are
combined with the default delimiters (space, tab, newline, comma, semicolon).. For
example, the following code parses a telephone number adding dash (-) to the
delimiters:
probe parse "707-467-8000" "-"
["707" "467" "8000"]
The next example adds equal (=) and double quote (“) to the to the delimiters:
probe parse <IMG SRC="test.gif" WIDTH="123"> {="}
["IMG" "SRC" "test.gif" "WIDTH" "123"]
To disable the default delimiters, use the /all refinement. With the /all refinement,
only the delimiters passed in the second argument are used.

Parsing
Grammar Rules
The next example parses a string based on commas only; any other delimiters are
ignored. Consequently, the spaces within the strings are not removed:
probe parse/all "Harry, 1011 Main St., Ukiah" ","
["Harry" " 1011 Main St." " Ukiah"]
You can parse strings that contain null characters as separators (such as certain
types of data files):
parse/all nulled-string "^(null)"
Grammar Rules N
The parse function accepts grammar rules that are written in a dialect of REBOL.
Dialects are sub-languages of REBOL that use the same lexical form for all data
types, but allow a different ordering of the values within a block. Within this dialect
the grammar and vocabulary of REBOL is altered to make it similar in structure to
the well known BNF (Backus-Naur Form) which is commonly used to specify
language grammars, network protocols, header formats, etc.
To define rules, use a block to specify the sequence of the inputs. For instance, if
you want to parse a string and return the characters "the phone", you can use
a rule:
parse string ["the phone"]
To allow any number of spaces or no spaces between the words, write the rule like
this:
parse string ["the" "phone"]
You can indicate alternate rules with a vertical bar (|). For example:
["the" "phone" | "a" "radio"]
accepts strings that match any of the following:
the phone
a radio

Parsing
Grammar Rules
A rule can contain blocks that are treated as sub-rules. The following line:
[ ["a" | "the"] ["phone" | "radio"] ]
a phone
a radio
the phone
the radio
For increased readability, write the sub-rules as a separate block and give them a
name to help indicate their purpose:
article: ["a" | "the"]

device: ["phone" | "radio"]
parse string [article device]
In addition to matching a single instance of a string, you can provide a count or a

range that repeats the match. The following example provides a count:
[3 "a" 2 "b"]
which accepts strings that match:
aaabb
The next example provides a range:
[1 3 "a" "b"]
which accepts strings that match any of the following:
ab aab aaab
The starting point of a range can be zero, meaning that it is optional.
[0 3 "a" "b"]

Parsing
Grammar Rules
b ab aab aaab
Use some to specify that one or more characters are matched. Use any to specify
that zero or more characters are matched. For example, some used in the following
line:
[some "a" "b"]
accepts strings that contain one or more characters a and b:
ab aab aaab aaaab
The next example uses any:
[any "a" "b"]
which accepts strings that contain zero or more characters a or b:
b ab aab aaab aaaab
The words some and any can also be used on blocks. For example:
[some ["a" | "b"]]
accepts strings that contain any combination of the characters a and b.
Another way to express that a character is optional is to provide an alternate choice

of none:
["a" | "b" | none]
This example accepts strings that contain a or b or none.
The none is useful for specifying optional patterns or for catching error cases when
no pattern matches.

Parsing
Skipping Input
Skipping Input N
The skip, to, and thru words allow input to be skipped.
Use skip to skip a single character, or use it with a repeat to skip over multiple
characters:
["a" skip "b"]

["a" 10 skip "b"]
["a" 1 10 skip "b"]
To skip until a specific character is found, use to:
["a" to "b"]
The previous example starts parsing at a and ends at b but does not include b.
To include the ending character, use thru:
["a" thru "b"]
The previous example starts parsing at a, ends at b, and includes b.
The following rule finds the title of an HTML page and prints it:
page: read http://www.rebol.com/

parse page [thru <title> copy text to </title>]
print text
REBOL Technologies
The first thru finds the title tag and goes immediately past it. Next, the input string
is copied into a variable called text until the ending tag is found (but it doesn’t go
past it, or the text would include the tag).

Parsing
Match Types
Match Types N
When parsing strings, these data types and words can be used to match characters
in the input string:
Table 14-1. Match Types
Match Type Description
"abc" match the entire string

#"c" match a single character
<tag> match a tag string
end match to the end of the input
(bitset) match any specified char in the set
To use all of these words (except bitset, which is explained below) in a single rule,
use:
[<B> ["excellent" | "incredible"] #"!" </B> end]
This example parses the input strings:
<B>excellent!</B>
<B>incredible!</B>
The end specifies that nothing follows in the input stream. The entire input has
been parsed. It is optional depending on whether the parse function’s return value
is to be checked. Refer to the “Evaluation” section below for more information.
The bitset data type deserves more explanation. Bitsets are used to specify
collections of characters in an efficient manner. The charset function enables you
to specify individual characters or ranges of characters. For example, the line:
digit: charset "0123456789"
defines a character set that contains digits. This allows rules like:
[3 digit "-" 3 digit "-" 4 digit]

Parsing
Match Types
which can parse phone numbers of the form:
707-467-8000
To accept any number of digits, it is common to write the rule:
digits: [some digit]
A character set can also specify ranges of characters. For instance, the digit
character set could have be written as:
digit: charset [#"0" - #"9"]
Alternatively, you can combine specific characters and ranges of characters:
the-set: charset ["+-." #"0" - #"9"]
To expand on this, here is the alphanumeric set of characters:
alphanum: charset [#"0" - #"9" #"A" - #"Z" #"a" - #"z"]
Character sets can also be modified with the insert and remove functions, or
combinations of sets can be created with the union and intersect functions. This
line copies the digit character set and adds a dot to it:
digit-dot: insert copy digit "."
The following lines define useful character sets for parsing:
digit: charset [#"0" - #"9"]

alpha: charset [#"A" - #"Z" #"a" - #"z"]
alphanum: union alpha digit

Parsing
Recursive Rules
Recursive Rules N
Here is an example of rule set that parses mathematical expressions and gives a
precedence (a priority) to the math operators used:
expr: [term ["+" | "-"] expr | term]

term: [factor ["*" | "/"] term | factor]
factor: [primary "**" factor | primary]
primary: [some digit | "(" expr ")"]
digit: charset "0123456789"
Now we can parse many types of math expressions. The following examples return
true, indicating that the expressions were valid:
probe parse "1 + 2 * ( 3 - 2 ) / 4" expr
true
probe parse "4/5+3**2-(5*6+1)" expr
true
Notice in the examples that some of the rules refer to themselves. For instance, the
expr rule includes expr. This is a useful technique for defining repeating
sequences and combinations. The rule is recursive —it refers to itself.
When using recursive rules, care is required to prevent endless recursion. For
instance:
expr: [expr ["+" | "-"] term]
creates an infinite loop because the first thing expr does is use expr again.
Evaluation N
Normally, you parse a string to produce some result. You want to do more than just
verify that the string is valid, you want to do something as it is parsed. For instance,
you may want to pick out substrings from various parts of the string, create blocks
of related values, or compute a value.

Parsing
Evaluation
Return Value 0
The examples in previous chapters showed how to parse strings, but no results were
produced. This is only done to verify that a string has the specified grammar; the
value returned from parse indicates its success. The following examples show this:
probe parse "a b c" ["a" "b" "c"]
true
probe parse "a b" ["a" "c"]
false
The parse function returns true only if it reaches the end of the input string. An
unsuccessful match stops the parse of the series. If parse runs out of values to
search for before reaching the end of the series, it does not traverse the series and
returns false:
probe parse "a b c d" ["a" "b" "c"]
false
probe parse "a b c d" [to "b" thru "d"]
true
probe parse "a b c d" [to "b" to end]
true

Parsing
Evaluation
Expressions in Rules 0
Within a rule, you can include a REBOL expression to be evaluated when parse
reaches that point in the rule. Parentheses are used to indicate such expressions:
string: "there is a phone in this sentence"

probe parse string [
to "a"
to "phone" (print "found phone")
to end
]
found phone
true
The example above parses the string a phone and prints the message found
phone after the match is complete. If the strings a or phone are missing and the
parse can not be done, the expression is not evaluated.

Parsing
Evaluation
Expressions can appear anywhere within a rule, and multiple expressions can occur
in different parts of a rule. For instance, the following code prints different strings
depending on what inputs were found:
parse string [
"a" | "the"
to "phone" (print "answer") |
to "radio" (print "listen") |
to "tv" (print "watch")
]
answer
string: "there is the radio on the shelf"
parse string [
"a" | "the"
to "phone" (print "answer") |
to "radio" (print "listen") |
to "tv" (print "watch")
]
listen
Here is an example that counts the number of times the HTML pre-format tag
appears in a text string:
count: 0
page: read http://www.rebol.com/dictionary.html
parse page [any [thru <pre> (count: count + 1)]]
print count
777

Parsing
Evaluation
Copying the Input 0
The most common action done with parse is to pick up parts of the string being
parsed. This is done with copy, and it is followed by the name of a variable to which
you want to copy the string. The following example parses the title of a web page:

print text
REBOL/Core Dictionary
The example works by skipping over text until it finds the <title> tag. That’s
where it starts making a copy of the input stream and setting a variable called text
to hold it. The copy operation continues until the closing </title> tag is found.
The copy action also can be used with entire rule blocks. For instance, for the rule:
[copy heading ["H" ["1" | "2" | "3"]]
the heading string contains the entire H1, H2, or H3 string. This also works for large
multi-block rules.
Marking the Input 0
The copy action makes a copy of the substring that it finds, but that is not always
desirable. In some cases, it is better to save the current position of the input stream
in a variable.
NOTE: The copy word as used in parse is different from the copy function used in
REBOL expressions. Parse uses a dialect of REBOL, and copy has a different
meaning within that dialect.

Parsing
Evaluation
In the following example, the begin variable holds a reference to the page input
string just after <title>. The ending refers to the page string just before
</title>. These variables can be used in the same way as they would be used
with any other series.
parse page [
thru <title> begin: to </title> ending:
(change/part begin "Word Reference Guide" ending)
]
You can see the above parse expression actually changed the contents of the title:

print text
Word Reference Guide
Here is another example that marks the position of every table tag in an HTML file:
page: read http://www.rebol.com/index.html

tables: make block! 20
parse page [
any [to "<table" mark: thru ">"
(append tables index? mark)
]
]

Parsing
Evaluation
The tables block now contains the position of every tag:
foreach table tables [

print ["table found at index:" table]
]
table found at index: 836

NOTE: The current position in the input string can also be modified. The next section
explains how this is done.
Modifying the String 0
Now that you know how to obtain the position of the input series, you also can use
other series functions on it, including insert, remove, and change. To write a script
that replaces all question marks (?) with exclamation marks (!), write:
str: "Where is the turkey? Have you seen the turkey?"

parse str [some [to "?" mark: (change mark "!") skip]]
print str
Where is the turkey! Have you seen the turkey!
The skip at the tail advances the input over the new character, which is not
necessary in this case, but it is a good practice.

Parsing
Evaluation
As another example, to insert the current time everywhere the word time appears
in some text, write:
str: "at this time, I’d like to see the time change"
parse str [
some [to "time"
mark:
(remove/part mark 4 mark: insert mark now/time)
:mark
]
]
print str
at this 14:42:12, I’d like to see the 14:42:12 change
Notice the :mark word used above. It sets the input to a new position. The insert
function returns the new position just past the insert of the current time. The word
:mark is used to set the input to that position.
Using Objects 0
When parsing large grammar from a set of rules, variables are used to make the
grammar more readable. However, the variables are global and may become
confused with other variables that have the same name somewhere else in the
program.

Parsing
Evaluation
The solution to this problem is to use an object to make all the rule words local to
a context. For instance:
tag-parser: make object! [

tags: make block! 100
text: make string! 8000
html-code: [
copy tag ["<" thru ">"] (append tags tag) |
copy txt to "<" (append text txt)
]
parse-tags: func [site [url!]] [
clear tags clear text
parse read site [to "<" some html-code]
foreach tag tags [print tag]
print text
]
]
tag-parser/parse-tags http://www.rebol.com
Debugging 0
As rules are written, there are times debugging is needed. Specifically, you may
want to know how far you got in the parsing of a rule.
The trace function can be used to watch the parse operation progress, but this can
output thousands of lines that are difficult to review.
A better way is to insert debugging expressions into the parse rules. As an example,
to debug the rule:
[to "<IMG" "SRC" "=" filename ">"]
insert a the print function after key sections to monitor your progress through the
rule:
[to "<IMG" (print 1) "SRC" "=" (print 2)

filename (print 3) ">"]
This example prints 1, 2, and 3 as the rule is processed.

Parsing
Dealing with Spaces
Another approach is to print out part of the input string as the parse happens:
[
to "<IMG" here: (print here)
"SRC" "=" here: (print here)
filename here: (print here) ">"
]
If this is done often, you can create a rule for it:
here: [where: (print where)]
[
to "<IMG" here
"SRC" "=" here
filename here ">"
]
The copy function can also be used to indicate what substrings were parsed as the
rule was handled.
Dealing with Spaces N
The parse function normally ignores all intervening whitespace between patterns
that it scans. For instance, the rule:
["a" "b" "c"]
returns strings that match:
abc
a bc
ab c
a b c
a b c
and other similarly spaced combinations.

Parsing
Dealing with Spaces
To enforce a specific spacing convention, use parse with the /all refinement. In the
preceeding example, this refinement causes parse to only match the first case (abc).
parse/all "abc" ["a" "b" "c"]
Specifying the /all refinement forces every character in the input stream to be dealt
with, including the default delimiters, such as space, tab, newline.
To handle spaces in your rules, create a character set that specifies the valid space
characters:
spacer: charset reduce [tab newline #" "]
If you want a single space character between each letter write:
["a" spacer "b" spacer "c"]
To allow multiple space characters, write:
spaces: [some spacer]

["a" spaces "b" spaces "c"]
For more sophisticated grammars, create a character set that lets you scan a string
up to a space character.
non-space: complement spacer

to-space: [some non-space | end]
words: make block! 20
parse/all text [
some [copy word to-space (append words word) spacer]
]
The preceding example builds a block of all of its words. The complement function
inverts the character set. Now it contains everything except the spacing characters
you defined earlier. The non-space character set contains all characters except
space characters. The to-space rule accepts one or more characters up to a space
character or the end of the input stream. The main rule expects to begin with a
word, copy that word up to a space, then skip the space character and begin the
next word.

Parsing
Parsing Blocks and Dialects
Parsing Blocks and Dialects N
Blocks are parsed similar to strings. A set of rules specify the order of expected
values. However, unlike the parsing of strings, the parsing of blocks is not
concerned with characters or delimiters. Parsing of blocks is done at the value level,
making the grammar rules easier to specify and operation many times faster.
Block parsing is the easiest way to create REBOL dialects. Dialects are
sub-languages of REBOL that use the same lexical form for all data types but allow
a different ordering of the values within a block. The values do not need to conform
to the normal order required by REBOL function arguments. Dialects are able to
provide greater expressive power for specific domains of use. For instance, the
parser rules themselves are specified as a dialect.
Matching Words 0
When parsing a block, to match against a word specify the word as a literal:
’name
’when
’empty

Parsing
Matching Data Types 0
You can match a value of any data type by specifying the data type word. See
Table 14-2 below.
Table 14-2. Data Type Matches
Data Type Word Description
string! matches any quoted string

time! matches any time
date! matches any date
tuple! matches any tuple
NOTE: Don’t forget the "!" that is part of the name or an error will be generated.
Characters Not Allowed 0
The parse operations allowed for blocks are those that deal with specific characters.
For instance, a match cannot be specified to the first letter of a word or string, nor
to spacing or newline characters.
Dialect Examples 0
A few concise examples help illustrate the parsing of blocks:
block: [when 10:30]

print parse block [’when 10:30]
print parse block [’when time!]
parse block [’when set time time! (print time)]
Notice that a specific word can be matched by using its literal word in the rule (as
in the case of ’when). A data type can be specified rather than a value, as in the
lines above containing time!. In addition, a variable can be set to a value with the
set operation.

Parsing
As with strings, alternate rules can be specified when parsing blocks:
rule: [some [
’when set time time! |
’where set place string! |
’who set persons [word! | block!]
]]
These rules allow information to be entered in any order:
parse [
who Fred
where "Downtown Center"
when 9:30
] rule
print [time place persons]
This example could have used variable assignment, but it illustrates how to provide
alternate input ordering.
Here’s another example that evaluates the results of the parse:
rule: [
set count integer!
set str string!
(loop count [print str])
]
parse [3 "great job"] rule
parse [3 "hut" 1 "hike"] [some rule]

Parsing
Finally, here is a more advanced example:
rule: [
set action [’buy | ’sell]
set number integer!
’shares ’at
set price money!
(either action = ’sell [
print ["income" price * number]
total: total + (price * number)
][
print ["cost" price * number]
total: total - (price * number)
]
)
]
total: 0
parse [sell 100 shares at $123.45] rule
print ["total:" total]
total: 0
parse [
sell 300 shares at $89.08
buy 100 shares at $120.45
sell 400 shares at $270.89
] [some rule]
print ["total:" total]
Parsing Sub-blocks 0
When parsing a block, if a sub-block is found, it is treated as a single value that is

of the block! data type. However, to parse a sub-block, you must invoke the parser
recursively on the sub-block. The into word provides this capability. It expects that
the next value in the input block is a sub-block to be parsed. This is as if a block!
data type had been provided. If the next value is not a block! data type, the match

Parsing
fails and into looks for alternates or exits the rule. If the next value is a block, the
parser rule that follows the into word is used to begin parsing the sub-block. It is
processed in the same way as a sub-rule.
rule: [date! into [string! time!]]

data: [10-Jan-2000 ["Ukiah" 10:30]]
print parse data rule
All of the normal parser operations can be applied to into.
rule: [
set date date!
set info into [string! time!]]
]
data: [10-Jan-2000 ["Ukiah" 10:30]]
print info
rule: [date! copy items 2 into [string! time!]]

data: [10-Jan-2000 ["Ukiah" 10:30] ["Rome" 2:45]]
probe items

Parsing
Summary of Parse Operations
Summary of Parse Operations N
General Forms
Table 14-3. General Forms
Operator Description
| alternate rule
[block] sub-rule
(paren) evaluate a REBOL expression
Specifying Quantity
Table 14-4. Specifying Quantity
none match nothing

opt zero or one time
some one or more times
any zero or more times
12 repeat pattern 12 times
1 12 repeat pattern 1 to 12 times
0 12 repeat pattern 0 to 12 times

Parsing
Skipping Values
Table 14-5. Skipping Values
skip skip a value (or multiple if repeat given)

to advance input to a value or data type
thru advance input thru a value or data type
Getting Values
Table 14-6. Getting Values
set set the next value to a variable

copy copy the next match sequence to a variable
Using Words
Table 14-7. Using Words
word look-up value of a word

word: mark the current input series position
:word set the current input series position
’word matches the word literally (parse block)

Parsing
Value Matches (examples, any data type is valid - block parsing only)
Table 14-8. Value Matches
"fred" matches the string "fred"

%data matches the file name %data
10:30 matches the time 10:30
1.2.3 matches the tuple 1.2.3
Data type Words

Table 14-9. Data Type Words
type! matches anything of a given data type

Appendix A
Values
This appendix gives a listing of the value types used in REBOL and their use. It
■ “Number Values” on page Appendix A-2

■ “Series Values” on page Appendix A-8
■ “Other Values” on page Appendix A-48
A- 1
Values
Number Values
Number Values A
Decimal A
Concept
The decimal! data type includes 64-bit standard IEEE floating point numbers. They
are distinguished from integer numbers by a decimal point.
Format
Decimal values are a sequence of numeric digits, followed by a decimal point,
which can be a period (.) or a comma (,), followed by more digits. A plus (+) or
minus (-) immediately before the first digit indicates sign. Leading zeros before the
decimal point are ignored. Extra spaces, commas, and periods are not allowed.
1.23
123.
123.0
0.321
0.123
1234.5678
A comma can be used in place of a period to represent the decimal point (which is
the custom in some countries):
1,23
0,321
1234,5678
Use a single quote (‘) to separate the digits in long decimals. Single quotes can
appear anywhere after the first digit in the number, but not before the first digit.
100’234’562.3782
100’234’562,3782
Do not use commas or periods separate the digits in a decimal value.
A-2 REBOL/Core User Guide Version 2.3

Values
Number Values
Scientific notation can be used to specify the exponent of a number by appending

the number with the letter E or e followed by a sequence of digits. The exponent
can be a positive or negative number.
1.23E10
1.2e007
123.45e-42
56,72E300
-0,34e-12
0.0001e-001
Decimal numbers span from 2.2250738585072e-308 up to 1.7976931348623e+308

and can contain up to 15 digits of precision.
Creation
Use the to-integer function to convert a string!, integer!, block!, or a decimal!
data type to a decimal number:
probe to-decimal "123.45"
123.45
probe to-decimal 123
123
probe to-decimal [-123 45]
-1.23E+47
probe to-decimal [123 -45]
1.23E-43
probe to-decimal -123.8
-123.8
probe to-decimal 12.3
12.3
REBOL/Core User Guide Version 2.3 A- 3

Values
Number Values
If a decimal and integer are combined in an expression, the integer is converted to

a decimal number:
probe 1.2 + 2
3.2
probe 2 + 1.2
3.2
probe 1.01 > 1
true
probe 1 > 1.01
false
Related
Use decimal? to determine whether a value is an decimal! data type.
print decimal? 0.123
true
Use the form, print, and mold functions with an integer argument to print a
decimal value in its simplest form:
integer . If it can be represented as one.
decimal without exponent. If it’s not too big or too small.
scientific notation. If it’s too big or small.

Values
Number Values
For example,
probe mold 123.4
123.4
probe form 2222222222222222
2.22222222222222E+15
print 1.00001E+5
100001
Single quotes (‘) and a leading plus sign (+) do not appear in decimal output:
print +1’100’200.222’112
1100200.222112
Integer A
Concept
The integer! data type includes 32-bit positive and negative numbers and zero.
Unlike decimal numbers, integers do not contain a decimal point.
Format
Integer values consist of a sequence of numeric digits. A plus (+) or minus (-)
immediately before the first digit indicates sign. (There cannot be a space between
the sign and the first digit.) Leading zeros are ignored.
0 1234 +1234 -1234 00012 -0123
Do not use commas or periods in integers. If a comma or period is found within an

integer it is interpreted as a decimal value. . However, you can use a single quote
(‘) to separate the digits in long integers. Single quotes can appear anywhere after
the first digit in the number, but not before the first digit.
2’147’483’647

Values
Number Values
Integers span a range from -2147483648 to 2147483647.
Creation
Use the to-integer function to convert a string!, logic!, decimal!, or integer! data
type to an integer:
probe to-integer "123"
123
probe to-integer false
probe to-integer true
probe to-integer 123.4
123
probe to-integer 123.8
123
probe to-integer -123.8
-123

Values
Number Values
If a decimal and integer are combined in an expression, the integer is converted to

a decimal:
probe 1.2 + 2
3.2
probe 2 + 1.2
3.2
probe 1.01 > 1
true
probe 0 < .001
true
Related
Use integer? to determine whether a value is an integer! data type.
probe integer? -1234
true
Use the form, print, and mold functions with an integer argument to print a integer
value as a string:
probe mold 123
123
probe form 123
123
print 123
123
Integers that are out of range or cannot be represented in 32 bits are flagged as an
error.

Values
Series Values
Series Values A
Binary A
Concept
Binary values hold binary data of any arbitrary type. Any sequence of bytes can be
stored, such as an image, audio, executable file, compressed data, and encrypted
data. The source format for binary data can be base-2 (binary), base-16 (hex), and
base-64. The default base for binary data in REBOL is base-16.
Format
Binary strings are written as a number sign (#) followed by a string enclosed in
braces. The characters within the string are encoded in one of several formats as
specified by an optional number prior to the number sign. Base-16 is the default
format.
#{3A18427F 899AEFD8} ; default base-16

2#{10010110110010101001011011001011} ; base-2
64#{LmNvbSA8yw9CB0aGvXmgUkVCu2Uz934b} ; base-64
Spaces, tabs and newlines are permitted within the string. Binary data can span
multiple lines.
probe #{
3A
18
92
56
}
#{3A189256}
Strings that are missing the correct number of characters to create a correct binary
result are padded on the right.

Values
Series Values
Creation
The to-binary function converts data to the binary! data type at the default base
set in system/options/binary-base:
probe to-binary "123"
#{313233}
probe to-binary "today is the day..."
#{746F64617920697320746865206461792E2E2E}
To convert an integer into its binary value, pass it in a block:
probe to-binary [1]
#{01}
probe to-binary [11]
#{0B}
Converting a series of integers into a binary, returns the bit conversion for each
integer concatenated into a single binary value:
probe to-binary [1 1 1 1]
#{01010101}
Related
Use binary? determine whether a value is an binary! data type.
probe binary? #{616263}
true

Values
Series Values
Binary values are a type of series:
probe series? #{616263}
true
probe length? #{616263} ; three hex values in this binary
Closely related to working with binary! data types are the functions enbase and
debase. The enbase function converts strings to their base-2, base-16 or base-64
representations as strings. The debase function converts enbased strings to a binary
value of the base specified in system/options/binary-base.
Block A
Concept
Blocks are groups of values and words. Blocks are used everywhere, from a script
itself to blocks of data and code provided in a script.
Block values are indicated by opening and closing square brackets ([]) with any
amount of data contained between them.
[123 data "hi"] ; block with data

[] ; empty block
Blocks can hold records of information:
woodsmen: [
"Paul" "Bunyuan" [email protected]
"Grizzly" "Adams" [email protected]
"Davey" "Crocket" [email protected]
]
Blocks can contain code:
[print "this is a segment of code"]

Values
Series Values
Blocks are also a type of series, and thus anything that can be done with a series
can be done with a block value.
Blocks can be searched:
probe copy/part (find woodsmen "Grizzly") 3
[
"Grizzly" "Adams" [email protected]]
Blocks can be modified:
append woodsmen [
"John" "Muir" [email protected]
]
probe woodsmen
[
"Paul" "Bunyuan" [email protected]
"Grizzly" "Adams" [email protected]
"Davey" "Crocket" [email protected]
"John" "Muir" [email protected]
]
Blocks can be evaluated:
blk: [print "data in a block"]

do blk
data in a block

Values
Series Values
Blocks can contain blocks:
blks: [
[print "block one"]
[print "block two"]
[print "block three"]
]
foreach blk blks [do blk]
block one
block two
block three
Format
Blocks can contain any number of values or no values at all. They can extend over
multiple lines and can include any type of value, including other blocks.
An empty block:
[ ]
A block of integers:
[24 37 108]
A REBOL header:
REBOL [
Title: "Test Script"
Date: 31-Dec-1998
Author: "Ima User"
]
The condition and evaluation block of a function:
while [time < 10:00] [

print time
time: time + 0:10
]

Values
Series Values
Words in a block need not be defined:
blk: [undefined words in a block]

probe value? pick blk 1
false
Blocks allow any number of lines, spaces, or tabs. Lines and spaces can be placed
anywhere within the block, so long as they do not divide a single value.
Creation
The to-block function converts data to the block! data type:
probe to-block [email protected]
[[email protected]]
probe to-block {123 10:30 "string" [email protected]}
[123 10:30 "string" [email protected]]
Related
Use block? to determine whether a value is an block! data type.
probe block? [123 10:30]
true
As blocks are a subset of the series! pseudotype, use series? to check this:
probe series? [123 10:30]
true
Using form on a block value creates a string from the contents contained in the
block:
probe form [123 10:30]
123 10:30

Values
Series Values
Using mold on a block value creates a string from the block value and it’s contents,
thus allowing it to be reloaded as a REBOL block value:
probe mold [123 10:30]
[123 10:30]
Closely related data types are hash! and list!. They are used in much the same way
as block values, but have special capabilities. List values are designed to handle
modification of lists more quickly than block values, and hash values are designed
handle data lookup and hash indexing of data. These are useful when dealing with
large data sets.
Email A
Concept
An email address is a data type. The email! data type allows for easy expression of
email addresses:
send [email protected] {some message}
emails: [
[email protected]
[email protected]
[email protected]
[email protected]
]
mesg: {poetry reading at 8:00pm!}
foreach email emails [send email mesg]
Email is also one of the series! data types, so the same rules that apply to series
apply to emails:
probe head change/part [email protected] "john" 4
[email protected]

Values
Series Values
Format
The standard format of an email address is a name, followed by an at sign (@),
followed by a domain. An email address can be of any length, but must not include
any of restricted characters, such as square brackets, quotes, braces, spaces,
newlines, etc..
The following email! data type formats are valid:
[email protected]
[email protected]
[email protected]
Upper and lower cases are preserved in email addresses.
Access
Refinements can be used with an email value to get the user name or domain. The
refinements are:
/user. – Get the user name.
/host. Get the domain.
Here’s how these refinements work:
probe email/user
luke
probe email/host
rebol.com

Values
Series Values
Creation
The to-email function converts data to the email! data type:
probe to-email "[email protected]"
[email protected]
probe to-email [info rebol.com]
[email protected]
probe to-email [info rebol com]
[email protected]
probe to-email [user some long domain name out there dom]
[email protected]
Related
Use email? to determine whether a value is an email! data type.
probe email? [email protected]
true
As emails are a subset of the series! pseudotype, use series? to determine whether
the value is a series:
probe series? [email protected]
true
probe pick [email protected] 5
#"@"

Values
Series Values
File A
Concept
The file! data type can be a file name, directory name, or directory path.
%file.txt
%directory/
%directory/path/to/some/file.txt
File values are a subset of series, and thus can be manipulated as a series:
probe find %dir/path1/path2/file.txt "path2"
%path2/file.txt
f: %dir/path/file.txt
probe head remove/part (find f "path/") (length? "path/")
%dir/file.txt
Format
Files are designated with a percent sign (%)followed by a sequence of characters:
load %image.jpg
prog: load %examples.r
save %this-file.txt "This file has few words."
files: load %../programs/
Unusual characters in file names must be encoded with a % hexadecimal number,

which is an Internet convention. A file name with a space (hexadecimal 20) would
look like:
probe %cool%20movie%20clip.mpg
print %cool%20movie%20clip.mpg
cool movie clip.mpg

Values
Series Values
Another format is to enclose the file name in quotes:
probe %"cool movie clip.mpg"
print %"cool movie clip.mpg"
cool movie clip.mpg
The standard character for separating directories in a path is the forward slash (/),
not the backslash (\). However, the REBOL language automatically converts
backslashes found in file names to forward slashes:
probe %\some\path\to\some\where\movieclip.mpg
%/some/path/to/some/where/movieclip.mpg
Creation
The to-file function converts data to the file! data type:
probe to-file "testfile"
%testfile
When passed a block, elements in the block are concatenated into a file path with
the final element used as the file name:
probe to-file [some path to a file the-file.txt]
%some/path/to/a/file/the-file.txt
Related
Use file? to determine whether a value is an file! data type.
probe file? %rebol.r
true

Values
Series Values
As files are a subset of the series! pseudotype, use series? to check this:
probe series? %rebol.r
true
Hash A
Concept
Hash is a block that is specially organized to make finding data faster. When
searching is performed on a hash block, the search is performed by using a hash
table for lookup. For large blocks, this can speed searches by hundreds of times.
Format
Hash blocks must be constructed by using make or to-hash. They have no lexical
format.
Creation
Use make to initialize a hash block:
hsh: make hash! 10 ; allocating space for 10 elements
The to-hash function converts data to the hash data type.
Convert a block:
blk: [1 "one" 2 "two" 3 "three" 4 "four"]

probe hash: to-hash blk
make hash! [1 "one" 2 "two" 3 "three" 4 "four"]
print select hash 2
two

Values
Series Values
Convert various values:
probe to-hash [email protected]
probe to-hash 123.5
probe to-hash {123 10:30 "string" [email protected]}
Related
Use hash? to test the data type.
hsh: to-hash [1 "one" 2 "two" 3 "three" 4 "four"]

probe hash? Hsh
true
As hashes are a subset of the series! pseudotype, use series? to check this:
probe series? hsh
true
Forming a hash value creates a string from the contents contained in the hash:
probe form hsh
"1 one 2 two 3 three 4 four"
Molding a hash value creates a string of the hash value itself and its contents, thus
allowing it to be reloaded as a REBOL hash value:
probe mold hsh
make hash! [1 "one" 2 "two" 3 "three" 4 "four"]
Image A
Concept
The image! data type is a series that holds RGB images. This data type is used with
REBOL/View.

Values
Series Values
The image formats supported are GIF, JPEG, and BMP. The loaded image can be
manipulated as a series.
Format
Images are normally loaded from a file. However, they can be expressed in source
code as well by making an image. The block provided includes the image size and
its RGB data.
image: make image! [192x144 #{

B34533B44634B44634B54735B7473
84836B84836B84836BA4837BA4837
BC4837BC4837BC4837BC4837BC483 ...
}
Creation
Empty images can be created using make or to-image:
empty-img: make image! 300x300
empty-img: to-image 150x300
The size of the image is provided.
Images can also be made from snapshots of a face object. This is also done using
make or to-image:
face-shot: make image! face
face-shot: to-image face
Use load to load an image file. If the image’s format is not supported, it will fail to
load.
Loading an image:
img: load %bay.jpg

Values
Series Values
Related
Use image? to determine whether a value is the image! data type:
probe image? img
Images are a subset of the series! pseudotype:
probe series? img
Use the /size refinement to return the pixel size of an image as a pair value:
probe img/size
The pixel values of an image are obtained using pick and changed using poke. The
value returned by pick is an RGB tuple value. The value replaced with poke also
should be a tuple value.
Picking specific pixels:
probe pick img 1
probe pick img 1500
Poking specific pixels:
poke img 1 255.255.255

probe pick img 1
poke img 1500 0.0.0

probe pick img 1500
Issue A
Concept
An issue! is a series of characters used to sequence symbols or identifiers for things
like telephone numbers, model numbers, serial numbers, and credit card numbers.

Values
Series Values
Issue values are a subset of series, and thus can be manipulated as series:
probe copy/part find #888-555-1212 "555" 3
#555
Format
Issues start with a number sign (#) and continue until the first delimiting character
(such as a space) is reached.
#707-467-8000
#A-0987654321-CD-09876
#1234-5678-4321-8765
#MG82/32-7
Values that contain delimiting characters should be written as strings rather than
issues.
Creation
The to-issue function converts data to the issue! data type:
probe to-issue "1234-56-7890"
#1234-56-7890
Related
Use issue? to determine whether a value is an issue! data type.
probe issue? #1234-56-7890
true
As issues are a subset of the series pseudotype, use series? to check this:
probe series? #1234-56-7890
true

Values
Series Values
The form function returns an issue as a string without the number sign (#):
probe form #1234-56-7890
1234-56-7890
The mold function returns an issue as a string that can be read by REBOL as an
issue value:
probe mold #1234-56-7890
#1234-56-7890
The print function prints an issue to standard output after doing a reform on it:
print #1234-56-7890
1234-56-7890
List A
Concept
Lists are linked list blocks that allow for faster and more efficient insertion and
removal of their values. They can be used in cases where a large number of
insertions or removals are being performed on large blocks.
Format
List blocks must be constructed by using make or to-list. They have no lexical
format.
Lists values are not a direct substitute for blocks. There are a couple of differences
between blocks and lists:
Inserting into a list modifies its reference to just after the point of insertion.
Removing the element currently referenced in a list causes the reference to reset to
the tail of the list
The following examples show the difference in behavior between inserting into a
list and a block.

Values
Series Values
Initializing a block and list:
blk: [1 2 3]
lst: to-list [1 2 3]
Inserting into a block and list:
insert blk 0
insert lst 0
Looking at the word after the block and list after insertion. Notice blk points to
the head, as before the insertion of 0, but lst points to just after the point of
insertion:
print blk
0 1 2 3
print lst
1 2 3
print head lst
0 1 2 3
The following examples show the difference in behavior between removing an

element from a list and a block.
Initializing a block and a list:
blk: [1 2 3]
Removing from the block and list:
remove blk
remove lst

Values
Series Values
Looking at the word after removal of the value. Notice lst now points to the tail
of the series:
print blk
2 3
print tail? lst
true
print head lst
2 3
If you don’t want the word to be at the tail after removing a value, step forward and
remove the value behind the current index. The following examples depicts this.
Initializing a list:
Stepping forward and removing the value behind the current index:
remove back (lst: next lst)
Looking at the word after removing the value:
probe lst
make list! [2 3]
Creation
Use make to initialize a list value:
lst: make list! 10 ; allocating space for 10 elements
The to-list function converts data to the list! data type:

Values
Series Values
Convert a block:
blk: [1 "one" 2 "two" 3 "three" 4 "four"]

probe to-list blk
Related
Use list? to determine whether a value is an list! data type.
lst: to-list [1 "one" 2 "two" 3 "three" 4 "four"]

probe list? Lst
true
Since lists are a subset of the series! data type, use series? to check whether a list
is a series:
probe series? lst
true
Using form on a list value creates a string from the contents contained in the list:
probe form lst
"1 one 2 two 3 three 4 four"
Using mold on a list value creates a string of the list value itself and it’s contents,
thus allowing it to be reloaded as a REBOL list value:
probe mold lst
make list! [1 "one" 2 "two" 3 "three" 4 "four"]
Paren A
Concept
A paren! data type is a block that is immediately evaluated. It is identical to a block
in every way, except that it is evaluated when it is encountered and its result is
returned.

Values
Series Values
When used within an evaluated expression, a paren! allows you to control the order
of evaluation:
print 1 + (2 * 3)
print 1 + 2 * 3
The value of a paren! can be accessed and modified in the same way as any block.
However, when referring to a paren!, care must be taken to prevent if from being
evaluated. If you store a paren in a variable, you will need to use a get-word form
(:word) to prevent it from being evaluated.

Values
Series Values
Parens are a type of series, thus anything that can be done with a series can be done
with paren values.
paren: first [(1 + 2 * 3 / 4)]
print type? :paren
paren!
print length :paren
print first :paren
print last :paren
insert :paren [10 + 5 *]

probe :paren
(10 + 5 * 1 + 2 * 3 / 4)
print paren
12.75
Format
Parens are identified by their open and closing parenthesis. They can span multiple
lines and contain any data, including other paren values.

Values
Series Values
Creation
The make function can be used to allocate a paren value:
paren: make paren! 10

insert :paren 10
insert :paren ‘+
insert :paren 20
print :paren
20 + 10
print paren
30
The to-paren function converts data to the paren! data type:
probe to-paren "123 456"
(123 456)
probe to-paren [123 456]
(123 456)
Related
Use paren? to test the data type.
blk: [(3 + 3)]

probe pick blk 1
(3 + 3)
probe paren? pick blk 1
true

Values
Series Values
As parens are a subset of the series! pseudotype, use series? to check this:
probe series? pick blk 1
true
Using form on a paren value creates a string from the contents contained in the
paren:
probe form pick blk 1
3 + 3
Path A
Concept
Paths are a collection of words and values delineated with forward slashes (/). Paths
are used to navigate to or find something. The words and values of a path are called
refinements, and they are combined to provide a means of navigating through a
value or function.
Paths can be used on blocks, files, strings, lists, hashes, functions, and objects.
How a path operates depends on the data type being used.
Paths can be used to select values from blocks, pick characters from strings, access
variables in objects, refine the operation of a function:
USA/CA/Ukiah/size (block selection)
names/12 (string position)
account/balance (object function)
match/any (function option)

Values
Series Values
The example below shows the simplicity of using a path to access a mini-database
created from a few blocks:
towns: [
Hopland [
phone #555-1234
web http://www.hopland.ca.gov
]
Ukiah [
phone #555-4321
web http://www.ukiah.com
]
]
print towns/ukiah/web
http://www.ukiah.com
Table A-1 shows the relationship of paths corresponding with type words, type
tests, and conversions:
Table A-1. Path Relationship
Action Type Word Type Test Conversion
path/word: set-path! set-path? to-set-path

path/word path! path? to-path
’path/word lit-path! lit-path? to-lit-path
Examples of Paths
Evaluate an object’s function:
obj: make object! [

hello: func [] [print "hello! hello!"]
]
obj/hello
hello! hello!

Values
Series Values
Evaluate an object’s word:
obj: make object! [

text: "do you believe in magic?"
]
probe obj/text
do you believe in magic?
Function refinements:
hello: func [/again] [

print either again ["hello again!"]["hello"]
]
hello/again
hello again!
Select from blocks, or multiple blocks:
USA: [
CA [
Ukiah [
population 15050
elevation "610 feet"
]
Willits [
population 9935
]
]
]
print USA/CA/Ukiah/population
15050
print USA/CA/Willits/elevation
1350 feet

Values
Series Values
Pick elements from series and embedded series by their numeric position:
string-series: "abcdefg"
block-series: ["John" 21 "Jake" 32 "Jackson" 43 "Joe" 52]
block-with-sub-series: [ "abc" [4 5 6 [7 8 9]]]
probe string-series/4
#"d"
probe block-series/3
Jake
probe block-series/6
43
probe block-with-sub-series/1/2
#"b"
probe block-with-sub-series/2/2
probe block-with-sub-series/2/4/2
The words supplied as paths are symbolic and therefore unevaluated. This is
necessary to allow the most intuitive form for object referencing. To use a word’s
reference, an explicit word value reference is required:
city: ’Ukiah
probe USA/CA/:city
[
population 15050
]

Values
Series Values
Paths in blocks, hashes, or objects are evaluated by matching the word at the top
level of the path, and verifying the word as a block!, hash! or object! value. Then
the next word in the path is sought as a word expressed in the block, hash or object
and an implicit select is performed. The value following the word matched is
returned. When the returned value is a block, hash, or object, the path can be
extended:
Getting the value associated with CA in USA:
probe USA/CA
[
Ukiah [
population 15050
]
Willits [
population 9935
]
]
Getting the value associated with Willits in USA/CA:
probe USA/CA/Willits
[
population 9935
]
Getting the value associated with population in USA/CA/Willits:
probe USA/CA/Willits/population
9935

Values
Series Values
When a word is used in a path that does not exist at the given point in the structure,
an error is produced:
probe USA/CA/Mendocino
** Script Error: Invalid path value: Mendocino.
** Where: probe USA/CA/Mendocino
Paths can be used to change values in blocks and objects:
USA/CA/Willits/elevation: "1 foot, after the earthquake"

probe USA/CA/Willits
[
population 9935
elevation "1 foot, after the earthquake"
]
obj/text: "yes, I do believe in magic."

probe obj
make object! [
text: "yes, I do believe in magic."
]
Blocks, hashes, functions, and objects can be mixed in paths.
Selecting from elements in a block inside an object:
obj: make object! [

USA: [
CA [
population "too many"
]
]
]
probe obj/USA/CA/population
too many

Values
Series Values
Using function refinements within an object:
obj: make object! [

hello: func [/again] [
print either again [
"hello again"
] [
"oh, hello"
]
]
]
obj/hello/again
hello again
Paths are a type of series, thus anything that can be done with a series can be done
with path values:
root: [sub1 [sub2 [

word "a word at the end of the path"
num 55
] ] ]
path: ’root/sub1/sub2/word
probe :path
root/sub1/sub2/word
In the previous example, the :path notation was used to get the path itself, not
the path’s value:
probe path
a word at the end of the path
Looking at how long a path is:
probe length? :path

Values
Series Values
Finding a word within a path:
probe find :path ’sub2
sub2/word
Changing a word in a path:
change find :path ’word ’num

probe :path
root/sub1/sub2/num
probe path
55
Format
Paths are expressed relative to a root word by providing a number of refinements,
each separated by a forward slash (/). These refinements can be words or values.
Their specific interpretation vary depending on the data type of the root value.
The words supplied as refinements in paths are symbolic and are not evaluated.
This is necessary to allow the most intuitive form for object referencing. To use a
word’s reference, an explicit word value reference is required:
root/:word
This example uses the value of the variable, rather than it name.
Creation
You can make an empty path of a given size with:
path: make path! 10

insert :path ‘test
insert tail :path ‘this
print :path
test/this

Values
Series Values
The to-path function converts data to the path! data type:
probe to-path [root sub]
root/sub
probe to-path "root sub"
root/sub
The to-set-word function converts other values to the set-word data type.
probe to-set-path "root sub"
root/sub:
The to-lit-word function converts other values to the lit-word data type.
probe to-lit-path "root sub"
’root/sub
Related
Use path?, set-path?, and lit-path? to determine the data type of a value.
probe path? second [1 two "3"]
false
blk: [sub1 [sub2 [word 1]]]

blk2: [blk/sub1/sub2/word: 2]
if set-path? (pick blk2 1) [print "it is set"]
it is set
probe lit-path? first [’root/sub]
true

Values
Series Values
As paths are a subset of the series! pseudotype, use series? to check this:
probe series? pick [root/sub] 1
true
Use form on a path value creates a string from the path:
probe form pick [root/sub] 1
root/sub
Use mold on a path value creates a string of the path value itself, thus allowing it
to be reloaded as a REBOL path value:
probe mold pick [root/sub] 1
root/sub
String A
Concept
Strings are a series of characters. All operations performable on series values can be
performed on strings.
Format
String values are written as a sequence of characters surrounded by double quotes
“ “ or braces {}. Strings enclosed in double quotes are restricted to a single line and
must not contain unprintable characters.
"This is a short string of characters."

Values
Series Values
Strings enclosed in braces are used for larger sections of text that span multiple
lines. All of the characters of the string, including spaces, tabs, quotes, and newlines
are part of the string.
{This is a long string of text that will

not easily fit on a single line of source.
These are often used for documentation
purposes.}
Braces are counted within the string, so a string can include other braces as long as
the number of closing braces matches the number of opening braces.
{
This is another long string of text that would
never fit on a single line. This string also
includes braces { a few layers deep { and is
valid because there are as many closing braces }
as there are open braces } in the string.
}
You can include special characters and operations in strings by prefixing them with
a caret (^). Special characters include:
Table A-1. Special Characters
Character Definition
" Inserts a double quote (").

} Inserts a closing brace (}).
^ Inserts a caret (^).
/ Starts a new line.
(line) Starts a new line.
- Inserts a tab.
(tab) Inserts a tab.
(page) Starts a new page.
(letter) Inserts control-letter (A-Z).

Values
Series Values
Table A-1. Special Characters
(back) Erases one character to the left of the insertion point.

(null) Inserts a null character.
(escape) Inserts an escape character.
(xx) Inserts an ASCII character by hexidecimal (xx) number.
Creation
Use make to create a pre-allocated amount of space for an empty string:
make string! 40’000 ; space for 40k characters
The to-string function converts data of other data types to a string! data type:
probe to-string 29-2-2000
"29-Feb-2000"
probe to-string 123456.789
"123456.789"
probe to-string #888-555-2341
"888-555-2341"
Converting a block of data to a string with to-string has the effect of doing a rejoin,
but without evaluating the block’s contents:
probe to-string [123 456]
"123456"
probe to-string [225.225.225.0 none true ’word]
"225.225.225.0nonetrueword"

Values
Series Values
Related
Use string? or series? to determine whether a value is an string! data type:
print string? "123"
true
print series? "123"
true
The functions form and mold are closely related to strings, as they create strings
from other data types. The form function makes a human readable version of a
specified data type, while mold makes a REBOL readable version.
probe form "111 222 333"
"111 222 333"
probe mold "111 222 333"
{"111 222 333"}
Tag A
Concept
Tags are used in HTML and other markup languages to indicate how text fields are
to be treated. For example, the tag <HTML> at the beginning of a file indicates
that it should be parsed by the rules of the Hypertext Markup Language. A tag
with a forward slash (/), such as </HTML>, indicates the closing of the tag.

Values
Series Values
Tags are a subset of series, and thus can be manipulated as such:
a-tag: <img src="mypic.jpg">

probe a-tag
<img src="mypic.jpg">
append a-tag { alt="My Picture!"}

probe a-tag
<img src="mypic.jpg" alt="My Picture!">
Format
A valid tag is any text that begins with an open angle bracket (<).
<a href="index.html">
<img src="mypic.jpg" width="150" height="200">
</a>
Creation
The to-tag function converts data to the tag! data type:
probe to-tag "title"
<title>
Use build-tag to construct tags, including their attributes. The build-tag function
takes one argument, a block. In this block, the first word is used as the tag name
and the remaining words are processed as attribute value pairs:
probe build-tag [a href http://www.rebol.com/]
<a href="http://www.rebol.com/">
probe build-tag [
img src %mypic.jpg width 150 alt "My Picture!"
]
<img src="mypic.jpg" width="150" alt="My Picture!">

Values
Series Values
Related
Use tag? to determine whether a value is an tag! data type.
probe tag? <a href="http://www.rebol.com/">
true
As tags are a subset of the series pseudotype, use series? to check this:
probe series? <a href="http://www.rebol.com/">
true
The form function returns a tag as a string:
probe form <a href="http://www.rebol.com/">
{<a href="http://www.rebol.com/">}
The mold function returns a tag as a string:
probe mold <a href="http://www.rebol.com/">
{<a href="http://www.rebol.com/">}
The print function prints a tag to standard output after doing a reform on it:
print <a href="http://www.rebol.com/">
<a href="http://www.rebol.com/">
URL A
Concept
URL is an acronym for Uniform Resource Locator, an Internet standard used to
access resources such as web pages, images, files, and email across the network.
The best known URL scheme is that used for web locations such as
http://www.REBOL.com.

Values
Series Values
URL values are a subset of series, and thus can be manipulated as series:
url: http://www.rebol.com/reboldoc.html
probe to-file find/reverse (tail url) "rebol"
%reboldoc.html
Format
The first part of a URL indicates its communications protocol, called a scheme. The
language supports several schemes, including: web pages (HTTP:), file transfer
(FTP:), newsgroups (NNTP:), email (MAILTO:), files (FILE:), finger
(FINGER:), whois (WHOIS:), small network time (DAYTIME:), post office
(POP:), transmission control (TCP:) and domain name service (DNS:).
These scheme names are followed by characters that are dependent on which
scheme being used.
http://host.dom/path/file
ftp://host.dom/path/file
nntp://news.some-isp.net/some.news.group
mailto:name@domain
file://host/path/file
finger://[email protected]
whois://[email protected]
daytime://everest.cclabs.missouri.edu
pop://user:[email protected]/
tcp://host.dom:21
dns://host.dom
Some fields are optional. For instance, the host can be followed by a port number
if it differs from the default. An FTP URL supplies a default password if one is not
specified:
ftp://user:[email protected]/path/file

Values
Series Values
Characters in a URL must conform to Internet standards. Restricted characters must

be encoded in hexadecimal by preceding them with the escape character %:
probe http://www.somes-
ite.dom/odd%28dir%29/odd%7Bfile%7D.txt
http://www.somesite.dom/odd%28dir%29/odd%7Bfile%7D.txt
print http://www.somes-
ite.dom/odd%28dir%29/odd%7Bfile%7D.txt
http://www.somesite.dom/odd(dir)/odd{file}.txt
Creation
The to-url function converts blocks to the url! data type, the first element in the
block is the scheme, the second element is the domain (with or without
user:pass and port) the remaining elements are the path and file:
probe to-url [http www.rebol.com reboldoc.html]
http://www.rebol.com/reboldoc.html
probe to-url [http www.rebol.com %examples "websend.r"]
http://www.rebol.com/examples/websend.r
probe to-url [http usr:[email protected]:80 "(path)"

%index.html]
http://usr:[email protected]:80/%28path%29/index.html
Related
The data type word is url!.
Use url? to test the data type.
probe url? ftp://ftp.rebol.com/
true

Values
Other Values
As urls are a subset of the series pseudotype, use series? to check this:
probe series? http://www.rebol.com/
true
Other Values A
Character A
Concept
Characters are not strings; they are the individual values from which strings are
constructed. A character can be a printable, unprintable, or a control character.
Format
A char! value is written as a number sign (#) followed by a string enclosed in
double quotes. The number sign is necessary to distinguish a character from a
string:
#"R" ; the single character: R

"R" ; a string with the character: R
Characters can include escape sequences that begin with a caret(^)and are followed
by one or more characters of encoding. This encoding can include the characters
#"^A" to #"^Z" for control A to control Z (upper and lower case are the
same):
#"^A" #"^Z"

Values
Other Values
Following is a table of control characters that can be used in REBOL.

Table A-2. Control Characters
#"(null)" or null (zero)

#"@"
#"(line)", #"/" end of line
or, #"."
#"(tab)" or horizontal tab
#"-"
#"(page)" new page (and page eject)
#"(esc)" escape
#"(back)" backspace
#"(del)" delete
#"^" caret character
#"^"" quotation mark
#"(00)" to hex forms of characters
#"(FF)"
Creation
Characters can be converted to and from other data types with the to-char function:
probe to-char "a"
#"a"
probe to-char "z"
#"z"

Values
Other Values
Characters follow the ASCII standard and can be constructed by specifying a

character’s numeric equivalent:
probe to-char 65
#"A"
probe to-char 52
#"4"
probe to-char 52.3
#"4"
Another method of obtaining a character is to get the first character from a string:
probe first "ABC"
#"A"
While characters in strings are not case sensitive, individual characters are case
sensitive:
probe "a" = "A"
true
probe #"a" = #"A"
false
Related
Use char? to determine whether a value is a char! data type.
probe char? "a"
false
probe char? #"a"
true

Values
Other Values
Use the form function to print a character without the number sign:
probe form #"A"
"A"
Use mold on to print a character with the number sign and double quotes (and
escape sequences for those characters that require it.):
probe mold #"A"
{#"A"}
Date A
Concept
Around the world, dates are written in a variety of formats. However, most
countries use the day-month-year format. One of the few exceptions is the
United States , which commonly uses a month-day-year format. For
example, a date written numerically as 2/1/1999 is ambiguous. The month
could be interpreted as either February or January. Some countries use a dash
(-), some use a forward slash (/), and others use a period (.) as a separator.
Finally, computer people often prefer dates in the year-month-day (ISO) format
so they can be easily sorted.

Values
Other Values
Format
The REBOL language is flexible, allowing date! data types to be expressed in a
variety of formats. For example, the first day of March can be expressed in any of
the following formats:
probe 1/3/1999
1-Mar-1999
probe 1-3-1999
1-Mar-1999
probe 1999-3-1 ;ISO format
1-Mar-1999
The year can span up to 9999 and down to 1. Leap days (February 29) can only be
written for leap years:
probe 29-2-2000
29-Feb-2000
The fields of dates can be separated with forward slashes (/) or dashes (-). Dates
can be written in either a year-month-day format or a day-month-year format:
probe 1999-10-5
5-Oct-1999
probe 1999/10/5
5-Oct-1999
probe 5-10-1999
5-Oct-1999
probe 5/10/1999
5-Oct-1999

Values
Other Values
Because the international date formats that are not widely used in the USA, a month
name or month abbreviation can also be used:
probe 5/Oct/1999
5-Oct-1999
probe 5-October-1999
5-Oct-1999
probe 1999/oct/5
5-Oct-1999
When the year is the last field, it can be written as either a four digit or two digit
number:
probe 5/oct/99
5-Oct-1999
probe 5/oct/1999
5-Oct-1999
However, it is preferred to write the year in full. Otherwise, problems occur with
date comparison and sorting operations. While two digits can be used to express a
year , the interpretation of a two-digit year is relative to the current year and is only
valid for 50 years in the future or in the past:
probe 28-2-66 ; refers to 1966
28-Feb-1966
probe 12-Mar-20 ; refers to 2020
12-Mar-2020
probe 11-3-45 ; refers to 2045, not 1945
11-Mar-2045
It is recommended to use a four-digit year to avoid potential problems.

Values
Other Values
To represent dates in the first century (which is rarely done because the Gregorian
calendar did not exist), use leading zeros to represent the century (as in
9-4-0029).
Dates can also include an optional time field and an optional time zone. The time
is separated from the date with a forward slash (/). The time zone is appended
using a plus (+) or minus (-), and no spaces are allowed. Time zones are written
as a time shift (plus or minus) from GMT. The resolution of the time zone is to the
half hour. If the time shift is an integer, it is assumed to be hours:
probe 4/Apr/2000/6:00+8:00
4-Apr-2000/6:00+8:00
probe 1999-10-2/2:00-4:00
2-Oct-1999/2:00-4:00
probe 1/1/1990/12:20:25-6
1-Jan-1990/12:20:25
There can be no spaces within the date. For example:
10 - 5 - 99
would be interpreted as a subtraction expression , not a date.
Access
Refinements can be used with a date value to get any of its defined fields:
Table A-3. Date Value Refinements
/day Gets the day.

/month Gets the month.
/year Gets the year.
/yearday Gets the day of the year.

Values
Other Values
Table A-3. Date Value Refinements
/weekday Gets the weekday (1-7/Mon-Sun).

/time Gets the time (if present).
/hour Gets the time’s hour (if present)
/minute Gets the time’s minute (if present).
/second Gets the time’s second (if present).
/zone Gets the time zone (if present).
Here’s how these refinements work:
some-date: 29-Feb-2000
probe some-date/day
29
probe some-date/month
probe some-date/year
2000
days: ["Mon" "Tue" "Wed" "Thu" "Fri" "Sat" "Sun"]

probe pick days some-date/weekday
Tue

Values
Other Values
When a time is present, the time related refinements can be used. The /hour,
/minute and /second refinements are used with the /time refinement that isolates
the time segment of the date value for them to work on:
lost-time: 29-Feb-2000/11:33:22.14-8:00
probe lost-time/time
11:33:22.14
probe lost-time/time/hour
11
probe lost-time/time/minute
33
probe lost-time/time/second
22.14
probe lost-time/zone
-8:00
Creation
Use the to-date function to convert values to a date!:
probe to-date "5-10-1999"
5-Oct-1999
probe to-date "5 10 1999 10:30"
5-Oct-1999/10:30
probe to-date [1999 10 5]
5-Oct-1999
probe to-date [5 10 1999 10:30 -8:00]
5-Oct-1999/10:30-8:00

Values
Other Values
[!Note When converting to a date!, the year must be specified as four digits.
Conversions can be applied to various math operations on dates:
probe 5-Oct-1999 + 1
6-Oct-1999
probe 5-10-1999 - 10
25-Sep-1999
probe 5-Oct-1999/23:00 + 5:00
6-Oct-1999/4:00
Related
Use date? to determine whether a value is a date! data type.
probe date? 5/1/1999
true
The related function to-idate returns a standard Internet date string. The Internet
date format is day, date, month, year, time (24-hour clock), and time zone offset
from GMT.
probe to-idate now
Fri, 30 Jun 2000 14:42:26 -0700
The now function returns the current date and time in full format including the time
zone offset:
probe now
30-Jun-2000/14:42:26-7:00

Values
Other Values
Logic A
Concept
The logic! data type consists of two states representing true and false. They are
often returned from comparisons such as:
age: 100
probe age = 100
true
time: 10:31:00
probe time < 10:30
false
str: "this is a string"

probe (length? str) > 10
true
The logic! data type is most commonly used as parameters to conditional functions
such as if, while, and until:
if age = 100 [print "Centennial human"]
Centennial human
while [time > 6:30] [

send person "Wake up!"
wait [0:10]
]
The complement of a logic value is obtained from the not function:
there: place = "Ukiah"

if not there [...]

Values
Other Values
Format
Normally, logic values are retrieved from the evaluation of comparison expressions.
However, words can be set to a logic value and used to turn the word on or off:
print-me: false
print either print-me ["turned on"]["turned off"]
turned off
print-me: true
turned on
The false value is not equivalent to integer zero or none. However, in conditional
expressions false and none have the same effect:
print-me: none
turned off
Just about any value assigned to a word has the same effect as true:
print-me: "just a string"

turned on
print-me: 11-11-1999
turned on
The following words are predefined to hold logic values:
true
on ;same as true
yes ;same as true
false
off ;same as false
no ;same as false

Values
Other Values
So, instead of true and false, when it makes sense, the words on and off, or yes and
no can be used instead:
print-me: yes
turned on
print-me: no
turned off
print-me: on
turned on
print-me: off
turned off

Values
Other Values
Creation
The to-logic function converts integer! or none! values to the logic! data type:
probe to-logic 0
false
probe to-logic 200
true
probe to-logic none
false
probe to-logic []
true
probe to-logic "a"
true
probe to-logic none
false
Related
Use logic? to determine whether a value is a logic! data type.
probe logic? 1
false
probe logic? on
true
probe logic? false
true

Values
Other Values
Use the functions form, print, and mold to print a logic value:
probe form true
true
probe mold false
false
print true
true
Money A
Concept
There is a wide variety of international symbols for monetary denominations. Some
symbols are used before the amount and some after. As a standard for representing
international monetary values, the REBOL language uses the United States
monetary format , but allows the inclusion of specific denominations.
Format
The money! data type uses standard IEEE floating point numbers allowing up to 15
digits of precision including cents.
The language limits the length to 64 characters. Values that are out of range or
cannot be represented in 64 characters are flagged as an error.

Values
Other Values
Monetary values are prefixed with an optional currency designator, followed by a

dollar sign ($). A plus (+) or minus (-) can appear immediately before the first
character (currency designator or dollar sign) to indicate sign.
$123
-$123
$123.45
US$12
US$12.34
-US$12.34
$12,34
-$12,34
DEM$12,34
To break long numbers into readable segments, a single quote (‘) can be placed
anywhere between two digits within the amount, but not before the amount.
probe $1’234.56
$1234.56
probe $1’234’567,89
$1234567.89
Do not use commas and periods to break up large amounts,

as both these characters represent decimal points.
The money! data type is a hybrid data type. Conceptually money is scalar—an
amount of money. However, because the currency designation is stored as a string,
the money! data type has two elements:
string! – The currency designator string, which can have 3 characters

maximum.
decimal! – The money amount.
To demonstrate this, the following money is specified with the USD prefix:
my-money: USD$12345.67

Values
Other Values
Here are the two components:
probe first my-money
USD
probe second my-money
12345.67
probe pick my-money 3 ; only two components
none
If no currency designator is used, the currency designator string is empty:
my-money: $12345.67
""
12345.67
Various international currencies can be specified in the currency designator, such

as:
my-money: DKM$12’345,67
DKM
12345.67

Values
Other Values
Creation
Use the to-money function to convert money from a string!, integer!, decimal!, or
block!.
probe to-money 123
$123.00
probe to-money "123"
$123.00
probe to-money 12.34
$12.34
probe to-money [DEM 12.34]
DEM$12.34
probe to-money [USA 12 34]
USA$12.34
Money can be added, subtracted, and compared with other money of the same
currency. An error occurs if a different currency is used for such operations
(automatic conversions are not currently supplied).
probe $100 + $10
$110.00
probe $100 - $50
$50.00
probe equal? DEM$100.11 DEM$100.11
true

Values
Other Values
Money can be multiplied and divided by integers and decimals. Money can also be
divided by money, resulting in an integer or decimal.
probe $100 + 11
$111.00
probe $100 / 4
$25.00
probe $100 * 5
$500.00
probe $100 - 20.50
$79.50
probe 10 + $1.20
$11.20
probe 10 - $0.25
$9.75
probe $10 / .50
$20.00
probe 10 * $0.75
$7.50
Related
Use money? to determine whether a value is an money! data type.
probe money? USD$12.34
true

Values
Other Values
Use the form, print, and mold functions with a money argument to print a money
value with the currency designator and dollar sign ($), as a decimal number with
two digits of decimal precision.
probe form USD$12.34
USD$12.34
probe mold USD$12.34
USD$12.34
print USD$12.34
USD$12.34
None A
Concept
The none! data type contains a single value that represents nothing or no value.
The concept of none is not the same as an empty block, empty string, or null
character. It is an actual value that represents non-existence.
A none! value can be returned from various functions, primarily those involving
series (for example, pick and find).
The REBOL word none is defined as a none! data type and contains a none! value.
The word none is not equivalent to zero or false. However, none is interpreted as
false by many functions.
A none! value has many uses such as a return value from series functions like pick,
find and select:
if (pick series 30) = none [...]

Values
Other Values
In databases, a none can be a placeholder for missing values:
email-database: [
"Bobby" [email protected] 40
"Linda" none 23
"Sara" [email protected] 33
]
It also can be used as a logic value:
secure none
Format
The word none is predefined to hold a none value.
Although none is not equivalent to zero or false, it is valid within conditional

expressions and has the same effect as false:
probe find "abcd" "e"
none
if find "abcd" "e" [print "found"]
Creation
The to-none function always returns none.
Related
Use none? to determine whether a value is an integer! data type.
print none? 1
false
print none? find [1 2 3] 4
true

Values
Other Values
The form, print, and mold functions print the value none when passed a none
argument.
probe form none
none
probe mold none
none
print none
none
Pair A
Concept
A pair! data type is used to indicate spatial coordinates, such as positions on a
display. They are used for both positions and sizes. Pairs are used primarily in
REBOL/View.
Format
A pair is specified as integers separated by an x character.
100x50
1024x800
-50x200

Values
Other Values
Creation
Use to-pair to convert block or string values into a pair data type:
p: to-pair "640x480"
probe p
640x480
p: to-pair [800 600]

probe p
800x600
Related
Use pair? to determine whether a value is a pair! data type:
probe pair? 400x200
true
probe pair? pair
true
Pairs can be used with most integer math operators:
100x200 + 10x20
10x20 * 2x4
100x30 / 10x3
100x100 * 3
10x10 + 3

Values
Other Values
Pairs can be viewed by their individual coordinates:
pair: 640x480
probe first pair
640
probe second pair
480
All pair values support the /x and /y refinements. These refinements allow the
viewing and manipulation of individual pair coordinates.
Viewing individual coordinates:
probe pair/x
640
probe pair/y
480
Modifying individual coordinates:
pair/x: 800
pair/y: 600
probe pair
800x600
Time A
Concept
The REBOL language supports the standard expression of time in hours, minutes,
seconds, and subseconds. Both positive and negative times are permitted.
The time! data type uses relative rather than absolute time. For example, 10:30 is
10 hours and 30 minutes rather than the time of 10:30 A.M. or P.M.

Values
Other Values
Format
Times are expressed as a set of integers separated by colons (:).. Hours and minutes
are required, but seconds are optional. Within each field, leading zeros are ignored:
10:30
0:00
18:59
23:59:50
8:6:20
8:6:2
The minutes and seconds fields can contain values greater than 60. Values greater
than 60 are automatically converted. For instance 0:120:00 is the same as 2:00.
probe 00:120:00
2:00
Subseconds are specified using a decimal in the seconds field. Use either a period
or a comma as the decimal point. The hours and minutes fields become optional
when the decimal is present. Subseconds are encoded to the nano-second, or one
billionth of a second:
probe 32:59:29.5
32:59:29.5
probe 1:10,25
0:01:10.25
probe 0:0.000000001
0:00:00.000000001
probe 0:325.2
0:05:25.2

Values
Other Values
Times can be followed by AM or PM, but no space is permitted. PM adds 12 hours

to the time:
probe 10:20PM
22:20
probe 3:32:20AM
3:32:20
Times are output in a standard hours, minutes, seconds, and subseconds format,
regardless of how they are entered:
probe 0:87363.21
24:16:03.21
Access
Time values have three refinements that can be used to return specific information
about the value:
Table A-4. Time Value Refinements
/hour Gets the value’s hour.

/minute Gets the value’s minute.
/second Gets the value’s second.

Values
Other Values
Here’s how to use a time value’s refinements:
lapsed-time: 91:32:12.14
probe lapsed-time/hour
91
probe lapsed-time/minute
32
probe lapsed-time/second
12.14
Times with time zones can only be used with the date! .
Creation
Times can be converted using the to-time function:
probe to-time "10:30"
10:30
probe to-time [10 30]
10:30
probe to-time [0 10 30]
0:10:30
probe to-time [10 30 20.5]
10:30:20.5
In the previous examples, the values are not evaluated. To evaluate values as
mathematical expressions, use the reduce function:
probe to-time reduce [10 30 + 5]
10:35

Values
Other Values
In various math operations involving time values, the time values, integers, or
decimals are converted as shown below:
probe 10:30 + 1
10:30:01
probe 10:00 - 10
9:59:50
probe 0:00 - 10
-0:00:10
probe 5:10 * 3
15:30
probe :0.000000001 * 1’500’600
0:00:00.0015006
probe 8:40:20 / 4
2:10:05
probe 8:40:20 / 2:20:05
probe 8:40:20 // 4:20
0:00:20

Values
Other Values
Related
Use time? to determine whether a value is a time! data type:
probe time? 10:30
true
probe time? 10.30
false
Use the now function with the /time refinement to return the current local date and
time:
print now/time
14:42:15
Use the wait function to wait for a duration, port, or both.
If a value is a time! data type, wait delays for that period of time. If a value is a
date!/time!, wait waits until the indicated date and time. If the value is an integer!
or decimal!, the function waits the indicated number of seconds. If the value is a
port, the function will wait for an event from that port. If a block is specified, it will
wait for any of the times or ports to occur. It returns the port that caused the wait
to complete or returns none if the timeout occurred. For example,
probe now/time
14:42:16
wait 0:00:10
probe now/time
14:42:26

Values
Other Values
Tuple A
Concept
It is common to represent version numbers, Internet addresses, and RGB color
values as a sequence of three or four integers. These types of numbers are called a
tuple! (as in quintuple) and are represented as a set of integers separated by
periods.
1.3.0 2.1.120 1.0.2.32 ; version

199.4.80.250 255.255.255.0 ; net addresses/masks
0.80.255 200.200.60 ; RGB colors
Format
Each integer field of a tuple! data type can range between 0 and 255. Negative
integers produce an error.
Three to ten integers can be specified in a tuple. In the case where only two integers
are given, there must be at least two periods, otherwise the value is treated as a
decimal.
probe 1.2 ; is decimal
1.2
probe type? 1.2
decimal!
probe 1.2.3 ; is tuple
1.2.3
probe 1.2. ; is tuple
1.2.0
probe type? 1.2.
tuple!

Values
Other Values
Creation
Use the to-tuple function to convert data to the tuple! data type:
probe to-tuple "12.34.56"
12.34.56
probe to-tuple [12 34 56]
12.34.56
Related
Use tuple? to determine whether a value is a tuple! data type.
probe tuple? 1.2.3.4
true
Use the form function to print a tuple as a string:
probe form 1.2.3.4
1.2.3.4
Use the mold function to convert a tuple into a string that can be read back into
REBOL as a tuple:
probe mold 1.2.3.4
1.2.3.4
Use the print function to print a tuple to standard output after using the reform
function:
print 1.2.3.4
1.2.3.4

Values
Other Values
Words A
Concept
Words are the symbols used by REBOL. A word may or may not be a variable,
depending on how it is used. Words are often used directly as symbols.
REBOL has no keywords, there are no restrictions on what words are used or how
they are used. For instance, you can define your own function called print and
use it instead of the predefined function for printing values.
There are four different formats for using words, depending on the operation
required.
Table A-5. Word Use Formats
Action Type Word Type Test Conversion
word: set-word! set-word? to-set-word

:word get-word! get-word? to-get-word
word word! word? to-word
’word lit-word! lit-word? to-lit-word
Format
Words are composed of alphabetic characters, numbers, and any of the following
characters:
? ! . ’ + - * & | = _ ~
A word cannot begin with a number, and there are also some restrictions on words
that could be interpreted as numbers. For instance, -1 and +1 are numbers, not
words.
The end of a word is marked by a space, a newline, or one of the following

characters:
[ ] ( ) { } " : ; /

Values
Other Values
Thus, the square brackets of a block are not part of a word:
[test]
The following characters are not allowed in words:
@ # $ % ^ ,
Words can be of any length, but cannot extend past the end of a line.
this-is-a-very-long-word-used-as-an-example
Sample words are:
Copy print test
number? time? date!
++ -- == +-
***** *new-line*
The REBOL language is not case-sensitive. The words following words:
blue
Blue
BLUE
all refer to the same word. The case of the word is preserved when it is printed.
Words can be reused. The meaning of a word is dependent on its context, so words
can be reused in different contexts. You can reuse any word, even predefined REBOL
words. For instance, the REBOL word if can be used in your code differently than
how it is used by the REBOL interpreter.

Values
Other Values
Creation
The to-word function converts values to the word! data type.
probe to-word "test"
test
The to-set-word function converts values to the set-word! data type.
probe make set-word! "test"
test:
The to-get-word function converts values to the get-word! data type.
probe to-get-word "test"
:test
The to-lit-word function converts values to the lit-word! data type.
probe to-lit-word "test"
’test
Related
Use word?, set-word?, get-word?, and lit-word? to test the data type.
probe word? second [1 two "3"]
true
if set-word? first [word: 10] [print "it is set"]
it is set
probe get-word? second [pr: :print]
true
probe lit-word? first [’foo bar]
true

Values
Other Values

Appendix B
Errors
This appendix gives basic information on error types and how to use them in
REBOL. It includes the following information:
■ “Overview” on page B-2

■ “Error Categories” on page B-2
■ “Catching Errors” on page B-3
■ “Error Object” on page B-6

■ “Generating Errors” on page B-7
■ “Error Messages” on page B-11
B- 1
Errors
Overview
Overview B
Errors are exceptions that occur when certain irregular conditions occur. These
conditions range from syntax errors to file or network access errors. Here are a few
examples:
12-30
** Syntax Error: Invalid date -- 12-30.

** Where: (line 1) 12-30
1 / 0

** Where: 1 / 0
read %nofile.r
** Access Error: Cannot open /example/nofile.r.

** Where: read %nofile.r
Errors are processed within the system as values of the error! datatype. An error is
an object that, if evaluated, will print an error message and halt. You can also catch
errors and handle them in your script. Errors can be passed to functions, returned
from functions, and assigned to variables.
Error Categories B
There are several categories of errors.
Syntax Errors B
Syntax errors occur when a script uses REBOL syntax incorrectly. For instance, if a
closing bracket is missing or a string is missing its closing quote, a syntax error will
occur. These errors only occur during the load or evaluation of a file or string.
B-2 REBOL/Core User Guide Version 2.3

Errors
Catching Errors
Script Errors B
Script errors are general run-time errors. For instance, an invalid argument to a
function will cause a script error.
Math Errors B
Math errors occur when a math operation cannot be processed. For instance, when
attempting to divide by zero an error will occur.
Access Errors B
Access errors occur when a problem occurs with a file, port or network access. For
example, an access error will occur when attempting to read a file that does not
exist.
User Errors B
User errors are generated explicitly by a script by creating an error value and
returning it.
Internal Errors B
Internal errors occur within the REBOL interpreter.
Catching Errors B
You can catch errors with the try function. The try function is similar to the do
function. It evaluates a block, but always returns a value, even when an error
occurs.
When no error occurs, try returns the value of a block. For example:
print try [100 / 10]
10
REBOL/Core User Guide Version 2.3 B- 3

Errors
Catching Errors
When an error occurs, try returns the error. If you write:
print try [100 / 0]

** Where: 100 / 0
the error is returned from the try and the print function cannot handle it.
To handle errors in a script, you must prevent REBOL from evaluating the error. You
can prevent an error from being evaluated by passing it to a function. For instance,
the error? function will return true when it is passed an error:
print error? try [100 / 0]
true
You can also print the data type of the value returned from a try:
print type? try [100 / 0]
error!
The disarm function converts an error to an error object that can be examined. In
the example below, the error variable holds an error object:
error: disarm try [100 / 0]

Errors
Catching Errors
When an error is disarmed, it will be an object! data type, not an error! datatype.
Evaluating the disarmed object will not cause an error:
probe disarm try [100 / 0]
make object! [
code: 400
type: 'math
id: 'zero-divide
arg1: none
arg2: none
arg3: none
near: [100 / 0]
where: none
]
Error values can be set to a word before they are disarmed. To set a word to an error,
it must be preceded by a function that prevents the error from propagating further.
For example:
disarm err: try [100 / 0]
Setting a variable enables you to access the value of the block later. The example
below will print an error or non-error value:
either error? result: try [100 / 0] [

probe disarm result
][
print result
]

Errors
Error Object
Error Object B
The error object shown above has the structure:
make object! [
code: 400
type: 'math
id: 'zero-divide
arg1: none
arg2: none
arg3: none
near: [100 / 0]
where: none
]
Table B-1. Error Object Fields
Field Description
code The error code number. These are obsolete and should not be
used.
type The type field identifies the error category. It is always a word
data type of syntax, script, math, access, user and
internal.
id The id field is the name for the error. It identifies the specific
error that occurred within the error category.
arg1, arg2, arg3 These fields hold the arguments to the error message. For
instance, they may include the data type of the value that
caused the error.
near The near field is a code fragment that shows where the error
occurred.
where The where field is reserved.

Errors
Generating Errors
You can write code that checks any of the error object fields. In this example, the
error is printed only when the error id indicates a divide by zero error:
error: disarm try [1 / 0]

if error/id = ’zero-divide [
print {It is a Divide by Zero error}
]
It is a Divide by Zero error
The error id word also provides the error block that will be printed by the
interpreter. For example:
error: disarm try [print zap]

probe get error/id
[:arg1 "has no value"]
This block is defined by the system/errors object.
Generating Errors B
User errors can be generated. The simplest way to generate an error is make it. Here
is an example:
make error! "this is an error"
** User Error: this is an error.

** Where: make error! "this is an error"

Errors
Generating Errors
Any of the existing errors can be generated by making the error with a block
argument. This block contains the error category name and the error message id
name. If the error requires arguments, the arguments follow the message id name.
The arguments are what define the arg1, arg2 and arg3 values in the error
object. Here is an example:
make error! [script expect-set series! number!]
** Script Error: Expected one of: series! - not: number!.

** Where: make error! [script expect-set series! number!]
Custom errors can be entered into the system/error object’s user category. This
is done by making a new user category with new entries. These entries are used
when generating errors. For instance, the following example enters an error into the
user category:
system/error/user: make system/error/user [

my-error: "a simple error"
]
Now an error can be generated using the my-error message id:
if error? err: try [

make error! [user my-error]
] [probe disarm err]
make object! [
code: 803
type: ’user
id: ’my-error
arg1: none
arg2: none
arg3: none
near: [make error! [user my-error]]
where: none
]

Errors
Generating Errors
To create more informative errors, define an error that uses data available when it
is generated. This data is included in the disarmed error object and printed as part
of the error message. For instance, to use all three argument spaces in an error
object:
system/error/user: make system/error/user [

my-error: [:arg1 "doesn’t go into" :arg2 "using"
:arg3]
]
if error? err: try [

make error! [user my-error [this] "that" my-function]
] [probe disarm err]
make object! [
code: 803
type: ’user
id: ’my-error
arg1: [this]
arg2: "that"
arg3: ’my-function
near: [make error! [user my-error [this] "that"
my-function]]
where: none
]
The error message generated for my-error can be printed without stopping the
script:
disarmed: disarm err

print bind (get disarmed/id) (in disarmed ’id)
this doesn’t go into that using my-function

Errors
Generating Errors
A new library category may be created if there is a need to group a series of errors
together by making a new category in system/error:
system/error: make system/error [

my-errors: make object! [
code: 1000
type: "My Error Category"
error1: "a simple error"
error2: [:arg1 "doesn’t go into" :arg2 "using"
:arg3]
]
]
The type defined in the error object will be the error type printed when the error is
generated. The following example illustrates generating an error from both error1
and error2 in the my-error category.
Generating an error from error1. This error requires no arguments:
disarmed: disarm try [make error! [my-errors error1]]

print get disarmed/id
a simple error
Generating an error from error2 requires three arguments:
disarmed: disarm try [

make error! [my-errors error2 [this] "that" my-func-
tion]]
print bind (get disarmed/id) (in disarmed ’id)
this doesn’t go into that using my-function
Finally, the description that returns the errors defined in my-errors may be
obtained with:
probe get in get disarmed/type ’type
My Error Category

Errors
Error Messages
Error Messages B
Listed below is a list of all errors defined in the system/error object error catalog.
Syntax Errors B
Message ID: invalid
Data could not be translated into a valid REBOL datatype. In other words, a
malformed value was evaluated.
Message:
["Invalid" :arg1 "--" :arg2]
Example:
filter-error try [load "1024AD"]
** Syntax Error: Invalid integer -- 1024AD

** Where: (line 1) 1024AD
Message ID: missing
A block, string or paren expression was left unclosed.
Message:
["Missing" :arg2 "at" :arg1]
Example:
filter-error try [load "("]
** Syntax Error: Missing ) at end-of-script

** Where: (line 1) (

Errors
Error Messages
Message ID: header
An attempt was made to evaluate a file as a REBOL script and the file did not have
a REBOL header.
Message:
Script is missing a REBOL header
Example:
write %no-header.r {print "data"}

filter-error try [do %no-header.r]
** Syntax Error: Script is missing a REBOL header

** Where: do %no-header.r
Script Errors B
Message ID: no-value
An attempt was made to evaluate an undefined word.
Message:
[:arg1 "has no value"]
Example:
filter-error try [undefined-word]
** Script Error: undefined-word has no value

** Where: undefined-word
Message ID: need-value

Errors
Error Messages
An attempt was made to define a word to nothing. A set-word was used without an
argument.
Message:
[:arg1 "needs a value"]
Example:
filter-error try [set-to-nothing:]
** Script Error: set-to-nothing needs a value

** Where: set-to-nothing:
Message ID: no-arg
A function was evaluated without providing it with all the arguments it was
expecting.
Message:
[:arg1 "is missing its" :arg2 "argument"]
Example:
f: func [b][probe b]
filter-error try [f]
** Script Error: f is missing its b argument

** Where: f
Message ID: expect-arg
A function was provided an argument of a datatype it wasn’t expecting.
Message:
[:arg1 "expected" :arg2 "argument of type:" :arg3]

Errors
Error Messages
Example:
f: func [b [block!]][probe b]
filter-error try [f "string"]
** Script Error: f expected b argument of type: block

** Where: f "string"
Message ID: expect-set
Two series values were used together in a way that was not compatible. For
instance, when trying to do a union between a string and a block.
Message:
["Expected one of:" :arg1 "- not:" :arg2]
Example:
filter-error try [union [a b c] "a b c"]
** Script Error: Expected one of: block! - not: string!

** Where: union [a b c] "a b c"
Message ID: invalid-arg
This is a generic error for handling values that were used improperly. For instance,
when a set-word is used inside of a function’s specification block.
Message:
["Invalid argument:" :arg1]

Errors
Error Messages
Example:
filter-error try [f: func [word:][probe word]]
** Script Error: Invalid argument: word

** Where: func [word:] [probe word]
Message ID: invalid-op
An attempt was made to use an operator that had been redefined. The operator used
is no longer a valid operator.
Message:
["Invalid operator:" :arg1]
Example:
*: "operator redefined to a string"

filter-error try [5 * 10]
** Script Error: Invalid operator: *

** Where: 5 * 10
Message ID: no-op-arg
A math or comparison operator was used without providing the second argument.
Message:
Operator is missing an argument
Example:
filter-error try [1 +]
** Script Error: Operator is missing an argument

** Where: 1 +

Errors
Error Messages
Message ID: no-return
A function expecting a block to return a value did not return anything. For instance,
when using the while or until function.
Message:
Block did not return a value
Examples:
filter-error try [ ; first block returns nothing

while [print 10][probe "ten"]
]
10
** Script Error: Block did not return a value
** Where: while [print 10] [probe "ten"]
filter-error try [
until [print 10] ; block returns nothing
]
10
** Script Error: Block did not return a value
** Where: until [print 10]
Message ID: not-defined
A word used was not defined within any context.
Message:
[:arg1 "is not defined in this context"]
Message ID: no-refine
An attempt was made to use a function refinement that didn’t exist for that
function.

Errors
Error Messages
Message:
[:arg1 "has no refinement called" :arg2]
Example:
f: func [/a] [if a [print "a"]]

filter-error try [f/b]
** Script Error: f has no refinement called b

** Where: f/b
Message ID: invalid-path
An attempt was made to access a block or object value using a path that did not
exist within that block or object.
Message:
["Invalid path value:" :arg1]
Example:
blk: [a "a" b "b"]

filter-error try [print blk/c]
** Script Error: Invalid path value: c

** Where: print blk/c
obj: make object! [a: "a" b: "b"]

filter-error try [print obj/d]
** Script Error: Invalid path value: d

** Where: print obj/d
Message ID: cannot-use
An attempt was made to perform an operation on a value of an incompatible

datatype. For instance, when attempting to add a string to a number.

Errors
Error Messages
Message:
["Cannot use" :arg1 "on" :arg2 "value"]
Example:
filter-error try [1 + "1"]
** Script Error: Cannot use add on string! value

** Where: 1 + "1"
Message ID: already-used
An attempt was made to alias a word that had already been aliased.
Message:
["Alias word is already in use:" :arg1]
Example:
alias ’print "prink"

filter-error try [alias ’probe "prink"]
** Script Error: Alias word is already in use: prink

** Where: alias ’probe "prink"
Message ID: out-of-range
An attempt was made to modify an invalid series index.
Message:
["Value out of range:" :arg1]

Errors
Error Messages
Example:
blk: [1 2 3]
filter-error try [poke blk 5 "five"]
** Script Error: Value out of range: 5

** Where: poke blk 5 "five"
Message ID: past-end
An attempt was made to access series data beyond the length of the series.
Message:
Out of range or past end
Example:
blk: [1 2 3]
filter-error try [print fourth blk]
** Script Error: Out of range or past end

** Where: print fourth blk
Message ID: no-memory
The system ran out of memory while trying to complete an operation.
Message:
Not enough memory
Message ID: wrong-denom
A math operation was performed on money values of two different denominations.

For instance, when trying to add USD$1.00 to DEN$1.50.

Errors
Error Messages
Message:
[:arg1 "not same denomination as" :arg2]
Example:
filter-error try [US$1.50 + DM$1.50]
** Script Error: US$1.50 not same denomination as DM$1.50

** Where: US$1.50 + DM$1.50
Message ID: bad-press
An attempt was made to decompress a binary value that was corrupt or not a
compressed format.
Message:
["Invalid compressed data - problem:" :arg1]
Example:
compressed: compress {some data}

change compressed "1"
filter-error try [decompress compressed]
** Script Error: Invalid compressed data - problem: -3

** Where: decompress compressed
Message ID: bad-port-action
An attempt was made to perform an unsupported action on a port. For instance,

when trying to use find on a TCP port.
Message:
["Cannot use" :arg1 "on this type port"]

Errors
Error Messages
Message ID: needs
An attempt was made to run a script that needed either a new version of REBOL or
a file that couldn’t be found. This information will be found in the script’s REBOL
header.
Message:
["Script needs:" :arg1]
Message ID: locked-word
An attempt was made to modify a protected word. The word will have been
protected with the protect function.
Message:
["Word" :arg1 "is protected, cannot modify"]
Example:
my-word: "data"
protect ’my-word
filter-error try [my-word: "new data"]
** Script Error: Word my-word is protected, cannot modify

** Where: my-word: "new data"
Message ID: dup-vars
A function was evaluated that had multiple occurrences of a word defined in its
specification block. For instance, if the word arg was defined as both argument one
and two.
Message:
["Duplicate function value:" :arg1]

Errors
Error Messages
Example:
filter-error try [f: func [a /local a][print a]]
** Script Error: Duplicate function value: a

** Where: func [a /local a] [print a]
Access Errors B
Message ID: cannot-open
A file could not be accessed. This could be a local or network file. Most common
reason for this error is a nonexistent directory.
Message:
["Cannot open" :arg1]
Example:
filter-error try [read %/c/path-not-here]
** Access Error: Cannot open /c/path-not-here

** Where: read %/c/path-not-here
Message ID: not-open
An attempt was made to use a port that was closed.
Message:
["Port" :arg1 "not open"]

Errors
Error Messages
Example:
p: open %file.txt
close p
filter-error try [copy p]
** Access Error: Port file.txt not open

** Where: copy p
Message ID: already-open
An attempt was made to open a port that was already open.
Message:
["Port" :arg1 "already open"]
Example:
p: open %file.txt
filter-error try [open p]
** Access Error: Port file.txt already open

** Where: open p
Message ID: already-closed
An attempt was made to close a port that had already been closed.
Message:
["Port" :arg1 "already closed"]

Errors
Error Messages
Example:
p: open %file.txt
close p
filter-error try [close p]
** Access Error: Port file.txt not open

** Where: close p
Message ID: invalid-spec
An attempt was made to create a port with make using a specification that a port
could not be built from.
Message:
["Invalid port spec:" :arg1]
Example:
filter-error try [p: make port! [scheme: ’naughta]]
** Access Error: Invalid port spec: scheme naughta

** Where: p: make port! [scheme: ’naughta]
Message ID: socket-open
The operating system ran out of sockets to allocate.
Message:
["Error opening socket" :arg1]
Message ID: no-connect
A connection to another host failed. This is generic error covering a range of reasons
for the connection failure. When more information is known about the reason for
the connection failure, a more specific error will be thrown.

Errors
Error Messages
Message:
["Cannot connect to" :arg1]
Example:
filter-error try [read http://www.host.dom/]
** Access Error: Cannot connect to www.host.dom

** Where: read http://www.host.dom/
Message ID: no-delete
An attempt was made to delete a file that was either locked or protected.
Message:
["Cannot delete" :arg1]
Example:
p: open %file.txt
filter-error try [delete %file.txt]
** Access Error: Cannot delete file.txt

** Where: delete %file.txt
Message ID: no-rename
An attempt was made to rename a file that was either locked or protected.
Message:
["Cannot rename" :arg1]

Errors
Error Messages
Example:
p: open %file.txt
filter-error try [rename %file.txt %new-name.txt]
** Access Error: Cannot rename file.txt

** Where: rename %file.txt %new-name.txt
Message ID: no-make-dir
An attempt was made to create a directory in a file path that did not exist or was
write protected.
Message:
["Cannot make directory" :arg1]
Example:
filter-error try [make-dir %/c/no-path/dir]
** Access Error: Cannot make directory /c/no-path/dir/

** Where: m-dir path return path
Message ID: timeout
The timeout period elapsed while waiting to for a response from another host. This
timeout is set in the port’s timeout attribute.
Message:
Network timeout
Message ID: new-level
An attempt was made within a script to change the security to a lower level of
security that was denied. This is to say, whenever a script requests a lower security
setting and the user denies the request, this error is thrown.

Errors
Error Messages
Message:
["Attempt to change security level to" :arg1]
Example:
secure quit
filter-error try [secure none] ; denied request
secure none
Message ID: security
A security violation occurred. This will happen when an attempt is made to access
a file or the network when the secure setting is set to throw.
Message:
REBOL - Security Violation
Example:
secure throw
filter-error try [open %file.txt]
** Access Error: REBOL - Security Violation

** Where: open %file.txt
secure none
Message ID: invalid-path
A malformed file path was used.
Message:
["Bad file path:" :arg1]

Errors
Error Messages
Example:
filter-error try [read %/]
Internal Errors B
Message ID: bad-path
A path was evaluated that began with an invalid word.
Message:
["Bad path:" arg1]
Example:
path: make path! [1 2 3]

filter-error try [path]
** Internal Error: Bad path: 1

** Where: path
Message ID: not-here
An attempt was made to use a REBOL/Command or REBOL/View feature from

REBOL/Core.
Message:
[arg1 "not supported on your system"]
Message ID: stack-overflow
The system’s memory stack overflowed while trying to perform an operation.

Errors
Error Messages
Message:
["Stack overflow"]
Example:
call-self: func [][call-self]

filter-error try [call-self]
** Internal Error: Stack overflow

** Where: call-self
Message ID: globals-full
The maximum allowable number of defined global words has been exceeded.
Message:
["No more global variable space"]

Errors
Error Messages

Appendix C
Console
This appendix gives basic information on using, configuring and directly accessing
the console in REBOL. It includes the following information:
■ “Command Prompt” on page C-2

■ “History Recall” on page C-2
■ “Busy Indicator” on page C-3
■ “Advanced Console Operations” on page C-3
C- 1
Console
Command Prompt
Command Prompt C
The default command line prompt is >>. You can change the prompt with code
such as:
system/console/prompt: "Input: "
The prompt then becomes:
Input:
The prompt can be a block that is evaluated each time. This line prints the current
time:
system/console/prompt: [reform [now/time " >> "]]
This would result in a prompt of:
10:30 >>
The default result indicator is == and can be modified with a line such as:
system/console/result: "Result: "
These settings can be placed in the user.r file to make them permanent.
History Recall C
Each line typed into REBOL at the prompt is stored in a history block, and it 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 is accessed from the system console
object:
probe system/console/history
You can save the history block as a file:
save %history.r system/console/history
C- 2 REBOL/Core User Guide Version 2.3

Console
Busy Indicator
and it can be reloaded later with:
system/console/history: load %history.r
These lines can be put in the user.r file to save and reload your history
between REBOL sessions.
Busy Indicator C
When REBOL waits for a network operation to complete, a busy indicator appears
on screen to indicate that something is happening. You can change the indicator
with a line like:
system/console/busy: "123456789-"
Whe REBOL is running in quiet mode, te busy indicator will not be displayed.
Advanced Console Operations C
The console provides "virtual terminal" capability that allows you to perform
operations such as cursor movement, cursor addressing, line editing, screen
clearing, control key input, and cursor position querying.
The console control sequences follow the ANSI standard. These features provide
you with the capability to write your own platform-independent terminal programs
such as text editors, email clients, or telnet emulators.
The console features apply to both input and output. On input, function keys will
be converted to multiple-character escape sequences. On output, multiple-character
escape sequences can be used to control the display of text in the console window.
Both the input and output sequences begin with the ANSI escape character, 27
decimal (1B hex). The next character in the sequence indicates the control keys on
input or the terminal control operation on output.
NOTE: The ANSI control characters are case-sensitive and normally require an upper
case character.
REBOL/Core User Guide Version 2.3 C- 3

Console
Advanced Console Operations
Keyboard Input Sequences C
The special keys and second character in the sequence are included in the following
table:
[! Need the Table
Terminal Output Sequences C
There are several variations in the terminal control output character sequences.
Some command codes are preceded by a number (sent in ASCII) indicating that the
operation is to be performed the specified number of times. For example the cursor
motion command may be preceded by two numbers separated by a semicolon to
indicate the row and column position to move to. The cursor command characters
(upper case required) are included in the following table:
Table C-1. Terminal Output Sequence Examples
Output Sequence Description
(1B) Use this escape code prior to the following codes

D Moves cursor one space left
C Moves cursor one space right
A Moves cursor one space up
B Moves cursor one space down
nD Moves cursor n spaces left
nC Moves cursor n spaces right
nA Moves cursor n spaces up
nB Moves cursor n spaces down
r;cH Moves cursor to row r, column c*
H Moves cursor to top left corner (home)*
P Deletes one character to the right at current location
nP Deletes n characters to the right at current location

Console
Table C-1. Terminal Output Sequence Examples
Output Sequence Description
@ Inserts one blank space at current location

n@ Inserts n blank spaces at current location
J Clears screen and moves cursor to top left corner (home)*
K Clears from current position to end of current line
6n Places the current cursor position in the input buffer
7n Places screen dimensions in the input buffer
* Top left corner is defined as row 1, column 1
The following example moves the cursor to the right ten spaces:
print "^(1B)[10CHi!"
Hi
This example moves the cursor to the left seven spaces and clears the remainder of
the line:
cursor: func [parm [string!]][join "^(1B)[" parm]

print ["How are you" cursor "7D" cursor "K"]
How a
To find the current console window size, you can use this example:
cons: open/binary [scheme: ’console]

print cursor "7n" screen-dimensions: next next to-string
copy cons
33;105R
close cons
REBOL/Core User Guide Version 2.3 C- 5

Console
The above example opens the console, sends a control character to the input buffer
and copies the return value. It reads the value (screen dimensions) that is returned
after the control character and closes the console. The return value is the height and
width separated by a semicolon (;) and followed by an R. In the above example,
the screen is 33 high by 105 wide.
NOTE: Printing a character to the bottom-right corner of some terminals will cause a
new line, which will scroll the screen. Others will not. This inconsistency between
console terminal types must be considered when writing REBOL scripts intended to
be cross-platform.

Core

Uploaded by

Document Informationclick to expand document informationREBOL(tm) TECHNOLOGIES REBOL / CORE USER GUIDE VERSION 2. REBOL and the REBOL logo are trademarks of REBOL Technologies. All other product names, marks, logos, and symbols may be trademarks or registered trademarks of their respective owners.

Document Informationclick to expand document information

Copyright:

Available Formats

Core

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Core

Uploaded by

Copyright:

Available Formats

REBOL™ TECHNOLOGIES

Windows® is a registered trademark of Microsoft Corporation.

REBOL and the REBOL logo are trademarks of REBOL Technologies.

Carl Sassenrath Barbara Ramsey Erin Thomas Scott Allen

Jennifer Nelson Dan Ramsey Cynthia Sassenrath Dan Stevens

Dave Turner Jessica Johnson Mitch Rodgers Andrew Morton

Chapter 2. Quick Tour

Chapter 6. Block Series

Chapter 7. String Series

Chapter 10. Math

Chapter 11. Files

Chapter 13. Ports

Chapter 14. Parsing

This chapter provides an introduction to REBOL/Core. It contains the following

■ “About REBOL/Core” on page xxii

■ “Additional Documentation” on page xxiii

■ “Document Conventions” on page xxiii

■ “REBOL Welcomes Your Comments” on page xxiv

REBOL is the Relative Expression-Based Object Language designed by Carl

REBOL is a messaging language that provides a broad range of practical solutions

About this Guide 0

xx ii REBOL/Core User Guide Version 1.0

The following documentation should be used in conjunction with this guide:

Item Convention Example

Native REBOL words Bold make/library

Contacting REBOL Technical Support 0

If you encounter a problem, contact REBOL Technologies by sending an email

REBOL/Core User Guide Version 1.0 xxiii

REBOL Welcomes Your Comments 0

■ Title and version of the guide

Send comments and corrections to [email protected].

xx iv REBOL/Core User Guide Version 1.0

■ “Installing REBOL” on page 1-2

■ “Quitting REBOL” on page 1-14

■ “Using the Console” on page 1-14

■ “Errors” on page 1-25

■ “Upgrading” on page 1-26

For REBOL/Core, the only installation procedure is to uncompress the distribution

REBOL/Core includes the following distribution files:

■ rebol.exe or rebol—An executable program that starts the REBOL console.

■ rebol.r—A system bootstrap file.

■ setup.html-Information about the set-up and installation of REBOL/Core.

■ notes.html—Notes about the current release.

■ feedback.r—A script for submitting user feedback or questions to REBOL

■ docs.r—A script that downloads all current REBOL documentation.

To set up your network:

1-2 REBOL/Core User Guide Version 2.3

■ Type your email address. For example, [email protected].

Proxy and Firewall Settings 0

■ To provide proxy server information:

REBOL/Core User Guide Version 2.3 1- 3

socks - use the latest SOCKS version (5)

REBOL can be started by double-clicking the REBOL program icon, an associated

1-4 REBOL/Core User Guide Version 2.3

■ Drag the script to the program icon

■ Create a shortcut or alias icon.

From Another Application 0