Skip to content

Docs for 1.4.0 #98

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Mar 17, 2022
Merged

Docs for 1.4.0 #98

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2276f70
Plugin changes
Perryvw Mar 13, 2022
d688cd0
Add extension option to config docs
Perryvw Mar 13, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions docs/api/plugins.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
```
27 changes: 14 additions & 13 deletions docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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<br />`/** @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<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")`. |
| 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<br />`/** @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<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")`. |

## Standard options

Expand Down