REBOL
  Internet Communications LanguageTM

REBOL/Core
Release Notes

Version 2.3

(25-Jun-2000)

Contents

New Features

The following table shows a summary of new features in REBOL/Core 2.3:
 

New Features 

Description 
load/markup refinement returns a block of tags and text
repend function reduces argument before appending
replace/case allows case sensitive replace
?? function adds useful debugging function
to-pair function converts values into pairs
pair datatype new datatype that represents vectors and coordinates
offset? function returns the offset between series positions
does function shortcut for creating functions without arguments
unique function returns a series with duplicates removed
functions accepting pair! many existing functions now accept the pair value
make-dir/deep refinement allows creation of multiple depth directories

Enhancements

The following table shows a summary of enhancements made to existing functions and global objects in REBOL/Core 2.3:
 

Enhancement 

Description 
help function information is formatted differently. Help can now perform searches over internal documentation
http user-agent Http handler now allows setting the http user-agent
value/selector return returns the set value, not the aggregate value
random function now operates on negative values and tuples
system/options/path indicates directory the running rebol script is in
what function changed the way functions are listed; they are sorted now
build-tag accepts a wider range of values
parse can parse blocks
if, any and all functions changed false return values to none
pop handler contains information on messages sizes
and, or, xor AND, OR, and XOR now work on binary types.  The
        resulting binary will be as long as the longest of the two
        binary values.  The bitwise operations use the binary value's offset
        to determine where to start.
functions accepting pair! many functions now accept the pair value
query function changed to allow the querying of objects to determine changed words
load/next changed behavior with respect to script header
tab completion changed to show a list of possibilities upon hitting tab twice

Fixes

The following table shows a summary of fixes incorporated into REBOL/Core 2.3:
 

Fixes

Description 
to-block function fixed to work properly on path literals
to-word function fixed to properly convert set-word values into word values
trim/lines fixed so that it removes all extra white space
Networking Network activity can now be interrupted with the escape key
split-path function fixed so that the lowest level path splits correctly

New Functions and Refinements

The following new functions and refinements are incorporated in to REBOL/Core 2.3:

Pair Datatype

Pairs are datatypes used to describe the (x,y) coordinates of a point. This datatype is most commonly used to describe graphical objects and their screen positions, sizes offsets, etc. A pair datatype consists of two values separated by an upper or lowercase 'x' as in 10x20. Example: A: 10x20, defines A as a pair datatype consisting of the coordinates x=10, y=20. These values can be individually accessed using the refinements /x and /y as in: print A/x, which would print the value 10.

Make-dir/deep

Using the /deep refinement for make-dir will cause all directories in the supplied path to be created if those directories do not already exist. The following example uses make-dir/deep to create a long directory structure:
probe dir? %/c/abc
false

make-dir/deep %/c/abc/def/ghi/jkl/mno/pqr/stu/vwx/yz/
probe dir? %/c/abc
true

probe dir? %/c/abc/def/ghi/jkl/mno/pqr/stu/vwx/yz/
true

If make-dir/deep fails any directories that were created before failing will be removed.

Unique

Unique accepts a series argument and returns another series. The result of unique is a copy of the passed in series with out any duplicate items. Here are some examples demonstrating the behavior of unique:
probe unique "abcabcabc"
"abc"
probe unique [1 2 3 3 2 1 2 3 1]
[1 2 3]
The /case refinement may be used with unique to make the operation case sensitive.

Does

Use does to create functions with out arguments or locally defined words. For example:
get-script-dir: does [probe system/options/path]
probe get-script-dir
%/usr/local/rebol/

Offset?

Offset? takes two series as arguments and returns the distance between their two indexes.

The following example shows offset? being used on the same series:

colors: ["red" "green" "blue" "yellow" "orange"]
colors-2: skip colors 3
probe offset? colors colors-2
3
The example below shows how offset? can also be used with two different series:
str: "abcdef"
blk: skip [a b c d e f] 4
probe offset? str blk
4

Load/Markup

Using the /markup refinement for load causes the string, file or URL argument to be treated as markup data. (Files and URLs are first read in as strings by load.) All tags found in the argument to load/markup will be converted to a tag! value, and all other non tag data is left as a string. The result of load/markup is a block of tag! values and strings. The next example demonstrates the behavior of Load/markup:
probe load/markup {<head> 123 abc </head>}
[<head> { 123 abc } </head>]

Repend

Repend is short for "reduce append". Repend takes two arguments. The first argument is a series. The second argument to repend is reduced before it is appended to the first argument.

Here are some examples of using Repend:

a: "AA" b: "BB" c: "CC"
probe repend [] [a b c]
["AA" "BB" "CC"]

probe repend "" [a b c]
"AABBCC"

Replace/case

The replace function now has a /case refinement that forces case sensitive replacements. By default replace is case insensitive.

This example demonstrates using replace on a block without /case:

probe replace/all [A a B b A a B b] 'A 'C
[C C B b C C B b]

This example demonstrates replace on a block with /case:

probe replace/all/case [A a B b A a B b] 'A 'C
[C a B b C a B b]

This example demonstrates using replace on a string without /case:

probe replace/all "ABCabcDEFdefABCabcDEFdef" "abc" "xxx"
"xxxxxxDEFdefxxxxxxDEFdef"

This example demonstrates using replace on a string with /case:

probe replace/all/case "ABCabcDEFdefABCabcDEFdef" "abc" "xxx"
"ABCxxxDEFdefABCxxxDEFdef"

??

?? accepts one argument of any data type.

As an aid to debugging, if a word is supplied to ?? that word will printed out along with the mold of its value. Like the behavior of probe, ?? returns the unevaluated value of its argument so that ?? can be used transparently within arbitrary REBOL expressions. When ?? is used directly on a non word value the molded value is printed and the unevaluated value is returned.

The next example demonstrates using ?? on a word defined to a block:

blk: ["a" block 'of [values]]
?? blk
blk: ["a" block 'of [values]
The next example demonstrates using ?? on a word defined as a function:
?? probe
probe: func [
    {Prints a molded, unevaluated value and returns the same value.}
    value
][
    print mold :value :value
]
The next example demonstrates using ?? on a non word value:
?? 12:30pm
12:30

To-pair

To-pair accepts one argument of any data type.

To-pair attempts to convert the supplied argument into a pair value.

The next example demonstrates using to-pair with a block:

probe to-pair [11 11]
11x11
The next example demonstrates using to-pair with a string:
probe to-pair "11x11"
11x11

Enhancements

Parse Block

Under REBOL/Core 2.3 parse can be used on blocks. The ability to create dialects in REBOL is enhanced through the ability to parse blocks. Refer to the User's Guide for more information on using parse with blocks.

POP handler change

The POP mail handler has been enhanced to store the total size of messages and the sizes of individual messages. The total size of messages can be found stored as an integer representing bytes in the POP port's locals object under the total-size field. Individual message sizes are stored as a block of message numbers and byte sizes in the port's locals object under the sizes field. Examples:

Total size of all messages in a POP connection:

pop: open pop://login:pass@mail.site.com/
size: probe pop/locals/total-size
735907

print join to-integer size / 1024 "K"
718K

Sizes of individual messages:
pop: open pop://login:pass@mail.site.com/
sizes: pop/locals/sizes
foreach [mesg-num size] sizes [
    print [
        "Message" mesg-num "is" join to-integer size / 1024 "K"
    ]
]
Message 1 is 2K
Message 2 is 2K
Message 4 is 1K
Message 5 is 9K
Message 6 is 1K
Message 7 is 678K
Message 8 is 1K

Tab Completion

Tab completion for the REBOL console has been expanded to show a list of possible matches when pressing tab a second time.

To see the behavior of REBOL's tab completion, type fun at the REBOL prompt and then hit the tab key. Tab completion will expand fun to func. Hitting the tab key once more will show the following: function!, function?, func and function as possible matches for the word you are typing in.

Load's /Next Refinement

The behavior has changed for load's /next refinement. Load/next will not skip over a REBOL script header. To load a script header as an object using the /next refinement, include the /header refinement. Examples:

Saving a simple script to the file simple.r:

save %simple.r [
    REBOL [
        title: "simple"
        file:  %simple.r
        ]

    print "simple script"
]

Using load/next on a simple script:
script: probe load/next %simple.r
[
    REBOL { [
    title: "simple"
    file: %simple.r
]
print "simple script"}]

probe load/next second script
[[
        title: "simple"
        file: %simple.r
    ] {
print "simple script"}]

Using load/next/header on a simple script:
script: probe load/next/header %simple.r
[
    make object! [
        Title: "simple"
        Date: none
        Name: none
        Version: none
        File: %simple.r
        Home: none
        Author: none
        Owner: none
        Rights: none
        Needs: none
        Tabs: none
        Usage: none
        Purpose: none
        Comment: none
        History: none
        Language: none
    ] {
print "simple script"}]

probe load/next second script
[
    print { "simple script"}]

Query Function

Query now accepts objects, returning a block of modified words in that object or none. The block returned from using query on an object contains the words which have been modified since the object's creation or since it was last passed to query/clear. The words in the returned block are bound to the context of the object. Using query, changes to an object can be tracked. The following example illustrates the use of query on objects:

Defining an object:

obj: make object! [
    field-one: "string"
    field-two: 123
    field-three: 11:11:01
]
Using query on obj immediately after the object was created will return none:
probe query obj
none
Using query after a field within obj has changed:
obj/field-two: 456
obj/field-three: 12:12:02 mod: query obj
probe get mod/1
456

probe get mod/2
12:12:02

Query returned a block of modified words bound to obj. Use query/clear to reset the modified state of the object.

The next example demonstrates clearing the modified state of the fields in obj:

query/clear obj
probe query obj
none
Query on obj returned none because the modified state was reset using query/clear.

Functions Accepting Pair Values

Following is a list of the functions that have been extended to accept pair values:

Addition Functions + and Add

probe 12x12 + 12x12
24x24

probe add 11x11 11
22x22

Subtraction Functions - and Subtract

probe 24x24 - 12x20
12x4

probe subtract 24x24 12
12x12

Multiplication Functions * and Multiply

probe 12x12 * 12x12
144x144

probe multiply 12x12 24
288x288

Division Functions / and Divide

probe 12x12 / 2x4
6x3

probe divide 24x24 4
6x6

Remainder Functions // and Remainder

probe 24x24 // 5x3
4x0

probe remainder 24x24 10
4x4

Minimum Functions Min and Minimum

probe min 12x12 12x11
12x11

probe minimum 23x24 24x24
23x24

Maximum Functions Max and Maximum

probe max 12x12 12x11
12x12

probe maximum 23x24 24x24
24x24

Negate Function

probe negate 12x12
-12x-12

probe negate 12x0
-12x0

Absolute Functions Abs and Absolute

probe abs -12x-24
12x24

probe absolute -12x24
12x24

Zero? Function

probe zero? 12x0
false

probe zero? 0x0
true

Pick, First and Second Functions

probe pick 24x12 1
24

probe pick 24x12 2
12

probe pick 24x12 3 ; anything beyond 2 returns NONE
none

probe first 24x12
24

probe second 24x12
12

Reverse Function

probe reverse 12x24
24x12

Random Function

The random function now takes negative values. When a negative value is used, random returns a number between -1 and the negative value. Examples:
loop 5 [print random -5]
-5
-5
-3
-3
-5

loop 5 [print random -$5]
-$4.00
-$5.00
-$3.00
-$5.00
-$3.00

System/options/path

The word path has been added to the system/options object. System/options/path is the directory where the current REBOL script was executed from. Example:
print system/options/path
/C/REBOL/

What Function

What now alphabetically sorts the list of defined functions printed.

If, Any and All Functions

If, any and all now return none as a "fail" value where they had previously returned false. Here are some examples of the new return value:
val: 10
probe if val = 100 [print "matched"]
none
val: 10
probe any [val = 100 val = 1000 val = 10000]
none
set [val1 val2 val3] [10 100 2000]
probe all [val1 = 10 val2 = 100 val3 = 1000]
none

Help

Use the help function to get the description, arguments, and refinements for all functions, or to inspect other REBOL values. Type help and the function name at the prompt: 
        >> help cosine
USAGE:
    COSINE value /radians
DESCRIPTION:
     Returns the trigonometric cosine in degrees.
     COSINE is a native value.
ARGUMENTS:
     value -- (Type: number)
REFINEMENTS:
     /radians -- Value is specified in radians.

Help can also be used to search REBOL's internal documentation. For example, you can find help with the following words: path, to- functions, operators (op!), datatype!, and native!. Here is an example of using help with a word: 

>> help path
Found these words:
     clean-path     (function)
     inst-path      (object)
     lit-path!      (datatype)
     lit-path?      (action)
     make-dir-path  (function)
     path!          (datatype)
     path?          (action)
     set-path!      (datatype)
     set-path?      (action)
     split-path     (function)
     to-lit-path    (function)
     to-path        (function)
     to-set-path    (function)

Fixes

Here are the fixes made to this version since version 2.3:

Split-path Function

When splitting the lowest level of a file path (%. or %/), the second value in the returned block will be none. When splitting a file (%file), the first value in the returned block will be the current directory (%./) and the second value the file itself (%file). Here are some examples of using split-path:
probe split-path %.
[%./ none]

probe split-path %./
[%./ none]

probe split-path %/
[%/ none]

probe split-path %file.txt
[%./ %file.txt]

Network activity interruptible

Network activity may now be interrupted by pressing the escape key (esc).

A known exception is network activity on the BeOS version of REBOL/core which currently is not interruptible with the escape key.

Trim/lines

Trim/lines now removes all extra white space in a string, compressing all occurrences of whitespace into single spaces. The following example demonstrates the behavior of trim/lines:
str: {
    line one
    ^- ^- line two
 

    line five
 

    line eight
}
probe trim/lines str
"line one line two line five line eight"

To-word Function

To-word now accepts set-word values as an argument. The behavior of to-word with a set-word as an argument is demonstrated in the following example:
probe to-word first [data: "string of data"]
data
probe type? to-word first [data: "string of data"]
word!

To-block Function

When a path literal is used as an argument to to-block, a block is returned containing the path components as words. The following example demonstrates the use of to-block with a literal path value:
probe to-block 'system/options/path
[system options path]

Feedback

REBOL Technologies is very interested in any problems you encounter. To report a bug, use the feedback script included with
this release. Start REBOL, then enter:

     do %feedback.r

If you have configured REBOL to send email, the script will prompt you for information, then email your information directly to
our support department.

You may also directly email us. Please include a subject line that describes the problem
like "making blocks does not work" rather than just "bug". Email:

     feedback@REBOL.com

We will send an automatic confirmation of each report. If you don't get the confirmation, then we may not have received your email or
the return address is incorrect.

Be sure to include a simple example of the problem within the bug report. If the problem is found in a large script, edit it down to just the bug.
Please don't send large files.

Also, be sure to include the version number as is printed in the title banner. The version in the banner indicates not only the version and revision, but also the
update number and the platform (OS). For example,

     2.3.0.3.1

indicates that you are running Version 2.3.0 for the Windows 95/98/NT. Version numbers have the format:

     version.revision.update.platform

From the REBOL language you can obtain the version number with:

     print REBOL/version

Copyright © 1998-2000 REBOL Technologies. All Rights Reserved. REBOLTM Communications Language and the REBOL logo are trademarks of REBOL Technologies. Other trademarks are the property of their respective owners. Information in this document is subject to change without notice. Type license at the REBOL prompt for terms of the REBOL Technologies Software End User License Agreement.