X Tutup
Skip to content

Operator Mapping Library Extensions#969

Merged
Perryvw merged 12 commits intoTypeScriptToLua:masterfrom
tomblind:operator-map-extensions
Jan 26, 2021
Merged

Operator Mapping Library Extensions#969
Perryvw merged 12 commits intoTypeScriptToLua:masterfrom
tomblind:operator-map-extensions

Conversation

@tomblind
Copy link
Collaborator

@tomblind tomblind commented Jan 24, 2021

Resolves #964

Support for mapping lua's metamethod-based operator overloads to function declarations. This allows operator overloads provided by libraries to be callable from TS.

A common example of this would be a math vector class:

interface Vector {
    x: number;
    y: number;
}

declare function Vector(x: number, y: number): Vector;

const a = Vector(1, 2);
const b = Vector(3, 4);
const result = a + b; // Not allowed

To solve this, declaration writers can now map the add operator to a function:

declare const vectorAdd: LuaAdd<Vector, Vector, Vector>;

const result = vectorAdd(a, b); // transpiles to 'result = a + b'

Mappings don't need to be global functions:

declare namespace Vector {
    export const add: LuaAdd<Vector, Vector, Vector>;
}
const result = Vector.add(a, b); // result = a + b

They can also declared as methods on the object using an alternate type:

interface Vector {
    add: LuaAddMethod<Vector, Vector>;
}
const result = a.add(b); // result = a + b

Overloads are allowed using intersections and work as expected:

declare const vectorMul: LuaMul<Vector, Vector, Vector> & LuaMul<Vector, number, number>;
const result = vectorMul(a, b); // result is Vector
const result = vectorMul(a, 7); // result is number

Currently, the following operators are supported:

  • Common binary math operators (add, subtract, etc...)
  • Negation operator
  • Less-than & greater-than operators
  • Table length operator
  • Concat operator
  • Bitwise operators (5.3+ only)

lolleko
lolleko reviewed Jan 25, 2021
View reviewed changes
Perryvw
Perryvw reviewed Jan 25, 2021
View reviewed changes
language-extensions/index.d.ts Outdated
declare function $multi<T extends any[]>(...values: T): MultiReturn<T>;
declare type MultiReturn<T extends any[]> = T & { readonly " __multiBrand": unique symbol };

declare type LuaAdd<TA, TB, TR> = ((a: TA, b: TB) => TR) & { readonly __luaAddBrand: unique symbol };
Copy link
Member

@Perryvw Perryvw Jan 25, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should probably add jsdoc comments explaining these language extensions (we should also for multi & multireturn, but can be in another PR) so that people that didn't write but just consume declarations can also understand what is happening. Something like:

/**
 * Calls to functions with this type are translated to `a + b`.
 * For more information see: https://typescripttolua.github.io/docs/advanced/language-extensions
 *
 * @param TA The type of the left-hand-side of the operation.
 * @param TB The type of the right-hand-side of the operation.
 * @param TR The resulting (return) type of the operation.
 */
declare type LuaAdd<TA, TB, TR> = ((a: TA, b: TB) => TR) & { readonly __luaAddBrand: unique symbol };

ALSO: Thoughts on renaming the type params to TLeft, TRight, TReturn?

test/unit/language-extensions/operators.spec.ts Outdated
`;

const binaryMathOperatorTests: Array<[string, number, number, number]> = [
["LuaAdd", 7, 4, 11],
Copy link
Member

@Perryvw Perryvw Jan 25, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not obvious what this means at first, might be more readable if you use objects instead of tuples, ie { extensionType: "LuaAdd", left: 7, right: 4, expectedResult: 11 }, similar to https://github.com/TypeScriptToLua/TypeScriptToLua/blob/master/test/unit/assignments.spec.ts#L408

tomblind and others added 3 commits January 26, 2021 06:24
@tomblind
addressed feedback
8b6f539
@tomblind @Perryvw
Update src/transformation/utils/diagnostics.ts
9608682 
Co-authored-by: Perry van Wesel <Perryvw@users.noreply.github.com>
@tomblind
snapshot update
f6117f1
@Perryvw Perryvw merged commit 0158732 into TypeScriptToLua:master Jan 26, 2021
@lolleko lolleko mentioned this pull request Jan 29, 2021
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@lolleko lolleko lolleko approved these changes

@Perryvw Perryvw Perryvw approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Overloaded Operator Mapping Proposals

3 participants

@tomblind @lolleko @Perryvw
X Tutup