Next version!

CHANGELOG.md

@@ -1,3 +1,123 @@
+# 0.24.0 - Teal Spring '24
+
+2024-10-07
+
+This a big release! It is a culmination of work that has spanned multiple
+years, and it would not be possible without the amazing feedback given by
+the community on the `next` branch, where this was developed. This release
+does include that "lot of new code" that I wanted to merge in the "near
+future", as stated in the previous release's changelog.
+
+The main feature is the addition of interfaces, which introduces a model for
+subtyping table types in the language. That should allow for representing the
+various kinds of object models that are used across the Lua ecosystem, without
+promoting any particular class/object system over the others.
+
+This release features commits by François Perrad, Victor Ilchev and Hisham
+Muhammad.
+
+## What's New
+
+### Language
+
+* **Interfaces**: you can now declare abstract interfaces, and record types
+  can implement them. This allows you to declare subtyping relations, and
+  better support inheritance models (e.g. `local record Circle is Shape`).
+  * Records and interfaces may declare a `where` clause with an expression
+    over `self`, which allows the `is` operator to discriminate the type.
+  * With discriminated record types, it is now possible to declare unions
+    over multiple record types.
+  * "Arrayrecords" are no longer a distinct type: they are just records
+    that implement an array interface (e.g. `local record R is {T}`)
+  * Type variables in functions can now have constraints on interfaces
+    (e.g. `function my_func<F is MyInterface>(...)`)
+  * `self` is now a valid type that can be used when declaring arguments
+    in functions declared in interfaces and records
+    * When a record is declared to be a subtype of an interface using `is`,
+      any function arguments using `self` in the parent interface type will
+      then resolve to the child record's type.
+* **Optional/required arguments in function calls** - functions may declare
+  arguments as optional, affecting the required arity of function calls.
+  The rightmost arguments of a function can have their variable names
+  annotated with a `?` sign, indicating that the argument does not need
+  to be passed in a function call. This refers only to the presence of the
+  argument in a call, and not to its type or nullability: a required
+  argument may still be called with an explicit `null`, but an optional
+  argument may be elided.
+  * In previous versions of Teal, all function arguments were effectively
+    optional. This means that Teal is now stricter which checking for
+    function calls. You can use `--feat-arity=off` in the command line
+    or `feat_arity = "off"` in `tlconfig.lua` to obtain the previous
+    behavior.
+  * To convert code that uses the old arity checking rules to the new
+    behavior, you can also use compiler pragmas in the code,
+    `--#pragma arity off` and `--#pragma arity off` to disable or enable
+    stricter arity checks.
+* **Macro expressions**: you can declare a restricted form of function called
+  a `macroexp`, which is always expanded inline. These can also be used
+  to declare compile-time metamethods, which expand without requiring
+  a metatable at runtime. The `where` clauses used in interfaces and
+  records are syntax sugar for macro expressions that implement a
+  pseudo-metamethod `__is`.
+* Dynamic `require` calls that do not take a module name as a literal
+  string are now allowed, and return `any`; you can load a static type
+  definition using `local type MyType = require("...")` and then cast
+  your dynamic require like so: `local my_mod = require(var) as MyType`
+* The type system is more nominal: all named types are now treated nominally,
+  except for unions, which are always type aliases. Previously record types
+  were nominal, but a named typed that resolved to a primitive such as
+  `integer` was structural. There are still subleties on the rules for when
+  a `local type` produces a new distinct type or an alias; they are
+  [explained in the docs](docs/aliasing.md).
+* The `<total>` attribute for variables can now only be applied when
+  initializing variables with literal tables. This is a minor breaking change,
+  but the usefulness of this attribute in other cases was very limited,
+  and it also produced misleading results.
+* Improved type signatures in the standard library
+  * `select` produces variadic returns
+
+### API
+
+* Simplified API in the `tl` module.
+  * The 0.15 API is still supported for backwards compatibility.
+
+### Tooling
+
+* `tl build` was removed. [Cyan](https://github.com/teal-language/cyan)
+  should be used instead as the build tool for Teal projects.
+
+### Fixes
+
+* Fix commits included in this release refer both to bugs present
+  in the `master` branch as well as fixes specific to the 0.24 series,
+  reported by the community during the beta testing of this release.
+  The Git history and the GitHub issues list contain a more detailed
+  accounting of the bugfixes that went into this release.
+  Some of the fixes include:
+  * `tl check` now reports if the input file does not exist.
+  * Reporting location of the end of an `if` block correctly.
+  * No longer crash if a `require()` epression fails to resolve (#778).
+  * `tl types` now reports the types of variables in `for` loops.
+  * Improved error message when calling functions with insufficient
+    arguments.
+  * Disallowing using a base type as a type variable name.
+  * Type arguments resolving correctly in recursive functions.
+  * Type arguments resolving correctly in nested records (#754).
+  * `or` type inference between types with a subtyping relation
+    resolves to whichever is the larger type.
+  * Reporting an error if an iterator used in a generic `for` does not
+    declare a return value type (#736).
+  * When checking `<total>` values, no longer reporting record
+    function and metamethods as missing fields (#749).
+  * Localizing a record no longer makes the local a type (#759).
+  * Bad assignments of record tables are reported (#752).
+  * Nominal type alias declarations work as expected (#238).
+  * Nominals with generics can be resolved correcty (#777).
+  * Nested types are not closed too early (#775).
+  * Not failing when resolving nested empty tables.
+  * Exporting generics and type aliases from modules correctly
+    using `return` at the toplevel (#804).
+
 # 0.15.3
 
 2023-11-05

Makefile

@@ -1,3 +1,5 @@
+LUA ?=
+
 ifeq ($(OS), Windows_NT)
 	BUSTED = busted.bat --suppress-pending --exclude-tags=unix
 else
@@ -8,8 +10,8 @@ all: selfbuild suite
 
 selfbuild:
 	cp tl.lua tl.lua.bak
-	./tl gen --check tl.tl && cp tl.lua tl.lua.1 || { cp tl.lua tl.lua.1; cp tl.lua.bak tl.lua; exit 1; }
-	./tl gen --check tl.tl && cp tl.lua tl.lua.2 || { cp tl.lua tl.lua.2; cp tl.lua.bak tl.lua; exit 1; }
+	$(LUA) ./tl gen --check tl.tl && cp tl.lua tl.lua.1 || { cp tl.lua tl.lua.1; cp tl.lua.bak tl.lua; exit 1; }
+	$(LUA) ./tl gen --check tl.tl && cp tl.lua tl.lua.2 || { cp tl.lua tl.lua.2; cp tl.lua.bak tl.lua; exit 1; }
 	diff tl.lua.1 tl.lua.2
 
 suite:

docs/aliasing.md

@@ -0,0 +1,145 @@
+# Type aliasing rules in Teal
+
+## The general rule
+
+In Teal we can declare new types with user-defined names. These are called
+_nominal types_. These nominal types may be unique, or aliases.
+
+The `local type` syntax produces a new _nominal type_. Whenever you assign to
+it another user-defined nominal type, it becomes a _type alias_. Whenever you
+assign to it a type constructor, it becomes a new unique type. Type
+constructors are syntax constructs such as: block constructors for records,
+interfaces and enums (e.g. `record` ... `end`); function signature
+declarations with `function()`; applications of generics with `<>`-notation;
+declarations of array, tuple or map types with `{}`-notation; or a primitive
+type name such as `number`.
+
+Syntax such as `local record R` is a shorthand to `local type R = record`, so
+the same rules apply: it declares a new unique type.
+
+Nominal types are compared against each other _by name_, but type aliases are
+considered to be equivalent.
+
+```lua
+local record Point3D
+   x: number
+   y: number
+   z: number
+end
+
+local record Vector3D
+   x: number
+   y: number
+   z: number
+end
+
+local p: Point3D = { x = 1.0, y = 0.3, z = 2.5 }
+
+local v: Vector3D = p -- Teal compile error: Point3D is not a Vector3D
+
+local type P3D = Point3D
+
+local p2: P3D
+
+p2 = p  -- ok! P3D is a type alias type Point3D
+p = p2  -- ok! aliasing works both ways: they are effectively the same type
+```
+
+Nominal types are compared against non-nominal types _by structure_, so that
+you can manipulate concrete values, which have inferred types. For example,
+you can assign a plain function to a nominal function type, as long as the
+signatures are compatible, and you can assign a number literal to a nominal
+number type.
+
+```lua
+local type MyFunction = function(number): string
+
+-- f has a nominal type
+local f: MyFunction
+
+-- g is inferred a structural type: function(number): string
+local g = function(n: number): string
+   return tostring(n)
+end
+
+f = g  -- ok! structural matched against nominal
+g = f  -- ok! nominal matched against structural
+```
+
+You can declare structural types for functions explicitly:
+
+```lua
+local type MyFunction = function(number): string
+
+-- f has a nominal type
+local f: MyFunction
+
+-- h was explicitly given a structural function type
+local h: function(n: number): string
+
+f = h  -- ok!
+h = f  -- ok!
+```
+
+By design, there is no syntax in Teal for declaring structural record types.
+
+## Some examples
+
+Type aliasing only happens when declaring a new user-defined nominal type
+using an existing user-defined nominal type.
+
+```lua
+local type Record1 = record
+   x: integer
+   y: integer
+end
+
+local type Record2 = Record1
+
+local r1: Record1
+assert(r1 is Record2) -- ok!
+```
+
+This does not apply to primitive types. Declaring a type name with the same
+primitive type as a previous declaration is not an aliasing operation. This
+allows you to create types based on primitive types which are distinct from
+each other.
+
+```lua
+local type Temperature = number
+
+local type TemperatureAlias = Temperature
+
+local type Width = number
+
+local temp: Temperature
+
+assert(temp is TemperatureAlias)  -- ok!
+assert(temp is Width)             -- Teal compile error: temp (of type Temperature) can never be a Width
+```
+
+Like records, each declaration of a function type in the program source code
+represents a distinct type. The `function(...):...` syntax for type
+declaration is a type constructor.
+
+```lua
+local type Function1 = function(number): string
+
+local type Function2 = function(number): string
+
+local f1: Function1
+
+assert(f1 is Function2) -- Teal compile error: f1 (of type Function2) can never be a Function1
+```
+
+However, user-defined nominal names referencing those function types can be
+aliased.
+
+```lua
+local type Function1 = function(number): string
+
+local type Function3 = Function1
+
+local f1: Function1
+assert(f1 is Function3) -- ok!
+```