From 395fe514f67589f3423f2033c38fedd09f6a882e Mon Sep 17 00:00:00 2001 From: Perryvw Date: Sat, 26 Dec 2020 21:36:57 +0100 Subject: [PATCH 1/3] Added language extensions page --- docs/advanced/language-extensions.md | 60 ++++++++++++++++++++++++++++ sidebars.json | 2 +- 2 files changed, 61 insertions(+), 1 deletion(-) create mode 100644 docs/advanced/language-extensions.md diff --git a/docs/advanced/language-extensions.md b/docs/advanced/language-extensions.md new file mode 100644 index 00000000..3c0f3c94 --- /dev/null +++ b/docs/advanced/language-extensions.md @@ -0,0 +1,60 @@ +--- +title: Language extensions +--- + +import { SideBySide } from "@site/src/components/SideBySide"; + +TypeScriptToLua provides several extensions to typescript in the form of types and helper functions. To use these language extensions, add the types to your `tsconfig.json`: + +```json +{ + "compilerOptions": { + ... + "types": ["typescript-to-lua/language-extensions"], + ... + }, +} +``` + +## MultiReturn Type +This language extension allows typing of Lua functions that return multiple values. For example, consider Lua's `string.find`, it returns two indices: the start of the found substring and the end of the found substring. In TypeScript, function can only return one value so a special type is needed to indicate to tstl there are multiple return values. This is the `MultiReturn<>` type. + +It allows us to declare `string.find` like this: + + +```ts title=stringfind.ts +declare namespace string { + export function find(haystack: string, needle: string): MultiReturn<[number, number]>; +} + +const [start, end] = string.find("Hello, world!", "world"); +``` +Translating into: +```lua title=stringfind.lua +start, ____end = string.find("Hello, world!", "world") +``` + +:::note +Prefer MultiReturn over the similar [@tupleReturn anotation](./compiler-annotations.md#tuplereturn). MultiReturn can do anything tupleReturn can, with the added benefit of being able to distinguish between actual tuple tables and multiple return values in the type system. +::: + +### $multi +Now that we have a type-safe way of describing multiple return values of a function, we would also like a type-safe way of creating instances of this type. In order to create a function that returns multiple values it needs to return a `MultiReturn<>` type. This is where the `$multi` function comes in. Calling `$multi` in a return statement will create an instance of the `MultiReturn<>` type: + +```ts title=multi.ts +function myFunc(): MultiReturn<[string, number]> { + return $multi("foo", 4); +} + +const [foo, four] = myFunc(); +``` + +Translates into: +```lua title=multi.lua +function myFunc(self) + return "foo", 4 +end +foo, four = myFunc(nil) +``` + + diff --git a/sidebars.json b/sidebars.json index 6c6869dc..6e0b48cd 100644 --- a/sidebars.json +++ b/sidebars.json @@ -8,7 +8,7 @@ { "type": "category", "label": "Advanced", - "items": ["advanced/writing-declarations", "advanced/compiler-annotations"] + "items": ["advanced/writing-declarations", "advanced/compiler-annotations", "advanced/language-extensions"] }, { "type": "category", From 48827c3646e400ff23ba7948ec1157fd32f1cb5f Mon Sep 17 00:00:00 2001 From: Perryvw Date: Sat, 26 Dec 2020 21:41:29 +0100 Subject: [PATCH 2/3] fix prettier --- docs/advanced/language-extensions.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/advanced/language-extensions.md b/docs/advanced/language-extensions.md index 3c0f3c94..ca1a93f9 100644 --- a/docs/advanced/language-extensions.md +++ b/docs/advanced/language-extensions.md @@ -17,19 +17,21 @@ TypeScriptToLua provides several extensions to typescript in the form of types a ``` ## MultiReturn Type + This language extension allows typing of Lua functions that return multiple values. For example, consider Lua's `string.find`, it returns two indices: the start of the found substring and the end of the found substring. In TypeScript, function can only return one value so a special type is needed to indicate to tstl there are multiple return values. This is the `MultiReturn<>` type. It allows us to declare `string.find` like this: - ```ts title=stringfind.ts declare namespace string { - export function find(haystack: string, needle: string): MultiReturn<[number, number]>; + export function find(haystack: string, needle: string): MultiReturn<[number, number]>; } const [start, end] = string.find("Hello, world!", "world"); ``` + Translating into: + ```lua title=stringfind.lua start, ____end = string.find("Hello, world!", "world") ``` @@ -38,23 +40,23 @@ start, ____end = string.find("Hello, world!", "world") Prefer MultiReturn over the similar [@tupleReturn anotation](./compiler-annotations.md#tuplereturn). MultiReturn can do anything tupleReturn can, with the added benefit of being able to distinguish between actual tuple tables and multiple return values in the type system. ::: -### $multi +### \$multi + Now that we have a type-safe way of describing multiple return values of a function, we would also like a type-safe way of creating instances of this type. In order to create a function that returns multiple values it needs to return a `MultiReturn<>` type. This is where the `$multi` function comes in. Calling `$multi` in a return statement will create an instance of the `MultiReturn<>` type: ```ts title=multi.ts function myFunc(): MultiReturn<[string, number]> { - return $multi("foo", 4); + return $multi("foo", 4); } const [foo, four] = myFunc(); ``` Translates into: + ```lua title=multi.lua function myFunc(self) return "foo", 4 end foo, four = myFunc(nil) ``` - - From e6a853785531a5152cbb403d44d4da4d7e19da18 Mon Sep 17 00:00:00 2001 From: Perryvw Date: Sun, 27 Dec 2020 12:42:27 +0100 Subject: [PATCH 3/3] PR comments --- docs/advanced/language-extensions.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/advanced/language-extensions.md b/docs/advanced/language-extensions.md index ca1a93f9..c54fe7cf 100644 --- a/docs/advanced/language-extensions.md +++ b/docs/advanced/language-extensions.md @@ -4,7 +4,7 @@ title: Language extensions import { SideBySide } from "@site/src/components/SideBySide"; -TypeScriptToLua provides several extensions to typescript in the form of types and helper functions. To use these language extensions, add the types to your `tsconfig.json`: +TypeScriptToLua provides several extensions to the TypeScript language in the form of types and helper functions. To use these language extensions, add the types to your `tsconfig.json`: ```json { @@ -18,7 +18,7 @@ TypeScriptToLua provides several extensions to typescript in the form of types a ## MultiReturn Type -This language extension allows typing of Lua functions that return multiple values. For example, consider Lua's `string.find`, it returns two indices: the start of the found substring and the end of the found substring. In TypeScript, function can only return one value so a special type is needed to indicate to tstl there are multiple return values. This is the `MultiReturn<>` type. +This language extension allows typing of Lua functions that return multiple values. For example, consider Lua's `string.find`, it returns two indices: the start of the found substring and the end of the found substring. In TypeScript, functions can only return one value so a special type is needed to indicate to tstl there are multiple return values. This is the `MultiReturn<>` type. It allows us to declare `string.find` like this: @@ -37,12 +37,12 @@ start, ____end = string.find("Hello, world!", "world") ``` :::note -Prefer MultiReturn over the similar [@tupleReturn anotation](./compiler-annotations.md#tuplereturn). MultiReturn can do anything tupleReturn can, with the added benefit of being able to distinguish between actual tuple tables and multiple return values in the type system. +Prefer MultiReturn over the similar [@tupleReturn annotation](./compiler-annotations.md#tuplereturn). MultiReturn can do anything tupleReturn can, with the added benefit of being able to distinguish between actual tuple tables and multiple return values in the type system. ::: ### \$multi -Now that we have a type-safe way of describing multiple return values of a function, we would also like a type-safe way of creating instances of this type. In order to create a function that returns multiple values it needs to return a `MultiReturn<>` type. This is where the `$multi` function comes in. Calling `$multi` in a return statement will create an instance of the `MultiReturn<>` type: +In order to create a function that returns multiple values it needs to return a `MultiReturn<>` type. This is where the `$multi` function comes in. Calling `$multi` in a return statement will create an instance of the `MultiReturn<>` type: ```ts title=multi.ts function myFunc(): MultiReturn<[string, number]> {