REBOL 3 Functions: compose

compose value /deep /only /into out

Evaluates a block of expressions, only evaluating parens, and returns a block.

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 series

It requires no intermediate storage.