README
¶
The world’s most powerful template engine and Go embeddable interpreter.
Website | Get Started | Documentation | Community | Contributing
Features
- Fast, a very fast embeddable pure Go language interpreter.
- Modern and powerful template engine with Go as scripting language.
- Native support for Markdown in templates.
- Secure by default. No access to packages unless explicitly enabled.
- Easy to embed and to interop with any Go application.
Get Started with Programs
Execute a Go program embedded in your application:
package main
import "github.com/open2b/scriggo"
func main() {
// src is the source code of the program to run.
src := []byte(`
package main
func main() {
println("Hello, World!")
}
`)
// Create a file system with the file of the program to run.
fsys := scriggo.Files{"main.go": src}
// Build the program.
program, err := scriggo.Build(fsys, nil)
if err != nil {
panic(err)
}
// Run the program.
err = program.Run(nil)
if err != nil {
panic(err)
}
}
Get Started with Templates
Scriggo, in templates, supports inheritance, macros, partials, imports and contextual autoescaping but most of all it uses the Go language as the template scripting language.
{% extends "layout.html" %}
{% import "banners.html" %}
{% macro Body %}
<ul>
{% for product in products %}
<li><a href="{{ product.URL }}">{{ product.Name }}</a></li>
{% end %}
</ul>
{{ render "pagination.html" }}
{{ Banner() }}
{% end %}
Scriggo template files can be written in plain text, HTML, Markdown, CSS, JavaScript and JSON.
Execute a Scriggo template in your application
// Build and run a Scriggo template.
package main
import (
"os"
"github.com/open2b/scriggo"
"github.com/open2b/scriggo/builtin"
"github.com/open2b/scriggo/native"
)
func main() {
// Content of the template file to run.
content := []byte(`
<!DOCTYPE html>
<html>
<head>Hello</head>
<body>
Hello, {{ capitalize(who) }}!
</body>
</html>
`)
// Create a file system with the file of the template to run.
fsys := scriggo.Files{"index.html": content}
// Declare some globals.
var who = "world"
opts := &scriggo.BuildOptions{
Globals: native.Declarations{
"who": &who, // global variable
"capitalize": builtin.Capitalize, // global function
},
}
// Build the template.
template, err := scriggo.BuildTemplate(fsys, "index.html", opts)
if err != nil {
panic(err)
}
// Run the template and print it to the standard output.
err = template.Run(os.Stdout, nil, nil)
if err != nil {
panic(err)
}
}
For a complete get started guide see the Scriggo site.
Contributing
Want to help contribute to Scriggo? See CONTRIBUTING.md.
Documentation
¶
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HTMLEscape ¶ added in v0.47.0
HTMLEscape escapes s, replacing the characters <, >, &, " and ' and returns the escaped string as HTML type.
Use HTMLEscape to put a trusted or untrusted string into an HTML element content or in a quoted attribute value. But don't use it with complex attributes like href, src, style, or any of the event handlers like onmouseover.
Example ¶
package main
import (
"fmt"
"github.com/open2b/scriggo"
)
func main() {
fmt.Println(scriggo.HTMLEscape("Rock & Roll!"))
}
Output: Rock & Roll!
Types ¶
type BuildError ¶ added in v0.47.0
type BuildError struct {
// contains filtered or unexported fields
}
BuildError represents an error occurred building a program or template.
Example ¶
package main
import (
"fmt"
"github.com/open2b/scriggo"
)
func main() {
fsys := scriggo.Files{
"index.html": []byte(`{{ 42 + "hello" }}`),
}
_, err := scriggo.BuildTemplate(fsys, "index.html", nil)
if err != nil {
fmt.Printf("Error has type %T\n", err)
fmt.Printf("Error message is: %s\n", err.(*scriggo.BuildError).Message())
fmt.Printf("Error path is: %s\n", err.(*scriggo.BuildError).Path())
}
}
Output: Error has type *scriggo.BuildError Error message is: invalid operation: 42 + "hello" (mismatched types int and string) Error path is: index.html
func (*BuildError) Error ¶ added in v0.47.0
func (err *BuildError) Error() string
Error returns a string representation of the error.
func (*BuildError) Message ¶ added in v0.47.0
func (err *BuildError) Message() string
Message returns the error message.
func (*BuildError) Path ¶ added in v0.47.0
func (err *BuildError) Path() string
Path returns the path of the file where the error occurred.
func (*BuildError) Position ¶ added in v0.47.0
func (err *BuildError) Position() Position
Position returns the position in the file where the error occurred.
type BuildOptions ¶ added in v0.31.0
type BuildOptions struct {
// AllowGoStmt, when true, allows the use of the go statement.
AllowGoStmt bool
// Packages is a package importer that makes native packages available
// in programs and templates through the import statement.
Packages native.Importer
// TreeTransformer is a function that transforms a tree. If it is not nil,
// it is called before the type checking.
//
// Used for templates only.
TreeTransformer func(tree *ast.Tree) error
// NoParseShortShowStmt, when true, don't parse the short show statements.
//
// Used for templates only.
NoParseShortShowStmt bool
// MarkdownConverter converts a Markdown source code to HTML.
//
// Used for templates only.
MarkdownConverter Converter
// Globals declares constants, types, variables, functions and packages
// that are accessible from the code in the template.
//
// Used for templates only.
Globals native.Declarations
}
BuildOptions contains options for building programs and templates.
type ExitError ¶ added in v0.47.0
ExitError represents an exit from an execution with a non-zero status code. It may wrap the error that caused the exit.
An ExitError is conventionally passed to the Stop method of native.Env so that the error code can be used as the process exit code.
func NewExitError ¶ added in v0.52.0
NewExitError returns an exit error with the given status code and error. The status code should be in the range [1, 125] and err can be nil. It panics if code is zero.
type FormatFS ¶ added in v0.47.0
FormatFS is the interface implemented by a file system that can determine the file format from a path name.
type PanicError ¶ added in v0.47.0
type PanicError struct {
// contains filtered or unexported fields
}
PanicError represents the error that occurs when an executed program or template calls the panic built-in and the panic is not recovered.
func (*PanicError) Error ¶ added in v0.47.0
func (p *PanicError) Error() string
Error returns all currently active panics as a string.
To print only the message, use the String method instead.
func (*PanicError) Message ¶ added in v0.47.0
func (p *PanicError) Message() interface{}
Message returns the panic message.
func (*PanicError) Next ¶ added in v0.47.0
func (p *PanicError) Next() *PanicError
Next returns the next panic in the chain.
func (*PanicError) Path ¶ added in v0.47.0
func (p *PanicError) Path() string
Path returns the path of the file that panicked.
func (*PanicError) Position ¶ added in v0.47.0
func (p *PanicError) Position() Position
Position returns the position in file where the panic occurred.
func (*PanicError) Recovered ¶ added in v0.47.0
func (p *PanicError) Recovered() bool
Recovered reports whether it has been recovered.
func (*PanicError) String ¶ added in v0.47.0
func (p *PanicError) String() string
String returns the panic message as a string.
type Position ¶ added in v0.47.0
type Position struct {
Line int // line starting from 1
Column int // column in characters starting from 1
Start int // index of the first byte
End int // index of the last byte
}
Position is a position in a file.
type PrintFunc ¶
type PrintFunc func(interface{})
PrintFunc represents a function that prints the arguments of the print and println builtins.
type Program ¶
type Program struct {
// contains filtered or unexported fields
}
Program is a program compiled with the Build function.
func Build ¶ added in v0.31.0
func Build(fsys fs.FS, options *BuildOptions) (*Program, error)
Build builds a program from the package in the root of fsys with the given options.
Current limitation: fsys can contain only one Go file in its root.
If a build error occurs, it returns a *BuildError.
Example ¶
package main
import (
"log"
"github.com/open2b/scriggo"
)
func main() {
fsys := scriggo.Files{
"main.go": []byte(`
package main
func main() { }
`),
}
_, err := scriggo.Build(fsys, nil)
if err != nil {
log.Fatal(err)
}
}
Output:
func (*Program) Disassemble ¶
Disassemble disassembles the package with the given path and returns its assembly code. Native packages can not be disassembled.
func (*Program) Run ¶
func (p *Program) Run(options *RunOptions) error
Run starts the program and waits for it to complete. It can be called concurrently by multiple goroutines.
If the executed program panics, and it is not recovered, Run returns a *PanicError.
If the Stop method of native.Env is called, Run returns the argument passed to Stop.
If the Fatal method of native.Env is called, Run panics with the argument passed to Fatal.
If the context has been canceled, Run returns the error returned by the Err method of the context.
Example ¶
package main
import (
"fmt"
"log"
"github.com/open2b/scriggo"
"github.com/open2b/scriggo/native"
)
func main() {
fsys := scriggo.Files{
"main.go": []byte(`
package main
import "fmt"
func main() {
fmt.Println("Hello, I'm Scriggo!")
}
`),
}
opts := &scriggo.BuildOptions{
Packages: native.Packages{
"fmt": native.Package{
Name: "fmt",
Declarations: native.Declarations{
"Println": fmt.Println,
},
},
},
}
program, err := scriggo.Build(fsys, opts)
if err != nil {
log.Fatal(err)
}
err = program.Run(nil)
if err != nil {
log.Fatal(err)
}
}
Output: Hello, I'm Scriggo!
type RunOptions ¶
type RunOptions struct {
// Context is a context that can be read by native functions and methods
// via the Context method of native.Env. Canceling the context, the
// execution is terminated and the Run method returns Context.Err().
Context context.Context
// Print is called by the print and println builtins to print values.
// If it is nil, the print and println builtins format their arguments as
// expected and write the result to standard error.
Print PrintFunc
}
RunOptions are the run options.
type Template ¶ added in v0.47.0
type Template struct {
// contains filtered or unexported fields
}
Template is a template compiled with the BuildTemplate function.
func BuildTemplate ¶ added in v0.47.0
BuildTemplate builds the named template file rooted at the given file system. Imported, rendered and extended files are read from fsys.
If fsys implements FormatFS, file formats are read with its Format method, otherwise it depends on the file name extension
HTML : .html CSS : .css JavaScript : .js JSON : .json Markdown : .md .mkd .mkdn .mdown .markdown Text : all other extensions
If the named file does not exist, BuildTemplate returns an error satisfying errors.Is(err, fs.ErrNotExist).
If a build error occurs, it returns a *BuildError.
Example ¶
package main
import (
"log"
"github.com/open2b/scriggo"
)
func main() {
fsys := scriggo.Files{
"index.html": []byte(`{% name := "Scriggo" %}Hello, {{ name }}!`),
}
_, err := scriggo.BuildTemplate(fsys, "index.html", nil)
if err != nil {
log.Fatal(err)
}
}
Output:
func (*Template) Disassemble ¶ added in v0.47.0
Disassemble disassembles a template and returns its assembly code.
n determines the maximum length, in runes, of a disassembled text:
n > 0: at most n runes; leading and trailing white space are removed n == 0: no text n < 0: all text
func (*Template) Run ¶ added in v0.47.0
Run runs the template and write the rendered code to out. vars contains the values of the global variables. It can be called concurrently by multiple goroutines.
If the executed template panics, and it is not recovered, Run returns a *PanicError.
If the Stop method of native.Env is called, Run returns the argument passed to Stop.
If the Fatal method of native.Env is called, Run panics with the argument passed to Fatal.
If the context has been canceled, Run returns the error returned by the Err method of the context.
If a call to out.Write returns an error, a panic occurs. If the executed code does not recover the panic, Run returns the error returned by out.Write.
Example ¶
package main
import (
"log"
"os"
"github.com/open2b/scriggo"
)
func main() {
fsys := scriggo.Files{
"index.html": []byte(`{% name := "Scriggo" %}Hello, {{ name }}!`),
}
template, err := scriggo.BuildTemplate(fsys, "index.html", nil)
if err != nil {
log.Fatal(err)
}
err = template.Run(os.Stdout, nil, nil)
if err != nil {
log.Fatal(err)
}
}
Output: Hello, Scriggo!
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package ast declares the types used to define program and template trees.
|
Package ast declares the types used to define program and template trees. |
|
astutil
Package astutil implements methods to walk and dump a tree.
|
Package astutil implements methods to walk and dump a tree. |
|
Package builtin provides simple functions, types, constants and a package that can be used as globals in a Scriggo template.
|
Package builtin provides simple functions, types, constants and a package that can be used as globals in a Scriggo template. |
|
cmd
|
|
|
internal
|
|
|
compiler
Package compiler implements parsing, type checking and emitting of sources.
|
Package compiler implements parsing, type checking and emitting of sources. |
|
compiler/types
Package types implements functions and types to represent and work with Scriggo types.
|
Package types implements functions and types to represent and work with Scriggo types. |
|
Package native provides types to implement native variables, constants, functions, types and packages that can be imported or used as builtins in programs and templates.
|
Package native provides types to implement native variables, constants, functions, types and packages that can be imported or used as builtins in programs and templates. |
|
test
module
|