[ANN] stdlib 37 released

[Gary Vaughan <gary@...>]

General Lua Libraries

I am ashamed to have to announce the re-release of stdlib 37.

stdlib's home page is at http://rrthomas.github.io/lua-stdlib

Stdlib v36 tripped a bug in LuaRocks, so I rushed out a v37 and missed
the opportunity to fix some outstanding bugs and gotchas that shouldn't
have been in v36 or v37.

This release is in much better shape, and is vastly more compatible with
earlier releases.  If you tried to port anything substantial from an
earlier stdlib to either v36 or the first botched v37 and tripped over
the incompatibilities, please accept my apologies, and try again with
this release.  There are still a few incompatibilities (mostly changing
from getopt to optparse).

I ported GNU Zile, which uses stdlib extensively, from v34.1 to this
release in a few minutes, with only the optparse upgrade, two require
statments with a '_ext' to remove, and one bad assumption in a 2 line
function to tweak -- everything else continues to work as before, even
though Zile still uses the old deprecated APIs.

* Noteworthy changes in release 37 (2014-01-19) [stable]

** New features:

 - Lazy loading of submodules into `std` on first reference.  On initial
   load, `std` has the usual single `version` entry, but the `__index`
   metatable will automatically require submodules on first reference:

      local std = require "std"
      local prototype = std.container.prototype

 - New `std.optparse` module: A civilised option parser.
   (L)Documentation distributed in doc/classes/std.optparse.html.

** Bug fixes:

 - Modules no longer leak `new' and `proper_subset' into the global
   table.

 - Cloned `Object` and `Container` derived types are more aggressive
   about sharing metatables, where previously the metatable was copied
   unnecessarily the base object used `_functions` for module functions

 - The retracted release 36 changed the operand order of many `std.list`
   module functions unnecessarily.  Now that `_function` support is
   available, there's no need to be so draconian, so the original v35
   and earlier operand order works as before again.

 - `std.list.new`, `std.set.new`, `set.strbuf.new` and `std.tree.new`
   are available again for backwards compatibility.

 - LuaRocks install doesn't copy config.ld and config.ld to $docdir.

** Incompatible changes:

 - `std.getopt` is no more. It appears to have no users, though if there
   is a great outcry, it should be easy to make a compatibility api over
   `std.optparse` in the next release.


This release also contains all the improvements from release 36. The
following is editted slightly from the distributed NEWS file to remove
mention of changes that have been fixed or undone above:

* Noteworthy changes in release 36 (2014-01-16) [stable]

** New features:

 - Modules have been refactored so that they can be safely
   required individually, and without loading themselves or any
   dependencies on other std modules into the global namespace.

 - Objects derived from the `std.object` prototype have a new
   <derived_object>:prototype () method that returns the contents of the
   new internal `_type` field.  This can be overridden during cloning
   with, e.g.:

      local Object = require "std.object"
      Prototype = Object { _type = "Prototype", <other_fields> }

 - Objects derived from the `std.object` prototype return a new table
   with a shallow copy of all non-private fields (keys that do not
   begin with "_") when passed to `table.totable` - unless overridden
   in the derived object's __totable field.

 - list and strbuf are now derived from `std.object`, which means that
   they respond to `object.prototype` with appropriate type names ("List",
   "StrBuf", etc.) and can be used as prototypes for further derived
   objects or clones; support object:prototype (); respond to totable etc.

 - A new Container module at `std.container` makes separation between
   container objects (which are free to use __index as a "[]" access
   metamethod, but) which have no object methods, and regular objects
   (which do have object methods, but) which cannot use the __index
   metamethod for "[]" access to object contents.

 - set and tree are now derived from `std.container`, so there are no
   object methods.  Instead there are a full complement of equivalent
   module functions.  Metamethods continue to work as before.

 - `string.prettytostring` always displays table elements in the same
   order, as provided by `table.sort`.

 - `table.totable` now accepts a string, and returns a list of the
   characters that comprise the string.

 - Can now be installed directly from a release tarball by `luarocks`.
   No need to run `./configure` or `make`, unless you want to install to
   a custom location, or do not use LuaRocks.

** Bug fixes:

 - string.escape_pattern is now Lua 5.2 compatible.

 - all objects now reuse prototype metatables, as required for __le and
   __lt metamethods to work as documented.

** Deprecations:

 - To avoid confusion between the builtin Lua `type` function and the
   method for finding the object prototype names, `std.object.type` is
   deprecated in favour of `std.object.prototype`. `std.object.type`
   continues to work for now, but might be removed from a future
   release.

      local prototype = (require 'std.object').prototype

   ...makes for more readable code, rather than confusion between the
   different flavours of `type`.

** Incompatible changes:

 - Following on from the Grand Renaming™ change in the last release,
   `std.debug_ext`, `std.io_ext`, `std.math_ext`, `std.package_ext`,
   `std.string_ext` and `std.table_ext` no longer have the spurious
   `_ext` suffix.  Instead, you must now use, e.g.:

      local string = require "std.string"

   These names are now stable, and will be available from here for
   future releases.

 - The `std.set` module is a `std.container` with no object methods,
   and now uses module functions instead:

     local union = Set.union (set1, set2)


Install it with LuaRocks, using:

    luarocks install stdlib 37

Until the rocks are available from the official repository in a few days,
you can install directly from the stdlib release branch, with:

    $ luarocks install \
    http://raw.github.com/rrthomas/lua-stdlib/release-v37/stdlib-37-1.rockspec