bindings

Documentation

Overview

Example

var m Map

userName := m.Declare("author_name", safe.TextSafe)
articleURL := m.Declare("article_url", safe.URLSafe)
articleHTML := m.Declare("article_html", safe.HTMLSafe)

comments := m.Nest("comments")
commentHTML := comments.Declare("comment_html", safe.HTMLSafe)
commentAuthor := comments.Declare("author", safe.TextSafe)

values := m.MustBind(
	userName.BindConst("adam"),
	articleURL.BindConst("https://something.com"),
	articleHTML.BindConst("<p>...</p>"),
	comments.BindSeries(
		comments.MustBind(
			commentHTML.BindConst("<p>Hello!</p>"),
			commentAuthor.BindConst("Peter")),
		comments.MustBind(
			commentHTML.BindConst("<p>Hello!</p>"),
			commentAuthor.BindConst("Paul"))))

commentStream := values.GetStream(comments)
firstCommentValue := commentStream.Stream()()
fmt.Printf("First comment's author: %s", firstCommentValue.GetString(commentAuthor))

Output:

First comment's author: Peter

Index

• Variables
• func Bind(vm *ValueMap, args ...BindArg) error
• func DebugString(dd DebugDumper) string
• func GetStringByName(vm *ValueMap, name string) string
• type BindArg
  • func (a BindArg) DebugDump(w io.Writer, depth int)
  • func (a BindArg) String() string
• type BindArgs
  • func (a BindArgs) DebugDump(w io.Writer, depth int)
• type DebugDumper
• type Map
  • func (m *Map) Attach(v Var, level safe.TrustLevel) Var
  • func (m *Map) Bind(values ...Value) (*ValueMap, error)
  • func (m *Map) BindSeries(maps ...*ValueMap) Value
  • func (m *Map) BindStream(stream ValueStream) Value
  • func (m *Map) DebugDump(w io.Writer, depth int)
  • func (m *Map) DebugName() string
  • func (m *Map) Declare(name string, level safe.TrustLevel) Var
  • func (m *Map) MustBind(values ...Value) *ValueMap
  • func (m *Map) Nest(name string) *Map
  • func (m *Map) Root() bool
  • func (m *Map) String() string
• type Value
• type ValueIterator
• type ValueMap
  • func (vm *ValueMap) DebugDump(w io.Writer, depth int)
  • func (vm *ValueMap) GetStream(m *Map) ValueStream
  • func (vm *ValueMap) GetString(v Var) string
  • func (vm *ValueMap) Set(v Value) error
  • func (vm *ValueMap) String() string
• type ValueSeries
  • func (s ValueSeries) Stream() ValueIterator
• type ValueStream
• type Var
  • func Declare(name string, l safe.TrustLevel) Var
  • func (v Var) Attached() bool
  • func (v Var) Bind(ss safe.String) Value
  • func (v Var) BindConst(value constString) Value
  • func (v Var) Check(required safe.TrustLevel) bool
  • func (v Var) String() string

Examples

• Package

Variables

var ErrUndefined = errors.New("undefined")

ErrUndefined is returned when the ValueMap cannot set a value, because the associated Var or nested Map aren't declared in ValueMap.Vars.

var ZeroVar = Var{}

ZeroVar is a an empty Var.

Functions

func Bind

func Bind(vm *ValueMap, args ...BindArg) error

Bind applies the provided bindings to the ValueMap. This is the same as calling ValueMap.Set repeatedly, but allows the caller to conveniently specify entire nested structures in one call.

See BindArg for more.

func DebugString

func DebugString(dd DebugDumper) string

DebugString converts a DebugDumper to a verbose string representation for debugging or human-readable diffing.

In particular, this is useful with cmp.Transformer to generate human-readable diffs in tests. For example:

cmp.Transformer(func(vm *ValueMap) string { return DebugString(vm) })

func GetStringByName

func GetStringByName(vm *ValueMap, name string) string

GetStringByName looks up the value of a Var with the given name. Doesn't distinguish between empty string and no value. If the Var was previously undeclared, then this will have the side effect of declaring it in the associated Map.

This is slower than ValueMap.GetString and should only be used for debugging.

Types

type BindArg

type BindArg struct {
	// Fields to specify a safe string value.
	Var   Var
	Value safe.String

	// Fields to specify a nested ValueStream.
	NestedMap  *Map
	NestedRows [][]BindArg

	// Optional: if Var/NestedMap are not specified, lookup or declare using
	// this name.
	Name string
	// Optional: if specified, Var will be promoted to safe.Max of this and its
	// existing trust requirement.
	TrustRequirement safe.TrustLevel
}

BindArg specifies a single string or nested map to set on a ValueMap. Each BindArg must specify either a string or a ValueStream.

To specify a string, set Value to a non-nil safe.String and Var to a variable on which it should be set. If Var is no attached, it will become attached to the ValueMap passed to Bind.

To specify a ValueStream, set NestedRows such that each slice of BindArgs (each row) contains valid arguments for Bind on the NestedMap. Set NestedMap to the corresponding Map.

As a convenience, if Var or NestedMap are not available, but Name is a non-empty string, then Bind will lookup or declare the Var or Map automatically. This is slower than providing the Var or NestedMap.

Optionally, if TrustRequirement is specified, it will be treated as an extra requirement on top of the Var's requirement, and Var will be promoted to safe.Max of the two.

func (BindArg) DebugDump

func (a BindArg) DebugDump(w io.Writer, depth int)

DebugDump writes a verbose description of the BindArg to the writer. Depth can be used to indent output with tabs.

func (BindArg) String

func (a BindArg) String() string

type BindArgs

type BindArgs []BindArg

BindArgs is a slice of BindArg values. Its only advantage over a plain slice is that it knows how to DebugDump itself, and so can be passed to functions that accept DebugDumper.

func (BindArgs) DebugDump

func (a BindArgs) DebugDump(w io.Writer, depth int)

DebugDump writes a verbose description of the BindArgs to the writer.

type DebugDumper

type DebugDumper interface {
	DebugDump(w io.Writer, depth int)
}

DebugDumper knows how to print a verbose description of itself to a provided writer. The depth argument controls indentation.

type Map

type Map struct {
	// If true, then the Map won't accept Bind arguments for non-existent Vars.
	Strict bool
	// contains filtered or unexported fields
}

Map is a collection of Vars and nested Maps. Each html5.Template uses a single root Map to hold all the dynamic elements of the page, and their requisite levels of trust.

Maps are "instantiated" into ValueMaps, which specify a set of values for the Vars and nested Maps in the Map.

func (*Map) Attach

func (m *Map) Attach(v Var, level safe.TrustLevel) Var

Attach returns a copy of the provided free Var that's associated to this Map.

func (*Map) Bind

func (m *Map) Bind(values ...Value) (*ValueMap, error)

Bind creates a ValueMap and sets the provided values, if any. The Values must be associated to Vars associated to this Map, otherwise Bind will panic.

func (*Map) BindSeries

func (m *Map) BindSeries(maps ...*ValueMap) Value

BindSeries is like BindStream, but constructs a ValueStream for the caller.

func (*Map) BindStream

func (m *Map) BindStream(stream ValueStream) Value

BindStream binds the provided ValueStream to this Map, returning a Value that can be set on a parent ValueMap.

func (*Map) DebugDump

func (m *Map) DebugDump(w io.Writer, depth int)

DebugDump writes a detailed description of this Map to the writer.

func (*Map) DebugName

func (m *Map) DebugName() string

DebugName returns a name of this map, or "root" if it isn't nested. Used for debugging only.

func (*Map) Declare

func (m *Map) Declare(name string, level safe.TrustLevel) Var

Declare a Var with the given name, at the given trust level.

func (*Map) MustBind

func (m *Map) MustBind(values ...Value) *ValueMap

MustBind is like Bind, but panics on error.

func (*Map) Nest

func (m *Map) Nest(name string) *Map

Nest creates a nested Map with the given name and returns it. Nested Maps can be used to create ValueStreams, which specify repeated sections in the HTML page. (For example, comments under an article.) Maps can be nested to arbitrary depth.

func (*Map) Root

func (m *Map) Root() bool

Root returns whether this Map is the top-most Map in the hierarchy, or a nested Map.

func (*Map) String

func (m *Map) String() string

type Value

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

Value specifies a single value for the ValueMap - it can be either a string value of a Var, or a ValueStream value of a nested Map.

type ValueIterator

type ValueIterator func() *ValueMap

ValueIterator returns a new ValueSet on each call. It returns nil when there are no more values.

type ValueMap

type ValueMap struct {
	Vars *Map
	// contains filtered or unexported fields
}

ValueMap associates Vars to their Values. It may also contain nested ValueMaps, much like Map can contain nested Maps.

A note on performance:

This is a specialized, high-performance container. On simple lookups and inserts, it outperforms native go maps by a factor of 3. This is possible because the ValueMap knows ahead of time all the keys (Vars) that may set, and so it can preallocate sufficient space and doesn't have to deal with hashing. To realize this performance gain, you must use this package idiomatically - declare Maps on application startup, and then use the same vars throughout the lifetime of the program.

func (*ValueMap) DebugDump

func (vm *ValueMap) DebugDump(w io.Writer, depth int)

DebugDump writes a verbose description of this ValueMap and its values to the provided writer. Depth can be used to indent the output with tabs.

func (*ValueMap) GetStream

func (vm *ValueMap) GetStream(m *Map) ValueStream

GetStream returns the ValueStream associated with the Map. The Map must be a nested member of this ValueMap.Vars, otherwise the result will be bogus.

func (*ValueMap) GetString

func (vm *ValueMap) GetString(v Var) string

GetString returns the string value for the Var, which must be associated to this ValueMap.Vars, otherwise GetString will panic.

GetString doesn't distinguish between empty strings and missing values.

func (*ValueMap) Set

func (vm *ValueMap) Set(v Value) error

Set the Value on this ValueMap. The Value must be associated to a Var or nested Map declared in this ValueMap.Vars, otherwise Set will panic.

func (*ValueMap) String

func (vm *ValueMap) String() string

type ValueSeries

type ValueSeries []*ValueMap

ValueSeries is a convenient implementation of ValueSetStream, which is backed by a slice of ValueSets.

func (ValueSeries) Stream

func (s ValueSeries) Stream() ValueIterator

Stream returns an iterators that returns ValueSets from the slice one at a time.

type ValueStream

type ValueStream interface {
	// Stream returns an iterator at position zero. Each call to Stream must
	// return an iterator that yields the same values in the same order.
	Stream() ValueIterator
}

ValueStream is a collection of ValueMaps used to generate repeated subsections of an HTML page. A convenient implementation is ValueSeries, but this interface can also be implemented such that values are loaded on the fly, to avoid using too much memory when generating large HTML pages.

type Var

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

Var uniquelly names a string variable and its required trust level.

func Declare

func Declare(name string, l safe.TrustLevel) Var

Declare an unnatached Var as a placeholder. Unnatached Vars cannot be used with ValueMaps, but can be converted to attached Vars using Map.Attach.

func (Var) Attached

func (v Var) Attached() bool

Attached returns whether this Var is attached to a Map.

func (Var) Bind

func (v Var) Bind(ss safe.String) Value

Bind returns a Value created by binding the provided string to this Var.

func (Var) BindConst

func (v Var) BindConst(value constString) Value

BindConst is like Bind, but bypasses the trust level check. To guarantee safety, BindConst only accepts string literals.

func (Var) Check

func (v Var) Check(required safe.TrustLevel) bool

Check whether this Var's trust level can satisfy the required trust level.

func (Var) String

func (v Var) String() string