Autoloading

shed ships with a library of shell functions and command completions, but rather than defining them all up front, it loads each one lazily, the first time you actually use it. The same mechanism is open to you: drop your own function or completion files into a directory, point an environment variable at it, and they become available exactly like the bundled ones.

Three kinds of resource autoload this way, each with its own search path:

Resource	Search path	Loaded when
Functions	SHED_FUNC_PATH	the function is first called
Completions	SHED_COMPLETE_PATH	you first tab-complete that command
Help pages	SHED_HPATH	you first help that topic

Each path is a :-separated list of directories, just like PATH, but holding shell scripts rather than executables.

How names resolve

Within a search-path directory, a file's stem (its name with any extension removed) is the name it registers under. greet.sh registers as greet; a file named git with no extension registers as git.

Autoloadable names come from two sources: the set bundled into the shed binary, and your search-path directories. If one of your files has a stem matching a bundled name, your file overrides the bundled definition. Any other file simply adds a new name alongside the bundled set. This lets you replace a shipped function with your own version, or grow the library with new ones, without touching shed itself.

Functions

SHED_FUNC_PATH lists directories of function files. At startup, every file becomes an autoloadable function named after its stem, but its body is not read until the function is first called. Until then it is just a registered name.

mkdir -p ~/.shed/func
echo 'greet() { echo "hello, $1"; }' > ~/.shed/func/greet.sh
export SHED_FUNC_PATH=$HOME/.shed/func

greet world       # sources greet.sh, then runs greet -> "hello, world"

Inspecting a function with declare -f also forces it to load, so it doubles as a way to preview an autoloaded body without running it:

declare -f split   # loads the bundled `split` function, then prints its source

The functions bundled with shed are listed under help functions, and reading their source with declare -f is a good way to pick up idiomatic shed scripting. For the language reference on writing your own, see shed Scripting Features.

Completions

SHED_COMPLETE_PATH lists directories of completion files. Here a file's stem is a command name, and the file is sourced the first time you request completion for that command. Typically the file calls the complete builtin to register a completion spec, which then drives the results:

mkdir -p ~/.shed/complete
echo "complete -W 'staging production canary' deploy" > ~/.shed/complete/deploy.sh
export SHED_COMPLETE_PATH=$HOME/.shed/complete

deploy <Tab>       # sources deploy.sh on first use, then offers the three words

The -W form above completes from a static word list, but a completion file can register any spec complete supports. The bundled completions favor the dynamic -F {func} form, where a helper function populates candidates on each request — for example, alias.sh is just:

_alias_comp() { compadd -D 'alias' $(compgen -a -- "$2"); }
complete -F _alias_comp alias

Nothing is loaded for commands you never complete, so a large completion library costs nothing until it is used.

Help pages

Help topics autoload the same way through SHED_HPATH. Because help pages are plain documentation rather than shell code they get their own treatment in Interactive Documentation, but the model is identical: a :-separated path of directories, searched by filename stem, overriding or extending the bundled pages.

When changes take effect

The autoload sets for functions and completions are collected once, when a shell starts. New files you add to a search-path directory are picked up by the next shell you launch; a shell that is already running keeps the set it loaded at startup. (Help pages are re-scanned on each help invocation, so new help files show up right away.)