Attributes

Attributes are special runtime settings that modify block behavior, such as how many times a block repeats or how it selects which element to run.

Attributes are set by calling the standard library's attribute functions and stored in the program's attribute stack. Each frame of the attribute stack stores a full set of attributes.

When a block resolves, it consumes attributes from the topmost attribute frame and replaces them with their default values.

Frames can be added to and removed from the attribute stack using [push-attrs] and [pop-attrs].

Repetitions

By setting the repetitions attribute, you can control how many times the next encountered block will run. This attribute is set with the [rep] function.

Example

[rep:10]{[step]\n}
# Output:
# 1
# 2
# 3
# 4
# 5
# 6
# 7
# 8
# 9
# 10

Separator

The separator attribute controls what is printed between each block repetition. It is set using the [sep] function.

Example

[rep:4][sep:" and "]
It just keeps {going}...

# Output:
# It just keeps going and going and going and going...

The selector attribute controls how Rant chooses which branch of a block to take. It does this using a special state machine object, which must be created separately but can be shared between blocks to coordinate their behavior.

Selector modes

Mode	Description
`random`	Select a random element each time. (default)
`one`	Select the same, random element each time.
`forward`	Select in a wrapping sequence from first to last.
`forward-clamp`	Select from first to last, then repeat the last element forever.
`forward-mirror`	Select from first to last, then last to first, then start over.
`reverse`	Select in a wrapping reverse sequence from last to first.
`reverse-clamp`	Select from last to first, then repeat the first element forever.
`reverse-mirror`	Select in a from last to first, then first to last, then start over.
`deck`	Select each element once in a random sequence, then reshuffles.
`deck-loop`	Select each element once in a wrapping random sequence, without reshuffling.
`deck-clamp`	Select each element once in a random sequence, repeating the final element.
`deck-mirror`	Select each element once in a random sequence, then repeats the sequence backwards before reshuffling.
`ping`	Select from first to last, switching directions when a boundary element is reached.
`pong`	Select from last to first, switching directions when a boundary element is reached.
`no-double`	Select a random element each time, ensuring the same element never occurs twice in a row.

Example

# Print every element of the block in a random order with no duplicates

<$s=[mksel:deck]>  # Create a "deck" selector
[sel:<s>]          # Apply the selector
[rep:all]          # Set repetitions
[sep:,\s]          # Set separator
{A|B|C|D|E|F|G|H}

# Output
# F, C, E, G, B, H, D, A

Mutator

The mutator attribute allows the user to supply a function (known as the "mutator function") that is called in place of each iteration of the block. The mutator function accepts the current block element as a callback parameter, which it can then call to produce output for that iteration.

This is extremely useful for applying filters or post-processing to a block at a per-iteration level.

[rep: all]
[sep: \n]
[mut: [?:elem] { [elem]! }] # Just adds an exclamation point
[mksel: forward |> sel]
{
    One | Two | Three | Four | Five | Six | Seven | Eight | Nine | Ten
}

You can also choose how many times you want to run the element, or even not run it at all.

# Without mutator
[rep: all]
[sep: \s]
[sel: forward]
{ the | quick | brown | fox }
# -> the quick brown fox


# With mutator
[mut: [?: el] { [el] [el |> rev] }]
[rep: all]
[sep: \s]
[sel: forward]
{ the | quick | brown | fox }
# -> theeht quickkciuq brownnworb foxxof

Rant Reference