Documentation
¶
Overview ¶
Package cli provides CLI-specific functions for Duso scripts.
These functions extend the core language with file I/O, environment access, and module loading. They are NOT part of the core language and are only available when using the duso CLI.
Embedded Go applications can optionally register these functions if they wish, or implement their own versions with different behavior.
Package cli provides CLI-specific functions for Duso scripts. This file contains the main registration function.
Package cli provides CLI-specific functions for Duso scripts.
Index ¶
- Variables
- func ClearBusySpinner()
- func EmbeddedDirRead(path string) ([]fs.DirEntry, error)
- func EmbeddedFileRead(path string) ([]byte, error)
- func EmbeddedGlob(pattern string) ([]string, error)
- func EmbeddedStat(path string) (fs.FileInfo, error)
- func ExitCode(fallback int) int
- func ExpandGlob(pattern string) ([]string, error)
- func GetSysFlag[T any](key string, defaultVal T) T
- func LintScript(filename string, source string) ([]*script.LintDiagnostic, error)
- func ListDirVFS(path string) ([]map[string]any, error)
- func NewConsoleDebugHandler(interp *script.Interpreter) script.DebugHandler
- func ReadEmbeddedFile(path string) ([]byte, error)
- func ReadScriptWithFallback(scriptPath string, scriptDir string) ([]byte, error)
- func RegisterCLIBuiltins(resolver *ModuleResolver)
- func RegisterFunctions(interp *script.Interpreter, opts RegisterOptions, stdinServer *StdinHTTPServer) error
- func ResolvePath(p string) string
- func SetEmbeddedFS(fs embed.FS)
- type BusySpinner
- type Evaluator
- type GoFunction
- type ModuleResolver
- type RegisterOptions
- type StdinHTTPServer
- type Value
- type ValueRef
Constants ¶
This section is empty.
Variables ¶
var (
RegisterBuiltin = script.RegisterBuiltin
)
Registry functions
Functions ¶
func ClearBusySpinner ¶
func ClearBusySpinner()
ClearBusySpinner clears any active spinner without the mutex lock Used internally by OutputWriter to auto-clear before printing
func EmbeddedDirRead ¶
EmbeddedDirRead reads a directory from embedded fs with path normalization.
func EmbeddedFileRead ¶
EmbeddedFileRead reads from embedded fs with path normalization. Text assets are gzip-compressed at build time (see cmd/duso/embed); this is the single choke point through which every embedded byte read passes, so inflating here makes compression transparent to all callers. Filenames are unchanged, so ReadDir/Glob/Stat are unaffected.
func EmbeddedGlob ¶
EmbeddedGlob matches files in embedded fs with path normalization.
func EmbeddedStat ¶
EmbeddedStat gets file info from embedded fs with path normalization.
func ExitCode ¶
ExitCode returns the code shutdown() asked for, or fallback if it was never called. The CLI's own exit paths route through this, so a shutdown() from a handler still decides the process's exit status even though the main script finished by other means.
func ExpandGlob ¶
ExpandGlob expands glob patterns for filesystem, /EMBED/, and /STORE/ paths. Returns a list of matching file paths.
func GetSysFlag ¶
GetSysFlag retrieves a flag from the sys datastore with type preservation and default fallback. Usage: GetSysFlag("-no-color", false), GetSysFlag("-v", false), etc. Returns the value from datastore, or defaultVal if not found or type mismatch.
func LintScript ¶
func LintScript(filename string, source string) ([]*script.LintDiagnostic, error)
LintScript analyzes a Duso script and returns diagnostics
func ListDirVFS ¶
ListDirVFS lists directory contents supporting /EMBED/, /STORE/, and regular filesystem. Returns a list of directory entries with {name, is_dir} fields.
func NewConsoleDebugHandler ¶
func NewConsoleDebugHandler(interp *script.Interpreter) script.DebugHandler
NewConsoleDebugHandler creates a debug event handler for console-based debugging. It displays debug information to stderr and opens an interactive REPL for inspection. The interpreter is needed to access the debug session mutex to serialize REPL access.
func ReadEmbeddedFile ¶
ReadEmbeddedFile reads a file from the embedded filesystem. Path should start with /EMBED/ for embedded files.
func ReadScriptWithFallback ¶
ReadScriptWithFallback reads a script file with fallback logic. Tries in order: 1. Local file at the given path 2. /STORE/ virtual filesystem at /STORE/{path} 3. Embedded file at /EMBED/{path} 4. Embedded file at /EMBED/{scriptDir}/{path} (for relative imports)
func RegisterCLIBuiltins ¶
func RegisterCLIBuiltins(resolver *ModuleResolver)
RegisterCLIBuiltins registers CLI-specific builtins to the global script registry.
func RegisterFunctions ¶
func RegisterFunctions(interp *script.Interpreter, opts RegisterOptions, stdinServer *StdinHTTPServer) error
RegisterFunctions registers all CLI-specific functions (load, save, include, require) in the given interpreter.
This is called automatically by the duso CLI in cmd/duso/main.go. Embedded Go applications can optionally call this to enable CLI features, or implement their own versions of these functions.
Provides module loading via: - include(filename): Loads and executes scripts in current scope (variables leak) - require(moduleName): Loads modules in isolated scope (variables isolated, returns exports)
The optional stdinServer parameter enables HTTP stdin/stdout transport. If provided, script input/output is exposed over HTTP instead of the console.
Example (CLI usage - automatic):
// cmd/duso/main.go already calls this for you
interp := script.NewInterpreter(false)
cli.RegisterFunctions(interp, cli.RegisterOptions{ScriptDir: "/path/to/script"}, nil)
Example (embedded usage - optional):
interp := script.NewInterpreter(false)
// Enable file I/O (optional)
cli.RegisterFunctions(interp, cli.RegisterOptions{ScriptDir: "."}, nil)
// Now scripts can use: load(), save(), include(), require()
Example (with HTTP stdin/stdout):
server := cli.NewStdinHTTPServer(9999, "localhost") go server.Start() cli.RegisterFunctions(interp, opts, server)
func ResolvePath ¶
ResolvePath turns a user-supplied path into its concrete form for the underlying file I/O routines. Resolution rules:
/EMBED/... passed through (embedded read-only filesystem) /STORE/... passed through (datastore-backed VFS) /HERE/... rewritten to dir(currentFrame.Filename) + rest /CWD/... rewritten to os.Getwd() + rest /... absolute disk path, returned as-is bare path joined onto the entry-script's appDir
/HERE/ falls back to cwd when there is no current frame (REPL / -c). Bare paths fall back to cwd when no appDir was set.
func SetEmbeddedFS ¶
SetEmbeddedFS sets the embedded filesystem for use by file I/O functions. Called from cmd/duso/main.go during initialization.
Types ¶
type BusySpinner ¶
type BusySpinner struct {
// contains filtered or unexported fields
}
BusySpinner manages a spinning busy cursor
type GoFunction ¶
type GoFunction = script.GoFunction
Type aliases to avoid script. prefix in CLI builtins
type ModuleResolver ¶
type ModuleResolver struct {
ScriptDir string // Directory of the currently executing script
DusoPath []string // Parsed from DUSO_LIB env variable
}
ModuleResolver handles finding module files using the standard search order: 1. User-provided filespec (absolute or ~/...) 2. Relative to script directory 3. DUSO_LIB environment variable directories
func NewModuleResolver ¶
func NewModuleResolver(opts RegisterOptions) *ModuleResolver
NewModuleResolver creates a ModuleResolver from RegisterOptions. This is used internally by RegisterFunctions and can also be used by the CLI to handle doc() lookups before script execution.
func (*ModuleResolver) ResolveModule ¶
func (r *ModuleResolver) ResolveModule(moduleName string) (string, []string, error)
ResolveModule finds a module file using the standard resolution algorithm. Search order: . (current dir) → $DUSO_LIB paths → /EMBED Supports both direct modules (http.du) and directory-based modules (http/http.du). Returns: (resolved absolute path, list of paths searched, error)
type RegisterOptions ¶
type RegisterOptions struct {
ScriptDir string // Directory relative to which files are loaded/saved
}
RegisterOptions configures how CLI functions are registered.
type StdinHTTPServer ¶
type StdinHTTPServer struct {
// contains filtered or unexported fields
}
StdinHTTPServer provides HTTP access to a script's stdin/stdout. It allows remote clients (LLMs, tests, etc.) to: - Read accumulated script output (GET /) - Wait for and provide input to input() calls (GET /input, POST /input)
This is a generic stdin/stdout transport that works for all scripts, not just debug mode. When -stdin-port is specified, the script's stdin/stdout is automatically exposed over HTTP.
func NewStdinHTTPServer ¶
func NewStdinHTTPServer(port int, bind string) *StdinHTTPServer
NewStdinHTTPServer creates a new HTTP stdin/stdout server.
func (*StdinHTTPServer) GetInputReader ¶
func (s *StdinHTTPServer) GetInputReader() func(string) (string, error)
GetInputReader returns a function compatible with interp.InputReader. It reads from the HTTP input channel and blocks waiting for POST /input.
func (*StdinHTTPServer) GetOutputWriter ¶
func (s *StdinHTTPServer) GetOutputWriter() func(string) error
GetOutputWriter returns a function compatible with interp.OutputWriter. It captures output to the HTTP buffer and also writes to stdout (tee pattern). This ensures output is visible in the terminal and can be captured with shell redirection.
func (*StdinHTTPServer) Start ¶
func (s *StdinHTTPServer) Start() error
Start begins listening on the stdin/stdout port. This method blocks until the server is closed.
func (*StdinHTTPServer) Stop ¶
func (s *StdinHTTPServer) Stop() error
Stop shuts down the HTTP server.
Source Files