hero

package module
v0.0.1 Latest Latest
Warning

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

 Go to latest Published: Feb 20, 2017 License: Apache-2.0 Imports: 10 Imported by: 0

README

Hero

Hero is a handy, fast and powerful go template engine, which pre-compiles the html templates to go code. It has been used in production environment in bthub.io.

GoDoc Go Report Card Travis CI

中文文档

Features

  • High performance.
  • Easy to use.
  • Powerful. template Extend and Include supported.
  • Auto compiling when files change.

Performance

Hero is the fastest and least-memory used among currently known template engines in the benchmark. The data of chart comes from https://github.com/SlinSo/goTemplateBenchmark. You can find more details and benchmarks from that project.

Install

go get github.com/shiyanhui/hero
go get github.com/shiyanhui/hero/hero

# Hero needs `goimports` to format the generated codes.
# So if you have not installed `goimports`, please install it.
go get golang.org/x/tools/cmd/goimports

Usage

hero [options]

options:
	- source:  the html template file or dir, default is current dir.
	- dest:    generated golang files dir, it will be the same with source if not set.
	- pkgname: the generated template package name, default is `template`.
	- watch:   whether auto compile when the source files change.

example:
	hero -source="./"
	hero -source="$GOPATH/src/app/template" -watch

Quick Start

Assume that we are going to render a user list userlist.html. index.html is the layout, and user.html is an item in the list.

And assumes that they are all under $GOPATH/src/app/template

index.html
<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
    </head>

    <body>
        <%@ body { %>
        <% } %>
    </body>
</html>
userlist.html
<%: func UserList(userList []string, buffer *bytes.Buffer) %>

<%~ "index.html" %>

<%@ body { %>
    <% for _, user := range userList { %>
        <ul>
            <%+ "user.html" %>
        </ul>
    <% } %>
<% } %>
user.html
<li>
    <%= user %>
</li>

Then we compile the templates to go code.

hero -source="$GOPATH/src/app/template"

We will get three new .go files under $GOPATH/src/app/template, i.e. index.html.go, user.html.go and userlist.html.go.

Then we write a http server in $GOPATH/src/app/main.go.

main.go
package main

import (
    "bytes"
	"net/http"

	"app/template"
)

func main() {
	http.HandleFunc("/users", func(w http.ResponseWriter, req *http.Request) {
		var userList = []string {
          	"Alice",
			"Bob",
			"Tom",
		}

        buffer := new(bytes.Buffer)
        template.UserList(userList, buffer)

		w.Write(buffer.Bytes())
	})

	http.ListenAndServe(":8080", nil)
}

At last, start the server and visit http://localhost:8080/users in your browser, we will get what we want!

Template syntax

There are only nine necessary kinds of statements, which are:

  • Function Definition <%: func define %>

    • Function definition statement defines the function which represents a html file.
    • The function defined should contains a parameter buffer *bytes.Buffer.
    • Example:<%: func UserList(userList []string, buffer *bytes.Buffer) %>, which we have mentioned in quick start.

  • Extend <%~ "parent template" %>

    • Extend statement states the parent template the current template extends.
    • The parent template should be quoted with "".
    • Example: <%~ "index.html" >, which we have mentioned in quick start, too.

  • Include <%+ "sub template" %>

    • Include statement includes a sub-template to the current template. It works like #include in C++.
    • The sub-template should be quoted with "".
    • Example: <%+ "user.html" >, which we also have mentioned in quick start.

  • Import <%! go code %>

    • Import statement imports the packages used in the defined function, and it also contains everything that is outside of the defined function.

    • Import statement will NOT be inherited by child template.

    • Example:

      <%!
	import (
      	"fmt"
    	"strings"
    )

	var a int

	const b = "hello, world"

	func Add(a, b int) int {
    	return a + b
	}

	type S struct {
    	Name string
	}

	func (s S) String() string {
    	return s.Name
	}
%>

  • Block <%@ blockName { %> <% } %>

    • Block statement represents a block. Child template overwrites blocks to extend parent template.

    • Example:

      <!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
    </head>

    <body>
        <%@ body { %>
        <% } %>
    </body>
</html>

  • Code <% go code %>

    • Code statement states all code inside the defined function. It's just go code.

    • Example:

      <% for _, user := userList { %>
    <% if user != "Alice" { %>
    	<%= user %>
    <% } %>
<% } %>

<%
	a, b := 1, 2
	c := Add(a, b)
%>

  • Raw Value <%==[t] variable %>

    • Raw Value statement will convert the variable to string.

    • t is the type of variable, hero will find suitable converting method by t. Candidates of t are:

      • b: bool
      • i: int, int8, int16, int32, int64
      • u: byte, uint, uint8, uint16, uint32, uint64
      • f: float32, float64
      • s: string
      • bs: []byte
      • v: interface

      Note:

      • If t is not set, the value of t is s.
      • Had better not use v, cause when t=v, the converting method is fmt.Sprintf("%v", variable) and it is very slow.

    • Example:

      <%== "hello" %>
<%==i 34  %>
<%==u Add(a, b) %>
<%==s user.Name %>

  • Escaped Value <%=[t] variable %>

    • Escaped Value statement is similar with Raw Value statement, but after converting, it will escaped it with html.EscapesString.

    • t is the same with that of Raw Value Statement.

    • Example:

      <%= a %>
<%=i a + b %>
<%=u Add(a, b) %>
<%=bs []byte{1, 2} %>

  • Note <%# note %>

    • Note statement add notes to the template.
    • It will not be added to the generated go source.
    • Example: <# this is just a note example>.

License

Hero is licensed under the Apache License.

Documentation

Index

Constants

View Source 
const (
	TypeImport = iota
	TypeDefinition
	TypeExtend
	TypeInclude
	TypeBlock
	TypeCode
	TypeEscapedValue
	TypeRawValue
	TypeNote
	TypeHTML
	TypeRoot
)
View Source 
const (
	Bool      = "b"
	Int       = "i"
	Uint      = "u"
	Float     = "f"
	String    = "s"
	Bytes     = "bs"
	Interface = "v"
)
View Source 
const (
	OpenBrace   = '{'
	CloseBrace  = '}'
	LT          = '<'
	GT          = '>'
	Percent     = '%'
	Exclamation = '!'
	Colon       = ':'
	Tilde       = '~'
	Plus        = '+'
	Equal       = '='
	At          = '@'
	Pound       = '#'
	Space       = ' '
	BreakLine   = '\n'
)

Variables

This section is empty.

Functions

func EscapeHTML 

func EscapeHTML(html string, buffer *bytes.Buffer)

EscapeHTML escapes the html and then put it to the buffer.

func FormatBool 

func FormatBool(b bool, buffer *bytes.Buffer)

FormatBool format bool to string and then put the result to the buffer.

func FormatFloat 

func FormatFloat(f float64, buffer *bytes.Buffer)

FormatFloat format float64 to string and then put the result to the buffer.

func FormatInt 

func FormatInt(i int64, buffer *bytes.Buffer)

FormatInt format int to string and then put the result to the buffer.

func FormatUint 

func FormatUint(u uint64, buffer *bytes.Buffer)

FormatUint formats uint to string and put it to the buffer. It's part of go source: https://github.com/golang/go/blob/master/src/strconv/itoa.go#L60

func Generate 

func Generate(source, dest, pkgName string)

Generate generates go code from source to test. pkgName represents the package name of the generated code.

func GetBuffer 

func GetBuffer() *bytes.Buffer

GetBuffer returns a *bytes.Buffer from sync.Pool.

func PutBuffer 

func PutBuffer(buffer *bytes.Buffer)

PutBuffer puts a *bytes.Buffer to the sync.Pool.

Types

This section is empty.

Source Files

View all Source files

Directories

Path Synopsis
examples
app
app/template
Code generated by hero.
 Code generated by hero.

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.