CHANGELOG README @@ -3,8 +3,14 @@ -- output = assert(io.open('functional.mkd', "w")) -input = assert(io.open('functional.lua')) +-- First pull in README +input = assert(io.open('README')) +output:write(input:read("*a")) +input:close() + +-- Then pull in docs from the source +input = assert(io.open('functional.lua')) for line in input:lines() do if in_block_comment then s, e, m = line:find("(.-)]]") doc.lua @@ -1,58 +1,4 @@ --[[[ -`lua-functional` provides a set of higher-order functions typically found in -functional languages. - -* Homepage: [http://www.samsarin.com/blog/lua-functional](http://www.samsarin.com/blog/lua-functional) -* Download: [http://github.com/samsarin/lua-functional](http://github.com/samsarin/lua-functional) -* Current Version: 0.1 -* License: [MIT License](http://www.opensource.org/licenses/mit-license.php) - -Contents: - -* [Concepts](#concepts) -* [Function Reference](#reference) - -### Concepts {#concepts} - -#### Sequences {#sequence} - -This library provides several functions that work with a "sequence". A sequence -as defined by this library is something that can be iterated over. A Lua table -is a sequence and can be passed to any function that accepts a sequence. In -addition, it is possible to use a "wrapped iterator" as a sequence. A -wrapped iterator allows a custom iterator to be used instead of a table. - -As a contrived example, you may want to concatenate a sparse array of strings -into a single string. In Lua, the end of the array is inidcated by a nil value, -so the traditional array iterator, [ipairs][], would stop concatenation as soon -as an element in the array is nil. However, you can use a custom iterator -to achieve the desired effect: - - local array = { 'a', 'b', 'c', nil, 'e' } - local sequence = functional.wrap_iter(functional.nipairs(array)) - local concatenate = function(t, v) return v and t .. v or t end - local result = functional.reduce(concatenate, "", sequence) - print(result) - -results in: - - abce - -The example above uses a custom iterator from the functional module, nipairs, -which iterates through a spare array until it hits the last index. The iterator -is "wrapped" with [wrap_iter](#wrap_iter), which creates a single object that -can be passed as a sequence to a higher-order function. - -#### Tables vs. Arrays - -In Lua the most basic data structure is a table, not a list as in most -functional languages. Most higher-order functions in this project treat -sequences as arrays. That is, they are treated as they have a well-defined -order and the keys are ignored. Only where specifically stated do higher-order -functions use tables as an unordered collection of key/value pairs. - -[ipairs]: http://www.lua.org/manual/5.1/manual.html#pdf-ipairs -[generic for]: http://www.lua.org/pil/7.2.html ### Function Reference {#reference} ]] functional.lua 2cac6fe6ba5d95f3d53700ca648a467a668fb06e Chris Pettitt cpettitt@gmail.com http://github.com/samsarin/lua-functional/commit/5d44d721146acaf30dc6591088f5d1f49d472d5a 5d44d721146acaf30dc6591088f5d1f49d472d5a 2008-05-29T19:31:26-07:00 2008-05-29T19:31:26-07:00 Additional documentation improvements. - Moved the documentation at the top of functionl.lua to README - Modified doc.lua to include README in doc generation - Added a CHANGELOG 92ba99310bac0c4e3812f4ef357ecefc76a8fbab Chris Pettitt cpettitt@gmail.com