[ANN] typecheck 3.0 released

[Gary V. Vaughan <gary@...>]

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