X Tutup
Skip to content

plugins.md

Latest commit

 

History

History
110 lines (84 loc) · 3.4 KB

plugins.md

File metadata and controls

110 lines (84 loc) · 3.4 KB
title Plugins

TypeScriptToLua supports plugins - an interface that allows to customize transpilation behavior.

To add a plugin you have to add it under tstl.luaPlugins option in the configuration file.

Example:

{
  "tstl": {
    "luaPlugins": [
      // Plugin is a JavaScript module exporting an object
      { "name": "./plugin1.js" },
      // TypeScriptToLua can load plugins written in TypeScript using `ts-node`
      { "name": "./plugin2.ts" },
      // Plugins can be published to npm
      { "name": "tstl-plugin-3" }
    ]
  }
}

API

visitors

Internally, to process Abstract Syntax Tree of a TypeScript program, TypeScriptToLua implements the visitor pattern. Visitor is a function, called with a processed node and transformation context, and returning a Lua AST node. Plugins can inject their own visitors using visitors property, overriding standard transformation behavior.

Example:

import * as ts from "typescript";
import * as tstl from "typescript-to-lua";

const plugin: tstl.Plugin = {
  // `visitors` is a record where keys are TypeScript node syntax kinds
  visitors: {
    // Visitor can be a function that returns Lua AST node
    [ts.SyntaxKind.ReturnStatement]: () => tstl.createReturnStatement([tstl.createBooleanLiteral(true)]),
  },
};

export default plugin;

Example 2:

import * as ts from "typescript";
import * as tstl from "typescript-to-lua";

const plugin: tstl.Plugin = {
  visitors: {
    // Visit string literals, if original transformer returns a string literal, change the string to "bar" instead
    [ts.SyntaxKind.StringLiteral]: (node, context) => {
      // `context` exposes `superTransform*` methods, that can be used to call either the visitor provided by previous
      // plugin, or a standard TypeScriptToLua visitor
      const result = context.superTransformExpression(node);

      // Standard visitor for ts.StringLiteral always returns tstl.StringLiteral node
      if (tstl.isStringLiteral(result)) {
        result.value = "bar";
      }

      return result;
    },
  },
};

export default plugin;

printer

printer is a function that overrides the standard implementation of the Lua AST printer. It receives some information about the file and the transformed Lua AST. See the LuaPrinter page for more information.

Example:

import { SourceNode } from "source-map";
import * as ts from "typescript";
import * as tstl from "typescript-to-lua";

const CUSTOM_COMMENT_HEADER = "-- This code was generated with a custom plugin!\n";

class CustomPrinter extends tstl.LuaPrinter {
  /* Override printFile */
  protected printFile(file: tstl.File): SourceNode {
    const originalResult = super.printFile(file);
    // Add header comment at the top of the file
    return this.createSourceNode(file, [`${CUSTOM_COMMENT_HEADER} ${this.luaFile}\n`, originalResult]);
  }

  /* Override printBoolean */
  public printBooleanLiteral(expression: tstl.BooleanLiteral): SourceNode {
    // Print any boolean as 'true'
    return this.createSourceNode(expression, "true");
  }
}

const plugin: tstl.Plugin = {
  printer: (program: ts.Program, emitHost: tstl.EmitHost, fileName: string, file: tstl.File) =>
    new CustomPrinter(emitHost, program, fileName).print(file),
};

export default plugin;
X Tutup