Function projects

Place principal.sun and sun-project.json in a project folder, then place calibrate.sun inside a functions subfolder. A call to calibrate loads its definition without first executing the helper file as a script. This is function lookup, not an import or package system.

result = calibrate([1, 2, 3], 2, 10);
disp(result);

Save the following as sun-project.json. Paths are ordered, nonrecursive directories relative to the canonical project root. Duplicates are removed; manifest paths and resolved symlinks must remain inside that root.

{
  "version": 1,
  "paths": ["functions"]
}

Save this function as functions/calibrate.sun. An automatically loaded file must contain exactly one function matching its canonical filename and no script statements or additional functions. Malformed, mismatched or unauthorized first candidates report an error instead of falling through to another file.

function result = calibrate(values, gain, offset)
    result = values .* gain + offset;
end

• A same-named array is indexed; other bound values block user-function calls. Explicit built-in calls retain legacy scalar-binding dispatch behavior.
• Registered script/session functions precede built-ins.
• Built-ins precede automatic files; files cannot automatically override them.
• Then search the calling source directory, project root, explicit CLI --path directories and manifest paths, in that order.
• Nested file calls use the loaded function's directory. Registered script functions retain their original source directory when called later.

run/check find the nearest ancestor sun-project.json, up to 64 directories; otherwise they use the source directory. REPL discovery starts from its initial working directory. --project chooses an explicit root and repeatable --path adds directories relative to it, or absolute external directories.

Function lookup does not change the data working directory. CLI CSV paths remain relative to the process cwd; Studio keeps its per-command source/project cwd behavior.

sun run principal.sun --project /path/to/project
sun run principal.sun --project /path/to/project --path utilities
sun repl --project /path/to/project
sun check principal.sun --project /path/to/project

Definitions are cached by canonical path for one execution only. The next command rereads helpers, including edits, deletions and parse failures. Save helper buffers before running; unsaved helper text is not substituted for disk contents. The main editor buffer can still run unsaved.

Automatically loaded functions do not persist as registered session definitions. Changing the project does not clear Workspace or existing registered functions. check validates the requested source, parallel structure and project configuration, not all transitive calls.

Limits: 1 MiB per helper, 256 files and 8 MiB of function source per execution; manifests are limited to 64 KiB and 32 paths, with up to 32 extra CLI paths and 4096 bytes per path.

Open the project folder in Studio so the engine can use its manifest and helpers from scripts, console and Canvas. Opening only one file does not authorize siblings or its parent manifest; open the folder or explicitly grant the needed files. Symlinks escaping granted roots are rejected.

These checks govern function loading, not an OS filesystem sandbox: the CSV host API is a separate facility. A compatible engine must advertise function_files; restart or update older engines.

Loaded sources have versioned path/content identities. Breakpoints verify on load, and stepping displays the helper's actual source and locals. External user calls are not supported in parfor workers or LLVM; a helper may itself contain an otherwise supported parfor.