scriggo

package module
v0.56.1 Latest Latest
Warning

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

Go to latest
Published: Aug 4, 2022 License: BSD-3-Clause Imports: 16 Imported by: 11

README

Scriggo

The world’s most powerful template engine and Go embeddable interpreter.

Go Reference Go Report Card

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

func HTMLEscape(s string) native.HTML

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 &amp; 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 Converter added in v0.47.0

type Converter func(src []byte, out io.Writer) error

Converter is implemented by format converters.

type ExitError added in v0.47.0

type ExitError struct {
	Code int
	Err  error
}

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

func NewExitError(code int, err error) *ExitError

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.

func (*ExitError) Error added in v0.47.0

func (e *ExitError) Error() string

func (*ExitError) Unwrap added in v0.52.0

func (e *ExitError) Unwrap() error

type Files added in v0.47.0

type Files map[string][]byte

Files implements a file system that read the files from a map.

func (Files) Open added in v0.47.0

func (fsys Files) Open(name string) (fs.File, error)

Open opens the named file.

type Format added in v0.47.0

type Format int

A Format represents a content format.

const (
	FormatText Format = iota
	FormatHTML
	FormatCSS
	FormatJS
	FormatJSON
	FormatMarkdown
)

Formats.

func (Format) String added in v0.47.0

func (format Format) String() string

String returns the name of the format.

type FormatFS added in v0.47.0

type FormatFS interface {
	fs.FS
	Format(name string) (Format, error)
}

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.

func (Position) String added in v0.47.0

func (p Position) String() string

String returns line and column separated by a colon, for example "37:18".

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

func (p *Program) Disassemble(pkgPath string) ([]byte, error)

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

func BuildTemplate(fsys fs.FS, name string, options *BuildOptions) (*Template, error)

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

func (t *Template) Disassemble(n int) []byte

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

func (t *Template) Run(out io.Writer, vars map[string]interface{}, options *RunOptions) error

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!

func (*Template) UsedVars added in v0.47.0

func (t *Template) UsedVars() []string

UsedVars returns the names of the global variables used in the template. A variable used in dead code may not be returned as used.

Directories

Path Synopsis
ast
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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL