diff --git a/docs/typedefs/FS.luau b/docs/typedefs/FS.luau index 3aa051b..f611fc6 100644 --- a/docs/typedefs/FS.luau +++ b/docs/typedefs/FS.luau @@ -14,7 +14,7 @@ export type MetadataPermissions = { readOnly: boolean, } --- FIXME: We lose doc comments here because of the union type +-- FIXME: We lose doc comments here below in Metadata because of the union type --[=[ @interface Metadata @@ -87,189 +87,201 @@ export type WriteOptions = { end ``` ]=] -return { - --[=[ - @within FS - @tag must_use +local fs = {} - Reads a file at `path`. +--[=[ + @within FS + @tag must_use - An error will be thrown in the following situations: + Reads a file at `path`. - * `path` does not point to an existing file. - * The current process lacks permissions to read the file. - * The contents of the file cannot be read as a UTF-8 string. - * Some other I/O error occurred. + An error will be thrown in the following situations: - @param path The path to the file to read - @return The contents of the file - ]=] - readFile = function(path: string): string - return nil :: any - end, - --[=[ - @within FS - @tag must_use + * `path` does not point to an existing file. + * The current process lacks permissions to read the file. + * The contents of the file cannot be read as a UTF-8 string. + * Some other I/O error occurred. - Reads entries in a directory at `path`. + @param path The path to the file to read + @return The contents of the file +]=] +function fs.readFile(path: string): string + return nil :: any +end - An error will be thrown in the following situations: +--[=[ + @within FS + @tag must_use - * `path` does not point to an existing directory. - * The current process lacks permissions to read the contents of the directory. - * Some other I/O error occurred. + Reads entries in a directory at `path`. - @param path The directory path to search in - @return A list of files & directories found - ]=] - readDir = function(path: string): { string } - return {} - end, - --[=[ - @within FS + An error will be thrown in the following situations: - Writes to a file at `path`. + * `path` does not point to an existing directory. + * The current process lacks permissions to read the contents of the directory. + * Some other I/O error occurred. - An error will be thrown in the following situations: + @param path The directory path to search in + @return A list of files & directories found +]=] +function fs.readDir(path: string): { string } + return {} +end - * The file's parent directory does not exist. - * The current process lacks permissions to write to the file. - * Some other I/O error occurred. +--[=[ + @within FS - @param path The path of the file - @param contents The contents of the file - ]=] - writeFile = function(path: string, contents: string) end, - --[=[ - @within FS + Writes to a file at `path`. - Creates a directory and its parent directories if they are missing. + An error will be thrown in the following situations: - An error will be thrown in the following situations: + * The file's parent directory does not exist. + * The current process lacks permissions to write to the file. + * Some other I/O error occurred. - * `path` already points to an existing file or directory. - * The current process lacks permissions to create the directory or its missing parents. - * Some other I/O error occurred. + @param path The path of the file + @param contents The contents of the file +]=] +function fs.writeFile(path: string, contents: string) end - @param path The directory to create - ]=] - writeDir = function(path: string) end, - --[=[ - @within FS +--[=[ + @within FS - Removes a file. + Creates a directory and its parent directories if they are missing. - An error will be thrown in the following situations: + An error will be thrown in the following situations: - * `path` does not point to an existing file. - * The current process lacks permissions to remove the file. - * Some other I/O error occurred. + * `path` already points to an existing file or directory. + * The current process lacks permissions to create the directory or its missing parents. + * Some other I/O error occurred. - @param path The file to remove - ]=] - removeFile = function(path: string) end, - --[=[ - @within FS + @param path The directory to create +]=] +function fs.writeDir(path: string) end - Removes a directory and all of its contents. +--[=[ + @within FS - An error will be thrown in the following situations: + Removes a file. - * `path` is not an existing and empty directory. - * The current process lacks permissions to remove the directory. - * Some other I/O error occurred. + An error will be thrown in the following situations: - @param path The directory to remove - ]=] - removeDir = function(path: string) end, - --[=[ - @within FS - @tag must_use + * `path` does not point to an existing file. + * The current process lacks permissions to remove the file. + * Some other I/O error occurred. - Gets metadata for the given path. + @param path The file to remove +]=] +function fs.removeFile(path: string) end - An error will be thrown in the following situations: +--[=[ + @within FS - * The current process lacks permissions to read at `path`. - * Some other I/O error occurred. + Removes a directory and all of its contents. - @param path The path to get metadata for - @return Metadata for the path - ]=] - metadata = function(path: string): Metadata - return nil :: any - end, - --[=[ - @within FS - @tag must_use + An error will be thrown in the following situations: - Checks if a given path is a file. + * `path` is not an existing and empty directory. + * The current process lacks permissions to remove the directory. + * Some other I/O error occurred. - An error will be thrown in the following situations: + @param path The directory to remove +]=] +function fs.removeDir(path: string) end - * The current process lacks permissions to read at `path`. - * Some other I/O error occurred. +--[=[ + @within FS + @tag must_use - @param path The file path to check - @return If the path is a file or not - ]=] - isFile = function(path: string): boolean - return nil :: any - end, - --[=[ - @within FS - @tag must_use + Gets metadata for the given path. - Checks if a given path is a directory. + An error will be thrown in the following situations: - An error will be thrown in the following situations: + * The current process lacks permissions to read at `path`. + * Some other I/O error occurred. - * The current process lacks permissions to read at `path`. - * Some other I/O error occurred. + @param path The path to get metadata for + @return Metadata for the path +]=] +function fs.metadata(path: string): Metadata + return nil :: any +end - @param path The directory path to check - @return If the path is a directory or not - ]=] - isDir = function(path: string): boolean - return nil :: any - end, - --[=[ - @within FS +--[=[ + @within FS + @tag must_use - Moves a file or directory to a new path. + Checks if a given path is a file. - Throws an error if a file or directory already exists at the target path. - This can be bypassed by passing `true` as the third argument, or a dictionary of options. - Refer to the documentation for `WriteOptions` for specific option keys and their values. + An error will be thrown in the following situations: - An error will be thrown in the following situations: + * The current process lacks permissions to read at `path`. + * Some other I/O error occurred. - * The current process lacks permissions to read at `from` or write at `to`. - * The new path exists on a different mount point. - * Some other I/O error occurred. + @param path The file path to check + @return If the path is a file or not +]=] +function fs.isFile(path: string): boolean + return nil :: any +end - @param from The path to move from - @param to The path to move to - @param overwriteOrOptions Options for the target path, such as if should be overwritten if it already exists - ]=] - move = function(from: string, to: string, overwriteOrOptions: (boolean | WriteOptions)?) end, - --[=[ - @within FS +--[=[ + @within FS + @tag must_use - Copies a file or directory recursively to a new path. + Checks if a given path is a directory. - Throws an error if a file or directory already exists at the target path. - This can be bypassed by passing `true` as the third argument, or a dictionary of options. - Refer to the documentation for `WriteOptions` for specific option keys and their values. + An error will be thrown in the following situations: - An error will be thrown in the following situations: + * The current process lacks permissions to read at `path`. + * Some other I/O error occurred. - * The current process lacks permissions to read at `from` or write at `to`. - * Some other I/O error occurred. + @param path The directory path to check + @return If the path is a directory or not +]=] +function fs.isDir(path: string): boolean + return nil :: any +end - @param from The path to copy from - @param to The path to copy to - @param overwriteOrOptions Options for the target path, such as if should be overwritten if it already exists - ]=] - copy = function(from: string, to: string, overwriteOrOptions: (boolean | WriteOptions)?) end, -} +--[=[ + @within FS + + Moves a file or directory to a new path. + + Throws an error if a file or directory already exists at the target path. + This can be bypassed by passing `true` as the third argument, or a dictionary of options. + Refer to the documentation for `WriteOptions` for specific option keys and their values. + + An error will be thrown in the following situations: + + * The current process lacks permissions to read at `from` or write at `to`. + * The new path exists on a different mount point. + * Some other I/O error occurred. + + @param from The path to move from + @param to The path to move to + @param overwriteOrOptions Options for the target path, such as if should be overwritten if it already exists +]=] +function fs.move(from: string, to: string, overwriteOrOptions: (boolean | WriteOptions)?) end + +--[=[ + @within FS + + Copies a file or directory recursively to a new path. + + Throws an error if a file or directory already exists at the target path. + This can be bypassed by passing `true` as the third argument, or a dictionary of options. + Refer to the documentation for `WriteOptions` for specific option keys and their values. + + An error will be thrown in the following situations: + + * The current process lacks permissions to read at `from` or write at `to`. + * Some other I/O error occurred. + + @param from The path to copy from + @param to The path to copy to + @param overwriteOrOptions Options for the target path, such as if should be overwritten if it already exists +]=] +function fs.copy(from: string, to: string, overwriteOrOptions: (boolean | WriteOptions)?) end + +return fs diff --git a/docs/typedefs/Net.luau b/docs/typedefs/Net.luau index 9b495f8..52eb28d 100644 --- a/docs/typedefs/Net.luau +++ b/docs/typedefs/Net.luau @@ -196,98 +196,106 @@ export type WebSocket = { end) ``` ]=] -return { - --[=[ - @within Net +local net = {} - Sends an HTTP request using the given url and / or parameters, and returns a dictionary that describes the response received. +--[=[ + @within Net - Only throws an error if a miscellaneous network or I/O error occurs, never for unsuccessful status codes. + Sends an HTTP request using the given url and / or parameters, and returns a dictionary that describes the response received. - @param config The URL or request config to use - @return A dictionary representing the response for the request - ]=] - request = function(config: string | FetchParams): FetchResponse - return nil :: any - end, - --[=[ - @within Net - @tag must_use + Only throws an error if a miscellaneous network or I/O error occurs, never for unsuccessful status codes. - Connects to a web socket at the given URL. + @param config The URL or request config to use + @return A dictionary representing the response for the request +]=] +function net.request(config: string | FetchParams): FetchResponse + return nil :: any +end - Throws an error if the server at the given URL does not support - web sockets, or if a miscellaneous network or I/O error occurs. +--[=[ + @within Net + @tag must_use - @param url The URL to connect to - @return A web socket handle - ]=] - socket = function(url: string): WebSocket - return nil :: any - end, - --[=[ - @within Net + Connects to a web socket at the given URL. - Creates an HTTP server that listens on the given `port`. + Throws an error if the server at the given URL does not support + web sockets, or if a miscellaneous network or I/O error occurs. - This will ***not*** block and will keep listening for requests on the given `port` - until the `stop` function on the returned `ServeHandle` has been called. + @param url The URL to connect to + @return A web socket handle +]=] +function net.socket(url: string): WebSocket + return nil :: any +end - @param port The port to use for the server - @param handlerOrConfig The handler function or config to use for the server - ]=] - serve = function(port: number, handlerOrConfig: ServeHttpHandler | ServeConfig): ServeHandle - return nil :: any - end, - --[=[ - @within Net - @tag must_use +--[=[ + @within Net - Encodes the given value as JSON. + Creates an HTTP server that listens on the given `port`. - @param value The value to encode as JSON - @param pretty If the encoded JSON string should include newlines and spaces. Defaults to false - @return The encoded JSON string - ]=] - jsonEncode = function(value: any, pretty: boolean?): string - return nil :: any - end, - --[=[ - @within Net - @tag must_use + This will ***not*** block and will keep listening for requests on the given `port` + until the `stop` function on the returned `ServeHandle` has been called. - Decodes the given JSON string into a lua value. + @param port The port to use for the server + @param handlerOrConfig The handler function or config to use for the server +]=] +function net.serve(port: number, handlerOrConfig: ServeHttpHandler | ServeConfig): ServeHandle + return nil :: any +end - @param encoded The JSON string to decode - @return The decoded lua value - ]=] - jsonDecode = function(encoded: string): any - return nil :: any - end, - --[=[ - @within Net - @tag must_use +--[=[ + @within Net + @tag must_use - Encodes the given string using URL encoding. + Encodes the given value as JSON. - @param s The string to encode - @param binary If the string should be treated as binary data and/or is not valid utf-8. Defaults to false - @return The encoded string - ]=] - urlEncode = function(s: string, binary: boolean?): string - return nil :: any - end, - --[=[ - @within Net - @tag must_use + @param value The value to encode as JSON + @param pretty If the encoded JSON string should include newlines and spaces. Defaults to false + @return The encoded JSON string +]=] +function net.jsonEncode(value: any, pretty: boolean?): string + return nil :: any +end - Decodes the given string using URL decoding. +--[=[ + @within Net + @tag must_use - @param s The string to decode - @param binary If the string should be treated as binary data and/or is not valid utf-8. Defaults to false - @return The decoded string - ]=] - urlDecode = function(s: string, binary: boolean?): string - return nil :: any - end, -} + Decodes the given JSON string into a lua value. + + @param encoded The JSON string to decode + @return The decoded lua value +]=] +function net.jsonDecode(encoded: string): any + return nil :: any +end + +--[=[ + @within Net + @tag must_use + + Encodes the given string using URL encoding. + + @param s The string to encode + @param binary If the string should be treated as binary data and/or is not valid utf-8. Defaults to false + @return The encoded string +]=] +function net.urlEncode(s: string, binary: boolean?): string + return nil :: any +end + +--[=[ + @within Net + @tag must_use + + Decodes the given string using URL decoding. + + @param s The string to decode + @param binary If the string should be treated as binary data and/or is not valid utf-8. Defaults to false + @return The decoded string +]=] +function net.urlDecode(s: string, binary: boolean?): string + return nil :: any +end + +return net diff --git a/docs/typedefs/Process.luau b/docs/typedefs/Process.luau index 4fcc7a7..e4fa07a 100644 --- a/docs/typedefs/Process.luau +++ b/docs/typedefs/Process.luau @@ -78,83 +78,91 @@ export type SpawnResult = { end ``` ]=] -return { - --[=[ - @within Process - @read_only +local process = {} - The current operating system being used. +--[=[ + @within Process + @tag read_only - Possible values: + The current operating system being used. - * `"linux"` - * `"macos"` - * `"windows"` - ]=] - os = (nil :: any) :: OS, - --[=[ - @within Process - @read_only + Possible values: - The architecture of the processor currently being used. + * `"linux"` + * `"macos"` + * `"windows"` +]=] +process.os = (nil :: any) :: OS - Possible values: +--[=[ + @within Process + @tag read_only - * `"x86_64"` - * `"aarch64"` - ]=] - arch = (nil :: any) :: Arch, - --[=[ - @within Process - @read_only + The architecture of the processor currently being used. - The arguments given when running the Lune script. - ]=] - args = (nil :: any) :: { string }, - --[=[ - @within Process - @read_only + Possible values: - The current working directory in which the Lune script is running. - ]=] - cwd = (nil :: any) :: string, - --[=[ - @within Process - @read_write + * `"x86_64"` + * `"aarch64"` +]=] +process.arch = (nil :: any) :: Arch - Current environment variables for this process. +--[=[ + @within Process + @tag read_only - Setting a value on this table will set the corresponding environment variable. - ]=] - env = (nil :: any) :: { [string]: string? }, - --[=[ - @within Process + The arguments given when running the Lune script. +]=] +process.args = (nil :: any) :: { string } - Exits the currently running script as soon as possible with the given exit code. +--[=[ + @within Process + @tag read_only - Exit code 0 is treated as a successful exit, any other value is treated as an error. + The current working directory in which the Lune script is running. +]=] +process.cwd = (nil :: any) :: string - Setting the exit code using this function will override any otherwise automatic exit code. +--[=[ + @within Process + @read_write - @param code The exit code to set - ]=] - exit = function(code: number?) end, - --[=[ - @within Process + Current environment variables for this process. - Spawns a child process that will run the program `program`, and returns a dictionary that describes the final status and ouput of the child process. + Setting a value on this table will set the corresponding environment variable. +]=] +process.env = (nil :: any) :: { [string]: string? } - The second argument, `params`, can be passed as a list of string parameters to give to the program. +--[=[ + @within Process - The third argument, `options`, can be passed as a dictionary of options to give to the child process. - Refer to the documentation for `SpawnOptions` for specific option keys and their values. + Exits the currently running script as soon as possible with the given exit code. - @param program The program to spawn as a child process - @param params Additional parameters to pass to the program - @param options A dictionary of options for the child process - @return A dictionary representing the result of the child process - ]=] - spawn = function(program: string, params: { string }?, options: SpawnOptions?): SpawnResult - return nil :: any - end, -} + Exit code 0 is treated as a successful exit, any other value is treated as an error. + + Setting the exit code using this function will override any otherwise automatic exit code. + + @param code The exit code to set +]=] +function process.exit(code: number?) end + +--[=[ + @within Process + + Spawns a child process that will run the program `program`, and returns a dictionary that describes the final status and ouput of the child process. + + The second argument, `params`, can be passed as a list of string parameters to give to the program. + + The third argument, `options`, can be passed as a dictionary of options to give to the child process. + Refer to the documentation for `SpawnOptions` for specific option keys and their values. + + @param program The program to spawn as a child process + @param params Additional parameters to pass to the program + @param options A dictionary of options for the child process + @return A dictionary representing the result of the child process +]=] +function process.spawn(program: string, params: { string }?, options: SpawnOptions?): SpawnResult + return nil :: any +end + +return process diff --git a/docs/typedefs/Roblox.luau b/docs/typedefs/Roblox.luau index 63581d2..880f060 100644 --- a/docs/typedefs/Roblox.luau +++ b/docs/typedefs/Roblox.luau @@ -213,179 +213,187 @@ export type DataModel = fs.writeFile("myPlaceFile.rbxl", newPlaceFile) ``` ]=] -return { - --[=[ - @within Roblox - @tag must_use +local roblox = {} - Deserializes a place into a DataModel instance. +--[=[ + @within Roblox + @tag must_use - This function accepts a string of contents, *not* a file path. - If reading a place file from a file path is desired, `fs.readFile` - can be used and the resulting string may be passed to this function. + Deserializes a place into a DataModel instance. - ### Example usage + This function accepts a string of contents, *not* a file path. + If reading a place file from a file path is desired, `fs.readFile` + can be used and the resulting string may be passed to this function. - ```lua - local fs = require("@lune/fs") - local roblox = require("@lune/roblox") + ### Example usage - local placeFile = fs.readFile("filePath.rbxl") - local game = roblox.deserializePlace(placeFile) - ``` + ```lua + local fs = require("@lune/fs") + local roblox = require("@lune/roblox") - @param contents The contents of the place to read - ]=] - deserializePlace = function(contents: string): DataModel - return nil :: any - end, - --[=[ - @within Roblox - @tag must_use + local placeFile = fs.readFile("filePath.rbxl") + local game = roblox.deserializePlace(placeFile) + ``` - Deserializes a model into an array of instances. + @param contents The contents of the place to read +]=] +function roblox.deserializePlace(contents: string): DataModel + return nil :: any +end - This function accepts a string of contents, *not* a file path. - If reading a model file from a file path is desired, `fs.readFile` - can be used and the resulting string may be passed to this function. +--[=[ + @within Roblox + @tag must_use - ### Example usage + Deserializes a model into an array of instances. - ```lua - local fs = require("@lune/fs") - local roblox = require("@lune/roblox") + This function accepts a string of contents, *not* a file path. + If reading a model file from a file path is desired, `fs.readFile` + can be used and the resulting string may be passed to this function. - local modelFile = fs.readFile("filePath.rbxm") - local instances = roblox.deserializeModel(modelFile) - ``` + ### Example usage - @param contents The contents of the model to read - ]=] - deserializeModel = function(contents: string): { Instance } - return nil :: any - end, - --[=[ - @within Roblox - @tag must_use + ```lua + local fs = require("@lune/fs") + local roblox = require("@lune/roblox") - Serializes a place from a DataModel instance. + local modelFile = fs.readFile("filePath.rbxm") + local instances = roblox.deserializeModel(modelFile) + ``` - This string can then be written to a file, or sent over the network. + @param contents The contents of the model to read +]=] +function roblox.deserializeModel(contents: string): { Instance } + return nil :: any +end - ### Example usage +--[=[ + @within Roblox + @tag must_use - ```lua - local fs = require("@lune/fs") - local roblox = require("@lune/roblox") + Serializes a place from a DataModel instance. - local placeFile = roblox.serializePlace(game) - fs.writeFile("filePath.rbxl", placeFile) - ``` + This string can then be written to a file, or sent over the network. - @param dataModel The DataModel for the place to serialize - @param xml If the place should be serialized as xml or not. Defaults to `false`, meaning the place gets serialized using the binary format and not xml. - ]=] - serializePlace = function(dataModel: DataModel, xml: boolean?): string - return nil :: any - end, - --[=[ - @within Roblox - @tag must_use + ### Example usage - Serializes one or more instances as a model. + ```lua + local fs = require("@lune/fs") + local roblox = require("@lune/roblox") - This string can then be written to a file, or sent over the network. + local placeFile = roblox.serializePlace(game) + fs.writeFile("filePath.rbxl", placeFile) + ``` - ### Example usage + @param dataModel The DataModel for the place to serialize + @param xml If the place should be serialized as xml or not. Defaults to `false`, meaning the place gets serialized using the binary format and not xml. +]=] +function roblox.serializePlace(dataModel: DataModel, xml: boolean?): string + return nil :: any +end - ```lua - local fs = require("@lune/fs") - local roblox = require("@lune/roblox") +--[=[ + @within Roblox + @tag must_use - local modelFile = roblox.serializeModel({ instance1, instance2, ... }) - fs.writeFile("filePath.rbxm", modelFile) - ``` + Serializes one or more instances as a model. - @param instances The array of instances to serialize - @param xml If the model should be serialized as xml or not. Defaults to `false`, meaning the model gets serialized using the binary format and not xml. - ]=] - serializeModel = function(instances: { Instance }, xml: boolean?): string - return nil :: any - end, - --[=[ - @within Roblox - @tag must_use + This string can then be written to a file, or sent over the network. - Gets the current auth cookie, for usage with Roblox web APIs. + ### Example usage - Note that this auth cookie is formatted for use as a "Cookie" header, - and that it contains restrictions so that it may only be used for - official Roblox endpoints. To get the raw cookie value without any - additional formatting, you can pass `true` as the first and only parameter. + ```lua + local fs = require("@lune/fs") + local roblox = require("@lune/roblox") - ### Example usage + local modelFile = roblox.serializeModel({ instance1, instance2, ... }) + fs.writeFile("filePath.rbxm", modelFile) + ``` - ```lua - local roblox = require("@lune/roblox") - local net = require("@lune/net") + @param instances The array of instances to serialize + @param xml If the model should be serialized as xml or not. Defaults to `false`, meaning the model gets serialized using the binary format and not xml. +]=] +function roblox.serializeModel(instances: { Instance }, xml: boolean?): string + return nil :: any +end - local cookie = roblox.getAuthCookie() - assert(cookie ~= nil, "Failed to get roblox auth cookie") +--[=[ + @within Roblox + @tag must_use - local myPrivatePlaceId = 1234567890 + Gets the current auth cookie, for usage with Roblox web APIs. - local response = net.request({ - url = "https://assetdelivery.roblox.com/v2/assetId/" .. tostring(myPrivatePlaceId), - headers = { - Cookie = cookie, - }, - }) + Note that this auth cookie is formatted for use as a "Cookie" header, + and that it contains restrictions so that it may only be used for + official Roblox endpoints. To get the raw cookie value without any + additional formatting, you can pass `true` as the first and only parameter. - local responseTable = net.jsonDecode(response.body) - local responseLocation = responseTable.locations[1].location - print("Download link to place: " .. responseLocation) - ``` + ### Example usage - @param raw If the cookie should be returned as a pure value or not. Defaults to false - ]=] - getAuthCookie = function(raw: boolean?): string? - return nil :: any - end, - --[=[ - @within Roblox - @tag must_use + ```lua + local roblox = require("@lune/roblox") + local net = require("@lune/net") - Gets the bundled reflection database. + local cookie = roblox.getAuthCookie() + assert(cookie ~= nil, "Failed to get roblox auth cookie") - This database contains information about Roblox enums, classes, and their properties. + local myPrivatePlaceId = 1234567890 - ### Example usage + local response = net.request({ + url = "https://assetdelivery.roblox.com/v2/assetId/" .. tostring(myPrivatePlaceId), + headers = { + Cookie = cookie, + }, + }) - ```lua - local roblox = require("@lune/roblox") + local responseTable = net.jsonDecode(response.body) + local responseLocation = responseTable.locations[1].location + print("Download link to place: " .. responseLocation) + ``` - local db = roblox.getReflectionDatabase() + @param raw If the cookie should be returned as a pure value or not. Defaults to false +]=] +function roblox.getAuthCookie(raw: boolean?): string? + return nil :: any +end - print("There are", #db:GetClassNames(), "classes in the reflection database") +--[=[ + @within Roblox + @tag must_use - print("All base instance properties:") + Gets the bundled reflection database. - local class = db:GetClass("Instance") - for name, prop in class.Properties do - print(string.format( - "- %s with datatype %s and default value %s", - prop.Name, - prop.Datatype, - tostring(class.DefaultProperties[prop.Name]) - )) - end - ``` - ]=] - getReflectionDatabase = function(): Database - return nil :: any - end, - -- TODO: Make typedefs for all of the datatypes as well... - Instance = (nil :: any) :: { - new: ((className: "DataModel") -> DataModel) & ((className: string) -> Instance), - }, + This database contains information about Roblox enums, classes, and their properties. + + ### Example usage + + ```lua + local roblox = require("@lune/roblox") + + local db = roblox.getReflectionDatabase() + + print("There are", #db:GetClassNames(), "classes in the reflection database") + + print("All base instance properties:") + + local class = db:GetClass("Instance") + for name, prop in class.Properties do + print(string.format( + "- %s with datatype %s and default value %s", + prop.Name, + prop.Datatype, + tostring(class.DefaultProperties[prop.Name]) + )) + end + ``` +]=] +function roblox.getReflectionDatabase(): Database + return nil :: any +end + +-- TODO: Make typedefs for all of the datatypes as well... +roblox.Instance = (nil :: any) :: { + new: ((className: "DataModel") -> DataModel) & ((className: string) -> Instance), } + +return roblox diff --git a/docs/typedefs/Serde.luau b/docs/typedefs/Serde.luau index a42d256..da4f187 100644 --- a/docs/typedefs/Serde.luau +++ b/docs/typedefs/Serde.luau @@ -27,92 +27,97 @@ export type CompressDecompressFormat = "brotli" | "gzip" | "lz4" | "zlib" fs.writeFile("myFile.yaml", serde.encode("yaml", someYaml)) ``` ]=] -return { - --[=[ - @within Serde - @tag must_use +local serde = {} - Encodes the given value using the given format. +--[=[ + @within Serde + @tag must_use - Currently supported formats: + Encodes the given value using the given format. - | Name | Learn More | - |:-------|:---------------------| - | `json` | https://www.json.org | - | `yaml` | https://yaml.org | - | `toml` | https://toml.io | + Currently supported formats: - @param format The format to use - @param value The value to encode - @param pretty If the encoded string should be human-readable, including things such as newlines and spaces. Only supported for json and toml formats, and defaults to false - @return The encoded string - ]=] - encode = function(format: EncodeDecodeFormat, value: any, pretty: boolean?): string - return nil :: any - end, - --[=[ - @within Serde - @tag must_use + | Name | Learn More | + |:-------|:---------------------| + | `json` | https://www.json.org | + | `yaml` | https://yaml.org | + | `toml` | https://toml.io | - Decodes the given string using the given format into a lua value. + @param format The format to use + @param value The value to encode + @param pretty If the encoded string should be human-readable, including things such as newlines and spaces. Only supported for json and toml formats, and defaults to false + @return The encoded string +]=] +function serde.encode(format: EncodeDecodeFormat, value: any, pretty: boolean?): string + return nil :: any +end - Currently supported formats: +--[=[ + @within Serde + @tag must_use - | Name | Learn More | - |:-------|:---------------------| - | `json` | https://www.json.org | - | `yaml` | https://yaml.org | - | `toml` | https://toml.io | + Decodes the given string using the given format into a lua value. - @param format The format to use - @param encoded The string to decode - @return The decoded lua value - ]=] - decode = function(format: EncodeDecodeFormat, encoded: string): any - return nil :: any - end, - --[=[ - @within Serde - @tag must_use + Currently supported formats: - Compresses the given string using the given format. + | Name | Learn More | + |:-------|:---------------------| + | `json` | https://www.json.org | + | `yaml` | https://yaml.org | + | `toml` | https://toml.io | - Currently supported formats: + @param format The format to use + @param encoded The string to decode + @return The decoded lua value +]=] +function serde.decode(format: EncodeDecodeFormat, encoded: string): any + return nil :: any +end - | Name | Learn More | - |:---------|:----------------------------------| - | `brotli` | https://github.com/google/brotli | - | `gzip` | https://www.gnu.org/software/gzip | - | `lz4` | https://github.com/lz4/lz4 | - | `zlib` | https://www.zlib.net | +--[=[ + @within Serde + @tag must_use - @param format The format to use - @param encoded The string to compress - @return The compressed string - ]=] - compress = function(format: CompressDecompressFormat, s: string): string - return nil :: any - end, - --[=[ - @within Serde - @tag must_use + Compresses the given string using the given format. - Decompresses the given string using the given format. + Currently supported formats: - Currently supported formats: + | Name | Learn More | + |:---------|:----------------------------------| + | `brotli` | https://github.com/google/brotli | + | `gzip` | https://www.gnu.org/software/gzip | + | `lz4` | https://github.com/lz4/lz4 | + | `zlib` | https://www.zlib.net | - | Name | Learn More | - |:---------|:----------------------------------| - | `brotli` | https://github.com/google/brotli | - | `gzip` | https://www.gnu.org/software/gzip | - | `lz4` | https://github.com/lz4/lz4 | - | `zlib` | https://www.zlib.net | + @param format The format to use + @param encoded The string to compress + @return The compressed string +]=] +function serde.compress(format: CompressDecompressFormat, s: string): string + return nil :: any +end - @param format The format to use - @param encoded The string to decompress - @return The decompressed string - ]=] - decompress = function(format: CompressDecompressFormat, s: string): string - return nil :: any - end, -} +--[=[ + @within Serde + @tag must_use + + Decompresses the given string using the given format. + + Currently supported formats: + + | Name | Learn More | + |:---------|:----------------------------------| + | `brotli` | https://github.com/google/brotli | + | `gzip` | https://www.gnu.org/software/gzip | + | `lz4` | https://github.com/lz4/lz4 | + | `zlib` | https://www.zlib.net | + + @param format The format to use + @param encoded The string to decompress + @return The decompressed string +]=] +function serde.decompress(format: CompressDecompressFormat, s: string): string + return nil :: any +end + +return serde diff --git a/docs/typedefs/Stdio.luau b/docs/typedefs/Stdio.luau index eb03304..3c5198e 100644 --- a/docs/typedefs/Stdio.luau +++ b/docs/typedefs/Stdio.luau @@ -60,80 +60,87 @@ end stdio.ewrite("\nAnd some error text, too") ``` ]=] -return { - --[=[ - @within Stdio - @tag must_use +local stdio = {} - Return an ANSI string that can be used to modify the persistent output color. +stdio.prompt = prompt - Pass `"reset"` to get a string that can reset the persistent output color. +--[=[ + @within Stdio + @tag must_use - ### Example usage + Return an ANSI string that can be used to modify the persistent output color. - ```lua - stdio.write(stdio.color("red")) - print("This text will be red") - stdio.write(stdio.color("reset")) - print("This text will be normal") - ``` + Pass `"reset"` to get a string that can reset the persistent output color. - @param color The color to use - @return A printable ANSI string - ]=] - color = function(color: Color): string - return nil :: any - end, - --[=[ - @within Stdio - @tag must_use + ### Example usage - Return an ANSI string that can be used to modify the persistent output style. + ```lua + stdio.write(stdio.color("red")) + print("This text will be red") + stdio.write(stdio.color("reset")) + print("This text will be normal") + ``` - Pass `"reset"` to get a string that can reset the persistent output style. + @param color The color to use + @return A printable ANSI string +]=] +function stdio.color(color: Color): string + return nil :: any +end - ### Example usage +--[=[ + @within Stdio + @tag must_use - ```lua - stdio.write(stdio.style("bold")) - print("This text will be bold") - stdio.write(stdio.style("reset")) - print("This text will be normal") - ``` + Return an ANSI string that can be used to modify the persistent output style. - @param style The style to use - @return A printable ANSI string - ]=] - style = function(style: Style): string - return nil :: any - end, - --[=[ - @within Stdio - @tag must_use + Pass `"reset"` to get a string that can reset the persistent output style. - Formats arguments into a human-readable string with syntax highlighting for tables. + ### Example usage - @param ... The values to format - @return The formatted string - ]=] - format = function(...: any): string - return nil :: any - end, - --[=[ - @within Stdio + ```lua + stdio.write(stdio.style("bold")) + print("This text will be bold") + stdio.write(stdio.style("reset")) + print("This text will be normal") + ``` - Writes a string directly to stdout, without any newline. + @param style The style to use + @return A printable ANSI string +]=] +function stdio.style(style: Style): string + return nil :: any +end - @param s The string to write to stdout - ]=] - write = function(s: string) end, - --[=[ - @within Stdio +--[=[ + @within Stdio + @tag must_use - Writes a string directly to stderr, without any newline. + Formats arguments into a human-readable string with syntax highlighting for tables. - @param s The string to write to stderr - ]=] - ewrite = function(s: string) end, - prompt = prompt, -} + @param ... The values to format + @return The formatted string +]=] +function stdio.format(...: any): string + return nil :: any +end + +--[=[ + @within Stdio + + Writes a string directly to stdout, without any newline. + + @param s The string to write to stdout +]=] +function stdio.write(s: string) end + +--[=[ + @within Stdio + + Writes a string directly to stderr, without any newline. + + @param s The string to write to stderr +]=] +function stdio.ewrite(s: string) end + +return stdio diff --git a/docs/typedefs/Task.luau b/docs/typedefs/Task.luau index d902568..924e6bb 100644 --- a/docs/typedefs/Task.luau +++ b/docs/typedefs/Task.luau @@ -27,69 +27,75 @@ print("Running after task.spawn yields") ``` ]=] -return { - --[=[ - @within Task +local task = {} - Stops a currently scheduled thread from resuming. +--[=[ + @within Task - @param thread The thread to cancel - ]=] - cancel = function(thread: thread) end, - --[=[ - @within Task + Stops a currently scheduled thread from resuming. - Defers a thread or function to run at the end of the current task queue. + @param thread The thread to cancel +]=] +function task.cancel(thread: thread) end - @param functionOrThread The function or thread to defer - @return The thread that will be deferred - ]=] - defer = function(functionOrThread: thread | (T...) -> ...any, ...: T...): thread - return nil :: any - end, - --[=[ - @within Task +--[=[ + @within Task - Delays a thread or function to run after `duration` seconds. + Defers a thread or function to run at the end of the current task queue. - If no `duration` is given, this will wait for the minimum amount of time possible. + @param functionOrThread The function or thread to defer + @return The thread that will be deferred +]=] +function task.defer(functionOrThread: thread | (T...) -> ...any, ...: T...): thread + return nil :: any +end - @param functionOrThread The function or thread to delay - @return The thread that will be delayed - ]=] - delay = function( - duration: number?, - functionOrThread: thread | (T...) -> ...any, - ...: T... - ): thread - return nil :: any - end, - --[=[ - @within Task +--[=[ + @within Task - Instantly runs a thread or function. + Delays a thread or function to run after `duration` seconds. - If the spawned task yields, the thread that spawned the task - will resume, letting the spawned task run in the background. + If no `duration` is given, this will wait for the minimum amount of time possible. - @param functionOrThread The function or thread to spawn - @return The thread that was spawned - ]=] - spawn = function(functionOrThread: thread | (T...) -> ...any, ...: T...): thread - return nil :: any - end, - --[=[ - @within Task + @param functionOrThread The function or thread to delay + @return The thread that will be delayed +]=] +function task.delay( + duration: number?, + functionOrThread: thread | (T...) -> ...any, + ...: T... +): thread + return nil :: any +end - Waits for *at least* the given amount of time. +--[=[ + @within Task - The minimum wait time possible when using `task.wait` is limited by the underlying OS sleep implementation. - For most systems this means `task.wait` is accurate down to about 5 milliseconds or less. + Instantly runs a thread or function. - @param duration The amount of time to wait - @return The exact amount of time waited - ]=] - wait = function(duration: number?): number - return nil :: any - end, -} + If the spawned task yields, the thread that spawned the task + will resume, letting the spawned task run in the background. + + @param functionOrThread The function or thread to spawn + @return The thread that was spawned +]=] +function task.spawn(functionOrThread: thread | (T...) -> ...any, ...: T...): thread + return nil :: any +end + +--[=[ + @within Task + + Waits for *at least* the given amount of time. + + The minimum wait time possible when using `task.wait` is limited by the underlying OS sleep implementation. + For most systems this means `task.wait` is accurate down to about 5 milliseconds or less. + + @param duration The amount of time to wait + @return The exact amount of time waited +]=] +function task.wait(duration: number?): number + return nil :: any +end + +return task