docs

cmd/liquid/main.go

@@ -1,3 +1,12 @@
+// Package main defines a command-line interface to the Liquid engine.
+//
+// This command intended for testing and bug reports.
+//
+// Examples:
+//
+// 	echo '{{ "Hello " | append: "World" }}' | liquid
+// 	liquid source.tpl
+
 package main
 
 import (

engine.go

@@ -71,26 +71,26 @@ func (e *Engine) RegisterTag(name string, td Renderer) {
 }
 
 // ParseTemplate creates a new Template using the engine configuration.
-func (e *Engine) ParseTemplate(text []byte) (*Template, error) {
-	root, err := e.cfg.Compile(string(text))
+func (e *Engine) ParseTemplate(source []byte) (*Template, error) {
+	root, err := e.cfg.Compile(string(source))
 	if err != nil {
 		return nil, err
 	}
 	return &Template{root, &e.cfg}, nil
 }
 
 // ParseAndRender parses and then renders the template.
-func (e *Engine) ParseAndRender(text []byte, b Bindings) ([]byte, error) {
-	tpl, err := e.ParseTemplate(text)
+func (e *Engine) ParseAndRender(source []byte, b Bindings) ([]byte, error) {
+	tpl, err := e.ParseTemplate(source)
 	if err != nil {
 		return nil, err
 	}
 	return tpl.Render(b)
 }
 
-// ParseAndRenderString is a convenience wrapper for ParseAndRender, that has string input and output.
-func (e *Engine) ParseAndRenderString(text string, b Bindings) (string, error) {
-	bs, err := e.ParseAndRender([]byte(text), b)
+// ParseAndRenderString is a convenience wrapper for ParseAndRender, that takes string input and returns a string.
+func (e *Engine) ParseAndRenderString(source string, b Bindings) (string, error) {
+	bs, err := e.ParseAndRender([]byte(source), b)
 	if err != nil {
 		return "", err
 	}

engine_test.go

@@ -41,20 +41,46 @@ func TestEngine_ParseAndRenderString(t *testing.T) {
 
 func Example() {
 	engine := NewEngine()
-	template := `<h1>{{ page.title }}</h1>`
+	source := `<h1>{{ page.title }}</h1>`
 	bindings := map[string]interface{}{
 		"page": map[string]string{
 			"title": "Introduction",
 		},
 	}
-	out, err := engine.ParseAndRenderString(template, bindings)
+	out, err := engine.ParseAndRenderString(source, bindings)
 	if err != nil {
 		log.Fatalln(err)
 	}
 	fmt.Println(out)
 	// Output: <h1>Introduction</h1>
 }
 
+func ExampleEngine_ParseAndRenderString() {
+	engine := NewEngine()
+	source := `{{ hello | capitalize | append: " Mundo" }}`
+	bindings := map[string]interface{}{"hello": "hola"}
+	out, err := engine.ParseAndRenderString(source, bindings)
+	if err != nil {
+		log.Fatalln(err)
+	}
+	fmt.Println(out)
+	// Output: Hola Mundo
+}
+func ExampleEngine_ParseTemplate() {
+	engine := NewEngine()
+	source := `{{ hello | capitalize | append: " Mundo" }}`
+	bindings := map[string]interface{}{"hello": "hola"}
+	tpl, err := engine.ParseTemplate([]byte(source))
+	if err != nil {
+		log.Fatalln(err)
+	}
+	out, err := tpl.RenderString(bindings)
+	if err != nil {
+		log.Fatalln(err)
+	}
+	fmt.Println(out)
+	// Output: Hola Mundo
+}
 func ExampleEngine_RegisterFilter() {
 	engine := NewEngine()
 	engine.RegisterFilter("has_prefix", strings.HasPrefix)
@@ -69,6 +95,27 @@ func ExampleEngine_RegisterFilter() {
 	fmt.Println(out)
 	// Output: true
 }
+func ExampleEngine_RegisterFilter_optional_argument() {
+	engine := NewEngine()
+	// func(a, b int) int) would default the second argument to zero.
+	// Then we can't tell the difference between {{ n | inc }} and
+	// {{ n | inc: 0 }}. A function in the parameter list has a special
+	// meaning as a default parameter.
+	engine.RegisterFilter("inc", func(a int, b func(int) int) int {
+		return a + b(1)
+	})
+	template := `10 + 1 = {{ m | inc }}; 20 + 5 = {{ n | inc: 5 }}`
+	bindings := map[string]interface{}{
+		"m": 10,
+		"n": "20",
+	}
+	out, err := engine.ParseAndRenderString(template, bindings)
+	if err != nil {
+		log.Fatalln(err)
+	}
+	fmt.Println(out)
+	// Output: 10 + 1 = 11; 20 + 5 = 25
+}
 
 func ExampleEngine_RegisterTag() {
 	engine := NewEngine()

expression/expressions.go

@@ -1,4 +1,6 @@
-// Package expression parses and evaluates the expression language that is used in objects {{a.b[c]}} and tag parameters {%assign pages = site.pages | reverse%}.
+// Package expression parses and evaluates the expression language.
+//
+// This is the language that is used inside Liquid object and tags; e.g. "a.b[c]" in {{ a.b[c] }}, and "pages = site.pages | reverse" in {% assign pages = site.pages | reverse %}.
 package expression
 
 import (

parser/parser.go

@@ -1,9 +1,4 @@
-// Package parser parses template source into a render tree, which can be applied
-// to variable bindings to produce output.
-//
-// Except where noted in the documentation for the liquid package, even public symbols
-// in this package are intended to be public only to other subpackages within this
-// repo, and are not guaranteed stable even across subminor version number increments.
+// Package parser parses template source into an abstract syntax tree.
 package parser
 
 import (