fxn/workspace-detector
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add better documentation to functions for editors

Browse Source
This commit is contained in:
Ivy C
2025-09-27 17:45:00 -04:00
parent 1b882bb715
commit 157cc8a8a3
5 changed files with 199 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
lib/cli.luau
+41 -3
View File
@@ -12,7 +12,19 @@ export type CLI = {
local cli = {} :: CLI
-- parses command line arguments into options
--[[
Parses command line arguments into an options table.
### Example usage
```lua
local cli = require("./cli")
local opts = cli.parseArgs()
```
@return An options table containing parsed command line arguments of type `types.opts`.
]]--
function cli.parseArgs(): types.opts
local args: {string} = process.args
local opts: types.opts = {
@@ -73,7 +85,19 @@ function cli.parseArgs(): types.opts
return opts
end
-- prints usage instructions for the command line tool
--[[
Prints usage instructions for the command line tool.
### Example usage
```lua
local cli = require("./cli")
cli.printUsage()
```
@return none
]]--
function cli.printUsage()
stdio.write(stdio.color("red"))
stdio.write("Error: Please provide file path(s) or use --directory flag.\n")
@@ -90,7 +114,21 @@ function cli.printUsage()
stdio.write(stdio.color("reset"))
end
-- checks if output file exists to prevent overwriting
--[[
Checks if the specified output file already exists to prevent overwriting.
If the file exists, prints an error message and exits the program.
### Example usage
```lua
local cli = require("./cli")
cli.checkOutputFile("output.txt")
```
@param outputFile The path to the output file to check.
@return none
]]--
function cli.checkOutputFile(outputFile: string?)
if outputFile and fs.isFile(outputFile) then
stdio.write(stdio.color("red"))
lib/compression.luau
+22 -3
View File
@@ -8,9 +8,28 @@ type CompressionModule = {
local compressionModule = {} :: CompressionModule
-- take in file contents and zlib decompress them
-- if recursive param is true repeatedly zlib decompress the file until it fails
-- (modelscrape files are often double/triple zlib decompressed)
--[[
Decompresses zlib-compressed data. If recursive is true, continues to decompress until data is no longer zlib-compressed.
### Example usage
```lua
local fs = require("@lune/fs")
local compression = require("./compression")
local compressedData = fs.readFile("compressedFile.bin")
local decompressedData = compression.zlibDecompress(compressedData, true)
if decompressedData then
print("Decompression successful.")
else
print("Decompression failed.")
end
```
@param contents The zlib-compressed data as a string.
@param opts Options table of type `types.opts`
@return The decompressed data as a string, or false if decompression fails.
]]--
function compressionModule.zlibDecompress(contents: string, opts: types.opts): string | boolean
assert(typeof(contents) == "string", "Expected contents to be of type 'string'")
assert(typeof(opts) == "table", "Expected opts to be of type 'table'")
lib/core.luau
+78 -4
View File
@@ -13,7 +13,27 @@ export type Core = {
local core = {} :: Core
-- recursively searches a model for a workspace instance
--[[
Recursively scans a model (table of Instances) for a Workspace instance.
### Example usage
```lua
local roblox = require("@lune/roblox")
local core = require("./core")
local model = roblox.deserializeModel(fileContents)
if core.scanForWorkspace(model) then
print("This model contains a Workspace instance.")
else
print("This model does not contain a Workspace instance.")
end
```
@param model The deserialized Roblox model to scan.
@param printInstanceNames If true, prints the full names of all instances in the model during the scan.
@return True if a Workspace instance is found, false otherwise.
]]--
function core.scanForWorkspace(model: types.model, printInstanceNames: boolean): boolean
assert(typeof(model) == "table", "Expected model to be of type 'table''")
assert(typeof(printInstanceNames) == "boolean", "Expected printInstanceNames to be of type 'boolean'")
@@ -28,14 +48,62 @@ function core.scanForWorkspace(model: types.model, printInstanceNames: boolean):
return false
end
-- checks if file has valid extension
--[[
Returns true if the file has a .rbxm or .rbxmx extension, false otherwise.
### Example usage
```lua
local fs = require("@lune/fs")
local modelFile = fs.readFile("filePath.rbxm")
if core.isValidModelFile("filePath.rbxm") then
print("This is a valid Roblox model file.")
else
print("This is not a valid Roblox model file.")
end
```
@param contents The filename of the model file to check.
@return True if the file has a valid model extension, false otherwise.
]]--
function core.isValidModelFile(fileName: string): boolean
assert(typeof(fileName) == "string", "Expected fileName to be of type 'string'")
local ext = string.match(fileName, "%.([^%.]+)$")
return ext == "rbxm" or ext == "rbxmx"
end
-- takes in fileContents as a string and deserializes them returning the results of scanForWorkspace() on the deserialized model. if it can't be deserialized, it will return the results of a naive search through the xml
--[[
Checks if the given file contents contain a Workspace instance.
If the file is a valid Roblox model file, attempts to deserialize it and scan for a Workspace instance.
If deserialization fails, falls back to a simple string search for the Workspace tag.
If zlib decompression options are enabled in opts, attempts to decompress the file contents before scanning.
### Example usage
```lua
local fs = require("@lune/fs")
local core = require("./core")
local fileContents = fs.readFile("model.rbxm")
local opts = {
printInstanceNames = true,
zlibDecompressFiles = true,
zlibDecompressFilesRecursive = false
}
if core.fileContainsWorkspace(fileContents, opts) then
print("The file contains a Workspace instance.")
else
print("The file does not contain a Workspace instance.")
end
```
@param fileContents The contents of the file to check.
@param opts Options table of type `types.opts`
@return True if a Workspace instance is found, false otherwise.
]]
function core.fileContainsWorkspace(fileContents: string, opts: types.opts): boolean
assert(typeof(fileContents) == "string", "Expected fileContents to be of type 'string'")
assert(typeof(opts) == "table", "Expected opts to be of type 'table'")
@@ -55,7 +123,13 @@ function core.fileContainsWorkspace(fileContents: string, opts: types.opts): boo
end
-- formats the workspace detection result as a colored string
--[[
Formats the workspace detection result as a colored string.
@param result The boolean result of the workspace detection.
@param fileName The name of the file that was checked.
@return A formatted string indicating whether the file contains a Workspace instance, colored green for true and yellow for false.
]]--
function core.formatResult(result: boolean, fileName: string): string
assert(typeof(result) == "boolean", "Expected result to be of type 'boolean'")
assert(typeof(fileName) == "string", "Expected fileName to be of type 'string'")
lib/fileproc.luau
+36 -2
View File
@@ -12,7 +12,23 @@ export type FileProc = {
local fileproc = {} :: FileProc
-- collects files to process from command line args or directory
--[[
Collects files to process based on command line arguments or directory mode.
### Example usage
```lua
local cli = require("./cli")
local fileproc = require("./fileproc")
local opts = cli.parseArgs()
local filesToProcess = fileproc.collectFiles(opts)
print("Files to process:", table.concat(filesToProcess, ", "))
```
@param opts Options table of type `types.opts`.
@return A list of file paths to process.
]]--
function fileproc.collectFiles(opts: types.opts): {string}
assert(typeof(opts) == "table", "Expected opts to be of type 'table'")
local filesToProcess = opts.filesToProcess or {}
@@ -52,7 +68,25 @@ function fileproc.collectFiles(opts: types.opts): {string}
return filesToProcess
end
-- processes each file and checks for workspace instances
--[[
Processes each file and checks for workspace instances.
### Example usage
```lua
local cli = require("./cli")
local fileproc = require("./fileproc")
local opts = cli.parseArgs()
local filesToProcess = fileproc.collectFiles(opts)
local filesWithWorkspace = fileproc.processFiles(filesToProcess, opts)
print("Files containing Workspace instances:", table.concat(filesWithWorkspace, ", "))
```
@param filesToProcess A list of file paths to process.
@param opts Options table of type `types.opts`.
@return A list of file paths that contain Workspace instances.
]]--
function fileproc.processFiles(filesToProcess: {string}, opts: types.opts): {string}
assert(typeof(filesToProcess) == "table", "Expected filesToProcess to be of type 'table'")
assert(typeof(opts) == "table", "Expected opts to be of type 'table'")
lib/types.luau
+22
View File
@@ -2,6 +2,19 @@
local types = {}
--[[
Options table type definition.
Will contain these values:
* `outputFile` - The path to the output file, if specified
* `directoryMode` - Whether to operate in directory mode
* `directoryPath` - The path to the directory to scan, if in directory mode
* `forceBinaryRead` - Whether to force reading files even if they lack file extensions
* `printInstanceNames` - Whether to print the names of all instances in the models scanned
* `zlibDecompressFiles` - Whether to decompress zlib-compressed files
* `zlibDecompressFilesRecursive` - Whether to recursively decompress zlib-compressed files
* `filesToProcess` - A list of file paths to process
]]--
export type opts = {
outputFile: string?,
directoryMode: boolean,
@@ -15,6 +28,15 @@ export type opts = {
export type model = {Instance}
--[[
Callback function type definition.
A function that takes a file path and options table, and returns either a string (e.g. processed data) or false on failure.
@param file The path to the file to process.
@param opts Options table of type `types.opts`
@return A string containing processed data, or false if processing fails.
]]--
export type callbackFunction = (file: string, opts: opts) -> string | boolean
return types