lua-users home
lua-l archive

[Date Prev][Date Next][Thread Prev][Thread Next] [Date Index] [Thread Index]


stdlib is a library of modules for common programming tasks, including list,
table and functional operations, objects, pickling, pretty-printing and
command-line option parsing.

I am happy to announce release 41.0.0 of stdlib.

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

With this release stdlib is moving to semantic versioning.  It is a beta
release because it constitutes a virtual rewrite, including a fairly
substantial reorganisation that makes the libraries clearer and easier
to use, but at the cost of drop-in backwards compatibility.  In particular,
the list module is liable to change radically for better functional
programming support in an upcoming release.

Some of the newest features, such as gradual typing at API boundaries,
and interfacing with the std.debug module are somewhat half-baked, so you
shouldn't use them unless you are happy to rewrite your code for future
releases of stdlib.

None-the-less, this is a useful and solid update, and is worth upgrading to
now if you plan to transition to future stable releases without the pain
of everything changing all at once... especially if you want to support
the upcoming Lua 5.3 release.


## Noteworthy changes in release 41.0.0 (2015-01-03) [beta]

### New features

  - Preliminary Lua 5.3.0 compatibility.

  - `object.prototype` now reports "file" for open file handles, and
    "closed file" for closed file handles.

  - New `debug.argerror` and `debug.argcheck` functions that provide Lua
    equivalents of `luaL_argerror` and `luaL_argcheck`.

  - New `debug.argscheck` function for checking all function parameter
    types with a single function call in the common case.

  - New `debug.export` function, which returns a wrapper function for
    checking all arguments of an inner function against a type list.

  - New `_DEBUG.argcheck` field that disables `debug.argcheck`, and
    changes `debug.argscheck` to return its function argument unwrapped,
    for production code.  Similarly `_DEBUG = false` deactivates these
    functions in the same way.

  - New `std.operator` module, with easier to type operator names (`conj`,
    `deref`, `diff`, `disj`, `eq`, `neg`, `neq`, `prod`, `quot`, and `sum`),
    and a functional operator for concatenation `concat`; plus new mathematical
    operators `mod`, and `pow`; and relational operators `lt`, `lte`, `gt` and
    `gte`.

  - `functional.case` now accepts non-callable branch values, which are
    simply returned as is, and functable values which are called and
    their return value propagated back to the case caller.  Function
    values behave the same as in previous releases.

  - `functional.collect`, `functional.filter`, `functional.map` and
    `functional.reduce` now work with standard multi-return iterators,
    such as `std.pairs`.

  - `functional.collect` defaults to using `std.ipairs` as an iterator.

  - New `functional.cond`, for evaluating multiple distinct expressions
    to determine what following value to be the returned.

  - `functional.filter` and `functional.map` default to using `std.pairs`
    as an iterator.

  - The init argument to `functional.foldl` and `functional.foldr` is now
    optional; when omitted these functions automatically start with
    the left- or right-most element of the table argument resp.

  - New `functional.callable` function for unwrapping objects or
    primitives that can be called as if they were a function.

  - New `functional.lambda` function for compiling lambda strings:

    ```lua
    table.sort (t, lambda "|a,b| a<b")
    ```

    or, equivalently using auto-arguments:

    ```lua
    table.sort (t, lambda "= _1 < _2"
    ```

  - New `functional.map_with` that returns a new table with keys matching
    the argument table, and values made by mapping the supplied function
    over value tables.  This replaces the misplaced, and less powerful
    `list.map_with`.

  - `functional.memoize` now propagates multiple return values correctly.
    This allows memoizing of functions that use the `return nil, "message"`
    pattern for error message reporting.

  - New `functional.nop` function, for use where a function is required
    but no work should be done.

  - New `functional.zip`, which in addition to replacing the functionality
    of deprecated `list.transpose` when handling lists of lists, correctly
    zips arbitrary tables of tables, and is orthogonal to `functional.map`.
    It is also more than twice as fast as `list.transpose`, processing
    with a single pass over the argument table as opposed to the two
    passes and addition book-keeping required by `list.transpose`s
    algorithm.

  - New `functional.zip_with`, subsumes functionality of deprecated
    `list.zip_with`, but also handles arbitrary tables of tables correctly,
    and is orthogonal to `functional.map_with`.

  - `std` module now collects stdlib functions that do not really belong
    in specific type modules: including `std.assert`, `std.eval`, and
    `std.tostring`. See LDocs for details.

  - New `std.ipairs` function that ignores `__ipairs` metamethod (like Lua
    5.1 and Lua 5.3), while always iterating from index 1 through n, where n
    is the last non-`nil` valued integer key. Writing your loops to use
    `std.ipairs` ensures your code will behave consistently across supported
    versions of Lua.

    All of stdlib's implementation now uses `std.ipairs` rather than `ipairs`
    internally.

  - New `std.ielems` and `std.elems` functions for iterating sequences
    analagously to `std.ipairs` and `std.pairs`, but returning only the
    value part of each key-value pair visited.

  - New `std.ireverse` function for reversing the proper sequence part of
    any table.

  - New `std.pairs` function that respects `__pairs` metamethod, even on
    Lua 5.1.

    All of stdlib's implementation now uses `std.pairs` rather than `pairs`
    internally. Among other improvements, this makes for a much more
    elegant imlementation of `std.object`, which also behaves intuitively
    and consistently when passed to `std.pairs`.

  - `std.require` now give a verbose error message when loaded module does not
    meet version numbers passed.

  - New `std.ripairs` function for returning index & value pairs in
    reverse order, starting at the highest non-nil-valued contiguous integer
    key.

  - New `table.len` function for returning the length of a table, much like
    the core `#` operation, but respecing `__len` even on Lua 5.1.

  - New `table.insert` and `table.remove` that use `table.len` to
    calculate default *pos* parameter, as well as diagnosing out of bounds
    *pos* parameters consistently on any supported version of Lua.

  - `table.insert` returns the modified table.

  - New `table.maxn` is available even when Lua compiled without
    compatibility, but uses the core implementation when possible.

  - New `table.okeys` function, like `table.keys` except that the list of
    keys is returned with numerical keys in order followed by remaining
    keys in asciibetical order.

  - `std.tostring`, `std.string.prettytostring` and the base `std.object`
    `__tostring` metamethod now all use `table.okeys` to sort keys in the
    generated stringification of a table.

### Deprecations

  - Deprecated APIs are kept for a minimum of 1 year following the first
    release that contains the deprecations.  With each new release of
    lua-stdlib, any APIs that have been deprecated for longer than that
    will most likely be removed entirely.  You can prevent that by
    raising an issue at <https://github.com/lua-stdlib/lua-stdlib/issues>
    explaining why any deprecation should be reinstated or at least kept
    around for more than 1 year.

  - By default, deprecated APIs will issue a warning to stderr on every
    call.  However, in production code, you can turn off these warnings
    entirely with any of:

    ```lua
    _DEBUG = false
    _DEBUG = { deprecate = false }
    require "std.debug_init".deprecate = false
    ```

    Or, to confirm you're not trying to call a deprecated function at
    runtime, you can prevent deprecated functions from being defined at
    all with any of:

    ```lua
    _DEBUG = true
    _DEBUG = { deprecate = true }
    require "std.debug_init".deprecate = true
    ```

    The `_DEBUG` global must be set before requiring any stdlib modules,
    but you can adjust the fields in the `std.debug_init` table at any
    time.

  - `functional.eval` has been moved to `std.eval`, the old name now
    gives a deprecation warning.

  - `functional.fold` has been renamed to `functional.reduce`, the old
    name now gives a deprecation warning.

  - `functional.op` has been moved to a new `std.operator` module, the
    old function names now gives deprecation warnings.

  - `list.depair` and `list.enpair` have been moved to `table.depair` and
    `table.enpair`, the old names now give deprecation warnings.

  - `list.filter` has been moved to `functional.filter`, the old name now
    gives a deprecation warning.

  - `list.flatten` has been moved to `table.flatten`, the old name now
    gives a deprecation warning.

  - `list.foldl` and `list.foldr` have been replaced by the richer
    `functional.foldl` and `functional.foldr` respectively.  The old
    names now give a deprecation warning.  Note that List object methods
    `foldl` and `foldr` are not affected.

  - `list.index_key` and `list.index_value` have been deprecated. These
    functions are not general enough to belong in lua-stdlib, because
    (among others) they only work correctly with tables that can be
    inverted without loss of key values.  They currently give deprecation
    warnings.

  - `list.map` and `list.map_with` has been deprecated, in favour of the
    more powerful new `functional.map` and `functional.map_with` which
    handle tables as well as lists.

  - `list.project` has been deprecated in favour of `table.project`, the
    old name now gives a deprecation warning.

  - `list.relems` has been deprecated, in favour of the more idiomatic
    `functional.compose (std.ireverse, std.ielems)`.

  - `list.reverse` has been deprecated in favour of the more general
    and more accurately named `std.ireverse`.

  - `list.shape` has been deprecated in favour of `table.shape`, the old
    name now gives a deprecation warning.

  - `list.transpose` has been deprecated in favour of `functional.zip`,
    see above for details.

  - `list.zip_with` has been deprecated in favour of `functional.zip_with`,
    see above for details.

  - `string.assert` has been moved to `std.assert`, the old name now
    gives a deprecation warning.

  - `string.require_version` has been moved to `std.require`, the old
    name now gives a deprecation warning.

  - `string.tostring` has been moved to `std.tostring`, the old name now
    gives a deprecation warning.

  - `table.metamethod` has been moved to `std.getmetamethod`, the old
    name now gives a deprecation warning.

  - `table.ripairs` has been moved to `std.ripairs`, the old name now
    gives a deprecation warning.

  - `table.totable` has been deprecated and now gives a warning when used.

### Incompatible changes

  - `std.monkey_patch` works the same way as the other submodule
    monkey_patch functions now, by injecting its methods into the given
    (or global) namespace.  To get the previous effect of running all the
    monkey_patch functions, either run them all manually, or call
    `std.barrel ()` as before.

  - `functional.bind` sets fixed positional arguments when called as
    before, but when the newly bound function is called, those arguments
    fill remaining unfixed positions rather than being overwritten by
    original fixed arguments.  For example, where this would have caused
    an error previously, it now prints "100" as expected.

    ```lua
    local function add (a, b) return a + b end
    local incr = functional.bind (add, {1})
    print (incr (99))
    ```

    If you have any code that calls functions returned from `bind`, you
    need to remove the previously ignored arguments that correspond to
    the fixed argument positions in the `bind` invocation.

  - `functional.collect`, `functional.filter` and `functional.map` still
    make a list from the results from an iterator that returns single
    values, but when an iterator returns multiple values they now make a
    table with key:value pairs taken from the first two returned values of
    each iteration.

  - The `functional.op` table has been factored out into its own new
    module `std.operator`.  It will also continue to be available from the
    legacy `functional.op` access point for the forseeable future.

  - The `functional.op[".."]` operator is no longer a list concatenation
    only loaded when `std.list` is required, but a regular string
    concatenation just like Lua's `..` operator.

  - `io.catdir` now raises an error when called with no arguments, for
    consistency with `io.catfile`.

  - `io.die` no longer calls `io.warn` to write the error message to
    stderr, but passes that error message to the core `error` function.

  - `std.set` objects used to be lax about enforcing type correctness in
    function arguments, but now that we have strict type-checking on all
    apis, table arguments are not coerced to Set objects but raise an
    error.  Due to an accident of implementation, you can get the old
    inconsistent behaviour back for now by turning off type checking
    before loading any stdlib modules:

    ```lua
    _DEBUG = { argcheck = false }
    local set = require "std.set"
    ```

  - `string.pad` will still (by implementation accident) coerce non-
    string initial arguments to a string using `string.tostring` as long
    as argument checking is disabled.  Under normal circumstances,
    passing a non-string will now raise an error as specified in the api
    documentation.

  - `table.totable` is deprecated, and thus objects no longer provide or
    use a `__totable` metamethod.  Instead, using a `__pairs` metamethod
    to return key/value pairs, and that will automatically be used by
    `__tostring`, `object.mapfields` etc.  The base object now provides a
    `__pairs` metamethod that returns key/value pairs in order, and
    ignores private fields.  If you have objects that relied on the
    previous treatment of `__totable`, please convert them to set a
    custom `__pairs` instead.


### Bug fixes

  - Removed LDocs for unused `_DEBUG.std` field.

  - `debug.trace` works with Lua 5.2.x again.

  - `list:foldr` works again instead of raising a "bad argument #1 to
    'List'" error.

  - `list.transpose` works again, and handles empty lists without
    raising an error; but is deprecated and will be removed in a future
    release (see above).

  - `list.zip_with` no longer raises an argument error on every call; but,
    like `list.transpose`, is also deprecated (see above).

  - `optparse.on` now works with `std.strict` enabled.

  - `std.require` (nee `string.require_version`) now extracts the last
    substring made entirely of digits and periods from the required
    module's version string before splitting on period.  That means, for
    version strings like luaposix's "posix library for Lua 5.2 / 32" we
    now correctly compare just the numeric part against specified version
    range rather than an ASCII comparison of the whole thing as before!

  - The documentation now correcly notes that `std.require` looks
    first in `module.version` and then `module._VERSION` to match the
    long-standing implementation.

  - `string.split` now really does split on whitespace when no split
    pattern argument is provided.  Also, the documentation now
    correctly cites `%s+` as the default whitespace splitting pattern
    (not `%s*` which splits between every non-whitespace character).


Install it with LuaRocks, using:

    luarocks install stdlib 41.0.0
    https://raw.githubusercontent.com/lua-stdlib/lua-stdlib/release-v41.0.0/stdlib-41.0.0-1.rockspec