jsonnet

README

go-jsonnet

This an implementation of Jsonnet in pure Go. It is feature complete but is not as heavily exercised as the Jsonnet C++ implementation. Please try it out and give feedback.

This code is known to work on Go 1.8 and above. We recommend always using the newest stable release of Go.

Build instructions

export GOPATH=$HOME/go-workspace
mkdir -pv $GOPATH
go get github.com/google/go-jsonnet
cd $GOPATH/src/github.com/google/go-jsonnet
cd jsonnet
go build
./jsonnet /dev/stdin <<< '{x: 1, y: self.x} + {x: 10}'
{
   "x": 10,
   "y": 10
}

Running tests

./tests.sh  # Also runs `go test ./...`

Implementation Notes

We are generating some helper classes on types by using http://clipperhouse.github.io/gen/. Do the following to regenerate these if necessary:

go get github.com/clipperhouse/gen
go get github.com/clipperhouse/set
export PATH=$PATH:$GOPATH/bin  # If you haven't already
go generate

Generated Stdlib

To regenerate the standard library, do:

./reset_stdast_go.sh && go run cmd/dumpstdlibast.go

Documentation

Overview

Package jsonnet implements a parser and evaluator for jsonnet.

Jsonnet is a domain specific configuration language that helps you define JSON data. Jsonnet lets you compute fragments of JSON within the structure, bringing the same benefit to structured data that templating languages bring to plain text.

See http://jsonnet.org/ for a full language description and tutorial.

Index

• func SnippetToAST(filename string, snippet string) (ast.Node, error)
• func Version() string
• type ColorFormatter
• type ErrorFormatter
• type FileImporter
  • func (importer *FileImporter) Import(dir, importedPath string) (*ImportedData, error)
• type Hidden
• type ImportCache
  • func MakeImportCache(importer Importer) *ImportCache
  • func (cache *ImportCache) ImportCode(codeDir, importedPath string, e *evaluator) (value, error)
  • func (cache *ImportCache) ImportString(codeDir, importedPath string, e *evaluator) (*valueString, error)
• type ImportCacheValue
• type ImportedData
• type Importer
• type MemoryImporter
  • func (importer *MemoryImporter) Import(dir, importedPath string) (*ImportedData, error)
• type NativeFunction
  • func (native *NativeFunction) EvalCall(arguments callArguments, e *evaluator) (value, error)
  • func (native *NativeFunction) Parameters() Parameters
• type Parameters
• type PlusSuperUnboundField
• type RuntimeError
  • func (err RuntimeError) Error() string
• type TraceElement
• type TraceFrame
• type VM
  • func MakeVM() *VM
  • func (vm *VM) EvaluateSnippet(filename string, snippet string) (json string, formattedErr error)
  • func (vm *VM) EvaluateSnippetMulti(filename string, snippet string) (files map[string]string, formattedErr error)
  • func (vm *VM) EvaluateSnippetStream(filename string, snippet string) (docs []string, formattedErr error)
  • func (vm *VM) ExtCode(key string, val string)
  • func (vm *VM) ExtVar(key string, val string)
  • func (vm *VM) Importer(i Importer)
  • func (vm *VM) NativeFunction(f *NativeFunction)
  • func (vm *VM) TLACode(key string, val string)
  • func (vm *VM) TLAVar(key string, val string)

Functions

func SnippetToAST

func SnippetToAST(filename string, snippet string) (ast.Node, error)

SnippetToAST parses a snippet and returns the resulting AST.

func Version

func Version() string

Version returns the Jsonnet version number.

Types

type ColorFormatter

type ColorFormatter func(w io.Writer, f string, a ...interface{}) (n int, err error)

ColorFormatter represents a function that writes to the terminal using color.

type ErrorFormatter

type ErrorFormatter interface {
	// Format static, runtime, and unexpected errors prior to printing them.
	Format(err error) string

	// Set the the maximum length of stack trace before cropping.
	SetMaxStackTraceSize(size int)

	// Set the color formatter for the location color.
	SetColorFormatter(color ColorFormatter)
}

An ErrorFormatter formats errors with stacktraces and color.

type FileImporter

type FileImporter struct {
	JPaths []string
}

FileImporter imports data from files.

func (*FileImporter) Import

func (importer *FileImporter) Import(dir, importedPath string) (*ImportedData, error)

Import imports a file.

type Hidden

type Hidden int

Hidden represents wether to include hidden fields in a lookup.

type ImportCache

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

ImportCache represents a cache of imported data.

func MakeImportCache

func MakeImportCache(importer Importer) *ImportCache

MakeImportCache creates and ImportCache using an importer.

func (*ImportCache) ImportCode

func (cache *ImportCache) ImportCode(codeDir, importedPath string, e *evaluator) (value, error)

ImportCode imports code from a path.

func (*ImportCache) ImportString

func (cache *ImportCache) ImportString(codeDir, importedPath string, e *evaluator) (*valueString, error)

ImportString imports a string, caches it and then returns it.

type ImportCacheValue

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

ImportCacheValue represents a value in an imported-data cache.

type ImportedData

type ImportedData struct {
	FoundHere string
	Content   string
}

ImportedData represents imported data and where it came from.

type Importer

type Importer interface {
	Import(codeDir string, importedPath string) (*ImportedData, error)
}

An Importer imports data from a path.

type MemoryImporter

type MemoryImporter struct {
	Data map[string]string
}

MemoryImporter "imports" data from an in-memory map.

func (*MemoryImporter) Import

func (importer *MemoryImporter) Import(dir, importedPath string) (*ImportedData, error)

Import imports a map entry.

type NativeFunction

type NativeFunction struct {
	Func   func([]interface{}) (interface{}, error)
	Params ast.Identifiers
	Name   string
}

NativeFunction represents a function implemented in Go.

func (*NativeFunction) EvalCall

func (native *NativeFunction) EvalCall(arguments callArguments, e *evaluator) (value, error)

EvalCall evaluates a call to a NativeFunction and returns the result.

func (*NativeFunction) Parameters

func (native *NativeFunction) Parameters() Parameters

Parameters returns a NativeFunction's parameters.

type Parameters

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

Parameters represents required position and optional named parameters for a function definition.

type PlusSuperUnboundField

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

PlusSuperUnboundField represents a `field+: ...` that hasn't been bound to an object.

type RuntimeError

type RuntimeError struct {
	StackTrace []TraceFrame
	Msg        string
}

RuntimeError is an error discovered during evaluation of the program

func (RuntimeError) Error

func (err RuntimeError) Error() string

type TraceElement

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

TraceElement represents tracing information, including a location range and a surrounding context. TODO(sbarzowski) better name

type TraceFrame

type TraceFrame struct {
	Loc  ast.LocationRange
	Name string
}

TraceFrame is tracing information about a single frame of the call stack. TODO(sbarzowski) the difference from TraceElement. Do we even need this?

type VM

type VM struct {
	MaxStack int

	ErrorFormatter ErrorFormatter
	StringOutput   bool
	// contains filtered or unexported fields
}

VM is the core interpreter and is the touchpoint used to parse and execute Jsonnet.

func MakeVM

func MakeVM() *VM

MakeVM creates a new VM with default parameters.

func (*VM) EvaluateSnippet

func (vm *VM) EvaluateSnippet(filename string, snippet string) (json string, formattedErr error)

EvaluateSnippet evaluates a string containing Jsonnet code, return a JSON string.

The filename parameter is only used for error messages.

func (*VM) EvaluateSnippetMulti

func (vm *VM) EvaluateSnippetMulti(filename string, snippet string) (files map[string]string, formattedErr error)

EvaluateSnippetMulti evaluates a string containing Jsonnet code to key-value pairs. The keys are field name strings and the values are JSON strings.

The filename parameter is only used for error messages.

func (*VM) EvaluateSnippetStream

func (vm *VM) EvaluateSnippetStream(filename string, snippet string) (docs []string, formattedErr error)

EvaluateSnippetStream evaluates a string containing Jsonnet code to an array. The array is returned as an array of JSON strings.

The filename parameter is only used for error messages.

func (*VM) ExtCode

func (vm *VM) ExtCode(key string, val string)

ExtCode binds a Jsonnet external code var to the given code.

func (*VM) ExtVar

func (vm *VM) ExtVar(key string, val string)

ExtVar binds a Jsonnet external var to the given value.

func (*VM) Importer

func (vm *VM) Importer(i Importer)

Importer sets Importer to use during evaluation (import callback).

func (*VM) NativeFunction

func (vm *VM) NativeFunction(f *NativeFunction)

NativeFunction registers a native function.

func (*VM) TLACode

func (vm *VM) TLACode(key string, val string)

TLACode binds a Jsonnet top level argument to the given code.

func (*VM) TLAVar

func (vm *VM) TLAVar(key string, val string)

TLAVar binds a Jsonnet top level argument to the given value.