Documentation

Overview

Package templateproto defines a proto-based way to configure templates for JSON documents.

Index

Constants

This section is empty.

Variables

View Source
var File_go_chromium_org_luci_common_data_text_templateproto_template_proto protoreflect.FileDescriptor
View Source
var ParamRegex = regexp.MustCompile(`^\${[^}]+}$`)

ParamRegex is the regular expression that all parameter names must match.

Functions

func NormalizeJSON

func NormalizeJSON(data string, obj bool) (string, error)

NormalizeJSON is used to take some free-form JSON and validates that:

* it only contains a valid JSON object (e.g. `{...stuff...}`); OR
* it only contains a valid JSON array (e.g. `[...stuff...]`)

If obj is true, this looks for an object, if it's false, it looks for an array.

This will also remove all extra whitespace and sort all objects by key.

Types

type File

type File struct {
	Template map[string]*File_Template `` /* 157-byte string literal not displayed */
	// contains filtered or unexported fields
}

File represents a file full of template definitions.

func LoadFile

func LoadFile(data string) (file *File, err error)

LoadFile loads a File from a string containing the template text protobuf.

Expects config.Interface to be in the context already.

func (*File) Descriptor

func (*File) Descriptor() ([]byte, []int)

Deprecated: Use File.ProtoReflect.Descriptor instead.

func (*File) GetTemplate

func (x *File) GetTemplate() map[string]*File_Template

func (*File) Normalize

func (f *File) Normalize() error

Normalize will normalize all of the Templates in this message, returning an error if any are invalid.

func (*File) ProtoMessage

func (*File) ProtoMessage()

func (*File) ProtoReflect

func (x *File) ProtoReflect() protoreflect.Message

func (*File) Render

func (f *File) Render(spec *Specifier) (string, error)

Render renders the specified template with the given parameters.

func (*File) RenderL

func (f *File) RenderL(templName string, params LiteralMap) (ret string, err error)

RenderL renders a specified template with go literal arguments.

func (*File) Reset

func (x *File) Reset()

func (*File) String

func (x *File) String() string

type File_Template

type File_Template struct {

	// Markdown-formatted documentation for this schema entry.
	Doc string `protobuf:"bytes,1,opt,name=doc,proto3" json:"doc,omitempty"`
	// body is the main JSON output for this template. It must have the form
	// of valid json, modulo the substitution parameters. In order for this
	// Template to be valid, body must parse as valid JSON, after all
	// substitutions have been applied.
	Body string `protobuf:"bytes,2,opt,name=body,proto3" json:"body,omitempty"`
	// param is a listing of all of the parameterized bits in the Template body.
	// The key must match the regex /\${[^}]+}/. So "${foo}" would be ok, but
	// "foo", "$foo", or "${}" would not.
	//
	// params provided here must be present in Body at least once in order
	// for the Template to be valid.
	Param map[string]*File_Template_Parameter `` /* 151-byte string literal not displayed */
	// contains filtered or unexported fields
}

Template defines a single template.

func (*File_Template) Descriptor

func (*File_Template) Descriptor() ([]byte, []int)

Deprecated: Use File_Template.ProtoReflect.Descriptor instead.

func (*File_Template) GetBody

func (x *File_Template) GetBody() string

func (*File_Template) GetDoc

func (x *File_Template) GetDoc() string

func (*File_Template) GetParam

func (x *File_Template) GetParam() map[string]*File_Template_Parameter

func (*File_Template) Normalize

func (t *File_Template) Normalize() error

Normalize will normalize the Template message, returning an error if it is invalid.

func (*File_Template) ProtoMessage

func (*File_Template) ProtoMessage()

func (*File_Template) ProtoReflect

func (x *File_Template) ProtoReflect() protoreflect.Message

func (*File_Template) Render

func (t *File_Template) Render(params map[string]*Value) (string, error)

Render turns the Template into a JSON document, filled with the given parameters. It does not validate that the output is valid JSON, but if you called Normalize on this Template already, then it WILL be valid JSON.

func (*File_Template) RenderL

func (t *File_Template) RenderL(m LiteralMap) (string, error)

RenderL renders this template with a LiteralMap, calling its Convert method and passing the result to Render.

func (*File_Template) Reset

func (x *File_Template) Reset()

func (*File_Template) String

func (x *File_Template) String() string

type File_Template_Parameter

type File_Template_Parameter struct {

	// Markdown-formatted documentation for this schema entry.
	Doc     string `protobuf:"bytes,1,opt,name=doc,proto3" json:"doc,omitempty"`
	Default *Value `protobuf:"bytes,2,opt,name=default,proto3" json:"default,omitempty"`
	// nullable indicates if 'null' is a valid value for this parameter. This
	// can be used to distinguish e.g. "" from not-supplied. If default is
	// Value{null: {}}, this must be true.
	Nullable bool    `protobuf:"varint,3,opt,name=nullable,proto3" json:"nullable,omitempty"`
	Schema   *Schema `protobuf:"bytes,4,opt,name=schema,proto3" json:"schema,omitempty"`
	// contains filtered or unexported fields
}

func (*File_Template_Parameter) Accepts

func (p *File_Template_Parameter) Accepts(v *Value) error

Accepts returns nil if this Parameter can accept the Value.

func (*File_Template_Parameter) Descriptor

func (*File_Template_Parameter) Descriptor() ([]byte, []int)

Deprecated: Use File_Template_Parameter.ProtoReflect.Descriptor instead.

func (*File_Template_Parameter) GetDefault

func (x *File_Template_Parameter) GetDefault() *Value

func (*File_Template_Parameter) GetDoc

func (x *File_Template_Parameter) GetDoc() string

func (*File_Template_Parameter) GetNullable

func (x *File_Template_Parameter) GetNullable() bool

func (*File_Template_Parameter) GetSchema

func (x *File_Template_Parameter) GetSchema() *Schema

func (*File_Template_Parameter) Normalize

func (p *File_Template_Parameter) Normalize() error

Normalize will normalize the Parameter, returning an error if it is invalid.

func (*File_Template_Parameter) ProtoMessage

func (*File_Template_Parameter) ProtoMessage()

func (*File_Template_Parameter) ProtoReflect

func (x *File_Template_Parameter) ProtoReflect() protoreflect.Message

func (*File_Template_Parameter) Reset

func (x *File_Template_Parameter) Reset()

func (*File_Template_Parameter) String

func (x *File_Template_Parameter) String() string

type LiteralMap

type LiteralMap map[string]interface{}

LiteralMap is a type for literal in-line param substitutions, or when you know statically that the params correspond to correct Value types.

func (LiteralMap) Convert

func (m LiteralMap) Convert() (map[string]*Value, error)

Convert converts this to a parameter map that can be used with Template.Render.

type Schema

type Schema struct {

	// Types that are assignable to Schema:
	//	*Schema_Int
	//	*Schema_Uint
	//	*Schema_Float
	//	*Schema_Bool
	//	*Schema_Str
	//	*Schema_Bytes
	//	*Schema_Enum
	//	*Schema_Object
	//	*Schema_Array
	Schema isSchema_Schema `protobuf_oneof:"schema"`
	// contains filtered or unexported fields
}

func (*Schema) Accepts

func (s *Schema) Accepts(v *Value) error

Accepts returns nil if this Schema can accept the Value.

func (*Schema) Descriptor

func (*Schema) Descriptor() ([]byte, []int)

Deprecated: Use Schema.ProtoReflect.Descriptor instead.

func (*Schema) GetArray

func (x *Schema) GetArray() *Schema_JSON

func (*Schema) GetBool

func (x *Schema) GetBool() *Schema_Atom

func (*Schema) GetBytes

func (x *Schema) GetBytes() *Schema_Sequence

func (*Schema) GetEnum

func (x *Schema) GetEnum() *Schema_Set

func (*Schema) GetFloat

func (x *Schema) GetFloat() *Schema_Atom

func (*Schema) GetInt

func (x *Schema) GetInt() *Schema_Atom

func (*Schema) GetObject

func (x *Schema) GetObject() *Schema_JSON

func (*Schema) GetSchema

func (m *Schema) GetSchema() isSchema_Schema

func (*Schema) GetStr

func (x *Schema) GetStr() *Schema_Sequence

func (*Schema) GetUint

func (x *Schema) GetUint() *Schema_Atom

func (*Schema) Normalize

func (s *Schema) Normalize() error

Normalize will normalize the Schema, returning an error if it is invalid.

func (*Schema) ProtoMessage

func (*Schema) ProtoMessage()

func (*Schema) ProtoReflect

func (x *Schema) ProtoReflect() protoreflect.Message

func (*Schema) Reset

func (x *Schema) Reset()

func (*Schema) String

func (x *Schema) String() string

func (*Schema) Zero

func (s *Schema) Zero() *Value

Zero produces a Value from this schema which is a valid 'zero' value (in the go sense)

type Schema_Array

type Schema_Array struct {
	Array *Schema_JSON `protobuf:"bytes,9,opt,name=array,proto3,oneof"`
}

type Schema_Atom

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

func (*Schema_Atom) Descriptor

func (*Schema_Atom) Descriptor() ([]byte, []int)

Deprecated: Use Schema_Atom.ProtoReflect.Descriptor instead.

func (*Schema_Atom) ProtoMessage

func (*Schema_Atom) ProtoMessage()

func (*Schema_Atom) ProtoReflect

func (x *Schema_Atom) ProtoReflect() protoreflect.Message

func (*Schema_Atom) Reset

func (x *Schema_Atom) Reset()

func (*Schema_Atom) String

func (x *Schema_Atom) String() string

type Schema_Bool

type Schema_Bool struct {
	Bool *Schema_Atom `protobuf:"bytes,4,opt,name=bool,proto3,oneof"`
}

type Schema_Bytes

type Schema_Bytes struct {
	Bytes *Schema_Sequence `protobuf:"bytes,6,opt,name=bytes,proto3,oneof"`
}

type Schema_Enum

type Schema_Enum struct {
	Enum *Schema_Set `protobuf:"bytes,7,opt,name=enum,proto3,oneof"` // populated with Value_Str
}

type Schema_Float

type Schema_Float struct {
	Float *Schema_Atom `protobuf:"bytes,3,opt,name=float,proto3,oneof"`
}

type Schema_Int

type Schema_Int struct {
	Int *Schema_Atom `protobuf:"bytes,1,opt,name=int,proto3,oneof"`
}

type Schema_JSON

type Schema_JSON struct {

	// restricts the maximum amount of bytes that a Value for this field may
	// take.
	MaxLength uint32 `protobuf:"varint,1,opt,name=max_length,json=maxLength,proto3" json:"max_length,omitempty"`
	// contains filtered or unexported fields
}

func (*Schema_JSON) Descriptor

func (*Schema_JSON) Descriptor() ([]byte, []int)

Deprecated: Use Schema_JSON.ProtoReflect.Descriptor instead.

func (*Schema_JSON) GetMaxLength

func (x *Schema_JSON) GetMaxLength() uint32

func (*Schema_JSON) ProtoMessage

func (*Schema_JSON) ProtoMessage()

func (*Schema_JSON) ProtoReflect

func (x *Schema_JSON) ProtoReflect() protoreflect.Message

func (*Schema_JSON) Reset

func (x *Schema_JSON) Reset()

func (*Schema_JSON) String

func (x *Schema_JSON) String() string

type Schema_Object

type Schema_Object struct {
	Object *Schema_JSON `protobuf:"bytes,8,opt,name=object,proto3,oneof"`
}

type Schema_Sequence

type Schema_Sequence struct {

	// restricts the maximum amount of bytes that a Value for this field may
	// take.
	MaxLength uint32 `protobuf:"varint,1,opt,name=max_length,json=maxLength,proto3" json:"max_length,omitempty"`
	// contains filtered or unexported fields
}

func (*Schema_Sequence) Descriptor

func (*Schema_Sequence) Descriptor() ([]byte, []int)

Deprecated: Use Schema_Sequence.ProtoReflect.Descriptor instead.

func (*Schema_Sequence) GetMaxLength

func (x *Schema_Sequence) GetMaxLength() uint32

func (*Schema_Sequence) ProtoMessage

func (*Schema_Sequence) ProtoMessage()

func (*Schema_Sequence) ProtoReflect

func (x *Schema_Sequence) ProtoReflect() protoreflect.Message

func (*Schema_Sequence) Reset

func (x *Schema_Sequence) Reset()

func (*Schema_Sequence) String

func (x *Schema_Sequence) String() string

type Schema_Set

type Schema_Set struct {

	// entry lists the possible tokens that this set can have.
	Entry []*Schema_Set_Entry `protobuf:"bytes,1,rep,name=entry,proto3" json:"entry,omitempty"`
	// contains filtered or unexported fields
}

func (*Schema_Set) Descriptor

func (*Schema_Set) Descriptor() ([]byte, []int)

Deprecated: Use Schema_Set.ProtoReflect.Descriptor instead.

func (*Schema_Set) GetEntry

func (x *Schema_Set) GetEntry() []*Schema_Set_Entry

func (*Schema_Set) Has

func (s *Schema_Set) Has(token string) bool

Has returns true iff the given token is a valid value for this enumeration.

func (*Schema_Set) Normalize

func (s *Schema_Set) Normalize() error

Normalize will normalize the Schema_Set, returning an error if it is invalid.

func (*Schema_Set) ProtoMessage

func (*Schema_Set) ProtoMessage()

func (*Schema_Set) ProtoReflect

func (x *Schema_Set) ProtoReflect() protoreflect.Message

func (*Schema_Set) Reset

func (x *Schema_Set) Reset()

func (*Schema_Set) String

func (x *Schema_Set) String() string

type Schema_Set_Entry

type Schema_Set_Entry struct {

	// Markdown-formatted documentation for this schema entry.
	Doc   string `protobuf:"bytes,1,opt,name=doc,proto3" json:"doc,omitempty"`
	Token string `protobuf:"bytes,2,opt,name=token,proto3" json:"token,omitempty"`
	// contains filtered or unexported fields
}

func (*Schema_Set_Entry) Descriptor

func (*Schema_Set_Entry) Descriptor() ([]byte, []int)

Deprecated: Use Schema_Set_Entry.ProtoReflect.Descriptor instead.

func (*Schema_Set_Entry) GetDoc

func (x *Schema_Set_Entry) GetDoc() string

func (*Schema_Set_Entry) GetToken

func (x *Schema_Set_Entry) GetToken() string

func (*Schema_Set_Entry) ProtoMessage

func (*Schema_Set_Entry) ProtoMessage()

func (*Schema_Set_Entry) ProtoReflect

func (x *Schema_Set_Entry) ProtoReflect() protoreflect.Message

func (*Schema_Set_Entry) Reset

func (x *Schema_Set_Entry) Reset()

func (*Schema_Set_Entry) String

func (x *Schema_Set_Entry) String() string

type Schema_Str

type Schema_Str struct {
	Str *Schema_Sequence `protobuf:"bytes,5,opt,name=str,proto3,oneof"`
}

type Schema_Uint

type Schema_Uint struct {
	Uint *Schema_Atom `protobuf:"bytes,2,opt,name=uint,proto3,oneof"`
}

type Specifier

type Specifier struct {
	TemplateName string            `protobuf:"bytes,1,opt,name=template_name,json=templateName,proto3" json:"template_name,omitempty"`
	Params       map[string]*Value `` /* 153-byte string literal not displayed */
	// contains filtered or unexported fields
}

func (*Specifier) Descriptor

func (*Specifier) Descriptor() ([]byte, []int)

Deprecated: Use Specifier.ProtoReflect.Descriptor instead.

func (*Specifier) GetParams

func (x *Specifier) GetParams() map[string]*Value

func (*Specifier) GetTemplateName

func (x *Specifier) GetTemplateName() string

func (*Specifier) Normalize

func (s *Specifier) Normalize() error

Normalize will normalize this Specifier

func (*Specifier) ProtoMessage

func (*Specifier) ProtoMessage()

func (*Specifier) ProtoReflect

func (x *Specifier) ProtoReflect() protoreflect.Message

func (*Specifier) Reset

func (x *Specifier) Reset()

func (*Specifier) String

func (x *Specifier) String() string

type Value

type Value struct {

	// Types that are assignable to Value:
	//	*Value_Int
	//	*Value_Uint
	//	*Value_Float
	//	*Value_Bool
	//	*Value_Str
	//	*Value_Bytes
	//	*Value_Object
	//	*Value_Array
	//	*Value_Null
	Value isValue_Value `protobuf_oneof:"value"`
	// contains filtered or unexported fields
}

Value defines a specific value for a parameter, and is used at Template expansion time.

func MustNewValue

func MustNewValue(v interface{}) *Value

MustNewValue creates a new *Value wrapping v, and panics if v is a bad type

func NewValue

func NewValue(v interface{}) (*Value, error)

NewValue creates a new *Value wrapping v.

Allowed types are:

* Any of the explicit *Value_Int - style types
* nil -> Null
* string -> String
* []byte -> Bytes
* int, int8, int16, int32, int64 -> Integer
* uint, uint8, uint16, uint32, uint64 -> Unsigned
* float32, float64 -> Float
* bool -> Boolean
* map[string]interface{} -> Object
* []interface{} -> Array

func (*Value) Check

func (v *Value) Check(s *Schema) error

Check ensures that this value conforms to the given schema.

func (*Value) Descriptor

func (*Value) Descriptor() ([]byte, []int)

Deprecated: Use Value.ProtoReflect.Descriptor instead.

func (*Value) GetArray

func (x *Value) GetArray() string

func (*Value) GetBool

func (x *Value) GetBool() bool

func (*Value) GetBytes

func (x *Value) GetBytes() []byte

func (*Value) GetFloat

func (x *Value) GetFloat() float64

func (*Value) GetInt

func (x *Value) GetInt() int64

func (*Value) GetNull

func (x *Value) GetNull() *emptypb.Empty

func (*Value) GetObject

func (x *Value) GetObject() string

func (*Value) GetStr

func (x *Value) GetStr() string

func (*Value) GetUint

func (x *Value) GetUint() uint64

func (*Value) GetValue

func (m *Value) GetValue() isValue_Value

func (*Value) IsNull

func (v *Value) IsNull() bool

IsNull returns true if this Value is the null value.

func (*Value) JSONRender

func (v *Value) JSONRender() string

JSONRender returns the to-be-injected string rendering of v.

func (*Value) Normalize

func (v *Value) Normalize() error

Normalize returns a non-nil error if the Value is invalid for its nominal type.

func (*Value) ProtoMessage

func (*Value) ProtoMessage()

func (*Value) ProtoReflect

func (x *Value) ProtoReflect() protoreflect.Message

func (*Value) Reset

func (x *Value) Reset()

func (*Value) String

func (x *Value) String() string

type Value_Array

type Value_Array struct {
	Array string `protobuf:"bytes,8,opt,name=array,proto3,oneof"`
}

func (*Value_Array) Check

func (v *Value_Array) Check(schema *Schema) error

Check returns nil iff this Value correctly parses as a JSON array.

func (*Value_Array) JSONRender

func (v *Value_Array) JSONRender() string

JSONRender returns a rendering of this JSON array as JSON. This is a direct return of the JSON encoded string; no validation is done. To check that the contained string is valid, use the Valid() method.

func (*Value_Array) Normalize

func (v *Value_Array) Normalize() error

Normalize returns nil iff this Value correctly parses as a JSON array.

type Value_Bool

type Value_Bool struct {
	Bool bool `protobuf:"varint,4,opt,name=bool,proto3,oneof"`
}

func (*Value_Bool) JSONRender

func (v *Value_Bool) JSONRender() string

JSONRender returns a rendering of this bool as JSON, e.g. go value true renders as `true`.

type Value_Bytes

type Value_Bytes struct {
	Bytes []byte `protobuf:"bytes,6,opt,name=bytes,proto3,oneof"`
}

func (*Value_Bytes) Check

func (v *Value_Bytes) Check(schema *Schema) error

Check returns nil iff this Value meets the max length criteria.

func (*Value_Bytes) JSONRender

func (v *Value_Bytes) JSONRender() string

JSONRender returns a rendering of these bytes as JSON, e.g. go value []byte("foo") renders as `"Zm9v"`.

type Value_Float

type Value_Float struct {
	Float float64 `protobuf:"fixed64,3,opt,name=float,proto3,oneof"`
}

func (*Value_Float) JSONRender

func (v *Value_Float) JSONRender() string

JSONRender returns a rendering of this float as JSON, e.g. go value 1.23 renders as `1.23`.

type Value_Int

type Value_Int struct {
	Int int64 `protobuf:"varint,1,opt,name=int,proto3,oneof"`
}

func (*Value_Int) JSONRender

func (v *Value_Int) JSONRender() string

JSONRender returns a rendering of this int as JSON, e.g. go value 100 renders as `100`. If the absolute value is > 2**53, this will render it as a string.

Integers render as strings to avoid encoding issues in JSON, which only supports double-precision floating point numbers.

type Value_Null

type Value_Null struct {
	Null *emptypb.Empty `protobuf:"bytes,9,opt,name=null,proto3,oneof"`
}

func (*Value_Null) JSONRender

func (v *Value_Null) JSONRender() string

JSONRender returns a rendering of null. This always returns `null`.

type Value_Object

type Value_Object struct {
	Object string `protobuf:"bytes,7,opt,name=object,proto3,oneof"`
}

func (*Value_Object) Check

func (v *Value_Object) Check(schema *Schema) error

Check returns nil iff this Value correctly parses as a JSON object.

func (*Value_Object) JSONRender

func (v *Value_Object) JSONRender() string

JSONRender returns a rendering of this JSON object as JSON. This is a direct return of the JSON encoded string; no validation is done. To check that the contained string is valid, use the Valid() method.

func (*Value_Object) Normalize

func (v *Value_Object) Normalize() error

Normalize returns nil iff this Value correctly parses as a JSON object.

type Value_Str

type Value_Str struct {
	Str string `protobuf:"bytes,5,opt,name=str,proto3,oneof"`
}

func (*Value_Str) Check

func (v *Value_Str) Check(schema *Schema) error

Check returns nil iff this Value meets the max length criteria, and/or can be used to fill an enumeration value from the provided schema.

func (*Value_Str) JSONRender

func (v *Value_Str) JSONRender() string

JSONRender returns a rendering of this string as JSON, e.g. go value "foo" renders as `"foo"`.

type Value_Uint

type Value_Uint struct {
	Uint uint64 `protobuf:"varint,2,opt,name=uint,proto3,oneof"`
}

func (*Value_Uint) JSONRender

func (v *Value_Uint) JSONRender() string

JSONRender returns a rendering of this uint as JSON, e.g. go value 100 renders as `"100"`.

Unsigns render as strings to avoid encoding issues in JSON, which only supports double-precision floating point numbers.