From 26c880c7a03657590de54fbc7a4486e83882f7f3 Mon Sep 17 00:00:00 2001 From: Filip Tibell Date: Thu, 23 Feb 2023 11:11:47 +0100 Subject: [PATCH] Document all global and user-accessible types --- docs/luneTypes.d.luau | 136 ++++++++++++++++++++++-- packages/cli/src/gen/definitions/tag.rs | 11 ++ 2 files changed, 139 insertions(+), 8 deletions(-) diff --git a/docs/luneTypes.d.luau b/docs/luneTypes.d.luau index 06dddd6..d0fbbd0 100644 --- a/docs/luneTypes.d.luau +++ b/docs/luneTypes.d.luau @@ -1,5 +1,15 @@ +--[=[ + @type FsWriteOptions + @within fs + + Options for filesystem APIs what write to files and/or directories. + + This is a dictionary that may contain one or more of the following values: + + * `overwrite` - If the target path should be overwritten or not, in the case that it already exists +]=] export type FsWriteOptions = { - overwrite: boolean, + overwrite: boolean?, } --[=[ @@ -134,7 +144,8 @@ declare 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 table of options with `overwrite` set to `true.` + This can be bypassed by passing `true` as the third argument, or a dictionary of options. + Refer to the documentation for `FsWriteOptions` for specific option keys and their values. An error will be thrown in the following situations: @@ -151,12 +162,40 @@ declare fs: { type NetMethod = "GET" | "POST" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "PATCH" +--[=[ + @type NetFetchParams + @within net + + Parameters for sending network requests with `net.request`. + + This is a dictionary that may contain one or more of the following values: + + * `url` - The URL to request. This is always required + * `method` - The HTTP method verb, such as `"GET"`, `"POST"`, `"PATCH"`, `"PUT"`, or `"DELETE"`. Defaults to `"GET"` + * `headers` - A table of key-value pairs representing headers + * `body` - The request body +]=] export type NetFetchParams = { url: string, method: NetMethod?, headers: { [string]: string }?, body: string?, } + +--[=[ + @type NetFetchResponse + @within new + + Response type for sending network requests with `net.request`. + + This is a dictionary containing the following values: + + * `ok` - If the status code is a canonical success status code, meaning within the range 200 -> 299 + * `statusCode` - The status code returned for the request + * `statusMessage` - The canonical status message for the returned status code, such as `"Not Found"` for status code 404 + * `headers` - A table of key-value pairs representing headers + * `body` - The request body, or an empty string if one was not given +]=] export type NetFetchResponse = { ok: boolean, statusCode: number, @@ -165,6 +204,20 @@ export type NetFetchResponse = { body: string, } +--[=[ + @type NetRequest + @within net + + Data type for requests in `net.serve`. + + This is a dictionary containing the following values: + + * `path` - The path being requested, relative to the root. Will be `/` if not specified + * `query` - A table of key-value pairs representing query parameters in the request path + * `method` - The HTTP method verb, such as `"GET"`, `"POST"`, `"PATCH"`, `"PUT"`, or `"DELETE"`. Will always be uppercase + * `headers` - A table of key-value pairs representing headers + * `body` - The request body, or an empty string if one was not given +]=] export type NetRequest = { path: string, query: { [string]: string? }, @@ -172,6 +225,19 @@ export type NetRequest = { headers: { [string]: string }, body: string, } + +--[=[ + @type NetRequest + @within net + + Response type for requests in `net.serve`. + + This is a dictionary that may contain one or more of the following values: + + * `status` - The status code for the request, in the range `100` -> `599` + * `headers` - A table of key-value pairs representing headers + * `body` - The response body +]=] export type NetResponse = { status: number?, headers: { [string]: string }?, @@ -181,15 +247,50 @@ export type NetResponse = { type NetServeHttpHandler = (request: NetRequest) -> string | NetResponse type NetServeWebSocketHandler = (socket: NetWebSocket) -> () +--[=[ + @type NetServeConfig + @within net + + Configuration for `net.serve`. + + This may contain one of, or both of the following callbacks: + + * `handleRequest` for handling normal http requests, equivalent to just passing a function to `net.serve` + * `handleWebSocket` for handling web socket requests, which will receive a `NetWebSocket` object as its first and only parameter +]=] export type NetServeConfig = { handleRequest: NetServeHttpHandler?, handleWebSocket: NetServeWebSocketHandler?, } +--[=[ + @type NetServeHandle + @within net + + A handle to a currently running web server, containing a single `stop` function to gracefully shut down the web server. +]=] export type NetServeHandle = { stop: () -> (), } +--[=[ + @type NetWebSocket + @within net + + A reference to a web socket connection. + + The web socket may be in either an "open" or a "closed" state, changing its current behavior. + + When open: + + * Any function on the socket such as `send`, `next` or `close` can be called without erroring + * `next` can be called to yield until the next message is received or the socket becomes closed + + When closed: + + * `next` will no longer return any message(s) and instead instantly return nil + * `send` will throw an error stating that the socket has been closed +]=] declare class NetWebSocket close: () -> () send: (message: string) -> () @@ -265,6 +366,17 @@ declare net: { type ProcessSpawnOptionsStdio = "inherit" | "default" +--[=[ + @type ProcessSpawnOptions + @within process + + A dictionary of options for `process.spawn`, with the following available values: + + * `cwd` - The current working directory for the process + * `env` - Extra environment variables to give to the process + * `shell` - Whether to run in a shell or not - set to `true` to run using the default shell, or a string to run using a specific shell + * `stdio` - How to treat output and error streams from the child process - set to "inherit" to pass output and error streams to the current process +]=] export type ProcessSpawnOptions = { cwd: string?, env: { [string]: string }?, @@ -272,6 +384,19 @@ export type ProcessSpawnOptions = { stdio: ProcessSpawnOptionsStdio?, } +--[=[ + @type ProcessSpawnResult + @within process + + Result type for child processes in `process.spawn`. + + This is a dictionary containing the following values: + + * `ok` - If the child process exited successfully or not, meaning the exit code was zero or not set + * `code` - The exit code set by the child process, or 0 if one was not set + * `stdout` - The full contents written to stdout by the child process, or an empty string if nothing was written + * `stderr` - The full contents written to stderr by the child process, or an empty string if nothing was written +]=] export type ProcessSpawnResult = { ok: boolean, code: number, @@ -353,12 +478,7 @@ declare 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. - The available options inside of the `options` dictionary are: - - * `cwd` - The current working directory for the process - * `env` - Extra environment variables to give to the process - * `shell` - Whether to run in a shell or not - set to `true` to run using the default shell, or a string to run using a specific shell - * `stdio` - How to treat output and error streams from the child process - set to "inherit" to pass output and error streams to the current process + Refer to the documentation for `ProcessSpawnOptions` 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 diff --git a/packages/cli/src/gen/definitions/tag.rs b/packages/cli/src/gen/definitions/tag.rs index c4da915..3ceb88c 100644 --- a/packages/cli/src/gen/definitions/tag.rs +++ b/packages/cli/src/gen/definitions/tag.rs @@ -7,6 +7,7 @@ use super::item::DefinitionsItem; #[serde(rename_all = "PascalCase")] pub enum DefinitionsItemTag { Class(String), + Type(String), Within(String), Param((String, String)), Return(String), @@ -21,6 +22,10 @@ impl DefinitionsItemTag { matches!(self, Self::Class(_)) } + pub fn is_type(&self) -> bool { + matches!(self, Self::Class(_)) + } + pub fn is_within(&self) -> bool { matches!(self, Self::Within(_)) } @@ -57,6 +62,12 @@ impl TryFrom<&DefinitionsItem> for DefinitionsItemTag { .context("Missing class name for class tag")? .to_string(), ), + "type" => Self::Class( + value + .get_value() + .context("Missing type name for type tag")? + .to_string(), + ), "within" => Self::Within( value .get_value()