[Date Prev][Date Next][Thread Prev][Thread Next]
[Date Index]
[Thread Index]
- Subject: [ANN] stdlib 41.0.0 released
- From: "Gary V. Vaughan" <gary@...>
- Date: Sat, 3 Jan 2015 20:38:31 +0000
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
