functional

Contents

• Functions
• Fields
• Class Iterator

Modules

• functional

Module functional

A module for functional programming utils.

About the module

This module seeks to provide some utility functions and structures which are too verbose in vanilla lua, in particular with regards to iteration and inline function definition.

The module is writen completely in vanilla lua, with no dependencies on external packages. This was a decision made for portability, and has drawbacks. Since none of this was written as a C binding, it is not as performant as it could be.

For example, luafun is "high-performance functional programming library for Lua designed with LuaJIT's trace compiler in mind" . If your environment allows you to use LuaJIT and performance is a concern, perhaps luafun will be more suited for your needs.

The motivation behind this module is, again, portability. If you want to embed this code on a webpage, or use it in some weird system for which a C binding wouldn't work, this project is aimed at you.

Definitions

Array

As lua doesn't have a dedicated array type, the word "array" in this document referes to a table with contiguous non-nil values starting at index 1.

Iterable

An iterable refers to either of:

• An array (see above); or
• An instance of Iterator.

Info:

• Copyright: 2019
• Release: 0.8.0
• License: MIT
• Author: William Quelho Ferreira

Functions

iterate (iterable)	Create an Iterator for the iterable.
filter (iterable, predicate)	Select only values which match the predicate.
map (iterable, mapping)	Map values into new values.
reduce (iterable, reducer, initial_value)	Collapse values into a single value.
foreach (iterable, func)	Apply a function to all values.
take (iterable, n)	Iterate over the n first values and stop.
skip (iterable, n)	Iterate over the values, starting at the (n+1)th one.
every (iterable, n)	Take 1 value every n.
any (iterable, predicate)	Checks if any values evaluate to true.
all (iterable, predicate)	Checks if all values evaluate to true.
to_array (iterable)	Return an array version of the iterable.
to_coroutine (iterable)	Create a coroutine that yields the values of the iterable.
negate (predicate)	Create a negated function of predicate.
compose (f1, f2, ...)	Create a function composition from the given functions.
bind (func, ...)	Create a function with bound arguments.
accessor (t)	Create a function that accesses t.
item_getter (k)	Create a function that accesses the key k for a table.
bind_self (t, k, ...)	Create f bound function whose first argument is t.
constant (value)	Create a function that always returns the same value.
import ()	Import Iterator and commonly used functions into global scope.

Fields

_VERSION

Module version.

Class Iterator

Iterator.create (iterable)	Iterate over the given iterable.
Iterator.counter ()	Iterate over the naturals starting at 1.
Iterator.from_coroutine (co)	Iterate over the coroutine's yielded values.
Iterator.from_iterated_call (func)	Iterate over the function's returned values upon repeated calls
Iterator.clone (iterable)	Nondestructively return an indepent iterable from the given one.
Iterator:filter (predicate)	Select only values which match the predicate.
Iterator:map (mapping)	Map values into new values.
Iterator:reduce (reducer, initial_value)	Collapse values into a single value.
Iterator:foreach (func)	Apply a function to all values.
Iterator:take (n)	Iterate over the n first values and stop.
Iterator:skip (n)	Iterate over the values, starting at the (n+1)th one.
Iterator:every (n)	Take 1 value every n.
Iterator:any (predicate)	Checks if any values evaluate to true.
Iterator:all (predicate)	Checks if all values evaluate to true.
Iterator:count (predicate)	Counts how many values evaluate to true.
Iterator:to_array ()	Create an array out of the Iterator's values.
Iterator:to_coroutine ()	Create a coroutine that yields the values of the Iterator.
Iterator:is_complete ()	Check whether or not the iterator is done.

Functions

iterate (iterable)

Create an Iterator for the iterable.

Equivalent to

Iterator.create(iterable)

.

Parameters:

• iterable iterable the values to be iterated over

Returns:

Iterator the new Iterator

filter (iterable, predicate)

Select only values which match the predicate.

Equivalent to

iterate(iterable):filter(predicate)

.

Parameters:

• iterable iterable the values to be filtered
• predicate predicate the function to evaluate for each value

Returns:

Iterator the filtering Iterator

See also:

• iterate
• Iterator:filter

map (iterable, mapping)

Map values into new values.

Equivalent to

iterate(iterable):map(mapping)

.

Please note that at no point during iteration may the mapping function return nil as its first value.

Parameters:

• iterable iterable the values to be mapped
• mapping function the function to evaluate for each value

Returns:

Iterator the mapping Iterator

See also:

• iterate
• Iterator:map

reduce (iterable, reducer, initial_value)

Collapse values into a single value.

Equivalent to

iterate(iterable):reduce(reducer)

.

A reducer is a function of the form

function(accumulated_value, new_value)

which returns the reducing or "accumulation" of accumulated_value and new_value

The definition of "reducing" is flexible, and a few common examples include sum and concatenation.

Parameters:

• iterable iterable the values to be collapsed
• reducer reducer the collapsing function
• initial_value the initial value passed to the reducer

Returns:

the accumulation of all values

See also:

• iterate
• Iterator:reduce

foreach (iterable, func)

Apply a function to all values.

Equivalent to

iterate(iterable):foreach(func)

.

The main difference between foreach and map is that foreach ignores the return value(s) of its function, while map uses them and has restrictions on what it can return.

Another important difference is that map is a lazy evaluator, while foreach iterates over its values immediately.

Parameters:

• iterable iterable the values to be iterated over
• func function the function to apply for each value

See also:

• iterate
• Iterator:foreach

take (iterable, n)

Iterate over the n first values and stop.

Equivalent to

iterate(iterable):take(n)

.

Parameters:

• iterable iterable the values to be iterated over
• n integer amount of values to take

Returns:

Iterator the new Iterator

See also:

• iterate
• Iterator:take

skip (iterable, n)

Iterate over the values, starting at the (n+1)th one.

Equivalent to

iterate(iterable):skip(n)

.

Parameters:

• iterable iterable the values to be iterated over
• n integer amount of values to skip

Returns:

Iterator the new Iterator

See also:

• iterate
• Iterator:skip

every (iterable, n)

Take 1 value every n.

Equivalent to

iterate(iterable):every(n)

.

The first value is always taken.

Parameters:

• iterable iterable the values to be iterated over
• n integer one more than the number of skipped values

Returns:

Iterator the new Iterator

See also:

• Iterator:every
• iterate
• skip

any (iterable, predicate)

Checks if any values evaluate to true.

Equivalent to

iterate(iterable):any(predicate)

.

Parameters:

• iterable iterable the values to be iterated over
• predicate predicate the function to evaluate for each value, defaults to

  not (value == nil or value == false)

Returns:

boolean true if and only if at least one of the values evaluate to true

See also:

• Iterator:any
• iterate

all (iterable, predicate)

Checks if all values evaluate to true.

Equivalent to

iterate(iterable):all(predicate)

.

Parameters:

• iterable iterable the values to be iterated over
• predicate predicate the function to evaluate for each value, defaults to

  not (value == nil or value == false)

Returns:

boolean true if and only if all of the values evaluate to true

See also:

• Iterator:all
• iterate

to_array (iterable)

Return an array version of the iterable.

If iterable is an array, return itself.

If iterable is an Iterator, return

iterable:to_array()

Parameters:

• iterable iterable the values to make an array out of

Returns:

array the array

See also:

• Iterator:to_array
• iterate

to_coroutine (iterable)

Create a coroutine that yields the values of the iterable.

Equivalent to

iterate(iterable):to_coroutine()

.

Parameters:

• iterable iterable the values to be iterated over

Returns:

thread The new coroutine

See also:

• Iterator:to_coroutine
• iterate

negate (predicate)

Create a negated function of predicate.

Parameters:

• predicate predicate the function to be negated

Returns:

predicate the inverted predicate

compose (f1, f2, ...)

Create a function composition from the given functions.

Parameters:

• f1 function the outermost function of the composition
• f2 function the second outermost function of the composition
• ... function... any further functions to add to the composition, in order

Returns:

function the composite function

bind (func, ...)

Create a function with bound arguments.

The bound function returned will call func with the arguments passed on to its creation.

If more arguments are given during its call, they are appended to the original ones.

Parameters:

• func function the function to create a binding of
• ... the arguments to bind to the function.

Returns:

function the bound function

accessor (t)

Create a function that accesses t.

The argument passed to the returned function is used as the key k to be accessed. The value of t[k] is returned.

Parameters:

• t table the table to be accessed

Returns:

function the accessor

item_getter (k)

Create a function that accesses the key k for a table.

The argument passed to the returned function is used as the table t to be accessed. The value of t[k] is returned.

Parameters:

• k the key to access

Returns:

function the item getter

bind_self (t, k, ...)

Create f bound function whose first argument is t.

Particularly useful to pass a method as a function.

Equivalent to

bind(t[k], t, ...)

.

Parameters:

• t table the table to be accessed
• k the key to be accessed
• ... further arguments to bind to the function

Returns:

function the binding for t[k]

constant (value)

Create a function that always returns the same value.

Parameters:

• value the constant to be returned

Returns:

function the constant function

import ()

Import Iterator and commonly used functions into global scope.

Upon calling this, the following values will be added to global scope (_G) with the same names:

• Iterator
• iterate
• filter
• map
• reduce
• foreach
• take
• skip
• every
• any
• all

They can still be accessed through the module after the call.

Fields

_VERSION

Module version.

Class Iterator

Iterator.create (iterable)

Iterate over the given iterable.

If iterable is an array, create an Iterator instance that returns its values one by one. If it is an iterator, return itself.

Parameters:

• iterable iterable the values to be iterated over

Returns:

Iterator the new Iterator

Iterator.counter ()

Iterate over the naturals starting at 1.

Returns:

Iterator the counter

See also:

• Iterator:take
• Iterator:skip
• Iterator:every

Iterator.from_coroutine (co)

Iterate over the coroutine's yielded values.

Parameters:

• co thread the coroutine to iterate

Returns:

Iterator the new Iterator

Iterator.from_iterated_call (func)

Iterate over the function's returned values upon repeated calls

Parameters:

• func function the function to call

Returns:

Iterator the new Iterator

Iterator.clone (iterable)

Nondestructively return an indepent iterable from the given one.

If iterablet is an Iterator, clone it according to its subtype. If iterable is an array, then return itself.

Please note that coroutine and iterated function call iterators cannot be cloned.

Parameters:

• iterable iterable the iterable to be cloned

Returns:

iterable the clone

Iterator:filter (predicate)

Select only values which match the predicate.

Parameters:

• predicate predicate the function to evaluate for each value

Returns:

Iterator the filtering Iterator

Iterator:map (mapping)

Map values into new values.

Please note that at no point during iteration may the mapping function return nil as its first value.

Parameters:

• mapping function the function to evaluate for each value

Returns:

Iterator the mapping Iterator

Iterator:reduce (reducer, initial_value)

Collapse values into a single value.

A reducer is a function of the form

function(accumulated_value, new_value)

which returns the reducing or "accumulation" of accumulated_value and new_value

The definition of "reducing" is flexible, and a few common examples include sum and concatenation.

Parameters:

• reducer reducer the collapsing function
• initial_value the initial value passed to the reducer

Returns:

the accumulation of all values

Iterator:foreach (func)

Apply a function to all values.

The main difference between Iterator:foreach and Iterator:map is that foreach ignores the return value(s) of its function, while map uses them and has restrictions on what it can return.

Another important difference is that Iterator:map is a lazy evaluator, while Iterator:foreach iterates over its values immediately.

Parameters:

• func function the function to apply for each value

Iterator:take (n)

Iterate over the n first values and stop.

Parameters:

• n integer amount of values to take

Returns:

Iterator the new Iterator

Iterator:skip (n)

Iterate over the values, starting at the (n+1)th one.

Parameters:

• n integer amount of values to skip

Returns:

Iterator the new Iterator

Iterator:every (n)

Take 1 value every n.

The first value is always taken.

Parameters:

• n integer one more than the number of skipped values

Returns:

Iterator the new Iterator

See also:

Iterator:skip

Iterator:any (predicate)

Checks if any values evaluate to true.

Parameters:

• predicate predicate the function to evaluate for each value, defaults to

  not (value == nil or value == false)

Returns:

boolean true if and only if at least one of the values evaluate to true

Iterator:all (predicate)

Checks if all values evaluate to true.

Parameters:

• predicate predicate the function to evaluate for each value, defaults to

  not (value == nil or value == false)

Returns:

boolean true if and only if all of the values evaluate to true

Iterator:count (predicate)

Counts how many values evaluate to true.

Parameters:

• predicate predicate function to evaluate for each value; if nil, then counts all values.

Returns:

integer the number of values that match the predicate

Iterator:to_array ()

Create an array out of the Iterator's values.

Returns:

array the array of values

Iterator:to_coroutine ()

Create a coroutine that yields the values of the Iterator.

Returns:

thread The new coroutine

Iterator:is_complete ()

Check whether or not the iterator is done.

Please note that even if the iterator has reached its actual last value, it has no way of knowing it was the last. Therefore, this function will only return true once the iterator returns nil for the first time.

Returns:

boolean true if the Iterator has iterated over all its values.