zson

package
v1.15.0 Latest Latest
Warning

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

 Go to latest Published: Mar 29, 2024 License: BSD-3-Clause Imports: 23 Imported by: 9

Documentation

Overview

Package zson provides fundamental interfaces to the ZSON data format comprising Reader, Writer, Parser, and so forth. The ZSON format includes a type system that requries a semantic analysis to parse an input to its structured data representation. To do so, Parser translats a ZSON input to an AST, Analyzer performs semantic type analysis to turn the AST into a Value, and Builder constructs a zed.Value from a Value.

Index

Constants

View Source 
const (
	ReadSize = 64 * 1024
	MaxSize  = 50 * 1024 * 1024
)

Variables

View Source 
var ErrBufferOverflow = errors.New("ZSON scanner buffer size exceeded")

Functions

func Build 

func Build(b *zcode.Builder, val Value) (zed.Value, error)

func BuildPrimitive 

func BuildPrimitive(b *zcode.Builder, val Primitive) error

func FormatPrimitive added in v1.0.0 

func FormatPrimitive(typ zed.Type, bytes zcode.Bytes) string

func FormatType 

func FormatType(typ zed.Type) string

FormatType formats a type in canonical form to represent type values as standalone entities.

func FormatTypeValue added in v1.0.0 

func FormatTypeValue(tv zcode.Bytes) string

func FormatValue 

func FormatValue(val zed.Value) string

func Implied 

func Implied(typ zed.Type) bool

Implied returns true for primitive types whose type can be inferred syntactically from its value and thus never needs a decorator.

func IsIdentifier added in v1.0.0 

func IsIdentifier(s string) bool

func IsTypeName added in v1.0.0 

func IsTypeName(s string) bool

IsTypeName returns true iff s is a valid, unquoted ZSON type name.

func Marshal 

func Marshal(v interface{}) (string, error)

func MarshalZNG 

func MarshalZNG(v interface{}) (zed.Value, error)

func MustParseValue added in v1.1.0 

func MustParseValue(zctx *zed.Context, zson string) zed.Value

func ParsePrimitive 

func ParsePrimitive(typeText, valText string) (zed.Value, error)

func ParseType 

func ParseType(zctx *zed.Context, zson string) (zed.Type, error)

func ParseValue 

func ParseValue(zctx *zed.Context, zson string) (zed.Value, error)

func ParseValueFromAST 

func ParseValueFromAST(zctx *zed.Context, ast astzed.Value) (zed.Value, error)

func QuotedName added in v1.0.0 

func QuotedName(name string) string

func QuotedString added in v1.0.0 

func QuotedString(s []byte) string

QuotedString quotes and escapes a ZSON string for serialization in accordance with the ZSON spec. It was copied and modified [with attribution](https://github.com/brimdata/zed/blob/main/acknowledgments.txt) from the encoding/json package in the Go source code.

func QuotedTypeName added in v1.3.0 

func QuotedTypeName(name string) string

func SelfDescribing 

func SelfDescribing(typ zed.Type) bool

SelfDescribing returns true for types whose type name can be entirely derived from its typed value, e.g., a record type can be derived from a record value because all of the field names and type names are present in the value, but an enum type cannot be derived from an enum value because not all the enumerated names are present in the value. In the former case, a decorated typedef can use the abbreviated form "(= <name>)", while the letter case, a type def must use the longer form "<value> (<name> = (<type>))".

func String 

func String(p interface{}) string

func TranslateType 

func TranslateType(zctx *zed.Context, astType astzed.Type) (zed.Type, error)

func Unhex added in v1.0.0 

func Unhex(b byte) byte

func Unmarshal 

func Unmarshal(zson string, v interface{}) error

func UnmarshalZNG 

func UnmarshalZNG(val zed.Value, v interface{}) error

Types

type Analyzer 

type Analyzer map[string]zed.Type

An Analyzer transforms an astzed.Value (which has decentralized type decorators) to a typed Value, where every component of a nested Value is explicitly typed. This is done via a semantic analysis where type state flows both down a the nested value hierarchy (via type decorators) and back up via fully typed value whose types are then usable as typedefs. The Analyzer tracks the ZSON typedef semantics by updating its table of name-to-type bindings in accordance with the left-to-right, depth-first semantics of ZSON typedefs.

func NewAnalyzer 

func NewAnalyzer() Analyzer

func (Analyzer) ConvertValue 

func (a Analyzer) ConvertValue(zctx *zed.Context, val astzed.Value) (Value, error)

type Array 

type Array struct {
	Type     zed.Type
	Elements []Value
}

Note that all of the types include a generic zed.Type as their type since anything can have a zed.TypeNamed along with its normal type.

func (*Array) SetType 

func (a *Array) SetType(t zed.Type)

func (*Array) TypeOf 

func (a *Array) TypeOf() zed.Type

type Binding 

type Binding struct {
	Name     string      // user-defined name
	Template interface{} // zero-valued entity used as template for new such objects
}

type Entry 

type Entry struct {
	Key   Value
	Value Value
}

Note that all of the types include a generic zed.Type as their type since anything can have a zed.TypeNamed along with its normal type.

type Enum 

type Enum struct {
	Type zed.Type
	Name string
}

Note that all of the types include a generic zed.Type as their type since anything can have a zed.TypeNamed along with its normal type.

func (*Enum) SetType 

func (e *Enum) SetType(t zed.Type)

func (*Enum) TypeOf 

func (e *Enum) TypeOf() zed.Type

type Error added in v1.0.0 

type Error struct {
	Type  zed.Type
	Value Value
}

Note that all of the types include a generic zed.Type as their type since anything can have a zed.TypeNamed along with its normal type.

func (*Error) SetType added in v1.0.0 

func (e *Error) SetType(t zed.Type)

func (*Error) TypeOf added in v1.0.0 

func (e *Error) TypeOf() zed.Type

type Formatter 

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

func NewFormatter 

func NewFormatter(pretty int, persist *regexp.Regexp) *Formatter

func (*Formatter) Format 

func (f *Formatter) Format(val zed.Value) string

func (*Formatter) FormatRecord 

func (f *Formatter) FormatRecord(rec zed.Value) string

func (*Formatter) Persist 

func (f *Formatter) Persist(re *regexp.Regexp)

Persist matches type names to the regular expression provided and persists the matched types across records in the stream. This is useful when typedefs have complicated type signatures, e.g., as generated by fused fields of records creating a union of records.

type Lexer 

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

func NewLexer 

func NewLexer(r io.Reader) *Lexer

type Map 

type Map struct {
	Type    zed.Type
	Entries []Entry
}

Note that all of the types include a generic zed.Type as their type since anything can have a zed.TypeNamed along with its normal type.

func (*Map) SetType 

func (m *Map) SetType(t zed.Type)

func (*Map) TypeOf 

func (m *Map) TypeOf() zed.Type

type MarshalContext 

type MarshalContext struct {
	*MarshalZNGContext
	// contains filtered or unexported fields
}

func NewMarshaler 

func NewMarshaler() *MarshalContext

func NewMarshalerIndent 

func NewMarshalerIndent(indent int) *MarshalContext

func NewMarshalerWithContext 

func NewMarshalerWithContext(zctx *zed.Context) *MarshalContext

func (*MarshalContext) Marshal 

func (m *MarshalContext) Marshal(v interface{}) (string, error)

func (*MarshalContext) MarshalCustom 

func (m *MarshalContext) MarshalCustom(names []string, fields []interface{}) (string, error)

type MarshalZNGContext 

type MarshalZNGContext struct {
	*zed.Context
	zcode.Builder
	// contains filtered or unexported fields
}

func NewZNGMarshaler 

func NewZNGMarshaler() *MarshalZNGContext

func NewZNGMarshalerWithContext 

func NewZNGMarshalerWithContext(zctx *zed.Context) *MarshalZNGContext

func (*MarshalZNGContext) Decorate 

func (m *MarshalZNGContext) Decorate(style TypeStyle)

Decorate informs the marshaler to add type decorations to the resulting ZNG in the form of named types in the sytle indicated, e.g., for a `struct Foo` in `package bar` at import path `github.com/acme/bar: the corresponding name would be `Foo` for TypeSimple, `bar.Foo` for TypePackage, and `github.com/acme/bar.Foo`for TypeFull. This mechanism works in conjunction with Bindings. Typically you would want just one or the other, but if a binding doesn't exist for a given Go type, then a ZSON type name will be created according to the decorator setting (which may be TypeNone).

func (*MarshalZNGContext) Marshal 

func (m *MarshalZNGContext) Marshal(v interface{}) (zed.Value, error)

func (*MarshalZNGContext) MarshalCustom 

func (m *MarshalZNGContext) MarshalCustom(names []string, vals []interface{}) (zed.Value, error)

func (*MarshalZNGContext) MarshalValue 

func (m *MarshalZNGContext) MarshalValue(v interface{}) (zed.Type, error)

MarshalValue marshals v into the value that is being built and is typically called by a custom marshaler.

func (*MarshalZNGContext) NamedBindings 

func (m *MarshalZNGContext) NamedBindings(bindings []Binding) error

NamedBindings informs the Marshaler to encode the given types with the corresponding ZSON type names. For example, to serialize a `bar.Foo` value decoroated with the ZSON type name "SpecialFoo", simply call NamedBindings with the value []Binding{{"SpecialFoo", &bar.Foo{}}. Subsequent calls to NamedBindings add additional such bindings leaving the existing bindings in place. During marshaling, if no binding is found for a particular Go value, then the marshaler's decorator setting applies.

type Null 

type Null struct {
	Type zed.Type
}

Note that all of the types include a generic zed.Type as their type since anything can have a zed.TypeNamed along with its normal type.

func (*Null) SetType 

func (n *Null) SetType(t zed.Type)

func (*Null) TypeOf 

func (n *Null) TypeOf() zed.Type

type Parser 

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

func NewParser 

func NewParser(r io.Reader) *Parser

func (*Parser) ParseValue 

func (p *Parser) ParseValue() (astzed.Value, error)

type Primitive 

type Primitive struct {
	Type zed.Type
	Text string
}

Note that all of the types include a generic zed.Type as their type since anything can have a zed.TypeNamed along with its normal type.

func (*Primitive) SetType 

func (p *Primitive) SetType(t zed.Type)

func (*Primitive) TypeOf 

func (p *Primitive) TypeOf() zed.Type

type Record 

type Record struct {
	Type   zed.Type
	Fields []Value
}

Note that all of the types include a generic zed.Type as their type since anything can have a zed.TypeNamed along with its normal type.

func (*Record) SetType 

func (r *Record) SetType(t zed.Type)

func (*Record) TypeOf 

func (r *Record) TypeOf() zed.Type

type Set 

type Set struct {
	Type     zed.Type
	Elements []Value
}

Note that all of the types include a generic zed.Type as their type since anything can have a zed.TypeNamed along with its normal type.

func (*Set) SetType 

func (s *Set) SetType(t zed.Type)

func (*Set) TypeOf 

func (s *Set) TypeOf() zed.Type

type TypeStyle 

type TypeStyle int
const (
	StyleNone TypeStyle = iota
	StyleSimple
	StylePackage
	StyleFull
)

type TypeValue 

type TypeValue struct {
	Type  zed.Type
	Value zed.Type
}

Note that all of the types include a generic zed.Type as their type since anything can have a zed.TypeNamed along with its normal type.

func (*TypeValue) SetType 

func (t *TypeValue) SetType(T zed.Type)

func (*TypeValue) TypeOf 

func (t *TypeValue) TypeOf() zed.Type

type Union 

type Union struct {
	Type  zed.Type
	Tag   int
	Value Value
}

Note that all of the types include a generic zed.Type as their type since anything can have a zed.TypeNamed along with its normal type.

func (*Union) SetType 

func (u *Union) SetType(t zed.Type)

func (*Union) TypeOf 

func (u *Union) TypeOf() zed.Type

type UnmarshalContext 

type UnmarshalContext struct {
	*UnmarshalZNGContext
	// contains filtered or unexported fields
}

func NewUnmarshaler 

func NewUnmarshaler() *UnmarshalContext

func (*UnmarshalContext) Unmarshal 

func (u *UnmarshalContext) Unmarshal(zson string, v interface{}) error

type UnmarshalZNGContext 

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

func NewZNGUnmarshaler 

func NewZNGUnmarshaler() *UnmarshalZNGContext

func (*UnmarshalZNGContext) Bind 

func (u *UnmarshalZNGContext) Bind(templates ...interface{}) error

Bindings informs the unmarshaler that ZSON values with a type name equal to any of the three variations of Go type mame (full path, package.Type, or just Type) may be used to inform the deserialization of a ZSON value into a Go interface value. If full path names are not used, it is up to the entitity that marshaled the original ZSON to ensure that no type-name conflicts arise, e.g., when using the TypeSimple decorator style, you cannot have a type called bar.Foo and another type baz.Foo as the simple type decorator will be "Foo" in both cases and thus create a name conflict.

func (*UnmarshalZNGContext) NamedBindings 

func (u *UnmarshalZNGContext) NamedBindings(bindings []Binding) error

func (*UnmarshalZNGContext) SetContext added in v1.3.0 

func (u *UnmarshalZNGContext) SetContext(zctx *zed.Context)

SetContext provides an optional type context to the unmarshaler. This is needed only when unmarshaling Zed type values into Go zed.Type interface values.

func (*UnmarshalZNGContext) Unmarshal 

func (u *UnmarshalZNGContext) Unmarshal(val zed.Value, v interface{}) error

type Value 

type Value interface {
	TypeOf() zed.Type
	SetType(zed.Type)
}

type ZNGMarshaler 

type ZNGMarshaler interface {
	MarshalZNG(*MarshalZNGContext) (zed.Type, error)
}

type ZNGUnmarshaler 

type ZNGUnmarshaler interface {
	UnmarshalZNG(*UnmarshalZNGContext, zed.Value) error
}

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.