pkl

package
v0.13.2 Latest Latest
Warning

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

Go to latest
Published: Mar 3, 2026 License: Apache-2.0 Imports: 26 Imported by: 185

Documentation

Index

Constants

View Source
const (
	Nanosecond  DurationUnit = 1
	Microsecond              = Nanosecond * 1000
	Millisecond              = Microsecond * 1000
	Second                   = Millisecond * 1000
	Minute                   = Second * 60
	Hour                     = Minute * 60
	Day                      = Hour * 24
)
View Source
const (
	Bytes     DataSizeUnit = 1
	Kilobytes              = 1000
	Kibibytes              = 1024
	Megabytes              = Kilobytes * 1000
	Mebibytes              = Kibibytes * 1024
	Gigabytes              = Megabytes * 1000
	Gibibytes              = Mebibytes * 1024
	Terabytes              = Gigabytes * 1000
	Tebibytes              = Gibibytes * 1024
	Petabytes              = Terabytes * 1000
	Pebibytes              = Tebibytes * 1024
)
View Source
const StructTag = "pkl"

Variables

View Source
var MaybePreconfiguredOptions = func(opts *EvaluatorOptions) {
	if len(opts.AllowedResources) == 0 {
		WithDefaultAllowedResources(opts)
	}
	if len(opts.Env) == 0 {
		WithOsEnv(opts)
	}
	if len(opts.AllowedModules) == 0 {
		WithDefaultAllowedModules(opts)
	}
	if opts.CacheDir == "" {
		WithDefaultCacheDir(opts)
	}
	if opts.Logger == nil {
		opts.Logger = NoopLogger
	}
}

MaybePreconfiguredOptions is like PreconfiguredOptions, except it only applies options if they have not already been set.

It panics if the home directory cannot be determined.

View Source
var NoopLogger = NewLogger(io.Discard)

NoopLogger is a logger that discards all messages.

View Source
var PreconfiguredOptions = func(opts *EvaluatorOptions) {
	WithDefaultAllowedResources(opts)
	WithOsEnv(opts)
	WithDefaultAllowedModules(opts)
	WithDefaultCacheDir(opts)
	opts.Logger = NoopLogger
}

PreconfiguredOptions configures an evaluator with:

  • allowance for "file", "http", "https", "env", "prop", "package resource schemes
  • allowance for "repl", "file", "http", "https", "pkl", "package" module schemes
  • environment variables from the host environment
  • ~/.pkl/cache as the cache directory
  • no-op logging

It panics if the home directory cannot be determined.

View Source
var StderrLogger = NewLogger(os.Stdout)

StderrLogger is a logger that writes to standard error.

View Source
var WithDefaultAllowedModules = func(opts *EvaluatorOptions) {
	opts.AllowedModules = append(opts.AllowedModules, "pkl:", "repl:", "file:", "http:", "https:", "modulepath:", "package:", "projectpackage:")
}

WithDefaultAllowedModules enables reading stdlib, repl, file, http, https, modulepath, and package modules.

View Source
var WithDefaultAllowedResources = func(opts *EvaluatorOptions) {
	opts.AllowedResources = append(opts.AllowedResources, "http:", "https:", "file:", "env:", "prop:", "modulepath:", "package:", "projectpackage:")
}

WithDefaultAllowedResources enables reading http, https, file, env, prop, modulepath, and package resources.

View Source
var WithDefaultCacheDir = func(opts *EvaluatorOptions) {
	dirname, err := os.UserHomeDir()
	if err != nil {
		panic(err)
	}
	opts.CacheDir = filepath.Join(dirname, ".pkl/cache")
}

WithDefaultCacheDir sets the cache directory to Pkl's default location. It panics if the home directory cannot be determined.

View Source
var WithExternalClientFs = func(fs fs.FS, scheme string) func(opts *ExternalReaderClientOptions) {
	return func(opts *ExternalReaderClientOptions) {
		reader := &fsReader{fs: fs, scheme: scheme}
		WithExternalClientModuleReader(&fsModuleReader{reader})(opts)
		WithExternalClientResourceReader(&fsResourceReader{reader})(opts)
	}
}

WithExternalClientFs sets up a ModuleReader and ResourceReader to the ExternalReaderClient that associates the provided scheme with files from fs.

View Source
var WithExternalClientModuleReader = func(reader ModuleReader) func(*ExternalReaderClientOptions) {
	return func(options *ExternalReaderClientOptions) {
		options.ModuleReaders = append(options.ModuleReaders, reader)
	}
}

WithExternalClientModuleReader adds an additional ModuleReader to the ExternalReaderClient.

View Source
var WithExternalClientResourceReader = func(reader ResourceReader) func(*ExternalReaderClientOptions) {
	return func(options *ExternalReaderClientOptions) {
		options.ResourceReaders = append(options.ResourceReaders, reader)
	}
}

WithExternalClientResourceReader adds an additional ResourceReader to the ExternalReaderClient.

View Source
var WithExternalClientStreams = func(requestReader io.Reader, responseWriter io.Writer) func(*ExternalReaderClientOptions) {
	return func(options *ExternalReaderClientOptions) {
		options.RequestReader = requestReader
		options.ResponseWriter = responseWriter
	}
}

WithExternalClientStreams sets the input and output interfaces the ExternalReaderClient will use to communicate with the Pkl evaluator.

View Source
var WithExternalModuleReader = func(scheme string, spec ExternalReader) func(opts *EvaluatorOptions) {
	return func(opts *EvaluatorOptions) {
		if opts.ExternalModuleReaders == nil {
			opts.ExternalModuleReaders = map[string]ExternalReader{}
		}
		opts.ExternalModuleReaders[scheme] = spec
		opts.AllowedModules = append(opts.AllowedModules, regexp.QuoteMeta(scheme+":"))
	}
}
View Source
var WithExternalResourceReader = func(scheme string, spec ExternalReader) func(opts *EvaluatorOptions) {
	return func(opts *EvaluatorOptions) {
		if opts.ExternalResourceReaders == nil {
			opts.ExternalResourceReaders = map[string]ExternalReader{}
		}
		opts.ExternalResourceReaders[scheme] = spec
		opts.AllowedResources = append(opts.AllowedResources, regexp.QuoteMeta(scheme+":"))
	}
}
View Source
var WithFs = func(fs fs.FS, scheme string) func(opts *EvaluatorOptions) {
	return func(opts *EvaluatorOptions) {
		reader := &fsReader{fs: fs, scheme: scheme}
		WithModuleReader(&fsModuleReader{reader})(opts)
		WithResourceReader(&fsResourceReader{reader})(opts)
	}
}

WithFs sets up a ModuleReader and ResourceReader that associates the provided scheme with files from fs.

For example, this may come from files within embed.FS.

In Pkl terms, files within this file system are interpreted as based off the root path "/". For example, the path "foo.txt" within the provided file system is matched to path "/foo.txt" in Pkl code.

If on Pkl 0.22 or lower, triple-dot imports and globbing are not supported.

Modules and resources may be globbed within Pkl via `import*` and `read*`. Modules may be imported via triple-dot imports.

Pkl has a built-in file system that reads from the host disk. This behavior may be overwritten by setting the scheme as `file`.

View Source
var WithModuleReader = func(reader ModuleReader) func(opts *EvaluatorOptions) {
	return func(opts *EvaluatorOptions) {
		opts.ModuleReaders = append(opts.ModuleReaders, reader)
		opts.AllowedModules = append(opts.AllowedModules, regexp.QuoteMeta(reader.Scheme()+":"))
	}
}

WithModuleReader sets up the given module reader, and also adds the reader's scheme to the evaluator's allowed modules list.

View Source
var WithOsEnv = func(opts *EvaluatorOptions) {
	if opts.Env == nil {
		opts.Env = make(map[string]string)
	}
	for _, e := range os.Environ() {
		if i := strings.Index(e, "="); i >= 0 {
			opts.Env[e[:i]] = e[i+1:]
		}
	}
}

WithOsEnv enables reading `env` values from the current environment.

View Source
var WithProject = func(project *Project) func(opts *EvaluatorOptions) {
	return func(opts *EvaluatorOptions) {
		WithProjectEvaluatorSettings(project)(opts)
		WithProjectDependencies(project)(opts)
	}
}
View Source
var WithProjectDependencies = func(project *Project) func(opts *EvaluatorOptions) {
	return func(opts *EvaluatorOptions) {
		opts.ProjectBaseURI = strings.TrimSuffix(project.ProjectFileUri, "/PklProject")
		opts.DeclaredProjectDependencies = project.Dependencies()
	}
}

WithProjectDependencies configures the evaluator with dependencies from the specified project.

View Source
var WithProjectEvaluatorSettings = func(project *Project) func(opts *EvaluatorOptions) {
	return func(opts *EvaluatorOptions) {
		evaluatorSettings := project.EvaluatorSettings
		opts.Properties = evaluatorSettings.ExternalProperties
		opts.Env = evaluatorSettings.Env
		if evaluatorSettings.AllowedModules != nil {
			opts.AllowedModules = *evaluatorSettings.AllowedModules
		}
		if evaluatorSettings.AllowedResources != nil {
			opts.AllowedResources = *evaluatorSettings.AllowedResources
		}
		if evaluatorSettings.NoCache != nil && *evaluatorSettings.NoCache {
			opts.CacheDir = ""
		} else {
			opts.CacheDir = evaluatorSettings.ModuleCacheDir
		}
		opts.RootDir = evaluatorSettings.RootDir
		if evaluatorSettings.Http != nil {
			opts.Http = &Http{}
			if evaluatorSettings.Http.Proxy != nil {
				opts.Http.Proxy = &Proxy{NoProxy: opts.Http.Proxy.NoProxy}
				if evaluatorSettings.Http.Proxy.Address != nil {
					opts.Http.Proxy.Address = *evaluatorSettings.Http.Proxy.Address
				}
			}
			if evaluatorSettings.Http.Rewrites != nil {
				opts.Http.Rewrites = *evaluatorSettings.Http.Rewrites
			}
		}
		if evaluatorSettings.ExternalModuleReaders != nil {
			opts.ExternalModuleReaders = make(map[string]ExternalReader, len(evaluatorSettings.ExternalModuleReaders))
			for scheme, reader := range evaluatorSettings.ExternalModuleReaders {
				opts.ExternalModuleReaders[scheme] = ExternalReader(reader)
				if evaluatorSettings.AllowedModules == nil {
					WithDefaultAllowedModules(opts)
					opts.AllowedModules = append(opts.AllowedModules, regexp.QuoteMeta(scheme+":"))
				}
			}
		}
		if evaluatorSettings.ExternalResourceReaders != nil {
			opts.ExternalResourceReaders = make(map[string]ExternalReader, len(evaluatorSettings.ExternalResourceReaders))
			for scheme, reader := range evaluatorSettings.ExternalResourceReaders {
				opts.ExternalResourceReaders[scheme] = ExternalReader(reader)
				if evaluatorSettings.AllowedResources == nil {
					WithDefaultAllowedResources(opts)
					opts.AllowedResources = append(opts.AllowedResources, regexp.QuoteMeta(scheme+":"))
				}
			}
		}
		if evaluatorSettings.TraceMode != nil {
			opts.TraceMode = *evaluatorSettings.TraceMode
		}
	}
}

WithProjectEvaluatorSettings configures the evaluator with settings from the given ProjectEvaluatorSettings.

View Source
var WithResourceReader = func(reader ResourceReader) func(opts *EvaluatorOptions) {
	return func(opts *EvaluatorOptions) {
		opts.ResourceReaders = append(opts.ResourceReaders, reader)
		opts.AllowedResources = append(opts.AllowedResources,