Rebol3 Functions Dictionary
Warning
Some function descriptions are sourced from the old Rebol3 documentation project and may be outdated. If you notice any outdated or incorrect information, please report it on GitHub.
ABOUT¶
Information about REBOL
Usage:
about
Description:
Displays REBOL title and version information on the REBOL console.
>> about╔══════════════════════════════════════════════════════════════════════════╗
║ ║
║ REBOL/Bulk 3.18.3 (Oldes branch) ║
║ ║
║ Copyright 2012 REBOL Technologies ║
║ 2012-2025 Rebol Open Source Contributors ║
║ Apache 2.0 License, see LICENSE. ║
║ Website https://github.com/Oldes/Rebol3 ║
║ ║
║ Platform Windows | x64-pc-win32-pe | cl ║
║ Build 11-Mar-2025/19:26 ║
║ ║
║ Home C:\Users\oldes\Rebol\ ║
║ ║
╚══════════════════════════════════════════════════════════════════════════╝
Important notes:
* Sandbox and security are not fully available.
* Direct access to TCP HTTP required (no proxies).
* Use at your own risk.
* Try/except is deprecated and will be removed! Use try/with instead.
* This Rebol version has switched map and construction syntax!
See: https://github.com/Oldes/Rebol-issues/issues/2589
Special functions:
Help - show built-in help information
ABS¶
Note: Shell shortcut for absolute.
ABSOLUTE¶
Returns the absolute value.
Usage:
absolute
ARGUMENTS: value [number! pair! money! time!]
Description:
Returns a positive value equal in magnitude.
>> absolute -123
== 123
>> absolute -1:23
== 1:23
>> absolute -1x4
== 1x4ACCESS-OS¶
Access to various operating system functions (getuid, setuid, getpid, kill, etc.)
Usage:
access-os
ARGUMENTS: field [word!] Valid words: uid, euid, gid, egid, pid REFINEMENTS: /set To set or kill pid (sig 15) value [integer! block!] Argument, such as uid, gid, or pid (in which case, it could be a block with the signal no)
ACOS¶
Returns the trigonometric arccosine.
Usage:
acos
ARGUMENTS: value [decimal!] In radians
Description:
ACTION?¶
Returns TRUE if it is this type.
Usage:
action?
ARGUMENTS: value [any-type!]
Description:
Actions are special functions that operate with datatypes. See action! for more.
>> action? :add
== true
>> action? :append
== true
>> action? :+
== false
>> action? "add"
== falseADD¶
Returns the addition of two values.
Usage:
add
ARGUMENTS: value1 [scalar! date! vector!] value2 [scalar! date! vector!]
Description:
Note: The + operator is a special infix form for this function.
Many different datatypes support addition.
print add 123 1
124
print add 1.23 .004
1.234
print add 1.2.3.4 4.3.2.1
5.5.5.5
print add $1.01 $0.0000000001
$1.0100000001
print add 3:00 -4:00
-1:00
print add 31-Dec-1999 1
1-Jan-2000When adding values of different datatypes, the values must be compatible. Auto conversion of the values will occur into the datatype that has the most expansive representation. For example an integer added to a decimal will produce a decimal.
AJOIN¶
Reduces and joins a block of values into a new string. Ignores none and unset values.
Usage:
ajoin
ARGUMENTS: block [block!] REFINEMENTS: /with delimiter [any-type!] /all Do not ignore none and unset values
Description:
The join and rejoin functions return the same datatype as their first element, be it a string!, file!, binary!, tag!, email! or whatever. However, there are times when you just want to construct a string!, and that's the purpose of ajoin.
For example:
ajoin ["test" 123]
"test123"It is similar to reform but does not insert spaces between values:
reform ["test" 123]
"test 123"Note that the block is always evaluated:
time: 10:30
ajoin [time/hour "h" time/minute "m"]
"10h30m"The ajoin function is equivalent to:
to-string reduce blockHow it differs
Here are examples that show how ajoin differs from join and rejoin.
Compare:
ajoin [<test> 123]
"<test>123"with:
rejoin [<test> 123]
<test123>and:
join <test> 123
<test123>Notice that the last two examples return a tag!, not a string!.
ALL¶
Shortcut AND. Evaluates and returns at the first FALSE or NONE.
Usage:
all
ARGUMENTS: block [block!] Block of expressions
Description:
The all function is the most common way to test multiple conditions, such as in the line:
if all [num > 1 num < 1000] [do something]It works by evaluating each expression in a block until one of the expressions returns none! or false, in which case a none! is returned. Otherwise, the value of the last expression will be returned.
print all [1 none]
none
print all [none 1]
none
print all [1 2]
2
print all [10 > 1 "yes"]
yes
print all [1 > 10 "yes"]
none
time: 10:30
if all [time > 10:00 time < 11:00] [print "time is now"]
time is nowNo other expressions are evaluated beyond the point where a value fails:
a: 0
all [none a: 2]
print a
0
a: 0
all [1 a: 2]
print a
2
day: 10
time: 9:45
ready: all [day > 5 time < 10:00 time: 12:00]
print time
12:00The any function is a companion of all to test for the opposite condition, where any one of the values will result in a true result.
ALL-OF¶
Returns TRUE if all value(s) pass the test, otherwise NONE.
Usage:
all-of
ARGUMENTS: word [word! block!] Word or block of words to set each time (local) data [series! any-object! map! none!] The series to traverse test [block!] Condition to test each time
Description:
>> all-of x [33 -1 24] [x > 0]
== #(none)
>> all-of x [33 -1 24] [integer? x]
== #(true)ALSO¶
Returns the first value, but also evaluates the second.
Usage:
also
ARGUMENTS: value1 [any-type!] value2 [any-type!]
Description:
The also function lets you evaluate two expressions, but return the first, rather than the second. This function may seem a bit odd at first, but in many cases it can save you from needing another temporary variable.
Consider the case where you want to evaluate a block and return its result, but before returning the result, you want to change directories.
You could write:
result: do block
change-dir old-dir
return resultOr, you could write
return also do block change-dir old-dirIn fact, that's actually what happens in the in-dir function. Another case might be an I/O port used by a function that wants to return the port's data but also close it:
return also port/locals/buffer close portIf you close the port first, the buffer cannot be accessed.
ALTER¶
Append value if not found, else remove it; returns true if added.
Usage:
alter
ARGUMENTS: series [series! port! bitset!] (modified) value REFINEMENTS: /case Case-sensitive comparison
Description:
The alter function helps you manage small data-sets. It either adds or removes a value depending on whether the value is already included. (The word alter is short for the word "alternate", the action taking place.)
For example, let's say you want to keep track of a few options used by your code. The options may be: flour, sugar, salt, and pepper. The following code will create a new block (to hold the data set) and add to it:
options: copy []
alter options 'salt
probe options
[salt]
alter options 'sugar
probe options
[salt sugar]You can use functions like find to test the presence of an option in the set:
if find options 'salt [print "Salt was found"]
Salt was foundIf you use alter a second time for the same option word, it will be removed:
alter options 'salt
probe options
[sugar]Normally alter values are symbolic words (such as those shown above) but any datatype can be used such as integers, strings, etc.
alter options 120
alter options "test"
probe options
[sugar 120 "test"]Also, alter returns true if the value was added to the series, or false if the value was removed.
AND¶
Returns the first value ANDed with the second.
Usage:
and
ARGUMENTS: value1 [logic! integer! char! tuple! binary! bitset! typeset! datatype!] value2 [logic! integer! char! tuple! binary! bitset! typeset! datatype!]
Description:
For logic! values, both values must be true to return true, otherwise a false is returned. AND is an infix operator.
print true and true
true
print true and false
false
print (10 < 20) and (20 > 15)
trueFor integer!, tuple!, binary!, and other datatypes, each bit is separately anded.
print 123 and 1
1
print 1.2.3.4 and 255.0.255.0
1.0.3.0AND~¶
Returns the first value ANDed with the second.
Usage:
and~
ARGUMENTS: value1 [logic! integer! char! tuple! binary! bitset! typeset! datatype!] value2 [logic! integer! char! tuple! binary! bitset! typeset! datatype!]
Description:
This is the primary function behind the and operator. It can be used where you want prefix rather than infix notation:
bits: and~ mask 3ANY¶
Shortcut OR. Evaluates and returns the first value that is not FALSE or NONE.
Usage:
any
ARGUMENTS: block [block!] Block of expressions
Description:
The any function is the most common way to test for one of multiple conditions, such as in the line:
if any [a > 10 b > 20 c > 30] [do something]Here, if any one of the conditions produces a true result, the if will evaluate the block.
This function works by evaluating each expression in a block until one of the expressions returns a value other than none! or false, in which case the value is returned. Otherwise, none! will be returned.
Examples to help show how it works:
print any [1 none]
1
print any [none 1]
1
print any [none none]
none
print any [false none]
none
print any [true none]
true
time: 10:30
if any [time > 10:00 time < 11:00] [print "time is now"]
time is nowNo other expressions are evaluated beyond the point where a successful value is found. This can be useful. For example:
a: 0
any [none a: 2]
print a
2
a: 0
any [1 a: 2]
print a
0
day: 10
time: 9:45
ready: any [day > 5 time < 10:00 time: 12:00]
print time
9:45The any function is also useful for setting default values. For example:
size: any [size 100]If size was none!, then it gets set to 100. This works even better if there are alternative defaults:
size: any [size prefs/size 100]Another use for any is to emulate a sequence of if...elseif...elseif...else. Instead of writing:
either cond-1 [
code-1
] [
either cond-2 [
code-2
] [
either cond-3 ...
]
]it is possible to write:
any [
if cond-1 [
code-1
true ; in case code-1 returns FALSE or NONE
]
if cond-2 [
code-2
true
]
...
]Also see the case function for more about this code pattern.
The all function is a companion of any to test for the opposite condition, where all of the values must be true to return a true result.
ANY-BLOCK?¶
Return TRUE if value is any type of block.
Usage:
any-block?
ARGUMENTS: value [any-type!]
Description:
Returns true only if the value is a block! (any kind of block) and false for all other values.
>> any-object? "foo"
== #(false)
>> any-block? [1 2]
== #(true)
>> any-block? first [(1 2) 3]
== #(true)
>> any-block? 'a/b/c
== #(true)
>> any-block? 12
== #(false)To learn what datatypes are blocks:
print any-block!
block! paren! path! set-path! get-path! lit-path!ANY-FUNCTION?¶
Return TRUE if value is any type of function.
Usage:
any-function?
ARGUMENTS: value [any-type!]
Description:
Returns true if the value is any type of function and returns false for all other values.
>> any-function? :find
== #(true)
>> any-function? :+
== #(true)
>> any-function? func [] [print "hi"]
== #(true)
>> any-function? 123
== #(false)To learn what datatypes are functions:
print any-function!
native! action! rebcode! command! op! closure! function!ANY-OBJECT?¶
Return TRUE if value is any type of object.
Usage:
any-object?
ARGUMENTS: value [any-type!]
Description:
>> any-object? system
== #(true)
>> any-object? try [1 / 0]
== #(true)
>> any-object? "foo"
== #(false)ANY-OF¶
Returns the first value(s) for which the test is not FALSE or NONE.
Usage:
any-of
ARGUMENTS: word [word! block!] Word or block of words to set each time (local) data [series! any-object! map! none!] The series to traverse test [block!] Condition to test each time
Description:
>> any-of x [-1 4 10] [x > 0]
== 4
>> any-of [x y] [1 4 10 8 5 -3] [(x - 2) = y]
== [10 8]ANY-PATH?¶
Return TRUE if value is any type of path.
Usage:
any-path?
ARGUMENTS: value [any-type!]
Description:
Returns true if the value is any type of path! and returns false for all other values.
>> any-path? 'test/this
== #(true)
>> any-path? first [example/item: 10]
== #(true)
>> any-path? second [print :example/item]
== #(true)
>> any-path? 123
== #(false)To learn what datatypes are paths:
print any-path!
path! set-path! get-path! lit-path!ANY-STRING?¶
Return TRUE if value is any type of string.
Usage:
any-string?
ARGUMENTS: value [any-type!]
Description:
Returns true for any type of string, and false for all other values.
>> any-string? "Hello"
== #(true)
>> any-string? email@rebol.com
== #(true)
>> any-string? ftp://ftp.rebol.com
== #(true)
>> any-string? %dir/file.txt
== #(true)
>> any-string? @name
== #(true)
>> any-string? 11-Jan-2000
== #(false)To see what datatypes are strings:
print any-string!
string! file! email! ref! url! tag!ANY-WORD?¶
Return TRUE if value is any type of word.
Usage:
any-word?
ARGUMENTS: value [any-type!]
Description:
Returns true for any type of word and false for all other values.
>> any-word? 'word
== #(true)
>> any-word? /word
== #(true)
>> any-word? #issue
== #(true)
>> any-word? first [set-word: 'lit-word :get-word]
== #(true)
>> any-word? second [set-word: 'lit-word :get-word]
== #(true)
>> any-word? third [set-word: 'lit-word :get-word]
== #(true)
>> any-word? 123
== #(false)To see what datatypes are words:
print any-word!
word! set-word! get-word! lit-word! refinement! issue!APPEND¶
Inserts element(s) at tail; for series, returns head.
Usage:
append
ARGUMENTS: series [series! port! map! gob! object! bitset!] Any position (modified) value [any-type!] The value to insert REFINEMENTS: /part Limits to a given length or position range [number! series! pair!] /only Only insert a block as a single value (not the contents of the block) /dup Duplicates the insert a specified number of times count [number! pair!]
Description:
The append function is a shortcut for doing an insert at the tail of any type of series and returning the head:
head insert tail series valueBasic examples:
string: copy "hello"
probe append string " there"
"hello there"
file: copy %file
probe append file ".txt"
%file.txt
url: copy http://
probe append url "www.rebol.com"
http://www.rebol.comThe /only refinement forces a block to be appended as a single block element, rather than appending the separate elements of the block:
block: copy [1 2 3]
probe append block [4 5 6]
[1 2 3 4 5 6]
block: copy [1 2 3]
probe append/only block [4 5 6]
[1 2 3 [4 5 6]]To learn more about the operation of the other refinements, see the insert function.
APPLY¶
Apply a function to a reduced block of arguments.
Usage:
apply
ARGUMENTS: func [any-function!] Function value to apply block [block!] Block of args, reduced first (unless /only) REFINEMENTS: /only Use arg values as-is, do not reduce the block
Description:
When you evaluate a function, you normally provide any arguments directly in-line with its call:
append data 123However, there are times when you want to store the arguments as a single block and pass them to the function. This is the purpose of the apply function. The above example can be written as:
apply :append [data 123]or, using a variable to hold the block:
args: [data 123]
apply :append argsIf any arguments are missing from the block, a none! is passed instead:
data: [456]
apply :append [data]
probe data
[456 none]Function refinements can also be passed in the order they are specified by the arguments spec block. For example, we can see:
>> ? append
USAGE:
APPEND series value /part length /only /dup countSo in this example we use the /dup refinement:
data: [456]
apply :append [data 1 none none none true 3]
probe data
[456 1 1 1]Note that the refinement itself must be set to true.
ARCCOSINE¶
Returns the trigonometric arccosine (in degrees by default).
Usage:
arccosine
ARGUMENTS: value [number!] REFINEMENTS: /radians Returns result in radians
Description:
The arccosine provides the inverse of the cosine function.
print arccosine .5
60.0Note that arccosine goes to infinity at 90 degrees and will cause a numeric overflow.
ARCSINE¶
Returns the trigonometric arcsine (in degrees by default).
Usage:
arcsine
ARGUMENTS: value [number!] REFINEMENTS: /radians Returns result in radians
Description:
The arcsine provides the inverse of the sine function.
>> arcsine .5
== 30.0Note that arccsine goes to infinity at 0 and each 180 degrees and will cause a numeric overflow.
ARCTANGENT¶
Returns the trigonometric arctangent (in degrees by default).
Usage:
arctangent
ARGUMENTS: value [number!] REFINEMENTS: /radians Returns result in radians
Description:
The arctangent function provides the inverse of the tangent function.
>> arctangent .22
== 12.4074185274007ARCTANGENT2¶
Returns the angle of the point, when measured counterclockwise from a circle's X axis (where 0x0 represents the center of the circle). The return value is in interval -180 to 180 degrees.
Usage:
arctangent2
ARGUMENTS: point [pair!] X/Y coordinate in space REFINEMENTS: /radians Result is in radians instead of degrees
ARRAY¶
Makes and initializes a series of a given size.
Usage:
array
ARGUMENTS: size [integer! block!] Size or block of sizes for each dimension REFINEMENTS: /initial Specify an initial value for all elements value Initial value (will be called each time if a function)
Description:
In REBOL, arrays are simply blocks that are initialized to a specific size with all elements set to an initial value (v:none by default). The array function is used to create and initialize arrays.
Supplying a single integer as the argument to array will create an array of a single dimension. The example below creates a five element array with values set to none:
>> block: array 5
== [#(none) #(none) #(none) #(none) #(none)]
>> length? block
== 5To initialize an array to values other than NONE, use the /initial refinement. The example below intializes a block with zero values:
>> block: array/initial 5 0
== [0 0 0 0 0]To create an array of multiple dimensions, provide a block of integers as the argument to the array function. Each integer specifies the size of that dimension of the array. (In REBOL, such multidimensional arrays are created using blocks of blocks.)
>> xy-block: array [2 3]
== [[#(none) #(none) #(none)] [#(none) #(none) #(none)]]
>> xy-block: array/initial [2 3] 0
== [[0 0 0] [0 0 0]]Once an array has been created, you can use paths or the pick and poke functions to set and get values of the block based on their indices:
block/3: 1000
poke block 5 now
probe block
[0 0 1000 0 12-Feb-2009/17:46:59-8:00]
probe block/3
1000
repeat n 5 [poke block n n]
probe block
[1 2 3 4 5]
xy-block/2/1: 1.2.3
xy-block/1/3: copy "test"
probe xy-block
[[0 0 "test"] [1.2.3 0 0]]
probe xy-block/2/1
1.2.3
repeat y 2 [
dim: pick xy-block y
repeat x 3 [poke dim x to-pair reduce [x y]]
]
probe xy-blockCoding Style Notes
REBOL uses the concept of expandable series for holding and manipulating data, rather than the concept of fixed size arrays. For example, in REBOL you would normally write:
block: copy []
repeat n 5 [append block n]rather than:
block: array 5
repeat n 5 [poke block n n]In other words, REBOL does not require you to specify the size of data arrays (blocks, bytes, or strings) in advance. They are dynamic.
AS¶
Coerce a series into a compatible datatype without copying it.
Usage:
as
ARGUMENTS: type [any-block! any-string! datatype!] The datatype or example value spec [any-block! any-string!] The series to coerce
AS-BLUE¶
Decorates a value with blue ANSI escape codes
Usage:
as-blue
ARGUMENTS:
value
AS-CYAN¶
Decorates a value with cyan ANSI escape codes
Usage:
as-cyan
ARGUMENTS:
value
AS-GRAY¶
Decorates a value with gray ANSI escape codes
Usage:
as-gray
ARGUMENTS:
value
AS-GREEN¶
Decorates a value with green ANSI escape codes
Usage:
as-green
ARGUMENTS:
value
AS-PAIR¶
Combine X and Y values into a pair.
Usage:
as-pair
ARGUMENTS: x [number!] y [number!]
Description:
Provides a shortcut for creating pair! values from separate X and Y integers.
print as-pair 100 50
100x50AS-PURPLE¶
Decorates a value with purple ANSI escape codes
Usage:
as-purple
ARGUMENTS:
value
AS-RED¶
Decorates a value with red ANSI escape codes
Usage:
as-red
ARGUMENTS:
value
AS-WHITE¶
Decorates a value with white ANSI escape codes
Usage:
as-white
ARGUMENTS:
value
AS-YELLOW¶
Decorates a value with yellow ANSI escape codes
Usage:
as-yellow
ARGUMENTS:
value
ASCII?¶
Returns TRUE if value or string is in ASCII character range (below 128).
Usage:
ascii?
ARGUMENTS: value [any-string! char! integer!]
Description:
>> ascii? "hello"
== #(true)
>> ascii? "česko"
== #(false) ;; because (to integer! #"č") == 269ASIN¶
Returns the trigonometric arcsine.
Usage:
asin
ARGUMENTS: value [decimal!] In radians
ASK¶
Ask the user for input.
Usage:
ask
ARGUMENTS: question [series!] Prompt to user REFINEMENTS: /hide Turns off echoing inputs /char Waits only on single key press and returns char as a result limit [bitset! string! block! char! none!] Limit input to specified chars or control words
Description:
Provides a common prompting function that is the same as a prin followed by an input. The resulting input will have spaces trimmed from its head and tail. The /hide refinement hides input with "*" characters. The function returns a string!.
Example, where the user enters Luke as input:
ask "Your name, please? "
Your name, please? Luke
== "Luke"ASSERT¶
Assert that condition is true, else cause an assertion error.
Usage:
assert
ARGUMENTS: conditions [block!] REFINEMENTS: /type Safely check datatypes of variables (words and paths)
Description:
In code, it is common to check conditions that should always be valid or true. For example, a check may be made for a value to be in range or of a given datatype.
Since the conditions are always supposed to be true, it's often not worth the effort to provide a detailed error message or explanation if the condition fails, and often such information would only be meaningful to the programmer, not the end user.
To make it easier to check such conditions, the assert function is provided.
Assert can check "truth" conditions, or with a refinement, it can check datatype validity conditions.
To check truth conditions, the argument of assert is a block of one or more conditions, and each is checked (similar to all) to be true:
num: 10
assert [num > 20]
** Script error: assertion failed for: [num > 20]
** Where: assert
** Near: assert [num > 20]Note that for compound assertions, the error message will indicate the assertion that failed:
num: 10
age: 20
assert [num > 0 age > 50]
** Script error: assertion failed for: [age > 50]
** Where: assert
** Near: assert [num > 0 age > 50]Look at the error line closely, and you can tell which one failed.
Note: only the first three elements of the failed assertion will be shown (to help avoid long error lines.)
It is also common to validate datatypes using the /type refinement:
age: "37"
name: "Bob"
assert/type [age integer! name string!]
** Script error: datatype assertion failed for: age
** Where: assert
** Near: assert/type [age integer! name string!]It fails because age is actually a string, not an integer.
The assert function is useful for validating value before a section of code that depends on those value:
assert/type [
spec object!
body block!
spec/size number!
spec/name [string! none!]
spec/options [block! none!]
]Note that assert is safe to use on all function datatypes. The functions will not be evaluated as part of the process; therefore, assert is an easy way to prevent function passage in unwanted cases.
AT¶
Returns the series at the specified index, relative to the current position.
Usage:
at
ARGUMENTS: series [series! gob! port!] index [number! logic! pair!]
Description:
Provides a simple way to index into any type of series. at returns the series at the new index point.
Note that the operation is relative to the current position within the series.
A positive integer N moves to the position N in the series:
numbers: [11 22 33]
print at numbers 2
22 33An index of 0 is the same as an index of 1:
print at numbers 0
11 22 33Using a negative index N, you can go N values backwards in a series:
numbers: at numbers 3
print numbers
33
print at numbers -1
22 33More examples, combined with other series functions:
words: [grand grape great good]
print first at words 2
grape
remove at words 2
insert at words 3 [super]
probe words
[grand great super good]ATAN¶
Returns the trigonometric arctangent.
Usage:
atan
ARGUMENTS: value [decimal!] In radians
ATAN2¶
Returns the angle of the point y/x in the interval [-pi,+pi] radians.
Usage:
atan2
ARGUMENTS: y [decimal!] The proportion of the Y-coordinate x [decimal!] The proportion of the X-coordinate
ATTEMPT¶
Tries to evaluate a block and returns result or NONE on error.
Usage:
attempt
ARGUMENTS: block [block!] REFINEMENTS: /safer Capture all possible errors and exceptions
Description:
The attempt function is a shortcut for the frequent case of:
error? try [block]More accurately, this is performed:
if not error? try [set/any 'val block] [val]The format for attempt is:
attempt [block]attempt is useful where you either do not care about the error result or you want to make simple types of decisions based on the error.
attempt [make-dir %fred]attempt returns the result of the block if an error did not occur. If an error did occur, a none is returned.
In the line:
value: attempt [load %data]
probe value
nonethe value is set to none if the %data file cannot be loaded (e.g. it is missing or contains an error). This allows you to write conditional code such as:
if not value: attempt [load %data] [print "Problem"]
ProblemOr code such as:
value: any [attempt [load %data] [12 34]]
probe value
[12 34]ATZ¶
Returns the series at the specified 0-based index, relative to the current position.
Usage:
atz
ARGUMENTS: series [series! gob! port!] index [number! logic! pair!]
Description:
>> blk: [1 2 3 4]
== [1 2 3 4]
>> at blk 2
== [2 3 4]
>> atz blk 2
== [3 4]AVERAGE¶
Returns the average of all values in a block
Usage:
average
ARGUMENTS: block [block! vector! paren!]
Description:
>> average [1 2 3]
== 2BACK¶
Returns the series at its previous position.
Usage:
back
ARGUMENTS: series [series! gob! port!]
Description:
Works on any type of series. If the series is at its head, it will remain at its head. back will not go past the head, nor will it wrap to the tail.
print back tail "abcd"
d
str: tail "time"
until [
str: back str
print str
head? str
]
e
me
ime
time
blk: tail [1 2 3 4]
until [
blk: back blk
print first blk
head? blk
]
4
3
2
1BINARY¶
Entry point of the binary DSL (Bincode)
Usage:
binary
ARGUMENTS: ctx [object! binary! integer! none!] Bincode context. If none, it will create a new one. REFINEMENTS: /init Initializes buffers in the context spec [binary! integer! none!] /write Write data into output buffer data [binary! block!] Data dialect /read Read data from the input buffer code [word! block! integer! binary!] Input encoding /into Put READ results in out block, instead of creating a new block out [block!] Target block for results, when /into is used /with Additional input argument num [integer!] Bits/bytes number used with WORD! code type to resolve just single value
Description:
This is quite complex dialect which requires own documentation. But it may be used for binary data streaming in both directions like:
>> stream: binary bin: #{}
== make object! [
type: 'bincode
buffer: #{}
buffer-write: #{}
r-mask: 0
w-mask: 0
]
>> binary/write stream [UI8 1 SI16 -2 UI16BYTES "hello"]
== make object! [
type: 'bincode
buffer: #{01FFFE000568656C6C6F}
buffer-write: #{}
r-mask: 0
w-mask: 0
]
>> bin
== #{01FFFE000568656C6C6F}
>> binary/read stream 'UI8
== 1
>> binary/read stream [SI16 UI16BYTES]
== [-2 #{68656C6C6F}]BINARY?¶
Returns TRUE if it is this type.
Usage:
binary?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values.
>> binary? #{13ff acd0}
== #(true)
>> binary? 2#{00001000}
== #(true)
>> binary? 1234
== #(false)BIND¶
Binds words to the specified context.
Usage:
bind
ARGUMENTS: word [block! any-word!] A word or block (modified) (returned) context [any-word! object! module! port!] A reference to the target context REFINEMENTS: /copy Bind and return a deep copy of a block, don't modify original /only Bind only first block (not deep) /new Add to context any new words found /set Add to context any new set-words found
Description:
Binds meaning to words in a block. That is, it gives words a context in which they can be interpreted. This allows blocks to be exchanged between different contexts, which permits their words to be understood. For instance a function may want to treat words in a global database as being local to that function.
The second argument to bind is a word from the context in which the block is to be bound. Normally, this is a word from the local context (e.g. one of the function arguments), but it can be a word from any context within the system.
bind will modify the block it is given. To avoid that, use the /copy refinement. It will create a new block that is returned as the result.
words: [a b c]
fun: func [a b c][print bind words 'a]
fun 1 2 3
fun "hi" "there" "fred"
hi there fred
words: [a b c]
object: make object! [
a: 1
b: 2
c: 3
prove: func [] [print bind words 'a]
]
object/prove
1 2 3
settings: [start + duration]
schedule: function [start] [duration] [
duration: 1:00
do bind settings 'start
]
print schedule 10:30
11:30Editor note: Describe /new here Editor note: Describe /set here
BITSET?¶
Returns TRUE if it is this type.
Usage:
bitset?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values.
>> bitset? make bitset! "abc"
== #(true)
>> bitset? charset "abc"
== #(true)
>> bitset? 123
== #(false)BLOCK?¶
Returns TRUE if it is this type.
Usage:
block?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values.
>> block? [1 2 3]
== #(true)
>> block? "1 2 3"
== #(false)
>> data: load "1 2 3" ; converts "1 2 3" into a block
== [1 2 3]BLUR¶
Blur (Gaussian) given image
Usage:
blur
ARGUMENTS: image [image!] Image to blur (modified) radius [number!] Blur amount
Description:
img: load %same/image.png
blur img 5 ;; blurs the original image!BODY-OF¶
Returns a copy of the body of any function, any object, map or struct
Usage:
body-of
ARGUMENTS: value [any-function! any-object! map! struct!]
Description:
>> body-of object [a: 1]
== [
a: 1
]
>> body-of func[][1 + 1]
== [1 + 1]BREAK¶
Breaks out of a loop, while, until, repeat, foreach, etc.
Usage:
break
REFINEMENTS: /return Forces the loop function to return a value value [any-type!]
Description:
The break function stops loop functions.
For example:
repeat n 5 [
print n
if n > 2 [break]
]
1
2
3The current loop is immediately terminated and evaluation resumes after the repeat function.
Return Value
The break /return refinement will return a value from a loop. It is commonly used to return a specific value or pass to a conditional expression when the loop is terminated early.
Here's an example:
print repeat n 5 [
if n > pi [break/return n]
none
]
4An example using foreach :
values: [8:30 breakfast 12:00 lunch 5:00 dinner]
meal: foreach [time event] [
if time > 14:00 [break/return event]
none
]
probe meal
dinnerImportant Scoping Rule
The break function acts immediately on the "closest block".
Although break can be placed anywhere within the block being repeated, even within a sub-block or function, because break is a function that is not directly bound to the loop, it will break the closest loop, not necessarily the intended loop. This does not affect most programs but could affect custom-made loop functions.
In this example, even though the break appears in the repeat loop, it applies to the a-loop loop block and has no effect on the outer repeat loop.
a-loop: func [count block] [loop count block]
repeat a 3 [
print a
a-loop 4 [break]
]
1
2
3BROWSE¶
Open web browser to a URL or local file.
Usage:
browse
ARGUMENTS: url [url! file! none!]
Description:
If the browser cannot be found, nothing will happen.
BUGS¶
View bug database.
Usage:
bugs
CALL¶
Run another program; return immediately with the process ID.
Usage:
call
ARGUMENTS: command [any-string! block! file!] An OS-local command line (quoted as necessary), a block with arguments, or an executable file REFINEMENTS: /wait Wait for command to terminate and then return the exit code /console Runs command with I/O redirected to console /shell Forces command to be run from shell /info Returns process information object containing the ID of the process (or 0 if failed to run), includes the exit code when used with /wait /input in [string! binary! file! none!] Redirects stdin to in /output out [string! binary! file! none!] Redirects stdout to out /error err [string! binary! file! none!] Redirects stderr to err
Description:
The call function interfaces to the operating system's command shell to execute programs, shell commands, and redirect command input and output.
call is normally blocked by the security level specified with the secure function. To use it, you must change your secure settings or run the script with reduced security (at your own risk):
secure callThe call function accepts one argument, which can be a string or a block specifying a shell command and its arguments. The following example shows a string as the call argument.
call "cp source.txt dest.txt"Use a block argument with call when you want to include REBOL values in the call to a shell command, as shown in the following example:
source: %source.txt
dest: %dest.txt
call reduce ["cp" source dest]The call function translates the file names in a block to the notation used by the shell. For example:
[dir %/c/windows]will convert the file name to windows shell syntax before doing it.
When shell commands are called, they normally run as a separate process in parallel with REBOL. They are asynchronous to REBOL. However, there are times when you want to wait for a shell command to finish, such as when you are executing multiple shell commands.
In addition, every shell command has a return code, which normally indicates the success or failure of the command. Typically, a shell command returns zero when it is successful and a non-zero value when it is unsuccessful.
The /wait refinement causes the call function to wait for a command's return code and return it to the REBOL program. You can then use the return code to verify that a command executed successfully, as shown in the following example:
if zero? call/wait "dir" [
print "worked"
]In the above example, call successfully executes the Windows dir command, which is indicated by the zero return value. However, in the next example, call is unsuccessful at executing the xcopy command, which is indicated by the return value other than zero.
if not zero? code: call/wait "xcopy" [
print ["failed:" code]
]In Windows and Unix (Linux), input to a shell command can be redirected from a file, URL, string, or port. By default, a shell command's output and errors are ignored by REBOL. However, shell command output and errors can be redirected to a file, URL, port, string, or the REBOL console.
instr: "data"
outstr: copy ""
errstr: copy ""
call/input/output/error "sort" instr outstr errstr
print [outstr errstr]See the REBOL Command Shell Interface documentation for more details.
Editor note: Proper link to the REBOL Command Shell Interface?
CASE¶
Evaluates each condition, and when true, evaluates what follows it.
Usage:
case
ARGUMENTS: block [block!] Block of cases (conditions followed by values) REFINEMENTS: /all Evaluate all cases (do not stop at first true case)
Description:
The case function provides a useful way to evaluate different expressions depending on specific conditions. It differs from the switch function because the conditions are evaluated and can be an expression of any length.
The basic form of case is:
case [
cond1 [code1]
cond2 [code2]
cond3 [code3]
]The if a condition is true (that is, it is not false or none ) then the block that follows it is evaluated, otherwise the next condition is evaluated.
num: 50
case [
num < 10 [print "small"]
num < 100 [print "medium"]
num < 1000 [print "large"]
]
mediumTo create a default case, simply use true as your last condition:
num: 10000
case [
num < 10 [print "small"]
num < 100 [print "medium"]
num < 1000 [print "large"]
true [print "huge"]
]
hugeReturn Value
The case function will return the value of the last expression it evaluated. This can come in handy:
num: 50
value: case [
num < 10 [num + 2]
num < 100 [num / 2]
true [0]
]
print value
25Evaluating All
Normally the case function stops after the first true condition is found and its block evaluated. However, the /all option forces case to evaluate the expressions for all true conditions.
num: 50
case/all [
num < 10 [print "small"]
num < 100 [print "medium"]
num < 1000 [print "large"]
]
medium
largeCATCH¶
Catches a throw from a block and returns its value.
Usage:
catch
ARGUMENTS: block [block!] Block to evaluate REFINEMENTS: /name Catches a named throw word [word! block!] One or more names /all Catches all throws, named and unnamed /quit Special catch for QUIT native /with callback [block! function!] Code to be evaluated on a catch
Description:
catch and throw go together. They provide a way to exit from a block without evaluating the rest of the block. To use it, provide catch with a block to evaluate. If within that block a throw is evaluated, it will return from the catch at that point.
The result of the catch will be whatever was passed as the argument to the throw.
write %file.txt "i am a happy little file with no real purpose"
print catch [
if exists? %file.txt [throw "Doc found"]
"Doc not found"
]
Doc not foundWhen using multiple catch functions, provide them with a name using the /name refinement to identify which one will catch which throw.
Editor note: Example with /name
Editor note: Example of using catch in a function spec.
CAUSE-ERROR¶
Causes an immediate error throw with the provided information.
Usage:
cause-error
ARGUMENTS: err-type [word!] err-id [word!] args
Description:
Editor note: Description is a stub. cause-error constructs and immediately throws an error!.
Editor note: Link to concept of error types?
Editor note: Argument description is a stub. The err-type argument controls the general type of error to construct, valid values are the words of the system/catalog/errors object. The err-id argument selects a specific error type within the err-type class of errors. The args argument is used to pass error-specific values
Editor note: Description of error IDs is a stub. All information about the currently available error types can be found in system/catalog/errors:
>> words-of system/catalog/errors
== [Throw Note Syntax Script Math Access Command resv700 User Internal]The specific errors within a given class can be inspected similarly:
>> ? system/catalog/errors/math
SYSTEM/CATALOG/ERRORS/MATH is an object of value:
code integer! 400
type string! "math error"
zero-divide string! "attempt to divide by zero"
overflow string! "math or number overflow"
positive string! "positive number required"All words except for code and type within an error type are possible specific errors. Their associated value is part of the error message that will displayed to the user if the error remains unhandled.
Some errors take arguments:
>> ? system/catalog/errors/script/no-value
SYSTEM/CATALOG/ERRORS/SCRIPT/NO-VALUE is a block of value: [:arg1 "has no value"]As an example, this no-value error which takes a single argument can be caused as follows:
>> cause-error 'script 'no-value 'Foo
** script error: Foo has no valueSimilarly, the two-argument no-arg error can be caused as follows:
>> cause-error 'script 'no-arg [Foo bar]
** script error: Foo is missing its bar argumentCD¶
Change directory (shell shortcut function).
Usage:
cd
ARGUMENTS:
path Accepts %file, :variables and just words (as dirs)
Description:
Variant of change-dir for shell use. Supports inputting words as directory names:
cd ..
cd somewhereCHANGE¶
Replaces element(s); returns just past the change.
Usage:
change
ARGUMENTS: series [series! gob! port! struct!] At position (modified) value [any-type!] The new value REFINEMENTS: /part Limits the amount to change to a given length or position range [number! series! pair!] /only Only change a block as a single value (not the contents of the block) /dup Duplicates the change a specified number of times count [number! pair!]
Description:
The change function modifies any type of series, such as a string! or block!, at its current index position.
It has many variations, but let's take a simple example that modifies a string! series:
name: "bog"
change name "d"
probe name
"dog"
change next name "i"
probe name
"dig"
change tail name "it"
probe name
"digit"Here is an example that changes a block! series:
colors: [red green blue]
change colors 'gold
probe colors
[gold green blue]
change at colors 3 [silver orange teal]
probe colors
[gold green silver orange teal]As you can see, if the second argument is a single value, it will replace the value at the current position in the first series. However, if the second argument is a series compatible with the first (block or string-based datatype), all of its values will replace those of the first argument or series.
Result
Be sure to note that change returns the series position just past the modification.
This allows you to cascade multiple changes.
For example:
test: "abcde"
change change test "1" "23"
probe test
"123de"So, you must use head if you need the string at its starting position:
probe head change "bog" "d"
"dog"
probe head change [1 4 5] [1 2 3]
[1 2 3]
probe head change [123 "test"] "the"
["the" "test"]Partial changes
The /PART refinement changes a specified number of elements within the target series.
In this line, the 2 indicates that the "ab" are both replaced with the new string, "123":
probe head change/part "abcde" "123" 2
"123cde"Duplication
probe head change/dup "abc" "->" 5
"->->->->->"Editor note: This section is new or has has recently changed and is still under construction.
title: copy "how it REBOL"
change title "N"
probe title
"Now it REBOL"
change find title "t" "s"
probe title
"Now is REBOL"
blk: copy ["now" 12:34 "REBOL"]
change next blk "is"
probe blk
["now" "is" "REBOL"]
probe head change/only [1 4 5] [1 2 3]
[[1 2 3] 4 5]
probe head change/only [1 4 5] [[1 2 3]]
[[[1 2 3]] 4 5]
string: copy "crush those grapes"
change/part string "eat" find/tail string "crush"
probe string
"eat those grapes"CHANGE-DIR¶
Changes the current directory path.
Usage:
change-dir
ARGUMENTS: path [file!]
Description:
Changes the value of system/script/path. This value is used for file-related operations. Any file path that does not begin with a slash (/) will be relative to the path in system/script/path. When a script file is executed using the do native, the path will automatically be set to the directory containing the path. When REBOL starts, it is set to the current directory where REBOL is started.
current: what-dir
make-dir %./rebol-temp/
probe current
%/C/REBOL/3.0/docs/scripts/
change-dir %./rebol-temp/
probe what-dir
%/C/REBOL/3.0/docs/scripts/rebol-temp/
change-dir current
delete %./rebol-temp/
probe what-dir
%/C/REBOL/3.0/docs/scripts/Note that the shorter shell friendly cd also exists.
CHANGES¶
What's new about this version.
Usage:
changes
CHAR?¶
Returns TRUE if it is this type.
Usage:
char?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values.
>> char? #"1"
== #(true)
>> char? 1
== #(false)CHARSET¶
Makes a bitset of chars for the parse function.
Usage:
charset
ARGUMENTS: chars [string! block! binary! char! integer!] REFINEMENTS: /length Preallocate this many bits len [integer!] Must be > 0
Description:
The charset function is a shortcut for:
make bitset! valueIt is used often for character based bitsets.
chars: charset "aeiou"
print find chars "o"
true
print find "there you go" chars
ere you go
digits: charset "0123456789"
area-code: ["(" 3 digits ")"]
phone-num: [3 digits "-" 4 digits]
print parse "(707)467-8000" [[area-code | none] phone-num]
trueCHECK¶
Temporary series debug check
Usage:
check
ARGUMENTS: val [series!]
CHECKSUM¶
Computes a checksum, CRC, hash, or HMAC.
Usage:
checksum
ARGUMENTS: data [binary! string! file!] If string, it will be UTF8 encoded. File is dispatched to file-checksum function. method [word!] One of `system/catalog/checksums` and HASH REFINEMENTS: /with Extra value for HMAC key or hash table size; not compatible with TCP/CRC24/CRC32/ADLER32 methods. spec [any-string! binary! integer!] String or binary for MD5/SHA* HMAC key, integer for hash table size. /part Limits to a given length length
Description:
Generally, a checksum is a number which accompanies data to verify that the data has not changed (did not have errors).
Available checksum method may differ between Rebol versions. What is available can be found in "system/catalog/checksums"
>> data: "foo" foreach method system/catalog/checksums [print [pad method 10 mold/flat checksum data method]]
adler32 42074437
crc24 5804686
crc32 -1938594527
md4 #{0AC6700C491D70FB8650940B1CA1E4B2}
md5 #{ACBD18DB4CC2F85CEDEF654FCCC4A4D8}
ripemd160 #{42CFA211018EA492FDEE45AC637B7972A0AD6873}
sha1 #{0BEEC7B5EA3F0FDBC95D0DD47F3C5BC275DA8A33}
sha224 #{0808F64E60D58979FCB676C96EC938270DEA42445AEEFCD3A4E6F8DB}
sha256 #{2C26B46B68FFC68FF99B453C1D30413413422D706483BFA0F98A5E886266E7AE}
sha384 #{98C11FFDFDD540676B1A137CB1A22B2A70350C9A44171D6B1180C6BE5CBB2EE3F79D532C8A1DD9EF2E8E08E752A3BABB}
sha512 #{F7FBBA6E0636F890E56FBBF3283E524C6FA3204AE298382D624741D0DC6638326E282C41BE5E4254D8820772C5518A2C5A8C0C7F7EDA19594A7EB539453E1ED7}
sha3-224 #{F4F6779E153C391BBD29C95E72B0708E39D9166C7CEA51D1F10EF58A}
sha3-256 #{76D3BC41C9F588F7FCD0D5BF4718F8F84B1C41B20882703100B9EB9413807C01}
sha3-384 #{665551928D13B7D84EE02734502B018D896A0FB87EED5ADB4C87BA91BBD6489410E11B0FBCC06ED7D0EBAD559E5D3BB5}
sha3-512 #{4BCA2B137EDC580FE50A88983EF860EBACA36C857B1F492839D6D7392452A63C82CBEBC68E3B70A2A1480B4BB5D437A7CBA6ECF9D89F9FF3CCD14CD6146EA7E7}
xxh3 #{AB6E5F64077E7D8A}
xxh32 #{E20F0DD9}
xxh64 #{33BF00A859C4BA3F}
xxh128 #{79AEF92E83454121AB6E5F64077E7D8A}
tcp 39201CLEAN-PATH¶
Returns new directory path with //, . and .. processed.
Usage:
clean-path
ARGUMENTS: file [file! url! string!] REFINEMENTS: /only Do not prepend current directory /dir Add a trailing / if missing
Description:
Rebuilds a directory path after decoding parent (..) and current (.) path indicators.
>> clean-path %com/www/../../../graphics/image.jpg
== %/C/REBOL/3.0/docs/graphics/image.jpg
>> messy-path: %/rebol/scripts/neat-stuff/../../experiments/./tests
== %/rebol/scripts/neat-stuff/../../experiments/./tests
>> neat-path: clean-path messy-path
== %/rebol/experiments/testsURLs are returned unmodified (because the true paths may not be known).
CLEAR¶
Removes elements from current position to tail; returns at new tail.
Usage:
clear
ARGUMENTS: series [series! port! map! gob! bitset! none!] At position, if ordered collection (modified)
Description:
clear is similar to remove but removes through the end of the series rather than just a single value. It returns at the current index position in the series.
str: copy "with all things considered"
clear skip str 8
print str
with all
str: copy "get there quickly"
clear find str "qui"
print str
get there
head clear find %file.txt %.txt
%fileCLOS¶
Defines a closure function.
Usage:
clos
ARGUMENTS: spec [block!] Help string (opt) followed by arg words (and opt type and string) body [block!] The body block of the function
CLOSE¶
Closes a port.
Usage:
close
ARGUMENTS: port [port!]
Description:
Closes a port opened earlier with the open function. Any changes to the port data that have been buffered will be written.
port: open %test-file.txt
insert port "Date: "
insert port form now
insert port newline
close port
print read %test-file.txt
readCLOSURE¶
Defines a closure function with all set-words as locals.
Usage:
closure
ARGUMENTS: spec [block!] Help string (opt) followed by arg words (and opt type and string) body [block!] The body block of the function REFINEMENTS: /with Define or use a persistent object (self) object [any-object! block! map!] The object or spec /extern words [block!] These words are not local
Description:
A closure is a special type of function that has persistent variables.
With a closure you can write a block inside the closure body and the block will remain persistent:
add2: closure [c d] [[c + d]]
do add2 1 2
3This works because the variables of a closure remain valid, even outside the closure after it has been called. Such variables have indefinite extent. They are not limited to the lifetime of the function.
Note, however, that this luxury provided by closures is not without its costs. Closures require more time to evaluate as well as more memory space.
In essence a closure is an object. When you define the closure, it constructs a prototype object, and each time you call the closure, the prototype object is instantiated and the body code is evaluated within that context.
More about closures here.
More about the benefits and costs of closures here.
CLOSURE?¶
Returns TRUE if it is this type.
Usage:
closure?
ARGUMENTS: value [any-type!]
Description:
Returns true if the input is a closure!
>> closure? make closure! [[][]]
== #(true)Editor note: Are there better examples?
COLLECT¶
Evaluates a block, storing values via KEEP function, and returns block of collected values.
Usage:
collect
ARGUMENTS: body [block!] Block to evaluate REFINEMENTS: /into Insert into a buffer instead (returns position after insert) output [series!] The buffer series (modified)
Description:
Using the internal keep function, will collect values spread around a block to be stored in another block and returned:
>> collect [keep 1 2 3 keep 4]
== [1 4]Can also be used with the parse function:
>> collect [
parse [a b c d e] [
any ['c | 'e | set w word! (keep w)]
]
]
== [a b d]Blocks are collected and appended to the output as a series of values:
>> collect [keep 1 keep [2 3]]
== [1 2 3]The keep function has a refinement /only to append blocks as blocks to the output:
>> collect [keep 1 keep/only [2 3]]
== [1 [2 3]]COLLECT-WORDS¶
Collect unique words used in a block (used for context construction).
Usage:
collect-words
ARGUMENTS: block [block!] REFINEMENTS: /deep Include nested blocks /set Only include set-words /ignore Ignore prior words words [any-object! block! none!] Words to ignore /as Datatype of the words in the returned block type [datatype!] Any word type
Description:
>> collect-words [a: 1 + b]
== [a + b]
>> collect-words/set [a: 1 + b]
== [a]
>> collect-words/set/as [a: 1 + b] set-word!
== [a:]COLOR-DISTANCE¶
Human perception weighted Euclidean distance between two RGB colors
Usage:
color-distance
ARGUMENTS: a [tuple!] b [tuple!]
Description:
>> color-distance 0.0.0 0.0.0
== 0.0
>> color-distance 0.0.0 255.0.0
== 402.874670338059
>> color-distance 0.0.0 255.255.0
== 649.929226916285
>> color-distance 0.0.0 255.255.255
== 764.833315173967COMBINE¶
Combines a block of values with a possibility to ignore by its types. Content of parens is evaluated.
Usage:
combine
ARGUMENTS: data [block!] Input values REFINEMENTS: /with Add delimiter between values delimiter /into Output results into a serie of required type out [series!] /ignore Fine tune, what value types will be ignored ignored [typeset!] Default is: #(typeset! [none! unset! error! any-function!]) /only Insert a block as a single value
Description:
>> combine [a b c]
== "abc"
>> combine [a #(none) b () c #(unset)]
== "abc"
>> combine/with [a #(none) b () c #(unset)] #"|"
== "a|b|c"
>> combine [{abc} (if false {def}) {ghi}]
== "abcghi"COMMAND?¶
Returns TRUE if it is this type.
Usage:
command?
ARGUMENTS: value [any-type!]
COMMENT¶
Ignores the argument value and returns nothing.
Usage:
comment
ARGUMENTS:
value A string, block, file, etc.
Description:
This function can be used to add comments to a script or to remove a block from evaluation. Note that this function is only effective in evaluated code and has no effect in data blocks. That is, within a data block comments will appear as data. In many cases, using comment is not necessary. Placing braces around any expression will prevent if from being evaluated (so long as it is not part of another expression).
comment "This is a comment."
comment [print "As a comment, this is not printed"]Note also that if the expression can't be loaded using load, the expression can't be commented out:
comment [a,b]
** Syntax error: invalid "word" -- "a,b"
** Near: (line 1) comment [a,b]COMPLEMENT¶
Returns the one's complement value.
Usage:
complement
ARGUMENTS: value [logic! integer! tuple! binary! bitset! typeset! image!]
Description:
The complement function is used for bit-masking integer! and tuple! values or inverting bitset! values (charsets).
complement 0
-1
complement -1
0
complement 0.255.0
255.0.255
chars: complement charset "ther "
find "there it goes" chars
it goesCOMPLEMENT?¶
Returns TRUE if the bitset is complemented
Usage:
complement?
ARGUMENTS: value [bitset!]
COMPOSE¶
Evaluates a block of expressions, only evaluating parens, and returns a block.
Usage:
compose
ARGUMENTS: value Block to compose REFINEMENTS: /deep Compose nested blocks /only Insert a block as a single value (not the contents of the block) /into Output results into a block with no intermediate storage out [any-block!]
Description:
The compose function builds a block of values, evaluating paren! expressions and inserting their results. It is a very useful method of building new blocks.
compose [result of 1 + 2 = (1 + 2)]
[result of 1 + 2 = 3]Notice that only the paren! expression is evaluated. All other values are left unchanged.
Here's another example, as might be used to create a header block (that has field names):
compose [time: (now/time) date: (now/date)]
[time: 17:47:13 date: 12-Feb-2009]Sub-Blocks
If the result of an expression is a block, then the elements of that block are inserted into the output block:
colors: ["red" "green" "blue"]
compose [1 2 3 (colors)]
[1 2 3 "red" "green" "blue"]If you want to insert the actual block, rather than its elements, there are a couple ways to do so. You can use the /only refinement:
colors: ["red" "green" "blue"]
compose/only [1 2 3 (colors)]
[1 2 3 ["red" "green" "blue"]]Or, you can add a reduce to put the block within another block:
colors: ["red" "green" "blue"]
compose [1 2 3 (reduce [colors])]
[1 2 3 ["red" "green" "blue"]]Evaluating All Parens
To evaluate all paren expressions, regardless of how deep the are nested within blocks, use the /deep refinement:
compose/deep [1 [2 [(1 + 2) 4]]]
[1 [2 [3 4]]]You can use /deep and /only together:
colors: ["red" "green" "blue"]
compose [1 2 3 [4 (colors)]]
[1 2 3 [4 "red" "green" "blue"]]Memory usage for large blocks
For most blocks you don't need to worry about memory because REBOL's automatic storage manager will efficiently handle it; however, when building large block series with compose, you can manage memory even more carefully.
For example, you might write:
append series compose [a (b) (c)]The word a and the evaluated results of b and c are appended to the series.
If this is done a lot, a large number of temporary series are generated, which take memory and also must be garbage collected later.
The /into refinement helps optimize the situation:
compose/into [a (b) (c)] tail seriesIt requires no intermediate storage.
COMPRESS¶
Compresses data.
Usage:
compress
ARGUMENTS: data [binary! string!] If string, it will be UTF8 encoded method [word!] One of `system/catalog/compressions` REFINEMENTS: /part length Length of source data /level lvl [integer!] Compression level 0-9
Description:
Editor note: Describe the method that compress uses to compress data
print compress "now is the dawning"
#{789CCBCB2F57C82C5628C9485548492CCFCBCC4B07003EB606BA12000000}
string: form first system/words
print length? string
8329
small: compress string
print length? small
3947As with all compressed files, keep an uncompressed copy of the original data file as a backup.
CONFIRM¶
Confirms a user choice.
Usage:
confirm
ARGUMENTS: question [series!] Prompt to user REFINEMENTS: /with choices [string! block!]
Description:
This function provides a method of prompting the user for a true ("y" or "yes") or false ("n" or "no") response. Alternate responses can be identified with the /with refinement.
confirm "Answer: 14. Y or N? "
confirm/with "Use A or B? " ["A" "B"]CONSTRUCT¶
Creates an object with scant (safe) evaluation.
Usage:
construct
ARGUMENTS: block [block! string! binary!] Specification (modified) REFINEMENTS: /with Default object object [object!] /only Values are kept as-is
Description:
This function creates new objects but without evaluating the object's specification (as is done in the make and context functions).
When you construct an object, only literal types are accepted. Functional evaluation is not performed. This allows your code to directly import objects (such as those sent from unsafe external sources such as email, cgi, etc.) without concern that they may include "hidden" side effects using executable code.
construct is used in the same way as the context function:
obj: construct [
name: "Fred"
age: 27
city: "Ukiah"
]
probe obj
make object! [
name: "Fred"
age: 27
city: "Ukiah"
]But, very limited evaluation takes place. That means object specifications like:
obj: construct [
name: uppercase "Fred"
age: 20 + 7
time: now
]
probe obj
make object! [
name: 'uppercase
age: 20
time: 'now
]do not produce evaluated results.
Except with the /only refinement, the construct function does perform evaluation on the words true, on, yes, false, off, no and none to produce their expected values. Literal words and paths will also be evaluated to produce their respective words and paths. For example:
obj: construct [
a: yes
b: none
c: 'word
]
probe obj
make object! [
a: true
b: none
c: word
]
type? obj/a
logic!
type? obj/c
word!The construct function is useful for importing external objects, such as preference settings from a file, CGI query responses, encoded email, etc.
To provide a template object that contains default variable values (similar to make), use the /with refinement. The example below would use an existing object called standard-prefs as the template.
prefs: construct/with load %prefs.r standard-prefsCONTEXT¶
Creates an object.
Usage:
context
ARGUMENTS: spec [block!] REFINEMENTS: /only Do not bind nested blocks
Description:
This function creates a unique new object. It is just a shortcut for make object!.
person: context [
name: "Fred"
age: 24
birthday: 20-Jan-1986
language: "REBOL"
]
probe person
make object! [
name: "Fred"
age: 24
birthday: 20-Jan-1986
language: "REBOL"
]
person2: make person [
name "Bob"
]
probe person2
make object! [
name: "Bob"
age: 24
birthday: 20-Jan-1986
language: "REBOL"
]CONTEXT?¶
Returns the context in which a word is bound.
Usage:
context?
ARGUMENTS: word [any-word!] Word to check.
CONTINUE¶
Throws control back to top of loop.
Usage:
continue
Description:
The continue function is the opposite of break. It jumps back to the top of the loop instead of exiting the loop.
For example:
repeat n 5 [
if n < 3 [continue]
print n
]
3
4
5COPY¶
Copies a series, object, or other value.
Usage:
copy
ARGUMENTS: value [series! port! map! object! bitset! any-function! error!] At position REFINEMENTS: /part Limits to a given length or end position range [number! series! pair!] /deep Also copies series values within the block /types What datatypes to copy kinds [typeset! datatype!]
Description:
The copy function will copy any series, such as string! or block!, and most other compound datatypes such as object! or function!. It is not used for immediate datatypes, such as integer!, decimal!, time!, date!, and others.
This example shows what happens if you don't copy:
name: "Tesla"
print name
Tesla
name2: name
insert name2 "Nicola "
print name2
Nicola Tesla
print name
Nicola TeslaThat's because, it's the same string:
same? name name2
trueHere's the example using copy for the second string:
name: "Tesla"
print name
Tesla
name2: copy name
insert name2 "Nicola "
print name2
Nicola Tesla
print name
Tesla
same? name name2
falseThe same behavior is also true for blocks. This example shows various results:
block1: [1 2 3]
block2: block1
block3: copy block1
append block1 4
append block2 5
append block4 6
probe block1
[1 2 3 4 5]
probe block2
[1 2 3 4 5]
probe block3
[1 2 3 6]There will be times in your code where you'll want to append to or insert in a string or other series. You will need to think about what result you desire.
Compare this example:
str1: "Nicola"
str2: append str1 " Tesla"
print str1
Nicola Tesla
print str2
Nicola Teslawith this example that uses the copy function:
str1: "Nicola"
str2: append copy str1 " Tesla"
print str1
Nicola
print str2
Nicola TeslaCopy Part
It is fairly common to copy just a sub-string or sub-block. To do so, use the /part refinement. The length of the result is determined by an integer size or by the ending position location.
name: "Nicola Tesla"
copy/part name 6
"Nicola"
copy/part skip name 7 5
"Tesla"
copy/part find name "Tesla" tail name
"Tesla"Notice that the ending position can be a length or a position within the string (as shown by the tail example above.)
If you use other languages, you will notice that this result is similar to what a substr function provides. Although we recommend using copy with /part, you can easily define your own substr function this way:
substr: func [arg [series!] start length] [
copy/part skip arg start length
]For example:
substr "string example" 7 7
"example"We should explain why we don't normally define a substr function. Most of the time when you're extracting substrings, you are either using a function like find or you're using a loop of some kind. Therefore, you don't really care about the starting offset of a string, you only care about the current location.
For example:
str: "This is an example string."
str2: copy/part find str "ex" 7And, in fact, it's common to write use two find functions in this way:
start: find str "ex"
end: find start "le"
str2: copy/part start endwhich advanced users often write in one line this way:
str2: copy/part s: find str "ex" find s "le"Of course, if the string might not be found, this is a helpful pattern to use:
str2: all [
start: find str "ex"
end: find start "le"
copy/part start end
]If the start or end are not found, then str2 is set to none.
Here's an example of a simple loop that finds substrings:
str: "this example is an example"
pat: "example"
while [str: find str pat] [
print copy/part str length? pat
str: skip str length? pat
]Copy Deep
When copying blocks, keep in mind that simple use of the copy function does not make copies of series values within a block.
Notice that the copy here does not copy the name string:
person1: ["Tesla" 10-July-1856 Serbian]
person2: copy person1
insert person/2 "Nicola "
probe person1
["Nicola Tesla" 10-July-1856 Serbian]If you need to copy both the block and all series values within it, use copy with the /deep refinement:
person1: ["Tesla" 10-July-1856 Serbian]
person2: copy/deep person1
insert person/2 "Nicola "
probe person1
["Tesla" 10-July-1856 Serbian]
probe person2
["Nicola Tesla" 10-July-1856 Serbian]Here both the block and the string are separate series.
Also be aware that if your block contains other blocks, they will be deep copied as well, including all strings and other series within them.
If you want to deep copy only a specific datatype, such as just strings or just blocks, you can use the /types refinement.
Here are a few examples of its usage:
copy/deep/types block string!
copy/deep/types block any-string!
copy/deep/types block make typeset! [string! url! file!]Copy Objects
If you use copy on an object, a copy of the object is returned. This can be useful when objects are used only as simple storage structures. Note that rebinding is not done; therefore, do not use copy on objects when that is required.
Helpful Hint
To see a list of functions that modify their series (not copy), type this line:
? modifies
Found these related words:
alter function! If a value is not found in a series, append i...
append action! Inserts a value at tail of series and returns...
bind native! Binds words to the specified context. (Modifi...
change action! Changes a value in a series and returns the s...
clear action! Removes all values. For series, removes from ...
decloak native! Decodes a binary string scrambled previously ...
deline native! Converts string terminators to standard forma...
detab native! Converts tabs in a string to spaces (default ...
encloak native! Scrambles a binary string based on a key. (Mo...
enline native! Converts standard string terminators to curre...
entab native! Converts spaces in a string to tabs (default ...
insert action! Inserts into a series and returns the series ...
lowercase native! Converts string of characters to lowercase. (...
...COS¶
Returns the trigonometric cosine.
Usage:
cos
ARGUMENTS: value [decimal!] In radians
COSINE¶
Returns the trigonometric cosine.
Usage:
cosine
ARGUMENTS: value [number!] In degrees by default REFINEMENTS: /radians Value is specified in radians
Description:
Ratio between the length of the adjacent side to the length of the hypotenuse of a right triangle.
print cosine 90
0.0
print (cosine 45) = (sine 45)
true
print cosine/radians pi
-1.0CREATE¶
Send port a create request.
Usage:
create
ARGUMENTS: port [port! file! url! block!]
Description:
Creates the file or URL object that is specified.
create %testfile.txt
read %./
[%testfile.txt]CURSOR¶
Changes the mouse cursor image.
Usage:
cursor
ARGUMENTS: image [integer! image! none!]
Description:
This only works in a View window.
cursor 1
cursor 2
cursor 3
cursor 4
cursor 5
cursor 6Editor note: Describe all cursors here
DATATYPE?¶
Returns TRUE if it is this type.
Usage:
datatype?
ARGUMENTS: value [any-type!]
Description:
Returns false for all other values.
print datatype? integer!
true
print datatype? 1234
falseDATE?¶
Returns TRUE if it is this type.
Usage:
date?
ARGUMENTS: value [any-type!]
Description:
Returns false for all other values.
print date? 1/3/69
true
print date? 12:39
falseDEBASE¶
Decodes binary-coded string to binary value.
Usage:
debase
ARGUMENTS: value [binary! any-string!] The string to decode base [integer!] Binary base to use: 85, 64, 36, 16, or 2 REFINEMENTS: /url Base 64 Decoding with URL and Filename Safe Alphabet /part Limit the length of the input limit [integer! binary! any-string!]
Description:
Converts from an encoded string to the binary value. Primarily used for BASE-64 decoding.
>> debase "MTIzNA==" 64
== #{31323334}
>> debase "12AB C456" 16
== #{12ABC456}
>> enbased: enbase "a string of text" 64
== "YSBzdHJpbmcgb2YgdGV4dA=="
>> string? enbased ;; enbased value is a string
== #(true)
>> debased: debase enbased 64 ;; converts to binary value
== #{6120737472696E67206F662074657874}
>> to string! debased ;; converts back to original string
== "a string of text"If the input value cannot be decoded (such as when the proper number of characters is missing), an 'invalid-data error is thrown. This behavior is different from Rebol2, where none is returned.
>> debase "AA" 16
== #{AA}
>> debase "A" 16
** Script error: data not in correct format: "A"DECIMAL?¶
Returns TRUE if it is this type.
Usage:
decimal?
ARGUMENTS: value [any-type!]
Description:
Returns false for all other values.
>> decimal? 1.2
== #(true)
>> decimal? 1
== #(false)DECLOAK¶
Decodes a binary string scrambled previously by encloak.
Usage:
decloak
ARGUMENTS: data [binary!] Binary series to descramble (modified) key [string! binary! integer!] Encryption key or pass phrase REFINEMENTS: /with Use a string! key as-is (do not generate hash)
Description:
decloak is a low strength decryption method that is used with encloak. See the encloak function for a complete description and examples.
DECODE¶
Decodes a series of bytes into the related datatype (e.g. image!).
Usage:
decode
ARGUMENTS: type [word!] Media type (jpeg, png, etc.) data The data to decode
Description:
Used to call codecs to decode binary data (bytes) into related datatypes.
Codecs are identified by words that symbolize their types. For example the word png is used to identify the PNG codec.
See the system/codecs for a list of loaded codecs. Codecs can be native (built-in), externally loaded, or even coded in REBOL.
Examples
The line:
image: load %photo.jpgis roughly equivalent to:
data: read %photo.jpg ; returns binary data
image: decode 'jpeg dataDECODE-URL¶
Return object with URL components, or cause an error if not a valid URL
Usage:
decode-url
ARGUMENTS: url [url! string!]
Description:
This is a handy function that saves you the effort of writing your own URL parser.
probe decode-url http://user:pass@www.rebol.com/file.txt
[scheme: 'http pass: "pass" user: "user" host: "www.rebol.com" path: "/file.txt"]DECOMPRESS¶
Decompresses data.
Usage:
decompress
ARGUMENTS: data [binary!] Source data to decompress method [word!] One of `system/catalog/compressions` REFINEMENTS: /part Limits source data to a given length or position length [number! series!] Length of compressed data (must match end marker) /size bytes [integer!] Number of uncompressed bytes.
Description:
Examples:
write %file.txt read http://www.rebol.net
size? %file.txt
5539
save %file.comp compress read %file.txt
size? %file.comp
2119
write %file.decomp decompress load %file.comp
size? %file.decomp
5539If the data passed to the decompress function has been altered or corrupted, a decompression error will occur.
A typical error is out of memory, if the decompressed file length appears to be wrong (perhaps several gigabytes instead of 5539 bytes) to decompress.
Using the /limit refinement, puts a hard limit to the size of the decompressed file:
decompress/limit read %file.comp 5000
** Script error: maximum limit reached: 5539
** Where: decompress
** Near: decompress/limit read %file.comp 5000This can help avoiding that a decompress operation on a corrupt file suddenly eats all system resources.
Special Notes
decompress can decompress any ZLIB data as long as the data has the length of the uncompressed data in binary little-endian representation appended:
zlib-decompress: func [
zlib-data [binary!]
length [integer!] "known uncompressed zlib data length"
][
decompress head insert tail zlib-data third make struct! [value [integer!]] reduce [length]
]DEDUPLICATE¶
Removes duplicates from the data set.
Usage:
deduplicate
ARGUMENTS: set [block! string! binary!] The data set (modified) REFINEMENTS: /case Use case-sensitive comparison /skip Treat the series as records of fixed size size [integer!]
DEFAULT¶
Set a word to a default value if it hasn't been set yet.
Usage:
default
ARGUMENTS: word [word! set-word! lit-word!] The word (use :var for word! values) value The value
Description:
The default function is a clear way to indicate that you want a variable set to a default value if it's not already been set.
For example:
default size 100would set size to 100 if it's not already been set to some other value.
You can think of default as a shortcut for any when used like this:
size: any [size 100]However, default avoids the need to specify the size word twice and also makes the intention of your code more clear. It's quite often used for global configuration variables that may or may not have been set by prior code.
DEHEX¶
Converts URL-style hex encoded (%xx) strings. If input is UTF-8 encode, you should first convert it to binary!
Usage:
dehex
ARGUMENTS: value [any-string! binary!] The string to dehex REFINEMENTS: /escape char [char!] Can be used to change the default escape char #"%" /uri Decode space from a special char (#"+" by default or #"_" when escape char is #"=")
Description:
Converts the standard URL hex sequence that begins with a % followed by a valid hex value. Otherwise, the sequence is not converted and will appear as written.
>> dehex "a%20b"
== "a b"
>> dehex/uri "a+b"
== "a b"
>> dehex/escape "a#20b" #"#"
== "a b"DELECT¶
Parses a common form of dialects. Returns updated input block.
Usage:
delect
ARGUMENTS: dialect [object!] Describes the words and datatypes of the dialect input [block!] Input stream to parse output [block!] Resulting values, ordered as defined (modified) REFINEMENTS: /in Search for var words in specific objects (contexts) where [block!] Block of objects to search (non objects ignored) /all Parse entire block, not just one command at a time
Description:
DELECT stands for DEcode diaLECT. It is used to implement REBOL's internal dialects such as DRAW, EFFECT, RICH TEXT, SECURE, and VID, but its function is available to all users.
This is used for parsing unordered dialects. In unordered dialects, the order of arguments is less important than their type.
Here's a simple example. First the dialect is specified as a context:
dialect: context [
default: [tuple!]
single: [string!]
double: [integer! string!]
]Then an input and output block is specified. The input block contains the data to parse. The output block stores the result:
inp: [1.2.3 single "test" double "test" 123]
out: make block! 4 ; (any initial size works)Now the input is processed using delect, one step at a time:
while [inp: delect dialect inp out] [
?? out
?? inp
]To read more about delect, see here.
DELETE¶
Send port a delete request.
Usage:
delete
ARGUMENTS: port [port! file! url! block!]
Description:
Deletes the file or URL object that is specified. If the file or URL refers to an empty directory, then the directory will be deleted.
write %delete-test.r "This file is no longer needed."
delete %delete-test.r
writeDELETE-DIR¶
Deletes a directory including all files and subdirectories.
Usage:
delete-dir
ARGUMENTS: path [file!]
DELINE¶
Converts string terminators to standard format, e.g. CRLF to LF.
Usage:
deline
ARGUMENTS: string [any-string!] (modified) REFINEMENTS: /lines Return block of lines (works for LF, CR, CR-LF endings) (no modify)
Description:
Useful for converting OS dependent string terminators to LF.
CRLF string termination:
>> deline "a^M^/b" ; Windows, DOS, CP/M, OS/2, Symbian
== "a^/b"CR string termination:
>> deline "a^Mb" ; MacOS 1-9
== "a^/b"LF string termination:
>> deline "a^/b" ; MacOSX, AmigaOS, FreeBSD, GNU/Linux, BeOS, RiscOS
== "a^/b"When using the /LINES refinement, the string will be split in blocks of strings per line:
>> deline/lines "a^M^/b"
== [
"a"
"b"
]Note that when reading from disk, READ/STRING provides the same functionality.
>> write %test.txt ajoin ["a" CRLF "b"]
== %test.txt
>> read/string %test.txt
== "a^/b"
>> to string! read %test.txt
== "a^M^/b"DELTA-PROFILE¶
Delta-profile of running a specific block.
Usage:
delta-profile
ARGUMENTS: block [block!]
Description:
Provides detailed profiling information captured during the evaluation of a block.
See Profiler for detailed examples.
Simple example:
>> dp [loop 10 [next "a"]]
== make object! [
timer: 39
evals: 31
eval-natives: 14
eval-functions: 1
series-made: 1
series-freed: 0
series-expanded: 0
series-bytes: 432
series-recycled: 0
made-blocks: 1
made-objects: 0
recycles: 0
]DELTA-TIME¶
Delta-time - returns the time it takes to evaluate the block.
Usage:
delta-time
ARGUMENTS: block [block!]
Description:
Returns the amount of time required to evaluate a given block.
Example:
>> dt [loop 1000000 [next "a"]]
0:00:00.25See Profiler for detailed information about timing and profiling.
DETAB¶
Converts tabs to spaces (default tab size is 4).
Usage:
detab
ARGUMENTS: string [any-string!] (modified) REFINEMENTS: /size Specifies the number of spaces per tab number [integer!]
Description:
The REBOL language default tab size is four spaces. detab will remove tabs from the entire string even beyond the first non-space character.
The series passed to this function is modified as a result.
text: "^-lots^-^-of^-^-tabs^-^-^-^-here"
print detab copy text
lots of tabs hereUse the /size refinement for other sizes such as eight:
print detab/size text 8
lots of tabs hereDH¶
Diffie-Hellman key exchange
Usage:
dh
ARGUMENTS: dh-key [handle!] DH key created using `dh-init` function REFINEMENTS: /public Returns public key as a binary /secret Computes secret result using peer's public key public-key [binary!] Peer's public key
DH-INIT¶
Generates a new Diffie-Hellman private/public key pair
Usage:
dh-init
ARGUMENTS: g [binary!] Generator p [binary!] Field prime
DIFFERENCE¶
Returns the special difference of two values.
Usage:
difference
ARGUMENTS: set1 [block! string! bitset! date! typeset! map!] First data set set2 [block! string! bitset! date! typeset! map!] Second data set REFINEMENTS: /case Uses case-sensitive comparison /skip Treat the series as records of fixed size size [integer!]
Description:
Returns the elements of two series that are not present in both. Both series arguments must be of the same datatype (string, block, etc.) Newer versions of REBOL also let you use difference to compute the difference between date/times.
lunch: [ham cheese bread carrot]
dinner: [ham salad carrot rice]
probe difference lunch dinner
[cheese bread salad rice]
probe difference [1 3 2 4] [3 5 4 6]
[1 2 5 6]
string1: "CBAD" ; A B C D scrambled
string2: "EDCF" ; C D E F scrambled
probe difference string1 string2
"BAEF"Date differences produce a time in hours:
probe difference 1-Jan-2002/0:00 1-Feb-2002/0:00
-744:00
probe difference 1-Jan-2003/10:30 now
-59449:55:14This is different from when using subtract, which returns the difference in days:
probe subtract 1-Jan-2002/0:00 1-Feb-2002/0:00
-31
probe subtract 1-Jan-2003/10:30 now
-2477There is a limit to the time period that can be differenced between dates (determined by the internal size of the time! datatype).
Note that performing this function over very large data sets can be CPU intensive.
DIR¶
Print contents of a directory (ls).
Usage:
dir
ARGUMENTS: path [file! word! path! string! unset!] Accepts %file, :variables, and just words (as dirs) REFINEMENTS: /f Files only /d Dirs only /r Recursive /i indent [string! char!] /l Limit recursive output to given maximal depth max-depth [integer!]
DIR?¶
Returns TRUE if the value looks like a directory spec (ends with a slash (or backslash)).
Usage:
dir?
ARGUMENTS: target [file! url! none!] REFINEMENTS: /check If the file is a directory on local storage (don't have to end with a slash)
Description:
Returns false if it is not a directory.
print dir? %file.txt
false
print dir? %.
trueNote that the file that is input, is read from disk, if it exists. The function returns true, when the input either ends in / or if the name exists on disk as a directory.
DIR-TREE¶
Prints a directory tree
Usage:
dir-tree
ARGUMENTS: path [file! word! path! string! unset!] Accepts %file, :variables, and just words (as dirs) REFINEMENTS: /d Dirs only /i indent [string! char!] /l max-depth /callback on-value [function!] Function with [value depth] args - responsible to format value line
DIRIZE¶
Returns a copy (always) of the path as a directory (ending slash).
Usage:
dirize
ARGUMENTS: path [file! string! url!]
Description:
Convert a file name to a directory name.
For example:
probe dirize %dir
%dir/It is useful in cases where paths are used:
dir: %files/examples
new-dir: dirize dir/new-code
probe new-dir
%files/examples/new-code/This is useful because the PATH notation does not allow you to write:
new-dir: dirize dir/new-code/DIVIDE¶
Returns the first value divided by the second.
Usage:
divide
ARGUMENTS: value1 [scalar! vector!] value2 [scalar! vector!]
Description:
If the second value is zero, an error will occur.
Examples:
print divide 123.1 12
10.25833333333333
print divide 10:00 4
2:30When dividing values of different datatypes, they must be compatible:
divide 4x5 $2.7
** Script error: incompatible argument for divide of pair!
** Where: divide
** Near: divide 4x5 $2.7DO¶
Evaluates a block, file, URL, function, word, or any other value.
Usage:
do
ARGUMENTS: value [any-type!] Normally a file name, URL, or block REFINEMENTS: /args If value is a script, this will set its system/script/args arg Args passed to a script (normally a string) /next Do next expression only, return it, update block variable var [word!] Variable updated with new block position
Description:
The do function evaluates a script file or a series of expressions and returns a result.
It performs the fundamental interpretive action of the REBOL language and is used internally within many other functions such as if, case, while, loop, repeat, foreach, and others.
Most Common Use
Most of the time do is used to evaluate a script from a file! or url! as shown in these examples:
do %setup.r
Settings done.
do http://www.rebol.com/speed.r
Console: 0:00:01.609 - 314 KC/S
Processor: 0:00:00.406 - 2128 RHz (REBOL-Hertz)
Memory: 0:00:00.657 - 72 MB/S
Disk/File: 0:00:00.234 - 130 MB/SNote that do of a file! or url! requires that the script contain a valid REBOL header; otherwise, you'll get an "Script is missing a REBOL header" error.
Other Uses
The do function can also be called to evaluate other types of arguments such as a block!, path!, string!, or function!.
do [1 + 2]
3
do "1 + 2" ; see special note below
3Expressions are evaluated left to right and the final result is returned. For example:
do [1 + 2 3 * 4]
12To obtain all results, use the reduce function instead.
print reduce [1 + 2 3 * 4]
3 12Other Examples
Selecting a block to evaluate:
blk: [
[print "test"]
[loop 3 [print "loop"]]
]
do first blk
test
do second blk
loop
loop
loopRefinements
The /args refinement allows you to pass arguments to another script and is used with a file, or URL. Arguments passed with /args are stored in system/script/args within the context of the loaded script.
The /next refinement returns a block consisting of two elements. The first element is the evaluated return of the first expression encountered. The second element is the original block with the current index placed after the last evaluated expression.
Special Notes
Evaluating strings is much slower than evaluating blocks and values. That's because REBOL is a symbolic language, not a string language. It is considered bad practice to convert values to strings and join them together to pass to do for evaluation. This can be done directly without strings.
For example, writing code like this is a poor practice:
str: "1234 + "
code: join str "10"
do code
1244Instead, just use:
blk: [1234 +]
code: join blk 10
do code
1244In other words, you can join values in blocks just as easily as strings.
DO-CALLBACK¶
Internal function to process callback events.
Usage:
do-callback
ARGUMENTS: event [event!] Callback event
DO-CODEC¶
Evaluate a CODEC function to encode or decode media types.
Usage:
do-codec
ARGUMENTS: handle [handle!] Internal link to codec action [word!] Decode, encode, identify data [binary! image! string!]
Description:
This is an internal native function used to call codecs. It is normally called by the encode and decode functions.
See the system/catalog/codecs for a list of loaded codecs. Codecs can be native (built-in), externally loaded, or coded in REBOL.
DO-COMMANDS¶
Evaluate a block of extension module command functions (special evaluation rules.)
Usage:
do-commands
ARGUMENTS: commands [block!] Series of commands and their arguments
Description:
High speed command! block evaluation for extensions.
Originally created to evaluate graphics rendering commands, it can be used for any external sequence of commands that require maximum speed (e.g. high speed math processing such as FFTs, image processing, audio processing.)
Special Evaluation Method
The greater speed of command blocks is obtained through the use of a special evaluation method:
- Evaluation is strictly linear. Sub-expressions, control branching, and recursion are not allowed so no stack management is required.
- Arguments are already reduced to their final values (or variables that hold those values.)
- Special variations of function arguments are not allowed. Only word and 'word forms are allowed.
- Arguments must appear in the correct order and no optional arguments are allowed.
- Arguments are placed directly within the command argument frame, not on the primary evaluator stack.
In subsystems like the R3 GUI, graphical elements are rendered by generating semi-static draw blocks either during style definition (definition of a button), face instantiation (creating an instance of a button), or face state modification (eg. hovering over a button).
The advantage of the static form of such draw blocks is that they require no further evaluation, hence take no additional memory or CPU time. In fact, the state of the GUI at any specific time is simply a sequence of draw block renderings. Therefore, a fast method of calling draw functions can greatly speed-up the rendering time of the GUI.
For special draw dialects (like the one used in the GUI) where optional or datatype-ordered arguments are allowed, a conversion from the dialect block to the command block is required. However, this conversion was already being performed in order to reduce the run-time overhead of the dialects (to avoid the NxM argument reordering penalty), so no additional overhead is incurred.
General Form
The general form is:
do-commands [
command1 arg11 arg12
command2 arg21 arg22 arg23
result: command3 arg31
...
]Notice that set-words for results are allowed. In addition, the result of the final command will be returned from the do-commands function.
Argument Requirements
Command blocks are written in a reduced minimal form. They consist of one or more commands followed by their arguments. The arguments must be actual values or variables; sub-expressions and operators are not allowed. If necessary, use reduce with /only or compose to preprocess command blocks.
For example, you can write:
line 0x0 100x100
line 100x100 200x200and the command can also be variables:
line start1 end1
line start2 end2Sub expressions are not allowed:
line 0x0 base + 10 ; error
line 0x0 add base 10 ; errorHowever, if necessary you can escape to parens for sub-expressions, but it reduces run-time performance:
line 0x0 (base + 10) ; ok, but slowErrors
An error will occur if any value other than a command is found:
multiply 10 20
** Script error: expected command! not multiplyAn error will also occur if an argument is not of the correct datatype, or if the block ends before all of its actual arguments are provided.
DO-EVENTS¶
Waits for window events. Returns when all windows are closed.
Usage:
do-events
Description:
Process user events in GUI windows. When this function is called the program becomes event driven. This function does not return until all windows have been closed.
DOES¶
A shortcut to define a function that has no arguments or locals.
Usage:
does
ARGUMENTS: body [block!] The body block of the function
Description:
does provides a shortcut for defining functions that have no arguments or local variables.
rand10: does [random 10]
print rand10
5
this-month: does [now/month]
print this-month
2This function is provided as a coding convenience and it is otherwise identical to using func or function.
DP¶
Note: Shell shortcut for delta-profile.
DS¶
Temporary stack debug
Usage:
ds
Description:
Having such a code in the console:
>> fun: func[a][ if a > 0 [ds] ]
>> fun 1Will output:
STACK[16] ds[0] native!
STACK[12] if[3] native!
condition: #(true)
true-branch: [ds]
only: #(none)
STACK[5] fun[1] function!
a: 1DT¶
Note: Shell shortcut for delta-time.
DUMP¶
Temporary debug dump
Usage:
dump
ARGUMENTS: v REFINEMENTS: /fmt only series format
Description:
Note: A debug build is required to use this function!
DUMP-OBJ¶
Returns a string with information about an object value
Usage:
dump-obj
ARGUMENTS: obj [any-object! map!] REFINEMENTS: /weak Provides sorting and does not displays unset values /match Include only those that match a string or datatype pattern /not-none Ignore NONE values
Description:
This function provides an easy way to view the contents of an object. The function is friendly to print. It is an alternative to mold and probe which may display too much information for deeply structured objects.
>> print dump-obj object [a: 1 b: "hello"]
a integer! 1
b string! "hello"ECDH¶
Elliptic-curve Diffie-Hellman key exchange
Usage:
ecdh
ARGUMENTS: key [handle! none!] Keypair to work with, may be NONE for /init refinement REFINEMENTS: /init Initialize ECC keypair. type [word!] One of supported curves: system/catalog/elliptic-curves /curve Returns handles curve type /public Returns public key as a binary /secret Computes secret result using peer's public key public-key [binary!] Peer's public key
ECDSA¶
Elliptic Curve Digital Signature Algorithm
Usage:
ecdsa
ARGUMENTS: key [handle! binary!] Keypair to work with, created using ECDH function, or raw binary key (needs /curve) hash [binary!] Data to sign or verify REFINEMENTS: /sign Use private key to sign data, returns ASN1 encoded result /verify Use public key to verify signed data, returns true or false signature [binary!] ASN1 encoded /curve Used if key is just a binary type [word!] One of supported curves: system/catalog/elliptic-curves
ECHO¶
Copies console output to a file.
Usage:
echo
ARGUMENTS: target [file! none! logic!]
Description:
Write output to a file in addition to the user console. The previous contents of a file will be overwritten. The echo can be stopped with echo none or by starting another echo.
echo %helloworld.txt
print "Hello World!"
echo none
Hello World!EIGHTH¶
Returns the eighth value of a series.
Usage:
eighth
ARGUMENTS:
value
Description:
This is an ordinal.
See the first function for examples. If no value is found, none is returned.
EITHER¶
If TRUE condition return first arg, else second; evaluate blocks by default.
Usage:
either
ARGUMENTS: condition [any-type!] true-branch false-branch REFINEMENTS: /only Suppress evaluation of block args.
Description:
The either function will evaluate one block or the other depending on a condition.
This function provides the same capability as the if-else statements found in other languages. Because REBOL is a functional language, it is not desirable to use the word else within the expression.
Here's an example:
either 2 > 1 [print "greater"] [print "not greater"]
greater
either 1 > 2 [print "greater"] [print "not greater"]
not greaterThe condition can be the result of several expressions within any or and, or any other function that produces a result:
either all [
time > 10:20
age > 20
find users "bob"
] [print "that's true"] [print "that's false"]
that's trueIn addition, it can be pointed out that the evaluated blocks can be within a variable:
blk1: [print "that's true"]
blk2: [print "that's false"]
either 2 > 1 blk1 blk2
that's trueReturn Value
The either function returns the result of the block that it evaluates.
print either 2 > 1 ["greater"] ["not greater"]
greaterSimplification
The above example is pretty common, but it should be noted that it can be easily refactored:
either 2 > 1 [print "greater"] [print "not greater"]is better written as:
print either 2 > 1 ["greater"] ["not greater"]or even better written as:
print pick ["greater" "not greater"] 2 > 1The importance of this is that you're picking from a choice of two strings, and you're doing it here with one less block than the code above it.
Be careful with this last method. The pick function only allows true and false, not none. See either for more details.
A Common Error
A common error is to forget to provide the second block to the either function. This usually happens when you simplify an expression, and forget to change the either to an if function.
This is wrong:
either 2 > 1 [print "greater"]and it may become quite confusing as to why your program isn't working correctly.
You should have written:
if 2 > 1 [print "greater"]ELLIPSIZE¶
Truncate and add ellipsis if str is longer than len
Usage:
ellipsize
ARGUMENTS: str [string!] (modified) len [integer!] Max length REFINEMENTS: /one-line Escape line breaks
EMAIL?¶
Returns TRUE if it is this type.
Usage:
email?
ARGUMENTS: value [any-type!]
Description:
Returns false for all other values.
print email? info@rebol.com
true
print email? http://www.REBOL.com
falseEMPTY?¶
Returns TRUE if empty or NONE, or for series if index is at or beyond its tail.
Usage:
empty?
ARGUMENTS: series [series! object! gob! port! bitset! typeset! map! none!]
Description:
This is a synonym for tail? The check is made relative to the current location in the series.
print empty? []
true
print empty? [1]
falseThe empty? function is useful for all types of series. For instance, you can use it to check a string returned from the user:
str: ask "Enter name:"
if empty? str [print "Name is required"]It is often used in conjunction with trim to remove black spaces from the ends of a string before checking it:
if empty? trim str [print "Name is required"]ENBASE¶
Encodes a string into a binary-coded string.
Usage:
enbase
ARGUMENTS: value [binary! any-string!] If string, will be UTF8 encoded base [integer!] Binary base to use: 85, 64, 36, 16, or 2 REFINEMENTS: /url Base 64 Encoding with URL and Filename Safe Alphabet /part Limit the length of the input limit [integer! binary! any-string!] /flat No line breaks
Description:
Converts from a string or binary into an encode string value.
>> enbase "Here is a string." 64
== "SGVyZSBpcyBhIHN0cmluZy4="
>> enbase #{12abcd45} 16
== "12ABCD45"The debase function is used to convert the binary back again. For example:
>> str: enbase "This is a string" 16
== "54686973206973206120737472696E67"
>> debase str 16
== #{54686973206973206120737472696E67}ENCLOAK¶
Scrambles a binary string based on a key.
Usage:
encloak
ARGUMENTS: data [binary!] Binary series to scramble (modified) key [string! binary! integer!] Encryption key or pass phrase REFINEMENTS: /with Use a string! key as-is (do not generate hash)
Description:
encloak is a low strength encryption method that can be useful for hiding passwords and other such values. It is not a replacement for AES or Blowfish, but works for noncritical data.
Do not use it for top secret information!
To cloak a binary string, provide the binary string and a cloaking key to the encloak function:
>> bin: encloak #{54686973206973206120737472696E67} "a-key"
== #{4972E8CD78CE343EC727810866AE5F6B}To cloak a string of characters, convert it using to-binary :
>> bin: encloak to-binary "This is a string" "a-key"
== #{4972E8CD78CE343EC727810866AE5F6B}The result is an encrypted binary value which can be decloaked with the line:
>> decloak bin "a-key"
== #{54686973206973206120737472696E67}
>> to string! bin
== "This is a string"The stronger your key, the better the encryption. For important data use a much longer key that is harder to guess. Also, do not forget your key, or it may be difficult or impossible to recover your data.
Now you have a simple way to save out a hidden string, such as a password:
key: ask "Cloak key? (do not forget it) "
data: to-binary "string to hide"
save %data encloak data keyTo read the data and decloak it:
key: ask "Cloak key? "
data: load %data
data: to-string decloak data keyOf course you can cloak any kind of data using these functions, even non-character data such as programs, images, sounds, etc. In those cases you do not need the to-binary conversion shown above.
Note that by default, the cloak functions will hash your key strings into 160 bit SHA1 secure cryptographic hashes. If you have created your own hash key (of any length), you use the /with refinement to provide it.
ENCODE¶
Encodes a datatype (e.g. image!) into a series of bytes.
Usage:
encode
ARGUMENTS: type [word!] Media type (jpeg, png, etc.) data The data to encode REFINEMENTS: /as Special encoding options options Value specific to type of codec
Description:
Used to call codecs to encode datatypes into binary data (bytes).
Codecs are identified by words that symbolize their types. For example the word png is used to identify the PNG codec.
See the system/codecs for a list of loaded codecs. Codecs can be native (built-in), externally loaded, or even coded in REBOL.
Examples
The line:
save %photo.bmp imageIs roughly equivalent to:
data: encode 'bmp image
write %photo.bmp dataENCODING?¶
Returns the media codec name for given binary data. (identify)
Usage:
encoding?
ARGUMENTS: data [binary!]
Description:
>> encoding? read %test.wav
== wav
>> encoding? read %test.png
== pngENHEX¶
Converts string into URL-style hex encodeding (%xx) when needed.
Usage:
enhex
ARGUMENTS: value [any-string! binary!] The string to encode REFINEMENTS: /escape Can be used to change the default escape char #"%" char [char!] /except Can be used to specify, which chars can be left unescaped unescaped [bitset!] By default it is URI bitset when value is file or url, else URI-Component /uri Encode space using a special char (#"+" by default or #"_" when escape char is #"=")
Description:
>> enhex "a b"
== "a%20b"
>> enhex/uri "a b"
== "a+b"
>> enhex/escape "a b" #"#"
== "a#20b"ENLINE¶
Converts string terminators to native OS format, e.g. LF to CRLF.
Usage:
enline
ARGUMENTS: series [any-string! block!] (modified)
Description:
Basic example:
enline "a^/b"
"a^/M^/b"To convert from any string termination format to, use enline after the deline function:
enline deline "a^Mb"
"a^/M^/b"See deline for more information about string termination formats.
ENTAB¶
Converts spaces to tabs (default tab size is 4).
Usage:
entab
ARGUMENTS: string [any-string!] (modified) REFINEMENTS: /size Specifies the number of spaces per tab number [integer!]
Description:
The REBOL language default tab-size is four spaces. Use the /size refinement for other sizes such as eight. entab will only place tabs at the beginning of the line (prior to the first non-space character).
The series passed to this function is modified as a result.
text: {
no
tabs
in
this
sentence
}
remove head remove back tail text
probe text
{ no
tabs
in
this
sentence}
probe entab copy text
{^-no
tabs
in
this
sentence}
print entab copy text
no
tabs
in
this
sentence
probe entab/size copy text 2
{^-^-no
^- tabs
^- in
^- this
^- sentence}
print entab/size copy text 2
no
tabs
in
this
sentenceThe opposite function is detab which converts tabs back to spaces:
probe entab text
{^-no
tabs
in
this
sentence}
probe detab text
{ no
tabs
in
this
sentence}ENUM¶
Creates enumeration object from given specification
Usage:
enum
ARGUMENTS: spec [block!] Specification with names and values. title [string! word!] Enumeration name
EQUAL?¶
Returns TRUE if the values are equal.
Usage:
equal?
ARGUMENTS: value1 [any-type!] value2 [any-type!]
Description:
String-based datatypes are considered equal when they are identical or differ only by character casing (uppercase = lowercase). Use == or find/match/case to compare strings by casing.
print equal? 123 123
true
print equal? "abc" "abc"
true
print equal? [1 2 3] [1 2 4]
false
print equal? 12-june-1998 12-june-1999
false
print equal? 1.2.3.4 1.2.3.0
false
print equal? 1:23 1:23
trueEQUIV?¶
Returns TRUE if the values are equivalent.
Usage:
equiv?
ARGUMENTS: value1 [any-type!] value2 [any-type!]
ERROR?¶
Returns TRUE if it is this type.
Usage:
error?
ARGUMENTS: value [any-type!]
Description:
Returns false for all other values. This is useful for determining if a try function returned an error.
if error? try [1 + "x"][
print "Did not work."
]
Did not work.EVEN?¶
Returns TRUE if the number is even.
Usage:
even?
ARGUMENTS: number [number! char! date! money! time! pair!]
Description:
Returns true only if the argument is an even integer value. If the argument is a decimal, only its integer portion is examined.
>> even? 100
== #(true)
>> even? 7
== #(false)EVENT?¶
Returns TRUE if it is this type.
Usage:
event?
ARGUMENTS: value [any-type!]
Description:
Returns true if the value is an event datatype.
EVOKE¶
Special guru meditations. (Not for beginners.)
Usage:
evoke
ARGUMENTS: chant [word! block! integer!] Single or block of words ('? to list)
Description:
This is useful for analyzing hard REBOL crashes that lead to assertion errors and other crashes that aren't related to your script errors, but directly exposes bugs in the REBOL kernel. This is helpful information for REBOL Technologies to fix these bugs.
To enable this kind of analysis, have this at the beginning of your program:
secure [debug allow]
evoke 'crash-dumpIf REBOL crashes, you will get a stack dump. You can force a crash using:
evoke 'crash--REBOL Kernel Dump--
Evaluator:
Cycles: 50001
Counter: 8027
Dose: 10000
Signals: #00000000
Sigmask: #FFFFFFFF
DSP: 5
DSF: 1
Memory/GC:
Ballast: 2998784
Disable: 1
Protect: 1
Infants: 3
STACK[5] evoke[1] native!
chant: crashSpecial Notes
Common for all operations with evoke is that debugging must be allowed using:
secure [debug allow]evoke also allows other debug output, mostly used internally by REBOL Technologies to help test REBOL 3.
The function can also be used to monitor the garbage collector:
evoke 'watch-recycleor to monitor object copying:
evoke 'watch-obj-copyor to set the stack size:
evoke 'stack-size 2000000or to debug delect information:
evoke 'delectEXCLUDE¶
Returns the first data set less the second data set.
Usage:
exclude
ARGUMENTS: set1 [block! string! bitset! typeset! map!] First data set set2 [block! string! bitset! typeset! map!] Second data set REFINEMENTS: /case Uses case-sensitive comparison /skip Treat the series as records of fixed size size [integer!]
Description:
Returns the elements of the first set less the elements of the second set. In other words, it removes from the first set all elements that are part of the second set.
lunch: [ham cheese bread carrot]
dinner: [ham salad carrot rice]
probe exclude lunch dinner
[cheese bread]
probe exclude [1 3 2 4] [3 5 4 6]
[1 2]
string1: "CBAD" ; A B C D scrambled
string2: "EDCF" ; C D E F scrambled
probe exclude string1 string2
"BA"
items: [1 1 2 3 2 4 5 1 2]
probe exclude items items ; get unique set
[]
str: "abcacbaabcca"
probe exclude str str
""Note that performing this function over very large data sets can be CPU intensive.
EXISTS?¶
Determines if a file or URL exists.
Usage:
exists?
ARGUMENTS: target [file! url!]
Description:
Returns false if the file does not exist.
print exists? %file.txt
false
print exists? %doc.r
falseEXIT¶
Exits a function, returning no value.
Usage:
exit
Description:
exit is used to return from a function without returning a value.
test-str: make function! [str] [
if not string? str [exit]
print str
]
test-str 10
test-str "right"Note: Use quit to exit the interpreter.
EXP¶
Raises E (the base of natural logarithm) to the power specified
Usage:
exp
ARGUMENTS: power [number!]
Description:
The exp function returns the exponential value of the argument provided.
print exp 3
20.08553692318766On overflow, an error is returned (which can be trapped with the try function). On underflow, a 0 is returned.
EXTEND¶
Extend an object, map, or block type with word and value pair.
Usage:
extend
ARGUMENTS: obj [object! map! block! paren!] object to extend (modified) word [any-word!] val
Description:
This function is useful to extend object!, map! or block! values using a word/value pair. It returns the input value. It performs no copy.
Examples:
a: [b: 1 c: 2]
extend a 'd 3
= 3
probe a
[b: 1 c: 2 d: 3]
a: make object! [b: 1 c: 2]
extend a 'd 3
3
probe a
make object! [
b: 1
c: 2
d: 3
]
a: make map! [b: 1 c: 2]
extend a 'd 3
3
probe a
make map! [
b: 1
c: 2
d: 3
]EXTRACT¶
Extracts a value from a series at regular intervals.
Usage:
extract
ARGUMENTS: series [series!] width [integer!] Size of each entry (the skip) REFINEMENTS: /index Extract from an offset position pos The position(s)
Description:
Returns a series of values from regularly spaced positions within a specified series. For example:
data: ["Dog" 10 "Cat" 15 "Fish" 20]
probe extract data 2
["Dog" "Cat" "Fish"]Essentially, extract lets you access a series as a record or "row" of a given length (specified by the width argument). The default, as shown above, extracts the first value. If you wanted to extract the second value (the second "column" of data):
data: ["Dog" 10 "Cat" 15 "Fish" 20]
probe extract/index data 2 2
[10 15 20]In the example below, the width of each row is three:
people: [
1 "Bob" "Smith"
2 "Cat" "Walker"
3 "Ted" "Jones"
]
block: extract people 3
probe block
[
1
2
3
]
block: extract/index people 3 2
probe block
["Bob" "Cat" "Ted"]Of course, extract works on any series, not just those that appear in a row format (such as that above). The example below creates a block containing every other word from a string:
str: "This is a given block here"
blk: parse str none
probe blk
["This" "is" "a" "given" "block" "here"]
probe extract blk 2
["This" "a" "block"]
probe extract/index blk 2 2
["is" "given" "here"]Here is an example that uses extract to obtain the names of all the predefined REBOL/View VID styles:
probe extract system/view/vid/vid-styles 2FIFTH¶
Returns the fifth value of a series.
Usage:
fifth
ARGUMENTS:
value
Description:
This is an ordinal.
See the first function for examples. If no value is found, none is returned.
print fifth "REBOL"
L
print fifth [11 22 33 44 55 66]
55FILE-CHECKSUM¶
Computes a checksum of a given file's content
Usage:
file-checksum
ARGUMENTS: file [file!] Using 256kB chunks method [word!] One of system/catalog/checksums
FILE?¶
Returns TRUE if it is this type.
Usage:
file?
ARGUMENTS: value [any-type!]
Description:
Returns false for all other values. Note that file? does not check for the existence of a file, but whether or not a value is the FILE! datatype.
print file? %file.txt
true
print file? "REBOL"
falseNote also this is not a direct opposite to the dir? function as dir? does not test against a datatype, where file? does.
FILE-TYPE?¶
Return the identifying word for a specific file type (or NONE).
Usage:
file-type?
ARGUMENTS: file [file! url!]
FILTER¶
PNG delta filter
Usage:
filter
ARGUMENTS: data [binary!] Input width [number!] Scanline width type [integer! word!] 1..4 or one of: [sub up average paeth] REFINEMENTS: /skip bpp [integer!] Bytes per pixel
FIND¶
Searches for a value; for series returns where found, else none.
Usage:
find
ARGUMENTS: series [series! gob! port! bitset! typeset! object! map! none!] value [any-type!] REFINEMENTS: /part Limits the search to a given length or position range [number! series! pair!] /only Treats a series value as only a single value /case Characters are case-sensitive /same Use "same?" as comparator /any Enables the * and ? wildcards /with Allows custom wildcards wild [string!] Specifies alternates for * and ? /skip Treat the series as records of fixed size size [integer!] /last Backwards from end of series /reverse Backwards from the current position /tail Returns the end of the series /match Performs comparison and returns the head of the match (not imply /tail)
Description:
Returns none! if the value was not found. Otherwise, returns a position in the series where the value was found. Many refinements to this function are available.
Use /tail to return the position just past the match.
Use /case to specify that the search should be case sensitive. Note that using find on a binary string will do a case-insensitive search.
The /match refinement can be used to perform a character by character match of the input value to the series. The position just past the match is returned.
Wildcards can be specified with /any.
The /only refinement applies to block values and is ignored for strings.
The /last refinement causes find to search from the tail of the series toward the head.
And, /reverse searches backwards from the current position toward the head.
probe find "here and now" "and"
"and now"
probe find/tail "here and now" "and"
" now"
probe find [12:30 123 c@d.com] 123
[123 c@d.com]
probe find [1 2 3 4] 5
none
probe find/match "here and now" "here"
" and now"
probe find/match "now and here" "here"
none
probe find [1 2 3 4 3 2 1] 2
[2 3 4 3 2 1]
probe find/last %file.fred.txt "."
%.txt
probe find/last [1 2 3 4 3 2 1] 2
[2 1]
probe find/any "here is a string" "s?r"
noneFIND-ALL¶
Find all occurrences of a value within a series (allows modification).
Usage:
find-all
ARGUMENTS: series [word!] Variable for block, string, or other series value body [block!] Evaluated for each occurrence
FIND-MAX¶
Returns the series where the largest value is found, or none if the series is empty.
Usage:
find-max
ARGUMENTS: series [series!] Series to search REFINEMENTS: /skip Treat the series as records of fixed size size [integer!]
FIND-MIN¶
Returns the series where the smallest value is found, or none if the series is empty.
Usage:
find-min
ARGUMENTS: series [series!] Series to search REFINEMENTS: /skip Treat the series as records of fixed size size [integer!]
FIND-SCRIPT¶
Find a script header within a binary string. Returns starting position.
Usage:
find-script
ARGUMENTS: script [binary!]
Description:
This is a high-speed lower level function to scan UTF-8 for a REBOL script signature, useful during loading of scripts and to ensure that scripts are proper UTF-8.
Editor note: Not sure about the description
FIRST¶
Returns the first value of a series.
Usage:
first
ARGUMENTS:
value
Description:
This is an ordinal. It returns the first value in any type of series at the current position. If no value is found, none is returned.
print first "REBOL"
R
print first [11 22 33 44 55 66]
11
print first 1:30
1
print first 199.4.80.1
199
print first 12:34:56.78
12FIRST+¶
Return the FIRST of a series then increment the series index.
Usage:
first+
ARGUMENTS: word [word!] Word must refer to a series
Description:
Example:
blk: [a b c]
first+ blk
a
first+ blk
b
first+ blk
c
first+ blk
noneFLUSH¶
Flush output stream buffer.
Usage:
flush
ARGUMENTS: port [port!]
FOR¶
Evaluate a block over a range of values. (See also: REPEAT)
Usage:
for
ARGUMENTS: word [word!] Variable to hold current value start [series! number! pair!] Starting value end [series! number! pair!] Ending value bump [number! pair!] Amount to skip each time body [block!] Block to evaluate
Description:
The first argument is used as a local variable to keep track of the current value. It is initially set to the START value and after each evaluation of the block the BUMP value is added to it until the END value is reached (inclusive).
for num 0 30 10 [ print num ]
30
for num 4 -37 -15 [ print num ]
-26FORALL¶
Evaluates a block for every value in a series.
Usage:
forall
ARGUMENTS: word [word!] Word that refers to the series, set to each position in series body [block!] Block to evaluate each time
Description:
The forall function moves through a series one value at a time.
The word argument is a variable that moves through the series. Prior to evaluation, the word argument must be set to the desired starting position within the series (normally the head, but any position is valid). After each evaluation of the block, the word will be advanced to the next position within the series.
cities: ["Eureka" "Ukiah" "Santa Rosa" "Mendocino"]
forall cities [print first cities]
Eureka
Ukiah
Santa Rosa
Mendocino
chars: "abcdef"
forall chars [print first chars]
a
b
c
d
e
fWhen forall finishes the word is reset to the starting position of the series.
chars: next "abcdef"
"bcdef"
forall chars []
chars
"bcdef"The result of forall is the result of the last expression of the block:
chars: "abcdef"
forall chars [first chars]
#"f"Or the result of a break/return from the block:
chars: "abcdef"
forall chars [break/return 5]
5The forall function can be thought of as a shortcut for:
[
original: series
while [not tail? series] [
x: (your code)
series: next series
]
series: original
:x
]FOREACH¶
Evaluates a block for each value(s) in a series.
Usage:
foreach
ARGUMENTS: word [word! block!] Word or block of words to set each time (local) data [series! any-object! map! none!] The series to traverse body [block!] Block to evaluate each time
Description:
The foreach function repeats the evaluation of a block for each element of a series. It is used often in programs.
Example:
values: [11 22 33]
foreach value values [print value]
11
22
33Another example that prints each word in a block along with its value:
colors: [red green blue]
foreach color colors [print [color get color]]
red 255.0.0
green 0.255.0
blue 0.0.255If the series is a string, each character will be fetched:
string: "REBOL"
foreach char string [print char]
R
E
B
O
LThis example will print each filename from a directory block:
files: read %.
foreach file files [
if find file ".t" [print file]
]
file.txt
file2.txt
newfile.txt
output.txtMultiple Elements
When a block contains groups of values that are related, foreach function can fetch all elements 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 ["watch" title "at" time "for" price]
]
watch Contact at 8:30 for $4.95
watch Ghostbusters at 10:15 for $3.25
watch Matrix at 12:45 for $4.25In 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.
Series Reference
To reference the series itself during foreach you can use a set-word! within the variable block. This operation is similar to the forall and forskip functions.
Example:
foreach [v1: v2] [1 2 3] [?? [v1 v2]]
v1: [1 2 3] v2: 1
v1: [2 3] v2: 2
v1: [3] v2: 3Notice that the v1 set-word does not affect the index position.
If you are using this option to remove values, please see the remove-each function which is many times faster for large series.
Foreach of Objects and Maps
The foreach function can also be used with object! and map! datatypes.
When using a single word argument, foreach will obtain the object field name or map key.
fruits: make object! [apple: 10 orange: 12 banana: 30]
foreach field fruits [print field]
apple
orange
bananaNote that each word is bound back to the object, and can be used to access the field value with get and set.
If a second word argument is provided, it will obtain the value of each entry:
foreach [field value] fruits [print [field value]]
apple 10
orange 12
banana 30The same behavior applies to the map! datatype, except that empty keys (those set to none) will be skipped.
When a set-word! is used in the variables block, it will obtain the object value itself.
FOREVER¶
Evaluates a block endlessly.
Usage:
forever
ARGUMENTS: body [block!] Block to evaluate each time
Description:
Evaluates a block continuously, or until a break or error condition is met.
forever [
if (random 10) > 5 [break]
]FORM¶
Converts a value to a human-readable string.
Usage:
form
ARGUMENTS: value [any-type!] The value to form
Description:
The form function converts a value to a human readable string. It is commonly used by print for output.
form 1234
"1234"
form 10:30
"10:30"
form %image.jpg
"image.jpg"When given a block of values, spaces are inserted between each values (except after a newline).
form [1 2 3]
"1 2 3"To avoid the spaces between values use ajoin, join, or rejoin.
The reform function combines reduce with form to evaluate values:
reform [1 + 2 3 + 4]
"3 7"To produce REBOL-readable output, use the mold function.
FORM-OID¶
Return the x.y.z.... style numeric string for the given OID
Usage:
form-oid
ARGUMENTS: oid [binary!]
FORMAT¶
Format a string according to the format dialect.
Usage:
format
ARGUMENTS: rules A block in the format dialect. E.g. [10 -10 #"-" 4 $32 "green" $0] values REFINEMENTS: /pad p Pattern to use instead of spaces
Description:
This is useful for table output in the console, where fixed-width fonts are used. It can also be used to specially format numbers or complex values.
The first input, is the dialect. It's a combination of positive or negative formatting integers and strings or chars, that are to be inserted between the integers.
A positive integer N, means the value will be left adjusted with N chars for space.
A negative integer N, means the value will be right adjusted with N chars for space.
In both cases, a value that takes up more space than N, is truncated to N chars.
The second input is the values, either as a block or as a single value.
Example:
format [-3 -3 -4] [1 2 3]
" 1 2 3"Format a time value using /pad to add zeroes:
format/pad [-2 ":" -2 ":" -2] [12 47 9] 0
"12:47:09"It can also be used to pad zeroes to a single numeric value:
format/pad [-8] 5125 0
"00005125"FORMAT-DATE-TIME¶
replaces a subset of ISO 8601 abbreviations such as yyyy-MM-dd hh:mm:ss
Usage:
format-date-time
ARGUMENTS: value [date! time!] rule [string! tag!]
FORMAT-TIME¶
Convert a time value to a human readable string
Usage:
format-time
ARGUMENTS: time [time!]
FORSKIP¶
Evaluates a block for periodic values in a series.
Usage:
forskip
ARGUMENTS: word [word!] Word that refers to the series, set to each position in series size [integer! decimal!] Number of positions to skip each time body [block!] Block to evaluate each time
Description:
Prior to evaluation, the word must be set to the desired starting position within the series (normally the head, but any position is valid). After each evaluation of the block, the word's position in the series is changed by skipping the number of values specified by the second argument (see the skip function).
areacodes: [
"Ukiah" 707
"San Francisco" 415
"Sacramento" 916
]
forskip areacodes 2 [
print [ first areacodes "area code is" second areacodes]
]
Sacramento area code is 916FOURTH¶
Returns the fourth value of a series.
Usage:
fourth
ARGUMENTS:
value
Description:
This is an ordinal.
See the first function for examples. If no value is found, none is returned.
print fourth "REBOL"
O
print fourth [11 22 33 44 55 66]
44
print fourth 199.4.80.1
1FRACTION¶
Returns the fractional part of a decimal value
Usage:
fraction
ARGUMENTS: number [decimal!]
FRAME?¶
Returns TRUE if it is this type.
Usage:
frame?
ARGUMENTS: value [any-type!]
FUNC¶
Defines a user function with given spec and body.
Usage:
func
ARGUMENTS: spec [block!] Help string (opt) followed by arg words (and opt type and string) body [block!] The body block of the function
Description:
The func function creates new functions from a spec block and a body block.
General form:
name: func [spec] [body]The spec block specifies the interface to the function. It can begin with an optional title string which used by the help function. That is followed by words that specify the arguments to the function. Each of argument can include an optional block of datatypes to specify the valid datatypes for the argument. Each may be followed by a comment string which describes the argument in more detail.
The argument words may also specify a few variations on the way the argument will be evaluated. The most common is 'word which indicates that a word is expected that should not be evaluated (the function wants its name, not its value). A :word may also be given which will get the value of the argument, but not perform full evaluation.
To add refinements to a function supply a slash (/) in front of an argument's word. Within the function the refinement can be tested to determine if the refinement was present. If a refinement is followed by more arguments, they will be associated with that refinement and are only evaluated when the refinement is present.
Local variables are specified after a /local refinement.
A function returns the last expression it evaluated. You can also use return and exit to exit the function. A return is given a value to return. exit returns no value.
sum: func [a b] [a + b]
print sum 123 321
444
sum: func [nums [block!] /average /local total] [
total: 0
foreach num nums [total: total + num]
either average [total / (length? nums)][total]
]
print sum [123 321 456 800]
print sum/average [123 321 456 800]
425
print-word: func ['word] [print form word]
print-word testing
testingFUNCO¶
Non-copying function constructor (optimized for boot).
Usage:
funco
ARGUMENTS: spec [block!] Help string (opt) followed by arg words (and opt type and string) body [block!] The body block of the function
Description:
Similar to func, except the spec or body is not copied.
FUNCT¶
Defines a function with all set-words as locals.
Usage:
funct
ARGUMENTS: spec [block!] Help string (opt) followed by arg words (and opt type and string) body [block!] The body block of the function REFINEMENTS: /with Define or use a persistent object (self) object [any-object! block! map!] The object or spec /extern words [block!] These words are not local
Description:
This is similar to func, except all set-words are assumed locals. This way, it's not necessary to specify the /local part of the spec, although you still can.
Example:
f: funct [a] [
b: a
]
f 7
7
b
** Script error: b has no valueIf you still desire to create non-local values in the function, use set to set words:
f: funct [a] [
b: a
set 'c b / 2
]
f 7
3.5
c
3.5If c still needs to be local, you can add the local refinement:
unset 'c ; make sure it's not set
f: funct [a /local c] [
b: a
set 'c b / 2
]
f 7
3.5
c
** Script error: c has no valueFUNCTION¶
Defines a function with all set-words as locals.
Usage:
function
ARGUMENTS: spec [block!] Help string (opt) followed by arg words (and opt type and string) body [block!] The body block of the function REFINEMENTS: /with Define or use a persistent object (self) object [any-object! block! map!] The object or spec /extern words [block!] These words are not local
Description:
This is similar to func, except all set-words are assumed locals. This way, it's not necessary to specify the /local part of the spec, although you still can.
Example:
average: function [block] [
total: 0
foreach number block [total: number + total]
total / (length? block)
]
print average [1 10 12.34]
7.78
total
** Script error: total has no valueIf you still desire to create non-local values in the function, use set to set words:
f: function [a] [
b: a
set 'c b / 2
]
f 7
3.5
c
3.5If c still needs to be local, you can add the local refinement:
unset 'c ; make sure it's not set
f: function [a /local c] [
b: a
set 'c b / 2
]
f 7
3.5
c
** Script error: c has no valueFUNCTION?¶
Returns TRUE if it is this type.
Usage:
function?
ARGUMENTS: value [any-type!]
Description:
Returns false for all other values.
print function? :func
true
print function? "test"
falseGCD¶
Returns the greatest common divisor
Usage:
gcd
ARGUMENTS: a [integer!] b [integer!]
GENERATE¶
Generate specified cryptographic key
Usage:
generate
ARGUMENTS: type [word!] Key type: system/catalog/elliptic-curves
GET¶
Gets the value of a word or path, or values of an object.
Usage:
get
ARGUMENTS: word Word, path, object to get REFINEMENTS: /any Allows word to have no value (allows unset)
Description:
The argument to get must be a word, so the argument must be quoted or extracted from a block. To get the value of a word residing in an object, use the in function.
value: 123
print get 'value
123
print get second [the value here]
123
print get in system/console 'prompt
>>If the argument to get is an object, the result is the same as that of values-of.
GET-ENV¶
Returns the value of an OS environment variable (for current process).
Usage:
get-env
ARGUMENTS: var [any-string! any-word!]
Description:
This function will return the string associated with an OS environment variable.
probe get-env "COMPUTERNAME"
"BIGBOY"To obtain a list of all environment variables and their values, use list-env.
GET-PATH?¶
Returns TRUE if it is this type.
Usage:
get-path?
ARGUMENTS: value [any-type!]
Description:
Returns false for all other values.
get-path? to-get-path 'path/to/somewhere
trueGET-WORD?¶
Returns TRUE if it is this type.
Usage:
get-word?
ARGUMENTS: value [any-type!]
Description:
Returns false for all other values.
print get-word? second [pr: :print]
trueGOB?¶
Returns TRUE if it is this type.
Usage:
gob?
ARGUMENTS: value [any-type!]
Description:
Returns false for all other values.
gob? make gob! [text: "this is a gob!"]
trueGREATER-OR-EQUAL?¶
Returns TRUE if the first value is greater than or equal to the second value.
Usage:
greater-or-equal?
ARGUMENTS:
value1
value2
Description:
Returns false for all other values. Both values must be of the same datatype or an error will occur. For string-based datatypes, the sorting order is used for comparison with character casing ignored (uppercase = lowercase).
print greater-or-equal? "abc" "abb"
true
print greater-or-equal? 16-June-1999 12-june-1999
true
print greater-or-equal? 1.2.3.4 4.3.2.1
false
print greater-or-equal? 1:00 11:00
falseGREATER?¶
Returns TRUE if the first value is greater than the second value.
Usage:
greater?
ARGUMENTS:
value1
value2
Description:
Returns false for all other values. The values must be of the same datatype or an error will occur. For string-based datatypes, the sorting order is used for comparison with character casing ignored (uppercase = lowercase).
print greater? "abc" "abb"
true
print greater? 16-June-1999 12-june-1999
true
print greater? 4.3.2.1 1.2.3.4
true
print greater? 11:00 12:00
falseGUI-METRIC¶
Returns specific gui related metric setting.
Usage:
gui-metric
ARGUMENTS: keyword [word!] Available keywords: SCREENS, BORDER-FIXED, BORDER-SIZE, SCREEN-DPI, LOG-SIZE, PHYS-SIZE, SCREEN-SIZE, VIRTUAL-SCREEN-SIZE, TITLE-SIZE, WINDOW-MIN-SIZE, WORK-ORIGIN and WORK-SIZE. REFINEMENTS: /set val Value used to set specific setting(works only on 'writable' keywords). /display idx [integer!] Display index, starting with 0
HALT¶
Stops evaluation and returns to the input prompt.
Usage:
halt
Description:
Useful for program debugging.
div: 10
if error? try [100 / div] [
print "math error"
halt
]HANDLE-EVENTS¶
Adds a handler to the view event system.
Usage:
handle-events
ARGUMENTS: handler [block!]
Description:
This is used internally in the view function.
HANDLE?¶
Returns TRUE if it is this type.
Usage:
handle?
ARGUMENTS: value [any-type!]
Description:
Returns false for all other values.
Editor note: Need example.
HANDLED-EVENTS?¶
Returns event handler object matching a given name.
Usage:
handled-events?
ARGUMENTS:
name
HAS¶
A shortcut to define a function that has local variables but no arguments.
Usage:
has
ARGUMENTS: vars [block!] List of words that are local to the function body [block!] The body block of the function
Description:
Defines a function that consists of local variables only. This is a shortcut for func and function.
For example:
ask-name: has [name] [
name: ask "What is your name?"
print ["Hello" name]
]
ask-name
Hello LukeThe example above is a shortcut for:
ask-name: func [/local name] [...]HASH¶
Computes a hash value from any Rebol value. This number may change between different Rebol versions!
Usage:
hash
ARGUMENTS: value [any-type!]
HASH?¶
Returns TRUE if it is this type.
Usage:
hash?
ARGUMENTS: value [any-type!]
HEAD¶
Returns the series at its beginning.
Usage:
head
ARGUMENTS: series [series! gob! port!]
Description:
The insert function returns at the current string position, so head adjusts the index back to the head:
str: "all things"
print head insert str "with "
with all thingsNow here is not at the head:
here: find str "all"
print here
all thingsNow we print at the head:
print head here
with all thingsHEAD?¶
Returns TRUE if a series is at its beginning.
Usage:
head?
ARGUMENTS: series [series! gob! port!]
Description:
cds: [
"Rockin' REBOLs"
"Carl's Addiction"
"Jumpin' Jim"
]
print head? cds
true
cds: tail cds
print head? cds
false
until [
cds: back cds
print first cds
head? cds
]
Rockin' REBOLsHELP¶
Prints information about words and values
Usage:
help
ARGUMENTS: word [any-type!] REFINEMENTS: /doc Open web browser to related documentation /into Help text will be inserted into provided string instead of printed string [string!] Returned series will be past the insertion
Description:
The help function provides information about words and values.
Type help or ? at the console prompt to view a summary of help:
>> help
Use HELP or ? to see built-in info:
help insert
? insert
To search within the system, use quotes:
? "insert"
To browse online web documents:
help/doc insert
To view words and values of a context or object:
? lib - the runtime library
? self - your user context
? system - the system object
? system/options - special settings
To see all words of a specific datatype:
? native!
? function!
? datatype!
To see all available codecs:
? codecs
Other debug functions:
?? - display a variable and its value
probe - print a value (molded)
source - show source code of func
trace - trace evaluation steps
what - show a list of known functions
Other information:
about - see general product info
license - show user license
usage - program cmd line options
Help about a Function
If you provide a function word as an argument, help prints all of the information related to that function.
For example:
>> help insertUSAGE:
INSERT series value
DESCRIPTION:
Inserts element(s); for series, returns just past the insert.
INSERT is an action! value.
ARGUMENTS:
series [series! port! map! gob! object! bitset!] At position (modified).
value [any-type!] The value to insert.
REFINEMENTS:
/part Limits to a given length or position
range [number! series! pair!]
/only Only insert a block as a single value (not the contents of the block)
/dup Duplicates the insert a specified number of times
count [number! pair!]
For more detailed information, you can use the doc refinement:
>> help/doc insertto open the web browser to the page related to that function.
Help about Datatypes
All datatypes are explained through help.
To obtain a list of all REBOL datatypes, type:
>> ? datatype!DATATYPE! is a datatype.
It is defined as a type of datatype.
It is of the general type symbol.
Found these related words:
end! datatype! internal marker for end of block
unset! datatype! no value returned or set
none! datatype! no value represented
logic! datatype! boolean true or false
integer! datatype! 64 bit integer
decimal! datatype! 64bit floating point number (IEEE standard)
percent! datatype! special form of decimals (used mainly for layout)
money! datatype! high precision decimals with denomination (opt)
char! datatype! 8bit and 16bit character
pair! datatype! two dimensional point or size
tuple! datatype! sequence of small integers (colors, versions, IP)
time! datatype! time of day or duration
date! datatype! day, month, year, time of day, and timezone
binary! datatype! string series of bytes
string! datatype! string series of characters
file! datatype! file name or path
email! datatype! email address
ref! datatype! reference
url! datatype! uniform resource locator or identifier
tag! datatype! markup string (HTML or XML)
bitset! datatype! set of bit flags
image! datatype! RGB image with alpha channel
vector! datatype! high performance arrays (single datatype)
block! datatype! series of values
paren! datatype! automatically evaluating block
path! datatype! refinements to functions, objects, files
set-path! datatype! definition of a path's value
get-path! datatype! the value of a path
lit-path! datatype! literal path value
hash! datatype! series of values (using hash table)
map! datatype! name-value pairs (hash associative)
datatype! datatype! type of datatype
typeset! datatype! set of datatypes
word! datatype! word (symbol or variable)
set-word! datatype! definition of a word's value
get-word! datatype! the value of a word (variable)
lit-word! datatype! literal word value
refinement! datatype! variation of meaning or location
issue! datatype! identifying marker word
native! datatype! direct CPU evaluated function
action! datatype! datatype native function (standard polymorphic)
rebcode! datatype! virtual machine function
command! datatype! special dispatch-based function
op! datatype! infix operator (special evaluation exception)
closure! datatype! function with persistent locals (indefinite extent)
function! datatype! interpreted function (user-defined or mezzanine)
frame! datatype! internal context frame
object! datatype! context of names with values
module! datatype! loadable context of code and data
error! datatype! errors and throws
task! datatype! evaluation environment
port! datatype! external series, an I/O channel
gob! datatype! graphical object
event! datatype! user interface event (efficiently sized)
handle! datatype! arbitrary internal object or value
struct! datatype! native structure definition
library! datatype! external library reference
utype! datatype! user defined datatype
For help on a specific datatype:
>> help integer!INTEGER! is a datatype.
It is defined as a 64 bit integer.
It is of the general type scalar.
Found these related words:
zero integer! 0
To list all words that are function! datatypes, type:
>> ? function!and the result would be:
Found these related words:
? function! Prints information about words and values.
?? function! Debug print a word, path, or block of such, f...
about function! Information about REBOL
alter function! If a value is not found in a series, append i...
any-block? function! Return TRUE if value is any type of block.
any-function? function! Return TRUE if value is any type of function.
any-object? function! Return TRUE if value is any type of object.
any-path? function! Return TRUE if value is any type of path.
any-string? function! Return TRUE if value is any type of string.
any-word? function! Return TRUE if value is any type of word.
array function! Makes and initializes a series of a given siz...
as-pair function! Combine X and Y values into a pair.
ask function! Ask the user for input.
...Help Search
The help function also finds words that contain a specified string. For example, to find all of the words that include the string path!, type:
>> ? "path"and the result will be:
Found these related words:
?? function! Debug print a word, path, or block of such, f...
any-path! typeset! [path! set-path! get-path! lit-path!]
any-path? function! Return TRUE if value is any type of path.
assert native! Assert that condition is true, else throw an ...
cd function! Change directory (shell shortcut function).
change-dir native! Changes the current directory path.
clean-path function! Returns new directory path with //, . and .. ...
dirize function! Returns a copy of the path turned into a dire...
file! datatype! file name or path
...Help on Objects
If you use help on an object, it will list a summary of the object's fields.
>> ? systemSYSTEM is an object of value:
product word! Bulk
platform word! Windows
version tuple! 3.18.3
build object! [os os-version abi sys arch libc vendor target compiler date git]
user object! [name data]
options object! [boot path home data modules flags script args do-arg import debug secure version boot-level quiet binary-base decimal-digits ...
catalog object! [datatypes actions natives handles errors reflectors boot-flags bitsets checksums compressions elliptic-curves ciphers event-t...
contexts object! [root sys lib user]
state object! [note last-error last-result wait-list]
modules object! [help blend2d blurhash easing mathpresso miniaudio sqlite triangulate webp github httpd prebol scheduler soundex spotify thru-...
codecs object! [text markup qoi pkix der crt ppk ssh-key safe utc-time unixtime ar gzip zip tar json dng jpegxr dds tiff gif bmp jpeg png wav]
dialects object! [secure draw effect text rebcode]
schemes object! [system console callback file dir event dns tcp udp checksum crypt clipboard serial audio midi safe tls smtp smtps http https ...
ports object! [system event input output echo mail callback]
locale object! [language language* locale locale* months days]
script object! [title header parent path args]
standard object! [codec enum error script header scheme port port-spec-head port-spec-file port-spec-net port-spec-checksum port-spec-crypt por...
view object! [screen-gob handler metrics]
license string! {^[[0m╔══════════════════════════════════════════════════════════════════════════╗^/║^[[30;107m ...
Help on Errors
There is a special mechanism for getting help on errors.
When you get an error message at the console, you can type why? to see info about that specific error.
For example:
>> test
** Script error: test has no value
>> why?
Opening web browser...and, this page, no-value, would be displayed.
See why? for more about this function.
HSV-TO-RGB¶
Converts HSV (hue, saturation, value) to RGB
Usage:
hsv-to-rgb
ARGUMENTS: hsv [tuple!]
ICONV¶
Convert binary to text using specified codepage, or transcode to a new binary
Usage:
iconv
ARGUMENTS: data [binary!] codepage [word! integer! tag! string!] Source codepage id REFINEMENTS: /to Transcode to a new binary target [word! integer! tag! string!] Target codepage id
IF¶
If TRUE condition, return arg; evaluate blocks by default.
Usage:
if
ARGUMENTS: condition [any-type!] true-branch REFINEMENTS: /only Return block arg instead of evaluating it.
Description:
The if function will evaluate the block when its first argument is true.
True is defined to be any value that is not false or none.
if 2 > 1 [print "that's true"]
that's trueThe condition can be the result of several expressions within any or and, or any other function that produces a result:
if all [
time > 10:20
age > 20
find users "bob"
] [print "that's true"]
that's trueIn addition, it can be pointed out that the block can be in a variable also:
blk: [print "that's true"]
if 2 > 1 blk
that's trueReturn Value
When the condition is true, the if function returns the value that is the result of evaluating the block. Otherwise, it returns none. This is a useful feature.
For example:
print if 2 > 1 [1 + 2]
3
print if 1 > 2 [1 + 2]
none
names: ["Carl" "Brian" "Steve"]
print if find names "Carl" ["Person found"]
Person foundWhere's the Else?
Unlike most other languages, REBOL uses functions, not commands to evaluate all expressions. Therefore, it's not desirable to use the word else if you need that behavior. Instead, use the either function:
either 2 > 1 [print "greater"] [print "not greater"]
greater
either 1 > 2 [print "greater"] [print "not greater"]
not greaterSimplification
The above example is pretty common, but it should be noted that it can be easily refactored:
either 2 > 1 [print "greater"] [print "not greater"]is better written as:
print either 2 > 1 ["greater"] ["not greater"]or even better written as:
print pick ["greater" "not greater"] 2 > 1The importance of this is that you're picking from a choice of two strings, and you're doing it here with one less block than the code above it.
Be careful with this last method. The pick function only allows true and false, not none. See either for more details.
In addition, it should be noted that the any function used earlier didn't really require the if at all. It could have been written as:
all [
time > 10:20
age > 20
find users "bob"
print "that's true"
]A Common Error
A common error is to use if and add an "else" block without using the either function. The extra block gets ignored:
n: 0
if 1 > 2 [n: 1] [n: 2]
print n
0The second block is ignored in this case and not evaluated.
The code should have used the either function:
n: 0
either 1 > 2 [n: 1] [n: 2]
print n
2The /Else refinement is obsolete
The /Else refinement is obsolete and will be removed in future versions. Avoid it.
IMAGE¶
Interface to basic image encoding/decoding (only on Windows and macOS so far!)
Usage:
image
REFINEMENTS: /load Image file to load or binary to decode src-file [file! binary!] /save Encodes image to file or binary dst-file [none! file! binary!] If NONE is used, binary is made internally dst-image [none! image!] If NONE, loaded image may be used if there is any /frame Some image formats may contain multiple images num [integer!] 1-based index of the image to receive /as Used to define which codec should be used type [word!] One of: [PNG JPEG JPEGXR BMP DDS GIF TIFF] read only: [DNG ICO HEIF]
IMAGE-DIFF¶
Count difference (using weighted RGB distance) of two images of the same size. Returns 0% if images are same and 100% if completely different.
Usage:
image-diff
ARGUMENTS: a [image!] If sizes of the input images are not same... b [image!] ... then only the smaller part is compared! REFINEMENTS: /part Limit computation only to a part of the image offset [pair!] Zero based top-left corner size [pair!] Size of the sub-image to use
IMAGE?¶
Returns TRUE if it is this type.
Usage:
image?
ARGUMENTS: value [any-type!]
Description:
Returns true if the value is an image! datatype.
This function is often used after the load function to verify that the data is in fact an image. For example:
img: load %test-image.png
if not image? img [alert "Not an image file!"]IMPORT¶
Imports a module; locate, load, make, and setup its bindings.
Usage:
import
ARGUMENTS: module [any-word! file! url! string! binary! module! block!] REFINEMENTS: /version ver [tuple!] Module must be this version or greater /check sum [binary!] Match checksum (must be set in header) /no-share Force module to use its own non-shared global namespace /no-lib Don't export to the runtime library (lib) /no-user Don't export to the user context
Description:
The import function is used to import modules into your runtime environment. For a full description see the modules: loading modules section of this documentation.
For example, you can write:
import 'mysqland the system will search for the mysql module.
You can also use a filename or URL for the module identifier:
import %mysql.r
import http://www.rebol.com/mods/mysql.rWhen successful, the import function returns a module! datatype as its result.
This allows you to write:
mysql: import 'mysqlNow, the mysql variable can be used to refer to values within the mysql module.
For example the module value is used here to reference a function:
mysql/open-db %my-database.sqlSee below for more.
Like the header needs field, the import function also lets you specify a version and a checksum.
These are all supported:
import/version mysql 1.2.3
import/check mysql #{A94A8FE5CCB19BA61C4C0873D391E987982FBBD3}
import/version/check mysql 1.2.3 #{A94A8FE5CCB19BA61C4C0873D391E987982FBBD3}The benefit of using the import function compared to the needs header field is that the arguments can be variables.
A basic example is:
mod: 'mysql
import modOr, something like:
mod-list: [
mysql 1.2.3
db-gui 2.4.5
http-server 1.0.1
]
foreach [id ver] mod-list [
import/version id ver
]IN¶
Returns the word or block in the object's context.
Usage:
in
ARGUMENTS: object [any-object! block!] word [any-word! block! paren!] (modified if series)
Description:
Return the word from within another context. This function is normally used with set and get.
set-console: func ['word value] [
set in system/console word value
]
set-console prompt "==>"
set-console result "-->"This is a useful function for accessing the words and values of an object. The in function will obtain a word from an object's context. For example, if you create an object:
example: make object! [ name: "fred" age: 24 ]You can access the object's name and age fields with:
print example/name
print example/age
24But you can also access them with:
print get in example 'name
print get in example 'age
24The in function returns the name and age words as they are within the example object. If you type:
print in example 'name
nameThe result will be the word name, but with a value as it exists in the example object. The get function then fetches their values. This is the best way to obtain a value from an object, regardless of its datatype (such as in the case of a function).
A set can also be used:
print set in example 'name "Bob"
BobUsing in, here is a way to print the values of all the fields of an object:
foreach word words-of example [
probe get in example word
]
24Here is another example that sets all the values of an object to none:
foreach word words-of example [
set in example word none
]The in function can also be used to quickly check for the existence of a word within an object:
if in example 'name [print example/name]
none
if in example 'address [print example/address]This is useful for objects that have optional variables.
Advanced binding uses
In R3, in can also be used for binding a block to an object to support this useful idiom:
do in example [age + 1]
25Identically, a paren! can be used as the rebound block:
do in example second [(age + 1) (age + 20)]
44IN-DIR¶
Evaluate a block while in a directory.
Usage:
in-dir
ARGUMENTS: dir [file!] Directory to change to (changed back after) block [block!] Block to evaluate
Description:
This is useful if you need to temporarily switch to a different directory to do something, and then switch back without manually doing so.
Example:
in-dir %tmp-dir/ [tmp-files: read %.]INDEX?¶
Returns the current position (index) of the series.
Usage:
index?
ARGUMENTS: series [series! gob! port! none!] REFINEMENTS: /xy Returns index as an XY pair offset
Description:
The index function returns the position within a series. For example, the first value in a series is an index of one, the second is an index of two, etc.
str: "with all things considered"
print index? str
1
print index? find str "things"
10
blk: [264 "Rebol Dr." "Calpella" CA 95418]
print index? find blk 95418
5Use the OFFSET? function when you need the index difference between two positions in a series.
INDEXZ?¶
Returns the current 0-based position (index) of the series.
Usage:
indexz?
ARGUMENTS: series [series! gob! port! none!] REFINEMENTS: /xy Returns index as an XY pair offset
INIT-WORDS¶
Usage:
init-words
ARGUMENTS: words [block!]
INPUT¶
Inputs a string from the console.
Usage:
input
REFINEMENTS:
/hide Turns off echoing inputs
Description:
Returns a string from the standard input device (normally the keyboard, but can also be a file or an interactive shell). The string does not include the new-line character used to terminate it.
The /HIDE refinement hides input with "*" characters.
prin "Enter a name: "
name: input
print [name "is" length? name "characters long"]
Luke is 4 characters longINSERT¶
Inserts element(s); for series, returns just past the insert.
Usage:
insert
ARGUMENTS: series [series! port! map! gob! object! bitset!] At position (modified) value [any-type!] The value to insert REFINEMENTS: /part Limits to a given length or position range [number! series! pair!] /only Only insert a block as a single value (not the contents of the block) /dup Duplicates the insert a specified number of times count [number! pair!]
Description:
If the value is a series compatible with the first (block or string-based datatype), then all of its values will be inserted. The series position just past the insert is returned, allowing multiple inserts to be cascaded together.
/part allows you to specify how many elements you want to insert.
/only will force a block to be insert, rather than its individual elements. (Is only done if first argument is a block datatype.)
/dup will cause the inserted series to be repeated a given number of times. (Positive integer or zero)
The series will be modified.
str: copy "here this"
insert str "now "
print str
now here this
insert tail str " message"
print str
now here this message
insert tail str reduce [tab now]
print str
now here this message 12-Feb-2009/17:47:52-8:00
insert insert str "Tom, " "Tina, "
print str
Tom, Tina, now here this message 12-Feb-2009/17:47:52-8:00
insert/dup str "." 7
print str
.......Tom, Tina, now here this message 12-Feb-2009/17:47:52-8:00
insert/part tail str next "!?$" 1
print str
.......Tom, Tina, now here this message 12-Feb-2009/17:47:52-8:00?
blk: copy ["hello"]
insert blk 'print
probe blk
[print "hello"]
insert tail blk http://www.rebol.com
probe blk
[print "hello" http://www.rebol.com]
insert/only blk [separate block]
probe blk
[[separate block] print "hello" http://www.rebol.com]INTEGER?¶
Returns TRUE if it is this type.
Usage:
integer?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values.
print integer? -1234
true
print integer? "string"
falseINTERN¶
Imports (internalize) words and their values from the lib into the user context.
Usage:
intern
ARGUMENTS: data [block! any-word!] Word or block of words to be added (deeply)
INTERSECT¶
Returns the intersection of two data sets.
Usage:
intersect
ARGUMENTS: set1 [block! string! bitset! typeset! map!] first set set2 [block! string! bitset! typeset! map!] second set REFINEMENTS: /case Uses case-sensitive comparison /skip Treat the series as records of fixed size size [integer!]
Description:
Returns all elements within two blocks or series that exist in both.
lunch: [ham cheese bread carrot]
dinner: [ham salad carrot rice]
probe intersect lunch dinner
[ham carrot]
probe 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
probe intersect string1 string2
"CD"
items: [1 1 2 3 2 4 5 1 2]
probe intersect items items ; get unique set
[1 2 3 4 5]
str: "abcacbaabcca"
probe intersect str str
"abc"To obtain a unique set (to remove duplicate values) you can use UNIQUE.
Note that performing this function over very large data sets can be CPU intensive.
INVALID-UTF?¶
Checks UTF encoding; if correct, returns none else position of error.
Usage:
invalid-utf?
ARGUMENTS: data [binary!] REFINEMENTS: /utf Check encodings other than UTF-8 num [integer!] Bit size - positive for BE negative for LE
ISSUE?¶
Returns TRUE if it is this type.
Usage:
issue?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values.
print issue? #1234-5678-9012
true
print issue? #467-8000
true
print issue? $12.56
falseJOIN¶
Concatenates values.
Usage:
join
ARGUMENTS:
value Base value
rest Value or block of values
Description:
Returns a new series that joins together a value with another value or block of values.
join "super" "duper"
"superduper"
join %file ".txt"
%file.txtThis differs from append and repend because a new value is created, and the first argument is not modified in any way.
The first argument determines the datatype of the returned value. When the first argument is a type of series, the return value will be that type of series (d:string, file!, url!, block!, etc.)
When the first argument is a scalar value (such as integer!, date!, time!, and others), the return will always be a string!.
When the second argument is a block!, it will be evaluated and all of its values joined to the return value.
join http:// ["www.rebol.com/" %index.html]
http://www.rebol.com/index.html
join "t" ["e" "s" "t"]
"test"
join 11:11 "PM"
"11:11PM"Note that it also works for block! series, but returns a block, not a string:
join [1] ["two" 3 "four"]
[1 "two" 3 "four"]And, this case is important to note:
join <a> "test"
<atest>(See rejoin for more detail on this case.)
If you want the result here to be a string!, use the ajoin function instead.
KEYS-OF¶
Returns a copy of the words of any function, any object, map, date, handle or struct
Usage:
keys-of
ARGUMENTS: value [any-function! any-object! map! date! handle! struct!]
LAST¶
Returns the last value of a series.
Usage:
last
ARGUMENTS: value [series! tuple! gob!]
Description:
LAST returns the last value of a series. If the series is empty, LAST will cause an error.
print last "abcde"
e
print last [1 2 3 4 5]
5
print last %file
e
probe last 'system/options
optionsIf you do not want an error when the series is empty, use the PICK function instead:
string: ""
print pick back tail string 1
noneLAST?¶
Returns TRUE if the series length is 1.
Usage:
last?
ARGUMENTS: series [series! port! map! tuple! bitset! object! gob! any-word!]
LATIN1?¶
Returns TRUE if value or string is in Latin-1 character range (below 256).
Usage:
latin1?
ARGUMENTS: value [any-string! char! integer!]
Description:
>> latin1? "mýdlo"
== #(true) ;; because (to integer! #"ý") == 253
>> latin1? "česko"
== #(false) ;; because (to integer! #"č") == 269LAUNCH¶
Runs a script as a separate process; return immediately.
Usage:
launch
ARGUMENTS: script [file! string!] The name of the script REFINEMENTS: /with args [string! block! none!] Arguments to the script /wait Wait for the process to terminate
Description:
The LAUNCH function is used to run REBOL scripts as a separate process. When LAUNCH is called, a new process is created and passed the script file name or URL to be processed. The process is created as a subprocess of the main REBOL process.
Launch has certain restrictions depending on the REBOL system used. Also, within Unix/Linux systems, launch will use the same shell standard files as the main REBOL process, and output will be merged.
launch %calculator.r
launch http://www.rebol.com/scripts/news.rLCM¶
Returns the least common multiple
Usage:
lcm
ARGUMENTS: a [integer!] b [integer!]
LENGTH?¶
Returns the length (from the current position for series.)
Usage:
length?
ARGUMENTS: series [series! port! map! tuple! bitset! object! gob! struct! any-word! none!]
Description:
The length? function returns the number of values from the current position of a series to the tail of the series.
For example:
print length? "REBOL"
5but, in the case of an offset position from skip :
print length? skip "REBOL" 2
3or from find :
print length? find "REBOL" "L"
1Other examples:
print length? [1 2 3 4 5]
5
print length? [1 2 3 [4 5]]
4
print length? read http://www.rebol.com
7216
obj: object [a: 10 b: 20]
print length? obj
2LESSER-OR-EQUAL?¶
Returns TRUE if the first value is less than or equal to the second value.
Usage:
lesser-or-equal?
ARGUMENTS:
value1
value2
Description:
Returns FALSE for all other values. For string-based datatypes, the sorting order is used for comparison with character casing ignored (uppercase = lowercase).
print lesser-or-equal? "abc" "abd"
true
print lesser-or-equal? 10-June-1999 12-june-1999
true
print lesser-or-equal? 4.3.2.1 1.2.3.4
false
print lesser-or-equal? 1:23 10:00
trueLESSER?¶
Returns TRUE if the first value is less than the second value.
Usage:
lesser?
ARGUMENTS:
value1
value2
Description:
Returns FALSE for all other values. The values must be of the same datatype, or an error will occur. For string-based datatypes, the sorting order is used for comparison with character casing ignored (uppercase = lowercase).
print lesser? "abc" "abcd"
true
print lesser? 12-june-1999 10-june-1999
false
print lesser? 1.2.3.4 4.3.2.1
true
print lesser? 1:30 2:00
trueLIBRARY?¶
Returns TRUE if it is this type.
Usage:
library?
ARGUMENTS: value [any-type!]
Description:
Returns TRUE if the value is a LIBRARY datatype.
LICENSE¶
Prints the REBOL/core license agreement
Usage:
license
Description:
Returns the REBOL end user license agreement for the currently running version of REBOL.
>> license╔══════════════════════════════════════════════════════════════════════════╗
║ ║
║ Copyright 2012 REBOL Technologies ║
║ 2012-2025 Rebol Open Source Contributors ║
║ Licensed under the Apache License, Version 2.0. ║
║ https://www.apache.org/licenses/LICENSE-2.0 ║
║ ║
║ Notice https://github.com/Oldes/Rebol3/blob/master/NOTICE ║
║ ║
╚══════════════════════════════════════════════════════════════════════════╝
For SDK and other specially licensed versions of REBOL, the license function may return an empty string.
LIMIT-USAGE¶
Set a usage limit only once (used for SECURE).
Usage:
limit-usage
ARGUMENTS: field [word!] eval (count) or memory (bytes) limit [number!]
LIST-DIR¶
Print contents of a directory (ls).
Usage:
list-dir
ARGUMENTS: path [file! word! path! string! unset!] Accepts %file, :variables, and just words (as dirs) REFINEMENTS: /f Files only /d Dirs only /r Recursive /i indent [string! char!] /l Limit recursive output to given maximal depth max-depth [integer!]
Description:
Lists the files and directories of the specified path in a sorted multi-column output. If no path is specified, the directory specified in system/script/path is listed. Directory names are followed by a slash (/) in the output listing.
list-dirTo obtain a block of files for use by your program, use the LOAD function. The example below returns a block that contains the names of all files and directories in the local directory.
files: load %./
print length? files
probe files
[%autos.txt %build-docs.r %bulk-modify.r %cgi.r %convert-orig.r %CVS/ %emit-html.r %eval-examples.r %fix-args.r %fred/ %funcs.r %helloworld.txt %merge-funcs.r %newfile.txt %notes.txt %public/ %replace.r %scan-doc.r %scan-titles.r %strip-title.r %test-file.txt %trash.me]LIST-ENV¶
Returns a map of OS environment variables (for current process).
Usage:
list-env
Description:
This function will return a map! of OS environment variables and their values.
>> list-env
== #[
"=::" "::\"
"ALLUSERSPROFILE" "C:\ProgramData"
"APPDATA" "C:\Users\oldes\AppData\Roaming"
...LIT-PATH?¶
Returns TRUE if it is this type.
Usage:
lit-path?
ARGUMENTS: value [any-type!]
Description:
Returns true if the value is a literal path datatype.
>> lit-path? first ['some/path other/path]
== #(true)
>> lit-path? second ['some/path other/path]
== #(false)LIT-WORD?¶
Returns TRUE if it is this type.
Usage:
lit-word?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values.
>> lit-word? first ['foo bar]
== #(true)LOAD¶
Loads code or data from a file, URL, string, or binary.
Usage:
load
ARGUMENTS: source [file! url! string! binary! block!] Source or block of sources REFINEMENTS: /header Result includes REBOL header object (preempts /all) /all Load all values (does not evaluate REBOL header) /as Override default file-type; use NONE to always load as code type [word! none!] E.g. text, markup, jpeg, unbound, etc.
Description:
Reads and converts external data, including programs, data structures, images, and sounds into memory storage objects that can be directly accessed and manipulated by programs.
The argument to LOAD can be a file, URL, string, or binary value. When a file name or URL is provided, the data is read from disk or network first, then it is loaded. In the case of a string or binary value, it is loaded directly from memory.
Here are a few examples of using LOAD:
script: load %dict-notes.r
image: load %image.png
sound: load %whoosh.wav
;data: load http://www.rebol.com/example.r
;data: load ftp://ftp.rebol.com/example.r
data: load "1 2 luke fred@example.com"
code: load {loop 10 [print "hello"]}LOAD is often called for a text file that contains REBOL code or data that needs to be brought into memory. The text is first searched for a REBOL header, and if a header is found, it is evaluated first. (However, unlike the DO function, LOAD does not require that there be a header.)
If the load results in a single value, it will be returned. If it results in a block, the block will be returned. No evaluation of the block will be done; however, words in the block will be bound to the global context.
If the header object is desired, use the /HEADER option to return it as the first element in the block.
The /ALL refinement is used to load an entire script as a block. The header is not evaluated.
The /NEXT refinement was removed - use TRANSCODE/NEXT instead
LOAD-EXTENSION¶
Low level extension module loader (for DLLs).
Usage:
load-extension
ARGUMENTS: name [file! binary!] DLL file or UTF-8 source REFINEMENTS: /dispatch Specify native command dispatch (from hosted extensions) function [handle!] Command dispatcher (native)
LOAD-JSON¶
Convert a JSON string to Rebol data
Usage:
load-json
ARGUMENTS: input [string!] The JSON string
Description:
>> load-json to-json [1 2 3]
== [1 2 3]
>> load-json to-json #[a: 1 b: "test"]
== #[
a: 1
b: "test"
]It is same like using decode.
>> decode 'json {{"a":1,"b":"test"}}
== #[
a: 1
b: "test"
]LOG-10¶
Returns the base-10 logarithm.
Usage:
log-10
ARGUMENTS: value [number!]
Description:
The LOG-10 function returns the base-10 logarithm of the number provided. The argument must be a positive value, otherwise an error will occur (which can be trapped with the TRY function).
print log-10 100
2.0
print log-10 1000
3.0
print log-10 1234
3.091315159697223LOG-2¶
Return the base-2 logarithm.
Usage:
log-2
ARGUMENTS: value [number!]
Description:
The LOG-10 function returns the base-2 logarithm of the number provided. The argument must be a positive value, otherwise an error will occur (which can be trapped with the TRY function).
print log-2 2
1.0
print log-2 4
2.0
print log-2 256
8.0
print log-2 1234
10.26912667914941LOG-E¶
Returns the natural (base-E) logarithm of the given value
Usage:
log-e
ARGUMENTS: value [number!]
Description:
The LOG-E function returns the natural logarithm of the number provided. The argument must be a positive value, otherwise an error will occur (which can be trapped with the TRY function).
print log-e 1234
7.118016204465333
print exp log-e 1234
1234.0LOGIC?¶
Returns TRUE if it is this type.
Usage:
logic?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values. Note that all conditional functions will accept more than just a LOGIC value. A NONE will act as FALSE, and all other values other than logic will act as TRUE.
print logic? true
true
print logic? 123
falseLOOP¶
Evaluates a block a specified number of times.
Usage:
loop
ARGUMENTS: count [number!] Number of repetitions block [block!] Block to evaluate
Description:
The loop function is the simplest way to repeat the evaluation of a block. This function is very efficient and should be used if no loop counter is required.
loop 3 [print "hi"]
hi
hi
hiHere's an example that creates a block of 10 random integers:
block: make block! 10
loop 10 [append block random 100]
probe block
[31 25 53 20 40 2 30 79 47 79]Returned Value
When finished the loop function returns the final value the block:
num: 0
print loop 10 [num: num + 1]
10Other Notes
- Negative or zero loop counts do not evaluate the block.
- If a decimal! count is used, it will be truncated to a lower integer value.
- The break function can be used to stop the loop at any time.
- The repeat function is similar to loop, except that it allows a variable to keep track of the current loop counter.
LOWERCASE¶
Converts string of characters to lowercase.
Usage:
lowercase
ARGUMENTS: string [any-string! char!] (modified if series) REFINEMENTS: /part Limits to a given length or position length [number! any-string!]
Description:
The series passed to this function is modified as a result.
>> lowercase "ABCDEF"
== "abcdef"
>> lowercase/part "ABCDEF" 3
== "abcDEF"LS¶
Note: Shell shortcut for list-dir.
MAKE¶
Constructs or allocates the specified datatype.
Usage:
make
ARGUMENTS: type [any-type!] The datatype or an example value spec [any-type!] Attributes or size of the new value (modified)
Description:
The TYPE argument indicates the datatype to create.
The form of the constructor is determined by the datatype. For most series datatypes, a number indicates the size of the initial allocation.
str: make string! 1000
blk: make block! 10
cash: make money! 1234.56
print cash
$1234.560000000000000
time: make time! [10 30 40]
print time
10:30:40NOTE: MAKE when used with OBJECTS will modify the context of the spec block (as if BIND was used on it). If you need to reuse the spec block use MAKE in combination with COPY/deep like this:
make object! copy/deep specMAKE-DIR¶
Creates the specified directory. No error if already exists.
Usage:
make-dir
ARGUMENTS: path [file! url!] REFINEMENTS: /deep Create subdirectories too
Description:
Creates a new directory at the specified location. This operation can be performed for files or FTP URLs.
make-dir %New-Dir/
delete %New-Dir/MAP¶
Make a map value (hashed associative block).
Usage:
map
ARGUMENTS:
val
Description:
Description is needed.
MAP-EACH¶
Evaluates a block for each value(s) in a series and returns them as a block.
Usage:
map-each
ARGUMENTS: word [word! block!] Word or block of words to set each time (local) data [block! vector!] The series to traverse body [block!] Block to evaluate each time
Description:
>> map-each w [1 2 3][w * 100]
== [100 200 300]MAP-EVENT¶
Returns event with inner-most graphical object and coordinate.
Usage:
map-event
ARGUMENTS: event [event!]
Description:
No description provided.
MAP-GOB-OFFSET¶
Translates a gob and offset to the deepest gob and offset in it, returned as a block.
Usage:
map-gob-offset
ARGUMENTS: gob [gob!] Starting object xy [pair!] Staring offset REFINEMENTS: /reverse Translate from deeper gob to top gob.
Description:
No description provided.
MAP?¶
Returns TRUE if it is this type.
Usage:
map?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values.
>> map? #[a: 1]
== #(true)
>> map? object [a: 1]
== #(false)MAX¶
Returns the greater of the two values.
Usage:
max
ARGUMENTS: value1 [scalar! date! series!] value2 [scalar! date! series!]
Description:
Returns the maximum of two values.
print max 0 100
100
print max 0 -100
0
print max 4.56 4.2
4.56The maximum value is computed by comparison, so MAX can also be used for non-numeric datatypes as well.
print max 1.2.3 1.2.8
1.2.8
print max "abc" "abd"
abd
print max 12:00 11:00
12:00
print max 1-Jan-1920 20-Feb-1952
20-Feb-1952Using MAX on xy pairs will return the maximum of each X and Y coordinate separately.
print max 100x10 200x20
200x20MAXIMUM¶
Returns the greater of the two values.
Usage:
maximum
ARGUMENTS: value1 [scalar! date! series!] value2 [scalar! date! series!]
Description:
See the MAX function for details.
MIN¶
Returns the lesser of the two values.
Usage:
min
ARGUMENTS: value1 [scalar! date! series!] value2 [scalar! date! series!]
Description:
Returns the minimum of two values.
print min 0 100
0
print min 0 -100
-100
print min 4.56 4.2
4.2The minimum value is computed by comparison, so MIN can also be used for non-numeric datatypes as well.
print min 1.2.3 1.2.8
1.2.3
print min "abc" "abd"
abc
print min 12:00 11:00
11:00
print min 1-Jan-1920 20-Feb-1952
1-Jan-1920Using min on xy pairs will return the minimum of each X and Y coordinate separately.
print min 100x10 200x20
100x10MINIMUM¶
Returns the lesser of the two values.
Usage:
minimum
ARGUMENTS: value1 [scalar! date! series!] value2 [scalar! date! series!]
Description:
See the MIN function for details.
MKDIR¶
Creates the specified directory. No error if already exists.
Usage:
mkdir
ARGUMENTS: path [file! url!] REFINEMENTS: /deep Create subdirectories too
Description:
Note: Shell shortcut for make-dir.
MOD¶
Compute a nonnegative remainder of A divided by B.
Usage:
mod
ARGUMENTS: a [number! money! char! time!] b [number! money! char! time!] Must be nonzero.
Description:
Similar to REMAINDER, but the result is always non-negative.
MODIFIED?¶
Returns the last modified date of a file.
Usage:
modified?
ARGUMENTS: target [file! url!]
Description:
Returns NONE if the file does not exist.
print modified? %file.txt
noneMODIFY¶
Change mode or control for port or file.
Usage:
modify
ARGUMENTS: target [port! file!] field [word! none!] value
MODULE¶
Creates a new module.
Usage:
module
ARGUMENTS: spec [block!] The header block of the module (modified) body [block!] The body block of the module (modified) REFINEMENTS: /mixin Mix in words from other modules words [object!] Words collected into an object
Description:
Description is needed.
MODULE?¶
Returns TRUE if it is this type.
Usage:
module?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values.
>> module? object [a: 1]
== #(false)
>> module? system/modules/help
== #(true)MODULO¶
Wrapper for MOD that handles errors like REMAINDER. Negligible values (compared to A and B) are rounded to zero.
Usage:
modulo
ARGUMENTS: a [number! money! char! time!] b [number! money! char! time!] Absolute value will be used.
Description:
See MOD for details.
MOLD¶
Converts a value to a REBOL-readable string.
Usage:
mold
ARGUMENTS: value [any-type!] The value to mold REFINEMENTS: /only For a block value, mold only its contents, no outer [] /all Use construction syntax /flat No indentation /part Limit the length of the result limit [integer!]
Description:
The mold function converts values to a source-code formatted string (REBOL-readable).
print mold 10:30
10:30
print mold %image.jpg
%image.jpg
print mold [1 2 3]
[1 2 3]The primary importance of mold is to produce strings that can be reloaded with load.
str: mold [1 + 2]
probe load str
[1 + 2]The mold function is the cousin of form which produces a human-readable string (used by the print function.) For example a block will be shown with brackets
Also, remold first uses reduce then mold.
The /only Refinement
In some cases it is useful to not mold the outermost brackets of blocks. This is done with the /only refinement:
print mold/only [1 2 3]
1 2 3This is commonly true for blocks of values that are saved to files:
write %example.r mold/only [1 2 3]See the save function.
The /all Refinement
For some values mold produces an approximate string value, not a perfect representation. If you attempt to load such a string, its value may be different.
For example:
mold 'true
"true"
mold true
"true"The first is the word true the second is the logic! value true -- they are different but represented by the same word. If you load the resulting string, you will only obtain the word true not the logic value:
type? load mold true
word!The /all option provides a more accurate transformation from values to strings and back (using load.)
mold/all 'true
"true"
mold/all true
"#[true]"Using load, you can see the difference:
type? load mold/all 'true
word!
type? load mold/all true
logic!Another difference occurs with strings that are indexed from their head positions. Sometimes this is desired, sometimes not. It can be seen here:
mold next "ABC"
"BC"
mold/all next "ABC"
{#[string! "ABC" 2]}The following datatypes are affected: unset!, none!, logic!, bitset!, image!, map!, datatype!, typeset!, native!, action!, op!, closure!, function!, object!, module!, error!, task!, port!, gob!, event!, handle!.
The decimal! datatype is implemented as IEEE 754 binary floating point type. When molding decimal! values, mold/all will need to use the maximal precision 17 digits to allow for accurate transformation of Rebol decimals to string and back, as opposed to just mold, which uses a default precision 15 decimal digits.
The /flat Refinement
The /flat refinement is useful for minimizing the size of source strings. It properly removes leading indentation (from code lines, but not multi-line strings.) The /flat option is often used for data exchanged between systems or stored in files.
Here is code often used for saving a script in minimal format (in R3):
write %output.r mold/only/flat codeFor code larger than about 1K, you can also compress it:
write %output.rc compress mold/only/flat codeSuch a file can be reloaded with:
load/all decompress read %output.rcNote that if using R2, these lines must be modified to indicate binary format.
Code Complexity Comparisons
It should be noted that mold function is used for computing the relative complexity of code using the Load Mold Sizing method.
MOLD64¶
Temporary function to mold binary base 64.
Usage:
mold64
ARGUMENTS:
data
MONEY?¶
Returns TRUE if it is this type.
Usage:
money?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values.
print money? $123
true
print money? 123.45
falseMORE¶
Print file (shell shortcut function).
Usage:
more
ARGUMENTS: file [file! word! path! string!] Accepts %file and also just words (as file names)
Description:
Description is needed.
MOVE¶
Move a value or span of values in a series.
Usage:
move
ARGUMENTS: source [series! gob!] Source series (modified) offset [integer!] Offset to move by, or index to move to REFINEMENTS: /part Move part of a series length [integer!] The length of the part to move /skip Treat the series as records of fixed size size [integer!] Size of each record /to Move to an index relative to the head of the series
Description:
Description is needed.
MULTIPLY¶
Returns the first value multiplied by the second.
Usage:
multiply
ARGUMENTS: value1 [scalar! vector!] value2 [scalar! vector!]
Description:
The datatype of the second value may be restricted to INTEGER or DECIMAL, depending on the datatype of the first value (e.g. the first value is a time).
print multiply 123 10
1230
print multiply 3:20 3
10:00
print multiply 0:01 60
1:00NATIVE?¶
Returns TRUE if it is this type.
Usage:
native?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values. When passing a function to NATIVE? to be checked, it must be denoted with ":". This is because the ":word" notation passes a word's reference, not the word's value. NATIVE? can only determine whether or not a function is a native if it is passed the function's reference.
probe native? :native? ; it's actually an ACTION!
false
probe native? "Vichy"
false
probe native? :if
trueNEGATE¶
Changes the sign of a number.
Usage:
negate
ARGUMENTS: number [number! pair! money! time! bitset!]
Description:
Returns the negative of the value provided.
print negate 123
-123
print negate -123
123
print negate 123.45
-123.45
print negate -123.45
123.45
print negate 10:30
-10:30
print negate 100x20
-100x-20
print negate 100x-20
-100x20NEGATIVE?¶
Returns TRUE if the number is negative.
Usage:
negative?
ARGUMENTS: number [number! money! time! pair!]
Description:
Returns FALSE for all other values.
print negative? -50
true
print negative? 50
falseNEW-LINE¶
Sets or clears the new-line marker within a block or paren.
Usage:
new-line
ARGUMENTS: position [block! paren!] Position to change marker (modified) value Set TRUE for newline REFINEMENTS: /all Set/clear marker to end of series /skip Set/clear marker periodically to the end of the series size [integer!]
Description:
Where the NEW-LINE? function queries the status of the a block for markers, the NEW-LINE function inserts or removes them. You can use it to generate formatted blocks.
Given a block at a specified offset, new-line? will return true if there is a marker at that position.
dent-block: func [
"Indent the contents of a block"
block
][
head new-line tail new-line block on on
]
b: [1 2 3 4 5 6]
probe dent-block b
[
1 2 3 4 5 6
If you want to put each item in a block on a new line, you can insert markers in bulk, using the /all refinement.
b: [1 2 3 4 5 6]
probe new-line/all b on
[
1
2
3
4
5
6
If you don't know whether a block contains markers, you may want to remove all markers before formatting the data.
b: [
1 2
3 4
]
probe new-line/all b off
[1 2 3 4]Another common need is formatting blocks into lines of fixed size groups of items; that's what the /skip refinement is for.
b: [1 2 3 4 5 6]
probe new-line/skip b on 2
[
1 2
3 4
5 6
NEW-LINE?¶
Returns the state of the new-line marker within a block or paren.
Usage:
new-line?
ARGUMENTS: position [block! paren!] Position to check marker
Description:
Given a block at a specified offset, new-line? will return true if there is a line marker at that position.
b: [1 2 3 4 5 6]
forall b [if new-line? b [print index? b]]
b: [
1 2
3 4
5 6
]
forall b [if new-line? b [print index? b]]
5NEXT¶
Returns the series at its next position.
Usage:
next
ARGUMENTS: series [series! gob! port!]
Description:
If the series is at its tail, it will remain at its tail. NEXT will not go past the tail, nor will it wrap to the head.
print next "ABCDE"
BCDE
print next next "ABCDE"
CDE
print next [1 2 3 4]
2 3 4
str: "REBOL"
loop length? str [
print str
str: next str
]
L
blk: [red green blue]
loop length? blk [
probe blk
blk: next blk
]
[blue]NINTH¶
Returns the ninth value of a series.
Usage:
ninth
ARGUMENTS:
value
Description:
See the FIRST function for examples.
An error will occur if no value is found. Use the PICK function to avoid this error.
NONE?¶
Returns TRUE if it is this type.
Usage:
none?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values.
print none? NONE
true
print none? pick "abc" 4
true
print none? find "abc" "d"
trueNOT¶
Returns the logic complement.
Usage:
not
ARGUMENTS: value [any-type!] (Only FALSE and NONE return TRUE)
Description:
The not function is a logic! function that returns true if the value is false or none. It will return false for all other values.
not true
false
not none
true
not (10 = 1)
true
not 0
false ; take note of this
not 1
falseTo complement an integer! use the complement function or negate function.
NOT-EQUAL?¶
Returns TRUE if the values are not equal.
Usage:
not-equal?
ARGUMENTS: value1 [any-type!] value2 [any-type!]
Description:
String-based datatypes are considered equal when they are identical or differ only by character casing (uppercase = lowercase). Use == or find/match/case to compare strings by casing.
print not-equal? "abc" "abcd"
true
print not-equal? [1 2 4] [1 2 3]
true
print not-equal? 12-sep-98 10:30
trueNOT-EQUIV?¶
Returns TRUE if the values are not equivalent.
Usage:
not-equiv?
ARGUMENTS: value1 [any-type!] value2 [any-type!]
NOW¶
Returns date and time.
Usage:
now
REFINEMENTS:
/year Returns year only
/month Returns month only
/day Returns day of the month only
/time Returns time only
/zone Returns time zone offset from UCT (GMT) only
/date Returns date only
/weekday Returns day of the week as integer (Monday is day 1)
/yearday Returns day of the year (Julian)
/precise High precision time
/utc Universal time (no zone)
Description:
For accuracy, first verify that the time, date and timezone are correctly set on the computer.
print now
12-Feb-2009/17:47:54-8:00
print now/date
12-Feb-2009
print now/time
17:47:54
print now/zone
-8:00
print now/weekday
4NUMBER?¶
Returns TRUE if the value is any type of number and not a NaN.
Usage:
number?
ARGUMENTS:
value
Description:
Returns FALSE for all other values.
>> number? 1234
== #(true)
>> number? 12.3
== #(true)
>> number? "12"
== #(false)OBJECT¶
Creates an object.
Usage:
object
ARGUMENTS: spec [block!] REFINEMENTS: /only Do not bind nested blocks
Description:
No description provided.
OBJECT?¶
Returns TRUE if it is this type.
Usage:
object?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values.
>> object? system
== #(true)
>> object? 1
== #(false)ODD?¶
Returns TRUE if the number is odd.
Usage:
odd?
ARGUMENTS: number [number! char! date! money! time! pair!]
Description:
Returns TRUE only if the argument is an odd integer value. If the argument is a decimal, only its integer portion is examined.
print odd? 3
true
print odd? 100
false
print odd? 0
falseOFFSET?¶
Returns the offset between two series positions.
Usage:
offset?
ARGUMENTS: series1 [series!] series2 [series!]
Description:
Return the difference of the indexes for two positions within a series.
str: "abcd"
p1: next str
print offset? str p1
1
str: "abcd"
p1: next str
p2: find str "d"
print offset? p1 p2
2OP?¶
Returns TRUE if it is this type.
Usage:
op?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values.
print op? :and
true
print op? :+
trueOPEN¶
Opens a port; makes a new port from a specification if necessary.
Usage:
open
ARGUMENTS: spec [port! file! url! block! word!] REFINEMENTS: /new Create new file - if it exists, reset it (truncate) /read Open for read access /write Open for write access /seek Optimize for random access /allow Specifies protection attributes access [block!]
Description:
Opens a port for I/O operations. The value returned from OPEN can be used to examine or modify the data associated with the port. The argument must be a fully-specified port specification, an abbreviated port specification such as a file path or URL, or a block which is executed to modify a copy of the default port specification.
autos: open/new %autos.txt
insert autos "Ford"
insert tail autos " Chevy"
close autos
print read %autos.txtOPEN?¶
Returns TRUE if port is open.
Usage:
open?
ARGUMENTS: port [port!]
Description:
Description is needed.
OR¶
Returns the first value ORed with the second.
Usage:
or
ARGUMENTS: value1 [logic! integer! char! tuple! binary! bitset! typeset! datatype!] value2 [logic! integer! char! tuple! binary! bitset! typeset! datatype!]
Description:
An infix-operator. For LOGIC values, both must be FALSE to return FALSE; otherwise a TRUE is returned. For integers, each bit is separately affected. Because it is an infix operator, OR must be between the two values.
print true or false
true
print (10 > 20) or (20 < 100)
true
print 122 or 1
123
print 1.2.3.4 or 255.255.255.0
255.255.255.4OR~¶
Returns the first value ORed with the second.
Usage:
or~
ARGUMENTS: value1 [logic! integer! char! tuple! binary! bitset! typeset! datatype!] value2 [logic! integer! char! tuple! binary! bitset! typeset! datatype!]
Description:
The trampoline action function for OR operator.
PAD¶
Pad a FORMed value on right side with spaces
Usage:
pad
ARGUMENTS: str Value to pad, FORM it if not a string n [integer!] Total size (in characters) of the new string (pad on left side if negative) REFINEMENTS: /with Pad with char c [char!]
PAIR?¶
Returns TRUE if it is this type.
Usage:
pair?
ARGUMENTS: value [any-type!]
Description:
Returns true if the value is an xy pair datatype.
print pair? 120x40
true
print pair? 1234
falseSee the PAIR! word for more detail.
PAREN?¶
Returns TRUE if it is this type.
Usage:
paren?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values. A paren is identical to a block, but is immediately evaluated when found.
print paren? second [123 (456 + 7)]
true
print paren? [1 2 3]
falsePARSE¶
Parses a string or block series according to grammar rules.
Usage:
parse
ARGUMENTS: input [series!] Input series to parse rules [block!] Rules to parse REFINEMENTS: /case Uses case-sensitive comparison
Description:
The parse function is used to match patterns of values and perform specific actions upon such matches. A full summary can be found in parsing: summary of parse operations .
Both string! and block! datatypes can be parsed. Parsing of strings matches specific characters or substrings. Parsing of blocks matches specific values, or specific datatypes, or sub-blocks.
Whereas most languages provide a method of parsing strings, the parsing of blocks is an important feature of the REBOL language.
The parse function takes two main arguments: an input to be parsed and the rules that are used to parse it. The rules are specified as a block of grammar productions that are to be matched.
General parse rules
Rules consist of these main elements:
| Item | Description |
|---|---|
| keyword | a special word of the dialect, listed in the table below |
| word | get or set a variable (see below) - cannot be a keyword |
| path | get or set a variable via a path (see below) |
| value | match the input to a value (accepted datatypes depend on input datatype) |
| "|" | backtrack and match to next alternate rule (or) |
| [block] | a block of sub-rules |
| (paren) | evaluate an expression (a production) |
List of keywords
Within the parse dialect, these words are treated as keywords and cannot be used as variables.
| Keyword | Description |
|---|---|
| and rule | match the rule, but do not advance the input (allows matching multiple rules to the same input) |
| any rule | match the rule zero or more times; stop on failure or if input does not change. |
| break | break out of a match loop (such as any, some, while), always indicating success. |
| change rule only value | match the rule, and if true, change the input to the new value (can be different lengths) |
| copy word | set the word to a copy of the input for matched rules |
| do rule | evaluate the input as code, then attempt to match to the rule |
| end | match end of input |
| fail | force current rule to fail, backtrack |
| if (expr) | evaluate the expression (in a paren) and if false or none, fail and backtrack |
| insert only value | insert a value at the current input position (with optional ONLY for blocks by reference); input position is adjusted just past the insert |
| into rule | match a series, then parse it with given rule; new series can be the same or different datatype. |
| opt rule | match to the rule once or not at all (zero or one times) |
| not rule | invert the result of the next rule |
| quote arg | accept next argument exactly as is (exception: paren) |
| reject | similar to break: break out of a match loop (such as any, some, while), but indicate failure. |
| remove rule | match the rule, and if true, remove the matched input |
| return rule | match the rule, and if true, immediately return the matched input as result of the PARSE function |
| set word | set the word to the value of the input for matched rules |
| skip | skip input (for the count range, if provided before it) |
| some rule | match to the rule one or more times; stop on failure or if input does not change. |
| then | regardless of failure or success of what follows, skip the next alternate rule (branch) |
| thru rule | scan forward in input for matching rules, advance input to tail of the match |
| to rule | scan forward in input for matching rules, advance input to head of the match |
| while rule | like any, match to the rule zero or more times; stop on failure; does not care if input changes or not. |
| ?? | Debugging output. Prints the next parse rule value and shows the current input position (e.g. where you are in the string.) |
In addition, none is a special value that can be used as a default match rule. It is often used at the end of alternate rules to catch all no-match cases.
Simple Parse
There is also a simple parse mode that does not require rules, but takes a string of characters to use for splitting up the input string.
Parse also works in conjunction with bitsets (charset) to specify groups of special characters.
The result returned from a simple parse is a block of values. For rule-based parses, it returns TRUE if the parse succeeded through the end of the input string.
print parse "divide on spaces" none
divide on spaces
print parse "Harry Haiku, 264 River Rd., Ukiah, 95482" ","
Harry Haiku 264 River Rd. Ukiah 95482
page: read http://hq.rebol.net
parse page [thru <title> copy title to </title>]
print title
Now is REBOL
digits: charset "0123456789"
area-code: ["(" 3 digits ")"]
phone-num: [3 digits "-" 4 digits]
print parse "(707)467-8000" [[area-code | none] phone-num]
truePAST?¶
Returns TRUE if series is past its end.
Usage:
past?
ARGUMENTS: series [series! gob! port!]
Description:
Description is needed.
PATH?¶
Returns TRUE if it is this type.
Usage:
path?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values.
print path? first [random/seed 10]
truePERCENT?¶
Returns TRUE if it is this type.
Usage:
percent?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values.
>> percent? 10%
== #(true)
>> percent? 10
== #(false)PICK¶
Returns the value at the specified position.
Usage:
pick
ARGUMENTS: aggregate [series! map! gob! pair! date! time! tuple! bitset! port!] index Index offset, symbol, or other value to use as index
Description:
The value is picked relative to the current position in the series (not necessarily the head of the series). The VALUE argument may be INTEGER or LOGIC. A positive integer positions forward, a negative positions backward. If the INTEGER is out of range, NONE is returned. If the value is LOGIC, then TRUE refers to the first position and FALSE to the second (same order as EITHER). An attempt to pick a value beyond the limits of the series will return NONE.
str: "REBOL"
print pick str 2
E
print pick 199.4.80.1 3
80
print pick ["this" "that"] now/time > 12:00
thisPICKZ¶
Returns the value at the specified position. (0-based wrapper over PICK action)
Usage:
pickz
ARGUMENTS: aggregate [series! bitset! tuple!] index [integer!] Zero based
POKE¶
Replaces an element at a given position.
Usage:
poke
ARGUMENTS: series [series! port! map! gob! bitset!] (modified) index Index offset, symbol, or other value to use as index value [any-type!] The new value (returned)
Description:
Similar to CHANGE, but also takes an index into the series.
str: "ABC"
poke str 2 #"/"
print str
A/C
print poke 1.2.3.4 2 10
10POKEZ¶
Replaces an element at a given position. (0-based wrapper over POKE action)
Usage:
pokez
ARGUMENTS: series [series! bitset! tuple!] (modified) index [integer!] Zero based value [any-type!] The new value (returned)
PORT?¶
Returns TRUE if it is this type.
Usage:
port?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values.
file: open %newfile.txt
print port? file
close file
true
print port? "test"
falsePOSITIVE?¶
Returns TRUE if the value is positive.
Usage:
positive?
ARGUMENTS: number [number! money! time! pair!]
Description:
Returns FALSE for all other values.
print positive? 50
true
print positive? -50
falsePOWER¶
Returns the first number raised to the second number.
Usage:
power
ARGUMENTS: number [number!] exponent [number!]
Description:
print power 12.3 5
281530.5684300001PREMULTIPLY¶
Premultiplies RGB channel with its alpha channel
Usage:
premultiply
ARGUMENTS: image [image!] Image to premultiply (modified)
PRIN¶
Outputs a value with no line break.
Usage:
prin
ARGUMENTS: value [any-type!]
Description:
No line termination is used, so the next value printed will appear on the same line. If the value is a block, each of its values will be evaluated first then printed.
prin "The value is "
prin [1 + 2]
prin ["The time is" now/time]PRINT¶
Outputs a value followed by a line break.
Usage:
print
ARGUMENTS: value [any-type!] The value to print
Description:
The print function outputs values in "human-friendly" format (without source code syntax.)
print 1234
1234
print "Example"
Example
print read %file.txt
(file output)
print read http://www.rebol.com
(web page output)If the value is a block, it will be processed by reduce to evaluate each of its values, which will then be output:
print ["The time is" now/time]
The time is 17:47:54
print ["You are using REBOL" system/product system/version]
You are using REBOL core 3.0.0.3.1Removing Spaces
If you need to join strings and values together for output, use the ajoin, join, or rejoin functions.
print ajoin ["REBOL/" system/product " V" system/version/1]]
REBOL/core V3
print ajoin ["The time is " 11:30 "AM"]
The time is 11:30AMRelated Functions
If a newline is not desired, use prin which does not terminate the output:
prin "T"
print "est"
TestThe print function is based on the reform function, which combines the reduce and form functions.
Notice the difference between:
str: reform ["The time is" now/time]
print str
The time is 17:47:54and:
str: form ["The time is" now/time]
print str
The time is now/timeThe alternative to form is mold which produces source code string output, and remold combines reduce with mold in the same way.
str: mold ["The time is" now/time]
print str
["The time is" now/time]
str: mold ["The time is" now/time]
print str
["The time is" 17:47:54]The probe function is similar to print but is defined as:
probe: func [value] [print mold :value :value]The second use of value is to cause probe to return the value it was passed.
If you want to copy print output to a file as well as the console, use the echo function.
echo %output.txt
print "Copying to file"PRINT-HORIZONTAL-LINE¶
Usage:
print-horizontal-line
PRINT-TABLE¶
Print a block of blocks as an ASCII table
Usage:
print-table
ARGUMENTS: headers [block!] block [block!]
PRINTF¶
Formatted print.
Usage:
printf
ARGUMENTS:
fmt Format
val Value or block of values
Description:
Description is needed.
PROBE¶
Debug print a molded value and returns that same value.
Usage:
probe
ARGUMENTS: value [any-type!] The output is truncated to size defined in: system/options/probe-limit
Description:
The probe function will mold a value into reloadable source format and display it.
num: 1
probe [num + 2 "ABC"]
[num + 2 "ABC"]Compare with the print function which will reduce the block:
print [num + 2 "ABC"]
3 ABCReturn Value
The probe function also returns its argument value as its result, making it easy to insert into code for debugging purposes.
Examples:
n: probe 1 + 2
3
print n
3
print 2 * probe pi * probe sine 45
0.707106781186547
2.22144146907918
4.44288293815837
word: 'here
if probe find [where here there] word [print "found"]
[here there]
foundSee the print function for information about related functions.
PROFILE¶
Profile code
Usage:
profile
ARGUMENTS: blocks [block!] Block of code values (block, word, or function) to profile REFINEMENTS: /times Running the test code multiple times, results are average count [integer!] Default value is 10, minimum is 2 and maximum 1000 /quiet Returns [time evaluations series-made series-expanded memory source] results only
PROTECT¶
Protect a series or a variable from being modified.
Usage:
protect
ARGUMENTS: value [word! series! bitset! map! object! module!] REFINEMENTS: /deep Protect all sub-series/objects as well /words Process list as words (and path words) /values Process list of values (implied GET) /hide Hide variables (avoid binding and lookup) /lock Protect permanently (unprotect will fail)
Description:
The protect function provides the following features:
- protects string!, block!, and other series from modification (making them read-only.)
- protects variables (words) from being set to new values.
- protects object!, module!, and map! from modification (by protecting all its words.)
- hide words within objects or modules - making them private - a method of read and write protection.
Synopsis
The protect argument and refinements provide these various protections:
| Argument | Refinement | Protection provided |
|---|---|---|
| word! or path! | cannot set the word (variable) | |
| word! or path! | /hide | cannot bind to the word (variable) |
| string! | cannot modify the string | |
| block! | cannot modify the block | |
| block! | /deep | cannot modify block or any series within it |
| block! | /words | cannot set listed words or paths (variables) |
| block! | /hide | cannot bind to listed words or paths |
| object! | cannot modify object or set its words (variables) | |
| object! | /deep | cannot modify object, set its words, or modify any of its series values |
Protecting series (strings and blocks)
For example to use protect to prevent modification to a string:
test: "text"
protect test
append test "a"
** Script error: protected value or series - cannot modifyThe text string itself is now read-only. Any attempt to modify it will result in that error message.
This also applies to other series:
test: [100 "example" 10:20]
protect test
append test 1.2
** Script error: protected value or series - cannot modifyBut notice:
print append test/2 "x"
examplexSo, series within the block are still modifiable.
To protect all series found within a block, use the /deep refinement:
test: [100 "example" 10:20]
protect/deep test
print append test/2 "x"
** Script error: protected value or series - cannot modifyProtecting objects and modules
It can also be applied to objects and modules, where its meaning becomes: do not let the fields of the object be modified. However, the contents of those fields can still be modified.
person: make object! [
name: "Bob"
age: 32
]
protect person
person/name: "Ted"
** Script error: protected variable - cannot modify: nameHowever, you can still modify the contents of the name string:
append person/name "a"
print person/name
BobaTo prevent that, you call protect with the /deep refinement to protect all series within the object:
person: make object! [
name: "Bob"
age: 32
]
protect/deep person
append person/name "a"
** Script error: protected value or series - cannot modifyProtecting variables (words)
Protect can also be used to prevent a variable word from being modified using a set operation.
test: "This word is protected!"
protect 'test
test: 123
** Script error: protected variable - cannot modify: testHiding variables (words)
To make a variable private, use the /hide refinement. In effect, this prevents any further bindings to the variable. It also blocks attempts at select, in, get, mold, and form, as well as reflect access.
For example, here is an object that defines a password variable that is hidden. Once the object has been created, the pass variable is not accessible, except with the functions defined prior to the protect.
manager: object [
pass: none
set-pass: func [pw][
print "setting password..."
pass: pw
exit ; return nothing
]
get-pass: does [
checksum/secure to-binary pass
]
protect/hide 'pass
]The password can be accessed with the provided functions:
manager/set-pass "bingo"
setting password...
print manager/get-pass
#{E410B808A7F76C6890C9ECACF2B564EC98204FDB}But any other access is not allowed:
probe manager/pass
** Script error: cannot access pass in path manager/pass
probe get in manager 'pass
none
probe select manager 'pass
none
probe words-of manager
[set-pass get-pass]For security reasons, once hidden, a variable cannot be unhidden.
Compatibility
Related articles
(From the A43 release.)
PROTECT-SYSTEM-OBJECT¶
Protect the system object and selected sub-objects.
Usage:
protect-system-object
PROTECTED?¶
Return true if immediate argument is protected from modification.
Usage:
protected?
ARGUMENTS: value [word! series! bitset! map! object! module!]
PUT¶
Replaces the value following a key, and returns the new value.
Usage:
put
ARGUMENTS: series [any-block! map! port! object!] (modified) key [any-type!] value [any-type!] The new value (returned) REFINEMENTS: /case Perform a case-sensitive search /skip Treat the series as records of fixed size size [integer!]
PWD¶
Returns the current directory path.
Usage:
pwd
Description:
Note: Shell shortcut for what-dir.
Q¶
Note: Shell shortcut for quit.
QUERY¶
Returns information about target if possible.
Usage:
query
ARGUMENTS: target [port! file! url! block! vector! date! handle! word!] field [word! block! none! datatype!] NONE will return valid modes for target type REFINEMENTS: /mode ** DEPRECATED **
Description:
Its argument is an unopened port specification. The size, date and status fields in the port specification will be updated with the appropriate information if the query succeeds.
QUIT¶
Stops evaluation and exits the interpreter.
Usage:
quit
REFINEMENTS:
/return Returns a value (to prior script or command shell)
value Note: use integers for command shell
/now Quit immediately
Description:
You can call quit to exit (terminate) your program at any point.
time: 10:00
if time > 12:00 [
print "time for lunch"
quit
]Without refinements, quit is a non-forceful exception (it will throw a quit exception.) This behavior allows a parent program to stop the termination.
To force an immediate quit (no exception), use the /now refinement:
if bad-data [quit/now]You can also return an integer! quit code to the operating system (shell) by using the return refinement:
quit/return 40Note that not all operating systems environments may support this quit code.
QUOTE¶
Returns the value passed to it without evaluation.
Usage:
quote
ARGUMENTS: value [any-type!]
Description:
>> quote foo
== fooWithout quote it throws an error:
>> foo
** Script error: foo has no valueRANDOM¶
Returns a random value of the same datatype; or shuffles series.
Usage:
random
ARGUMENTS: value Maximum value of result (modified when series) REFINEMENTS: /seed Restart or randomize /secure Returns a cryptographically secure random number /only Pick a random value from a series
Description:
The value passed can be used to restrict the range of the random result. For integers random begins at one, not zero, and is inclusive of the value given. (This conforms to the indexing style used for all series datatypes, allowing random to be used directly with functions like PICK.)
loop 3 [print random 10]
1
5
3
lunch: ["Italian" "French" "Japanese" "American"]
print pick lunch random 4
AmericanIf the given argument is a logic value, the result is actually the same as the result of the expression
even? random 2Example
loop 4 [print random true]
false
false
false
true
loop 2 [print random 1:00:00]
0:12:20
0:48:22For decimal value the function generates a uniformly distributed random number between zero (inclusive) and the given value (inclusive).
loop 3 [print random 1.0]
0.209417212061865
0.878424991742667
0.93627033045037Main properties:
- the probability density in the interior points is the reciprocal of the given decimal VALUE argument
- the probability density in the exterior points is 0.0
- as specified by IEEE754, the bounds represent "close" interior well as "close" exterior real numbers. Therefore, the frequency of every bound corresponds to the length of the segment containing adjacent interior real values (real numbers, that are IEEE 754 - rounded to the value of the bound) multiplied by the interior density equal to the reciprocal of the given VALUE
print random "abcdef"
dbcafe
print random [1 2 3 4 5]
2 4 5 3 1In this case RANDOM randomly shuffles the given series "in place", yielding the original series with the same elements, just shuffled. To cut it down, you can use CLEAR:
key: random "abcdefghijklmnopqrstuv0123456789"
clear skip key 6
print key
anfrukHere's an example password generator. Add more partial words to get more variations:
syls: ["ca" "ru" "lo" "ek" "-" "." "!"]
print rejoin random syls
.!ru-ekcaloTo initialize the random number generator, you can seed it with a value (to repeat the sequence) or the current time to start a unique seed.
random/seed 123
random/seed nowThat last line is a good example to provide a fairly random starting value for the random number generator.
The /SECURE variant uses SHA1() of a repeating pattern of the integer bytes (20 bytes total) and it produces cryptographically secure 64-bit random numbers. Cryptographical security means, that it is infeasible to compute the state of the generator from its output. If you don't need to make computing of the generator state infeasible (needed especially when you use the generator to generate passwords, challenges, etc. and want to comply to the FIPS security standards), it is more efficient to use the raw variant (without /SECURE refinement). Even in that case it is not feasible to compute the state, since the state of present generator consists of too many bits to be computable from the output.
Algorithm
The RANDOM function uses a random generator by Donald E. Knuth adjusted to generate 62-bit random integers. Thus, the maximal obtainable random number is 2 to the power of 62 = 4611686018427387904.
If the RANDOM function obtains 0 as an argument, it yields 0. If the argument is a positive integer, the RANDOM function uses rejection, rejecting all "raw randoms" that exceed the largest obtainable multiple of the given VALUE argument. This way, the uniformity of the distribution is assured. In case the given VALUE exceeds the biggest obtainable "raw random", we would have to reject every "raw random" number, so in that case an overflow error is caused (It certainly is an error expecting a bigger random, than the "raw random" maximum).
If the given VALUE is negative, then the generated random integers are in the interval VALUE <= R <= -1.
Uniformly distributed random decimals are generated using the integer output of the Knuth's generator as follows:tt62: to integer! 2 ** 62
4611686018427387904
random-dec: func [x [decimal!]] [(to decimal! (random tt62) - 1) / tt62 * x]
random/seed 0
random 1.0
0.209417212061865
random/seed 0
random-dec 1.0
0.209417212061865In case the given decimal VALUE is positive, the generated random deviates are uniformly distributed in the interval 0.0 <= R <= VALUE, i.e. including bounds.
In case the given decimal VALUE is negative, the random deviates are uniformly distributed in the interval VALUE <= R <= 0.0. Sometimes we need to obtain a uniformly distributed random number R, such that 0.0 < R < 1.0 (i.e. a uniformly distributed random number in the given interval, excluding the bounds). We can get such an R rejecting the bounds as follows:random/seed 0
until [
r: random 1.0
all [
r !== 0.0
r !== 1.0
]
]
r
0.209417212061865RC4¶
Encrypt/decrypt data (modifies) using RC4 algorithm.
Usage:
rc4
REFINEMENTS: /key Provided only for the first time to get stream HANDLE! crypt-key [binary!] Crypt key. /stream ctx [handle!] Stream cipher context. data [binary!] Data to encrypt/decrypt.
READ¶
Read from a file, URL, or other port.
Usage:
read
ARGUMENTS: source [port! file! url! block! word!] REFINEMENTS: /part Partial read a given number of units (source relative) length [number!] /seek Read from a specific position (source relative) index [number!] /string Convert UTF and line terminators to standard text string /binary Preserves contents exactly /lines Convert to block of strings (implies /string) /all Response may include additional information (source relative)
Description:
Using READ is the simplest way to get information from a file or URL. This is a higher level port operation that opens a port, reads some or all of the data, then closes the port and returns the data that was read. When used on a file, or URL, the contents of the file, or URL are returned as a string.
The /LINES refinement returns read content as a series of lines. One line is created for each line terminator found in the read data.
The /PART refinement reads the specified number of elements from the file, URL, or port. Reading a file or URL will read the specified number of characters. Used with /LINES, it reads a specified number of lines.
See the User's Guide for more detailed explanation of using READ and its refinements.
write %rebol-test-file.r "text file"
print read %rebol-test-file.r
read
write %rebol-test-file.r [
{A learned blockhead is a greater man
than an ignorant blockhead.
-- Rooseveldt Franklin}
]
probe first read/lines %rebol-test-file.r
write
probe pick (read/lines %rebol-test-file.r) 3
probe read/part %rebol-test-file.r 9
probe read/with %rebol-test-file.r "blockhead"
write/append %matrix.avi to-binary "abcdefg"REBCODE?¶
Returns TRUE if it is this type.
Usage:
rebcode?
ARGUMENTS: value [any-type!]
Description:
No description provided.
RECYCLE¶
Recycles unused memory.
Usage:
recycle
REFINEMENTS: /off Disable auto-recycling /on Enable auto-recycling /ballast Trigger for auto-recycle (memory used) size [integer!] /torture Constant recycle (for internal debugging)
Description:
This function will force a garbage collection of unused words and values found in memory. This function is not required or recommened for most scripts because the system does it automatically as necessary.
To disable garbage collection, you can specify /off refinement.
recycle/offTo enable it again, use /on:
recycle/onNote that recently used values may not be immediately garbage collected, even though they are no longer being referenced by your program.
REDUCE¶
Evaluates expressions and returns multiple results.
Usage:
reduce
ARGUMENTS: value REFINEMENTS: /no-set Keep set-words as-is. Do not set them. /only Only evaluate words and paths, not functions words [block! none!] Optional words that are not evaluated (keywords) /into Output results into a block with no intermediate storage out [any-block!]
Description:
The reduce function evaluates multiple expressions and returns a block of results. This is one of the most useful functions in REBOL.
For example:
values: reduce [1 + 2 3 + 4]
probe values
[3 7]Compare this with do, which only returns the result of the last expression:
values: do [1 + 2 3 + 4]
probe values
7Part of other functions
The reduce function is important because it enables you to create blocks of expressions that are evaluated and passed to other functions. Some functions, like print, use reduce as part of their operation, as shown in the following example:
print [1 + 2 3 + 4]
3 7The rejoin, repend, reform, remold functions also use reduce as part of their operation, as shown in the following examples:
rejoin ["example" 1 + 2]
example3
str: copy "example"
repend str [1 + 2] ; modifies (uses append)
example3
reform ["example 1 + 2]
example 3
remold ["example" 1 + 2]
["example" 3]Ignored reduction
For convenience, expressions that are fully evaluated simply pass-through the reduce function.
reduce 123
123
reduce "example"
exampleThis makes it possible to use reduce in cases where other datatypes may be passed. For example, here is a common function for building HTML strings that relies on this behavior:
html: make string! 1000
emit: func [data] [repend html data]
emit "test... "
emit ["number is: " 10]
print html
test... number is: 10Blocks with set-words
When you reduce blocks that contain set-words, those words will be set. For example:
a: 1
reduce [a: 2]
print a
2There are times when you do not want this to occur. For example, if you're building a header for a file, you may want to leave the set-words alone.
The /no-set refinement can be used to handle this case.
full-name: "Bob Smith"
reduce/no-set [name: full-name time: now + 10]
[name: "Bob Smith" time: 15-Aug-2010/16:10:50-7:00]Memory usage for large blocks
For most blocks you don't need to worry about memory because REBOL's automatic storage manager will efficiently handle it; however, when building large block series with reduce, you can manage memory even more carefully.
For example, it is common to write:
repend series [a b c]which is shorthand for:
append series reduce [a b c]The evaluated results of a, b, and c are appended to the series.
If this is done a lot, a large number of temporary series are generated, which take memory and also must be garbage collected later.
The /into refinement helps optimize the situation:
reduce/into [a b c] tail seriesIt requires no intermediate storage.
Common Problems
Although reduce will create a new outer block, all other series (blocks, strings, etc.) are referenced, not copied. If you modify those values, they will change in all blocks that reference them.
For example:
str: "name"
probe result: reduce [str]
["name"]
insert str "new-"
probe result
["new-name"]You can see that it's the same string. To change that behavior use the copy function:
result: reduce [copy str]or, for blocks that contain multiple strings or other values:
result: copy/deep reduce [str]REF?¶
Returns TRUE if it is this type.
Usage:
ref?
ARGUMENTS: value [any-type!]
REFINEMENT?¶
Returns TRUE if it is this type.
Usage:
refinement?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values.
print refinement? /any
true
print refinement? 'any
falseREFLECT¶
Returns specific details about a datatype.
Usage:
reflect
ARGUMENTS: value [any-type!] field [word!] Such as: spec, body, words, values, title
Description:
>> reflect object [a: 1 b: 2] 'words
== [a b]
>> reflect object [a: 1 b: 2] 'values
== [1 2]Or used on function:
>> reflect :print 'words
== [value]
>> reflect :print 'title
== "Outputs a value followed by a line break."REFORM¶
Forms a reduced block and returns a string.
Usage:
reform
ARGUMENTS:
value Value to reduce and form
Description:
Identical to FORM but reduces its argument first. Spaces are inserted between each value.
probe reform ["the time is:" now/time]
"the time is: 17:47:54"
probe form ["the time is:" now/time]
"the time is: now/time"REGISTER-CODEC¶
Registers non-native codec to system/codecs and it's suffixes into system/options/file-types
Usage:
register-codec
ARGUMENTS: codec [block! object!] Codec to register (should be based on system/standard/codec template)
REJOIN¶
Reduces and joins a block of values.
Usage:
rejoin
ARGUMENTS: block [block!] Values to reduce and join
Description:
Similar to join but accepts only one argument, the block (which will be reduced first). No spaces are inserted between values.
rejoin ["time=" now/time]
time=17:47:54Notice this important case:
rejoin [<a> "test"]
<atest>This is fine for lines like:
rejoin [<a href=> "test.html"]
<a href=test.html>But you can see it creates a problem in this case:
rejoin [<a href=test.html> "test" </a>]
<a href=test.htmltest</a>>If you want the result to be a string!, use the ajoin function instead.
ajoin [<a href=test.html> "test" </a>]
"<a href=test.html>test</a>"RELEASE¶
Release internal resources of the handle. Returns true on success.
Usage:
release
ARGUMENTS: handle [handle!]
REMAINDER¶
Returns the remainder of first value divided by second.
Usage:
remainder
ARGUMENTS: value1 [scalar!] value2 [scalar!]
Description:
If the second number is zero, an error will occur.
print remainder 123 10
3
print remainder 10 10
0
print remainder 10.2 10
0.1999999999999993If the first value is positive, then the returned remainder is nonnegative.
If the first value is negative, then the returned remainder is nonpositive.
REMOLD¶
Reduces and converts a value to a REBOL-readable string.
Usage:
remold
ARGUMENTS: value The value to reduce and mold REFINEMENTS: /only For a block value, mold only its contents, no outer [] /all Mold in serialized format /flat No indentation /part Limit the length of the result limit [integer!]
Description:
Identical to MOLD, but reduces its argument first. Spaces are inserted between each values in a block.
print remold ["the time is:" now/time]
["the time is:" 17:47:54]REMOVE¶
Removes element(s); returns same position.
Usage:
remove
ARGUMENTS: series [series! gob! port! bitset! none! map!] At position (modified) REFINEMENTS: /part Removes multiple elements or to a given position range [number! series! pair! char!] /key Removes a key from map. key-arg [any-type!]
Description:
Removes a single value from the current position in any type of series.
str: copy "send it here"
remove str
print str
end it hereCombine it with other functions to remove a value at a specific index:
remove find str "it"
print str
end t hereYou can remove any number of values with the /PART refinement:
str: copy "send it here"
remove/part str 3
print str
d it hereThe PART refinement also accepts an index of the series being removed form. It must be the same series.
remove/part str find str "here"
print str
hereAn example using a block!:
blk: copy [red green blue]
remove next blk
probe blk
[red blue]REMOVE-EACH¶
Removes values for each block that returns truthy value.
Usage:
remove-each
ARGUMENTS: word [word! block!] Word or block of words to set each time (local) data [series! map!] The series to traverse (modified) body [block!] Block to evaluate (return TRUE to remove) REFINEMENTS: /count Returns removal count
Description:
The remove-each function is a high performance method of removing specific elements from a series. It is similar to foreach but will remove one or more values depending on the result of the evaluated block.
In this example, remove-each is used to remove all strings from the block:
values: [12 "abc" test 5 "de" 10:30]
remove-each value values [string? value]
probe values
[12 test 5 10:30]Here, all integer values greater than 11 are removed:
values: [12 "abc" test 5 "de" 10:30]
remove-each value values [all [integer? value value > 11]]
probe values
["abc" test 5 "de" 10:30]Multiple Elements
The remove-each function can be used on multiple elements, just as foreach does.
movies: [
8:30 "Contact" $4.95
10:15 "Ghostbusters" $3.25
12:45 "Matrix" $4.25
]
foreach [time title price] movies [
print [title "at" time "for" price]
if price > $4.00 [print "removed" true]
]
Contact at 8:30 for $4.95
removed
Ghostbusters at 10:15 for $3.25
Matrix at 12:45 for $4.25
removedThis example also shows that the evaluated block may contain any other expressions as long as the last one returns true for removed values.
Also, notice here the way if is used for its return value.
RENAME¶
Rename a file.
Usage:
rename
ARGUMENTS: from [port! file! url! block!] to [port! file! url! block!]
Description:
Renames a file within the same directory:
write %testfile now
rename %testfile %remove.me
probe read %remove.me
delete %remove.me
writeThis function cannot be used to move a file from one directory to another.
REPEAT¶
Evaluates a block a number of times or over a series.
Usage:
repeat
ARGUMENTS: word [word!] Word to set each time value [number! series! pair! none!] Maximum number or series to traverse body [block!] Block to evaluate each time
Description:
The repeat function is an easy way to repeat the evaluation of a block with a loop counter.
repeat num 3 [print num]
1
2
3Here the num counter begins at one and continues up to and including the integer value given.
Other Notes
- Negative or zero loop counts do not evaluate the block.
- If a decimal! count is used, it will be truncated to a lower integer value.
- The break function can be used to stop the loop at any time.
- The loop function is similar to repeat, except that it has no loop counter. If you don't need the counter, loop is more efficient.
- The evaluated block is deep copied and rebound (see bind ) to a new context that holds the loop variable. For large nested repeat loops, you will want to consider this overhead. An alternative is to use while, until, or loop which do not require the copy and bind.
In question...
If the value is a series, then the loop will repeat for each element of the series.
However, there's currently a difference between R2 and R3. In R2, if the value is a series, then the word holds the first value of each element of the series. In R3 it holds just the indexed series.
Editor note: Determine if this is intentional
REPEND¶
Appends a reduced value to a series and returns the series head.
Usage:
repend
ARGUMENTS: series [series! port! map! gob! object! bitset!] Series at point to insert (modified) value The value to insert REFINEMENTS: /part Limits to a given length or position length [number! series! pair!] /only Appends a block value as a block /dup Duplicates the insert a specified number of times count [number! pair!]
Description:
REPEND stands for REDUCE APPEND. It performs the same operation as APPEND (inserting elements at the tail of a series) but Reduces the block of inserted elements first. Just like APPEND, REPEND returns the head of the series.
For example, writing:
numbers: [1 2 3]
probe repend numbers [2 + 2 2 + 3 3 + 3]
[1 2 3 4 5 6]is the same as writing:
numbers: [1 2 3]
probe append numbers reduce [2 + 2 2 + 3 3 + 3]
[1 2 3 4 5 6]REPEND is very useful when you want to add to a series elements that need to be evaluated first. The example below creates a list of all the .r files in the current directory, along with their sizes and modification dates.
data: copy []
foreach file load %. [
if %.r = suffix? file [
repend data [file size? file modified? file]
]
]
probe data
[%build-docs.r 7915 13-Feb-2009/0:03:17.078 %bulk-modify.r 4210 7-Feb-2009/17:20:06.906 %cgi.r 5125 12-Feb-2009/20:54:51.578 %convert-orig.r 1112 7-Feb-2009/17:20:06.906 %emit-html.r 10587 13-Feb-2009/0:09:38.875 %eval-examples.r 2545 13-Feb-2009/1:46:59.765 %fix-args.r 416 13-Feb-2009/0:41:11.296 %funcs.r 1133 12-Feb-2009/18:54:32.875 %merge-funcs.r 1318 13-Feb-2009/0:42:03.718 %replace.r 197 7-Feb-2009/16:56:23 %scan-doc.r 3429 13-Feb-2009/0:05:33.062 %scan-titles.r 4402 12-Feb-2009/16:51:42.687 %strip-title.r 274 7-Feb-2009/17:20:06.953]When used with strings, repend is a useful way to join values. The example below is a common method of generating HTML web page code:
html: copy "<html><body>"
repend html [
"Date is: " now/date <P>
"Time is: " now/time <P>
"Zone is: " now/zone <P>
</body></html>
]
print html
<html><body>Date is: 12-Feb-2009<P>Time is: 17:47:54<P>Zone is: -8:00<P></body></html>REPLACE¶
Replaces a search value with the replace value within the target series.
Usage:
replace
ARGUMENTS: target [series!] Series to replace within (modified) search Value to be replaced (converted if necessary) replace Value to replace with (called each time if a function) REFINEMENTS: /all Replace all occurrences /case Case-sensitive replacement /tail Return target after the last replacement position
Description:
Searches target block or series for specified data and replaces it with data from the replacement block or series. Block elements may be of any datatype.
The /ALL refinement replaces all occurrences of the searched data in the target block or series.
str: "a time a spec a target"
replace str "a " "on "
print str
on ime a spec a target
replace/all str "a " "on "
print str
on ime on pec on arget
fruit: ["apples" "lemons" "bananas"]
replace fruit "lemons" "oranges"
print fruit
apples oranges bananas
numbers: [1 2 3 4 5 6 7 8 9]
replace numbers [4 5 6] ["four" "five" "six"]
print numbers
1 2 3 four five six 7 8 9REQUEST-DIR¶
Asks user to select a directory and returns full directory path (or block of paths).
Usage:
request-dir
REFINEMENTS: /title Change heading on request text [string!] /dir Set starting directory name [file!] /keep Keep previous directory path
REQUEST-FILE¶
Asks user to select a file and returns full file path (or block of paths).
Usage:
request-file
REFINEMENTS: /save File save mode /multi Allows multiple file selection, returned as a block /file Default file name or directory name [file!] /title Window title text [string!] /filter Block of filters (filter-name filter) list [block!]
Description:
Opens the standard operating system file requester to allow the user to select one or more files.
Details
The line:
file: request-filewill open the file requester and return a single file name as a full file path. This is normally used to read or load files.
If the user clicks CANCEL or closes the file requestor, a NONE is returned.
To open the file requester to save a file:
file: request-file/saveThis will change the text of the window to indicate that a save (write) will be done.
A default name can be provided for the file:
file: request-file/file %test.txtThis also works with the /save option, and a full path can be provided, in which case the requester will show the directory where the file will be found.
In addition, just a directory can be used:
file: request-file/file %/c/data/files/Be sure to include the terminating slash to indicate a directory. Otherwise it will be treated as a file.
To allow the selection of multiple files at the same time:
files: request-file/multi
foreach file files [print file]The result is returned as a block, and each file within the block is a full path.
You can also provide file list filters to show only specific files. For example:
file: request-file/filter [
"REBOL Scripts" "*.r"
"Text files" "*.txt"
]The /title refinement lets you modify the window title for the file requester to help make it more clear to users.
file: request-file/save/title "Save your data file"
either file [save file data] [print "data not saved"]REQUEST-PASSWORD¶
Asks user for input without echoing, and the entered password is not stored in the command history.
Usage:
request-password
RESIZE¶
Resizes an image to the given size.
Usage:
resize
ARGUMENTS: image [image!] Image to resize size [pair! percent! integer!] Size of the new image (integer value is used as width) REFINEMENTS: /filter Using given filter type (default is Lanczos) name [word! integer!] One of: system/catalog/filters /blur factor [number!] The blur factor where > 1 is blurry, < 1 is sharp
RESOLVE¶
Copy context by setting values in the target from those in the source.
Usage:
resolve
ARGUMENTS: target [any-object!] (modified) source [any-object!] REFINEMENTS: /only from [block! integer!] Only specific words (exports) or new words in target (index to tail) /all Set all words, even those in the target that already have a value /extend Add source words to the target if necessary
Description:
The resolve function is used to merge values from one context into another but avoids replacing existing values.
It is used mainly to support runtime environments, where newly exported functions must be merged into an existing lib context. Because lib can become quite large, performance must be optimized, which is the reason why resolve is a native function.
This example will help to show the basic concept:
obj1: object [a: 10]
obj2: object [b: 20]
append obj1 'b
resolve obj1 obj2
print obj1
a: 10
b: 20But notice:
obj1: object [a: 10]
obj2: object [a: 30 b: 20]
append obj1 'b
resolve obj1 obj2
print obj1
a: 10
b: 20So, resolve has no affect on values that have already been set in the target context.
Note that protected words will not be modified, they are ignored. No error occurs.
| /only | only affect word values that are provided in a block argument that follows this refinement. In addition, this refinement also supports a special optimization where you can indicate the index of the starting point for changes. That is useful with large contexts such as lib and others. |
| /all | forces resolve to change all values, not just those that are unset. This is similar to append on an object! except that the source is an object, not a block. |
| /extend | any words not found in the target context will be added. This eliminates the append step that was shown above (or a similar bind step). This refinement optimizes such operations. |
RETURN¶
Returns a value from a function.
Usage:
return
ARGUMENTS: value [any-type!]
Description:
Exits the current function immediately, returning a value as the result of the function. To return no value, use the EXIT function.
fun: make function! [this-time] [
return either this-time >= 12:00 ["after noon"][
"before noon"]
]
print fun 9:00
print fun 18:00REVERSE¶
Reverses the order of elements; returns at same position.
Usage:
reverse
ARGUMENTS: series [series! gob! tuple! pair!] At position (modified) REFINEMENTS: /part Limits to a given length or position range [number! series!]
Description:
Reverses the order of elements in a series or tuple.
blk: [1 2 3 4 5 6]
reverse blk
print blk
6 5 4 3 2 1The /PART refinement reverses the specified number of elements from the current index forward. If the number of elements specified exceeds the number of elements left in the series or tuple, the elements from the current index to the end will be reversed.
text: "It is possible to reverse one word in a sentence."
reverse/part (find text "reverse") (length? "reverse")
print text
It is possible to esrever one word in a sentence.Note that reverse returns the starting position it was given. (This change was made to newer versions.)
blk: [1 2 3 4 5 6]
print reverse/part blk 4
4 3 2 1 5 6Reverse also works for pairs and tuples:
print reverse 10x20
print reverse 1.2.3
3.2.1For tuple values the current index cannot be moved so the current index is always the beginning of the tuple.
print reverse 1.2.3.4
4.3.2.1
print reverse/part 1.2.3.4 2
4.3.2.1REWORD¶
Make a string or binary based on a template and substitution values.
Usage:
reword
ARGUMENTS: source [any-string! binary!] Template series with escape sequences values [map! object! block!] Keyword literals and value expressions REFINEMENTS: /case Characters are case-sensitive /only Use values as-is, do not reduce the block, insert block values /escape Choose your own escape char(s) or [begin end] delimiters char [char! any-string! binary! block! none!] Default "$" /into Insert into a buffer instead (returns position after insert) output [any-string! binary!] The buffer series (modified)
Description:
This is a general substitution function useful for building web pages, form letters, and other documents.
Work In Process
The block substitution abilities are still pending but string substitution works well now.
RGB-TO-HSV¶
Converts RGB value to HSV (hue, saturation, value)
Usage:
rgb-to-hsv
ARGUMENTS: rgb [tuple!]
RM¶
Send port a delete request.
Usage:
rm
ARGUMENTS: port [port! file! url! block!]
Description:
Note: Shell shortcut for delete.
ROUND¶
Rounds a numeric value; halves round up (away from zero) by default.
Usage:
round
ARGUMENTS: value [number! pair! money! time!] The value to round REFINEMENTS: /to Return the nearest multiple of the scale parameter scale [number! money! time!] Must be a non-zero value (result will be of this type) /even Halves round toward even results /down Round toward zero, ignoring discarded digits. (truncate) /half-down Halves round toward zero /floor Round in negative direction /ceiling Round in positive direction /half-ceiling Halves round in positive direction
Description:
"Rounding is meant to loose precision in a controlled way." -- Volker Nitsch
The round function is quite flexible. With the various refinements and the scale option, you can easily round in various ways. Most of the refinements are mutually exclusive--that is, you should use only one of them--the /to refinement is an obvious exception; it can be combined with any other refinement.
By default, round returns the nearest integer, with halves rounded up (away from zero).
probe round 1.4999
1
probe round 1.5
2
probe round -1.5
-2If the result of the rounding operation is a number! with no decimal component, and the SCALE value is not time! or money!, an integer will be returned. This makes it easy to use the result of ROUND directly with iterator functions such as LOOP and REPEAT.
The /TO refinment controls the "precision" of the rounding. That is, the result will be a multiple of the SCALE parameter. In order to round to a given number of decimal places, you don't pass in the number of decimal places, but rather the "level of precision" they represent. For example, to round to two decimal places, often used for money values, you would do this:
probe round/to $1.333 .01
$0.5558830792256812207833088To round to the nearest 1/8, often used for interest rates, you would do this:
probe round/to 1.333 .125
1.375To round to the nearst 1K increment (e.g. 1024 bytes):
probe round/to 123'456 1024
123904If the /TO refinement is used, and SCALE is a time! or money! value, the result will be coerced to that type. If SCALE is not used, or is not a time! or money! value, the datatype of the result will be the same as the valued being rounded.
The /EVEN refinement is designed to reduce bias when rounding large groups of values. It is sometimes called Banker's rounding, or statistical rounding. For cases where the final digit of a number is 5 (e.g. 1.5 or 15), the previous digit will be rounded to an even result (2, 4, etc.).
repeat i 10 [val: i + .5 print [val round/even val]]
10.5 10
repeat i 10 [val: i * 10 + 5 print [val round/even/to val 10]]
105 100The /DOWN refinement rounds toward zero, ignoring discarded digits. It is often called "truncate".
probe round/down 1.999
1
probe round/down -1.999
-1
probe round/down/to 1999 1000
1000
probe round/down/to 1999 500
1500The /HALF-DOWN refinement causes halves to round toward zero; by default they are rounded up.
probe round/half-down 1.5
1
probe round/half-down -1.5
-1
probe round/half-down 1.50000000001
2
probe round/half-down -1.50000000001
-2The /HALF-CEILING refinement causes halves to round in a positive direction; by default they are rounded up (away from zero). This works like the default behavior for positive values, but is not the same for negative values.
probe round -1.5
-2
probe round/half-ceiling -1.5
-1/FLOOR causes numbers with any decimal component to be rounded in a negative direction. It works like /DOWN for positive numbers, but not for negative numbers.
round/floor 1.999
round/floor -1.01
round/floor -1.00000000001/CEILING is the reverse of /FLOOR; numbers with any decimal component are rounded in a positive direction.
round/ceiling 1.01
round/ceiling 1.0000000001
round/ceiling -1.999If you are rounding extremely large numbers (e.g. 562'949'953'421'314), or using very high precision decimal values (e.g. 13 or more decimal places), you may run up against REBOL's native limits for values and its internal rounding rules. The ROUND function is a mezzanine and has no control over that behavior.
Sometimes, it might appear that ROUND is doing something strange, so before submitting a bug to RAMBO, think about what you're actually asking it to do. For example, look at the results from this piece of code:
repeat i 10 [
scale: .9 + (i * .01)
print [scale round/down/to 10.55 scale]
]
1.0 10.0The results approach 10.55 for values from 0.91 to 0.95, but then jump back when using values in the range 0.96 to 0.99. Those are the expected results, because you're truncating, that is, truncating to the nearest multiple of SCALE.
The design and development of the ROUND function involved many members of the REBOL community. There was much debate about the interface (one function with refinement versus individual functions for each rounding type, what words to use for parameter names, behavior with regards to type coercion).
RSA¶
Encrypt/decrypt/sign/verify data using RSA cryptosystem. Only one refinement must be used!
Usage:
rsa
ARGUMENTS: rsa-key [handle!] RSA context created using `rsa-init` function data [binary!] Data to work with. REFINEMENTS: /encrypt Use public key to encrypt data /decrypt Use private key to decrypt data /sign Use private key to sign data. Result is PKCS1 v1.5 binary /verify Use public key to verify signed data (returns TRUE or FALSE) signature [binary!] Result of the /sign call /hash Signature's message digest algorithm algorithm [word! none!]
RSA-INIT¶
Creates a context which is than used to encrypt or decrypt data using RSA
Usage:
rsa-init
ARGUMENTS: n [binary!] Modulus e [binary!] Public exponent REFINEMENTS: /private Init also private values d [binary!] Private exponent p [binary!] Prime number 1 q [binary!] Prime number 2
SAME?¶
Returns TRUE if the values are identical.
Usage:
same?
ARGUMENTS: value1 [any-type!] value2 [any-type!]
Description:
Returns TRUE if the values are identical objects, not just in value. For example, a TRUE would be returned if two strings are the same string (occupy the same location in memory). Returns FALSE for all other values.
a: "apple"
b: a
print same? a b
true
print same? a "apple"
falseSAVE¶
Saves a value, block, or other data to a file, URL, binary, or string.
Usage:
save
ARGUMENTS: where [file! url! binary! string! none!] Where to save (suffix determines encoding) value Value(s) to save REFINEMENTS: /header Provide a REBOL header block (or output non-code datatypes) header-data [block! object! logic!] Header block, object, or TRUE (header is in value) /all Save in serialized format /length Save the length of the script content in the header /compress Save in a compressed format or not method [logic! word!] true = compressed, false = not, 'script = encoded string
Description:
The save function is used to save REBOL code and data to a file, upload it to a URL, or store it into a local string.
When saving to a file or URL, the output of this function is always UTF-8 (an Unicode encoded format where ASCII is normal, but other characters are encoded.)
The format of the resulting output depends on what you need. The save function is designed to allow simple values to be easily saved to be loaded with load later:
save %date.r now
load %date.r
26-Feb-2009/13:06:15-8:00But, it also allows complex more complex data to be saved:
save %data.r reduce ["Data" 1234 %filename now/time]
load %data.r
["Data" 1234 %filename 13:07:15]
save %options.r system/options
load %options.r
make object! [
home: %/C/rebol/
script: none
path: %/C/rebol/
boot: %/C/rebol/view.exe
args: none
...In general, save performs the appropriate conversion and formatting to preserve datatypes. For instance, if the value is a REBOL block, it will be saved as a REBOL script that, when loaded, will be identical.
Editor note: saving /all
Editor note: saving with headers Note: Users must take care in how saved data is loaded. More on this below.
SCALAR?¶
Return TRUE if value is any type of scalar.
Usage:
scalar?
ARGUMENTS: value [any-type!]
Description:
Description is needed.
SCRIPT?¶
Checks file, url, or string for a valid script header.
Usage:
script?
ARGUMENTS: source [file! url! binary! string!]
Description:
If the header is found, the script string will be returned as of that point. If not found, then NONE is returned.
print either script? %file.txt ["found"]["not found"]SECOND¶
Returns the second value of a series.
Usage:
second
ARGUMENTS:
value
Description:
An error will occur if no value is found. Use the PICK function to avoid this error.
print second "REBOL"
E
print second [11 22 33 44 55 66]
22
print second 12-jun-1999
6
print second 199.4.80.1
4
print second 12:34:56.78
34SECURE¶
Set security policies (use SECURE help for more information).
Usage:
secure
ARGUMENTS: policy [word! lit-word! block! unset!] Set single or multiple policies (or HELP)
Description:
The secure function controls file, network, evaluation, and all other external access and related policies.
The function uses a simple dialect to specify security sandboxes and other options that allow or deny access. You can set different security levels and multiple sandboxes for networking and specific files and directories.
What can be controlled
The secure function gives you control over policies for:
| file | file read, write, and directory creation and listing |
| net | read and write access to the network interfaces |
| eval | limit the number of evaluation cycles allowed (always quits) |
| memory | limit the amount of memory used (always quits) |
| secure | control changes to security policies with secure |
| protect | protecting and hiding values with protect |
| debug | use of debug-related functions: trace and stack |
| envr | getting OS/shell environment variables with get-env |
| call | launching external programs with call |
| browse | opening the web browser with browse |
| extension | importing extensions (may contain native code) |
A list of these for your current release can always be obtained with the line:
secure query(Which will also show their current policy settings.)
Usage
The argument to the secure function can be a word or a block.
| word | a general, top-level action such as setting global security levels to allow or deny all access. It can also be used to query the current security policies. |
| block | specify separate security policies for files, directories, networking, extensions, debugging, and other features. |
If the argument is a word, it can be:
| help | summarize what policies can be set |
| query | show current policies |
| allow | remove all policies (no security) |
| none | the same as allow (no security) |
| ask | require user permission on all policies |
| throw | throw an error for all violations |
| quit | exit the program for all violations |
For example, developers often type:
secure noneto disable all security when developing new programs. However, use this with care. Do not run (or do) any programs other than those that you trust.
Another example is:
secure quitthe program will quit immediately if any security violation occurs. Of course, this is a little extreme, and you won't get far. You'll want to specify a block for greater control. See the next section.
To provide more detailed security, use a block:
secure [
net quit
file ask
%./ allow
]This block will:
- disable networking (force a quit if attempted)
- ask for user approval for all file access, except:
- allow access to the local directory
As you can see, the security dialect consists of a block of paired values. The first value in the pair specifies what is being secured (file or net), and the second value specifies the level of security (allow, ask, throw, quit). The second value can also be a block to further specify read and write security.
Security policies
The security policies are:
| allow | removes all READ and/or WRITE restrictions. |
| ask | restricts immediate READ and/or WRITE access and prompts the user for each access attempt, requiring approval before the operation may be completed. |
| throw | denies READ and/or WRITE access, throwing an error when a restricted access attempt is made. |
| quit | denies READ and/or WRITE access and quits the script when restricted access is attempted. |
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.
Access types
The access types allowed are:
| read | controls read access. |
| write | controls write, delete, and rename access. |
| execute | controls execute access. |
| all | controls all access. |
The pairs are processed in the order they appear, with later pairs modifying the effect of earlier pairs. This permits setting one type of access without explicitly setting all others. For example:
secure [
net allow
file [
ask all
allow read
quit execute
]
]The above sets the security level to ask for all operations except for reading (which is allowed).
This technique can also be used for individual files and directories. For example:
secure [
net allow
file quit
%source/ [ask read]
%object/ [allow all]
]will prompt the user if an attempt is made to read the %source directory, but it will allow all operations on the %object directory. Otherwise, it uses the default (quit).
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.
Querying security
The secure function 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 word query can also be used to obtain the current security settings without modifying them:
probe secure query
[file allow net allow ...]Using 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.
Securing security
Once you have your security policies set, it's a good idea to secure the secure function to prevent modifications. This is done in the same way as other policies.
For example:
secure [secure quit]will cause your program to immediately quit if any other code tries to modify the security policies.
User confirmation
Note that lowering the security level produces a change security settings requestor to the user. The exception is when the REBOL session is running in quiet mode which will, instead, terminate the REBOL session. No request is generated when security levels are raised. Note that the security request includes an option to allow all access for the remainder of the scripts processing.
Controlling security at startup
To disable all security on startup, you can start REBOL with:
rebol -s args...This policy allows open access for everything.
You can also use the --secure argument to specify any other default security level on startup.
Limiting evaluation (quota)
You can set secure to limit interpreter evaluation. This feature allows you to restrict server scripts (such as CGI) to a specific evaluation length to prevent runaway programs.
This example sets the limit to 50000 cycles, after which the program will immediately quit (the default behavior):
>> secure [eval 50000]
>> loop 100000 [next "test"]
<quit>
Also, for debugging you can use the more detailed form of
>> secure [eval [throw 50000]]
>> loop 100000 [next "test"]
** Access error: security violation: eval
** Where: loop
** Near: loop 100000 [next "test"]You can continue your debugging at the console, but secure will trap again on the next evaluation sample. To disable that behavior:
>> secure [eval allow]When tuning your program, to determine how many cycles your code needs, you can use:
>> stats/evals
== 50403However, add to that number a good margin of error for special conditions within your code. In many cases you will want to make it ten or twenty times larger, just to be sure.
A few notes:
- The maximum evaluation limit is 9e18.
- The evaluation limit can be set only once and cannot be reset. However, for debugging after an eval THROW exception, you can use
secure to disable the trap (use: [eval allow]). - The limit is approximate. It is sampled at regular intervals (to avoid slowing down evaluation.) The sampling period is 10000 cycles, so that is the resolution of the limit. For example, if you set the limit to 1, it won't trap an error until 10000.
- If the program quits, the exit code is set to 101, the same as any security termination; however, we may want to use special codes to indicate the reason for the quit.
- Some types of loops are not yet checked, but we will add them. For example, PARSE cycles are not yet counted.
- Time limits are not yet supported, but may be added in the future. However, the cycle limit is better for most cases, because it is CPU speed independent.
Limiting memory
You can set secure to limit the amount of memory allocated by your program. This feature allows you to restrict server scripts (such as CGI) to a specific memory usage to prevent runaway programs.
>> secure [memory 2'000'000]
>> strings: []
>> loop 100000 [append strings make string! 100'000]
<quit>This feature works the same way as the evaluation limit described above. Read that section for more details.
To determine how much memory your program has currently used:
>> stats
== 913616The number is shown in bytes.
In addition, it should be noted that the memory limit applies to actual memory consumed. Due to automatic memory allocation (garbage collection) it is possible for a program to run a indefinite amount of time on a specific amount of memory.
The memory limit can be set only once and cannot be reset. However, for debugging after an eval THROW exception, you can use
secure [memory allow]SELECT¶
Searches for a value; returns the value that follows, else none.
Usage:
select
ARGUMENTS: series [series! port! map! object! module! none!] value [any-type!] REFINEMENTS: /part Limits the search to a given length or position range [number! series! pair!] /only Treats a series value as only a single value /case Characters are case-sensitive /same Use "same?" as comparator /any Enables the * and ? wildcards /with Allows custom wildcards wild [string!] Specifies alternates for * and ? /skip Treat the series as records of fixed size size [integer!] /last Backwards from end of series /reverse Backwards from the current position
Description:
Similar to the find function, but returns the next value in the series rather than the position of the match. Returns NONE if search failed.
The /only refinement is evaluated for a block argument and is ignored if the argument is a string.
blk: [red 123 green 456 blue 789]
print select blk 'red
123
weather: [
"Ukiah" [clear 78 wind west at 5 MPH]
"Santa Rosa" [overcast 65 wind north at 10 MPH]
"Eureka" [rain 62 wind north at 15 MPH]
]
probe select weather "Eureka"
[rain 62 wind north at 15 MPH]SELFLESS?¶
Returns true if the context doesn't bind 'self.
Usage:
selfless?
ARGUMENTS: context [any-word! any-object!] A reference to the target context
SERIES?¶
Return TRUE if value is any type of series.
Usage:
series?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values.
print series? "string"
true
print series? [1 2 3]
true
print series? 1234
falseSET¶
Sets a word, path, block of words, or object to specified value(s).
Usage:
set
ARGUMENTS: word [word! lit-word! any-path! block! object!] Word, block of words, path, or object to be set (modified) value [any-type!] Value or block of values REFINEMENTS: /any Allows setting words to any value, including unset /only Block or object value argument is set as a single value /some None values in a block or object value argument, are not set
Description:
If the first argument is a block of words and the value is not a block, all of the words in the block will be set to the specified value. If the value is a block, then each of the words in the first block will be set to the respective values in the second block. If there are not enough values in the second block, the remaining words will be set to NONE
The /ANY refinement allows words to be set any datatype including those such as UNSET! that are not normally allowed. This is useful in situations where all values must be handled.
set 'test 1234
print test
1234
set [a b] 123
print a
123
print b
123
set [d e] [1 2]
print d
1
print e
2You can also use set-word! within the set function:
set [a: b:] [1 2]This is useful if you use the funct function, which auto-detects local variables that use the set-word notation.
SET-ENV¶
Sets the value of an OS environment variable (for current process).
Usage:
set-env
ARGUMENTS: var [any-string! any-word!] Variable to set value [string! none!] Value to set, or NONE to unset it
SET-PATH?¶
Returns TRUE if it is this type.
Usage:
set-path?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values.
if set-path? first [a/b/c: 10] [print "Path found"]
Path foundSET-SCHEME¶
Low-level port scheme actor initialization.
Usage:
set-scheme
ARGUMENTS: scheme [object!]
SET-USER¶
Initialize user's persistent data under system/user
Usage:
set-user
ARGUMENTS: name [word! ref! string! email! unset! none!] User's name REFINEMENTS: /p Password used to encrypt the data password [string! binary!] /f Use custom persistent data file location file [file!] /n Setup a user if does not exists
SET-WORD?¶
Returns TRUE if it is this type.
Usage:
set-word?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values.
if set-word? first [word: 10] [print "it will be set"]
it will be setSEVENTH¶
Returns the seventh value of a series.
Usage:
seventh
ARGUMENTS:
value
Description:
See the FIRST function for examples.
An error will occur if no value is found. Use the PICK function to avoid this error.
SHIFT¶
Shifts an integer left or right by a number of bits.
Usage:
shift
ARGUMENTS: value [integer!] bits [integer!] Positive for left shift, negative for right shift REFINEMENTS: /logical Logical shift (sign bit ignored)
Description:
Supports right or left bits shifts on integers.
SHIFT-LEFT¶
Shift bits to the left (unsigned).
Usage:
shift-left
ARGUMENTS: data [integer!] bits [integer!]
SHIFT-RIGHT¶
Shift bits to the right (unsigned).
Usage:
shift-right
ARGUMENTS: data [integer!] bits [integer!]
SHOW¶
Display or update a graphical object or block of them.
Usage:
show
ARGUMENTS: gob [gob! none! block!]
Description:
This is a low-level View function that is used to display or update a face. The face being displayed must be part of a pane that is part of a window display.
The SHOW function is called frequently to update the display of a face after changes have been made. If the face contains a pane of sub-faces, all of those faces will be redisplayed.
If you attempt to show a face and nothing happens, make sure that the face is part of the display hierarchy. That is, the face must be present in the pane list of another face that is being displayed.
For example, if you modify any of the attributes of a face, you call the SHOW function to display the change. The code below shows this:
view layout [
bx: box 100x24 black
button "Red" [bx/color: red show bx]
button "Green" [bx/color: green show bx]
]The example below creates a layout face and then removes faces from its pane. The SHOW function is called each time to refresh the face and display what has happened.
out: layout [
h1 "Show Example"
t1: text "Text 1"
t2: text "Text 2"
]
view/new out
wait 1
remove find out/pane t2
show out
wait 1
remove find out/pane t1
show out
wait 1
append out/pane t2
show out
wait 1
unviewSHOW-SOFT-KEYBOARD¶
Display on-screen keyboard for user input.
Usage:
show-soft-keyboard
REFINEMENTS: /attach gob [gob!] GOB which should be visible during the input operation
SIGN?¶
Returns sign of number as 1, 0, or -1 (to use as multiplier).
Usage:
sign?
ARGUMENTS: number [number! money! time!]
Description:
The SIGN? function returns a positive, zero, or negative integer based on the sign of its argument.
print sign? 1000
1
print sign? 0
0
print sign? -1000
-1The sign is returned as an integer to allow it to be used as a multiplication term within an expression:
val: -5
new: 2000 * sign? val
print new
-2000
size: 20
num: -30
if size > 10 [xy: 10x20 * sign? num]
print xy
-10x-20SIN¶
Returns the trigonometric sine.
Usage:
sin
ARGUMENTS: value [decimal!] In radians
SINE¶
Returns the trigonometric sine.
Usage:
sine
ARGUMENTS: value [number!] In degrees by default REFINEMENTS: /radians Value is specified in radians
Description:
Ratio between the length of the opposite side to the length of the hypotenuse of a right triangle.
print sine 90
1.0
print (sine 45) = (cosine 45)
true
print sine/radians pi
0.0SINGLE?¶
Returns TRUE if the series length is 1.
Usage:
single?
ARGUMENTS: series [series! port! map! tuple! bitset! object! gob! any-word!]
SIXTH¶
Returns the sixth value of a series.
Usage:
sixth
ARGUMENTS:
value
Description:
See the FIRST function for examples.
An error will occur if no value is found. Use the PICK function to avoid this error.
SIZE?¶
Returns the size of a file or vector (bits per value).
Usage:
size?
ARGUMENTS: target [file! url! port! vector!]
Description:
If the file or URL is a directory, it returns the number of entries in the directory.
print size? %file.txt
noneSKIP¶
Returns the series forward or backward from the current position.
Usage:
skip
ARGUMENTS: series [series! gob! port!] offset [number! logic! pair!]
Description:
For example, SKIP series 1 is the same as NEXT. If skip attempts to move beyond the head or tail it will be stopped at the head or tail.
str: "REBOL"
print skip str 3
OL
blk: [11 22 33 44 55]
print skip blk 3
44 55SORT¶
Sorts a series; default sort order is ascending.
Usage:
sort
ARGUMENTS: series [series!] At position (modified) REFINEMENTS: /case Case sensitive sort /skip Treat the series as records of fixed size size [integer!] Size of each record /compare Comparator offset or function comparator [integer! any-function!] /part Limits the sorting to a given length or position range [number! series!] /all Compare all fields /reverse Reverse sort order
Description:
Sorting will modify any type of series passed as the argument:
blk: [799 34 12 934 -24 0]
sort blk
print blk
-24 0 12 34 799 934
print sort "dbeca"
"abcde"Normally sorting is not sensitive to character cases:
sort ["Fred" "fred" "FRED"]
["fred" "FRED" "Fred"]But you can make it sensitive with the /CASE refinement:
sort/case ["Fred" "fred" "FRED"]
["FRED" "Fred" "fred"]Editor note: Sort bug here causes camel-case strings to be sorted incorrectly. When using the /SKIP refinement, you can treat the series as a set of records of a fixed size. Here we sort by a "name" column, while "age" is skipped:
name-ages: [
"Larry" 45
"Curly" 50
"Mo" 42
]
print sort/skip name-ages 2
Curly 50 Larry 45 Mo 42A /COMPARE function can be specified to perform the comparison. This allows you to change the ordering of the SORT:
names: [
"Larry"
"Curly"
"Mo"
]
print sort/compare names func [a b] [a < b]
Curly Larry MoThe /ALL refinement will force the entire record to be passed as a series to the compare function. This is useful if you need to compare one or more fields of a record while also doing a skip operation.
Editor note: Need a good working example. This may not be possible until remaining SORT bugs are fixed. When sorting pair! data (points and area sizes), the y coordinate is dominant. This is preferred to support the y sorting used by various graphics algorithms.
probe sort [1x2 2x1 0x0 1x0 0x1 1x1]
[0x0 1x0 0x1 1x1 2x1 1x2]SOURCE¶
Prints the source code for a word
Usage:
source
ARGUMENTS: word [word! path!]
Description:
The source function displays the source code for REBOL defined functions.
For example:
>> source joinjoin: make function! [[
"Concatenates values."
value "Base value"
rest "Value or block of values"
][
append either series? :value [copy value] [form :value] reduce :rest
]]
REBOL defined functions include the mezzanine functions (built-in interpreted functions) and user defined functions. Native functions have no source to display.
SPEC-OF¶
Returns a copy of the spec of any function, any object, vector, datatype or struct
Usage:
spec-of
ARGUMENTS: value [any-function! any-object! vector! datatype! struct!]
Description:
>> spec-of :join
== [
"Concatenates values."
value "Base value"
rest "Value or block of values"
]SPEED?¶
Returns approximate speed benchmarks [eval cpu memory file-io].
Usage:
speed?
REFINEMENTS:
/no-io Skip the I/O test
/times Show time for each test
SPLIT¶
Split a series into pieces; fixed or variable size, fixed number, or at delimiters
Usage:
split
ARGUMENTS: series [series!] The series to split dlm REFINEMENTS: /parts If dlm is an integer, split into n pieces, rather than pieces of length n. /at Split into 2, at the index position if an integer or the first occurrence of the dlm
Description:
The split function is used to divide a series into subcomponents. It provides several ways to specify how you want the split done.
Given an integer as the dlm parameter, split will break the series up into pieces of that size.
>> split "1234567812345678" 4
== ["1234" "5678" "1234" "5678"]If the series can't be evenly split, the last value will be shorter.
>> split "1234567812345678" 3
== ["123" "456" "781" "234" "567" "8"]
>> split "1234567812345678" 5
== ["12345" "67812" "34567" "8"]Given an integer as dlm, and using the /parts refinement, it breaks the series into n pieces, rather than pieces of length n.
>> split/parts [1 2 3 4 5 6] 2
== [[1 2 3] [4 5 6]]
>> split/parts "1234567812345678" 2
== ["12345678" "12345678"]If the series can't be evenly split, the last value will be longer.
>> split/parts "1234567812345678" 3
== ["12345" "67812" "345678"]
>> split/parts "1234567812345678" 5
== ["123" "456" "781" "234" "5678"]If dlm is a block containing only integer values, those values determine the size of each piece returned. That is, each piece can be a different size.
>> split [1 2 3 4 5 6] [2 1 3]
== [[1 2] [3] [4 5 6]]
>> split "1234567812345678" [4 4 2 2 1 1 1 1]
== ["1234" "5678" "12" "34" "5" "6" "7" "8"]
>> split first [(1 2 3 4 5 6 7 8 9)] 3
== [(1 2 3) (4 5 6) (7 8 9)]
>> split #{0102030405060708090A} [4 3 1 2]
== [#{01020304} #{050607} #{08} #{090A}]If the total of the dlm sizes is less than the length of the series, the extra data will be ignored.
>> split [1 2 3 4 5 6] [2 1]
== [[1 2] [3]]If you have extra dlm sizes after the series data is exhausted, you will get empty values.
>> split [1 2 3 4 5 6] [2 1 3 5]
== [[1 2] [3] [4 5 6] []]If the last dlm size would return more data than the series contains, it returns all the remaining series data, and no more.
>> split [1 2 3 4 5 6] [2 1 6]
== [[1 2] [3] [4 5 6]]Negative values can be used to skip in the series without returning that part:
>> split [1 2 3 4 5 6] [2 -2 2]
== [[1 2] [5 6]]Char or any-string values can be used for simple splitting, much as you would with "parse", but with different behavior for strings that have embedded quotes.
>> split "abc,de,fghi,jk" #","
== ["abc" "de" "fghi" "jk"]
>> split "abc<br>de<br>fghi<br>jk" <br>
== ["abc" "de" "fghi" "jk"]If you want to split at more than one character value, you can use a charset.
>> split "abc|de/fghi:jk" charset "|/:"
== ["abc" "de" "fghi" "jk"]Note that for greater control, you can use simple parse rules:
>> split "abc de fghi jk" [some #" "]
== ["abc" "de" "fghi" "jk"]SPLIT-LINES¶
Given a string series, split lines on CR-LF.
Usage:
split-lines
ARGUMENTS: value [string!]
SPLIT-PATH¶
Splits and returns directory path and file as a block.
Usage:
split-path
ARGUMENTS: target [file! url! string!]
Description:
Returns a block consisting of two elements, the path and the file. Can be used on URLs and files alike.
probe split-path %tests/math/add.r
[%tests/math/ %add.r]
set [path file] split-path http://www.rebol.com/graphics/logo.gif
print path
http://www.rebol.com/graphics/
print file
logo.gifSQRT¶
Returns the square root of a number.
Usage:
sqrt
ARGUMENTS: value [decimal!]
SQUARE-ROOT¶
Returns the square root of a number.
Usage:
square-root
ARGUMENTS: value [number!]
Description:
Returns the square-root of the number provided. If the number is negative, an error will occur (which you can trap with the TRY function).
print square-root 4
2.0
print square-root 2
1.414213562373095STACK¶
Returns stack backtrace or other values.
Usage:
stack
ARGUMENTS: offset [integer!] Relative backward offset REFINEMENTS: /block Block evaluation position /word Function or object name, if known /func Function value /args Block of args (may be modified) /size Current stack size (in value units) /depth Stack depth (frames) /limit Stack bounds (auto expanding)
Description:
No description provided.
STATS¶
Provides status and statistics information about the interpreter.
Usage:
stats
REFINEMENTS: /show Print formatted results to console /profile Returns profiler object /timer High resolution time difference from start /evals Number of values evaluated by interpreter /dump-series pool-id [integer!] Dump all series in pool pool-id, -1 for all pools
Description:
The STATS function returns a wide range of useful REBOL system statistics, including information about memory usage, interpreter cycles, and more.
If no refinement is provide, STATS returns the amount of memory that it is using. This value must be computed from tables.
The /pools refinement returns information about the memory pools that REBOL uses for managing its memory.
The /types refinement provides a summary of the number of each datatype currently allocated by the system.
foreach [type num] stats/types [
print [type num]
]The /series shows the number of series values, both string and block oriented, as free space, etc.
The /frames provides the number of context frames used for objects and functions.
The /recycle option summarizes garbage collection information.
The /evals provides counters for the number of interpreter cycles, functions invoked, and blocks evaluated.
The /clear refinement can be used with the /evals refinement to clear its counters.
stats/evals/clear
loop 100 [print "hello"]
print stats/evalsSTRICT-EQUAL?¶
Returns TRUE if the values are strictly equal.
Usage:
strict-equal?
ARGUMENTS: value1 [any-type!] value2 [any-type!]
Description:
Strict equality requires the values to not differ by datatype (so 1 would not be equal to 1.0) nor by character casing (so "abc" would not be equal to "ABC").
print strict-equal? 123 123
true
print strict-equal? "abc" "ABC"
falseSTRICT-NOT-EQUAL?¶
Returns TRUE if the values are not strictly equal.
Usage:
strict-not-equal?
ARGUMENTS: value1 [any-type!] value2 [any-type!]
Description:
Returns FALSE if the values neither differ by datatype (so 1 would not be equal to 1.0) nor by character casing (so "abc" would not be equal to "ABC").
print strict-not-equal? 124 123
true
print strict-not-equal? 12-sep-98 10:30
trueSTRING?¶
Returns TRUE if it is this type.
Usage:
string?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values.
print string? "with all things considered"
true
print string? 123
falseSTRUCT?¶
Returns TRUE if it is this type.
Usage:
struct?
ARGUMENTS: value [any-type!]
Description:
Returns TRUE if the value is a STRUCT datatype.
SU¶
Initialize user's persistent data under system/user
Usage:
su
ARGUMENTS: name [word! ref! string! email! unset! none!] User's name REFINEMENTS: /p Password used to encrypt the data password [string! binary!] /f Use custom persistent data file location file [file!] /n Setup a user if does not exists
SUBTRACT¶
Returns the second value subtracted from the first.
Usage:
subtract
ARGUMENTS: value1 [scalar! date! vector!] value2 [scalar! date! vector!]
Description:
Note: The + operator is a special infix form for this function.
Many different datatypes support subtraction. Here are just a few:
print subtract 123 1
122
print subtract 1.2.3.4 1.0.3.0
0.2.0.4
print subtract 12:00 11:00
1:00
print subtract 1-Jan-2000 1
31-Dec-1999When subtracting values of different datatypes, the values must be compatible. Auto conversion of the values will occur into the datatype that has the most expansive representation. For example an integer subtracted from a decimal will produce a decimal.
SUFFIX?¶
Return the file suffix of a filename or url. Else, NONE.
Usage:
suffix?
ARGUMENTS: path [file! url! string!]
Description:
The SUFFIX? function can be used to obtain the file extention (e.g. .exe, .txt, .jpg, etc.) that is part of a filename.
print suffix? %document.txt
.txt
print suffix? %program.exe
.exe
print suffix? %dir/path/doc.txt
.txt
print suffix? %file.type.r
.r
print suffix? http://www.rebol.com/doc.txt
.txtIf there is no suffix, a NONE is returned:
print suffix? %filename
noneThe suffix function can be used with any string datatype, but always returns a FILE! datatype if the suffix was found.
print type? suffix? %file.txt
file!
print type? suffix? "file.txt"
file!
print type? suffix? http://www.rebol.com/file.txt
file!This was done to allow code such as:
url: http://www.rebol.com/docs.html
if find [%.txt %.html %.htm %.doc] suffix? url [
print [url "is a document file."]
]
http://www.rebol.com/docs.html is a document file.SUM¶
Returns the sum of all values in a block
Usage:
sum
ARGUMENTS: values [block! vector! paren!]
SUPPLEMENT¶
Append value if not found; returns series at same position.
Usage:
supplement
ARGUMENTS: series [block!] (modified) value REFINEMENTS: /case Case-sensitive comparison
SWAP¶
Swaps elements between two series or the same series.
Usage:
swap
ARGUMENTS: series1 [series! gob!] At position (modified) series2 [series! gob!] At position (modified)
Description:
Description is needed.
SWAP-ENDIAN¶
Swaps byte order (endianness)
Usage:
swap-endian
ARGUMENTS: value [binary!] At position (modified) REFINEMENTS: /width bytes [integer!] 2, 4 or 8 (default is 2) /part Limits to a given length or position range [number! series!]
SWITCH¶
Selects a choice and evaluates the block that follows it.
Usage:
switch
ARGUMENTS: value Target value cases [block!] Block of cases to check REFINEMENTS: /default def Default case if no others found /all Evaluate all matches (not just first one) /case Perform a case-sensitive comparison
Description:
The switch function selects the block for a given choice and evaluates it.
For example:
switch 22 [
11 [print "here"]
22 [print "there"]
]
thereThis function is equivalent to writing a select like this:
do select [
11 [print "here"]
22 [print "there"]
] 22Variety of Datatypes
The selection choices can be of any datatype. Here are some examples:
file: %user.r
switch file [
%user.r [print "here"]
%rebol.r [print "everywhere"]
%file.r [print "there"]
]
here
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
tag: <title>
print switch html [
<pre> ["preformatted text"]
<title> ["page title"]
<li> ["bulleted list item"]
]
page titleCases Not Evaluated
It's very important to note that the choices are not evaluated (think of them as constants.) This allows the choices to be words, as shown below. If you need evaluation of the case values, use the case function instead.
person: 'mom
switch person [
dad [print "here"]
mom [print "there"]
kid [print "everywhere"]
]
thereThis most often becomes important when you want to switch based on a datatype value. You must be sure to use type? with a /word refinement:
val: 123
switch type?/word [
integer! [print "it's integer"]
decimal! [print "it's decimal"]
date! [print "it's a date"]
]
it's integerHere the type? function returns the word (name) of the datatype!, not the datatype's type value.
Another possible approach is to evaluate the block of cases. For the example above:
switch type? reduce [
integer! [print "it's integer"]
decimal! [print "it's decimal"]
date! [print "it's a date"]
]
it's integerThis works because words like integer! are set to their actual datatype values.
Default Case
You can use the /default refinement to specify a default case.
time: 14:00
switch/default time [
8:00 [send wendy@domain.dom "Hey, get up"]
12:30 [send cindy@dom.dom "Join me for lunch."]
16:00 [send group@every.dom "Dinner anyone?"]
][
print ["Nothing done at" time]
]
Nothing done at 14:00Return Value
The switch function returns the value of the case block that it evaluated, or none otherwise.
car: pick [Ford Chevy Dodge] random 3
print switch car [
Ford [351 * 1.4]
Chevy [454 * 5.3]
Dodge [154 * 3.5]
]
491.4Common Problems
The most common problem is to assume that switch evaluates your case values. It does not. This kind of code does not work:
item1: 100
item2: 200
n: 100
switch n [
item1 [...]
item2 [...]
]However, you can reduce the case block to its actual values:
switch n reduce [
item1 [...]
item2 [...]
]TAG?¶
Returns TRUE if it is this type.
Usage:
tag?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values.
print tag? <title>
true
print tag? "title"
falseTAIL¶
Returns the series just past its end.
Usage:
tail
ARGUMENTS: series [series! gob! port!]
Description:
Access to the tail allows insertion at the end of a series (because insertion always occurs before the specified element).
blk: copy [11 22 33]
insert tail blk [44 55 66]
print blk
11 22 33 44 55 66TAIL?¶
Returns TRUE if series is at or past its end; or empty for other types.
Usage:
tail?
ARGUMENTS: series [series! gob! port! bitset! typeset! map!]
Description:
This function is the best way to detect the end of a series while moving through it.
print tail? "string"
false
print tail? tail "string"
true
str: "Ok"
print tail? tail str
true
print tail? next next str
true
items: [oven sink stove blender]
while [not tail? items] [
print first items
items: next items
]
blender
blk: [1 2]
print tail? tail blk
true
print tail? next next blk
trueTAKE¶
Removes and returns one or more elements.
Usage:
take
ARGUMENTS: series [series! port! gob! none!] At the current position (modified) REFINEMENTS: /part Specifies a length or end position range [number! series! pair!] /deep Also copies series values within the block /last Takes from the tail end /all Copies the complete content of the series and then clears it
Description:
The take function removes a value from a series and returns it as the result. It's a useful combination of pick with remove.
For example, used on blocks:
data: [a b c d]
take data
a
probe data
[b c d]Used on strings:
str: "abcd"
take str
#"a"
probe str
"bcd"For Queues and Stacks
The take function is quite useful for making queues and stacks.
An example queue is implemented as first in first out (FIFO) block. New values are added with append and removed with take.
data: make block! 10
append data 1
append data 2
append data 3
take data
1
take data
2An example stack is implemented as last in first out (LIFO). The difference is to use the /last refinement with take.
data: make block! 10
append data 1
append data 2
append data 3
take/last data
3
take/last data
2The data queued and stacked above can be any REBOL values, including string, functions, objects or whatever.
TAN¶
Returns the trigonometric tangent.
Usage:
tan
ARGUMENTS: value [decimal!] In radians
TANGENT¶
Returns the trigonometric tangent.
Usage:
tangent
ARGUMENTS: value [number!] In degrees by default REFINEMENTS: /radians Value is specified in radians
Description:
Ratio between the length of the opposite side to the length of the adjacent side of a right triangle.
print tangent 30
0.5773502691896257
print tangent/radians 2 * pi
0.0TASK¶
Creates a task.
Usage:
task
ARGUMENTS: spec [block!] Name or spec block body [block!] The body block of the task
Description:
Description is needed.
TASK?¶
Returns TRUE if it is this type.
Usage:
task?
ARGUMENTS: value [any-type!]
Description:
No description provided.
TENTH¶
Returns the tenth value of a series.
Usage:
tenth
ARGUMENTS:
value
Description:
See the FIRST function for examples.
An error will occur if no value is found. Use the PICK function to avoid this error.
THIRD¶
Returns the third value of a series.
Usage:
third
ARGUMENTS:
value
Description:
An error will occur if no value is found. Use the PICK function to avoid this error.
print third "REBOL"
B
print third [11 22 33 44 55 66]
33
print third 12-jun-1999
12
print third 199.4.80.1
80
print third 12:34:56.78
56.78THROW¶
Throws control back to a previous catch.
Usage:
throw
ARGUMENTS: value [any-type!] Value returned from catch REFINEMENTS: /name Throws to a named catch word [word!]
Description:
CATCH and THROW go together. They provide a method of exiting from a block without evaluating the rest of the block. To use it, provide CATCH with a block to evaluate. If within that block a THROW is evaluated, the script will return from the CATCH at that point. The result of the CATCH will be the value that was passed as the argument to the THROW. When using multiple CATCH functions, provide them with a name to identify which one will CATCH which THROW.
print catch [
if exists? %file.txt [throw "Doc file!"]
]
noneTIME?¶
Returns TRUE if it is this type.
Usage:
time?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values.
print time? 12:00
true
print time? 123
falseTINT¶
Mixing colors (tint and or brightness)
Usage:
tint
ARGUMENTS: target [tuple! image!] Target RGB color or image (modifed) rgb [tuple!] Color to use for mixture amount [number!] Effect amount
TITLE-OF¶
Returns a copy of the title of any function, datatype or module
Usage:
title-of
ARGUMENTS: value [any-function! datatype! module!]
Description:
>> title-of :print
== "Outputs a value followed by a line break."TO¶
Converts to a specified datatype.
Usage:
to
ARGUMENTS: type [any-type!] The datatype or example value value [any-type!] The attributes of the new value
Description:
Every datatype provides a TO method to allow conversions from other datatypes. The to-binary, to-block, and all other to- functions are mezzanine functions that are based on this TO function.
Here are a few examples:
probe to file! "test.r"
%test.r
probe to path! [a b c]
a/b/cThe TO function lets the target datatype be specified as an argument, allowing you to write code such as:
flag: true
value: to either flag [integer!][decimal!] "123"
print value
123The conversions that are allowed depend on the specific datatype. Some datatypes allow special conversions, such as:
print to integer! false
0
print to integer! true
1
print to logic! 1
true
print to time! 600 ; # of seconds
0:10TO-BINARY¶
Converts to binary! value.
Usage:
to-binary
ARGUMENTS:
value
Description:
Returns a binary! value made from the given value.
probe to-binary "123456"
#{313233343536}Notice, that the binary returned is not how the "actual storage" in computer memory looks. Instead, the bits are in "network order", which is, by convention, big endian:
to-binary 1
#{0000000000000001}TO-BITSET¶
Converts to bitset! value.
Usage:
to-bitset
ARGUMENTS:
value
Description:
Returns a bitset! value made from the given value.
probe to-bitset [#"a" - #"z" #"A" - #"Z"]
make bitset! #{00000000000000007FFFFFE07FFFFFE0}TO-BLOCK¶
Converts to block! value.
Usage:
to-block
ARGUMENTS:
value
Description:
Returns a block! value made from the given value.
NOTE: The behavior of this function differs from Rebol2 and Red! Conversions using to from non-blocks only wrap the value in a block of the specified type. Use make if you expect tokenization!
>> to-block "123 10:00"
== ["123 10:00"] ;; no tokenization!
>> make block! "123 10:00"
== [123 10:00]For conversions from another block-like type, one can use the as function, which coerces the original value to another type without creating a new one.
>> path: 'hello/world
== hello/world
>> blk: as block! path
== [hello world] ;; this value has coerced type
>> insert next blk 'cruel
== [world]
>> path
== hello/cruel/world ;; original value was modified too
>> append to-block path 42
== [hello cruel world 42] ;; this is new series value!
>> path
== hello/cruel/world ;; original value was not modifiedTO-CHAR¶
Converts to char! value.
Usage:
to-char
ARGUMENTS:
value
Description:
Returns a char! value made from the given value.
>> to-char "a"
== #"a"
>> to-char 65
== #"A"TO-CLOSURE¶
Converts to closure! value.
Usage:
to-closure
ARGUMENTS:
value
Description:
No description provided.
TO-COMMAND¶
Converts to command! value.
Usage:
to-command
ARGUMENTS:
value
TO-DATATYPE¶
Converts to datatype! value.
Usage:
to-datatype
ARGUMENTS:
value
Description:
Can be used to convert a word! containing a valid datatype name into a datatype!.
>> to-datatype 'integer!
== #(integer!)
>> type? to-datatype 'integer!
== #(datatype!)
>> to-datatype "foo"
** Script error: cannot MAKE #(datatype!) from: "foo"TO-DATE¶
Converts to date! value.
Usage:
to-date
ARGUMENTS: value [any-type!] May be also a standard Internet date string/binary REFINEMENTS: /utc Returns the date with UTC zone
Description:
Returns a date! value made from the given value.
>> to-date "12-April-1999"
== 12-Apr-1999Also accepts a string in the Internet Message Date format (RFC2822).
>> to-date "Mon, 1 Apr 2019 21:50:04 GMT"
== 1-Apr-2019/21:50:04
>> to-date "Thu, 28 Mar 2019 20:00:59 +0100"
== 28-Mar-2019/20:00:59+1:00When the input is of type integer! or decimal!, it is treated as a Unix timestamp.
>> to-date 123456789
== 29-Nov-1973/21:33:09
>> encode 'unixtime 29-Nov-1973/21:33:09
== 123456789
>> to-date 1741600660.239
== 10-Mar-2025/9:57:40.239TO-DECIMAL¶
Converts to decimal! value.
Usage:
to-decimal
ARGUMENTS:
value
Description:
Returns a decimal! value made from the given value.
>> to-decimal 1
== 1.0
>> to-decimal 10-Mar-2025/9:57:40.239
== 1741600660.239 ;; Unix timestamp with a precisionTO-DEGREES¶
Converts radians to degrees
Usage:
to-degrees
ARGUMENTS: radians [integer! decimal!] Radians to convert
Description:
>> to-degrees pi
== 180.0TO-EMAIL¶
Converts to email! value.
Usage:
to-email
ARGUMENTS:
value
Description:
Returns an email! value made from the given value.
print to-email [luke rebol.com]
lukerebol.comTO-ERROR¶
Converts to error! value.
Usage:
to-error
ARGUMENTS:
value
Description:
Returns an error! value made from the given value.
probe disarm try [to-error "Oops! My error."]
make object! [
code: 308
type: 'Script
id: 'cannot-use
arg1: 'to
arg2: unset!
arg3: none
near: [to error! :value]
where: [to to-error try do attempt if emit parse foreach catch if either if do begin do]
Note that this differs from TO and MAKE in that you have to wrap the call in a TRY block to catch the error it makes.
TO-EVENT¶
Converts to event! value.
Usage:
to-event
ARGUMENTS:
value
Description:
No description provided.
TO-FILE¶
Converts to file! value.
Usage:
to-file
ARGUMENTS:
value
Description:
Returns a file! value made from the given value.
>> to-file "test.txt"
== %test.txtTO-FUNCTION¶
Converts to function! value.
Usage:
to-function
ARGUMENTS:
value
Description:
>> fun: to-function [[a][a * 10]]
>> fun 1
== 10TO-GET-PATH¶
Converts to get-path! value.
Usage:
to-get-path
ARGUMENTS:
value
Description:
Returns a get-path! value made from the given value.
>> to-get-path [path to word]
== :path/to/wordTO-GET-WORD¶
Converts to get-word! value.
Usage:
to-get-word
ARGUMENTS:
value
Description:
Returns a get-word! value made from the given value.
probe to-get-word "test"
:testTO-GOB¶
Converts to gob! value.
Usage:
to-gob
ARGUMENTS:
value
Description:
No description provided.
TO-HASH¶
Converts to hash! value.
Usage:
to-hash
ARGUMENTS:
value
TO-HEX¶
Converts numeric value to a hex issue! datatype (with leading # and 0's).
Usage:
to-hex
ARGUMENTS: value [integer! tuple!] Value to be converted REFINEMENTS: /size Specify number of hex digits in result len [integer!]
Description:
The TO-HEX function provides an easy way to convert an integer to a hexidecimal value.
>> to-hex 123
== #000000000000007BThe value returned is a string of the ISSUE datatype (not the BINARY datatype). This allows you to convert hex values back to integers:
>> to-integer #7B
== 123Note: To convert HTML hex color values (like #80FF80) to REBOL color values, it is easier to do the conversion to binary and then use a base 16 encoding:
to-html-color: func [color [tuple!]] [
to-issue enbase to-binary color 16
]
print to-html-color 255.155.50
FF9B32The TO-ISSUE function is just used to add the # to it.
To convert from an HTML color back to a REBOL color tuple, you can use this:
to-rebol-color: func [color [issue!]] [
to-tuple debase color 16
]
to-rebol-color #FF9B32If the HTML color value is a string, convert it to an issue first. The function below will work for strings and issues:
to-rebol-color2: func [color [string! issue!]] [
if string? color [
if find/match color "#" [color: next color]
color: to-issue color
]
to-tuple debase color 16
]
to-rebol-color2 "#FF9B32"TO-IDATE¶
Returns a standard Internet date string.
Usage:
to-idate
ARGUMENTS: date [date!] REFINEMENTS: /gmt Converts local time to GMT (Greenwich Mean Time)
TO-IMAGE¶
Converts to image! value.
Usage:
to-image
ARGUMENTS:
value
Description:
This is a special conversion function that is used for converting a FACE object (such as those created by the layout function) into an image bitmap in memory.
For example, the code below converts the OUT layout to a bitmap image, then writes it out as a PNG file:
out: layout [
h2 "Title"
field
button "Done"
]
image: to-image out
save/png %test-image.png imageThis function provides a useful way to save REBOL generated images for use in other programs or web pages (which also allows you to print the images). For example, you can display the image above in a web browser with this code:
write %test-page.html trim/auto {
<html><body>
<h2>Image:</h2>
<img src="test-image.png">
</body></html>
}
browse %test-page.html
writeTO-INTEGER¶
Converts to integer! value.
Usage:
to-integer
ARGUMENTS:
value
Description:
Returns an integer! value made from the given value.
print to-integer "123"
123
print to-integer 123.9
123
print to-integer #"A" ; convert to the character value
65
print to-integer #102030 ; convert hex value (see to-hex for info)
1056816TO-ISSUE¶
Converts to issue! value.
Usage:
to-issue
ARGUMENTS:
value
Description:
Returns an issue! value made from the given value.
print to-issue "1234-56-7890"
1234-56-7890To convert HTML RGB color values (that look like #000000), see the to-hex function.
TO-ITIME¶
Returns a standard internet time string (two digits for each segment)
Usage:
to-itime
ARGUMENTS: time [time! number! block! none!]
Description:
>> to-itime now/time
== "09:46:03"TO-JSON¶
Convert Rebol data to a JSON string
Usage:
to-json
ARGUMENTS: data REFINEMENTS: /pretty indent [string!] Pretty format the output, using given indentation /ascii Force ASCII output (instead of UTF-8)
Description:
>> to-json #[a: 1 b: ["hello"]]
== {{"a":1,"b":["hello"]}}to-json is basically the same as using encode
>> encode 'json #[a: 1 b: ["hello"]]
== {{"a":1,"b":["hello"]}}But it provides easy option for producing nicely formatted output.
>> to-json/pretty #[a: 1 b: ["hello"]] " "
== {{
"a": 1,
"b": [
"hello"
]
}}TO-LIT-PATH¶
Converts to lit-path! value.
Usage:
to-lit-path
ARGUMENTS:
value
Description:
Returns a lit-path! value made from the given value.
>> to-lit-path [a b c]
== 'a/b/cTO-LIT-WORD¶
Converts to lit-word! value.
Usage:
to-lit-word
ARGUMENTS:
value
Description:
Returns a ilt-word! value made from the given value.
>> to-lit-word "test"
== 'testTO-LOCAL-FILE¶
Converts a REBOL file path to the local system file path.
Usage:
to-local-file
ARGUMENTS: path [file! string!] REFINEMENTS: /full Prepends current dir for full path (for relative paths only)
Description:
This function provides a way to convert standard, system independent REBOL file formats into the file format used by the local operating system.
probe to-local-file %/c/temp
"c:\temp"
probe to-local-file what-dir
"C:\REBOL\3.0\docs\scripts\"Note that the format of the file path depends on your local system. Be careful how you use this function across systems.
TO-LOGIC¶
Converts to logic! value.
Usage:
to-logic
ARGUMENTS:
value
Description:
Returns a logic! value made from the given value.
print to-logic 1
print to-logic 0
falseTO-MAP¶
Converts to map! value.
Usage:
to-map
ARGUMENTS:
value
Description:
>> to-map [a: 1 b: 2]
== #[
a: 1
b: 2
]TO-MODULE¶
Converts to module! value.
Usage:
to-module
ARGUMENTS:
value
Description:
TO-MONEY¶
Converts to money! value.
Usage:
to-money
ARGUMENTS:
value
Description:
Returns a money! value made from the given value.
>> to-money 123.4
== $123.4NOTE: Currency types are not supported yet!
TO-OBJECT¶
Converts to object! value.
Usage:
to-object
ARGUMENTS:
value
Description:
This function currently works only for conversions from an error! value.
>> to-object try [1 / 0]
== make object! [
code: 400
type: 'Math
id: 'zero-divide
arg1: #(none)
arg2: #(none)
arg3: #(none)
near: [/ 0]
where: [/ try]
]TO-PAIR¶
Converts to pair! value.
Usage:
to-pair
ARGUMENTS:
value
Description:
Returns a pair! value made from the given value.
>> to-pair [120 50]
== 120x50
>> x: 100 y: 50
>> to-pair reduce [x y]
== 100x50This last line is done so often that the as-pair function was created.
>> as-pair x y
== 100x50TO-PAREN¶
Converts to paren! value.
Usage:
to-paren
ARGUMENTS:
value
Description:
Returns a paren! value made from the given value.
NOTE: The behavior of this function differs from Rebol2 and Red! Conversions using to from non-blocks only wrap the value in a block of the specified type. Use make if you expect tokenization!
>> to-paren "123 456"
== ("123 456")
>> make paren! "123 456"
== (123 456)For conversions from another block-like type, one can use the as function, which coerces the original value to another type without creating a new one.
>> blk: ["hello" "world"]
== ["hello" "world"]
>> par: as paren! blk
== ("hello" "world")
>> uppercase par/2
== "WORLD"
>> blk
== ["hello" "WORLD"]TO-PATH¶
Converts to path! value.
Usage:
to-path
ARGUMENTS:
value
Description:
Returns a path! value made from the given value.
colors: make object! [reds: ["maroon" "brick" "sunset"]]
p-reds: to-path [colors reds]
print form :p-reds
colors/reds
print p-reds
colors/reds
insert tail p-reds "bright"
print colors/reds
maroon brick sunset
print p-reds
colors/reds/"bright"TO-PERCENT¶
Converts to percent! value.
Usage:
to-percent
ARGUMENTS:
value
Description:
No description provided.
TO-PORT¶
Converts to port! value.
Usage:
to-port
ARGUMENTS:
value
Description:
Returns a port! value made from the given value.
probe to-port [scheme: 'checksum]TO-RADIANS¶
Converts degrees to radians
Usage:
to-radians
ARGUMENTS: degrees [integer! decimal!] Degrees to convert
Description:
>> to-radians 180.0
== 3.14159265358979TO-REAL-FILE¶
Returns canonicalized absolute pathname. On Posix resolves symbolic links and returns NONE if file does not exists!
Usage:
to-real-file
ARGUMENTS: path [file! string!]
Description:
>> to-real-file %../Rebol
== %/C/Users/oldes/Rebol/
>> to-real-file ".."
== %/C/Users/oldes/TO-REBOL-FILE¶
Converts a local system file path to a REBOL file path.
Usage:
to-rebol-file
ARGUMENTS: path [file! string!]
Description:
This function provides a standard way to convert local operating system files into REBOL's standard machine independent format.
>> to-rebol-file %../Rebol
== %../Rebol
>> to-rebol-file "../Rebol"
== %../Rebol
>> to-rebol-file "C:\Program Files\"
== %/C/Program%20Files/Note that the format of the file path depends on your local system. Be careful how you use this function across systems.
TO-REF¶
Converts to ref! value.
Usage:
to-ref
ARGUMENTS:
value
Description:
Returns a ref! value made from the given value.
>> to-ref "Oldes"
== @OldesTO-REFINEMENT¶
Converts to refinement! value.
Usage:
to-refinement
ARGUMENTS:
value
Description:
Returns a refinement! value made from the given value.
>> to-refinement 'REBOL
== /REBOLTO-RELATIVE-FILE¶
Returns the relative portion of a file if in a subdirectory, or the original if not.
Usage:
to-relative-file
ARGUMENTS: file [file! string!] File to check (local if string!) REFINEMENTS: /no-copy Don't copy, just reference /as-rebol Convert to REBOL-style filename if not /as-local Convert to local-style filename if not
Description:
>> what-dir
== %/C/Users/oldes/Rebol/
>> to-relative-file %/C/Users/Oldes/Rebol/temp
== %tempTO-SET-PATH¶
Converts to set-path! value.
Usage:
to-set-path
ARGUMENTS:
value
Description:
Returns a set-path! value made from the given value.
>> to-set-path [some path]
== some/path:TO-SET-WORD¶
Converts to set-word! value.
Usage:
to-set-word
ARGUMENTS:
value
Description:
Returns a set-word! value made from the given value.
>> to-set-word "test"
== test:TO-STRING¶
Converts to string! value.
Usage:
to-string
ARGUMENTS:
value
Description:
Returns a string! value made from the given value.
>> to-string [123 456]
== "123456"TO-TAG¶
Converts to tag! value.
Usage:
to-tag
ARGUMENTS:
value
Description:
Returns a tag! value made from the given value.
>> to-tag ";comment:"
== <;comment:>TO-TIME¶
Converts to time! value.
Usage:
to-time
ARGUMENTS:
value
Description:
Returns a time! value made from the given value.
Integer and decimal values are interpreted as a number of seconds.
>> to-time 75
== 0:01:15
>> to-time 75.5
== 0:01:15.5A block may contain up to three values. The first two must be integers, and correspond to the hour and minute values. The third value can be an integer or decimal value, and corresponds to the number of seconds.
>> to-time [0 1 15.5]
== 0:01:15.5TO-TUPLE¶
Converts to tuple! value.
Usage:
to-tuple
ARGUMENTS:
value
Description:
Returns a tuple! value made from the given value.
>> to-tuple [12 34 56]
== 12.34.56To convert REBOL RGB color tuples to HTML hex color values, see the to-hex function.
Tuples can have up to 12 segments.
TO-TYPESET¶
Converts to typeset! value.
Usage:
to-typeset
ARGUMENTS:
value
Description:
Returns a typeset! value made from the given value.
>> types: to-typeset [string! file! url!]
== make typeset! [string! file! url!]
>> find types #(url!)
== #(true)TO-URL¶
Converts to url! value.
Usage:
to-url
ARGUMENTS:
value
Description:
Returns a url! value made from the given value.
>> to-url "http://www.rebol.com"
== http://www.rebol.comTO-VALUE¶
Returns the value if it is a value, NONE if unset.
Usage:
to-value
ARGUMENTS: value [any-type!]
Description:
>> to-value ()
== #(none)
>> to-value 1
== 1
>> to-value #(unset)
== #(none)TO-VECTOR¶
Converts to vector! value.
Usage:
to-vector
ARGUMENTS:
value
Description:
Currently, to-vector can only be used with a valid vector specification.
>> to-vector [uint8! 3]
== make vector! [unsigned integer! 8 3 [0 0 0]]
>> to-vector [int16! [1 2 3]]
== make vector! [integer! 16 3 [1 2 3]]Vectors can be created using construction syntax.
>> #(uint8! 3)
== make vector! [unsigned integer! 8 3 [0 0 0]]
>> #(int16! [1 2 3])
== make vector! [integer! 16 3 [1 2 3]]Currently there are these vector types: * Signed integers: int8!, int16!, int32!, int64! * Unsigned integers: uint8!, uint16!, uint32!, uint64! * 32bit decimal: float! * 64bit decimal: double!
TO-WORD¶
Converts to word! value.
Usage:
to-word
ARGUMENTS:
value
Description:
Returns a word! value made from the given value.
>> to-word "test"
== testTRACE¶
Enables and disables evaluation tracing and backtrace.
Usage:
trace
ARGUMENTS: mode [integer! logic!] REFINEMENTS: /back Set mode ON to enable or integer for lines to display /function Traces functions only (less output)
Description:
The trace lets you watch the evaluation of your script, expression by expression.
The three most common arguments to trace are shown here:
trace on ; turn on trace
trace off ; turn off trace
trace 5 ; turn on, but trace only 5 levels deepOnce enabled, when you evaluate an expression, you will see each step as a single line:
>> print 123
1: print : native! [value]
2: 123
--> print
123
<-- print == unset!Understanding the format
The trace format uses these formatting notations to indicate what your code is doing:
| Notation | Meaning |
|---|---|
| (indent) | The indentation for each line indicates the depth of the code. |
|
N:
| The index number of the value in the code block (that is to be evaluated.) |
|
-->
| Entry into a function, followed by its formal argument list. |
|
<--
| Return from a function, followed by the value it returned (==). |
To help understand the format, here's a description for each line in the earlier example:
| Code | Meaning |
|---|---|
|
>> print 123
| Typed into the console to evaluate. |
|
1: print : native! [value]
| The value at block index 1 is the word print. It's value is looked up and found to be a native! function that takes value as an argument. |
|
2: 123
| The value at block index 2 is the integer 123. |
|
--> print
| The argument is valid and the print function is entered. The --> means "enter into the function." |
|
123
| Output is printed. |
|
<-- print == unset!
| The print function returns, but it has no return value (it is unset.) The <-- means "return from the function." |
Here is a user defined function to compute the average of a block of numbers.
ave: func [nums [block!] /local val][
val: 0
foreach num nums [val: val + num]
val / length? nums
]Tracing the evaluation, you will see how each new level is indented and begins a new sequence of index numbers. Notice also the foreach loop.
>> ave [1 2 3]
1: ave : function! [nums /local val]
2: [1 2 3]
--> ave
1: val:
2: 0
3: foreach : native! ['word data body]
5: nums : [1 2 3]
6: [val: val + num]
--> foreach
1: val:
2: val : 0
3: + : op! [value1 value2]
4: num : 1
--> +
<-- + == 1
1: val:
2: val : 1
3: + : op! [value1 value2]
4: num : 2
--> +
<-- + == 3
1: val:
2: val : 3
3: + : op! [value1 value2]
4: num : 3
--> +
<-- + == 6
<-- foreach == 6
7: val : 6
8: / : op! [value1 value2]
9: length? : action! [series]
10: nums : [1 2 3]
--> length?
<-- length? == 3
--> /
<-- / == 2
<-- ave == 2
== 2Minimizing the output
At times the trace output will be a lot more than you want. The trick becomes how to cut it down without losing the information you need.. There are three methods:
- Specify a trace depth.
- Locate the trace on and off lines deeper within your code.
- Trace only functions, not all values.
- Use the backtrace option. (see more below)
Using the example above, set the trace depth to 2, and run it again. You will see:
>> trace 2
>> ave [1 2 3]
1: ave : function! [nums /local val]
2: [1 2 3]
--> ave
1: val:
2: 0
3: foreach : native! ['word data body]
5: nums : [1 2 3]
6: [val: val + num]
--> foreach
<-- foreach == 6
7: val : 6
8: / : op! [value1 value2]
9: length? : action! [series]
10: nums : [1 2 3]
--> length?
<-- length? == 3
--> /
<-- / == 2
<-- ave == 2
== 2The output has been reduced. You no longer see the foreach loop operate.
Most of the time you don't need to trace your entire program, just part of it. So, it is useful just to put trace in your code where you need it.
Using the same example as above:
ave: func [nums [block!] /local val][
val: 0
trace on
foreach num nums [val: val + num]
trace off
val / length? nums
]You will now see:
>> ave [1 2 3]
<-- trace == unset!
5: foreach : native! ['word data body]
7: nums : [1 2 3]
8: [val: val + num]
--> foreach
1: val:
2: val : 0
3: + : op! [value1 value2]
4: num : 1
--> +
<-- + == 1
1: val:
2: val : 1
3: + : op! [value1 value2]
4: num : 2
--> +
<-- + == 3
1: val:
2: val : 3
3: + : op! [value1 value2]
4: num : 3
--> +
<-- + == 6
<-- foreach == 6
9: trace : native! [mode /back]
10: off : false
--> trace
== 2With the /function refinement you can trace just function calls and their returns. The evaluation of each code block value is not shown, saving a few lines.
>> trace/function on
>> ave [1 2 3]
--> ave [1 2 3] . .
--> foreach num [1 2 3] [val: val + num]
--> + 0 1
<-- + == 1
--> + 1 2
<-- + == 3
--> + 3 3
<-- + == 6
<-- foreach == 6
--> length? [1 2 3]
<-- length? == 3
--> / 6 3
<-- / == 2
<-- ave == 2In this mode, the function call lines will show the arguments passed to the functions. (A dot is used to show NONE value slots, such as those for unused refinements or local variables.)
Backtrace
At times it is important to know what your code was doing immediately before a crash. In such cases, you don't want to see trace output until after the crash. That is the purpose of the /back refinement: to tell trace to redirect its output to an internal buffer that you can examine later.
To enable backtrace:
>> trace/back onThen, run your code. When your crash occurs, type:
>> trace/back 20to see the last 20 lines (or however many lines you want to see.)
You can also modify your trace depth as you would normally. For example:
>> trace/back on
>> trace 5will only trace down five levels of code.
When you are done with the backtrace, you can disable it with:
>> trace/back offand that will also free memory used by the backtrace buffer.
To use backtrace with the /function refinement:
>> trace/back/function onThis will also speed-up trace evaluation.
Here is an example session:
>> trace/back on
>> test: func [a] [if integer? a [loop a [bug]]]
>> test 10
** Script error: bug has no value
** Where: loop if test
** Near: loop a [bug]
>> trace/back 10
--> if
1: loop : native! [count block]
2: a : 10
3: [bug]
--> loop
1: bug : unset!
**: error : Script no-value
1: trace/back
2: 20
--> traceSo, it's not hard to see what was going on when the script crashed. Backtrace can be quite handy when you need it.
- Tracing is disabled automatically when you display the backtrace. (This prevents additional accumulation of trace information, allowing you to redisplay the buffer without interference from additional console lines.)
- Backtrace will slow down your program by a factor of 20 (because for each value that is evaluated, it must store a log record).
- The internal backtrace buffer is 100KB. On average, the most it will hold is 100 pages of backtrace.
- Enabling normal trace will disable backtrace and delete the backtrace buffer.
- Backtrace may interfere with some kinds of tracing, especially if the bug is related to a defect within the REBOL interpreter itself.
The stack function can also be used to show stack related backtrace information.
TRANSCODE¶
Translates UTF-8 binary source to values. Returns one or several values in a block.
Usage:
transcode
ARGUMENTS: source [binary! string!] UTF-8 input buffer; string argument will be UTF-8 encoded REFINEMENTS: /next Translate next complete value (blocks as single value) /one Translate next complete value (returns the value only) /only Translate only a single value (blocks dissected) /error Do not cause errors - return error object as value in place /line Return also information about number of lines scaned count [integer!] Initial line number /part Translates only part of the input buffer length [integer!] Length of source to decode
Description:
The transcode function translates source code and data into the block value memory format that can be interpreted by REBOL.
Input
The source input to transcode must be Unicode UTF-8. This is a binary! encoded format, and should not be confused with a string!, which is a decoded in-memory indexable string.
If you need to transcode a string, you must convert it to a UTF-8 binary first. This can be done with to-binary.
data: transcode to-binary stringRefinements
Without refinements, transcode will convert the entire input string.
Refinements are provided for partial translation:
| /next | Translate the next full value. If it is a block, translate the entire block. |
| /only | Translate the next singular value. If it is a block, translate only the first element of the block, and return it within a block. |
| /error | Convert syntax errors to error objects and output them rather than throwing them as an error. |
These refinements can be used in various ways to parse REBOL source a value at a time.
Output
The output from transcode is a block! containing two values:
- The translated value, block of values, or error! object.
- The binary! source at the point where the translation ended.
a: to-binary "a b c"
#{6120622063}
transcode/only a
[a #{20622063}]TRIM¶
Removes spaces from strings, nulls from binary, nones from blocks or objects.
Usage:
trim
ARGUMENTS: series [series! object! error! module!] Series (modified) or object (made) REFINEMENTS: /head Removes only from the head /tail Removes only from the tail /auto Auto indents lines relative to first line /lines Removes all line breaks and extra spaces /all Removes all whitespace /with str [char! string! binary! integer!] Same as /all, but removes characters in 'str'
Description:
Trim removes unwanted values, normally it trims whitespace from a string! or none! values from a block! or object!.
Here is an example of a string:
str: " string "
probe trim str
"string"Note that the str is modified. To avoid that, use copy:
new-str: trim copy strFor a block! :
trim reduce [none 'a none 'b none]
[a b]It removes the none! values from the block. (And it will also remove unset! values as well.)
Note that the block is modified. But, in this example, reduce creates a unique copy, so the original is not effected.
And for an object! :
trim system/options
make object! [
home: %/C/Program%20Files/
path: %/C/rebol/r3/
boot: %/C/rebol/r3/view.exe
binary-base: 16
decimal-digits: 15
]Because object fields cannot be removed (due to binding) the result of trim of an object is always to return a new shallow object. (The values of the object are not deep-copied or rebound.)
The new object only shows fields that have actual value (not none or unset.)
Details on trimming strings
The default for TRIM is to remove whitespace characters (tabs and spaces) from the heads and tails of every line of a string. Empty leading and trailing lines are also trimmed.
When a string includes multiple lines, the head and tail whitespace will be trimmed from each line (but not within the line):
str: {
Now is the winter
of our discontent
made glorious summer
by this sun of York.
}
probe trim str
{Now is the winter
of our discontent
made glorious summer
by this sun of York.
}The line terminator of the final line is preserved.
As mentioned above, empty leading and trailing lines are also trimmed:
probe trim {
Non-empty line.
Non-empty line.
Non-empty line.
}
{Non-empty line.
Non-empty line.
Non-empty line.
}Note that TRIM modifies the string in the process.
str: " string "
trim str
probe str
"string"TRIM does not copy the string. If that's what you want, then use TRIM with COPY to copy the string before trimming it.
Several refinements to TRIM are available. To trim just the head and/or tail of a string you can use the /HEAD or /TAIL refinements.
probe trim/head " string "
"string "
probe trim/tail " string "
" string"
probe trim/head/tail " string "
"string"When using /HEAD or /TAIL, multiple lines are not affected:
probe trim/head { line 1
line 2
line 3
}
{line 1
line 2
line 3
}To trim just the head and tail of a multiline string, but none of its internal spacing:
str: { line 1
line 2
line 3
line 4
line 5 }
probe trim/head/tail str
{line 1
line 2
line 3
line 4
line 5}If you use TRIM/LINES then all lines and extra spaces will be removed from the text. This is useful for word wrapping and web page kinds of applications.
str: {
Now is
the
winter
}
probe trim/lines str
"Now is^/the^/winter"You can also remove /ALL space:
probe trim/all " Now is the winter "
"Nowisthewinter"
str: {
Now is
the
winter
}
probe trim/all str
"Nowisthewinter"One of the most useful TRIM refinements is /AUTO which will do a "smart" trim of the indentation of text lines. This mode detects the indentation from the first line and preserves indentation for the lines to follow:
probe trim/auto {
line 1
line 2
line 3
line 4
line 5
}
{line 1
line 2
line 3
line 4
line 5
}This is useful for sections of text that are embedded within code and indented to the level of the code.
To trim other characters, the /WITH refinement is provided. It takes an additional string that specifies what characters to be removed.
str: {This- is- a- line.}
probe trim/with str "-"
"This is a line."
str: {This- is- a- line.}
probe trim/with str "- ."
"Thisisaline"TRIM on blocks
When trim is used on a block!, it strips all none! values from the block:
trim reduce [1 2 none]
[1 2]Note that trim modifies the argument block.
TRIM on objects
When trim is used on an object!, it will return a new object that has all none! values removed:
obj: make object [arg1: 10 arg2: none]
trim obj
make object! [
arg1: 10
]TRUE?¶
Returns true if an expression can be used as true.
Usage:
true?
ARGUMENTS: val [any-type!]
Description:
>> true? 1
== #(true)
>> true? 2
== #(true)
>> true? none
== #(false)
>> true? off
== #(false)Note that unset! value is truthy!
>> true? #(unset)
== #(true)TRUNCATE¶
Removes all bytes/values from series' head to its current index position
Usage:
truncate
ARGUMENTS: series [series!] Series to be truncated REFINEMENTS: /part Also shorten resulted series to a length or end position range [number! series!]
Description:
>> str: "12345"
== "12345"
>> truncate skip str 3
== "45"This function is useful for removing processed data from an input buffer.
TRY¶
Tries to DO a block and returns its value or an error!.
Usage:
try
ARGUMENTS: block [block! paren!] REFINEMENTS: /all Catch also BREAK, CONTINUE, RETURN, EXIT and THROW exceptions. /with On error, evaluate the handler and return its result handler [block! any-function!] /except ** DEPRERCATED ** code [block! any-function!]
Description:
The try function evaluates a block and will capture any errors that occur during that evaluation.
The purpose of try is to give your own code the opportunity to handle errors, rather than causing your program to terminate with an error message.
For example, in this line:
try [delete %afile.txt]if the file does not exist, then the error will not cause your program to terminate.
Return Value
The try function returns an error value if an error happened, otherwise it returns the normal result of the block.
Taking the above example, we can do something special if an error happened:
if error? try [delete %afile.txt] [print "delete failed"]or, even use the error value itself:
if error? err: try [delete %afile.txt] [print ["delete failed:" mold err]]Sometimes you'll want to use the value that was returned:
either error? val: try [1 + "x"] [print "nope"] [print val]
nope
either error? val: try [1 + 2] [print "nope"] [print val]
3Exception Handling
The try function is for error handling, but there are times when you may be returning error objects as values, and you cannot distinguish between an error occurring and the error value itself. This is case rare, but it does happen.
For this situation the /with refinement is provided. If an error occurs, it will evaluate a exception handling function (or just a block). This indicates that an error exception happened (not just an error value being passed.)
The example below will catch the "zero-divide" error within a function. The error is passed as the argument to the exception function, and a value (zero in this case) is returned from the try function:
>> try/with [1 / 0] :print
** Math error: attempt to divide by zero
** Where: / try
** Near: / 0Or to provide a default value in case of the error:
>> try/with [1 / 0] ['oh-no]
== oh-noLast error is stored in the system/state object and may be used like:
>> try [1 / 0]
** Math error: attempt to divide by zero
** Where: / try
** Near: / 0
>> system/state/last-error
** Math error: attempt to divide by zero
** Where: / try
** Near: / 0Shortcut
The attempt function is shortcut for the common pattern where you don't care about the specific error, and mainly just want the non-error result.
data: attempt [load %data.r]The data will be either the data or none, if it failed to load.
TUPLE?¶
Returns TRUE if it is this type.
Usage:
tuple?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values.
>> tuple? 1.2.3.4
== #(true)
>> tuple? "1.2.3.4"
== #(false)TYPE?¶
Returns the datatype of a value.
Usage:
type?
ARGUMENTS: value [any-type!] REFINEMENTS: /word Returns the datatype as a word
Description:
To check for a single datatype, use its datatype test function (e.g. string?, time?) The /WORD refinement returns the type as a word so you can use if for FIND, SELECT, SWITCH, and other functions.
>> type? 10
== #(integer!)
>> type? :type?
== #(native!)value: 10:30
print switch type?/word value [
integer! [value + 10]
decimal! [to-integer value]
time! [value/hour]
date! [first value/time]
]
10TYPES-OF¶
Returns a copy of the types of any function
Usage:
types-of
ARGUMENTS: value [any-function!]
Description:
>> spec-of :to-radians
== [
"Converts degrees to radians"
degrees [integer! decimal!] "Degrees to convert"
]
>> types-of :to-radians
== [make typeset! [integer! decimal!]]TYPESET?¶
Returns TRUE if it is this type.
Usage:
typeset?
ARGUMENTS: value [any-type!]
Description:
>> typeset? any-string!
== #(true)
>> typeset? string!
== #(false)UNBIND¶
Unbinds words from context.
Usage:
unbind
ARGUMENTS: word [block! any-word!] A word or block (modified) (returned) REFINEMENTS: /deep Process nested blocks
Description:
>> a: 1 b: [a a]
== [a a] ;; words inside the block are bound
>> not none? context? first b
== #(true)
>> reduce b
== [1 1] ;; and so have the value
>> unbind b
== [a a]
>> context? first b
== #(none)
>> reduce b
** Script error: a word is not bound to a contextUNDIRIZE¶
Returns a copy of the path with any trailing "/" removed.
Usage:
undirize
ARGUMENTS: path [file! string! url!]
Description:
>> undirize %some/path/
== %some/pathUNFILTER¶
Reversed PNG delta filter
Usage:
unfilter
ARGUMENTS: data [binary!] Input width [number!] Scanline width (not counting the type byte) REFINEMENTS: /as Filter type. If not used, type is decoded from first byte on each line. type [integer! word!] 1..4 or one of: [sub up average paeth] /skip bpp [integer!] Bytes per pixel
Description:
Compression preprocessing, as used in PNG images.
>> bin: #{01020304050102030405} ;; original data
== #{01020304050102030405}
>> filter bin 5 'sub
== #{01010101010101010101} ;; data filtered for good compression
>> unfilter/as #{01010101010101010101} 5 'sub
== #{01020304050102030405} ;; original data againUNHANDLE-EVENTS¶
Removes a handler from the view event system.
Usage:
unhandle-events
ARGUMENTS: handler [object!]
Description:
No description provided.
UNION¶
Returns the union of two data sets.
Usage:
union
ARGUMENTS: set1 [block! string! bitset! typeset! map!] first set set2 [block! string! bitset! typeset! map!] second set REFINEMENTS: /case Use case-sensitive comparison /skip Treat the series as records of fixed size size [integer!]
Description:
Returns all elements present within two blocks or strings ignoring the duplicates.
lunch: [ham cheese bread carrot]
dinner: [ham salad carrot rice]
probe union lunch dinner
[ham cheese bread carrot salad rice]
probe sort union [1 3 2 4] [3 5 4 6]
[1 2 3 4 5 6]
string1: "CBDA" ; A B C D scrambled
string2: "EDCF" ; C D E F scrambled
probe sort union string1 string2
"ABCDEF"
items: [1 1 2 3 2 4 5 1 2]
probe union items items ; get unique set
[1 2 3 4 5]
str: "abcacbaabcca"
probe union str str
"abc"To obtain a unique set (to remove duplicate values) you can use UNIQUE.
Note that performing this function over very large data sets can be CPU intensive.
UNIQUE¶
Returns the data set with duplicates removed.
Usage:
unique
ARGUMENTS: set1 [block! string! bitset! typeset! map!] REFINEMENTS: /case Use case-sensitive comparison (except bitsets) /skip Treat the series as records of fixed size size [integer!]
Description:
Removes all duplicate values from a set or series:
lunch: [ham cheese bread carrot ham ham carrot]
probe unique lunch
[ham cheese bread carrot]
probe unique [1 3 2 4 3 5 4 6]
[1 3 2 4 5 6]
string: "CBADEDCF"
probe unique string
"CBADEF"Note that performing this function over very large data sets can be CPU intensive.
UNLESS¶
If FALSE condition, return arg; evaluate blocks by default.
Usage:
unless
ARGUMENTS: condition [any-type!] false-branch REFINEMENTS: /only Return block arg instead of evaluating it.
Description:
The unless function is the equivalent of writing if not of a condition.
unless now/time > 12:00 [print "It's still morning"]See the if function for a lot more information.
Why?
This function can take some getting used to. It has been provided to make PERL programmers happier, and it's marginally simpler and faster than writing an if not expression.
UNPROTECT¶
Unprotect a series or a variable (it can again be modified).
Usage:
unprotect
ARGUMENTS: value [word! series! bitset! map! object! module!] REFINEMENTS: /deep Protect all sub-series as well /words Block is a list of words /values Process list of values (implied GET)
Description:
Unprotects a series, variable, or object that was protected earlier with protect.
For example:
test: "text"
protect test
append test "a"
** Script error: protected value or series - cannot modify
unprotect test
append test "a"
probe texta
"texta"To unprotect all series found within a block, use the /deep refinement:
test: [100 "example" 10:20]
protect/deep test
print append "example" "x"
** Script error: protected value or series - cannot modify
unprotect/deep test
print append "example" "x"
examplexSee protect for other usage and information.
UNSET¶
Unsets the value of a word (in its current context.)
Usage:
unset
ARGUMENTS: word [word! block! none!] Word or block of words
Description:
Using UNSET, the word's current value will be lost. If a block is specified, all the words within the block will be unset.
test: "a value"
unset 'test
print value? 'test
falseUNSET?¶
Returns TRUE if it is this type.
Usage:
unset?
ARGUMENTS: value [any-type!]
Description:
Returns TRUE if a value is UNSET. Normally you should use VALUE? to test if a word has a value.
if unset? do [print "test"] [print "Nothing was returned"]
testUNTIL¶
Evaluates a block until it is TRUE.
Usage:
until
ARGUMENTS: block [block!]
Description:
The until function evaluates a block until the block returns true. It is different from while because it only requires a single block, which also serves as the condition. However, the block is always evaluated at least once.
The general form is:
while [cond] [body]For example:
num: 0
until[
print num
num: num + 1
num >= 2
]
0
1
2Another example:
str: "test"
until [
print str
tail? str: next str
]
test
est
st
tReturn Value
The last value of the block is returned from the until function. Because this is also the termination condition, it will always be non-none non-false, but that can be useful at times.
Other Notes
- A break can be used to escape from the loop at any time.
- A common mistake is to forget that block must return the test condition for the loop, which could result in an infinite loop.
UNVIEW¶
Closes a window view.
Usage:
unview
ARGUMENTS: window [object! gob! word! none!] Window face or GOB. 'all for all. none for last
Description:
The UNVIEW function is used to close a window previously opened with the VIEW function. By default, the last window that has been opened will be closed. To close a specific window, use the /only refinement and specify the window's face (that which was returned from a layout, for example). All windows can be closed with the /all refinement.
The example below opens a window that displays a Close button. Clicking on the button will evaluate the UNVIEW function and the window will be closed.
view layout [button "Close" [unview]]Note that the VIEW function will not return until all windows have been closed. (Use VIEW/new to return immediately after the window is opened.)
The next example will open two windows, then use UNVIEW/only to close each one separately.
out1: layout [button "Close 2" [unview out2]]
out2: layout [button "Close 1" [unview out1]]
view/new out1
view/new out2
do-eventsYou could have closed both windows with the line:
unview/allUPDATE¶
Updates external and internal states (normally after read/write).
Usage:
update
ARGUMENTS: port [port!]
Description:
Updates the input or output of a port. If input is expected, the port is checked for more input. If output is pending then that output is written.
out: open/new %trash.me
insert out "this is a test"
update out
insert out "this is just a test"
close outUPPERCASE¶
Converts string of characters to uppercase.
Usage:
uppercase
ARGUMENTS: string [any-string! char!] (modified if series) REFINEMENTS: /part Limits to a given length or position length [number! any-string!]
Description:
The series passed to this function is modified as a result.
print uppercase "abcdef"
ABCDEF
print uppercase/part "abcdef" 1
AbcdefURL?¶
Returns TRUE if it is this type.
Usage:
url?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values.
print url? http://www.REBOL.com
true
print url? "test"
falseUSAGE¶
Prints command-line arguments
Usage:
usage
Description:
Displays REBOL command line arguments, including options and examples.
>> usage
Command line usage:
REBOL |options| |script| |arguments|
Standard options:
--args data Explicit arguments to script (quoted)
--do expr Evaluate expression (quoted)
--help (-?) Display this usage information (then quit)
--script file Explicit script filename
--version tuple Script must be this version or greater
Special options:
--boot level Valid levels: base sys mods
--debug flags For user scripts (system/options/debug)
--halt (-h) Leave console open when script is done
--import file Import a module prior to script
--quiet (-q) No startup banners or information
--secure policy Can be: none allow ask throw quit
--trace (-t) Enable trace mode during boot
--verbose Show detailed startup information
--cgi (-c) Starts in a CGI mode
Other quick options:
-s No security
+s Full security
-v Display version only (then quit)
Examples:
REBOL script.r
REBOL -s script.r
REBOL script.r 10:30 test@example.com
REBOL --do "watch: on" script.r
SDK and special versions of REBOL may not include usage information.
USE¶
Defines words local to a block.
Usage:
use
ARGUMENTS: vars [block! word!] Local word(s) to the block body [block!] Block to evaluate
Description:
The first block contains a list of words which will be local to the second block. The second block will be evaluated and its results returned from the USE.
total: 1234
nums: [123 321 456]
use [total] [
total: 0
foreach n nums [total: total + n]
print total
]
900
print total
1234Note: The USE function modifies the context (bindings) of the code block (as if BIND was used on it). This can lead to problems for recursive functions. To use the USE function recusively, you will need to COPY/deep the code block first:
words: [a]
body: [print a * b]
use words copy/deep bodyUSER'S¶
Resolves user's data value
Usage:
user's
ARGUMENTS:
key
Description:
It can be used in the following scenario:
>> set-user/n Test
[REBOL] Initialize user: Test
[REBOL] Creating a new persistent storage file: /C/Users/oldes/Rebol/.Test.safe
Enter password:
>> user's key
== #(none) ;; Because the key has not been stored yet.
>> put system/user/data 'key "secret"
== "secret"
>> user's key
== "secret"
>> set-user ;; Removes current user
>> user's key
== #(none) ;; Because there is no user now
>> set-user Test
[REBOL] Initialize user: Test
Enter password:
>> user's key
== "secret"UTF?¶
Returns UTF BOM (byte order marker) encoding; + for BE, - for LE.
Usage:
utf?
ARGUMENTS: data [binary!]
Description:
>> utf? #{FEFF005700720069007400650072}
== 16
>> utf? #{FFFE570072006900740065007200}
== -16
>> utf? #{fffe0000650000007300000063000000}
== -32
>> utf? #{EFBBBFC3A4C3B6C3BC}
== 8UTYPE?¶
Returns TRUE if it is this type.
Usage:
utype?
ARGUMENTS: value [any-type!]
Description:
No description provided.
VALUE?¶
Returns TRUE if the word has a value.
Usage:
value?
ARGUMENTS: value [word!]
Description:
The value? function returns true if the specified word! has a value. It returns false if not.
>> value? 'system
== #(true)
>> value? 'not-defined
== #(false)The word can be passed as a literal or as the result of other operations.
>> value? first [system not-defined]
== #(true)
>> value? second [system not-defined]
== #(false)VALUES-OF¶
Returns a copy of the values of any object, map or struct
Usage:
values-of
ARGUMENTS: value [any-object! map! struct!]
Description:
>> values-of #[a: 1 b: 2]
== [1 2]
>> values-of object [a: 1 b: 2]
== [1 2]VECTOR?¶
Returns TRUE if it is this type.
Usage:
vector?
ARGUMENTS: value [any-type!]
Description:
>> vector? #(uint8! 3)
== #(true)
>> vector? [1 2 3]
== #(false)VERSION¶
Return Rebol version string
Usage:
version
REFINEMENTS:
/data loadable version
Description:
>> version
== {Rebol/Bulk 3.18.3 (9-Mar-2025/22:36 UTC)
Copyright (c) 2012 REBOL Technologies
Copyright (c) 2012-2025 Rebol Open Source Contributors
Source: https://github.com/Oldes/Rebol3
}VIEW¶
Displays a window view.
Usage:
view
ARGUMENTS: window [gob! block! object! image!] Window gob, VID face, or VID layout block REFINEMENTS: /options opts [block!] Window options spec block /no-wait Return immediately. Do not wait and process events. /as-is Leave window as is. Do not add a parent gob.
Description:
NOTE: GUI system is only partially supported in this Rebol version!
WAIT¶
Waits for a duration, port, or both.
Usage:
wait
ARGUMENTS: value [number! time! port! block! none!] REFINEMENTS: /all Returns all in a block /only only check for ports given in the block to this function
Description:
If the value is a time!, delay for that period. If the value is an integer! or decimal!, wait that number of seconds. If the value is a port!, wait for an event from that port. If a block! is specified, wait for any of the times or ports to occur. Return the port that caused the wait to complete or return none if the timeout occurred.
print now/time
17:48:19
wait 1
print now/time
17:48:22
wait 0:00:01
print now/time
17:48:23WAIT-FOR-KEY¶
Wait for single key press and return char (or word for control keys) as a result
Usage:
wait-for-key
REFINEMENTS: /only limit [bitset! string! block! none! char!] Limit input to specified chars or control words
WAKE-UP¶
Awake and update a port with event.
Usage:
wake-up
ARGUMENTS: port [port!] event [event!]
Description:
No description provided.
WHAT¶
Prints a list of known functions
Usage:
what
ARGUMENTS: name [word! lit-word! unset!] Optional module name REFINEMENTS: /args Show arguments not titles
Description:
The what function lists globally exported functions and their titles or arguments.
For example:
>> what
...
about Information about REBOL
abs Returns the absolute value.
absolute Returns the absolute value.
action Creates datatype action (for internal usage only).
action? Returns TRUE if it is this type.
add Returns the result of adding two values.
ajoin Reduces and joins a block of values into a new string.
alias Creates an alternate spelling for a word.
...To see function arguments use:
>> what/args
...
about []
abs [value]
absolute [value]
action? [value]
add [value1 value2]
ajoin [block]
...Also see the help function which allows searching for functions.
Module Export Lists
To see a list of functions for a specific module, provide the module name:
>> what/args help? ['word /doc /into string]
a-an [s]
about []
browse [url]
bugs []
changes []
dot [value]
dump-obj [obj /weak /match pattern /not-none]
form-pad [val size]
form-type [value]
form-val [val]
help ['word /doc /into string]
license []
list-codecs []
out-description [des]
output [value]
pad [val size]
source ['word]
usage []
what ['name /args]
WHAT-DIR¶
Returns the current directory path.
Usage:
what-dir
Description:
>> what-dir
== %/C/Users/oldes/Rebol/WHILE¶
While a condition block is TRUE, evaluates another block.
Usage:
while
ARGUMENTS: cond-block [block!] body-block [block!]
Description:
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.
The general form is:
while [cond] [body]For example:
num: 0
while [num < 3] [
print num
num: num + 1
]
0
1
2Another example, using while to traverse a series (like foreach ):
color: [red green blue]
while [not tail? color] [
print first color
color: next color
]
red
green
blueHere is an example using a string series:
str: "abc"
while [not tail? str: next str] [
print ["length of" str "is" length? str]
]
length of abc is 3
length of bc is 2
length of c is 1Condition Block
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.
color: [red green blue]
while [
print index? color
not tail? color
][
print first color
color: next color
]
1
red
2
green
3
blue
4Return Value
The last value of the block is returned from the while function.
Other Notes
- A break can be used to escape from the loop at any time.
- The most common mistake is to forget to provide a block for the first argument (the condition).
WILDCARD¶
Return block of absolute path files filtered using wildcards.
Usage:
wildcard
ARGUMENTS: path [file!] Source directory value [any-string!] Search value with possible * and ? wildcards
WILDCARD?¶
Return true if file contains wildcard chars (* or ?)
Usage:
wildcard?
ARGUMENTS: path [file!]
WITH¶
Evaluates a block binded to the specified context
Usage:
with
ARGUMENTS: context [object! module! port!] A reference to the target context body [block!] A code to be evaluated
WORD?¶
Returns TRUE if it is this type.
Usage:
word?
ARGUMENTS: value [any-type!]
Description:
Returns FALSE for all other values. To test for "word:", ":word", or "'word", use the SET?, GET?, and LITERAL? functions.
print word? second [1 two "3"]
trueWORDS-OF¶
Returns a copy of the words of any function, any object, map, date, handle or struct
Usage:
words-of
ARGUMENTS: value [any-function! any-object! map! date! handle! struct!]
Description:
No description provided.
WRAP¶
Evaluates a block, wrapping all set-words as locals.
Usage:
wrap
ARGUMENTS: body [block!] Block to evaluate
Description:
>> a: 1 ;; Having some value....
== 1
>> wrap load "a: 2" ;; Evaluate some code which is
;; using the same value name
== 2
>> a
== 1 ;; Original value was not changedWRITE¶
Writes to a file, URL, or port - auto-converts text strings.
Usage:
write
ARGUMENTS: destination [port! file! url! block! word!] data Data to write (non-binary converts to UTF-8) REFINEMENTS: /part Partial write a given number of units length [number!] /seek Write at a specific position index [number!] /append Write data at end of file /allow Specifies protection attributes access [block!] /lines Write each value in a block as a separate line /binary Preserves contents exactly /all Response may include additional information (source relative)
Description:
WRITE is typically used to write a file to disk, but many other operations, such as writing data to URLs and ports, are possible.
Normally a string or binary value is provided to this function, but other types of data such as a number or a time can be written. They will be converted to text.
The /BINARY refinement will write out data as its exact representation. This is good for writing image, sound and other binary data.
The /STRING refinement translates line terminators to the operating system's line terminator. This behavior is default.
The /APPEND refinement is useful logging purposes, as it won't overwrite existing data.
The /LINES refinement can take a block of values and will write each value to a line. By default, WRITE will write the block of values as a concatonated string of formed values.
The /PART refinement will read the specified number of elements from the data being written. The /WITH refinement converts characters, or strings, specified into line terminators.
See the User's Guide for more detailed explanation of using READ and its refinements.
write %junkme.txt "This is a junk file."
write
write %datetime.txt now
write
write/binary %data compress "this is compressed data"
write %rebol-test-file.r "some text"
print read %rebol-test-file.r
read
write/append %rebol-test-file.r "some more text"
print read %rebol-test-file.r
write %rebol-test-file.r reduce ["the time is:" form now/time]
print read %rebol-test-file.r
read
write/lines %rebol-test-file.r reduce ["time is:" form now/time]
print read %rebol-test-file.r
write/part %rebol-test-file.r "this is the day!" 7
print read %rebol-test-file.rXOR¶
Returns the first value exclusive ORed with the second.
Usage:
xor
ARGUMENTS: value1 [logic! integer! char! tuple! binary! bitset! typeset! datatype!] value2 [logic! integer! char! tuple! binary! bitset! typeset! datatype!]
Description:
For integers, each bit is exclusively-or'd. For logic values, this is the same as the not-equal function.
print 122 xor 1
123
print true xor false
true
print false xor false
false
print 1.2.3.4 xor 1.0.0.0
0.2.3.4XOR~¶
Returns the first value exclusive ORed with the second.
Usage:
xor~
ARGUMENTS: value1 [logic! integer! char! tuple! binary! bitset! typeset! datatype!] value2 [logic! integer! char! tuple! binary! bitset! typeset! datatype!]
Description:
The trampoline action function for XOR operator.
XTEST¶
Usage:
xtest
ZERO?¶
Returns TRUE if the value is zero (for its datatype).
Usage:
zero?
ARGUMENTS:
value
Description:
Check the value of a word is zero.
>> zero? 50
== #(false)
>> zero? 0
== #(true)-¶
Returns the second value subtracted from the first.
Usage:
-
ARGUMENTS: value1 [scalar! date! vector!] value2 [scalar! date! vector!]
--¶
Decrement an integer or series index. Return its prior value.
Usage:
--
ARGUMENTS: word [word!] Integer or series variable
---¶
Ignores the argument value and returns nothing.
Usage:
---
ARGUMENTS:
value A string, block, file, etc.
&¶
Returns the first value ANDed with the second.
Usage:
&
ARGUMENTS: value1 [logic! integer! char! tuple! binary! bitset! typeset! datatype!] value2 [logic! integer! char! tuple! binary! bitset! typeset! datatype!]
/¶
Returns the first value divided by the second.
Usage:
/
ARGUMENTS: value1 [scalar! vector!] value2 [scalar! vector!]
//¶
Wrapper for MOD that handles errors like REMAINDER. Negligible values (compared to A and B) are rounded to zero.
Usage:
//
ARGUMENTS: a [number! money! char! time!] b [number! money! char! time!] Absolute value will be used.
=¶
Returns TRUE if the values are equal.
Usage:
=
ARGUMENTS: value1 [any-type!] value2 [any-type!]
==¶
Returns TRUE if the values are strictly equal.
Usage:
==
ARGUMENTS: value1 [any-type!] value2 [any-type!]
=?¶
Returns TRUE if the values are identical.
Usage:
=?
ARGUMENTS: value1 [any-type!] value2 [any-type!]
>¶
Returns TRUE if the first value is greater than the second value.
Usage:
>
ARGUMENTS:
value1
value2
>=¶
Returns TRUE if the first value is greater than or equal to the second value.
Usage:
>=
ARGUMENTS:
value1
value2
>>¶
Shift bits to the right (unsigned).
Usage:
>>
ARGUMENTS: data [integer!] bits [integer!]
*¶
Returns the first value multiplied by the second.
Usage:
*
ARGUMENTS: value1 [scalar! vector!] value2 [scalar! vector!]
**¶
Returns the first number raised to the second number.
Usage:
**
ARGUMENTS: number [number!] exponent [number!]
%¶
Returns the remainder of first value divided by second.
Usage:
%
ARGUMENTS: value1 [scalar!] value2 [scalar!]
|¶
Returns the first value ORed with the second.
Usage:
|
ARGUMENTS: value1 [logic! integer! char! tuple! binary! bitset! typeset! datatype!] value2 [logic! integer! char! tuple! binary! bitset! typeset! datatype!]
+¶
Returns the addition of two values.
Usage:
+
ARGUMENTS: value1 [scalar! date! vector!] value2 [scalar! date! vector!]
++¶
Increment an integer or series index. Return its prior value.
Usage:
++
ARGUMENTS: word [word!] Integer or series variable
?¶
Note: Shell shortcut for help.
??¶
Debug print a word, path, or block of such, followed by its molded value.
Usage:
??
ARGUMENTS:
name Word, path or block to obtain values.
<¶
Returns TRUE if the first value is less than the second value.
Usage:
<
ARGUMENTS:
value1
value2
<=¶
Returns TRUE if the first value is less than or equal to the second value.
Usage:
<=
ARGUMENTS:
value1
value2
<>¶
Returns TRUE if the values are not equal.
Usage:
<>
ARGUMENTS: value1 [any-type!] value2 [any-type!]
<<¶
Shift bits to the left (unsigned).
Usage:
<<
ARGUMENTS: data [integer!] bits [integer!]
!¶
Returns the logic complement.
Usage:
!
ARGUMENTS: value [any-type!] (Only FALSE and NONE return TRUE)
!=¶
Returns TRUE if the values are not equal.
Usage:
!=
ARGUMENTS: value1 [any-type!] value2 [any-type!]
!==¶
Returns TRUE if the values are not strictly equal.
Usage:
!==
ARGUMENTS: value1 [any-type!] value2 [any-type!]