luttje / luttje/glua-api-snippets

Model specific behavior of `CompileString`

Open
#89 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
45
Forks
10
PR merge metrics
No merged PRs in 30d

Description

It's something a bit niche, but [`CompileString`](https://wiki.facepunch.com/gmod/Global.CompileString) has very specific conditions about what type of value it returns based on the `handleError` argument. If that argument is unspecified, `nil` or `true`, then the function returns either the compiled `function` or `nil` to indicate an error which has been handled by the game:
```
] lua_run_cl print("Error return type:", type(CompileString("end", "bad")))

[ERROR] bad:1: '' expected near 'end'
1. unknown - LuaCmd:1

Error return type: nil
] lua_run_cl print("Error return type:", type(CompileString("end", "bad", nil)))

[ERROR] bad:1: '' expected near 'end'
1. unknown - LuaCmd:1

Error return type: nil
] lua_run_cl print("Error return type:", type(CompileString("end", "bad", true)))

[ERROR] bad:1: '' expected near 'end'
1. unknown - LuaCmd:1

Error return type: nil
```
... and, if `handleError` is `false`, then the function returns either the compiled `function` or `string`:
```
] lua_run_cl print("Error return type:", type(CompileString("end", "bad", false)))
Error return type: string
```

### Possible solution
The wiki only specifies the return type as `function`, which probably warrants an edit to the actual wiki page to change the return type to "string or function or nil", but I'm not sure if that's possible?

The exact behavior *could* be modeled with a change to `handleError`'s type and some `@overload`s for `CompileString`:
```lua
---![(Shared)](https://github.com/user-attachments/assets/a356f942-57d7-4915-a8cc-559870a980fc) This function will compile the code argument as lua code and return a function that will execute that code.
---
--- Please note that this function will not automatically execute the given code after compiling it.
---
---[View wiki](https://wiki.facepunch.com/gmod/Global.CompileString)
---@param code string The code to compile.
---@param identifier string An identifier in case an error is thrown. (The same identifier can be used multiple times)
---@param handleError? true If false this function will return an error string instead of throwing an error.
---@return function? # A function that, when called, will execute the given code.
---
--- Returns the error string if there was a Lua error and third argument is false.
---@overload fun(code: string, identifier: string, handleError: false): function|string
---@overload fun(code: string, identifier: string, handleError: boolean): function|string|nil
function _G.CompileString(code, identifier, handleError) end
```
With this, the following example checks out:
```lua
local handleError = ...
local _ = CompileString("end", "error handled maybe", handleError) -- `string|function|nil` (can't know the exact value of `handleError` so assume both cases are possible)
local _ = CompileString("end", "error handled", true) -- `function?` (explicit handling by the game)
local _ = CompileString("end", "error handled by default") -- `function?` (`handleError = true` by default)
local _ = CompileString("end", "error handled by default", nil) -- `function?` (ditto)
local _ = CompileString("end", "error not handled", false) -- `function|string` (explicit handling by the caller)
```

I don't like how `handleError` is documented as just having a type of "`true`" by default - it might be overkill, but it's nice to have this very specific behavior modeled in the type system.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Search the generated Lua API snippets for the _G.CompileString declaration and compare it with the linked Garry's Mod wiki behavior. Review the proposed handleError overloads and return types, then update the declaration so the documented cases distinguish function, string, and nil. Done means the generated language-server comments accurately represent each handleError case.

Written by the indexing model from the issue text.

Assessment

Tech stack
lua
Domain
developer-experience, tooling
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.