README ¶
Jet Template Engine for Go
Jet is a template engine developed to be easy to use, powerful, dynamic, yet secure and very fast.
- supports template inheritance with
extends
,import
andinclude
statements - descriptive error messages with filename and line number
- auto-escape
- simple C-like expressions
- very fast execution – Jet can execute templates faster than some pre-compiled template engines
- very light in terms of allocations and memory footprint
- simple and familiar syntax
- easy to use
You can find the documentation in the wiki.
Upgrade to v2
The last release of v1 was v1.2 which is available at https://github.com/CloudyKit/jet/releases/tag/v1.2 and the tag v1.2.
To upgrade to v2 a few updates to your templates are necessary – these are explained in the upgrade guide.
IntelliJ Plugin
If you use IntelliJ there is a plugin available at https://github.com/jhsx/GoJetPlugin. There is also a very good Go plugin for IntelliJ – see https://github.com/go-lang-plugin-org/go-lang-idea-plugin. GoJetPlugin + Go-lang-idea-plugin = happiness!
Examples
You can find examples in the wiki.
Running the example application
An example application is available in the repository. Use go get -u github.com/CloudyKit/jet
or clone the repository into $GOPATH/github.com/CloudyKit/jet
, then do:
$ cd examples/todos; go run main.go
Faster than some pre-compiled template engines
The benchmark consists of a range over a slice of data printing the values, the benchmark is based on https://github.com/SlinSo/goTemplateBenchmark, Jet performs better than all template engines without pre-compilation, and performs better than gorazor, Ftmpl and Egon, all of which are pre-compiled to Go.
go 1.6.2
PASS
BenchmarkEgonSlinso-4 2000000 989 ns/op 517 B/op 0 allocs/op
BenchmarkQuicktemplate-4 1000000 1004 ns/op 999 B/op 0 allocs/op
BenchmarkEgo-4 1000000 2137 ns/op 603 B/op 8 allocs/op
BenchmarkJet-4 500000 2798 ns/op 536 B/op 0 allocs/op
BenchmarkJetHTML-4 500000 2822 ns/op 536 B/op 0 allocs/op
BenchmarkGorazor-4 500000 3028 ns/op 613 B/op 11 allocs/op
BenchmarkFtmpl-4 500000 3192 ns/op 1152 B/op 12 allocs/op
BenchmarkEgon-4 300000 4673 ns/op 1172 B/op 22 allocs/op
BenchmarkKasia-4 200000 6902 ns/op 1789 B/op 26 allocs/op
BenchmarkSoy-4 200000 7144 ns/op 1684 B/op 26 allocs/op
BenchmarkMustache-4 200000 8213 ns/op 1568 B/op 28 allocs/op
BenchmarkPongo2-4 200000 9989 ns/op 2949 B/op 46 allocs/op
BenchmarkGolang-4 100000 16284 ns/op 2039 B/op 38 allocs/op
BenchmarkAmber-4 100000 17208 ns/op 2050 B/op 39 allocs/op
BenchmarkHandlebars-4 50000 29864 ns/op 4258 B/op 90 allocs/op
BenchmarkAce-4 30000 40771 ns/op 5710 B/op 77 allocs/op
BenchmarkDamsel-4 20000 95947 ns/op 11160 B/op 165 allocs/op
ok github.com/SlinSo/goTemplateBenchmark 34.384s
go tip
BenchmarkQuicktemplate-4 2000000 916 ns/op 999 B/op 0 allocs/op
BenchmarkEgonSlinso-4 2000000 1074 ns/op 517 B/op 0 allocs/op
BenchmarkEgo-4 1000000 1822 ns/op 603 B/op 8 allocs/op
BenchmarkJetHTML-4 500000 2627 ns/op 536 B/op 0 allocs/op
BenchmarkJet-4 500000 2652 ns/op 536 B/op 0 allocs/op
BenchmarkFtmpl-4 500000 2700 ns/op 1152 B/op 12 allocs/op
BenchmarkGorazor-4 500000 2858 ns/op 613 B/op 11 allocs/op
BenchmarkEgon-4 500000 4023 ns/op 827 B/op 22 allocs/op
BenchmarkSoy-4 300000 5590 ns/op 1784 B/op 26 allocs/op
BenchmarkKasia-4 200000 6487 ns/op 1789 B/op 26 allocs/op
BenchmarkMustache-4 200000 6515 ns/op 1568 B/op 28 allocs/op
BenchmarkPongo2-4 200000 7602 ns/op 2949 B/op 46 allocs/op
BenchmarkAmber-4 100000 13942 ns/op 2050 B/op 39 allocs/op
BenchmarkGolang-4 100000 16945 ns/op 2039 B/op 38 allocs/op
BenchmarkHandlebars-4 100000 20152 ns/op 4258 B/op 90 allocs/op
BenchmarkAce-4 50000 33091 ns/op 5509 B/op 77 allocs/op
BenchmarkDamsel-4 20000 86340 ns/op 11159 B/op 165 allocs/op
PASS
ok github.com/SlinSo/goTemplateBenchmark 36.200s
Contributing
All contributions are welcome – if you find a bug please report it.
Thanks
- @golang developers for the awesome language and the standard library
- @SlinSo for the benchmarks that I used as a base to show the results above
Documentation ¶
Index ¶
- func IsEmptyTree(n Node) bool
- type ActionNode
- type AdditiveExprNode
- type Arguments
- type BlockNode
- type BlockParameter
- type BlockParameterList
- type BoolNode
- type BranchNode
- type CallExprNode
- type ChainNode
- type CommandNode
- type ComparativeExprNode
- type Expression
- type FieldNode
- type Func
- type IdentifierNode
- type IfNode
- type IncludeNode
- type IndexExprNode
- type ListNode
- type Loader
- type LogicalExprNode
- type MultiplicativeExprNode
- type NilNode
- type Node
- type NodeBase
- type NodeType
- type NotExprNode
- type NumberNode
- type NumericComparativeExprNode
- type OSFileSystemLoader
- type PipeNode
- type Pos
- type RangeNode
- type Ranger
- type Renderer
- type RendererFunc
- type Runtime
- func (r *Runtime) Context() reflect.Value
- func (state *Runtime) Resolve(name string) reflect.Value
- func (state *Runtime) Set(name string, val interface{})
- func (w Runtime) Write(b []byte) (int, error)
- func (st *Runtime) YieldBlock(name string, context interface{})
- func (st *Runtime) YieldTemplate(name string, context interface{})
- type SafeWriter
- type Set
- func (s *Set) AddGlobal(key string, i interface{}) *Set
- func (s *Set) AddGlobalFunc(key string, fn Func) *Set
- func (s *Set) AddGopathPath(path string)
- func (s *Set) AddPath(path string)
- func (s *Set) GetTemplate(name string) (template *Template, err error)
- func (s *Set) LoadTemplate(name, content string) (template *Template, err error)
- func (a *Set) LookupGlobal(key string) (val interface{}, found bool)
- func (s *Set) Parse(name, content string) (*Template, error)
- func (s *Set) SetDevelopmentMode(b bool) *Set
- type SetNode
- type SliceExprNode
- type StringNode
- type Template
- type TernaryExprNode
- type TextNode
- type Translator
- type VarMap
- type YieldNode
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsEmptyTree ¶
IsEmptyTree reports whether this tree (node) is empty of everything but space.
Types ¶
type ActionNode ¶
ActionNode holds an action (something bounded by delimiters). Control actions have their own nodes; ActionNode represents simple ones such as field evaluations and parenthesized pipelines.
func (*ActionNode) String ¶
func (a *ActionNode) String() string
type AdditiveExprNode ¶
type AdditiveExprNode struct {
// contains filtered or unexported fields
}
AdditiveExprNode represents an add or subtract expression ex: expression ( '+' | '-' ) expression
type Arguments ¶
type Arguments struct {
// contains filtered or unexported fields
}
Arguments holds the arguments passed to jet.Func.
func (*Arguments) NumOfArguments ¶
NumOfArguments returns the number of arguments
func (*Arguments) RequireNumOfArguments ¶
RequireNumOfArguments panics if the number of arguments is not in the range specified by min and max. In case there is no minimum pass -1, in case there is no maximum pass -1 respectively.
type BlockNode ¶
type BlockNode struct { NodeBase //The line number in the input. Deprecated: Kept for compatibility. Name string //The name of the template (unquoted). Parameters *BlockParameterList Expression Expression //The command to evaluate as dot for the template. List *ListNode Content *ListNode }
BlockNode represents a {{block }} action.
type BlockParameter ¶
type BlockParameter struct { Identifier string Expression Expression }
type BlockParameterList ¶
type BlockParameterList struct { NodeBase List []BlockParameter }
func (*BlockParameterList) Param ¶
func (bplist *BlockParameterList) Param(name string) (Expression, int)
func (*BlockParameterList) String ¶
func (bplist *BlockParameterList) String() (str string)
type BranchNode ¶
type BranchNode struct { NodeBase Set *SetNode Expression Expression List *ListNode ElseList *ListNode }
BranchNode is the common representation of if, range, and with.
func (*BranchNode) String ¶
func (b *BranchNode) String() string
type CallExprNode ¶
type CallExprNode struct { NodeBase BaseExpr Expression Args []Expression }
CallExprNode represents a call expression ex: expression '(' (expression (',' expression)* )? ')'
func (*CallExprNode) String ¶
func (s *CallExprNode) String() string
type ChainNode ¶
ChainNode holds a term followed by a chain of field accesses (identifier starting with '.'). The names may be chained ('.x.y'). The periods are dropped from each ident.
type CommandNode ¶
type CommandNode struct { NodeBase Call bool BaseExpr Expression Args []Expression }
CommandNode holds a command (a pipeline inside an evaluating action).
func (*CommandNode) String ¶
func (c *CommandNode) String() string
type ComparativeExprNode ¶
type ComparativeExprNode struct {
// contains filtered or unexported fields
}
ComparativeExprNode represents a comparative expression ex: expression ( '==' | '!=' ) expression
type Expression ¶
type Expression interface { Node }
type FieldNode ¶
FieldNode holds a field (identifier starting with '.'). The names may be chained ('.x.y'). The period is dropped from each ident.
type Func ¶
Func function implementing this type is called directly, which is faster than calling through reflect. If a function is being called many times in the execution of a template, you may consider implementing a wrapper for that function implementing a Func.
type IdentifierNode ¶
IdentifierNode holds an identifier.
func (*IdentifierNode) String ¶
func (i *IdentifierNode) String() string
type IfNode ¶
type IfNode struct {
BranchNode
}
IfNode represents an {{if}} action and its commands.
type IncludeNode ¶
type IncludeNode struct { NodeBase Name Expression Expression Expression }
IncludeNode represents a {{include }} action.
func (*IncludeNode) String ¶
func (t *IncludeNode) String() string
type IndexExprNode ¶
type IndexExprNode struct { NodeBase Base Expression Index Expression }
func (*IndexExprNode) String ¶
func (s *IndexExprNode) String() string
type Loader ¶
type Loader interface { // Open opens the underlying reader with template content. Open(name string) (io.ReadCloser, error) // Exists checks for template existence and returns full path. Exists(name string) (string, bool) }
Loader is a minimal interface required for loading templates.
type LogicalExprNode ¶
type LogicalExprNode struct {
// contains filtered or unexported fields
}
LogicalExprNode represents a boolean expression, 'and' or 'or' ex: expression ( '&&' | '||' ) expression
type MultiplicativeExprNode ¶
type MultiplicativeExprNode struct {
// contains filtered or unexported fields
}
MultiplicativeExprNode represents a multiplication, division, or module expression ex: expression ( '*' | '/' | '%' ) expression
type NilNode ¶
type NilNode struct {
NodeBase
}
NilNode holds the special identifier 'nil' representing an untyped nil constant.
type NodeType ¶
type NodeType int
NodeType identifies the type of a parse tree node.
const ( NodeText NodeType = iota //Plain text. NodeAction //A non-control action such as a field evaluation. NodeChain //A sequence of field accesses. NodeCommand //An element of a pipeline. NodeField //A field or method name. NodeIdentifier //An identifier; always a function name. NodeIf //An if action. NodeList //A list of Nodes. NodePipe //A pipeline of commands. NodeRange //A range action. //NodeWith //A with action. NodeBlock NodeInclude NodeYield NodeSet NodeString //A string constant. NodeNil //An untyped nil constant. NodeNumber //A numerical constant. NodeBool //A boolean constant. NodeAdditiveExpr NodeMultiplicativeExpr NodeComparativeExpr NodeNumericComparativeExpr NodeLogicalExpr NodeCallExpr NodeNotExpr NodeTernaryExpr NodeIndexExpr NodeSliceExpr )
type NotExprNode ¶
type NotExprNode struct { NodeBase Expr Expression }
NotExprNode represents a negate expression ex: '!' expression
func (*NotExprNode) String ¶
func (s *NotExprNode) String() string
type NumberNode ¶
type NumberNode struct { NodeBase IsInt bool //Number has an integral value. IsUint bool //Number has an unsigned integral value. IsFloat bool //Number has a floating-point value. IsComplex bool //Number is complex. Int64 int64 //The signed integer value. Uint64 uint64 //The unsigned integer value. Float64 float64 //The floating-point value. Complex128 complex128 //The complex value. Text string //The original textual representation from the input. }
NumberNode holds a number: signed or unsigned integer, float, or complex. The value is parsed and stored under all the types that can represent the value. This simulates in a small amount of code the behavior of Go's ideal constants.
func (*NumberNode) String ¶
func (n *NumberNode) String() string
type NumericComparativeExprNode ¶
type NumericComparativeExprNode struct {
// contains filtered or unexported fields
}
NumericComparativeExprNode represents a numeric comparative expression ex: expression ( '<' | '>' | '<=' | '>=' ) expression
type OSFileSystemLoader ¶
type OSFileSystemLoader struct {
// contains filtered or unexported fields
}
OSFileSystemLoader implements Loader interface using OS file system (os.File).
func NewOSFileSystemLoader ¶
func NewOSFileSystemLoader(paths ...string) *OSFileSystemLoader
NewOSFileSystemLoader returns an initialized OSFileSystemLoader.
func (*OSFileSystemLoader) AddGopathPath ¶
func (l *OSFileSystemLoader) AddGopathPath(path string)
AddGopathPath adds a path located in the GOPATH. Example: l.AddGopathPath("github.com/CloudyKit/jet/example/views")
func (*OSFileSystemLoader) AddPath ¶
func (l *OSFileSystemLoader) AddPath(path string)
AddPath adds the path to the internal list of paths searched when loading templates.
func (*OSFileSystemLoader) Exists ¶
func (l *OSFileSystemLoader) Exists(name string) (string, bool)
Exists checks if the template name exists by walking the list of template paths returns string with the full path of the template and bool true if the template file was found
func (*OSFileSystemLoader) Open ¶
func (l *OSFileSystemLoader) Open(name string) (io.ReadCloser, error)
Open opens a file from OS file system.
type PipeNode ¶
type PipeNode struct { NodeBase //The line number in the input. Deprecated: Kept for compatibility. Cmds []*CommandNode //The commands in lexical order. }
PipeNode holds a pipeline with optional declaration
type Pos ¶
type Pos int
Pos represents a byte position in the original input text from which this template was parsed.
type RangeNode ¶
type RangeNode struct {
BranchNode
}
RangeNode represents a {{range}} action and its commands.
type Ranger ¶
Ranger a value implementing a ranger interface is able to iterate on his value and can be used directly in a range statement
type Renderer ¶
type Renderer interface {
Render(*Runtime)
}
Renderer any resulting value from an expression in an action that implements this interface will not be printed, instead, we will invoke his Render() method which will be responsible to render his self
type RendererFunc ¶
type RendererFunc func(*Runtime)
RendererFunc func implementing interface Renderer
func (RendererFunc) Render ¶
func (renderer RendererFunc) Render(r *Runtime)
type Runtime ¶
type Runtime struct {
// contains filtered or unexported fields
}
Runtime this type holds the state of the execution of an template
func (*Runtime) YieldBlock ¶
YieldBlock yields a block in the current context, will panic if the context is not available
func (*Runtime) YieldTemplate ¶
YieldTemplate yields a template same as include
type SafeWriter ¶
SafeWriter escapee func. Functions implementing this type will write directly into the writer, skipping the escape phase; use this type to create special types of escapee funcs.
type Set ¶
type Set struct {
// contains filtered or unexported fields
}
Set is responsible to load,invoke parse and cache templates and relations every jet template is associated with one set. create a set with jet.NewSet(escapeeFn) returns a pointer to the Set
func NewHTMLSet ¶
NewHTMLSet creates a new set, dirs is a list of directories to be searched for templates
func NewHTMLSetLoader ¶
NewHTMLSetLoader creates a new set with custom Loader
func NewSet ¶
func NewSet(escapee SafeWriter, dirs ...string) *Set
NewSet creates a new set, dirs is a list of directories to be searched for templates
func NewSetLoader ¶
func NewSetLoader(escapee SafeWriter, loader Loader) *Set
NewSetLoader creates a new set with custom Loader
func (*Set) AddGopathPath ¶
AddGopathPath add path based on GOPATH env to the lookup list, when loading a template the Set will look into the lookup list for the file matching the provided name.
func (*Set) AddPath ¶
AddPath add path to the lookup list, when loading a template the Set will look into the lookup list for the file matching the provided name.
func (*Set) LoadTemplate ¶
func (*Set) LookupGlobal ¶
func (*Set) Parse ¶
Parse parses the template, this method will link the template to the set but not the set to
func (*Set) SetDevelopmentMode ¶
SetDevelopmentMode set's development mode on/off, in development mode template will be recompiled on every run
type SetNode ¶
type SetNode struct { NodeBase Let bool IndexExprGetLookup bool Left []Expression Right []Expression }
SetNode represents a set action, ident( ',' ident)* '=' expression ( ',' expression )*
type SliceExprNode ¶
type SliceExprNode struct { NodeBase Base Expression Index Expression EndIndex Expression }
func (*SliceExprNode) String ¶
func (s *SliceExprNode) String() string
type StringNode ¶
type StringNode struct { NodeBase Quoted string //The original text of the string, with quotes. Text string //The string, after quote processing. }
StringNode holds a string constant. The value has been "unquoted".
func (*StringNode) String ¶
func (s *StringNode) String() string
type Template ¶
type Template struct { Name string // name of the template represented by the tree. ParseName string // name of the top-level template during parsing, for error messages. Root *ListNode // top-level root of the tree. // contains filtered or unexported fields }
Template is the representation of a single parsed template.
func (*Template) ExecuteI18N ¶
type TernaryExprNode ¶
type TernaryExprNode struct { NodeBase Boolean, Left, Right Expression }
TernaryExprNod represents a ternary expression, ex: expression '?' expression ':' expression
func (*TernaryExprNode) String ¶
func (s *TernaryExprNode) String() string
type Translator ¶
type YieldNode ¶
type YieldNode struct { NodeBase //The line number in the input. Deprecated: Kept for compatibility. Name string //The name of the template (unquoted). Parameters *BlockParameterList Expression Expression //The command to evaluate as dot for the template. Content *ListNode IsContent bool }
YieldNode represents a {{yield}} action
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
examples
|
|
asset_packaging
+Build ignore
|
+Build ignore |
todos
+Build ignore
|
+Build ignore |
loaders
|
|