tecs.watch

Changerecord#

record Change
    path: string
    kind: string
end

One settled content change.

Fields

path: string

kind: string

ChangeHandlertype#

type ChangeHandler = function(change: Change): nil

Receives one settled change.

Configtype#

type Config = {
    intervalSeconds: number?,
    settle: integer?,
    capacity: integer?,
    clock: (function(): number)?,
    source: Source?
}

Settings copied by install.

intervalSeconds sets the delay between polls and defaults to 0.5. settle requires that many extra matching scans after a change is first seen and defaults to 1, so one scan observes and the next confirms; zero queues immediately. capacity bounds distinct pending paths and defaults to 1024. clock reads seconds from a monotonic origin and defaults to nupp.time, and source reads one path's state and defaults to nupp.io.files.info. The last two exist for a test or a headless tool that drives its own time and its own filesystem; a game supplies neither.

Sourcetype#

type Source = function(path: string): (integer, number)

Reads one path's size and modification time.

A path that is missing, or that has become a directory, answers -1, -1 rather than raising: some editors save by renaming a temporary over the target, so a scan landing in the gap has to read that as not settled.

addfunction#

function add(path: string, kind: string?): boolean

Registers a path to watch, and reports whether it was newly registered.

The path's current state becomes the baseline, so a file registered on frame ten does not dispatch on frame eleven. Registering a path already watched moves its kind and leaves its baseline alone, which is what a second loader naming the same file should do.

Registration does not require an installed watcher. A loader registers what it loaded whenever it loads it, and install takes the whole set up.

Arguments

Returns

Raises

• when path is empty

dispatchfunction#

function dispatch(): integer

Runs the registered handlers over every queued change.

Call this once per logical update, at a point the frame has declared. A handler that raises is logged and the batch continues, because one file that is not usable yet says nothing about the next.

Returns

dispatchedfunction#

function dispatched(): integer

Returns how many changes have reached a handler since install.

Returns

forgetfunction#

function forget(path: string): boolean

Stops watching one path and forgets its state.

A change already queued for the path still dispatches, because it settled while the path was watched and a handler that has been promised a reload gets one.

Arguments

Returns

installfunction#

function install(config: Config?): nil

Starts watching, taking every registered path's current state as its baseline.

Changes made before this call do not dispatch, which is what lets a build register paths as it loads them and install once everything is loaded.

Arguments

Returns

Raises

• when settle is negative or capacity is not a positive integer

isInstalledfunction#

function isInstalled(): boolean

Returns whether the watcher is running.

Returns

kindsfunction#

function kinds(): {string}

Returns the content kinds that have a handler, in sorted order.

Returns

onfunction#

function on(kind: string, handler: ChangeHandler?): nil

Registers the handler for a content kind.

Re-registering a kind replaces its handler, and nil removes it. Handlers outlive install and uninstall, so a build that stops and starts watching registers them once.

Arguments

Returns

Raises

• when kind is empty

pendingfunction#

function pending(): integer

Returns how many settled changes are waiting for dispatch.

Returns

pollfunction#

function poll(): integer

Scans when the interval has elapsed, and does nothing otherwise.

This is what a host calls once per turn. It never dispatches, so it is safe anywhere in a turn.

Returns

resetfunction#

function reset(): nil

Forgets every path, handler and queued change, and stops watching.

A test that installs the watcher needs this between cases. A game does not: uninstall already stops the polling and keeps what was registered.

Returns

scanfunction#

function scan(): integer

Looks at every watched path once, whatever the interval says.

Call this directly when a headless tool or a test controls the timing. A change that has now settled is queued rather than dispatched, because the handler runs where the frame says it runs.

Returns

uninstallfunction#

function uninstall(): nil

Stops watching and drops whatever was queued.

Registered paths and handlers survive, so a later install resumes with the same set and takes a fresh baseline.

Returns

unsettledfunction#

function unsettled(): {string}

Returns the watched paths whose latest change has not settled, sorted.

Returns

watchingfunction#

function watching(): {string}

Returns the watched paths, in sorted order.

Returns

DOCUMENTvariable#

const DOCUMENT

Read-only. Names the kind a file registered without one is watched as.

SHADERvariable#

const SHADER

Read-only. Names the kind a shader source is watched as.