#cp.fn

A collection of functions that are useful for working with functions. Heavily inspired by Point-Free's Overture library for Swift.

In general, the functions in this module come in two categories:

Functions which perform an action directly.
Functions which return a new function.

The second category of functions are called "combinators". A combinator is a function that returns a new function, often with configuration parameters passed in.

#Submodules

#API Overview

Functions - API calls offered directly by the extension

all
any
call
chain
compare
compose
constant
curry
debug
flip
fork
identity
ifilter
none
over
pipe
prefix
reduce
resolve
set
uncurry
with

#API Documentation

#Functions

#all


Signature	`cp.fn.all(...) -> function`
Type	Function
Description	A combinator that returns a function that passes its arguments to all the functions in `fns` and returns the last result, if all functions return a `truthy` value. Otherwise, it returns `nil`.
Parameters	... - A table or list of functions to call.
Returns	A function that passes its arguments to all the functions in `fns` and returns the last result, if all functions return a `truthy` value.
Notes	None
Examples	None
Source	src/extensions/cp//fn.lua line 52

#any


Signature	`cp.fn.any(...) -> function`
Type	Function
Description	A combinator that returns a function that passes its arguments to all the functions in `fns` and returns the first `truthy` result, or `nil` if all functions return a `falsy` value.
Parameters	... - A table or list of functions to call.
Returns	A function that passes its arguments to all the functions in `fns` and returns the first `truthy` result, or `nil` if all functions return a 'falsy' value.
Notes	None
Examples	None
Source	src/extensions/cp//fn.lua line 82

#call


Signature	`cp.fn.call(fn) -> ...`
Type	Function
Description	Calls the function `fn` with no arguments, returning the result.
Parameters	fn - The function to call.
Returns	The results of the function call.
Notes	None
Examples	None
Source	src/extensions/cp//fn.lua line 169

#chain


Signature	`cp.fn.chain(...) -> function`
Type	Function
Description	Chain a series of functions together, passing the results of each function on to the next one, returning the last result, or returning `nil` immediately after all results of a function are `nil`.
Parameters	... - A list of functions.
Returns	A function that takes any number of inputs and returns any number of inputs.
Notes	The difference between `chain` and `pipe` is that chain will fail early with a `nil` result, while `pipe` will pass the `nil` onto the next function. Alternately, you can create a chain using the `//` operator, followed by `>>` for each subsequent function. Eg: `chain // fn1 >> fn2 >> fn3`. If using the alternate syntax, you may have to put parentheses around the chain if mixing with other operators like `pipe` or `compose`.
Examples	None
Source	src/extensions/cp//fn.lua line 634

#compare


Signature	`cp.fn.compare(...) -> function`
Type	Function
Description	A combinator that returns a function that checks each provided comparator in turn, returning `true` if the given comparator returns `true`, otherwise if the values are equal, checks the next comparator, and so on.
Parameters	... - A list of comparators.
Returns	A function that takes two inputs and `true` if the first input is less than the second input.
Notes	The comparators are called in the order they are provided. If no comparators are provided, returns a `nil` function, which is generally sorted with the standard `<` operator.
Examples	None
Source	src/extensions/cp//fn.lua line 182

#compose


Signature	`cp.fn.compose(...) -> function`
Type	Function
Description	A combinator that performs backwards composition of functions, returning a function that is the composition of a list of functions processed from last to first.
Parameters	fns	... - A table or a list of functions.
Returns	A function that takes the input for the last function, and returns the result of the first function.
Notes	None
Examples	None
Source	src/extensions/cp//fn.lua line 221

#constant


Signature	`cp.fn.constant(value) -> function`
Type	Function
Description	A combinator that returns a function that always returns the `value`.
Parameters	value - The value to return.
Returns	A function that always returns the value `value`.
Notes	None
Examples	None
Source	src/extensions/cp//fn.lua line 241

#curry


Signature	`cp.fn.curry(function, argCount) -> function`
Type	Function
Description	Curries a function with the specified number of arguments, returning a function that accepts the first argument. It will return other functions that accept the second argument, and so on, until the final argument is collected, and the values are passed to the original function.
Parameters	fn - The function to curry. argCount - The number of arguments to accept.
Returns	A function that accepts the first argument.
Notes	None
Examples	None
Source	src/extensions/cp//fn.lua line 280

#debug


Signature	`cp.fn.debug(message, ...) -> function`
Type	Function
Description	Returns a function that will print the provided message to the console.
Parameters	message - The message to print to the console. ... - Optional functions to call with the values passed to the returned function.
Returns	A function that will print the provided message to the console.
Notes	This is useful for debugging, but is not recommended for production code. For example, the following will return "b" and also print `"table: 0xXXXXXXXXX"` and `"b"` to the console: `fn.chain // fn.constant({"a", "b", "c"}) >> fn.debug("%d") >> fn.table.get(2) >> fn.debug("%d")` Optional functions can be passed in, which will be provided the values passed to the returned function. If not provided, the values will be passed into the message for formatting directly. The returned function will always return the values passed in.
Examples	None
Source	src/extensions/cp//fn.lua line 654

#flip


Signature	`cp.fn.flip(fn) -> function`
Type	Function
Description	A combinator that flips the order of the next two arguments to a curried function.
Parameters	fn - The function to flip.
Returns	A function that accepts the second argument and returns a function expecting the first argument.
Notes	If multiple arguments are provided for either function, the order of the arguments within that list are not flipped.
Examples	None
Source	src/extensions/cp//fn.lua line 296

#fork


Signature	`cp.fn.fork(...) -> function`
Type	Function
Description	A combinator that returns a function that returns the result of calling `...` with the functions passed in. This can be used to split an input into multiple outputs.
Parameters	... - A table or list of functions to call.
Returns	A function that returns the result of calling `...` with the functions passed in.
Notes	None
Examples	None
Source	src/extensions/cp//fn.lua line 140

#identity


Signature	`cp.fn.identity(...) -> ...`
Type	Function
Description	Returns the values passed in.
Parameters	... - The values to return.
Returns	The values passed in.
Notes	None
Examples	None
Source	src/extensions/cp//fn.lua line 318

#ifilter


Signature	`cp.fn.ifilter([predicate]) -> function(table) -> table`
Type	Function
Description	Returns a function that filters a table using the given predicate, in index order. If the predicate is not provided, the original table will be returned unchanged.
Parameters	predicate - A function that takes a value and returns true if the value should be included in the filtered table.
Returns	A function that takes a table and returns a filtered table.
Notes	None
Examples	None
Source	src/extensions/cp/fn/table.lua line 173

#none


Signature	`cp.fn.none(...) -> function`
Type	Function
Description	A combinator that returns a function that passes its arguments to all the functions in `fns` and returns `true` if the first return value from each is `falsey`, otherwise it returns `false`.
Parameters	... - A table or list of functions to call.
Returns	A function which will be `true` if all of the functions in `fns` are `falsy`.
Notes	None
Examples	None
Source	src/extensions/cp//fn.lua line 113

#over


Signature	`cp.fn.over(setter, fn) -> function`
Type	Function
Description	A combinator that returns a function that applies the transform function to the `setter`.
Parameters	setter - An immutable setter function. tx - A value transform function.
Returns	A root transform function.
Notes	None
Examples	None
Source	src/extensions/cp//fn.lua line 331

#pipe


Signature	`cp.fn.pipe(...) -> function`
Type	Function
Description	A combinator that pipes a series of functions together, passing the results of each function on to the next one. The returned function takes any number of inputs and may return any number of inputs, depending on the results of the final function.
Parameters	fns	... - A table or list of functions.
Returns	A function that takes any number of inputs and returns any number of inputs.
Notes	The difference between `chain` and `pipe` is that chain will fail early with a `nil` result, while `pipe` will pass the `nil` onto the next function.
Examples	None
Source	src/extensions/cp//fn.lua line 345

#prefix


Signature	`cp.fn.prefix(fn, ...) -> function`
Type	Function
Description	Prefixes the provided values as the first arguments to the function.
Parameters	fn - The function to prefix. ... - The arguments to prefix the function with.
Returns	A function that takes the remainder of `fn`'s arguments and returns the result of `fn` with the provided arguments prepended.
Notes	None
Examples	None
Source	src/extensions/cp//fn.lua line 370

#reduce


Signature	`cp.fn.reduce(fn, initial, ...) -> any`
Type	Function
Description	Reduces a list of values into a single value.
Parameters	fn - The function to reduce with. initial - The initial value to start with. ... - The table or list of values to reduce.
Returns	The reduced value.
Notes	None
Examples	None
Source	src/extensions/cp//fn.lua line 396

#resolve


Signature	`cp.fn.resolve(value, ...) -> any`
Type	Function
Description	If the value is a function, calls it with the provided arguments, otherwise returns the value.
Parameters	value - The value to resolve. ... - The arguments to pass to the function.
Returns	The resolved value.
Notes	None
Examples	None
Source	src/extensions/cp//fn.lua line 416

#set


Signature	`cp.fn.set(setter, value) -> function`
Type	Function
Description	Applies a value to an immutable `setter` function.
Parameters	setter - An immutable setter function (function(A -> B) -> function(S) -> T) value - A new value.
Returns	A root transform function.
Notes	None
Examples	None
Source	src/extensions/cp//fn.lua line 433

#uncurry


Signature	`cp.fn.uncurry(fn, argCount) -> function`
Type	Function
Description	Uncurry a curried function with the specified number of arguments, returning a function the specified number of arguments.
Parameters	fn - The function to uncurry. argCount - The number of arguments to uncurry.
Returns	A function that takes the specified number of arguments.
Notes	None
Examples	None
Source	src/extensions/cp//fn.lua line 465

#with


Signature	`cp.fn.with(value, fn) -> function`
Type	Function
Description	A combinator that returns a function that will call the provided function with the provided value as the first argument.
Parameters	value - The value to pass to the function. fn - The function to call.
Returns	A function that will call the provided function with the provided value as the first argument.
Notes	None
Examples	None
Source	src/extensions/cp//fn.lua line 481