Penlight Lua Libraries

1. Why a new set of libraries?

Penlight brings together a set of generally useful pure Lua modules,
focussing on input data handling (such as reading configuration files),
functional programming (such as map, reduce, placeholder expressions,etc),
and OS path management.  Much of the functionality is inspired by the
Python standard libraries.

2. Requirements

The file and directory functions depend on LuaFileSystem (lfs). If you want
dir.copyfile to work properly on Windows, then you need Alien. (Both are
present in Lua for Windows.)

3. What's New with 0.6.3?

The map and reduce functions now take the function first, as Nature intended.

The Python-like overloading of '*' for strings has been dropped, since it
is silly. Also, strings are no longer callable; use 's:at(1)' instead of
's(1)' - this tended to cause Obscure Error messages.

Wherever a function argument is expected, you can use the operator strings
like '+','==',etc as well as pl.operator.add, pl.operator.eq, etc.
(see end of pl/operator.lua for the full list.)

tablex now has compare() and compare_no_order(). An explicit set()
function has been added which constructs a table with the specified
keys, all set to a value of true.

List has reduce() and partition() (This is a cool function which 
separates out elements of a list depending on a classifier function.)

There is a new array module which generalizes tablex operations like
map and reduce for two-dimensional arrays.

The famous iterator over permutations from PiL 9.3 has been included.

David Manura's list comprehension library has been included.

Also, utils now contains his memoize function, plus a useful function
args which captures the case where varargs contains nils.

There was a bug with dir.copyfile() where the flag was the wrong way round.

config.lines() had a problem with continued lines.

Some operators were missing in pl.operator; have renamed them to be
consistent with the Lua metamethod names.

4. What's New with 0.7.0b?

Features:

utils.is_type(v,tp) can say is_type(s,'string') and is_type(l,List).
utils.is_callable(v) either a function, or has a __call metamethod.

Sequence wrappers: can write things like this:

seq(s):last():filter('<'):copy()

seq:mapmethod(s,name) - map using a named method over a sequence.

seq:enum(s)  If s is a simple sequence, then 
     for i,v in seq.enum(s) do print(i,v) end

seq:take(s,n)  Grab the next n values from a (possibly infinite)
sequence.

In a related change suggested by Flemming Madsden, the in-place List
methods like reverse() and sort() return the list, allowing for
method chaining.

list.join()  explicitly converts using tostring first.

tablex.count_map() like seq.count_map(), but takes an equality function.

tablex.difference()  set difference
tablex.set()  explicit set generator given a list of values

Template.indent_substitute() is a new Template method which adjusts
for indentation and can also substitute templates themselves.

pretty.read(). This reads a Lua table (as dumped by pretty.write)
and attempts to be paranoid about its contents.

sip.match_at_start(). Convenience function for anchored SIP matches.

Bug Fixes:

tablex.deepcompare() was confused by false boolean values, which
it thought were synonymous with being nil.

pretty.write() did not handle cycles, and could not display tables
with 'holes' properly (Flemming Madsden)

The SIP pattern '$(' was not escaped properly.
sip.match() did not pass on options table.

seq.map() was broken for double-valued sequences.
seq.copy_tuples() did not use default_iter(), so did not e.g. like
table arguments.

dir.copyfile() returns the wrong result for *nix operations.
dir.makepath() was broken for non-Windows paths.

5. Known Issues

Error handling is still hit and miss.

There are 4462 lines of source and 497 lines of formal tests, 
which is not an ideal ratio.

pretty.write is not such a pretty Lua table formatter as it thinks.

Formal documentation for comprehension and luabalanced is missing.

5. Installation

The directory structure is

  lua
     pl 
       (module files)
  examples
     penlight
        (examples)
        tests
           (tests)
  docs
     penlight
        (index.html)
        (examples.html)
        api
           (index.html)
           modules

With Lua for Windows, you can unzip into the base Lua directory,
 e.g. 'c:\Program Files\Lua\5.1'.

Otherwise, make sure that 'pl' is sitting on your module path.

6. Building the Documentation

The Users Guide is processed by markdown.lua. If you like the section headers,
you'll need to download my modified version:

http://mysite.mweb.co.za/residents/sdonovan/lua/markdown.zip

docgen.lua will preprocess the documentation (handles @see references)
and use markdown.

gen_modules.bat does the LuaDoc stuff.