Feature/add function argument parameters (#40)

b0mbie · web-flow · commit 4356d7cdd254 · 2024-01-21T21:00:12.000+01:00
* Add function argument params for `http` library

* Add function argument params for `concommand.Add`

* Add function argument params for `cvars.AddChangeCallback`

* Add function argument params for `duplicator` library

* Add function argument params for `net.Receive`

* Add function argument params for `saverestore` library

* Add function argument params for `search.AddProvider`

* Add function argument params for `sound` library

* Add function argument params for `spawnmenu` library

* Add function argument params for `steamworks` library

* Add function argument params for `undo.AddFunction`

* Don't override `duplicator.RegisterConstraint` actually

The callback receives `...` arguments, which is too complex for LuaLS to handle.

* Make `len` in `net.Receive` callback an `integer`

Unless you can have a fraction of a bit, it makes sense to put an integer here.

* Add function arg param types for `spawnmenu.PopulateFromTextFiles`
diff --git a/custom/concommand.Add.lua b/custom/concommand.Add.lua
@@ -0,0 +1,20 @@
+---[SHARED AND MENU] Creates a console command that runs a function in lua with optional autocompletion function and help text.
+---
+--- This will fail if the concommand was previously removed with concommand.Remove in a different realm (creating a command on the client that was removed from the server and vice-versa).
+---
+---[(View on wiki)](https://wiki.facepunch.com/gmod/concommand.Add)
+---@param name string The command name to be used in console.
+---
+--- This cannot be a name of existing console command or console variable. It will silently fail if it is.
+---@param callback fun(ply: Player, cmd: string, args: table, argStr: string) The function to run when the concommand is executed. Arguments passed are:
+--- * Player ply - The player that ran the concommand. NULL entity if command was entered with the dedicated server console.
+--- * string cmd - The concommand string (if one callback is used for several concommands).
+--- * table args - A table of all string arguments.
+--- * string argStr - The arguments as a string.
+---@param autoComplete? fun(cmd: string, args: string): string[]? The function to call which should return a table of options for autocompletion. (Console_Command_Auto-completion)
+--- This only properly works on the client since it is **not** networked. Arguments passed are:
+--- * string cmd - The concommand this autocompletion is for.
+--- * string args - The arguments typed so far.
+---@param helpText? string The text to display should a user run 'help cmdName'.
+---@param flags? number Concommand modifier flags. See Enums/FCVAR.
+function concommand.Add(name, callback, autoComplete, helpText, flags) end
diff --git a/custom/cvars.AddChangeCallback.lua b/custom/cvars.AddChangeCallback.lua
@@ -0,0 +1,14 @@
+---[SHARED AND MENU] Adds a callback to be called when the named convar changes.
+---
+--- This does not callback convars in the menu state.
+--- This does not callback convars on the client with FCVAR_GAMEDLL and convars on the server without FCVAR_GAMEDLL.
+--- This does not callback convars on the client with FCVAR_REPLICATED.
+---
+---[(View on wiki)](https://wiki.facepunch.com/gmod/cvars.AddChangeCallback)
+---@param name string The name of the convar to add the change callback to.
+---@param callback fun(convar: string, oldValue: string, newValue: string) The function to be called when the convar changes. The arguments passed are:
+--- * string convar - The name of the convar.
+--- * string oldValue - The old value of the convar.
+--- * string newValue - The new value of the convar.
+---@param identifier? string If set, you will be able to remove the callback using cvars.RemoveChangeCallback. The identifier is not required to be globally unique, as it's paired with the actual name of the convar.
+function cvars.AddChangeCallback(name, callback, identifier) end
diff --git a/custom/duplicator.RegisterBoneModifier.lua b/custom/duplicator.RegisterBoneModifier.lua
@@ -0,0 +1,17 @@
+---[SHARED] Registers a function to be called on each of an entity's bones when duplicator.ApplyBoneModifiers is called.
+---
+--- This function is available to call on the client, but registered functions aren't used anywhere!
+---
+---[(View on wiki)](https://wiki.facepunch.com/gmod/duplicator.RegisterBoneModifier)
+---@param key any The type of the key doesn't appear to matter, but it is preferable to use a string.
+---@param boneModifier fun(ply: Player, ent: Entity, boneID: number, bone: PhysObj, data: table) Function called on each bone that an ent has. Called during duplicator.ApplyBoneModifiers.
+--- Function parameters are:
+--- * Player ply
+--- * Entity ent
+--- * number boneID
+--- * PhysObj bone
+--- * table data
+---
+---
+--- The data table that is passed to boneModifier is set with duplicator.StoreBoneModifier
+function duplicator.RegisterBoneModifier(key, boneModifier) end
diff --git a/custom/duplicator.RegisterEntityClass.lua b/custom/duplicator.RegisterEntityClass.lua
@@ -0,0 +1,9 @@
+---[SHARED] This allows you to specify a specific function to be run when your SENT is pasted with the duplicator, instead of relying on the generic automatic functions.
+---
+--- Automatically calls duplicator.Allow for the entity class.
+---
+---[(View on wiki)](https://wiki.facepunch.com/gmod/duplicator.RegisterEntityClass)
+---@param name string The ClassName of the entity you wish to register a factory for
+---@param _function fun(ply: Player, ...) The factory function you want to have called. It should have the arguments (Player, ...) where ... is whatever arguments you request to be passed. It also should return the entity created, otherwise duplicator.Paste result will not include it!
+---@param ... any Strings of the names of arguments you want passed to function the from the Structures/EntityCopyData. As a special case, "Data" will pass the whole structure.
+function duplicator.RegisterEntityClass(name, _function, ...) end
diff --git a/custom/duplicator.RegisterEntityModifier.lua b/custom/duplicator.RegisterEntityModifier.lua
@@ -0,0 +1,10 @@
+---[SHARED] This allows you to register tweaks to entities. For instance, if you were making an "unbreakable" addon, you would use this to enable saving the "unbreakable" state of entities between duplications.
+---
+--- This function registers a piece of generic code that is run on all entities with this modifier. In order to have it actually run, use duplicator.StoreEntityModifier.
+---
+--- This function does nothing when run clientside.
+---
+---[(View on wiki)](https://wiki.facepunch.com/gmod/duplicator.RegisterEntityModifier)
+---@param name string An identifier for your modification. This is not limited, so be verbose. `Person's 'Unbreakable' mod` is far less likely to cause conflicts than `unbreakable`
+---@param func fun(ply: Player, ent: Entity, data: table) The function to be called for your modification. It should have the arguments (`Player`, `Entity`, `Data`), where data is what you pass to duplicator.StoreEntityModifier.
+function duplicator.RegisterEntityModifier(name, func) end
diff --git a/custom/http.Fetch.lua b/custom/http.Fetch.lua
@@ -0,0 +1,30 @@
+---[SHARED AND MENU] Launches an asynchronous **GET** request to a HTTP server.
+---
+--- HTTP requests returning a status code >= `400` are still considered a success and will call the Structures/HTTPRequest callback.
+---
+--- The Structures/HTTPRequest callback is usually only called on DNS or TCP errors (e.g. the website is unavailable or the domain does not exist).
+---
+--- A rough overview of possible Structures/HTTPRequest messages:
+--- * `invalid url` - Invalid/empty url ( no request was attempted )
+--- * `invalid request` - Steam HTTP lib failed to create a HTTP request
+--- * `error` - OnComplete callback's second argument, `bError`, is `true`
+--- * `unsuccessful` - OnComplete's first argument, `pResult->m_bRequestSuccessful`, returned `false`
+---
+--- This cannot send or receive multiple headers with the same name.
+--- HTTP-requests that respond with a large body may return an `unsuccessful` error. Try using the [Range](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Range) header to download the file in chunks.
+---
+--- 	HTTP-requests to destinations on private networks (such as `192.168.0.1`, or `127.0.0.1`) won't work.
+---
+--- 	To enable HTTP-requests to destinations on private networks use Command Line Parameters `-allowlocalhttp`. (Dedicated servers only)
+---
+---[(View on wiki)](https://wiki.facepunch.com/gmod/http.Fetch)
+---@param url string The URL of the website to fetch.
+---@param onSuccess? fun(body: string, size: integer, headers: table<string, string>, code: integer) Function to be called on success. Arguments are
+--- * string body
+--- * number size - equal to string.len(body).
+--- * table headers
+--- * number code - The HTTP success code.
+---@param onFailure? fun(error: string) Function to be called on failure. Arguments are
+--- * string error - The error message.
+---@param headers? table KeyValue table for headers.
+function http.Fetch(url, onSuccess, onFailure, headers) end
diff --git a/custom/http.Post.lua b/custom/http.Post.lua
@@ -0,0 +1,25 @@
+---[SHARED AND MENU] Sends an asynchronous **POST** request to a HTTP server.
+---
+--- HTTP requests returning a status code >= `400` are still considered a success and will call the Structures/HTTPRequest callback.
+---
+--- The Structures/HTTPRequest callback is usually only called on DNS or TCP errors (e.g. the website is unavailable or the domain does not exist).
+---
+--- This cannot send or receive multiple headers with the same name.
+--- HTTP-requests that respond with a large body may return an `unsuccessful` error. Try using the [Range](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Range) header to download the file in chunks.
+---
+--- 	HTTP-requests to destinations on private networks (such as `192.168.0.1`, or `127.0.0.1`) won't work.
+---
+--- 	To enable HTTP-requests to destinations on private networks use Command Line Parameters `-allowlocalhttp`. (Dedicated servers only)
+---
+---[(View on wiki)](https://wiki.facepunch.com/gmod/http.Post)
+---@param url string The url to of the website to post.
+---@param parameters table The post parameters (x-www-form-urlencoded) to be send to the server. **Keys and values must be strings**.
+---@param onSuccess? fun(body: string, size: integer, headers: table<string, string>, code: integer) Function to be called on success. Arguments are
+--- * string body
+--- * string size - equal to string.len(body).
+--- * table headers
+--- * number code - The HTTP success code.
+---@param onFailure? fun(error: string) Function to be called on failure. Arguments are
+--- * string error - The error message.
+---@param headers? table<string, string> KeyValue table for headers.
+function http.Post(url, parameters, onSuccess, onFailure, headers) end
diff --git a/custom/net.Receive.lua b/custom/net.Receive.lua
@@ -0,0 +1,15 @@
+---[SHARED] Adds a net message handler. Only one receiver can be used to receive the net message.
+--- The message-name is converted to lower-case so the message-names "`BigBlue`" and "`bigblue`" would be equal.
+--- You **must** put this function **outside** of any other function or hook for it to work properly unless you know what you are doing!
+---
+--- You **must** read information in the same order as you write it.
+---
+--- Each net message has a length limit of **64KB**!
+---
+---[(View on wiki)](https://wiki.facepunch.com/gmod/net.Receive)
+---@param messageName string The message name to hook to.
+---@param callback fun(len: integer, ply: Player) The function to be called if the specified message was received. Arguments are:
+---
+--- * number len - Length of the message, in bits.
+--- * Player ply - The player that sent the message, works **only** server-side.
+function net.Receive(messageName, callback) end
diff --git a/custom/saverestore.AddRestoreHook.lua b/custom/saverestore.AddRestoreHook.lua
@@ -0,0 +1,24 @@
+---[SHARED] Adds a restore/load hook for the Half-Life 2 save system.
+---
+---[(View on wiki)](https://wiki.facepunch.com/gmod/saverestore.AddRestoreHook)
+---@param identifier string The unique identifier for this hook.
+---@param callback fun(save: IRestore) The function to be called when an engine save is being loaded. It has one argument:
+---
+---
+--- IRestore save - The restore object to be used to read data from save file that is being loaded
+---
+---
+---
+---
+---
+--- You can also use those functions to read data:
+---
+---
+--- saverestore.ReadVar
+---
+---
+--- saverestore.ReadTable
+---
+---
+--- saverestore.LoadEntity
+function saverestore.AddRestoreHook(identifier, callback) end
diff --git a/custom/saverestore.AddSaveHook.lua b/custom/saverestore.AddSaveHook.lua
@@ -0,0 +1,24 @@
+---[SHARED] Adds a save hook for the Half-Life 2 save system. You can this to carry data through level transitions in Half-Life 2.
+---
+---[(View on wiki)](https://wiki.facepunch.com/gmod/saverestore.AddSaveHook)
+---@param identifier string The unique identifier for this hook.
+---@param callback fun(save: ISave) The function to be called when an engine save is being saved. It has one argument:
+---
+---
+--- ISave save - The save object to be used to write data to the save file that is being saved
+---
+---
+---
+---
+---
+--- You can also use those functions to save data:
+---
+---
+--- saverestore.WriteVar
+---
+---
+--- saverestore.WriteTable
+---
+---
+--- saverestore.SaveEntity
+function saverestore.AddSaveHook(identifier, callback) end
diff --git a/custom/search.AddProvider.lua b/custom/search.AddProvider.lua
@@ -0,0 +1,11 @@
+---[CLIENT] Adds a search result provider. For examples, see gamemodes/sandbox/gamemode/cl_search_models.lua
+---
+---[(View on wiki)](https://wiki.facepunch.com/gmod/search.AddProvider)
+---@param provider fun(searchQuery: string): table[] Provider function. It has one argument: string searchQuery
+--- You must return a list of tables structured like this:
+--- * string text - Text to "Copy to clipboard"
+--- * function func - Function to use/spawn the item
+--- * Panel icon - A panel to add to spawnmenu
+--- * table words - A table of words?
+---@param id? string If provided, ensures that only one provider exists with the given ID at a time.
+function search.AddProvider(provider, id) end
diff --git a/custom/sound.Generate.lua b/custom/sound.Generate.lua
@@ -0,0 +1,11 @@
+---[CLIENT] Creates a sound from a function.
+---
+---[(View on wiki)](https://wiki.facepunch.com/gmod/sound.Generate)
+---@param indentifier string An unique identified for the sound.
+---
+--- 			You cannot override already existing ones.
+---
+---@param samplerate number The sample rate of the sound. Must be `11025`, `22050` or `44100`.
+---@param length number The length in seconds of the sound to generate.
+---@param callback fun(sample: integer): number A function which will be called to generate every sample on the sound. This function gets the current sample number passed as the first argument. The return value must be between `-1.0` and `1.0`. Other values will wrap back to the -1 to 1 range and basically clip. There are **65535** possible quantifiable values between -1 and 1.
+function sound.Generate(indentifier, samplerate, length, callback) end
diff --git a/custom/sound.PlayURL.lua b/custom/sound.PlayURL.lua
@@ -0,0 +1,24 @@
+---[CLIENT] Allows you to play external sound files, as well as online radio streams.
+--- You can find a list of all error codes [here](http://www.un4seen.com/doc/#bass/BASS_ErrorGetCode.html)
+---
+--- For offline file playback, see sound.PlayFile.
+---
+--- Due to a bug with [BASS](http://www.un4seen.com/), AAC codec streams cannot be played in 3D mode.
+---
+---[(View on wiki)](https://wiki.facepunch.com/gmod/sound.PlayURL)
+---@param url string The URL of the sound to play
+---@param flags string Flags for the sound. Can be one or more of following, separated by a space (`" "`):
+--- * 3d - Makes the sound 3D, so you can set its position
+--- * mono - Forces the sound to have only one channel
+--- * noplay - Forces the sound not to play as soon as this function is called
+--- * noblock - Disables streaming in blocks. It is more resource-intensive, but it is required for IGModAudioChannel:SetTime.
+---
+---
+---
+---
+--- If you don't want to use any of the above, you can just leave it as `""`.
+---@param callback fun(soundchannel: IGModAudioChannel, errorID: number, errorName: string) Callback function that is called as soon as the the stream is loaded. It has the following arguments:
+--- * IGModAudioChannel soundchannel - The sound channel
+--- * number errorID - ID of an error, if an error has occured
+--- * string errorName - Name of an error, if an error has occured
+function sound.PlayURL(url, flags, callback) end
diff --git a/custom/spawnmenu.AddContentType.lua b/custom/spawnmenu.AddContentType.lua
@@ -0,0 +1,15 @@
+---[CLIENT] Registers a new content type that is saveable into spawnlists.
+--- Created/called by spawnmenu.CreateContentIcon.
+---
+---[(View on wiki)](https://wiki.facepunch.com/gmod/spawnmenu.AddContentType)
+---@param name string An unique name of the content type.
+---@param constructor fun(container: Panel, data: table) A function that is called whenever we need create a new panel for this content type.
+---
+--- It has two arguments:
+---
+---
+--- Panel container - The container/parent of the new panel
+---
+---
+--- table data - Data for the content type passed from spawnmenu.CreateContentIcon
+function spawnmenu.AddContentType(name, constructor) end
diff --git a/custom/spawnmenu.AddCreationTab.lua b/custom/spawnmenu.AddCreationTab.lua
@@ -0,0 +1,10 @@
+---[CLIENT] Inserts a new tab into the CreationMenus table, which will be used by the creation menu to generate its tabs (Spawnlists, Weapons, Entities, etc.)
+---
+---[(View on wiki)](https://wiki.facepunch.com/gmod/spawnmenu.AddCreationTab)
+---@generic T : Panel
+---@param name string What text will appear on the tab (I.E Spawnlists).
+---@param _function fun(): T The function called to generate the content of the tab.
+---@param material? string Path to the material that will be used as an icon on the tab.
+---@param order? number The order in which this tab should be shown relative to the other tabs on the creation menu.
+---@param tooltip? string The tooltip to be shown for this tab.
+function spawnmenu.AddCreationTab(name, _function, material, order, tooltip) end
diff --git a/custom/spawnmenu.PopulateFromTextFiles.lua b/custom/spawnmenu.PopulateFromTextFiles.lua
@@ -0,0 +1,5 @@
+---[CLIENT] Loads spawnlists from text files.
+---
+---[(View on wiki)](https://wiki.facepunch.com/gmod/spawnmenu.PopulateFromTextFiles)
+---@param callback fun(filename: string, name: string, contents: table, icon: string, id: integer, parentid: integer, needsapp: string) The function to call. Arguments are ( strFilename, strName, tabContents, icon, id, parentid, needsapp )
+function spawnmenu.PopulateFromTextFiles(callback) end
diff --git a/custom/steamworks.Download.lua b/custom/steamworks.Download.lua
@@ -0,0 +1,12 @@
+---[CLIENT AND MENU] Downloads a file from the supplied addon and saves it as a .cache file in garrysmod/cache folder.
+---
+--- This is mostly used to download the preview image of the addon, but the game seems to also use it to download replays and saves.
+---
+--- In case the retrieved file is an image and you need the IMaterial, use Global.AddonMaterial with the path supplied from the callback.
+---
+---[(View on wiki)](https://wiki.facepunch.com/gmod/steamworks.Download)
+---@param workshopPreviewID string The Preview ID of workshop item.
+---@param uncompress boolean Whether to uncompress the file or not, assuming it was compressed with LZMA.
+--- You will usually want to set this to true.
+---@param resultCallback fun(pathToSavedFile: string) The function to process retrieved data. The first and only argument is a string, containing path to the saved file.
+function steamworks.Download(workshopPreviewID, uncompress, resultCallback) end
diff --git a/custom/steamworks.DownloadUGC.lua b/custom/steamworks.DownloadUGC.lua
@@ -0,0 +1,8 @@
+---[CLIENT AND MENU] Downloads a Steam Workshop file by its ID and returns a path to it.
+---
+---[(View on wiki)](https://wiki.facepunch.com/gmod/steamworks.DownloadUGC)
+---@param workshopID string The ID of workshop item to download. **NOT** a file ID.
+---@param resultCallback fun(path: string, file: file_class) The function to process retrieved data. Arguments passed are:
+--- * string path - Contains a path to the saved file, or nil if the download failed for any reason.
+--- * file_class file - A file object pointing to the downloaded .gma file. The file handle will be closed after the function exits.
+function steamworks.DownloadUGC(workshopID, resultCallback) end
diff --git a/custom/undo.AddFunction.lua b/custom/undo.AddFunction.lua
@@ -0,0 +1,9 @@
+---[SERVER] Adds a function to call when the current undo block is undone. Note that if an undo has a function, the player will always be notified when this undo is performed, even if the entity it is meant to undo no longer exists.
+---
+---[(View on wiki)](https://wiki.facepunch.com/gmod/undo.AddFunction)
+---@param func fun(undoData: Undo) The function to call. First argument will be the Structures/Undo, all subsequent arguments will be what was passed after this function in the argument below.
+---
+--- Returning `false` will mark execution of this function as "failed", meaning that the undo might be skipped if no other entities are removed by it. This is useful when for example an entity you want to access is removed therefore there's nothing to do.
+---
+---@param ... any Arguments to pass to the function (after the undo info table)
+function undo.AddFunction(func, ...) end
