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
- type BindArgs
- 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
- type ValueSeries
- type ValueStream
- type Var
Examples ¶
Constants ¶
This section is empty.
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 ¶
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 ¶
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.
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.
type DebugDumper ¶
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 ¶
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 ¶
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) DebugName ¶
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) Nest ¶
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.
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 ¶
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 ¶
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.
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) BindConst ¶
BindConst is like Bind, but bypasses the trust level check. To guarantee safety, BindConst only accepts string literals.