[ANN] typecheck 3.0 released
[Date Prev][
Date Next][Thread Prev][
Thread Next]
[
Date Index]
[
Thread Index]
- Subject: [ANN] typecheck 3.0 released
- From: Gary V. Vaughan <gary@...>
- Date: 2023年1月31日 18:04:38 -0700
I am happy to announce release 3.0 of typecheck.
The main purpose of this release is to consolidate and normalize API calls.
Typecheck's home page is at http://gvvaughan.github.io/typecheck
A Luaish run-time gradual type checking system, for argument and return
types at function boundaries with simple annotations that can be disabled
in production code. Its API and type mismatch errors are modelled on the
core Lua C-language `argcheck ()` API.
- _Luaish_: Type check failures show error messages in the same format as
Lua itself;
- _run time_: Without changing any library code, the application can decide
at run time whether to enable type checking as it loads the library;
- _gradual_: Type checks can be introduced to the functions in your code
gradually, to as few or as many as seem useful;
- _type checking_: function argument types and return types are checked
against the specification, and raise an error on mismatch.
This is a light-weight library for Lua 5.1 (including LuaJIT), 5.2, 5.3 and
5.4 written in pure Lua.
This code started life as the function argument and return type checking
system I wrote for lua-stdlib. I’m still in the process of slimming down
lua-stdlib in preparation for the next release though, part of which means
that you can now use typecheck without requiring the installation of all of
stdlib.
## Noteworthy changes in release 3.0 (2023年01月31日) [stable]
### New Features
- `ARGCHECK_FRAME` is now exported for use when writing your own
functions that need to adjust any stack `level` argument they
support, rather than having to divine if from the internals of
`_debug.argcheck`.
- Accept either of 'integer' or 'int' in an argcheck typespec.
- When diagnosing a type mismatch, be specific about unexpected
'integer' or 'float' rather than just 'number'
```
bad argument #1 to 'getfenv' (integer expected, got float)
```
- Instead of diagnosing an argument mismatch against `?any` as
'expected any value or nil, got no value', we now get
'expected argument, got no value'. Similarly, for missing
results for `?any' we now get 'expected result, go no value'.
- Support importing into another project directly with:
```sh
$ cp ../typecheck/lib/typecheck/init.lua lib/typecheck.lua
```
- Multi-typed specifications are sorted asciibetically in error
messages by `argerror` and `resulterror` to make writing tests
for typechecked functions easier.
### Bug fixes
- No matter whether 'int' or 'integer' is specified, always use
'integer' in error messages, for consistency with 'bool' as an
alias of 'boolean'.
- When 'table of int', 'list of funcs', 'table of bool' or
similar are specified, consistently use 'table of integers',
'list of functions', 'table of booleans', etc.
- `argscheck` now correctly diagnoses unexpected `nil` arguments
with 'got nil', and missing arguments with 'got no value'.
Likewise for result errors about unexpected `nil` results and
missing return values.
- Diagnose passing of incompatible objects with a `__tostring`
metamethod to parameters that require a string instead of silently
coercing to a string.
- Functable's are most definitely NOT functors as that term is used
by functional programmers. The library will accept 'functor'
as a synonym for backwards compatibility, but otherwise we now
use the term functable everywhere to avoid confusion.
### Incompatible changes
- `types.stringy` is no longer available; silently converting any
object passed to a string parameter by calling the `__tostring`
metamethod has unintended consequences for the function behaviour
and behaves differently when typechecking is disabled and the
conversion to string is consequently disabled.
1. If you know you want an argument converted to a string before
passing to typechecked function, you should call `tostring` on
it at the call-site.
2. If you know you want tables with `__tostring` metamethods to
be valid arguments, make the typespec 'string|table' and call
`tostring` on it in your function.
- Number-like string arguments are considered a mismatch for
previously compatible expected number types for the same reason.
As above, either call `tonumber` at the call-site, or make the
typespec 'number|string' and call `tonumber` inside your function.
- `argcheck`, `argerror`, `argscheck` and `resulterror` no longer
accept a table with a `__tostring` metamethod as a substitute for
an actual string for those parameters that require a string.
- `extramsg_mismatch` provides more specific details when the
expected argument is 'int' or 'integer':
```
bad argument #1 to 'getfenv' (float has no integer representation)
```
Install it with LuaRocks, using:
luarocks install typecheck 3.0