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/fatih/color
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 Contents
- type ErrorFormatter
- type FileImporter
- type Hidden
- type ImportCache
- type Importer
- type MemoryImporter
- type NativeFunction
- type Parameters
- type PlusSuperUnboundField
- type RuntimeError
- type TraceElement
- type TraceFrame
- type 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)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func SnippetToAST ¶
SnippetToAST parses a snippet and returns the resulting AST.
Types ¶
type ColorFormatter ¶
ColorFormatter represents a function that writes to the terminal using color.
type Contents ¶ added in v0.11.2
type Contents struct {
// contains filtered or unexported fields
}
Contents is a representation of imported data. It is a simple string wrapper, which makes it easier to enforce the caching policy.
func MakeContents ¶ added in v0.11.2
MakeContents creates Contents from a string.
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
// contains filtered or unexported fields
}
FileImporter imports data from the filesystem.
type ImportCache ¶
type ImportCache struct {
// contains filtered or unexported fields
}
ImportCache represents a cache of imported data.
While the user-defined Importer implementations are required to cache file content, this cache is an additional layer of optimization that caches values (i.e. the result of executing the file content). It also verifies that the content pointer is the same for two foundAt values.
func MakeImportCache ¶
func MakeImportCache(importer Importer) *ImportCache
MakeImportCache creates an ImportCache using an Importer.
func (*ImportCache) ImportCode ¶
func (cache *ImportCache) ImportCode(importedFrom, importedPath string, i *interpreter, trace TraceElement) (value, error)
ImportCode imports code from a path.
func (*ImportCache) ImportString ¶
func (cache *ImportCache) ImportString(importedFrom, importedPath string, i *interpreter, trace TraceElement) (*valueString, error)
ImportString imports a string, caches it and then returns it.
type Importer ¶
type Importer interface {
// Import fetches data from a given path. It may be relative
// to the file where we do the import. What "relative path"
// means depends on the importer.
//
// It is required that:
// a) for given (importedFrom, importedPath) the same
// (contents, foundAt) are returned on subsequent calls.
// b) for given foundAt, the contents are always the same
//
// It is recommended that if there are multiple locations that
// need to be probed (e.g. relative + multiple library paths)
// then all results of all attempts will be cached separately,
// both nonexistence and contents of existing ones.
// FileImporter may serve as an example.
Import(importedFrom, importedPath string) (contents Contents, foundAt string, err error)
}
An Importer imports data from a path. TODO(sbarzowski) caching of errors (may require breaking changes)
type MemoryImporter ¶
MemoryImporter "imports" data from an in-memory map.
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, i *interpreter, trace TraceElement) (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 (*VM) EvaluateSnippet ¶
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) NativeFunction ¶
func (vm *VM) NativeFunction(f *NativeFunction)
NativeFunction registers a native function.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package ast provides AST nodes and ancillary structures and algorithms.
|
Package ast provides AST nodes and ancillary structures and algorithms. |
|
Package dump can dump a Go data structure to Go source file, so that it can be statically embedded into other code.
|
Package dump can dump a Go data structure to Go source file, so that it can be statically embedded into other code. |
|
Package linter analyses Jsonnet code for code "smells".
|
Package linter analyses Jsonnet code for code "smells". |
|
Package parser reads Jsonnet files and parses them into AST nodes.
|
Package parser reads Jsonnet files and parses them into AST nodes. |