# Closures

Closures in zeptoforth involve binding an execution token with a single-cell, double-cell, or multi-cell value at a specified, arbitrary address in RAM; this address will then serve as an execution token itself which, when executed, pushes the bound value onto the stack and then execute the bound execution token. The only requirement for the address specified is that it is halfword-aligned.

### `closure`

The `closure` module contains the following words:

##### `closure-size`
( -- bytes )

The size of a single-cell closure in bytes.

##### `dclosure-size`
( -- bytes )

The size of a double-cell closure in bytes.

##### `nclosure-size`
( count -- bytes )

The size of a multi-cell closure containing *count* values in bytes.

##### `ndclosure-size`
( count -- bytes )

The size of a multi-double cell closure containing *count* values in bytes.

##### `refclosure-size`
( -- bytes )

The size of a single-cell reference closure in bytes.

##### `drefclosure-size`
( -- bytes )

The size of a double-cell reference closure in bytes.

##### `nrefclosure-size`
( count -- bytes )

The size of a multi-cell reference closure containing *count* values in bytes.

##### `ndrefclosure-size`
( count -- bytes )

The size of a multi-double-cell reference closure containing *count* values in bytes.

##### `bind`
( x addr xt -- )

Bind the execution token *xt* to single-cell value *x* at address *addr* in RAM, which will serve as a new execution token. `closure-size` bytes must be available at *addr*. When *addr* is executed as an execution token, the single-cell value *x* will be pushed onto the stack and then the execution token *xt* will be executed. *addr* can be arbitrarily reused and can be at any address in RAM.

##### `dbind`
( d addr xt -- )

Bind the execution token *xt* to double-cell data *d* at address *addr* in RAM, which will serve as a new execution token. `dclosure-size` bytes must be available at *addr*. When *addr* is executed as an execution token, the double-cell value *d* will be pushed onto the stack and then the execution token *xt* will be executed. *addr* can be arbitrarily reused and can be at any address in RAM.

##### `nbind`
( xn ... x0 count addr xt -- )

Bind the execution token *xt* to *count* multiple values *xn* through *x0* at address *addr* in RAM, which will serve as a new execution token. `nclosure-size` (with *count* specified) bytes must be available at *addr*. When *addr* is executed as an execution token, multiple values *xn* through *x0* will be pushed onto the stack and then the execution token *xt* will be executed. *addr* can be arbitrarily reused and can be at any address in RAM.

##### `ndbind`
( dn ... d0 count addr xt -- )

Bind the execution token *xt* to *count* multiple double-cell values *dn* through *d0* at address *addr* in RAM, which will serve as a new execution token. `nclosure-size` (with *count* specified) bytes must be available at *addr*. When *addr* is executed as an execution token, multiple values *dn* through *d0* will be pushed onto the stack and then the execution token *xt* will be executed. *addr* can be arbitrarily reused and can be at any address in RAM.

##### `refbind`
( x addr xt -- )

Bind the execution token *xt* to single-cell value *x* at address *addr* in RAM, which will serve as a new execution token. `closure-size` bytes must be available at *addr*. When *addr* is executed as an execution token, an address pointing to RAM containing the single-cell value *x* will be pushed onto the stack and then the execution token *xt* will be executed. *addr* can be arbitrarily reused and can be at any address in RAM.

##### `drefbind`
( d addr xt -- )

Bind the execution token *xt* to double-cell data *d* at address *addr* in RAM, which will serve as a new execution token. `dclosure-size` bytes must be available at *addr*. When *addr* is executed as an execution token, an address pointing to RAM containing the double-cell value *d* will be pushed onto the stack and then the execution token *xt* will be executed. *addr* can be arbitrarily reused and can be at any address in RAM.

##### `nrefbind`
( xn ... x0 count addr xt -- )

Bind the execution token *xt* to *count* multiple values *xn* through *x0* at address *addr* in RAM, which will serve as a new execution token. `nclosure-size` (with *count* specified) bytes must be available at *addr*. When *addr* is executed as an execution token, multiple addresses pointing to RAM containing *xn* through *x0* will be pushed onto the stack and then the execution token *xt* will be executed. *addr* can be arbitrarily reused and can be at any address in RAM.

##### `ndrefbind`
( dn ... d0 count addr xt -- )

Bind the execution token *xt* to *count* multiple double-cell values *dn* through *d0* at address *addr* in RAM, which will serve as a new execution token. `nclosure-size` (with *count* specified) bytes must be available at *addr*. When *addr* is executed as an execution token, multiple addresses pointing to RAM containing *dn* through *d0* will be pushed onto the stack and then the execution token *xt* will be executed. *addr* can be arbitrarily reused and can be at any address in RAM.

##### `with-closure`
( ? x bound-xt scope-xt -- ? ) scope-xt: ( ? closure-xt -- ? )

Create a closure binding the execution token *bound-xt* to single-cell data *x* in the current task's dictionary, place it on the data stack, and execute *scope-xt*. When the closure is executed, *x* will be pushed onto the data stack and *bound-xt* will be executed. This closure is valid only within the scope of *scope-xt*, and will be de-alloted from the dictionary after it completes executing or if an exception is raised within it, after which it will re-raise said exception.

##### `with-dclosure`
( ? d bound-xt scope-xt -- ? ) scope-xt: ( ? closure-xt -- ? )

Create a closure binding the execution token *bound-xt* to double-cell data *d* in the current task's dictionary, place it on the data stack, and execute *scope-xt*. When the closure is executed, *d* will be pushed onto the data stack and *bound-xt* will be executed. This closure is valid only within the scope of *scope-xt*, and will be de-alloted from the dictionary after it completes executing or if an exception is raised within it, after which it will re-raise said exception.

##### `with-nclosure`
( ? xn ... x0 count bound-xt scope-xt -- ? ) scope-xt: ( ? closure-xt -- ? )

Create a closure binding the execution token *bound-xt* to multi-cell data *xn* ... *x0* consisting of *count* cells in the current task's dictionary, place it on the data stack, and execute *scope-xt*. When the closure is executed, *xn* ... *x0* will be pushed onto the data stack and *bound-xt* will be executed. This closure is valid only within the scope of *scope-xt*, and will be de-alloted from the dictionary after it completes executing or if an exception is raised within it, after which it will re-raise said exception.

##### `with-ndclosure`
( ? dn ... d0 count bound-xt scope-xt -- ? ) scope-xt: ( ? closure-xt -- ? )

Create a closure binding the execution token *bound-xt* to multi-double-cell data *dn* ... *d0* consisting of *count* cells in the current task's dictionary, place it on the data stack, and execute *scope-xt*. When the closure is executed, *dn* ... *d0* will be pushed onto the data stack and *bound-xt* will be executed. This closure is valid only within the scope of *scope-xt*, and will be de-alloted from the dictionary after it completes executing or if an exception is raised within it, after which it will re-raise said exception.

##### `with-refclosure`
( ? x bound-xt scope-xt -- ? ) scope-xt: ( ? closure-xt -- ? )

Create a closure binding the execution token *bound-xt* to single-cell data *x* in the current task's dictionary, place it on the data stack, and execute *scope-xt*. When the closure is executed, an address pointing to RAM containing *x* will be pushed onto the data stack and *bound-xt* will be executed. This closure is valid only within the scope of *scope-xt*, and will be de-alloted from the dictionary after it completes executing or if an exception is raised within it, after which it will re-raise said exception.

##### `with-drefclosure`
( ? d bound-xt scope-xt -- ? ) scope-xt: ( ? closure-xt -- ? )

Create a closure binding the execution token *bound-xt* to double-cell data *d* in the current task's dictionary, place it on the data stack, and execute *scope-xt*. When the closure is executed, an address pointing to RAM containing *d* will be pushed onto the data stack and *bound-xt* will be executed. This closure is valid only within the scope of *scope-xt*, and will be de-alloted from the dictionary after it completes executing or if an exception is raised within it, after which it will re-raise said exception.

##### `with-nrefclosure`
( ? xn ... x0 count bound-xt scope-xt -- ? ) scope-xt: ( ? closure-xt -- ? )

Create a closure binding the execution token *bound-xt* to multi-cell data *xn* ... *x0* consisting of *count* cells in the current task's dictionary, place it on the data stack, and execute *scope-xt*. When the closure is executed, addresses pointing to RAM containing *xn* ... *x0* will be pushed onto the data stack and *bound-xt* will be executed. This closure is valid only within the scope of *scope-xt*, and will be de-alloted from the dictionary after it completes executing or if an exception is raised within it, after which it will re-raise said exception.

##### `with-ndrefclosure`
( ? dn ... d0 count bound-xt scope-xt -- ? ) scope-xt: ( ? closure-xt -- ? )

Create a closure binding the execution token *bound-xt* to multi-double-cell data *dn* ... *d0* consisting of *count* cells in the current task's dictionary, place it on the data stack, and execute *scope-xt*. When the closure is executed, addresses pointing to RAM containing *dn* ... *d0* will be pushed onto the data stack and *bound-xt* will be executed. This closure is valid only within the scope of *scope-xt*, and will be de-alloted from the dictionary after it completes executing or if an exception is raised within it, after which it will re-raise said exception.