Core Functions Proposal

wiki

In general, the functions tend to take iterators, except where it makes more sense to pass tables directly. Harmonizing this aspect is still an ongoing process. filter and find_if_iter are essentially the same operation, except the second returns a sequence. Perhaps filter should return a sequence, and one can use collect if one wants an array result.

--- string functions -----

function split(s: string, delim: string = '%s+'): array

Comments: See SplitJoin. split functions also often have a "limit" parameter [1]. Corner cases will need to be specified (e.g. how empty patterns behave) as done in the specifications in "Comparison to Other Languages" in SplitJoin.

-- escapes Lua string 'magic' characters
function escape(s: string): string

--- extended table and sequence functions 

-- shallow copy either of a table
function copy(t: table): table

-- collect a single-valued sequence as an array
-- e.g. collect(lfs.dir '.')
function collect(seq: iterator): array

-- collect a double-valued sequence as an array of pairs
-- e.g. collect2(pairs{a=2,b=2}) => {{'a',2},{'b',2}}
function collect2(seq: iterator2): array

    -- Suggestion: Instead of 2 values, define a function that allows
    -- an arbitrary number of return values, improving generality.
    -- AlexandreErwinIttner
    -- e.g. collectn(myIterator) => {{'a',2,'foo'},{'b',2},{'bar'}}
    function collectn(seq: iterator): array

-- construct a generator over all the values of the array;
-- otherwise tries to use the __iter metamethod
-- collect(iter(t)) is an identity function for an array t
function iter(t: object): callable

-- convert a single valued sequence into a sequence of index,value
-- enum(iter(t)) is equivalent to ipairs(t)
function emum(t: iterator): keyval_iter

-- create an array over a range of numbers, arguments as
-- in the numeric for statement
-- e.g. range(1,5) => {1,2,3,4,5}
function range(x1: number, x2:number, x3:number = nil): array

-- recursive copy, preserving metatables
function deepcopy(t: table): table

-- recursive compare, can ignore metatables
function deepcompare(t1: value, t2: value, ignore_meta: boolean = false): boolean

-- basic recursive table-to-string dump, intended for debug purposes.
-- will handle cycles, not guaranteed to result in parseable Lua.
-- An extra argument may be used to control the result, but the default should be sensible.
function dump(t: table, options: table = nil): string

function values(t: hash): array

function keys(t: hash): array

-- construct a table which is the result of applying a function
-- to a key-value iterator like pairs or ipairs
-- e.g. map(tonumber,ipairs {'1','2'}) => {1,2}
-- e.g. map(string.upper,pairs{a='one',a='two'}) => {a='ONE',b='TWO'}
function map(f: callable, iter: keyval_iter): table

-- construct an array with elements which are arrays chosen from the
-- next element of each array.
-- zip({1,2,3},{10,20,30}) -> {{1,10},{2,20},{3,30}}
function zip(t1: array, t2:array, ...): array

-- make a map from an array of pairs where the keys are the first value
-- and the values are the second value
-- keymap{{'a',1},{'b',2}} -> {a = 1, b = 2}
-- keymap(collect2(pairs(t))) is an identity function for hashes.
function keymap(t: array): hash

-- take an array contain subarrays and generate a flattened array
-- e.g. {1,{2,3}} -> {1,2,3}
function flatten(t: array): array

-- e.g. {1,2,2,3,3,3} -> {1,2,3}
function unique(t: array): array

-- apply a binary function to all elements of an array in pairs
-- reduce(+,{1,2,3}) can be defined as 1 + reduce(+,{2,3}) etc
function reduce(f: callable2, t: array): array

-- look for value in key/value sequence using simple value equality
-- find(2,ipairs{10,4,2}) -> 3
-- find(2,pairs{a=1,b=2}) -> 'b'
-- find(2,ipairs_slice({2,2,3},2)) -> 2
function find(val: value, iter: keyval_iter): key

-- look for key in key/value sequence using predicate function
function find_if(f: predicate, iter: keyval_iter): key,value

-- like find, but returns a keyval_iter
-- e.g for i in find_iter(3,ipairs(t)) do ... end
function find_iter(val: value, iter: keyval_iter): keyval_iter

-- like find_if, but returns a keyval_iter
function find_if_iter(f: predicate, iter: keyval_iter): keyval_iter

-- in simplest form, transforms an array into a set: {'a','b'} => {a=true,b=true}
-- generally, f will be called with each value and returns new value, new key
-- I.e. a generalized map function from arrays to hashes.
function makeset(t: array, f: callable = nil): hash  

-- intersection of two hash-like tables; in its basic form, set intersection
-- if choose is defined, will allow you to choose between two different
-- values for the same key; will default to picking the value from the first table.
-- e.g. intersect({a=1,b=2},{b=3,c=4}) => {a=1,b=2}
-- e.g. intersect({a=1,b=2},{b=3,c=4},function(x,y) return x>y end) => {a=1,b=3}
function intersect(t1,t2: hash, choose: predicate2 = nil): hash

-- union of two hash-like tables, set union.
-- choose operates as in intersect above
function union(t1,t2: hash, choose: predicate2 = nil): hash

-- like string.sub
function slice(t: array, i1: index, i2: index = -1): array  

-- like slice, but returns a key/value iterator like ipairs()
function ipairs_slice(t: array, i1: index, i2: index = -1): iterator2

-- append the values from t2 to t1, returns t1
function extend(t1: array, t2: array): array

-- concatenate two arrays to form a new array
function tjoin(t1: array, t2: array): array

-- return a table with values matching a predicate function f
-- filter(f,pairs(t)) and filter(f,ipairs(t)) are the common patterns.
function filter(f: predicate, iter: keyval_iter): table

-- like the old table.foreach, but passes value first, then key to f
-- This simplifies the common case of just operating on the value.
-- (The argument order is open to debate)
function forall(f: callable, iter: keyval_iter)   

-- like table.concat, but uses tostring() and ipairs()
function concat(t: array, delim: string): string 

-- update the first hash by adding the key/value pairs of the sequence.
-- returns the first hash for convenience.
function update(t1: hash, iter: keyval_iter): hash

--- Functional Support ----

-- returns the function |...| f(g(...))
function combine(f,g: callable): function

-- returns the function |...| f(first_arg,...)
function bind_first(f: callable, first_arg: value): function

-- returns the function |x| f(x,...)
function bind_rest(f: callable, ...): function

--- Path functions ---

-- joins up to three parts together using the appropriate path separator
function join(p1: path, p2: path, p3: path = nil)

-- will always provide suitable full path to temporary name, even on Windows
function tmpname(): string  

-- splits a filesystem path into a table with the directory, name and extension parts
-- (e.g, splitpath(p).ext will get the extension)
function splitpath(p: path): {dir=string,name=string,ext=string}

-- turns a filesystem glob pattern into an equivalent Lua string pattern
-- e.g. glob '*.lua' -> '.+%.lua$'
function glob(p: mask): pattern

-- the path where the given module will be found by Lua
-- note 1: may be part of 5.2
-- note 2: assumes standard path matching
function packagepath(mod: string): path

-- the full path of the current script, usually passed arg[0] (but uses this by default)
function progpath(name: string = nil): path

-- adds the current progpath to package.path, so that subsequent require calls
-- will look in this directory first.
function require_here(path: string = nil)

Here are some useful functional features which are not necessarily part of the core.

-- usually, 'callable' means either a function or an object that defines __call.
-- This allows you to handle the case where a callable argument is neither, 
-- e.g. is a string.
function add_callable_handler(f: callable)

-- returns a standard Lua operation, optionally with the second value bound.
-- e.g. filter(operator('>',3),ipairs{1,4,2,6}) -> {4,6}
-- e.g  map(operator('[]',1),pairs{a={1,10},b={2,20}}) -> {a=1,b=2}
function operator(s: operator, arg: value = nil): value

SteveDonovan