From 2276f70e21bafcb0819915031ff6ffdef8b675fd Mon Sep 17 00:00:00 2001 From: Perryvw Date: Sun, 13 Mar 2022 16:20:13 +0100 Subject: [PATCH 1/2] Plugin changes --- docs/api/plugins.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/docs/api/plugins.md b/docs/api/plugins.md index c77dcaa5..1a769fb6 100644 --- a/docs/api/plugins.md +++ b/docs/api/plugins.md @@ -108,3 +108,42 @@ const plugin: tstl.Plugin = { export default plugin; ``` + +### `beforeTransform` + +The `beforeTransform` function on plugins is called after gathering the TypeScript program and compiler options, but before any transformation to Lua is done. + +It can be used to set up the plugin + +```ts +import * as ts from "typescript"; +import * as tstl from "typescript-to-lua"; + +class Plugin implements tstl.Plugin { + public beforeTransform(program: ts.Program, options: tstl.CompilerOptions, emitHost: EmitHost) { + console.log("starting transformation of program", program, "with options", options); + } +} + +const plugin = new Plugin(); +export default plugin; +``` + +### `afterPrint` + +The `afterPrint` function is called _after_ tstl has finished its work, except for resolving dependencies and calculating output paths. You can use this to modify the list of output files and do direct string modifications to them. + +```ts +import * as ts from "typescript"; +import * as tstl from "typescript-to-lua"; + +const plugin: tstl.Plugin = { + afterPrint(program: ts.Program, options: tstl.CompilerOptions, emitHost: EmitHost, result: tstl.ProcessedFile[]) { + for (const file of result) { + file.code = "-- Commented added by afterPrint plugin\n" + file.code; + } + }, +}; + +export default plugin; +``` From d688cd0b367f3fc104a7d2115c8aa36e23319331 Mon Sep 17 00:00:00 2001 From: Perryvw Date: Sun, 13 Mar 2022 16:47:37 +0100 Subject: [PATCH 2/2] Add extension option to config docs --- docs/configuration.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index fa672273..9b377cd6 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -23,19 +23,20 @@ You can use our [VS Code extension](editor-support.md) or manually specify the J } ``` -| Option | Values | Description | -| -------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `luaTarget` | `"JIT"`, `"5.3"`, `"5.2"`, `"5.1"`, `"universal"` (default: `"universal"`) | Specifies the Lua version you want to generate code for. Choosing `universal` makes TypeScriptToLua generate code compatible with all supported Lua targets. | -| `noImplicitSelf` | `true`, `false` (default: `false`) | If true, treats all project files as if they were prefixed with
`/** @noSelfInFile **/`. | -| `noHeader` | `true`, `false` (default: `false`) | Set this to true if you don't want to include our header in the output. | -| `luaLibImport` | `"inline"`, `"require"`, `"always"`, `"none"` (default: `"require"`) | We polyfill certain JavaScript features with Lua functions, this option specifies how these functions are imported into the Lua output. | -| `sourceMapTraceback` | `true`, `false` (default: `false`) | Overrides Lua's `debug.traceback` to apply sourcemaps to Lua stacktraces. This will make error messages point to your original TypeScript code instead of the generated Lua. | -| `luaBundle` | File path (relative to the `tsconfig.json`) | Will bundle all output lua files into a single bundle file. Requires **luaBundleEntry** to be set! | -| `luaBundleEntry` | File path (relative to the `tsconfig.json`) | This should be the name/path of the TS file in your project that will serve as entry point to the bundled code. | -| `luaPlugins` | `Array<{ name: string; import?: string }>` | List of [TypeScriptToLua plugins](api/plugins.md). | -| `buildMode` | `"default"`, `"library"` (default: `"library"`) | Use `buildMode: "library"` to build [publishable library packages](publishing-modules.md). | -| `tstlVerbose` | `true`, `false` (default: `false`) | Output additional logging when performing a tstl build, to help diagnose issues. | -| `noResolvePaths` | `Array` | An array of require paths that will **NOT** be resolved. For example `["require1", "sub.require2"]` will stop tstl from trying to resolve Lua sources for `require("require1")` and `require("sub.require2")`. | +| Option | Values | Description | +| -------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `buildMode` | `"default"`, `"library"` (default: `"library"`) | Use `buildMode: "library"` to build [publishable library packages](publishing-modules.md). | +| `extension` | File extension (default: `".lua"`) | Extension of emitted lua files. | +| `luaTarget` | `"JIT"`, `"5.3"`, `"5.2"`, `"5.1"`, `"universal"` (default: `"universal"`) | Specifies the Lua version you want to generate code for. Choosing `universal` makes TypeScriptToLua generate code compatible with all supported Lua targets. | +| `noImplicitSelf` | `true`, `false` (default: `false`) | If true, treats all project files as if they were prefixed with
`/** @noSelfInFile **/`. | +| `noHeader` | `true`, `false` (default: `false`) | Set this to true if you don't want to include our header in the output. | +| `luaLibImport` | `"inline"`, `"require"`, `"none"` (default: `"require"`) | We polyfill certain JavaScript features with Lua functions, this option specifies how these functions are imported into the Lua output. `"inline"`: Inline used functions in code; `"require"`: Require full lualib bundle if used in file. `"none"`: Never require/inline any lualib features. | +| `sourceMapTraceback` | `true`, `false` (default: `false`) | Overrides Lua's `debug.traceback` to apply sourcemaps to Lua stacktraces. This will make error messages point to your original TypeScript code instead of the generated Lua. | +| `luaBundle` | File path (relative to the `tsconfig.json`) | Will bundle all output lua files into a single bundle file. Requires **luaBundleEntry** to be set! | +| `luaBundleEntry` | File path (relative to the `tsconfig.json`) | This should be the name/path of the TS file in your project that will serve as entry point to the bundled code. | +| `luaPlugins` | `Array<{ name: string; import?: string }>` | List of [TypeScriptToLua plugins](api/plugins.md). | +| `tstlVerbose` | `true`, `false` (default: `false`) | Output additional logging when performing a tstl build, to help diagnose issues. | +| `noResolvePaths` | `Array` | An array of require paths that will **NOT** be resolved. For example `["require1", "sub.require2"]` will stop tstl from trying to resolve Lua sources for `require("require1")` and `require("sub.require2")`. | ## Standard options