PathHandler

Work with a file or a folder as an object: join paths, list a folder, read and write files, open big ones, recycle instead of delete.

FileService:GetPathHandler(path) gives one. Path work (Path, Join, Connect, GetParent) never touches the disk; everything else ends in Async and waits. A PathHandler is outside the tree: its Parent is nil and it has no children, so a folder's contents come from ListDirAsync. Creating, copying and moving refuse a name that exists already, and RecycleAsync keeps what it removes restorable.

ShotInstancenot creatableFiles

Example

Walk a folderShotScript

-- Makes a small folder tree, walks it with ListDirAsync and prints it indented, then removes it.
use FileService
local top = FileService:GetPathHandler("MyProject")
FileService:MakeFolderAsync(top:Join("Notes", "Old").Path)
top:WriteChildAsync("todo.txt", "buy milk")
top:Join("Notes"):WriteChildAsync("app.log", "started")

local function walk(path : PathHandler, indent : string)
	local isFolder = path:IsFolderAsync()
	print(indent .. path.BaseName .. (if isFolder then "/" else ""))
	if isFolder then
		local listing : {[string] : PathHandler} = path:ListDirAsync() or {}
		local names : {string} = {}
		for name in listing do
			table.insert(names, name)
		end
		table.sort(names)
		for _, name in names do
			walk(listing[name], indent .. "  ")
		end
	end
end
walk(top, "")
FileService:RemoveAsync(top.Path)
print("after RemoveAsync: " .. top:GetFileTypeAsync())

What it printedOutput

MyProject/
  Notes/
    Old/
    app.log
  todo.txt
after RemoveAsync: None

A short program that makes a small folder tree, walks it with ListDirAsync and prints it indented, beside the indented listing it printed when it ran. — Walking a folder

Properties

Name	Type	Default	Description
BaseName	`string`	read-only	The last part of the path, the file or folder name with its extension; a trailing slash is ignored.
Path	`string`	read-only	The path as given, backslashes turned into forward slashes; a relative path starts at the project file's folder.

Methods

Name	Arguments	Returns	Description
Connect	`(with: string)`	`string`	The path of a child named with, as a plain string, without making a PathHandler or touching the disk.
CopyAsync yields	`(targetParent: PathHandler, newName: string?)`	`(PathHandler?, string?)`	Waits to copy this file or folder into targetParent, under newName if given; it refuses an existing target and a targetParent that isn't a folder.
CreateSubFileAsync yields	`(name: string)`	`(PathHandler?, string?)`	Waits to make an empty file of that name in this folder; it refuses a name that exists and a folder that doesn't.
CreateSubFolderAsync yields	`(name: string)`	`(PathHandler?, string?)`	Waits to make a folder of that name inside this one; nil and "it exists already" when something has the name.
ExistsAsync yields	`()`	`boolean`	Waits to look whether a file or a folder is at the path.
FindFirstChildAsync yields	`(name: string)`	`(PathHandler?, string?)`	Waits to find that exact name in this folder; nil alone when it isn't there, nil and why when the folder can't be read.
GetFileTypeAsync yields	`()`	`"File" \| "Folder" \| "None"`	Waits to look what is at the path: "File", "Folder", or "None" when nothing is there.
GetNameAndExtension	`()`	`(string, string?)`	Splits BaseName at its first dot: archive.tar.gz gives archive and tar.gz, and a name without a dot gives nil.
GetParent	`()`	`PathHandler?`	The folder above as a PathHandler, without touching the disk; nil for a drive alone or a bare name.
IsFileAsync yields	`()`	`boolean`	Waits to look whether the path is a file; false for a folder or for nothing there.
IsFolderAsync yields	`()`	`boolean`	Waits to look whether the path is a folder; false for a file or for nothing there.
Join	`(...: string)`	`PathHandler`	A PathHandler for a path below this one, one part per argument, without touching the disk; an empty part errors.
ListDirAsync yields	`()`	`({ [string]: PathHandler }?, string?)`	Waits to list this folder as a table from each entry's name to its PathHandler; nil and why when it can't be read.
MoveIntoAsync yields	`(targetParent: PathHandler, newName: string?)`	`(PathHandler?, string?)`	Waits to move this file or folder into targetParent, under newName if given; across drives it copies, then recycles the original.
OpenAsync yields	`()`	`(FileHandler?, string?)`	Waits to open the file as a FileHandler, making a missing one empty with the folders above; a folder is refused.
OverwriteAsync yields	`(content: string \| buffer)`	`(boolean, string?)`	Waits to replace the whole file with content, a string or a buffer, making it and the folders above when missing.
ReadBufferAsync yields	`()`	`(buffer?, string?)`	Waits to read the whole file into a buffer, for bytes rather than text; nil and why when it can't.
ReadStringAsync yields	`()`	`(string?, string?)`	Waits to read the whole file as a string; nil and why, such as "no such file", when it can't.
RecycleAsync yields	`()`	`(RecycledItem?, string?)`	Waits to move the file or folder into a .ShotRecycleBin folder on its own drive, giving a RecycledItem to restore or delete it.
WriteChildAsync yields	`(name: string, content: string \| buffer)`	`(boolean, string?)`	Waits to write content as the file of that name in this folder, replacing it and making missing folders on the way.

From ShotInstance 33