# Stdlib NEWS - User visible changes ## Noteworthy changes in release ?.? (????-??-??) [?] ### New features - Overhaul of the LDoc documentation, adding more introductory material, clearer usage examples and better internal consistency. At this point we're pushing the technical limits of what LDoc can do for us organization-wise, but improvements and corrections to the content are always welcome! - With this release, stdlib is much more focused, and non-core modules `optparse`, `std.functional`, 'std.prototype', `std.strict` and `typecheck` have been moved into their own packages and release cycle. Also, the shared debug initialization, Lua host normalization and API deprecation code have been split out into new 'std._debug', 'std.normalize' and 'apimaturity' respectively, and are pulled in automatically as dependencies for any of any modules that need them. You can still install them all separately from their own projects or by using Luarocks: ```bash luarocks install optparse luarocks install std.functional luarocks install std.prototype luarocks install std.strict luarocks install typecheck ``` - All support for previously deprecated APIs has been removed, reducing the install size even further. - `std.string.prettytostring` continues to use `normalize.string.render` for more legible deeply nested table output, identically to previous releases. - `std.npairs` and `std.rnpairs` now respect `__len` metamethod, if any. - `std.table.okeys` has been removed for lack of utility. If you still need it, use this instead: ```lua local okeys = std.functional.compose (std.table.keys, std.table.sort) ``` ### Bug fixes - `std.string.wrap` doesn't throw a StrBuf deprecation warning any more. - `std.getmetamethod` now returns functable valued metamethods correctly, rather than `nil` as in previous releases. It's also considerably faster now that it doesn't use `pcall` any more. - `table.pack` now sets `n` field to number of arguments packed, even in Lua 5.1. ### Incompatible changes - `std.container`, `std.functional`, `std.list`, `std.maturity`, `std.object`, `std.operator`, `std.optparse`, `std.set`, `std.strbuf`, `std.strict` and `std.tuple` have been moved to their own packages, and are no longer shipped as part of stdlib. - Monkey patching calls `std.barrel`, `std.monkey_patch`, `std.io.monkey_patch`, `std.math.monkey_patch`, `std.string.monkey_patch` and `std.table.monkey_patch` have all been removed. - `std.debug.argerror`, `std.debug.argcheck`, `std.debug.argscheck`, `std.debug.extramsg_mismatch`, `std.debug.extramsg_toomany`, `std.debug.parsetypes`, `std.debug.resulterror` and `std.debug.typesplit` have all been moved to their own package, and are no longer shipped as part of stdlib. - `std.debug.DEPRECATED` and `std.debug.DEPRECATIONMSG` have been removed. At some point these will resurface in a new standalone package. - Deprecated functions `string.assert`, `string.require_version`, `string.tostring`, `table.clone_rename`, `table.metamethod`, `table.ripairs` and `table.totable` have been removed. See previous NEWS entries below for what they were replaced by. - Passing a table with a `__len` metamethod, that returns a value other the index of the largest non-nil valued integer key, to `std.npairs` now iterates upto whatever `__len` returns rather than `std.table.maxn`. If `__len` is not present, or gives the same result as `maxn` then `npairs` continues to behave as in the previous release. - `std.tostring` and `std.string.render` have been superceded by their equivalents from 'std.normalize': `str` and `string.render`. Those implementations handle skipping initial sequence keys for a more compact output, escaping of whitespace and other C escape characters for even more compact output and stringification of nested Objects and Containers using their `__tostring` metamethods. - For consistency with std.normalize and other package symbols, we now spell `package.path_mark` as `package.pathmark`. ## Noteworthy changes in release 41.2.0 (2015-03-08) [stable] ### New features - New iterators, `std.npairs` and `std.rnpairs` behave like `std.ipairs` and `std.ripairs` resp., except that they will visit all integer keyed elements, including nil-valued "holes". This is useful for iterating over argument lists with nils: ```lua function fn(a, b, c) for _, v in npairs {...} do print(v) end fn(nil, nil, 3) --> nil nil 3 ``` - New `debug.getfenv` and `debug.setfenv` that work with Lua 5.2 and 5.3. - `debug.argscheck` will skip typecheck for `self` parameter if the function name specification contains a colon. - New `debug.resulterror` is much like `debug.argerror`, but uses the message format "bad result #n from 'fname'". - New `debug.extramsg_mismatch` to generate `extramsg` argument for `debug.argerror` or `debug.resulterror` on encountering a type mismatch. - New `debug.extramsg_toomany` to generate a too many arguments or similar `extramsg` argument. ### Deprecations - `debug.toomanyargmsg` has been deprecated in favour of the more orthogal `debug.extramsg_toomany` api. You can rewrite clients of deprecated api like this: ```lua if maxn(argt) > 7 then argerror('fname', 8, extramsg_toomany('argument', 7, maxn(argt)), 2) end ``` ### Bug fixes - `std.getmetamethod` no longer rejects non-table subjects when `_DEBUG.argcheck` is set. - `functional.bind`, `functional.collect`, `functional.compose`, `functional.filter` and `functional.map` propagate nil valued arguments correctly. - `functional.callable` no longer raises an argument error when passed a nil valued argument. - `debug.argcheck` and `debug.argscheck` accept "bool" as an alias for "boolean" consistently. - `io.catdir` and `io.dirname` no longer leak extra results from implementation details. ### Incompatible changes - `functional.collect` uses `std.npairs` as a default iterator rather than `std.ipairs`. ## Noteworthy changes in release 41.1.1 (2015-01-31) [stable] ### Bug fixes - `std.barrel` no longer gets stuck in an infinite loop when called in Lua 5.3. ## Noteworthy changes in release 41.1.0 (2015-01-30) [stable] ### New features - Anything that responds to `tostring` can be appended to a `std.strbuf`: ```lua local a, b = StrBuf {'foo', 'bar'}, StrBuf {'baz', 'quux'} a = a .. b --> 'foobarbazquux' ``` - `std.strbuf` stringifies lazily, so adding tables to a StrBuf object, and then changing the content of them before calling `tostring` also changes the contents of the buffer. See LDocs for an example. - `debug.argscheck` accepts square brackets around final optional parameters, which is distinct to the old way of appending `?` or `|nil` in that no spurious "or nil" is reported for type mismatches against a final bracketed argument. - `debug.argscheck` can also check types of function return values, when specified as: ```lua fn = argscheck('fname(?any...) => int, table or nil, string', fname) ``` Optional results can be marked with brackets, and an ellipsis following the final type denotes any additional results must match that final type specification. Alternative result type groups are separated by "or". - New `table.unpack(t, [i, [j]])` function that defaults j to `table.maxn(t)`, even on luajit which stops before the first nil valued numeric index otherwise. ### Deprecations - `std.strbuf.tostring` has been deprecated in favour of `tostring`. Why write `std.strbuf.tostring(sb)` or `sb:tostring()` when it is more idiomatic to write `tostring(sb)`? ### Bug fixes - `std.barrel` and the various `monkey_patch` functions now return their parent module table as documented. - stdlib modules are all `std.strict` compliant; require 'std.strict' before requiring other modules no longer raises an error. - `debug.argscheck` can now diagnose when there are too many arguments, even in the case where the earlier arguments match parameters by skipping bracketed optionals, and the total number of arguments is still less than the absolute maximum allowed if optionals are counted too. - `package.normalize` now leaves valid ./../../ path prefixes unmolested. ### Incompatible changes - `debug.argscheck` requires nil parameter type `?` notation to be prepended to match Specl and TypedLua syntax. `?` suffixes are a syntax error. - `debug.argscheck` uses `...` instead of `*` appended to the final element if all unmatched argument types should match. The trailing `*` syntax was confusing, because it was easy to misread it as "followed by zero-or- more of this type". ## 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 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). ## Noteworthy changes in release 40 (2014-05-01) [stable] ### New features - `functional.memoize` now accepts a user normalization function, falling back on `string.tostring` otherwise. - `table.merge` now supports `map` and `nometa` arguments orthogonally to `table.clone`. - New `table.merge_select` function, orthogonal to `table.clone_select`. See LDocs for details. ### Incompatible changes - Core methods and metamethods are no longer monkey patched by default when you `require 'std'` (or `std.io`, `std.math`, `std.string` or `std.table`). Instead they provide a new `monkey_patch` method you should use when you don't care about interactions with other modules: ```lua local io = require 'std.io'.monkey_patch() ``` To install all of stdlib's monkey patches, the `std` module itself has a `monkey_patch` method that loads all submodules with their own `monkey_patch` method and runs them all. If you want full compatibility with the previous release, in addition to the global namespace scribbling snippet above, then you need to adjust the first line to: ```lua local std = require 'std'.monkey_patch() ``` - The global namespace is no longer clobbered by `require 'std'`. To get the old behaviour back: ```lua local std = require 'std'.barrel(_G) ``` This will execute all available monkey_patch functions, and then scribble all over the `_G` namespace, just like the old days. - The `metamethod` call is no longer in `std.functional`, but has moved to `std.table` where it properly belongs. It is a utility method for tables and has nothing to do with functional programming. - The following deprecated camelCase names have been removed, you should update your code to use the snake_case equivalents: `std.io.processFiles`, `std.list.indexKey`, `std.list.indexValue`, `std.list.mapWith`, `std.list.zipWith`, `std.string.escapePattern`, `std.string. escapeShell`, `std.string.ordinalSuffix`. - The following deprecated function names have been removed: `std.list.new` (call `std.list` directly instead), `std.list.slice` (use `std.list.sub` instead), `std.set.new` (call `std.set` directly instead), `std.strbuf.new` (call `std.strbuf` directly instead), and `std.tree.new` (call `std.tree` directly instead). ### Bug fixes - Allow `std.object` derived tables as `std.tree` keys again. ## Noteworthy changes in release 39 (2014-04-23) [stable] ### New features - New `std.functional.case` function for rudimentary case statements. The main difference from serial if/elseif/end comparisons is that `with` is evaluated only once, and then the match function is looked up with an O(1) table reference and function call, as opposed to hoisting an expression result into a temporary variable, and O(n) comparisons. The function call overhead is much more significant than several comparisons, and so `case` is slower for all but the largest series of if/elseif/end comparisons. It can make your code more readable, however. See LDocs for usage. - New pathstring management functions in `std.package`. Manage `package.path` with normalization, duplicate removal, insertion & removal of elements and automatic folding of '/' and '?' onto `package.dirsep` and `package.path_mark`, for easy addition of new paths. For example, instead of all this: ```lua lib = std.io.catfile('.', 'lib', package.path_mark .. '.lua') paths = std.string.split(package.path, package.pathsep) for i, path in ipairs(paths) do -- ... lots of normalization code... end i = 1 while i <= #paths do if paths[i] == lib then table.remove(paths, i) else i = i + 1 end end table.insert(paths, 1, lib) package.path = table.concat(paths, package.pathsep) ``` You can now write just: ```lua package.path = package.normalize('./lib/?.lua', package.path) ``` - `std.optparse:parse` accepts a second optional parameter, a table of default option values. - `table.clone` accepts an optional table of key field renames in the form of `{oldkey=newkey, ...}` subsuming the functionality of `table.clone_rename`. The final `nometa` parameter is supported whether or not a rename map is given: ```lua r = table.clone(t, 'nometa') r = table.clone(t, {oldkey=newkey}, 'nometa') ``` ### Deprecations - `table.clone_rename` now gives a warning on first call, and will be removed entirely in a few releases. The functionality has been subsumed by the improvements to `table.clone` described above. ### Bug fixes - `std.optparse` no longer throws an error when it encounters an unhandled option in a combined (i.e. `-xyz`) short option string. - Surplus unmapped fields are now discarded during object cloning, for example when a prototype has `_init` set to `{'first', 'second'}`, and is cloned using `Proto {'one', 'two', 'three'}`, then the unmapped `three` argument is now discarded. - The path element returned by `std.tree.nodes` can now always be used as a key list to dereference the root of the tree, particularly `tree[{}]` now returns the root node of `tree`, to match the initial `branch` and final `join` results from a full traversal by `std.tree.nodes(tree)`. ### Incompatible changes - `std.string` no longer sets `__append`, `__concat` and `__index` in the core strings metatable by default, though `require 'std'` does continue to do so. See LDocs for `std.string` for details. - `std.optparse` no longer normalizes unhandled options. For example, `--unhandled-option=argument` is returned unmolested from `parse`, rather than as two elements split on the `=`; and if a combined short option string contains an unhandled option, then whatever was typed at the command line is returned unmolested, rather than first stripping off and processing handled options, and returning only the unhandled substring. - Setting `_init` to `{}` in a prototype object will now discard all positional parameters passed during cloning, because a table valued `_init` is a list of field names, beyond which surplus arguments (in this case, all arguments!) are discarded. ## Noteworthy changes in release 38 (2014-01-30) [stable] ### New features - The separator parameter to `std.string.split` is now optional. It now splits strings with `%s+` when no separator is specified. The new implementation is faster too. - New `std.object.mapfields` method factors out the table field copying and mapping performed when cloning a table `_init` style object. This means you can call it from a function `_init` style object after collecting a table to serve as `src` to support derived objects with normal std.object syntax: ```lua Proto = Object { _type = 'proto' _init = function(self, arg, ...) if type(arg) == 'table' then mapfields(self, arg) else -- non-table instantiation code end end, } new = Proto(str, #str) Derived = proto {_type='Derived', ...} ``` - Much faster object cloning; `mapfields` is in imperative style and makes one pass over each table it looks at, where previous releases used functional style (stack frame overhead) and multiple passes over input tables. On my 2013 Macbook Air with 1.3GHz Core i5 CPU, I can now create a million std.objects with several assorted fields in 3.2s. Prior to this release, the same process took 8.15s... and even release 34.1, with drastically simpler Objects (19SLOC vs over 120) took 5.45s. - `std.object.prototype` is now almost an order of magnitude faster than previous releases, taking about 20% of the time it previously used to return its results. - `io.warn` and `io.die` now integrate properly with `std.optparse`, provided you save the `opts` return from `parser:parse` back to the global namespace where they can access it: ```lua local OptionParser = require 'std.optparse' local parser = OptionParser 'eg 0\nUsage: eg\n' _G.arg, _G.opts = parser:parse(_G.arg) if not _G.opts.keep_going then require 'std.io'.warn 'oh noes!' end ``` will, when run, output to stderr: "eg: oh noes!" ### Bug fixes - Much improved documentation for `optparse`, so you should be able to use it without reading the source code now! - `io.warn` and `io.die` no longer output a line-number when there is no file name to append it to. - `io.warn` and `io.die` no longer crash in the absence of a global `prog` table. - `string.split` no longer goes into an infinite loop when given an empty separator string. - Fix `getmetatable(container._functions) == getmetatable(container)`, which made tostring on containers misbehave, among other latent bugs. - `_functions` is never copied into a metatable now, finally solving the conflicted concerns of needing metatables to be shared between all objects of the same `_type` (for `__lt` to work correctly for one thing) and not leaving a dangling `_functions` list in the metatable of cloned objects, which could delete functions with matching names from subsequent clones. ## 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: ```lua 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. ## 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 :prototype() method that returns the contents of the new internal `_type` field. This can be overridden during cloning with, e.g.: ```lua local Object = require 'std.object' Prototype = Object {_type='Prototype', } ``` - 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. ```lua 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.: ```lua local string = require 'std.string' ``` These names are now stable, and will be available from here for future releases. - The `std.list` module, as a consequence of returning a List object prototype rather than a table of functions including a constructor, now always has the list operand as the first argument, whether that function is called with `.` syntax or `:` syntax. Functions which previously had the list operand in a different position when called with `.` syntax were: list.filter, list.foldl, list.foldr, list.index_key, list.index_value, list.map, list.map_with, list.project, list.shape and list.zip_with. Calls made as object methods using `:` calling syntax are unchanged. - The `std.set` module is a `std.container` with no object methods, and now uses prototype functions instead: ```lua local union = Set.union(set1, set2) ``` ## Noteworthy changes in release 35 (2013-05-06) [stable] ### New features - Move to the Slingshot release system. - Continuous integration from Travis automatically builds stdilb with Lua 5.1, Lua 5.2 and luajit-2.0 with every commit, which should help prevent future release breaking compatibility with one or another of those interpreters. ### Bug fixes - `std.package_ext` no longer overwrites the core `package` table, leaving the core holding on to memory that Lua code could no longer access. ### Incompatible changes - The Grand Renaming™ - everything now installs to $luaprefix/std/, except `std.lua` itself. Importing individual modules now involves: ```lua local list = require 'std.list' ``` If you want to have all the symbols previously available from the global and core module namespaces, you will need to put them there yourself, or import everything with: ```lua require 'std' ``` which still behaves per previous releases. Not all of the modules work correctly when imported individually right now, until we figure out how to break some circular dependencies. ## Noteworthy changes in release 34.1 (2013-04-01) [stable] - This is a maintenance release to quickly fix a breakage in getopt from release v34. Getopt no longer parses non-options, but stops on the first non-option... if a use case for the other method comes up, we can always add it back in. ## Noteworthy changes in release 34 (2013-03-25) [stable] - stdlib is moving towards supporting separate requirement of individual modules, without scribbling on the global environment; the work is not yet complete, but we're collecting tests along the way to ensure that once it is all working, it will carry on working; - there are some requirement loops between modules, so not everything can be required independently just now; - `require 'std'` will continue to inject std symbols into the system tables for backwards compatibility; - stdlib no longer ships a copy of Specl, which you will need to install separately if you want to run the bundled tests; - getopt supports parsing of undefined options; useful for programs that wrap other programs; - getopt.Option constructor is no longer used, pass a plain Lua table of options, and getopt will do the rest; ## Noteworthy changes in release 33 (2013-07-27) [stable] - This release improves stability where Specl has helped locate some corner cases that are now fixed. - `string_ext.wrap` and `string_ext.tfind` now diagnose invalid arguments. - Specl code coverage is improving. - OrdinalSuffix improvements. - Use '%' instead of math.mod, as the latter does not exist in Lua 5.2. - Accept negative arguments. ## Noteworthy changes in release 32 (2013-02-22) [stable] - This release fixes a critical bug preventing getopt from returning anything in getopt.opt. Gary V. Vaughan is now a co-maintainer, currently reworking the sources to use (Lua 5.1 compatible) Lua 5.2 style module packaging, which requires you to assign the return values from your imports: ```lua getopt = require 'getopt' ``` - Extension modules, table_ext, package_ext etc. return the unextended module table before injecting additional package methods, so you can ignore those return values or save them for programatically backing out the changes: ```lua table_unextended = require 'table_ext' ``` - Additionally, Specl (see http://github.com/gvvaughan/specl/) specifications are being written for stdlib modules to help us stop accidentally breaking things between releases. ## Noteworthy changes in release 31 (2013-02-20) [stable] - This release improves the list module: lists now have methods, list.slice is renamed to list.sub (the old name is provided as an alias for backwards compatibility), and all functions that construct a new list return a proper list, not a table. As a result, it is now often possible to write code that works on both lists and strings. ## Noteworthy changes in release 30 (2013-02-17) [stable] - This release changes some modules to be written in a Lua 5.2 style (but not the way they work with 5.1). Some fixes and improvements were made to the build system. Bugs in the die function, the parser module, and a nasty bug in the set module introduced in the last release (29) were fixed. ## Noteworthy changes in release 29 (2013-02-06) [stable] - This release overhauls the build system to have LuaRocks install releases directly from git rather than from tarballs, and fixes a bug in set (issue #8). ## Noteworthy changes in release 28 (2012-10-28) [stable] - This release improves the documentation and build system, and improves require_version to work by default with more libraries. ## Noteworthy changes in release 27 (2012-10-03) [stable] - This release changes getopt to return all arguments in a list, rather than optionally processing them with a function, fixes an incorrect definition of set.elems introduced in release 26, turns on debugging by default, removes the not-very-useful string.gsubs, adds constructor functions for objects, renames table.rearrange to the more descriptive table.clone_rename and table.indices to table.keys, and makes table.merge not clone but modify its left-hand argument. A function require_version has been added to allow version constraints on a module being required. Gary Vaughan has contributed a memoize function, and minor documentation and build system improvements have been made. Usage information is now output to stdout, not stderr. The build system has been fixed to accept Lua 5.2. The luarock now installs documentation, and the build command used is now more robust against previous builds in the same tree. ## Noteworthy changes in release 26 (2012-02-18) [stable] - This release improves getopt's output messages and conformance to standard practice for default options. io.processFiles now unsets prog.file when it finishes, so that a program can tell when itâs no longer processing a file. Three new tree iterators, inodes, leaves and ileaves, have been added; the set iterator set.elements (renamed to set.elems for consistency with list.elems) is now leaves rather than pairs. tree indexing has been made to work in more circumstances (thanks, Gary Vaughan). io.writeline is renamed io.writelines for consistency with io.readlines and its function. A slurping function, io.slurp, has been added. Strings now have a __concat metamethod. ## Noteworthy changes in release 25 (2011-09-19) [stable] - This release adds a version string to the std module and fixes a buglet in the build system. ## Noteworthy changes in release 24 (2011-09-19) [stable] - This release fixes a rename missing from release 23, and makes a couple of fixes to the new build system, also from release 23. ## Noteworthy changes in release 23 (2011-09-17) [stable] - This release removes the posix_ext module, which is now part of luaposix, renames string.findl to string.tfind to be the same as lrexlib, and autotoolizes the build system, as well as providing a rockspec file. ## Noteworthy changes in release 22 (2011-09-02) [stable] - This release adds two new modules: strbuf, a trivial string buffers implementation, which is used to speed up the stdlib tostring method for tables, and bin, which contains a couple of routines for converting binary data into numbers and strings. Some small documentation and build system fixes have been made. ## Noteworthy changes in release 21 (2011-06-06) [stable] - This release converts the documentation of stdlib to LuaDoc, adds an experimental Lua 5.2 module "fstable", for storing tables directly on disk as files and directories, and fixes a few minor bugs (with help from David Favro). - This release has been tested lightly on Lua 5.2 alpha, but is not guaranteed to work fully. ## Noteworthy changes in release 20 (2011-04-14) [stable] - This release fixes a conflict between the global _DEBUG setting and the use of strict.lua, changes the argument order of some list functions to favour OO-style use, adds posix.euidaccess, and adds OO-style use to set. mk1file can now produce a single-file version of a user-supplied list of modules, not just the standard set. ## Noteworthy changes in release 19 (2011-02-26) [stable] - This release puts the package.config reflection in a new package_ext module, where it belongs. Thanks to David Manura for this point, and for a small improvement to the code. ## Noteworthy changes in release 18 (2011-02-26) [stable] - This release provides named access to the contents of package.config, which is undocumented in Lua 5.1. See luaconf.h and the Lua 5.2 manual for more details. ## Noteworthy changes in release 17 (2011-02-07) [stable] - This release fixes two bugs in string.pad (thanks to Bob Chapman for the fixes). ## Noteworthy changes in release 16 (2010-12-09) [stable] - Adds posix module, using luaposix, and makes various other small fixes and improvements. ## Noteworthy changes in release 15 (2010-06-14) [stable] - This release fixes list.foldl, list.foldr, the fold iterator combinator and io.writeLine. It also simplifies the op table, which now merely sugars the built-in operators rather than extending them. It adds a new tree module, which subsumes the old table.deepclone and table.lookup functions. table.subscript has become op['[]'], and table.subscripts has been removed; the old treeIter iterator has been simplified and generalised, and renamed to nodes. The mk1file script and std.lua library loader have had the module list factored out into modules.lua. strict.lua from the Lua distribution is now included in stdlib, which has been fixed to work with it. Some minor documentation and other code improvements and fixes have been made. ## Noteworthy changes in release 14 (2010-06-07) [stable] - This release makes stdlib compatible with strict.lua, which required a small change to the debug_ext module. Some other minor changes have also been made to that module. The table.subscripts function has been removed from the table_ext.lua. ## Noteworthy changes in release 13 (2010-06-02) [stable] - This release removes the lcs module from the standard set loaded by 'std', removes an unnecessary definition of print, and tidies up the implementation of the "op" table of functional versions of the infix operators and logical operators. ## Noteworthy changes in release 12 (2009-09-07) [stable] - This release removes io.basename and io.dirname, which are now available in lposix, and the little-used functions addSuffix and changeSuffix which dependend on them. io.pathConcat is renamed to io.catdir and io.pathSplit to io.splitdir, making them behave the same as the corresponding Perl functions. The dependency on lrexlib has been removed along with the rex wrapper module. Some of the more esoteric and special-purpose modules (mbox, xml, parser) are no longer loaded by 'require 'std''. This leaves stdlib with no external dependencies, and a rather more coherent set of basic modules. ## Noteworthy changes in release 11 (2009-03-15) [stable] - This release fixes a bug in string.format, removes the redundant string.join (it's the same as table.concat), and adds to table.clone and table.deepclone the ability to copy without metatables. Thanks to David Kantowitz for pointing out the various deficiencies. ## Noteworthy changes in release 10 (2009-03-13) [stable] - This release fixes table.deepclone to copy metatables, as it should. Thanks to David Kantowitz for the fix. ## Noteworthy changes in release 9 (2009-02-19) [stable] - This release updates the object module to be the same as that published in "Lua Gems", and fixes a bug in the utility mk1file which makes a one-file version of the library, to stop it permanently redefining require. ## Noteworthy changes in release 8 (2008-09-04) [stable] - This release features fixes and improvements to the set module; thanks to Jiutian Yanling for a bug report and suggestion which led to this work. ## Noteworthy changes in release 7 (2008-09-04) [stable] - just a bug fix ## Noteworthy changes in release 6 (2008-07-28) [stable] - This release rewrites the iterators in a more Lua-ish 5.1 style. ## Noteworthy changes in release 5 (2008-03-04) [stable] - I'm happy to announce a new release of my standard Lua libraries. It's been nearly a year since the last release, and I'm happy to say that since then only one bug has been found (thanks Roberto!). Two functions have been added in this release, to deal with file paths, and one removed (io.length, which is handled by lfs.attributes) along with one constant (INTEGER_BITS, handled by bitlib's bit.bits). - For those not familiar with stdlib, it's a pure-Lua library of mostly fundamental data structures and algorithms, in particular support for functional and object-oriented programming, string and regex operations and extensible pretty printing of data structures. More specific modules include a getopt implementation, a generalised least common subsequences (i.e. diff algorithm) implementation, a recursive-descent parser generator, and an mbox parser. - It's quite a mixed bag, but almost all written for real projects. It's written in a doc-string-ish style with the supplied very simple ldoc tool. - I am happy with this code base, but there are various things it could use: 0. Tests. Tests. Tests. The code has no unit tests. It so needs them. 1. More code. Nothing too specialised (unless it's too small to be released on its own, although very little seems "too small" in the Lua community). Anything that either has widespread applicability (like getopt) or is very general (data structures, algorithms, design patterns) is good. 2. Refactoring. The code is not ideally factored. At the moment it is divided into modules that extend existing libraries, and new modules constructed along similar lines, but I think that some of the divisions are confusing. For example, the functional programming support is spread between the list and base modules, and would probably be better in its own module, as those who aren't interested in the functional style won't want the functional list support or the higher-order functions support, and those who want one will probably want the other. 3. Documentation work. There's not a long wrong with the existing documentation, but it would be nice, now that there is a stable LuaDoc, to use that instead of the built-in ldoc, which I'm happy to discard now that LuaDoc is stable. ldoc was always designed as a minimal LuaDoc substitute in any case. 4. Maintenance and advocacy. For a while I have been reducing my work on Lua, and am also now reducing my work in Lua. If anyone would like to take on stdlib, please talk to me. It fills a much-needed function: I suspect a lot of Lua programmers have invented the wheels with which it is filled over and over again. In particular, many programmers could benefit from the simplicity of its simple and well-designed functional, string and regex capabilities, and others will love its comprehensive getopt. ## Noteworthy changes in release 4 (2007-04-26) [beta] - This release removes the dependency on the currently unmaintained lposix library, includes pre-built HTML documentation, and fixes some 5.0-style uses of variadic arguments. Thanks to Matt for pointing out all these problems. stdlib is very much user-driven at the moment, since it already does everything I need, and I don't have much time to work on it, so do please contact me if you find bugs or problems or simply don't understand it, as the one thing I *do* want to do is make it useful and accessible! ## Noteworthy changes in release 3 (2007-02-25) [beta] - This release fixes the "set" and "lcs" (longest common subsequence, or "grep") libraries, which were broken, and adds one or two other bug and design fixes. Thanks are due to Enrico Tassi for pointing out some of the problems. ## Noteworthy changes in release 2 (2007-01-05) [beta] - This release includes some bug fixes, and compatibility with lrexlib 2.0. ## Noteworthy changes in release 1 (2011-09-02) [beta] - It's just a snapshot of CVS, but it's pretty stable at the moment; stdlib, until such time as greater interest or participation enables (or forces!) formal releases will be in permanent beta, and tracking CVS is recommended. [optparse]: https://github.com/gvvaughan/optparse [strict]: https://github.com/lua-stdlib/strict