Require
Extension
ExtensionDescription
Require is a simple class for including code from external .scd files. The simplest usage is via the Require() constructor:
Class Methods
.new
Run code or include an object from an external .scd file.
Required files are cached, so they are guaranteed to be only executed once. For example, if [A] [B] and [C] each includes [D], [D] will only every be executed once (unless the always argument is specified).
Arguments:
| identifier |
A relative or absolute path to a file or directory. Identifiers not starting from a root path are assumed to be relative to the file containing the Require statement. A .scd extension is implicitly included if not specified. Wildcards can be used to include multiple files (see String: -pathMatch). |
Returns:
Return value is the result of executing the file as a function - usually the return value of the last line of code. This can be ignored, or used to return a singleton-like object. For example:
might return a global mixer object specified in mixer.scd. It will return a cached copy unless always:true is specified. If multiple files are Require'd via a wildcard, the return value is an array of the result of executing each file.
.reset
Reset the cache of Require'd objects. This will cause all Require calls to re-load the scd's the next time they are run.
.with
Run a function with several required files. Note that for now, requirements are loaded synchronously, but in the future they maybe loaded asynchronously.
Required files are cached, so they are guaranteed to be only executed once. See Require: -cache.
Arguments:
| ... identifiersAndFunc |
An array of requirement identifiers, with a function as the last argument. Requirements will be looked up as in Require: -new. When all requirements are loaded, the final function argument is called with the requirements as arguments. |
.cache
Specify a caching mode for a require file. Specifying this anywhere in a file that will be Require'd will set the cache key for the file. This will control when the file is re-executed, and when the cached result of the file is used. If multiple arguments are specified, the cache entry for the file will be cleared in all cases. It's best to place a single `Require.cache(...)` entry at the top of your file, for clarity.
Possible attributes are:
/cmdPeriod - file will be re-executed after a CmdPeriod.
/serverBoot - file will be re-executed after a server reboot.
/serverTree - file will be re-executed after a server tree event (cooresponds roughly to CmdPeriod).
/content - file will be re-executed if file content changes.
/evaluate - file will be re-executed each time the user executes code from an IDE via e.g. Cmd+Enter. Simply: if you run code once via Cmd+Enter, a single Require'd file will be executed only once no matter how many times it's Required. If you execute code twice, it will be executed twice, since the cache is cleared on the second code evaluation. This is the default option.
/never - file will be executed again ever time it's Require'd.
Examples
The cache for this file will be cleared when the content of the file changes, or if the server is rebooted. This is useful for server resources like buffers, but may re-load buffers if you change the file.