Function arrayHandler

pub fn arrayHandler<T: StartMarker + Clone>(
    c: Configuration<T>,
    v: Variables<'_, T>,
    data: Option<TokenStream>,
    t: TokenStream,
) -> Result<(Variables<'_, T>, TokenStream), (Variables<'_, T>, TokenStream)>

Provides tools for working with arrays.

Syntax: $(array <q>? <command> <arguments>)

An array in do_with_in! is a Group (delimited token stream) containing zero or more Groups, and nothing else. The array commands simply manipulate these sequences of tokens to produce an evaluated result. All commands that “modify” an array in fact produce a new evaluated result. By convention, arrays are delimited by square brackets e.g. [{100} {a b}].

q mode

If the array token is followed immediately by a q, the command will treat its arguments as quoted and handle them as such. For example:

%(array q length %(quote [ {foo} ])); // evaluates to 1;
%(let x = { quux });
%(array ith 2 [ {1} {foo bar baz} { $x } ]); // evaluates to { quux }
%(array q ith 2 %(quote [ {1} {foo bar baz} { $x } ])); // evaluates to %(quote { $x }).

Commands

Command	Summary	Syntax
length	Return the length of the array.	$(array length <array>)
ith	Work with array using positional arguments.	$(array ith <operation> <arguments>
slice	TODO
concat	Concatenate the elements of two or more arrays together.	$(array concat <array1> <array2> ...)
each	Passes array of argument tuples to a handler.	$(array each <handlerName> <array>)
map	Returns a new array based on applying to	$(array map <should_isolate> <name> <block> <srcArray>)
mk	Iterates through arguments, checks if they are valid array elements, and groups them	$(array mk <block1> <block2> ... )

Some of these commands do a lot:

ith

All ith subcommands take a zero-indexed position argument to indicate where in the array the subcommand applies. Negative integers may be used to index from the tail of the array e.g. -1 represents the final element, -2 the penultimate element, and so on. The special tokens head and tail can be used instead of integer positions 0 and -1 respectively.

Subcommand	Summary	Syntax
get	Returns the element at <position>.	$(array ith get <position> $array);
set	Replace the element at <position> with <newEl>.	$(array ith set <position> <newEl> $array);
insert	Insert element <newEl> before the element at <position>.	$(array ith insert <position> <newEl> $array)
remove	Remove the element at <position>.	$(array ith remove <position> $array)

each

Iterates through each item in and runs the handler identified by , passing the item’s sub-elements as arguments. Useful for cases where map would be overkill, or for adding flexibility to mk-generated handlers’ simple argument passing. See examples/mem.rs for a demonstration of the latter pattern.

Example:

$(array each run [ {$(let f = {3})} {$(let g = {4})} ] ) will set $f to 3 and $g to 4.

map

If should_isolate is set to true, the code block is kept isolated from the running environment, if false, variables and handlers defined within the block will persist in the environment, allowing patterns like currying.

The <name> argument is used to set a variable representing the current element available for use within the code block <block>.