ucl/_docs/mod/core.md

---
---

# Core Builtins

### call

```
call BLOCK [ARGS...]
```

Invokes block, passing in the arguments. This is as if block was invoked as a command. This may not always be necessary
unless these are need to call BLOCK with exactly 0 arguments.

### echo

```
echo [ARGS...]
```

Displays the string representation of ARGS to stdout followed by a new line.

### foreach

```
foreach COL BLOCK
```

Iterates BLOCK over every element of the sequence.

The values pass to BLOCK will depend on the type of COL. If COL is a list, BLOCK receives the element value.
If COL is a hash, BLOCK receives both the key and value of each element.

BLOCK can call `break` and `continue` which will exit out of the loop, or jump to the start of the next iteration
respectively.
The return value of `foreach` will be the result of the last iteration, unless `break` is called with a value.

This is implemented as a macro but can be used in a pipeline. 

```
foreach [1 2 3] { |e|
  echo "Element = $e"
}

[a:"one" b:"two"] | foreach { |k v|
  echo "Key $k = $v"
}
```

## index

```
index COL [INDEX...] 
```

Returns the index value at INDEX of COL. COL can be either a list or a hash.

### keys

```
keys HASH
```

Returns the keys of the passed in hash as a list. The order of keys are non-deterministic.
If HASH is not a hash, then nil will be returned.

### len

```
len COL
```

Returns the length of COL. If COL is a list or hash, COL will be the number of
elements. If COL is a string, COL will be the string's length. All other values will
return a length of 0.

If COL is an iterator, `len` will consume the values of the iterator and return the number of items consumed. 

### map

```
map COL BLOCK
```

Returns a new list of elements mapped from COL according to the result of BLOCK. COL can be any list or hash
with the result being a concrete list. COL can be an iterator, in which case the result will be an iterator
which will call BLOCK for every consumed value.

```
map [1 2 3] { |x| str $x | len }
```

### proc

```
proc [NAME] BLOCK
```

Defines a new function optionally with the given name. When called without NAME, this will define a new
lambda which can be invoked using `call`.

When NAME is set, this function defining a function a name will always declare it at the top-level scope.

### reduce

```
reduce COL [INIT] BLOCK
```

Returns the result of reducing the elements of COL with the passed in block.

BLOCK will receive at least two argument, with the current value of the accumulator always being the last argument.
If COL is a list or iterator, the arguments will be _|element accumulator|_, and if COL is a hash, the arguments will be
_|key value accumulator|_. 

The block result will be set as the value of the accumulator for the next iteration. Once all elements are process
the accumulator value will be returned as the result of `reduce`.

If INIT is not set, and COL is a list, the accumulator will be set to the first value and BLOCK will be called
from the second element, if any. If COL is a hash, then the accumulator will be set to nil.

## seq

```
seq [FROM] TO [-inc]
```

Returns a listable sequence containing all the integers from 0 to TO, exclusive.
TO can be either be negative or positive. If TO Is positive, then the sequence will
step by +1; if TO is negative, then the sequence will step by -1.

If FROM is specified, then the collection contains all the integers from FROM inclusive, to TO
exclusive. The step will be +1 or -1 if TO is greater than, or less than FROM respectively.

If FROM and TO are equal, or if FROM is unspecified and TO is 0, then the sequence will be empty.

If -inc is specified, then the sequence will step towards TO inclusively.

```
foreach (seq 5) { |i|
  echo $i
}
```

### set

```
set NAME VALUE
```

Sets the value of variable NAME to VALUE. Any variable with NAME will be checked
within the scope first, including any parent scopes, before a new variable is defined.
Any new variables will only be defined with the current scope.