FileService

Read, write, list, copy, move and follow the files and folders on this computer, from any program.

Write use FileService in a .shot file. Paths are the computer's, with / or \, and a relative one starts at the project file's folder. Every member that touches the disk ends in Async and waits; a failure gives nil or false and one line of why, such as ReadAsync notes/todo.txt: no such file. Calls on one path take turns in the order they were made. GetPathHandler gives the object form, a PathHandler. See paths.

ShotInstanceservicenot creatableFiles

A service: write use FileService.

Example

Write, read and listShotScript

-- Writes a to-do list in a folder of its own, adds to it, reads it back, lists the folder and removes it.
use FileService
local todo = "Notes/todo.txt"
FileService:WriteAsync(todo, "buy milk")
FileService:AppendAsync(todo, ", call home")
print("todo.txt: " .. tostring((FileService:ReadAsync(todo))))
local size = FileService:SizeAsync(todo)
print("its size: " .. tostring(size) .. " bytes")
local rest = FileService:ReadFromAsync(todo, 10)
print("after the first 10 bytes: " .. tostring(rest))

FileService:CopyAsync(todo, "Notes/todo-copy.txt")
local entries : {FileEntry} = FileService:ListAsync("Notes") or {}
for _, entry in entries do
	print((if entry.IsFolder then "folder " else "file ") .. entry.Name)
end
local missing, why = FileService:ReadAsync("Notes/nothing.txt")
print("a missing file: " .. tostring(missing) .. ", " .. tostring(why))
FileService:RemoveAsync("Notes")
print("Notes after RemoveAsync: " .. tostring(FileService:ExistsAsync("Notes")))

What it printedOutput

todo.txt: buy milk, call home
its size: 19 bytes
after the first 10 bytes: call home
file todo-copy.txt
file todo.txt
a missing file: nil, ReadAsync Notes/nothing.txt: no such file
Notes after RemoveAsync: false

Methods

Name	Arguments	Returns	Description
AppendAsync yields	`(path: string, text: string)`	`(boolean, string?)`	Waits to add text at the file's end, making a missing file; calls on one path take turns, so appends keep their order.
CopyAsync yields	`(from: string, to: string, overwrite: boolean?)`	`(boolean, string?)`	Waits to copy a file, or a folder with everything in it; an existing target is replaced only when overwrite is true.
ExistsAsync yields	`(path: string)`	`boolean`	Waits to look whether a file or a folder is at the path.
Follow	`(path: string, offset: number?, interval: number?)`	`Follow`	Starts following a file without waiting: a Follow that hands over added text; offset nil starts at the end, 0 at the start.
GetPathHandler	`(path: string)`	`PathHandler`	A PathHandler for the path, without touching the disk; backslashes become forward slashes, and an empty path errors.
IsFolderAsync yields	`(path: string)`	`boolean`	Waits to look whether the path is a folder; false for a file or for nothing there.
ListAsync yields	`(path: string)`	`({ FileEntry }?, string?)`	Waits to list a folder's entries, sorted by name, each with Name, IsFolder and Modified in seconds since 1970; nil and why on failure.
MakeFolderAsync yields	`(path: string)`	`(boolean, string?)`	Waits to make a folder and any missing folders above it; a folder that exists already is fine.
MoveAsync yields	`(from: string, to: string, overwrite: boolean?)`	`(boolean, string?)`	Waits to move or rename a file or folder; an existing target is replaced only when overwrite is true.
ReadAsync yields	`(path: string)`	`(string?, string?)`	Waits to read a whole file as text; nil and why, such as "no such file", when it can't.
ReadFromAsync yields	`(path: string, offset: number)`	`(string?, string?)`	Waits to read the text after offset bytes, 0 giving all of it; nil and why when the file is now shorter than offset.
RemoveAsync yields	`(path: string)`	`(boolean, string?)`	Waits to remove a file, or a folder with everything in it; a missing path gives false and why.
SizeAsync yields	`(path: string)`	`(number?, string?)`	Waits for the file's size in bytes; today it reads the whole file to find it.
WriteAsync yields	`(path: string, text: string)`	`(boolean, string?)`	Waits to replace a file's text, making the file and any missing folders above it.

From ShotInstance 33