{"id":13711725,"url":"https://github.com/shiyanhui/hero","last_synced_at":"2025-05-15T17:01:29.545Z","repository":{"id":44342837,"uuid":"79034512","full_name":"shiyanhui/hero","owner":"shiyanhui","description":"A handy, fast and powerful go template engine.","archived":false,"fork":false,"pushed_at":"2020-01-09T01:41:22.000Z","size":79,"stargazers_count":1570,"open_issues_count":28,"forks_count":94,"subscribers_count":44,"default_branch":"master","last_synced_at":"2025-04-01T07:40:21.440Z","etag":null,"topics":["go","hero","template-engine"],"latest_commit_sha":null,"homepage":"https://shiyanhui.github.io/hero","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shiyanhui.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-01-15T13:31:50.000Z","updated_at":"2025-03-28T20:08:37.000Z","dependencies_parsed_at":"2022-09-05T05:11:13.779Z","dependency_job_id":null,"html_url":"https://github.com/shiyanhui/hero","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shiyanhui%2Fhero","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shiyanhui%2Fhero/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shiyanhui%2Fhero/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shiyanhui%2Fhero/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shiyanhui","download_url":"https://codeload.github.com/shiyanhui/hero/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247801155,"owners_count":20998338,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","hero","template-engine"],"created_at":"2024-08-02T23:01:10.999Z","updated_at":"2025-04-08T08:11:00.795Z","avatar_url":"https://github.com/shiyanhui.png","language":"Go","funding_links":[],"categories":["General Purpose Preprocessor","Template Engines","Go","go","模板引擎`模版渲染和模版生成处理库`","模板引擎","Relational Databases","\u003cspan id=\"模板引擎-template-engines\"\u003e模板引擎 Template Engines\u003c/span\u003e","Repositories","Libraries"],"sub_categories":["Snippets Manager","HTTP Clients","查询语","Advanced Console UIs","交流","\u003cspan id=\"高级控制台用户界面-advanced-console-uis\"\u003e高级控制台用户界面 Advanced Console UIs\u003c/span\u003e","高級控制台界面","高级控制台界面"],"readme":"# Hero\n\nHero is a handy, fast and powerful go template engine, which pre-compiles the html templates to go code.\nIt has been used in production environment in [bthub.io](http://bthub.io).\n\n[![GoDoc](https://godoc.org/github.com/shiyanhui/hero?status.svg)](https://godoc.org/github.com/shiyanhui/hero)\n[![Go Report Card](https://goreportcard.com/badge/github.com/shiyanhui/hero)](https://goreportcard.com/report/github.com/shiyanhui/hero)\n[![Travis CI](https://travis-ci.org/shiyanhui/hero.svg?branch=master)](https://travis-ci.org/shiyanhui/hero.svg?branch=master)\n\n[中文文档](https://github.com/shiyanhui/hero/blob/master/README_CN.md)\n\n- [Features](#features)\n- [Install](#install)\n- [Usage](#usage)\n- [Quick Start](#quick-start)\n- [Template Syntax](#template-syntax)\n- [License](#license)\n\n## Features\n\n- High performance.\n- Easy to use.\n- Powerful. template `Extend` and `Include` supported.\n- Auto compiling when files change.\n\n## Performance\n\nHero is the fastest and least-memory used among currently known template engines\nin the benchmark. The data of chart comes from [https://github.com/SlinSo/goTemplateBenchmark](https://github.com/SlinSo/goTemplateBenchmark#full-featured-template-engines-2).\nYou can find more details and benchmarks from that project.\n\n\u003cimg src='http://i.imgur.com/93D7T5C.png' width=\"600\"\u003e\n\u003cimg src='http://i.imgur.com/EIGtYyF.png' width=\"600\"\u003e\n\n## Install\n\n```shell\ngo get github.com/shiyanhui/hero/hero\n\n# Hero needs `goimports` to format the generated codes.\ngo get golang.org/x/tools/cmd/goimports\n```\n\n## Usage\n\n```shell\nhero [options]\n\n  -source string\n        the html template file or dir (default \"./\")\n  -dest string\n        generated golang files dir, it will be the same with source if not set\n  -extensions string\n        source file extensions, comma splitted if many (default \".html\")\n  -pkgname template\n        the generated template package name, default is template (default \"template\")\n  -watch\n        whether automatically compile when the source files change\n\nexample:\n\thero -source=\"./\"\n\thero -source=\"$GOPATH/src/app/template\" -dest=\"./\" -extensions=\".html,.htm\" -pkgname=\"t\" -watch\n```\n\n## Quick Start\n\nAssume that we are going to render a user list `userlist.html`. `index.html`\nis the layout, and `user.html` is an item in the list.\n\nAnd assumes that they are all under `$GOPATH/src/app/template`\n\n### index.html\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n    \u003chead\u003e\n        \u003cmeta charset=\"utf-8\"\u003e\n    \u003c/head\u003e\n\n    \u003cbody\u003e\n        \u003c%@ body { %\u003e\n        \u003c% } %\u003e\n    \u003c/body\u003e\n\u003c/html\u003e\n```\n\n### userlist.html\n\n```html\n\u003c%: func UserList(userList []string, buffer *bytes.Buffer) %\u003e\n\n\u003c%~ \"index.html\" %\u003e\n\n\u003c%@ body { %\u003e\n    \u003c% for _, user := range userList { %\u003e\n        \u003cul\u003e\n            \u003c%+ \"user.html\" %\u003e\n        \u003c/ul\u003e\n    \u003c% } %\u003e\n\u003c% } %\u003e\n```\n\n### user.html\n\n```html\n\u003cli\u003e\n    \u003c%= user %\u003e\n\u003c/li\u003e\n```\n\nThen we compile the templates to go code.\n\n```shell\nhero -source=\"$GOPATH/src/app/template\"\n```\n\nWe will get three new `.go` files under `$GOPATH/src/app/template`,\ni.e. `index.html.go`, `user.html.go` and `userlist.html.go`.\n\nThen we write a http server in `$GOPATH/src/app/main.go`.\n\n### main.go\n\n```go\npackage main\n\nimport (\n    \"bytes\"\n    \"net/http\"\n\n    \"app/template\"\n)\n\nfunc main() {\n    http.HandleFunc(\"/users\", func(w http.ResponseWriter, req *http.Request) {\n        var userList = []string {\n            \"Alice\",\n            \"Bob\",\n            \"Tom\",\n        }\n\n        // Had better use buffer pool. Hero exports `GetBuffer` and `PutBuffer` for this.\n        //\n        // For convenience, hero also supports `io.Writer`. For example, you can also define\n        // the function to `func UserList(userList []string, w io.Writer) (int, error)`,\n        // and then:\n        //\n        //   template.UserList(userList, w)\n        //\n        buffer := new(bytes.Buffer)\n        template.UserList(userList, buffer)\n        w.Write(buffer.Bytes())\n    })\n\n    http.ListenAndServe(\":8080\", nil)\n}\n```\n\nAt last, start the server and visit `http://localhost:8080/users` in your browser, we will get what we want!\n\n## Template syntax\n\nThere are only nine necessary kinds of statements, which are:\n\n- Function Definition `\u003c%: func define %\u003e`\n  - Function definition statement defines the function which represents an html file.\n  - The type of the last parameter in the function defined should be `*bytes.Buffer` for manual buffer management or `io.Writer` for automatic buffer management (\n    note: if using `io.Writer` you may optionally specify return values `(int, error)` to handle the result of `io.Writer.Write`). Hero will identify the parameter name\n    automaticly.\n  - Example:\n    - `\u003c%: func UserList(userList []string, buffer *bytes.Buffer) %\u003e`\n    - `\u003c%: func UserList(userList []string, w io.Writer) %\u003e`\n    - `\u003c%: func UserList(userList []string, w io.Writer) (int, error) %\u003e`\n\n- Extend `\u003c%~ \"parent template\" %\u003e`\n  - Extend statement states the parent template the current template extends.\n  - The parent template should be quoted with `\"\"`.\n  - Example: `\u003c%~ \"index.html\" \u003e`, which we have mentioned in quick start, too.\n\n- Include `\u003c%+ \"sub template\" %\u003e`\n  - Include statement includes a sub-template to the current template. It works like `#include` in `C++`.\n  - The sub-template should be quoted with `\"\"`.\n  - Example: `\u003c%+ \"user.html\" \u003e`, which we also have mentioned in quick start.\n\n- Import `\u003c%! go code %\u003e`\n  - Import statement imports the packages used in the defined function, and it also contains everything that is outside of the defined function.\n  - Import statement will NOT be inherited by child template.\n  - Example:\n\n    ```go\n    \u003c%!\n      import (\n          \"fmt\"\n          \"strings\"\n      )\n\n      var a int\n\n      const b = \"hello, world\"\n\n      func Add(a, b int) int {\n          return a + b\n      }\n\n      type S struct {\n          Name string\n      }\n\n      func (s S) String() string {\n          return s.Name\n      }\n    %\u003e\n    ```\n\n- Block `\u003c%@ blockName { %\u003e \u003c% } %\u003e`\n\n  - Block statement represents a block. Child template overwrites blocks to extend parent template.\n\n  - Example:\n\n    ```html\n    \u003c!DOCTYPE html\u003e\n    \u003chtml\u003e\n        \u003chead\u003e\n            \u003cmeta charset=\"utf-8\"\u003e\n        \u003c/head\u003e\n\n        \u003cbody\u003e\n            \u003c%@ body { %\u003e\n            \u003c% } %\u003e\n        \u003c/body\u003e\n    \u003c/html\u003e\n    ```\n\n- Code `\u003c% go code %\u003e`\n\n  - Code statement states all code inside the defined function. It's just go code.\n\n  - Example:\n\n    ```go\n    \u003c% for _, user := range userList { %\u003e\n        \u003c% if user != \"Alice\" { %\u003e\n            \u003c%= user %\u003e\n        \u003c% } %\u003e\n    \u003c% } %\u003e\n\n    \u003c%\n        a, b := 1, 2\n        c := Add(a, b)\n    %\u003e\n    ```\n\n- Raw Value `\u003c%==[t] variable %\u003e`\n\n  - Raw Value statement will convert the variable to string.\n  - `t` is the type of variable, hero will find suitable converting method by `t`. Candidates of `t` are:\n    - `b`: bool\n    - `i`: int, int8, int16, int32, int64\n    - `u`: byte, uint, uint8, uint16, uint32, uint64\n    - `f`: float32, float64\n    - `s`: string\n    - `bs`: []byte\n    - `v`: interface\n\n    Note:\n    - If `t` is not set, the value of `t` is `s`.\n    - Had better not use `v`, cause when `t=v`, the converting method is `fmt.Sprintf(\"%v\", variable)` and it is very slow.\n  - Example:\n\n    ```go\n    \u003c%== \"hello\" %\u003e\n    \u003c%==i 34  %\u003e\n    \u003c%==u Add(a, b) %\u003e\n    \u003c%==s user.Name %\u003e\n    ```\n\n- Escaped Value `\u003c%=[t] variable %\u003e`\n\n  - Escaped Value statement is similar with Raw Value statement, but after converting, it will be escaped it with `html.EscapesString`.\n  - `t` is the same as in `Raw Value Statement`.\n  - Example:\n\n    ```go\n    \u003c%= a %\u003e\n    \u003c%=i a + b %\u003e\n    \u003c%=u Add(a, b) %\u003e\n    \u003c%=bs []byte{1, 2} %\u003e\n    ```\n\n- Note `\u003c%# note %\u003e`\n\n  - Note statement add notes to the template.\n  - It will not be added to the generated go source.\n  - Example: `\u003c# this is just a note example\u003e`.\n\n## License\n\nHero is licensed under the Apache License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshiyanhui%2Fhero","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshiyanhui%2Fhero","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshiyanhui%2Fhero/lists"}