starlark

package
v0.1.0-dev.20260206221031 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 6, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package starlark provides the Starlark runtime and host bindings for lore.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func FillSlot 

func FillSlot(node *execution.Node, graph *execution.Graph, slotName string, value starlark.Value) error

FillSlot fills a slot in a node from a Starlark value.

Any slot accepts:

  • A promise (Output): creates an edge, value flows at runtime
  • A gather (Gather): creates edges from all members (parallel execution)
  • An immediate value: stored directly, known at analysis time

Types

type ArchivePlan 

type ArchivePlan struct {
	// contains filtered or unexported fields
}

ArchivePlan implements plan.archive.* bindings using the slot-based model.

func NewArchivePlan 

func NewArchivePlan(graph *execution.Graph, h host.Host, project string) *ArchivePlan

NewArchivePlan creates a new ArchivePlan for the given graph and host.

func (*ArchivePlan) Attr 

func (a *ArchivePlan) Attr(name string) (starlark.Value, error)

Starlark HasAttrs interface

func (*ArchivePlan) AttrNames 

func (a *ArchivePlan) AttrNames() []string

func (*ArchivePlan) Freeze 

func (a *ArchivePlan) Freeze()

func (*ArchivePlan) Hash 

func (a *ArchivePlan) Hash() (uint32, error)

func (*ArchivePlan) String 

func (a *ArchivePlan) String() string

Starlark Value interface

func (*ArchivePlan) Truth 

func (a *ArchivePlan) Truth() starlark.Bool

func (*ArchivePlan) Type 

func (a *ArchivePlan) Type() string

type Bindings 

type Bindings struct {
	// contains filtered or unexported fields
}

Bindings provides lore's host API to Starlark scripts.

func NewBindings 

func NewBindings(features []string, settings map[string]string, output io.Writer) *Bindings

NewBindings creates a new Bindings instance.

func (*Bindings) Globals 

func (b *Bindings) Globals() starlark.StringDict

Globals returns the predeclared globals for Starlark scripts.

func (*Bindings) UpdateFeatures 

func (b *Bindings) UpdateFeatures(features []string)

UpdateFeatures allows changing features after creation.

func (*Bindings) UpdateSettings 

func (b *Bindings) UpdateSettings(settings map[string]string)

UpdateSettings allows changing settings after creation.

type DockerBindings 

type DockerBindings struct {
	// contains filtered or unexported fields
}

DockerBindings provides the docker.* API to Starlark scripts.

Uses kwargs pass-through: any keyword argument is converted to a CLI flag. This means all docker flags work automatically without explicit binding code.

Example: 

docker.run("nginx", detach=True, name="web", publish=["80:80"])
# Executes: docker run --detach --name web --publish 80:80 nginx

func NewDockerBindings 

func NewDockerBindings(b *Bindings) *DockerBindings

NewDockerBindings creates docker bindings attached to the parent bindings.

func (*DockerBindings) Struct 

func (d *DockerBindings) Struct() *starlarkstruct.Struct

Struct returns the docker.* namespace for Starlark.

type FilePlan 

type FilePlan struct {
	// contains filtered or unexported fields
}

FilePlan implements plan.file.* bindings using the slot-based model. Each method adds a node to the execution graph.

Slots can be filled with either: - Immediate values (strings known at analysis time) - Promises (Output handles that create edges)

func NewFilePlan 

func NewFilePlan(graph *execution.Graph, h host.Host, project string) *FilePlan

NewFilePlan creates a new FilePlan for the given graph and host.

func (*FilePlan) Attr 

func (f *FilePlan) Attr(name string) (starlark.Value, error)

Starlark HasAttrs interface

func (*FilePlan) AttrNames 

func (f *FilePlan) AttrNames() []string

func (*FilePlan) Freeze 

func (f *FilePlan) Freeze()

func (*FilePlan) Hash 

func (f *FilePlan) Hash() (uint32, error)

func (*FilePlan) String 

func (f *FilePlan) String() string

Starlark Value interface

func (*FilePlan) Truth 

func (f *FilePlan) Truth() starlark.Bool

func (*FilePlan) Type 

func (f *FilePlan) Type() string

type Gather 

type Gather struct {
	// contains filtered or unexported fields
}

Gather represents a collection of outputs that can run in parallel. When used as a slot input, it creates edges from ALL members to the consumer, enabling parallel execution of the gathered nodes.

Usage in Starlark: 

a = plan.file.copy(src1, dst1)
b = plan.file.copy(src2, dst2)
c = plan.file.copy(src3, dst3)
group = plan.gather(a, b, c)
d = plan.whatever(group)  # d waits for a, b, c (which run in parallel)

func NewGather 

func NewGather(graph *execution.Graph, outputs ...*Output) *Gather

NewGather creates a new Gather from multiple outputs.

func (*Gather) FillSlot 

func (g *Gather) FillSlot(consumer *execution.Node, slotName string)

FillSlot fills a slot in the consumer node with all gathered promises, creating edges from each member. This enables parallel execution.

func (*Gather) Freeze 

func (g *Gather) Freeze()

func (*Gather) Hash 

func (g *Gather) Hash() (uint32, error)

func (*Gather) Outputs 

func (g *Gather) Outputs() []*Output

Outputs returns the gathered outputs.

func (*Gather) String 

func (g *Gather) String() string

Starlark Value interface

func (*Gather) Truth 

func (g *Gather) Truth() starlark.Bool

func (*Gather) Type 

func (g *Gather) Type() string

type GitBindings 

type GitBindings struct {
	// contains filtered or unexported fields
}

GitBindings provides the git.* API to Starlark scripts.

Uses kwargs pass-through: any keyword argument is converted to a CLI flag. This means all git flags work automatically without explicit binding code.

Example: 

git.clone("https://github.com/user/repo", depth=1, branch="main")
# Executes: git clone --depth 1 --branch main https://github.com/user/repo

func NewGitBindings 

func NewGitBindings(b *Bindings) *GitBindings

NewGitBindings creates git bindings attached to the parent bindings.

func (*GitBindings) Struct 

func (g *GitBindings) Struct() *starlarkstruct.Struct

Struct returns the git.* namespace for Starlark.

type GitPlan 

type GitPlan struct {
	// contains filtered or unexported fields
}

GitPlan implements plan.git.* bindings using the slot-based model.

func NewGitPlan 

func NewGitPlan(graph *execution.Graph, h host.Host, project string) *GitPlan

NewGitPlan creates a new GitPlan for the given graph and host.

func (*GitPlan) Attr 

func (g *GitPlan) Attr(name string) (starlark.Value, error)

Starlark HasAttrs interface

func (*GitPlan) AttrNames 

func (g *GitPlan) AttrNames() []string

func (*GitPlan) Freeze 

func (g *GitPlan) Freeze()

func (*GitPlan) Hash 

func (g *GitPlan) Hash() (uint32, error)

func (*GitPlan) String 

func (g *GitPlan) String() string

Starlark Value interface

func (*GitPlan) Truth 

func (g *GitPlan) Truth() starlark.Bool

func (*GitPlan) Type 

func (g *GitPlan) Type() string

type NpmBindings 

type NpmBindings struct {
	// contains filtered or unexported fields
}

NpmBindings provides the npm.* API to Starlark scripts.

Uses kwargs pass-through: any keyword argument is converted to a CLI flag. This means all npm flags work automatically without explicit binding code.

Example: 

npm.install("astro", "tailwind", global=True, save_dev=True)
# Executes: npm install --global --save-dev astro tailwind

func NewNpmBindings 

func NewNpmBindings(b *Bindings) *NpmBindings

NewNpmBindings creates npm bindings attached to the parent bindings.

func (*NpmBindings) Struct 

func (n *NpmBindings) Struct() *starlarkstruct.Struct

Struct returns the npm.* namespace for Starlark.

type Output 

type Output struct {
	// contains filtered or unexported fields
}

Output represents a promise - a handle to a node's output that can flow through the graph to fill slots in other nodes.

When passed to a plan function's slot, it creates an edge in the graph. The same promise can flow to multiple slots (fan-out).

func NewOutput 

func NewOutput(node *execution.Node, graph *execution.Graph, slot string) *Output

NewOutput creates a new Output (promise) representing a node's output.

func ResolveInput 

func ResolveInput(value starlark.Value) (*Output, error)

ResolveInput extracts an *Output from a Starlark value. Returns an error if the value is not an Output.

func (*Output) Attr 

func (o *Output) Attr(name string) (starlark.Value, error)

Starlark HasAttrs interface

func (*Output) AttrNames 

func (o *Output) AttrNames() []string

func (*Output) DependOn 

func (o *Output) DependOn(consumer *execution.Node)

DependOn creates an edge making the given node depend on this output's node.

func (*Output) FillSlot 

func (o *Output) FillSlot(consumer *execution.Node, slotName string)

FillSlot fills a slot in the consumer node with this promise, creating an edge. This is called when a promise is passed to a plan function.

func (*Output) Freeze 

func (o *Output) Freeze()

func (*Output) Graph 

func (o *Output) Graph() *execution.Graph

Graph returns the execution graph.

func (*Output) Hash 

func (o *Output) Hash() (uint32, error)

func (*Output) Node 

func (o *Output) Node() *execution.Node

Node returns the execution node that produces this output.

func (*Output) Path 

func (o *Output) Path() string

Path returns a path from the node's slots.

func (*Output) Slot 

func (o *Output) Slot() string

Slot returns which output slot this represents.

func (*Output) String 

func (o *Output) String() string

Starlark Value interface

func (*Output) Truth 

func (o *Output) Truth() starlark.Bool

func (*Output) Type 

func (o *Output) Type() string

type PackageContext 

type PackageContext struct {
	// Name is the package name being deployed.
	Name string

	// Version is the version being deployed.
	Version string

	// Features are the enabled feature flags for this deployment.
	Features []string

	// Settings are key-value configuration settings.
	Settings map[string]string

	// DryRun indicates this is a preview (no actual changes).
	DryRun bool

	// SourceRoot is the package source directory in the registry cache.
	SourceRoot string

	// TargetRoot is the deployment target directory (usually $HOME).
	TargetRoot string
}

PackageContext provides information about the package being deployed. Passed to phase scripts as the second argument.

func (*PackageContext) HasFeature 

func (p *PackageContext) HasFeature(name string) bool

HasFeature checks if a feature is enabled.

func (*PackageContext) Setting 

func (p *PackageContext) Setting(key string) string

Setting returns a setting value, or empty string if not set.

func (*PackageContext) ToStarlark 

func (p *PackageContext) ToStarlark() starlark.Value

ToStarlark converts the PackageContext to a Starlark struct. Exposed to phase scripts as the second argument.

Starlark API: 

package.name        # string: package name
package.version     # string: package version
package.features    # list[string]: enabled features
package.settings    # dict[string, string]: key-value settings
package.dry_run     # bool: true if this is a preview
package.source_root # string: package source directory
package.target_root # string: deployment target directory
package.has_feature(name)  # bool: check if feature is enabled
package.setting(key, default="")  # string: get setting value

type PackagePlan 

type PackagePlan struct {
	// contains filtered or unexported fields
}

PackagePlan implements plan.package.* bindings using the slot-based model. Each method adds a node to the execution graph.

func NewPackagePlan 

func NewPackagePlan(graph *execution.Graph, h host.Host, project string) *PackagePlan

NewPackagePlan creates a new PackagePlan for the given graph and host.

func (*PackagePlan) Attr 

func (p *PackagePlan) Attr(name string) (starlark.Value, error)

Starlark HasAttrs interface

func (*PackagePlan) AttrNames 

func (p *PackagePlan) AttrNames() []string

func (*PackagePlan) Freeze 

func (p *PackagePlan) Freeze()

func (*PackagePlan) Hash 

func (p *PackagePlan) Hash() (uint32, error)

func (*PackagePlan) String 

func (p *PackagePlan) String() string

Starlark Value interface

func (*PackagePlan) Truth 

func (p *PackagePlan) Truth() starlark.Bool

func (*PackagePlan) Type 

func (p *PackagePlan) Type() string

type PackageQueries 

type PackageQueries interface {
	// Installed checks if a package is installed.
	Installed(name string) bool

	// Version returns the installed version of a package, or empty string if not installed.
	Version(name string) string
}

PackageQueries provides read-only package manager queries.

type PlanBindings 

type PlanBindings interface {
	// Graph returns the underlying execution graph being built.
	Graph() *execution.Graph

	// Host returns the host abstraction for path expansion, etc.
	Host() host.Host

	// Project returns the project name for grouping nodes.
	Project() string

	// PackageInstall adds a package installation node.
	PackageInstall(packages ...string) *execution.Node

	// PackageUpgrade adds a package upgrade node.
	PackageUpgrade(packages ...string) *execution.Node

	// PackageRemove adds a package removal node.
	PackageRemove(packages ...string) *execution.Node

	// PackageUpdate adds a package index update node.
	PackageUpdate() *execution.Node

	// Configure adds a configuration file node (template expansion + copy).
	Configure(source, target string) *execution.Node

	// Link adds a symlink creation node.
	Link(source, target string) *execution.Node

	// Copy adds a file copy node.
	Copy(source, target string) *execution.Node

	// Write adds a file write node (write content directly to target).
	Write(target, content string) *execution.Node

	// Remove adds a file/directory removal node.
	Remove(target string) *execution.Node

	// Download adds a file download node.
	Download(url, target string) *execution.Node

	// ArchiveExtract adds an archive extraction node.
	ArchiveExtract(archive, target string) *execution.Node

	// GitClone adds a git clone node.
	GitClone(url, target string) *execution.Node

	// GitCheckout adds a git checkout node.
	GitCheckout(ref string) *execution.Node

	// GitPull adds a git pull node.
	GitPull() *execution.Node

	// Service adds a service management node.
	Service(name string, action ServiceAction) *execution.Node

	// Shell adds a shell command execution node.
	Shell(command string) *execution.Node

	// DependsOn creates a dependency edge between nodes.
	// The 'from' node will execute after the 'to' node completes.
	DependsOn(from, to *execution.Node)
}

PlanBindings provides operations that add nodes to the execution graph. Each method returns the created node for chaining or dependency specification.

Note: Go method names are simple (Install, Remove, etc.) while Starlark uses nested structs (plan.package.install, plan.file.copy) and engine operations use namespaced names (package-install, package-remove).

func NewPlanBindings 

func NewPlanBindings(graph *execution.Graph, h host.Host, project string) PlanBindings

NewPlanBindings creates a new PlanBindings for the given graph and host.

type PlanRoot 

type PlanRoot struct {
	// contains filtered or unexported fields
}

PlanRoot implements the top-level plan namespace using the slot-based model. It provides access to sub-namespaces (package, file, archive, git) and top-level bindings (source, literal, download, service, shell, depends_on).

func NewPlanRoot 

func NewPlanRoot(graph *execution.Graph, h host.Host, project string) *PlanRoot

NewPlanRoot creates a new PlanRoot for the given graph and host.

func (*PlanRoot) Attr 

func (p *PlanRoot) Attr(name string) (starlark.Value, error)

Starlark HasAttrs interface

func (*PlanRoot) AttrNames 

func (p *PlanRoot) AttrNames() []string

func (*PlanRoot) Freeze 

func (p *PlanRoot) Freeze()

func (*PlanRoot) Hash 

func (p *PlanRoot) Hash() (uint32, error)

func (*PlanRoot) String 

func (p *PlanRoot) String() string

Starlark Value interface

func (*PlanRoot) Truth 

func (p *PlanRoot) Truth() starlark.Bool

func (*PlanRoot) Type 

func (p *PlanRoot) Type() string

type ServiceAction 

type ServiceAction int

ServiceAction represents a service management action. 

const (
	// ServiceStart starts a service.
	ServiceStart ServiceAction = iota
	// ServiceStop stops a service.
	ServiceStop
	// ServiceRestart restarts a service.
	ServiceRestart
	// ServiceEnable enables a service at boot.
	ServiceEnable
	// ServiceDisable disables a service at boot.
	ServiceDisable
)

func (ServiceAction) String 

func (a ServiceAction) String() string

String returns the action name.

type ServiceQueries 

type ServiceQueries interface {
	// Exists checks if a service exists.
	Exists(name string) bool

	// Running checks if a service is currently running.
	Running(name string) bool

	// Enabled checks if a service is enabled at boot.
	Enabled(name string) bool
}

ServiceQueries provides read-only service manager queries.

type StarlarkPlanBindings 

type StarlarkPlanBindings struct {
	PlanBindings
}

StarlarkPlanBindings wraps PlanBindings for Starlark conversion.

func (*StarlarkPlanBindings) ToStarlark 

func (s *StarlarkPlanBindings) ToStarlark() starlark.Value

ToStarlark converts the plan bindings to a Starlark value. Exposed to phase scripts as the third argument.

All namespaces use the Attr receiver pattern for consistency and static analysis support. Starlark API: 

plan.package.install("pkg1", "pkg2", ...)  # Install packages
plan.package.upgrade("pkg1", ...)          # Upgrade packages
plan.package.remove("pkg1", ...)           # Remove packages
plan.package.update()                      # Update package index
plan.file.configure(source, target)        # Configure file (template + copy)
plan.file.link(source, target)             # Create symlink
plan.file.copy(source, target)             # Copy file
plan.file.write(target, content)           # Write content to file
plan.file.remove(target)                   # Remove file/directory
plan.archive.extract(archive, prefix)      # Extract archive
plan.git.clone(url, path)                  # Clone repository
plan.git.checkout(repo, ref)               # Checkout ref
plan.git.pull(repo)                        # Pull changes
plan.source(path)                          # Declare source file
plan.literal(content)                      # Inline content
plan.download(url)                         # Download file
plan.service(name, action)                 # Manage service
plan.shell(command)                        # Run shell command
plan.depends_on(consumer, producer)        # Create dependency

type SystemBindings 

type SystemBindings interface {
	// Platform returns information about the current system.
	Platform() host.Platform

	// Package provides package manager queries.
	Package() PackageQueries

	// Service provides service manager queries.
	Service() ServiceQueries

	// ToStarlark converts the system bindings to a Starlark value.
	ToStarlark() starlark.Value
}

SystemBindings provides read-only queries about the current platform state. Wraps host.Host to expose platform information to phase scripts.

func NewSystemBindings 

func NewSystemBindings(h host.Host) SystemBindings

NewSystemBindings creates a new SystemBindings from a host.Host.

type SystemFile 

type SystemFile struct {
	// contains filtered or unexported fields
}

SystemFile implements system.file.* bindings for filesystem queries. These are immediate queries - they execute during analysis, not deferred.

func NewSystemFile 

func NewSystemFile(h host.Host) *SystemFile

NewSystemFile creates a new SystemFile for the given host.

func (*SystemFile) Attr 

func (f *SystemFile) Attr(name string) (starlark.Value, error)

Starlark HasAttrs interface

func (*SystemFile) AttrNames 

func (f *SystemFile) AttrNames() []string

func (*SystemFile) Freeze 

func (f *SystemFile) Freeze()

func (*SystemFile) Hash 

func (f *SystemFile) Hash() (uint32, error)

func (*SystemFile) String 

func (f *SystemFile) String() string

Starlark Value interface

func (*SystemFile) Truth 

func (f *SystemFile) Truth() starlark.Bool

func (*SystemFile) Type 

func (f *SystemFile) Type() string

type SystemGit 

type SystemGit struct{}

SystemGit implements system.git.* bindings for git queries. These are immediate queries - they execute during analysis, not deferred.

func NewSystemGit 

func NewSystemGit() *SystemGit

NewSystemGit creates a new SystemGit.

func (*SystemGit) Attr 

func (g *SystemGit) Attr(name string) (starlark.Value, error)

Starlark HasAttrs interface

func (*SystemGit) AttrNames 

func (g *SystemGit) AttrNames() []string

func (*SystemGit) Freeze 

func (g *SystemGit) Freeze()

func (*SystemGit) Hash 

func (g *SystemGit) Hash() (uint32, error)

func (*SystemGit) String 

func (g *SystemGit) String() string

Starlark Value interface

func (*SystemGit) Truth 

func (g *SystemGit) Truth() starlark.Bool

func (*SystemGit) Type 

func (g *SystemGit) Type() string

type SystemPackage 

type SystemPackage struct {
	// contains filtered or unexported fields
}

SystemPackage implements system.package.* bindings for package manager queries. These are immediate queries - they execute during analysis, not deferred.

func NewSystemPackage 

func NewSystemPackage(pm host.PackageManager) *SystemPackage

NewSystemPackage creates a new SystemPackage for the given package manager.

func (*SystemPackage) Attr 

func (p *SystemPackage) Attr(name string) (starlark.Value, error)

Starlark HasAttrs interface

func (*SystemPackage) AttrNames 

func (p *SystemPackage) AttrNames() []string

func (*SystemPackage) Freeze 

func (p *SystemPackage) Freeze()

func (*SystemPackage) Hash 

func (p *SystemPackage) Hash() (uint32, error)

func (*SystemPackage) String 

func (p *SystemPackage) String() string

Starlark Value interface

func (*SystemPackage) Truth 

func (p *SystemPackage) Truth() starlark.Bool

func (*SystemPackage) Type 

func (p *SystemPackage) Type() string

type SystemRoot 

type SystemRoot struct {
	// contains filtered or unexported fields
}

SystemRoot implements the top-level system namespace using the Attr receiver pattern. It provides access to sub-namespaces (package, service, git, file) and the platform struct.

Unlike plan.*, system.* bindings query current system state immediately rather than building an execution graph.

func NewSystemRoot 

func NewSystemRoot(h host.Host) *SystemRoot

NewSystemRoot creates a new SystemRoot for the given host.

func (*SystemRoot) Attr 

func (s *SystemRoot) Attr(name string) (starlark.Value, error)

Starlark HasAttrs interface

func (*SystemRoot) AttrNames 

func (s *SystemRoot) AttrNames() []string

func (*SystemRoot) Freeze 

func (s *SystemRoot) Freeze()

func (*SystemRoot) Hash 

func (s *SystemRoot) Hash() (uint32, error)

func (*SystemRoot) String 

func (s *SystemRoot) String() string

Starlark Value interface

func (*SystemRoot) Truth 

func (s *SystemRoot) Truth() starlark.Bool

func (*SystemRoot) Type 

func (s *SystemRoot) Type() string

type SystemService 

type SystemService struct {
	// contains filtered or unexported fields
}

SystemService implements system.service.* bindings for service manager queries. These are immediate queries - they execute during analysis, not deferred.

func NewSystemService 

func NewSystemService(sm host.ServiceManager) *SystemService

NewSystemService creates a new SystemService for the given service manager.

func (*SystemService) Attr 

func (s *SystemService) Attr(name string) (starlark.Value, error)

Starlark HasAttrs interface

func (*SystemService) AttrNames 

func (s *SystemService) AttrNames() []string

func (*SystemService) Freeze 

func (s *SystemService) Freeze()

func (*SystemService) Hash 

func (s *SystemService) Hash() (uint32, error)

func (*SystemService) String 

func (s *SystemService) String() string

Starlark Value interface

func (*SystemService) Truth 

func (s *SystemService) Truth() starlark.Bool

func (*SystemService) Type 

func (s *SystemService) Type() string

Source Files

View all Source files

Directories

Path Synopsis
Package platform provides platform-specific plan bindings for the Starlark runtime.
 Package platform provides platform-specific plan bindings for the Starlark runtime.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.