Add support for generating LuaCATS definitions for the Lua API

[kalimag]

Adds the ability to generate API definitions in the LuaCATS format to the Lua Console.

LuaCATS is primarily the annotation format of Lua Language Server, which drives the most popular VS Code Lua extension and can be used in other editors with language server support.

LuaCATS is an extension/fork of the annotation format used by EmmyLua, but I'm not sure what the status of the latter is. These definitions might be compatible with EmmyLua, but the only spec of its format I could find is sparse and partially in Chinese. EmmyLua extension now uses LuaCATS annotations, too.

The generated definitions could be further improved, e.g. enumerating valid values for surfaceName parameters, specifying the structure of certain table values, and callback function signatures. But that would require extending the API metadata and I wanted to get some feedback first.

Current output:

• BizHawk Dev Builds
• BizHawk 2.11

Check if completed:

• I, the committer, have read the licensing terms for contributors (last updated 2022-07-15) and am compliant

will resolve #3860

[kalimag]

Just for example, some issues LuaLS can detect in the bundled scripts using these definitions:

[vadosnaprimer]

Let's move forward with this one!

I decided to move from notepad++ to vscode for lua coding after 15 years, and ended up making exactly the same thing independently yesterday, I didn't even remember this PR! And here it's done in a much nicer way, so let's have it!

[YoshiRulz]

After fixing malformed examples, works w/ SumnekoLua plugin in IDEA.

[YoshiRulz]

We don't want to encourage this. There are enough footguns in calling gui.* already with Lua not having named arguments.

[kalimag]

Removing this will likely cause a lot of unnecessary warnings

[YoshiRulz]

I think type coercion warnings are good, but then I also consider dynamic languages like Lua to always be inferior to statically-typed languages. Is passing numbers for strings idiomatic in general, or only in concatenation?

[kalimag]

Well, number-to-string conversion is specifically a feature in BizHawk's Lua bindings, not a feature of the Lua runtime. That's why LLS warns about it unless the parameter definition allows numbers.

But reading numbers from memory and passing them to gui functions is a pretty common pattern in BizHawk scripts, so I added this special case for those functions to avoid warnings in existing, working scripts. I have a test directory with the bundled Lua scripts and some from the Lua scripts catalog, and removing this code causes 73 additional warnings, 16 of which are in BizHawk's own scripts (for example).

I have no strong opinions on deprecating this behavior, but currently it's valid so the definitions say it's valid.

[YoshiRulz]

We should introduce new attributes if this grows to any more enums.

[YoshiRulz]

Reference types (i.e. string and byte[]) are nullable too

[kalimag]

True, but this is about documenting when null/nil is valid, and in the Lua API it's generally not unless the parameter is optional.

If the Lua libraries used #nullabe annotations that information should be taken into account here, but currently that's not the case (and also I don't think .NET Framework has a reflection API to read that information).

[YoshiRulz]

All reference types in the Lua API are nullable because Lua is not a .NET language and cannot "see" the NRT metadata.

[kalimag]

I do not follow. Are you saying want every string parameter to be marked string? in the definitions?

[YoshiRulz]

Passing nil for a parameter annotated as string results in a warning from the language server, so yes they all need to be string?. Unless you want to create another attribute and mark all the functions which throw on null arguments.

[kalimag]

That's the point, though? gui.addmessage(nil) throws an error, so the diagnostics should warn about it. event.onexit(function() end, nil) doesn't throw an error, so diagnostics shouldn't warn.

That both are a nullable reference type on the technical level is irrelevant. As far as Lua is concerned, anything goes and you can pass a dozen table arguments to memory.writebyte if you want, but the diagnostics should help you catch that before it causes a runtime error.

[kalimag]

(Didn't see the edit)

Currently the assumption for reference types is: parameters cannot be null unless they are optional. That seems to work well with the existing API surface.

If there turn out to be exceptions where this doesn't hold true, I think it would be preferable to mark nullable parameters rather than not-nullable ones, and for that I'd prefer to just reuse C# #nullable annotations rather than creating a bespoke attribute, if reasonably possible.