Skip to content

Commit dcd9c4b

Browse files
PerryvwPerryvw
authored
Docs for 1.4.0 (#98)
* Plugin changes * Add extension option to config docs
1 parent d0dd124 commit dcd9c4b

File tree

2 files changed

+53
-13
lines changed

2 files changed

+53
-13
lines changed

‎docs/api/plugins.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,3 +108,42 @@ const plugin: tstl.Plugin = {
108108

109109
export default plugin;
110110
```
111+
112+
### `beforeTransform`
113+
114+
The `beforeTransform` function on plugins is called after gathering the TypeScript program and compiler options, but before any transformation to Lua is done.
115+
116+
It can be used to set up the plugin
117+
118+
```ts
119+
import * as ts from "typescript";
120+
import * as tstl from "typescript-to-lua";
121+
122+
class Plugin implements tstl.Plugin {
123+
public beforeTransform(program: ts.Program, options: tstl.CompilerOptions, emitHost: EmitHost) {
124+
console.log("starting transformation of program", program, "with options", options);
125+
}
126+
}
127+
128+
const plugin = new Plugin();
129+
export default plugin;
130+
```
131+
132+
### `afterPrint`
133+
134+
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.
135+
136+
```ts
137+
import * as ts from "typescript";
138+
import * as tstl from "typescript-to-lua";
139+
140+
const plugin: tstl.Plugin = {
141+
afterPrint(program: ts.Program, options: tstl.CompilerOptions, emitHost: EmitHost, result: tstl.ProcessedFile[]) {
142+
for (const file of result) {
143+
file.code = "-- Commented added by afterPrint plugin\n" + file.code;
144+
}
145+
},
146+
};
147+
148+
export default plugin;
149+
```

‎docs/configuration.md‎

Lines changed: 14 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -23,19 +23,20 @@ You can use our [VS Code extension](editor-support.md) or manually specify the J
2323
}
2424
```
2525

26-
| Option | Values | Description |
27-
| -------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
28-
| `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. |
29-
| `noImplicitSelf` | `true`, `false` (default: `false`) | If true, treats all project files as if they were prefixed with<br />`/** @noSelfInFile **/`. |
30-
| `noHeader` | `true`, `false` (default: `false`) | Set this to true if you don't want to include our header in the output. |
31-
| `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. |
32-
| `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. |
33-
| `luaBundle` | File path (relative to the `tsconfig.json`) | Will bundle all output lua files into a single bundle file. Requires **luaBundleEntry** to be set! |
34-
| `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. |
35-
| `luaPlugins` | `Array<{ name: string; import?: string }>` | List of [TypeScriptToLua plugins](api/plugins.md). |
36-
| `buildMode` | `"default"`, `"library"` (default: `"library"`) | Use `buildMode: "library"` to build [publishable library packages](publishing-modules.md). |
37-
| `tstlVerbose` | `true`, `false` (default: `false`) | Output additional logging when performing a tstl build, to help diagnose issues. |
38-
| `noResolvePaths` | `Array<string>` | 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")`. |
26+
| Option | Values | Description |
27+
| -------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
28+
| `buildMode` | `"default"`, `"library"` (default: `"library"`) | Use `buildMode: "library"` to build [publishable library packages](publishing-modules.md). |
29+
| `extension` | File extension (default: `".lua"`) | Extension of emitted lua files. |
30+
| `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. |
31+
| `noImplicitSelf` | `true`, `false` (default: `false`) | If true, treats all project files as if they were prefixed with<br />`/** @noSelfInFile **/`. |
32+
| `noHeader` | `true`, `false` (default: `false`) | Set this to true if you don't want to include our header in the output. |
33+
| `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. |
34+
| `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. |
35+
| `luaBundle` | File path (relative to the `tsconfig.json`) | Will bundle all output lua files into a single bundle file. Requires **luaBundleEntry** to be set! |
36+
| `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. |
37+
| `luaPlugins` | `Array<{ name: string; import?: string }>` | List of [TypeScriptToLua plugins](api/plugins.md). |
38+
| `tstlVerbose` | `true`, `false` (default: `false`) | Output additional logging when performing a tstl build, to help diagnose issues. |
39+
| `noResolvePaths` | `Array<string>` | 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")`. |
3940

4041
## Standard options
4142

0 commit comments

Comments
 (0)