eval

package
v1.4.0 Latest Latest
Warning

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

 Go to latest Published: Jul 9, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package eval wraps Nix evaluation states and values.

The package exposes Go-native evaluators, values, builders, and realized strings over the generated pkg/raw expression API. Evaluators own the underlying Nix evaluation state and values are tied to the evaluator that created them.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Evaluator 

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

Evaluator owns a Nix evaluation state.

An Evaluator borrows the Store and Nix context used to create it. The store and context must outlive the evaluator. Evaluator is not goroutine-safe. Values returned by an Evaluator are caller-owned, tied to that evaluator, and must not be used with another evaluator. Callers should close every Value before closing the Evaluator.

func New 

func New(ctx *nixcontext.Context, s *store.Store, opts ...Option) (*Evaluator, error)

New creates an evaluator using an initialized Nix context and open store.

The returned Evaluator owns the raw EvalState and borrows ctx and s. The caller must close the evaluator when finished.

func (*Evaluator) Attr 

func (e *Evaluator) Attr(v *Value, name string) (*Value, error)

Attr returns the caller-owned forced attribute named name.

func (*Evaluator) AttrByIndex 

func (e *Evaluator) AttrByIndex(v *Value, index uint32) (*Value, error)

AttrByIndex returns the caller-owned forced attribute value at index.

func (*Evaluator) AttrLazy 

func (e *Evaluator) AttrLazy(v *Value, name string) (*Value, error)

AttrLazy returns a caller-owned attribute without forcing its value.

func (*Evaluator) AttrName 

func (e *Evaluator) AttrName(v *Value, index uint32) (string, error)

AttrName returns the attribute name at index.

func (*Evaluator) Borrow 

func (e *Evaluator) Borrow() (*raw.EvalState, error)

Borrow returns the borrowed raw Nix evaluation state.

Callers must not free the returned pointer and must not retain it beyond the immediate raw Nix call that needs it. This is an escape hatch for integration with lower-level bindings.

func (*Evaluator) Call 

func (e *Evaluator) Call(fn, arg *Value) (*Value, error)

Call applies fn to arg and returns a caller-owned result value.

func (*Evaluator) CallMulti 

func (e *Evaluator) CallMulti(fn *Value, args ...*Value) (*Value, error)

CallMulti applies fn to args and returns a caller-owned result value.

func (*Evaluator) Close 

func (e *Evaluator) Close() error

Close releases the owned EvalState.

Close is safe to call more than once. Once Close returns, methods that need the raw evaluation state and operations on Values created by e report status.ErrClosed. Caller-owned Values may still be closed while their Context remains open.

func (*Evaluator) EvalString 

func (e *Evaluator) EvalString(expr, path string) (*Value, error)

EvalString evaluates a Nix expression string at path.

The path is used by Nix for diagnostics and relative path resolution. The returned Value is owned by the caller and must be closed.

func (*Evaluator) EvalWithArgs added in v1.4.0 

func (e *Evaluator) EvalWithArgs(expr, path string, arg any) (*Value, error)

EvalWithArgs evaluates expr as a function and applies arg.

Arg may be nil, a boolean, string, integer, float, slice, or map with string keys. Slices and maps may contain nested combinations of those types. The path is used by Nix for diagnostics and relative path resolution. The returned Value is owned by the caller and must be closed.

func (*Evaluator) Force 

func (e *Evaluator) Force(v *Value) error

Force evaluates v to weak head normal form.

func (*Evaluator) ForceDeep 

func (e *Evaluator) ForceDeep(v *Value) error

ForceDeep recursively evaluates v.

func (*Evaluator) HasAttr 

func (e *Evaluator) HasAttr(v *Value, name string) (bool, error)

HasAttr reports whether v has an attribute named name.

func (*Evaluator) Index 

func (e *Evaluator) Index(v *Value, index uint32) (*Value, error)

Index returns the caller-owned forced list item at index.

func (*Evaluator) NewValue 

func (e *Evaluator) NewValue(gv GoValue) (*Value, error)

NewValue creates a caller-owned Nix value from a typed GoValue.

func (*Evaluator) RealiseString 

func (e *Evaluator) RealiseString(v *Value) (*RealisedString, error)

RealiseString realizes v as a string and returns referenced store paths.

func (*Evaluator) Unmarshal 

func (e *Evaluator) Unmarshal(v *Value, out any) error

Unmarshal decodes a Nix value into the Go value pointed to by out.

Struct fields are matched with the nix tag, or with the exact Go field name when no nix tag is present. Fields tagged nix:"-" are skipped. A missing field tagged validate:"required" returns a MissingAttrError; other missing fields are left unchanged. Extra Nix attributes are ignored.

func (*Evaluator) WrapValue 

func (e *Evaluator) WrapValue(ptr *raw.NixValue) (*Value, error)

WrapValue adopts an owned raw Nix value as a Value tied to e.

This is an integration point for sibling gonix packages that receive owned or refcounted values from lower-level Nix APIs. Callers transfer ownership of ptr to the returned Value and must not decref ptr directly after a successful call. The returned Value must be closed by the caller.

type GoValue 

type GoValue func(*Evaluator, *raw.NixValue) error

GoValue initializes a Nix value from Go-native data.

Use the helper functions in this package, such as Int, String, List, and Attrs, to construct GoValue values for Evaluator.NewValue.

func Apply 

func Apply(fn, arg *Value) GoValue

Apply returns a GoValue that initializes an unapplied function call.

func Attrs 

func Attrs(values map[string]GoValue) GoValue

Attrs returns a GoValue that initializes a Nix attribute set.

func Bool 

func Bool(value bool) GoValue

Bool returns a GoValue that initializes a Nix boolean.

func Copy 

func Copy(src *Value) GoValue

Copy returns a GoValue that initializes a value by copying src.

func Float 

func Float(value float64) GoValue

Float returns a GoValue that initializes a Nix floating-point number.

func Int 

func Int(value int64) GoValue

Int returns a GoValue that initializes a Nix integer.

func List 

func List(values ...GoValue) GoValue

List returns a GoValue that initializes a Nix list.

func Null 

func Null() GoValue

Null returns a GoValue that initializes Nix null.

func PathString 

func PathString(value string) GoValue

PathString returns a GoValue that initializes a Nix path string.

func String 

func String(value string) GoValue

String returns a GoValue that initializes a Nix string.

type InvalidUnmarshalError 

type InvalidUnmarshalError struct {
	Type reflect.Type
}

InvalidUnmarshalError describes an invalid target passed to Evaluator.Unmarshal.

func (*InvalidUnmarshalError) Error 

func (e *InvalidUnmarshalError) Error() string

type MissingAttrError 

type MissingAttrError struct {
	Attr string
	Path string
}

MissingAttrError describes a required Nix attribute that was absent.

func (*MissingAttrError) Error 

func (e *MissingAttrError) Error() string

type Option 

type Option func(*config)

Option configures Evaluator creation.

func WithFlakeSettings 

func WithFlakeSettings(settings *flakesettings.Settings) Option

WithFlakeSettings adds flake evaluator integration to the state builder.

func WithLookupPath 

func WithLookupPath(entries ...string) Option

WithLookupPath sets the Nix evaluator lookup path.

Entries use Nix lookup-path syntax, for example "nixpkgs=/path/to/nixpkgs". Repeated options append entries in order.

type RealisedString 

type RealisedString struct {
	// Value is the realized string content.
	Value string

	// Paths are owned store paths referenced by Value.
	Paths []*storepath.Path
}

RealisedString is a Nix string with its referenced store paths.

RealiseString returns Go-owned string data and owned store path clones. Call Close when finished to release the paths.

func (*RealisedString) Close 

func (r *RealisedString) Close() error

Close releases every referenced store path.

Close attempts to close every path and returns a joined error if one or more closes fail. It is safe to call more than once.

type UnmarshalTypeError 

type UnmarshalTypeError struct {
	Value string
	Type  reflect.Type
	Path  string
}

UnmarshalTypeError describes a Nix value that cannot be decoded into a Go type.

func (*UnmarshalTypeError) Error 

func (e *UnmarshalTypeError) Error() string

type UnsupportedTypeError 

type UnsupportedTypeError struct {
	Type reflect.Type
	Path string
}

UnsupportedTypeError describes a Go type that an Evaluator cannot convert to or from a Nix value.

func (*UnsupportedTypeError) Error 

func (e *UnsupportedTypeError) Error() string

type Value 

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

Value owns a reference to a Nix value.

Values are tied to the Evaluator that created them and must be closed by the caller before the Context. Value operations require the Evaluator to remain open. Close releases the owned value reference and is idempotent.

func (*Value) AttrLen 

func (v *Value) AttrLen() (uint32, error)

AttrLen returns the number of attributes in a Nix attribute set.

func (*Value) Bool 

func (v *Value) Bool() (bool, error)

Bool returns v as a Go bool.

func (*Value) Borrow 

func (v *Value) Borrow() (*raw.NixValue, error)

Borrow returns the borrowed raw Nix value handle.

Callers must not free the returned pointer and must not retain it beyond the immediate raw Nix call that needs it. This is an escape hatch for integration with lower-level bindings.

func (*Value) Close 

func (v *Value) Close() error

Close releases the owned Nix value reference.

Close is safe to call more than once. It may be called after the Evaluator is closed, but the Context must remain open. Once Close returns, methods that need the raw value handle report status.ErrClosed.

func (*Value) Float 

func (v *Value) Float() (float64, error)

Float returns v as a Go float64.

func (*Value) Int 

func (v *Value) Int() (int64, error)

Int returns v as a Go int64.

func (*Value) ListLen 

func (v *Value) ListLen() (uint32, error)

ListLen returns the number of items in a Nix list.

func (*Value) PathString 

func (v *Value) PathString() (string, error)

PathString returns v as a Nix path string.

func (*Value) String 

func (v *Value) String() (string, error)

String returns v as a Go string.

func (*Value) Type 

func (v *Value) Type() (ValueType, error)

Type returns the Nix value type.

func (*Value) TypeName 

func (v *Value) TypeName() (string, error)

TypeName returns Nix's human-readable type name for v.

type ValueType 

type ValueType int

ValueType identifies a Nix value's runtime type. 

const (
	// ValueTypeThunk is a deferred Nix expression.
	ValueTypeThunk ValueType = iota
	// ValueTypeInt is a Nix integer.
	ValueTypeInt
	// ValueTypeFloat is a Nix floating-point number.
	ValueTypeFloat
	// ValueTypeBool is a Nix boolean.
	ValueTypeBool
	// ValueTypeString is a Nix string.
	ValueTypeString
	// ValueTypePath is a Nix path.
	ValueTypePath
	// ValueTypeNull is Nix null.
	ValueTypeNull
	// ValueTypeAttrs is a Nix attribute set.
	ValueTypeAttrs
	// ValueTypeList is a Nix list.
	ValueTypeList
	// ValueTypeFunction is a Nix function.
	ValueTypeFunction
	// ValueTypeExternal is an external value.
	ValueTypeExternal
	// ValueTypeFailed is a failed value.
	ValueTypeFailed
)

func (ValueType) String 

func (vt ValueType) String() string

type ValueTypeError 

type ValueTypeError struct {
	// Actual is the value's runtime Nix type.
	Actual ValueType

	// Expected is the Nix type required by the getter.
	Expected ValueType
}

ValueTypeError describes a Value getter called for the wrong Nix type.

func (*ValueTypeError) Error 

func (e *ValueTypeError) Error() string

Source Files

View all Source files

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.