declaration fixes (#25)

* updated assert to handle return values

* updated getmetatable to allow any type as input, including strings which have a metatable

* fixed setmetatable index metamethod handling

* added support for LuaTables to pairs

* added missing string.rep function

* added tests for io and file

* fixed popen return values

* fixes to io read functions

* improved declarations for io read

* added standard stream handles to io

* fixed mistake in file.lines

Co-authored-by: Tom <[email protected]>

Author: tomblind

core/global.d.ts

@@ -25,7 +25,11 @@ declare const _G: typeof globalThis;
  * otherwise, returns all its arguments. In case of error, `message` is the
  * error object; when absent, it defaults to "assertion failed!"
  */
-declare function assert(v: any, message?: string): asserts v;
+declare function assert<V>(v: V): Exclude<V, undefined | null | false>;
+declare function assert<V, A extends any[]>(
+    v: V,
+    ...args: A
+): LuaMultiReturn<[Exclude<V, undefined | null | false>, ...A]>;
 
 /**
  * This function is a generic interface to the garbage collector. It performs
@@ -109,7 +113,7 @@ declare function error(message: string, level?: number): never;
  * metatable has a __metatable field, returns the associated value. Otherwise,
  * returns the metatable of the given object.
  */
-declare function getmetatable<T extends object>(object: T): LuaMetatable<T> | undefined;
+declare function getmetatable<T>(object: T): LuaMetatable<T> | undefined;
 
 /**
  * Returns three values (an iterator function, the table t, and 0) so that the
@@ -153,6 +157,9 @@ declare function next(table: object, index?: any): LuaMultiReturn<[any, any] | [
  * See function next for the caveats of modifying the table during its
  * traversal.
  */
+declare function pairs<TKey, TValue>(
+    t: LuaTable<TKey, TValue>
+): LuaIterable<LuaMultiReturn<[TKey, TValue]>>;
 declare function pairs<T>(t: T): LuaIterable<LuaMultiReturn<[keyof T, T[keyof T]]>>;
 
 /**
@@ -234,10 +241,17 @@ declare function select<T>(index: '#', ...args: T[]): number;
  *
  * This function returns table.
  */
-declare function setmetatable<T extends object, TIndex extends object>(
+declare function setmetatable<
+    T extends object,
+    TIndex extends object | ((this: T, key: any) => any) | undefined = undefined
+>(
     table: T,
-    metatable: LuaMetatable<T & TIndex, TIndex> | null | undefined
-): T & TIndex;
+    metatable?: LuaMetatable<T, TIndex> | null
+): TIndex extends (this: T, key: infer TKey) => infer TValue
+    ? T & { [K in TKey & string]: TValue }
+    : TIndex extends object
+    ? T & TIndex
+    : T;
 
 /**
  * When called with no base, tonumber tries to convert its argument to a number.

core/io.d.ts

@@ -61,9 +61,7 @@ declare namespace io {
         filename?: string,
         ...formats: T
     ): LuaIterable<
-        LuaMultiReturn<
-            [] extends T ? [string] : { [P in keyof T]: T[P] extends 'n' ? number : string }
-        >
+        LuaMultiReturn<[] extends T ? [string] : { [P in keyof T]: FileReadFormatToType<T[P]> }>
     >;
 
     /**
@@ -100,12 +98,31 @@ declare namespace io {
      * you can use to read data from this program (if mode is "r", the default) or
      * to write data to this program (if mode is "w").
      */
-    function popen(prog: string, mode?: 'r' | 'w'): LuaFile;
+    function popen(prog: string, mode?: 'r' | 'w'): LuaMultiReturn<[LuaFile] | [undefined, string]>;
 
     /**
      * Equivalent to io.input():read(···).
      */
-    const read: LuaFile['read'];
+    function read(): io.FileReadFormatToType<io.FileReadLineFormat> | undefined;
+    function read<T extends io.FileReadFormat>(format: T): io.FileReadFormatToType<T> | undefined;
+    function read<T extends io.FileReadFormat[]>(
+        ...formats: T
+    ): LuaMultiReturn<{ [P in keyof T]?: io.FileReadFormatToType<T[P]> }>;
+
+    /**
+     * Predefined file handle for standard error stream. The I/O library never closes this file.
+     */
+    const stderr: LuaFile;
+
+    /**
+     * Predefined file handle for standard input stream. The I/O library never closes this file.
+     */
+    const stdin: LuaFile;
+
+    /**
+     * Predefined file handle for standard output stream. The I/O library never closes this file.
+     */
+    const stdout: LuaFile;
 
     /**
      * In case of success, returns a handle for a temporary file. This file is
@@ -125,6 +142,8 @@ declare namespace io {
      * Equivalent to io.output():write(···).
      */
     function write(...args: (string | number)[]): LuaMultiReturn<[LuaFile] | [undefined, string]>;
+
+    type FileReadFormatToType<T> = T extends FileReadNumberFormat ? number : string;
 }
 
 interface LuaFile {
@@ -157,12 +176,10 @@ interface LuaFile {
      * In case of errors this function raises the error, instead of returning an
      * error code.
      */
-    lines<T extends FileReadFormat[]>(
+    lines<T extends io.FileReadFormat[]>(
         ...formats: T
     ): LuaIterable<
-        LuaMultiReturn<
-            [] extends T ? [string] : { [P in keyof T]: T[P] extends 'n' ? number : string }
-        >
+        LuaMultiReturn<[] extends T ? [string] : { [P in keyof T]: io.FileReadFormatToType<T[P]> }>
     >;
 
     /**
@@ -193,9 +210,11 @@ interface LuaFile {
      *
      * The formats "l" and "L" should be used only for text files.
      */
-    read<T extends FileReadFormat[]>(
+    read(): io.FileReadFormatToType<io.FileReadLineFormat> | undefined;
+    read<T extends io.FileReadFormat>(format: T): io.FileReadFormatToType<T> | undefined;
+    read<T extends io.FileReadFormat[]>(
         ...formats: T
-    ): LuaMultiReturn<{ [P in keyof T]?: T[P] extends 'n' ? number : string }>;
+    ): LuaMultiReturn<{ [P in keyof T]?: io.FileReadFormatToType<T[P]> }>;
 
     /**
      * Sets and geionts the file position, measured from the beginning of the

core/metatable.d.ts

@@ -1,6 +1,6 @@
 // Based on https://www.lua.org/manual/5.3/manual.html#2.4
 
-interface LuaMetatable<T, TIndex = object> {
+interface LuaMetatable<T, TIndex extends object | ((this: T, key: any) => any) | undefined> {
     /**
      * the addition (+) operation. If any operand for an addition is not a number
      * (nor a string coercible to a number), Lua will try to call a metamethod.
@@ -102,7 +102,7 @@ interface LuaMetatable<T, TIndex = object> {
      * this table with key. (This indexing is regular, not raw, and therefore can
      * trigger another metamethod.)
      */
-    __index?: TIndex | ((this: T, key: any, value: any) => any);
+    __index?: TIndex;
 
     /**
      * The indexing assignment table[key] = value. Like the index event, this

core/string.d.ts

@@ -179,6 +179,11 @@ declare namespace string {
      */
     function match(s: string, pattern: string, init?: number): LuaMultiReturn<string[]>;
 
+    /**
+     * Returns a string that is the concatenation of `n` copies of the string `s`.
+     */
+    function rep(s: string, n: number): string;
+
     /**
      * Returns a string that is the string s reversed.
      */

special/5.1-only.d.ts

@@ -96,4 +96,8 @@ declare namespace debug {
     ): LuaMultiReturn<[string, any]>;
 }
 
-type FileReadFormat = '*n' | '*a' | '*l' | number;
+declare namespace io {
+    type FileReadNumberFormat = '*n';
+    type FileReadLineFormat = '*l';
+    type FileReadFormat = FileReadNumberFormat | FileReadLineFormat | '*a' | number;
+}

special/5.2-or-jit.d.ts

@@ -1 +1,5 @@
-type FileReadFormat = '*n' | '*a' | '*l' | '*L' | number;
+declare namespace io {
+    type FileReadNumberFormat = '*n';
+    type FileReadLineFormat = '*l';
+    type FileReadFormat = FileReadNumberFormat | FileReadLineFormat | '*a' | '*L' | number;
+}

special/5.3-plus.d.ts

@@ -227,4 +227,8 @@ interface LuaMetatable<T> {
     __shr?(this: T, operand: any): any;
 }
 
-type FileReadFormat = 'n' | 'a' | 'l' | 'L' | number;
+declare namespace io {
+    type FileReadNumberFormat = 'n';
+    type FileReadLineFormat = 'l';
+    type FileReadFormat = FileReadNumberFormat | FileReadLineFormat | 'a' | 'L' | number;
+}