go-xslate: github.com/lestrrat/go-xslate Index | Examples | Files | Directories

package xslate

import "github.com/lestrrat/go-xslate"

Package xslate is the main interface to the Go version of Xslate.

Xslate is an extremely powerful template engine, based on Perl5's Text::Xslate module (http://xslate.org/). Xslate uses a virtual machine to execute pre-compiled template bytecode, which gives its flexibility while maitaining a very fast execution speed.

You may be thinking "What? Go already has text/template and html/template!". You are right in that this is another added complexity, but the major difference is that Xslate assumes that your template data resides outside of your go application (e.g. on the file system), and properly handles updates to those templates -- you don't have to recompile your application or write freshness checks yourselve to get the updates reflected automatically.

Xslate does all that, and also tries its best to keep things fast by creating memory caches and file-based caches.

It also supports a template syntax known as TTerse, which is a simplified version of the famous Template-Toolkit (http://www.template-toolkit.org) syntax, which is a full-blown language on its own that allows you to create flexible, rich templates.

The simplest way to use Xslate is to prepare a directory with Xslate templates (say, "/path/to/tempalte"), and do something like the following:

tx, _ := xslate.New(xslate.Args {
  "Loader": xslate.Args {
    "LoadPaths": []string { "/path/to/templates" },
  },
})
output, _ := tx.Render("main.tx", xslate.Vars { ... })
fmt.Println(output)

By default Xslate loads templates from the filesystem AND caches the generated compiled bytecode into a temporary location so that the second time the same template is called, no parsing is required.

Note that RenderString() DOES NOT CACHE THE GENERATED BYTECODE. This has significant effect on performance if you repeatedly call the same template. It is strongly recommended that you use the caching layer to boost performance.

Index

Examples

Package Files

xslate.go

Variables

var Debug = false

Debug enables debug output. This can be toggled by setting XSLATE_DEBUG environment variable.

func DefaultCompiler Uses

func DefaultCompiler(tx *Xslate, args Args) error

DefaultCompiler sets up and assigns the default compiler to be used by Xslate. Given an unconfigured Xslate instance and arguments, sets up the compiler of said Xslate instance. Current implementation just uses compiler.New()

func DefaultLoader Uses

func DefaultLoader(tx *Xslate, args Args) error

DefaultLoader sets up and assigns the default loader to be used by Xslate.

func DefaultParser Uses

func DefaultParser(tx *Xslate, args Args) error

DefaultParser sets up and assigns the default parser to be used by Xslate.

func DefaultVM Uses

func DefaultVM(tx *Xslate, args Args) error

DefaultVM sets up and assigns the default VM to be used by Xslate

type Args Uses

type Args map[string]interface{}

Args is the concret type that implements `ConfigureArgs`. Normally this is all you need to pass to `New()`

func (Args) Get Uses

func (args Args) Get(key string) (interface{}, bool)

Get retrieves the value assigned to `key`

type ConfigureArgs Uses

type ConfigureArgs interface {
    Get(string) (interface{}, bool)
}

ConfigureArgs is the interface to be passed to `Configure()` method. It just needs to be able to access fields by name like a map

type Vars Uses

type Vars vm.Vars

Vars is an alias to vm.Vars, declared so that you (the end user) does not have to import two packages just to use Xslate

type Xslate Uses

type Xslate struct {
    Flags    int32
    VM       *vm.VM
    Compiler compiler.Compiler
    Parser   parser.Parser
    Loader   loader.ByteCodeLoader
}

Xslate is the main package containing all the goodies to execute and render an Xslate template

Code:

tx, err := New(Args{
    "Parser": Args{
        "Syntax": "TTerse",
    },
    "Loader": Args{
        "LoadPaths": []string{"/path/to/templates"},
    },
})
if err != nil {
    log.Fatalf("Failed to create Xslate: %s", err)
}
output, err := tx.Render("foo.tx", nil)
if err != nil {
    log.Fatalf("Failed to render template: %s", err)
}
fmt.Fprintf(os.Stdout, output)

func New Uses

func New(args ...Args) (*Xslate, error)

New creates a new Xslate instance. If called without any arguments, creates a new Xslate instance using all default settings.

To pass parameters, use `xslate.Vars`

Possible Options:

* ConfigureLoader: Callback to setup the Loader. See DefaultLoader
* ConfigureParser: Callback to setup the Parser. See DefaultParser
* ConfigureCompiler: Callback to setup the Compiler. See DefaultCompiler
* ConfigureVM: Callback to setup the Virtual Machine. See DefaultVM
* Parser: Arbitrary arguments passed to ConfigureParser function
* Loader: Arbitrary arguments passed to ConfigureLoader function
* Compiler: Arbitrary arguments passed to ConfigureCompiler function
* VM: Arbitrary arguments passed to ConfigureVM function

func (*Xslate) Configure Uses

func (tx *Xslate) Configure(args ConfigureArgs) error

Configure is called automatically from `New()` to configure the xslate instance from arguments

func (*Xslate) DumpAST Uses

func (tx *Xslate) DumpAST(b bool)

DumpAST sets the flag to dump the abstract syntax tree after parsing the template. Use of this method is only really useful if you know the internal repreentation of the templates

func (*Xslate) DumpByteCode Uses

func (tx *Xslate) DumpByteCode(b bool)

DumpByteCode sets the flag to dump the bytecode after compiling the template. Use of this method is only really useful if you know the internal repreentation of the templates

func (Xslate) Render Uses

func (tx Xslate) Render(name string, vars Vars) (string, error)

Render loads the template specified by the given name string. By default Xslate looks for files in the local file system, and caches the generated bytecode too.

If you wish to, for example, load the templates from a database, you can change the generated loader object by providing a `ConfigureLoader` parameter in the xslate.New() function:

xslate.New(Args {
  "ConfigureLoader": func(tx *Xslate, args Args) {
    tx.Loader = .... // your custom loader
  },
})

`Render()` returns the resulting text from processing the template. `err` is nil on success, otherwise it contains an `error` value.

func (*Xslate) RenderInto Uses

func (tx *Xslate) RenderInto(w io.Writer, template string, vars Vars) error

RenderInto combines Render() and writing its results into an io.Writer. This is a convenience method for frameworks providing a Writer interface, such as net/http's ServeHTTP()

func (*Xslate) RenderString Uses

func (tx *Xslate) RenderString(template string, vars Vars) (string, error)

RenderString takes a string argument and treats it as the template content. Like `Render()`, this template is parsed and compiled. Because there's no way to establish template "freshness", the resulting bytecode from `RenderString()` is not cached for reuse.

If you *really* want to change this behavior, it's not impossible to bend Xslate's Loader mechanism to cache strings as well, but the main Xslate library will probably not adopt this feature.

Directories

PathSynopsis
compiler
functions
functions/array
functions/hash
functions/time
internal/frame
internal/rbpool
internal/rvpool
internal/stack
loaderPackage loader abstracts the top-level xslate package from the job of loading the bytecode from a key value.
node
parser
parser/kolonish
parser/tterse
test
vmPackage vm implements the virtual machine used to run the bytecode generated by http://github.com/lestrrat/go-xslate/compiler

Package xslate imports 15 packages (graph) and is imported by 9 packages. Updated 2018-03-06. Refresh now. Tools for package owners.