Strongly type enums + Fix bug in enums when key is empty in docs (SCREENFADE 0)

Author: luttje

__tests__/api-writer/glua-api-writer.spec.ts

@@ -6,7 +6,7 @@ import { apiDefinition as structApiDefinition, markup as structMarkup, json as s
 import { markup as panelMarkup, apiDefinition as panelApiDefinition } from '../test-data/offline-sites/gmod-wiki/panel-slider';
 import { markup as multiReturnFuncMarkup, apiDefinition as multiReturnFuncApiDefinition } from '../test-data/offline-sites/gmod-wiki/library-function-concommand-gettable';
 import { markup as varargsFuncMarkup, apiDefinition as varargsFuncApiDefinition } from '../test-data/offline-sites/gmod-wiki/library-function-coroutine-resume';
-import { LibraryFunction, WikiPage, WikiPageMarkupScraper } from '../../src/scrapers/wiki-page-markup-scraper';
+import { Enum, LibraryFunction, WikiPage, WikiPageMarkupScraper } from '../../src/scrapers/wiki-page-markup-scraper';
 import { GluaApiWriter } from '../../src/api-writer/glua-api-writer';
 import fetchMock from "jest-fetch-mock";
 
@@ -149,6 +149,79 @@ describe('GLua API Writer', () => {
     expect(api).toMatch(new RegExp(`^${overrideStart}`));
   });
 
+  it('should create aliasses for global enumerations', () => {
+    const writer = new GluaApiWriter();
+    const api = writer.writePage(<Enum>{
+      type: 'enum',
+      name: 'MATERIAL_FOG',
+      address: 'Enums/MATERIAL_FOG',
+      description: 'The fog mode.',
+      realm: 'Client',
+      items: [
+        {
+          key: 'MATERIAL_FOG_NONE',
+          value: '0',
+          description: 'No fog',
+        },
+        {
+          key: 'MATERIAL_FOG_LINEAR',
+          value: '1',
+          description: 'Linear fog',
+        },
+        {
+          key: 'MATERIAL_FOG_LINEAR_BELOW_FOG_Z',
+          value: '2',
+        }
+      ],
+    });
+
+    expect(api).toEqual(`---@alias MATERIAL_FOG 0|1|2\n--- No fog\nMATERIAL_FOG_NONE = 0\n--- Linear fog\nMATERIAL_FOG_LINEAR = 1\nMATERIAL_FOG_LINEAR_BELOW_FOG_Z = 2\n\n\n`);
+  });
+
+  it('should create enums for table enumerations', () => {
+    const writer = new GluaApiWriter();
+    const api = writer.writePage(<Enum>{
+      type: 'enum',
+      name: 'SCREENFADE',
+      address: 'Enums/SCREENFADE',
+      description: 'The screen fade mode.',
+      realm: 'Client',
+      items: [
+        {
+          key: '',
+          value: '0',
+          description: 'Instant fade in',
+        },
+        {
+          key: 'SCREENFADE.IN',
+          value: '1',
+          description: 'Instant fade in',
+        },
+        {
+          key: 'SCREENFADE.OUT',
+          value: '2',
+          description: 'Slowly fade in',
+        },
+        {
+          key: 'SCREENFADE.MODULATE',
+          value: '4',
+        },
+        {
+          key: 'SCREENFADE.STAYOUT',
+          value: '8',
+          description: 'Never disappear',
+        },
+        {
+          key: 'SCREENFADE.PURGE',
+          value: '16',
+          description: 'Used to purge all currently active screen fade effects...\nMultiple\nLines',
+        },
+      ],
+    });
+
+    expect(api).toEqual(`---@enum SCREENFADE\n--- The screen fade mode.\nSCREENFADE = {\n  --- Instant fade in\n  IN = 1,\n  --- Slowly fade in\n  OUT = 2,\n  MODULATE = 4,\n  --- Never disappear\n  STAYOUT = 8,\n  --- Used to purge all currently active screen fade effects...\n  --- Multiple\n  --- Lines\n  PURGE = 16,\n}\n\n`);
+  });
+
   it('should convert table<type> to type[]', () => {
     const writer = new GluaApiWriter();
     const api = writer.writePage(<LibraryFunction>{
@@ -319,6 +392,32 @@ describe('GLua API Writer', () => {
     expect(api).toEqual(`---[CLIENT] Returns where on the screen the specified position vector would appear.\n---\n---[(View on wiki)](na)\n---@return ToScreenData # The created Structures/ToScreenData.\nfunction Vector.ToScreen() end\n\n`);
   });
 
+  // number{ENUM_NAME} -> ENUM_NAME
+  it('should support enum type', () => {
+    const writer = new GluaApiWriter();
+    const api = writer.writePage(<LibraryFunction>{
+      name: 'FogMode',
+      address: 'render.FogMode',
+      parent: 'render',
+      dontDefineParent: true,
+      description: 'Sets the fog mode.',
+      realm: 'Client',
+      type: 'libraryfunc',
+      url: 'na',
+      arguments: [
+        {
+          args: [{
+            name: 'mode',
+            type: 'number{MATERIAL_FOG}',
+            description: 'The fog mode.',
+          }]
+        }
+      ],
+    });
+
+    expect(api).toEqual(`---[CLIENT] Sets the fog mode.\n---\n---[(View on wiki)](na)\n---@param mode MATERIAL_FOG The fog mode.\nfunction render.FogMode(mode) end\n\n`);
+  });
+
   // it('should be able to write Annotated API files directly from wiki pages', async () => {
   //   const baseUrl = 'https://wiki.facepunch.com/gmod/GM:AcceptInput';
   //   fetchMock.mockResponseOnce(html, { url: baseUrl });

src/api-writer/glua-api-writer.ts

@@ -1,5 +1,5 @@
 import { ClassFunction, Enum, Function, HookFunction, LibraryFunction, TypePage, Panel, PanelFunction, Realm, Struct, WikiPage, isPanel, FunctionArgument, FunctionCallback } from '../scrapers/wiki-page-markup-scraper.js';
-import { escapeSingleQuotes, putCommentBeforeEachLine, removeNewlines, safeFileName, toLowerCamelCase } from '../utils/string.js';
+import { escapeSingleQuotes, indentText, putCommentBeforeEachLine, removeNewlines, safeFileName, toLowerCamelCase } from '../utils/string.js';
 import {
   isClassFunction,
   isHookFunction,
@@ -225,22 +225,44 @@ export class GluaApiWriter {
 
   private writeEnum(_enum: Enum) {
     let api: string = '';
-    const isContainedInTable = _enum.items[0]?.key.includes('.') ?? false;
+
+    // If the first key is empty (like SCREENFADE has), check the second key
+    const isContainedInTable =
+      _enum.items[0]?.key === ''
+        ? _enum.items[1]?.key.includes('.')
+        : _enum.items[0]?.key.includes('.');
 
     if (_enum.deprecated)
       api += `---@deprecated ${removeNewlines(_enum.deprecated)}\n`;
 
-    api += `---@enum ${_enum.name}\n`;
+    if (isContainedInTable) {
+      api += `---@enum ${_enum.name}\n`;
+    } else {
+      // Until LuaLS supports global enumerations (https://github.com/LuaLS/lua-language-server/issues/2721) we
+      // will use @alias as a workaround
+      const validEnumerations = _enum.items.map(item => item.value).join('|');
+      api += `---@alias ${_enum.name} ${validEnumerations}\n`;
+    }
 
     if (isContainedInTable) {
       api += _enum.description ? `${putCommentBeforeEachLine(_enum.description.trim(), false)}\n` : '';
       api += `${_enum.name} = {\n`;
     }
 
     const writeItem = (key: string, item: typeof _enum.items[0]) => {
+      if (key === '') {
+        // Happens for SCREENFADE which has a blank key to describe what 0 does.
+        return;
+      }
+
       if (isContainedInTable) {
         key = key.split('.')[1];
-        api += `  ${key} = ${item.value}, ` + (item.description ? `--[[ ${item.description} ]]` : '') + '\n';
+
+        if (item.description?.trim()) {
+          api += `${indentText(putCommentBeforeEachLine(item.description.trim(), false), 2)}\n`;
+        }
+
+        api += `  ${key} = ${item.value},\n`;
       } else {
         api += item.description ? `${putCommentBeforeEachLine(item.description.trim(), false)}\n` : '';
         if (item.deprecated)
@@ -364,6 +386,13 @@ export class GluaApiWriter {
 
       if (!innerType) throw new Error(`Invalid table type: ${type}`);
 
+      return innerType;
+    } else if (type.startsWith('number{')) {
+      // Convert number{MATERIAL_FOG} to MATERIAL_FOG enum for LuaLS
+      let innerType = type.match(/{([^}]+)}/)?.[1];
+
+      if (!innerType) throw new Error(`Invalid number type: ${type}`);
+
       return innerType;
     }
 

src/utils/string.ts

@@ -58,3 +58,13 @@ export function escapeSingleQuotes(str: string) {
   return str.replace(/'/g, '\\\'');
 }
 
+/**
+ * Indents all lines in a string by a given amount
+ *
+ * @param text The text to indent
+ * @param indent The amount of spaces to indent by
+ * @returns The indented text
+ */
+export function indentText(text: string, indent: number) {
+  return text.split('\n').map(line => ' '.repeat(indent) + line).join('\n');
+}