(This part is extremely speculative. It's beginning to use Starlark as an example of what we might want to see in an "L3+" system. The goal in this doc isn't necessarily working stuff or committing to details, it's just to dream about what good composition would look like.)

((UPDATE: Work started on — this should provide a very useful binding library that, combined with our existing schemas, should make massive amounts of things “just work”.)



(A working title for "a snippet of starlark which patches a warpforge plot document".)

Traits of a good Larksnip

A good larksnip should be applicable to a plot as a patch, and it should be commutative with other well-behaved larksnips.

In essense, that is always reached if it's a patch that A) doesn't look at what it's about to patch (!) and thereby doesn't change behavior based on what's come before and B) doesn't collide with anything.

(That Part B criteria would be really tricky... if we didn't have content-addressing providing a natural conflict avoidance mechanism. But we do have it! Sweet.)

What about things that don't fit that model?

How should one deal with noncommutable things?

For example, $PATH. Appending path — like any string append — is not commutative. It's order sensitive.

Okay, then there are two options:

Using Libraries

Larksnips wouldn't be very useful if you couldn't refer to libraries of them that get common work done.

The "standard library"

There's almost nothing in the "standard library".

Just the Plot and Formula and suchlike built-in types.

And the PlotPatch function, which takes a bunch of functions that

Using other libraries

🚧 Very unclear how this should work.

Almost certainly, the libraries are allowed to exist in parent workspaces.

(There wouldn't be much practical value in boilerplate reduction provided if this wasn't allowed!)

(If working in a team, you'll want to track the libraries in the parent workspace that the team shares for all the teams projects.)


🚧 Needs definition, badly.

The catalog is probably an input.

Are parent catalogs searchable? Yeah, a handle to that seems reasonable. Maybe.

I don't think ingesting during the lark evaluation is allowed. No.

Are lark libraries an input? No idea.

// In general this should probably feel a fair bit like "go generate". It can be looser with its inputs than our systems otherwise can be. That's acceptable purely because we're committing the outputs.


See Review Starlark for an L3+ language.

import typicalbase from zomg/foo
import addStrace from yonder/larksnips

PlotPatch( # takes varargs, and applies them sequentially.
	typicalbase, # a document.  If you don't start the stack with a doc, it's zero.
	addStrace, # a `func(plot):plot` that adds an strace ware to the apps folder.

# stdlib: 1.11
# filesystem: allowed
somefunc = load("libzow:15") # these would be looked up in catalogs, I guess?

	name = "",
	plot = PlotPatch(....)


Is any of this, frankly, a good idea? Unclear. The one critical scorecard row is "are we every going to feel a desire to template lark files", and the answer to that must be "no".

Should a lark be stuck emitting just one plot and module? Probably not.

^ See Path Golgi — larks should definitely be able to emit multiple modules.

Does the above imply that splitting plots and modules might've been a mistake? Yes quite possibly.

If a plot is generated, will there be a reliable way to remember (in the same workspaces as the generation was originally performed in, at least) what lark did so? I certainly hope so; we will want this info for any refreshing purposes as well as for GC if a lark eval doesn't generate a module this time.